Resources Documentation RenderMan :Developers' Guide :The Tools :RfK Dev Guide :

Custom Katana Ops (2.0)

RenderMan for Katana 2.0 offers a way to add customization without the need for recompiling the plugin. New Ops can be registered for insertion into the scene graph Op hierarchy using the configuration file config.xml.

Configuring RfK2.0 with Custom Ops

In order to configure RfK2.0 to use custom Ops you must build a configuration file to specify your Ops and the order in which they should be evaluated. The file:

$KATANA_RESOURCES/RfK/config.xml

is read from any location relative to an entry in the KATANA_RESOURCES path. The results are combined in the order read.

The configuration currently supports specification of additional "terminal Op" instances added onto the scene as visible to rendering and live render update observation.

The config.xml file format is:

<rfkConfig format="1">
    <!-- Ops which affect the scene as seen at ribgen time -->
    <renderTerminalOps>
        <op type="SomeOpName" insertWhen="afterAddShaderInfo"/>
        <op type="AnotherOpName" insertWhen="last" needsSystemArgs="true"/>
        <op type="AnOpWithArgs" insertWhen="last">
            <attr type="GroupAttr">
                <attr name="taco" tupleSize="1" type="IntAttr">
                    <sample size="1" time="0" value="1 "/>
                </attr>
                <attr name="cheese" tupleSize="1" type="StringAttr">
                    <sample size="1" time="0">
                        <str value="salsa"/>
                    </sample>
                </attr>
            </attr>
        </op>
   </renderTerminalOps>

   <!-- Ops which are evaluated during live render updates -->
   <liveRenderTerminalOps>
        <op type="SomeOpName" insertWhen="afterAddShaderInfo"/>
   </liveRenderTerminalOps>
</rfkConfig>

Ops can be added as either renderTerminalOps or liveRenderTerminalOps. The format of the Ops within each type are the same, the only difference is when the Ops are evaluated by Katana.

renderTerminalOps

The "op" elements added here affect the scene as seen at ribgen time.

liveRenderTerminalOps

The "op" elements here are added to the live render observer within the Katana process. If you need to manipulate the scene in any manner unique to live render updates, you may do this here.

An "op" element has two required properties:

type

a string containing the name of a registered Op type

insertWhen

a string indicating where amongst the terminal ops added by RfK itself the op should be inserted. See table below for a list of valid string values.

An "op" element may have these optional properties:

needsSystemArgs

values of "yes", "true" or "1" result in the "system" GroupAttribute being added to the Op's arguments. This contains information about the current frame and shutter information.

An "op" element may also have a child element of type "attr". This is expected to be the XML serialization of an FnAttribute::GroupAttribute, which can be generated from Python or C++ via the attr's getXML() method.

Valid `insertWhen` Options
Option	Description
`first`	Before all other terminal Ops
`beforeAddShaderInfo`	Before the `"PRManAddShaderParameterInfo"` Op. This Op provides shader parameter type and meta data inside a `"material.__prmanShaderInfo"` attribute. If your Op changes the shaders included in the "material" attribute, you need to do so at this phase or earlier.
`afterAddShaderInfo`	Immediately the `"PRManAddShaderParameterInfo` Op. If your Op depends on that information, you need to run here or later.
`beforeTagEmissiveGeo`	RfK tracks lights which need to use AreaLightSource calls with internal attribute conventions. If your Op manipulates a light in a way which would result in it having a `"geometry.areaLightGeometrySource"` attribute which aims at a gprim location, it needs to run at or before this stage. An example of an Op like this is `"PRManIdentifyRmsAreaLight"` - which recognizes shader parameter conventions present in provided RMS lights to create the expected geometry
`afterTagEmissiveGeo`	If your Op expects to be able to identify lights intended for use with AreaLightSource via RfK's internal attribute conventions, it must happen at this stage or later. (You're unlikely to need this.)
`last`	Append your Op after all others.

Supported Configuration Options

In addition to the renderTerminalOps and liveRenderTerminalOps hooks there are several other specialized options that are recognized by the RfK plugin. The first two are a simple configuration/extension options. The last two enable the passage of non-standard information from args files to custom terminal Ops.

Note: The theoretical Ops mentioned below in the example sections will become reality in an upcoming release which will include a test Op for the passthrough name functionality.

shaderPathRecursionLimit

Searching through the shader search paths will, by default, recurse down 3 levels before terminating the search in that path. This is configurable through the shaderPathRecursionLimit option in config.xml. Setting the value to 0 (zero) will disable recursion when searching the shader paths.

Example entry in config.xml:

System Message: WARNING/2 (../rfk/rfkCustomOps_2.0.txt, line 166)

Cannot analyze code. Pygments package not found.

.. code:: xml

    <!-- Turn off shader search path recursion -->
    <int name="shaderPathRecursionLimit" value="0"/>

shaderPostProcessFunctionName

A shader's "info" attribute can be modified using a function to run after a shader has been loaded and configured. The shaderPostProcessFunctionName refers to an attribute function which takes a group attribute in (the existing info attribute) and returns a new info attribute.

Example entry in config.xml:

System Message: WARNING/2 (../rfk/rfkCustomOps_2.0.txt, line 181)

Cannot analyze code. Pygments package not found.

.. code:: xml

    <int name="shaderPostProcessFunctionName" value="MyFunc"/>

hintPassthroughNames

Non-standard parameter hints can be passed from args file through to an Op using shader parameter info mechanism (PRManAddShaderParameterInfoOp) and the hintPassthroughNames list. Parameter hint names specified in this list are available to Ops configured using insertWhen=afterAddShaderInfo.

outputTagPassthroughNames: Non-standard per-shader, per-output tags can be passed from args file through to an Op using shader parameter info mechanism (PRManAddShaderParameterInfoOp) and the outputTagPassthroughNames list. Output tag names specified in this list are available to Ops configured using insertWhen=afterAddShaderInfo.

Coming Soon

An upcoming RfK 2.0 release will include an example config.xml as well as Op code which demonstrates the extraction of hintPassthroughNames and outputTagPassthroughNames.