This interface represents a compiled material. More...

#include <icompiled_material.h>

Inheritance diagram for mi::neuraylib::ICompiled_material:

[legend]

Public Member Functions
Material body and temporaries
virtual const IExpression_direct_call *	get_body () const =0
	Returns the body (or material root) of the compiled material. More...

virtual Size	get_temporary_count () const =0
	Returns the number of temporaries. More...

virtual const IExpression *	get_temporary (Size index) const =0
	Returns a temporary. More...

template<class T>
const T *	get_temporary (Size index) const
	Returns the expression of a temporary. More...

virtual const IExpression *	lookup_sub_expression (const char *path) const =0
	Looks up a sub-expression of the compiled material. More...

virtual bool	is_valid (IMdl_execution_context *context) const =0
	Indicates whether the compiled material is valid. More...

Parameters and arguments (class compilation mode only)
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 IValue *	get_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 const IString *	get_connected_function_db_name (const char material_instance_name, Size parameter_index, Sint32 errors=0) const =0
	Looks up the DB name of a function call connected to the argument of a compiled material. More...

Properties of the compiled material
virtual Float32	get_mdl_meters_per_scene_unit () const =0
	Returns the conversion ration between meters and scene units. 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 Material_opacity	get_opacity () const =0
	Returns the opacity of the compiled material. More...

virtual Material_opacity	get_surface_opacity () const =0
	Returns the surface opacity of the compiled material. More...

virtual bool	get_cutout_opacity (Float32 *cutout_opacity) const =0
	Returns the cutout opacity (provided it is a constant). More...

virtual Size	get_referenced_scene_data_count () const =0
	Returns the number of scene data attributes referenced by this compiled material. More...

virtual const char *	get_referenced_scene_data_name (Size index) const =0
	Return the name of a scene data attribute referenced by this compiled material. More...

virtual bool	depends_on_state_transform () const =0
	Indicates whether the compiled material depends on coordinate space transformations like `state::transform`() and related functions. More...

virtual bool	depends_on_state_object_id () const =0
	Indicates whether the compiled material depends on `state::object_id()`. More...

virtual bool	depends_on_global_distribution () const =0
	Indicates whether the compiled material depends on global distribution (edf). More...

virtual bool	depends_on_uniform_scene_data () const =0
	Indicates whether the compiled material depends on uniform scene data. More...

Hash values of the compiled material or parts thereof
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 base::Uuid	get_sub_expression_hash (const char *path) const =0
	Returns the hash of a sub-expression of the compiled material. More...

Public Member Functions inherited from mi::neuraylib::IScene_element
virtual Element_type	get_element_type () const =0
	Indicates the actual scene element represented by interfaces derived from this interface. More...

Public Member Functions inherited from mi::neuraylib::IAttribute_set
virtual IData *	create_attribute (const char name, const char type)=0
	Creates a new attribute `name` of the type `type`. More...

template<class T>
T *	create_attribute (const char name, const char type)
	Creates a new attribute `name` of the type `type`. More...

template<class T>
T *	create_attribute (const char *name)
	Creates a new attribute `name` of the type `T`. More...

virtual bool	destroy_attribute (const char *name)=0
	Destroys the attribute `name`. More...

virtual const IData *	access_attribute (const char *name) const =0
	Returns a const pointer to the attribute `name`. More...

template<class T>
const T *	access_attribute (const char *name) const
	Returns a const pointer to the attribute `name`. More...

virtual IData *	edit_attribute (const char *name)=0
	Returns a mutable pointer to the attribute `name`. More...

template<class T>
T *	edit_attribute (const char *name)
	Returns a mutable pointer to the attribute `name`. More...

virtual bool	is_attribute (const char *name) const =0
	Indicates existence of an attribute. More...

virtual const char *	get_attribute_type_name (const char *name) const =0
	Returns the type of an attribute. More...

virtual Sint32	set_attribute_propagation (const char *name, Propagation_type value)=0
	Sets the propagation type of the attribute `name`. More...

virtual Propagation_type	get_attribute_propagation (const char *name) const =0
	Returns the propagation type of the attribute `name`. More...

