An instantiated material. More...

#include <mdl_generated_dag.h>

Inheritance diagram for mi::mdl::IMaterial_instance:

Public Types
enum	Flags { INSTANCE_COMPILATION = 0 << 0 , CLASS_COMPILATION = 1 << 0 , NO_ARGUMENT_INLINE = 1 << 1 , NO_RESOURCE_SHARING = 1 << 2 , NO_TERNARY_ON_DF = 1 << 3 , NO_DEAD_PARAMS = 1 << 4 , NO_STRING_PARAMS = 1 << 5 , NO_BOOL_PARAMS = 1 << 6 , NO_ENUM_PARAMS = 1 << 7 , NO_TRIVIAL_CUTOUT_OPACITY = 1 << 8 , NO_TRANSPARENT_LAYERS = 1 << 9 , IGNORE_NOINLINE = 1 << 10 , TARGET_MATERIAL_MODEL = 1 << 11 , DEFAULT_CLASS_COMPILATION }
	Instantiation flags. More...

enum	Slot { MS_THIN_WALLED , MS_SURFACE_BSDF_SCATTERING , MS_SURFACE_EMISSION_EDF_EMISSION , MS_SURFACE_EMISSION_INTENSITY , MS_SURFACE_EMISSION_MODE , MS_BACKFACE_BSDF_SCATTERING , MS_BACKFACE_EMISSION_EDF_EMISSION , MS_BACKFACE_EMISSION_INTENSITY , MS_BACKFACE_EMISSION_MODE , MS_IOR , MS_VOLUME_VDF_SCATTERING , MS_VOLUME_ABSORPTION_COEFFICIENT , MS_VOLUME_SCATTERING_COEFFICIENT , MS_VOLUME_EMISSION_INTENSITY , MS_GEOMETRY_DISPLACEMENT , MS_GEOMETRY_CUTOUT_OPACITY , MS_GEOMETRY_NORMAL , MS_HAIR , MS_LAST = MS_HAIR }
	Material slots on which hashes are calculated. More...

enum	Property { IP_DEPENDS_ON_TRANSFORM = 0x001 , IP_DEPENDS_ON_OBJECT_ID = 0x002 , IP_DEPENDS_ON_GLOBAL_DISTRIBUTION = 0x004 , IP_USES_TERNARY_OPERATOR = 0x008 , IP_USES_TERNARY_OPERATOR_ON_DF = 0x010 , IP_CLASS_COMPILED = 0x020 , IP_DISTILLED = 0x040 , IP_DEPENDS_ON_UNIFORM_SCENE_DATA = 0x080 , IP_TARGET_MATERIAL_MODEL = 0x100 }
	Property flags of an instance. More...

enum	Opacity { OPACITY_OPAQUE , OPACITY_TRANSPARENT , OPACITY_UNKNOWN }
	Opacity of an instance. More...

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

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

Public Member Functions
virtual IType_factory *	get_type_factory ()=0
	Get the type factory of this instance. More...

virtual IValue_factory *	get_value_factory ()=0
	Get the value factory of this instance. More...

virtual DAG_constant const *	create_constant (IValue const *value)=0
	Create a constant node. More...

virtual DAG_node const *	create_call (char const signature, IDefinition::Semantics sema, DAG_call::Call_argument const call_args[], int num_call_args, IType const ret_type)=0
	Create a call node. More...

virtual DAG_parameter const *	create_parameter (IType const *type, int index)=0
	Create a parameter reference node. More...

virtual Error_code	initialize (ICall_name_resolver resolver, IResource_modifier resource_modifier, IGenerated_code_dag const code_dag, size_t argc, DAG_node const argv[], bool use_temporaries, unsigned flags, ICall_evaluator evaluator, bool fold_meters_per_scene_unit, float mdl_meters_per_scene_unit, float wavelength_min, float wavelength_max, char const const fold_params[], size_t num_fold_params, IType const *target_type)=0
	Initialize this material instance. More...

