neuray API Programmer's Manual

mi::neuraylib::IMdl_compiled_material Class Reference

[Materials (MDL)]

Description

This interface represents a compiled material. A compiled material is a canonical representation of a material instance including all its attachments (function calls). In this canonical representation, all attachments are resolved and common subexpressions are identified (denoted as temporaries here).

Note that there are two modes to create compiled materials: instance compilation and class compilation. In instance compilation mode all arguments of the material instance, i.e., the values and the attachments are folded and the result is a constant (basically a struct with a fixed set of fields). In class compilation mode only the attachments are folded and the result is a symbolic constant where the value arguments of the material instance are represented by symbolic placeholders. The class compilation mode allows to share the compiled representation for materials if they are structurally equivalent (the attachment structure is similar) and only the value arguments differ.

Each field of the material is either a constant value, the result of function call, or the index of a temporary or an argument. Constant values are represented by the corresponding instance of mi::IData. Function calls are represented as values of type mi::ICall. References to temporaries are represented by instances of mi::ITemporary, whose value is the index into the array of temporaries. References to arguments appear only in case of class compilation. In this case they are represented by instances of mi::IParameter, whose value is the index into the array of arguments.

See also:

mi::neuraylib::IMdl_material_instance, mi::neuraylib::IMdl_function_call

Common methods related to instance and class compilation

virtual bool  depends_on_state_object_id() const =0
Indicates whether this material depends on state::object_id().
virtual bool  depends_on_state_transform() const =0
Indicates whether this material depends on coordinate space transformations like statetransform() and related functions.
virtual const IDataget_field( const char* name) const =0
Returns the value of a field. More...
template< class T>const T* get_field( const char* name) const
Returns the value of a field. More...
virtual Float32 get_mdl_meters_per_scene_unit() const =0
Returns the conversion ration between meters and scene units for this material.
virtual const IDataget_temporary( Uint32 index) const =0
Returns the value of a temporary. More...
template< class T>const T* get_temporary( Uint32 index) const
Returns the value of a temporary. More...
virtual Uint32 get_temporary_count() const =0
Returns the number of temporaries used by this material instance. More...

Additional methods related to class compilation

virtual const IDataget_argument( Uint32 index) const =0
Returns the value of an argument. More...
template< class T>const T* get_argument( Uint32 index) const
Returns the value of an argument. More...
virtual base::​Uuid get_hash() const =0
Returns a hash of all fields and temporaries. More...
virtual Uint32 get_parameter_count() const =0
Returns the number of parameters used by this material instance. More...
virtual const char* get_parameter_name( Uint32 index) const =0
Returns the name of a parameter. More...
virtual base::​Uuid get_slot_hash( Material_slot slot) const =0
Returns the hash of a particular material slot. More...

Member Functions

virtual bool mi::​neuraylib::​IMdl_compiled_material::depends_on_state_object_id() const [pure virtual]

Indicates whether this material depends on state::object_id().

virtual bool mi::​neuraylib::​IMdl_compiled_material::depends_on_state_transform() const [pure virtual]

Indicates whether this material depends on coordinate space transformations like statetransform() and related functions.

virtual const IData* mi::​neuraylib::​IMdl_compiled_material::get_argument( Uint32 index) const [pure virtual]

Returns the value of an argument. The number of arguments equals the number of parameters.

Parameters

index
The index of the argument.

Returns

The value of the argument, or NULL if index is out of range.

template< class T>

const T* mi::​neuraylib::​IMdl_compiled_material::get_argument( Uint32 index) const [inline]

Returns the value of an argument. This templated member function is a wrapper of the non-template variant for the user's convenience. It eliminates the need to call mi::base::IInterface::get_interface( const Uuid &) on the returned pointer, since the return type already is a pointer to the type T specified as template argument.

Parameters

index
The index of the argument.

Returns

The value of the argument, or NULL if index is out of range.

virtual const IData* mi::​neuraylib::​IMdl_compiled_material::get_field( const char* name) const [pure virtual]

Returns the value of a field. See [MDLLS] for details about the fields of a material.

Parameters

name
The name of the field.

Returns

The field value, or NULL if name is invalid.

template< class T>

const T* mi::​neuraylib::​IMdl_compiled_material::get_field( const char* name) const [inline]

Returns the value of a field. See [MDLLS] for details about the fields of a material.

This templated member function is a wrapper of the non-template variant for the user's convenience. It eliminates the need to call mi::base::IInterface::get_interface( const Uuid &) on the returned pointer, since the return type already is a pointer to the type T specified as template parameter.

Parameters

name
The name of the field.

Returns

The field value, or NULL if name is invalid.

virtual base::​Uuid mi::​neuraylib::​IMdl_compiled_material::get_hash() const [pure virtual]

Returns a hash of all fields and temporaries. The hash allows to quickly identify compiled materials that have the same fields and temporaries. Note that the arguments are not included in the hash value.

See also:

get_slot_hash() for hashes for individual material slots

virtual Float32 mi::​neuraylib::​IMdl_compiled_material::get_mdl_meters_per_scene_unit() const [pure virtual]

Returns the conversion ration between meters and scene units for this material.

virtual Uint32 mi::​neuraylib::​IMdl_compiled_material::get_parameter_count() const [pure virtual]

Returns the number of parameters used by this material instance.

Returns

The number of parameters.

virtual const char* mi::​neuraylib::​IMdl_compiled_material::get_parameter_name( Uint32 index) const [pure virtual]

Returns the name of a parameter. Note that the parameter name is only available if the corresponding parameter of the original material instance has a constant as argument. If that argument is an attachment, NULL is returned.

virtual base::​Uuid mi::​neuraylib::​IMdl_compiled_material::get_slot_hash( Material_slot slot) const [pure virtual]

Returns the hash of a particular material slot. The slots hashes allow to quickly compare slots of compiled materials. Note that the arguments are not included in the hash value.

See also:

get_hash() for a hash covering all slots together

virtual const IData* mi::​neuraylib::​IMdl_compiled_material::get_temporary( Uint32 index) const [pure virtual]

Returns the value of a temporary.

Parameters

index
The index of the temporary.

Returns

The value of the temporary, or NULL if index is out of range.

template< class T>

const T* mi::​neuraylib::​IMdl_compiled_material::get_temporary( Uint32 index) const [inline]

Returns the value of a temporary. This templated member function is a wrapper of the non-template variant for the user's convenience. It eliminates the need to call mi::base::IInterface::get_interface( const Uuid &) on the returned pointer, since the return type already is a pointer to the type T specified as template parameter.

Parameters

index
The index of the temporary.

Returns

The value of the temporary, or NULL if index is out of range.

virtual Uint32 mi::​neuraylib::​IMdl_compiled_material::get_temporary_count() const [pure virtual]

Returns the number of temporaries used by this material instance.

Returns

The number of temporaries.