Materials (MDL)

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

Classes
class	mi::IMdl_compiled_material
	This interface represents a compiled material. More...
class	mi::IMdl_function_call
	This interface represents a function call. More...
class	mi::IMdl_function_definition
	This interfaces represents a function definition. More...
class	mi::IMdl_material_definition
	This interfaces represents a material definition. More...
class	mi::IMdl_material_instance
	This interface represents a material instance. More...
class	mi::IMdl_module
	This interfaces represents an MDL module. More...
class	mi::Mdl_argument_editor
	A wrapper around the interfaces for MDL material instances and function calls. More...
class	mi::Mdl_definition_wrapper
	A wrapper around the interfaces for MDL material and function definitions. More...

Enumerations
enum	mi::Material_slot {   mi::SLOT_THIN_WALLED,   mi::SLOT_SURFACE_SCATTERING,   mi::SLOT_SURFACE_EMISSION_EDF_EMISSION,   mi::SLOT_SURFACE_EMISSION_INTENSITY,   mi::SLOT_BACKFACE_SCATTERING,   mi::SLOT_BACKFACE_EMISSION_EDF_EMISSION,   mi::SLOT_BACKFACE_EMISSION_INTENSITY,   mi::SLOT_IOR,   mi::SLOT_VOLUME_SCATTERING,   mi::SLOT_VOLUME_ABSORPTION_COEFFICIENT,   mi::SLOT_VOLUME_SCATTERING_COEFFICIENT,   mi::SLOT_GEOMETRY_DISPLACEMENT,   mi::SLOT_GEOMETRY_CUTOUT_OPACITY,   mi::SLOT_GEOMETRY_NORMAL }
	Material slots identify parts of a material. More...

Detailed 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::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::IMdl_material_definition and mi::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::IMdl_material_instance and mi::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 Iray 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 Iray 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.

Annotations

Material and function definitions and their parameters may have annotation blocks. They are exposed in the API as values of type mi::IAttribute_container. The names of the attributes are the names of the annotations in the block. The order of annotations in an annotation block in the MDL source is not preserved, only the relative order of annotations of the same name.

If an annotation with a given name occurs only once in the annotation block, it is represented as an attribute of type mi::IStructure, where the type name of the structure is the name of the annotation, and the fields of the structure represent the arguments of the annotation. The field names are the parameter names from the declaration of the annotation.

If an annotation with a given name occurs multiple times in an annotation block, all occurrences are represented as a single structure. The field names of this structure are consecutive numbers starting from zero, and the individual fields are encoded as described above for annotations that occur only once.

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 "struct" creates the following function definitions:

• a default constructor named "mdl::struct::Foo()", and
• an elemental constructor named "mdl::struct::Foo(int,float)".

The elemental constructor has a parameter "param_int" of type "Sint32" and a parameter "param_float" of type "Float32". Both constructors have the return type "mdl::struct::Foo".

In addition, for each exported struct type, and for each of its fields, a function for the corresponding member selection operator is created in the DB. The name of that function is formed by concatenating the name of the struct type with the name of the field with an intervening dot, e.g., "foo.bar". The function 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 "struct" creates the two functions 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 functions have a single parameter "s" of type "mdl::struct::Foo" and return type "Sint32" and "Float32", respectively.

Arrays, vectors, and matrices

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.

Example

The MDL code

export int some_function(float[42] some_parameter) { ... }
export int some_function(float[<N>] some_parameter) { ... }
export int some_function(float3 some_parameter) { ... }
export int some_function(float3x3 some_parameter) { ... }

in a module "indexable" creates the indexing functions

• "mdl::indexable::float[42]@(float[42],int)" with the first parameter "a" of type "Float32>[42]",
• "mdl::float[]@(float[],int)" with the first parameter "a" of type "Float32[]",
• "mdl::float3@(float3,int)" with the first parameter "a" of type "Float32<3>", and
• "mdl::float3x3@(float3x3,int)" with the first parameter "a" of type "Float32<3,3>".

In all cases the second parameter "i" is of type "Sint32". In the first three cases the return type is "Float32". In the last case the return type is "Float32<3>". 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.

Enumeration Type Documentation

enum mi::Material_slot

Material slots identify parts of a material.

See Also

mi::IMdl_compiled_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.