neuray API Programmer's Manual

mi::neuraylib::IAttribute_set Class Reference

[Scene elements]

Description

The attribute set comprises all attributes attached to a database element. Attributes are pieces of information that can be attached to any database element. Basically, an attribute set is a map from attribute names (strings) to attribute values (instances of mi::IData).

Attributes can be inherited in the scene graph. For details, see mi::neuraylib::Propagation_type.

Note:

Setting an attribute value is done by value (or deep copy) and not by reference. This is relevant for types that usually follow reference semantics, for example, arrays or structures. Note that references to other DB elements (see mi::IRef) are still stored as reference.

mi::base::Interface_declare\< ..., neuraylib::IAttribute_set \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. The basic extensible interface.The basic extensible interface. Common base interface for all scene elements.Common base interface for all scene elements. mi::base::Interface_declare\< ..., neuraylib::IScene_element \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ..., neuraylib::IScene_element \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ..., neuraylib::IScene_element \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ..., neuraylib::IScene_element \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ..., neuraylib::IScene_element \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ..., neuraylib::IScene_element \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ..., neuraylib::IScene_element \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ..., neuraylib::IScene_element \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ..., neuraylib::IScene_element \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ..., neuraylib::IScene_element \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ..., neuraylib::IScene_element \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ..., neuraylib::IScene_element \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ..., neuraylib::IScene_element \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ..., neuraylib::IScene_element \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ..., neuraylib::IScene_element \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ..., neuraylib::IScene_element \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ..., neuraylib::IScene_element \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ..., neuraylib::IScene_element \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ..., neuraylib::IScene_element \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ..., neuraylib::IScene_element \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ..., neuraylib::IScene_element \>Mixin class template for deriving new interface declarations. mi::base::Interface_declare\< ..., neuraylib::IScene_element \>Mixin class template for deriving new interface declarations. Textures add image processing options to images.Textures add image processing options to images. This interfaces represents a function definition.This interfaces represents a function definition. Interface representing an on-demand mesh.Interface representing an on-demand mesh. An instance is a scene element that adds a transformation and attributes to another...An instance is a scene element that adds a transformation and attributes to another scene element. An attribute container is a database element that stores attributes and no other...An attribute container is a database element that stores attributes and no other data. This interface represents a function call.This interface represents a function call. A group is a container for other scene elements.A group is a container for other scene elements. A scene element that stores scene-specific settings.A scene element that stores scene-specific settings. Irradiance probes are used to render the irradiance at certain locations in the scene...Irradiance probes are used to render the irradiance at certain locations in the scene. Interface representing a polygon mesh.Interface representing a polygon mesh. mi::base::Interface_declare\< ..., neuraylib::IPolygon_mesh \>Mixin class template for deriving new interface declarations. Interface representing a subdivision surface.Interface representing a subdivision surface. Interface representing a freeform surface.Interface representing a freeform surface. Decals are sticker-like objects that can be applied to other geometry objects.Decals are sticker-like objects that can be applied to other geometry objects. Interface representing a triangle mesh.Interface representing a triangle mesh. This interfaces represents a material definition.This interfaces represents a material definition. A scene element that stores measured BSDF data.A scene element that stores measured BSDF data. This interface represents light profiles.This interface represents light profiles. The camera defines the viewpoint from which the scene is rendered.The camera defines the viewpoint from which the scene is rendered. This interface represents a compiled material.This interface represents a compiled material. This interfaces represents an MDL module.This interfaces represents an MDL module. Point, spot, directional and area lighting.Point, spot, directional and area lighting. This interface represents a pixel image file.This interface represents a pixel image file. This interface represents a material instance.This interface represents a material instance.

Public Member Functions

virtual const IData* access_attribute( const char* name) const =0
Returns a const pointer to the attribute name. More...
template< class T>const T* access_attribute( const char* name) const
Returns a const pointer to the attribute name. More...
virtual IData* create_attribute( const char* name, const char* type) =0
Creates a new attribute name of the type type. More...
template< class T>T* create_attribute( const char* name, const char* type)
Creates a new attribute name of the type type. More...
template< class T>T* create_attribute( const char* name)
Creates a new attribute name of the type T. More...
virtual bool  destroy_attribute( const char* name) =0
Destroys the attribute name. More...
virtual IData* edit_attribute( const char* name) =0
Returns a mutable pointer to the attribute name. More...
template< class T>T* edit_attribute( const char* name)
Returns a mutable pointer to the attribute name. More...
virtual const char* enumerate_attributes( Sint32 index) const =0
Returns the name of the attribute indicated by index. More...
virtual Propagation_type get_attribute_propagation( const char* name) const =0
Returns the propagation type of the attribute name.
virtual const char* get_attribute_type_name( const char* name) const =0
Returns the type of an attribute. More...
virtual bool  is_attribute( const char* name) const =0
Indicates existence of an attribute. More...
virtual Sint32 set_attribute_propagation( const char* name, Propagation_type value) =0
Sets the propagation type of the attribute name. More...

Member Functions

virtual const IData* mi::​neuraylib::​IAttribute_set::access_attribute( const char* name) const [pure virtual]

Returns a const pointer to the attribute name.

Parameters

name
The name of the attribute. In addition, you can also access parts of array or structure attributes directly. For an array element add the index in square brackets to the attribute name. For a structure member add a dot and the name of the structure member to the attribute name.

Returns

A pointer to the attribute, or NULL if there is no attribute with the name name .

template< class T>

const T* mi::​neuraylib::​IAttribute_set::access_attribute( const char* name) const [inline]

Returns a const pointer to the attribute name. 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.

Parameters

name
The name of the attribute. In addition, you can also access parts of array or structure attributes directly. For an array element add the index in square brackets to the attribute name. For a structure member add a dot and the name of the structure member to the attribute name.

