Declaration Options

Declarations of shaders (and phenomena, see page phenomenon) allow a number of options to be specified in the declaration block. These options specify requirements of the shader or phenomenon, specifying conditions that must be met before the shader or phenomenon can run correctly, or information about the shader that tells mental ray how to call it. They should be used only if it is impossible for the shader to do its job without this option, but not to second-guess the user, assuming that if this shader is used, then the user "probably" wants this option. Shader requirements take away control from the user and should be used with care. Before rendering, mental ray collects the requirements of all shaders defined in the scene, checks for conflicts, and adjusts global options and camera parameters to suit the shaders. Shaders should not assume that an option specified in the declaration has an effect because mental ray may choose to ignore it if there is a conflict with another declaration.

For example, if a shader specifies that it can operate only if ray tracing is enabled (a common case for lens shaders), it should specify the trace on option to tell mental ray to enable ray tracing even if no ray tracing was specified in the global options statement.

Here is the complete list of available options. If an option is not present, the default is "don't care" unless otherwise noted. If specified, these options are equivalent to the corresponding options given in the options top-level statement; refer to the description of option blocks for more details on the operation of these options.

scanline on|off

The scanline rendering algorithm must be turned on or off, respectively.

trace on|off

Ray tracing must be turned on or off. For example, lens shaders that modify the ray direction should set this to on.

shadow off

Shadows must be turned off for this shader to function.

shadow on

Shadowing must be enabled, either regular, sorted, or segmented.

shadow sort

Shadowing must be enabled, either sorted or segmented. Regular is not sufficient.

shadow segments

Segmented shadows must be enabled. Regular or sorted shadows are not sufficient.

face front|back|both

Intersection testing should consider front-facing, back-facing, or both front-facing and back-facing geometry, respectively. For example, a surface is visible if the incoming ray direction is opposite to the normal vector of the surface, and the face mode is either front or both but not back.

derivative [1] [2]

The object that this shader or phenomenon is attached to (by being named in its material, for example) must have first or second derivatives, respectively, or both. This option has an effect only on free-form surface geometry because mental ray cannot compute derivatives for polygons.

object space

The shader functions only if all geometry is defined in object coordinates.

camera space

The shader functions only if all geometry is defined in camera space.

volume level_int

The volume level defines the "density" behavior of volume shaders. If autovolume mode is enabled in the options block, mental ray keeps track of which volumes a ray is in. If the current point is in multiple volumes, equal volume levels mix, and higher levels displace lower volumes. For example, if the point is in four volumes A, B, C, and D, with volume shaders defining levels 3, 2, 3, and 1, respectively, both the volume shaders A and C will be called because they displace B and D. See page autovolshd for more information about autovolume-enabled volume shaders.