Example for MDL Modules

[Previous] [Up]

This example loads an MDL module and inspects it contents.

New Topics

• Configuration of the MDL SDK
• Loading of MDL modules
• Enumerating the contents of MDL modules
• Inspecting the parameters of material and function definitions

Detailed Description

Configuration of the MDL SDK

In order to allow the the MDL SDK to locate MDL modules and its resources in the file system it is necessary to configure the MDL module search path. This is done by calling mi::neuraylib::IMdl_configuration::add_mdl_path().

# get the component using a context manager
with neuray.get_api_component(pymdlsdk.IMdl_configuration) as cfg:
    cfg.add_mdl_path('/home/user/mdl')

Our example module ::nvidia::sdk_examples::tutorials makes use of textures. The support for image formats in the the MDL SDK is provided by image plugins, which have to be loaded explicitly via mi::neuraylib::IPlugin_configuration::load_plugin_library().

The Python bindings provide a helper function for loading plugins as well. The file extension can be omitted to platform dependent code.

# Load the 'nv_openimageio' plug-in
if not pymdlsdk.load_plugin(neuray, 'nv_openimageio'):
    raise Exception('Failed to load the \'nv_openimageio\' plugin.')

Loading of MDL modules

MDL modules are loaded with the method mi::neuraylib::IMdl_impexp_api::load_module(). Note that this method expects the module name, not the name of the file containing the module. To find the corresponding file it is necessary to configure the module search path as described above.

To load a module the IMdl_impexp_api component is acquired first. It is good practice to also create an optional context in order to get detailed log messages.

with neuray.get_api_component(pymdlsdk.IMdl_impexp_api) as imp_exp, \
    neuray.get_api_component(pymdlsdk.IMdl_factory) as mdl_factory, \
    mdl_factory.create_execution_context() as context:
 
    res = imp_exp.load_module(transaction, module_mdl_name, context)

Enumerating the contents of MDL modules

The mi::neuraylib::IModule interface offers various methods related to metadata, like the name of the module, or the name of the file it was loaded from. Furthermore, it offers methods to enumerate the material and function definitions contained in the module. It also allows to enumerate all modules that have been (directly) imported by that module. Imported modules will be automatically loaded (if not already loaded before).

Inspecting the parameters of material and function definitions

MDL materials and functions (as found in a .mdl file) are represented in the MDL SDK API by the interface. Similar to the module interface this interface offers various methods related to metadata, like the name of the definition, or the name of the containing module. Important methods are those that provide details about the parameters, like their names, types, and the values of defaults (if present).

In this example we simply print the parameter information for a selected material and the exported elements of the parenting module.

To read information about a module that has been loaded before it has to accessed using a transaction.

with transaction.access_as(pymdlsdk.IModule, module_db_name) as module:
    if not module.is_valid_interface():
        return
    print("MDL Qualified Name: %s" % module.get_mdl_name())
    print("MDL Simple Name: %s" % module.get_mdl_simple_name())

Compared to the native API, there are two access functions. The access_as used above returns an object of a given type, in this case IModule. The access functions returns a generic interface and the type has to be queried manually.

Source Code Location:
examples/mdl_python/modules/example_modules.py

[Previous] [Up]