Iray Programmer's Manual


Iray 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 mi::neuraylib::IOptions class:

mi::IString iray_instancing

Controls the instancing mode in Iray, 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. Iray will apply incremental object transform updates when instancing is fully enabled. This significantly reduces the scene preprocesing runtime overhead when moving objects around.

  • "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. Iray will apply incremental instance transform updates when user instancing is enabled. This significantly reduces the scene preprocesing runtime overhead when when moving around flattened instances. Note that moving around objects which are part of a flattened group will not benefit from incremental transform updates.

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.

Fast light updates without instancing of geometry

In addition to its potential memory saving effect, the instancing feature allows Iray to respond quickly to instance transform changes. However, instancing can negatively impact rendering performance, in particular if the bounding boxes of instanced geometries overlap.

The following idea describes how to use instancing to enable fast updates of light positions, like for a re-lighting scenario, while preserving good rendering performance. This is achieved by instancing only light sources and flattening all other geometry.

Note that this idea currently works only for light sources built with emissive materials assigned to regular geometry. Support for fast instance transform updates on standard light sources, such as point, rectangle, disc, and cylinder is planned for the next release.

For this idea, the iray_instancing rendering option needs to be set to "user". The scene graph needs to be split into lights and geometry, i.e., there has to be a group that collects all geometry but none of the lights that will be moved. Instancing is then disabled for this geometry group by setting the instancing attribute to false.

That results in this group being flattened into one large block containing all geometry, while all remaining elements outside of the group are treated as individual instances with fast transformation updates.