----------------------------------------------------------------------------
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.

  - 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-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.

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.

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.

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

