Options

options "name"
    option_statements
end options

Options blocks contain global settings like rendering modes, default or override values for properties of scene elements, and other general settings. One options block scene element must be specified to the render statement in order to render a scene. Most of the render options values can be overridden with an appropriate command-line option.

The following option_statements are supported:

String Options

Traditionally, option names are hardcoded in the .mi syntax and in the data structures of the programming interface. New options are implemented as arbitrary name value pairs, where the name of the option is a quoted string, and the value can be a boolean, string, integer, float, 3 floats, or 4 floats:

  "name" on|off
  "name" "string"
  "name" int
  "name" float
  "name" float float float
  "name" float float float float

Only one option of a given name can be specified; the last option overrides previous ones of the same name. An integer value may be specified in place of a float value and some options may contain either 3 or 4 floating point values; besides these exceptions, values of a wrong type are ignored. Also, misspelled or unknown options are silently ignored by mental ray.

String options can be freely intermixed with other option statements in the options block, with one exception: a string option may not be preceded by a frame buffer n option without a type string; the frame buffer statement should therefore contain an empty type string (frame buffer n "").

By convention, option names consist of multiple words separated by a blank space where the first word specifies the logical group or affected feature of the option, as in "finalgather mode" "automatic".

The string options provide a more general and flexible syntax to specify options in the .mi format; the syntax does, however, not specify the semantics of how specific options are used by mental ray. It is also possible to provide options which are not known by mental ray but could be used by custom shader packages using the C++ shader interface extensions.

Those string options which are supported by mental ray are documented below in line with all other options.

Unified Sampling

"unified sampling" on|off: Turn unified sampling on or off.; Once enabled, a simple set of controls can be used to tune the sampling quality of any of the different primary rendering algorithms. The native settings of those algorithms are overruled. In addition, this sampling method uses different approaches for adaptivity to image detail, working more effectively with oversampling effects like area lights, motion blur, and depth-of-field.; The default is off.
"unified sampling subfilter" on|off 3.13: Control the unified sampling filter.; The value on enables a new, superior sample filtering scheme that improves quality for scenes with a large min/max samples range. It avoids artifacts of the original filter seen along object edges, on very bright small highlights, or as flickering in animations, which were caused by disproportional heavy weighting of pixels with larger number of samples. The new filtering requires slightly more memory per filtered frame buffer, dependent on the filter size, the tile size, and the number of rendering threads.
The value off uses the original filtering scheme for strict backwards compatibility to the previous version of mental ray.; The default is on. 3.13
"samples max" num_scalar: Set the maximum number of samples per pixel.; If the specified number of samples is reached then no more samples are taken, regardless of the quality setting. A value of 1.0 means 1 sample per pixel. Higher values enable oversampling, like 1000 will set a maximum of 1000 samples per pixel. Lower values will cause undersampling, like a setting of 0.5 means 1 sample will be taken to fill several pixels. This results in a coarse image, suitable for preview rendering purposes. The number of samples actually rendered for a given pixel lies between min and max settings, and will be determined by the quality and error measures during rendering of a scene.; The default is 100.
"samples min" num_scalar: Set the minimum of samples per pixel.; The minimum number of samples is always taken, regardless of the demands from quality and error measures during rendering of a scene. The meaning of the value is similar to max. The number of samples actually rendered for a given pixel lies between min and max settings, and will be determined by the quality and error measures during rendering of a scene.; The default is 1.
"samples quality" r [g b]: Set the desired sampling quality.; This is the primary quality control for unified sampling. It is given as a color triple or a single scalar value, applying to all color channels identically. Typical values are between 0.0 and 1.0 but values much higher are also accepted. The higher the quality the more samples are taken in the areas of largest error.; The default is 0.5.
"samples error cutoff" r [g b]: Set the sampling error threshold.; It is given as a color triple or a single scalar value, applying to all color channels identically. If set to values greater than 0.0 areas with sample errors which fall below that threshold won't be considered for more sampling.; The default is 0.0.

Legacy Sampling

contrast r g b [a]: The color contrast to control spatial oversampling.; If neighboring samples differ by more than the color r, g, b, a, then additional samples are taken controlled by the recursive supersampling algorithm and its samples parameters. The contrast is modified based on the recursion level: at sample level 0, the contrast is used directly; at sample level 1, the contrast is doubled (effectively requiring a higher contrast to force another subdivision), and so on. Negative levels divide the contrast, i.e. use a fraction 1/2 , 1/4 , and so on. In general, the contrast is multiplied by 2^level at the supersampling level level, which is bounded by samples.; This is the primary control of anti-aliasing image quality. Typically values are 0.1 for r, g, b, and a. Higher values such as 0.2 or 0.3 reduce quality; lower values increase quality. Values less than 0.05 do not further increase quality in most cases. The r, g, b, a components can be specified separately to allow physiologically correct contrast values; the human eye is much more sensitive to different shades of green than blue and red, and can only poorly distinguish shades of blue. The a value should be set to 1.0 if the matte (alpha) channel is not needed; it is also possible to set a lower than r, g, b to generate matte channels with a higher quality than the color image. Note that for high-quality rendering, the samples parameters must be adjusted.; The default is 0.1 0.1 0.1 0.1. If just r g b is given a defaults to the average of r g b.; The rasterizer does not use this setting.
time contrast r g b [a]: The time contrast to control temporal oversampling for motion blurred scenes.; The number of temporal samples is approximately proportional to the inverse of the time contrast value. Using values for time contrast that are higher than contrast can speed up motion blur rendering at the price of more grainy images without degrading the quality of spatial anti-aliasing. For this reason the mental ray default is chosen much higher than the spatial contrast. For fast motion blur, an alternative non-adaptive sampling technique can be used by setting the time contrast to 0 0 0 and minimum and maximum sampling to the equal relatively high value, such as 2 2. See the rasterizer for an alternative high-speed motion blurring algorithm.; The default is 0.2 0.2 0.2 0.2. If just r g b is given a defaults to the average of r g b.; The rasterizer does not use this setting.
samples [min_int ] max_int: Determine the minimum and maximum sample rate.; Each pixel is sampled at least 2^min×2^min times and at most 2^max×2^max times. (2ⁿ in each direction). If min is 0, each pixel is sampled at least once. Positive values increase the sample rate; negative numbers reduce the sample rate to less than one initial sample per pixel (infrasampling). For example, if min is 1, each pixel is sampled at least 2×2 = 4 times, if min is -1, at least one sample is taken for 2×2 = 4 pixels. min defaults to -2, which means that at least one sample per 4×4 = 16 pixels is taken. If min is chosen too small, small features may be lost if all samples happen to miss it (if it is found just once in any pixel of a task, mental ray will analyze the feature and render it correctly). If no min value is given, max - 2 is used by default. It is recommended to use max values larger than or equal to min + 2; the difference should not be higher than 3. Typical values for min and max are -2 0 for low-quality preview rendering, -1 1 for medium-quality rendering, and 0 2 or 1 3 for high-quality renders. Note, that while this option offers simple control of rendering quality, it is recommended to control quality with the contrast option, which allows much finer control and deals more gracefully with high-contrast cases where the samples option can leave aliasing due to the hard cutoff. The samples statement should be used only as a hard sampling limit. If a filter options statement is used to set a filter other than box 1 1, min and max must be set to at least -1 0. mental ray enables jittering by default, unless max is less than 1.; The default is -2 0.; The rasterizer does not use this setting.
samples min_int max_int defmin_int defmax_int: Per-object sample setting defaults.; mental ray accepts two optional extra parameters that set the default object sample limits. In mental ray, objects may constrain sampling of the pixels they cover. The defmin_int and defmax_int parameters apply to pixels where no objects are seen, or all the objects that are seen have no samples limit. mental ray will never take fewer than 2^min and more than 2^max samples per direction, and in areas with no object sample settings it will further reduce that range to 2^defmin through 2^defmax.; The defaults are -2 0 -128 127 (the last two values are markers for "no further restrictions" because they are outside of the -2 0 range).
samples collect num_int: Control spacial sampling quality in the rasterizer.; The rasterizer has a separate pixel sample collection and compositing phase, which controls the number of samples per pixel-dimension to use for computing a pixel value. Due to motion blurring, this number can differ from the number of shading samples taken because shading samples are cached and re-used along the motion path. Increasing the collect rate improves motion blurring at little performance cost, unless the -shading_samples parameter is so low that extra shading sampling points are forced.; The default is 3, which yields 9 samples per pixel.
shading samples num_scalar: Control shading quality in the rasterizer.; After geometry has been tessellated according to the geometry approximation settings, it is further subdivided by the rasterizer into shading samples. The num value controls the number of shading calls per pixel.; The default value is 1.0.
samples motion num_int: Control shading quality of moving objects in the rasterizer.; Determines at how many points in time a moving object is sampled in rasterizer mode. A value of 1 means that a moving object is sampled once at shutter open time, and this result is blurred across the motion path. Higher values than 1 sample at more points during the shutter interval.; The default is 1.

Sampling Options

