neuray API Programmer's Manual

mi::neuraylib::Mdl_argument_editor Class Reference

[Materials (MDL)]

Description

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

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

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

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

General methods

 Mdl_argument_editor( ITransaction* transaction, const char* name, IFactory* factory)
Constructs an MDL argument editor for a fixed material instance or function call. More...
const char* get_argument_type( Uint32 index) const
Returns the type of the argument at index. More...
const char* get_argument_type( const char* name) const
Returns the type of an argument. More...
const char* get_definition() const
Returns the DB name of the corresponding material or function definition.
const char* get_name() const
Returns the MDL name of the material instance of function call.
Uint32 get_parameter_count() const
Returns the number of parameters.
Sint32 get_parameter_index( const char* name) const
Returns the index position of a parameter. More...
const char* get_parameter_name( Uint32 index) const
Returns the name of the parameter at index. More...
const char* get_parameter_type( Uint32 index) const
Returns the type of the parameter at index. More...
const char* get_parameter_type( const char* name) const
Returns the type of a parameter. More...
const char* get_return_type() const
Returns the return type. More...
Element_type get_type() const
Indicates whether the argument editor acts on a material instance or on a function call. More...
bool  is_parameter_type_uniform( Uint32 index) const
Indicates whether the type of a parameter is uniform. More...
bool  is_parameter_type_uniform( const char* name) const
Indicates whether the type of a parameter is uniform. More...
bool  is_return_type_varying() const
Indicates whether the return type is varying. More...
bool  is_valid() const
Indicates whether the argument editor is in a valid state. More...

Methods related to argument values (no attachments)

template< class T>Sint32 get_value( Uint32 argument_index, T& value) const
Returns the value of a non-array argument. More...
template< class T>Sint32 get_value( const char* argument_name, T& value) const
Returns the value of a non-array argument. More...
template< class T>Sint32 get_value( Uint32 argument_index, Size array_index, T& value) const
Returns the value of an element of an array argument. More...
template< class T>Sint32 get_value( const char* argument_name, Size array_index, T& value) const
Returns the value of an element of an array argument. More...
template< class T>Sint32 set_value( Uint32 argument_index, const T& value)
Sets the value of a non-array argument. More...
template< class T>Sint32 set_value( const char* argument_name, const T& value)
Sets the value of a non-array argument. More...
template< class T>Sint32 set_value( Uint32 argument_index, Size array_index, const T& value)
Sets the value of an element of an array argument. More...
template< class T>Sint32 set_value( const char* argument_name, Size array_index, const T& value)
Sets the value of an element of an array argument. More...

Methods related to attachments

const char* get_attachment( Uint32 argument_index) const
Returns the attachment of an argument. More...
const char* get_attachment( const char* argument_name) const
Returns the attachment of an argument. More...
const char* get_attachment( Uint32 argument_index, Size array_index) const
Returns the attachment of an element of an array argument. More...
const char* get_attachment( const char* argument_name, Size array_index) const
Returns the attachment of an element of an array argument. More...
bool  has_attachment( Uint32 argument_index) const
Indicates whether an argument has an attachment. More...
bool  has_attachment( const char* argument_name) const
Indicates whether an argument has an attachment. More...
bool  has_attachment( Uint32 argument_index, Size array_index) const
Indicates whether an element of an array argument has an attachment. More...
bool  has_attachment( const char* argument_name, Size array_index) const
Indicates whether an element of an array argument has an attachment. More...
Sint32 remove_attachment( Uint32 argument_index)
Removes the attachment of an argument. More...
Sint32 remove_attachment( const char* argument_name)
Removes the attachment of an argument. More...
Sint32 remove_attachment( Uint32 argument_index, Size array_index)
Removes the attachment of an element of an array argument. More...
Sint32 remove_attachment( const char* argument_name, Size array_index)
Removes the attachment of an element of an array argument. More...
Sint32 set_attachment( Uint32 argument_index, const char* attachment_name)
Sets the attachment of an argument. More...
Sint32 set_attachment( const char* argument_name, const char* attachment_name)
Sets the attachment of an argument. More...
Sint32 set_attachment( Uint32 argument_index, Size array_index, const char* attachment_name)
Sets the attachment of an element of an array argument. More...
Sint32 set_attachment( const char* argument_name, Size array_index, const char* attachment_name)
Sets the attachment of an element of an array argument. More...

