MDL SDK API nvidia_logo_transpbg.gif Up
MDL-related elements

MDL-related elements comprise a set of interfaces related to the Material Definition Language (MDL). More...

Classes

class  mi::neuraylib::Annotation_wrapper
 A wrapper around the interfaces for MDL annotations. More...
 
class  mi::neuraylib::Argument_editor
 A wrapper around the interface for MDL material instances and function calls. More...
 
class  mi::neuraylib::Definition_wrapper
 A wrapper around the interface for MDL function definitions. More...
 
class  mi::neuraylib::ICompiled_material
 This interface represents a compiled material. More...
 
class  mi::neuraylib::IFunction_call
 This interface represents a function call. More...
 
class  mi::neuraylib::IFunction_definition
 This interface represents a function definition. More...
 
class  mi::neuraylib::IMaterial_instance
 This interface represents a material instance. More...
 
class  mi::neuraylib::IModule
 This interface represents an MDL module. More...
 

Enumerations

enum  mi::neuraylib::Material_slot {
  mi::neuraylib::SLOT_THIN_WALLED ,
  mi::neuraylib::SLOT_SURFACE_SCATTERING ,
  mi::neuraylib::SLOT_SURFACE_EMISSION_EDF_EMISSION ,
  mi::neuraylib::SLOT_SURFACE_EMISSION_INTENSITY ,
  mi::neuraylib::SLOT_SURFACE_EMISSION_MODE ,
  mi::neuraylib::SLOT_BACKFACE_SCATTERING ,
  mi::neuraylib::SLOT_BACKFACE_EMISSION_EDF_EMISSION ,
  mi::neuraylib::SLOT_BACKFACE_EMISSION_INTENSITY ,
  mi::neuraylib::SLOT_BACKFACE_EMISSION_MODE ,
  mi::neuraylib::SLOT_IOR ,
  mi::neuraylib::SLOT_VOLUME_SCATTERING ,
  mi::neuraylib::SLOT_VOLUME_ABSORPTION_COEFFICIENT ,
  mi::neuraylib::SLOT_VOLUME_SCATTERING_COEFFICIENT ,
  mi::neuraylib::SLOT_VOLUME_EMISSION_INTENSITY ,
  mi::neuraylib::SLOT_GEOMETRY_DISPLACEMENT ,
  mi::neuraylib::SLOT_GEOMETRY_CUTOUT_OPACITY ,
  mi::neuraylib::SLOT_GEOMETRY_NORMAL ,
  mi::neuraylib::SLOT_HAIR ,
  mi::neuraylib::SLOT_FIRST = SLOT_THIN_WALLED ,
  mi::neuraylib::SLOT_LAST = SLOT_HAIR ,
  SLOT_FORCE_32_BIT = 0xffffffffU
}
 Material slots identify parts of a compiled material. More...
 
enum  mi::neuraylib::Material_opacity {
  mi::neuraylib::OPACITY_OPAQUE ,
  mi::neuraylib::OPACITY_TRANSPARENT ,
  mi::neuraylib::OPACITY_UNKNOWN ,
  OPACITY_FORCE_32_BIT = 0xffffffffU
}
 The opacity of a compiled material. More...
 
enum  mi::neuraylib::Mdl_repair_options {
  mi::neuraylib::MDL_REPAIR_DEFAULT = 0 ,
  mi::neuraylib::MDL_REMOVE_INVALID_ARGUMENTS = 1 ,
  mi::neuraylib::MDL_REPAIR_INVALID_ARGUMENTS = 2 ,
  MDL_REPAIR_OPTIONS_FORCE_32_BIT = 0xffffffffU
}
 Options for repairing function calls. More...
 

Detailed Description

MDL-related elements comprise a set of interfaces related to the Material Definition Language (MDL).

See [MDLTI] for a technical introduction into the Material Definition Language and [MDLLS] for the language specification. See also MDL type system.

The unit of compilation in MDL is a module. Importing an MDL module creates an instance of mi::neuraylib::IModule in the DB. A module allows to retrieve the referenced (aka imported) modules, as well as the exported material and function definitions. For all exported definitions, DB elements of type mi::neuraylib::IFunction_definition are created in the DB accordingly. Both, material and function definitions can be instantiated. Those instantiations are represented by the interface mi::neuraylib::IFunction_call.

Naming scheme for MDL elements

