neuray API Programmer's Manual

mi::neuraylib::IAttribute_vector Class Reference

[Leaf nodes]

Description

Interface representing an attribute vector for triangle meshes, polygon meshes, and subdivision surfaces. Attribute vectors are used for mesh attributes, which are an extension of the regular attributes (see mi::neuraylib::IAttribute_set). They are only supported for scene elements that represent geometry, namely triangle meshes, polygon meshes, and subdivision surfaces. In contrast to regular attributes which exist only once per object, mesh attributes are always a vector of values with one vector element per primitive, per point, or per vertex. Note that a vector element in itself can be an array. For different mesh attributes and their types see mi::neuraylib::Mesh_attribute_name.

Attributes vectors are basically dynamic arrays supporting a limited set of element types. They need to be sufficiently large such that the indices in the corresponding indexing structure are valid. That is, for per-primitive attributes their size needs to be at least the number of primitives. For per-point attributes, their size needs to be at least the number of points. And for per-vertex attributes, their size needs to be at least the largest used index plus 1.

Attribute vectors cannot be created on their own; they have to be requested from an mi::neuraylib::ITriangle_mesh, mi::neuraylib::IPolygon_mesh, mi::neuraylib::ISubdivision_surface, mi::neuraylib::IFreeform_surface, mi::neuraylib::IFibers, or their corresponding connectivities.

This interface allows to resize an attribute vector, and to retrieve and to change the vector elements. Note that attributes have a particular type which determines the variant of the various methods on this interface to use. For example, material indices are of type mi::Uint32. Hence, for such an attribute one would use get_uint32(), append_uint32(), and set_uint32(). Other methods to retrieve or change the vector elements will fail as they do not match the actual type of the vector elements.

Note:

  • You must not release the mesh or connectivity from which this attribute vector was obtained before you release the attribute vector.

  • Some of the methods below use two different size parameters, namely k and n. The n parameter allows to append or set an entire range of vector elements in one call (and defaults to 1). The k parameter refers to the size of a single vector element (see array_size()). Its value is fixed and only used in a sanity check. Methods with both parameters expect the data in an n-major layout.

mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. The basic extensible interface.The basic extensible interface.

General methods

virtual Uint32 array_size() const =0
Returns the array size of the vector elements. More...
virtual Uint32 capacity() const =0
Returns the capacity reserved in the vector for elements.
virtual void clear() =0
Clears the attribute vector. More...
virtual bool  is_valid_attribute() const =0
Indicates whether this attribute vector is valid. More...
virtual void reserve( Uint32 size) =0
Reserves new capacity size for elements.
virtual void resize( Uint32 size) =0
Resizes the size of the attribute vector.
virtual Uint32 size() const =0
Returns the size of the attribute vector, i.e., number of elements.

Elements of type mi::Uint32

virtual Sint32 append_uint32( Uint32 u) =0
Appends a value of type mi::Uint32 to the attribute vector. More...
virtual Sint32 append_uint32( const Uint32* u, Uint32 k, Size n = 1) =0
Appends one or more values of type mi::Uint32 to the attribute vector. More...
virtual Uint32 get_uint32( Uint32 index) const =0
Returns the value of type mi::Uint32 at position index. More...
virtual Sint32 set_uint32( Uint32 index, Uint32 u) =0
Sets the value of type mi::Uint32 at position index to the new value u. More...
virtual Sint32 set_uint32( Uint32 index, const Uint32* u, Uint32 k, Size n = 1) =0
Sets one or more values of type mi::Uint32 starting at position index. More...

Elements of type mi::Float32_3

virtual Sint32 append_vector3( const Float32_3_struct& v) =0
Appends a new 3d-vector to the attribute vector. More...
virtual const Float32_3_struct& get_vector3( Uint32 index) const =0
Returns the value of type mi::Float32_3 at position index. More...
virtual Sint32 set_vector3( Uint32 index, const Float32_3_struct& v) =0
Sets the 3d-vector at position index to the new 3d-vector v. More...

Elements of type mi::Float32_3[]

virtual Sint32 append_vector3( const Float32_3_struct* v, Uint32 k, Size n = 1) =0
Appends one or more k -tuples of 3d-vectors to the attribute vector from the array v. More...
virtual const Float32_3_struct* get_vector3( Uint32 index, Uint32 k) const =0
Returns a pointer to the k values of type mi::Float32_3 at position index. More...
virtual Sint32 set_vector3( Uint32 index, const Float32_3_struct* v, Uint32 k, Size n = 1) =0
Sets one or more k -tuples of 3d-vectors starting at position index to the new 3d-vectors v. More...

Elements of type mi::Float32 or mi::Float32[]

