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

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

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 n) =0
Appends n 3d-vectors to the attribute vector from the array v. More...
virtual const Float32_3_struct* get_vector3( Uint32 index, Uint32 n) const =0
Returns a pointer to the n values of type mi::Float32_3 at position index. More...
virtual Sint32 set_vector3( Uint32 index, const Float32_3_struct* v, Uint32 n) =0
Sets the n 3d-vectors starting at position index to the new 3d-vectors v. More...

Elements of type mi::Float32

virtual Sint32 append_float32( const Float32* f, Uint32 n) =0
Appends n floats to the attribute vector from the array f. More...
virtual const Float32* get_float32( Uint32 index, Uint32 n) const =0
Returns a pointer to the n value of type mi::Float32 at position index. More...
virtual Sint32 set_float32( Uint32 index, const Float32* f, Uint32 n) =0
Sets the n floats at position index to the new floats f. More...

Member Functions

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

Appends n 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 n does not match the array size of the attribute.
  • -5: The attribute does not store elements of type mi::Float32.
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_vector3( const Float32_3_struct& v) [pure virtual]

Appends a new 3d-vector to the attribute vector.

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 n) [pure virtual]

Appends n 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 n 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(), and mi::neuraylib::IPolygon_connectivity::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 n) const [pure virtual]

Returns a pointer to the n value 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, n 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 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 n) const [pure virtual]

Returns a pointer to the n 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, n 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 n) [pure virtual]

Sets the n floats at 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 n does not match the array size of the attribute.
  • -5: The attribute does not store elements of type mi::Float32.
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_vector3( Uint32 index, const Float32_3_struct& v) [pure virtual]

Sets the 3d-vector at position index to the new 3d-vector v.

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 n) [pure virtual]

Sets the n 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 n 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::size() const [pure virtual]

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