User Data

Custom information can be incorporated into elements of a scene such as lights, cameras, objects, and instances. Use the dynamic miData attribute to connect a mental ray User Data node to the element so that this custom information can be accessed by mental ray shaders.

1. Create a mental ray User Data node using the command:

   createNode -n "miUserData" mentalrayUserData;
   

   The mentalrayUserData node should contain custom user data that matches the format required by your mental ray shader.

2. Connect miUserData.message to shader.data

   The mentalrayUserData node consists of two attributes: binaryData and asciiData. asciiData is the preferred method. The asciiData attributes should be filled with custom user data and connected to the mental ray shader using the mentalrayuserData.message plug.

   Note

   The mentalrayUserData node is only translated if connected to a mental ray shader.

3. Create the miData attribute as follows:

   addAttr -ln "miData" -at message pSphereShape1;
   

4. Connect the miData attribute to the userdata node as follows:

   connectAttr -f miUserData.message pSphereShape1.miData;
   

   Tip

   Add a magic number to the user data, preferably as the first value in the block. This allows your shaders to easily identify the user data.

Export shadow shader

Use this attribute to have transparent shadows even when photons are used. The attribute functions locally and overrides the shadowEffectsWithPhotons attribute (the Direct Illumination Shadow Effects setting in Caustics and Global Illumination > Photon Tracing section of the Render Settings), on a per-material basis, so that shadow shaders are exported even when photons are turned on.

Create this attribute as follows:

addAttr -ln miExportShadowShader -at bool phong1SG;

Disable animation detection

mental ray automatically detects animation of scene objects and related shading nodes when translating subsequent frames. The Optimize Animation Detection option (in the Render Settings window, mental ray tabs, in the Options tab, Translation section, Performance sub-section) even performs a pre-scan of the Maya dependency graph to find animated nodes much faster and to mark the individual nodes accordingly for accelerated translation of the whole animation.

There are ways to hint to mental ray about animated nodes manually, in cases where the default performance might still not be optimal or the standard detection algorithm does not catch all animations.

Individual instances or whole DAG subtrees can be excluded from being considered for animation by adding a new dynamic attribute 'miAnimated' (boolean)and setting it to off. Once found on a transform node, the DAG traversal prunes the remaining subtree from animation detection (not the node itself). The Optimize Animation Detection option needs to be turned off to activate the manual overrides.

Create this attribute as an override on the shape node as follows:

addAttr -ln miAnimated -at bool group1;

Disable DG cycle detection

Use this attribute to turn off the detection of cycles in the dependency graph when very complex shading networks are used, to improve performance. Cycles in shading networks may cause mental ray for Maya to become unstable in some cases. Set this attribute to false to disable the DG cycle detection.

Create this attribute as follows:

addAttr -at bool -ln "nodeCycleCheck" mentalrayGlobals

Force on-demand translation of geometry

Use the Export Objects On Demand option to control the processing of objects in your scene. This option is particularly effective in scenes that have objects beyond the view of the camera. In this case, mental ray does not process the objects beyond the camera view, therefore reducing processing time.

Create this attribute as an override on the shape node as follows:

addAttr -ln "miPlaceholder" -at bool pSphereShape1

Disable custom node automatic light linking

Use this attribute to turn off automatic light linking on a per-node basis (set the attribute to false). This is useful when the same material is used by several objects that have different light linking. In this case, disable light linking with this attribute, then manually connect the light nodes to the shader’s light attributes.

Create this attribute as follows:

addAttr -ln "miLightLink" -at bool mib_illum_lambert1

Label

To enable export of mental ray labels, this dynamic attribute is recognized on the transform node of geometry. mental ray does not perform any checks on these labels, but just exports them. There is no label framebuffer support at this time.

Create this attribute as follows:

addAttr -ln "miLabel" -at long nurbsSphere1

Cutout opacity

Add the miCutAwayOpacity (float) to the material’s shading engine.

This attribute is useful for 2D stand-ins or card objects where a complex 2D shape is cut out of a plane by means of transparency mapping.

miCutAwayOpacity is an opacity threshold. All surface points that are less opaque than specified are considered non-existent. For example, a value of 0.05 removes all surface points with a transparency of 99.5% or more.

