-
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 a Collada scene file. They can also specify scene elements that Collada doesn't know about, but renderers do know about. Combined with a [conditions file](Conditions File Format), mappings can create scene variants to be rendered.
Mappings must be specified in a [mappings file](Mappings File Format).
A mapping is a line of text with the general form:
left-hand target
operator
right-hand value
The right-hand 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 left-hand 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 right-hand value
:
-
[Collada path]
A value enclosed in[]
square braces should contain a Scene DOM path. This value will be looked up in the Collada scene file. -
<Adjustments path>
A value enclosed in<>
angle braces should contain a Scene DOM path. This value will be looked up in the adjustments file for the current renderer. - Unenclosed values will be treated as regular, constant
strings
.
See Scene DOM Paths for more about Scene DOM paths.
RenderToolbox3 uses 5 types of operator
:
-
=
assigns theright-hand value
to theleft-hand target
. -
+=
adds theright-hand value
to theleft-hand target
. -
-=
subtracts theright-hand value
from theleft-hand target
. -
*=
multiplies theright-hand value
with theleft-hand target
. -
/=
divides theleft-hand target
by theright-hand value
.
RenderToolbox3 uses 2 types of left-hand target
. The interpretation of the target depends on the [mappings file](Mappings File Format) block that contains the mapping.
-
<Adjustments path>
A target enclosed in<>
angle braces should contain a Scene DOM path. Theright-hand value
will be applied to this part of the adjustments file for the current renderer. This type of target is only valid inPBRT
andMitsuba
blocks. - Unenclosed targets are interpreted differently, depending on the block name:
-
Collada
target should be a Scene DOM path.right-hand value
applies to the Collada scene file. -
PBRT
target should use generic mappings syntax.right-hand value
applies to the PBRT adjustments file. PBRT-native type names and parameter names are allowed. -
Mitsuba
target should use generic mappings syntax.right-hand value
applies to the Mitsuba adjustments file. Mitsuba-native type names and parameter names are allowed. -
Generic
target should use generic mappings syntax.right-hand value
will be applied to the adjustments file for the current renderer. Only generic scene elements are allowed.
-
See below for more about generic mappings syntax.
RenderToolbox3 defines a "generic mapping" syntax which is easier to use than Scene DOM paths. Generic mapping syntax is allowed in the left-hand target
of mappings contained in PBRT
, Mitsuba
, and Generic
blocks of the [mappings file](Mappings File Format).
Generic mappings 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 right-hand 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 right-hand value
.
Inside a PBRT
block, generic mappings may use category
, property
, and type
names that only PBRT knows about. For example, these generic mappings 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, generic mappings may use category
, property
, and type
names that only Mitsuba knows about. For example, these generic mappings 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, generic mappings must use category
, property
, and type
names that are defined in RenderToolbox3'sn Generic Scene Elements. For example, these generic mappings would declare and configure a new material and light source, for use with either renderer:
% a generic anisotropic Ward material
myMaterial:material:ward
myMaterial:alphaU.float = 0.1
% a generic directional light
myLight:light:directional
myLight:intensity.spectrum = mySpectrum.spd
The words material
, ward
, 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.