Material Definition Language API nvidia_logo_transpbg.gif Up
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
mi::neuraylib::Argument_editor Class Reference

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

Public Member Functions

General methods
 Argument_editor (ITransaction *transaction, const char *name, IMdl_factory *mdl_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_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...
 
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 constant expressions for arguments
template<class T >
Sint32 get_value (Size parameter_index, T &value) const
 Returns a non-compound argument (values of constants only, no calls). More...
 
template<class T >
Sint32 get_value (const char *parameter_name, T &value) const
 Returns a non-compound argument (values of constants only, no calls). More...
 
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, const T &value)
 Sets a non-compound argument. More...
 
template<class T >
Sint32 set_value (const char *parameter_name, const T &value)
 Sets a non-compound argument. 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...
 
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 dynamic array argument. More...
 
Sint32 set_array_size (const char *parameter_name, Size size)
 Sets the length of a dynamic array argument. More...
 
Methods related to call expressions for arguments
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 the call of an argument. 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 IScene_elementget_scene_element () const
 Get the MDL function call or material instance. More...
 
IScene_elementget_scene_element ()
 Get the MDL function call or material instance. More...
 
Element_type get_element_type () const
 Get the element type. More...
 
const std::stringget_name () const
 Get the DB name of the MDL function call or material instance. 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 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.

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

Constructor & Destructor Documentation

mi::neuraylib::Argument_editor::Argument_editor ( ITransaction transaction,
const char *  name,
IMdl_factory mdl_factory 
)
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.

Member Function Documentation

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.

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.

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

Returns all arguments.

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.
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.
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.
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.
const char * mi::neuraylib::Argument_editor::get_definition ( ) const
inline

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

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

Get the element type.

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

Get the expression factory.

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

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

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

Get the MDL factory.

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

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

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

Returns the number of parameters.

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.
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.
const IType_list * mi::neuraylib::Argument_editor::get_parameter_types ( ) const
inline

Returns the types of all parameters.

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

Returns the return type.

Returns
The return type in case of function calls, otherwise NULL.
const IScene_element * mi::neuraylib::Argument_editor::get_scene_element ( ) const
inline

Get the MDL function call or material instance.

IScene_element * mi::neuraylib::Argument_editor::get_scene_element ( )
inline

Get the MDL function call or material instance.

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

Get the transaction.

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
Either mi::neuraylib::ELEMENT_TYPE_MATERIAL_INSTANCE, or mi::neuraylib::ELEMENT_TYPE_FUNCTION_CALL, or undefined if is_valid() return false.
template<class T >
Sint32 mi::neuraylib::Argument_editor::get_value ( Size  parameter_index,
T &  value 
) const

Returns a non-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.
[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 T.
template<class T >
Sint32 mi::neuraylib::Argument_editor::get_value ( const char *  parameter_name,
T &  value 
) const

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

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 T.
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 T.
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 T.
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 T.
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 T.
IValue_factory * mi::neuraylib::Argument_editor::get_value_factory ( ) const
inline

Get the value factory.

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

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

Sets the length of a dynamic 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.
  • -5: The argument is not a dynamic array.
Sint32 mi::neuraylib::Argument_editor::set_array_size ( const char *  parameter_name,
Size  size 
)
inline

Sets the length of a dynamic 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.
  • -5: The argument is not a dynamic array.
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.
Sint32 mi::neuraylib::Argument_editor::set_call ( const char *  parameter_name,
const char *  call_name 
)
inline

Sets the call of an argument.

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.
template<class T >
Sint32 mi::neuraylib::Argument_editor::set_value ( Size  parameter_index,
const T &  value 
)

Sets a non-compound 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.
valueThe new value of the specified argument.
Returns
  • 0: Success.
  • -1: is_valid() returns false.
  • -2: parameter_index is out of range.
  • -5: The type of the argument does not match T.
template<class T >
Sint32 mi::neuraylib::Argument_editor::set_value ( const char *  parameter_name,
const T &  value 
)

Sets a non-compound 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.
valueThe new value of the specified argument.
Returns
  • 0: Success.
  • -1: is_valid() returns false.
  • -2: parameter_name is invalid.
  • -5: The type of the argument does not match T.
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 dynamic 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.
  • -5: The type of the argument does not match T.
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 dynamic 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.
  • -5: The type of the argument does not match T.
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.
  • -5: The type of the argument does not match T.
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.
  • -5: The type of the argument does not match T.