-
Notifications
You must be signed in to change notification settings - Fork 2
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).
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
.
RenderToolbox3 uses 3 types of value
:
- Basic strings are treated as constants. For example
1.0
orD65.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.
RenderToolbox3 uses 5 types of operator
:
-
=
assigns thevalue
to thetarget
. -
+=
adds thevalue
to thetarget
. -
-=
subtracts thevalue
from thetarget
. -
*=
multiplies thevalue
with thetarget
. -
/=
divides thetarget
by thevalue
.
The operator
must be flanked by spaces, to distinguish it from the target
and value
, which might contain similar characters.
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.
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
.
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.
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.
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.