Documentation:ToDo ChangeListReview

Change Log Extracts

These are change-log extracts that might be useful with helping to update the documentation. There are some items still to be done, they're categorized, while items that have been completed are at the bottom of this page.

What's New

These are items that can be added to the yet to be written, What's New in POV-Ray 3.7 section basically as is, or one-liners.

1. Added "out-of-the-box" transparency support for GIF files.
2. Added support for PNG sRGB chunks.
3. Windows console version now sends stream output to stderr by default.
4. Added Control-A support in windows version commandline input box (select all).
5. Changed windows version render window keypress code to hand focus to main window for any key, not just escape.
6. Expanded number of available insert menu ID's to about 9000. Added support for loading of JPG and PNG files as insert menu hints. The search order is PNG, then JPG and if they don't exist then BMP.
7. Windows editor tab/indent settings are no longer per-file+global default; changing one affects all files.
8. Added display of filename when hovering over an editor tab.
9. Added right-click menu to editor tabs allowing opening of folder in explorer and copy of filename to clipboard.
10. New thread-safe random number generator added.

Photons

1. Refer FS#93 (Photons are unnaturally amplified by pass_through objects)
   As the error is also present in POV-Ray 3.6, behavior has necessarily changed with this fix; pass_through objects will now affect the color of photons on their way to their target, according to pigment filter/transmit, interior fade, and media (which implies that opaque objects will block photons even when declared pass_through); it needs to be seen whether this new behavior will be accepted by the users, or whether some additional mechanism will have to be implemented to choose between old and new behavior for compatibility with legacy scenes. At present, behavior can only be changed at compile time with the preprocessor defines PT_FILTER_BEFORE_TARGET and PT_AMPLIFY_BUG in photons.cpp.
2. Added multiple-thread support to photon shooting code. To take advantage of this at the moment, your scene will need multiple light sources.

Linux/Unix

1. Linux: rework --benchmark. The built-in benchmark now accepts +L<path> command-line options and does no longer read any INI file but the provided one.
2. Added preliminary Linux support for these two features
   • CPU timer; might return incorrect results depending on the platform.
   • signal catching (e.g. when aborting a render by hitting Ctrl+C).
3. Added support for 'pause when done' in linux build.
4. Added support for --benchmark on unix works together with +wt and print built-in features with --version
5. Unix default file gamma changed from from 1.0 to 2.2.

Image Related

1. Added experimental support for reading the pixel resolution of an image map. This is done by giving an image map pigment identifier to max_extent(), which will then return the resolution of the image map as the x and y values of the returned vector.
2. Partial fix for broken alpha channel output; v3.6 behavior is now reproduced exactly (including bugs), regardless of version. Further changes will address the premultiplied-alpha issue (which was already handled wrong in 3.6) and possibly add options for use cases where v3.6 behavior might be undesired.
3. Changes to input image transparency handling:
   • For material_map, no alpha premultiplication handling is done whatsoever; instead, the data as stored in the file is used.
   • For bump_map and image_pattern, images with alpha channel are treated as if they had a black background (unless the alpha channel itself is used).
4. Changed antialiasing to compare gamma-adjusted colours instead of linear colours, to improve antialiasing of darker regions.
   • Note that this gamma-adjustment is only applied to copies of the sample values, and does not affect averaging of the sample values, which is still performed on the original linear data. It is also independent of both preview display and output file gamma.
   • The antialiasing gamma-adjustment is controlled by the new ini-file / command-line options Antialias_Gamma=x and +AGx respectively, defaulting to 2.5. Note that this differs from Display_Gamma and File_Gamma defaults, as it is intended to fit human vision rather than typical CRT characteristics. Nevertheless, the value specified is once again the inverse of the gamma actually applied, in order to use the more familiar value range.
5. Changed input file gamma syntax for individual files; as an alternative to the file_gamma keyword, the parser will now also accept the gamma keyword originally introduced for specifying gamma in color values. (To specify the default input file gamma in the global_settings section, file_gamma is still mandatory though, as gamma would be ambiguous and misleading.)
6. Added premultiplied BOOL parameter to input image file syntax.
   • Like the gamma/file_gamma parameter, it must immediately follow the filename (though the order of gamma/file_gamma and premultiplied does not matter).
   • The boolean parameter specifies whether the file is stored in premultiplied associated or non-premultiplied straight alpha format, overriding the file format specific default. This keyword has no effect on files without an alpha channel.
7. Added support for using the sRGB transfer function for output file gamma the syntax is File_Gamma=sRGB. SRGB and srgb are supported as well.
   • Note that when File_Gamma=sRGB is used with PNG output file format, POV-Ray writes an sRGB chunk, thereby claiming that the output conforms to the sRGB color space; however, this claim is not necessarily true, as POV-Ray is currently not color space aware; it depends on whether your scene input data conforms to the sRGB color space.
   • The other gamma INI file parameters Antialias_Gamma and Display_Gamma do NOT support the sRGB value at present.

