Materials

Monolithic Materials

Type

Attribute

Description

string

material.<renderer><ShaderCategory>Shader

The name of the renderer-specific shader to use for the shader category with the given name, for example:

material.dlSurfaceShader = "dlPrincipled"

group

material.<renderer><ShaderCategory>Params

A group that contains attributes that represent the parameters of the shader that is referenced by the material.<renderer><ShaderCategory>Shader attribute.

For example, a material.dlSurfaceParams group attribute contains attributes that represent the parameters of the shader referenced in material.dlSurfaceShader.

group

material.ops

See Deferred Material Ops.

Network Materials

Type

Attribute

Description

group

material.parameters

Contains a child attribute for every Material Interface parameter of the Network Material which has been altered from its default value, for example using a Material node in edit mode.

any

material.parameters.<exposedParameter>

The current value of the exposed parameter with the given name expressed as an attribute, for example:

material.parameters.Thickness = 0.73f

group

material.nodes

Contains child attributes for each shading node contributing to the Network Material represented by the material group attribute.

group

material.nodes.<node>

Contains child attributes that describe the shading node with the given name, for example dlPrincipled25.

string

material.nodes.<node>.name

The name of the shading node, as determined by the value of the name parameter of the corresponding Katana shading node, for example:

material.nodes.dlPrincipled25.name = "dlPrincipled25"

string

material.nodes.<node>.type

The type of the shading node, as determined by the value of the nodeType parameter of the corresponding Katana shading node, referencing a particular shader that the node represents by its name, for example:

material.nodes.dlPrincipled25.type = "dlPrincipled"

string

material.nodes.<node>.target

The name of the renderer that the shading node targets, for example:

material.nodes.dlPrincipled25.target = "dl"

string

material.nodes.<node>.srcName

The name of the Katana node that created this attribute, for example:

material.nodes.dlPrincipled25.srcName = "dlPrincipled25"

group

material.nodes.<node>.parameters

Contains a child attribute for every shader parameter of the node which has been altered from its default value.

any

material.nodes.<node>.parameters.<parameter>

The altered value of the parameter with the given name expressed as an attribute, for example:

material.nodes.dlPrincipled25.parameters.coating_thickness = 0.48f

If the parameter is exposed in the Material Interface of the Network Material (see material.interface below), this value is used as the default value for the parameter in the Material Interface.

group

material.nodes.<node>.connections

Contains a child attribute for every connection going into the node.

Note that non-contributing nodes are skipped for connections expressed by this attribute (e.g. Dot nodes and disabled nodes), whereas material.layout.<node>.connections (see below) takes those into account.

string

material.nodes.<node>.connections.<inputPort>

A reference to the output port on another node, given in the format <sourcePort>@<sourceNode>, which is connected to the input port with the given name, for example:

material.nodes.dlPrincipled25.connections.color = "outColor@myChecker"

group

material.terminals

Contains two child attributes for every terminal of the Network Material that is represented by the material group attribute.

string

material.terminals.<renderer><ShaderCategory>

The name of the shading node connected to the terminal with the given name (which consists of the name of the renderer and the name of the shader category), for example:

material.terminals.dlSurface = "dlPrincipled25"

string

material.terminals.<renderer><ShaderCategory>Port

The name of the output port on the shading node with the name that is specified in the material.terminals.<renderer><ShaderCategory> attribute, for example:

material.terminals.dlSurfacePort = "outColor"

group

material.interface

Contains child group attributes for each shader parameter that has been exposed for the Material Interface of the Network Material.

group

material.interface.<exposedParameter>

Contains child attributes that describe the exposed parameter with the given name, for example Thickness, or Roughness.

string

material.interface.<exposedParameter>.src

The path of the source parameter that the exposed parameter represents, given in the format <node>.<parameter>, e.g. "dlPrincipled25.coating_thickness", or "dlPrincipled25.roughness", for example:

material.interface.Thickness.src = "dlPrincipled25.coating_thickness"

group

material.interface.<exposedParameter>.hints

Contains child attributes for hints that have been set for the exposed parameter, which depend on the type of the parameter and the type of widget used for it. A couple of common parameter hints are documented below. For more information, see Widgets and Hints.

string

material.interface.<exposedParameter>.hints.help

Help text that has been set for the exposed parameter, which is made available to the user in the form of a help button in the parameter’s UI.

string

material.interface.<exposedParameter>.hints.page

The title of a page under which the exposed parameter is to appear, for example "Coating", or "Base".

string

material.style

Indicates the type of material that the material group attribute represents.

