mi::neuraylib::Argument_editor Class Reference

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

#include <argument_editor.h>

Public Member Functions
General methods
	Argument_editor (ITransaction *transaction, const char *name, IMdl_factory *mdl_factory, bool intent_to_edit=false)
	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...
bool	is_valid_instance (IMdl_execution_context *context) const
	Indicates whether the material instance or function call referenced by this argument editor is valid. More...
mi::Sint32	repair (mi::Uint32 flags, IMdl_execution_context *context)
	Attempts to repair an invalid material instance or function call. 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_definition () const
	Returns the DB name of the corresponding material or function definition. More...
const char *	get_mdl_definition () const
	Returns the MDL name of the corresponding material or function definition. More...
bool	is_array_constructor () const
	Indicates whether the argument editor acts on a function call that is an instance of the array constructor. More...
bool	is_material () const
	Indicates whether the argument editor acts on a material instance. More...
const IType *	get_return_type () const
	Returns the return type. 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...
bool	is_parameter_enabled (Size index, IMdl_evaluator_api *evaluator) const
	Checks the enable_if condition of the given parameter. More...
const IExpression_list *	get_arguments () const
	Returns all arguments. More...
IExpression::Kind	get_argument_kind (Size parameter_index) const
	Returns the expression kind of an argument. More...
IExpression::Kind	get_argument_kind (const char *parameter_name) const
	Returns the expression kind of an argument. More...
Methods related to resetting of arguments
Sint32	reset_argument (Size index)
	Resets the argument at index. More...
Sint32	reset_argument (const char *name)
	Sets an argument identified by name to its default. More...
Methods related to constant expressions
template<class T>
Sint32	get_value (Size parameter_index, T &value) const
	Returns an argument (values of constants only, no calls). More...
template<class T>
Sint32	get_value (const char *parameter_name, T &value) const
	Returns an argument (values of constants only, no calls). More...
template<class T>
Sint32	set_value (Size parameter_index, const T &value)
	Sets an argument. More...
template<class T>
Sint32	set_value (const char *parameter_name, const T &value)
	Sets an argument. More...
Methods related to constant expressions (arrays)
template<class T>
Sint32	get_value (Size parameter_index, T *value, Size n) const
	Returns an array argument (values of constants only, no calls). More...
template<class T>
Sint32	get_value (const char *parameter_name, T *value, Size n) const
	Returns an array argument (values of constants only, no calls). More...
template<class T>
Sint32	set_value (Size parameter_index, const T *value, Size n)
	Sets an array argument (values of constants only, no calls). More...
template<class T>
Sint32	set_value (const char *parameter_name, const T *value, Size n)
	Sets an array argument (values of constants only, no calls). More...
Sint32	get_array_length (Uint32 parameter_index, Size &size) const
	Returns the length of an array argument. More...
Sint32	get_array_length (const char *parameter_name, Size &size) const
	Returns the length of an array argument. More...
Sint32	set_array_size (Uint32 parameter_index, Size size)
	Sets the length of a deferred-sized array argument. More...
Sint32	set_array_size (const char *parameter_name, Size size)
	Sets the length of a deferred-sized array argument. More...
Methods related to constant expressions (components of compounds)
template<class T>
Sint32	get_value (Size parameter_index, Size component_index, T &value) const
	Returns a component of a compound argument (values of constants only, no calls). More...
template<class T>
Sint32	get_value (const char *parameter_name, Size component_index, T &value) const
	Returns a component of a compound argument (values of constants only, no calls). More...
template<class T>
Sint32	get_value (Size parameter_index, const char *field_name, T &value) const
	Returns a field of a struct argument (values of constants only, no calls). More...
template<class T>
Sint32	get_value (const char *parameter_name, const char *field_name, T &value) const
	Returns a field of a struct argument (values of constants only, no calls). More...
template<class T>
Sint32	set_value (Size parameter_index, Size component_index, const T &value)
	Sets a component of a compound argument. More...
template<class T>
Sint32	set_value (const char *parameter_name, Size component_index, const T &value)
	Sets a component of a compound argument. More...