filter box|triangle|gauss|mitchell|lanczos [width [height]]: Set global image filtering characteristics.; The filter statement specifies how multiple samples are to be combined into a single pixel value. This option allows changing the filter kernel or the filter size. The available kernels are: box, triangle, Gauss, Mitchell, and Lanczos. The size of the filter is specified in pixel units. If no height is given it is taken to be equal to the width. Filters must be larger than 0.0. If the size of the filter is not specified, default values are used. These are 1.0 for box, 2.0 for triangle, 3.0 for Gauss and 4.0 for Mitchell and Lanczos. The default height is the same as the default width. Larger filter sizes result in softer images and may reduce rendering speed slightly, while values smaller than the defaults can introduce artifacts. Filters must be larger than 0.0 but sizes smaller than 1.0 are generally wasteful since they will discard some samples.; The box filter sums all samples in the filter area with an equal weight. The triangle filter functions has the shape of a pyramid centered on the pixel, which means that samples at the center of a rendered image pixel contribute more than more distant samples. The Gauss filter weights the samples using a Gauss curve that is cut off at an ellipse centered on the pixel. The Mitchell and Lanczos filters are both approximations of the theoretically ideal sinc filtering function, cut off after its second lobe. In most cases, the Mitchell filter gives better results. For these two, a filter width of 4.0 corresponds to a frequency cutoff of 2.0 pixels, the Nyquist frequency. In order to use non-default filters, the limits for the samples statement must specify min = -1 or greater, and max = 0 or greater. Otherwise, a warning will be printed and the filter statement ignored.; The default is a box filter of width and height 1.0, which is the fastest of the filters.
filter clip mitchell|lanczos [width [height]]: Set global image filtering characteristics.; These are variants of the regular Mitchell and Lanczos filters that clip the filter result to the range of samples under the filter. Mitchell and Lanczos filters have negative coefficients, which can cause ringing around sharp contrasts. Clipping prevents ringing.
jitter jitter: Enable spacial sample jittering.; The jittering factor introduces systematic variations into spatial sample locations. Without jittering, samples are taken at the corners of pixels or subpixels. Jittering displaces the samples by an amount calculated by lighting analysis. This is used to reduce artifacts. Jittering is turned off by specifying a jitter of 0.0.; Jittering is turned on by default if the maximum sampling is at least 1 (at lower sampling densities jittering introduces artifacts).

Progressive Rendering

"progressive" on|off: Turn progressive rendering on or off.; Note, that the iray rendering mode is also implicitly rendering in progressive mode, therefore sharing some of the progressive rendering options below.; The default is off.
"progressive subsampling size" size_int: Control coarse lower-resolution sampling of the first images.; Values greater than 1 activate subsampling in blocks of pixels. The value specifies the size of pixel blocks (sizexsize) where initial samples are placed first, typically displaying as a coarse image with the impression of a lower resolution. The larger size the coarser the initial image. Values of 0 or 1 disable this feature. A value of 2 computes samples for blocks of 2x2 = 4 pixels. The task size has to be a multiple of this subsampling size, otherwise it will be automatically adjusted to the closest possible value. Those pixels in a block which have not been rendered yet are filled with color values according to the setting of subsampling mode, see below.; The default is 0 for disabled.
"progressive subsampling mode" "sparse"|"detail": Control appearance of subsampling pixels which are not rendered yet.; If set to sparse then unrendered pixels are set to black. This produces images with missing pixels giving the impression of noise. If set to detail then pixels which have not been rendered yet are interpolated from the nearest surrounding finished samples. This displays as a smooth image of lower resolution.; The default is detail.
"progressive subsampling pattern" "linear"|"scatter": Control in which sequence the samples are computed.; If set to linear then pixels are computed in a line-by-line order within a pixel block. If set to scatter then pixels are rendered in a quasi-random order.; The default is scatter.
"progressive min samples" num_int: Set minimum number of samples per pixel for progressive rendering and iray.; Set the minimum number of samples per pixel to compute before considering any of the following abort criteria to stop progressive rendering and iray. If the corresponding maximum samples setting is lower than this value the minimum samples setting is ignored.; The default is 4.
"progressive max samples" num_int: Set number of samples per pixel to stop progressive rendering and iray.; If this number of samples per pixel has been rendered then stop progressive rendering and iray automatically. If set to 0 or lower then the number of samples is never considered to stop rendering.; The default is 100.
"progressive max time" seconds_int: Set time in seconds when to stop progressive rendering and iray.; If progressive rendering and iray has run the given number of seconds it gets stopped automatically. If set to 0 or lower then the passed time is never considered to stop rendering.; The default is 0 for unlimited.
"progressive error threshold" threshold_scalar: Set error threshold to stop progressive rendering and iray.; If the quality of the rendered image is below this error threshold then progressive rendering gets stopped automatically. A value if 0.0 targets perfect quality and won't stop rendering. A value of 0.5 will stop rendering already at a very low quality.; The default is 0.05 for regular progressive, and 0.15 for iray.
"progressive occlusion cache points" points_int: Enable built-in occlusion cache for progressive rendering with IBL.; Once enabled, occlusion information will be pre-computed and stored in the cache with the specified number of points. Higher values of points increase the quality of the occlusion information but require longer time to calculate before rendering starts. The cache will automatically be used with IBL in "approximate" lighting mode. A value of 0 will disable this feature.; The default is 0, which disables the cache.
"progressive occlusion cache rays" rays_int: Specify the number of occlusion rays to be shot per point in the occlusion cache.; Higher numbers increase quality but also raise pre-computation time. A value of 0 will enforce the default number of rays.; The default is 128.
"progressive occlusion cache max frame" frame_int: Set a frame number at which to stop using the occlusion cache.; If the specified frame has been rendered then the subsequent frames will fade out the cache contribution and converge to the exact IBL solution.; The default is 32.
"progressive occlusion cache exclude" label_int: Exclude objects to be considered for the occlusion cache.; Objects with the specific label are not taken into account when computing the cache.; The default 0, to not exclude anything.

Tessellation Quality

approximate technique [min_int max_int ] all

Set global override for geometry approximations.

This statement overrides all approximations for base surfaces (i.e. the surface before applying displacement), and free-form surfaces without displacement, in geometric objects. See section approx for a more detailed description of approximations. Here is a brief summary of technique, which is a list of one or more of the following:

view
tree
grid
fine
[regular] parametric u_subdiv [v_subdiv]
length edge
distance dist
angle angle
spatial edge
curvature dist angle

Like in object approximation statements, the subdivision limits min and max can be specified how often a triangle can be subdivided. The defaults for min and max are 0 and 5, respectively; 5 is a very high value because every increment of 1 can quadruple the number off triangles in the extreme case. In objects, the approximation technique is followed by the surface or curve it applies to; in the options the keyword all indicates that an option approximation overrides all object approximations. The spatial and curvature statements are obsolete (they are only combinations of length, distance, and angle modes) and are retained for backwards compatibility only.

approximate displace technique [min_int max_int ] all

Set global override for displacement approximations.

This statement overrides all approximations for displacement maps in geometric objects. Both kinds of approximation overrides are useful for temporarily reducing tessellation quality for previews to reduce tessellation and rendering time without redefining all objects, for example by specifying

approximate regular parametric 1.0 1.0 0 2 all
approximate displace regular parametric 1.0 1.0 0 2 all

mental ray also offers fine approximation, which can efficiently approximate very detailed displacement maps and surfaces with a minimum of parameters: approximate fine view length 0.5 all

max displace dist

Set global override for maximum displacement offset.

This statement overrides all max displace statements in displacement-mapped objects with the maximum displacement distance dist. No displacement shader may return a larger value; that would cause truncated displacement. dist must be greater than 0.0.

Motion Blur

shutter [delay] shutter

Control motion blur rendering.

The camera shutter opens at time delay and closes at time shutter. If shutter is equal to delay, motion blur rendering is disabled; if shutter is greater than delay, motion blur rendering is enabled. The normal range is (0, 1), which uses the full length of the motion vectors or motion vector paths. It can be useful to set delay and shutter both to 0.5, which disables motion blur rendering but computes scene data at an offset of one half of the frame, which allows bi-directional post-motion-blur in an output shader. Also, see the scanline rast mode for high-speed motion blur.

The defaults are both 0.0, disabling any motion blur.

motion on|off

Control motion data computation.

Normally, the shutter statement automatically determines whether motion blur computation is enabled, and turns it on if there is a non-zero shutter interval. The motion statement allows to overrides this and turn motion blur computation on or off explicitly. For example, it might be useful to define a zero shutter interval but still turn motion on (order is important), so that shaders get a valid state->motion vector. If motion is turned off, this vector is not computed.

Note: the main control for motion blur is the shutter option, not the motion toggle. The shutter defaults to 0 and must be set explicitly in order to render with motion blur. Here is a list of common motion blur settings:

shutter 1.0: render with motion blur (and generate motion vectors)
shutter 0.0 motion on: do not render motion blur but generate motion vectors
shutter 1.0 motion off: invalid setting, should not be used
shutter 0.5 0.5: do not render motion blur, but compute at half the motion vector offset

motion steps num_int

Control non-linear (piece-wise linear) motion blur.

If motion blurring is enabled, mental ray can create motion paths from motion transforms, much like multiple motion vectors on vertices can create motion paths. This option specifies how many motion path segments should be created for all motion transforms in the scene. The number num must be in the range 1…15. If objects with motion transformations also specify motion vectors, the number of motion vectors per vertex must agree with the motion steps value. mental ray will add both sequences vector by vector, so both lists must have the same length.

The default is 1.

"rast motion factor" num_scalar