Methods related to arrays

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

Constructors

mi::​neuraylib::​Mdl_argument_editor::Mdl_argument_editor( ITransaction* transaction, const char* name, IFactory* factory) [inline]

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

Parameters

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

Member Functions

const char* mi::​neuraylib::​Mdl_argument_editor::get_argument_type( Uint32 index) const [inline]

Returns the type of the argument at index. If a literal 0 is passed for index, the call is ambiguous. You need to explicitly cast the value to mi::Uint32.

Parameters

index
The index of the argument.

Returns

The argument type, or NULL if index is out of range.

const char* mi::​neuraylib::​Mdl_argument_editor::get_argument_type( const char* name) const [inline]

Returns the type of an argument.

Parameters

name
The name of the argument.

Returns

The argument type, or NULL if argument_name is invalid.

Sint32 mi::​neuraylib::​Mdl_argument_editor::get_array_length( Uint32 argument_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

argument_index
The index of the argument in question.
size
The current length of the array of the specified argument.

Returns

  • 0: Success.
  • -1: is_valid() returns false.
  • -2: argument_index is out of range.
  • -4: The argument is not an array.
Sint32 mi::​neuraylib::​Mdl_argument_editor::get_array_length( const char* argument_name, Size& size) const [inline]

Returns the length of an array argument.

Parameters

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

Returns

  • 0: Success.
  • -1: is_valid() returns false.
  • -2: argument_name is invalid.
  • -4: The argument is not an array.
const char* mi::​neuraylib::​Mdl_argument_editor::get_attachment( Uint32 argument_index) const [inline]

Returns the attachment of an 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

argument_index
The index of the argument in question.

Returns

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

const char* mi::​neuraylib::​Mdl_argument_editor::get_attachment( const char* argument_name) const [inline]

Returns the attachment of an argument.

Parameters

argument_name
The name of the argument in question.

Returns

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

const char* mi::​neuraylib::​Mdl_argument_editor::get_attachment( Uint32 argument_index, Size array_index) const [inline]

Returns the attachment of an element 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

argument_index
The index of the argument in question.
array_index
The array element of the argument in question.

Returns

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

const char* mi::​neuraylib::​Mdl_argument_editor::get_attachment( const char* argument_name, Size array_index) const [inline]

Returns the attachment of an element of an array argument.

Parameters

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

Returns

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

const char* mi::​neuraylib::​Mdl_argument_editor::get_definition() const [inline]

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

const char* mi::​neuraylib::​Mdl_argument_editor::get_name() const [inline]

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

Uint32 mi::​neuraylib::​Mdl_argument_editor::get_parameter_count() const [inline]

Returns the number of parameters.

Sint32 mi::​neuraylib::​Mdl_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.

const char* mi::​neuraylib::​Mdl_argument_editor::get_parameter_name( Uint32 index) const [inline]

Returns the name of the parameter at index.

Parameters

index
The index of the parameter.

Returns

The name of the parameter, or NULL if index is out of range.

const char* mi::​neuraylib::​Mdl_argument_editor::get_parameter_type( Uint32 index) const [inline]

Returns the type of the parameter at index. If a literal 0 is passed for index, the call is ambiguous. You need to explicitly cast the value to mi::Uint32.

Parameters

index
The index of the parameter.

Returns

The parameter type, or NULL if index is out of range.

const char* mi::​neuraylib::​Mdl_argument_editor::get_parameter_type( const char* name) const [inline]

Returns the type of a parameter.

Parameters

name
The name of the parameter.

Returns

The parameter type, or NULL if name is invalid.

const char* mi::​neuraylib::​Mdl_argument_editor::get_return_type() const [inline]

Returns the return type.

Returns

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

Element_type mi::​neuraylib::​Mdl_argument_editor::get_type() const [inline]

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

Returns

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

template< class T>

Sint32 mi::​neuraylib::​Mdl_argument_editor::get_value( Uint32 argument_index, T& value) const [inline]

Returns the value of a non-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.

Note:

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

Parameters

argument_index
The index of the argument in question.
value
The current value of the specified argument.

Returns

  • 0: Success.
  • -1: is_valid() returns false.
  • -2: argument_index is out of range.
  • -3: mi::get_value() failed.

template< class T>

Sint32 mi::​neuraylib::​Mdl_argument_editor::get_value( const char* argument_name, T& value) const [inline]

Returns the value of a non-array argument.

Note:

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

Parameters

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

Returns

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

template< class T>

Sint32 mi::​neuraylib::​Mdl_argument_editor::get_value( Uint32 argument_index, Size array_index, T& value) const [inline]

Returns the value of an element 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.

Note:

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

Parameters

argument_index
The index of the argument in question.
array_index
The array element of the argument in question.
value
The current value of the specified element of the array argument.

Returns

  • 0: Success.
  • -1: is_valid() returns false.
  • -2: argument_index or array_index is out of range.
  • -3: mi::get_value() failed.

template< class T>

Sint32 mi::​neuraylib::​Mdl_argument_editor::get_value( const char* argument_name, Size array_index, T& value) const [inline]

Returns the value of an element of an array argument.

Note:

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

Parameters

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

Returns

  • 0: Success.
  • -1: is_valid() returns false.
  • -2: argument_name is invalid or array_index is out of range.
  • -3: mi::get_value() failed.
bool mi::​neuraylib::​Mdl_argument_editor::has_attachment( Uint32 argument_index) const [inline]

Indicates whether an argument has an attachment. If a literal 0 is passed for argument_index, the call is ambiguous. You need to explicitly cast the value to mi::Uint32.

Parameters

argument_index
The index of the argument in question.

Returns

true if the specified argument has an attachment, otherwise false (including argument_index is out of range).

bool mi::​neuraylib::​Mdl_argument_editor::has_attachment( const char* argument_name) const [inline]

Indicates whether an argument has an attachment.

Parameters

argument_name
The name of the argument in question.

Returns

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

bool mi::​neuraylib::​Mdl_argument_editor::has_attachment( Uint32 argument_index, Size array_index) const [inline]

Indicates whether an element of an array argument has an attachment. If a literal 0 is passed for argument_index, the call is ambiguous. You need to explicitly cast the value to mi::Uint32.

Parameters

argument_index
The index of the argument in question.
array_index
The array element of the argument in question.

Returns

true if the specified element of the argument has an attachment, otherwise false (including argument_index or array_index is out of range).

bool mi::​neuraylib::​Mdl_argument_editor::has_attachment( const char* argument_name, Size array_index) const [inline]

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

Parameters

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

Returns

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

bool mi::​neuraylib::​Mdl_argument_editor::is_parameter_type_uniform( Uint32 index) const [inline]

Indicates whether the type of a parameter is uniform. If a literal 0 is passed for index, the call is ambiguous. You need to explicitly cast the value to mi::Uint32.

Parameters

index
The index of the parameter.

Returns

true if the parameter is uniform, otherwise false (including invalid index ).

bool mi::​neuraylib::​Mdl_argument_editor::is_parameter_type_uniform( const char* name) const [inline]

Indicates whether the type of a parameter is uniform.

Parameters

name
The name of the parameter.

Returns

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

bool mi::​neuraylib::​Mdl_argument_editor::is_return_type_varying() const [inline]

Indicates whether the return type is varying.

Returns

true if the return type is varying, otherwise false .

bool mi::​neuraylib::​Mdl_argument_editor::is_valid() const [inline]

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

Sint32 mi::​neuraylib::​Mdl_argument_editor::remove_attachment( Uint32 argument_index) [inline]

Removes the attachment of an argument. Attempts to remove a non-existing attachment is not considered a failure (as long as argument_name is valid).

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

Parameters

argument_index
The index of the argument in question.

Returns

  • 0: Success.
  • -1: is_valid() returns false.
  • -2: argument_index is out of range.
  • -4: The material instance or function call is immutable.
Sint32 mi::​neuraylib::​Mdl_argument_editor::remove_attachment( const char* argument_name) [inline]

Removes the attachment of an argument. Attempts to remove a non-existing attachment is not considered a failure (as long as argument_name is valid).

Parameters

argument_name
The name of the argument in question.

Returns

  • 0: Success.
  • -1: is_valid() returns false.
  • -2: argument_name is invalid.
  • -4: The material instance or function call is immutable.
Sint32 mi::​neuraylib::​Mdl_argument_editor::remove_attachment( Uint32 argument_index, Size array_index) [inline]

Removes the attachment of an element of an array argument. Attempts to remove a non-existing attachment is not considered a failure (as long as argument_name is valid).

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

Parameters

argument_index
The index of the argument in question.
array_index
The array element of the argument in question.

Returns

  • 0: Success.
  • -1: is_valid() returns false.
  • -2: argument_name or argument_index is out of range.
  • -4: The material instance or function call is immutable.
Sint32 mi::​neuraylib::​Mdl_argument_editor::remove_attachment( const char* argument_name, Size array_index) [inline]

Removes the attachment of an element of an array argument. Attempts to remove a non-existing attachment is not considered a failure (as long as argument_name is valid).

Parameters

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

Returns

  • 0: Success.
  • -1: is_valid() returns false.
  • -2: argument_name is invalid or argument_index is out of range.
  • -4: The material instance or function call is immutable.
Sint32 mi::​neuraylib::​Mdl_argument_editor::set_array_length( Uint32 argument_index, Size size) [inline]

Sets 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

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

Returns

  • 0: Success.
  • -1: is_valid() returns false.
  • -2: argument_index is out of range.
  • -4: The argument is not a dynamic array.
Sint32 mi::​neuraylib::​Mdl_argument_editor::set_array_length( const char* argument_name, Size size) [inline]

Sets the length of an array argument.

Parameters

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

Returns

  • 0: Success.
  • -1: is_valid() returns false.
  • -2: argument_name is invalid.
  • -4: The argument is not a dynamic array.
Sint32 mi::​neuraylib::​Mdl_argument_editor::set_attachment( Uint32 argument_index, const char* attachment_name) [inline]

Sets the attachment of an 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

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

Returns

  • 0: Success.
  • -1: is_valid() returns false.
  • -2: argument_index is out of range.
  • -3: attachment_name is invalid.
  • -4: The material instance or function call is immutable.
  • -5: The parameter is uniform, but the return type of the attachment is varying.
Sint32 mi::​neuraylib::​Mdl_argument_editor::set_attachment( const char* argument_name, const char* attachment_name) [inline]

Sets the attachment of an argument.

Parameters

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

Returns

  • 0: Success.
  • -1: is_valid() returns false.
  • -2: argument_name is invalid.
  • -3: attachment_name is invalid.
  • -4: The material instance or function call is immutable.
  • -5: The parameter is uniform, but the return type of the attachment is varying.
Sint32 mi::​neuraylib::​Mdl_argument_editor::set_attachment( Uint32 argument_index, Size array_index, const char* attachment_name) [inline]

Sets the attachment of an element 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

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

Returns

  • 0: Success.
  • -1: is_valid() returns false.
  • -2: argument_index or array_index is out of range.
  • -3: attachment_name is invalid.
  • -4: The material instance or function call is immutable.
  • -5: The parameter is uniform, but the return type of the attachment is varying.
Sint32 mi::​neuraylib::​Mdl_argument_editor::set_attachment( const char* argument_name, Size array_index, const char* attachment_name) [inline]

Sets the attachment of an element of an array argument.

Parameters

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

Returns

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

template< class T>

Sint32 mi::​neuraylib::​Mdl_argument_editor::set_value( Uint32 argument_index, const T& value) [inline]

Sets the value of a non-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.

Note:

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

Parameters

argument_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: argument_index is out of range.
  • -3: mi::set_value() failed (type mismatch).
  • -4: The material instance or function call is immutable.

template< class T>

Sint32 mi::​neuraylib::​Mdl_argument_editor::set_value( const char* argument_name, const T& value) [inline]

Sets the value of a non-array argument.

Note:

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

Parameters

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

Returns

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

template< class T>

Sint32 mi::​neuraylib::​Mdl_argument_editor::set_value( Uint32 argument_index, Size array_index, const T& value) [inline]

Sets the value of an element 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.

Note:

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

Parameters

argument_index
The index of the argument in question.
array_index
The array element of the argument in question.
value
The new value of the specified element of the array argument.

Returns

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

template< class T>

Sint32 mi::​neuraylib::​Mdl_argument_editor::set_value( const char* argument_name, Size array_index, const T& value) [inline]

Sets the value of an element of an array argument.

Note:

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

Parameters

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

Returns

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