User guide

Appendix A: Custom Katana
Filters
There are two C++ APIs for writing new scene graph filters: the Scene Graph Generator API and Attribute Modifier
API. Scene Graph Generators allow you to create new scene graph locations, and Attribute Modifiers allow you to
modify attributes at existing location. These are often used together.
Scene Graph Generators
Scene Graph Generators are custom filters that allow new hierarchy to be created, and attributes values to be set on
any locations in the newly created locations.
Typical uses for Scene Graph Generators include reading in geometry from custom data formats (for example,
Alembic_In is written as a Scene Graph Generator), or to procedurally create data such as geometry at render-time
(such as the for render-time created debris or plants).
From a RenderMan perspective, Scene Graph Generators can be seen as Katana's equivalent of RenderMan
procedurals. The main advantages of using Scene Graph Generators are:
The data can be used in different target renderers.
Render-time procedurals are usually black-boxes that are difficult for users to control. Data produced by a Scene
Graph Generator can be inspected, edited and over-ridden directly in Katana.
Since Katana filters are be run on demand as the scene graph it iterated, Scene Graph Generators have to be written
to deliver data on demand as well. The API reflects this: for every location you create you provide methods to
respond to requests for:
• What are the names of attribute groups at this location.
• For any named attribute group, what are its values for the current time range.
• What are iterators for the first child and next sibling of this location, to enable walking the scene graph.
Example code for a number of different Scene Graph Generators are supplied in the Katana installation:
• ${KATANA_ROOT}/plugins/Src/ScenegraphGenerators/GeoMakers
• ${KATANA_ROOT}/plugins/Src/ScenegraphGenerators/SphereMakerMaker
• ${KATANA_ROOT}/plugins/Src/ScenegraphGenerators/ScenegraphXml
• ${KATANA_ROOT}/plugins/Src/ScenegraphGenerators/Alembic_In