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 locationTypes, and with a certain order. They are registered with the following MACRO:

define DEFINE_PRIM_DECORATOR_PLUGIN(NAME, LOCATION_TYPES, ORDER, CREATE_FUNC)

The 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 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 std::numeric_limits<int>::max() / 2, or in other words, the half way point of an int. The PrimDecoratorRegistry python module can be used to quickly query the order of any existing PrimDecorator.

A PrimDecorator must provide an override to the process method. This method is where the conversion should take place and USD data should be written to the provided editLayer. This 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.

LocationType	Description
*	The PrimDecorator run against all locations. It is important to note that this does not mean the locationTypes is matched using any pattern, just that the * is a special case.
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 * 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 getOptionValue.

PrimDecoratorDescription

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

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.