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

Inheritance diagram for mi::neuraylib::IRendering_configuration:

Public Types
enum	Alpha_mode { ALPHA_PRIMARY = 0, ALPHA_TRANSMIT = 1, ALPHA_TRANSMIT_SPECULAR = 2 }
	Controls the behavior of the alpha channel. More...

Public Types inherited from mi::base::Interface_declare< 0x8e148c6e, 0x3515, 0x4368, 0xba, 0xb7, 0x97, 0xfd, 0x26, 0x35, 0xbb, 0x91 >
typedef Interface_declare< id1, id2, id3, id4, id5, id6, id7, id8, id9, id10, id11, IInterface >	Self
	Own type. More...

typedef Uuid_t< id1, id2, id3, id4, id5, id6, id7, id8, id9, id10, id11 >	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...

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

Render modes
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...

GPUs
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_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 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 Uint32	get_highest_gpu_id (Uint32 host_id=0)=0
	Returns the highest GPU 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...

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

Static Public Attributes
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...

Additional Inherited Members
Static Public Member Functions inherited from mi::base::Interface_declare< 0x8e148c6e, 0x3515, 0x4368, 0xba, 0xb7, 0x97, 0xfd, 0x26, 0x35, 0xbb, 0x91 >
static bool	compare_iid (const Uuid &iid)
	Compares the interface ID `iid` against the interface ID of this interface and of its ancestors. More...

Detailed Description

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

Member Enumeration Documentation

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.

Member Function Documentation

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, in case of success, -1 in case of failure.

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 contains "." as sole entry.

Parameters

path	The path to be added.

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

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 before the resource search paths are considered. By default, the list of resource paths contains "." as sole entry.

Parameters

path	The path to be added.

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

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: Section Light path expression grammar of the Iray Programmer's Manual.

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.

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 contains "." as sole entry.

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 before the resource search paths are considered. By default, the list of resource paths contains "." as sole entry.

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 in render targets and Light path expression grammar of the Iray Programmer's Manual.

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.

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.

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

pure virtual

Returns if GPU detection is enabled.

Returns: The currently configured setting.

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 GPU description refers to a GPU installed on the machine with the given host ID, and to the local host otherwise.

Returns: The highest GPU ID installed on the specified host.

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.

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.

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 contains "." as sole entry.

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

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 contains "." as sole entry.

Returns: The number of currently configured paths.

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

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.

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

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

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 before the resource search paths are considered. By default, the list of resource paths contains "." as sole entry.

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

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 before the resource search paths are considered. By default, the list of resource paths contains "." as sole entry.

Returns: The number of currently configured paths.

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.

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

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

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.

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, in case of success, -1 in case of failure.

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 contains "." as sole entry.

Parameters

path	The path to be removed.

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

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 before the resource search paths are considered. By default, the list of resource paths contains "." as sole entry.

Parameters

path	The path to be removed.

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

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

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

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

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