Options

The option data structure pointed to by state->options has the following format, split here over three tables due to its size. The option structure may never be written to by shaders.

type	name	content
`int`	`min_samples`	minimum sampling level
`int`	`max_samples`	maximum sampling level
`miColor`	`contrast`	sampling contrast
`miColor`	`time_contrast`	temporal sampling contrast
`miBoolean`	`samplelock`	noise animation locking on/off
`char`	`render_space`	coordinate space: 'c' for camera space, 'o' for object space
`int`	`task_size`	rendered image rectangle size
`miCBoolean`	`pixel_preview`	selective pixel sampling mode
`miCBoolean`	`task_preview`	selective task sampling mode
`miCBoolean`	`visible_lights`	have visible area lights in the scene
`miBoolean`	`strips`	tessellation to strips and fans
`miCBoolean`	`no_lens`	disable lens shaders
`miCBoolean`	`no_volume`	disable volume shaders
`miCBoolean`	`no_geometry`	disable geometry shaders
`miCBoolean`	`no_displace`	disable displace shaders
`miUint1`	`no_output`	disable output shaders
`miCBoolean`	`no_merge`	disable edge merging
`miCBoolean`	`no_hair`	disable hair rendering
`miCBoolean`	`no_pass`	disable sample passes
`miCBoolean`	`no_predisplace`	disable displacement shader pre-sampling
`miTag`	`userdata`	optional user data blocks
`miApprox`	`approx`	approximation override
`miApprox`	`approx_displace`	displacement approximation override
`miTag`	`contour_contrast`	contour contrast shader
`miTag`	`contour_store`	contour store shader
`miTag`	`inh_funcdecl`	inheritance/traversal declaration
`miUint1`	`diagnostic_mode`	`miSCENE_DIAG_` flag bitmap
`float`	`diag_photon_density`	density for diagnostic photon mode
`float`	`diag_grid_size`	grid size for diagnostic grid mode
`miBoolean`	`desaturate`	fade to white, no clipping
`miBoolean`	`dither`	enable frame buffer dithering
`miBoolean`	`nopremult`	disable premultiplication
`int`	`colorclip`	color clipping modes
`float`	`gamma`	frame buffer gamma value, 1 for none
`miColor`	`luminance_weight`	weights to calculate luminance
`int`	`no_images`	highest frame buffer index plus 1
`miTag`	`images_info`	frame buffer information
`miTag`	`fb_dir`	frame buffer directory

Rendering algorithm options:

type	name	content
`miBoolean`	`trace`	ray tracing turned on?
`miBoolean`	`scanline`	scanline mode turned on?
`miBoolean`	`motion`	motion blur turned on?
`float`	`shutter_delay`	shutter open time for motion blur
`float`	`shutter`	shutter close time for motion blur
`miCBoolean`	`autovolume`	automatic volume management
`char`	`filter`	nonlocal sampling filter: 'b' - box, 't' - triangle, 'g' - Gauss, 'm' - Mitchell, or 'l' - Lanczos
`float`	`filter_size_x`	filter size in x
`float`	`filter_size_y`	filter size in y
`int`	`reflection_depth`	max reflection trace depth
`int`	`refraction_depth`	max refraction trace depth
`int`	`trace_depth`	max combined trace depth
`char`	`face`	'f' - front, 'b' - back, or 'a' - both faces
`char`	`field`	'o' - odd or 'e' - even fields, 0 - frames
`float`	`jitter`	sample jittering: 0 - off, 1 - on
`char`	`shadow`	0 - off, 1 - normal, 's' - segmented, 'l' - sorted
`char`	`use_shadow_maps`	use shadow maps for rendering
`miCBoolean`	`rendering_shadow_maps`	currently working on a shadow map rectangle
`char`	`recompute_shadow_maps`	'n' for reuse, 'y' for rebuild
`miCBoolean`	`shadow_map_motion`	motion blurred shadowmaps
`char`	`acceleration`	ray tracing algorithm: 'b' - BSP, 'n' - BSP2, 'g' - grid
`short`	`grid_res[3]`	grid resolution in world space: X, Y, Z
`short`	`grid_max_depth`	maximum grid nesting
`short`	`grid_max_size`	maximum grid leaf size
`float`	`grid_max_size`	grid resolution correction
`int`	`space_max_size`	maximum BSP leaf size
`int`	`space_max_depth`	maximum BSP nesting
`int`	`space_max_mem`	maximum bsp memory in MB, 0 for unlimited

