This interface represents a compiled material. More...

#include <icompiled_material.h>

Inheritance diagram for mi::neuraylib::ICompiled_material:

[legend]

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 IExpression *	get_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...

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

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

virtual const char *	get_referenced_scene_data_name (Size index) const =0
	Return the name of a scene data attribute referenced by this instance. 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 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 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 IExpression *	lookup_sub_expression (const char *path) const =0
	Looks up a sub-expression of the compiled material. 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 database name of the mdl instance connected to the argument of a compiled material. More...

virtual Material_opacity	get_opacity () const =0
	Returns the opacity of the material. More...

virtual Material_opacity	get_surface_opacity () const =0
	Returns the surface opacity of the material by checking, if a transmissive BSDF is present in the `surface.scattering` slot of the material. More...

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

virtual bool	is_valid (IMdl_execution_context *context) const =0
	Returns `true`, if the compiled material is valid, `false` otherwise. 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 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 this 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 this 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 this 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 this 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 direct call expression that represents the body 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 database name of the mdl instance connected to the argument of a compiled material.

The parameters on the compiled material in class compilation mode can have more complex names if a shade graph has been compiled. The name corresponds to a path through the shade graph identifying a node and a parameter on that node whose value should be passed into the parameter of the compiled result. 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 that has been compiled.

Parameters

material_instance_name	The name of the material instance this material was compiled from.
parameter_index	The index of the parameter for which the database name of the connected function is to be looked up (e.g. if the compiled material has a parameter named `"tint.s.texture"` the function returns the database 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: The parameter material_instance_name is NULL or a material instance of that name does not exist in the database. -2: The given parameter index exceeds the parameter count of the compiled material. -3: The function 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 database name of the connected function or NULL in case an error occurred.

^◆ get_cutout_opacity()

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

pure virtual

Returns the cutout opacity of the material if it is constant.

Parameters

[out] cutout_opacity get the cutout_opacity value of the material

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 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

^◆ 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 for this material.

^◆ 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 material.

First, the cutout_opacity is checked. In case of opaque materials it is checked if a transmissive BSDF is present in the surface.scattering slot of the material.

^◆ 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.

^◆ get_parameter_name()

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.

^◆ 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 instance.

^◆ 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 instance.

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 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

^◆ get_surface_opacity()

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

pure virtual

Returns the surface opacity of the material by checking, if a transmissive BSDF is present in the surface.scattering slot of the material.

^◆ 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 element.

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 the expression of 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 used by this compiled material.

^◆ is_valid()

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

pure virtual

Returns true, if the compiled material is valid, false otherwise.

Parameters

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

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

^◆ 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_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_surface_opacity()

^◆ get_temporary() [1/2]

^◆ get_temporary() [2/2]

^◆ get_temporary_count()

^◆ is_valid()

^◆ lookup_sub_expression()