virtual const char *	enumerate_attributes (Sint32 index) const =0
	Returns the name of the attribute indicated by `index`. More...

Public Member Functions inherited from mi::base::IInterface
virtual Uint32	retain () const =0
	Increments the reference count. More...

virtual Uint32	release () const =0
	Decrements the reference count. More...

virtual const IInterface *	get_interface (const Uuid &interface_id) const =0
	Acquires a const interface from another. More...

template<class T>
const T *	get_interface () const
	Acquires a const interface from another. More...

virtual IInterface *	get_interface (const Uuid &interface_id)=0
	Acquires a mutable interface from another. More...

template<class T>
T *	get_interface ()
	Acquires a mutable interface from another. More...

virtual Uuid	get_iid () const =0
	Returns the interface ID of the most derived interface. More...

Additional Inherited Members
Public Types inherited from mi::base::Interface_declare< 0x3115ab0f, ... >
typedef Interface_declare< id1, ... >	Self
	Own type. More...

typedef Uuid_t< id1, ... >	IID
	Declares the interface ID (IID) of this interface. More...

Public Types inherited from mi::base::Interface_declare< 0x8a2a4da9, ... >
typedef Interface_declare< id1, ... >	Self
	Own type. More...

typedef Uuid_t< id1, ... >	IID
	Declares the interface ID (IID) of this interface. More...

Public Types inherited from mi::base::Interface_declare< 0x1bcb8d48, ... >
typedef Interface_declare< id1, ... >	Self
	Own type. More...

typedef Uuid_t< id1, ... >	IID
	Declares the interface ID (IID) of this interface. More...

Public Types inherited from mi::base::IInterface
typedef Uuid_t<0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0>	IID
	Declares the interface ID (IID) of this interface. More...

Static Public Member Functions inherited from mi::base::Interface_declare< 0x3115ab0f, ... >
static bool	compare_iid (const Uuid &iid)
	Compares the interface ID `iid` against the interface ID of this interface and of its ancestors. More...

Static Public Member Functions inherited from mi::base::Interface_declare< 0x8a2a4da9, ... >
static bool	compare_iid (const Uuid &iid)
	Compares the interface ID `iid` against the interface ID of this interface and of its ancestors. More...

Static Public Member Functions inherited from mi::base::Interface_declare< 0x1bcb8d48, ... >
static bool	compare_iid (const Uuid &iid)
	Compares the interface ID `iid` against the interface ID of this interface and of its ancestors. More...

Static Public Member Functions inherited from mi::base::IInterface
static bool	compare_iid (const Uuid &iid)
	Compares the interface ID `iid` against the interface ID of this interface. 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 (if possible) 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

^◆ depends_on_global_distribution()

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

pure virtual

Indicates whether the compiled material depends on global distribution (edf).

^◆ depends_on_state_object_id()

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

pure virtual

Indicates whether the compiled material depends on state::object_id().

^◆ depends_on_state_transform()

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

pure virtual

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

^◆ depends_on_uniform_scene_data()

virtual bool mi::neuraylib::ICompiled_material::depends_on_uniform_scene_data ( ) const

pure virtual

Indicates whether the compiled material depends on uniform scene data.

^◆ get_argument() [1/2]

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

T	The interface type of the requested element

Parameters

index The index of the argument.

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

^◆ get_argument() [2/2]

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

pure virtual

Returns the value of an argument.

Parameters

index The index of the argument.

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

^◆ get_body()

virtual const IExpression_direct_call * mi::neuraylib::ICompiled_material::get_body ( ) const

pure virtual

Returns the body (or material root) of the compiled material.

^◆ get_connected_function_db_name()

virtual const IString * mi::neuraylib::ICompiled_material::get_connected_function_db_name	(	const char *	material_instance_name,
		Size	parameter_index,
		Sint32 *	errors = `0`
	)		const

pure virtual

Looks up the DB name of a function call connected to the argument of a compiled material.

Parameters

