This interface is used to query and change the rendering configuration. More...

#include <irendering_configuration.h>

Inheritance diagram for mi::neuraylib::IRendering_configuration:

Public Member Functions
MDL paths
virtual Sint32	add_mdl_path (const char *path)=0
	Adds a path to the list of paths to search for MDL modules. More...

virtual Sint32	remove_mdl_path (const char *path)=0
	Removes a path from the list of paths to search for MDL modules. More...

virtual void	clear_mdl_paths ()=0
	Clears the list of paths to search for MDL modules. More...

virtual Size	get_mdl_paths_length () const =0
	Returns the number of paths to search for MDL modules. More...

virtual const IString *	get_mdl_path (Size index) const =0
	Returns the `index` -th path to search for MDL modules. More...

Resource paths
virtual Sint32	add_resource_path (const char *path)=0
	Adds a path to the list of paths to search for resources, i.e., textures, light profiles, and BSDF measurements. More...

virtual Sint32	remove_resource_path (const char *path)=0
	Removes a path from the list of paths to search for resources, i.e., textures, light profiles, and BSDF measurements. More...

virtual void	clear_resource_paths ()=0
	Clears the list of paths to search for resources, i.e., textures, light profiles, and BSDF measurements. More...

virtual Size	get_resource_paths_length () const =0
	Returns the number of paths to search for resources, i.e., textures, light profiles, and BSDF measurements. More...

virtual const IString *	get_resource_path (Size index) const =0
	Returns the `index` -th path to search for resources, i.e., textures, light profiles, and BSDF measurements. More...

Include paths
virtual Sint32	add_include_path (const char *path)=0
	Adds a path to the list of paths to search for includes. More...

virtual Sint32	remove_include_path (const char *path)=0
	Removes a path from the list of paths to search for includes. More...

virtual void	clear_include_paths ()=0
	Clears the list of paths to search for includes. More...

virtual Size	get_include_paths_length () const =0
	Returns the number of paths to search for includes. More...

virtual const IString *	get_include_path (Size index) const =0
	Returns the `index` -th path to search for includes. More...

virtual Sint32	add_custom_attribute_filter (const char *name_pattern)=0
	Adds a filter to the list of custom attribute filters. More...

virtual Sint32	remove_custom_attribute_filter (const char *name_pattern)=0
	Removes a filter from the list of custom attribute filters. More...

virtual void	clear_custom_attribute_filters ()=0
	Clears the list of custom attribute filters. More...

virtual Size	get_custom_attribute_filter_length () const =0
	Returns the number of configured custom attribute filters. More...

virtual const char *	get_custom_attribute_filter (Size index) const =0
	Returns the `index` -th custom attribute filter. More...

Light path expressions
virtual const ILpe_check_result *	check_light_path_expressions (const IArray *expressions) const =0
	Checks whether a sequence of light path expressions (LPEs) is valid. More...

virtual const IStructure *	extract_light_path_expressions_from_name (const char *canvas_name) const =0
	Extract color and alpha light path expressions (LPEs) from a canvas name. More...

virtual const IString *	make_alpha_expression (Alpha_mode alpha_mode) const =0
	Generates a light path expression that controls the alpha channel behavior. More...

virtual const IString *	make_alpha_mask_expression (const IArray *labels, bool exclude, Alpha_mode alpha_mode) const =0
	Generates a light path expression that can be used to render alpha masks. More...

virtual const IString *	make_color_mask_expression (const IArray *labels, bool exclude) const =0
	Generates a light path expression that can be used to render color masks. More...

virtual const ILpe_analysis_result *	analyze_light_path_expressions (const IArray *expressions) const =0
	Analyzes a sequence of light path expressions (LPEs). More...

virtual ICanvas_parameters *	map_canvas_name (const char *name) const =0
	Creates canvas parameters from a canvas names. More...

virtual IString *	map_canvas_parameters (const ICanvas_parameters *) const =0
	Creates a canvas name from the provided parameters. More...

virtual const char *	map_canvas_type (Canvas_type) const =0
	Creates a canvas name for the provided type. More...

Public Member Functions inherited from mi::base::IInterface
virtual Uint32	retain () const =0
	Increments the reference count. More...

virtual Uint32	release () const =0
	Decrements the reference count. More...

virtual const IInterface *	get_interface (const Uuid &interface_id) const =0
	Acquires a const interface from another. More...

template<class T>
const T *	get_interface () const
	Acquires a const interface from another. More...

virtual IInterface *	get_interface (const Uuid &interface_id)=0
	Acquires a mutable interface from another. More...

