Mappings Syntax

A "mapping" is a line of text that specifies a manipulation to be applied to a scene element, or a renderer behavior. 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 allow a single parent scene to be converted into a family of related renderer-native scene files and renderings.

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 is a string 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.

The operator must be flanked by spaces, to distinguish it from the target and value, which 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.

Each type of mappings block accepts targets of one type:

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

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 Scene Target Example

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:

PBRT {
    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 Scene Target Example

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:

Mitsuba {
    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 Scene Target Example

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:

Generic {
    % 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.