Global illumination options:

type	name	content
`int`	`photon_reflection_depth`	max photon reflection trace depth
`int`	`photon_refraction_depth`	max photon refraction trace depth
`int`	`photon_trace_depth`	max combined photon trace depth
`miTag`	`photonmap_file`	photon map file name
`miTag`	`finalgather_file`	finalgather map file name
`miBoolean`	`photonmap_rebuild`	rebuild photon map, don't reuse
`miCBoolean`	`finalgather_rebuild`	rebuild final gather map
`miBoolean`	`caustic`	caustics on/off
`int`	`caustic_accuracy`	number of caustic photons in estimate
`float`	`caustic_radius`	maximum distance for caustic photons in estimate
`float`	`caustic_filter_const`	filter constant for caustics
`char`	`caustic_filter`	caustic filter type: 'b' - box, 'c' - cone, 'g' - Gauss
`miUint1`	`caustic_flag`	default caustic flag for objects
`miBoolean`	`globillum`	global illumination on/off
`int`	`globillum_accuracy`	number of globillum photons in estimate
`float`	`globillum_radius`	maximum distance for globillum photons in estimate
`miUint1`	`globillum_flag`	default globillum flag for objects
`int`	`photonvol_accuracy`	number of volume photons in estimate
`float`	`photonvol_radius`	maximum distance for volume photons in estimate
`int`	`finalgather`	final gathering: 0 - off, 1 - on, or 'f' - fastlookup
`int`	`finalgather_rays`	number of rays per final gather point
`float`	`finalgather_maxradius`	maximum distance between final gather points
`float`	`finalgather_minradius`	minimum distance between final gather points
`miCBoolean`	`finalgather_view`	final gather radii are specified in raster pixels
`miUint1`	`n_motion_vectors`	motion transformation path length

min_samples

The minimum oversampling level. 0 means one sample per pixel on average (mental ray actually samples corners, not centers of pixels). 1 means subdivide once, which results in four subpixels. 2 means each subpixel is subdivided again, resulting in 16 subpixels, and so on. -1 means one sample per four pixels, etc.

max_samples

After initial subdivision controlled by min_samples, pixels are further subdivided if the contrast demands it, up to the level determined by max_samples.

contrast

If two neighboring samples are more different than the contrast, the pixel is subdivided unless the max_samples limit has been reached.

time_contrast

Approximately an inverse to the number of time oversampling steps in motion blur rendering.

samplelock

If enabled, mental ray attempts to cast the same samples in each frame, which means that the graininess due to low sampling stays in place, instead of flickering. This is achieved by not initializing sampling sequences with the frame number. This has an effect only where the image doesn't change because otherwise oversampling will cast different samples. note that min_samples, max_samples, contrast, and time_contrast are not used by the rasterizer.

render_space

This is 'o' for object space and 'c' for camera space. Camera space rendering is supported for compatibility with mental ray 1.x, but not recommended for new scenes.

task_size

The size of one image rectangle into which the image to render is subdivided. A reasonable default is computed from the output image size if no value has been given explicitly.

pixel_preview

This is enabled during interactive rendering, where mental ray renders only those pixels that are affected by a user change, usually by tuning a shader parameter.

task_preview

This is enabled if the application has entered a mode where only certain image rectangles are rendered.

visible_lights

This is true if there are any lights marked "visible" in the currently rendered scene.

strips

