...
RenderMan for Katana supports three approaches to instancing: hierarchical instancing, leaf-level instancing, hierarchical instancing, and instance arrays. The first is a very deliberate approach where you set up an object master and then explicitly instance it. The second is where you give pieces of matching geometry the same "instance.ID" attribute to turn them into instances of each other. RenderMan for Katana will make the first location into the geometry master, and then create instances for the others.
For a more in-depth discussion about instancing, please read the Instancing in RenderMan documentation. It provides some great background information as well as some tips you should know about if you are instancing subdivision surfaces.
Instancing tips:
While you can vary Bxdfs, light linking, and attributes, there are some things that cannot vary per instance. Parameters under the "primvars" group in PrmanObjectStatements are things that cannot vary per instance. Displacement also cannot vary per instance.
Example
Below are two examples for how to set up your Node Graph to produce instancing. It shows that you can override certain attributes on each instance – in this case, the material – to give each instanced object a different look.
In this example, the green and the purple dragons are instances of the blue dragon. The materials have been overridden at the instance level. If you don't have a copy of the dragon, you can use any geometry you like. Just change the path to the Alembic_In node.
The file has three different approaches to instancing that you are likely to see in production.
...
lets you instance matching pieces of geometry via an attribute. The second and third are very deliberate approaches where you set up an object master and then explicitly instance it.
Leaf-level instancing
You may find that your scene is taking a lot of memory, and you think that because your scene has lots of repeated geometry, that you may be able to take advantage of instancing. In this case, you go through the scene and manually set up the instancing. The HierarchyCopy node in the example represents some arbitrary set of complex operations that got your Scene Graph into the state that it is in. The best that you will want to do is instance large chunks of geometry and set up Transform3D nodes to move the instances in to place.This approach uses The leaf-level instancing approach can be used to efficiently turn already existing geometry locations into instances of each other via the instance.ID attribute to tell . RenderMan for Katana that each location in the Scene Graph that shares the name used within the instance.ID attribute should be instances of one another.
The section below explains how to use the instance.ID attribute to create instances.
Instance Geometry as it is Imported
This approach uses the same instance.ID approach that the above method uses. However, if you are creating the geometry import yourself, you will save lots of processing time within Katana if you create your instances up-front. The LocationCreate nodes show you what to do if you want to instance geometry as it is brought in to Katana.
There are three steps needed to get this approach to instancing working.
- Assign a name to the instance.ID attribute of the instance source using an AttributeSet node
- Create Scene Graph locations for the instanced geometry using the LocationCreate node in your Node Graph
- Use an AttributeSet node to create instance.ID attributes on the new Scene Graph locations, and set the value to the same name that you used for the instance source
- Use a Transform3D node to move the instances into position
Once you have created your instances, you can then override the material if you so desired using the standard Katana mechanisms for applying a material to a Scene Graph location.
Below I have taken a screen snapshot of your your Node Graph should look, as well as how your AttributeSet nodes should look.
Defined Instance Sources/Object Masters and Instances
will make the first location it encounters with a certain instance.ID into the geometry master, and all subsequent locations will be instances. All locations with matching instance.IDs must be identical, otherwise there could be undefined behavior depending on which location RenderMan for Katana encounters first. The screenshot below shows an example of how to set the instance.ID attribute via an AttributeSet node.
Like it's name states, leaf-level instancing only works on scenegraph locations with no children. RenderMan for Katana will not traverse past a location with the instance.ID attribute, so it cannot be used to instance groups of geometry. If you need to instance a hierarchy, you will need to use either hierarchical instancing or an instance array. These are described in the next two sections.
Hierarchical Instancing
In this approach The last approach in the file is the one where specific instance source/object masters are called out via their Scene Graph locations and are then referenced in to their instance locations. This approach is good if you have several different kinds of instances you need to create, but don't want to worry about naming collisions.want to instance a hierarchy of locations.
The steps to creating instances using this approach are as follows.
- Use an AttributeSet node to change Change the "type" of the Scene Graph location to be used as the object master to "instance source". Note that the Scene Graph location for the instance source must be a group. If you change the type of a geometric primitive to "instance source", then RfK will not have any information about the primitive type, and the instances will not render.
- Use the LocationCreate node in the Node Graph to create Create locations for your instances. This can be done with a LocationCreate node or via an OpScript. If you want your instance source to be visible, you must also create a new instance for that as well (by contrast, the instance.ID approach will automatically make your instance source visible).
- Set the geometry.instanceSource attribute of each of your instance locations to be the Scene Graph location of your instance source
- Use Set the transforms on the instance locations using a Transform3D node to move the instances in to positionor an OpScript.
The screen snapshots below show examples of how to set the necessary attributes with AttributeSet nodes.
Once you have created your instances, you can then override the material if you so desired desire using the standard Katana mechanisms for applying a material to a Scene Graph location. Note that any material assigned at the instance source location will be ignored. This is to allow for overrides on the instance locations.
Here I have taken a screen snapshot of how your AttributeSet nodes should look.
However, you will only be able to override the materials at the root of the instance source location. Overrides to the materials on child locations of an instance source will need to be done with user attributes.
Instance Arrays
Just like in hierarchical instancing, this approach uses direct assignment of locations as an instance sources. Locations marked as instance sources can be referenced by the instance array location. This approach has some advantages and disadvantages over hierarchical instancing. The main advantage is that you only need to create one scenegraph location to represent all your instances. This can save on Katana scenegraph processing time. Additionally, you can reference multiple instance sources in a single instance array. The main disadvantage is that instance arrays do not provide ways to override materials per instance. It is important to determine your requirements before deciding on an instancing method.
The steps to set up the instance source locations are the same as in hierarchical instancing. Simply set the type of the group representing the object master to "instance source". Then you will need to create a location of type "instance array" on which you will build up your instance array attributes.
These are the attributes required on the instance array location:
| geometry.instanceSource | The array of instance source locations referenced in this instance array. |
| geometry.instanceIndex | For each instance in the instance array there is an element in the instanceIndex attribute. Each element maps to an index in the geometry.instanceSource attribute. This mapping determines which instance source is used for the instance represented by this element. |
| geometry.instanceMatrix | For each instance in the instance array there are 16 values in the instanceMatrix representing the transformation matrix of this instance. Note that this transform is relative to transform of the instance array itself. |
See this instanceArray.katana file for an example of how to set up an instance array from a point cloud.
Overriding Materials at the Instance Level
Shading overrides can be accomplished in multiple ways. In the example file, a simple approach is taken where a completely new Bxdf is assigned to each instance. Fancier ways to vary the shading on each instance are possible with RenderMan for Katana. One such approach is to create a unique "user" attribute per instance. Within your master material, you would create a PxrAttribute pattern that reads the user attribute, and then use the output to drive one of the parameters on the Bxdf.
While you can vary Bxdfs, transforms, light linking, and attributes per instance, there are some things that cannot be varied. Parameters under the "primvars" group in PrmanObjectStatements are things that cannot vary per instance. Displacement also cannot vary across instances because it changes the representation of the geometry master in the renderer. For a more in-depth discussion about instancing, please read the Instancing in RenderMan documentation. It provides some great background information as well as the full list of what can vary across instances.