MAXScript Extensions > MAXScript Extensions for mental ray > mental ray String Options >

# mental ray String Options

The mental ray Strings Options introduced in 3ds Max 2011 lets you toggle rendering options and set parameters not yet available in the UI using the Interface: mental_ray_string_options.

Overview:

Traditionally, mental ray options are generated by the controls of the mental ray Renderer User Interface and sent to the renderer to control the rendering process.

Some features supported by the latest version of the mental ray Renderer might not be exposed to the 3ds Max User Interface for various reasons.

The String Options provide a way to access these features via MAXScript and experiment with them before they are officially supported.

Special Considerations:

- Only one option of a given name can be taken into account, with the last option encountered overriding any previous definitions.

  - Thus, it is a good idea to always remove previously set options before setting new ones.

  - Also, the String Options are written to the beginning of the 'options "SceneOptions|SceneOptions"' block, thus using String Options to specify an option that is exported natively by the 3ds Max mental ray connection will have no effect as it will be overwritten by UI setting. For example, setting "finalgather" to "off" via String Options while Final Gather is enabled in the Render Scene Dialog will result in Final Gather being on in the scene.

- An integer value may be specified in place of a float value and some options may contain either Point3 or Point4 values to specify 3 or 4 floating point values.

- Besides these exceptions, values of a wrong type are ignored, for example specifying a Float value of 1.0 as String "1.0" will have no effect.

- Also, misspelled or unknown options are silently ignored by mental ray (they could be options related to 3rd party shaders).

The String Options supported by mental ray but not exposed to the 3ds Max mental ray User Interface are documented below:

Topic Navigation: |
--- | ---
Progressive Rendering Importons Irradiance Particles Image Based Lighting Final Gather Mode |

## Progressive Rendering

| Back To Topic Navigation

By default, mental ray computes images by splitting them into rectangular buckets which are rendered as parallel as possible to their final quality. This is well suited for distributed rendering of larger scenes at highest quality. It has the disadvantage that final images are available only after all buckets have been finished.

In contrast, the progressive rendering mode computes and delivers images at full resolution with incrementally progressing quality. This supports implementations of interactive rendering applications with mental ray for computationally expensive effects like ray tracing and indirect illumination. Best performance can be achieved for medium size models that completely fit into the memory of the machine.

Certain advanced rendering features are not supported to gain speed:

- Only the main color framebuffer is computed.

- Although the traditional shading model is supported, certain advanced features implemented in shaders may not work.

- Especially shaders which perform oversampling are generally not well suited for this rendering mode because sampling cannot be controlled and optimized by mental ray

### Progressive Mode String Options:

    mental_ray_string_options.AddOption "progressive" <Boolean>OnOff

Turn Progressive Rendering on or off.

If not set, the default is off

    mental_ray_string_options.AddOption "progressive subsampling size" <Integer>Size

Enable and control coarse sampling of the first images.

If not set, the default is 0 which means subsampling is disabled.

Values greater than 1 activate subsampling in blocks of pixels.

The value specifies the size of pixel blocks (sizexsize) where initial samples are placed first, typically displaying as a coarse image with the impression of a lower resolution.

The larger size the coarser the initial image.

Values of 0 or 1 disable this feature.

A value of 2 computes samples for blocks of 2x2 = 4 pixels.

The task size has to be a multiple of this subsampling size, otherwise it will be automatically adjusted to the closest possible value.

Those pixels in a block which have not been rendered yet are filled with color values according to the setting of subsampling mode, see below.

    mental_ray_string_options.AddOption "progressive sampling mode" <String>modeName

Controls the appearance of subsampling pixels which are not rendered yet.

Possible values are:

"detail" (default) - pixels that have not been rendered yet are interpolated from the nearest surrounding finished samples. This displays as a smooth image of lower resolution.

"sparse" - pixels that have not been rendered yet are set to black.

    mental_ray_string_options.AddOption "progressive sampling pattern" <String>patternName

Controls the sequence in which the samples are computed.

Possible values are:

"scatter" (default) - pixels are rendered in a quasi-random order.

"linear" - pixels are computed in a line-by-line order within a pixel block.

    mental_ray_string_options. AddOption "progressive min samples" <Integer>minSamples

Sets the minimum number of samples per pixel to render before considering any of the other criteria listed below.

