Options

The option data structure pointed to by state->options provides the following fields for direct read-only access. The option structure may never be written to by shaders. The extended string options are not available directly through this pointer but need to be retrieved using the C++ shader interface.

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 acceleration algorithm. This is either 'b' (a BSP algorithm), or 'n' (BSP2 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 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.

Copyright © 1986, 2015 NVIDIA ARC GmbH. All rights reserved.