Material Definition Language API nvidia_logo_transpbg.gif Up
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
mi::neuraylib::ICompiled_material Class Referenceabstract

This interface represents a compiled material. More...

Inheritance diagram for mi::neuraylib::ICompiled_material:
mi::base::Interface_declare< 0x3115ab0f, 0x7a91, 0x4651, 0xa5, 0x9a, 0xfd, 0xb0, 0x23, 0x16, 0xb4, 0xb7, neuraylib::IScene_element > mi::neuraylib::IScene_element mi::base::Interface_declare< 0x8a2a4da9, 0xe323, 0x452c, 0xb8, 0xda, 0x92, 0x45, 0x67, 0x85, 0xd7, 0x78, neuraylib::IAttribute_set > mi::neuraylib::IAttribute_set mi::base::Interface_declare< 0x1bcb8d48, 0x10c1, 0x4b3e, 0x9b, 0xfa, 0x06, 0x23, 0x61, 0x81, 0xd3, 0xe1 > mi::base::IInterface

Public Member Functions

Common methods related to instance and class compilation
virtual const
IExpression_direct_call
get_body () const =0
 Returns the direct call expression that represents the body of the compiled material. More...
 
virtual Size get_temporary_count () const =0
 Returns the number of temporaries used by this compiled material. More...
 
virtual const IExpressionget_temporary (Size index) const =0
 Returns the expression of a temporary. More...
 
template<class T >
const T * get_temporary (Size index) const
 Returns the expression of a temporary. More...
 
virtual Float32 get_mdl_meters_per_scene_unit () const =0
 Returns the conversion ration between meters and scene units for this material. More...
 
virtual Float32 get_mdl_wavelength_min () const =0
 Returns the smallest supported wavelength. More...
 
virtual Float32 get_mdl_wavelength_max () const =0
 Returns the largest supported wavelength. More...
 
virtual bool depends_on_state_transform () const =0
 Indicates whether this material depends on coordinate space transformations like state::transform() and related functions. More...
 
virtual bool depends_on_state_object_id () const =0
 Indicates whether this material depends on state::object_id(). More...
 
virtual bool depends_on_global_distribution () const =0
 Indicates whether this material depends on global distribution (edf). More...
 
Additional methods related to class compilation
virtual Size get_parameter_count () const =0
 Returns the number of parameters used by this compiled material. More...
 
virtual const char * get_parameter_name (Size index) const =0
 Returns the name of a parameter. More...
 
virtual const IValueget_argument (Size index) const =0
 Returns the value of an argument. More...
 
template<class T >
const T * get_argument (Size index) const
 Returns the value of an argument. More...
 
virtual base::Uuid get_hash () const =0
 Returns a hash of the body and all temporaries. More...
 
virtual base::Uuid get_slot_hash (Material_slot slot) const =0
 Returns the hash of a particular material slot. More...
 
virtual const IExpressionlookup_sub_expression (const char *path) const =0
 Looks up a sub-expression of the compiled material. More...
 

Additional Inherited Members

- Public Types inherited from mi::base::Interface_declare< 0x3115ab0f, 0x7a91, 0x4651, 0xa5, 0x9a, 0xfd, 0xb0, 0x23, 0x16, 0xb4, 0xb7, neuraylib::IScene_element >
typedef Interface_declare< id1,
id2, id3, id4, id5, id6, id7,
id8, id9, id10, id11,
neuraylib::IScene_element
Self
 Own type. More...
 
typedef Uuid_t< id1, id2, id3,
id4, id5, id6, id7, id8, id9,
id10, id11 > 
IID
 Declares the interface ID (IID) of this interface. More...
 
- Static Public Member Functions inherited from mi::base::Interface_declare< 0x3115ab0f, 0x7a91, 0x4651, 0xa5, 0x9a, 0xfd, 0xb0, 0x23, 0x16, 0xb4, 0xb7, neuraylib::IScene_element >
static bool compare_iid (const Uuid &iid)
 Compares the interface ID iid against the interface ID of this interface and of its ancestors. More...
 

Detailed Description

This interface represents a compiled material.

A compiled material is a canonical representation of a material instance including all its arguments (constants and call expressions). In this canonical representation, all function calls are folded into one expression 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 constants and calls, are folded and the result is an expression without any references to arguments anymore. In class compilation mode only the calls are folded and the result is an expression where the constant 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 call structure is similar) and only the value arguments differ.

The expression that represents the compiled material consists of constant values, results of function calls, indices of temporaries, or indices of arguments. Constant values are represented by expressions of the kind mi::neuraylib::IExpression_constant. Function calls are represented by expressions of the kind mi::neuraylib::IExpression_direct_call. References to temporaries are represented by expressions of the kind mi::neuraylib::IExpression_temporary, 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 expressions of the kind mi::neuraylib::IExpression_parameter, whose value is the index into the array of arguments.

