User:Jholsenback

Organization

Basically, I've been using this area as a scratch pad of sorts. As I complete things, and clean-up I'll probably just add a link here for reference.

Scratch Pad

Change Log Extracts

These are change-log extracts that might be useful with helping to update the documentation. For now they are just in reverse chronological order until I can arrange them in a more useful manner.

Beta 35

• Radiosity maximum_reuse parameter now governs the maximum effective radius of a sample more directly.
• Added "out-of-the-box" transparency support for GIF files.
• Added support for PNG sRGB chunks.

Note: Non-legacy scene default gamma handling for image input files has changed significantly from previous betas, affecting all file formats except OpenEXR, Radiance HDR and (with minor differences) most flavors of PNG; there will be NO corresponding warnings. See below for more detail.

Input image files not carrying unambiguous gamma information will now be assumed to match a common gamma setting, and gamma-adjusted accordingly; this common input file gamma setting can be specified in the scene file using the following syntax:

global_settings {
  file_gamma GAMMA
  }

where GAMMA is either a numeric expression specifying the approximate display gamma for which input files are assumed to be gamma pre-corrected, or the keyword srgb indicating that input files are assumed to match the sRGB standard. (In the latter case, gamma adjustment is applied according to the sRGB standard, instead of approximating with a gamma 2.2 power-law function.) The default setting is sRGB.

Regardless of this global setting, gamma correction is not applied if the image input file is obviously used as a mere data container, such as when immediately used in a height field.

Default gamma handling rules for any image input file can be overridden by specifying file_gamma GAMMA immediately after the file name, e.g.:

image_map {
  jpeg "foobar.jpg" file_gamma 1.8
  interpolate 2
  }

This also applies to contexts where gamma adjustment is not normally applied, e.g. file formats that are defined to be encoded linearly, or files used in height fields, to simplify handling of files not conforming to standards.

Note: Gamma handling for PNG input files has changed as follows in legacy #version 3.6 scenes:

1. In the absence of an assumed_gamma statement, non-indexed PNG files with a gAMA chunk (i.e. virtually all PNG files) will appear far brighter than with POV-Ray 3.6
2. In the presence of an assumed_gamma 1.0 statement, indexed PNG files (uncommon) will appear darker than with POV-Ray 3.6
3. In the presence of an assumed_gamma 2.2 statement, PNG files with a gAMA lower than 2.2 (uncommon) will appear darker than with POV-Ray 3.6
4. PNG files with an sRGB chunk but no gAMA chunk may appear significantly different than with POV-Ray 3.6
5. PNG files may generally appear slightly different than with POV-Ray 3.6

A warning will be printed in these cases, except for the latter.

Beta 34

• Added support for diffuse backside illumination:

To model thin, diffusely-translucent objects (e.g. paper, curtains, leaves etc.), an optional 2nd float parameter has been added to the diffuse finish statement to control the effect of illumination from the back of the surface. The default value is 0.0, i.e. no diffuse backside illumination. For realistic results, the sum of both parameters should be between 0.0 and 1.0, and the 2nd parameter should be the smaller of the two.

Note: This feature is currently experimental and may be subject to change. In particular, the syntax as well as interoperation with double_illuminate, multi-layered textures or conserve_energy are still under investigation.

A new sample scene, "advanced/diffuse_back.pov", has been provided to illustrate this new feature.

• New option added speed up radiosity pretrace:

As some computations don't contribute to the generation of radiosity samples, they can safely be skipped during radiosity pretrace to gain some speed if the pretrace's other role as a coarse preview is not required.

The following .ini file/command line options control whether pretrace performs all computations so it can double-feature as a coarse preview ("vain pretrace"):

Radiosity_Vain_Pretrace=bool   turns vain pretrace on/off
+RVP                           turns vain pretrace on (default)
-RVP                           turns vain pretrace off

Note: with vain pretrace off, preview will look remarkably odd during the radiosity pretrace phase; this is normal, and no reason to be alarmed.

At the moment, turning vain pretrace off will affect only classic lighting computations (diffuse lighting, higlights and iridescence); other features expendable during pretrace may follow in future versions.

• Windows console version now sends stream output to stderr by default.

Beta 33

• Added no_radiosity keyword, as known from MegaPOV:

Specifying no_radiosity in an object block makes that object invisible to radiosity rays, in the same way as no_image, no_reflection and no_shadow make an object invisible to primary, reflected and shadow test rays, respectively.

• Revival of Radiosity Load/Save + various other radiosity code changes:

The following .ini / command line parameters are recognized:

Radiosity_File_Name=<name>    or  +RF<name>  to set the cache file name
Radiosity_From_File=<on/off>  or  +RFI       to enable reading the radiosity file at startup
Radiosity_To_File=<on/off>    or  +RFO       to enable writing new samples to the radiosity file

Note: The parameter names are preliminary, and may still be subject to change; there is a potential conflict between the shorthand forms)

If both +RFI and +RFO are specified, new samples gathered are appended; otherwise, +RFO causes the file to be overwritten if it exists.

New samples gathered are written whenever an SMP block is completed. Tests indicate that this is almost neutral regarding performance, compared to operation with radiosity file output disabled.