Returns

A pointer to the attribute, or NULL if there is no attribute with the name name or if T does not match the attribute's type.

virtual IData* mi::​neuraylib::​IAttribute_set::create_attribute( const char* name, const char* type) [pure virtual]

Creates a new attribute name of the type type.

Parameters

name
The name of the attribute. The name must not contain "[", "]", or "."
type
The type of the attribute. See Types for a list of supported attribute types.

Returns

A pointer to the created attribute, or NULL in case of failure. Reasons for failure are:

  • name or type is invalid,
  • there is already an attribute with the name name, or
  • name is the name of a reserved attribute and type does match the required type(s) of such an attribute.

template< class T>

T* mi::​neuraylib::​IAttribute_set::create_attribute( const char* name, const char* type) [inline]

Creates a new attribute name of the type type. See Types for a list of supported attribute types.

Note that there are two versions of this templated member function, one that takes only one argument (the attribute name), and another one that takes two arguments (the attribute name and the type name). The version with one argument can only be used to create a subset of supported attribute types: it supports only those types where the type name can be deduced from the template parameter, i.e., it does not support arrays and structures. The version with two arguments can be used to create attributes of any supported type (but requires the type name as parameter, which for redundant for many types). Attempts to use the version with one argument with a template parameter where the type name can not be deduced results in compiler errors.

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.

Parameters

name
The name of the attribute. The name must not contain "[", "]", or "."
type
The type of the attribute. See Types for a list of supported attribute types.

Returns

A pointer to the created attribute, or NULL in case of failure. Reasons for failure are:

  • name or type is invalid,
  • there is already an attribute with the name name,
  • name is the name of a reserved attribute and type does match the required type(s) of such an attribute, or
  • T does not match type.

template< class T>

T* mi::​neuraylib::​IAttribute_set::create_attribute( const char* name) [inline]

Creates a new attribute name of the type T. See Types for a list of supported attribute types.

Note that there are two versions of this templated member function, one that takes only one argument (the attribute name), and another one that takes two arguments (the attribute name and the type name). The version with one argument can only be used to create a subset of supported attribute types: it supports only those types where the type name can be deduced from the template parameter, i.e., it does not support arrays and structures. The version with two arguments can be used to create attributes of any supported type (but requires the type name as parameter, which is redundant for many types). Attempts to use the version with one argument with a template parameter where the type name can not be deduced results in compiler errors.

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.

Parameters

name
The name of the attribute. The name must not contain "[", "]", or "."

Returns

A pointer to the created attribute, or NULL in case of failure. Reasons for failure are:

  • name or type is invalid,
  • there is already an attribute with the name name, or
  • name is the name of a reserved attribute and T does match the required type(s) of such an attribute.
virtual bool mi::​neuraylib::​IAttribute_set::destroy_attribute( const char* name) [pure virtual]

Destroys the attribute name.

Parameters

name
The name of the attribute to destroy.

Returns

Returns true if the attribute has been successfully destroyed, and false otherwise (there is no attribute with the name name ).

virtual IData* mi::​neuraylib::​IAttribute_set::edit_attribute( const char* name) [pure virtual]

Returns a mutable pointer to the attribute name.

Parameters

name
The name of the attribute. In addition, you can also access parts of array or structure attributes directly. For an array element add the index in square brackets to the attribute name. For a structure member add a dot and the name of the structure member to the attribute name.

Returns

A pointer to the attribute, or NULL if there is no attribute with the name name .

template< class T>

T* mi::​neuraylib::​IAttribute_set::edit_attribute( const char* name) [inline]

Returns a mutable pointer to the attribute name. 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.

Parameters

name
The name of the attribute. In addition, you can also access parts of array or structure attributes directly. For an array element add the index in square brackets to the attribute name. For a structure member add a dot and the name of the structure member to the attribute name.

Returns

A pointer to the attribute, or NULL if there is no attribute with the name name or if T does not match the attribute's type.

virtual const char* mi::​neuraylib::​IAttribute_set::enumerate_attributes( Sint32 index) const [pure virtual]

Returns the name of the attribute indicated by index.

Parameters

index
The index of the attribute.

Returns

The name of the attribute indicated by index , or NULL if index is out of bounds.

virtual Propagation_type mi::​neuraylib::​IAttribute_set::get_attribute_propagation( const char* name) const [pure virtual]

Returns the propagation type of the attribute name.

virtual const char* mi::​neuraylib::​IAttribute_set::get_attribute_type_name( const char* name) const [pure virtual]

Returns the type of an attribute. See Types for a list of supported attribute types.

Note:

The return value of this method is only valid until the next call of this method or any non-const methods on this instance.

Parameters

name
The name of the attribute. In addition, you can also query parts of array or structure attributes directly. For an array element add the index in square brackets to the attribute name. For a structure member add a dot and the name of the structure member to the attribute name.

Returns

The type name of the attribute (or part thereof), or NULL if there is no attribute with the name name .

virtual bool mi::​neuraylib::​IAttribute_set::is_attribute( const char* name) const [pure virtual]

Indicates existence of an attribute.

Parameters

name
The name of the attribute. In addition, you can also checks for parts of array or structure attributes directly. For an array element add the index in square brackets to the attribute name. For a structure member add a dot and the name of the structure member to the attribute name.

Returns

true if the attribute set contains this attribute (and the attribute contains the requested array element or struct member), false otherwise

virtual Sint32 mi::​neuraylib::​IAttribute_set::set_attribute_propagation( const char* name, Propagation_type value) [pure virtual]

Sets the propagation type of the attribute name.

Returns

  • 0: Success.
  • -1: Invalid parameters (NULL pointer or invalid enum value).
  • -2: There is no attribute with name name.