Control the reduction of shading quality for fast-moving objects.

When using the rasterizer with motion blur, there is often opposing demands on shading sample settings, with high values yielding higher quality, but lower values rendering faster. Setting this factor to a value larger than 0.0 automatically lowers shading samples for fast-moving objects, at a rate proportional to the magnitude of the setting and the speed of the instance in screen-space. Care is required when tuning this value, but 1.0 should provide a good starting point. A value of 0.0 disables this feature.

The default is 1.0.

"geom displace motion factor" num_scalar

Control the reduction of displacement quality for fast-moving objects.

For polygon/triangle and ccmesh displacement the adaptive subdivision checks the motion length in screen space, which is used to dynamically modify the length criterion of the displace approximation setting. This will adjust the quality of displacement in relation to the amount of motion blur in the image, with positive impact on performance and memory consumption. Geometry is reduced only in areas of the object with large motion. This feature is enabled by default with a factor of 1.0, which results in an good compromise between quality decrease and rendering acceleration. Values greater than 1.0 will further reduce the displacement detail, and values lower than 1.0 will raise quality towards the static case. Setting the factor to 0.0 will disable this feature, which should match the rendering results from previous versions of mental ray.

The default is 1.0.

Depth Limits

trace depth reflect_int [refract_int [sum_int ]]: Set recursion depth limits for ray tracing.; The reflect parameter limits the number of recursive reflection rays. If it is set to 0, no reflection rays will be cast; if it is set to 1, one level is allowed but a reflection ray can not be reflected again, and so on. Similarly, refract controls the maximum depth of refraction and transparency rays (which implement transparency with and without index of refraction). Additionally, it is possible to limit the sum of reflection and refraction rays with sum. For example, if 3 3 4 is given, an eye ray may be reflected 3 times, or refracted 3 times, or reflected twice and then refracted twice, or any other combination that sums up to at most 4. Note, that custom shaders may override these values.; The defaults are 2 2 4.
"rast transparency depth" depth_int: Set rasterizer transparency depth limit.; If set to a positive value then the transparency compositing for the rasterizer will end at the depth specified. This can be used to tune performance for scenes where it is known that the main color information is provided by the first few depth layers.; The default is 250.

Shadows

shadow off: Disable shadow computation.; This statement disables all shadows, and overrides instance and object shadow flags.
shadow on: Enable simple shadow computation.; This is the most efficient and least flexible of the shadow modes. If shadows overlap because multiple objects obscure the light source, the order in which these objects are considered (and their shadow shaders are called) is undefined. If one object is found to completely obscure the light, no other obscuring objects are considered. This statement turns off shadow sorting and shadow segments. Also see shadowmap motion below.
shadow sort: Enable sorted shadow mode.; The shadow sorting is similar to the simple shadow mode, but ensures that the shadow shaders of obscuring objects are called in the correct order, object closest to the illuminated point first. This mode is slightly slower but allows specialized shaders to record information about obscuring objects. If no such special shader is used, this mode offers no advantage over simple shadow on.
shadow segments: Enable advanced ray tracing shadow segments.; In this shadow mode the shadow shaders are called in order. Additionally, shadow rays are traced much like regular rays, passing from one obscuring object to the next, from the light source to the illuminated point. Each such ray is called a shadow segment. This slows down rendering, but is required if volume effects should cast shadows (such as certain complex shaders like fur and smoke volume shaders). This mode requires support from the shadow shader, which must use the mi_trace_shadow_seg function to cast the next shadow ray segment.
shadowmap on|off|detail: Global control of shadow map computation.; This flag turns shadow maps on or off for the entire render. Shadowmap parameters are specified on each light source. The mode detail enables detail shadowmaps which call shadow shaders attached to materials, and store more than single depth information per shadowmap pixel. For this reason, they tend to be slower than standard shadowmaps. Setting detail will force all shadow maps in the scene to be detail shadow maps.; The default is off, for disable all shadow maps.
shadowmap only: Compute shadow maps only.; mental ray will not render any regular output image but only generate shadow maps with shadowmap file statements. They will be computed and saved. This mode is disabled with shadowmap off.
shadowmap rebuild on|off: Determines whether all shadow maps should be recomputed.; If this option is off then shadow maps are loaded from files or reused from previously rendered frames if possible. If this option is on, no shadow map is reused - everything is recomputed.; The default is off.; Note: when using detail shadow maps, mental ray may write to the shadow map file during rendering even if the shadowmap rebuild option is set to off. This is due to certain optimizations of the implementation for empty tiles in the shadow map. Note that this can in particular lead to corrupt shadow map files and rendering failures when using the same shadow map file simultaneously for multiple renders on different machines in a render farm.
shadowmap rebuild merge: Specifies that shadowmaps should be loaded from files if available, but the regular shadowmap computation is performed anyway. The recomputed points are written top the existing shadowmap only if it is closer to the light. This is useful for building up shadowmaps for pass rendering, so that objects from another render pass can still cast shadows on objects in the current pass.
shadowmap motion on|off: Consider motion when computing shadow maps.; Determines whether shadow maps should be motion blurred such that moving objects will cast shadows along the path of motion. Turning this option off can improve performance of rendering shadow maps slightly faster. Note, that since shadow maps do not deal with transparent objects and motion blurring introduces a form of transparency at the edges, shadow map shadows can appear too large in the direction of motion if the object moves quickly.; The default is on.
shadowmap bias bias: Set global shadow map bias override.; This option applies the specified shadowmap bias to all light sources, as if the bias had been specified in each of them. Specifying a bias has the effect of switching the shadowmaps from the normal halfway-point Woo trick to a fixed-distance algorithm.
"shadowmap pixel samples" samples_int: Control anti-aliasing quality of shadow maps computed with the rasterizer.; This basically sets the samples collect option for shadowmap rendering to the specified value. A value of 0 enforces to use the samples collect default of the rasterizer also for shadowmap rendering, which is currently set to 3.; The default is 1, which means 1 sample per shadowmap pixel.

Rendering Algorithms

trace on|off: Enable ray tracing.; Normally, mental ray will use a combination of a scanline rendering algorithm and ray tracing to calculate samples of the scene. If trace off is specified, ray tracing is disabled, and mental ray will rely exclusively on the scanline algorithm. Since the scanline algorithm can only compute straight rays from the pinhole camera, reflection rays cannot be cast and refraction rays are computed like transparency rays, which do not allow control over the ray direction based on the index of refraction of the material. Lens shaders cannot alter the ray origin and direction. However, reflections onto environment maps do work. Shadows are also affected if ray tracing is turned off. If off, this flag overrides instance and object trace flags.; The default is on.
scanline on|off|rast|rapid: Enable and control the first-hit rendering algorithm.; This allows to select a scanline rendering algorithm that is used to accelerate computation of rays coming straight from the pinhole camera, such as primary rays. In most cases this gives better performance than pure ray tracing, but requires extra memory. Turning scanline off forces mental ray to rely entirely on ray tracing also for primary hits. This may slow down rendering in the general case, but in some cases, for example with small task size, the overhead of the scanline algorithm may outweigh its benefit. The rasterizer will be enabled with rast or rapid. It uses a different scanline algorithm based on sample caching. It is usually slightly faster than regular sampling for static scenes, and substantially faster when rendering motion blur. Sample caching does introduce artifacts for raytrace effects; in particular, moving mirrors and glass panes drag the reflection or refraction with them.; The default is on, for the regular scanline algorithm.
acceleration bsp: Use the original binary space partitioning BSP algorithm for acceleration of ray tracing.; This algorithm is often but not always faster than any other acceleration methods for scene which fit into memory. It is controlled by the bsp size and bsp depth statements. This BSP implementation can not cope with dynamic scene content like assemblies. In such cases, mental ray will switch automatically to BSP2.; This BSP algorithm is the default.
acceleration bsp2: Use the advanced binary space partitioning acceleration BSP2 algorithm.; The BSP2 acceleration is recommended for large scenes, and is required for rendering of scenes with assemblies. This acceleration implements heuristics for scenes with multiply-instanced objects by switching to the object space intersection, which replaces the functionality of the grid acceleration in previous mental ray versions. There are no further controlling options.
acceleration grid: Deprecated Enable grid acceleration method.; The option is kept for backwards compatibility and falls back to bsp2.
acceleration large bsp: Use the original BSP algorithm with extensions for ray tracing of large scenes.; This is an alternative to regular bsp mode. The parameters of the original BSP have identical meaning for this variant, but a multi-level BSP tree is actually used. This may slow down ray tracing up to 20% in extreme cases, but works much more effectively with geometry caching (and disk swapping) and allows far larger scenes to be rendered. Regular bsp mode can run into trouble when scenes begin to exceed a few tens of millions of triangles and poor scene coherence, like during final gathering.
bsp size size_int: Control leaf size for original BSP algorithms.; Sets the maximum number of primitives in a leaf of the BSP tree, for bsp and large bsp acceleration only. mental ray will subdivide BSP voxels containing more triangles, unless the maximum BSP depth is exhausted. Larger leaf sizes reduce memory consumption but increase rendering time.; The default is 10.
bsp depth depth_int: The maximum number of levels in the BSP tree, for bsp and large bsp acceleration only. Larger tree depths reduce rendering time but increase memory consumption, and also slightly increase preprocessing time. If there are too many triangles in the scene to fit into the BSP tree with the size specified by bsp size and bsp depth, the bsp size value is disregarded and larger leaves are created. This slows down rendering significantly. Larger bsp depth values of 50 or even higher often massively improve rendering speed in BSP mode for larger scenes. The book Rendering with mental ray further discusses how to tune these parameters for specific scenes.; The default is 40.
bsp shadow on|off: Enable separate BSP tree for shadow computation.; mental ray supports a separate shadow BSP tree that accelerates ray trace shadows, for bsp acceleration only. It can greatly improve speed if shadows are cast by simplified shadow-only objects because it is no longer necessary to populate the master BSP tree with large hero objects.; This mode is off by default.
grid resolution xres_int [yres_int zres_int ]: Deprecated; Ignored, but kept for backwards compatibility.
grid depth depth_int: Deprecated; Ignored, but kept for backwards compatibility.
grid size size_int: Deprecated; Ignored, but kept for backwards compatibility.