See Also
mi::neuraylib::IMaterial_instance, mi::neuraylib::IFunction_call

Member Function Documentation

virtual bool mi::neuraylib::ICompiled_material::depends_on_global_distribution ( ) const
pure virtual

Indicates whether this material depends on global distribution (edf).

virtual bool mi::neuraylib::ICompiled_material::depends_on_state_object_id ( ) const
pure virtual

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

virtual bool mi::neuraylib::ICompiled_material::depends_on_state_transform ( ) const
pure virtual

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

virtual const IValue* mi::neuraylib::ICompiled_material::get_argument ( Size  index) const
pure virtual

Returns the value of an argument.

Parameters
indexThe 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::ICompiled_material::get_argument ( Size  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.

Template Parameters
TThe interface type of the requested element
Parameters
indexThe index of the argument.
Returns
The value of the argument, or NULL if index is out of range.
virtual const IExpression_direct_call* mi::neuraylib::ICompiled_material::get_body ( ) const
pure virtual

Returns the direct call expression that represents the body of the compiled material.

virtual base::Uuid mi::neuraylib::ICompiled_material::get_hash ( ) const
pure virtual

Returns a hash of the body and all temporaries.

The hash allows to quickly identify compiled materials that have the same body and temporaries. Note that the arguments are not included in the hash value.

Note
For performance reasons, the hash for resources does not include the actual resource data, but certain properties to identify resources: If the absolute MDL file path is available, it is used (including the gamma value for textures). If the absolute MDL file path is not available, some internal IDs that identify the resource in the database are used instead.
For the latter case, the following applies: If two otherwise identical materials share a resource (in the sense of there is one and only one DB element for that resource), then their hash is also identical. But if the materials use distinct (but otherwise identical) copies of the same DB element, then their IDs are different, resulting in different hashes. IDs are also different if a module is removed from the database, and later loaded again. IDs might be different if the module is loaded in different processes.
See Also
get_slot_hash() for hashes for individual material slots
virtual Float32 mi::neuraylib::ICompiled_material::get_mdl_meters_per_scene_unit ( ) const
pure virtual

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

virtual Float32 mi::neuraylib::ICompiled_material::get_mdl_wavelength_max ( ) const
pure virtual

Returns the largest supported wavelength.

virtual Float32 mi::neuraylib::ICompiled_material::get_mdl_wavelength_min ( ) const
pure virtual

Returns the smallest supported wavelength.

virtual Size mi::neuraylib::ICompiled_material::get_parameter_count ( ) const
pure virtual

Returns the number of parameters used by this compiled material.

virtual const char* mi::neuraylib::ICompiled_material::get_parameter_name ( Size  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 a call, NULL is returned.

virtual base::Uuid mi::neuraylib::ICompiled_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.

Note
For performance reasons, the hash for resources does not include the actual resource data, but certain properties to identify resources: If the absolute MDL file path is available, it is used (including the gamma value for textures). If the absolute MDL file path is not available, some internal IDs that identify the resource in the database are used instead.
For the latter case, the following applies: If two otherwise identical materials share a resource (in the sense of there is one and only one DB element for that resource), then their hash is also identical. But if the materials use distinct (but otherwise identical) copies of the same DB element, then their IDs are different, resulting in different hashes. IDs are also different if a module is removed from the database, and later loaded again. IDs might be different if the module is loaded in different processes.
See Also
get_hash() for a hash covering all slots together
virtual const IExpression* mi::neuraylib::ICompiled_material::get_temporary ( Size  index) const
pure virtual

Returns the expression of a temporary.

Parameters
indexThe index of the temporary.
Returns
The expression of the temporary, or NULL if index is out of range.
template<class T >
const T* mi::neuraylib::ICompiled_material::get_temporary ( Size  index) const
inline

Returns the expression 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.

Template Parameters
TThe interface type of the requested element
Parameters
indexThe index of the temporary.
Returns
The expression of the temporary, or NULL if index is out of range.
virtual Size mi::neuraylib::ICompiled_material::get_temporary_count ( ) const
pure virtual

Returns the number of temporaries used by this compiled material.

virtual const IExpression* mi::neuraylib::ICompiled_material::lookup_sub_expression ( const char *  path) const
pure virtual

Looks up a sub-expression of the compiled material.

Parameters
pathThe path from the material root to the expression that should be returned, e.g., "surface.scattering.tint".
Returns
A sub-expression for expr according to path, or NULL in case of errors.