Controls the behavior of the alpha channel.

See also:

make_alpha_mask_expression()

make_alpha_expression()

Adds a filter to the list of custom attribute filters. Custom attribute filters are used to prevent non-predefined attributes on scene elements from causing the render to update when they are created/changed or removed. Please note that only non-predefined attributes will be considered.

Parameters

name_pattern

An extended regular expression that acts as filter on the names of attributes (see [OGBS7]). The regular expression is matched to any part of the attribute name, not just to the entire attribute name.

Returns

• 0: Success.
• -1: Invalid parameters (NULL pointer or empty string).
• -2: The filter already exists or does not denote a valid regular expression.

Adds a path to the list of paths to search for includes. Include paths are currently only used for include statements in .mi files. By default, the list of include paths contains "." as sole entry.

Parameters

path

The path to be added.

Returns

• 0: Success.
• -1: Invalid parameters (NULL pointer).
• -2: Invalid path.

Adds a path to the list of paths to search for MDL modules. This search path is also used for resources referenced in MDL modules. By default, the list of MDL paths is empty.

Parameters

path

The path to be added.

Returns

• 0: Success.
• -1: Invalid parameters (NULL pointer).
• -2: Invalid path.

Adds a path to the list of paths to search for resources, i.e., textures, light profiles, and BSDF measurements. Note that for MDL resources referenced in .mdl files the MDL search paths are considered, not the resource search path. By default, the list of resource paths is empty.

Parameters

path

The path to be added.

Returns

• 0: Success.
• -1: Invalid parameters (NULL pointer).
• -2: Invalid path.

Analyzes a sequence of light path expressions (LPEs). This function inspects the set of expressions for syntactic validity just like check_light_path_expressions. In addition, this function detects overlap between expressions. See mi::neuraylib::ILpe_analysis_result for details.

See also:

Section [:ipmlink reference Light path expression grammar] of the Iray Programmer's Manual.

Parameters

expressions

A static or dynamic array of structures of type "Lpexpr_pair". Such a structure has two members "color" and "alpha" of type mi::IString representing a color and an alpha light path expression, respectively. Empty strings can be used if one of the two members is not needed. The order of the light path expressions matters if an expression re-uses a name assigned to an earlier light path expression.

Returns

An array containing the result of the analysis as described above, or NULL (if expressions is NULL or has an incorrect type).

Checks whether a sequence of light path expressions (LPEs) is valid.

See also:

analyze_light_path_expressions for more extensive checks.

Section [:ipmlink reference Light path expression grammar] of the Iray Programmer's Manual.

Parameters

expressions

A static or dynamic array of structures of type "Lpexpr_pair". Such a structure has two members "color" and "alpha" of type mi::IString representing a color and an alpha light path expression, respectively. Empty strings can be used if one of the two members is not needed. The order of the light path expressions matters if an expression re-uses a name assigned to an earlier light path expression.

Returns

An array containing the error messages (the array is empty if all light path expressions are valid), or NULL (if expressions is NULL or has an incorrect type).

Clears the list of custom attribute filters. Custom attribute filters are used to prevent non-predefined attributes on scene elements from causing the render to update when they are created/changed or removed. Please note that only non-predefined attributes will be considered.

Clears the list of paths to search for includes. Include paths are currently only used for include statements in .mi files. By default, the list of include paths contains "." as sole entry.

Clears the list of paths to search for MDL modules. This search path is also used for resources referenced in MDL modules. By default, the list of MDL paths is empty.

Clears the list of paths to search for resources, i.e., textures, light profiles, and BSDF measurements. Note that for MDL resources referenced in .mdl files the MDL search paths are considered, not the resource search path. By default, the list of resource paths is empty.

Extract color and alpha light path expressions (LPEs) from a canvas name.

See also:

Sections [:ipmlink reference Canvas names] and [:ipmlink reference Light path expression grammar] of the Iray Programmer's Manual.

Parameters

canvas_name

A valid canvas name containing light path expressions.

