neuray API Programmer's Manual

mi::neuraylib::IMdl_configuration Class Reference

[Configuration Interfaces]

Description

This interface can be used to query and change the MDL configuration.

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

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...
void add_mdl_system_paths()
Adds the MDL system paths to the MDL search path.
void add_mdl_user_paths()
Adds the MDL user paths to the MDL search path.
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 const char* get_mdl_system_path( Size index) const =0
Returns the index -th path in the MDL system paths. More...
virtual Size get_mdl_system_paths_length() const =0
Returns the number of MDL system paths.
virtual const char* get_mdl_user_path( Size index) const =0
Returns the index -th path in the MDL user paths. More...
virtual Size get_mdl_user_paths_length() const =0
Returns the number of MDL user paths.
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...

Miscellaneous settings

virtual bool  get_expose_names_of_let_expressions() const =0
Indicates whether an attempt is made to expose names of let expressions. More...
virtual bool  get_implicit_cast_enabled() const =0
Indicates whether the SDK is supposed to automatically insert the cast operator for compatible types. More...
virtual bool  get_simple_glossy_bsdf_legacy_enabled() const =0
Returns true if the legacy behavior for bsdfs of type df::simple_glossy_bsdf() used in MDL modules with versions smaller that 1.3 is enabled, false otherwise.
virtual Sint32 set_expose_names_of_let_expressions( bool value) =0
Defines whether an attempt is made to expose names of let expressions. More...
virtual Sint32 set_implicit_cast_enabled( bool value) =0
Defines whether a cast operator is automatically inserted for compatible argument types. More...
virtual Sint32 set_simple_glossy_bsdf_legacy_enabled( bool value) =0
Configures the behavior of df::simple_glossy_bsdf() in MDL modules of versions smaller than 1.3. More...

Entity resolver

virtual IMdl_entity_resolver* get_entity_resolver() const =0
Returns an instance of the built-in entity resolver. More...
virtual void set_entity_resolver( IMdl_entity_resolver* resolver) =0
Installs an external entity resolver. More...

Miscellaneous settings

virtual IType::​Modifier get_material_ior_frequency() const =0
Returns the frequency of the material.ior field. More...
virtual Sint32 set_material_ior_frequency( IType::​Modifier frequency_qualifier) =0
Sets the frequency of the material.ior field. More...

Member Functions

virtual Sint32 mi::​neuraylib::​IMdl_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.

void mi::​neuraylib::​IMdl_configuration::add_mdl_system_paths() [inline]

Adds the MDL system paths to the MDL search path.

void mi::​neuraylib::​IMdl_configuration::add_mdl_user_paths() [inline]

Adds the MDL user paths to the MDL search path.

virtual Sint32 mi::​neuraylib::​IMdl_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.

virtual void mi::​neuraylib::​IMdl_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.

virtual void mi::​neuraylib::​IMdl_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.

virtual IMdl_entity_resolver* mi::​neuraylib::​IMdl_configuration::get_entity_resolver() const [pure virtual]

Returns an instance of the built-in entity resolver.

Note:

  • The returned instance contains a copy of the currently configured search paths, subsequent changes to the search paths are not reflected in this instance.

  • The built-in entity resolver is only available after has been started.

virtual bool mi::​neuraylib::​IMdl_configuration::get_expose_names_of_let_expressions() const [pure virtual]

Indicates whether an attempt is made to expose names of let expressions.

See also:

set_expose_names_of_let_expressions()

virtual bool mi::​neuraylib::​IMdl_configuration::get_implicit_cast_enabled() const [pure virtual]

Indicates whether the SDK is supposed to automatically insert the cast operator for compatible types.

See also:

set_implicit_cast_enabled()

virtual IType::​Modifier mi::​neuraylib::​IMdl_configuration::get_material_ior_frequency() const [pure virtual]

Returns the frequency of the material.ior field. Returns either mi::neuraylib::IType::MK_VARYING or mi::neuraylib::IType::MK_UNIFORM.

virtual const IString* mi::​neuraylib::​IMdl_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.

virtual Size mi::​neuraylib::​IMdl_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.

virtual const char* mi::​neuraylib::​IMdl_configuration::get_mdl_system_path( Size index) const [pure virtual]

Returns the index -th path in the MDL system paths. The default MDL system path is

  • %PROGRAMDATA%\NVIDIA Corporation\mdl (on Windows),

  • /opt/nvidia/mdl (on Linux), and

  • /Library/Application Support/NVIDIA Corporation/mdl (on Mac OS).

