Materials
=========

Defining Monolithic Materials
-----------------------------

.. list-table::
    :header-rows: 1
    :widths: 20 80

    - * Attribute
      * Description

    - * :kat:attr:`string material.<renderer><ShaderCategory>Shader`
      * This string has different names depending on the renderer and shader
        used, for example, ``prmanLightShader`` or ``arnoldSurfaceShader``. The
        value specifies the name of the shader to use.

    - * :kat:attr:`group material.<renderer><ShaderCategory>Params`
      * This group has different names depending on the renderer and shader
        used, for example, ``prmanLightParams`` or ``arnoldSurfaceParams``.

        The group contains all the shader attributes used by a particular
        shader type for a specific renderer.

    - * :kat:attr:`group material.ops`
      * See :ref:`deferred-material-ops`.

Defining Network Materials
--------------------------

.. note::
    This section is under construction.

.. list-table::
    :header-rows: 1
    :widths: 20 80

    - * Attribute
      * Description

    - * :kat:attr:`string material.style`
      *
    - * :kat:attr:`string material.nodes.<node>.name`
      *
    - * :kat:attr:`string material.nodes.<node>.type`
      *
    - * :kat:attr:`string material.nodes.<node>.target`
      *
    - * :kat:attr:`string material.nodes.<node>.srcName`
      *
    - * :kat:attr:`any material.nodes.<node>.parameters.<param>`
      *
    - * :kat:attr:`string material.nodes.<node>.connections.<param>`
      *
    - * :kat:attr:`string material.terminals.<renderer><ShaderCategory>`
      *
    - * :kat:attr:`string material.terminals.<renderer><ShaderCategory>Port`
      *
    - * :kat:attr:`string material.interface.<param>.src`
      *
    - * :kat:attr:`string material.interface.<param>.hints`
      *


Assigning Materials
-------------------

To assign a material to a location, set a ``materialAssign`` attribute on the
target location pointing to the scene graph location of the material.


.. list-table::
    :header-rows: 1
    :widths: 20 80

    - * Attribute
      * Description

    - * :kat:attr:`string materialAssign`
      * The scene graph location of the assigned material, for example
        :kat:loc:`/root/materials/material1`.


Material Underlays
------------------

.. list-table::
    :header-rows: 1
    :widths: 20 80

    - * Attribute
      * Description

    - * :kat:attr:`string 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 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.

Viewer Shaders
--------------

.. list-table::
    :header-rows: 1
    :widths: 20 80

    - * Attribute
      * Description

    - * :kat:attr:`string material.viewerShaderSource`
      * Source of the Viewer shader.