There are four different types of names for MDL elements: DB names, MDL names, simple MDL names, and serialized names.

Encoded names

Encoded names are a naming scheme for MDL elements. Its purpose is to avoid certain problems that exist with the old naming scheme, especially in the context of package and module names containing certain meta-characters. For example, given the function name "::f::g(int)::h::i(j::k)": does the signature start at the first or second left parenthesis?

The main idea is to use percent-encoding for certain characters when they do not appear as meta-character.

Decoded characterEncoded character
( %28
) %29
<%3C
>%3E
, %2C
: %3A
$ %24
# %23
? %3F
@ %40
% %25

To avoid redundant representations, only upper-case letters are used as hexadecimal digits of encoded characters. All characters not listed in the table above are never encoded.

Encoding these characters when they do not appear as meta-characters avoids the known ambiguities. The example from above would be either "::f::g(int%29::h::i%28j::k)" (if the signature starts at the first left parenthesis) or "::f::g%28int%29::h::i(j::k)" (if the signature starts at the second left parenthesis).

An important consequence from resolving such ambiguities is the fact that it is always possible to decode an encoded name, whereas (in general) it is not possible to encode a name without context. Therefore, you should use encoded names as much as possible, and use decoded names only e.g. for display purposes.

Note
All DB names of modules, material and function definitions, their MDL names and simple names, and all MDL-related type names in the API are encoded; exceptions from this rule are explicitly documented. One such exception are the functions mi::neuraylib::IMdl_factory::decode_name(), mi::neuraylib::IMdl_factory::encode_module_name(), mi::neuraylib::IMdl_factory::encode_function_definition_name(), and mi::neuraylib::IMdl_factory::encode_type_name(), which help with decoding and encoding of names.
Due to a technical limitation module names containing parentheses or commas are not yet supported.

DB names

DB names are the most prominent type of names for MDL elements in the MDL SDK API. These type names are mainly used to identify MDL elements, in particular, to access them in the database.

The DB names for modules as well as for function and material definitions have an "mdl" or "mdle" prefix. This prefix is also used for automatically created function calls and materials instances used as parameter defaults. User-generated function calls, material instances, and compiled materials might use the prefix, but are not required to.

If the interface of an MDL element is given, then its DB name can be obtained from mi::neuraylib::ITransaction::name_of().

Decoded DB names are shown in the table below only for better understanding and comparison with subsequent tables. There is hardly any use of them, except for dealing with older file formats.

MDL entity Decoded name Encoded name
module with builtins mdl::<builtins> mdl::%3Cbuiltins%3E
user module mdl::foo mdl::foo
MDLE module (Linux) mdle::/path/to/bar.mdle   (1) mdle::/path/to/bar.mdle   (1)
MDLE module (Windows) mdle::/C:/path/to/bar.mdle   (1) mdle::/C%3A/path/to/bar.mdle   (1)
builtin function mdl::operator+(float,float) mdl::operator+(float,float)
builtin function, affected by encoding mdl::operator<<(int,int) mdl::operator%3C%3C(int,int)
builtin template-like function mdl::operator?(bool,<0>,<0>) mdl::operator%3F(bool,%3C0%3E,%3C0%3E)
user function mdl::foo::my_func(color) mdl::foo::my_func(color)
user function, module name affected by encoding mdl::foo,bar::my_func(::foo,bar::my_enum) mdl::foo%2Cbar::my_func(::foo%2Cbar::my_enum)
user material mdl::foo::my_mat(color) mdl::foo::my_mat(color)

(1) Note that the DB name for an MDLE module is not the same as the filename (modulo "mdle::" prefix), in particular on Windows (slash before drive letter, encoded colon after drive letter, slashes vs backslashes). Even on non-Windows systems there might be differences due to filename normalization. Use mi::neuraylib::IMdl_factory::get_db_module_name() to obtain the DB name for an MDLE module from the filename.

MDL names

MDL names are useful for display purposes. They are similar to the DB names, except that they lack the "mdl" or "mdle" prefix. Entities from the ::<builtins> module also lack the leading scope "::".

The interfaces for modules as well as for function and material definitions provide methods to obtain the MDL name, see mi::neuraylib::IModule::get_mdl_name(), and mi::neuraylib::IFunction_definition::get_mdl_name(). The corresponding DB name can be obtained from an MDL name with the help of the methods mi::neuraylib::IMdl_factory::get_db_module_name() and mi::neuraylib::IMdl_factory::get_db_definition_name(). Note that there is no MDL name for function calls, material instances, or compiled materials.

