Appendix A: mental ray
user data nodes
The following is a brief explanation of mental ray user data nodes and how they should be used inside Maya.
mental ray supports a large number of scene entities of a predefined type. In certain applications, however, these entity types are not sufficient to represent data in a scene effectively. In other cases, it is useful for an entity to contain some custom data or custom attributes. To solve these problems, user data entities can be used and placed almost anywhere in a scene.
Two types of user data are supported:
Both types of user data have their own specific node representation.
The advantage of declared user data is that mental ray knows the type of the parameters. Therefore, mental ray is able to swap the data properly in case the data has been created on one platform but will be rendered on another with a different byte order (endianess).
The literal user data, on the other hand, should be prepared for swapping if necessary, for example, by adding an integer value which allows it to detect if swapping is necessary, which needs to be performed in the shader which is retrieving the data.
This type of user data is represented with the new Maya node type mentalrayUserData. It provides two input attributes (asciiData and binaryData) to set or to get the ASCII encoding (used in .mi files) or the actual block of bytes.
The ASCII representation is simply stored in a node attribute of type string, since it uses only 7-bit characters which can be used inside Maya. The encoding uses two characters for a single byte; thus the length of the string must be a multiple of two. For .mi file export, this representation is basically copied. For integrated rendering, the data is decoded in the plug-in and the resulting binary data block is supplied to the mental ray core.
This type of user data is very similar to regular shader nodes, since it provides a set of input attributes. It does not provide output attributes because nothing is computed in difference to shaders, and the node serves only as a data holder.
Like regular custom shaders, this type of node is generated from a data .mi declaration via the shader manager. The node factory detects that this is a user data node and marks such nodes internally with a miFactoryData attribute for quick identification.
The Maya user interface is created in the same way as it is for other factory nodes, and allows values to be set in the attribute editor. Connections to other nodes are not supported in mental ray; hence any connection in Maya will be resolved at translation time and exported a fixed value for that frame.
Both types of user data nodes can be used in two ways:
Any user data node should be connected using the standard .message plug. Actually, any other plug can be used for connections as well, the plug itself is not relevant.
You can attach the data nodes inside Maya using the standard tools (for example the Connection Editor, drag and drop from Hypergraph or Hypershade etc.).
Connecting to shaders in Maya should be straight-forward. Connecting to scene entities like shape nodes (including geometry, lights and cameras) or transform nodes (DAG instance) requires you to add a dynamic attribute miData (message) and connect it to the user data node so that it is recognized during translation.
In an animation, any changes on the attributes or the byte block of the user data between frames are detected by the plug-in, and leads to incremental changes in mental ray, or the exported .mi file (if the file per frame option is disabled).
When the user data node is attached to a shader parameter, then the data can be accessed in a custom shader using mental ray mi_db_*() functions, passing the supplied tag value from the input parameter. In most cases, mental ray does not touch the content of the user data (except for potential swapping, see above).
Once the pointer to the user data memory has been retrieved, accessing the values of declared user data is like reading the fields of a C structure with a matching declaration. For literal byte data, the layout of the data is unknown to mental ray, so all structuring and decoding is up to the shaders.
It is possible in mental ray to “chain” several user data blocks, and attach that chain to a single scene entity. A helpful hint in this case is to add a “magic” number to the user data, preferably as the first value in the block, which lets your shaders identify the user data as the ones you expect.