The tessellator will attempt to pack triangles into strips and fans. This is not useful for rendering with mental ray, and in fact incurs overhead due to strip and fan construction, but it can greatly improve the performance of OpenGL viewers.

no_lens no_volume no_geometry no_displace no_output no_merge no_hair no_pass no_predisplace

These flags disable lens, volume, geometry, displace, and output shader calls, respectively, or edge merging, hair and sample pass rendering, and displacement pre-sampling. They are useful for quick preview rendering. Shaders may still explicitly call the disabled shaders, but mental ray won't.

userdata

User data blocks are independent named toplevel scene entities that hold structured or unstructured data of any kind. Structured data is declared much like shader parameters, while unstructured data is a raw byte stream with a fixed size. User data is useful for large amounts of shared scene data.

approx

May be set to any approximation method, which will override approximations specified in objects. This is useful for quick preview rendering where geometric precision does not matter. This is disabled if the method is set to miAPPROX_STYLE_NONE.

approx_displace

This is the same as approx, but applies to displacement approximations in objects.

contour_contrast

The contour contrast shader, or 0.

contour_store

The contour store shader, or 0.

inh_funcdecl

The declaration of the inheritance function or traversal function, or 0.

diagnostic_mode

If nonzero, enables various diagnostic modes that put false-color diagnostic data on top of the rendered image. The modes are:

miSCENE_DIAG_SAMPLES: shows where image samples were taken.
miSCENE_DIAG_PHOTON_D: shows photon density.
miSCENE_DIAG_PHOTON_I: shows photon irradiance.
miSCENE_DIAG_GRID_O: overlays object-space grid lines.
miSCENE_DIAG_GRID_W: overlays world-space grid lines.
miSCENE_DIAG_GRID_C: overlays camera-space grid lines.
miSCENE_DIAG_BSP_D: shows the BSP tree depth.
miSCENE_DIAG_BSP_L: shows the BSP leaf size.
miSCENE_DIAG_FG: shows final gather points.

diag_photon_density

Calibrates the colors for the photon diagnostic modes.

diag_grid_size

Determines the grid line distance in the grid diagnostic modes.

desaturate

Enables fading colors to white, instead of clipping individual components, when storing colors in 8-bit or 16-bit frame buffers.

dither

Enables dithering when storing colors in 8-bit or 16-bit frame buffers.

nopremult

Disables premultiplication, and stores unpremultiplied colors in frame buffers.

colorclip

Selects the color clipping mode applied when storing colors in 8-bit or 16-bit frame buffers, to make sure that RGB do not exceed alpha in premultiplication mode:

miIMG_COLORCLIP_RGB: preserves RGB and adjusts alpha if necessary.
miIMG_COLORCLIP_ALPHA: preserves alpha and adjusts RGB if necessary.
miIMG_COLORCLIP_RAW: disables color clipping.

Color clipping is applied to the color averaged over the time if motion blur is rendered.

gamma

The gamma value applied when storing colors in 8-bit or 16-bit frame buffers. 1.0 disables gamma correction.

luminance_weight

The weights applied to RGB by the mi_luminance shader interface function to compute a luminance value.

no_images

Deprecated The number of the highest defined frame buffer, plus 1.

images_info

An array of type miFb_info specifying the frame buffers.

Rendering algorithm options in the state→options structure:

trace

If this flag is miTRUE, secondary ray tracing (reflection and refraction) is enabled. If it is miFALSE, only eye and transparency rays are evaluated, refraction rays degenerate to transparency rays, lens shaders cannot modify the ray origin and direction, and no shadows are computed regardless of the shadow flag.

scanline

If this flag is miTRUE, the scanline algorithm is enabled for primary rays. If scanline is miFALSE, primary rays are cast using pure ray tracing, which may slow down the rendering process.

motion

If this flag is miTRUE, motion blurring is enabled; if it is miFALSE, motion blurring is disabled even if motion vectors are present.

shutter