template<class T>
Sint32	set_value (Size parameter_index, const char *field_name, const T &value)
	Sets a field of a struct argument. More...
template<class T>
Sint32	set_value (const char *parameter_name, const char *field_name, const T &value)
	Sets a field of a struct argument. More...
Methods related to call expressions
const char *	get_call (Size parameter_index) const
	Returns an argument (call expressions only). More...
const char *	get_call (const char *parameter_name) const
	Returns an argument (call expressions only). More...
Sint32	set_call (Size parameter_index, const char *call_name)
	Sets an argument (call expressions only). More...
Sint32	set_call (const char *parameter_name, const char *call_name)
	Sets an argument (call expressions only). 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...
IValue_factory *	get_value_factory () const
	Get the value factory. More...
IExpression_factory *	get_expression_factory () const
	Get the expression factory. More...
const IFunction_call *	get_scene_element () const
	Get the MDL function call or material instance. More...
IFunction_call *	get_scene_element ()
	Get the MDL function call or material instance. 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 call or material instance. More...

Detailed Description

A wrapper around the interface 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. The key benefit is that it wraps API call sequences occurring in typical tasks into one single method call, e.g., changing arguments (as long as their type is not too complex): Typically this requires at least seven API calls (even more in case of arrays or if you do not use mi::neuraylib::set_value()). The argument editor offers a single method to support this task.

Many methods are overload in the first parameter to support argument indices as well as argument names. See set_value(Size,const T&) and set_value(const char*,const T&) for an overview of the various overloads of set_value(). See get_value(Size,T&)constand get_value(const char*,T&)const for an overview of the various overloads of get_value().

Note

The index-based overloads are faster than the name-based overloads and should be preferred if the index/indices are known.

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

See mi::neuraylib::IFunction_call for the underlying interface. See also mi::neuraylib::Definition_wrapper for a similar wrapper for MDL material and function definitions.

Constructor & Destructor Documentation

Argument_editor()

mi::neuraylib::Argument_editor::Argument_editor ( ITransaction *  transaction, const char *  name, IMdl_factory *  mdl_factory, bool  intent_to_edit = false  )

inline

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

Parameters

transaction	The transaction to be used.
name	The name of the wrapped material instance or function call.
mdl_factory	A pointer to the API component mi::neuraylib::IMdl_factory. Needed by all mutable methods, can be NULL if only const methods are used.
intent_to_edit	For best performance, the parameter should be set to true iff the intention is to edit the material instance or function call. This parameter is for performance optimizations only; the argument editor will work correctly independently of the value used. The performance penalty for setting it incorrectly to true is usually higher than setting it incorrectly to false. If in doubt, use the default of false.

Member Function Documentation

get_argument_kind() [1/2]

IExpression::Kind mi::neuraylib::Argument_editor::get_argument_kind ( const char *  parameter_name ) const

inline

Returns the expression kind of an argument.

This method should be used to figure out whether mi::neuraylib::Argument_editor::get_value() or mi::neuraylib::Argument_editor::get_call() should be used for reading an argument.

get_argument_kind() [2/2]

IExpression::Kind mi::neuraylib::Argument_editor::get_argument_kind ( Size  parameter_index ) const

inline

Returns the expression kind of an argument.

This method should be used to figure out whether mi::neuraylib::Argument_editor::get_value() or mi::neuraylib::Argument_editor::get_call() should be used for reading an argument.

get_arguments()

const IExpression_list * mi::neuraylib::Argument_editor::get_arguments ( ) const

inline

Returns all arguments.

get_array_length() [1/2]

Sint32 mi::neuraylib::Argument_editor::get_array_length ( const char *  parameter_name, Size &  size  ) const

inline

Returns the length of an array argument.

Parameters

	parameter_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: parameter_name is invalid.
• -4: The argument is not a constant.
• -5: The argument is not an array.

get_array_length() [2/2]

Sint32 mi::neuraylib::Argument_editor::get_array_length ( Uint32  parameter_index, Size &  size  ) const

inline

Returns the length of an array argument.

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

Parameters

	parameter_index	The index 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: parameter_index is out of range.