Create this attribute as follows:

addAttr -longName "miCutAwayOpacity" -attributeType "float" shadingGroup1;

Custom motion vectors

mental ray for Maya supports the creation of zero-length motion vectors. Custom displacement shaders can manipulate the motion vectors to generate motion blurred displacement. Only geometric shape nodes that are marked with the attribute miCustomMotion (boolean) set to true are considered for custom motion.

The global option Export Custom Vectors can be used to control this feature. It is enabled by default. If disabled, no custom motion vectors are generated for any object. This functionality also requires that Motion Blur has been enabled in mental ray render settings.

Create this attribute as follows:

addAttr -ln "miCustomMotion" -at bool myShapeNode;

where myShapeNode is a shape node.

Force displacement animation

To specify that an object contains animated displacement, add the miDisplaceAnimation (boolean) dynamic attribute to the object shape node.

This is a hint to the translation engine and avoids potentially expensive traversal of the DG to detect animated displacement.

Create this attribute as follows:

addAttr -ln "miDisplaceAnimation" -at bool myShapeNode;

Force triangle export of polygon meshes

This option processes all polygon meshes as tessellated triangles, based on Maya’s tessellation. This allows for more efficient use of memory so that large scenes with large polygon meshes render with less memory usage.

For more information, see Export Triangulated Polygons.

In addition, there is support on each shape node for the dynamic attribute miTriangles (boolean), which overrides the global setting on a per-shape basis. Therefore, two common scenarios are supported:

• disable triangles globally but enable it for specific shapes,
• enable triangles globally but disable it for specific shapes.

Create this attribute as follows:

addAttr -ln "miTriangles" -at bool myMeshNode;

Force lights emitted photons

In the Attribute Editor for each Maya light, the mental ray section of the attributes specifies the number of photons that are used for caustics and global illumination. This is, by default, the number of photons to be stored.

For correct physical simulations, the number of photons to be emitted is much more appropriate. To support this, mental ray recognizes two attributes on directional, point, and spot lights:

'causticPhotonsEmit' (integer)

'globIllPhotonsEmit' (integer).

If they are created they will be translated and exported in addition to the photon stored number.

Create these attributes as follows:

addAttr -ln "causticPhotonsEmit" -at "short" myLightShape;
addAttr -ln "globIllPhotonsEmit" -at "short” myLightShape;

Photon only lights

The mental ray light property photons only can be controlled on Maya light nodes using the dynamic attribute

'miPhotonsOnly' (boolean)

If photon emission is enabled on the light node then this attribute is recognized and translated to mental ray. To optimize photon tracing performance, you can mark light sources as only being considered for photon emission and disable their direct light contribution in mental ray.

Create this attribute as an override on the light shape node as follows:

addAttr -ln "miPhotonsOnly" -at bool spotLightShape1

Translate polygon meshes as subdivision base mesh primitives

You can smooth polygon meshes by assigning them a subdivision surface approximation (that is, a mentalraySubdivApprox node) either through the Approximation Editor, or, manually. Beginning Maya 2008, the subdivision approximation node produces ccmesh primitives instead of subdivision base mesh primitives.

To revert to the old behavior, add the dynamic attribute

'miExportCCMesh' (boolean)

to mentalraySubdivApprox nodes. If turned off, mental ray for Maya translates smoothed polygon meshes to subdivision base mesh primitives. These are often slower and require more memory than ccmesh primitives.

Create this attribute as an override on the shape node as follows:

addAttr -ln "miExportCCMesh" -at bool mentalraySubdivApprox1

Custom flags

The Maya transform node does not expose all extended instance flags for mental ray, but they can be controlled via dynamic attributes:

'miReflection' (integer)
'miRefraction' (integer)
'miTransparency' (integer)

The value is an index into predefined flags (bit sets):

• 0 - cast off, receive off
• 1 - cast on, receive on
• 2 - no bit set, inherit
• 3 - cast on, receive off
• 4 - cast off, receive on

Create the attributes above by following these examples:

addAttr -ln "miReflection" -at "enum" -enumName "Cast Off Receive Off:Cast On Receive On:Inherit:Cast On Receive Off:Cast Off Receive On" myTransformNode
addAttr -ln "miRefraction" -at "enum" -enumName "Cast Off Receive Off:Cast On Receive On:Inherit:Cast On Receive Off:Cast Off Receive On" myTransformNode
addAttr -ln "miTransparency" -at "enum" -enumName "Cast Off Receive Off:Cast On Receive On:Inherit:Cast On Receive Off:Cast Off Receive On" myTransformNode

If any of the reflection and refraction attributes is present, then the standard trace flag is not respected any more.

'miFinalGather' (integer)

This attribute follows the scheme of the existing caustic and globillum standard flags, and supports the following values:

• 0 - hide on
• 1 - cast off, receive off
• 2 - cast on, receive off
• 3 - cast off, receive on
• 4 - cast on, receive on
• 5 - not bit set, inherit

Create this attribute as follows:

addAttr -ln "miFinalGather" -at "enum" -enumName "Hide On:Cast Off Receive Off:Cast On Receive Off:Cast Off Receive On:Cast On Receive On:Inherit" myTransformNode

Custom element

To enable file export of a replacement element instead of the currently instanced Maya shape, use the dynamic attributes:

'miExportElement' (boolean)
'miElement' (string)

If the boolean option is enabled, the replacement element is exported as the object name, without further checks.

Create these attributes as follows:

addAttr -ln "miExportElement" -at bool myTransformNode 
addAttr -ln "miElement" -dt "string" myTransformNode

Custom phenomenon for translation

To enable translation of a different material than the currently assigned Maya shading engine, use the dynamic attributes:

'miExportMaterial' (boolean)
'miMaterial' (message)

If the boolean option is enabled, the replacement material, typically a connection to a Maya shading engine or a custom node, is translated as the instance material. If the connected node is a custom node of type material, it is translated as a full replacement of the regular material description in mental ray.

Create these attributes as follows:

addAttr -ln "miExportMaterial" -at bool myTransformNode 
addAttr -ln "miMaterial" -at message myTransformNode

Rasterizer shading samples override

The global option for rasterizer shading quality (mental ray: shading samples) can be overridden on a per-object/per-instance basis. The per-object override can be accessed via the Shading Quality attribute in the Attribute Editor of the object’s shape node, in the mental ray section. For per-instance override, the dynamic attribute

'miShadingSamples' (float)

is recognized on the Maya shape and transform nodes and translated to mental ray if its value is not negative.

Create this attribute as follows:

addAttr -ln "miShadingSamples" -at "float" myTransformNode

Depth-of-field samples override

The depth-of-field effect in Maya (controlled on the camera) uses a mental ray custom lens shader which performs true 3D depth-of-field rendering, shooting multiple rays per pixel to get a smooth result.

The number of these extra lens samples is pre-defined to 4 but can be adjusted in two ways.

You can add the dynamic attribute

'dofLensSamples' (integer)

to the mental ray globals node, which defines a new default for all depth-of-field effects on all cameras in the scene.

Create this attribute as follows:

addAttr -ln "dofLensSamples" -at "short" mentalrayGlobals 

A per camera override is supported as well by adding the dynamic attribute

'miLensSamples' (integer)

to the Maya camera shape node.

Create this attribute as follows:

addAttr -ln "miLensSamples" -at "short" perspShape

When the objects get out of focus, it is often necessary to raise the number of samples.

Memory mode

mental ray watches memory consumption during integrated rendering (preview and batch), and may react to low memory conditions to circumvent mental ray fatal memory errors which normally crash Maya. By default, mental ray is aborted when any memory request exceeds the currently set memory limit plus a 'zone' of 20% (matching the recommendation of setting the memory limit to 80% of installed physical memory).

This functionality can be adjusted by adding the following dynamic attribute to the mental ray globals node:

'memoryMode' (enum: none, report, inquiry, abort, release)

The mode values are as follows:

• 'none' (0) to disable the memory handling altogether
• 'report' (1)
• 'inquiry' (2) to print a warning message in the script editor
• 'abort' (3) to force an interrupt of mental ray rendering
• 'release' (4) to call a MEL procedure to release memory in Maya

