Default Attribute Producer Plug-ins

A number of aspects of the Katana ecosystem follow the principle of convention over configuration. For example, shaders may contain hundreds of configurable parameters but the shader author provides sensible default values for most of these parameters, this saves artists’ time by only requiring them to provide values in situations where the defaults aren’t suitable. Similarly, renderers provide a vast array of configuration options with sensible defaults, users are only required to override values in situations where the defaults are not appropriate for their use.

One of the main problems with the convention over configuration principle is that it often requires users to have an in-depth knowledge of the available parameters, their default values and acceptable inputs. Default Attribute Producers (DAPs) provide a solution to this by interrogating default values, their acceptable inputs and then returning a description of each parameter. This description is then used (primarily) in Katana’s user interface to allow users to introspect all configurable aspects of a shader, renderer or any other plug-in that extends Katana.

DAPs are implemented as C++ plug-ins and called from within Ops. They are able to query the incoming scene graph at the point they are invoked (but not modify it) and callers may request the DAP limit the values it should provide by specifying the attrRoot parameter. For example a DAP for producing shader defaults may receive attrRoot = "material", in which case it should only return default values under the material.XXX attribute hierarchy.

DAPs are themselves evaluated within the Runtime. For each call to their cook() function they must generate and return an FnAttribute::GroupAttribute value for the requested context. The context is defined as:

  • Op / scene graph location combination - Op and scene graph location the calling Op is currently being evaluated at.

  • Attribute path - an optional string which is used to scope the work of the DAP to a specific portion of the attribute hierarchy at the current location.

This translates to the following basic C++ signature of a DAP:

class MyDefaultAttributeProducer : public FnDefaultAttributeProducer::DefaultAttributeProducer
{
public:

    static FnAttribute::GroupAttribute cook(
        const FnGeolibOp::GeolibCookInterface& interface,
        const std::string& attrRoot,
        const std::string& inputLocationPath,
        int32_t inputIndex);
};
Where:

  • interface - the same interface passed to your Op’s cook() function, you are free to query the incoming scene graph but not make modifications to the outgoing scene graph.

  • attrRoot - allows the caller to scope the work of the DAP at a particular location to a sub-tree of the attribute hierarchy. For example, to only return values for the material attribute.

  • inputLocationPath - allows the caller to specify an scene graph location in the incoming scene where attribute queries should be directed.

  • inputIndex - allows the caller to specify a particular branch on the incoming Op tree where attribute queries should be directed.

DAP Calling Conventions

As discussed previously, DAPs are called within Ops. You can invoke them by calling FnGeolibCookInterfaceUtils::cookDaps() and passing in the necessary arguments (available to you in your Op’s cook context). You’ll get an FnAttribute::GroupAttribute back which you can either query or include in your Op’s cook() output. A number of conventions exist for certain attributes (such as UI hints); these are explained in more detail below. However, you are free to define any format when implementing your own DAPs and Ops.

The cookDaps() method signature is as follows:

static FnAttribute::GroupAttribute cookDaps(
    const GeolibCookInterface& interface,
    const std::string& attrRoot,
    const std::string& inputLocationPath = std::string(),
    int inputIndex = kFnKatGeolibDefaultInput,
    const FnAttribute::Attribute& cookOrderAttr = FnAttribute::Attribute());

By default, when cookDaps() is called, the built-in Katana DAPs - Material and GenericAssign - will be evaluated first and then the remaining DAPs will be evaluated in an arbitrary order. You can override this default behavior by passing an FnAttribute::StringAttribute containing an ordered array of DAPs to run. Any DAPs not in the list will be evaluated after in an arbitrary order. e.g.:

std::vector<std::string> newCookOrder;
newCookOrder.push_back("MyDefaultAttributeProducer");
newCookOrder.push_back("Material");
newCookOrder.push_back("GenericAssign");
FnAttribute::StringAttribute newCookOrder(newCookOrder, 1);

GroupAttibute defaultGroupAttr =
    FnGeolibCookInterfaceUtils::cookDaps(
        interface, "", "", kFnKatGeolibDefaultInput, newCookOrder);

When are DAPs called?

DAPs can be called at anytime during an Op’s cook call (even at render time). Some Ops (like the AttributePanelPolish Op), are only appended to the Op tree during a UI session and make explicit calls to retrieve default attribute values. This allows the Attributes tab to fill in the blanks when you view attributes.

Note

At present a number of Katana’s built-in DAPs are not threadsafe. Care should be taken to invoke cookDaps() only in serial sections of code.

DAPs will be evaluated by the following built-in Katana Ops:

  • AdjustScreenWindowResolve

  • AttributePanelPolish

  • LocalizeAttribute

  • ZoomToRect

DAP Attribute Conventions

Like Ops, DAPs impose no restrictions on attribute hierarchy (except that a GroupAttribute is returned) so any conventions largely depend on the consumer of the DAP’s return value.

If you’re writing a DAP for a particular purpose, such as to drive a custom UI tab, feel free to structure your GroupAttribute in a way most suited to your needs.

UI Hints Convention

If you’d like to integrate with areas in the Katana UI that display attribute values (such as the Attributes tab) you can include UI hints in the FnAttribute::GroupAttribute returned by your DAP’s cook() function, as the sample code below demonstrates:

FnDapUtil::SetAttrHints(
    gb, "attributeName",
    FnAttribute::GroupBuilder()
        .set("help", FnAttribute::StringAttribute("Some help text"))
        .set("widget", FnAttribute::StringAttribute("widgetName"))
        .set("options", FnAttribute::StringAttribute("widgetOptions"))
        .build());

DAP Class Reference

class DefaultAttributeProducer

DefaultAttributeProducer and classes derived from it are never instantiated. The base class contains some internal static functions used by the plug-in system (setHost() / getHost() / flush() / createSuite()).

Each derived class should define a static cook() function which will be registered in a FnDefaultAttributeProducerSuite_v1 instance.

The signature of the cook() function implemented by DefaultAttributeProducer plug-ins is: 

static FnAttribute::GroupAttribute cook(
        const FnGeolibOp::GeolibCookInterface & interface,
        const std::string & attrRoot,
        const std::string & inputLocationPath,
        int32_t inputIndex);