If motion is set to miTRUE, the shutter determines the length of time the shutter is open, which controls the length of the blur. 1.0 means that the blur is as long as the motion vectors and motion transformations dictate. Values greater than 1.0 are not recommended because motion paths are extrapolated beyond the given motion data. This may cause unexpected results in the case of multiple motion steps, for example.

shutter_delay

If motion is set to miTRUE, the shutter delay determines the time the shutter opens. It closes at the shutter time, which must be equal to or greater than shutter_delay. A shutter range of 0...1 means that the blur uses the entire range of the motion vectors, motion path, or motion transformations.

autovolume

If set, mental ray will keep track of which volumes a point is in. The shader can then use the shader interface functions mi_volume_num_shaders, mi_volume_cur_shader, mi_volume_user_color, and mi_volume_tags.

filter

Nonlocal filtering weighs samples according to their distance from the pixel center. Possible values are 'b' for box, 't' for triangle, and 'g' for gauss.

filter_size_x

Contains the filter width for collecting image samples into frame buffer pixels.

filter_size_y

Contains the filter height.

reflection_depth

The maximal allowed number of recursive reflections. A reflection ray will only by cast when this limit is not exceeded. If set to 0, no secondary reflection rays will be cast. See reflection_level above.

refraction_depth

The maximal allowed number of recursive refractions. A refraction ray will only be cast if this number is not exceeded. If set to 0, no secondary refraction or transparency rays will be cast. See refraction_level above.

trace_depth

The maximal summed trace depth. mental ray will allow this many segments of the ray tree when it is followed through the scene, with any combination of reflections and refractions permitted by the previous two values until the total trace depth is reached. A ray will only be cast if this number is not exceeded.

face

This variable specifies whether front-facing, back-facing, or all triangles are taken into account. All others are ignored, resulting in speed improvements. This is also called back face culling. The possible values are 'f' (front), 'b' (back), and 'a' (all/both).

field

Field rendering, if turned on, renders only the even or odd scanlines of an image. Two successive renders are then combined to a full frame, resulting in smoother animations. 0 turns off field rendering, 'e' renders only even scanlines (top is odd), and 'o' renders only odd scanlines.

jitter

If set to 1.0, jittering is enabled for samples smaller than a pixel. If set to 0.0, jittering is disabled. Other values are not legal.

shadow

This ASCII character controls shadow casting. If it is 0, shadows are disabled (shadow off); if it is 1, normal shadows are computed in undefined order with volume shaders applied to the light ray (shadow on); if it is 'l', shadow shaders are called in sorted order from the light source towards the illumination point (shadow sort); if it is 's', shadows are computed by tracing the segments between the illumination point, the occluding objects and the light source and applying volume shaders to these segments (shadow segment).

use_shadow_maps

Enables shadow maps if set to miTRUE.

rendering_shadow_maps

If set to miTRUE, mental ray is currently rendering a piece of a shadow map. Shaders will never see miTRUE because no shaders are called during shadow map rendering by mental ray.

recompute_shadow_maps

If set to 'y', shadow maps will be recomputed even if shadow map files were found. If set to 'n', shadow map files will be used if available. To use shadow map files, the shadow-casting light sources must specify a shadow map file name.

shadow_map_motion

If set to miTRUE, shadow maps will contain object motion blur, which will extend the shadows in the direction of motion.

acceleration

The ray tracing algorithm. This is either 'b' (a BSP algorithm), 'n' (BSP2 algorithm), or Deprecated 'g' (former hierarchical uniform grid algorithm). Note, primary rays are typically computed using the scanline/rasterizer algorithm if enabled.

grid_res[]

Deprecated Controls the number of grid voxels in world space, in each dimension, if the acceleration algorithm is grid.

grid_max_depth

Deprecated Controls the number of levels of the grid tree, formed if a grid voxel of one level contains too much geometry and must be subdivided by a subgrid on a lower level. It has an effect only if the acceleration algorithm is grid.

grid_max_size

