This document describes the various toxic settings file formats. It is written to be easy to read and understand, but it also contains enough details to be considered as a reference document.

In order to improve the quality of this document, please report typos and errors but also missing, incomplete or unclear material. In any case your comments and suggestions are welcome. In all cases, please use the forums to discuss this document.

• 1  Introduction
• 2  toxic Settings
  • 2.1  File Structure
  • 2.2  Settings
    • 2.2.1  Multithreading
  • 2.3  XML Schema
  • 2.4  Sample File
• 3  Scene Settings
  • 3.1  File Structure
  • 3.2  Rendering Settings
    • 3.2.1  Pixel Sampling
      • 3.2.1.1  Supersampling
      • 3.2.1.2  Whitted Adaptive Sampling
    • 3.2.2  Lighting Components
      • 3.2.2.1  Direct Lighting
      • 3.2.2.2  Indirect Lighting
      • 3.2.2.3  Specular Reflections
      • 3.2.2.4  Caustics
  • 3.3  Output Settings
    • 3.3.1  Gamma Correction
  • 3.4  XML Schema
  • 3.5  Sample Files

This document describes the various settings files used by toxic.

Settings are divided into two categories: toxic settings and scene settings.

toxic settings are system-dependent. They must be set according to the system ressources (like the number of processors) to make toxic run efficiently. They do not affect image quality.

Scene settings are system-independent, so they can be distributed along with scenes and used as-is on different machines. Typically, each scene has its own scene settings file associated to it. Scene settings describe how toxic is going to render the scene. They permit to control the trade-off between simulation accurary, visual quality and rendering speed.

By default, toxic settings are read from the settings/toxicsettings.xml file in the toxic installation directory.

Here is the basic structure of a valid toxic settings file:

The first statement (<?xml ... ?>) indicates the type and the encoding of the document.

The second statement (<ToxicSettings ... >) opens the root element of the settings file. The xsi:noNamespaceSchemaLocation attribute is the path to the toxicsettings.xsd schema (which is located in the schemas/ directory of the toxic distribution). toxic does not rely on this path to find the schema, so it will not complain if it is incorrect. However, you must specify the right path to the toxicsettings.xsd file in order to allow your favorite XML editor to find the schema and to validate your settings file.

The last statement (</ToxicSettings>) closes the root element.

One and ony one root element must appear in the file.

Syntax:

The <Multithreading /> element makes it possible to specify the number of threads used to render a frame. The minimum value of the renderingthreads attribute is 1. There is no maximum value.

The optimal number of rendering threads depends primarily on the number of CPU in the rendering machine.

One and only one <Multithreading /> element must appear inside the root element.

Note: the current version of toxic can not use more than one rendering thread. This limitation will be removed in future versions of toxic.

You can get the full XML Schema describing toxic settings file format here.

There is a sample toxic settings file here.

By default, the scene settings file must be located in the same directory as the scene file itself. The name of the scene settings file is obtained by appending the .settings suffix to the scene name. For example, given a scene file named bunny.xml, toxic will load scene settings from the file bunny.settings.xml.

Here is the basic structure of a valid scene settings file:

The first statement (<?xml ... ?>) indicates the type and the encoding of the document.

The second statement (<ToxicSceneSettings ... >) opens the root element of the settings file. The xsi:noNamespaceSchemaLocation attribute is the path to the toxicscene.settings.xsd schema (which is located in the schemas/ directory of the toxic distribution). toxic does not rely on this path to find the schema, so it will not complain if it is incorrect. However, you must specify the right path to the toxicscene.settings.xsd file in order to allow your favorite XML editor to find the schema and to validate your settings file.

The last statement (</ToxicSceneSettings>) closes the root element.

One and ony one root element must appear in the file.

Rendering settings are grouped together into a <Rendering /> element:

One and only one <Rendering /> element must appear inside the root element.

Pixel sampling settings control how and in how many parts is divided the surface of each pixel.

Pixel sampling settings are grouped together into a <PixelSampling /> element:

One and only one <PixelSampling /> element must appear inside the <Rendering /> element.

The <PixelSampling /> element must contain either a <Supersampling /> element or a <WhittedAdaptiveSampling /> element.

Supersampling settings must be placed into a <Supersampling /> block as follow:

One and only one of these three supersampling schemes must be selected: random, regular or stratified.

The random scheme is selected with the following code fragment:

The regular scheme is selected with the following code fragment:

Finally, The stratified scheme is selected with the following code fragment:

The attributes samples, width and height must be set to strictly positive integer values.

Whitted adaptive sampling is an adaptive method which allows to put more antialiasing work where it is needed. For a given pixel, it compares the contrast between the four corners of the pixel to a user-defined contrast threshold. If the computed contrast is greater than the threshold, the pixel is subdivided in four equal parts and this algorithm is recursively applied to the four parts.

Contrast between two colors is defined as the absolute value of the luminance difference. toxic computes the luminance of a given (R, G, B) color according to the CIE Rec. 709 standard:

The CIE Rec. 709 standard takes into account the way the human vision works by carefully weighting the R, G, B components in the luminance formula.

Whitted adaptive sampling is selected with the following code fragment (which must be inserted directly into the <PixelSampling /> element):

The contrastthreshold attribute defines the contrast threshold beyond which subdivision occurs. It must be set to a non-negative real value. If set to 0.0, subdivision will occur systematically up to the maximum depth.

The maximum subdivision depth is defined by the maxdepth attribute, which must be set to a non-negative integer value. If the maxdepth attribute is set to 0, subdivision will never happen.

This settings block allow to select which lighting components must be computed during the lighting simulation.

Lighting components are declared into a <Components /> element:

