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_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_list *	get_parameter_types () const
	Returns the types of all parameters. More...

const IType *	get_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_list *	get_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_block *	get_annotations () const
	Returns the annotations for a material or function definition. 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. More...

const IExpression_list *	get_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_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.
ITransaction *	get_transaction () const
	Get the transaction. More...

IMdl_factory *	get_mdl_factory () const
	Get the MDL factory. More...

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

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

	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.
[out]	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.

^◆ 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

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

^◆ 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

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

^◆ 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

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.

^◆ 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

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

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

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

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.

Public Member Functions

Methods related to member access.

Detailed Description

Constructor & Destructor Documentation

◆ Definition_wrapper()

Member Function Documentation

◆ create_instance() [1/2]

◆ create_instance() [2/2]

◆ get_annotations()

◆ get_default() [1/2]

◆ get_default() [2/2]

◆ get_defaults()

◆ get_element_type()

◆ get_enable_if_conditions()

◆ get_enable_if_user()

◆ get_enable_if_users()

◆ get_mdl_definition()

◆ get_mdl_factory()

◆ get_module()

◆ get_name()

◆ get_parameter_annotations()

◆ get_parameter_count()

◆ get_parameter_index()

◆ get_parameter_name()

◆ get_parameter_types()

◆ get_return_annotations()

◆ get_return_type()

◆ get_scene_element()

◆ get_thumbnail()

◆ get_transaction()

◆ get_type()

◆ is_exported()

◆ is_material()

◆ is_valid()

◆ is_valid_definition()

^◆ Definition_wrapper()

^◆ create_instance() [1/2]

^◆ create_instance() [2/2]

^◆ get_annotations()

^◆ get_default() [1/2]

^◆ get_default() [2/2]

^◆ get_defaults()

^◆ get_element_type()

^◆ get_enable_if_conditions()

^◆ get_enable_if_user()

^◆ get_enable_if_users()

^◆ get_mdl_definition()

^◆ get_mdl_factory()

^◆ get_module()

^◆ get_name()

^◆ get_parameter_annotations()

^◆ get_parameter_count()

^◆ get_parameter_index()

^◆ get_parameter_name()

^◆ get_parameter_types()

^◆ get_return_annotations()

^◆ get_return_type()

^◆ get_scene_element()

^◆ get_thumbnail()

^◆ get_transaction()

^◆ get_type()

^◆ is_exported()

^◆ is_material()

^◆ is_valid()

^◆ is_valid_definition()