• -4: The argument is not a constant.
• -5: The argument is not an array.

get_call() [1/2]

const char * mi::neuraylib::Argument_editor::get_call ( const char *  parameter_name ) const

inline

Returns an argument (call expressions only).

Parameters

parameter_name

The name of the argument in question.

Returns

The name of the call, or NULL if parameter_name is invalid or the argument expression is not a call.

get_call() [2/2]

const char * mi::neuraylib::Argument_editor::get_call ( Size  parameter_index ) const

inline

Returns an argument (call expressions only).

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

Parameters

parameter_index

The index of the argument in question.

Returns

The name of the call, or NULL if parameter_index is out of bounds or the argument expression is not a call.

get_definition()

const char * mi::neuraylib::Argument_editor::get_definition ( ) const

inline

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

get_element_type()

Element_type mi::neuraylib::Argument_editor::get_element_type ( ) const

inline

Get the element type.

get_expression_factory()

IExpression_factory * mi::neuraylib::Argument_editor::get_expression_factory ( ) const

inline

Get the expression factory.

get_mdl_definition()

const char * mi::neuraylib::Argument_editor::get_mdl_definition ( ) const

inline

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

get_mdl_factory()

IMdl_factory * mi::neuraylib::Argument_editor::get_mdl_factory ( ) const

inline

Get the MDL factory.

get_name()

const std::string & mi::neuraylib::Argument_editor::get_name ( ) const

inline

Get the DB name of the MDL function call or material instance.

get_parameter_count()

Size mi::neuraylib::Argument_editor::get_parameter_count ( ) const

inline

Returns the number of parameters.

get_parameter_index()

Size mi::neuraylib::Argument_editor::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::Argument_editor::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::Argument_editor::get_parameter_types ( ) const

inline

Returns the types of all parameters.

get_return_type()

const IType * mi::neuraylib::Argument_editor::get_return_type ( ) const

inline

Returns the return type.

get_scene_element() [1/2]

IFunction_call * mi::neuraylib::Argument_editor::get_scene_element ( )

inline

Get the MDL function call or material instance.

get_scene_element() [2/2]

const IFunction_call * mi::neuraylib::Argument_editor::get_scene_element ( ) const

inline

Get the MDL function call or material instance.

get_transaction()

ITransaction * mi::neuraylib::Argument_editor::get_transaction ( ) const

inline

Get the transaction.

get_type()

Element_type mi::neuraylib::Argument_editor::get_type ( ) const

inline

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

Returns

mi::neuraylib::ELEMENT_TYPE_FUNCTION_DEFINITION, or undefined if is_valid() returns false.

get_value() [1/8]

template<class T>

Sint32 mi::neuraylib::Argument_editor::get_value	(	const char *	parameter_name,
		const char *	field_name,
		T &	value
	)		const

Returns a field of a struct argument (values of constants only, no calls).

Parameters

	parameter_name	The name of the argument in question.
	field_name	The name of the struct field in question.
[out]	value	The current value of the specified argument.

Returns

• 0: Success.
• -1: is_valid() returns false.
• -2: parameter_name is invalid.
• -3: field_name is invalid.
• -4: The argument is not a constant.
• -5: The type of the argument does not match the template parameter T.

get_value() [2/8]

template<class T>

Sint32 mi::neuraylib::Argument_editor::get_value	(	const char *	parameter_name,
		Size	component_index,
		T &	value
	)		const

Returns a component of a compound argument (values of constants only, no calls).

Parameters

	parameter_name	The name of the argument in question.
	component_index	The index of the component in question.
[out]	value	The current value of the specified argument.

Returns

• 0: Success.
• -1: is_valid() returns false.
• -2: parameter_name is invalid.
• -3: component_index is out of range.
• -4: The argument is not a constant.
• -5: The type of the argument does not match the template parameter T.

get_value() [3/8]

template<class T>

Sint32 mi::neuraylib::Argument_editor::get_value	(	const char *	parameter_name,
		T &	value
	)		const

Returns an argument (values of constants only, no calls).

