MDL SDK API nvidia_logo_transpbg.gif Up
mi::mdl::IMaterial_instance Class Referenceabstract

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

Member Enumeration Documentation

 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

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

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

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
signatureThe signature of the called function.
semaThe semantic of the called function.
call_argsThe call arguments of the called function.
num_call_argsThe number of call arguments.
ret_typeThe 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
valueThe 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
typeThe type of the parameter
indexThe 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
indexthe 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
indexthe 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
indexthe 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
indexthe 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
slotthe 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
pathPath 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
indexthe 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
resolverThe call name resolver.
resource_modifierThe resource modifier or NULL.
code_dagThe generated code DAG.
argcThe number of arguments.
argvAn array of pointers to argument DAG nodes. The nodes will be imported into the material instance.
use_temporariesIf true, hide multiple used subexpressions behind temporaries, if false, generate a true DAG.
flagsInstantiation flags.
evaluatorIf non-NULL, use this evaluator additionally to fold intrinsic functions first.
fold_meters_per_scene_unitIf 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_unitThe value for the meter/scene unit conversion only used when folding is enabled.
wavelength_minThe value for the state::wavelength_min() function.
wavelength_maxThe value for the state::wavelength_max() function.
fold_paramsNames of parameters to be folded in class-compilation mode (in addition to flags).
num_fold_paramsThe number of parameter names to be folded.
target_typeRequested 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
pathPath of the sub expression to return.
node_resultIf the path names a node that is not nested within a constant, its value is stored here on return. Otherwise, NULL is stored.
value_resultIf 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
resa resource
tagthe tag value