Options

String Options3.5
Sampling Quality
Hardware Rendering
Tessellation Quality
Motion Blur
Trace Depth
Shadows
Rendering Algorithms
Feature Disabling
Caustics
Global Illumination
Final Gathering
Frame Buffer Control
Scene Geometry
Contours
State Shaders
Diagnostic Modes
Miscellaneous

Options

    options "name"  
        option_statements  
    end options

Options blocks contain rendering modes. An options element must be specified to render a scene. There is a variety of option_statements that can be listed in the options. Most of them can be overridden with an appropriate command-line option; see appendix cmdline.

The following option_statements are supported:

String Options3.5

Up to version 3.4, options are hardcoded in the .mi syntax and data structure in the programming interface. New options are implemented as arbitrary name - value pairs, where the name of the option is an arbitrary string, and the value can be a boolean, string, integer, float, 3 floats, or 4 floats:

  "name" off | on
  "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, missspelled options not known by mental ray are ignored.

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

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

These string options provide a new, 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 specify options which are not known by mental ray, they will be passed through by mental ray and could for example be accessed by shaders using the C++ shader interface extensions.

The individual string options known by mental ray are documented below with all other options:

Sampling Quality

contrast r g b [ a]

The contrast controls oversampling. If neighboring samples differ by more than the color r, g, b, a, supersampling is done as specified by the sampling parameters (see below). Default for a is the average of r, g, and b. The recursive supersampling algorithm controlled by samples modifies the contrast 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. The default is 0.1 0.1 0.1 0.1. This is the primary means of image quality control. Typically values are 0.1 for r, g, b, and a. 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. r, g, b, a 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. If the a value is missing, it is set to the average of r, g, b. Note that for high-quality rendering, the samples parameters must be adjusted. The rasterizer does not use the contrast or samples settings.

time contrast r g b [ a]

The time contrast controls temporal supersampling for motion blurred scenes. The number of temporal samples is approximately proportional to the inverse of the time contrast value. Default for a is the average of r, g, and b. 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 antialiasing. The default is 0.2 0.2 0.2 0.2; 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. Also see the scanline rapid mode for an alternative high-speed motion blurring algorithm.

samples [ min_int ] max_int

This statement determines the minimum and maximum sample rate. Each pixel is sampled at least 2^2min times and at most 2^2max times 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). min defaults to -2, which means that at least one sample per 1x1 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. The defaults for min and max are -2 and 0, respectively. 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 1 for mental ray 2.0, or at least -1 0 for mental ray 2.1 or later. mental ray 3.0 enables jittering by default, unless max is less than 1. The rasterizer does not use this setting.

samples min_int max_int defmin_int defmax_int^3.1

mental ray 3.1.2 accepts two optional extra parameters that set the default object sample limits. In mental ray 3.1.2, 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, 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 latter two are markers for "no further restrictions" because they are outside the -2 0 range.

samples collect num_int

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 value for num is 4, which yields 16 samples per pixel.

shading samples num_scalar

Shading in the rasterizer is controlled by the shading samples setting. After geometry has been tesselated according to the geometry approximation settings, it is further subdivided by the rasterizer into shading samples. the shading samples setting controls the number of shading calls per pixel. the default value is 1.0.

samples motion num_int

Determines at how many points in time a moving object is sampled in rasterizer mode. The default is 1, which 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.

filter box|triangle|gauss|mitchell|lanczos [width [height]]

The filter statement specifies how multiple samples are to be combined into a single pixel value. The filter defaults to a box filter of width and height 1.0, which is the fastest of the filters. 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 (mental ray 2.0: 1 1 or greater). Otherwise a warning will be printed and the filter statement ignored.

filter clip mitchell|lanczos [width [height]]^3.1

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

The jittering factor introduces systematic variations into 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 default in mental ray 2.x, and on by default in mental ray 3.0 if the maximum sampling is at least 1 (at lower sampling densities jittering introduces artifacts). Jittering is turned off by specifying a jitter of 0.0. To turn jittering on, use a jitter value of 1.0. In mental ray 2.1, jittering works best in ray tracing mode; in mental ray 3.0 it works equally well with ray tracing and scanline modes.

Hardware Rendering

hardware off|on|all -

