Material Definition Language API nvidia_logo_transpbg.gif Up
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
mi::neuraylib::IMdl_configuration Class Referenceabstract

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

Inheritance diagram for mi::neuraylib::IMdl_configuration:
mi::base::Interface_declare< 0x2657ec0b, 0x8a40, 0x46c5, 0xa8, 0x3f, 0x2b, 0xb5, 0x72, 0xa0, 0x8b, 0x9c > mi::base::IInterface

Public Member Functions

Logging
virtual void set_logger (base::ILogger *logger)=0
 Sets the logger. More...
 
virtual base::ILoggerget_logger ()=0
 Returns the used logger. 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 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...
 
Miscellaneuous 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...
 
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...
 

Additional Inherited Members

- Public Types inherited from mi::base::Interface_declare< 0x2657ec0b, 0x8a40, 0x46c5, 0xa8, 0x3f, 0x2b, 0xb5, 0x72, 0xa0, 0x8b, 0x9c >
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...
 
- Static Public Member Functions inherited from mi::base::Interface_declare< 0x2657ec0b, 0x8a40, 0x46c5, 0xa8, 0x3f, 0x2b, 0xb5, 0x72, 0xa0, 0x8b, 0x9c >
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 can be used to query and change the MDL configuration.

Member Function Documentation

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.
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
pathThe 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.
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 base::ILogger* mi::neuraylib::IMdl_configuration::get_logger ( )
pure virtual

Returns the used logger.

Returns
The currently used logger ( either explicitly installed via set_logger(), or the default logger). Never returns NULL.
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
pathThe 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
pathThe 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.

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

Note
Since some optimizations are essential for inner workings of the MDL compiler, there
See Also
mi::neuraylib::IFunction_definition::get_temporary_name(), mi::neuraylib::IMaterial_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 or mi::neuraylib::IMaterial_instance 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.

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.
virtual void mi::neuraylib::IMdl_configuration::set_logger ( base::ILogger logger)
pure virtual

Sets the logger.

Installs a custom logger, and deinstalls the previously installed logger. By default, an internal logger is installed that prints all messages of severity mi::base::details::MESSAGE_SEVERITY_INFO or higher to stderr.

Parameters
loggerThe new logger that receives all log messages. Passing NULL is allowed to reinstall the default logger.
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.