Feature Selection

lens on|off: Ignore all lens shaders if set to off.; The default is on.
volume on|off: Ignore all volume shaders if set to off.; The default is on.
geometry on|off: Ignore all geometry shaders if set to off.; The default is on.
displace on|off: Ignore all displacement shaders if set to off.; The default is on.
displace presample on|off: Control calling of displacement shaders to estimate bounds.; Normally, mental ray pre-samples displacement-mapped geometry to find better bounding boxes of object fragments. This increases the start up time when rendering the displaced object, but rendering itself is typically faster. However, for quick previews it may be desirable to get the first pixels as quickly as possible, regardless of the time it takes to complete the image. It may also be useful in cases where scene objects already provide a good estimate of the maximum displacement.; The default is on.
output on|off: Ignore all output shaders if set to off.; The output to image files, like in output statements, is not affected. Note, that all five disable options also affect shaders installed by phenomena. This means that the phenomenon can fail if it installs cooperating shaders that rely on each others existence, and one of them is disabled with these options. Phenomenon writers must allow for this case. The purpose of these options is fast preview rendering.; The default is on.
autovolume on|off: Enable auto volume extension.; The autovolume mode enables built-in functionality and a set of shader API functions that keep track of which volumes the current point is in: mi_volume_num_shaders, mi_volume_cur_shader, mi_volume_user_color, and mi_volume_tags.; The default is off.
photon autovolume on|off: Enable auto volume extension for photons.; This mode enables autovolume computations for light sources that are photon emitters. If the light source is inside objects whose materials have photonvolume shaders, they are applied correctly to photons emitted by the light source.; The default is off.
pass on|off: Control sample pass functionality.; Pass rendering performs operation on sample pass files. This option allows to enable or disable all pass statements in the camera. See page samplepass for more details about sample pass rendering.; The default is on.
lightmap on|off|only: Control lightmap rendering functionality.; This mode enables rendering of lightmaps. If this option is set to only, then only the lightmaps but not the camera images are rendered.; The default is on.
"ray differentials" on|off: Control ray differentials for texture filtering in secondary effects.; If turned on then ray differentials are automatically computed and propagated across ray tracing effects like reflections and refractions to determine the optimal filter size for filtered texture look-ups. If not enabled then differentials are not computed and texture filtering falls back to default filtering on primary visible objects only.; The default is off.

Caustics (Photons)

caustic on|off: Turn caustics on or off.; Even if caustics are enabled globally, they are only computed for light sources that specify an energy explicitly. The material shader that receives the caustics must also cooperate, and either the options block or the object to receive caustics must have appropriate caustic flag set. If the caustic option is set to off, this flag also overrides any instance and object caustics flags.; The default is off.
caustic mode: The global caustic cast and receive bits.; This bitmap forces to enable the corresponding bits on all instances. The default value is 3, which will enable the caustic cast and receive flags on instances and objects automatically, and the disable bits have no effect.; The default is 3.
caustic accuracy N [R]: Control caustic rendering quality.; This option controls how caustics are estimated from the photon maps during rendering. The photon map is searched outwards from the intersection point and the photons that are encountered are examined. N specifies the maximum number of photons that should be examined, and R specifies the maximum radius that is searched for photons. If N is zero, the number of photons is only limited by R, and mental ray will pick an appropriate default. If R is zero, then a scene-size dependent radius is used instead.; The default is 100 0.
caustic filter box|cone [ filter_const]: Control caustic filter.; Filtering controls the sharpness of the caustics. Specifying a cone filter with the default filter_const of 1.1 generally has the effect that the caustics in the model looks sharper. Increasing the filter_const makes the caustics more blurry and decreasing makes it even sharper but also slightly more noisy. The filter_const must be larger than 1.0.; The default is box 1.1.
"caustic merge" distance: Control merging for caustic photons.; If this option is set to a positive value, the caustic photons within the specified distance in world space are merged into a single photon. This can decrease the size of the caustic photon map dramatically.; The default is 0, for disabled.
caustic scale r g b [a]: Scale the contribution of caustics.; Caustics are multiplied by the specified color, to favor artistic look over physical correctness. Factors greater than 1 will exaggerate the effect.; The default is 1 1 1.
photon trace depth reflect_int [ refract_int [ sum_int ]]: Set recursion depth limits for photon tracing.; This option is similar to the trace depth option except that it applies to photons, not rays. The reflect parameter limits the number of recursive reflection photons. If it is set to 0, no photons will be reflected, if it is set to 1, one level is allowed but a photon cannot be reflected again, and so on. Similarly, refract controls the maximum depth of refracted photons. Additionally, it is possible to limit the sum of reflected and refracted photon levels with sum. Note, that custom shaders may override these values.; The default is 5 5 5
photonmap file "filename": Control disk-based photon map storage.; Tells mental ray to use the file filename to access the photon map on disk. If the photon map file does not exist, it will be created and the photon map will be saved into that file. If the file exists already, the photon map will be loaded from that file and used without computing a new photon map.; The default is not specified, which disables disk-based storage of photon maps.
photonmap rebuild on|off: Control re-computation of the photon map.; If a filename is specified for the photon map (using the photonmap filename option), it is normally loaded and used if the file exists. If the photonmap rebuild option is turned on, any existing file will be ignored, and the photon map will be recomputed, and an existing file will be overwritten.; The default is off.
photonmap only on|off: Compute photon maps only.; If this option is set, only the photon maps are computed without rendering any regular output image.; The default is off.

Global Illumination (Photons)

globillum on|off: Global illumination is turned on or off. Global illumination permits effects such as indirect lighting, color bleeding, etc. Note that global illumination is computed only for light sources that have an energy specified explicitly; see section light for details. The material shader that receives global illumination must also cooperate. If off, this flag overrides instance and object globillum flags.; The default is off.
globillum mode: Global globillum cast an receive bits. This bits force enabling of corresponded bits on all instances. The default value is 3, meaning that globillum cast and receive flags on instances and objects are automatically enabled and the disable bits have no effect.
globillum accuracy N [R]: This option controls how the photon map is used to estimate the intensity of global illumination. For a more detailed discussion of how this works, see the caustic accuracy option above. The default values are N=500 and R=0.0. For fast previews of global illumination, it can be useful to set N to 100.
"globillum merge" distance: If this option is set to a positive value, the globillum photons within the specified distance in world space are merged. For scenes with uneven photon distribution, this can decrease the size of the globillum photon map dramatically.
globillum scale r g b [a]: The irradiance part obtained from the globillum photonmap lookup is multiplied by the specified color. Factors greater than 1 increase the brightness of the effect.
photonvol accuracy N: This option controls how the photon map is used to estimate the intensity of caustics or global illumination within a participating medium. It applies to photon volume shaders, which compute light patterns in 3D space, such as volume caustics created by focused shafts of light cast by objects acting as lenses. The details are similar to what is described for the caustic accuracy option above. The default values are N=30 and R=0.0.
"photonvol merge" distance: If this option is set to a positive value, volume photons within the specified distance in world space are merged. For scenes with uneven photon distribution, this can decrease the size of the volume photon map.
photonvol scale r g b [a]: The illumination contributed by volume photons is multiplied by the specified color, making the effect brighter for factors greater than 1.0.
photon trace depth photonmap photonmap rebuild on|off photonmap only on|off: have the same meaning as for caustics.

Global Illumination GPU 3.12

