Iray Programmer's Manual

Rendering options

The following sections describe specific attributes on the mi::neuraylib::IOptions class, shown here with their default settings, for ambient occlusion and shadows as well as other miscellaneous parameters.

Ambient occlusion and lighting

mi::Boolean irt_use_ambient_occlusion = false

This setting enables the use of ambient occlusion in the beauty render instead of full environment lighting.

mi::Sint32 irt_ambient_occlusion_mode = 0
  • 0: diffuse ambient occlusion
  • 1: environment-guided ambient occlusion

This setting only affects the ambient_occlusion output canvas and the beauty render when irt_use_ambient_occlusion == true. The first variant corresponds to the common diffuse ambient occlusion calculation, which integrates the visibility weighted by the cosine of the direction and the normal over the hemisphere. The difference between the two settings is that the first variant assumes uniform ambient lighting, whereas the second lights the scene under the actual environment used in the scene. The exact behavior differs depending on the rendering output:

  • ambient_occlusion output: both methods render the scene with a white Lambertian material. The environment-guided ambient occlusion results in a color output.
  • beauty output: the scene is rendered with full material evaluation, but the contribution of the environment is computed from a user-controlled intensity when irt_ambient_occlusion_mode == 0 and from monochromatic environment luminance otherwise.
mi::Float32 irt_environment_occlusion_scale = 1.0

This setting describes the overall ratio between the openings and occlusions in the scene. The environment lighting is then dimmed accordingly instead of relying on actual environment lighting. Fast convergence with consistent lighting can then be achieved using IBL falloffs.

mi::Color irt_ambient_intensity = 0

Intensity of additional ambient lighting.

mi::Float32 irt_ambient_falloff_max_distance = FLT_MAX

World space distance beyond which potential occlusion does not influence result of ambient lighting and AO.

mi::Float32 irt_ambient_falloff_min_distance = FLT_MAX

World space distance below which all potential occlusion fully influences result of ambient lighting and AO.

mi::Float32 irt_ambient_falloff = 1

Exponent to be used for weighting the occlusion value between falloff min and max distance. The default 1 blends linearly.

mi::Sint32 irt_ambient_falloff_distance_space = 0
  • 0: world space
  • 1: raster space (pixels)

Defines whether the irt_ambient_falloff_min/max_distance values correspond to world space or raster space.

Indirect lighting

Iray Interactive includes a fast approximation technique for indirect lighting. This technique takes into account all light sources, HDRI environment, physical sun and sky and diffuse and glossy components of the material.

Iray Interactive supports two indirect illumination modes. The coarse mode is suitable to obtain a fast early impression of the indirect illumination in the scene. At the first primary hit point, the indirect illumination does only contribute to the diffuse layers, which means that glossy contributions are only taken into account at secondary hits and beyond.

In fine scale mode, all reflective layers, including glossy and measured BRDFs, of the material receive indirect illumination. Furthermore, indirect illumination from the close vicinity of the shading location is taken into account more accurately. In contrast to the coarse scale approximation, this mode does not introduce any undesirable corner darkening.

In turntable like outdoor scenes, indirect lighting can often be neglected, but it is usually an important contribution in indoor scenes.

mi::Sint32 irt_indirect_light_mode = 0
  • 0: no indirect lighting except specular transmission and reflection.
  • 1: coarse scale diffuse indirect illumination.
  • 2: fine scale indirect illumination, including glossy and measured BRDFs.
bool irt_indirect_outlier_rejection = true

The technique automatically rejects outliers which would lead to displeasing low-frequency contributions which converge away only slowly. This is similar to the firefly filter in Iray Photoreal. However, this means that some contributions are cut-off, which can be disabled by setting the above option to false.

Figure 1. Simple indoor scene without (0), with coarse scale (1) and with fine scale (2) indirect lighting enabled.
File: images/irt_livingroom.png


bool irt_area_as_point_lights = false

Approximate area by point lights, for example to avoid shadow noise during interaction.

Figure 2. Simple scene rendered with area lights approximated by point lights (left) and full area light sampling (right)
File: images/irt_area.png
mi::Sint32 irt_ambient_shadow_mode = 1