material_instance_name	The name of the material instance this compiled material was compiled from.
parameter_index	The index of the parameter for which the DB name of the connected function call is to be looked up. For example, if the compiled material has a parameter named `"tint.s.texture"` the function returns DB name of the function connected to the tint parameter.
errors	An optional pointer to an mi::Sint32 to which an error code will be written. The error codes have the following meaning: 0: Success. -1: `material_instance_name` is `NULL`, or there is no material instance of that name. -2: `parameter_index` is out of bounds. -3: The corresponding function call could not be found in the database. This might be due to the fact that the given parameter is not connected to a function or the material instance has been changed after the creation of this compiled material.

Returns: The DB name of the connected function call, or NULL in case of errors.

^◆ get_cutout_opacity()

virtual bool mi::neuraylib::ICompiled_material::get_cutout_opacity ( Float32 * cutout_opacity ) const

pure virtual

Returns the cutout opacity (provided it is a constant).

See also: get_opacity() and get_surface_opacity()

Parameters

[out] cutout_opacity The cutout opacity value in case of success.

Returns: true in case of success, false if the value is not a constant, but depends on parameters or complex user expressions.

^◆ get_hash()

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, temporaries, and parameter names. Note that the arguments themselves 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 and selector 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 compiled 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 compiled 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 of predefined material slots, and get_sub_expression_hash() for hashes of arbitrary subexpressions

^◆ get_mdl_meters_per_scene_unit()

virtual Float32 mi::neuraylib::ICompiled_material::get_mdl_meters_per_scene_unit ( ) const

pure virtual

Returns the conversion ration between meters and scene units.

^◆ get_mdl_wavelength_max()

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

pure virtual

Returns the largest supported wavelength.

^◆ get_mdl_wavelength_min()

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

pure virtual

Returns the smallest supported wavelength.

^◆ get_opacity()

virtual Material_opacity mi::neuraylib::ICompiled_material::get_opacity ( ) const

pure virtual

Returns the opacity of the compiled material.

The method returns OPACITY_TRANSPARENT if the cutout opacity is a constant and less than 1.0. Otherwise it checks whether a transmissive BSDF is present in the surface.scattering slot.

See get_surface_opacity() for a variant ignoring the cutout opacity, and get_cutout_opacity() to retrieve the cutout opacity itself.

^◆ get_parameter_count()

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

pure virtual

Returns the number of parameters used by this compiled material.

Parameters and arguments only exist in class compilation mode. This method always returns 0 in instance compilation mode.

^◆ get_parameter_name()

virtual const char * mi::neuraylib::ICompiled_material::get_parameter_name ( Size index ) const

pure virtual

Returns the name of a parameter.

In class compilation mode, the parameters are named according to the path to the corresponding node in the open material graph that served as basis for the compiled material. For example, the path "a.b.x" refers to a parameter named "x" on a node connected to a parameter named "b" on a node connected to the parameter "a" of the material instance that has been compiled.

Note that these paths here correspond to the open material graph that served as basis for the compiled material, and not to the structure of the resulting compiled material, as it is the case for lookup_sub_expression() or get_sub_expression_hash().

Parameters

index The index of the parameter.

Returns: The name of the parameter, or NULL if index is out of range.

^◆ get_referenced_scene_data_count()

virtual Size mi::neuraylib::ICompiled_material::get_referenced_scene_data_count ( ) const

pure virtual

Returns the number of scene data attributes referenced by this compiled material.

^◆ get_referenced_scene_data_name()

virtual const char * mi::neuraylib::ICompiled_material::get_referenced_scene_data_name ( Size index ) const

pure virtual

Return the name of a scene data attribute referenced by this compiled material.

Parameters

index The index of the scene data attribute.

^◆ get_slot_hash()

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 hash allows to quickly identify compiled materials where a particular material slot is identical (corresponding parts of the body and temporaries, and all parameter names). Note that the arguments themselves are not included in the hash value. See get_hash() for details about resources.

See also: get_hash() for a hash covering all slots in one hash value, and get_sub_expression_hash() for hashes of arbitrary subexpressions

^◆ get_sub_expression_hash()

virtual base::Uuid mi::neuraylib::ICompiled_material::get_sub_expression_hash ( const char * path ) const

pure virtual