Returns

A structure of type "Lpexpr_pair" or NULL if name is invalid. Such a structure has two members "color" and "alpha" of type mi::IString representing the color and alpha light path expression from canvas_name , respectively.

Returns if CPU fallback is enabled.

Returns

The currently configured setting.

Returns the index -th custom attribute filter. Custom attribute filters are used to prevent non-predefined attributes on scene elements from causing the render to update when they are created/changed or removed. Please note that only non-predefined attributes will be considered.

Returns

The index -th custom attribute filter, or NULL if index is out of bounds.

Returns the number of configured custom attribute filters. Custom attribute filters are used to prevent non-predefined attributes on scene elements from causing the render to update when they are created/changed or removed. Please note that only non-predefined attributes will be considered.

Returns

The number of currently configured custom attribute filters.

Returns whether the check for the GPU driver version is enabled.

Returns

The currently configured value.

Returns the description of a GPU with a given ID.

See also:

get_highest_gpu_id()

Parameters

gpu_id

The GPU ID. Note that the lowest GPU ID is 1, not 0. The highest ID can be obtained from get_highest_gpu_id(). Note that GPU IDs do not need to be consecutive.

host_id

An optional host ID. If larger than 0, the returned GPU description refers to a GPU installed on the machine with the given host ID, and to the local host otherwise. See mi::neuraylib::INetwork_configuration::register_host_callback() for details about host IDs of other machines in the cluster.

Returns

A description of the GPU with that ID, or NULL if gpu_id is not a valid GPU ID for the host host_id .

Returns if GPU detection is enabled.

Returns

The currently configured setting.

Returns the highest GPU ID.

See also:

get_gpu_description()

Parameters

host_id

An optional host ID. If larger than 0, the returned highest GPU ID refers to the machine with the given host ID, and to the local host otherwise. See mi::neuraylib::INetwork_configuration::register_host_callback() for details about host IDs of other machines in the cluster.

Returns

The highest GPU ID installed on the specified host. The value 0 indicates that no GPUs have been identified on the specified host.

Returns the index -th path to search for includes. Include paths are currently only used for include statements in .mi files. By default, the list of include paths contains "." as sole entry.

Returns

The index -th path, or NULL if index is out of bounds.

Returns the number of paths to search for includes. Include paths are currently only used for include statements in .mi files. By default, the list of include paths contains "." as sole entry.

Returns

The number of currently configured paths.

Returns the index -th path to search for MDL modules. This search path is also used for resources referenced in MDL modules. By default, the list of MDL paths is empty.

Returns

The index -th path, or NULL if index is out of bounds.

Returns the number of paths to search for MDL modules. This search path is also used for resources referenced in MDL modules. By default, the list of MDL paths is empty.

Returns

The number of currently configured paths.

Returns the name of a given render mode.

Parameters

index

The index of the render mode.

Returns

The name of the render mode, or NULL if index is out of bounds or is not running.

Returns the value of a general rendering option.

See also:

set_renderer_option()

Parameters

name

The name of the option.

Returns

The value of the option, or NULL in case of failure, e.g., if there is no such option.

Returns the number of render modes.

Returns

The number of render modes, or 0 if is not running.

Indicates whether a specific resource (GPU or CPU) is enabled or disabled for a render mode. A resource is either a GPU (individually) or all CPUs (together).

This method can only be used while is running.

Parameters

resource_id

The resource in question. This is either a valid GPU ID (see get_gpu_description() for the mapping of GPU IDs to GPUs) or the symbolic constant CPU.

host_id

The host that contains the resource in question. This is either a valid host ID (see mi::neuraylib::INetwork_configuration::register_host_callback() for details about host IDs of other machines in the cluster), or the symbolic constant LOCAL_HOST.

render_mode

The render mode in question.

enable

If true, the resource on that host is enabled for that render mode, otherwise disabled.

Returns

• 0: Success.
• -1: Invalid GPU ID.
• -2: Invalid host ID.
• -3: Invalid render mode.
• -6: The method cannot be called at this point of time.

