Iray Programmer's Manual

Rendering options

One of the main design goals of Iray Photoreal is ease of use. It is not necessary to control the algorithmic behavior via a myriad of settings of this render mode to achieve good results across different kind of scenes.

Nonetheless, the following few attributes on the IOptions class, shown here with their default settings where applicable, can control some aspects of Iray Photoreal:

mi::Sint32 iray_max_path_length

Bounds the maximum number of vertices (bounces) of light paths to contribute to the result. Since this setting cuts off indirect lighting contributions (one example would be the headlight of a car that depends on a lot of indirect effects to look correct), it should only be applied when the rendering has to be accelerated at the expense of physical accuracy.

mi::IString iray_default_alpha_lpe

Controls the default light path expression used for alpha channels if none is specified explicitly. The default is "E T* [LmLe]". See Canvas names in render targets for details.

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

Iray Photoreal 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 Photoreal 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''.

Consistency is not affected by this filter: fireflies are automatically detected and masked out in the early rendering stage when variance is high but eventually these missing contributions are faded back in over time. Thus, the results at a low sample count may appear slightly darker than the final, converged image. 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 Photoreal 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 Photoreal 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.

bool iray_optix_prime = true

Switches from the classical built-in Ray Tracing traversal and hierarchy construction code to the external NVIDIA OptiX Prime API. Setting this option to false will lead to slower scene-geometry updates when running on the GPU and (usually) increased overall rendering time, but features less temporary memory overhead during scene-geometry updates and also decreased overall memory usage during rendering.

mi::IString iray_instancing

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

mi::IString shadow_terminator_offset_mode = "user"

Allows to override the per-object boolean attribute "shadow_terminator_offset" globally for all scene objects. Possible values are "off", "on", and "user" (the latter will always use the per-object attribute). See Tessellating curved surfaces for more details about the shadow terminator artifact problem. Note that it is not recommended to always have this forced "on", as it can lead to other shadowing problems in some geometric setups.