MDL-related elements comprise a set of interfaces related to the Material Definition Language (MDL). More...
Classes | |
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... | |
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.
The DB names of all scene elements related to MDL always carry the prefix "mdl"
. This prefix is followed by the fully qualified MDL name of the entity including two initial colons, e.g., the DB element representing the df
module has the DB name "mdl::df"
. Since function definitions can be overloaded in MDL, the DB names contain the function signature, e.g., if there are two functions "bool foo(int n)"
and "bool foo(float f)"
in module bar
, the DB name of these are "mdl::bar::foo(int)"
and "mdl::bar::foo(float)"
respectively.
When instantiating a material or function definition, its formal parameters are provided with actual arguments. If the parameter has a default, the argument can be omitted in which case the default is used. Arguments of instances can also be changed after instantiation.
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.
"mod_struct"
creates the following function definitions:"mdl::mod_struct::Foo()"
,"mdl::mod_struct::Foo(int,float)"
, and"mdl::mod_struct::operator?(bool,::mod_struct::Foo,::mod_struct::Foo)"
."param_int"
of type mi::neuraylib::IType_int and a parameter "param_float"
of type mi::neuraylib::IType_float. All three 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.bar"
. The function definition has a single parameter "s"
of the struct type and the corresponding field type as return type.
"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.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 requires its own constructor. Therefore, a special convention is used to represent array constructors. Conversely, handling of array constructors requires special code paths compared to all other function calls.
Instead of infinitely many function definitions, there is one single function definition created in the DB as placeholder for all array constructors. The DB name of this function definition is "mdl::T[](...)"
. Since this function definition acts as placeholder for all array constructors the reported return type, the number of parameters, and their types are meaningless.
When creating a function call based on this function definition the following requirements must be met: (1) the expression list for the arguments contains a non-zero number of arguments, (2) all arguments must be of the same type (which is the element type of the constructed array), and (3) the positional order of the arguments in the expression list is used, their names are irrelevant.
Once a function call for the array constructor has been created its return type, the number of arguments, and their type is fixed. Changing the array length or the element type requires the creation of a new function call from the array constructor definition.
Arrays, vectors, and matrices are also called indexable types. For each such type occurring in an exported type or in the signature of an exported function or material, an indexing function is created in the DB. The name of this indexing function is formed by suffixing the name of the type with an at symbol ('@'). The indexing function has two parameters, where the first parameter "a"
is the value to be indexed and the second parameter "i"
is the index.
"mod_indexable"
creates the indexing functions"mdl::mod_indexable::float[42]@(float[42],int)"
with the first parameter "a"
of type mi::neuraylib::IType_array,"mdl::float[]@(float[],int)"
with the first parameter "a"
of type mi::neuraylib::IType_array,"mdl::float3@(float3,int)"
with the first parameter "a"
of type mi::neuraylib::IType_vector, and"mdl::float3x3@(float3x3,int)"
with the first parameter "a"
of type mi::neuraylib::IType_matrix."i"
is of type mi::neuraylib::IType_int. In the first three cases the return type is mi::neuraylib::IType_float. In the last case the return type is mi::neuraylib::IType_vector with three components of type mi::neuraylib::IType_float. Note that for immediate-sized arrays the indexing functions is in the module that uses that array type, for all other indexable types the indexing function is in the module that defines the type. Material slots identify parts of a compiled material.