Returns the index -th path to search for resources, i.e., textures, light profiles, and BSDF measurements. Note that for MDL resources referenced in .mdl files the MDL search paths are considered, not the resource search path. By default, the list of resource paths is empty.

Returns

The index -th path, or NULL if index is out of bounds.

Returns the number of paths to search for resources, i.e., textures, light profiles, and BSDF measurements. Note that for MDL resources referenced in .mdl files the MDL search paths are considered, not the resource search path. By default, the list of resource paths is empty.

Returns

The number of currently configured paths.

Generates a light path expression that controls the alpha channel behavior. This function generates a LPE that may be parsed as an alpha expression to control the behavior of the alpha channel. The resulting expression will apply to the entire image. For object masks, see make_alpha_mask_expression().

See also:

Section [:ipmlink reference Light path expression grammar] of the Iray Programmer's Manual.

Parameters

alpha_mode

The behavior of the alpha channel. See Alpha_mode for details.

Returns

An alpha LPE that may be used to render the desired image.

Generates a light path expression that can be used to render alpha masks. This function generates a LPE that may be parsed as an alpha expression to render masks. Masks may serve to cut out areas of an image for compositing. The generated expression will render a buffer that is opaque for all samples that immediately hit objects with one of the given labels, or, if exclude is active, all other objects. The opaque parts of the image are controlled by the alpha_mode parameter (see Alpha_mode for details).

An empty labels array is not supported. Use make_alpha_expression() instead.

See also:

Section [:ipmlink reference Light path expression grammar] of the Iray Programmer's Manual.

Parameters

labels

A static or dynamic array of strings containing the LPE labels of scene elements that should be selected or excluded.

exclude

If true, generates a mask for objects that are not included in labels.

alpha_mode

The behavior of the alpha channel within the mask region and optional matte shadow behavior. See Alpha_mode for details.

Returns

An alpha LPE that may be used to render the desired mask buffer, or NULL if labels is NULL , the array is empty, or contains elements of the wrong type.

Generates a light path expression that can be used to render color masks. This function generates a LPE that may be parsed as a LPE to render masks. The generated expression will render a buffer that matches the standard result for all samples that immediately hit objects with one of the given labels, or, if exclude is active, all other objects.

See also:

Section [:ipmlink reference Light path expression grammar] of the Iray Programmer's Manual.

Parameters

labels

A static or dynamic array of strings containing the LPE labels of scene elements that should be selected or excluded.

exclude

If true, generates a mask for objects that are not included in labels.

Returns

A LPE that may be used to render the desired mask buffer, or NULL if labels is NULL , the array is empty, or contains elements of the wrong type.

Creates canvas parameters from a canvas names. This function is intended to ease transition from name based render targets to the new interface. Note that this function only accepts the names listed in Section [:ipmlink reference Canvas names] of the Iray Programmer's Manual.

This function returns nullptr for invalid names.

Creates a canvas name from the provided parameters. This function is intended to ease transition from name based render targets to the new interface. It serves as the inverse to map_canvas_name. Note, however, that this function cannot encode all possible parameter blocks into strings and will only generate canvas names that are valid as per Section [:ipmlink reference Canvas names] of the Iray Programmer's Manual.

Also note that this function will not generate canvas names like "diffuse", which are just a shorthand notation for "result lpexpr=L.*DE"

Creates a canvas name for the provided type. This function is a simplified version of map_canvas_parameters which only maps the type without any additional data. This will generate canvas names without LPEs or indices.

Removes a filter from the list of custom attribute filters. Custom attribute filters are used to prevent non-predefined attributes on scene elements from causing the render to update when they are created/changed or removed. Please note that only non-predefined attributes will be considered.

Parameters

name_pattern

The filter to be removed.

Returns

• 0: Success.
• -1: Invalid parameters (NULL pointer).
• -2: There is no such filter in the filter list.

