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 compiled material's opacity. 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 character	Encoded 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 Iray 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 five function definitions which rather have the character of template functions with generic parameter and/or return types.

the array constructor (mi::neuraylib::IFunction_definition::DS_INTRINSIC_DAG_ARRAY_CONSTRUCTOR),
the array length operator (mi::neuraylib::IFunction_definition::DS_INTRINSIC_DAG_ARRAY_LENGTH),
the array index operator (mi::neuraylib::IFunction_definition::DS_ARRAY_INDEX),
the ternary operator (mi::neuraylib::IFunction_definition::DS_TERNARY), and
the cast operator (mi::neuraylib::IFunction_definition::DS_CAST).

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: "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 expression list for the arguments contains a non-zero number of arguments named "value0", "value1", and so on,
all arguments must be of the same type (which is the element type of the constructed array).

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 expression list for the arguments contains a single expression named "a" of type mi::neuraylib::IType_array.

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 expression list for the arguments contains two expressions named "a" and "i", respectively,
the expression named "a" is of type mi::neuraylib::IType_array, mi::neuraylib::IType_vector, or mi::neuraylib::IType_matrix, and
the expression named "i" is of type mi::neuraylib::IType_int.

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 expression list for the arguments contains three expressions named "cond", "true_exp", and "false_exp", respectively,
the expression named "cond" is of type mi::neuraylib::IType_bool, and
the two other expressions are of the same type.

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 expression list for the arguments contains two expressions named "cast" and "cast_return", respectively,
the expression named "cast" is of an arbitrary type (this is the intended argument of the function call),
the type of the expression named "cast_return" specifies the return type of the function call (no frequency qualifiers; the expression itself is not used), and
the types of "cast" and "cast_return" are compatible.

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

enum mi::neuraylib::Material_opacity

The compiled material's opacity.

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

Enumerator
OPACITY_OPAQUE	material is opaque
OPACITY_TRANSPARENT	material is transparent
OPACITY_UNKNOWN	material might be transparent

^◆ Material_slot

enum mi::neuraylib::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

enum mi::neuraylib::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.

Classes

Enumerations