This interface represents a material instance.
More...
|
| enum | Compilation_options {
DEFAULT_OPTIONS = 0,
CLASS_COMPILATION = 1
} |
| | Various options for the creation of compiled materials. More...
|
| |
typedef Interface_declare< id1,
id2, id3, id4, id5, id6, id7,
id8, id9, id10, id11,
neuraylib::IScene_element > | Self |
| | Own type. More...
|
| |
typedef Uuid_t< id1, id2, id3,
id4, id5, id6, id7, id8, id9,
id10, id11 > | IID |
| | Declares the interface ID (IID) of this interface. More...
|
| |
|
| static bool | compare_iid (const Uuid &iid) |
| | Compares the interface ID iid against the interface ID of this interface and of its ancestors. More...
|
| |
This interface represents a material instance.
A material instance is a concrete instance of a formal material definition, with a fixed set of arguments (possibly the defaults of the material definition). Material instances can be created from material definitions using mi::neuraylib::IMaterial_definition::create_material_instance().
- Note
- In order to write code common for functions and materials just once, it is possible to treat material instances as if they were function calls, i.e., via mi::neuraylib::IFunction_call. See mi::neuraylib::IMdl_configuration::set_materials_are_functions() for details and consequences.
- See Also
- mi::neuraylib::IMaterial_definition, mi::neuraylib::Argument_editor
Various options for the creation of compiled materials.
- See Also
- create_compiled_material()
| Enumerator |
|---|
| DEFAULT_OPTIONS |
Default compilation options (e.g., instance compilation).
|
| CLASS_COMPILATION |
Selects class compilation instead of instance compilation.
|
Creates a compiled material.
- Parameters
-
| flags | A bitmask of flags of type Compilation_options. |
| [in,out] | context | An optional pointer to an execution context which can be used to pass compilation options to the MDL compiler. The following options are supported for this operation:
- mi::Float32 "meters_per_scene_unit": The conversion ratio between meters and scene units for this material. Default: 1.0f.
- mi::Float32 "wavelength_min": The smallest supported wavelength. Default: 380.0f.
- mi::Float32 "wavelength_max": The largest supported wavelength. Default: 780.0f.
The following options are supported in class compilation mode:
bool "fold_ternary_on_df": Fold all ternary operators of *df types. Default: false.bool "fold_all_bool_parameters": Fold all bool parameters. Default: false.bool "fold_all_enum_parameters": Fold all enum parameters. Default: false.- mi::base::IInterface *"fold_parameters": A static or dynamic array of strings of the parameters to fold. The names of the parameters are those that would otherwise be reported in mi::neuraylib::ICompiled_material::get_parameter_name(). Default:
NULL
bool "fold_trivial_cutout_opacity": Fold the expression for geometry.cutout_opacity if it evaluates to a constant with value 0.0f or 1.0f. Default: false.bool "fold_transparent_layers": Calls to the functions df::weighted_layer(), df::fresnel_layer(), df::custom_curve_layer(), df::measured_curve_layer(), and their equivalents with color weights, are replaced by their base argument, if the weight argument evaluates to a constant with value 0.0f, and the layer argument is one of df::diffuse_transmission_bsdf(), df::specular_bsdf(), df::simple_glossy_bsdf(), or df::microfacet_*_bsdf(), and the scatter_mode argument (if present) is either df::scatter_transmit or df::scatter_reflect_transmit. In addition, the layer argument might be a combination of such BSDFs using the ternary operator.
During material compilation, messages like errors and warnings will be passed to the context for later evaluation by the caller. Possible error conditions:
- Type mismatch, call of an unsuitable DB element, or call cycle in the graph of this material instance.
- The thin-walled material instance has different transmission for surface and backface.
- An argument type of the graph of this material instance is varying but the corresponding parameter type is uniform.
- An element in the array for the context option "fold_parameters" does not have the type mi::IString.
|
- Returns
- The corresponding compiled material, or
NULL in case of failure.
| virtual const IExpression_list* mi::neuraylib::IMaterial_instance::get_arguments |
( |
) | |
const |
|
pure virtual |
| virtual const char* mi::neuraylib::IMaterial_instance::get_material_definition |
( |
) | |
const |
|
pure virtual |
| virtual const char* mi::neuraylib::IMaterial_instance::get_mdl_material_definition |
( |
) | |
const |
|
pure virtual |
Returns the MDL name of the corresponding material definition.
- Note
- The MDL name of the material definition is different from the name of the DB element (see get_material_definition()).
| virtual Size mi::neuraylib::IMaterial_instance::get_parameter_count |
( |
) | |
const |
|
pure virtual |
Returns the number of parameters.
| virtual Size mi::neuraylib::IMaterial_instance::get_parameter_index |
( |
const char * |
name) | |
const |
|
pure virtual |
Returns the index position of a parameter.
- Parameters
-
| name | The name of the parameter. |
- Returns
- The index of the parameter, or -1 if
name is invalid.
| virtual const char* mi::neuraylib::IMaterial_instance::get_parameter_name |
( |
Size |
index) | |
const |
|
pure virtual |
Returns the name of the parameter at index.
- Parameters
-
| index | The index of the parameter. |
- Returns
- The name of the parameter, or
NULL if index is out of range.
| virtual const IType_list* mi::neuraylib::IMaterial_instance::get_parameter_types |
( |
) | |
const |
|
pure virtual |
Returns the types of all parameters.
| virtual const IType* mi::neuraylib::IMaterial_instance::get_return_type |
( |
) | |
const |
|
pure virtual |
Returns the return type of the corresponding material definition (the fixed material type).
| virtual bool mi::neuraylib::IMaterial_instance::is_default |
( |
) | |
const |
|
pure virtual |
Indicates, if this material instance acts as a default argument of a material or function definition.
Defaults are immutable, their arguments cannot be changed and they cannot be used in call expressions.
- Returns
- true, if this material instance is a default, false otherwise.
Returns true if this material instance and all its arguments point to valid material and function definitions, false otherwise.
Material and function definitions can become invalid due to a module reload.
- See Also
- mi::neuraylib::IModule::reload(), mi::neuraylib::IMaterial_instance::repair()
- Parameters
-
| context | Execution context that can be queried for error messages after the operation has finished. Can be NULL. |
- Returns
true: The instance is valid.false: The instance is invalid.
Attempts to repair an invalid material instance.
- Parameters
-
| flags | Repair options, see mi::neuraylib::Mdl_repair_options. |
| context | Execution context that can be queried for error messages after the operation has finished. Can be NULL. |
- Returns
- 0: Success.
- -1: Repair failed. Check the
context for details.
| virtual Sint32 mi::neuraylib::IMaterial_instance::set_argument |
( |
Size |
index, |
|
|
const IExpression * |
argument |
|
) |
| |
|
pure virtual |
Sets the argument at index.
- Parameters
-
| index | The index of the argument. |
| argument | The argument. Note that the expression is copied. This copy operation is a shallow copy, e.g., DB elements referenced in call expressions are not copied. |
- Returns
- 0: Success.
- -1: Invalid parameters (
NULL pointer).
- -2: Parameter
index does not exist.
- -3: The argument type does not match the parameter type.
- -4: The material instance is immutable (because it appears in a default of a material definition).
- -5: The parameter type is uniform, but the argument type is varying.
- -6: The argument expression is not a constant nor a call.
- -7: The argument contains references to DB elements in a scope that is more private scope than the scope of this material instance.
- -8: The parameter types is uniform, but the argument is a call expression and the return type of the called function definition is effectively varying since the function definition itself is varying.
| virtual Sint32 mi::neuraylib::IMaterial_instance::set_argument |
( |
const char * |
name, |
|
|
const IExpression * |
argument |
|
) |
| |
|
pure virtual |
Sets an argument identified by name.
- Parameters
-
| name | The name of the parameter. |
| argument | The argument. Note that the expression is copied. This copy operation is a shallow copy, e.g., DB elements referenced in call expressions are not copied. |
- Returns
- 0: Success.
- -1: Invalid parameters (
NULL pointer).
- -2: Parameter
name does not exist.
- -3: The argument type does not match the parameter type.
- -4: The material instance is immutable (because it appears in a default of a material definition).
- -5: The parameter type is uniform, but the argument type is varying.
- -6: The argument expression is not a constant nor a call.
- -7: The argument contains references to DB elements in a scope that is more private scope than the scope of this material instance.
- -8: The parameter types is uniform, but the argument is a call expression and the return type of the called function definition is effectively varying since the function definition itself is varying.
Sets multiple arguments.
- Parameters
-
| arguments | The arguments. Note that the expressions are copied. This copy operation is a shallow copy, e.g., DB elements referenced in call expressions are not copied. |
- Returns
- 0: Success.
- -1: Invalid parameters (
NULL pointer).
- -2: One of the parameters in
arguments does not exist.
- -3: One of the argument types does not match the corresponding parameter type.
- -4: The material instance is immutable (because it appears in a default of a material definition).
- -5: One of the parameter types is uniform, but the corresponding argument type is varying.
- -6: One of the arguments is not a constant nor a call.
- -7: One of the arguments contains references to DB elements in a scope that is more private scope than the scope of this material instance.
- -8: One of the parameter types is uniform, but the corresponding argument is a call expression and the return type of the called function definition is effectively varying since the function definition itself is varying.
Public Types inherited from mi::base::Interface_declare< 0x037ec156, 0x281d, 0x466a, 0xa1, 0x56, 0x3e, 0xd6, 0x83, 0xe9, 0x5a, 0x00, neuraylib::IScene_element >
