MDL SDK API nvidia_logo_transpbg.gif Up
mi::neuraylib::Definition_wrapper Class Reference

A wrapper around the interface for MDL function definitions. More...

#include <definition_wrapper.h>

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. 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...
 
bool is_declarative () const
 Indicates whether the material or function definition is declarative. More...
 
bool is_material () const
 Indicates whether the definition represents a material. 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
IFunction_callcreate_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 IFunction_definitionget_scene_element () const
 Get the MDL function or material definition. More...
 
Element_type get_element_type () const
 Get the element type. More...
 
const std::string & get_name () const
 Get the DB name of the MDL function or material definition. More...
 

Detailed Description

A wrapper around the interface for MDL function definitions.

The purpose of the MDL definition wrapper is to simplify common working with MDL function definitions. The key benefit is that it wraps API call sequences occurring in typical tasks into one single method call, e.g., instance creation or obtaining the default values (as long as their type is not too complex).

Note
The definition wrapper does not expose the full functionality of the underlying interface, but provides access to it via get_scene_element().

See mi::neuraylib::IFunction_definition for the underlying interface. See also mi::neuraylib::Argument_editor for a similar wrapper for MDL function calls.

Constructor & Destructor Documentation

 Definition_wrapper()

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

 create_instance() [1/2]

IFunction_call * 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. If an argument is missing, then the default for that parameter is used. If there is no default, range annotations are used to obtain a suitable value, or the argument is default-constructed as last resort. Must not be NULL (or missing any arguments) in case of Template-like function definitions.
[out]errorsAn optional pointer to an mi::Sint32 to which an error code will be written. The error codes have the following meaning: See mi::neuraylib::IFunction_definition::create_function_call() for other possible error codes.
Returns
The constructed material instance or function call, or NULL in case of errors.

 create_instance() [2/2]

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.

This template wrapper exists only for backwards compatibility with older code. In new code, use the non-template overload instead.

 get_annotations()

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

Returns the annotations for a material or function definition.

 get_default() [1/2]

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.

 get_default() [2/2]

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.

 get_defaults()

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.

 get_element_type()

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

Get the element type.

 get_enable_if_conditions()

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.

 get_enable_if_user()

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.

 get_enable_if_users()

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.

 get_mdl_definition()

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

Returns the MDL name of the material or function definition.

 get_mdl_factory()

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

Get the MDL factory.

 get_module()

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

Returns the DB name of the corresponding module.

 get_name()

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

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

 get_parameter_annotations()

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.

 get_parameter_count()

Size mi::neuraylib::Definition_wrapper::get_parameter_count ( ) const
inline

Returns the number of parameters.

 get_parameter_index()

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.

 get_parameter_name()

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.

 get_parameter_types()

const IType_list * mi::neuraylib::Definition_wrapper::get_parameter_types ( ) const
inline

Returns the types of all parameters.

 get_return_annotations()

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

Returns the annotations of the return type.

 get_return_type()

const IType * mi::neuraylib::Definition_wrapper::get_return_type ( ) const
inline

Returns the return type.

 get_scene_element()

const IFunction_definition * mi::neuraylib::Definition_wrapper::get_scene_element ( ) const
inline

Get the MDL function or material definition.

 get_thumbnail()

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.

 get_transaction()

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

Get the transaction.

 get_type()

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
mi::neuraylib::ELEMENT_TYPE_FUNCTION_DEFINITION, or undefined if is_valid() returns false.

 is_declarative()

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

Indicates whether the material or function definition is declarative.

 is_exported()

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

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

 is_material()

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

Indicates whether the definition represents a material.

 is_valid()

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.

 is_valid_definition()

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.