Specify which objects should be rendered with hardware rendering: off disables hardware rendering (this is the default), on uses hardware rendering for all materials that specify a hardware shader, and all uses hardware rendering for all objects and tries to find hardware substitutes for materials that do not specify an explicit hardware shader. The most useful mode is all. Note that this option only selects which objects are eligible for hardware rendering, but mental ray may still fall back on software rendering for objects for which no appropriate hardware shaders are available. This is controlled separately by the following options.

hardware cg|native|fast* - [ force ]

This option controls how hardware shaders are selected for an object that is eligible for hardware rendering, as specified by the previous option. mental ray will try all approaches allowed by this option in turn:

cg: means that mental ray will first look for shaders implemented in NVIDIA's Cg 1.2 shader programming language. This is the default.
native: looks for shaders implemented in the OpenGL 2.0 native shader programming language, which is less powerful than Cg.
fast: uses hardcoded OpenGL materials that do not involve programmable shaders at all. This is limited to simple Gouraud models.
force: specifies that the search stops here, and objects that cannot use any of the above methods use a simple gray default material. If force is not specified, mental ray will fall back on software rendering for the object.

The hardware options can be combined. For example, -hardware all cg native fast force - will render all objects with the best available hardware shading method but never with software; this is useful for fast preview rendering. The option -hardware all cg native - is best for quality rendering, and so on.

Tessellation Quality

approximate technique [ min_int max_int ] all: 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: 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 3.1 and higher offer 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: 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

This statement controls motion blurring. The camera shutter opens at time delay^3.1 and closes at time shutter. The defaults are both 0.0, disabling any motion blur by default. If shutter is equal to delay, motion blurring is disabled; if shutter is greater than delay, motion blurring is enabled. The normal range is (0, 1), which uses the full length of the motion vectors or motion vector paths^3.1. It can be useful to set delay^3.1 and shutter both to 0.5, which disables motion blurring but renders with an offset of one half frame, which allows bidirectional post-blurring in an output shader. Also see the scanline rapid mode for high-speed motion blurring.

motion on|off

Normally the shutter statement controls whether motion blurring is enabled, and turns it on if there is a nonzero shutter interval. The motion statement overrides this and turns motion blurring on or off explicitly. For example, it is useful to define a zero shutter interval and then (order is important) turn motion blurring on, so that shaders get a correct state->motion vector. If motion blurring 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 explicitely in order to render with motion blur. Here is a description of the affect of a few typical settings:

shutter 1.0: render with motion blur
motion on: do not render motion blur but generate motion vectors
shutter 0.0 motion on: same as above, do not render motion blur but generate motion vectors
shutter 1.0 motion off: should not be used
shutter 0.5 0.5: do not render motion blur, but render at half the motion vector offset

In order to disable motion blur on the command line, the option -shutter 0 should be used (-motion off may not always work reliably without side effects).

motion steps num^3.1

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. The default is 1. 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.

Trace Depth

trace depth reflect_int [ refract_int [ sum_int ]]: 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. The defaults are 2 2 4. Note that custom shaders may override these values.

Shadows

shadow off: This statement disables all shadows, and overrides instance and object shadow flags.
shadow on: Simple shadows are enabled. This is the most efficient and least flexible of the three 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: This shadow mode enables shadow sorting. It is similar to the preceding 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: Like with shadow sort, 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|opengl|detail: This flag turns shadow maps on or off for the entire render. Shadowmap parameters are specified for each light source. The default is off because standard shadowmaps, while often significantly faster, always assume opaque objects. The opengl mode causes mental ray to use OpenGL acceleration if available when rendering standard shadow maps. The same limitations apply as mentioned with the scanline option. Additionally, because of the difference of the rendering algorithm, OpenGL shadowmaps contain slightly different information from those generated with the regular algorithm, and the resulting shadows may look different. In particular, soft areas of shadows tend to be smaller and some areas may incorrectly be determined to be not in shadow. When OpenGL rendering of shadow maps is enabled, only the master host will participate, since the computation cost of the map is so small that the network transfer costs could not be recovered. mental ray 3.3 also supports detail shadowmaps that call shadow shaders attached to materials, and store the sequence of transparent shadow-casting objects per shadowmap pixel. For this reason they tend to be slower than standard shadowmaps. Detail shadowmaps behave like a combination of standard shadowmaps and raytraced shadows. Setting shadowmap detail in the options block will compute all enabled shadow maps as detail shadow maps.
shadowmap only: mental ray will render only shadow maps but not the color image. Only shadow maps with shadowmap file statements will be rendered and saved. This mode is turned off with shadowmap off.
shadowmap rebuild on|off: Determines whether all shadow maps should be recomputed. If this option is off (the default) 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 multipass rendering, so that objects from another render pass can still cast shadows on objects in the current pass.
shadowmap motion on|off: 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. The default is on. 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.
shadowmap bias bias: 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.

