MDL SDK API nvidia_logo_transpbg.gif Up
mi::neuraylib::IMdl_configuration Class Referenceabstract

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

#include <imdl_configuration.h>

Inheritance diagram for mi::neuraylib::IMdl_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 IStringget_mdl_path (Size index) const =0
 Returns the index -th path to search for MDL modules. More...
 
virtual Size get_mdl_system_paths_length () const =0
 Returns the number of MDL system paths. More...
 
virtual const char * get_mdl_system_path (Size index) const =0
 Returns the index -th path in the MDL system paths. More...
 
void add_mdl_system_paths ()
 Adds the MDL system paths to the MDL search path. More...
 
virtual Size get_mdl_user_paths_length () const =0
 Returns the number of MDL user paths. More...
 
virtual const char * get_mdl_user_path (Size index) const =0
 Returns the index -th path in the MDL user paths. More...
 
void add_mdl_user_paths ()
 Adds the MDL user paths to the MDL search path. 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 IStringget_resource_path (Size index) const =0
 Returns the index -th path to search for resources, i.e., textures, light profiles, and BSDF measurements. More...
 
Miscellaneous settings
virtual Sint32 set_implicit_cast_enabled (bool value)=0
 Defines whether a cast operator is automatically inserted for compatible argument types. 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 Sint32 set_expose_names_of_let_expressions (bool value)=0
 Defines whether an attempt is made to expose names of let expressions. More...
 
virtual bool get_expose_names_of_let_expressions () const =0
 Indicates whether an attempt is made to expose names of let expressions. 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...
 
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. More...
 
virtual Sint32 set_material_ior_frequency (IType::Modifier frequency_qualifier)=0
 Sets the frequency of the material.ior field. More...
 
virtual IType::Modifier get_material_ior_frequency () const =0
 Returns the frequency of the material.ior field. More...
 
Entity resolver
virtual IMdl_entity_resolverget_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...
 
virtual void MI_NEURAYLIB_DEPRECATED_METHOD_14_1() set_logger (base::ILogger *logger)=0
 
virtual base::ILogger *MI_NEURAYLIB_DEPRECATED_METHOD_14_1() get_logger ()=0
 
- 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 IInterfaceget_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 IInterfaceget_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...
 

Additional Inherited Members

- Public Types inherited from mi::base::Interface_declare< 0x2657ec0b, ... >
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< 0x2657ec0b, ... >
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 can be used to query and change the MDL configuration.

Member Function Documentation

 add_mdl_path()

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
pathThe path to be added.
Returns
  • 0: Success.
  • -1: Invalid parameters ( NULL pointer).
  • -2: Invalid path.

 add_mdl_system_paths()

void mi::neuraylib::IMdl_configuration::add_mdl_system_paths ( )
inline

Adds the MDL system paths to the MDL search path.

 add_mdl_user_paths()

void mi::neuraylib::IMdl_configuration::add_mdl_user_paths ( )
inline

Adds the MDL user paths to the MDL search path.

 add_resource_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
pathThe path to be added.
Returns
  • 0: Success.
  • -1: Invalid parameters ( NULL pointer).
  • -2: Invalid path.

 clear_mdl_paths()

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.

 clear_resource_paths()

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.

 get_entity_resolver()

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

 get_expose_names_of_let_expressions()

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

 get_implicit_cast_enabled()

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

 get_material_ior_frequency()

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.

 get_mdl_path()

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.

 get_mdl_paths_length()

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.

 get_mdl_system_path()

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.

 get_mdl_system_paths_length()

virtual Size mi::neuraylib::IMdl_configuration::get_mdl_system_paths_length ( ) const
pure virtual

Returns the number of MDL system paths.

 get_mdl_user_path()

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.

 get_mdl_user_paths_length()

virtual Size mi::neuraylib::IMdl_configuration::get_mdl_user_paths_length ( ) const
pure virtual

Returns the number of MDL user paths.

 get_resource_path()

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.

 get_resource_paths_length()

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.

 get_simple_glossy_bsdf_legacy_enabled()

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.

 remove_mdl_path()

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
pathThe 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::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
pathThe path to be removed.
Returns
  • 0: Success.
  • -1: Invalid parameters ( NULL pointer).
  • -2: There is no such path in the path list.

 set_entity_resolver()

virtual void mi::neuraylib::IMdl_configuration::set_entity_resolver ( IMdl_entity_resolver resolver)
pure virtual

Installs an external entity resolver.

Parameters
resolverThe external entity resolver to be used instead of the built-in entity resolver. Pass NULL to uninstall a previously installed external entity resolver.
Note
MDL archive creation is not supported with an external entity resolver ( see mi::neuraylib::IMdl_archive_api::create_archive()).

 set_expose_names_of_let_expressions()

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 the MDL SDK has been started.
See also
mi::neuraylib::IFunction_definition::get_temporary_name()

 set_implicit_cast_enabled()

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 the MDL SDK has been started.
See also
mi::neuraylib::IExpression_factory::create_cast().
Parameters
valueTrue to enable the feature, false otherwise.
Returns
  • 0: Success.
  • -1: The method cannot be called at this point of time.

 set_material_ior_frequency()

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 the MDL SDK has been started.
Parameters
frequency_qualifierThe 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.

 set_simple_glossy_bsdf_legacy_enabled()

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
valueTrue to enable the feature, false otherwise.
Returns
  • 0: Success.
  • -1: The method cannot be called at this point of time.