virtual Sint32 append_float32( const Float32* f, Uint32 k, Size n = 1) =0
Appends one or more k -tuples of floats to the attribute vector from the array f. More...
virtual const Float32* get_float32( Uint32 index, Uint32 k) const =0
Returns a pointer to the k values of type mi::Float32 at position index. More...
virtual Sint32 set_float32( Uint32 index, const Float32* f, Uint32 k, Size n = 1) =0
Sets one or more k -tuples of floats at starting position index to the new floats f. More...

User-defined names

virtual const char* get_user_attribute_name() const =0
Returns the name of this attribute vector or NULL in case no name was given.
virtual Sint32 set_user_attribute_name( const char* name) =0
Sets a name for this attribute vector. More...

Member Functions

virtual Sint32 mi::​neuraylib::​IAttribute_vector::append_float32( const Float32* f, Uint32 k, Size n = 1) [pure virtual]

Appends one or more k -tuples of floats to the attribute vector from the array f.

Returns

  • 0: Success.
  • -1: The attribute is invalid.
  • -3: Invalid parameters (NULL pointer).
  • -4: The parameter k does not match the array size of the attribute.
  • -5: The attribute does not store elements of type mi::Float32 (or arrays thereof).

virtual Sint32 mi::​neuraylib::​IAttribute_vector::append_uint32( Uint32 u) [pure virtual]

Appends a value of type mi::Uint32 to the attribute vector.

Returns

  • 0: Success.
  • -1: The attribute is invalid.
  • -5: The attribute does not store elements of type mi::Uint32.

virtual Sint32 mi::​neuraylib::​IAttribute_vector::append_uint32( const Uint32* u, Uint32 k, Size n = 1) [pure virtual]

Appends one or more values of type mi::Uint32 to the attribute vector. The parameter k exists solely for consistency with other methods of this interface and must be set to 1.

Returns

  • 0: Success.
  • -1: The attribute is invalid.
  • -4: The parameter k does not match the array size of the attribute.
  • -5: The attribute does not store elements of type mi::Uint32.

virtual Sint32 mi::​neuraylib::​IAttribute_vector::append_vector3( const Float32_3_struct& v) [pure virtual]

Appends a new 3d-vector to the attribute vector. To append a range of 3d-vectors, use the overload with three parameters, and pass 1 for k.

Returns

  • 0: Success.
  • -1: The attribute is invalid.
  • -5: The attribute does not store elements of type mi::Float32_3.

virtual Sint32 mi::​neuraylib::​IAttribute_vector::append_vector3( const Float32_3_struct* v, Uint32 k, Size n = 1) [pure virtual]

Appends one or more k -tuples of 3d-vectors to the attribute vector from the array v.

Returns

  • 0: Success.
  • -1: The attribute is invalid.
  • -3: Invalid parameters (NULL pointer).
  • -4: The parameter k does not match the array size of the attribute.
  • -5: The attribute does not store elements of type mi::Float32_3 (or arrays thereof).

virtual Uint32 mi::​neuraylib::​IAttribute_vector::array_size() const [pure virtual]

Returns the array size of the vector elements. The array size of the vector elements equals the dim parameter during creation of the attribute vector, see mi::neuraylib::ITriangle_mesh::create_attribute_vector(), mi::neuraylib::ITriangle_connectivity::create_attribute_vector(), mi::neuraylib::IPolygon_mesh::create_attribute_vector(), mi::neuraylib::IPolygon_connectivity::create_attribute_vector(), mi::neuraylib::IFreeform_surface::create_attribute_vector(), and mi::neuraylib::IFibers::create_attribute_vector().

For example, the array size is 1 for normal vectors, and 2 for surface derivatives.

virtual Uint32 mi::​neuraylib::​IAttribute_vector::capacity() const [pure virtual]

Returns the capacity reserved in the vector for elements.

virtual void mi::​neuraylib::​IAttribute_vector::clear() [pure virtual]

Clears the attribute vector. Equivalent to calling resize() with argument 0.

virtual const Float32* mi::​neuraylib::​IAttribute_vector::get_float32( Uint32 index, Uint32 k) const [pure virtual]

Returns a pointer to the k values of type mi::Float32 at position index.

Returns

The pointer to the values, or NULL if the attribute is invalid, index is out of bounds, k is not equal to array_size() , or the attribute does not store elements of type mi::Float32 (or arrays thereof).

virtual Uint32 mi::​neuraylib::​IAttribute_vector::get_uint32( Uint32 index) const [pure virtual]

Returns the value of type mi::Uint32 at position index.

Returns

The value, or 0 if the attribute is invalid, index is out of bounds, or the attribute does not store elements of type mi::Uint32.

