Material Definition Language API nvidia_logo_transpbg.gif Up
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
mi::neuraylib::IMaterial_definition Class Referenceabstract

This interface represents a material definition. More...

Inheritance diagram for mi::neuraylib::IMaterial_definition:
mi::base::Interface_declare< 0x73753e3d, 0x62e4, 0x41a7, 0xa8, 0xf5, 0x37, 0xeb, 0xda, 0xd9, 0x01, 0xd9, neuraylib::IScene_element > mi::neuraylib::IScene_element mi::base::Interface_declare< 0x8a2a4da9, 0xe323, 0x452c, 0xb8, 0xda, 0x92, 0x45, 0x67, 0x85, 0xd7, 0x78, neuraylib::IAttribute_set > mi::neuraylib::IAttribute_set mi::base::Interface_declare< 0x1bcb8d48, 0x10c1, 0x4b3e, 0x9b, 0xfa, 0x06, 0x23, 0x61, 0x81, 0xd3, 0xe1 > mi::base::IInterface

Public Member Functions

virtual const char * get_module () const =0
 Returns the DB name of the module containing this material definition. More...
 
virtual const char * get_mdl_name () const =0
 Returns the MDL name of the material definition. More...
 
virtual const char * get_prototype () const =0
 Returns the DB name of the prototype, or NULL if this material definition is not a variant. More...
 
virtual bool is_exported () const =0
 Indicates whether the material definition is exported by its module. More...
 
virtual Size get_parameter_count () const =0
 Returns the number of parameters. More...
 
virtual const char * get_parameter_name (Size index) const =0
 Returns the name of the parameter at index. More...
 
virtual Size get_parameter_index (const char *name) const =0
 Returns the index position of a parameter. More...
 
virtual const IType_listget_parameter_types () const =0
 Returns the types of all parameters. More...
 
virtual const IExpression_listget_defaults () const =0
 Returns the defaults of all parameters. More...
 
virtual const IExpression_listget_enable_if_conditions () const =0
 Returns the enable_if conditions of all parameters. More...
 
virtual Size get_enable_if_users (Size index) const =0
 Returns the number of other parameters whose enable_if condition might depend on the argument of the given parameter. More...
 
virtual Size get_enable_if_user (Size index, Size u_index) const =0
 Returns the index of a parameter whose enable_if condition might depend on the argument of the given parameter. More...
 
virtual const IAnnotation_blockget_annotations () const =0
 Returns the annotations of the material definition itself, or NULL if there are no such annotations. More...
 
virtual const IAnnotation_listget_parameter_annotations () const =0
 Returns the annotations of all parameters. More...
 
virtual IMaterial_instancecreate_material_instance (const IExpression_list *arguments, Sint32 *errors=0) const =0
 Creates a new material instance. More...
 
virtual const char * get_thumbnail () const =0
 Returns the resolved file name of the thumbnail image for this material definition. More...
 

Additional Inherited Members

- Public Types inherited from mi::base::Interface_declare< 0x73753e3d, 0x62e4, 0x41a7, 0xa8, 0xf5, 0x37, 0xeb, 0xda, 0xd9, 0x01, 0xd9, neuraylib::IScene_element >
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 Public Member Functions inherited from mi::base::Interface_declare< 0x73753e3d, 0x62e4, 0x41a7, 0xa8, 0xf5, 0x37, 0xeb, 0xda, 0xd9, 0x01, 0xd9, neuraylib::IScene_element >
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

This interface represents a material definition.

A material definition describes the formal structure of a material instance, i.e. the number, types, names, and defaults of its parameters. The create_material_instance() method allows to create material instances based on this material definition.

See Also
mi::neuraylib::IMaterial_instance, mi::neuraylib::IModule, mi::neuraylib::Definition_wrapper

Member Function Documentation

virtual IMaterial_instance* mi::neuraylib::IMaterial_definition::create_material_instance ( const IExpression_list arguments,
Sint32 errors = 0 
) const
pure virtual

Creates a new material instance.

Parameters
argumentsThe arguments of the created material instance.
Arguments for parameters without default are mandatory, otherwise optional. The type of an argument must match the corresponding parameter type. Any argument missing in arguments will be set to the default of the corresponding parameter.
Note that the expressions in arguments are copied. This copy operation is a deep copy, e.g., DB elements referenced in call expressions are also copied.
NULL is a valid argument which is handled like an empty expression list.
[out]errorsAn 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 for a non-existing parameter was provided in arguments.
  • -2: The type of an argument in arguments does not have the correct type, see get_parameter_types().
  • -3: A parameter that has no default was not provided with an argument value.
  • -4: The definition can not be instantiated because it is not exported.
  • -5: A parameter type is uniform, but the corresponding argument has a varying return type.
  • -6: An argument expression is not a constant nor a call.
  • -8: One of the parameter types is uniform, but the corresponding argument or default is a call expression and the return type of the called function definition is effectively varying since the function definition itself is varying.