Default is 4.

    mental_ray_string_options.AddOption "progressive max samples" <Integer>maxSamples

Sets the number of samples per pixel that causes progressive rendering to stop.

Default is 100.

If this number of samples per pixel has been rendered, progressive rendering will stop automatically regardless of any other stop criteria.

    mental_ray_string_options.AddOption "progressive max time" <Integer>maxTime

Sets the time in seconds after which to stop progressive rendering.

Default is unlimited.

    mental_ray_string_options.AddOption "progressive error threshold" <Float>threshold

Sets the error threshold to stop progressive rendering.

Default is 0.05.

If this relative error threshold has been reached, progressive rendering will stop automatically.

A value of 0.0 targets perfect quality and won't stop rendering.

A value of 0.5 will stop rendering already at a very low quality.

Note that this setting has lowest priority to determine if progressive rendering should be stopped.

EXAMPLE
Here's a simple script which lets you explore the Progressive Rendering options.
    macroScript MR_Progressive category:"MXS Help"
    (
    global MentalRayStringOptions_Progressive
    try(destroyDialog MentalRayStringOptions_Progressive)catch()
    rollout MentalRayStringOptions_Progressive "mr Progressive Rendering"
    (
    checkbutton chk_progressiveOn ">Enable Progressive Rendering" width:190 align:#center
    spinner spn_samplingSize "Sampling Size:" range:[1,128,8] type:#integer fieldwidth:50 tooltip:"The size of pixel blocks in the initial coarse pass. 0 disables."

    label lbl_mode "Sampling Mode:" across:2 align:#left offset:[0,2]
    dropdownlist ddl_samplingMode items:#("detail", "sparse") width:80 align:#right offset:[1,0] tooltip:"Controls the appearance of not yet rendered subsampling pixels. Detail=Nearest Color, Coarse=Black"
    label lbl_pattern "Sampling Pattern:" across:2 align:#left
    dropdownlist ddl_samplingPattern items:#("scatter", "linear") width:80 align:#right offset:[1,-2] tooltip:"Controls the sequence in which the samples are computed. Scatter=Quasi-Random; Linear=Line By Line In Block"

    spinner spn_samplingMinSamples "Sampling Min.Samples:" range:[1,1000,4] type:#integer fieldwidth:50 tooltip:"Min. samples per pixel to render before considering any of the Stop Criteria below."
    spinner spn_samplingMaxSamples "Sampling Max.Samples:" range:[1,1000,100] type:#integer fieldwidth:50 tooltip:"Max. samples per pixel to render before stopping."
    spinner spn_MaxTime "Max.Time (sec):" range:[0,1000,10] type:#integer fieldwidth:50 tooltip:"Max. time to render before stopping."
    spinner spn_errorThreshold "Error Threshold:" range:[0.01,1,0.05] scale:0.01 type:#float fieldwidth:50 tooltip:"Error Threshold to reach before stopping."

    button btn_quickRender "QUICK RENDER" width:190 align:#center height:30
    button btn_clearSettings "Remove Settings And Close" width:190 align:#center tooltip:"Pressing this button will clear the settings from memory and close. Closing with [X] will keep the settings."
    fn removeProgressiveOptions =
    (
    local m = mental_ray_string_options
    for i = m.numOptions to 1 by -1 where matchPattern (m.GetOptionString i) pattern:"progressive*"do
    m.removeOption i
    )

    fn setProgressiveOptions =
    (
    removeProgressiveOptions()
    local m = mental_ray_string_options
    m.addOption "progressive" chk_progressiveOn.state
    m.addOption "progressive subsampling size" spn_samplingSize.value
    m.addOption "progressive subsampling mode" ddl_samplingMode.selected
    m.addOption "progressive subsampling pattern" ddl_samplingPattern.selected
    m.addOption "progressive min samples" spn_samplingMinSamples.value
    m.addOption "progressive max samples" spn_samplingMaxSamples.value
    m.addOption "progressive max time" spn_MaxTime.value
    m.addOption "progressive error threshold" spn_errorThreshold.value
    )
    fn getProgressiveOptions =
    (
    local m = mental_ray_string_options
    for i = 1 to m.numOptions do
    case m.GetOptionString i of
    (
    "progressive": chk_progressiveOn.state = m.GetOptionValue i
    "progressive subsampling size": spn_samplingSize.value = m.GetOptionValue i
    "progressive subsampling mode": ddl_samplingMode.selection = findItem ddl_samplingMode.items (m.GetOptionValue i)
    "progressive subsampling pattern": ddl_samplingPattern.selection= findItem ddl_samplingPattern.items (m.GetOptionValue i)
    "progressive min samples": spn_samplingMinSamples.value = m.GetOptionValue i
    "progressive max samples": spn_samplingMaxSamples.value = m.GetOptionValue i
    "progressive max time": spn_MaxTime.value = m.GetOptionValue i
    "progressive error threshold": spn_errorThreshold.value = m.GetOptionValue i
    )
    )
    on chk_progressiveOn changed state do setProgressiveOptions()
    on spn_MaxTime changed value do setProgressiveOptions()
    on spn_samplingSize changed value do setProgressiveOptions()
    on spn_samplingMinSamples changed value do setProgressiveOptions()
    on spn_samplingMaxSamples changed value do setProgressiveOptions()
    on spn_errorThreshold changed value do setProgressiveOptions()
    on ddl_samplingMode selected value do setProgressiveOptions()
    on ddl_samplingPattern selected value do setProgressiveOptions()
    on btn_quickRender pressed do max quick render
    on btn_clearSettings pressed do
    (
    removeProgressiveOptions()
    destroyDialog MentalRayStringOptions_Progressive
    )
    on MentalRayStringOptions_Progressive open do getProgressiveOptions()
    )--end rollout
    createDialog MentalRayStringOptions_Progressive 200 250
    )--end script

