Assembly Tips

PLEASE NOTE that some of the content of this tips page applies ONLY to standalone mental ray®, as we suggest .mi scene file manipulation, and other things currently NOT supported by the 3D applications for interactive rendering.

Assemblies, introduced in mental ray version 3.6, can be used to defer the loading of scene parts (ie, one or more objects and their instances) during the render. In this tips page, we assume you have familiarized yourself with placeholders in mental ray, since assemblies follow a natural progression. You can think of them as a special type of placeholder, one that contains whole subscenes rather than single objects. They incorporate a new scene entity named "assembly", rather than exist as extensions to the existing entities, as the placeholder object does. However, we will use some of the same mi source examples to illustrate our points. Please refer to Placeholder Tips, if you haven't already.

Similar to object placeholders, assemblies are demand-loaded parts of scenes. With object placeholders, we separate the notion of scene structure from memory usage. With assemblies, we put them together. In other words, the memory chunk is not at the object level, but rather at the subscene level, as organized by how you organize your assembly files.

As we did in describing placeholders, let us define some terminology.

• An assembly is a new mental ray scene entity, a special placeholder which represents a portion of a scene, a subscene, which only has its bounding box defined.
• The source geometry for all the objects in the subscene will be loaded in at a later time during rendering when a ray enters the bounding box.
• The flattened transformations will be calculated for all the instances in the subscene later , as well

Similar to object placeholders, there are two types of assembly placeholders:

• an assembly file and
• an assembly callback.

Assembly file

An assembly file can also be specified from within a geometry shader. In the scene file, a geometry shader is used by an instance.

This geometry shader would specify the name, bounding box and assembly file name. Above we chose to show that the object name and assembly file name could be input parameters for this shader. An example of the code for the geometry shader is shown below in the Examples section. Note, unlike the placeholder mechanism, we don't have to use a double colon to get the correct namespace.

Assembly callback

The assembly callback is a function that creates the source geometry. This mechanism can only be set up from within a geometry shader. So, unlike the assembly file placeholder this cannot be accomplished without writing some shader code. This is more for experienced geometry shader writers.

The placeholder portion of this geometry shader would look almost identical to the placeholder portion of a geometry shader using an assembly file. For example, it might specify the object name, flags, and bounding box; but then, it would identify the callback function instead of the assembly file. Usually, this callback function is included in the same file as the geometry shader, immediately following the placeholder portion of the main geometry shader.

Geometry shader functions

Inside a geometry shader, the two placeholder types use different api functions.

• mi_api_assembly_filename() defines the name of the object, and the location of the assembly file for use by an assembly file placeholder.
• mi_api_assembly_callback() defines the name of the callback function for use by an assembly callback placeholder.

Examples

These examples are excerpts taken from the mental images training class, Writing mental ray Shaders.

Assembly file

This example shows how to specify the assembly file inside an mi scene file. First, in the original scene file we refer to the assembly file with a file statement in the assembly block:

Note also that we have to specify a few more flags on the instance of the assembly because, we don't know the flags inside the assembly file ahead of time, because of whole subscene on-demand loading:

Now, we reuse the contents of the "tarantula_object.mi" file with an assembly file named "tarantula_assembly.mi":

Note that we just wrap an instance around the object defined in the included file. Then, we make an instgroup, and tie it to the root of the assembly. Any assembly must have a root, because this is what is attached to the instance of the root in the main scene file as can be seen above. The name referred to by the root has to match the name of the top-level instgroup for this subscene.

Now we could add more instances of the tarantula object on the inside of the assembly. For example,

assembly file from a geometry shader

This example uses a geometry shader that defines an object with an assembly file placeholder. In the scene file, a geometry shader is used by an instance, and we specify a simple geometry shader which just takes in the name of the assembly and the name of the assembly file.

Here's how it is used in the original scene file. The geometry shader is named "assembly_file":

Note that the assembly name passed into the geometry shader does not need a double colon preceding it, like it does in the placeholder example. Inside a geometry shader, an implicit namespace is still used, but mental ray now tracks it with this assembly, handling the bookeeping for you. This allows multiple instantiations of the same assembly without namespace tracking by the application, or the shader-writing user.

In the geometry shader, we use two string arguments, assembly_name and assembly_filename, convert them into variables named name and filename,and then use the assembly file placeholder api function. The basic functionality is represented below:

Note that the result for a geometry shader ultimately defines an instance group. mi_geoshader_add_result() ensures this. Since you can put not only assembly tags, but also instance tags, into the second argument of this function, you can use this to make multiple instances of assemblies in the geometry shader.

Assembly callback

Coming later ...