For display purposes you might want to decode the MDL name using mi::neuraylib::IMdl_factory::decode_name().

MDL entity Decoded name Encoded name
module with builtins ::<builtins> ::%3Cbuiltins%3E
user module ::foo ::foo
MDLE module (Linux) ::/path/to/bar.mdle   (2) ::/path/to/bar.mdle   (2)
MDLE module (Windows) ::/C:/path/to/bar.mdle   (2) ::/C%3A/path/to/bar.mdle   (2)
builtin function operator+(float,float) operator+(float,float)
builtin function, affected by encoding operator<<(int,int) operator%3C%3C(int,int)
builtin template-like function operator?(bool,<0>,<0>) operator%3F(bool,%3C0%3E,%3C0%3E)
user function ::foo::my_func(color) ::foo::my_func(color)
user function, module name affected by encoding ::foo,bar::my_func(::foo,bar::my_enum) ::foo%2Cbar::my_func(::foo%2Cbar::my_enum)
user material ::foo::my_mat(color) ::foo::my_mat(color)

(2) Note that the MDL name for an MDLE module is not the same as the filename (modulo "::" prefix), in particular on Windows (slash before drive letter, encoded colon after drive letter, slashes vs backslashes). Even on non-Windows systems there might be differences due to filename normalization.

Simple MDL names

Simple MDL names are a variant of the MDL names above. They are used in a few places when the context is clear. Simple MDL names for modules lack the package name prefix including the scope separator. Simple MDL names for function, material, and annotation definitions lack the module name prefix including the scope separator and the signature suffix.

Note that due to function overloading, multiple functions within a module might share the same simple name.

The interfaces for modules as well as for function and material definitions provide methods to obtain the simple MDL name, see mi::neuraylib::IModule::get_mdl_simple_name(), and mi::neuraylib::IFunction_definition::get_mdl_simple_name().

For display purposes you might want to decode the simple MDL name using mi::neuraylib::IMdl_factory::decode_name().

MDL entity Decoded name Encoded name
module with builtins <builtins> %3Cbuiltins%3E
user module foo foo
MDLE module (Linux) /path/to/bar.mdle   (3) /path/to/bar.mdle   (3)
MDLE module (Windows) /C:/path/to/bar.mdle   (3) /C%3A/path/to/bar.mdle   (3)
builtin function operator+ operator+
builtin function, affected by encoding operator<< operator%3C%3C
builtin template-like function operator? operator%3F
user function my_func my_func
user function, module name affected by encoding my_func my_func
user material my_mat my_mat

(3) Note that the simple MDL name for an MDLE module is not the same as the filename, in particular on Windows (slash before drive letter, encoded colon after drive letter, slashes vs backslashes). Even on non-Windows systems there might be differences due to filename normalization.

Serialized names

Serialized names are identical to encoded DB names with the exception of Template-like function definitions. For these functions, the serialized names have a suffix in angle brackets that contains additional information about the template parameters. This extra information is useful to reconstruct the correct template instance upon deserialization. See Template-like function definitions for an example of serialized names for each template-like function.

The methods mi::neuraylib::IMdl_impexp_api::serialize_function_name(), mi::neuraylib::IMdl_impexp_api::deserialize_function_name(), and mi::neuraylib::IMdl_impexp_api::deserialize_module_name() deal with serialized names.

Serialized names occur only in the encoded form.

MDL entity Decoded name Encoded name
module with builtins mdl::%3Cbuiltins%3E
user module mdl::foo
MDLE module (Linux) mdle::bar.mdle   (4)
MDLE module (Windows) mdle::bar.mdle   (5)
builtin function mdl::operator+(float,float)
builtin function, affected by encoding mdl::operator%3C%3C(int,int)
builtin template-like function mdl::operator%3F(bool,%3C0%3E,%3C0%3E)<int>
user function mdl::foo::my_func(color)
user function, module name affected by encoding mdl::foo%2Cbar::my_func(::foo%2Cbar::my_enum)
user material mdl::foo::my_mat(color)