Identifiers and Keywords

The following needs to be added to the identifiers and keywords list. A review of the syntax diagrams in the main and quick reference sections should also be done to double check!

1. aoi
2. area_illumination
3. deprecated
4. cubic (pattern)
5. cubic (warp)
6. elseif
7. for
8. file_gamma
9. gamma
10. maximum_reuse
11. mm_per_unit
12. no_radiosity
13. premultiplied
14. sint16be, sint16le
15. sint32be, sint32le
16. srgb
17. subsurface
18. uint8, sint8
19. uint16be, uint16le

Windows

1. Added 'alternate render file' feature to povwin IDE. See comments below.
2. Added extensions .MCR and .MAC to the list of files povwin considers include files (i.e. which are filtered
   as such in the various file dialogs and assigned the POV file type for the editor syntax highlighting).
3. Added .INI file type to povwin editor syntax highlighting.
4. Added window menu to povwin IDE. Entries are MRU-sorted.
5. Added these POVWIN features
   • file modified indicator to filename shown in POVWIN main window caption.
   • notification for when auto-reload results in files being auto-saved.
6. Added ability to close edit tab in windows version by middle-clicking on it. (NB this means on the tab itself, not the contents of the tab). Also, Ctrl-W now defaults to closing the current editor file.
7. Added /EDITDLLPATH command-line parameter, which overrides the default edit DLL locations for the windows version.
8. Added SEH and minidump generation to windows code. After an unhandled exception POVWIN will now offer the option of creating a minidump (brief or full) for submission to the team to assist in tracking down crashes.
9. Added ability to specify thread count from Windows version render menu (unsaved setting)

Windows Editor Changes

There been two notable changes to the POVWIN IDE.

1. Firstly, it now has a Window menu, which is located where the GUIEXT menu used to be (the latter has moved to within the Options menu). While technically a Window menu is not necessary, as all open files are visible in tabs, the addition of this menu provides two advantages:
   • We can provide the option of showing all tabs on a single line, with a scroller to view non-visible ones. This has not yet been added but will be at a later point.
   • The MRU arrangement of the window menu makes it trivial to toggle between files without taking your eyes off the text or using the mouse. The most recently view window (i.e. the current one) will always be entry 1 in the list. The second most recently viewed (i.e. the last window viewed before switching to the current one) will always be entry 2 in the list, and so forth. Given that entries 1 through 10 in the list are given the menu mnemonics 1 through 0 respectively, it is therefore clear that to toggle between the current and previous files all you need to do is hit Alt-W then 2. To go to the third oldest, Alt-W then 3, and so forth. Currently, the MRU list is not saved on exit. This will be added. We may also add keyboard accelerators (e.g. ALT-2, ALT-3 etc) as a shortcut for Alt-W 2, etc.
2. Secondly, there is now an 'alternate render file' feature. This is intended to make things easier when editing macro or include files. While it is possible to use SDL to detect whether a macro/include file is being rendered directly and to pull in supporting code, that approach is not very flexible. The alternate render file feature allows a render to be started on an include file, and instead of the include file being rendered directly (as would have happened previously), the source file that most recently included that file in a render will be rendered instead.

Note: by 'source file', we mean either a .POV or .INI file.

For this feature to work, you need to have rendered a file which includes the target file during the current editing session (the association between include files and source files is not persisted when POVWIN exits). Additionally you need to have requested to render a source file which does not have the .POV or .INI extension. When you request the render, a message box will appear asking you what to do. You can choose to render the alternate file this time only, to render the alternate file each time you render this one, or to render this one each time (i.e. disable the alternate file option). In all cases, the choice you give only persists for the current editing session; it is not restored when you re-launch POVWIN. this is by design.

Render Window

Due to issues with CPU usage, the new render window is now by default off. To work well this feature requires that hardware-assisted alpha blending is available on the target system, and as of the time of writing this is not common enough to justify turning it on by default.

Note: it will remain turned on if you already had it on (e.g. from a previous beta).

The new render window mode is only available on Windows 2000 or later. The presence of this code may case the beta to be unable to load on Windows 9x systems; if this occurs it will be fixed in the next beta.

Note: that we have not tested this new code on a Windows 2000 system, so we can't comment on how well it will work on those systems.

To activate the new render window, open the 'Render Window' sub-menu in the 'Options' menu, and select the 'Use New-style Render Window' entry.

The new render window is designed to help users get around the issue of the render window getting in the way when doing edit/render/fix cycles. It supports a 'transparency' mode that is in effect two things: both optical transparency (or more specifically translucency), and input transparency (more specifically, the Windows WS_EX_TRANSPARENT style).

