Namespace Tips

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

The namespace command is documented in Scene Desciption Language->Commands in the Namespace command section. It operates in syntax similarly to the other data base elements, in that you can define a namespace block by bracketing a section of the scene description with a starting and ending statement, ie., namespace "foo" ... end namespace

Namespace blocks

A namespace can be used to prevent names from conflicting with each other. For example, one might use a namespaceto ensure that the names in a given subscene do not interfere with other subscenes or the main scene. Think of it as a level in a name hierarchy, bounded by the block it defines. For example, if an object named "hand" were to be used on the left and right side of a character, one could specify a namespace for each of the left and right sides. A copy the mirrored hand of could keep the same name to each side. Think of it has a level of name hierarchy bounded by the block it defines, eg.

Now, outside of this block we can refer to the object using the namespace followed by the name separated by a double colon, e.g.,
instance "left_hand_instance" "left::hand"
whereas, if this instance were defined inside the "left" namespace block, you might use:
instance "hand_instance" "hand"
where both the instance and the object are defined in the same namespace.

If you needed to refer to a toplevel object within a given namespace block, use a double colon (::) in front of the name, eg,
::head might be how you refer to the head object defined at top level if you were within the "left" or "right" namespace blocks above.

Namespaces and geometry shaders

Now there are special purpose namespaces used by geometry shaders. When geometry (object(s), instance(s), etc.) is created by a geometry shader, mental ray defines it in a namespace with a unique, automatically-created name. This servers two purposes.

• First, it avoids name conflicts when two geometry shaders both create toplevel elements with the same name.
• Second, it provides mental ray with a way to track geometry created by geometry shaders, so that if they are not used in subsequent frames, they are automatically deleted.

Since it is possible to override the namespace of the name created in the geometry shader, one must pay careful attention to that second point. If one uses a namespace, or the top-level namespace, for such geometry, then if it will no longer be used in the scene, it must be deleted.

If implementing this stricly with .mi file editing, note that there is also a delete command, that may be useful for this situation. The delete command takes the name of the element in the database

Re: the top level namespace used in Placeholder Tips

Note that the top level namespace trick overrides expectations in the mental ray api, and therefore should be either avoided, or used with caution, inside of geometry shaders which will be used inside a 3D application, or which will be used in a sequence of incremental mi files. The geometry defined by your object created in the geometry shader cannot be deleted as it should when rerunning the geometry shader in a sequence of renders if that name is changing. In other words, if you spawn unique names at top level for each new frame, the old objects will pile up, unless your geometry shader knows how to explicitly delete them. That means it has to remember the names somehow.

Final Notes

Remember to think of mental ray as a database, that elements are created and deleted in the database, and that geometry shaders provide an automatic mechanism for this. So be careful when overriding this mechanism.