• New radiosity "high reproducibility" mode:

When specifying High_Reproducibility or +HR on the command line, POV-Ray will spend extra effort to make sure renders are deterministic despite SMP (currently, radiosity is the only code to use this flag; in HR mode, radiosity pretrace starts out with fewer threads, and some extra rules are imposed on sample re-use that may cause surplus samples to be gathered).

Beta 32

• Added ARRAYS_WriteDF3 macro to arrays.inc for writing an array to a df3 file.
• Added binary #write capability

It is now possible to write 8, 16 and 32-bit words to an external file. These words may be arranged in either little or big-endian fashion.

Placing one of the following keywords in the argument list of a #write statement causes the values up to the next comma to be written in binary format, using 2's complement integer representation, rounded to the nearest integer in the representable range:

  uint8              - unsigned byte (0..255)
  sint8              - signed byte (-128..127)
  uint16be, uint16le - unsigned 16-bit word (0..65535)
  sint16be, sint16le - signed 16-bit word (-32768..32767)
  sint32be, sint32le - signed 32-bit word (-2^31..2^31-1)

As of now, unsigned 32-bit words are not supported.

Keywords ending in "be" will cause the values to be written most significant byte first ("big endian", aka network byte order) while those ending in "le" will instead write the least significant byte first ("little endian", Intel format).

Note: See the sample macro ARRAYS_WriteDF3 in arrays.inc to see how this feature may be used.

Beta 31

• Adds experimental support for subsurface light transport (aka subsurface scattering).

Currently, SSLT is activated for a particular object by adding the following statement to its finish.

Be Aware: this is very likely to change!

  subsurface { COLOR, COLOR }

Specifying the (reduced) scattering coefficients (sigma'[s]) and absorption coefficients (sigma[a]), respectively, in units of 1/mm, for each of the three basic colors. The object's IOR will also affect the results.

The algorithm is designed to give realistic results at a scale of 10 mm per POV-Ray unit by default; for other scales, place the following statement in the global_settings section:

  mm_per_unit NUMBER

To tune the algorithm for quality or performance, the number of samples for the diffuse scattering and single-scattering approximation, respectively, can be specified by placing the following statement in the global_settings section:

  subsurface { samples NUMBER, NUMBER }

See the sample SSLT scene in scenes/subsurface/subsurface.pov for more information

Warning: SSLT is still in alpha stage.

Beta 29

• Added ability to declare an identifier as deprecated.

Note: This addition is already in progress. See the example below.

Beta 27

• Added support for specifying grayscale output via INI file or command-line.

This is intended to replace the use of hf_gray_16 in global_settings. If encountered, hf_gray_16 has no effect on the output type and will additionally generate a warning message (as before).

Currently only PNG file support is provided with grayscale output; others will be added over time.

Grayscale output may be specified via Grayscale_Output=true as an INI option, or +Fxg (for output type 'x') as a command-line option. For example, +Fng for PNG grayscale output.

Caveat: grayscale output implies the maximum bit-depth the format supports for PNG this is 16. it is not valid to specify bits per color channel with 'g' (e.g. +Fng16 is not allowed, and nor for that matter is +Fn16g). If bits per channel is provided via an INI option, it is ignored.

Beta 26

• Re-enable Include_Header (see <[email protected]>)

Beta 25

• Linux: add auto setting of thread count and rework --benchmark.

The number of threads is now set as the number of detected CPUs, or 4 otherwise. The built-in benchmark now accepts +L<path> command-line options and does no longer read any INI file but the provided one.

Beta 24

• Added multiple-thread support to photon shooting code.

To take advantage of this at the moment, your scene will need multiple light sources.

• Added experimental support for full area light diffuse and specular illumination.

By default this is off and thus area lights will work as previously, but the new feature can be turned on by specifying the new area_illumination keyword (followed by an optional on/off keyword) in the light source definition. The settings which determine the quality of the lighting are the Size_1 and Size_2 parameters of the area light (similarly to how they determine the quality of the shadows).

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

• Added a new list pattern type: cubic.

It takes six texture elements and maps each one to each of the six pyramids centered at each half-axis (thus effectively mapping each texture element to each side of a origin-centered cube).

• Added a new warp type: cubic.

It takes no parameters, and maps an area in the x-y plane between <0,0> and <1,1> around the origin in the same way as uv-mapping an origin-centered cube-shaped box would. Naturally the warp works with any object whereas the uv-mapping only works for the box object.

See the documentation of box uv-mapping for details.

Beta 23

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

Beta 22

• Added Control-A support in windows version commandline input box (select all).
• Changed render window keypress code

Changed windows version render window keypress code to hand focus to main window for any key, not just escape.

Keyword Addition Example

This outlines the steps to add a new keyword to the documentation. In this case deprecated

• first determine where the descriptive passage goes then add it
• update the syntax diagram in the appropriate places
• update the syntax diagram in the Quick Reference
• update the Identifiers and Keywords list (not done yet)

Note: save this until all keyword additions have been identified because it's an alphabetic list in html table form.

• document any other place(s) that it's used
• add a table of contents entry

Links

• The source and notes on the LaTeX markup used in the documentation.