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

A wrapper around the interfaces for MDL material and function definitions. More...

Public Member Functions

General methods
 Definition_wrapper (ITransaction *transaction, const char *name, IMdl_factory *mdl_factory)
 Constructs an MDL definition wrapper for a fixed material or function definition. More...
 
bool is_valid () const
 Indicates whether the definition wrapper is in a valid state. More...
 
bool is_valid_definition (IMdl_execution_context *context) const
 Indicates whether the material or function definition referenced by this definition wrapper matches a definition in its owner module. Definitions might become invalid due to a module reload of the owner module itself or another module imported by the owner module. More...
 
Element_type get_type () const
 Indicates whether the definition wrapper acts on a material definition or on a function definition. More...
 
const char * get_mdl_definition () const
 Returns the MDL name of the material or function definition. More...
 
const char * get_module () const
 Returns the DB name of the corresponding module. More...
 
bool is_exported () const
 Indicates whether the material or function definition is exported by its module. More...
 
Size get_parameter_count () const
 Returns the number of parameters. More...
 
const char * get_parameter_name (Size index) const
 Returns the name of the parameter at index. More...
 
Size get_parameter_index (const char *name) const
 Returns the index position of a parameter. More...
 
const IType_listget_parameter_types () const
 Returns the types of all parameters. More...
 
const ITypeget_return_type () const
 Returns the return type. More...
 
const char * get_thumbnail () const
 Returns the resolved file name of the thumbnail image for this MDL definition. More...
 
Methods related to argument defaults
const IExpression_listget_defaults () const
 Returns the defaults of all parameters. More...
 
template<class T >
Sint32 get_default (Size index, T &value) const
 Returns the default of a non-array parameter. More...
 
template<class T >
Sint32 get_default (const char *name, T &value) const
 Returns the default of a non-array parameter. More...
 
Methods related to annotations
const IAnnotation_blockget_annotations () const
 Returns the annotations for a material or function definition. More...
 
const IAnnotation_listget_parameter_annotations () const
 Returns the annotations of all parameters. More...
 
const IAnnotation_blockget_return_annotations () const
 Returns the annotations of the return type. More...
 
const IExpression_listget_enable_if_conditions () const
 Returns the enable_if conditions of all parameters. More...
 
Size get_enable_if_users (Size index) const
 Returns the number of other parameters whose enable_if condition might depend on the argument of the given parameter. More...
 
Size get_enable_if_user (Size index, Size u_index) const
 Returns the index of a parameter whose enable_if condition might depend on the argument of the given parameter. More...
 
Methods related to instantiation of definitions
IScene_elementcreate_instance (const IExpression_list *arguments=0, Sint32 *errors=0) const
 Creates an instance of the material or function definition. More...
 
template<class T >
T * create_instance (const IExpression_list *arguments=0, Sint32 *errors=0) const
 Creates an instance of the material or function definition. More...
 
Methods related to member access.
ITransactionget_transaction () const
 Get the transaction. More...
 
IMdl_factoryget_mdl_factory () const
 Get the MDL factory. More...
 
const IScene_elementget_scene_element () const
 Get the MDL function or material definition. More...
 
Element_type get_element_type () const
 Get the element type. More...
 
const std::stringget_name () const
 Get the DB name of the MDL function or material definition. More...
 

Detailed Description

A wrapper around the interfaces for MDL material and function definitions.

The purpose of the MDL definition wrapper is to simplify working with MDL material and function definitions. The key benefit is the unified treatment of material and function definitions which avoids duplication of code. For example, a GUI editor for the arguments can be essentially identical for materials and functions.

See mi::neuraylib::IMaterial_definition and mi::neuraylib::IFunction_definition for the underlying interfaces. See also mi::neuraylib::Argument_editor for a similar wrapper for MDL material instances and function calls.

Constructor & Destructor Documentation

mi::neuraylib::Definition_wrapper::Definition_wrapper ( ITransaction transaction,
const char *  name,
IMdl_factory mdl_factory 
)
inline

Constructs an MDL definition wrapper for a fixed material or function definition.

Parameters
transactionThe transaction to be used.
nameThe name of the wrapped material or function definition.
mdl_factoryA pointer to the API component mi::neuraylib::IMdl_factory. Needed only by create_instance() if called with NULL as first argument, can be NULL otherwise.

Member Function Documentation

IScene_element * mi::neuraylib::Definition_wrapper::create_instance ( const IExpression_list arguments = 0,
Sint32 errors = 0 
) const
inline

Creates an instance of the material or function definition.