Rendering Algorithms

trace on|off: 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. Ray tracing is turned on by default. If off, this flag overrides instance and object trace flags.
scanline on|off|rapid|opengl: This statement allows turning off the scanline rendering algorithm. By default, mental ray tries to use a scanline algorithm for straight rays from the pinhole camera, such as primary rays. In most cases this gives better performance than pure ray tracing. Turning scanline off forces mental ray to rely entirely on ray tracing. This will generally slow down rendering but in some cases, for example when the task size is very small, the overhead of initializing the scanline algorithm may outweigh its benefit and turning it off can result in an improvement in speed. The rasterizer mode uses a different scanline algorithm based on sample caching. It is usually slightly faster than regular sampling for static scenes, and substantially faster for motion-blurred scenes. Where regular motion blurring can reduce performance by a factor of up to 5, rapid motion blurring adds only about 25%-100% to the rendering time. Sample caching does introduce artifacts; in particular, moving mirrors and glass panes drag the reflection or refraction with them. The performance advantage is compelling, however. The opengl option will cause mental ray to use OpenGL hardware if present to further accelerate rendering. If possible, the master host will use OpenGL to generate acceleration data that the scanline algorithm then uses for intersection testing. Also see task size below.
acceleration bsp: Selects the binary space partitioning (BSP) ray tracing algorithm. This algorithm is often, but not always, faster. It is controlled by the bsp size and bsp depth statements. The BSP algorithm is the default.
acceleration grid: In mental ray 2.1, selects the static grid rendering algorithm. In mental ray 3.0, grid acceleration is not supported. In mental ray 3.1, selects the hierarchical voxel grid algorithm. Grids provide faster preprocessing especially on multiprocessor systems. Memory usage is more conservative and much easier to control than with the BSP algorithm. Speed is comparable to BSP but more scene-dependent, especially in mental ray 2.1.
acceleration large bsp: This is an alternative to regular bsp mode. All parameters are exactly the same, but a multi-level BSP tree is used. This slows down ray tracing by about 15-20%, 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. (Note that final gathering coherence can be improved with the finalgather falloff option).
bsp size size_int: The maximum number of primitives in a leaf of the BSP tree. mental ray will subdivide BSP voxels containing more triangles, unless the maximum BSP depth (see next statement) is exhausted. This statement is used only if binary space partitioning is enabled. It has no effect on the other algorithms. 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. This statement is used only if binary space partitioning is enabled. Larger tree depths reduce rendering time but increase memory consumption, and also slightly increase preprocessing time. The default is 40. 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" [Driemeyer 01] discusses how to choose good parameters in detail.
bsp shadow on|off^3.1: mental ray 3.1.2 and later support a separate shadow BSP tree that accelerates raytraced shadows. 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 ]: If the hierarchical grid algorithm^3.1 is used, this option sets the number of grid voxels in the X, Y, and Z dimensions. If only one number is given, it is used for all three dimensions. The default is 0 0 0, which selects a default computed at runtime. mental ray 3.1 can use subgrids to subdivide voxels with many triangles, so that scenes with local dense concentrations do not need to increase the global number of voxels just to capture the regions of high density. Incidentally, a grid resolution of 2 2 2 lets the grid algorithm degenerate to an octree algorithm.
grid depth depth_int^3.1: If the hierarchical grid algorithm^3.1 is used, this option sets the number of recursion levels. If a voxel of a grid contains too much detail, it is subdivided by a subgrid for that voxel, which adds another level. The default is 2 for two levels (subdivided voxels cannot be subdivided again).
grid size size_int^3.1: If the hierarchical grid algorithm^3.1 is used, this option sets the maximum number of triangles in a grid voxel. If there are more, and the grid depth permits it, the voxel is subdivided into a subgrid. Note that size_int must really be an integer; a floating-point value will cause the statement to be ignored, and a warning to be printed.

