Mappings Syntax

A "mapping" is a line of text that associates a value with part of a 3D scene. Mappings can modify values in the Collada scene file, or in the [adjustments file](Adjustments Files) for the current renderer. Modifying the adjustments file allows users to specify scene elements that Collada doesn't know about, like sampled spectra and area lights.

Combined with a [conditions file](Conditions File Format), mappings can cause one scene to be rendered with multiple variants.

Mappings must be specified in a [mappings file](Mappings File Format).

Basic Form

A mapping is a line of text with the general form:

target operator value

The value specifies a value, to apply to part of the 3D scene. The operator controls how the value will be applied to the scene. The target specifies the part of the 3D scene to modify.

There are a few variations on this form, using different types of target, operator, or value.

Values

RenderToolbox3 uses 3 types of value:

• Basic strings are treated as constants. For example 1.0 or `D65.spd'.
• A string enclosed in [] square braces must contain a Scene DOM path to be looked up in the Collada scene file. For example, [Camera-camera:optics:technique_common:orthographic:xmag].
• A string enclosed in <> angle braces must contain a Scene DOM path to be looked up in the adjustments file for the current renderer. For example, <integrator:integer|name=shadingSamples>.

See Scene DOM Paths for more about Scene DOM paths.

Operators

RenderToolbox3 uses 5 types of operator:

• = assigns the value to the target.
• += adds the value to the target.
• -= subtracts the value from the target.
• *= multiplies the value with the target.
• /= divides the target by the value.

Operators must be flanked by spaces, to distinguish them from targets and values that might contain similar characters.

Targets

RenderToolbox3 uses 2 types of target: Scene DOM paths, and Scene Targets. Scene DOM Paths are very flexible, but ugly. Scene Targets provide a convenient syntax for many common tasks. See Scene Targets below for more about Scene Targets.

Each type of mappings block accepts targets of one type:

• Collada blocks use Scene DOM Paths.
• PBRT and 'Mitsuba' blocks use Scene Targets, with renderer-native names and values.
• `Generic' blocks use Scene Targets, with [generic ](Generic Scene Elements) names and values.
• PBRT-path and 'Mitsuba-path' blocks use Scene DOM Paths.

Scene Targets

RenderToolbox3 defines a Scene Target syntax which is easier to use than Scene DOM paths.

Scene targets can declare scene elements, or configure existing elements. A declaration must take the following form:

id:category:type

Where id is a unique identifier of the new scene element, category is the name of a broad class of scene elements, like "Material" or "emitter", and type is a specific kind of scene element, like "plastic" or "directional".

Declarations should not use an operator or value.

A scene element configuration must take the following form:

id:property:type

Where id is the unique identifier of an existing scene element, property is the name of a property that the element exposes, such as "roughness" or "irradiance", and type is a value-type that is allowed for the named property, such as "float" or "spectrum".

Configurations should be followed by an operator and a value.

PBRT

Inside a PBRT block, scene targets may use category, property, and type names that only PBRT knows about. For example, these scene targets would declare and configure a new PBRT material:

myMaterial:Material:plastic
myMaterial:roughness.float = 0.2

The words Material, plastic, roughness, and float are all native to PBRT's scene file format.

Mitsuba

Likewise, inside a Mitsuba block, scene targets may use category, property, and type names that only Mitsuba knows about. For example, these scene targets would declare and configure a new Mitsuba light source:

myLight:emitter:directional
myLight:irradiance.spectrum = mySpectrum.spd

The words emitter, directional, irradiance, and spectrum are all native to Mitsuba's scene file format.

Generic

Inside a Generic block, scene targets must use category, property, and type names that are defined in RenderToolbox3's Generic Scene Elements. For example, these scene targets would declare and configure a new material and light source, for use with either renderer:

% a generic anisotropic Ward material
myMaterial:material:anisoward
myMaterial:alphaU.float = 0.1

% a generic directional light
myLight:light:directional
myLight:intensity.spectrum = mySpectrum.spd

The words material, anisoward, alphaU, and float are all defined as part of the RenderToolbox3 generic Ward material.

Likewise, the words light, directional, intensity, and spectrum are all defined as part of the RenderToolbox3 generic directional light source.