## Importons

| Back To Topic Navigation

Importons are "virtual particles". In some aspects they are similar to photons: they bounce in the scene. There are significant differences though: unlike photons, importons do not distribute energy. Instead, they contain a color describing the factor an illumination at a certain location would contribute to the final image. This way, they provide information to the renderer on how the computational efforts should be distributed in order to get an image of best quality with limited computational resources.

Unlike photons, importons are emitted from the camera and bounce towards lights, i.e. in a direction opposite to the photons. However, the duality of lights makes it possible to apply photon shaders to importons. For simplicity reason, mental ray does not introduce a new type of shaders but uses photon shaders for importons as well.

Importons are used as a supplementary mechanism which improves the rendering quality and performance. It is used as the primary mechanism to drive the quality of irradiance particles. Another usage in mental ray is improving the quality of the GI photon map. It allows for dramatic reduction of the photon map size with the help of merging within a variable merging distance which is determined with the help of importons. Such variable merging distance is superior to the constant merging distance.

If enabled, importons are shot before photon maps are created. They are used during the GI photon map creation. As they are not relevant to GI photon map nearest neighbor lookups, importons are discarded once the photon map is created.

### Importons String Options:

    mental_ray_string_options.AddOption "importon" <Boolean>OnOff

If set to true, the importons are emitted and an importon map is created.

The default value if not set is off.

    mental_ray_string_options.AddOption "importon density" <Float>density

Specifies the approximate number of importons shot from the camera per pixel.

The minimal value for this option in the current implementation is 0.02, i.e approximately 1 importon per 50 pixels.

The default and recommended value is 1.0.

Lower values will speed up importon emission, but could lead to a less optimal photon map and decrease the final image quality.

    mental_ray_string_options.AddOption "importon merge" <Float>merge

Specifies the world-space distance used to merge close importons.

The default value is 0.0, which means that merging is disabled.

    mental_ray_string_options.AddOption "importon trace depth" <Integer>traceDepth

Controls the diffusion of importons in the scene.

If set to 0.0 (default), importons will not scatter on the diffuse bounces.

In some cases it may be required to use more than a single diffuse bounce. This is the case if the combination with final gathering is used, or when the "importon traverse" option is switched off (see below).

    mental_ray_string_options.AddOption "importon traverse" <Boolean>traverse

Enables a special behavior of importons shot from the camera. Such importons would not be blocked by even completely opaque geometry. Instead, they would be stored for all intersections with geometry on the ray from the camera to infinity.

This leads to a significantly higher number of importons stored in the scene. However, it removes the discontinuity in the distribution of the importons originated from the visibility to the camera function.

The default value is on.

EXAMPLE
Here's an example of how to toggle Importon rendering mode:
    m = mental_ray_string_options
    for i = 1 tom.numOptions do
    m.removeOption 1 --remove any previous options
    m.addoption "importon" true
    m.addoption "importon density" 1.0