For Network Materials, material.style is set to "network".

For Monolithic Materials, the material.style attribute is not set.

string

material.info.name

The name of the NetworkMaterial node that created the Network Material.

int

material.info.layoutVersion

The version number of the material.layout attribute convention.

int

material.info.sourceLayoutVersion

The source network’s version number of the material.layout attribute convention. This will be zero for a legacy NetworkMaterial.

group

material.layout

Added for Network Materials created by NetworkMaterialCreate nodes. See Network Material Layout Attributes section below.

Network Material Layout Attributes

Note: Some attributes are equivalent to material.nodes attributes to ensure their availability for non-contributing nodes, e.g. Dot nodes and disabled nodes. Those nodes do not contribute to the Network Material’s result when it comes to rendering.

Type

Attribute

Description

group

material.layout

Similar to material.nodes, the material.layout group attribute contains child attributes for each shading node contributing to the Network Material represented by the material group attribute. In addition to shading nodes, other types of nodes are covered as well, which are part of the layout of the shading node network, for example Dot nodes, Switch nodes, and Backdrop nodes.

The layout information stored in material.layout can be used by UI components to restore a shading node network with its full layout, including node positions and colors. The attribute can typically safely be ignored by renderer plug-ins, as shading node layout information is not typically meaningful for rendering a scene.

group

material.layout.<node>

Contains child attributes that describe the Katana node with the given name, for example dlPrincipled25.

string

material.layout.<node>.katanaNodeType

The name of the type of the Katana node described by the material.layout.<node> group attribute, for example:

material.layout.dlPrincipled25.katanaNodeType = "DlShadingNode"

(A shading node type name is created as "%sShadingNode" % rendererName.capitalize(), for example DlShadingNode.)

float[3]

material.layout.<node>.color

The RGB component values of a color that has been applied to the node, for example:

material.layout.bump3d2.color = [0.45f, 0.25f, 0.25f]

string

material.layout.<node>.comment

A comment that has been set for the node, which may contain multiple lines of text.

int (bool)

material.layout.<node>.disabled

Boolean flag that states whether the node is disabled (1) or not (0), for example:

material.layout.bump3d2.disabled = 1

By default, nodes are enabled, and this attribute is not set.

string

material.layout.<node>.parent

The name of the NetworkMaterialCreate or ShadingGroup node that contains the Katana node with the given name, for example:

material.layout.Dot1.parent = "NetworkMaterialCreate4"

double[2]

material.layout.<node>.position

The position of the Katana node as X and Y coordinates within its parent group node’s node graph, for example:

material.layout.bump3d2.position = [-54.0, 13.5]

string[]

material.layout.<node>.connections

A list of descriptions of connections going into the node, each following the format <inputPort>:<sourcePort>@<sourceNode>, for example:

material.nodes.dlPrincipled25.connections = ["color:output@Dot1", "anisotropy_direction:outNormal@bump3d2"]

Note that non-contributing nodes are taken into account for connections expressed by this attribute (e.g. Dot nodes and disabled nodes), whereas material.nodes.<node>.connections (see above) skips them.

int (enum)

material.layout.<node>.viewState

A shading node’s view state:
  • 0: show the node in a minimal/collapsed state without any ports

  • 1: show connected ports only

  • 2: show all ports (default)

group

material.layout.<node>.nodeShapeAttributes

A group containing all of the node’s shape attributes. Supported types for child attributes are StringAttribute & FloatAttribute.

group

material.layout.<node>.parameters

A group containing a representation of all of the node’s locally set parameters as they would appear under material.nodes.

group

material.layout.<node>.parameterVars

A group containing a representation of all the node’s parameters, detailing their enabled state, value and type (see section below).

group

material.layout.<node>.userParameters

A group containing a representation of all of the node’s “user” parameters.

group

material.layout.<node>.nodeSpecificAttributes

A group containing any node type-specific attributes (see section below).

Parameter Variables Layout Attributes

All attributes in this section are inside the following attribute group: material.layout.<node>.parameterVars.<parameter>.

These attributes represent the raw parameter state before they are baked. In particular, these variables reflect what is shown in the Parameters tab.

Type

Attribute

Description

int

.enable

Trinary flag to indicate whether, when baked, this parameter should forcibly use the default value (-1), inherit the value set upstream (0), or use the locally set value (1).

any

.value

The locally set value of this parameter.

string

.type

A string representation of this parameter’s type.

Node Type-Specific Network Material Layout Attributes

Note: Some attributes are equivalent to material.nodes attributes to ensure their availability for non-contributing nodes.

