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
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. A reasonable default is computed from the output image size if no value has been given explicitly.
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, 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.
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.
The contour contrast shader, or 0.
The contour store shader, or 0.
The declaration of the inheritance function or traversal function, or 0.
If nonzero, enables various diagnostic modes that put false-color diagnostic data on top of the rendered image. The modes are:
shows where image samples were taken.
shows photon density.
shows photon irradiance.
overlays object-space grid lines.
overlays world-space grid lines.
overlays camera-space grid lines.
shows the BSP tree depth.
shows the BSP leaf size.
shows final gather points.
Calibrates the colors for the photon diagnostic modes.
Determines the grid line distance in the grid diagnostic modes.
Enables fading colors to white, instead of clipping individual components, when storing colors in 8-bit or 16-bit frame buffers.
Enables dithering when storing colors in 8-bit or 16-bit frame buffers.
Disables premultiplication, and stores unpremultiplied colors in 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:
preserves RGB and adjusts alpha if necessary.
preserves alpha and adjusts RGB if necessary.
disables color clipping.
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.
Deprecated The number of the highest defined frame buffer, plus 1.
An array of type miFb_info specifying the frame buffers.

Rendering algorithm options in the state→options structure:

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 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.
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.
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.
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.
Contains the filter height.
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/both).
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).
Enables shadow maps if set to miTRUE.
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 Deprecated 'g' (former hierarchical uniform grid algorithm). Note, primary rays are typically computed using the scanline/rasterizer algorithm if enabled.
Deprecated Controls the number of grid voxels in world space, in each dimension, if the acceleration algorithm is grid.
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.
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.
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.

Global illumination options in the state→options structure:

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.
Specifies whether caustics are being simulated or not.
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 filter constant for caustic estimates within the caustic radius.
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.
Specifies whether global illumination is being simulated or not.
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.
Specifies whether illumination is computed with final gathering. Final gathering can be combined with global illumination, caustics, or irradiance particles.
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 to render motion paths that are more smoothly curved at the expense of runtime.

Copyright © 1986-2011 by mental images GmbH