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 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.

Sampling Quality

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.
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).

Unified Sampling 3.9

"unified sampling" on|off 3.9: Turn unified sampling on or off.; Once enabled, the following 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 ignored.; The default is off.
"samples max" num_scalar 3.9: 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 3.9: 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] 3.9: 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 3.9: Set the sampling error threshold.; If set to values greater than 0 areas with sample errors which fall below that threshold won't be considered for more sampling.; The default is 0.0.

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 3.8: 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 3.8: 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 3.8: 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 3.8: 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. statements.; 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 other's 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 3.8: 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

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

globillum on|off: Global illumination is turned on or off. The default is 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.
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.

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 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 points"P_int: In the automatic and multiframe finalgather modes, the number of finalgather points used for interpolation of the indirect illumination.
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 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 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 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.
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 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 passes num_int: The final gathering pre-computation is performed in progressive manner with 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.

Ambient Occlusion

"ambient occlusion" on|off: Can be used to disable ambient occlusion support completely. Default is on. Actual computation is performed on demand of shaders only.
"ambient occlusion rays"nrays_int: The number of ambient occlusion rays used for computation of each ambient occlusion value. Can be overridden in shaders. The default is 256.
"ambient occlusion cache" on|off: Control creation of the ambient occlusion cache. Default is off. 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.
"ambient occlusion cache density"density: The upper bound to 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.

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, which means that 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: If enabled, the irradiance particles are used to simulate indirect lighting, disabling global illumination photons if they were turned on. If final gathering is enabled this setting is ignored. The default value is off.
"irradiance particles rays"rays_int: Controls the number of rays to shoot while estimating the irradiance. The minimum is 2. The default is 256.
"irradiance particles indirect passes"num_int: The number of possible passes of 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 irradiance particles will have 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 ]: This is the global scale factor for the intensity 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 and B at once, or as three separate values for individual control. The default is 1.0.
"irradiance particles interpolate"num_int | "command": This option is used to control the use of interpolation, and it can be either a numeric value or a string: 0 - no interpolation, 1 - interpolate always, 2 - interpolate only for secondary rays (no interpolation for eye rays but interpolation for reflections, refractions, etc). Alternatively, it can be "never", "always" or "secondary". Default: 1/"always".
"irradiance particles interppoints"num_int: The number of points to use for the 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 ]: The scaling factor for the irradiance contributed by 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 could actually be further scaled if the user specifies a global scaling factor with the "irradiance particle scale" string option: 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: The number of rays used for the computation of irradiance coming from the environment map. 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 outside scenes, it should work fine with a smaller number of rays. The default is taken from to actual value of "irradiance particles rays".
"irradiance particles file" "filename": If the file with 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: no file.
"irradiance particles rebuild" on|off: If enabled then mental ray will 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" 3.8: 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 3.8: 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 3.8: 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 ] 3.8: 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 3.8: 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 3.8: 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 3.8: 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.

iray Rendering Mode 3.8

"iray" on|off 3.8: 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 3.8: 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 3.8: 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 3.8: 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: This option controls how colors are clipped into a valid range [0,1] before being written to a non-floating point frame buffer or file. The rgb mode is the default. In this mode, RGB is first clipped to [0,1] and alpha subsequently to [max(R, G, B), 1]. In alpha mode, alpha is first clipped to [0,1] and RGB subsequently to [0, A]. In raw mode, RGB and A are both clipped to [0,1] independently of each other. In all modes, the RGB components are clipped as specified by the desaturate option. The rgb and alpha modes ensure that the resulting color is a valid premultiplied color. rgb should be used if the alpha channel is considered less important than preserving the RGB color and intensity. alpha mode is intended for alpha compositing, where the alpha channel is more important than the absolute color value to preserve correct transparencies. raw mode should only be used if no layering based on alpha is going to take place. This mode also forces the premultiply mode to on. It should be used with care because shaders might receive "illegal" colors (colors that cannot be composited in standard ways). Since mental ray 3.5, color clipping is applied to the color averaged over the time if motion blur is rendered.
desaturate on|off: If a color is output to a frame buffer that does not have 32-bit (floating-point) precision, and its RGB components are outside the range [0,max], mental ray will clip the color to this legal range. If desaturation is turned off, the individual components are simply clipped into range. Otherwise, mental ray tries to maintain the brightness of the color by moving it towards the grayscale axis of the color cube, until the RGB components are in the legal range. max is determined by the colorclip mode. Desaturation is turned off by default.
premultiply on|off: Premultiplication means that colors are stored with alpha multiplied to R, G, and B. For example, white at 10% opacity is not stored as (1, 1, 1, 0.1) but as (0.1, 0.1, 0.1, 0.1). This is the standard method in computer graphics to represent colors; mental ray always uses it internally and in all shaders. One implication is that R, G, and B can never exceed A if A is less than 1.0. mental ray normally enforces this when storing color values into frame buffers. The premultiply off option instructs mental ray to always store colors unpremultiplied into frame buffers and files. It does this by undoing the internally applied premultiplication. Note, that mental ray internally always works with premultiplied colors to present a uniform interface to shaders; since this is done with floating-point values there is no precision penalty.; This option is ignored if the colorclip raw mode is in effect.
dither on|off: Color values in mental ray can be stored in frame buffers of different precision, like with 8, 16, or 32 bits per color component. Using 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 calculated by the material shader are quantized to the low precision values for storage. Dithering mitigates the problem by introducing noise into the pixel such that the round-off errors are evened out. Note that this can cause run-length encoded picture files to be larger than without dithering. Dithering is applied when writing color values to a frame buffer with limited precision. It is not applied to HDR, float, and half-float color frame buffers.; Dithering is turned off by default.
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.