Returns the hash of a sub-expression of the compiled material.

The hash allows to quickly identify compiled materials where a particular sub-expression is identical (corresponding parts of the body and temporaries, and all parameter names). Note that the arguments themselves are not included in the hash value. See get_hash() for details about resources.

Note: This hash value is computed on-demand, unless the path corresponds to one of the predefined material slots, for which the method simply returns the precomputed hash value.

See also: get_hash() for a hash covering all slots in one hash value, and get_slot_hash() for hashes of predefined material slots

Parameters

path	The path from the material root to the expression that should be hashed, e.g., `"surface.scattering.tint"`. An empty path can be used to identify the entire compiled material.

Returns: A hash for the sub-expression identified by path, or default-constructed in case invalid paths.

^◆ get_surface_opacity()

virtual Material_opacity mi::neuraylib::ICompiled_material::get_surface_opacity ( ) const

pure virtual

Returns the surface opacity of the compiled material.

The methods checks whether a transmissive BSDF is present in the surface.scattering slot.

See get_opacity() for a variant taking the cutout opacity into account, and get_cutout_opacity() to retrieve the cutout opacity itself.

^◆ get_temporary() [1/2]

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

T	The interface type of the requested temporary.

Parameters

index The index of the temporary.

Returns: The expression of the temporary, or NULL if index is out of range.

^◆ get_temporary() [2/2]

virtual const IExpression * mi::neuraylib::ICompiled_material::get_temporary ( Size index ) const

pure virtual

Returns a temporary.

Parameters

index The index of the temporary.

Returns: The expression of the temporary, or NULL if index is out of range.

^◆ get_temporary_count()

virtual Size mi::neuraylib::ICompiled_material::get_temporary_count ( ) const

pure virtual

Returns the number of temporaries.

^◆ is_valid()

virtual bool mi::neuraylib::ICompiled_material::is_valid ( IMdl_execution_context * context ) const

pure virtual

Indicates whether the compiled material is valid.

A compiled material becomes invalid, if any of the modules it uses definitions from has has been reloaded.

Parameters

context In case of failure, the execution context can be checked for error messages. Can be NULL.

^◆ lookup_sub_expression()

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

path	The 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.

Public Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ depends_on_global_distribution()

◆ depends_on_state_object_id()

◆ depends_on_state_transform()

◆ depends_on_uniform_scene_data()

◆ get_argument() [1/2]

◆ get_argument() [2/2]

◆ get_body()

◆ get_connected_function_db_name()

◆ get_cutout_opacity()

◆ get_hash()

◆ get_mdl_meters_per_scene_unit()

◆ get_mdl_wavelength_max()

◆ get_mdl_wavelength_min()

◆ get_opacity()

◆ get_parameter_count()

◆ get_parameter_name()

◆ get_referenced_scene_data_count()

◆ get_referenced_scene_data_name()

◆ get_slot_hash()

◆ get_sub_expression_hash()

◆ get_surface_opacity()

◆ get_temporary() [1/2]

◆ get_temporary() [2/2]

◆ get_temporary_count()

◆ is_valid()

◆ lookup_sub_expression()

^◆ depends_on_global_distribution()

^◆ depends_on_state_object_id()

^◆ depends_on_state_transform()

^◆ depends_on_uniform_scene_data()

^◆ get_argument() [1/2]

^◆ get_argument() [2/2]

^◆ get_body()

^◆ get_connected_function_db_name()

^◆ get_cutout_opacity()

^◆ get_hash()

^◆ get_mdl_meters_per_scene_unit()

^◆ get_mdl_wavelength_max()

^◆ get_mdl_wavelength_min()

^◆ get_opacity()

^◆ get_parameter_count()

^◆ get_parameter_name()

^◆ get_referenced_scene_data_count()

^◆ get_referenced_scene_data_name()

^◆ get_slot_hash()

^◆ get_sub_expression_hash()

^◆ get_surface_opacity()

^◆ get_temporary() [1/2]

^◆ get_temporary() [2/2]

^◆ get_temporary_count()

^◆ is_valid()

^◆ lookup_sub_expression()