(4) With an MDLE callback that strips all directory components during serialization (see mi::neuraylib::IMdle_serialization_callback).
(5) With an MDLE callback that strips all drive and directory components during serialization (see mi::neuraylib::IMdle_serialization_callback).

Structs

For each exported struct type function definitions for its constructors are created in the DB. There is a default constructor and a so-called elemental constructor which has a parameter for each field of the struct. The name of these constructors is the name of the struct type including the signature.

Example
The MDL code
export struct Foo {
int param_int;
float param_float = 0;
};
in a module "mod_struct" creates the following function definitions:
  • a default constructor named "mdl::mod_struct::Foo()",
  • an elemental constructor named "mdl::mod_struct::Foo(int,float)", and
The elemental constructor has a parameter "param_int" of type mi::neuraylib::IType_int and a parameter "param_float" of type mi::neuraylib::IType_float. Both function definitions have the return type mi::neuraylib::IType_struct with name "::mod_struct::Foo".

In addition, for each exported struct type, and for each of its fields, a function definition for the corresponding member selection operator is created in the DB. The name of that function definition is obtained by concatenating the name of the struct type with the name of the field with an intervening dot, e.g., "foo.param_int". The function definition has a single parameter "s" of the struct type and the corresponding field type as return type.

Example
The MDL code
export struct Foo {
int param_int;
float param_float = 0;
};
in a module "mod_struct" creates the two function definitions named "mdl::mod_struct::Foo.param_int(::mod_struct::Foo)" and "mdl::mod_struct::Foo.param_float(::mod_struct::Foo)" to represent the member selection operators "Foo.param_int" and "Foo.param_float". The function definitions have a single parameter "s" of type "mdl::mod_struct::Foo" and return type mi::neuraylib::IType_int and mi::neuraylib::IType_float, respectively.

Arrays

In contrast to struct types which are explicitly declared there are infinitely many array types (considering pairs of element type and array length). Deferred-sized arrays make the situation even more complicated. Each of these array types would have its own constructor and index operator. Therefore, template-like functions definitions are used in the context of arrays to satisfy this need. See the next section for details

Template-like function definitions

Usually, function definitions have a fixed set of parameter types and a fixed return type. Exceptions of this rule are the following six function definitions which rather have the character of template functions with generic parameter and/or return types.

The MDL and DB names of these function definitions use "<0>" or "T" to indicate such a generic parameter or return type. When querying the actual type, mi::neuraylib::IType_int (arbitrary choice) is returned for lack of a better alternative.

When creating function calls from such template-like function definitions, the parameter and return types are fixed, i.e., the function call itself has concrete parameter and return types as usual, and has no template-like behavior as the definition from which it was created. This implies that, for example, after creating a ternary operator on floats, you cannot set its arguments to expressions of a different type than float (this would require creation of another function call with the desired parameter types).

Template-like functions are those functions for which serialized name and DB name differ (see Naming scheme for MDL elements).

More details about the six different template-like function definitions follow.

Array constructor

Semantic: mi::neuraylib::IFunction_definition::DS_INTRINSIC_DAG_ARRAY_CONSTRUCTOR
DB name: "mdl::T[](...)"
MDL name: "T[](...)"
Serialized named (example): "mdl::T[](...)<int,42>"

The following requirements apply when creating function calls of the array constructor:

The suffix for the serialized name has two arguments, the type name of the element type, and the size of the array.

Array length operator

Semantic: mi::neuraylib::IFunction_definition::DS_INTRINSIC_DAG_ARRAY_LENGTH
DB name: "mdl::operator_len(%3C0%3E[])"
MDL name): "operator_len(%3C0%3E[])"
Serialized name (example): "operator_len(%3C0%3E[])<float[42]>"

The following requirements apply when creating function calls of the array length operator:

The suffix for the serialized name has one argument, the type name of the array.

Array index operator

Semantic: mi::neuraylib::IFunction_definition::DS_ARRAY_INDEX
DB name: "mdl::operator[](%3C0%3E[],int)"
MDL name: "operator[](%3C0%3E[],int)"
Serialized name (example): "operator[](%3C0%3E[],int)<float[42]>"

Despite its name, the array index operator can also be used on vectors and matrices.

The following requirements apply when creating function calls of the array index operator:

The suffix for the serialized name has one argument, the type name of the array, vector, or matrix.

Ternary operator