Feature Disabling

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: Normally, mental ray presamples displacement-mapped geometry to find better bounding boxes of object fragments. This increases the startup time when rendering the displaced object, but rendering itself is much faster. The overall benefit can reach a performance factor of three. However, for quick previews it is sometimes desirable to get the first pixels as quickly as possible, regardless of the time it takes to complete the image; so this option allows disabling presampling. The default is on.
output on|off: Ignore all output shaders if set to off. The default is on. File output statements are 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.
autovolume on|off: Autovolume mode enables 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.
photon autovolume on|off: 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.
pass on|off^3.1: Multipass rendering^3.1 performs operation on sample pass files. This option allows disabling all pass statements in the camera. See page renderpass for more details about multipass rendering.
lightmap on|off|only^3.4: This mode enables rendering of lightmaps. By default, lightmaps are enabled. If this option is set to only, only the lightmaps but not the camera images are rendered.

Caustics

caustic on|off: Caustics are turned on or off. They are off by default. Caustics are lighting effects caused by specular focusing of light rays, such as the irregular light patterns on the floor of a swimming pool. Note that caustics 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 off, this flag overrides instance and object caustics flags.
caustic mode: Global caustic cast an receive bits. This bits force enabling of corresponded bits on all instances. The default value is 3, meaning that caustic cast and receive flags on instances and objects are automatically enabled and the disable bits have no effect.
caustic accuracy N [R]: 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. The default for N is 100. If R is zero, a scene-size dependent radius is used instead. This is the default.
caustic filter box|cone [ filter_const]: 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.
"caustic merge" distance3.5: If this option is set to a positive value, the caustic photons within the specified distance in world space are merged. This can decrease the size of the caustic photon map dramatically.
caustic scale r g b [ a]^3.4: Caustics are multiplied by the specified color. Factors greater than 1 increase the brightness of the effect.
photon trace depth reflect_int [ refract_int [ sum_int ]]: 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.
photonmap file " filename ": Tells mental ray to use the file filename for the photon map. If the photon map file does not exist, it is created and the photon map is saved. If it exists, it is loaded and used without computing a new photon map.
photonmap rebuild on|off: 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: If this option is set, only the photon maps but not the camera images are rendered. 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 glbillum 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" distance3.5: 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]^3.4: 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" distance3.5: 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]3.5: 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, and 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 3.3 allow rendering only the finalgather map, and skipping rendering of the images with the only option.
"finalgather mode" mode3.5: Select one of the four 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. See also the description in the functionality chapter.
"finalgather points" P_int 3.5: 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^3.1 is specified, in which case the values are in pixels. mental ray 3.4 works better and faster with smaller numbers of rays; 500 is a good value. It will be slower than 3.3 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 [ " name ", " name ", ... ]: mental ray 3.3 and later allow attaching a list of finalgather file names instead of 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 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^3.4_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^3.4: 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]3.4: 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]3.5: The irradiance part obtained from secondary bounce finalgather is multiplied by the specified color. Factors greater than 1 increase the brightness of the effect.

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). In 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. (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: mental ray supports 8, 16, or 32 bits per color component. In some cases, 8 bits per pixel, as supported by all popular picture file formats, can cause visible banding when the floating-point color values calculated by the material shader are quantized to the 8-bit values used in the picture file. 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 turned off by default.
gamma gamma_factor: Gamma correction can be applied to rendered and quantized (ie. not if the frame buffer is floating-point or RGBE) color pixels 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 gamma correction off. The reverse correction is applied to all quantized texture images.
frame buffer n [ " type "]: Define or delete user-defined frame buffer n. Up to eight user frame buffers are supported, numbered 0 through 7. 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 fb n, with n in the range 0...7, 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. The limitation to eight frame buffers has been removed in mental ray 3.4 and later.

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 shader: State shaders may be used to manipulate the state of mental ray before a shader is called. State shaders are invoked on four occations: When a shader state is created or 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. (A shader state is a data structure that is passed to all shader, and provides general information about mental ray and the current intersection, and can be used top communicate between shaders.) State shaders are defined in the options block of 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^3.1: This mode shows final gathering points, as green dots for initial raster-space final gathering points, blue dots^3.4 for final gathering 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 "^3.1: 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 were introduced in mental ray 3.1.2; they 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.