## Irradiance Particles

| Back To Topic Navigation

This algorithm is a novel approach to computing global illumination based on importance sampling which tends to converge much faster to a desirable quality than the existing solutions like global illumination photon tracing combined with final gathering.

Before rendering starts, importons are shot from the camera into the scene and collected as a new kind of particle, called an irradiance particle. They carry information about the amount of direct illumination coming in at their position (hence the name "irradiance") and, optionally, the amount of indirect irradiance incident at their position (if indirect passes are enabled). During rendering, the stored particles are used to estimate the irradiance at a shading point: if just direct illumination was collected for irradiance particles, this is equivalent to one bounce of indirect lighting.

The irradiance can also be interpolated from precomputed values at the particle positions.

The irradiance particle algorithm simulates some but not all of the indirect lighting interactions of the traditional global illumination algorithms in mental ray. For this reason, if irradiance particles are enabled then mental ray will turn off the global illumination photon tracing automatically if it was activated. This is a common situation when external applications are asked to generate mental ray scenes with photon shaders attached, which are needed for importons. Caustics can be used together with irradiance particles because they are used to capture indirect lighting effects that irradiance particles cannot simulate. If both final gathering and irradiance particles are enabled then final gathering is preferred and irradiance particles will be switched off automatically. Thus it is important to turn off FG explicitly when using String Options to enable Irradiance Particles.

Irradiance particles support a special Image Based Lighting-style functionality which can be enabled by setting the number of indirect passes to -1. In this case only the environment map lighting but not diffuse bounces are taken into account. If interpolation is disabled then only an environment pre-sampling map is build and no further pre-computation steps are required. If interpolation is enabled then particles are emitted in the pre-computation pass in the usual way, but used as interpolation points only.

### Irradiance Particles String Options:

    mental_ray_string_options.AddOption "irradiance particles" <Boolean>OnOff

If enabled, the irradiance particles are used to simulate indirect lighting, disabling global illumination photons if they were turned on.

If final gathering is enabled this setting is ignored.

The default value if not set is off.

    mental_ray_string_options.AddOption "irradiance particles rays" <Integer>Rays

Controls the number of rays to shoot while estimating the irradiance.

The minimum is 2.

The default is 256.

    mental_ray_string_options.AddOption "irradiance particles indirect passes" <Integer>indirectPasses

The number of possible passes of indirect lighting.

If this value is greater than 0, then a sequence of passes is performed to collect the irradiance coming at every particle position, so irradiance particles will have both direct illumination and indirect illumination information.

If this value is 0 (default), the irradiance particles will have only direct illumination information.

If the value is -1, only the environment map lighting but not diffuse bounces are taken into account. If interpolation is disabled then only an environment pre-sampling map will be built and no further pre-computation steps will be required. If interpolation is enabled then particles will be emitted in the pre-computation pass in the usual way, but will be used as interpolation points only.

    mental_ray_string_options.AddOption "irradiance particles scale" {<Float>Scale|<Point3>RGBScale}

This is the global scale factor for the intensity of the irradiance during rendering.

This is a global tuning option for artistic control.

It can be specified as a single Float value which is used to set R, G and B at once, or as Point3 value for separate control of the three color channels.

The default is 1.0.

    mental_ray_string_options.AddOption "irradiance particles interpolate" {<Integer>index|<String>modeName}

This option is used to control the use of interpolation, and it can be either a numeric value or a string:

0 - no interpolation

1 - always interpolate

2 - interpolate only for secondary rays (no interpolation for eye rays but interpolation for reflections, refractions, etc).

Alternatively, it can be set to the strings "never", "always" or "secondary".

Default is 1 ("always").

    mental_ray_string_options.AddOption "irradiance particles interppoints" <Integer>points

The number of nearest neighbor points to use for the interpolation (see above).

Default is 64.

    mental_ray_string_options.AddOption "irradiance particles env" <Boolean>OnOff

This flag enables the use of the environment maps for irradiance computation.

If enabled, a separate particle map is built for the environment (if an environment shader is present) and used during rendering.

Default is on.

    mental_ray_string_options.AddOption "irradiance particles env scale" {<Float>Scale|<Point3>RGBScale}

The scaling factor for the irradiance contributed by the environment.

It can be specified as a single float or as a Point3 value.

