Materials
=========
Monolithic Materials
--------------------
.. list-table::
:header-rows: 1
:widths: 5 20 75
- * Type
* Attribute
* Description
- * :kat:type:`string`
* :kat:attr:`material.<renderer><ShaderCategory>Shader`
* The name of the renderer-specific shader to use for the shader category
with the given name, for example:
:kat:attr:`material.dlSurfaceShader` = ``"dlPrincipled"``
- * :kat:type:`group`
* :kat:attr:`material.<renderer><ShaderCategory>Params`
* A group that contains attributes that represent the parameters of the
shader that is referenced by the
:kat:attr:`material.<renderer><ShaderCategory>Shader` attribute.
For example, a :kat:attr:`material.dlSurfaceParams` group attribute
contains attributes that represent the parameters of the shader
referenced in :kat:attr:`material.dlSurfaceShader`.
- * :kat:type:`group`
* :kat:attr:`material.ops`
* See :ref:`deferred-material-ops`.
Network Materials
-----------------
.. list-table::
:header-rows: 1
:widths: 5 20 75
- * Type
* Attribute
* Description
- * :kat:type:`group`
* :kat:attr:`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 :kat:node:`Material` node in edit mode.
- * :kat:type:`any`
* :kat:attr:`material.parameters.<exposedParameter>`
* The current value of the exposed parameter with the given name
expressed as an attribute, for example:
:kat:attr:`material.parameters.Thickness` = ``0.73f``
- * :kat:type:`group`
* :kat:attr:`material.nodes`
* Contains child attributes for each shading node contributing to the
Network Material represented by the :kat:attr:`material` group
attribute.
- * :kat:type:`group`
* :kat:attr:`material.nodes.<node>`
* Contains child attributes that describe the shading node with the given
name, for example :kat:attr:`dlPrincipled25`.
- * :kat:type:`string`
* :kat:attr:`material.nodes.<node>.name`
* The name of the shading node, as determined by the value of the
:kat:param:`name` parameter of the corresponding Katana shading node,
for example:
:kat:attr:`material.nodes.dlPrincipled25.name` = ``"dlPrincipled25"``
- * :kat:type:`string`
* :kat:attr:`material.nodes.<node>.type`
* The type of the shading node, as determined by the value of the
:kat:param:`nodeType` parameter of the corresponding Katana shading
node, referencing a particular shader that the node represents by its
name, for example:
:kat:attr:`material.nodes.dlPrincipled25.type` = ``"dlPrincipled"``
- * :kat:type:`string`
* :kat:attr:`material.nodes.<node>.target`
* The name of the renderer that the shading node targets, for example:
:kat:attr:`material.nodes.dlPrincipled25.target` = ``"dl"``
- * :kat:type:`string`
* :kat:attr:`material.nodes.<node>.srcName`
* The name of the Katana node that created this attribute, for example:
:kat:attr:`material.nodes.dlPrincipled25.srcName` =
``"dlPrincipled25"``
- * :kat:type:`group`
* :kat:attr:`material.nodes.<node>.parameters`
* Contains a child attribute for every shader parameter of the node which
has been altered from its default value.
- * :kat:type:`any`
* :kat:attr:`material.nodes.<node>.parameters.<parameter>`
* The altered value of the parameter with the given name expressed as an
attribute, for example:
:kat:attr:`material.nodes.dlPrincipled25.parameters.coating_thickness`
= ``0.48f``
If the parameter is exposed in the Material Interface of the Network
Material (see :kat:attr:`material.interface` below), this value is used
as the default value for the parameter in the Material Interface.
- * :kat:type:`group`
* :kat:attr:`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. :kat:node:`Dot` nodes and disabled nodes),
whereas :kat:attr:`material.layout.<node>.connections` (see below)
takes those into account.
- * :kat:type:`string`
* :kat:attr:`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:
:kat:attr:`material.nodes.dlPrincipled25.connections.color` =
``"outColor@myChecker"``
- * :kat:type:`group`
* :kat:attr:`material.terminals`
* Contains two child attributes for every terminal of the Network
Material that is represented by the :kat:attr:`material` group
attribute.
- * :kat:type:`string`
* :kat:attr:`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:
:kat:attr:`material.terminals.dlSurface` = ``"dlPrincipled25"``
- * :kat:type:`string`
* :kat:attr:`material.terminals.<renderer><ShaderCategory>Port`
* The name of the output port on the shading node with the name that is
specified in the
:kat:attr:`material.terminals.<renderer><ShaderCategory>` attribute,
for example:
:kat:attr:`material.terminals.dlSurfacePort` = ``"outColor"``
- * :kat:type:`group`
* :kat:attr:`material.interface`
* Contains child group attributes for each shader parameter that has been
exposed for the Material Interface of the Network Material.
- * :kat:type:`group`
* :kat:attr:`material.interface.<exposedParameter>`
* Contains child attributes that describe the exposed parameter with the
given name, for example :kat:attr:`Thickness`, or
:kat:attr:`Roughness`.
- * :kat:type:`string`
* :kat:attr:`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:
:kat:attr:`material.interface.Thickness.src` =
``"dlPrincipled25.coating_thickness"``
- * :kat:type:`group`
* :kat:attr:`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 :ref:`widgets-and-hints`.
- * :kat:type:`string`
* :kat:attr:`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.
- * :kat:type:`string`
* :kat:attr:`material.interface.<exposedParameter>.hints.page`
* The title of a page under which the exposed parameter is to appear, for
example ``"Coating"``, or ``"Base"``.
- * :kat:type:`string`
* :kat:attr:`material.style`
* Indicates the type of material that the :kat:attr:`material` group
attribute represents.
For Network Materials, :kat:attr:`material.style` is set to
``"network"``.
For Monolithic Materials, the :kat:attr:`material.style` attribute
is not set.
- * :kat:type:`string`
* :kat:attr:`material.info.name`
* The name of the :kat:node:`NetworkMaterial` node that created the
Network Material.
- * :kat:type:`int`
* :kat:attr:`material.info.layoutVersion`
* The version number of the :kat:attr:`material.layout` attribute
convention.
- * :kat:type:`int`
* :kat:attr:`material.info.sourceLayoutVersion`
* The source network's version number of the :kat:attr:`material.layout`
attribute convention. This will be zero for a legacy NetworkMaterial.
- * :kat:type:`group`
* :kat:attr:`material.layout`
* Added for Network Materials created by :kat:node:`NetworkMaterialCreate`
nodes. See :ref:`network-material-layout-attributes` section below.
.. _network-material-layout-attributes:
Network Material Layout Attributes
----------------------------------
Note: Some attributes are equivalent to :kat:attr:`material.nodes` attributes
to ensure their availability for non-contributing nodes, e.g. :kat:node:`Dot`
nodes and disabled nodes. Those nodes do not contribute to the Network
Material's result when it comes to rendering.
.. list-table::
:header-rows: 1
:widths: 5 20 75
- * Type
* Attribute
* Description
- * :kat:type:`group`
* :kat:attr:`material.layout`
* Similar to :kat:attr:`material.nodes`, the :kat:attr:`material.layout`
group attribute contains child attributes for each shading node
contributing to the Network Material represented by the
:kat:attr:`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 :kat:node:`Dot` nodes,
:kat:node:`Switch` nodes, and :kat:node:`Backdrop` nodes.
The layout information stored in :kat:attr:`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.
- * :kat:type:`group`
* :kat:attr:`material.layout.<node>`
* Contains child attributes that describe the Katana node with the given
name, for example :kat:attr:`dlPrincipled25`.
- * :kat:type:`string`
* :kat:attr:`material.layout.<node>.katanaNodeType`
* The name of the type of the Katana node described by the
:kat:attr:`material.layout.<node>` group attribute, for example:
:kat:attr:`material.layout.dlPrincipled25.katanaNodeType` =
``"DlShadingNode"``
(A shading node type name is created as
``"%sShadingNode" % rendererName.capitalize()``, for example
:kat:node:`DlShadingNode`.)
- * :kat:type:`float[3]`
* :kat:attr:`material.layout.<node>.color`
* The RGB component values of a color that has been applied to the node,
for example:
:kat:attr:`material.layout.bump3d2.color` = ``[0.45f, 0.25f, 0.25f]``
- * :kat:type:`string`
* :kat:attr:`material.layout.<node>.comment`
* A comment that has been set for the node, which may contain multiple
lines of text.
- * :kat:type:`int (bool)`
* :kat:attr:`material.layout.<node>.disabled`
* Boolean flag that states whether the node is disabled (``1``) or not
(``0``), for example:
:kat:attr:`material.layout.bump3d2.disabled` = ``1``
By default, nodes are enabled, and this attribute is not set.
- * :kat:type:`string`
* :kat:attr:`material.layout.<node>.parent`
* The name of the :kat:node:`NetworkMaterialCreate` or
:kat:node:`ShadingGroup` node that contains the Katana node with the
given name, for example:
:kat:attr:`material.layout.Dot1.parent` = ``"NetworkMaterialCreate4"``
- * :kat:type:`double[2]`
* :kat:attr:`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:
:kat:attr:`material.layout.bump3d2.position` = ``[-54.0, 13.5]``
- * :kat:type:`string[]`
* :kat:attr:`material.layout.<node>.connections`
* A list of descriptions of connections going into the node, each
following the format ``<inputPort>:<sourcePort>@<sourceNode>``, for
example:
:kat:attr:`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. :kat:node:`Dot` nodes and disabled
nodes), whereas :kat:attr:`material.nodes.<node>.connections` (see
above) skips them.
- * :kat:type:`int (enum)`
* :kat:attr:`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)
- * :kat:type:`group`
* :kat:attr:`material.layout.<node>.nodeShapeAttributes`
* A group containing all of the node's shape attributes. Supported types
for child attributes are :kat:attr:`StringAttribute` &
:kat:attr:`FloatAttribute`.
- * :kat:type:`group`
* :kat:attr:`material.layout.<node>.parameters`
* A group containing a representation of all of the node's
locally set parameters as they would appear under
:kat:attr:`material.nodes`.
- * :kat:type:`group`
* :kat:attr:`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).
- * :kat:type:`group`
* :kat:attr:`material.layout.<node>.userParameters`
* A group containing a representation of all of the node's
"user" parameters.
- * :kat:type:`group`
* :kat:attr:`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:
:kat:attr:`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.
.. list-table::
:header-rows: 1
:widths: 5 20 75
- * Type
* Attribute
* Description
- * :kat:type:`int`
* :kat:attr:`.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``).
- * :kat:type:`any`
* :kat:attr:`.value`
* The locally set value of this parameter.
- * :kat:type:`string`
* :kat:attr:`.type`
* A string representation of this parameter's type.
Node Type-Specific Network Material Layout Attributes
-----------------------------------------------------
Note: Some attributes are equivalent to :kat:attr:`material.nodes` attributes
to ensure their availability for non-contributing nodes.
All attributes in this section are inside the following attribute group:
:kat:attr:`material.layout.<node>.nodeSpecificAttributes`
**Shading Node**
.. list-table::
:header-rows: 1
:widths: 5 20 75
- * Type
* Attribute
* Description
- * :kat:type:`string`
* :kat:attr:`.name`
* The value of the :kat:param:`name` parameter of the Katana shading
node, equivalent to :kat:attr:`material.nodes.<node>.name`.
- * :kat:type:`string`
* :kat:attr:`.shaderType`
* The value of the :kat:param:`nodeType` parameter of the Katana shading
node, equivalent to :kat:attr:`material.nodes.<node>.type`
(named differently here to reduce ambiguity).
- * :kat:type:`string`
* :kat:attr:`.target`
* The name of the renderer that the shading node targets, equivalent to
:kat:attr:`material.nodes.<node>.target`.
- * :kat:type:`string[]`
* :kat:attr:`.expandedPages`
* A list of names of pages that are expanded to reveal their contents,
with subpages denoted by **>** characters.
- * :kat:type:`string[]`
* :kat:attr:`.collapsedPages`
* A list of names of pages that are collapsed to hide their contents,
with subpages denoted by **>** characters.
**Dot**
.. list-table::
:header-rows: 1
:widths: 5 20 75
- * Type
* Attribute
* Description
- * :kat:type:`int (bool)`
* :kat:attr:`.displayAsDot`
* Boolean flag that states whether to display a :kat:node:`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, :kat:node:`Dot` nodes are displayed with a round node
shape, and this attribute is not set.
**Backdrop**
.. list-table::
:header-rows: 1
:widths: 5 20 75
- * Type
* Attribute
* Description
- * :kat:type:`double[2]`
* :kat:attr:`.size`
* The size of the :kat:node:`Backdrop` node as width and height.
- * :kat:type:`string`
* :kat:attr:`.text`
* The text of the :kat:node:`Backdrop` node.
- * :kat:type:`float`
* :kat:attr:`.fontScale`
* The font scale used for the :kat:node:`Backdrop` node, as a multiplier
(default: ``1.0f``) of the text size used for node names.
- * :kat:type:`float`
* :kat:attr:`.zDepth`
* The Z order index of the :kat:node:`Backdrop` node.
**Switch**
.. list-table::
:header-rows: 1
:widths: 5 20 75
- * Type
* Attribute
* Description
- * :kat:type:`int`
* :kat:attr:`.size`
* The value of the :kat:node:`Switch` node's 'in' parameter.
- * :kat:type:`group`
* :kat:attr:`.inputs`
* The names and "display names" of the node's input ports.
**ShadingNodeArrayConnector**
.. list-table::
:header-rows: 1
:widths: 5 20 75
- * Type
* Attribute
* Description
- * :kat:type:`group`
* :kat:attr:`.inputs`
* The names and "display names" of the node's input ports.
**VariableSwitch**
.. list-table::
:header-rows: 1
:widths: 5 20 75
- * Type
* Attribute
* Description
- * :kat:type:`string`
* :kat:attr:`.variableName`
* The value of the :kat:node:`VariableSwitch` node's 'in' parameter.
- * :kat:type:`group`
* :kat:attr:`.patterns`
* The names and values of the node's "patterns" child parameters.
- * :kat:type:`group`
* :kat:attr:`.inputs`
* The names and display name labels of the node's input ports.
**ShadingGroup**
.. list-table::
:header-rows: 1
:widths: 5 20 75
- * Type
* Attribute
* Description
- * :kat:type:`string[]`
* :kat:attr:`.expandedPages`
* A list of names of pages that are expanded to reveal their contents in
the external interface of the :kat:node:`ShadingGroup` node, with
subpages denoted by **>** characters.
- * :kat:type:`string[]`
* :kat:attr:`.collapsedPages`
* A list of names of pages that are collapsed to hide their contents in
the external interface of the :kat:node:`ShadingGroup` node, with
subpages denoted by **>** characters.
- * :kat:type:`group`
* :kat:attr:`.outputSidebar`
* Group containing the page expansion state for the internal output
interface, in the form of :kat:attr:`.expandedPages` and
:kat:attr:`.collapsedPages` child string attributes equivalent to those
describing the external interface.
- * :kat:type:`group`
* :kat:attr:`.inputSidebar`
* Group containing the page expansion state for the internal input
interface, in the form of :kat:attr:`.expandedPages` and
:kat:attr:`.collapsedPages` child string attributes equivalent to those
describing the external interface.
- * :kat:type:`group`
* :kat:attr:`.outputPorts`
* Group containing an entry for every output port of the
:kat:node:`ShadingGroup` node.
- * :kat:type:`string`
* :kat:attr:`.outputPorts.<port>.name`
* The unique identifier name of the port.
- * :kat:type:`string`
* :kat:attr:`.outputPorts.<port>.displayName`
* The display name label of the port.
- * :kat:type:`string[]`
* :kat:attr:`.outputPorts.<port>.tags`
* A list of string tag expressions for valid port connections.
- * :kat:type:`group`
* :kat:attr:`.inputPorts`
* Group containing an entry for every output port of the
:kat:node:`ShadingGroup` node.
- * :kat:type:`string`
* :kat:attr:`.inputPorts.<port>.name`
* The unique identifier name of the port.
- * :kat:type:`string`
* :kat:attr:`.inputPorts.<port>.displayName`
* The display name label of the port.
- * :kat:type:`string[]`
* :kat:attr:`.inputPorts.<port>.tags`
* A list of string tag expressions for valid port connections.
- * :kat:type:`string[]`
* :kat:attr:`.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 :kat:attr:`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.
.. list-table::
:header-rows: 1
:widths: 5 20 75
- * Type
* Attribute
* Description
- * :kat:type:`string`
* :kat:attr:`materialAssign`
* The path of the scene graph location of the assigned material, for
example :kat:loc:`/root/materials/carPaint`.
Material Underlays
------------------
.. list-table::
:header-rows: 1
:widths: 5 20 75
- * Type
* Attribute
* Description
- * :kat:type:`group`
* :kat:attr:`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.
- * :kat:attr:`group`
* :kat:attr:`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-material-attribute-conventions:
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.
.. seealso::
:ref:`Material Solo Attribute Usage <solo-material-attribute-usage>` for more information on how the `soloMaterial` attribute is used.
.. list-table::
:header-rows: 1
:widths: 5 20 75
- * Type
* Attribute
* Description
- * :kat:type:`group`
* :kat:attr:`soloMaterial`
* A copy of the `material` attribute group of a solo NetworkMaterial.