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_mdl_module_name () const =0
 Returns the MDL name of the module containing this material definition. More...
 
virtual const char * get_mdl_simple_name () const =0
 Returns the simple MDL name of the function 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 void get_mdl_version (Mdl_version &since, Mdl_version &removed) const =0
 Returns the MDL version when this material definition was added and removed. 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 const char * get_thumbnail () const =0
 Returns the resolved file name of the thumbnail image for this material definition. More...
 
virtual bool is_valid (IMdl_execution_context *context) const =0
 Returns true if the definition is valid, false otherwise. A definition can become invalid if the module it has been defined in or another module imported by that module has been reloaded. In the first case, the definition can no longer be used. In the second case, the definition can be validated by reloading the module it has been defined in. More...
 
virtual IMaterial_instancecreate_material_instance (const IExpression_list *arguments, Sint32 *errors=0) const =0
 Creates a new material instance. More...
 
virtual const
IExpression_direct_call
get_body () const =0
 Returns the direct call expression that represents the body of the material. More...
 
virtual Size get_temporary_count () const =0
 Returns the number of temporaries used by this material. More...
 
virtual const IExpressionget_temporary (Size index) const =0
 Returns the expression of a temporary. More...
 
virtual const char * get_temporary_name (Size index) const =0
 Returns the name of a temporary. More...
 
template<class T >
const T * get_temporary (Size index) const
 Returns the expression of a temporary. 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.
  • -9: The material definition is invalid due to a module reload, see is_valid() for diagnostics.
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_direct_call* mi::neuraylib::IMaterial_definition::get_body ( ) const
pure virtual

Returns the direct call expression that represents the body of the material.

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_module_name ( ) const
pure virtual

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

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_mdl_simple_name ( ) const
pure virtual

Returns the simple MDL name of the function definition.

The simple name is the last component of the MDL name, i.e., without any packages and scope qualifiers.

Returns
The simple MDL name of the function definition.
virtual void mi::neuraylib::IMaterial_definition::get_mdl_version ( Mdl_version since,
Mdl_version removed 
) const
pure virtual

Returns the MDL version when this material definition was added and removed.

Parameters
[out]sinceThe MDL version in which this material definition was added. Since there are no material definitions in the standard library, the MDL version of the corresponding module is returned.
[out]removedThe MDL version in which this material definition was removed. Since there are no material definitions in the standard library, mi::neuraylib::MDL_VERSION_INVALID is always returned.
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 IExpression* mi::neuraylib::IMaterial_definition::get_temporary ( Size  index) const
pure virtual

Returns the expression of a temporary.

Parameters
indexThe 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::IMaterial_definition::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.

Template Parameters
TThe interface type of the requested element.
Parameters
indexThe index of the temporary.
Returns
The expression of the temporary, or NULL if index is out of range.
virtual Size mi::neuraylib::IMaterial_definition::get_temporary_count ( ) const
pure virtual

Returns the number of temporaries used by this material.

virtual const char* mi::neuraylib::IMaterial_definition::get_temporary_name ( Size  index) const
pure virtual

Returns the name of a temporary.

Note
Names of temporaries are not necessarily unique, e.g., due to inlining. Names are for informational purposes and should not be used to identify a particular temporary.
See Also
mi::neuraylib::IMdl_configuration::set_expose_names_of_let_expressions()
Parameters
indexThe index of the temporary.
Returns
The name of the temporary, or NULL if the temporary has no name or index is out of range.
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.

virtual bool mi::neuraylib::IMaterial_definition::is_valid ( IMdl_execution_context context) const
pure virtual

Returns true if the definition is valid, false otherwise. A definition can become invalid if the module it has been defined in or another module imported by that module has been reloaded. In the first case, the definition can no longer be used. In the second case, the definition can be validated by reloading the module it has been defined in.

Parameters
contextExecution context that can be queried for error messages after the operation has finished. Can be NULL.
Returns
- true The definition is valid.
  • false The definition is invalid.