'Input transparency' means that the window is transparent to input - so if you move your mouse over it or attempt to click on it, the mouse messages are in fact sent to whatever is underneath the window. In effect therefore it is as if the window were not there - even if you can still see it.

The effect of this is that, coupled with translucency, you can both see what is under the window (e.g. the POV-Ray editor), and also work with it (typing or selecting with the mouse, etc).

'Input Transparency' is enabled whenever you set the translucency of the render window to 25% or more (see below). At settings less than this, the render window will behave more or less as normal (though without some of the features of the classic render window, such as the ability to be de-coupled from the main window such that it does not get hidden when the main window is minimized).

To set the translucency of the render window, either rotate your mouse wheel when the render window has focus (this is the preferred method), or alternatively right-click on the window's title bar and choose a setting from the context menu that is provided.

When the render window has input focus, translucency is removed and it becomes opaque. It will switch back once another window gets focus, or if you adjust the translucency using one of the above methods.

If you want to work with input transparency, it is important that you understand that this means you can't work with the render window in the manner you are accustomed to, since of course the window will pass input to the application below it. To allow for interaction with the window in this circumstance, we have added a feature whereby hovering the mouse over the render window's caption for a short time, or clicking on the title bar, will activate the window, make it opaque, and allow input to be processed normally.

Of course the ability to click on the caption means that it's not completely input transparent, and we might disable this feature later if the hover feature works out well.

You will know if your mouse is over the appropriate area of the window since the cursor will turn to a hourglass shape during the 'hover' time.

Provided that the window is left in input transparency mode, if you move your mouse out of the window for a short time, it will automatically snap back into its former translucent mode.

You can tell if the window is in input transparency mode by looking for a '[T]' at the start of the render window caption. If present, then it's going to pass input to the application underneath it. While adjusting the translucency with the mouse wheel, the caption will display the new translucency setting and, if appropriate, a comment that the window has switched to passing input. (Recall however that this doesn't kick in until you switch focus to another window).

Miscellaneous

