mi::neuraylib::IMdl_material_instance Class Reference
[Materials (MDL)]
Description
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::IMdl_material_definition::create_material_instance().
See also:
mi::neuraylib::IMdl_material_definition
Public Enumerations
- enum Compilation_options{ DEFAULT_OPTIONS = 0, CLASS_COMPILATION = 1, COMPILATION_OPTIONS_FORCE_32_BIT = 0xffffffffU}
- Various options for the creation of compiled materials. More...
Public Member Functions
- virtual const IAttribute_container* access_arguments() const =0
- Returns the arguments of all parameters. More...
- virtual IMdl_compiled_material* create_compiled_material( Uint32 flags = 0, Float32 mdl_meters_per_scene_unit = 1.0f, Sint32* errors = 0) const =0
- Creates a compiled material. More...
- virtual const IAttachable* get_argument( Uint32 index) const =0
- Returns the argument at index. More...
- template< class T>const T* get_argument( Uint32 index) const
- Returns the argument at index. More...
- virtual const IAttachable* get_argument( const char* name) const =0
- Returns the argument for a parameter. More...
- template< class T>const T* get_argument( const char* name) const
- Returns the argument for a parameter. More...
- virtual const char* get_argument_type( Uint32 index) const =0
- Returns the type of the argument at index. More...
- virtual const char* get_argument_type( const char* name) const =0
- Returns the type of an argument. More...
- virtual const char* get_material_definition() const =0
- Returns the DB name of the corresponding material definition. More...
- virtual const char* get_name() const =0
- Returns the MDL name of the corresponding material definition. More...
- virtual Uint32 get_parameter_count() const =0
- Returns the number of parameters. More...
- virtual Sint32 get_parameter_index( const char* name) const =0
- Returns the index position of a parameter. More...
- virtual const char* get_parameter_name( Uint32 index) const =0
- Returns the name of the parameter at index. More...
- virtual const char* get_parameter_type( Uint32 index) const =0
- Returns the type of the parameter at index. More...
- virtual const char* get_parameter_type( const char* name) const =0
- Returns the type of a parameter. More...
- virtual bool is_parameter_type_uniform( Uint32 index) const =0
- Indicates whether the type of a parameter is uniform. More...
- virtual bool is_parameter_type_uniform( const char* name) const =0
- Indicates whether the type of a parameter is uniform. More...
- virtual Sint32 set_argument( Uint32 index, const IAttachable* value) =0
- Sets the argument at index. More...
- virtual Sint32 set_argument( const char* name, const IAttachable* value) =0
- Sets the argument for a parameter. More...
- virtual Sint32 set_arguments( const IAttribute_container* arguments) =0
- Sets the arguments of multiple parameters. More...
Enums
- enum mi::neuraylib::IMdl_material_instance::Compilation_options
Member Functions
- virtual const IAttribute_container* mi::neuraylib::IMdl_material_instance::access_arguments() const [pure virtual]
-
Returns the arguments of all parameters.
Returns
The arguments.
- virtual IMdl_compiled_material* mi::neuraylib::IMdl_material_instance::create_compiled_material( Uint32 flags = 0, Float32 mdl_meters_per_scene_unit = 1.0f, Sint32* errors = 0) const [pure virtual]
-
Creates a compiled material.
Parameters
- flags
- A bitmask of flags of type Compilation_options.
- mdl_meters_per_scene_unit
- The conversion ratio between meters and scene units for this material.
- 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: An argument of the material instance has an incorrect type.
- -2: The thin-walled material instance has different transmission for surface and backface.
Returns
The corresponding compiled material, or NULL in case of failure.
- virtual const IAttachable* mi::neuraylib::IMdl_material_instance::get_argument( Uint32 index) const [pure virtual]
-
Returns the argument at index.
Note:The method mi::neuraylib::IFactory::clone() is useful to obtain a mutable pointer to (a clone of) the argument.
If a literal 0 is passed for index, the call is ambiguous. You need to explicitly cast the value to mi::Uint32.
Parameters
- index
- The index of the argument.
Returns
The argument, or NULL if index is out of range.
-
template< class T>
const T* mi::neuraylib::IMdl_material_instance::get_argument( Uint32 index) const [inline] -
Returns the argument at index.
Note:The method mi::neuraylib::IFactory::clone() is useful to obtain a mutable pointer to (a clone of) the argument.
If a literal 0 is passed for index, the call is ambiguous. You need to explicitly cast the value to mi::Uint32.
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 argument.
Returns
The argument, or NULL if index is out of range.
- virtual const IAttachable* mi::neuraylib::IMdl_material_instance::get_argument( const char* name) const [pure virtual]
-
Returns the argument for a parameter.
Note:The method mi::neuraylib::IFactory::clone() is useful to obtain a mutable pointer to (a clone of) the argument.
Parameters
- name
- The name of the parameter.
Returns
The argument, or NULL if name is invalid.
-
template< class T>
const T* mi::neuraylib::IMdl_material_instance::get_argument( const char* name) const [inline] -
Returns the argument for a parameter.
Note:The method mi::neuraylib::IFactory::clone() is useful to obtain a mutable pointer to (a clone of) the 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 parameter.
Parameters
- name
- The name of the parameter.
Returns
The argument, or NULL if name is invalid.
- virtual const char* mi::neuraylib::IMdl_material_instance::get_argument_type( Uint32 index) const [pure virtual]
-
Returns the type of the argument at index. The type of a given argument is an attachable of the corresponding parameter type. For example, if get_parameter_type() returns "Sint32", this method returns "Attachable<Sint32>".
If a literal 0 is passed for index, the call is ambiguous. You need to explicitly cast the value to mi::Uint32.
Parameters
- index
- The index of the argument.
Returns
The argument type, or NULL if index is out of range.
- virtual const char* mi::neuraylib::IMdl_material_instance::get_argument_type( const char* name) const [pure virtual]
-
Returns the type of an argument. The type of a given argument is an attachable of the corresponding parameter type. For example, if get_parameter_type() returns "Sint32", this method returns "Attachable<Sint32>".
Parameters
- name
- The name of the argument.
Returns
The argument type, or NULL if name is invalid.
- virtual const char* mi::neuraylib::IMdl_material_instance::get_material_definition() const [pure virtual]
-
Returns the DB name of the corresponding material definition. The type of the material definition is mi::neuraylib::IMdl_material_definition.
Returns
The DB name of the material definition.
- virtual const char* mi::neuraylib::IMdl_material_instance::get_name() 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. Use mi::neuraylib::IMdl_compiler::name_of() to obtain the name of the DB element.
Returns
The MDL name of the material definition.
- virtual Uint32 mi::neuraylib::IMdl_material_instance::get_parameter_count() const [pure virtual]
-
Returns the number of parameters.
Returns
The number of material parameters.
- virtual Sint32 mi::neuraylib::IMdl_material_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::IMdl_material_instance::get_parameter_name( Uint32 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 char* mi::neuraylib::IMdl_material_instance::get_parameter_type( Uint32 index) const [pure virtual]
-
Returns the type of the parameter at index. If a literal 0 is passed for index, the call is ambiguous. You need to explicitly cast the value to mi::Uint32.
Parameters
- index
- The index of the parameter.
Returns
The parameter type, or NULL if index is out of range.
- virtual const char* mi::neuraylib::IMdl_material_instance::get_parameter_type( const char* name) const [pure virtual]
-
Returns the type of a parameter.
Parameters
- name
- The name of the parameter.
Returns
The parameter type, or NULL if name is invalid.
- virtual bool mi::neuraylib::IMdl_material_instance::is_parameter_type_uniform( Uint32 index) const [pure virtual]
-
Indicates whether the type of a parameter is uniform.
Parameters
- index
- The index of the parameter.
Returns
true if the parameter is uniform, otherwise false (including invalid index ).
- virtual bool mi::neuraylib::IMdl_material_instance::is_parameter_type_uniform( const char* name) const [pure virtual]
-
Indicates whether the type of a parameter is uniform.
Parameters
- name
- The name of the parameter.
Returns
true if the parameter is uniform, otherwise false (including invalid name ).
- virtual Sint32 mi::neuraylib::IMdl_material_instance::set_argument( Uint32 index, const IAttachable* value) [pure virtual]
-
Sets the argument at index.
Parameters
- index
- The index of the argument.
- value
- The argument. Note that the value is copied; passing a value obtained from another MDL interface does not create a link between both instances.
Returns
- 0: Success.
- -1: Invalid parameters (NULL pointer).
- -2: Parameter index does not exist.
- -3: Type of parameter does not match.
- -4: The material instance is immutable (because it appears in a default of a material definition).
- -5: The parameter type is uniform, but the attachment has a varying return type.
- virtual Sint32 mi::neuraylib::IMdl_material_instance::set_argument( const char* name, const IAttachable* value) [pure virtual]
-
Sets the argument for a parameter.
Parameters
- name
- The name of the parameter.
- value
- The argument. Note that the value is copied; passing a value obtained from another MDL interface does not create a link between both instances.
Returns
- 0: Success.
- -1: Invalid parameters (NULL pointer).
- -2: Parameter name does not exist.
- -3: Type of parameter does not match.
- -4: The material instance is immutable (because it appears in a default of a material definition).
- -5: The parameter type is uniform, but the attachment has a varying return type.
- virtual Sint32 mi::neuraylib::IMdl_material_instance::set_arguments( const IAttribute_container* arguments) [pure virtual]
-
Sets the arguments of multiple parameters.
Parameters
- arguments
- The arguments. Note that the values are copied; passing an attribute container obtained from another MDL interface does not create a link between both instances.
Returns
- 0: Success.
- -1: Invalid parameters (NULL pointer).
- -2: One of the parameters in arguments does not exist.
- -3: The type of one of the parameters does not match.
- -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 attachment has a varying return type.