All attributes in this section are inside the following attribute group: material.layout.<node>.nodeSpecificAttributes

Shading Node

Type

Attribute

Description

string

.name

The value of the name parameter of the Katana shading node, equivalent to material.nodes.<node>.name.

string

.shaderType

The value of the nodeType parameter of the Katana shading node, equivalent to material.nodes.<node>.type (named differently here to reduce ambiguity).

string

.target

The name of the renderer that the shading node targets, equivalent to material.nodes.<node>.target.

string[]

.expandedPages

A list of names of pages that are expanded to reveal their contents, with subpages denoted by > characters.

string[]

.collapsedPages

A list of names of pages that are collapsed to hide their contents, with subpages denoted by > characters.

Dot

Type

Attribute

Description

int (bool)

.displayAsDot

Boolean flag that states whether to display a Dot node with a round node shape (1) or with the standard node shape (0, aka. basic display), which shows view flag, node name, and edit flag.

By default, Dot nodes are displayed with a round node shape, and this attribute is not set.

Backdrop

Type

Attribute

Description

double[2]

.size

The size of the Backdrop node as width and height.

string

.text

The text of the Backdrop node.

float

.fontScale

The font scale used for the Backdrop node, as a multiplier (default: 1.0f) of the text size used for node names.

float

.zDepth

The Z order index of the Backdrop node.

Switch

Type

Attribute

Description

int

.size

The value of the Switch node’s ‘in’ parameter.

group

.inputs

The names and “display names” of the node’s input ports.

ShadingNodeArrayConnector

Type

Attribute

Description

group

.inputs

The names and “display names” of the node’s input ports.

VariableSwitch

Type

Attribute

Description

string

.variableName

The value of the VariableSwitch node’s ‘in’ parameter.

group

.patterns

The names and values of the node’s “patterns” child parameters.

group

.inputs

The names and display name labels of the node’s input ports.

ShadingGroup

Type

Attribute

Description

string[]

.expandedPages

A list of names of pages that are expanded to reveal their contents in the external interface of the ShadingGroup node, with subpages denoted by > characters.

string[]

.collapsedPages

A list of names of pages that are collapsed to hide their contents in the external interface of the ShadingGroup node, with subpages denoted by > characters.

group

.outputSidebar

Group containing the page expansion state for the internal output interface, in the form of .expandedPages and .collapsedPages child string attributes equivalent to those describing the external interface.

group

.inputSidebar

Group containing the page expansion state for the internal input interface, in the form of .expandedPages and .collapsedPages child string attributes equivalent to those describing the external interface.

group

.outputPorts

Group containing an entry for every output port of the ShadingGroup node.

string

.outputPorts.<port>.name

The unique identifier name of the port.

string

.outputPorts.<port>.displayName

The display name label of the port.

string[]

.outputPorts.<port>.tags

A list of string tag expressions for valid port connections.

group

.inputPorts

Group containing an entry for every output port of the ShadingGroup node.

string

.inputPorts.<port>.name

The unique identifier name of the port.

string

.inputPorts.<port>.displayName

The display name label of the port.

string[]

.inputPorts.<port>.tags

A list of string tag expressions for valid port connections.

string[]

.returnConnections

A list of valid return connections, with each entry matching the format <returnPort>:<sourcePort>@<sourceNode>.

Assigning Materials

To assign a material to an object, set a materialAssign string attribute on the scene graph location that represents the object to the path of the scene graph location of the material to assign.

Type

Attribute

Description

string

materialAssign

The path of the scene graph location of the assigned material, for example /root/materials/carPaint.

Material Underlays

Type

Attribute

Description

group

material.underlayAttrs

An attribute that, at material resolve time, is copied to the root level of the target location’s attributes, and merged underneath any existing attribute values at that location.

This allows, for example, custom “default” renderer object settings to be specified for locations, which can be overridden by any locally-set values.

group

info.material.underlayAttrs

This is primarily for debug purposes. After the implicit resolve these attributes are moved so that you can still see which material underlays have been processed, but are no longer at risk of being resolved again.

Solo Materials

Soloing shading nodes in a NetworkMaterialCreate or NetworkMaterialEdit node will result in a soloMaterial attribute on the resulting material location. This is the standard material attribute for the soloed network, copied to a soloMaterial attribute group. The original NetworkMaterial material attribute will still be present.

See also

Material Solo Attribute Usage for more information on how the soloMaterial attribute is used.

Type

Attribute

Description

group

soloMaterial

A copy of the material attribute group of a solo NetworkMaterial.