virtual const char* mi::​neuraylib::​IAttribute_vector::get_user_attribute_name() const [pure virtual]

Returns the name of this attribute vector or NULL in case no name was given.

virtual const Float32_3_struct& mi::​neuraylib::​IAttribute_vector::get_vector3( Uint32 index) const [pure virtual]

Returns the value of type mi::Float32_3 at position index.

Returns

The value, or (0, 0, 0) if the attribute is invalid, index is out of bounds, or the attribute does not store elements of type mi::Float32_3.

virtual const Float32_3_struct* mi::​neuraylib::​IAttribute_vector::get_vector3( Uint32 index, Uint32 k) const [pure virtual]

Returns a pointer to the k values of type mi::Float32_3 at position index.

Returns

The pointer to the values, or NULL if the attribute is invalid, index is out of bounds, k is not equal to array_size() , or the attribute does not store elements of type mi::Float32_3 (or arrays thereof).

virtual bool mi::​neuraylib::​IAttribute_vector::is_valid_attribute() const [pure virtual]

Indicates whether this attribute vector is valid. An attribute vector becomes invalid after it has been (re)attached to the corresponding mesh or connectivity and may no longer been used.

virtual void mi::​neuraylib::​IAttribute_vector::reserve( Uint32 size) [pure virtual]

Reserves new capacity size for elements.

virtual void mi::​neuraylib::​IAttribute_vector::resize( Uint32 size) [pure virtual]

Resizes the size of the attribute vector.

virtual Sint32 mi::​neuraylib::​IAttribute_vector::set_float32( Uint32 index, const Float32* f, Uint32 k, Size n = 1) [pure virtual]

Sets one or more k -tuples of floats at starting position index to the new floats f.

Returns

  • 0: Success.
  • -1: The attribute is invalid.
  • -2: index is out of bounds.
  • -3: Invalid parameters (NULL pointer).
  • -4: The parameter k does not match the array size of the attribute.
  • -5: The attribute does not store elements of type mi::Float32 (or arrays thereof).
  • -6: n is too large, i.e., index+n-1 is out of bounds.

virtual Sint32 mi::​neuraylib::​IAttribute_vector::set_uint32( Uint32 index, Uint32 u) [pure virtual]

Sets the value of type mi::Uint32 at position index to the new value u.

Returns

  • 0: Success.
  • -1: The attribute is invalid.
  • -2: index is out of bounds.
  • -5: The attribute does not store elements of type mi::Uint32.

virtual Sint32 mi::​neuraylib::​IAttribute_vector::set_uint32( Uint32 index, const Uint32* u, Uint32 k, Size n = 1) [pure virtual]

Sets one or more values of type mi::Uint32 starting at position index. The parameter k exists solely for consistency with other methods of this interface and must be set to 1.

Returns

  • 0: Success.
  • -1: The attribute is invalid.
  • -2: index is out of bounds.
  • -4: The parameter k does not match the array size of the attribute.
  • -5: The attribute does not store elements of type mi::Uint32.
  • -6: n is too large, i.e., index+n-1 is out of bounds.

virtual Sint32 mi::​neuraylib::​IAttribute_vector::set_user_attribute_name( const char* name) [pure virtual]

Sets a name for this attribute vector. Please note that name are only supported for attribute vectors of type mi::neuraylib::ATTR_USER.

Parameters

name
The attribute name

Returns

  • 0: Success.
  • -1: The attribute is not of type mi::neuraylib::ATTR_USER.

virtual Sint32 mi::​neuraylib::​IAttribute_vector::set_vector3( Uint32 index, const Float32_3_struct& v) [pure virtual]

Sets the 3d-vector at position index to the new 3d-vector v. To set a range of 3d-vectors, use the overload with four parameters, and pass 1 for k.

Returns

  • 0: Success.
  • -1: The attribute is invalid.
  • -2: index is out of bounds.
  • -5: The attribute does not store elements of type mi::Float32_3.

virtual Sint32 mi::​neuraylib::​IAttribute_vector::set_vector3( Uint32 index, const Float32_3_struct* v, Uint32 k, Size n = 1) [pure virtual]

Sets one or more k -tuples of 3d-vectors starting at position index to the new 3d-vectors v.

Returns

  • 0: Success.
  • -1: The attribute is invalid.
  • -2: index is out of bounds.
  • -3: Invalid parameters (NULL pointer).
  • -4: The parameter k does not match the array size of the attribute.
  • -5: The attribute does not store elements of type mi::Float32_3 (or arrays thereof).
  • -6: n is too large, i.e., index+n-1 is out of bounds.

virtual Uint32 mi::​neuraylib::​IAttribute_vector::size() const [pure virtual]

Returns the size of the attribute vector, i.e., number of elements.