Deprecated Controls the allowed complexity of a grid voxel before the voxel must be subdivided. It has an effect only if the acceleration algorithm is grid.

space_max_depth

Controls the number of levels of the BSP tree, formed if a BSP voxel of one level contains too much geometry and must be subdivided by a subvoxel on a lower level. It has an effect only if the acceleration algorithm is BSP.

space_max_size

Controls the allowed complexity of a BSP voxel before the voxel must be subdivided. It has an effect only if the acceleration algorithm is BSP. If the space_max_depth limit was reached, mental ray may exceed space_max_size.

space_max_mem

Limits the memory used by the BSP tree to the specified number of megabytes. This is mostly an emergency brake because it may result in an unbalanced BSP tree.

Global illumination options in the state→options structure:

photon_reflection_depth

The maximal allowed number of recursive photon reflections. Similar to reflection_depth. Default is 5.

photon_refraction_depth

The maximal allowed number of photon refractions. Similar to refraction_depth. Default is 5.

photon_trace_depth

The maximal summed photon trace depth. The maximum number of photon bounces is limited by this number. Default is 5.

photonmap_file

The name of the file where photon maps will be loaded and stored. This is a tag; the actual string can be accessed with mi_db_access.

finalgather_file

The name of the file where final gathering point maps will be loaded and stored. Note that unlike photon maps, final gather maps can be extended, and will grow over time unless periodically deleted.

photonmap_rebuild

If set, the photon map file, if specified, will not be loaded, and the photon map is rebuilt from scratch. It will still be written if photonmap_file is defined.

finalgather_rebuild

If set, the final gather map file, if specified, will not be loaded, and the final gather map is rebuilt from scratch. It will still be written if finalgather_file is defined.

caustic

Specifies whether caustics are being simulated or not.

caustic_accuracy

The maximum number of photons to use when computing a caustic irradiance estimate.

caustic_radius

The radius around the current point in which the caustic irradiance estimate will look for photons.

caustic_filter_const

The filter constant for caustic estimates within the caustic radius.

caustic_filter

The type of filter to apply to the photons within the caustic radius: 'b' for box, 'c' for cone, or 'g' for Gaussian.

caustic_flag

If bits 0 or 1 is set, all instances in the scene DAG will behave as if they had bit 0 or 1, respectively, set as well. Bit 0 enables photon casting and bit 1 enables photon reception. This is useful to make all objects in the scene contribute to photon tracing, if the scene was built without photon flags. Older scene creators may not know about these instance flags and leave them undefined.

globillum

Specifies whether global illumination is being simulated or not.

globillum_accuracy

The maximum number of photons to use when computing a global illumination irradiance estimate.

globillum_radius

The radius around the current point in which the global illumination irradiance estimate will look for photons.

globillum_flag

The same as caustic_flag, except that it applies to global illumination, not caustics.

photonvol_accuracy

The maximum number of photons to use when computing a volume global illumination irradiance estimate.

photonvol_radius

The radius around the current point in which the volume global illumination irradiance estimate will look for photons.

finalgather

Specifies whether illumination is computed with final gathering. Final gathering can be combined with global illumination, caustics, or irradiance particles.

finalgather_rays

The number of rays cast for each final gather point. mental ray's adaptive optimizer may decide to cast fewer rays than this number, but will never exceed it.

finalgather_maxradius

The maximum distance between final gather points. If a final gathering estimate is needed and no final gather point is within this radius, a new final gather point is computed.

finalgather_minradius

The minimum distance between final gather points. Final gather points will be avoided if they would be closer than this to another final gather point.

finalgather_view

If set, this flag switches final gather radii to raster pixels instead of world space units. This causes final gathering to be view-dependent: distant objects will receive fewer final gather points than close objects.

n_motion_vectors

Specifies the number of segments to be used for motion paths that approximate transformation motion. The default is 1; the maximum number is 15. Larger numbers allow to render motion paths that are more smoothly curved at the expense of runtime.