Interface representing an attribute vector for triangle meshes, polygon meshes, and subdivision surfaces. More...

#include <iattribute_vector.h>

Inheritance diagram for mi::neuraylib::IAttribute_vector:

Public Member Functions
General methods
virtual Uint32	size () const =0
	Returns the size of the attribute vector, i.e., number of elements. More...

virtual Uint32	capacity () const =0
	Returns the capacity reserved in the vector for elements. More...

virtual void	resize (Uint32 size)=0
	Resizes the size of the attribute vector. More...

virtual void	reserve (Uint32 size)=0
	Reserves new capacity `size` for elements. More...

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 Uint32	array_size () const =0
	Returns the array size of the vector elements. More...

Elements of type mi::Uint32
virtual Uint32	get_uint32 (Uint32 index) const =0
	Returns the value of type mi::Uint32 at position `index`. More...

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 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 const Float32_3_struct &	get_vector3 (Uint32 index) const =0
	Returns the value of type mi::Float32_3 at position `index`. More...

virtual Sint32	append_vector3 (const Float32_3_struct &v)=0
	Appends a new 3d-vector to the attribute vector. 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 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	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 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 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	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 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 Sint32	set_user_attribute_name (const char *name)=0
	Sets a name for this attribute vector. More...

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

Public Member Functions inherited from mi::base::IInterface
virtual Uint32	retain () const =0
	Increments the reference count. More...

virtual Uint32	release () const =0
	Decrements the reference count. More...

virtual const IInterface *	get_interface (const Uuid &interface_id) const =0
	Acquires a const interface from another. More...

template<class T>
const T *	get_interface () const
	Acquires a const interface from another. More...

virtual IInterface *	get_interface (const Uuid &interface_id)=0
	Acquires a mutable interface from another. More...

template<class T>
T *	get_interface ()
	Acquires a mutable interface from another. More...

virtual Uuid	get_iid () const =0
	Returns the interface ID of the most derived interface. More...

Additional Inherited Members
Public Types inherited from mi::base::Interface_declare< 0xfbe79601, ... >
typedef Interface_declare< id1, ... >	Self
	Own type. More...

typedef Uuid_t< id1, ... >	IID
	Declares the interface ID (IID) of this interface. More...

Public Types inherited from mi::base::IInterface
typedef Uuid_t<0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0>	IID
	Declares the interface ID (IID) of this interface. More...

Static Public Member Functions inherited from mi::base::Interface_declare< 0xfbe79601, ... >
static bool	compare_iid (const Uuid &iid)
	Compares the interface ID `iid` against the interface ID of this interface and of its ancestors. More...

Static Public Member Functions inherited from mi::base::IInterface
static bool	compare_iid (const Uuid &iid)
	Compares the interface ID `iid` against the interface ID of this interface. More...

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

Member Function Documentation

^◆ append_float32()

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

^◆ append_uint32() [1/2]

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.

^◆ append_uint32() [2/2]

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.

^◆ append_vector3() [1/2]

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.

^◆ append_vector3() [2/2]

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

^◆ array_size()

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.

^◆ capacity()

virtual Uint32 mi::neuraylib::IAttribute_vector::capacity ( ) const

pure virtual

Returns the capacity reserved in the vector for elements.

^◆ clear()

virtual void mi::neuraylib::IAttribute_vector::clear ( )

pure virtual

Clears the attribute vector.

Equivalent to calling resize() with argument 0.

^◆ get_float32()

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

^◆ get_uint32()

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.

^◆ get_user_attribute_name()

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.

^◆ get_vector3() [1/2]

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.

^◆ get_vector3() [2/2]

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

^◆ is_valid_attribute()

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.

^◆ reserve()

virtual void mi::neuraylib::IAttribute_vector::reserve ( Uint32 size )

pure virtual

Reserves new capacity size for elements.

^◆ resize()

virtual void mi::neuraylib::IAttribute_vector::resize ( Uint32 size )

pure virtual

Resizes the size of the attribute vector.

^◆ set_float32()

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.

^◆ set_uint32() [1/2]

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.

^◆ set_uint32() [2/2]

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.

^◆ set_user_attribute_name()

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.

^◆ set_vector3() [1/2]

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.

^◆ set_vector3() [2/2]

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.

^◆ size()

virtual Uint32 mi::neuraylib::IAttribute_vector::size ( ) const

pure virtual

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

Public Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ append_float32()

◆ append_uint32() [1/2]

◆ append_uint32() [2/2]

◆ append_vector3() [1/2]

◆ append_vector3() [2/2]

◆ array_size()

◆ capacity()

◆ clear()

◆ get_float32()

◆ get_uint32()

◆ get_user_attribute_name()

◆ get_vector3() [1/2]

◆ get_vector3() [2/2]

◆ is_valid_attribute()

◆ reserve()

◆ resize()

◆ set_float32()

◆ set_uint32() [1/2]

◆ set_uint32() [2/2]

◆ set_user_attribute_name()

◆ set_vector3() [1/2]

◆ set_vector3() [2/2]

◆ size()

^◆ append_float32()

^◆ append_uint32() [1/2]

^◆ append_uint32() [2/2]

^◆ append_vector3() [1/2]

^◆ append_vector3() [2/2]

^◆ array_size()

^◆ capacity()

^◆ clear()

^◆ get_float32()

^◆ get_uint32()

^◆ get_user_attribute_name()

^◆ get_vector3() [1/2]

^◆ get_vector3() [2/2]

^◆ is_valid_attribute()

^◆ reserve()

^◆ resize()

^◆ set_float32()

^◆ set_uint32() [1/2]

^◆ set_uint32() [2/2]

^◆ set_user_attribute_name()

^◆ set_vector3() [1/2]

^◆ set_vector3() [2/2]

^◆ size()