One and only one <Components /> element must appear inside the <Rendering /> element.

There are four lighting components: direct lighting, indirect lighting, specular reflections and caustics. These four components form global illumination (GI). Each component can be individually enabled or disabled.

Direct lighting is computed if and only if the following block appear in the <Components /> element:

The <DirectLighting /> element can not appear more than once inside the <Components /> element.

Required direct lighting settings:

• Area lights sampling settings: <ArealightSampling />.

Optional direct lighting settings:

• None.

The <ArealightSampling /> element is declared as follow:

One and only one of these three sampling schemes must be selected: random, regular or stratified.

The random scheme is selected with the following code fragment:

The regular scheme is selected with the following code fragment:

Finally, The stratified scheme is selected with the following code fragment:

The attributes samples, width and height must be set to strictly positive integer values.

Here is a sample, complete direct lighting settings block. It enables direct lighting and instructs toxic to use stratified sampling for area lights sampling:

Indirect lighting is computed if and only if the following block appear in the <Components /> element:

The <IndirectLighting /> element can not appear more than once inside the <Components /> element.

Required indirect lighting settings:

• Photon tracing settings: <PhotonTracing />.
• Radiance estimate settings: <RadianceEstimate />.

Optional indirect lighting settings:

• Radiance precomputation settings: <RadiancePrecomputation />.
• Primary final gathering settings: <PrimaryFinalGathering />.
• Secondary final gathering settings: <SecondaryFinalGathering />.

The <PhotonTracing /> element allows to specify the total number of photons to emit from light sources. It is declared as follow:

The photons attribute specifies how many photons must be emitted. It must be set to a strictly positive integer value.

The <RadianceEstimate /> element is declared as follow:

The maxphotons attribute is the maximum number of photons to take into account when estimating radiance at a given point of the scene. It must be set to a strictly positive integer value. The maxdistance attribute is the maximum distance to include a photon. It must be set to a strictly positive real value.

Photons are gathered until one the bounds (on distance or photon count) is reached.

If present, the <RadiancePrecomputation /> element instructs toxic to precompute radiance at the position of some of the emitted photons. It is declared as follow:

The spacing attribute specifies the density of the radiance precomputation. It must be set to a strictly positive integer value. If set to 1, radiance will be precomputed at the position of each photons. If set to n, radiance will be precomputed at the position of every n photons. The maxsearchdistance attribute must be set to a strictly positive real value. It specifies the maximum distance to search for a photon carrying a precomputed radiance estimate.

Note: future versions of toxic will probably replace the spacing attribute by something more intuitive.

The <PrimaryFinalGathering /> element, if present, instructs toxic to use final gathering to compute indirect lighting. This gives a much smoother indirect lighting, but at the price of a much longer rendering. It is declared as follow:

One and only one of these three sampling schemes must be selected: random, regular and stratified.

The random scheme is selected with the following code fragment:

The regular scheme is selected with the following code fragment:

Finally, The stratified scheme is selected with the following code fragment:

The attributes samples, width and height must be set to strictly positive integer values.

When using the regular and stratified sampling schemes, it is very important to set the width attribute to a value 4 times greater than the height value. This will ensure proper sampling of the final gathering hemisphere.

If present, the <SecondaryFinalGathering /> element instructs toxic to perform a secondary final gathering when needed. The secondary final gathering improves indirect lighting in corners and along edges.

The syntax is essentially the same as for the <PrimaryFinalGathering /> element. It just takes an additional distancethreshold attribute:

The distancethreshold attribute specifies the distance below which toxic must perform a secondary final gathering. It must be set to a strictly positive real value.

Here is a sample, complete indirect lighting settings block:

Specular reflections are computed if and only if the following block appear in the <Components /> element:

The <SpecularReflections /> element can not appear more than once inside the <Components /> element.

The maxdepth attribute specifies the maximum reflection level to take into account. The minimum value is 0. There is no maximum value. If set to 0, specular reflection will never be computed.

Caustics are computed if and only if the following block appear in the <Components /> element:

The <Caustics /> element can not appear more than once inside the <Components /> element.

Required indirect lighting settings:

• Photon tracing settings: <PhotonTracing />.
• Radiance estimate settings: <RadianceEstimate />.

Optional indirect lighting settings:

• None.

The <PhotonTracing /> element allows to specify the total number of photons to emit from light sources. It is declared as follow:

The photons attribute specifies how many photons must be emitted. It must be set to a strictly positive integer value.

The <RadianceEstimate /> element is declared as follow:

The maxphotons attribute is the maximum number of photons to take into account when estimating radiance at a given point of the scene. It must be set to a strictly positive integer value. The maxdistance attribute is the maximum distance to include a photon. It must be set to a strictly positive real value.

Photons are gathered until one the bounds (on distance or photon count) is reached.

Here is a sample, complete caustics settings block:

Output settings are grouped together into an <Output /> element:

One and only one <Output /> element must appear inside the root element.

Syntax:

If present, the <GammaCorrection /> element instructs toxic to gamma correct the rendered image. The desired gamma value is defined by the targetgamma attribute, which must be a strictly positive real value.

The <GammaCorrection /> element can not appear more than once inside the <Output /> element.

You can get the full XML Schema describing scene settings file format here.

You may want to start from this template file to write your own scene settings files. This file uses the following settings:

• Whitted adaptive antialiasing is used with a contrast threshold of 0.025 and a maximum subdivision depth of 3.
• Only the direct lighting component is computed. Not indirect illumination, no specular reflections and no caustics.
• The rendered image is gamma corrected for a target gamma value of 2.2.

Here are some other scene settings files to browse:

• cornellbox.settings.xml
• gally.settings.xml
• ring.settings.xml