neuray API Programmer's Manual

mi::IAttachable Class Reference

[Simple Types]

Description

Attachables provide an alternative between a reference and another type. Attachables are used to specify arguments of MDL material instances or function calls. There are two different kinds of such arguments: mutable, but fixed values, and (mutable) return values of other MDL material instances or function calls. The latter are represented by a reference to that material instance or function call, the former are represented by an additional attribute value.

Attachables are used to represent these two alternatives: they can hold a reference to another DB element (similar to mi::IRef), or a value of any other type. The reference has precedence of the value. If the reference is set, it represents the attachable, if not, the value represents the attachable. These references are also called attachments.

The type name of an attachable is "Attachable<", followed by the type name of the value, and finally ">", e.g., "Attachable<Color>" for an attachable that allows to set a mutable, but fixed color, or a reference to an MDL material instance of a function call that returns a color.

If the attachable is an attribute, the value can be directly accessed by adding ".value" to the name of the attachable.

See also:

mi::neuraylib::IMdl_material_instance, mi::neuraylib::IMdl_function_call, mi::IRef

mi::base::Interface_declare\< ..., IData_simple \>Mixin class template for deriving new interface declarations. This interface represents simple types.This interface represents simple types. mi::base::Interface_declare\< ..., IData \>Mixin class template for deriving new interface declarations. This interface is the base interface of all types.This interface is the base interface of all types. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. The basic extensible interface.The basic extensible interface.

Public Member Functions

virtual const base::​IInterface* get_reference() const =0
Returns the reference.
template< class T>const T* get_reference() const
Returns the reference. More...
virtual base::​IInterface* get_reference() =0
Returns the reference.
template< class T>T* get_reference()
Returns the reference. More...
virtual const char* get_reference_name() const =0
Returns the name of the referenced element.
virtual const IData* get_value() const =0
Returns the value.
template< class T>const T* get_value() const
Returns the value. More...
virtual IData* get_value() =0
Returns the value.
template< class T>T* get_value()
Returns the value. More...
virtual Sint32 set_reference( const base::​IInterface* db_element) =0
Sets the reference to db_element. More...
virtual Sint32 set_reference( const char* name) =0
Sets the reference to the database element named name. More...

Member Functions

virtual const base::​IInterface* mi::​IAttachable::get_reference() const [pure virtual]

Returns the reference.

template< class T>

const T* mi::​IAttachable::get_reference() const [inline]

Returns the reference. This templated member function is a wrapper of the non-template variant for the user's convenience. It eliminates the need to call mi::base::IInterface::get_interface( const Uuid&) on the returned pointer, since the return type already is a pointer to the type T specified as template parameter.

virtual base::​IInterface* mi::​IAttachable::get_reference() [pure virtual]

Returns the reference.

template< class T>

T* mi::​IAttachable::get_reference() [inline]

Returns the reference. This templated member function is a wrapper of the non-template variant for the user's convenience. It eliminates the need to call mi::base::IInterface::get_interface( const Uuid&) on the returned pointer, since the return type already is a pointer to the type T specified as template parameter.

virtual const char* mi::​IAttachable::get_reference_name() const [pure virtual]

Returns the name of the referenced element.

virtual const IData* mi::​IAttachable::get_value() const [pure virtual]

Returns the value.

template< class T>

const T* mi::​IAttachable::get_value() const [inline]

Returns the value. This templated member function is a wrapper of the non-template variant for the user's convenience. It eliminates the need to call mi::base::IInterface::get_interface( const Uuid &) on the returned pointer, since the return type already is a pointer to the type T specified as template parameter.

virtual IData* mi::​IAttachable::get_value() [pure virtual]

Returns the value.

template< class T>

T* mi::​IAttachable::get_value() [inline]

Returns the value. This templated member function is a wrapper of the non-template variant for the user's convenience. It eliminates the need to call mi::base::IInterface::get_interface( const Uuid &) on the returned pointer, since the return type already is a pointer to the type T specified as template parameter.

virtual Sint32 mi::​IAttachable::set_reference( const base::​IInterface* db_element) [pure virtual]

Sets the reference to db_element. Note that a NULL pointer is a valid parameter value that clears the previously set reference. Subsequent get_reference() calls will return NULL then.

If a literal 0 is passed for db_element, the call is ambiguous. You need to explicitly cast the value to const IInterface* or const char*.

Note:

This method might succeed even though the constructed attachable is considered ill-formed. This happens if an MDL function call with a varying return type is attached to a parameter that is marked as uniform. These kinds of mismatches will only be detected later and result in an invalid material instance or function call.

Returns

  • 0: Success (but see the note above about uniform and varying).
  • -2: db_element does not point to a DB element.
  • -3: db_element points to a DB element that has not yet been stored in the DB.
  • -4: The reference can not be set to the element because the element is in a more private scope than the reference.
  • -5: db_element is not of the type mi::neuraylib::IMdl_function_call or mi::neuraylib::IMdl_material_instance.
  • -6: The return type of db_element does not match the type of the attachable (if db_element is of the type mi::neuraylib::IMdl_function_call) or the type of the attachable is not "Attachable<Ref>" (if db_element is of the type mi::neuraylib::IMdl_material_instance).
virtual Sint32 mi::​IAttachable::set_reference( const char* name) [pure virtual]

Sets the reference to the database element named name. Note that a NULL pointer is a valid parameter value that clears the previously set reference. Subsequent get_reference() calls will return NULL then.

If a literal 0 is passed for name, the call is ambiguous. You need to explicitly cast the value to const IInterface* or const char*.

Note:

This method might succeed even though the constructed attachable is considered ill-formed. This happens if an MDL function call with a varying return type is attached to a parameter that is marked as uniform. These kinds of mismatches will only be detected later and result in an invalid material instance or function call.

Returns

  • 0: Success (but see the note above about uniform and varying).
  • -2: There is no element with that name.
  • -4: The reference can not be set to the element because the element is in a more private scope than the reference.
  • -5: The DB element name is not of the type mi::neuraylib::IMdl_function_call or mi::neuraylib::IMdl_material_instance.
  • -6: The return type of the DB element name does not match the type of the attachable (if the DB element is of the type mi::neuraylib::IMdl_function_call) or the type of the attachable is not "Attachable<Ref>" (if the DB element is of the type mi::neuraylib::IMdl_material_instance).