Allows to control occlusion tests for environment, instant sun and sky and ambient lighting:

  • 0: no occlusion
  • 1: raytraced occlusion
  • 2: This value is deprecated, and is used for screen space approximation, with directional occlusion tests for non-diffuse materials. This mode is less precise than raytraced occlusion tests, but converges faster to a noise free result. Noise results mainly from glossy components of the material. View-dependent occlusion seen in glossy layers, such as seen on the ground floor of the image, are retained.
  • 3: This value is deprecated, and is used for screen space ambient occlusion applied to all material layers. In this mode, less noise is visible on glossy materials to the expense of losing directional effects in the occlusion.

In modes 2 and 3, the influence region is controlled by the irt_ambient_falloff_min/max_distance parameters and the radius is always clamped to not exceed 200 pixels in raster space. In raytraced mode, this is only the case when irt_ibl_falloff = true, otherwise the occlusion distance is unlimited.

Since ambient and IBL shadows can be turned off by setting the value to 0, the parameter irt_ibl_shadows is now deprecated.

Note that modes 2 and 3 lead to a degradation of multi-GPU scalability.

Figure 3. Simple scene rendered with modes 0, 1, 2 and 3
File: images/shader_ball_mode_small.png
bool irt_shadows = true

Allows shadows to be forcibly turned off, independent of scene shadow flags.

bool irt_ibl_falloff = false

If this flag is enabled, the irt_ambient_falloff_min/max_distance parameters also affect raytraced occlusion for IBL and instant sun and sky.

bool shadow_cast = true

The per-instance bool shadow_cast flag controls whether an object is casting a shadow. It is taken into account by the renderer if irt_shadows is enabled.

bool_shadow_recv = true

The per-instance bool shadow_recv flag controls whether an object will display the effect of shadows cast by other objects ("receives" the shadow). It is taken into account by the renderer if irt_shadows is enabled.

Additional approximations

Iray Interactive allows to trade quality against performance in various ways.

mi::Sint32 depth = 16, mi::Sint32 depth_reflect = 4, mi::Sint32 depth_refract = 4, mi::Sint32 depth_shadow = 16

Maximum trace depth settings are respected by Iray Interactive. These values correspond to the maximum total number of bounces, maximum number of reflections and refractions and maximum number of shadow refractions respectively.

Figure 4. From left to right: A glass object rendered with different trace depths 8, 6, 4 and 2
File: images/irt_trace_depth_8_6_4_2.png
mi::Float32 irt_ray_importance_threshold = 0.02

If the contribution of a specular reflection or refraction bounce falls below this value it is cut off. The lower the value the more accurate the result. The tradeoff is elapsed time. Compared to limiting the trace depth, using this setting usually results in a better performance-quality ratio.

Figure 5. From left to right: A glass object rendered with importance thresholds 0, 0.05, 0.1 and 0.4
File: images/irt_importance_0_0.05_0.1_0.4.png
mi::Sint32 irt_render_mode = 1

When set to 0, the renderer is in interactive mode, depth of field and IBL shadows are turned off and some additional approximations are used. When set to 1, the standard refinement mode is used.

Antialiasing and filtering

Iray Interactive supports the filter parameter in the same way as Iray Photoreal (see Rendering options in Iray Photoreal).

bool irt_first_frame_antialiasing = false

FXAA antialiasing is applied by default to the first frame when irt_render_mode is set to zero, improving in particular the appearance of sharp edges. FXAA is not available in multi-GPU configurations.

mi::Sint32 filter = mi::neuraylib::FILTER_GAUSS

Iray Interactive natively supports mi::neuraylib::FILTER_BOX, mi::neuraylib::FILTER_TRIANGLE and mi::neuraylib::FILTER_GAUSS filters for antialiasing. If mi::neuraylib::FILTER_CMITCHELL or mi::neuraylib::FILTER_CLANCZOS is requested, Iray Interactive will use the default Gaussian filter instead.

mi::Float32 radius

The radius of the filter kernel. Recommended values are 0.5 for box filter, 1 for triangle filter and 1.5 for Gauss filter.

Environment map resolution

mi::Sint32 irt_environment_max_resolution = 2048

This parameter sets the maximum HDRI environment map resolution (width) used by the renderer. All environment maps with a higher resolution are scaled down to this size. This avoids high preprocessing times and device memory consumption for large environment maps to the expense of higher image quality.