mi::neuraylib::ICompiled_material Class Reference
[MDL-related elements]
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
Common methods related to instance and class compilation
- virtual bool depends_on_global_distribution() const =0
- Indicates whether this material depends on global distribution (edf).
- virtual bool depends_on_state_object_id() const =0
- Indicates whether this material depends on state::object_id().
- virtual bool depends_on_state_transform() const =0
- Indicates whether this material depends on coordinate space transformations like statetransform() and related functions.
- virtual bool depends_on_uniform_scene_data() const =0
- Indicates whether this material depends on uniform scene data.
- virtual const IExpression_direct_call* get_body() const =0
- Returns the direct call expression that represents the body of the compiled material.
- virtual Float32 get_mdl_meters_per_scene_unit() const =0
- Returns the conversion ration between meters and scene units for this material.
- virtual Float32 get_mdl_wavelength_max() const =0
- Returns the largest supported wavelength.
- virtual Float32 get_mdl_wavelength_min() const =0
- Returns the smallest supported wavelength.
- virtual Size get_referenced_scene_data_count() const =0
- Returns the number of scene data attributes referenced by this instance.
- 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...
- 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 Size get_temporary_count() const =0
- Returns the number of temporaries used by this compiled material.
Additional methods related to class compilation
- 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 database name of the mdl instance connected to the argument of a compiled 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 base::Uuid get_hash() const =0
- Returns a hash of the body and all temporaries. More...
- virtual Material_opacity get_opacity() const =0
- Returns the opacity of the material. More...
- virtual Size get_parameter_count() const =0
- Returns the number of parameters used by this compiled material.
- virtual const char* get_parameter_name( Size index) const =0
- Returns the name of a parameter. More...
- virtual base::Uuid get_slot_hash( Material_slot slot) const =0
- Returns the hash of a particular material slot. 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.
- virtual bool is_valid( IMdl_execution_context* context) const =0
- Returns true, if the compiled material is valid, false otherwise. More...
- virtual const IExpression* lookup_sub_expression( const char* path) const =0
- Looks up a sub-expression of the compiled material. More...
Member Functions
- 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 statetransform() and related functions.
- virtual bool mi::neuraylib::ICompiled_material::depends_on_uniform_scene_data() const [pure virtual]
-
Indicates whether this material depends on uniform scene data.
- 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.
-
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.
Parameters
- index
- The 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 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.
- 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
- 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
- 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 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.
- 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 Size mi::neuraylib::ICompiled_material::get_referenced_scene_data_count() const [pure virtual]
-
Returns the number of scene data attributes referenced by this instance.
- 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
- 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 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.
- 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.
-
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.
Parameters
- index
- The 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 bool mi::neuraylib::ICompiled_material::is_valid( IMdl_execution_context* context) const [pure virtual]
-
Returns true, if the compiled material is valid, false otherwise. 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.
- 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.