"gi gpu" "on"|"off"|"diffuse" 3.12: Use GI GPU, the GPU accelerated Global Illumination solution.; If enabled, the GI GPU implementation is used to speed up indirect illumination effects caused by diffuse bounces of light, similar to what final gathering computes. The base parameters are taken or derived from related finalgather settings, if any, unless they are overwritten by GI GPU only settings, see further below. This mode supports any existing, well-behaving shaders.; The value "on" computes the full solution, including proper handling of reflections and refractions, by using a hybrid CPU/GPU mode. The "diffuse" mode calculates just the diffuse inter-reflections, not considering these effects when passing through transparent objects or when being reflected by glossy materials, which may be sufficient in many cases. It is typically a lot faster to render because the calculation can run solely on the GPU without being interrupted by the CPU too often. If one of the GPU modes is enabled but no capable GPU was found, then a CPU fallback is automatically used that performs exactly identical computations for identical results. However, this may take much longer to compute dependent on the CPUs utilized.; The default is "off".
"gi gpu rays" rays_int 3.12: Sets the number of secondary rays for GI GPU.; Sets number of rays per primary ray per pass (see passes below), resulting in a total number of rays equal to rays × passes. This option determines the overall level of noise and appearance of details in the final image: the more samples the less noise and higher precision. The related filter setting has further impact. For efficiency reasons, the given ray value may be rounded internally to a nearby value that is best suited for fast convergence on the GPU. If this option is not present, or set to -1, it will be derived from finalgather accuracy and samples max settings.; The default is -1.
"gi gpu passes" passes_int 3.12: Sets the number of passes for GI GPU.; This controls the anti-aliasing quality. Each pass will spawn the same number of rays, leading to a total number of rays equal to rays × passes. Setting the number of passes to a square number like 4, 9 or 16, is preferred for best quality. At minimum, one pass will rendered. If this option is not present or set to -1, it gets calculated from uniform sampling settings or the legacy samples option.; The default is -1.
"gi gpu filter" scale 3.12: Sets the filter size for GI GPU.; This filter is used for filtering irradiance samples. It reduces noise artifacts, but might also blur shadow details. The scale value is given in screen space. If this option is not present, or is set to -1, it is calculated from finalgather points.; The default is -1.
"gi gpu depth" depth_int 3.12: Sets the ray tracing depth limit for GI GPU.; This sets the maximum number of bounces for indirect illumination. If this option is not present or set to -1, it is derived from finalgather trace depth limits.; The default is -1.
"gi gpu presample density" density 3.12: Control quality of GI GPU presampling.; Sets the density of sampling points in screen space, used to execute shaders and sample their contribution for later evaluation on the GPU. Higher values give more details, but cost performance. If this option is not present, it is derived from finalgather presample density.; The default is 0.2.
"gi gpu presample depth" depth 3.12: Control quality of GI GPU presampling.; Sets the ray tracing depth for presampling. The default setting is usually appropriate.; The default is 2.

Global Illumination "Next" (Prototype) 3.13

"gi" on|off 3.13: Enable the global illumination "next" prototype.; Activates the new brute-force GI engine when set to "on". Any other global illumination engine (photons, irradiance particles and final gathering) is automatically switched off.; The default is off.
"gi rays" rays_int 3.13: Set number of rays for the global illumination "next" prototype.; Specifies the number of rays to use to compute the GI solution. This determines the accuracy of the GI result. The actual number of rays used internally is taken from the given value rounded to the closest square number, for example 75 is rounded up to 81 (9 x 9) and 150 is rounded down to 144 (12 x 12).; The default is 100.
"gi depth" depth_int 3.13: Set the trace depth for the indirect lighting computation of the global illumination "next" prototype.; This option controls the depth of the ray generation for the irradiance computation, similar to the depth of final gathering. A value of 0 means one bounce of indirect lighting contribution, 1 means two bounces and so on.; The default is 2.

Final Gathering

finalgather on|off|only|fastlookup: Final gathering for global illumination is turned on or off. The default is off. Final gathering means that when the illumination is computed at a diffuse point, the hemisphere above the point is sampled for indirect illumination. The illumination at those points is then computed as direct illumination plus a contribution from the photon map if global illumination is on. Final gathering is best suited for scenes with slow variation in indirect illumination, for example purely diffuse scenes. Final gathering eliminates the low-frequency variation in the global illumination that can often be seen if too few photons are used. Performance is kept acceptable by reusing and interpolating nearby final gathers. (Without final gathering, global illumination is computed by direct lookup in the photon map at the point - similar to the way caustics are computed.) The fastlookup mode also turns final gathering on, but also alters the global illumination photon tracing stage by computing the irradiance at every photon location, and storing it with the photon. This means that the photons carry a good estimate of the local irradiance, requiring far fewer final gathering points. Photon tracing takes longer than before and requires slightly more memory, but rendering becomes faster. mental ray allows rendering only the finalgather map, and skipping rendering of the images with the only option.
finalgather accuracy [ view ] N [R_1 [R_2]]: N controls how many rays should be used in each final gathering step to compute the indirect illumination. The default is 1000. Increasing this number makes the indirect illumination less noisy but also increases the rendering time. R_1 is the maximum radius in which a final gather result can be interpolated or extrapolated. The default maximum radius is computed based on the scene extent. R_2 is the distance within a final gather result must be used for interpolation or extrapolation. The default is 10% of the maximum radius. Radius values are in world space units unless view is specified, in which case the values are in pixels. Since mental ray 3.4 final gathering works better and faster with smaller numbers of rays; 500 is a good value. It will be slower than earlier versions if the number of rays is left unchanged.
finalgather falloff [ start ] stop: Limits the length of final gather rays to a distance of stop in world space. If no object is found within a distance of stop, the ray defaults to the environment color. Objects farther away than stop from the illuminated point will not cast light. Effectively this limits the reach of indirect light for final gathering (but not photons). The start parameter defines the beginning of a linear falloff range; objects at a distance between start and stop will fade towards the environment color. This option is useful for keeping final gather rays from pulling remote parts of the scene, which may not affect illumination very much, into the geometry cache. This allows mental ray to render with a much smaller memory footprint. See also mi_ray_falloff.
finalgather file "filename": Tells mental ray to use the file filename for loading and saving final gather points. If the finalgather file does not exist, it is created and the final gather points are saved. If it exists, it is loaded, and the points stored in it become available for irradiance lookups. If mental ray creates extra final gather points, they are appended to the file. This means that the file may grow without bounds.
finalgather file [ "name1", "name2", … ]: mental ray supports to attach a list of finalgather file names instead of providing just a single file name. All files are read and merged. The first file is rewritten with the complete map like in the single-file case.
finalgather filter size_int: Final gathering uses an speckle elimination filter that prevents samples with extreme brightness from skewing the overall energy stored in a finalgather hemisphere. This is done by filtering neighboring samples such that extreme values are discarded in the filter size. By default, the filter size is 1. Setting this to 0 disables speckle elimination, which can add speckles but will better converge towards the correct total image brightness for extremely low accuracy settings. Size values greater than 1 eliminate more speckles and soften sample contrasts. Sizes greater than 4 or so are not normally useful.
"finalgather mode"mode: Select one of the finalgather modes. "3.4" (the default) and "strict 3.4" are compatibility modes. The former one focuses on usage of the same argument set, but with rendering improvements, the latter focuses on rendering images identical or very similar to mental ray 3.4. The "automatic" mode primarily targets rendering of single still images. The "multiframe" mode targets rendering of camera fly-through animations. Both use the finalgather points argument for the approximate resp. minimal number of final gather points used in interpolation. In both modes, all finalgather points are produced in the finalgather precomputing stage. For the "multiframe" mode, the finalgather accuracy R_1 is used to limit the maximal validity distance of a finalgather point to avoid picking up illumination from remote objects if the density of finalgather points is insufficient. The "force" mode disables final gather caching completely and always performs the full and accurate computation. This takes time but yields superior quality. See also the description in the functionality chapter.
"finalgather normal tolerance" angle: This option specifies the maximal angle in degrees up to which the normal of a finalgather point may deviate from the surface normal to be considered for interpolation. If the angle value exceeds the valid range of (0…90) degrees (excluding the extremes of 0 and 90), the built-in default is used.; The default is 25.842 degrees, to maintain backwards compatibility.
"finalgather passes" num_int: Enable progressive final gathering pre-computation.; The final gathering pre-computation is performed progressively in the given number num of refinement passes. A value of 0 disables this feature and computes final gathering in the same way as previous versions of mental ray. In the current implementation, the number of passes should be in the range of 3 to 8. Note, that only the 2 most recent passes actually apply adaptivity in the screen space sampling, any additional passes just provide earlier feedback. As a consequence, any extra passes beyond 3 don't change the final gathering solution.; The default value is 3, thus the feature is enabled by default.
"finalgather points"P_int: In the automatic and multiframe finalgather modes, the number of finalgather points used for interpolation of the indirect illumination.
finalgather presample density T: This option controls the density of initial finalgather points. It increases (decreases if T < 1) the number of finalgather points computed in the initial stage approximately T times.
finalgather rebuild on|off: If a filename is specified using the finalgather filename option, it can be loaded and used if the file exists. If the finalgather rebuild option is turned on, any existing file will be ignored, and all final gather points will be recomputed and an existing file will be overwritten. The default is on.
finalgather rebuild freeze: This is equivalent to finalgather rebuild off, except that the final gather map, once created by reading it from a file or building it for the first frame, will never be modified (unless the finalgather file filename or the finalgather accuracy is changed). Extra finalgather points created during rendering will not be appended, and the finalgather file on disk will not be modified. The user is responsible to make sure that the finalgather map matches the scene and viewpoint in an animation. This is useful if multiple concurrent renderers share the map.
finalgather scale r g b [a]: The irradiance part obtained from first bounce finalgather is multiplied by the specified color. Factors greater than 1 increase the brightness of the effect. Note that this affects single bounces only.
finalgather secondary scale r g b [a]: The irradiance part obtained from secondary bounce finalgather is multiplied by the specified color. Factors greater than 1 increase the brightness of the effect.
finalgather trace depth reflect_int [ refract_int [ diffuse_int [ sum_int ]]]: This option is similar to -trace_depth but applies only to finalgather rays. The defaults are all 0, which prevents finalgather rays from spawning subrays. This means that indirect illumination computed by final gathering cannot pass through glass or mirrors, for example. A depth of 1 (where the sum must not be less than the other two) would allow a single refraction or reflection. In mental ray^3.4 only it is possible to trace diffuse bounces, previous version could trace specular or glossy bounces only. It is not normally necessary to choose any depth greater than 2. This is not compatible with mental ray 3.1 and earlier, which used the trace depth (which defaults to 2 2 4) for final gathering.

