Placeholder Tips

PLEASE NOTE that much 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.

Placeholders can be used to defer the loading of objects during the render. Objects that use placeholders are called demand-loaded objects. From the mental ray documentation, in Scene Desciption Language->Scene Entities->Objects, under the "file" description: "Demand-loaded objects are useful to avoid parsing and permanently storing large objects that may or may not be required for rendering." Depending on the scene, placeholders could be used to decrease the amount of memory used during the render. In addition, they provide a mechanism to allow flushing and reloading if memory runs low.

First, let us define some terminology.

• A placeholder is an object which only has its bounding box and its flags defined.
• The source geometry will be loaded in at a later time during rendering when a ray enters the bounding box. Note that mental ray creates source geometry from the definition contained within the group ... end group block of the object definition. It is what defines the vectors, vertices, and either polygons, surfaces, or hair.

There are two types of placeholders:

• an object file and
• an object callback.

Object file

Only available for standalone, because 3D applications will not read in mi files.

An object file can also be specified from within a geometry shader. In the scene file, a geometry shader is used by an instance. The scene file would look a bit different, as depicted here:

This geometry shader would specify the name, flags, bounding box and object file name. Above we chose to show that the object name and object 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. It also explains why the double colon is in front of the object name.

Automatic Object file

This is the easy way to get the memory benefit of object file placeholders.

With standalone mental ray version 3.5, one can turn on a mechanism to automaticallly make each object in an mi file reloadable. In other words, mental ray will make an object file placeholder for each object it sees in the mi file, by marking its place so that it can reload it. This option is -reload. It takes an argument to specify the size of objects over which this mechanism will be used. To make most objects reloadable, just use an argument of one, i.e., -reload 1.

Object callback

The object callback is a function that creates the source geometry. This mechanism can only be set up from within a geometry shader. So, unlike the object 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 object file. For example, it might specify the object name, flags, and bounding box; but then, it would identify the callback function instead of the object 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_object_file() defines the name of the object, and the location of the object file for use by an object file placeholder.
• mi_api_object_callback() defines the name of the callback function for use by an object callback placeholder.

Examples

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

Object file

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

Now, the contents of the "tarantula_object.mi" file:

Note that the object name, flags and bounding box are repeated exactly as is in the object file. In mental ray version 3.4, repeating the flags and bounding box is not necessary. But note that the bounding box can be redefined to be smaller in the object file. The name must be the same, because the source geometry is defined in the object file using the incremental object definition. An incremental object definition must redefine a previously named object in the mental ray scene database.

Object file from a geometry shader

This example uses a geometry shader that defines an object with an object 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 object and the name of the object file.

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

Note that the object name passed into the geometry shader has a double colon preceding it. Inside a geometry shader, an implicit namespace is used. This means that normally inside a geometry shader, mental ray will create a unique namespace for an object created by the shader. By using the double colon, we are specifying that the name is in the top level namespace, which is the default for all names normally specified in a scene file without a namespace. In our object file, tarantula_object.mi, we use a top level name without a namespace.

Please see the Namespace Tips page for more information on namespaces. In particular, note care to be taken when using that the top level namespace trick inside a geometry shader.

In the geometry shader, we use two string arguments, object_name and object_filename, convert them into variables named objName and fileName,and then use the object file placeholder api function. The basic functionality is represented below:

There is a bit more to it, in order to extract the string parameter names for shaders. (That's subject for another tips page.) The full source of this code and its accompanying mi file can be found here.

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 object tags, but also instance tags, into the second argument of this function, you can use this to make multiple instances of a placeholder object in the geometry shader. Using an object file for this placeholder, one could provide a geometry shader that populates a scene with multiple instances of the object file placeholder object.

Object callback

A geometry shader can use an object callback instead of an object file. In that case, the source geometry is defined by a callback function instead of an mi scene file. An example of a callback that defines some hair is in another section of the Resources.

Note that in mental ray version 3.3 and later, the object tags and label are automatically copied to the incremental object defined by the callback. They should be defined in the original placeholder section of the geometry shader and not in the callback. The bounding box may also be defined to be smaller than as it was defined in the original placeholder section of the geometry shader.

Final Notes

With motion, a motion bounding box should be defined in the placeholder. As with the bounding box, the motion bounding box may be refined further, i.e., made smaller, in the object callback or object file

With displacement, an object specific maxdisplace may be defined in the placeholder. As with the bounding boxes, a more refined, smaller maxdisplace value may be defined in either the object file, or the object callback.

In most OEM implementations, mi object files cannot be read in from geometry shaders running inside the application. So, to use geometry shaders that specify object file placeholders, the entire scene must be exported to an mi file, and rendered with standalone mental ray. Please also note the caveat above regarding the top-level namespace trick.

Introduced in mental ray 3.6, mi files can now store multiple objects, actually partial scene DAG branches in a file that acts as a special placeholder which is called an assembly. A simple assembly tips page, in the works, follows as a natural progression from this page. For example, the namespace trick is not needed when using an assembly file from a geometry shader.