Semantic: mi::neuraylib::IFunction_definition::DS_TERNARY
DB name: "mdl::operator%3F(bool,%3C0%3E,%3C0%3E)"
MDL name: "operator%3F(bool,%3C0%3E,%3C0%3E)"
Serialized name (example): "operator%3F(bool,%3C0%3E,%3C0%3E)<float>"

The following requirements apply when creating function calls of the ternary operator:

The suffix for the serialized name has one argument, the type name of the "true_exp" expression (which is equal to the type name of the "false_exp" expression).

Cast operator

Semantic: mi::neuraylib::IFunction_definition::DS_CAST
DB name: "mdl::operator_cast(%3C0%3E)"
MDL name: "operator_cast(%3C0%3E)"
Serialized name (example): "operator_cast(%3C0%3E)<::foo::my_enum,::bar::my_enum>"

The following requirements apply when creating function calls of the cast operator:

The suffix for the serialized name has two arguments, the type name of the "cast" expression, followed by the type name of the "cast_return" expression.

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

Decl_cast operator

The decl_cast operator is used to express casts between different struct types from the same struct category.

Semantic: mi::neuraylib::IFunction_definition::DS_INTRINSIC_DAG_DECL_CAST
DB name: "mdl::operator_decl_cast(%3C0%3E)"
MDL name: "operator_decl_cast(%3C0%3E)"
Serialized name (example): "operator_decl_cast(%3C0%3E)<::foo::some_material_type,::foo::another_material_type>"

The following requirements apply when creating function calls of the decl_cast operator:

The suffix for the serialized name has two arguments, the type name of the "cast" expression, followed by the type name of the "cast_return" expression.

Enumeration Type Documentation

 Material_opacity

The opacity of a compiled material.

See mi::neuraylib::ICompiled_material::get_opacity() and mi::neuraylib::ICompiled_material::get_surface_opacity().

Enumerator
OPACITY_OPAQUE 

The material is opaque.

OPACITY_TRANSPARENT 

The material is transparent.

OPACITY_UNKNOWN 

The opacity of the material is unknown, e.g., because it depends on parameters.

 Material_slot

Material slots identify parts of a compiled material.

See also
mi::neuraylib::ICompiled_material and mi::neuraylib::ICompiled_material::get_slot_hash()
Enumerator
SLOT_THIN_WALLED 

Slot "thin_walled".

SLOT_SURFACE_SCATTERING 

Slot "surface.scattering".

SLOT_SURFACE_EMISSION_EDF_EMISSION 

Slot "surface.emission.emission".

SLOT_SURFACE_EMISSION_INTENSITY 

Slot "surface.emission.intensity".

SLOT_SURFACE_EMISSION_MODE 

Slot "surface.emission.mode".

SLOT_BACKFACE_SCATTERING 

Slot "backface.scattering".

SLOT_BACKFACE_EMISSION_EDF_EMISSION 

Slot "backface.emission.emission".

SLOT_BACKFACE_EMISSION_INTENSITY 

Slot "backface.emission.intensity".

SLOT_BACKFACE_EMISSION_MODE 

Slot "backface.emission.mode".

SLOT_IOR 

Slot "ior".

SLOT_VOLUME_SCATTERING 

Slot "volume.scattering".

SLOT_VOLUME_ABSORPTION_COEFFICIENT 

Slot "volume.absorption_coefficient".

SLOT_VOLUME_SCATTERING_COEFFICIENT 

Slot "volume.scattering_coefficient".

SLOT_VOLUME_EMISSION_INTENSITY 

Slot "volume.emission_intensity".

SLOT_GEOMETRY_DISPLACEMENT 

Slot "geometry.displacement".

SLOT_GEOMETRY_CUTOUT_OPACITY 

Slot "geometry.cutout_opacity".

SLOT_GEOMETRY_NORMAL 

Slot "geometry.normal".

SLOT_HAIR 

Slot "hair".

SLOT_FIRST 

First slot.

SLOT_LAST 

Last slot.

 Mdl_repair_options

Options for repairing function calls.

See also
mi::neuraylib::IFunction_call::repair().
Enumerator
MDL_REPAIR_DEFAULT 

Default mode, do not alter any inputs.

MDL_REMOVE_INVALID_ARGUMENTS 

Remove an invalid call attached to an argument.

MDL_REPAIR_INVALID_ARGUMENTS 

Attempt to repair invalid calls attached to an argument.