This method supports all atomic MDL types with the corresponding C-type as type of value (and int for mi::neuraylib::IValue_enum). Vectors and matrices are supported if value is of type mi::math::Vector and mi::math::Matrix, respectively. For arrays, see get_value(const char*,T*,Size)const. For components of compounds, see get_value(const char*,Size,T&)constand get_value(const char*,const char*,T&)const.

It is not possible to read entire structs with a single call (in general there is no corresponding C++ class, and absence of introspection machinery). Struct fields need to be read one by one.

There is no support for inner-most components of multi-dimensional compounds (arrays of compounds or structs of compounds) -- this would require additional overloads accepting two or more component indices and/or field names.

Parameters

	parameter_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: parameter_name is invalid.
• -4: The argument is not a constant.
• -5: The type of the argument does not match the template parameter T.

get_value() [4/8]

template<class T>

Sint32 mi::neuraylib::Argument_editor::get_value	(	const char *	parameter_name,
		T *	value,
		Size	n
	)		const

Returns an array argument (values of constants only, no calls).

Parameters

	parameter_name	The name of the argument in question.
[out]	value	The current value of the specified argument.
	n	The size of the C array (needs to match the size of the argument identified by parameter_name).

Returns

• 0: Success.
• -1: is_valid() returns false.
• -2: parameter_name is out of range.
• -4: The argument is not a constant.
• -5: The type of the argument does not match the template parameter T or the array size n.

get_value() [5/8]

template<class T>

Sint32 mi::neuraylib::Argument_editor::get_value	(	Size	parameter_index,
		const char *	field_name,
		T &	value
	)		const

Returns a field of a struct argument (values of constants only, no calls).

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

Parameters

	parameter_index	The index of the argument in question.
	field_name	The name of the struct field in question.
[out]	value	The current value of the specified argument.

Returns

• 0: Success.
• -1: is_valid() returns false.
• -2: parameter_index is out of range.
• -3: field_name is invalid.
• -4: The argument is not a constant.
• -5: The type of the argument does not match the template parameter T.

get_value() [6/8]

template<class T>

Sint32 mi::neuraylib::Argument_editor::get_value	(	Size	parameter_index,
		Size	component_index,
		T &	value
	)		const

Returns a component of a compound argument (values of constants only, no calls).

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

Parameters

	parameter_index	The index of the argument in question.
	component_index	The index of the component in question.
[out]	value	The current value of the specified argument.

Returns

• 0: Success.
• -1: is_valid() returns false.
• -2: parameter_index is out of range.
• -3: component_index is out of range.
• -4: The argument is not a constant.
• -5: The type of the argument does not match the template parameter T.

get_value() [7/8]

template<class T>

Sint32 mi::neuraylib::Argument_editor::get_value	(	Size	parameter_index,
		T &	value
	)		const

Returns an argument (values of constants only, no calls).

This method supports all atomic MDL types with the corresponding C-type as type of value (and int for mi::neuraylib::IValue_enum). Vectors and matrices are supported if value is of type mi::math::Vector and mi::math::Matrix, respectively. For arrays, see get_value(Size,T*,Size)const. For components of compounds, see get_value(Size,Size,T&)constand get_value(Size,const char*,T&)const.

It is not possible to read entire structs with a single call (in general there is no corresponding C++ class, and absence of introspection machinery). Struct fields need to be read one by one.

There is no support for inner-most components of multi-dimensional compounds (arrays of compounds or structs of compounds) -- this would require additional overloads accepting two or more component indices and/or field names.

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

Parameters

	parameter_index	The index of the argument in question.
[out]	value	The current value of the specified argument.

Returns

• 0: Success.
• -1: is_valid() returns false.
• -2: parameter_index is out of range.
• -4: The argument is not a constant.
• -5: The type of the argument does not match the template parameter T.

get_value() [8/8]

template<class T>

Sint32 mi::neuraylib::Argument_editor::get_value	(	Size	parameter_index,
		T *	value,
		Size	n
	)		const

Returns an array argument (values of constants only, no calls).

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

Parameters

	parameter_index	The index of the argument in question.
