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

When indirect lighting is not enabled, Iray Interactive determines the incoming lighting at a point as the sum of the contributions of the light sources, of the environment, and of an approximation of the indirect lighting. The contribution of the environment can be either obtained by the environment itself, or approximated by a constant color. This constant color can also be modulated by ambient occlusion. The indirect lighting is approximated by a constant color, also potentially modulated by ambient occlusion.

mi::Sint32 irt_env_lighting_mode = 0
  • 0: Environment lighting
  • 1: Constant color approximation
  • 2: Ambient occlusion approximation

This setting determines how the computation of environment lighting is performed. Using the default value of 0, Iray Interactive computes the environment lighting from the actual radiance coming from the environment. The value 1 approximates the contributions of the environment as irt_env_approx_color. The last value triggers the computation of ambient occlusion. The behavior of Iray Interactive is tied to the irt_ambient_occlusion_mode value. When irt_ambient_occlusion_mode == 0 the environment is considered uniform, with an emission determined by irt_env_approx_color. Otherwise, the emission of the environment is the monochromatic luminance of the actual environment.

Note that this setting only affects the lighting on diffuse and glossy surfaces, while the actual environment is always used when computing specular reflections.

mi::Color irt_env_approx_color = 0

Intensity of the constant lighting used to approximate environment lighting when irt_env_lighting_mode != 0.

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::Boolean irt_use_ambient_occlusion = false

This setting enables the use of ambient occlusion as an approximation of indirect lighting, where the approximated indirect lighting is defined by irt_ambient_intensity.

mi::Color irt_ambient_intensity = 0

Intensity of additional ambient lighting, typically used to approximate global illumination effects.

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, as well as IBL if irt_ibl_falloff = true.

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, as well as IBL if irt_ibl_falloff = true.

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.

Note: the environment lighting and indirect lighting approximation values described in the previous section are automatically disabled when irt_indirect_light_mode != 0.

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

bool iray_firefly_filter = true

Controls a built-in filter to reduce bright spots that may occur under some difficult lighting conditions. Such bright undesired pixels are often called ``fireflies''.

The filter works best in combination with the built-in tonemappers. If a tonemapper is not enabled, the filter estimates can be too pessimistic for some scenes, resulting in some fireflies to still appear.

mi::Float32 iray_nominal_luminance = 0

The nominal luminance is a hint to Iray Interactive on what is considered a "reasonable" luminance level when viewing the scene. This luminance level is used internally to tune the firefly filter and error estimate. When the nominal luminance value is set to 0, Iray Interactive will estimate the nominal luminance value from the tonemapper settings. If a user application applies its own tonemapping without using the built-in tonemappers, it is strongly advised to provide a nominal luminance.

Recommendations: For visualization, a reasonable nominal luminance would be the luminance value of a white color that maps to half the maximum brightness of the intended display device. For quantitative architectural daylight simulations (e.g. irradiance buffer), a reasonable nominal luminance could be the luminance of white paper under average day light.

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.


mi::IString iray_instancing

Controls the instancing feature. Possible values are "off", "on". No default is set, which is equivalent to "off".