changes.txt

----------------------------------------------------------------------------
Changelog information is available in the file revision.txt, which should be
located in the same directory as this file is.
----------------------------------------------------------------------------

--------------------------------------------------
Changes between POV-Ray 3.7.0 and UberPOV 1.37.0.0
--------------------------------------------------

  - UberPOV 1.37.0.0 is based on from POV-Ray 3.7.0, with the following notable
    changes (in addition to the obvious change of the program name and version).

  - UberPOV adds a few sample scenes for its own features.

  - For now, UberPOV does not come with any documentation worth mentioning;
    instead, please refer to the original POV-Ray 3.7 documentation, plus the
    descriptions of added features in this very file.

Testing for UberPOV:
--------------------

  - UberPOV supports the following #version directives:

        #version NUMBER;
        #version unofficial patch NUMBER;

    Both(!) directives specify the official(!) version of POV-Ray required to
    render the scene; however, while the former specifies that the
    corresponding official POV-Ray will suffice, the latter specifies that
    what is really needed is an unofficial version, and that the scene file
    will test for the presence of individual unofficial extensions using
    either the #patch directive or patch() function.

  - UberPOV predefines a global variable named "unofficial", with the value
    being "patch".

  - The new #patch directive has the following syntax:

        #patch STRING NUMBER;
        #patch NUMBER

    The former indicates that the scene file needs the unofficial extension
    specified by STRING at least at the version specified by NUMBER. An error
    is issued if the feature is not supported at all, or only at a lower
    version number, while a warning is issued if the integer portion of the
    specified version number is lower than that supported, indicating that the
    feature may not be fully backward compatible.
    The #patch directive and patch() function also constitute an unofficial
    extension that can be tested for; however, it has no associated name, and
    is instead tested for by using the latter variant of the #patch directive.

  - The new patch() function has the following syntax:

        patch(STRING)
        patch()

    The former returns the version number of the extension as supported by
    UberPOV, or 0.0 if it does not recognize the extension name specified; the
    latter returns the version number of the extension providing the #patch
    directive and patch() function, which is currently 0.99.

  - UberPOV currently recognizes the following extension names:

      - upov (137.00)

        This pseudo-extension indicates the version of UberPOV.

      - upov-blink (0.90):

        The "blink" keyword can be used as an object modifier to achieve
        multiple-exposure effects.

      - upov-file_time (0.90):

        The "file_time" keyword can be used as a function to determine the
        last modification time of a file.

      - upov-light_source-max_distance (0.80):

        The max_distance keyword can be used inside light_source statements to
        affect the light source distanc-based cutoff feature.

      - upov-persistent (0.10):

        The "#persistent" statement can be used to pass data to subsequent
        frames of an animation.

      - upov-radiosity-no_cache (0.10):

        The "no_cache" keyword can be specified inside the global radiosity
        block to enable unbiased computation of diffuse illumination.

      - upov-read-text (1.00):

        The "text" keyword can be specified in the "#read" directive, enabling
        plaintext reading.

      - upov-reflection-roughness (0.90):

        The "roughness" keyword can be specified inside the reflection
        block, enabling blurred reflections.

Plaintext Reading:
------------------

  - UberPOV allows the following syntax in the "#read" directive:

        #read( FILE, [...,] text,IDENTIFIER [,...] )

    This will cause the remainder of the current line to be read as plain ASCII
    text and stored in the variable denoted by IDENTIFIER.

    This syntax extension can be tested for using the #patch directive or
    patch() function with the patch name "upov-read-text"; the current
    implementation is version 1.0.

File Modification Time
----------------------

  - UberPOV provides a function to determine when a particular file was last
    modified:

        file_time(STRING)

    where STRING is the name of the file. The function returns a numeric value
    specifying the file's last modification time in days since 2000-01-01,
    00:00:00, with time of day being represented as fractional days.
    This is the same format as used by both the now keyword and the datetime
    function.

    This syntax extension can be tested for using the #patch directive or
    patch() function with the patch name "upov-file_time"; the current
    implementation is version 0.9.

Light Source Distance-Based Cutoff
----------------------------------

  - Light sources with distance-based fading (i.e. using the fade_distance
    keyword) are cut off entirely at a certain distance to improve performance.
    The cutoff distance is computed automatically based on nominal light source
    brightness, fade parameters, and the global_settings adc_bailout.

  - The following syntax can be used to overridde the cutoff distance for an
    individual light source:

        light_source { ... max_distance NUMBER }

    This will set the cutoff distance to the specified value. This syntax can
    also be used for non-fading light sources if desired.

    This syntax extension can be tested for using the #patch directive or
    patch() function with the patch name "upov-light_source-max_distance"; the
    current implementation is version 0.8.

Persistent Variables:
---------------------

  - UberPOV allows the following syntax:

        #persistent IDENTIFIER = VALUE [;]

    Just like #declare and #local, this statement defines a variable. However,
    this variable will persist for all subsequent frames in an animation (for
    command-line versions of UberPOV), or all subsequent renders in this
    session (for GUI versions), unless explicitly undefined later.

    Persistent variables can coexist with global (and local) variables of the
    same name, with global variables taking precedence over persistent ones,
    just like local variables take precedence over global ones.

    Known caveats:

      - At present, random number streams cannot be made persistent yet.

    This syntax extension can be tested for using the #patch directive or
    patch() function with the patch name "upov-persistent"; the current
    implementation is version 0.1.