Returns
The created material instance, or NULL in case of errors.
virtual const IAnnotation_block* mi::neuraylib::IMaterial_definition::get_annotations ( ) const
pure virtual

Returns the annotations of the material definition itself, or NULL if there are no such annotations.

virtual const IExpression_list* mi::neuraylib::IMaterial_definition::get_defaults ( ) const
pure virtual

Returns the defaults of all parameters.

Note
Not all parameters have defaults. Hence, the indices in the returned expression list do not necessarily coincide with the parameter indices of this definition. Therefore, defaults should be retrieved via the name of the parameter instead of its index.
virtual const IExpression_list* mi::neuraylib::IMaterial_definition::get_enable_if_conditions ( ) const
pure virtual

Returns the enable_if conditions of all parameters.

Note
Not all parameters have a condition. Hence, the indices in the returned expression list do not necessarily coincide with the parameter indices of this definition. Therefore, conditions should be retrieved via the name of the parameter instead of its index.
virtual Size mi::neuraylib::IMaterial_definition::get_enable_if_user ( Size  index,
Size  u_index 
) const
pure virtual

Returns the index of a parameter whose enable_if condition might depend on the argument of the given parameter.

Parameters
indexThe index of the parameter.
u_indexThe index of the enable_if user.
Returns
The index of a parameter whose enable_if condition depends on this parameter argument, or ~0 if indexes are out of range.
virtual Size mi::neuraylib::IMaterial_definition::get_enable_if_users ( Size  index) const
pure virtual

Returns the number of other parameters whose enable_if condition might depend on the argument of the given parameter.

Parameters
indexThe index of the parameter.
Returns
The number of other parameters whose enable_if condition depends on this parameter argument.
virtual const char* mi::neuraylib::IMaterial_definition::get_mdl_name ( ) const
pure virtual

Returns the MDL name of the material definition.

Note
The MDL name of the material definition is different from the name of the DB element. Use mi::neuraylib::ITransaction::name_of() to obtain the name of the DB element.
Returns
The MDL name of the material definition.
virtual const char* mi::neuraylib::IMaterial_definition::get_module ( ) const
pure virtual

Returns the DB name of the module containing this material definition.

The type of the module is mi::neuraylib::IModule.

virtual const IAnnotation_list* mi::neuraylib::IMaterial_definition::get_parameter_annotations ( ) const
pure virtual

Returns the annotations of all parameters.

Note
Not all parameters have annotations. Hence, the indices in the returned annotation list do not necessarily coincide with the parameter indices of this definition. Therefore, annotation blocks should be retrieved via the name of the parameter instead of its index.
virtual Size mi::neuraylib::IMaterial_definition::get_parameter_count ( ) const
pure virtual

Returns the number of parameters.

virtual Size mi::neuraylib::IMaterial_definition::get_parameter_index ( const char *  name) const
pure virtual

Returns the index position of a parameter.

Parameters
nameThe name of the parameter.
Returns
The index of the parameter, or -1 if name is invalid.
virtual const char* mi::neuraylib::IMaterial_definition::get_parameter_name ( Size  index) const
pure virtual

Returns the name of the parameter at index.

Parameters
indexThe 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_definition::get_parameter_types ( ) const
pure virtual

Returns the types of all parameters.

virtual const char* mi::neuraylib::IMaterial_definition::get_prototype ( ) const
pure virtual

Returns the DB name of the prototype, or NULL if this material definition is not a variant.

virtual const char* mi::neuraylib::IMaterial_definition::get_thumbnail ( ) const
pure virtual

Returns the resolved file name of the thumbnail image for this material definition.

The function first checks for a thumbnail annotation. If the annotation is provided, it uses the 'name' argument of the annotation and resolves that in the MDL search path. If the annotation is not provided or file resolution fails, it checks for a file module_name.material_name.png next to the MDL module. In case this cannot be found either NULL is returned.

virtual bool mi::neuraylib::IMaterial_definition::is_exported ( ) const
pure virtual

Indicates whether the material definition is exported by its module.