template<class T>
T *	get_interface ()
	Acquires a mutable interface from another. More...

virtual Uuid	get_iid () const =0
	Returns the interface ID of the most derived interface. More...

GPUs
enum	Alpha_mode { ALPHA_PRIMARY = 0x00u , ALPHA_TRANSMIT = 0x01u , ALPHA_TRANSMIT_SPECULAR = 0x02u , ALPHA_NONE = 0x03u , ALPHA_MODE_MASK = 0x0fu , ALPHA_MATTE_SHADOW = 0x10u , ALPHA_MODE_FORCE_32_BIT = 0xffffffffU }
	Controls the behavior of the alpha channel. More...

virtual Sint32	set_gpu_enabled (bool value)=0
	Enables or disables GPU detection. More...

virtual bool	get_gpu_enabled () const =0
	Returns if GPU detection is enabled. More...

virtual Sint32	set_cpu_fallback_enabled (bool value)=0
	Enables or disables CPU fallback. More...

virtual bool	get_cpu_fallback_enabled () const =0
	Returns if CPU fallback is enabled. More...

virtual Sint32	set_driver_version_check_enabled (bool value)=0
	Enables or disables the check for the GPU driver version. More...

virtual bool	get_driver_version_check_enabled () const =0
	Returns whether the check for the GPU driver version is enabled. More...

virtual Uint32	get_highest_gpu_id (Uint32 host_id=0)=0
	Returns the highest GPU ID. More...

virtual const IGpu_description *	get_gpu_description (Uint32 gpu_id, Uint32 host_id=0)=0
	Returns the description of a GPU with a given ID. More...

virtual Sint32	set_resource_enabled (Uint32 resource_id, Uint32 host_id, const char *render_mode, bool enable)=0
	Enables or disables a specific resource (GPU or CPU) for a render mode. More...

virtual Sint32	get_resource_enabled (Uint32 resource_id, Uint32 host_id, const char *render_mode, bool &enable)=0
	Indicates whether a specific resource (GPU or CPU) is enabled or disabled for a render mode. More...

Render modes
static const Uint32	CPU = 0xffffffff
	Symbolic constant to refer to the CPU on a particular host. More...

static const Uint32	ALL_GPUS = 0xfffffffe
	Symbolic constant to refer to all GPUs on a particular host. More...

static const Uint32	ALL_HOSTS = 0xfffffffd
	Symbolic constant to refer to all hosts in the cluster. More...

static const Uint32	LOCAL_HOST = 0
	Symbolic constant to refer to the local host in the cluster. More...

virtual Uint32	get_renderers_length () const =0
	Returns the number of render modes. More...

virtual const char *	get_renderer (Uint32 index) const =0
	Returns the name of a given render mode. More...

virtual Sint32	set_renderer_option (const char name, const char value)=0
	Sets the value of a general rendering option. More...

virtual const IString *	get_renderer_option (const char *name) const =0
	Returns the value of a general rendering option. More...

Additional Inherited Members
Public Types inherited from mi::base::Interface_declare< 0x8e148c6e, ... >
typedef Interface_declare< id1, ... >	Self
	Own type. More...

typedef Uuid_t< id1, ... >	IID
	Declares the interface ID (IID) of this interface. More...

Public Types inherited from mi::base::IInterface
typedef Uuid_t<0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0>	IID
	Declares the interface ID (IID) of this interface. More...

Static Public Member Functions inherited from mi::base::Interface_declare< 0x8e148c6e, ... >
static bool	compare_iid (const Uuid &iid)
	Compares the interface ID `iid` against the interface ID of this interface and of its ancestors. More...

Static Public Member Functions inherited from mi::base::IInterface
static bool	compare_iid (const Uuid &iid)
	Compares the interface ID `iid` against the interface ID of this interface. More...

Detailed Description

This interface is used to query and change the rendering configuration.

Member Enumeration Documentation

^◆ Alpha_mode

enum mi::neuraylib::IRendering_configuration::Alpha_mode

Controls the behavior of the alpha channel.

See also: make_alpha_mask_expression(); make_alpha_expression()

Enumerator
ALPHA_PRIMARY	Alpha value is based on primary visibility.
ALPHA_TRANSMIT	Alpha is transparent for paths that transmit the environment.
ALPHA_TRANSMIT_SPECULAR	Alpha is transparent for paths that transmit the environment specularly.
ALPHA_NONE	Alpha is transparent everywhere. Primarily useful together with ALPHA_MATTE_SHADOW.
ALPHA_MODE_MASK	Mask for primary modes.
ALPHA_MATTE_SHADOW	In combination with the primary modes: shadows on matte objects affect the alpha channel. If this bit is set, shadows on matte objects will make the alpha channel opaque.

Member Function Documentation

^◆ add_custom_attribute_filter()

virtual Sint32 mi::neuraylib::IRendering_configuration::add_custom_attribute_filter ( const char * name_pattern )

pure virtual

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.

^◆ add_include_path()

virtual Sint32 mi::neuraylib::IRendering_configuration::add_include_path ( const char * path )

pure virtual

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.

^◆ add_mdl_path()

virtual Sint32 mi::neuraylib::IRendering_configuration::add_mdl_path ( const char * path )

pure virtual

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.

^◆ add_resource_path()

virtual Sint32 mi::neuraylib::IRendering_configuration::add_resource_path ( const char * path )

pure virtual

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.

^◆ analyze_light_path_expressions()

virtual const ILpe_analysis_result * mi::neuraylib::IRendering_configuration::analyze_light_path_expressions ( const IArray * expressions ) const

pure virtual

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.

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

See also: Section "Light path expression grammar" of the Iray Programmer's Manual.

^◆ check_light_path_expressions()

virtual const ILpe_check_result * mi::neuraylib::IRendering_configuration::check_light_path_expressions ( const IArray * expressions ) const

pure virtual

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

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

Note: Not all render modes support all valid light path expressions.

See also: analyze_light_path_expressions for more extensive checks.; Section "Light path expression grammar" of the Iray Programmer's Manual.

^◆ clear_custom_attribute_filters()

virtual void mi::neuraylib::IRendering_configuration::clear_custom_attribute_filters ( )

pure virtual

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.

^◆ clear_include_paths()

virtual void mi::neuraylib::IRendering_configuration::clear_include_paths ( )

pure virtual

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.

^◆ clear_mdl_paths()

virtual void mi::neuraylib::IRendering_configuration::clear_mdl_paths ( )

pure virtual

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.

^◆ clear_resource_paths()

virtual void mi::neuraylib::IRendering_configuration::clear_resource_paths ( )

pure virtual

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_light_path_expressions_from_name()

virtual const IStructure * mi::neuraylib::IRendering_configuration::extract_light_path_expressions_from_name ( const char * canvas_name ) const

pure virtual

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

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.

See also: Sections "Canvas names" and "Light path expression grammar" of the Iray Programmer's Manual.

^◆ get_cpu_fallback_enabled()

virtual bool mi::neuraylib::IRendering_configuration::get_cpu_fallback_enabled ( ) const

pure virtual

Returns if CPU fallback is enabled.

Returns: The currently configured setting.

^◆ get_custom_attribute_filter()

virtual const char * mi::neuraylib::IRendering_configuration::get_custom_attribute_filter ( Size index ) const

pure virtual

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.

^◆ get_custom_attribute_filter_length()

virtual Size mi::neuraylib::IRendering_configuration::get_custom_attribute_filter_length ( ) const

pure virtual

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.

^◆ get_driver_version_check_enabled()

virtual bool mi::neuraylib::IRendering_configuration::get_driver_version_check_enabled ( ) const

pure virtual

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

Returns: The currently configured value.

^◆ get_gpu_description()

virtual const IGpu_description * mi::neuraylib::IRendering_configuration::get_gpu_description	(	Uint32	gpu_id,
		Uint32	host_id = `0`
	)

pure virtual

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.

^◆ get_gpu_enabled()

virtual bool mi::neuraylib::IRendering_configuration::get_gpu_enabled ( ) const

pure virtual

Returns if GPU detection is enabled.

Returns: The currently configured setting.

^◆ get_highest_gpu_id()

virtual Uint32 mi::neuraylib::IRendering_configuration::get_highest_gpu_id ( Uint32 host_id = 0 )

pure virtual

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.

^◆ get_include_path()

virtual const IString * mi::neuraylib::IRendering_configuration::get_include_path ( Size index ) const

pure virtual

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.

^◆ get_include_paths_length()

virtual Size mi::neuraylib::IRendering_configuration::get_include_paths_length ( ) const

pure virtual

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.

^◆ get_mdl_path()

virtual const IString * mi::neuraylib::IRendering_configuration::get_mdl_path ( Size index ) const

pure virtual

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.

^◆ get_mdl_paths_length()

virtual Size mi::neuraylib::IRendering_configuration::get_mdl_paths_length ( ) const

