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

Public Member Functions
General methods
	Mdl_argument_editor (neuraylib::ITransaction transaction, const char name, neuraylib::IFactory *factory)
	Constructs an MDL argument editor for a fixed material instance or function call. More...

bool	is_valid () const
	Indicates whether the argument editor is in a valid state. More...

Element_type	get_type () const
	Indicates whether the argument editor acts on a material instance or on a function call. More...

const char *	get_name () const
	Returns the MDL name of the material instance of function call. More...

const char *	get_definition () const
	Returns the DB name of the corresponding material or function definition. More...

Uint32	get_parameter_count () const
	Returns the number of parameters. More...

const char *	get_parameter_name (Uint32 index) const
	Returns the name of the parameter at `index`. More...

const char *	get_parameter_type (const char *parameter_name) const
	Returns the type of a parameter. More...

bool	is_parameter_type_uniform (const char *parameter_name) const
	Indicates whether the type of a parameter is uniform. More...

const char *	get_argument_type (const char *argument_name) const
	Returns the type of an argument. More...

const char *	get_return_type () const
	Returns the return type. More...

bool	is_return_type_varying () const
	Indicates whether the return type is varying. More...

Methods related to argument values (no attachments)
template<class T >
Sint32	get_value (const char *argument_name, T &value) const
	Returns the value of a non-array argument. More...

template<class T >
Sint32	get_value (const char *argument_name, Size array_index, T &value) const
	Returns the value of an element of an array argument. More...

template<class T >
Sint32	set_value (const char *argument_name, const T &value)
	Sets the value of a non-array argument. More...

template<class T >
Sint32	set_value (const char *argument_name, Size array_index, const T &value)
	Sets the value of an element of an array argument. More...

Methods related to attachments
bool	has_attachment (const char *argument_name) const
	Indicates whether an argument has an attachment. More...

bool	has_attachment (const char *argument_name, Size array_index) const
	Indicates whether an element of an array argument has an attachment. More...

const char *	get_attachment (const char *argument_name) const
	Returns the attachment of an argument. More...

const char *	get_attachment (const char *argument_name, Size array_index) const
	Returns the attachment of an element of an array argument. More...

Sint32	set_attachment (const char argument_name, const char attachment_name)
	Sets the attachment of an argument. More...

Sint32	set_attachment (const char argument_name, Size array_index, const char attachment_name)
	Sets the attachment of an element of an array argument. More...

Sint32	remove_attachment (const char *argument_name)
	Removes the attachment of an argument. More...

Sint32	remove_attachment (const char *argument_name, Size array_index)
	Removes the attachment of an element of an array argument. More...

Methods related to arrays
Sint32	get_array_length (const char *argument_name, Size &size) const
	Returns the length of an array argument. More...

Sint32	set_array_length (const char *argument_name, Size size)
	Sets the length of an array argument. More...

Detailed Description

A wrapper around the interfaces for MDL material instances and function calls.

The purpose of the MDL argument editor is to simplify working with MDL material instances and function calls. There are two key benefits: unified treatment of material instance and function calls, and wrapping of API call sequences occurring in typical tasks into one single method call.

Unified treatment of material instances and function calls avoids duplication of code. For example, a GUI editor for the arguments can be essentially identical for materials and functions.

Furthermore, the argument editor wraps several API calls needed in typical tasks into one single method call. For example, changing the value of an argument typically needs at least three API calls (even more in case of arrays or if you do not use mi::set_value()). The argument editor offers a single method to support this task.

See mi::IMdl_material_instance and mi::IMdl_function_call for the underlying interfaces. See also mi::Mdl_definition_wrapper for a similar wrapper for MDL material and function definitions.

Constructor & Destructor Documentation

mi::Mdl_argument_editor::Mdl_argument_editor	(	neuraylib::ITransaction *	transaction,
		const char *	name,
		neuraylib::IFactory *	factory
	)

inline

Constructs an MDL argument editor for a fixed material instance or function call.

Parameters

transaction	The transaction to use for all DB interactions.
name	The name of the wrapped material instance or function call.
factory	A pointer to the API component mi::neuraylib::IFactory. Needed by all mutable methods, can be `NULL` if only const methods are used.

