Material Soloing
================

|sparkles| **New in Katana 6.0**: Arbitrary ports can now be soloed through a set of new member functions on :kat:node:`NetworkMaterialCreate` and :kat:node:`NetworkMaterialEdit` nodes. To achieve this `MaterialSoloingConverter`\s are used.

Introduction
------------

Any port can be soloed, given a compatible `MaterialSoloingConverter` plug-in has been registered using the standard `PluginRegistry` system. More details can be found in the `Example User MaterialSoloingConverter`_ section below.

A `MaterialSoloingConverter` defines a conversion network from a given port type, to a type which is appropriate for rendering. By default, some `MaterialSoloingConverter`\s are defined within Katana, however developers are free to inherit from `BaseMaterialSoloingConverter` and register their own.

Any material soloing is non-persistent, and will not be saved to disk, baked (e.g via: :kat:node:`LookFileBake`, :kat:node:`LookFileMultiBake`, :kat:node:`UsdMaterialBake`, and :kat:node:`LookFileMaterialsOut` nodes), or partake in disk renders.


MaterialSoloingConverter Base Class
-----------------------------------

.. autoclass:: BaseMaterialSoloingConverter.BaseMaterialSoloingConverter


Example User MaterialSoloingConverter
-------------------------------------

Developers are free to write their own MaterialSoloingConverter, an example of this could look like the following::

    from PluginsAPI.BaseMaterialSoloingConverter import BaseMaterialSoloingConverter

    class MyMaterialSoloingConverter(BaseMaterialSoloingConverter):
        pass

    PluginRegistry = [
        ("MaterialSoloingConverter", 1, "MyMaterialSoloingConverter", MyMaterialSoloingConverter)
    ]

The body of :py:class:`MyMaterialSoloingConverter` should be replaced with implementations of methods marked `abstract` in the :py:class:`PluginsAPI.BaseMaterialSoloingConverter.BaseMaterialSoloingConverter` class, example `MaterialSoloingConverter`\s for commonly used render plug-ins can be found under `$KATANA_ROOT/plugins/Src/Resources/Core/Plugins`.

To capture the plug-in, add it to your ``KATANA_RESOURCES`` env path variable in a ``Plugins`` subfolder. For example::

        # For a plug-in at /home/Gandalf/katana_resources/Plugins/MyMaterialSoloingConverter.py:

        KATANA_RESOURCES=/home/Gandalf/katana_resources


.. _solo-material-attribute-usage:

Material Solo Attribute Usage
-----------------------------

.. seealso::
    :ref:`Attribute Conventions For Solo Materials <solo-material-attribute-conventions>` for more information on the `soloMaterial` attribute.

When a `MaterialResolve` Op is run, the `soloMaterial` and `material` attribute groups are copied to
the assignee (likely a geometry scene graph location).

A `MaterialSoloResolve` Op has been introduced as an implicit resolver, and is inserted at the
front of all render plug-in terminal Op chains when a Live or Preview render is triggered
(note: disk renders are exempt), and is also run before viewer implicit resolvers are run, meaning soloing works in the viewer as well.
The `MaterialSoloResolve` Op moves any `soloMaterial` attribute groups to a `material` attribute
group at the same scene graph location, effectively applying the solo material.

As well as the `MaterialSoloResolve` Op being added to Live and Preview renders, all `soloMaterial`
attributes are removed on look file bake by being inserted at the start of any look file bake Op chains,
e.g: :kat:node:`LookFileBake`, :kat:node:`LookFileMultiBake`, :kat:node:`UsdMaterialBake`, and
:kat:node:`LookFileMaterialsOut` nodes are all included.


.. |sparkles| unicode:: U+2728