Parameters
argumentsIf not NULL, then these arguments are used for the material instance or function call (all parameters without default need to be present). If NULL, then the default for a parameter is used, or the argument is default-constructed for parameters without default.
[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. If arguments is NULL, then the method always succeeds.
  • -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.
Returns
The constructed material instance or function call, or NULL in case of errors.
template<class T >
T* mi::neuraylib::Definition_wrapper::create_instance ( const IExpression_list arguments = 0,
Sint32 errors = 0 
) const
inline

Creates an instance of the material or function definition.

Parameters
argumentsIf not NULL, then these arguments are used for the material instance or function call (all parameters without default need to be present). If NULL, then the default for a parameter is used, or the argument is default-constructed for parameters without default.
[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. If arguments is NULL, then the method always succeeds.
  • -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.
Returns
The constructed material instance or function call, or NULL in case of errors.
Template Parameters
TEither mi::neuraylib::IMaterial_instance or mi::neuraylib::IFunction_call.
const IAnnotation_block * mi::neuraylib::Definition_wrapper::get_annotations ( ) const
inline

Returns the annotations for a material or function definition.

template<class T >
Sint32 mi::neuraylib::Definition_wrapper::get_default ( Size  index,
T &  value 
) const

Returns the default of a non-array parameter.

If a literal 0 is passed for index, the call is ambiguous. You need to explicitly cast the value to mi::Size.

Note
This method handles only constant defaults. Calls or parameter indices result in error code -4.
Parameters
indexThe index the parameter in question.
[out]valueThe default of the specified parameter.
Returns
  • 0: Success.
  • -1: is_valid() returns false.
  • -2: index is out of range, or there is no default for this parameter.
  • -4: The default is not a constant.
  • -5: The type of the default does not match T.
template<class T >
Sint32 mi::neuraylib::Definition_wrapper::get_default ( const char *  name,
T &  value 
) const

Returns the default of a non-array parameter.

Note
This method handles only constant defaults. Calls or parameter indices result in error code -4.
Parameters
nameThe name of the parameter in question.
[out]valueThe default of the specified parameter.
Returns
  • 0: Success.
  • -1: is_valid() returns false.
  • -2: name is invalid, or there is no default for this parameter.
  • -4: The default is not a constant.
  • -5: The type of the default does not match T.
const IExpression_list * mi::neuraylib::Definition_wrapper::get_defaults ( ) const
inline

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 the definition. Therefore, defaults should be retrieved via the name of the parameter instead of its index.
Element_type mi::neuraylib::Definition_wrapper::get_element_type ( ) const
inline

Get the element type.

const IExpression_list * mi::neuraylib::Definition_wrapper::get_enable_if_conditions ( ) const
inline

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.
Size mi::neuraylib::Definition_wrapper::get_enable_if_user ( Size  index,
Size  u_index 
) const
inline

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.
Size mi::neuraylib::Definition_wrapper::get_enable_if_users ( Size  index) const
inline

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.
const char * mi::neuraylib::Definition_wrapper::get_mdl_definition ( ) const
inline

Returns the MDL name of the material or function definition.

IMdl_factory * mi::neuraylib::Definition_wrapper::get_mdl_factory ( ) const
inline

Get the MDL factory.

const char * mi::neuraylib::Definition_wrapper::get_module ( ) const
inline

Returns the DB name of the corresponding module.

const std::string & mi::neuraylib::Definition_wrapper::get_name ( ) const
inline

Get the DB name of the MDL function or material definition.

const IAnnotation_list * mi::neuraylib::Definition_wrapper::get_parameter_annotations ( ) const
inline

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 the definition. Therefore, annotation blocks should be retrieved via the name of the parameter instead of its index.
Size mi::neuraylib::Definition_wrapper::get_parameter_count ( ) const
inline

Returns the number of parameters.

Size mi::neuraylib::Definition_wrapper::get_parameter_index ( const char *  name) const
inline

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.
const char * mi::neuraylib::Definition_wrapper::get_parameter_name ( Size  index) const
inline

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.
const IType_list * mi::neuraylib::Definition_wrapper::get_parameter_types ( ) const
inline

Returns the types of all parameters.

const IAnnotation_block * mi::neuraylib::Definition_wrapper::get_return_annotations ( ) const
inline

Returns the annotations of the return type.

Returns
The annotations of the returns type in case of a function definition, otherwise NULL.
const IType * mi::neuraylib::Definition_wrapper::get_return_type ( ) const
inline

Returns the return type.

Returns
The return type in case of function definitions, otherwise NULL.
const IScene_element * mi::neuraylib::Definition_wrapper::get_scene_element ( ) const
inline

Get the MDL function or material definition.

const char * mi::neuraylib::Definition_wrapper::get_thumbnail ( ) const
inline

Returns the resolved file name of the thumbnail image for this MDL 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.

ITransaction * mi::neuraylib::Definition_wrapper::get_transaction ( ) const
inline

Get the transaction.

Element_type mi::neuraylib::Definition_wrapper::get_type ( ) const
inline

Indicates whether the definition wrapper acts on a material definition or on a function definition.

Returns
Either mi::neuraylib::ELEMENT_TYPE_MATERIAL_DEFINITION, or mi::neuraylib::ELEMENT_TYPE_FUNCTION_DEFINITION, or undefined if is_valid() returns false.
bool mi::neuraylib::Definition_wrapper::is_exported ( ) const
inline

Indicates whether the material or function definition is exported by its module.

bool mi::neuraylib::Definition_wrapper::is_valid ( ) const
inline

Indicates whether the definition wrapper is in a valid state.

The definition wrapper is valid if and only if the name passed in the constructor identifies a material or function definition. This method should be immediately called after invoking the constructor. If it returns false, no other methods of this class should be called.

bool mi::neuraylib::Definition_wrapper::is_valid_definition ( IMdl_execution_context context) const
inline

Indicates whether the material or function definition referenced by this definition wrapper matches a definition in its owner module. Definitions might become invalid due to a module reload of the owner module itself or another module imported by the owner module.

Parameters
contextExecution context that can be queried for error messages after the operation has finished. Can be NULL.
Returns
True, if the definition is valid, false otherwise.