1. Added #declare atand = function (x) {degrees(atan(x))} to "math.inc".
2. You now have the ability to specify the render block size via either an INI-style option Render_Block_Size=n or on the command-line +BSn, where 'n' is an integer larger than or equal to 4. This represents the edge size of the square used to distribute work to the render threads, and thus the number of pixels in each block will be n squared. The default value is 32. If you specify a value that is greater than the larger of the width or height of the image being rendered, it is clipped to that value. Using render block sizes of less than eight can impact performance, particularly on large images that render quickly, as it significantly increases the amount of message traffic between the render backend and the graphical frontend (which communicate using a shared-memory queue).
3. Using Output_Gamma=on with legacy scenes (#version < 3.7) will now suppress sky spheres and background except in reflections, for backward compatibility with v3.6.
4. Implemented adaptive radiosity pretrace. When a second parameter is specified after the nearest_count keyword, pretrace will stop re-iterating over areas where, on average, that many (average-quality) samples are already present per ray.
5. Parser now checks for plausible relation between radiosity minimum_reuse and maximum_reuse:
   • If ony one value is specified, parser will warn if minimum_reuse > maximum_reuse/2, and adjust the unspecified value accordingly.
   • If both values are specified, parser will warn if minimum_reuse > maximum_reuse/2, but not modify any of the values; if minimum_reuse >= maximum_reuse; the parser will raise an error.
6. Mosaic preview now works again. The same issue as mentioned in the above section on render block size apply; we don't recommend using an end preview size of less than 8. Note that unless you specify an end preview size the code will default to using +ep2, so it is strongly recommended that you do provide it.
7. Added #elseif statement; the #if, #ifdef and #ifndef directives syntax is changed as follows:

IF_DIRECTIVE:
  #if ( Cond ) TOKENS... [ELSE_DIRECTIVE] #end
IFDEF_DIRECTIVE:
  #ifdef ( IDENTIFIER ) TOKENS... [ELSE_DIRECTIVE] #end
 IFNDEF_DIRECTIVE:
  #ifndef ( IDENTIFIER ) TOKENS... [ELSE_DIRECTIVE] #end
  
ELSE_DIRECTIVE:
  #else TOKENS... |
  #elseif ( Cond ) TOKENS... [ELSE_DIRECTIVE]

• Example:

#if (Foo)
  #debug "Foo is true\n"
#elseif (Bar)
  #debug "Foo is false, but Bar is true\n"
#else
  #debug "Foo and Bar are both false\n"
#end

In Progress

1. Changed alpha handling for image file input and output:
   • Previous versions of POV-Ray always expected straight (non-premultiplied) alpha for file input, while always writing associated (premultiplied) alpha for output; this has been changed on a per-file-format basis to use the same alpha handling mode for input and output alike:
     • PNG will use straight alpha as per specification.
     • OpenEXR and TIFF will use associated alpha as per specifications.
     • TGA and BMP 32-bit RGBA (an inofficial extension to BMP) will use straight alpha, retaining file input compatibility for now, until a final decision has been made on these formats.
2. When generating non-premultiplied alpha output to a classic low-dynamic-range file format (e.g. PNG), transparency of particularly bright areas will now be reduced, in order to better preserve highlights on transparent objects. (Note that this mechanism has some limitations with colored highlights.)
3. When used with file formats for which alpha output is currently not supported by POV-Ray (or only via an inofficial extension, as with BMP), turning on alpha output via Output_Alpha=on or +UA will now generate a warning.

• I'm currently working on the above 3 items: --jholsenback 17:28, 19 July 2010 (UTC)

Completed Items

Radiosity

• Speed up radiosity pretrace option

• Check here: --jholsenback 18:38, 23 May 2010 (UTC)

• Revival of Radiosity Load/Save

• Check here: --jholsenback 18:39, 23 May 2010 (UTC)

• New radiosity "high reproducibility" mode

• Check here: --jholsenback 18:39, 23 May 2010 (UTC)

• Radiosity maximum_reuse parameter

• Check here: --jholsenback 15:12, 31 May 2010 (UTC)

• Added no_radiosity keyword

• Check here: --jholsenback 15:14, 31 May 2010 (UTC)

• Added emission parameter to the finish block

• Check here: --jholsenback 13:16, 13 July 2010 (UTC)

New Features

• Diffuse backside illumination

• Check here:--jholsenback 13:39, 6 April 2010 (UTC)

• Added a new list pattern type: cubic

• Check here: --jholsenback 19:11, 15 April 2010 (UTC)

• Added a new warp type: cubic

• Check here: --jholsenback 19:11, 15 April 2010 (UTC)

• AOI Pattern

• Check here: --jholsenback 01:50, 18 May 2010 (UTC)

• Slope Pattern extension

• Check here: --jholsenback 11:40, 19 May 2010 (UTC)

• Subsurface scattering

• Check here: --jholsenback 17:55, 27 May 2010 (UTC)

• Added support for full area light diffuse and specular illumination

• Check here: --jholsenback 14:36, 14 June 2010 (UTC)

• Added RTR (real-time raytracing), clockless animation, and video capture support

• Check here: --jholsenback 18:44, 14 July 2010 (UTC)

Gamma

• Non-legacy scene default gamma handling for image input files

• Check here: --jholsenback 09:49, 5 May 2010 (UTC)

• assumed_gamma and File_Gamma

• Check here, here, here and here: --jholsenback 13:32, 11 June 2010 (UTC)

• gamma keyword to specify gamma pre-corrected colours

• Check here: --jholsenback 14:51, 9 July 2010 (UTC)

SDL

• Added ability to declare an identifier as deprecated

• Check here: --jholsenback 13:21, 31 March 2010 (UTC)

• Added comparison (=, !=, <, <=, >, >=) support for strings

• Check here: --jholsenback 14:15, 6 April 2010 (UTC)

• #break directive behavior

• Check here: --jholsenback 18:11, 26 May 2010 (UTC)

• ARRAYS_WriteDF3 macro

• Check here: --jholsenback 17:26, 3 June 2010 (UTC)

• Added binary #write capability

• Check here: --jholsenback 17:26, 3 June 2010 (UTC)

• Changed bounding method command-line option from +b2 to +bm2

• Check here: --jholsenback 12:37, 15 June 2010 (UTC)

• BSP (Binary Space Partitioning) tree bounding is now available

• Check here: --jholsenback 12:37, 15 June 2010 (UTC)

• Changed WorkThreads INI option to Work_Threads for consistency

• Check here: --jholsenback 18:53, 16 June 2010 (UTC)

• The version directive, command-line setting no longer provide compatibility

• Check here: --jholsenback 13:16, 13 July 2010 (UTC)

Images

• Added HDR file support (RGBE, as used in Radiance)and EXR file support

• Check here: --jholsenback 08:01, 8 April 2010 (UTC)

• PPM and 16-bit greyscale output

• Check here: --jholsenback 09:47, 5 May 2010 (UTC)

• bicubic image interpolation

• Check here: --jholsenback 11:37, 8 July 2010 (UTC)

• chroma sub-sampling in JPEG output

• Check here: --jholsenback 11:37, 8 July 2010 (UTC)

• Default output file type is now PNG

• Check here: --jholsenback 11:44, 8 July 2010 (UTC)

• alpha handling and +UA

• Check here: --jholsenback 13:54, 16 July 2010 (UTC)

• sky_sphere with layered pigment and filter

• Check here: --jholsenback 13:54, 16 July 2010 (UTC)