Material Definition Language 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::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...
 
enum  mi::neuraylib::Mdl_version {
  mi::neuraylib::MDL_VERSION_1_0,
  mi::neuraylib::MDL_VERSION_1_1,
  mi::neuraylib::MDL_VERSION_1_2,
  mi::neuraylib::MDL_VERSION_1_3,
  mi::neuraylib::MDL_VERSION_1_4,
  mi::neuraylib::MDL_VERSION_1_5,
  mi::neuraylib::MDL_VERSION_1_6,
  mi::neuraylib::MDL_VERSION_INVALID = 0xffffffffU
}
 The MDL version. 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.

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.

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.bar". 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 its own constructor and its own 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. As an exception of this rule, there are five function definitions which rather have the character of a template 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 creation of 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).

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[](...)"

The following requirements apply when creating function calls of the array constructor:

Function calls of the array constructor use "0", "1", etc. as parameter names (which are not valid MDL identifiers), no matter which names were used in the argument list during call creation.

Array length operator

Semantic: mi::neuraylib::IFunction_definition::DS_INTRINSIC_DAG_ARRAY_LENGTH
DB name: "mdl::operator_len(<0>[])"
MDL name: "operator_len(<0>[])"

The following requirements apply when creating function calls of the array length operator:

Array index operator

Semantic: mi::neuraylib::IFunction_definition::DS_ARRAY_INDEX
DB name: "mdl::operator[](<0>[],int)"
MDL name: "operator[](<0>[],int)"

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:

Ternary operator

Semantic: mi::neuraylib::IFunction_definition::DS_TERNARY
DB name: "mdl::operator?(bool,<0>,<0>)"
MDL name: "operator?(bool,<0>,<0>)"

The following requirements apply when creating function calls of the ternary operator:

Cast operator

Semantic: mi::neuraylib::IFunction_definition::DS_CAST
DB name: "mdl::operator_cast(<0>)"
MDL name: "operator_cast(<0>)"

The following requirements apply when creating function calls of the ternary operator:

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.

The MDL version.

Enumerator
MDL_VERSION_1_0 

MDL version 1.0.

MDL_VERSION_1_1 

MDL version 1.1.

MDL_VERSION_1_2 

MDL version 1.2.

MDL_VERSION_1_3 

MDL version 1.3.

MDL_VERSION_1_4 

MDL version 1.4.

MDL_VERSION_1_5 

MDL version 1.5.

MDL_VERSION_1_6 

MDL version 1.6.

MDL_VERSION_INVALID 

Invalid MDL version.