Iray Programmer's Manual

Canvas names in render targets

The canvas names in the IRender_target_base class determine what is rendered to the canvas. The pixel type of the canvas needs to be of a matching type corresponding to the canvas name. See the limitations subsection in the individual render mode sections for the relevant limitations on canvases.

The following canvas names are supported:

  • result, result lpexpr= lp-expressions, or lpexpr= lp-expressions

    A Color or Float32<3> canvas that contains the rendered image with all contributions, the beauty pass, including the alpha channel if the pixel type supports alpha.

    The optional lpexpr=... part specifies either one light path expression, or two LPEs separated by a semicolon. If one expression is given, the result color channels are restricted to those light transport paths that match the first expression. The optional second expression controls the contents of the alpha channel, if available in the canvas, independently of the color expression. The default is controlled by the "iray_default_alpha_lpe" option.

    Light path expressions are explained in depth in a separate section. Some common examples are:

    LP-Expression Description
    E D .* L Diffuse pass commonly used in conventional compositing workflows. The last event on the light path before the eye was a diffuse event.
    E G .* L Glossy pass commonly used in conventional compositing workflows. The last event on the light path before the eye was a glossy event.
    E S .* L Specular pass commonly used in conventional compositing workflows. The last event on the light path before the eye was a specular event, i.e., a mirror reflection or specular refraction.
    E D S .* L Diffuse part of caustics cast by a mirror reflection or specular refraction on another surface.
    E .* <L'key'> All direct and indirect light contribution coming from the key light group, which are all lights in the scene with the handle attribute set to key.
    E 'crate' .* L All direct and indirect light falling onto any object in the scene with the handle attribute set to crate.

    The alpha channel of each sample may be transparent (alpha 0) only if the alpha LPE matches the light transport path. Common examples of LPEs for the alpha channel are:

    LP-Expression Description
    E [LmLe] Alpha is based solely on primary visibility. This is the approach used traditionally by many renderers.
    E T* [LmLe] Transmitting objects make the alpha channel transparent. This is the default behavior.
    E <TS>* [LmLe] Only specular transmission makes the alpha channel transparent. This avoids unexpected results in scenes with materials that have a diffuse transmission component.

    The API provides a utility function, mi::neuraylib::IRendering_configuration::make_alpha_expression(), to generate the expressions listed above and mi::neuraylib::IRendering_configuration::make_alpha_mask_expression() to generate alpha mask expressions.

    Note that alpha LPEs operate independently of color LPEs. In particular, the paths that affect the alpha channel of a RGBA canvas are not restricted to those that affect the color channels.

    See LPEs for alpha control for more information on alpha LPEs.

  • alpha or alpha lpexpr= lp-expression

    A Float32 canvas that contains the alpha channel as described above.

  • depth

    A Float32 canvas that contains the depth of the hit point along the (negative) z-coordinate in camera space. The depth is zero at the camera position and extends positive into the scene.

  • distance

    A Float32 canvas that contains the distance between the camera and the hit point measured in camera space. The depth is zero at the camera position and extends positive into the scene. The distance is related to depth by a factor that is the inner product of the (normalized) ray direction and the negative z-axis (0,0,-1).

  • normal

    A Float32<3> canvas that contains the normalized surface shading normal in camera space excluding any effects from normal perturbation functions.

  • texture_coordinate[ i ]

    A Float32<4> canvas that contains the i-th texture coordinate at the hit point, where i is a non-negative integer value.

  • object_id

    A Sint32 canvas that contains the ID for the scene element at the hit point. Each scene element can have an optional attribute named label of type Sint32 which defines this ID. If this scene element is imported from a .mi file, this label can be set using the tag statement in .mi file syntax.

  • material_id

    A Sint32 canvas that contains the user-defined material ID of the material at the hit point. This ID can be used to identify regions in the image that show the same material or regions without material. The latter receive an ID of -1.

  • generated_material_id

    A Sint32 canvas that contains an internal implementation-specific ID of the surface material at the hit point. This ID can be used to identify regions in the image that show the same material or regions without material. The latter receive an ID of 0.

  • diffuse

    A Color canvas that contains the diffuse contribution on first bounce of the rendered image. In terms of light path expressions, this canvas name is a shortcut for lpexpr=E D .* L .

  • specular

    A Color canvas that contains the specular contribution on first bounce of the rendered image, i.e., a mirror reflection or specular refraction. In terms of light path expressions, this canvas name is a shortcut for lpexpr=E S .* L .

  • glossy

    A Color canvas that contains the glossy contribution on first bounce of the rendered image, i.e., all the non-diffuse and non-perfect specular contributions. In terms of light path expressions, this canvas name is a shortcut for lpexpr=E G .* L .

  • emission

    A Color canvas that contains the emission contribution from directly visible light sources and emitting surfaces in the rendered image. In terms of light path expressions, this name is a shortcut for lpexpr=E L .

  • shadow

    A Color canvas that contains the shadow in the scene. More precisely, the canvas contains the light contributions that are missing at a certain point because it is blocked by a some object, the shadow casters. With this definition, adding the shadow canvas to the result canvas removes the shadow. In practice, a weighted version of the shadow buffer can be added; with a small positive weight to lighten the shadow or a small negative weight to darken the shadow.

  • ambient_occlusion

    A Color canvas that contains the ambient occlusion in the scene in the range from 0 (fully occluded) to 1 (not occluded).

  • irradiance or irradiance lpexpr= lp-expression

    A Float32<3> canvas that contains the estimated irradiance at the hit point. The canvas contains black for direct environment hits.

    Like the result canvas, the contents of the irradiance canvas can be restricted to the light transport paths that match lp-expression. Consider using irradiance expressions for this canvas.

  • irradiance_probe or irradiance_probe lpexpr= lp-expression

    A Float32<3> canvas that contains the estimated irradiance at the probe points defined in the mi::neuraylib::IIrradiance_probes container attached to the mi::neuraylib::ICamera.

    Like the result canvas, the contents of the irradiance_probe canvas can be restricted to the light transport paths that match lp-expression. Consider using irradiance expressions for this canvas.