virtual DAG_call const *	get_constructor () const =0
	Return the material constructor of this instance. More...

virtual size_t	get_temporary_count () const =0
	Return the number of temporaries of this instance. More...

virtual DAG_node const *	get_temporary_value (size_t index) const =0
	Return the value of the temporary at index. More...

virtual size_t	get_parameter_count () const =0
	Return the number of parameters of this instance. More...

virtual IValue const *	get_parameter_default (size_t index) const =0
	Return the default value of a parameter of this instance. More...

virtual void	lookup_sub_expression (char const path, DAG_node const &node_result, IValue const *&value_result) const =0
	Return the node determined by the path, starting from the root expression of the material instance. More...

virtual DAG_hash	get_sub_expression_hash (char const *path) const =0
	Calculate the hash for the node determined by the path, starting from the root expression of the material instance. More...

virtual DAG_hash const *	get_hash () const =0
	Return the hash value of this material instance. More...

virtual DAG_hash const *	get_slot_hash (Slot slot) const =0
	Return the hash value of one material slot of this material instance. More...

virtual char const *	get_parameter_name (size_t index) const =0
	Return the canonical parameter name of the given parameter. More...

virtual bool	depends_on_transform () const =0
	Returns true if this instance depends on object transforms. More...

virtual bool	depends_on_object_id () const =0
	Returns true if this instance depends on the object id. More...

virtual bool	depends_on_global_distribution () const =0
	Returns true if this instance depends on the global distribution (edf). More...

virtual bool	depends_on_uniform_scene_data () const =0
	Returns true if this instance depends on uniform scene data. More...

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

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

virtual Opacity	get_opacity () const =0
	Returns the opacity of this instance. More...

virtual Opacity	get_surface_opacity () const =0
	Returns the surface opacity of this instance. More...

virtual IValue_float const *	get_cutout_opacity () const =0
	Returns the cutout opacity of this instance if it is constant. More...

virtual Messages const &	access_messages () const =0
	Access messages. More...

virtual size_t	get_memory_size () const =0
	Returns the amount of used memory by this code material instance. More...

virtual Properties	get_properties () const =0
	Get the instance properties. More...

virtual char const *	get_internal_space () const =0
	Get the internal space. More...

virtual void	set_resource_tag (IValue_resource const *res, int tag)=0
	Set a tag, version pair for a resource constant that might be reachable from this instance. More...

virtual size_t	get_resource_tag_map_entries_count () const =0
	Get the number of resource tag map entries. More...

virtual Resource_tag_tuple const *	get_resource_tag_map_entry (size_t index) const =0
	Get the i'th resource tag map entry or NULL if the index is out of bounds;. More...

virtual IResource_tagger *	get_resource_tagger () const =0
	Get the resource tagger for this material instance. More...

Additional Inherited Members
Static Public Member Functions inherited from mi::base::Interface_declare< 0x29c36255, ... >
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

An instantiated material.

With an IGenerated_code_dag at hand, creating an instantiated material usually consists of these steps:

Create the object with IGenerated_code_dag::create_material_instance().
Build the argument list using the IValue_factory retrieved from IMaterial_instance::get_value_factory(). Material parameter defaults retrieved from IGenerated_code_dag::get_material_parameter_default() can be used directly.
Call IMaterial_instance::initialize().

Member Enumeration Documentation

^◆ Flags

enum mi::mdl::IMaterial_instance::Flags

Instantiation flags.