Removes a path from the list of paths to search for includes. Include paths are currently only used for include statements in .mi files. By default, the list of include paths contains "." as sole entry.

Parameters

path

The path to be removed.

Returns

• 0: Success.
• -1: Invalid parameters (NULL pointer).
• -2: There is no such path in the path list.

Removes a path from the list of paths to search for MDL modules. This search path is also used for resources referenced in MDL modules. By default, the list of MDL paths is empty.

Parameters

path

The path to be removed.

Returns

• 0: Success.
• -1: Invalid parameters (NULL pointer).
• -2: There is no such path in the path list.

Removes a path from the list of paths to search for resources, i.e., textures, light profiles, and BSDF measurements. Note that for MDL resources referenced in .mdl files the MDL search paths are considered, not the resource search path. By default, the list of resource paths is empty.

Parameters

path

The path to be removed.

Returns

• 0: Success.
• -1: Invalid parameters (NULL pointer).
• -2: There is no such path in the path list.

Enables or disables CPU fallback. By default, CPU fallback is enabled. If GPUs fail during init or rendering then the CPU is allowed to take over instead of failing the rendering process.

This can only be configured before has been started.

Parameters

value

true if CPU fallback enabled, false otherwise.

Returns

0, in case of success, -1 in case of failure.

Enables or disables the check for the GPU driver version. This can only be configured before has been started.

Parameters

value

true to enable the check (the default), false to disable it

Returns

• 0: Success.
• -1: The method cannot be called at this point of time.

Enables or disables GPU detection. By default, GPU detection is enabled. GPU detection can be disabled in case it causes problems (hangs, crashes) or GPU usage is not desired at all.

This can only be configured before has been started.

Parameters

value

true if GPUs are to be detected, false otherwise.

Returns

0, in case of success, -1 in case of failure.

Sets the value of a general rendering option. There are three different types of options:

• scene-specific options (see mi::neuraylib::IOptions),

• render context-specific options (see mi::neuraylib::IRender_context::set_option()), and

• general rendering options (independent of the scene or the render context). For all three types there might be options that are common to all render modes as well as options specific for a certain render mode.

This method deals with the last of the three types. Currently, there are no options common for all render modes. See the documentation of the render mode in question for render mode-specific options.

Parameters

name

The name of the option to be set.

value

The value of the option to be set.

Returns

• 0: Success.
• -1: name is invalid.
• -2: value is invalid.
• -3: The option can not be set at this point in time, e.g., some options can only be set before has been started.

Enables or disables a specific resource (GPU or CPU) for a render mode. A resource is either a GPU (individually) or all CPUs (together).

This method can only be used while is running.

Parameters

resource_id

The resource in question. This is either a valid GPU ID (see get_gpu_description() for the mapping of IDs to GPUs), or one of the symbolic constants CPU and ALL_GPUS.

host_id

The host that contains the resource in question. This is either a valid host ID (see mi::neuraylib::INetwork_configuration::register_host_callback() for details about host IDs of other machines in the cluster), or one of the symbolic constants LOCAL_HOST and ALL_HOSTS.

render_mode

The render mode that will be affected. The value NULL can be used to affect all render mode.

enable

If true, the resource on that host will be enabled for that render mode, otherwise disabled.

Returns

• 0: Success.
• -1: Invalid GPU ID.
• -2: Invalid host ID.
• -3: Invalid render mode.
• -4: Changing the resource status at this time is not supported.
• -5: The render mode cannot make use of this resource (only possible if enable is true).
• -6: The method cannot be called at this point of time.

Symbolic constant to refer to all GPUs on a particular host.

See also:

set_resource_enabled()

Symbolic constant to refer to all hosts in the cluster.

See also:

set_resource_enabled()

Symbolic constant to refer to the CPU on a particular host. All CPU cores on a particular host are treated as a single resource which is referred to in this context as the CPU.

See also:

set_resource_enabled(), get_resource_enabled()

Symbolic constant to refer to the local host in the cluster.

See also:

set_resource_enabled(), get_resource_enabled()