neuray API Programmer's Manual

mi::neuraylib::IRendering_configuration Class Reference

[Configuration Interfaces]

Description

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

mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. The basic extensible interface.The basic extensible interface.

Public Enumerations

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

Static Public Variables

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 CPU = 0xffffffff
Symbolic constant to refer to the CPU on a particular host. More...
static const Uint32 LOCAL_HOST = 0
Symbolic constant to refer to the local host in the cluster. More...

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 void clear_mdl_paths() =0
Clears the list 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...
virtual Size get_mdl_paths_length() const =0
Returns the number 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...

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 void clear_resource_paths() =0
Clears the list 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...
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 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...

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 void clear_include_paths() =0
Clears the list 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 Size get_include_paths_length() const =0
Returns the number 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...

Render modes

virtual const char* get_renderer( Uint32 index) const =0
Returns the name of a given render mode. More...
virtual const IString* get_renderer_option( const char* name) const =0
Returns the value of a general rendering option. More...
virtual Uint32 get_renderers_length() const =0
Returns the number of render modes. More...
virtual Sint32 set_renderer_option( const char* name, const char* value) =0
Sets the value of a general rendering option. More...

GPUs

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 bool  get_gpu_enabled() const =0
Returns if GPU detection is enabled. More...
virtual Uint32 get_highest_gpu_id( Uint32 host_id = 0) =0
Returns the highest GPU ID. 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...
virtual Sint32 set_driver_version_check_enabled( bool value) =0
Enables or disables the check for the GPU driver version. More...
virtual Sint32 set_gpu_enabled( bool value) =0
Enables or disables GPU detection. 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...

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

Enums

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 = 0
Alpha value is based on primary visibility.
ALPHA_TRANSMIT = 1
Alpha is transparent for paths that transmit the environment.
ALPHA_TRANSMIT_SPECULAR = 2
Alpha is transparent for paths that transmit the environment specularly.
ALPHA_MODE_FORCE_32_BIT = 0xffffffffU

Member Functions

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.

Note:

Not all render modes support all valid light path expressions.

See also:

Section [:ipmlink light_path_expressions 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).

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.

See also:

Sections [:ipmlink canvas_names_in_render_targets Canvas names in render targets] and [:ipmlink light_path_expressions 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.

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

Note:

Not all render modes support all valid light path expressions.

See also:

Section [:ipmlink light_path_expressions 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.

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

Note:

Not all render modes support all valid light path expressions.

See also:

Section [:ipmlink light_path_expressions 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. 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.

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.

Note:

Not all render modes support all valid light path expressions.

See also:

Section [:ipmlink light_path_expressions 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.

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

Variables

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

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

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

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