pure virtual

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.

^◆ get_renderer()

virtual const char * mi::neuraylib::IRendering_configuration::get_renderer ( Uint32 index ) const

pure virtual

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 the Iray SDK is not running.

^◆ get_renderer_option()

virtual const IString * mi::neuraylib::IRendering_configuration::get_renderer_option ( const char * name ) const

pure virtual

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.

^◆ get_renderers_length()

virtual Uint32 mi::neuraylib::IRendering_configuration::get_renderers_length ( ) const

pure virtual

Returns the number of render modes.

Returns: The number of render modes, or 0 if the Iray SDK is not running.

^◆ get_resource_enabled()

virtual Sint32 mi::neuraylib::IRendering_configuration::get_resource_enabled	(	Uint32	resource_id,
		Uint32	host_id,
		const char *	render_mode,
		bool &	enable
	)

pure virtual

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 the Iray SDK 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.

^◆ get_resource_path()

virtual const IString * mi::neuraylib::IRendering_configuration::get_resource_path ( Size index ) const

pure virtual

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.

^◆ get_resource_paths_length()

virtual Size mi::neuraylib::IRendering_configuration::get_resource_paths_length ( ) const

pure virtual

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.

^◆ make_alpha_expression()

virtual const IString * mi::neuraylib::IRendering_configuration::make_alpha_expression ( Alpha_mode alpha_mode ) const

pure virtual

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().

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.

Note: Not all render modes support all valid light path expressions.

See also: Section "Light path expression grammar" of the Iray Programmer's Manual.

^◆ make_alpha_mask_expression()

virtual const IString * mi::neuraylib::IRendering_configuration::make_alpha_mask_expression	(	const IArray *	labels,
		bool	exclude,
		Alpha_mode	alpha_mode
	)		const

pure virtual

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.

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.

Note: Not all render modes support all valid light path expressions.

See also: Section "Light path expression grammar" of the Iray Programmer's Manual.

^◆ make_color_mask_expression()

virtual const IString * mi::neuraylib::IRendering_configuration::make_color_mask_expression	(	const IArray *	labels,
		bool	exclude
	)		const

pure virtual

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.

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.

Note: Not all render modes support all valid light path expressions.

See also: Section "Light path expression grammar" of the Iray Programmer's Manual.

^◆ map_canvas_name()

virtual ICanvas_parameters * mi::neuraylib::IRendering_configuration::map_canvas_name ( const char * name ) const

pure virtual

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 "Canvas names" of the Iray Programmer's Manual.

This function returns nullptr for invalid names.

^◆ map_canvas_parameters()

virtual IString * mi::neuraylib::IRendering_configuration::map_canvas_parameters ( const ICanvas_parameters * ) const

pure virtual

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 "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"

^◆ map_canvas_type()

virtual const char * mi::neuraylib::IRendering_configuration::map_canvas_type ( Canvas_type ) const

pure virtual

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.

^◆ remove_custom_attribute_filter()

virtual Sint32 mi::neuraylib::IRendering_configuration::remove_custom_attribute_filter ( const char * name_pattern )

pure virtual

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.

^◆ remove_include_path()

virtual Sint32 mi::neuraylib::IRendering_configuration::remove_include_path ( const char * path )

pure virtual

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.

^◆ remove_mdl_path()

virtual Sint32 mi::neuraylib::IRendering_configuration::remove_mdl_path ( const char * path )

pure virtual

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.

^◆ remove_resource_path()

virtual Sint32 mi::neuraylib::IRendering_configuration::remove_resource_path ( const char * path )

pure virtual

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.

^◆ set_cpu_fallback_enabled()

virtual Sint32 mi::neuraylib::IRendering_configuration::set_cpu_fallback_enabled ( bool value )

pure virtual

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 the Iray SDK has been started.

Parameters

value true if CPU fallback enabled, false otherwise.

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

^◆ set_driver_version_check_enabled()

virtual Sint32 mi::neuraylib::IRendering_configuration::set_driver_version_check_enabled ( bool value )

pure virtual

Enables or disables the check for the GPU driver version.

This can only be configured before the Iray SDK 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.

^◆ set_gpu_enabled()

virtual Sint32 mi::neuraylib::IRendering_configuration::set_gpu_enabled ( bool value )

pure virtual

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 the Iray SDK 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.

^◆ set_renderer_option()

virtual Sint32 mi::neuraylib::IRendering_configuration::set_renderer_option	(	const char *	name,
		const char *	value
	)

pure virtual

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 the Iray SDK has been started.