Ambient Occlusion 3.13

"ambient occlusion" on|off: Control ambient occlusion computation.; This enables ambient occlusion in general. If an actual computation is performed depends on other settings. If shaders request AO computations in the mental ray core then this setting should be enabled. If the built-in AO pass is used then this setting will ultimately control if the pass is rendered.; Default is on.
"ambient occlusion rays" nrays_int: The number of ambient occlusion rays spawned per sample.; This is a global default, but may be overridden from within shaders. If the AO pass is used then this setting is a hint, the actual number of rays may be different dependent on internal optimizations for GPU execution and the value of the "pass oversampling" setting.; The default is 256 for AO shaders, and -1 for AO pass.
"ambient occlusion cache" on|off: Control creation of the ambient occlusion cache for custom shaders.; If caching is disabled but the feature is turned on then ambient occlusion is performed on demand only, when shaders are actually calling for computing ambient occlusion.; The default is off.
"ambient occlusion cache density"density: The upper bound of the number of ambient occlusion points per pixel.
"ambient occlusion cache points"num_int: The number of cache points close to the lookup location to be used for interpolation.; The default value is 64.

Ambient Occlusion Pass, GPU Accelerated 3.13

"ambient occlusion framebuffer" "fb_name" 3.11: Set the AO frame buffer to enable the ambient occlusion pass.; Setting this to a valid frame buffer will enable the computation of the built-in AO pass.; The default value is not set for disabled.
"ambient occlusion pass gpu devices" devices_int 3.13: Select CUDA devices, or GPUs, to be used for the ambient occlusion pass rendering.; Specify GPU devices to be used for the AO computation. To select CUDA devices: the number is interpreted as a bitmask. A value of 1 means CUDA device 0, a value of 2 means CUDA device 1, and 3 means CUDA device 0 and 1. The value -1 enables all available CUDA devices. A setting of 0 switches to CPU mode.; The default is -1, for use all available CUDA devices.
"ambient occlusion pass cpu threads" threads_int 3.13: Control the number of CPUs, or CPU cores, to be used for ambient occlusion pass rendering.; Specify number of CPU threads devices to be used for the AO computation.; The default is -1, for set by mental ray.
"ambient occlusion pass oversampling"passes_int 3.13: The number of iterations to accumulate AO samples for a pixel.; This determines how many samples per image pixel are taken, thus controls anti-aliasing of the final result. Typical values are squared numbers like 1(1x1), 4(2x2), 9(3x3), and so on. Intermediate values may actually use the closest squared number internally. This setting also allows to balance AO computation and impact performance. Like raising the number of passes but reduce the number of rays will lower the AO execution time per pass, thus decreasing the load of the GPU if used, while rendering almost the same final quality. The total number of ambient occlusion rays per pixel is approximately the product of pass oversampling and rays.; By default, the value is derived from the global sampling setting, both for traditional and unified sampling modes.
"ambient occlusion pass filter"pixels_int 3.13: The AO filter radius in pixels.; The pixel radius used to filter ambient occlusion. This filtering reduces noise artifacts, recommended values are 4 to 12. A value of -1 selects an optimal internal default setting.; The default value is 0, for no filter.
"ambient occlusion falloff"exponent_int 3.11: Determine if/how the occlusion value is affected by scene distance.; Control how to fade out the occlusion effect with the occluder's distance. A value of 2 means quadratic falloff. Values greater 1 implement exponential falloff, 0 means falloff is disabled.; The default value is 2.
"ambient occlusion falloff min distance"distance 3.11: Minimal distance for the falloff to take effect.; The value can be a relative or absolute distance, see below for "max distance".; The default value is 0.
"ambient occlusion max distance"distance 3.11: Control the maximum reach of occlusion probe rays.; A negative value describes a factor relative to the scene extent, thus is a percentage. A positive value describes an absolute distance in world space units.; The default value is -1, for not limited.

Importons

"importon" on|off: If enabled, the importons are emitted and importon map is created.; The default value is off.
"importon density"density: Specifies the approximate number of importons shot from the camera per pixel.; The minimal value for this option in the current implementation is 0.02, i.e approximately 1 importon per 50 pixels. The default and recommended value is 1.0. Lower values will speed up importon emission, but could lead to less optimal photon map and decrease final image quality.
"importon merge"merge: Specifies the world-space distance used to merge importons closer than that distance.; The default value is 0.0, for merging is disabled.
"importon trace depth"depth_int: Controls the diffusion of importons in the scene. If set to zero, importons will not scatter on the diffuse bounces. This is the default. In some cases it may be required to use more than a single diffuse bounce. This is the case if the combination with final gathering is used, or when the "importon traverse" option is switched off.
"importon traverse" on|off: Enables a special behavior of importons shoot from the camera. Such importons would not be blocked by even completely opaque geometry. Instead, they would be stored for all intersections with geometry on the ray from the camera to infinity. This leads to a significantly higher number of importons stored in the scene. However, it removes the discontinuity in the distribution of the importons originated from the visibility to the camera function. The default value is on.

Irradiance Particles

"irradiance particles" on|off: Turn irradiance particles on or off.; If enabled, the irradiance particles are used to simulate indirect lighting, automatically disabling global illumination photons if they were turned on at the same time. If final gathering is enabled then irradiance particles are used to drive importance for optimized finalgather point distribution resulting in improved visual quality.; The default value is off.
"irradiance particles rays"rays_int [ r1_int [ r2_int [ r3_int ]]]: Control number of rays to shoot for estimating the irradiance.; The number of rays is used for the primary pass, all other optional numbers r1, r2, r3 are used for the secondary, or indirect, passes only. In case only rays is specified then it is used for the primary pass and 32 is used for all the indirect passes. With just r1 given in addition its value is used for all indirect passes instead. When r1 and r2 are provided then r1 is used for the first indirect pass and r2 for the second and all the subsequent indirect passes. In case all optional values are specified then r1 is used the first indirect pass, r2 for the second, r3 for the third and all subsequent indirect passes.; The default is 256. The minimum is 2.
"irradiance particles indirect passes"num_int: Set number of passes used to compute indirect lighting.; If this number is greater than 0, then a sequence of passes is done to collect the irradiance coming at every particle position, so that irradiance particles will carry both direct illumination and indirect illumination information. If this number is 0, then they will have only direct illumination information.; The default is 0.
"irradiance particles scale" r [ g b ]: Scale the contribution of the irradiance during rendering.; This is a global tuning option for artistic control. It can be specified as a single value which is used to set R, G, B at once, or as three separate values for individual control.; The default is 1.0.
"irradiance particles interpolate"num_int | "command": Control interpolation of irradiance particles.; This can be set to a numeric value or a string. The numeric values are: 0 for no interpolation, 1 for always interpolate, and 2 for interpolate only for secondary rays or, no interpolation for eye rays but interpolation for reflections, refractions, and so on. For convenience, the string values "never", "always" or "secondary" are also accepted as values having the same meaning.; Default: 1, "always".
"irradiance particles interppoints"num_int: Set number of points for interpolation.; Determines the number of points to be considered for interpolation (nearest-neighbor).; Default is 64.
"irradiance particles env" on|off: This flag enables the use of the environment maps for irradiance computation. If enabled then a separate particle map is built for the environment (if an environment shader is present) and used during rendering. Default is on.
"irradiance particles env scale" r [ g b ]: Scale the contribution to irradiance from the environment.; It can be specified as a scalar or as a color. This scaling factor is relative because it applies to the environment irradiance only: the environment irradiance is actually further scaled by the global scaling factor. If the env scale is set to 2.0 and the global scale is set to 3.0 then the actual scaling factor for the environment irradiance will be 6.0 (2.0 x 3.0).; Default is 1.0.
"irradiance particles env rays"num_int: Control number of rays for estimating the irradiance from the environment.; This number can be much greater than the number of rays used for normal irradiance computation, especially if most of the environment is covered by scene geometry (typical case: a room with just one or two windows). For outdoor scenes, it should work fine with a lower number of rays.; The default is the value of "irradiance particles rays".
"irradiance particles file" "filename": Control disk storage of irradiance particles.; If the file filename exists then mental ray will try to read the particle map from it. If it doesn't exist then the computed particle map will be saved to a file with the given name.; The default is: "", for not using a file.
"irradiance particles rebuild" on|off: Control re-computation of irradiance particles.; If enabled then mental ray will always re-compute the particle map. If disabled then an existing map will be re-used, like read from an existing file if specified, or taken from a previous frame of an animation. This can be useful to avoid flicker in animations, like for fly-throughs. Note, the global illumination might become wrong if objects are moving. Since the particle map is essentially view dependent it is possible that inaccuracies show up when the camera moves.; Default is on.

Image-Based Lighting