[out]	value	The current value of the specified argument.
	n	The size of the C array (needs to match the size of the argument identified by parameter_index).

Returns

• 0: Success.
• -1: is_valid() returns false.
• -2: parameter_index is out of range.
• -4: The argument is not a constant.
• -5: The type of the argument does not match the template parameter T or the array size n.

get_value_factory()

IValue_factory * mi::neuraylib::Argument_editor::get_value_factory ( ) const

inline

Get the value factory.

is_array_constructor()

bool mi::neuraylib::Argument_editor::is_array_constructor ( ) const

inline

Indicates whether the argument editor acts on a function call that is an instance of the array constructor.

See also

Arrays

is_material()

bool mi::neuraylib::Argument_editor::is_material ( ) const

inline

Indicates whether the argument editor acts on a material instance.

is_parameter_enabled()

bool mi::neuraylib::Argument_editor::is_parameter_enabled ( Size  index, IMdl_evaluator_api *  evaluator  ) const

inline

Checks the enable_if condition of the given parameter.

Parameters

index	The index of the parameter.
evaluator	A pointer to the API component mi::neuraylib::IMdl_evaluator_api.

Returns

false if the enable_if condition of this parameter evaluated to false, true otherwise

is_valid()

bool mi::neuraylib::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.

is_valid_instance()

bool mi::neuraylib::Argument_editor::is_valid_instance ( IMdl_execution_context *  context ) const

inline

Indicates whether the material instance or function call referenced by this argument editor is valid.

A material instance or function call is valid if itself and all calls attached to its arguments point to a valid definition.

Parameters

context

Execution context that can be queried for error messages after the operation has finished. Can be NULL.

Returns

True, if the instance is valid, false otherwise.

repair()

mi::Sint32 mi::neuraylib::Argument_editor::repair ( mi::Uint32  flags, IMdl_execution_context *  context  )

inline

Attempts to repair an invalid material instance or function call.

Parameters

flags	Repair options, see mi::neuraylib::Mdl_repair_options.
context	Execution context that can be queried for error messages after the operation has finished. Can be NULL.

Returns

• 0: Success.
• -1: Repair failed. Check the context for details.

reset_argument() [1/2]

Sint32 mi::neuraylib::Argument_editor::reset_argument ( const char *  name )

inline

Sets an argument identified by name to its default.

If the definition has a default for this parameter (and it does not violate a potential uniform requirement), then a clone of it is used as new argument. Otherwise, a constant expression is created, observing range annotations if present (see the overload of mi::neuraylib::IValue_factory::create() with two arguments).

Parameters

name	The name of the parameter.

Returns

• 0: Success.
• -1: Invalid parameters (NULL pointer).
• -2: Parameter name does not exist.
• -4: The function call or material instance is immutable (because it appears in a default of a function or material definition).
• -9: The function call or material instance is not valid (see is_valid()).

reset_argument() [2/2]

Sint32 mi::neuraylib::Argument_editor::reset_argument ( Size  index )

inline

Resets the argument at index.

If the definition has a default for this parameter (and it does not violate a potential uniform requirement), then a clone of it is used as new argument. Otherwise, a constant expression is created, observing range annotations if present (see the overload of mi::neuraylib::IValue_factory::create() with two arguments).

Parameters

index

The index of the argument.

Returns

• 0: Success.
• -2: Parameter index does not exist.
• -4: The function call or material instance is immutable (because it appears in a default of a function or material definition).
• -9: The function call or material instance is not valid (see is_valid()).

set_array_size() [1/2]

Sint32 mi::neuraylib::Argument_editor::set_array_size ( const char *  parameter_name, Size  size  )

inline

Sets the length of a deferred-sized array argument.

If the current argument is a call expression, it will be replaced by a constant expression.

Parameters

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

Returns

• 0: Success.
• -1: is_valid() returns false.
• -2: parameter_name is invalid.
• -4: The material instance or function call is immutable.
• -5: The argument is not a deferred-sized array.

set_array_size() [2/2]

Sint32 mi::neuraylib::Argument_editor::set_array_size ( Uint32  parameter_index, Size  size  )

inline

Sets the length of a deferred-sized array argument.

If the current argument is a call expression, it will be replaced by a constant expression.

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

Parameters

parameter_index	The index of the argument in question.
size	The new length of the array of the specified argument.

Returns

• 0: Success.
• -1: is_valid() returns false.
• -2: parameter_index is out of range.
• -4: The material instance or function call is immutable.
• -5: The argument is not a deferred-sized array.

set_call() [1/2]

Sint32 mi::neuraylib::Argument_editor::set_call ( const char *  parameter_name, const char *  call_name  )

inline

Sets an argument (call expressions only).

Parameters

parameter_name	The name of the argument in question.
call_name	The name of the call to set.

Returns

• 0: Success.
• -1: is_valid() returns false.
• -2: parameter_name is invalid.
• -3: The return type of call_name does not match the argument type.
• -4: The material instance or function call is immutable.
• -5: The parameter is uniform, but the return type of the call is varying.
• -6: call_name is invalid.

set_call() [2/2]

Sint32 mi::neuraylib::Argument_editor::set_call ( Size  parameter_index, const char *  call_name  )

inline

Sets an argument (call expressions only).

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

Parameters

parameter_index	The index of the argument in question.
call_name	The name of the call to set.

Returns

• 0: Success.
• -1: is_valid() returns false.
• -2: parameter_index is out of range.
• -3: The return type of call_name does not match the argument type.
• -4: The material instance or function call is immutable.
• -5: The parameter is uniform, but the return type of the call is varying.
• -6: call_name is invalid.

set_value() [1/8]

template<class T>

Sint32 mi::neuraylib::Argument_editor::set_value	(	const char *	parameter_name,
		const char *	field_name,
		const T &	value
	)

Sets a field of a struct argument.

If the current argument is a call expression, it will be replaced by a constant expression.

Parameters

parameter_name	The name of the argument in question.
field_name	The name of the struct_field in question.
value	The new value of the specified argument.

Returns

• 0: Success.
• -1: is_valid() returns false.
• -2: parameter_name is invalid.
• -3: field_name is invalid.
• -4: The material instance or function call is immutable.
• -5: The type of the argument does not match the template parameter T.

set_value() [2/8]

template<class T>

Sint32 mi::neuraylib::Argument_editor::set_value	(	const char *	parameter_name,
		const T &	value
	)

Sets an argument.

This method supports all atomic MDL types with the corresponding C-type as type of value (and int for mi::neuraylib::IValue_enum). Vectors and matrices are supported if value is of type mi::math::Vector and mi::math::Matrix, respectively. For arrays, see set_value(const char*,const T*,Size). For components of compounds, see set_value(const char*,Size,const T&) and set_value(const char*,const char*,const T&).

It is not possible to set entire structs with a single call (in general there is no corresponding C++ class, and absence of introspection machinery). Struct fields need to be set one by one.

There is no support for inner-most components of multi-dimensional compounds (arrays of compounds or structs of compounds) -- this would require additional overloads accepting two or more component indices and/or field names.

If the current argument is a call expression, it will be replaced by a constant expression.

Parameters

parameter_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: parameter_name is invalid.
• -4: The material instance or function call is immutable.
• -5: The type of the argument does not match the template parameter T.

set_value() [3/8]

template<class T>

Sint32 mi::neuraylib::Argument_editor::set_value	(	const char *	parameter_name,
		const T *	value,
		Size	n
	)

Sets an array argument (values of constants only, no calls).

If the argument is a deferred-sized array, then its size is adjusted according to the parameter n. If the argument is an immediate-sized array, then its size needs to match the parameter n.

Parameters

parameter_name	The name of the argument in question.
value	The new value of the specified argument.
n	The size of the C array (needs to match the size of the argument identified by parameter_index in case of immediate-sized arrays).

Returns

• 0: Success.
• -1: is_valid() returns false.
• -2: parameter_name is out of range.
• -4: The material instance or function call is immutable.
• -5: The type of the argument does not match the template parameter T or the array size n.

set_value() [4/8]

template<class T>

Sint32 mi::neuraylib::Argument_editor::set_value	(	const char *	parameter_name,
		Size	component_index,
		const T &	value
	)

Sets a component of a compound argument.

If the current argument is a call expression, it will be replaced by a constant expression.

This method does not change the size of deferred-sized arrays. You need to call explicitly mi::neuraylib::Argument_editor::set_array_size() for that.

Parameters

parameter_name	The name of the argument in question.
component_index	The index of the component in question.
value	The new value of the specified argument.

Returns

• 0: Success.
• -1: is_valid() returns false.
• -2: parameter_name is invalid.
• -3: component_index is out of range.
• -4: The material instance or function call is immutable.
• -5: The type of the argument does not match the template parameter T.

set_value() [5/8]

template<class T>

Sint32 mi::neuraylib::Argument_editor::set_value	(	Size	parameter_index,
		const char *	field_name,
		const T &	value
	)

Sets a field of a struct argument.

If the current argument is a call expression, it will be replaced by a constant expression.

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

Parameters

parameter_index	The index of the argument in question.
field_name	The name of the struct_field in question.
value	The new value of the specified argument.

Returns

• 0: Success.
• -1: is_valid() returns false.
• -2: parameter_index is out of range.
• -3: field_name is invalid.
• -4: The material instance or function call is immutable.
• -5: The type of the argument does not match the template parameter T.

set_value() [6/8]

template<class T>

Sint32 mi::neuraylib::Argument_editor::set_value	(	Size	parameter_index,
		const T &	value
	)

Sets an argument.

This method supports all atomic MDL types with the corresponding C-type as type of value (and int for mi::neuraylib::IValue_enum). Vectors and matrices are supported if value is of type mi::math::Vector and mi::math::Matrix, respectively. For arrays, see set_value(Size,const T*,Size). For components of compounds, see set_value(Size,Size,const T&) and set_value(Size,const char*,const T&).

It is not possible to set entire structs with a single call (in general there is no corresponding C++ class, and absence of introspection machinery). Struct fields need to be set one by one.

There is no support for inner-most components of multi-dimensional compounds (arrays of compounds or structs of compounds) -- this would require additional overloads accepting two or more component indices and/or field names.

If the current argument is a call expression, it will be replaced by a constant expression.

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

Parameters

parameter_index	The index of the argument in question.
value	The new value of the specified argument.

Returns

• 0: Success.
• -1: is_valid() returns false.
• -2: parameter_index is out of range.
• -4: The material instance or function call is immutable.
• -5: The type of the argument does not match the template parameter T.

set_value() [7/8]

template<class T>

Sint32 mi::neuraylib::Argument_editor::set_value	(	Size	parameter_index,
		const T *	value,
		Size	n
	)

Sets an array argument (values of constants only, no calls).

If the argument is a deferred-sized array, then its size is adjusted according to the parameter n. If the argument is an immediate-sized array, then its size needs to match the parameter n.

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

Parameters

parameter_index	The index of the argument in question.
value	The new value of the specified argument.
n	The size of the C array (needs to match the size of the argument identified by parameter_index in case of immediate-sized arrays).

Returns

• 0: Success.
• -1: is_valid() returns false.
• -2: parameter_index is out of range.
• -4: The material instance or function call is immutable.
• -5: The type of the argument does not match the template parameter T or the array size n.

set_value() [8/8]

template<class T>

Sint32 mi::neuraylib::Argument_editor::set_value	(	Size	parameter_index,
		Size	component_index,
		const T &	value
	)

Sets a component of a compound argument.

If the current argument is a call expression, it will be replaced by a constant expression.

This method does not change the size of deferred-sized arrays. You need to call explicitly mi::neuraylib::Argument_editor::set_array_size() for that.

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

Parameters

parameter_index	The index of the argument in question.
component_index	The index of the component in question.
value	The new value of the specified argument.

Returns

• 0: Success.
• -1: is_valid() returns false.
• -2: parameter_index is out of range.
• -3: component_index is out of range.
• -4: The material instance or function call is immutable.
• -5: The type of the argument does not match the template parameter T.