The MDL system paths can be changed via the environment variable MDL_SYSTEM_PATH. The environment variable can contain multiple paths which are separated by semicolons (on Windows) or colons (on Linux and Mac OS), respectively.

Returns

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

virtual Size mi::​neuraylib::​IMdl_configuration::get_mdl_system_paths_length() const [pure virtual]

Returns the number of MDL system paths.

virtual const char* mi::​neuraylib::​IMdl_configuration::get_mdl_user_path( Size index) const [pure virtual]

Returns the index -th path in the MDL user paths. The default MDL user path is

  • %DOCUMENTS%\mdl (on Windows),

  • $HOME/Documents/mdl (on Linux), and

  • $HOME/Documents/mdl (on Mac OS), where %DOCUMENTS% refers to the standard folder identified by FOLDERID_Documents from the Windows API (usually %USERPROFILE%\Documents).

The MDL user paths can be changed via the environment variable MDL_USER_PATH. The environment variable can contain multiple paths which are separated by semicolons (on Windows) or colons (on Linux and Mac OS), respectively.

Returns

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

virtual Size mi::​neuraylib::​IMdl_configuration::get_mdl_user_paths_length() const [pure virtual]

Returns the number of MDL user paths.

virtual const IString* mi::​neuraylib::​IMdl_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.

virtual Size mi::​neuraylib::​IMdl_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.

virtual bool mi::​neuraylib::​IMdl_configuration::get_simple_glossy_bsdf_legacy_enabled() const [pure virtual]

Returns true if the legacy behavior for bsdfs of type df::simple_glossy_bsdf() used in MDL modules with versions smaller that 1.3 is enabled, false otherwise.

virtual Sint32 mi::​neuraylib::​IMdl_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.

virtual Sint32 mi::​neuraylib::​IMdl_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.

virtual void mi::​neuraylib::​IMdl_configuration::set_entity_resolver( IMdl_entity_resolver* resolver) [pure virtual]

Installs an external entity resolver.

Note:

MDL archive creation is not supported with an external entity resolver ( see mi::neuraylib::IMdl_archive_api::create_archive()).

Parameters

resolver
The external entity resolver to be used instead of the built-in entity resolver. Pass NULL to uninstall a previously installed external entity resolver.
virtual Sint32 mi::​neuraylib::​IMdl_configuration::set_expose_names_of_let_expressions( bool value) [pure virtual]

Defines whether an attempt is made to expose names of let expressions. If set to true, the MDL compiler attempts to represent let expressions as temporaries, and makes the name of let expressions available as names of such temporaries. In order to do so, certain optimizations are disabled, in particular, constant folding. These names are only available on material and functions definitions, not on compiled materials, which are always highly optimized. Default: false.

Note:

  • Since some optimizations are essential for inner workings of the MDL compiler, there

  • This setting can only be configured before has been started.

See also:

mi::neuraylib::IFunction_definition::get_temporary_name()

virtual Sint32 mi::​neuraylib::​IMdl_configuration::set_implicit_cast_enabled( bool value) [pure virtual]

Defines whether a cast operator is automatically inserted for compatible argument types. If set to true, an appropriate cast operator is automatically inserted if arguments for instances of mi::neuraylib::IFunction_call have a different but compatible type. If set to false, such an assignment fails and it is necessary to insert the cast operator explicitly. Default: true.

Note:

This setting can only be configured before has been started.

See also:

mi::neuraylib::IExpression_factory::create_cast().

Parameters

value
True to enable the feature, false otherwise.

Returns

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

virtual Sint32 mi::​neuraylib::​IMdl_configuration::set_material_ior_frequency( IType::​Modifier frequency_qualifier) [pure virtual]

Sets the frequency of the material.ior field. Starting with MDL 1.9 the material.ior field is supposed to be no longer uniform, but varying. However, in the current implementation the material.ior field is varying for all MDL versions. In rare cases, this can lead to problems with MDL modules written for older MDL versions. This flag allows to trade the new feature of a varying material.ior field for full compatibility with older MDL versions. Default: mi::neuraylib::IType::MK_VARYING.

Note:

This setting can only be configured before has been started.

Parameters

frequency_qualifier
The desired frequency modifier for the material.ior field.

Returns

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

virtual Sint32 mi::​neuraylib::​IMdl_configuration::set_simple_glossy_bsdf_legacy_enabled( bool value) [pure virtual]

Configures the behavior of df::simple_glossy_bsdf() in MDL modules of versions smaller than 1.3.

Note:

This function has no effect in the MDL SDK and always returns -1.

Parameters

value
True to enable the feature, false otherwise.

Returns

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