"environment lighting mode" "off"|"automatic"|"approximate"|"light": Enable the native IBL mode.; The native IBL rendering is enabled by setting this option to a value other than "off". The mode "light" targets accurate results and will converge to the correct solution, albeit slow when using traditional shaders with strong, sharp glossy components. On the other hand, materials employing BSDFs will work well in this mode. The "automatic" mode is the suggested way of working, by providing a reasonable compromise between speed and quality. Its internal implementation may change between versions of mental ray. Currently, it corresponds to "light" with additional usage of the environment lighting cache, to gain overall performance at the expense of final quality. The "approximate" mode is targetted at fast results but delivers a biased, physically inaccurate result. It is intended for interactive applications rather than final quality renderings, and can be tuned with special options. It implies the use of environment lighting cache and environment lighting shadow "solid".; The default value is "off".
"environment lighting cache" on|off: Controls acceleration of IBL environment lookup.; The environment is sampled and baked into data structures for accelerated lookup during rendering, see resolution. This setting determines if a regular texture is used, or a special cache providing optimized access. In the case of a texture, enabled with off, the usual texture lookup machinery is used, which includes standard filtering of the texels resulting in a smooth environment. If the cache is enabled with on, this filtering is not performed except for the directly visible environment. With extremely low environment lighting resolution settings, sharp texels may be visible in reflections. On the other hand, the cache will reduce noise. The impact will be more obvious with high contrast environments, low resolution, or scenes with mainly diffuse surfaces.; The default is off.
"environment lighting quality" quality_scalar: Control the quality of the IBL rendering.; This setting primarily affects the number of environment samples taken per shading point. The quality value typically ranges from 0.0 to 1.0 for lowest to highest quality. But even higher values are accepted to further improve the rendering results in extreme cases.; The default is 0.2.
"environment lighting resolution" resolution_int: Control resolution of IBL acceleration data.; The environment is sampled and baked into data structures for accelerated lookup during rendering. Higher resolution results in better quality but requires longer construction time and more memory. Lower resolution will lead to less detail like softer shadows and highlights even for strong hot spots in the environment. Note, that this setting is also relevant for iray.; The default is 512.
"environment lighting scale" r [ g b ]: Scale the contribution of illumination from the IBL environment.; The illumination coming from the environment is multiplied by this factor, or by the color if individual r g b components have been provided. The directly visible environment is not affected.; The default is 1.0.
"environment lighting shader samples" samples_int: Control quality of IBL acceleration data.; Specifies the number of samples to take per measurement in the pre-process. If the resolution is very low, this value can be used to increase the sampling quality of the environment to avoid losing lighting information by potential misses of small hot spots. Note, that higher values increase pre-processing time. This setting is also relevant for iray.; The default is 2.
"environment lighting shadow" "off"|"solid"|"transparent": Control shadows cast by IBL.; Shadows cast from IBL will be disabled if set to "off". Fast opaque shadows are generated in "solid" mode. Full shadowing, including calling shadow shaders, is enabled with "transparent".; The default is "transparent".
"environment lighting approximate split" samples_int: Fine-tune performance of approximate IBL.; For the "approximate" lighting mode, draws given number of additional samples from the environment internally. This can reduce color noise at the cost of biased results. Only values greater than 1 are recognized.; The default value is 4.
"environment lighting approximate split vis" rays_int: Fine-tune performance of approximate IBL.; For the "approximate" lighting mode, cast the given number of visibility rays per internal sample. This can reduces the visibility noise at the expense of increased ray tracing overhead.; The default value is 2.

Importance Sampling 3.13

"light importance sampling" on|off 3.13: Enable light importance sampling.; The value "on" enables light importance sampling across all lights in the scene. This feature is intended to accelerate sampling of physically plausible light sources, area lights, and emissive objects. mental ray handles incompatible and legacy light sources automatically. In addition, this enables global light sampling optimizations for scenes with very many light sources. If set to "off" then light importance sampling is disabled. User lights are excluded from importance sampling mechanism in all modes.; The default is "on". 3.13
"light importance sampling quality" quality [ quality_2 ] 3.13: Control the quality of light importance sampling.; This option takes one or two float numbers as arguments and uses those as multiplier(s) for the total number of samples generated for the set of lights. If two values are given, the first quality is taken for primary rays and the next quality_2 for secondary rays. If just one value is given, it is taken for both primary and secondary rays. Note, that the semantic of this option has changed compared to mental ray 3.11.; The default is 1.0.
"light importance sampling precomp" on|off 3.11: Enable the pre-compute mode for light importance sampling.; If enabled, the core does not execute the light shaders but uses precomputed light emission values instead. This mode assumes that lights are isotropic, i.e. emit with the same intensity in all directions. If the pre-computation phase detects that some of the lights are not isotropic, those lights are automatically excluded from the pre-computation and processed with the light shader calls - the light importance sampling itself still applies to those lights. For textured lights, enabling this option produces much smoother images in less time, at the expense of some possible loss of illumination details.; The default is off.
"light importance sampling resolution" resolution 3.12: Control the pre-sampling quality of area lights with light importance sampling.; Higher values lead to more detailed pre-sampling. The default is typically sufficient for most cases. If lights have a high-variance HDR texture attached this value may need to be raised.; The default is 1.0.
"multiple importance sampling" on|off 3.11: Enable multiple importance sampling.; The value "on" enables multiple importance sampling for BSDF-based materials used in conjunction with physically plausible lighting. If set to "off" then multiple importance sampling is disabled.; The default is "off".

iray Rendering Mode

"iray" on|off: Enable the iray rendering mode.; Once enabled mental ray starts the iray rendering engine to compute images. The iray rendering mode is able to utilize any CUDA capable device like NVIDIA GPUs to achieve superior performance, but it can also use any available CPU, either as a fallback without GPU contribution, or in hybrid mode working in cooperation with GPUs. This is controlled by the application through string options, see below. Most regular rendering options of mental ray are ignored except for few progressive stop criteria and options for environment lighting when baking into textures.; The default value is off.
"iray devices" devices_string: Select CUDA devices, or GPUs, for iray rendering.; The devices string specifies logical CUDA device identifiers, separated by spaces. For example, the string "0 1 4" will enforce to utilize only the CUDA devices 0, 1, and 4. Such a CUDA device identifier refers to a specific GPU. This allows to exclude individual GPUs in a multi-GPU setup from iray rendering. For example, it may be desirable to disable the primary graphics card in a computer but only use the high-performance compute extension. The empty string "" disables all CUDA devices for iray, thus turns off GPU-based iray rendering (but still rendering on CPU if not disabled).; The default is unspecified, which will enable all available CUDA devices.
"iray max path length" num_int: Control iray rendering quality by limiting the path tracing depth.; Using this option, the number of bounces of light travelling through the scene can be reduced. In other words, the maximum length of a light transport path can be limited. This may be useful to gain speed in interactive modes like navigation, at the expense of physical accuracy. For example, when set to 1 only light sources themselves become visible and reflections or refractions are disabled, with a value of 2 iray renders direct lighting only and primary reflections and refractions, a value of 3 includes one indirect bounce of light and secondary reflections and refractions, higher values consider more bounces accordingly.; The default is unspecified, targetting highest quality by the use of virtually unlimited, more precisely sufficiently high, path length.
"iray threads" num_int: Control number of CPUs, or CPU cores, for iray rendering.; Specifies the number of CPUs, or CPU cores, to be used for rendering with iray in addition to the enabled CUDA devices, or GPUs. This value is bound by the global number of threads set for mental ray, which typically defaults to the number of available CPUs or CPU cores on the machine, but may be further restricted by licensing. Higher numbers than the mental ray setting have no effect.; The default is unspecified, resulting in reasonable CPU contribution to maximize overall performance.

Frame Buffer Control

