Skip to content

Mappings Syntax

Jump to bottom Edit New page
benjamin-heasly edited this page Jan 31, 2013 · 23 revisions

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 samples 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:

  • [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.

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 left- and values that contain similar characters. For example, Scene DOM Paths may also contain the equals sign =.

Targets

RenderToolbox3 uses 2 types of 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. The value will be applied to this part of the adjustments file for the current renderer. This type of target is only valid inside PBRT and Mitsuba blocks.
  • Unenclosed targets are interpreted differently, depending on the block name:
    • Collada unenclosed targets should contain Scene DOM paths. The value will be applied to the Collada scene file.
    • PBRT, Mitsuba, and Generic unenclosed targets should use scene target syntax. The value will be applied to the adjustments file for the current renderer.

See below for more about scene target syntax.

Scene Targets

RenderToolbox3 defines a scene target syntax which is easier to use than Scene DOM paths. Scene target syntax is allowed in the target of mappings inside PBRT, Mitsuba, and Generic blocks of the [mappings file](Mappings File Format).

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: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.

Add a custom footer
Add a custom sidebar
Clone this wiki locally