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

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

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. The default is 32 or 64.

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_*

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.

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

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

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 'g' (a hierarchical uniform grid algorithm. Note, primary rays are typically computed using the scanline/rasterizer algorithm if enabled.

grid_res[ ]

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

grid_max_depth

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

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.

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.

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

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

Copyright © 1986-2009 by mental images GmbH