PrimDecorators
==============

A PrimDecorator is a class which 

Once built, for these to be loaded by Katana they should be placed in either the ``PrimDecorators`` or ``Libs`` folders within ``KATANA_RESOURCES``.

A PrimDecorator is registered with a name against a set of :code:`locationTypes`, and with a certain :code:`order`. They are registered with the following MACRO:

.. code-block:: cpp

    define DEFINE_PRIM_DECORATOR_PLUGIN(NAME, LOCATION_TYPES, ORDER, CREATE_FUNC)

The :code:`locationTypes` determines which location this PrimDecorator should be run at, in order to perform any conversion for that location into USD. There are some `Special Location Types`_ as listed below to handle more intricate scenarios.

The :code:`order` determines, in which order the PrimDecorator's should run if there are multiple PrimDecorator's which match the same location type. If multiple PrimDecorators are registered against the same value, the registration order is used as a fall-back. The default order is :code:`std::numeric_limits<int>::max() / 2`, or in other words, the half way point of an int. The :code:`PrimDecoratorRegistry` python module can be used to quickly query the order of any existing PrimDecorator.

A PrimDecorator must provide an override to the :code:`process` method. This method is where the conversion should take place and USD data should be written to the provided :code:`editLayer`. This :code:`editLayer` is shared with the other PrimDecorator's, so it is possible to read information other PrimDecorator's have already written, hence why the order is important.

Special Location Types
^^^^^^^^^^^^^^^^^^^^^^

There are two special location types which can be provided to perform specialized matching.

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

    - * LocationType
      * Description

    - * :code:`*`
      * The PrimDecorator run against all locations. It is important to note that this does not mean the :code:`locationTypes` is matched using any pattern, just that the :code:`*` is a special case.

    - * :code:`postProcessor:<type>`
      * The PrimDecorator will run after a first full traversal of the scene tree. This allows the PrimDecorators to act on data already written in the first traversal. This can be combined with the :code:`*` location type, to run the PrimDecorator against all locations as part of the second traversal.

PrimDecoratorDescription
^^^^^^^^^^^^^^^^^^^^^^^^

PrimDecoratorDescription is used to describe the current PrimDecorator and a way of registering potential options which could change the behavior of the PrimDecorator itself. There is a C++ struct which defines the PrimDecoratorDescription, as well as each option.

These options will appear on the KatanaToUsd node when it is created and will be available to the PrimDecorator via a helper method :code:`getOptionValue`.

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

    - * Variable
      * Description

    - * name
      * The name of the PrimDecorator

    - * prettyName
      * The parent group name used for displaying the options this PrimDecorator has on the KatanaToUsd node.

    - * summary
      * A description of the PrimDecorator.

    - * locationTypes
      * The locationTypes this PrimDecorator is registered against.

    - * order
      * The order this PrimDecorator is registered with.

    - * primDecoratorArgs
      * A list of options which can be used to change behaviour of the PrimDecorator.

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

    - * Variable
      * Description

    - * name
      * The name of the option.

    - * description
      * A description of the option, this will be added as help text on the KatanaToUsd node.

    - * defaultValue
      * The default value, displayed on the node, and used if the option is not set.

    - * widgetHints
      * Any widget hints to help display the option as desired in the Parameters tab.