neuray API Programmer's Manual

mi::neuraylib::Definition_wrapper Class Reference

[MDL-related elements]

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.

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...
const char* get_mdl_definition() const
Returns the MDL name of the material or function definition.
const char* get_module() const
Returns the DB name of the corresponding module.
Size get_parameter_count() const
Returns the number of parameters.
Size get_parameter_index( const char* name) const
Returns the index position of a parameter. More...
const char* get_parameter_name( Size index) const
Returns the name of the parameter at index. More...
const IType_list* get_parameter_types() const
Returns the types of all parameters.
const IType* get_return_type() const
Returns the return type.
const char* get_thumbnail() const
Returns the resolved file name of the thumbnail image for this MDL definition. More...
Element_type get_type() const
Indicates whether the definition wrapper acts on a material definition or on a function definition. More...
bool  is_exported() const
Indicates whether the material or function definition is exported by its module.
bool  is_material() const
Indicates whether the definition represents a material.
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...

Methods related to argument defaults

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...
const IExpression_list* get_defaults() const
Returns the defaults of all parameters. More...

Methods related to annotations

const IAnnotation_block* get_annotations() const
Returns the annotations for a material or function definition.
const IExpression_list* get_enable_if_conditions() const
Returns the enable_if conditions of all parameters. 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...
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...
const IAnnotation_list* get_parameter_annotations() const
Returns the annotations of all parameters. More...
const IAnnotation_block* get_return_annotations() const
Returns the annotations of the return type.

Methods related to instantiation of definitions

IFunction_call* create_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.

Element_type get_element_type() const
Get the element type.
IMdl_factory* get_mdl_factory() const
Get the MDL factory.
const std::​string& get_name() const
Get the DB name of the MDL function or material definition.
const IFunction_definition* get_scene_element() const
Get the MDL function or material definition.
ITransaction* get_transaction() const
Get the transaction.

Constructors

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

transaction
The transaction to be used.
name
The name of the wrapped material or function definition.
mdl_factory
A 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 Functions

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

arguments
If 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.
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. 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.
  • -4: The function definition is one of Template-like function definitions and arguments is NULL.

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. This template wrapper exists only for backwards compatibility with older code. In new code, use the non-template overload instead.

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 [inline]

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

index
The index the parameter in question.
value
The 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 [inline]

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

name
The name of the parameter in question.
value
The 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

index
The index of the parameter.
u_index
The 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

index
The 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

name
The 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

index
The 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.

const IType* mi::​neuraylib::​Definition_wrapper::get_return_type() const [inline]

Returns the return type.

const IFunction_definition* 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

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_material() const [inline]

Indicates whether the definition represents a material.

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

context
Execution 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.