colorclip rgb|alpha|raw: Set global color clip mode for low-dynamic range color output.; This option determines how color and alpha values are clipped into a low-dynamic range [0,1] before writing to a non-floating point frame buffer or file. The rgb mode tries to retain the RGB values and just modifies alpha to be [max(R,G,B), 1]. The alpha mode keeps alpha intact, though clipped to [0,1] range, and adjusts RGB subsequently to [0,A] range. In raw mode, RGB and A values are just clipped to the range [0,1] independently of each other. In all modes, the RGB components are modified manipulated according to the desaturate option. The rgb and alpha modes ensure that the resulting color is a valid pre-multiplied color. The rgb mode should be used if the alpha channel is considered less important than preserving the RGB color and intensity. The alpha mode is intended for alpha compositing, where the alpha channel is more important than the absolute color value to preserve correct transparencies. The raw mode should be used if the color validation is performed elsewhere, like in custom shaders, and final color values should be passed through mental ray basically unaffected. This mode also forces the global premultiply option to on, to ensure least impact on the color pipeline by mental ray. On the other hand, care should be taken because shaders might receive illegal or unexpected colors (colors that cannot be composited in standard ways).; The default is rgb.; Note Color clipping is applied to the color averaged over time if motion blur is rendered.
desaturate on|off: Control color desaturation for low-dynamic range color output.; If a color is output to a low-dynamic range frame buffer, one that can not store values in floating-point precision, then its RGB components outside the range [0,max] need to be brought into this range (with max determined by the colorclip mode). If this option is turned off, the values of the individual components are simply clipped into range. If switched on, mental ray tries to maintain brightness by moving the color towards the grayscale axis of the color cube, until the RGB components come into the valid range.; The default is off.
premultiply on|off: Control storage of color with associated alpha for low-dynamic range color output.; Pre-multiplication means that colors are stored with the associated alpha value multiplied, like (R*A, G*A, B*A, A). For example, the white color with 10% opacity is stored as (0.1, 0.1, 0.1, 0.1) rather than (1, 1, 1, 0.1). This is a common method in computer graphics to represent low-dynamic range colors with transparency, to ease alpha blending compositing operations. mental ray is using this method internally and in its standard shaders. One implication is that R, G, and B can never exceed A, if A is less than 1.0. This is normally enforced only at the time when storing color values into frame buffers. If this option is set to off then colors are stored unpre-multiplied into frame buffers and files. That is achieved by applying a reverse operation to the pre-multiplied color values upon writing.; The default is on.; This option is ignored if colorclip is set to raw.; Note mental ray internally assumes to work with pre-multiplied colors. Shaders are also expected to return color values in this form. Since this is done with floating-point values there is no precision penalty. But,if shaders do not follow these rules when returning color values to mental ray then turning this option to off may lead to unexpected results, caused by the failure of the reverse multiplication in such cases.
dither on|off: Control color randomization to enhance low-dynamic range color output.; Setting this option to on intentionally applies tiny randomized variations to color values. Using frame buffers with lower precision like 8 or 16 bits per pixel, as supported by most popular picture file formats, can cause visible banding when the original floating-point color values get quantized to the lower precision values for storage. Dithering mitigates the problem by introducing noise into the pixel such that the round-off errors are evened out. Dithering is applied when writing color values to a frame buffer with limited precision, all color frame buffer data formats except HDR, float, and half-float.; The default is off.; Note Dithering can cause run-length encoded picture files to be larger than without dithering.
gamma gamma_factor: Global gamma correction factor which is applied to all rendered and quantized color pixels (ie. if the frame buffer is not floating-point or RGBE) to compensate for output devices with a nonlinear color response. All quantized R, G, B, and alpha component values are raised to 1 ⁄ gamma factor. The default gamma factor is 1.0, which turns global gamma correction off. Note, for historical reasons, the reverse correction is applied to all quantized input textures as well, i.e. all non-floating-point texture images. This can be avoided with the help of color profiles like the color profile option which offer more selective gamma correction capabilities.
frame buffer n ["type"]: Deprecated This option is supported for backwards compatibility but replaced by frame buffers.
Define or delete user-defined frame buffer n. Any number of user frame buffers is supported, numbered 0 through n. The frame buffer type type may be any standard image type allowed in an output statement, such as rgba or z. If the type is prefixed with a "+" sign, samples are interpolated; if prefixed with a " -" sign, it is padded. Padding is the default for all types. For example, +rgba_fp is an interpolated floating-point color frame buffer. If the type is omitted or an empty type string ("") is given then a type is determined automatically by mental ray (it is recommended to specify an empty type string instead of omitting the type since a following string option could otherwise be confused with a type specifier). After a frame buffer is defined, it may be used as the type name fb n in output statements in cameras. The frame buffer is created in memory during rendering only if it is referenced by at least one output statement. Note, that mental ray will automatically generate and assign names "fbN" to these buffers according to the buffer index N.
"rast useopacity" on|off: When using the rasterizer then enabling this setting enforces the transparency/opacity compositing to be performed on all color user frame buffers (i.e. non-primary color buffers) regardless of the individual setting on the frame buffer. By default, only the primary color frame buffer and explicitly marked user buffers are considered for rasterizer compositing. This option may be used in combination with the old user frame buffer interface.

Scene Geometry

camera space: All geometry is expected to be defined in camera space. Camera space assumes that the camera is at the coordinate origin (0, 0, 0) and looks down the negative Z axis. This means that geometry will typically have negative Z coordinates. This is the default. In camera space mode, instance transformations have no effect. This mode exists for backwards compatibility only and is not recommended. It is still the default, again for backwards compatibility reasons. This may change in the future.
object space: All geometry is expected to be defined in object space. Each object, light, and camera has its own coordinate space, typically but not necessarily with the coordinate origin (0, 0, 0) in the center of the object. The object coordinate space is positioned and oriented in world space with the instance transformation matrix (every object, light, and camera requires an instance). Object space allows multiple instancing where the object is placed in the scene more than once using multiple instance entities.

Contours

contour store shader: If the camera contains a contour output statement, contour rendering is enabled and a contour store shader must be defined. This function stores information about the future contour edge, such as color, depth, normal, and other local information that is later used by the contour contrast shader to decide where the contour lines should be drawn, and by contour shaders to decide which colors and thicknesses the contours should have. Shader lists are not allowed here.
contour contrast shader: If contour rendering is enabled, a contour contrast shader must also be defined. It decides where the contour lines should be drawn based on values stored by contour store shaders. The contrast shader compares two such value sets at a time. Shader lists are not allowed here.

State Shaders

state shader: State shaders may be used to manipulate the state of mental ray before regular shaders are called. State shaders are invoked on four occasions: right after a shader state has been created, right before the state gets destroyed, before a sample is taken, and after the sample has been taken. These four cases may be distinguished by constants passed to the shader from mental ray. State shaders are defined in the options block of the scene.
state [ [ shader [ , shader … ]] ]: List of state shaders that are called sequentially in the given order. Typically required when several shader packages used in a scene need to provide their own state shader to work. The empty list removes all state shaders from the scene.

Diagnostic Modes

diagnostic grid off|object|world|camera S: Draws a colored grid on all objects in the scene visualizing the coordinate space given. The distance between grid lines is S units. This is useful to estimate the size and distances between objects and to visualize the object space of objects. The off argument turns this mode off.
diagnostic bsp off|depth|size: This mode visualizes the depth and leaf size of the BSP tree used for ray tracing acceleration. This works only if ray tracing is enabled ( trace on) and the regular BSP algorithm is used ( acceleration bsp). (It does not work for large bsp.) Both modes are the default. The image is scaled so that black means zero depth or size, and red or white means highest depth or size encountered (the absolute values are shown in the message output if the verbosity is 4 or higher). BSP diagnostics can be used to check how often the maximum BSP depth and the maximum leaf size were reached, as specified with bsp depth and bsp size statements. If this happens frequently, the parameters should be increased.
diagnostic photon off|density|irradiance N: When using photon maps, this mode replaces all material shaders in a scene with an internal shader that produces a false-color rendering of photon density, or the average of the red, green, and blue irradiance components. Photon density is the number of photons per unit surface area. N is the density (or irradiance) that is assigned to 100%, or red. The colors are, from 0% to 100%: blue, cyan, green, yellow, and red. Higher values fade to white. N can be given as zero in which case the appropriate maximum is automatically found. This mode is useful when tuning the number of photons in a photon map and setting the various accuracy options, since the density (or irradiance) is estimated using those settings. The off argument turns this mode off.
diagnostic samples on|off: This mode replaces the rendered image with a grayscale image showing the number of image samples made for each pixel. A black pixel has had no samples, whereas a white pixel has had the maximum amount as specified with the -samples option. In addition, a red grid is drawn indicating task boundaries. Samples that lie exactly on pixel boundaries are considered to belong to the lower and/or left pixel. This mode is useful when tuning the samples and the contrast options for optimal effect.
diagnostic finalgather on|off: This mode shows final gathering points, as green dots for initial raster-space final gathering points, blue dots for final gather points from per-object finalgather map files and red dots for render-time final gathering points.

Miscellaneous

face front|back|both: The front side of a geometric object in the scene is defined to be the side its normal vector points away from. By specifying that only front-facing triangles are to be rendered, speed can be improved because fewer triangles need to be tested for a ray. This works well unless there are objects whose back side is seen by refracted or reflected rays - with face front, the back side would not be visible. The default is face both, and works best if volume effects are used, which usually depend on closed volumes.
task size size_int: This option specifies the size of the image tasks during rendering. Smaller task sizes are convenient for previewing, but also increase the overall rendering time. This option can also be used in order to optimize load balancing for parallel rendering. If the task_size is not specified, an appropriate default value is used. Note that very small task sizes can cause the scanline rendering algorithm to perform poorly and in such cases it may be desirable to turn it off. See scanline above.
inheritance " function_name ": To use parameter inheritance, a user-provided inheritance function must be specified. The function_name is the name of a C function linked to mental ray using a link command. No user-defined parameters are passed. The inheritance function is called for every pair of instances of which one is the parent (one level higher up in the scene DAG) of the other. The inheritance function must compute a set of inherited parameters from the parameters stored in these two instances. It is called even for the instances that contain no parameters and for top-level instances; in this case the corresponding parameter argument pointer is zero. Inheritance shaders are not regular shaders; they are usually written by translator writers who need to emulate the inheritance methods used by the language to be translated.
traversal " function_name ": The traversal statement is similar to the inheritance statement above, but installs function_name as a traversal function instead of an inheritance function. Traversal functions accessible through the options have more control over the inheritance process. It is not possible to have both an inheritance and a traversal function.
luminance weight ntsc: This statement defines the RGB component weights used by the mi_luminance shader API function as (0.299, 0.587, 0.114), as defined by the NTSC standard.
luminance weight r g b: This statement defines the RGB component weights used by the mi_luminance shader API function as ( r g b).
colorprofile "profile_name": This statement causes the use of color spaces. Specifically, the named color profile defines the rendering color space. The profile name may be one of mental rays already pre-defined profile names, or it may refer to a profile defined earlier within a colorprofile block.