This scaling factor is relative because it applies to the environment irradiance only: the environment irradiance could actually be further scaled if the user specifies a global scaling factor with the "irradiance particle scale" string option.

For example, if the env. scale is set to 2.0 and the global scale is set to 3.0 then the actual scaling factor for the environment irradiance will be 6.0 (2.0 x 3.0).

Default is 1.0.

    mental_ray_string_options.AddOption "irradiance particles env rays" <Integer>rays

The number of rays used for the computation of irradiance coming from the environment map.

This number can be much higher than the number of rays used for normal irradiance computation, especially if most of the environment is covered by scene geometry (typical case: a room with just one or two windows).

For outside scenes, it should work fine with a smaller number of rays.

The default is taken from to actual value of "irradiance particles rays".

    mental_ray_string_options. AddOption "irradiance particles file" <String>filename

If the file exists, mental ray will try to read the particle map from it.

If it doesn't exist, the computed particle map will be saved to a file with the given name.

The default is: no file.

    mental_ray_string_options.AddOption "irradiance particles rebuild" <Boolean>OnOff

If set to true, mental ray will re-compute the particle map.

If set to false, an existing map will be re-used, either read from an existing file if specified, or taken from a previous frame of an animation.

This can be useful to avoid flicker in animations, like for fly-throughs.

Note that the global illumination might become incorrect if objects are moving.

Since the particle map is essentially view dependent it is possible that inaccuracies show up when the camera moves.

Default is true.

