MDL SDK API nvidia_logo_transpbg.gif Up
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
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 interfaces for MDL material instances and function calls. More...
 
class  mi::neuraylib::Definition_wrapper
 A wrapper around the interfaces for MDL material and 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_definition
 This interface represents a material 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_BACKFACE_SCATTERING,
  mi::neuraylib::SLOT_BACKFACE_EMISSION_EDF_EMISSION,
  mi::neuraylib::SLOT_BACKFACE_EMISSION_INTENSITY,
  mi::neuraylib::SLOT_IOR,
  mi::neuraylib::SLOT_VOLUME_SCATTERING,
  mi::neuraylib::SLOT_VOLUME_ABSORPTION_COEFFICIENT,
  mi::neuraylib::SLOT_VOLUME_SCATTERING_COEFFICIENT,
  mi::neuraylib::SLOT_GEOMETRY_DISPLACEMENT,
  mi::neuraylib::SLOT_GEOMETRY_CUTOUT_OPACITY,
  mi::neuraylib::SLOT_GEOMETRY_NORMAL,
  mi::neuraylib::SLOT_HAIR
}
 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
}
 The compiled material's opacity. 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, instances of mi::neuraylib::IMaterial_definition and mi::neuraylib::IFunction_definition are created in the DB accordingly. Both, material and function definitions can be instantiated. Those instantiations are represented by the interfaces mi::neuraylib::IMaterial_instance and 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. In addition, there is a global configuration option to enable encoded names.

Encoded names

Encoded names are a new 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?

This new naming scheme can be enabled or disabled using mi::neuraylib::IMdl_configuration::set_encoded_names_enabled().

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. With encoded names enabled, 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
If encoded names are enabled, then 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.

Enabling the encoded names also activates another change for material definitions: Their name also includes the signature (as for function definitions). This avoids ambiguities between names of modules and material definitions.

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

MDL entity Encoded names disabled Encoded names enabled
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%3%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 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(), mi::neuraylib::IFunction_definition::get_mdl_name(), and mi::neuraylib::IMaterial_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 Encoded names disabled Encoded names enabled
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 ::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(), mi::neuraylib::IFunction_definition::get_mdl_simple_name(), and mi::neuraylib::IMaterial_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 Encoded names disabled Encoded names enabled
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 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 exist only if encoded names are enabled.

MDL entity Encoded names disabled Encoded names enabled
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::struct::Foo.param_int(::struct::Foo)" and "mdl::struct::Foo.param_float(::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::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 five 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 five different template-like function definitions follow.

Array constructor

Semantic: mi::neuraylib::IFunction_definition::DS_INTRINSIC_DAG_ARRAY_CONSTRUCTOR
DB name (encoded names disabled/enabled): "mdl::T[](...)"
MDL name (encoded names disabled/enabled): "T[](...)"
Serialized named (encoded names enabled, 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 (encoded names disabled): "mdl::operator_len(<0>[])"
DB name (encoded names enabled): "mdl::operator_len(%3C0%3E[])"
MDL name (encoded names disabled): "operator_len(<0>[])"
MDL name (encoded names enabled): "operator_len(%3C0%3E[])"
Serialized name (encoded names enabled, 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 (encoded names disabled): "mdl::operator[](<0>[],int)"
DB name (encoded names enabled): "mdl::operator[](%3C0%3E[],int)"
MDL name (encoded names disabled): "operator[](<0>[],int)"
MDL name (encoded names enabled): "operator[](%3C0%3E[],int)"
Serialized name (encoded names enabled, 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 (encoded names disabled): "mdl::operator?(bool,<0>,<0>)"
DB name (encoded names enabled): "mdl::operator%3F(bool,%3C0%3E,%3C0%3E)"
MDL name (encoded names disabled): "operator?(bool,<0>,<0>)"
MDL name (encoded names enabled): "operator%3F(bool,%3C0%3E,%3C0%3E)"
Serialized name (encoded names enabled, 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 (encoded names disabled): "mdl::operator_cast(<0>)"
DB name (encoded names enabled): "mdl::operator_cast(%3C0%3E)"
MDL name (encoded names disabled): "operator_cast(<0>)"
MDL name (encoded names enabled): "operator_cast(%3C0%3E)"
Serialized name (encoded names enabled, example): "operator_cast(%3C0%3E)<::foo::my_enum,::bar::my_enum>"

The following requirements apply when creating function calls of the ternary 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().

Enumeration Type Documentation

The compiled material's opacity.

Enumerator
OPACITY_OPAQUE 

material is opaque

OPACITY_TRANSPARENT 

material is transparent

OPACITY_UNKNOWN 

material might be transparent

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_BACKFACE_SCATTERING 

Slot backface.scattering.

SLOT_BACKFACE_EMISSION_EDF_EMISSION 

Slot backface.emission.emission.

SLOT_BACKFACE_EMISSION_INTENSITY 

Slot backface.emission.intensity.

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_GEOMETRY_DISPLACEMENT 

Slot geometry.displacement.

SLOT_GEOMETRY_CUTOUT_OPACITY 

Slot geometry.cutout_opacity.

SLOT_GEOMETRY_NORMAL 

Slot geometry.normal.

SLOT_HAIR 

Slot hair.