Iray Programmer's Manual


Iray Photoreal supports two ways of handling scene geometry: flattening and instancing. Several modes are available to control how and which geometry is instanced. The choice of mode is controlled by the following attribute on the IOptions class:

mi::IString iray_instancing

Controls the instancing mode, which can be one of the following values, where "off" is the default:

  • "off" :

    If instancing is disabled (the default), all scene geometry is flattened into one block. Geometry that is instanced multiple times in the scene will be duplicated. This almost always leads to higher memory use than instancing, but often yields higher rendering performance.

  • "on" :

    If instancing is fully enabled, instanced geometry will only exist once. Input scene instances will also be instances in the rendering core. This may yield a significantly lower memory footprint, but may incur significant runtime costs, especially if the geometric extent of the instances overlap.

  • "user" :

    Without further intervention, this user mode behaves like the "on" mode. However, it allows fine-grained control over what is instanced and what is flattened. Scene elements like objects, groups, and instances can be tagged for flattening, as explained in the following section.

User control of instancing

In the user mode of instancing, flattening can be controlled with the following attribute on the mi::neuraylib::IAttribute_set class, which can be set on objects, groups, and instances in the scene graph:

bool instancing = true

If set to false, the respective node is marked for flattening.

If a group is marked for flattening, all of its contents will be merged into one block. If the group contains multiple instances of some geometry, that geometry will be duplicated accordingly. The group itself will remain instanced, unless some mark higher up in the scene graph asks again for flattening..

If an object or instance is marked for flattening, this element (and, potentially, its sub-graph) will be flattened into the next group higher up in the scene graph. That group may be flattened further depending on other marks in the scene graph.