Custom mental ray text

mental images .mi files are created with the mental images scene description language, which can be either an ASCII or binary file.

In mental ray for Maya, you can write and insert a text-only integration of custom mental ray shaders within Maya. It allows creation of special-purpose Maya nodes that hold customized mental images (.mi) text.

You can assign these nodes to certain Maya scene entities with the help of the Custom Text Editor and special custom text controls.

The mi file generated with mental ray for Maya can contain customized versions of: camera output statements including lens, volume, and environment shaders, light shaders, material shaders, texture or utility shaders, and object definitions. Furthermore, text can be generated that is written at certain stages of the export.

Customize Scene Entities

The mental ray for Maya plug-in provides a proprietary type of node, the mentalrayText node. It comes with a simple user interface that allows editing ASCII text. For more information, see Assign custom text to an object or shader.

You can connect these nodes to other nodes in the scene in certain situations using the Custom Text Editor.

The mentalrayText node assignment to Maya nodes is done on a .mi Text in the Extra Attributes section. mental ray for Maya checks for this new attribute when traversing the scene and shader graphs. If it has been found, the contents of the connected mentalrayText is written without further checks.

Warning

The translation of such entities has been disabled by default for interactive preview rendering due to several unpredictable issues. It is enabled for the .mi file export to create customized scene files for external rendering.

Dependent on the text mode attribute, the custom text is appended, prefixed, or completely replaces existing text in the generated .mi text.

The Maya renderer ignores these extra attributes and can render the scene safely as usual. On the other hand, the changed scene may not render any more with mental ray because of broken dependencies between lights, objects, and materials. See General Notes.

The scene needs to be saved as a Maya Binary (.mb) file in order for the text nodes and its connections to be preserved.

Custom Text Editor control group support

The Custom Text Editor contains two rows of drop-down lists and buttons that are dimmed by default.

When selecting objects or shaders in Maya the Custom Text Editor is updated according to the selected entity and enables the appropriate control if the current selection allows creation and assignment of custom .mi text.

The two control groups support:

custom shader text
It is enabled when selecting any light, any camera, any shading group, except the initial variants, any shader, except Maya’s default lambert1 and particleCloud1.
custom object text
It is enabled when a mesh or NURBS shape is selected. If a direct transform of a shape is selected, the underlying shape is automatically determined and used.

Custom Text Variables

The custom text can make use of special placeholder characters or strings that are recognized during translation. They are replaced by actual values on export. There are four custom text variables being supported.

Character	Description
$	Use the placeholder in front of an attribute name to replace the name with the attribute value. The attribute name must be known to exist. The Custom Text Editor recognizes all numeric attribute types and string types.
‘	The back apostrophe ' should enclose a string and indicate to the Custom Text Editor that this string should be evaluated as either a MEL or Python command. The evaluated MEL/Python code must return a string. See ! below for more details.
!	The exclamation mark ! should be used to indicate whether the string enclosed by ' is in MEL or in Python. If you do not include the ! character, the Custom Text Editor assumes that the command is in MEL. For example '!mel any_mel_code' or '!python any_python_code'
@	Use the @ character to indicate padding. The number of @ characters that you use indicate the amount of padding. For example, use @@@@@ to pad up to 5 characters with zeroes.

TipAnimation is checked on the connected Maya node, not the custom text node. Therefore, if you are using a dynamic attribute that has been key animated in a custom text node, you must force the animation on the connected Maya node to export your animation correctly.

What happens when assigning text to entities

When creating a custom text node and assigning it to the selected node in the scene the Attribute Editor is updated.

The option menu lists all the available text nodes that were previously created. By selecting a new entry in this option menu the text assignment of the current scene entity is replaced with this newly chosen text node. Saving the scene to a Maya file also stores all the existing text nodes, both connected and unconnected. Custom text nodes have to be deleted by standard Maya methods, as the Custom Text Editor doesn't provide a way to do it.

Types of text assignments

Camera Output and Shaders

The text node assigned to a camera adapts the first output statement that is created by the plug-in. Thus, customized image files and framebuffers can be created. Furthermore lens, volume and environment shaders can be added. The other camera parameters are unaffected and is still written according to the settings set in Maya.

Light Shaders

The text node assigned to a light affects the original light shader output. The light parameters remain unchanged and are written as usual. Using alternatives to standard Maya light shaders break illumination of Maya materials since they depend on special light dependency nodes.

Material Shaders

A custom text node assigned to a shading group affects the export of mental ray materials. If text is applied in replace mode the connected surface, volume, and displace shaders won't be exported at all. Otherwise, those shaders are written as usual, including their own dependent nodes.

The custom text editor prefixes the name of the currently selected entity with material to inform about its intended use.

Other Shaders

Text nodes can also be assigned to any other shading node that is supported in the translation process. The editor enables the controls in case such a supported node was selected, and prefixes the type of the node to the name of the selected entity. This relates to all texture and utility nodes. Using this feature, graphs of custom text nodes can be created and exported. mental ray for Maya ensures proper export of the graph, where leaf nodes get exported before dependent nodes, even if they contain custom text. This way, custom text itself can contain references to nodes down the graph. There is one limitation: custom text is expected to not use any shaders that return structures. In connections, they are always written with only their node name—not appended with names of output plugs for example, .outColor.

Object Definitions

Custom text assigned to shape nodes affects the complete object definition except the object's name and its flags. In text replacement mode, the flags are written according to the settings in Maya, but can further be adapted in the custom text. Also, the exported object is tagged by default, thus the custom object definition should use a material tag number instead of a material name.

The actual material is assigned in the instance statement, which gives a list of materials, one for every tag number. This way, different instances of the same object, and even polygons out of a mesh object, can get different materials.

General Notes

Unfortunately, the custom text functionality does not prevent you from creating invalid mi scenes that don't render any more or produce unexpected results. Therefore, great care should be taken to avoid undesired custom text.
Text is printed in the .mi file without any further indentation. This is required for certain mi commands that are expected to start at the first column of a line.
The $include statement can be used anywhere in custom text to take the actual mi text from external files (this statement has to start in the first column of the line), but note that the actual inclusion is resolved at render time on the render host.
The original names of the Maya entities stay untouched and cannot be changed with custom mi text.
Placing comments around the text (starting with #) makes the identification of the custom parts in the .mi file much easier.
When a custom text node has been assigned to a Maya node, the newly created attribute mi text appears in the Extra Attributes section of that object’s Attribute Editor. Clicking the button in the text field displays the appropriate text field.
When using references to light in custom shader text, the Maya light names should be used.

Limitations

The non-deletable default lambert1, particleCloud1, initialShadingGroup, and initialParticleSE nodes deny storage of the extra text assignment if the scene is saved to a Maya file and later restored because they are handled in a non-standard way. The text nodes are stored, but the connection to these nodes are lost and has to be repeated. Any other Maya surface node saves and restores as expected.

The custom text nodes support limited animation. When exporting an animation, the regular node attributes are checked for changes from frame to frame, and the node gets incrementally exported in every subsequent frame. This happens even if custom text is attached.

No checks for the correctness of the mi syntax and the use of valid name references in the custom text can be made.

A custom text node that contains empty text and is not going to be appended but is connected to an entity removes the output of the shader or object to which it belongs.

Scenes containing both customized text and standard Maya nodes can't be expected to successfully render with mental ray anymore, especially when using customized light nodes, due to limitations with Maya light dependencies.

Custom text is expected to not use any shaders which return structures. In connections they are always written with only their node name—not appended with names of output plugs for example, .outColor.