Enumerator
INSTANCE_COMPILATION	Do an instance compilation, default.
CLASS_COMPILATION	Do a class compilation.
NO_ARGUMENT_INLINE	CLASS_COMPILATION: Do not inline any arguments.
NO_RESOURCE_SHARING	CLASS_COMPILATION: Do not share resource arguments.
NO_TERNARY_ON_DF	CLASS_COMPILATION: Do not allow ?: on df.
NO_DEAD_PARAMS	CLASS_COMPILATION: Remove dead parameters.
NO_STRING_PARAMS	CLASS_COMPILATION: Do not create string parameters.
NO_BOOL_PARAMS	CLASS_COMPILATION: Do not create bool parameters.
NO_ENUM_PARAMS	CLASS_COMPILATION: Do not create enum parameters.
NO_TRIVIAL_CUTOUT_OPACITY	CLASS_COMPILATION: Do not create a parameter for geometry.cutout_opacity if its value is constant 0.0f or 1.0f.
NO_TRANSPARENT_LAYERS	CLASS_COMPILATION: Do not create layering calls for transparent layers, i.e., with weight 0.0f.
IGNORE_NOINLINE	Ignore anno::noinline() annotations.
TARGET_MATERIAL_MODEL	Target material model mode.
DEFAULT_CLASS_COMPILATION	Do class compilation with default flags.

^◆ Opacity

enum mi::mdl::IMaterial_instance::Opacity

Opacity of an instance.

Enumerator
OPACITY_OPAQUE	opaque for sure
OPACITY_TRANSPARENT	transparent for sure
OPACITY_UNKNOWN	opacity unknown (depends on parameter or complex user expression)

^◆ Property

enum mi::mdl::IMaterial_instance::Property

Property flags of an instance.

Enumerator
IP_DEPENDS_ON_TRANSFORM	depends on object transforms
IP_DEPENDS_ON_OBJECT_ID	depends of the object id
IP_DEPENDS_ON_GLOBAL_DISTRIBUTION	depends on global distribution (edf)
IP_USES_TERNARY_OPERATOR	uses the ternary operator '?:'
IP_USES_TERNARY_OPERATOR_ON_DF	uses the ternary operator '?:' on *df
IP_CLASS_COMPILED	was class compiled
IP_DISTILLED	was created by the distiller
IP_DEPENDS_ON_UNIFORM_SCENE_DATA	depends on uniform scene data
IP_TARGET_MATERIAL_MODEL	instance is in target material mode

^◆ Slot

enum mi::mdl::IMaterial_instance::Slot

Material slots on which hashes are calculated.

Enumerator
MS_THIN_WALLED	.thin_walled
MS_SURFACE_BSDF_SCATTERING	.surface.scattering
MS_SURFACE_EMISSION_EDF_EMISSION	.surface.emission.emission
MS_SURFACE_EMISSION_INTENSITY	.surface.emission.intensity
MS_SURFACE_EMISSION_MODE	.surface.emission.mode
MS_BACKFACE_BSDF_SCATTERING	.backface.scattering
MS_BACKFACE_EMISSION_EDF_EMISSION	.backface.emission.emission
MS_BACKFACE_EMISSION_INTENSITY	.backface.emission.intensity
MS_BACKFACE_EMISSION_MODE	.backface.emission.mode
MS_IOR	.ior
MS_VOLUME_VDF_SCATTERING	.volume.scattering
MS_VOLUME_ABSORPTION_COEFFICIENT	.volume.absorption_coefficient
MS_VOLUME_SCATTERING_COEFFICIENT	.volume.scattering_coefficient
MS_VOLUME_EMISSION_INTENSITY	.volume.emission_intensity
MS_GEOMETRY_DISPLACEMENT	.geometry.displacement
MS_GEOMETRY_CUTOUT_OPACITY	.geometry.cutout_opacity
MS_GEOMETRY_NORMAL	.geometry.normal
MS_HAIR	.hair

Member Function Documentation

^◆ access_messages()

virtual Messages const & mi::mdl::IMaterial_instance::access_messages ( ) const

pure virtual

Access messages.

^◆ create_call()

virtual DAG_node const * mi::mdl::IMaterial_instance::create_call	(	char const *	signature,
		IDefinition::Semantics	sema,
		DAG_call::Call_argument const	call_args[],
		int	num_call_args,
		IType const *	ret_type
	)

pure virtual

Create a call node.

Parameters

signature	The signature of the called function.
sema	The semantic of the called function.
call_args	The call arguments of the called function.
num_call_args	The number of call arguments.
ret_type	The return type of the called function.