Glare Desaturation:
-------------------

  - If the chosen output file format does not support high dynamic range,
    portions of the image being overexposed with respect to some - but not
    all - of the RGB color channels will now be shifted towards white, thereby
    sacrificing saturation in favor of preserving brightness.
    The strength of this effect can be controlled by either of the following
    command line / .ini file options:

        +GLDx
        Glare_Desaturation=x

    The default is 0.0, meaning the feature is effectively turned off, while
    a value of 1.0 causes brightness to be preserved exactly at all cost (if
    possible at all); for a trade-off between saturation and brightness,
    choose any value in between.

    The effect is never applied to high dynamic range output files; however,
    it is still applied to the render preview in such cases.
    
    (Glare Desaturation in the render preview is not supported by the Unix
    version yet.)

Reflection Blur:
----------------

  - UberPOV allows the following syntax in a finish statement:

        reflection { ... roughness NUMBER }

    This adds blur to the reflectios; the amount of blur matches that of
    specular highlights with the same roughness specified.

    This syntax extension can be tested for using the #patch directive or
    patch() function with the patch name "upov-reflection-roughness"; the
    current implementation is version 0.9.

Unbiased Diffuse Illumination:
------------------------------

  - UberPOV allows to disable the caching of radiosity samples, by using the
    following syntax in the global radiosity block:

        no_cache [BOOL]

    It also changes the way the secondary ray directions are chosen, and
    effectively turns the radiosity algorithm into a purely stochastic unbiased
    algorithm to compute diffuse illumination.

    Most radiosity settings are without effect in this mode, except for the
    following:

        adc_bailout FLOAT
        brightness FLOAT
        brilliance BOOL
        count FLOAT
        gray_threshold FLOAT
        media BOOL
        normal BOOL
        recursion_limit INT
        subsurface BOOL

    The current implementation does not translate classic radiosity settings
    into useful parameters for this mode of operation; it is therefore highly
    recommended to use a much lower setting for the "count" parameter than
    typical with standard radiosity.

    This syntax extension can be tested for using the #patch directive or
    patch() function with the patch name "upov-radiosity-no_cache"; the current
    implementation is version 0.1.

Blink Keyword:
--------------

  - UberPOV can render an object as if it was present in the scene only during
    a portion of the exposure time. This feature is activated by using the
    following object modifier:

        blink [START_TIME,] END_TIME

    where START_TIME and END_TIME specify the time interval during which the
    object is supposed to be present, ranging from 0.0 (start of current frame)
    to 1.0 (end of current frame). The default values are 0.0 and 1.0
    respecively.

    The primary purpose of this feature is to provide basic support for motion
    blur effects, which can be achieved by creating multiple copies of an
    object with different blink intervals. Another potential use of this
    mechanism is to model ghost-like objects which appear transparent with
    respect to the background but opaque with respect to themselves.

    This syntax extension can be tested for using the #patch directive or
    patch() function with the patch name "upov-blink"; the current
    implementation is version 0.9.

Stochastic Anti-Aliasing:
-------------------------

  - UberPOV recognizes the following additional command line options and .ini
    file parameters:

        Sampling_Method=3         +AM3
        Antialias_Confidence=n.n  +ACn.n

    With anti-aliasing sampling method 3, a 2D halton pattern is used for
    oversampling, and the decision how many samples to take for a given pixel
    is based on a stochastic metric of the samples already taken for that
    pixel and its immediate four neighbors.

    In this mode, the Antialias_Depth=n / +Rn parameter specifies the absolute
    maximum number of samples for any given piel, according to the formula
    N=4^n. The Antialias_Threshold=n.n / +An.n parameter specifies a
    stochastic parameter called variance, which essentially expresses how much
    error in a pixel's color you are willing to accept. The new
    Antialias_Confidence=n.n / +ACn.n parameter specifies another stochastic
    parameter called confidence, which essentially expresses how sure you want
    to be that the computed color of a given pixel is indeed within that error
    margin.

Adaptive Multi-Level Oversampling:
----------------------------------

  - Various features of UberPOV rely on oversampling, i.e. averaging a bunch
    of secondary rays. When such secondary rays are again subject to another
    oversampling feature, UberPOV will adapt the number of tertiary rays shot
    in this second oversampling process, depending on the number of rays shot
    in the first one. In addition, the second oversampling process will switch
    to an entirely random oversampling pattern.

    The following features currently support this mechanism:

      - anti-aliasing mode 3
      - area lights
      - area illumination
      - focal blur
      - radiosity (partially; see below)
      - reflection blur
      - subsurface light transport

    Radiosity only supports this mechanism in the sense that subsequent
    oversampling processes can adapt to the number of radiosity sample rays
    shot. It does not adapt its own number of sample rays, as this would
    scramble the radiosity algorithm.

    UberPOV also recognizes the following command line option and .ini file
    parameter:

        Stochastic_Seed=n       +SSn

    This instructs UberPOV to seed the stochastic pseudo-random number
    generator with a particular initial state. This can be used to either make
    the sequence reproducible, or to the contrary cause different sequences to
    be used even in renders started at the same time. If set to 0 (the
    default), the seed value is determined from the current time and date.

Windows Related:
----------------

  - UberPOV for Windows does not come with an installer; instead, it is
    intended to be copied into the binary directory of an existing POV-Ray 3.7
    installation.

    Like POV-Ray 3.7.0 for Windows, UberPOV for Windows needs an additional
    editor DLL in order to be able to edit scenes in the GUI. Needless to say
    that UberPOV uses the very same DLL as POV-Ray.

  - At the time of writing, the UberPOV for Windows binary packages do not
    feature any additional distribution files yet, such as include files or
    sample scenes. These can be found in the /distribution/ directory of the
    source package.

Unix Related:
-------------

  - There is currently no explicit UberPOV for Unix distribution package;
    instead, you will need to obtain the full source code distribution
    package, and run the following commands prior to the actual Unix build
    process:

        cd <source_dir>/unix
        ./prebuild.sh