The existing attribute memoryZone on the mental ray globals node can be used to control the zone (in percent of memory limit) that determines when memory handling should come into action and proceed according to mode.

Create this attribute as follows:

addAttr -ln "memoryMode" -at "enum" -enumName "None:Report:Inquiry:Abort:Release" mentalrayGlobals

String options support (for Maya 2008 and below)

Many features can be controlled by string options, which minimizes parse errors. Use the dynamic attribute:

'miDefaultOptions.stringOptions' (compound, multi):

It has 3 children name, type, and value, all of type string, which provide the required information for the mental ray option. More children are possible but will be silently ignored by mental ray.

Set an attribute as follows:

setAttr -type "string"
miDefaultOptions.stringOptions[0].name "motion factor";
setAttr -type "string"
miDefaultOptions.stringOptions[0].type "scalar";
setAttr -type "string"
miDefaultOptions.stringOptions[0].value "1.0";

More attributes can be set by using a different array index. Reusing an existing index overwrites the corresponding option.

The following keywords are recognized in the type and value fields:

This attribute is created automatically for Maya 2008. For pre-Maya 2008 scenes, create the attribute as follows:

addAttr -at compound -nc 3 -ln "stringOptions" -multi miDefaultOptions;
addAttr -dt "string" -p "stringOptions" -ln "name" miDefaultOptions;
addAttr -dt "string" -p "stringOptions" -ln "value" miDefaultOptions;
addAttr -dt "string" -p "stringOptions" -ln "type" miDefaultOptions;

To turn off network baking

mental ray provides an attribute that allows you to control the use of satellites for integrated baking of textures. By default, mental ray sets this attribute to true:

setAttr miDefaultOptions.lightMapsNetwork false

However, mental ray may disable this option for the actual bake run when it detects unsupported cases such as when Bake to one map is enabled in any active bake set.

Ambient occlusion

To calculate ambient occlusion more accurately when transparency is a factor, turn on the Occlusion Deep attribute. You can expose this attribute using the following dynamic attribute:

addAttr -at "bool" -ln "occlusionDeep" textureBakeSet1

Hide objects from final gather rays

Add the dynamic boolean attribute miFinalGatherHide to the shape node of your object so that it becomes invisible to final gather rays. This is different from disabling the Final Gather Cast and Final Gather Receive flags, which turn the object into a black hole as far as final gather is concerned. Set this attribute as follows:

addAttr -ln "miFinalGatherHide" -at bool myShapeNode;

Elliptical filtering

You can obtain advanced features in elliptical filtering by setting the following dynamic attributes. For more information regarding these attributes, see the Auxiliary Functions section in the mental ray for Maya reference guide.

addAttr -longName "miEllipticalBilinear" -at bool -defaultValue 1 file1; 

addAttr -longName "miEllipticalEccMax" -at "float" -defaultValue 4.0 -minValue 0.001 -maxValue 40.0 file1; 

addAttr -longName "miEllipticalDiscR" -at "float" -defaultValue 0.3 -minValue 0.001 -maxValue 1.0 file1; 

addAttr -longName "miEllipticalCircleR" -at "float" -defaultValue 0.8 -minValue 0.001 -maxValue 1.0 file1;

mental ray Derivatives

Use this attribute if you want to use mental ray derivatives for NURBS and subdivision surfaces (to interact with shaders), instead of the default mental ray for Maya derivatives.

Create this attribute on the shape node as follows:

addAttr -ln "miDerivatives" -at "enum" -en "none:first:second:both" -dv 0 pSphereShape1;

Values within the range of 0 to 3 are supported for -miDerivatives.

• 0 = no derivatives
• 1 = first order derivatives
• 2 = second order derivatives
• 3 = first and second order derivatives

mental ray Ray Offset

Use this attribute to specify how much to offset a ray from the geometry. Ray Offset is useful in scenes with raytraced self-shadowing artifacts.

Create this attribute on the shape node as follows:

addAttr -ln miRayOffset -at "float" -dv 0.0 pSphereShape1;

This attribute is often used to help resolve shading artifacts such as the tessellation that appears in shadows or raytracing effects.