Member Function Documentation

const char * mi::Mdl_argument_editor::get_argument_type ( const char * argument_name) const

inline

Returns the type of an argument.

Parameters

argument_name The name of the argument.

Returns: The argument type, or NULL if argument_name is invalid.

Sint32 mi::Mdl_argument_editor::get_array_length	(	const char *	argument_name,
		Size &	size
	)		const

inline

Returns the length of an array argument.

Parameters

	argument_name	The name of the argument in question.
[out]	size	The current length of the array of the specified argument.

Returns

0: Success.
-1: is_valid() returns false.
-2: argument_name is invalid.
-4: The argument is not an array.

const char * mi::Mdl_argument_editor::get_attachment ( const char * argument_name) const

inline

Returns the attachment of an argument.

Parameters

argument_name The name of the argument in question.

Returns: The name of the attachment, or NULL in case of failures.

const char * mi::Mdl_argument_editor::get_attachment	(	const char *	argument_name,
		Size	array_index
	)		const

inline

Returns the attachment of an element of an array argument.

Parameters

argument_name	The name of the argument in question.
array_index	The array element of the argument in question.

Returns: The name of the attachment, or NULL in case of failures.

const char * mi::Mdl_argument_editor::get_definition ( ) const

inline

Returns the DB name of the corresponding material or function definition.

const char * mi::Mdl_argument_editor::get_name ( ) const

inline

Returns the MDL name of the material instance of function call.

Uint32 mi::Mdl_argument_editor::get_parameter_count ( ) const

inline

Returns the number of parameters.

