Description

Materials 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.

The unit of compilation in MDL is a module. Importing an MDL module creates an instance of mi::neuraylib::IMdl_module 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::IMdl_material_definition and mi::neuraylib::IMdl_function_definition are created in the DB accordingly. Both, material and function definitions can be instantiated. Those instantiations are represented by the interfaces mi::neuraylib::IMdl_material_instance and mi::neuraylib::IMdl_function_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. Note that the function signature uses MDL type names, not neuray API type names.

When instantiating a material or function definitions, its formal parameters are provided with actual arguments. If the parameter has a default initializer, the argument can be omitted in which case the default initializer is used. Arguments of instances can also be changed after instantiation.

The default initializers of material and function definitions, as well as the arguments of material instances and function calls are always of type mi::IAttachable, which is a discriminated union of mi::IRef and the corresponding parameter type itself. For example, the MDL type float of a parameter is mapped to the neuray API type "Float32", and the default or argument for this parameter will be exposed as "Attachable<Float32>". The value of this type either refers to a constant value, or is a reference to another MDL function call (with return type "Float32").

Defaults initializers can also be of type "Attachable<Parameter>". The mi::IParameter type is used to represent default initializers that refer to an earlier parameter in the parameter list: the value identifies the parameter via its position in the parameter list.