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

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' - BSP23.6, '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

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

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.

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

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

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

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.

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.

The size of one image rectangle into which the image to render is subdivided. The default is 32 or 64.

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.

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

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

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.

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

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.

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.

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

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.

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

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. In mental ray 3.5, color clipping is applied to the color averaged over the time if motion blur is rendered.

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

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

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.

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.

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

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 of motion transformations dictate. Values greater than 1.0 are not recommended because motion paths consisting of multiple motion

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.

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.

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

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.

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.

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.

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

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.

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.

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

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.

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.

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

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

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

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.

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. If the grid_max_depth limit was reached, mental ray may exceed grid_max_size.

A value 1.0 accepts mental ray's resolution estimate, larger values increase the resolution, and smaller values decrease it. It has an effect only if the acceleration algorithm is grid.

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.

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.

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.

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

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

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

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.

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.

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.

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.

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

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

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

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.

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

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

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

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

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

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.

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.

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.

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.

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 transform motion paths that are more smoothly curved, but also reduce performance.