Returns: The created call.

Note: Use this method to create arguments of the instance.

^◆ create_constant()

virtual DAG_constant const * mi::mdl::IMaterial_instance::create_constant ( IValue const * value )

pure virtual

Create a constant node.

Parameters

value The value of the constant.

Returns: The created constant.

Note: Use this method to create arguments of the instance.

^◆ create_parameter()

virtual DAG_parameter const * mi::mdl::IMaterial_instance::create_parameter	(	IType const *	type,
		int	index
	)

pure virtual

Create a parameter reference node.

Parameters

type	The type of the parameter
index	The index of the parameter.

Returns: The created parameter reference.

^◆ depends_on_global_distribution()

virtual bool mi::mdl::IMaterial_instance::depends_on_global_distribution ( ) const

pure virtual

Returns true if this instance depends on the global distribution (edf).

If this returns true, the material body expression of this material instance might depend on the MDL edf with global distribution.

^◆ depends_on_object_id()

virtual bool mi::mdl::IMaterial_instance::depends_on_object_id ( ) const

pure virtual

Returns true if this instance depends on the object id.

If this returns true, the material body expression of this material instance might depend on the MDL uniform state::object_id() state function.

^◆ depends_on_transform()

virtual bool mi::mdl::IMaterial_instance::depends_on_transform ( ) const

pure virtual

Returns true if this instance depends on object transforms.

If this returns true, the material body expression of this material instance might depend on the MDL uniform state::transform_*() state functions.

^◆ depends_on_uniform_scene_data()

virtual bool mi::mdl::IMaterial_instance::depends_on_uniform_scene_data ( ) const

pure virtual

Returns true if this instance depends on uniform scene data.

^◆ get_constructor()

virtual DAG_call const * mi::mdl::IMaterial_instance::get_constructor ( ) const

pure virtual

Return the material constructor of this instance.

This method returns the body expression of a material instance. This is always a call to the MDL material constructor.

^◆ get_cutout_opacity()

virtual IValue_float const * mi::mdl::IMaterial_instance::get_cutout_opacity ( ) const

pure virtual

Returns the cutout opacity of this instance if it is constant.

Returns: if the cutout opacity is a constant (and was read), NULL if it depends on parameters / complex user expressions

^◆ get_hash()

virtual DAG_hash const * mi::mdl::IMaterial_instance::get_hash ( ) const

pure virtual

Return the hash value of this material instance.

This is equivalent to the call get_sub_expression_hash() with the empty path "".

This returns the hash-value of the body expression of this material instance.

^◆ get_internal_space()

virtual char const * mi::mdl::IMaterial_instance::get_internal_space ( ) const

pure virtual

Get the internal space.

^◆ get_memory_size()

virtual size_t mi::mdl::IMaterial_instance::get_memory_size ( ) const

pure virtual

Returns the amount of used memory by this code material instance.

^◆ get_opacity()

virtual Opacity mi::mdl::IMaterial_instance::get_opacity ( ) const

pure virtual

Returns the opacity of this instance.

^◆ get_parameter_count()

virtual size_t mi::mdl::IMaterial_instance::get_parameter_count ( ) const

pure virtual

Return the number of parameters of this instance.

Note: : Returns always 0 in instance compilation mode.

^◆ get_parameter_default()

virtual IValue const * mi::mdl::IMaterial_instance::get_parameter_default ( size_t index ) const

pure virtual

Return the default value of a parameter of this instance.

Parameters

index the index of the parameter

^◆ get_parameter_name()

virtual char const * mi::mdl::IMaterial_instance::get_parameter_name ( size_t index ) const

pure virtual

Return the canonical parameter name of the given parameter.

Parameters

index the index of the parameter

^◆ get_properties()

virtual Properties mi::mdl::IMaterial_instance::get_properties ( ) const

pure virtual

Get the instance properties.

^◆ get_referenced_scene_data_count()

