Instance Groups

instgroup "name "
    "name"
    [ tag label_int ]
    [ data [ "data_name" ]]
    ...
end instgroup

Instance groups, together with instances, provide the structure from which scenes are built. The scene is anchored at a root instance group, which contains instances referencing objects, cameras, lights, objects, and/or other groups. In the simplest case, all cameras, lights, and objects can be collected into a single group, forming a "flat scene" because there is no hierarchy. Cameras, lights, and objects are never put into an instance group directly. Instead, an instance must be defined, one for each element, and the instance is then put into the group. (This is why it is called an "instance group.")

Instance groups can be nested. An instance group is placed into a parent instance group exactly like a camera, light, or object: an instance must be defined for the child instance group, and the instance is put into the parent instance group. As with other entities, it is possible to create more than one instance for an instance group; this allows multiple instancing of sub-scenes. There is no limit on the nesting depth of instance groups.

Since the only purpose of instance groups is as a container for instances, the syntax is very simple. After the name of the instance group, one or more names of instances follow. An incremental change to an instance group clears the old instance list (without deleting the instances themselves); to add or remove an instance in an instance group, the incremental change must respecify the entire instance list.

The top-level instance group has no instance. It is called the root instance group. The root instance group stands for the entire scene. It is passed to the render command to process the scene. More than one root instance group can exist, but only one can be processed at a time. Camera instances must always be attached to the root instance group, not a lower-level instance group, and it may not be multiply instanced to ensure unambiguity. Multiple cameras can exist in the root instance group, but only one can be passed to the render command.

A label integer can be attached to an instance group using the tag statement. Labels are not used by mental ray in any way, but a shader can use the mi_query function to obtain the label and perform light-specific operations.

Also, user data can be attached with a data statement. The argument must be the name of a previously defined data element in the scene file. If the argument is missing, a previously existing data reference is removed.

mental ray 3.3 and later also supports groups that contain instances of lights to be used like lights, for example in the shader interface. This makes it possible to to put a set of lights into a group, and then treating the whole group like a single light for the purpose of shading. The mi_sample_light and related shader interface functions accept instances of light groups as if they were instances of lights. Light groups contain instances of lights, where the instances contain identity transformations.