const char * mi::Mdl_argument_editor::get_parameter_name ( Uint32 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 char * mi::Mdl_argument_editor::get_parameter_type ( const char * parameter_name) const

inline

Returns the type of a parameter.

Parameters

parameter_name The name of the parameter.

Returns: The parameter type, or NULL if parameter_name is invalid.

const char * mi::Mdl_argument_editor::get_return_type ( ) const

inline

Returns the return type.

Returns: The return type in case of function calls, otherwise NULL.

Element_type mi::Mdl_argument_editor::get_type ( ) const

inline

Indicates whether the argument editor acts on a material instance or on a function call.

Returns: Either mi::ELEMENT_TYPE_MDL_MATERIAL_INSTANCE, or mi::ELEMENT_TYPE_MDL_FUNCTION_CALL, or undefined if is_valid() return false.

template<class T >

Sint32 mi::Mdl_argument_editor::get_value	(	const char *	argument_name,
		T &	value
	)		const

Returns the value of a non-array argument.

Note: This method always returns the value of the attachable, even if an attachment is present (which has precedence). See also has_attachment().

Parameters

	argument_name	The name of the argument in question.
[out]	value	The current value of the specified argument.

Returns

0: Success.
-1: is_valid() returns false.
-2: argument_name is invalid.
-3: mi::get_value() failed.

template<class T >

Sint32 mi::Mdl_argument_editor::get_value	(	const char *	argument_name,
		Size	array_index,
		T &	value
	)		const

Returns the value of an element of an array argument.

Note: This method always returns the value of the attachable, even if an attachment is present (which has precedence). See also has_attachment().

Parameters

	argument_name	The name of the argument in question.
	array_index	The array element of the argument in question.
[out]	value	The current value of the specified element of the array argument.

Returns

0: Success.
-1: is_valid() returns false.
-2: argument_name or array_index is invalid.
-3: mi::get_value() failed.

bool mi::Mdl_argument_editor::has_attachment ( const char * argument_name) const

inline

Indicates whether an argument has an attachment.

Parameters

argument_name The name of the argument in question.

Returns: true if the specified argument has an attachment, otherwise false (including argument_name is invalid).

bool mi::Mdl_argument_editor::has_attachment	(	const char *	argument_name,
		Size	array_index
	)		const

inline

Indicates whether an element of an array argument has an attachment.

Parameters

argument_name	The name of the argument in question.
array_index	The array element of the argument in question.

Returns: true if the specified element of the argument has an attachment, otherwise false (including argument_name or array_index is invalid).

bool mi::Mdl_argument_editor::is_parameter_type_uniform ( const char * parameter_name) const

inline

Indicates whether the type of a parameter is uniform.

Parameters

parameter_name The name of the parameter.

Returns: true if the parameter is uniform, otherwise false (including invalid name).

bool mi::Mdl_argument_editor::is_return_type_varying ( ) const

inline

Indicates whether the return type is varying.

Returns: true if the return type is varying, otherwise false.

bool mi::Mdl_argument_editor::is_valid ( ) const

inline

Indicates whether the argument editor is in a valid state.

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

Sint32 mi::Mdl_argument_editor::remove_attachment ( const char * argument_name)

inline

Removes the attachment of an argument.

Attempts to remove a non-existing attachment is not considered a failure (as long as argument_name is valid).

Parameters

argument_name The name of the argument in question.

Returns

0: Success.
-1: is_valid() returns false.
-2: argument_name is invalid.
-4: The material instance or function call is immutable.

Sint32 mi::Mdl_argument_editor::remove_attachment	(	const char *	argument_name,
		Size	array_index
	)

inline

Removes the attachment of an element of an array argument.

Attempts to remove a non-existing attachment is not considered a failure (as long as argument_name is valid).

Parameters

argument_name	The name of the argument in question.
array_index	The array element of the argument in question.

Returns

0: Success.
-1: is_valid() returns false.
-2: argument_name or array_index is invalid.
-4: The material instance or function call is immutable.

Sint32 mi::Mdl_argument_editor::set_array_length	(	const char *	argument_name,
		Size	size
	)

inline

Sets the length of an array argument.

Parameters

argument_name	The name of the argument in question.
size	The new length of the dynamic array of the specified argument.

Returns

0: Success.
-1: is_valid() returns false.
-2: argument_name is invalid.
-4: The argument is not a dynamic array.

Sint32 mi::Mdl_argument_editor::set_attachment	(	const char *	argument_name,
		const char *	attachment_name
	)

inline

Sets the attachment of an argument.

Parameters

argument_name	The name of the argument in question.
attachment_name	The name of the attachment to set.

Returns

0: Success.
-1: is_valid() returns false.
-2: argument_name is invalid.
-3: attachment_name is invalid.
-4: The material instance or function call is immutable.
-5: The parameter is uniform, but the return type of the attachment is varying.

Sint32 mi::Mdl_argument_editor::set_attachment	(	const char *	argument_name,
		Size	array_index,
		const char *	attachment_name
	)

inline

Sets the attachment of an element of an array argument.

Parameters

argument_name	The name of the argument in question.
array_index	The array element of the argument in question.
attachment_name	The name of the attachment to set.

Returns

0: Success.
-1: is_valid() returns false.
-2: argument_name or array_index is invalid.
-3: attachment_name is invalid.
-4: The material instance or function call is immutable.
-5: The parameter is uniform, but the return type of the attachment is varying.

template<class T >

Sint32 mi::Mdl_argument_editor::set_value	(	const char *	argument_name,
		const T &	value
	)

Sets the value of a non-array argument.

Note: This method always sets the value of the attachable, even if an attachment is present (which has precedence). See also has_attachment().

Parameters

argument_name	The name of the argument in question.
value	The new value of the specified argument.

Returns

0: Success.
-1: is_valid() returns false.
-2: argument_name is invalid.
-3: mi::set_value() failed (type mismatch).
-4: The material instance or function call is immutable.

template<class T >

Sint32 mi::Mdl_argument_editor::set_value	(	const char *	argument_name,
		Size	array_index,
		const T &	value
	)

Sets the value of an element of an array argument.

Note: This method always sets the value of the attachable, even if an attachment is present (which has precedence). See also has_attachment().

Parameters

argument_name	The name of the argument in question.
array_index	The array element of the argument in question.
value	The new value of the specified element of the array argument.

Returns

0: Success.
-1: is_valid() returns false.
-2: argument_name or array_index is invalid.
-3: mi::set_value() failed (type mismatch).
-4: The material instance or function call is immutable.

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation