MDL SDK API nvidia_logo_transpbg.gif Up
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_declarative () const
 Indicates whether the corresponding material or function definition is declarative. More...
 
bool is_material () const
 Indicates whether the argument editor acts on a material instance. More...
 
const ITypeget_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_listget_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_listget_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.

ITransactionget_transaction () const
 Get the transaction. More...
 
IMdl_factoryget_mdl_factory () const
 Get the MDL factory. More...
 
IValue_factoryget_value_factory () const
 Get the value factory. More...
 
IExpression_factoryget_expression_factory () const
 Get the expression factory. More...
 
const IFunction_callget_scene_element () const
 Get the MDL function call or material instance. More...
 
IFunction_callget_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
transactionThe transaction to be used.
nameThe name of the wrapped material instance or function call.
mdl_factoryA 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_editFor 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_nameThe name of the argument in question.
[out]sizeThe 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_indexThe index of the argument in question.
[out]sizeThe 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_nameThe 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_indexThe 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
nameThe 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
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::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_nameThe name of the argument in question.
field_nameThe name of the struct field in question.
[out]valueThe 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_nameThe name of the argument in question.
component_indexThe index of the component in question.
[out]valueThe 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_nameThe name of the argument in question.
[out]valueThe 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_nameThe name of the argument in question.
[out]valueThe current value of the specified argument.
nThe 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_indexThe index of the argument in question.
field_nameThe name of the struct field in question.
[out]valueThe 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_indexThe index of the argument in question.
component_indexThe index of the component in question.
[out]valueThe 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_indexThe index of the argument in question.
[out]valueThe 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_indexThe index of the argument in question.
[out]valueThe current value of the specified argument.
nThe 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_declarative()

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

Indicates whether the corresponding material or function definition is declarative.

 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
indexThe index of the parameter.
evaluatorA 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
contextExecution 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
flagsRepair options, see mi::neuraylib::Mdl_repair_options.
contextExecution 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
nameThe 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
indexThe 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_nameThe name of the argument in question.
sizeThe 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_indexThe index of the argument in question.
sizeThe 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_nameThe name of the argument in question.
call_nameThe 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_indexThe index of the argument in question.
call_nameThe 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.
  • -8: The parameter is uniform, but the argument is a call expression and the return type of the called function definition is effectively varying since the function definition itself is varying.
  • -10: The definition is non-declarative, but at least one of the arguments is a declarative call.

 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_nameThe name of the argument in question.
field_nameThe name of the struct_field in question.
valueThe 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_nameThe name of the argument in question.
valueThe 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_nameThe name of the argument in question.
valueThe new value of the specified argument.
nThe 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_nameThe name of the argument in question.
component_indexThe index of the component in question.
valueThe 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_indexThe index of the argument in question.
field_nameThe name of the struct_field in question.
valueThe 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_indexThe index of the argument in question.
valueThe 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_indexThe index of the argument in question.
valueThe new value of the specified argument.
nThe 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_indexThe index of the argument in question.
component_indexThe index of the component in question.
valueThe 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.