SCRIPT
Here is an example script to explore the Irradiance Particles rendering mode:
    macroScript MR_IrradPart category:"MXS Help"
    (
    global MentalRayStringOptions_IrradianceParticles
    try(destroyDialog MentalRayStringOptions_IrradianceParticles) catch()
    rollout MentalRayStringOptions_IrradianceParticles "mr Irradiance Particles"
    (
    checkbutton chk_IrraPartOn ">Enable Irradiance Particles" width:190 align:#center
    group "Global Settings"
    (
    spinner spn_Rays "Rays:" range:[1,4096,256] type:#integer fieldwidth:50 tooltip:"The number of rays to shoot. Default is 256."
    spinner spn_Passes "Indirect Passes:" range:[-1,32,0] type:#integer fieldwidth:50 tooltip:"Number of passes. 0 means direct illumination only."
    checkbox chk_LockScale "Lock" across:2 align:#left
    spinner spn_ScaleR "Scale R:" range:[0,1000,1] type:#float fieldwidth:50 tooltip:"Global Scale of Red Component or Global RGB Scale if Locked."
    spinner spn_ScaleG "Scale G:" range:[0,1000,1] type:#float fieldwidth:50 tooltip:"Global Scale of Green Component"
    spinner spn_ScaleB "Scale B:" range:[0,1000,1] type:#float fieldwidth:50 tooltip:"Global Scale of Blue Component"
    dropdownlist ddl_interpolationMode items:#("No Interpolation","Interpolate All","Interpolate Secondary") width:140 selection:2 align:#right offset:[1,0] tooltip:"Controls the interpolation mode."
    spinner spn_interpPoints "Interpolate Points:" range:[8,4096,64] type:#integer fieldwidth:50 tooltip:"Number of nearest neigbor points to interpolate."
    )
    group "Environment Irradiance"
    (
    checkbox chk_envOnOff "Enable Environment Irradiance"
    checkbox chk_envLockScale "Lock" across:2 align:#left
    spinner spn_envScaleR "Env.Scale R:" range:[0,1000,1] type:#float fieldwidth:50 tooltip:"Scale Red Env. Component or Env. RGB Scale if Locked on top of the Global Scale."
    spinner spn_envScaleG "Env.Scale G:" range:[0,1000,1] type:#float fieldwidth:50 tooltip:"Scale Green Env. Component on top of the Global Scale."
    spinner spn_envScaleB "Env.Scale B:" range:[0,1000,1] type:#float fieldwidth:50 tooltip:"Scale Blue Env. Component on top of the Global Scale."
    spinner spn_envRays "Env.Rays:" range:[1,4096,256] type:#integer fieldwidth:50 tooltip:"The number of Env. rays to shoot. Default is 256."
    )
    group "Irradiance Particles Cache File"
    (
    button btn_setParticleFile "Set Irradiance Particles Cache File..." width:185 align:#center
    edittext edt_particleFile "" fieldwidth:185 offset:[-10,-3]
    checkbox chk_rebuild "Rebuild Map" checked:true tooltip:"When checked, the map will be rebuild. When unchecked, the disk or previous animation frame map will be reused."
    )

    button btn_quickRender "QUICK RENDER" width:190 align:#center height:30
    button btn_clearSettings "Remove Settings And Close" width:190 align:#center tooltip:"Pressing this button will clear the settings from memory and close. Closing with [X] will keep the settings."
    fn removeOptions =
    (
    local m = mental_ray_string_options
    for i = m.numOptions to 1 by -1 where matchPattern (m.GetOptionString i) pattern:"irradiance*"do
    m.removeOption i
    )

    fn setOptions =
    (
    removeOptions()
    local m = mental_ray_string_options
    m.addOption "irradiance particles" chk_IrraPartOn.state
    m.addOption "irradiance particles rays" spn_Rays.value
    m.addOption "irradiance particles indirect passes" spn_passes.value
    if chk_LockScale.state then
    m.addOption "irradiance particles scale" spn_scaleR.value
    else
    m.addOption "irradiance particles scale" (Point3 spn_scaleR.value spn_scaleG.value spn_scaleB.value)
    m.addOption "irradiance particles interpolate" (ddl_interpolationMode.selection-1)
    m.addOption "irradiance particles interppoints" spn_interppoints.value
    m.addOption "irradiance particles env" chk_envOnOff.state
    if chk_envLockScale.state then
    m.addOption "irradiance particles env scale" spn_envScaleR.value
    else
    m.addOption "irradiance particles env scale" (Point3 spn_envScaleR.value spn_envScaleG.value spn_envScaleB.value)
    m.addOption "irradiance particles env rays" spn_envRays.value
    m.addOption "irradiance particles file" edt_particleFile.text
    m.addOption "irradiance particles rebuild" chk_rebuild.state
    try (
    renderers.current.FinalGatherEnable2 = false
    renderers.current.CommitUI()
    renderers.current.UpdateUI()
    )catch()
    )
    fn getOptions =
    (
    local m = mental_ray_string_options
    for i = 1 to m.numOptions do
    (
    local theVal = m.GetOptionValue i
    case m.GetOptionString i of
    (
    "irradiance particles": chk_IrraPartOn.state = theVal
    "irradiance particles rays": spn_Rays.value = theVal
    "irradiance particles indirect passes": spn_passes.value = theVal
    "irradiance particles scale": (
    if classof theVal == Point3 then
    (
    spn_scaleR.value = theVal.x
    spn_scaleG.value = theVal.y
    spn_scaleB.value = theVal.z
    chk_LockScale.state = false
    spn_scaleG.enabled = spn_scaleB.enabled = true
    )
    else if classof theVal == Integer or classof theVal == Float do
    (
    spn_scaleR.value = theVal
    chk_LockScale.state = true
    spn_scaleG.enabled = spn_scaleB.enabled = false
    )
    )
    "irradiance particles interpolate": (
    ddl_interpolationMode.selection = if classof theVal == Integer then theVal+1 else
    ((findItem #("never", "always","secondary") theVal)+1)
    )
    "irradiance particles interppoints": spn_interppoints.value = theVal
    "irradiance particles env": chk_envOnOff.state = theVal
    "irradiance particles env scale": (
    if classof theVal == Point3 then
    (
    spn_envScaleR.value = theVal.x
    spn_envScaleG.value = theVal.y
    spn_envScaleB.value = theVal.z
    chk_envLockScale.state = false
    spn_envScaleG.enabled = spn_envScaleB.enabled = true
    )
    else if classof theVal == Integer or classof theVal == Float do
    (
    spn_envScaleR.value = theVal
    chk_envLockScale.state = true
    spn_envScaleG.enabled = spn_envScaleB.enabled = false
    )
    )
    "irradiance particles env rays": spn_envRays.value = theVal
    "irradiance particles file": edt_particleFile.text = theVal
    "irradiance particles rebuild": chk_rebuild.state = theVal
    )--end case
    )--end i loop
    )
    on chk_IrraPartOn changed state do setOptions()
    on spn_Rays changed value do setOptions()
    on spn_Passes changed value do setOptions()
    on chk_LockScale changed state do
    (
    setOptions()
    spn_scaleG.enabled = spn_scaleB.enabled = not state
    )
    on spn_ScaleR changed value do setOptions()
    on spn_ScaleG changed value do setOptions()
    on spn_ScaleB changed value do setOptions()
    on ddl_interpolationMode selected itm do setOptions()
    on spn_interppoints changed value do setOptions()
    on chk_envOnOff changed state do setOptions()
    on chk_envLockScale changed state do
    (
    setOptions()
    spn_envScaleG.enabled = spn_envScaleB.enabled = not state
    )
    on spn_envScaleR changed value do setOptions()
    on spn_envScaleG changed value do setOptions()
    on spn_envScaleB changed value do setOptions()
    on spn_envRays changed value do setOptions()
    on btn_setParticleFile pressed do
    (
    local theVal = getSaveFileName caption:"Specify Irradiance Particles Cache Filename:" types:"Irradiance Particles Cache (*.ipc)|*.ipc"
    if theVal != undefined do
    (
    edt_particleFile.text = theVal
    setOptions()
    )
    )
    on edt_particleFile entered txt do setOptions()
    on chk_rebuild changed state do setOptions()
    on btn_quickRender pressed do max quick render
    on btn_clearSettings pressed do
    (
    removeOptions()
    try(renderers.current.FinalGatherEnable2 = true)catch()
    destroyDialog MentalRayStringOptions_IrradianceParticles
    )
    on MentalRayStringOptions_IrradianceParticles open do getOptions()
    )--end rollout
    createDialog MentalRayStringOptions_IrradianceParticles 200 490
    )--end script
No Global Illumination (left) vs Irradiance Particles, Default Settings (right).
Final Gather Global Illumination (left) vs Irradiance Particles, Global Scale 5.0 (right)
Irradiance Particles with 16 rays (left) vs. 64 rays (right).
Irradiance Particles with 256 rays, Global Scale 5.0, 5.0, 5.0 (left) vs. Global Scale 5.0, 1.0, 1.0 (right).
Irradiance Particles with 256 rays, Global Scale 1.0, 5.0, 1.0 (left) vs. Global Scale 1.0, 1.0, 5.0 (right).

## Image Based Lighting (IBL), a.k.a. Environment Lighting

| Back To Topic Navigation

    mental_ray_string_options.AddOption "environment lighting mode" <String>mode

Enables the built-in IBL mode if the value is set to "light".

The default value is "off".

    mental_ray_string_options.AddOption "environment lighting quality" <Float>quality

Controls the quality of the IBL contribution.

The value can range from 0.0 to 1.0 for lowest to highest quality.

The default is 0.2.

    mental_ray_string_options.AddOption "environment lighting shadow" <String>shadowMode

Control the shadows cast by IBL.

"off" - disable shadow casting

"solid" - cast opaque shadows

"transparent" (default) - full shadowing using the shadow shaders.

## Final Gather Mode

| Back To Topic Navigation

    mental_ray_string_options.AddOption "finalgather" <String>mode

Selects one of the available FG modes.

Possible string values are:

"automatic" (default) - targets primarily rendering of single still images. Uses the finalgather points argument for the approximate resp. minimal number of final gather points used in interpolation. All FG points are produced in the FG precomputing stage.

"multiframe" - targets rendering of camera fly-through animations. Uses the finalgather points argument for the approximate resp. minimal number of final gather points used in interpolation. All FG points are produced in the FG precomputing stage. The finalgather accuracy R_1 is used to limit the maximal validity distance of a finalgather point to avoid picking up illumination from remote objects if the density of finalgather points is insufficient.

"force" - disables final gather caching completely and always performs the full and accurate computation. This takes time but yields superior quality.

"strict 3.4" - compatibility mode - focuses on rendering images identical or very similar to mental ray 3.4.

"3.4" - compatibility mode - focuses on usage of the same argument set, but with rendering improvements

EXAMPLE
Here is an example of toggling Force Final Gather mode:
    m = mental_ray_string_options
    for i = m.numOptions to 1 by -1 \
    where matchpattern (m.GetOptionString i) pattern:"finalgather*" do
    m.removeOption 1 --remove previous options
    m.addOption "finalgather mode" "force"
    --Control image quality with the "Rays per FG Point" spinner.

#### See Also

- Interface: mental_ray_string_options

- mental_ray_renderer : RendererClass

- iray String Options