Assembly

Assemblies

Assemblies provide an encapsulation for entire subscenes. The key feature of assemblies is on-demand loading and unloading, which reduces memory consumption and allows faster rendering. An assembly subscene contains a complete scene sub-graph consisted of objects, instances, groups, textures, userdata, shaders, materials and other elements. Cameras, options and lights defined in assembly are ignored.

Assemblies can either be defined in separate files, or created procedurally.

Assembly is created or loaded when its bounding box is hit by a ray or when the bounding box overlaps a tile in the rasterizer renderer. For this reason, mental ray needs to know the bounding box of an assembly, which should be as tight as possible for the best performance and memory consumption.

Assemblies are instantiated similar to objects. The main scene should contain a stub with the following syntax:

    assembly "assembly_name"
        box [x_min y_min z_min x_max y_max z_max]
        [ motion box [x_min y_min z_min x_max y_max z_max] ]
        file "file_name"
    end assembly

The individual parameters are:

The box statement specifies a bounding box for the assembly, in the space of the assembly. It is the union of all bounding boxes of all geometric objects defined in the assembly and transformed to the assembly space. The box parameter must always be specified since it is not possible to compute the bounding box without loading the assembly.
The motion box is similar to the box, but contains the minimum and maximum components of all motion vectors and transforms. For assemblies with motion, the motion box has to be be specified. Unlike object motion bounding box, the assembly motion bounding box should take into account not only object motion vectors, but also motion transforms inside of the assembly.
The file statement specifies the name of the file where the subscene is stored in. A list of directories for looking up the file can be specified with a command line option, with a registry variable, or with the MI_ASSEMBLY_PATH environment variable.

Unlike objects, assemblies do not have trace, visible and similar flags. Those flags need to be defined on an instance of an assembly.

An assembly file uses the usual mental ray scene file syntax, with one exception: instead of the render directive, an assembly files ends with a root statement to specify a single group which will be attached to the main scene DAG when an assembly is loaded:

    root "group_name"

For compatibility reasons, a render statement can be used instead of the root statement (in which case camera and options are ignored).

Assemblies can also be created procedurally, detailed description is given in the Assembly API section.

Materials defined in an assembly should reference lights defined in the main scene only. This requirement is due to the fact that the rendering kernel would not be aware of them until all of the assemblies are loaded in order to apply lights on an object from a different assembly or from the main scene.

Transforms, flags, materials and light lists can be inherited from the main scene to an assembly.

An entire assembly is unloaded automatically if mental ray is running low on physical memory. However, a scene could consist of few assemblies only. Especially for scenes using ray tracing and global illumination, the spatial coherency of traced rays is very low. This could lead to frequent loading and unloading of assemblies, which is computationally expensive. In order to improve the performance, it is strongly recommended to use placeholder objects inside of the assemblies. If placeholder objects are used and mental ray is running low on memory, mental ray would first unload the results of placeholder object callbacks, but keep the assembly structure. Individual objects are much faster to recreate than entire assemblies.

For assemblies loaded from files mental ray provides on demand loading of individual objects automatically. For procedurally created assemblies, it is strongly recommended to write geometry shaders with assembly callbacks in such a way that object placeholder callbacks are registered.

Nested assemblies are currently not supported.