^◆ set_resource_enabled()

virtual Sint32 mi::neuraylib::IRendering_configuration::set_resource_enabled	(	Uint32	resource_id,
		Uint32	host_id,
		const char *	render_mode,
		bool	enable
	)

pure virtual

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 the Iray SDK 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.

Member Data Documentation

^◆ ALL_GPUS

const Uint32 mi::neuraylib::IRendering_configuration::ALL_GPUS = 0xfffffffe

static

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

See also: set_resource_enabled()

^◆ ALL_HOSTS

const Uint32 mi::neuraylib::IRendering_configuration::ALL_HOSTS = 0xfffffffd

static

Symbolic constant to refer to all hosts in the cluster.

See also: set_resource_enabled()

^◆ CPU

const Uint32 mi::neuraylib::IRendering_configuration::CPU = 0xffffffff

static

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()

^◆ LOCAL_HOST

const Uint32 mi::neuraylib::IRendering_configuration::LOCAL_HOST = 0

static

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

See also: set_resource_enabled(), get_resource_enabled()

Public Member Functions

GPUs

Render modes

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ Alpha_mode

Member Function Documentation

◆ add_custom_attribute_filter()

◆ add_include_path()

◆ add_mdl_path()

◆ add_resource_path()

◆ analyze_light_path_expressions()

◆ check_light_path_expressions()

◆ clear_custom_attribute_filters()

◆ clear_include_paths()

◆ clear_mdl_paths()

◆ clear_resource_paths()

◆ extract_light_path_expressions_from_name()

◆ get_cpu_fallback_enabled()

◆ get_custom_attribute_filter()

◆ get_custom_attribute_filter_length()

◆ get_driver_version_check_enabled()

◆ get_gpu_description()

◆ get_gpu_enabled()

◆ get_highest_gpu_id()

◆ get_include_path()

◆ get_include_paths_length()

◆ get_mdl_path()

◆ get_mdl_paths_length()

◆ get_renderer()

◆ get_renderer_option()

◆ get_renderers_length()

◆ get_resource_enabled()

◆ get_resource_path()

◆ get_resource_paths_length()

◆ make_alpha_expression()

◆ make_alpha_mask_expression()

◆ make_color_mask_expression()

◆ map_canvas_name()

◆ map_canvas_parameters()

◆ map_canvas_type()

◆ remove_custom_attribute_filter()

◆ remove_include_path()

◆ remove_mdl_path()

◆ remove_resource_path()

◆ set_cpu_fallback_enabled()

◆ set_driver_version_check_enabled()

◆ set_gpu_enabled()

◆ set_renderer_option()

◆ set_resource_enabled()

Member Data Documentation

◆ ALL_GPUS

◆ ALL_HOSTS

◆ CPU

◆ LOCAL_HOST

^◆ Alpha_mode

^◆ add_custom_attribute_filter()

^◆ add_include_path()

^◆ add_mdl_path()

^◆ add_resource_path()

^◆ analyze_light_path_expressions()

^◆ check_light_path_expressions()

^◆ clear_custom_attribute_filters()

^◆ clear_include_paths()

^◆ clear_mdl_paths()

^◆ clear_resource_paths()

^◆ extract_light_path_expressions_from_name()

^◆ get_cpu_fallback_enabled()

^◆ get_custom_attribute_filter()

^◆ get_custom_attribute_filter_length()

^◆ get_driver_version_check_enabled()

^◆ get_gpu_description()

^◆ get_gpu_enabled()

^◆ get_highest_gpu_id()

^◆ get_include_path()

^◆ get_include_paths_length()

^◆ get_mdl_path()

^◆ get_mdl_paths_length()

^◆ get_renderer()

^◆ get_renderer_option()

^◆ get_renderers_length()

^◆ get_resource_enabled()

^◆ get_resource_path()

^◆ get_resource_paths_length()

^◆ make_alpha_expression()

^◆ make_alpha_mask_expression()

^◆ make_color_mask_expression()

^◆ map_canvas_name()

^◆ map_canvas_parameters()

^◆ map_canvas_type()

^◆ remove_custom_attribute_filter()

^◆ remove_include_path()

^◆ remove_mdl_path()

^◆ remove_resource_path()

^◆ set_cpu_fallback_enabled()

^◆ set_driver_version_check_enabled()

^◆ set_gpu_enabled()

^◆ set_renderer_option()

^◆ set_resource_enabled()

^◆ ALL_GPUS

^◆ ALL_HOSTS

^◆ CPU

^◆ LOCAL_HOST