virtual size_t mi::mdl::IMaterial_instance::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 char const * mi::mdl::IMaterial_instance::get_referenced_scene_data_name ( size_t 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_resource_tag_map_entries_count()

virtual size_t mi::mdl::IMaterial_instance::get_resource_tag_map_entries_count ( ) const

pure virtual

Get the number of resource tag map entries.

^◆ get_resource_tag_map_entry()

virtual Resource_tag_tuple const * mi::mdl::IMaterial_instance::get_resource_tag_map_entry ( size_t index ) const

pure virtual

Get the i'th resource tag map entry or NULL if the index is out of bounds;.

Parameters

index the index of the resource map entry.

^◆ get_resource_tagger()

virtual IResource_tagger * mi::mdl::IMaterial_instance::get_resource_tagger ( ) const

pure virtual

Get the resource tagger for this material instance.

^◆ get_slot_hash()

virtual DAG_hash const * mi::mdl::IMaterial_instance::get_slot_hash ( Slot slot ) const

pure virtual

Return the hash value of one material slot of this material instance.

This is equivalent to a call to get_sub_expression_path() with the path that corresponds to slot.

Parameters

slot	the material slot

This returns the hash value of a sub expression of the material instance.

^◆ get_sub_expression_hash()

virtual DAG_hash mi::mdl::IMaterial_instance::get_sub_expression_hash ( char const * path ) const

pure virtual

Calculate the hash for the node determined by the path, starting from the root expression of the material instance.

When the path is empty, the result is equivalent to get_hash(). When the path corresponds to one of the predefined slots (see Slot), the result is equivalent to get_slot_hash().

Parameters

path	Path of the sub expression to calculate the hash for.

Returns: the hash of the subexpression, or the null hash if the path is invalid.

^◆ get_surface_opacity()

virtual Opacity mi::mdl::IMaterial_instance::get_surface_opacity ( ) const

pure virtual

Returns the surface opacity of this instance.

^◆ get_temporary_count()

virtual size_t mi::mdl::IMaterial_instance::get_temporary_count ( ) const

pure virtual

Return the number of temporaries of this instance.

^◆ get_temporary_value()

virtual DAG_node const * mi::mdl::IMaterial_instance::get_temporary_value ( size_t index ) const

pure virtual

Return the value of the temporary at index.

Parameters

index the index of the temporary

^◆ get_type_factory()

virtual IType_factory * mi::mdl::IMaterial_instance::get_type_factory ( )

pure virtual

Get the type factory of this instance.

Use this factory to create or import types owned by this instance.

^◆ get_value_factory()

virtual IValue_factory * mi::mdl::IMaterial_instance::get_value_factory ( )

pure virtual

Get the value factory of this instance.

Use this factory to create or import values owned by this instance.

^◆ initialize()

virtual Error_code mi::mdl::IMaterial_instance::initialize	(	ICall_name_resolver *	resolver,
		IResource_modifier *	resource_modifier,
		IGenerated_code_dag const *	code_dag,
		size_t	argc,
		DAG_node const *	argv[],
		bool	use_temporaries,
		unsigned	flags,
		ICall_evaluator *	evaluator,
		bool	fold_meters_per_scene_unit,
		float	mdl_meters_per_scene_unit,
		float	wavelength_min,
		float	wavelength_max,
		char const *const	fold_params[],
		size_t	num_fold_params,
		IType const *	target_type
	)

pure virtual

Initialize this material instance.

Parameters

resolver	The call name resolver.
resource_modifier	The resource modifier or NULL.
code_dag	The generated code DAG.
argc	The number of arguments.
argv	An array of pointers to argument DAG nodes. The nodes will be imported into the material instance.
use_temporaries	If true, hide multiple used subexpressions behind temporaries, if false, generate a true DAG.
flags	Instantiation flags.
evaluator	If non-NULL, use this evaluator additionally to fold intrinsic functions first.
fold_meters_per_scene_unit	If true, occurrences of the functions state::meters_per_scene_unit() and state::scene_units_per_meter() will be folded using the `mdl_meters_per_scene_unit` parameter.
mdl_meters_per_scene_unit	The value for the meter/scene unit conversion only used when folding is enabled.
wavelength_min	The value for the state::wavelength_min() function.
wavelength_max	The value for the state::wavelength_max() function.
fold_params	Names of parameters to be folded in class-compilation mode (in addition to flags).
num_fold_params	The number of parameter names to be folded.
target_type	Requested type of the material return type, or `NULL` for the return type of the material call itself.

Returns: The error code of the initialization.

Arguments are always given by position. If a NULL argument is given an EC_INSTANTIATION_ERROR is returned in error_code.

^◆ lookup_sub_expression()

virtual void mi::mdl::IMaterial_instance::lookup_sub_expression	(	char const *	path,
		DAG_node const *&	node_result,
		IValue const *&	value_result
	)		const

pure virtual

Return the node determined by the path, starting from the root expression of the material instance.

If the path is invalid, both result parameters will contain NULL on return. Note that constants can be return as constant nodes, or as values, depending on how they are nested within other nodes or values.

Parameters

path	Path of the sub expression to return.
node_result	If the path names a node that is not nested within a constant, its value is stored here on return. Otherwise, NULL is stored.
value_result	If the node named at the path is a nested constant, its value is stored here on return. Otherwise, NULL is stored.

^◆ set_resource_tag()

virtual void mi::mdl::IMaterial_instance::set_resource_tag	(	IValue_resource const *	res,
		int	tag
	)

pure virtual

Set a tag, version pair for a resource constant that might be reachable from this instance.

Parameters

res	a resource
tag	the tag value

Public Types

Public Member Functions

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ Flags

◆ Opacity

◆ Property

◆ Slot

Member Function Documentation

◆ access_messages()

◆ create_call()

◆ create_constant()

◆ create_parameter()

◆ depends_on_global_distribution()

◆ depends_on_object_id()

◆ depends_on_transform()

◆ depends_on_uniform_scene_data()

◆ get_constructor()

◆ get_cutout_opacity()

◆ get_hash()

◆ get_internal_space()

◆ get_memory_size()

◆ get_opacity()

◆ get_parameter_count()

◆ get_parameter_default()

◆ get_parameter_name()

◆ get_properties()

◆ get_referenced_scene_data_count()

◆ get_referenced_scene_data_name()

◆ get_resource_tag_map_entries_count()

◆ get_resource_tag_map_entry()

◆ get_resource_tagger()

◆ get_slot_hash()

◆ get_sub_expression_hash()

◆ get_surface_opacity()

◆ get_temporary_count()

◆ get_temporary_value()

◆ get_type_factory()

◆ get_value_factory()

◆ initialize()

◆ lookup_sub_expression()

◆ set_resource_tag()

^◆ Flags

^◆ Opacity

^◆ Property

^◆ Slot

^◆ access_messages()

^◆ create_call()

^◆ create_constant()

^◆ create_parameter()

^◆ depends_on_global_distribution()

^◆ depends_on_object_id()

^◆ depends_on_transform()

^◆ depends_on_uniform_scene_data()

^◆ get_constructor()

^◆ get_cutout_opacity()

^◆ get_hash()

^◆ get_internal_space()

^◆ get_memory_size()

^◆ get_opacity()

^◆ get_parameter_count()

^◆ get_parameter_default()

^◆ get_parameter_name()

^◆ get_properties()

^◆ get_referenced_scene_data_count()

^◆ get_referenced_scene_data_name()

^◆ get_resource_tag_map_entries_count()

^◆ get_resource_tag_map_entry()

^◆ get_resource_tagger()

^◆ get_slot_hash()

^◆ get_sub_expression_hash()

^◆ get_surface_opacity()

^◆ get_temporary_count()

^◆ get_temporary_value()

^◆ get_type_factory()

^◆ get_value_factory()

^◆ initialize()

^◆ lookup_sub_expression()

^◆ set_resource_tag()