Library Glossary
The following table lists all core supported types for node inputs, outputs and tokens types.
These are defined as 'typedef' elements in the standard library. The name of the 'typedef' is used
to specify the `type' of an input, output or token.
Note that except for the 'Description', the column headings for this section are the attribute names
on a 'typedef'.
Though new types can theoretically be defined this is not recommended as these new types is not
automatically recognized. For instance, both file I/O and shader generation will not recognize these types.
The associated API for a 'typedef' is TypeDef
and can be accessed via the 'getTypeDef()'
document API.
Note that the type 'geomname' is not used as a type for inputs, outputs or tokens and 'none'
was used for background nodes but has been deprecated as of version 1.38.
type
semantic
context
Description
BSDF
BSDF
EDF
EDF
VDF
VDF
boolean
boolean
color3
color
3 component color
color3array
color
color3 array
color4
color
4 component color
color4array
color
color4 array
displacementshader
shader
displacement
displacement shader
filename
URI to a file
float
float
floatarray
float array
geomname
Geometry DAG path. Use in material assignments
geomnamearray
geomname array
integer
integer
integerarray
integer array
lightshader
shader
light
light shader
material
material
material
matrix33
3 by 3 matrix
matrix44
4 by 4 matrix
none
Deprecated
string
string
stringarray
string array
surfaceshader
shader
surface
surface shader
vector2
vector2
vector2array
vector2 array
vector3
3 component vector
vector3array
vector3 array
vector4
4 component vector
vector4array
vector4 array
volumeshader
shader
volume
volume shader
Built-in geometry identifiers ('geomdefprop') are provided as part of the standard library. Each has a unique name,
a type, and the space that the input geometry resides in. For convenience the geometry type and
space are reflected in the name. For example: "Pobject" is position in object space. Only node definitions may
specify these identifiers in the 'defaultgeomprop' attribute for an
'input'.
The corresponding API class is
GeomPropDef
The bump definition contains an example of specifying it's
'normal' input as defaulting to routing world space normals as input by default.
Note that except for the 'Description', the column headings for this section are the attribute names
for a 'geomdefprop'.
name
type
geomprop
space
Description
Vworld
vector3
viewdirection
world
V in world space
Pobject
vector3
position
object
Position in object space
Nobject
vector3
normal
object
Normal in object space
Tobject
vector3
tangent
object
Tangent in object space
Bobject
vector3
bitangent
object
Bitangent in object space
Pworld
vector3
position
world
Position in world space
Nworld
vector3
normal
world
Normal in world space
Tworld
vector3
tangent
world
Tangent in world space
Bworld
vector3
bitangent
world
Bitangent in world space
UV0
vector2
texcoord
First texture coordinate set
A float, vector, and matrix input values can be specified in real world units. There are different
types of units which can be used. For now only distance and angle unit types are supported.
For each unit a scaling factor is provided relative to the "base" unit which has a scale value of
1. For instance the unit "foot" has a scale of "0.3048" which means that to convert from a foot
value to a "meter" the given scaling must be applied.
'rotate3d' shows an example of defining units for input angle.
Note that both the unit type ('unitype' attribute) and unit name ('unit' attribute) must be
specified together to be valid. Except for the 'Description', the column headings for this
section are the attribute names on the respective elements.
The API class interface for a 'unit' is Unit and for a 'unittype' is
UnitTypeDef
Example usage of units for code generation can be found in the
Python Shader Generation Example
Unit Type: distance
unit
scale
Description
nanometer
0.000000001
nanometer
micron
0.000001
micron
millimeter
0.001
millimeter
centimeter
0.01
centimeter
inch
0.0254
inch
foot
0.3048
foot
yard
0.9144
yard
meter
1.0
meter
kilometer
1000.0
kilometer
mile
1609.344
mile
Unit Type: angle
unit
scale
Description
degree
1.0
degree
radian
57.295779513
radian
Node Definitions
As of 1.38.8 color space transforms have node definitions and can thus be
instantiated as nodes in a shader graph. Each definition name is of the form:
being:
<source_space_name>_to_<definition_space_name>
such that source and destination color space names conform those found in the
AcesCg 1.2 OCIO configuration.
All definitions use the node group `colortransform` and can be found under that group
in the library reference:
An example is the AcesCg to LinRec709 transform
Note that any transforms which are currently specified as only
implementations will need to provide a node definition in addition to the implementation or they will not be
recognized as being a valid source color space. This includes usage within shader code generation.
Usage on Inputs
A color space transform can be used by specifying the source space 'colorspace' attribute on the any 3 and 4 channel color inputs.
It is invalid to set this on any other element type.
The artistic_ior definition shows an example of
specifying an 'edge_color' input 'colorspace' as 'lin_rec709'.
In the same example the 'ior' input has a 'colorspace' value of 'none'. 'none' has a special
meaning which indicates that the input should not be interpreted as a color
which can be transformed (there is no color swatch to indicate this).
For evaluation, the 'colorspace' attribute value can be parsed to determine the input colorspace.
For code generation, either the
colorspace name is passed on to the generated shader code, or it is replaced with color transformation code
which is added into the generated shader code. A code generation option is provided for user control.
The corresponding API class for a transform is
ColorSpaceTransform
Example usage of color management for code generation can be found in the
Python Shader Generation Example
Available Transforms
The list of currently available transforms is listed in the table below:
Source Color Space
Destination Color Space
Color Type
g18_rec709
lin_rec709
color3
g18_rec709
lin_rec709
color4
g22_rec709
lin_rec709
color3
g22_rec709
lin_rec709
color4
rec709_display
lin_rec709
color3
rec709_display
lin_rec709
color4
acescg
lin_rec709
color3
acescg
lin_rec709
color4
g22_ap1
lin_rec709
color3
g22_ap1
lin_rec709
color4
srgb_texture
lin_rec709
color3
srgb_texture
lin_rec709
color4
lin_adobergb
lin_rec709
color3
lin_adobergb
lin_rec709
color4
adobergb
lin_rec709
color3
adobergb
lin_rec709
color4
srgb_displayp3
lin_rec709
color3
srgb_displayp3
lin_rec709
color4
lin_displayp3
lin_rec709
color3
lin_displayp3
lin_rec709
color4
The following table lists all core supported types for node inputs, outputs and tokens types.
These are defined as 'typedef' elements in the standard library. The name of the 'typedef' is used to specify the `type' of an input, output or token. Note that except for the 'Description', the column headings for this section are the attribute names on a 'typedef'.
Though new types can theoretically be defined this is not recommended as these new types is not automatically recognized. For instance, both file I/O and shader generation will not recognize these types.
The associated API for a 'typedef' is TypeDef and can be accessed via the 'getTypeDef()' document API.
Note that the type 'geomname' is not used as a type for inputs, outputs or tokens and 'none' was used for background nodes but has been deprecated as of version 1.38.
| type | semantic | context | Description |
|---|
| BSDF | BSDF | ||
| EDF | EDF | ||
| VDF | VDF | ||
| boolean | boolean | ||
| color3 | color | 3 component color | |
| color3array | color | color3 array | |
| color4 | color | 4 component color | |
| color4array | color | color4 array | |
| displacementshader | shader | displacement | displacement shader |
| filename | URI to a file | ||
| float | float | ||
| floatarray | float array | ||
| geomname | Geometry DAG path. Use in material assignments | ||
| geomnamearray | geomname array | ||
| integer | integer | ||
| integerarray | integer array | ||
| lightshader | shader | light | light shader |
| material | material | material | |
| matrix33 | 3 by 3 matrix | ||
| matrix44 | 4 by 4 matrix | ||
| none | Deprecated | ||
| string | string | ||
| stringarray | string array | ||
| surfaceshader | shader | surface | surface shader |
| vector2 | vector2 | ||
| vector2array | vector2 array | ||
| vector3 | 3 component vector | ||
| vector3array | vector3 array | ||
| vector4 | 4 component vector | ||
| vector4array | vector4 array | ||
| volumeshader | shader | volume | volume shader |
Built-in geometry identifiers ('geomdefprop') are provided as part of the standard library. Each has a unique name, a type, and the space that the input geometry resides in. For convenience the geometry type and space are reflected in the name. For example: "Pobject" is position in object space. Only node definitions may specify these identifiers in the 'defaultgeomprop' attribute for an 'input'.
The corresponding API class is GeomPropDef
The bump definition contains an example of specifying it's 'normal' input as defaulting to routing world space normals as input by default.
Note that except for the 'Description', the column headings for this section are the attribute names for a 'geomdefprop'.
| name | type | geomprop | space | Description |
|---|---|---|---|---|
| Vworld | vector3 | viewdirection | world | V in world space |
| Pobject | vector3 | position | object | Position in object space |
| Nobject | vector3 | normal | object | Normal in object space |
| Tobject | vector3 | tangent | object | Tangent in object space |
| Bobject | vector3 | bitangent | object | Bitangent in object space |
| Pworld | vector3 | position | world | Position in world space |
| Nworld | vector3 | normal | world | Normal in world space |
| Tworld | vector3 | tangent | world | Tangent in world space |
| Bworld | vector3 | bitangent | world | Bitangent in world space |
| UV0 | vector2 | texcoord | First texture coordinate set |
A float, vector, and matrix input values can be specified in real world units. There are different types of units which can be used. For now only distance and angle unit types are supported.
For each unit a scaling factor is provided relative to the "base" unit which has a scale value of 1. For instance the unit "foot" has a scale of "0.3048" which means that to convert from a foot value to a "meter" the given scaling must be applied.
'rotate3d' shows an example of defining units for input angle.
Note that both the unit type ('unitype' attribute) and unit name ('unit' attribute) must be specified together to be valid. Except for the 'Description', the column headings for this section are the attribute names on the respective elements.
The API class interface for a 'unit' is Unit and for a 'unittype' is UnitTypeDef
Example usage of units for code generation can be found in the
Python Shader Generation Example
| unit | scale | Description |
|---|---|---|
| nanometer | 0.000000001 | nanometer |
| micron | 0.000001 | micron |
| millimeter | 0.001 | millimeter |
| centimeter | 0.01 | centimeter |
| inch | 0.0254 | inch |
| foot | 0.3048 | foot |
| yard | 0.9144 | yard |
| meter | 1.0 | meter |
| kilometer | 1000.0 | kilometer |
| mile | 1609.344 | mile |
| unit | scale | Description |
|---|---|---|
| degree | 1.0 | degree |
| radian | 57.295779513 | radian |
Node Definitions
As of 1.38.8 color space transforms have node definitions and can thus be instantiated as nodes in a shader graph. Each definition name is of the form: being:
<source_space_name>_to_<definition_space_name>
such that source and destination color space names conform those found in the
AcesCg 1.2 OCIO configuration.
All definitions use the node group `colortransform` and can be found under that group
in the library reference:
An example is the AcesCg to LinRec709 transform
Note that any transforms which are currently specified as only implementations will need to provide a node definition in addition to the implementation or they will not be recognized as being a valid source color space. This includes usage within shader code generation.
Usage on Inputs
A color space transform can be used by specifying the source space 'colorspace' attribute on the any 3 and 4 channel color inputs. It is invalid to set this on any other element type.
The artistic_ior definition shows an example of specifying an 'edge_color' input 'colorspace' as 'lin_rec709'.
In the same example the 'ior' input has a 'colorspace' value of 'none'. 'none' has a special meaning which indicates that the input should not be interpreted as a color which can be transformed (there is no color swatch to indicate this).
For evaluation, the 'colorspace' attribute value can be parsed to determine the input colorspace. For code generation, either the colorspace name is passed on to the generated shader code, or it is replaced with color transformation code which is added into the generated shader code. A code generation option is provided for user control.
The corresponding API class for a transform is ColorSpaceTransform
Example usage of color management for code generation can be found in the
Python Shader Generation Example
Available Transforms
The list of currently available transforms is listed in the table below:
| Source Color Space | Destination Color Space | Color Type |
|---|---|---|
| g18_rec709 | lin_rec709 | color3 |
| g18_rec709 | lin_rec709 | color4 |
| g22_rec709 | lin_rec709 | color3 |
| g22_rec709 | lin_rec709 | color4 |
| rec709_display | lin_rec709 | color3 |
| rec709_display | lin_rec709 | color4 |
| acescg | lin_rec709 | color3 |
| acescg | lin_rec709 | color4 |
| g22_ap1 | lin_rec709 | color3 |
| g22_ap1 | lin_rec709 | color4 |
| srgb_texture | lin_rec709 | color3 |
| srgb_texture | lin_rec709 | color4 |
| lin_adobergb | lin_rec709 | color3 |
| lin_adobergb | lin_rec709 | color4 |
| adobergb | lin_rec709 | color3 |
| adobergb | lin_rec709 | color4 |
| srgb_displayp3 | lin_rec709 | color3 |
| srgb_displayp3 | lin_rec709 | color4 |
| lin_displayp3 | lin_rec709 | color3 |
| lin_displayp3 | lin_rec709 | color4 |