A connectivity class for polygon mesh geometry and their attributes. More...

#include <ipolygon_connectivity.h>

Inheritance diagram for mi::neuraylib::IPolygon_connectivity:

Public Member Functions
Methods related to the mapping represented by the connectivity
virtual Uint32	polygons_size () const =0
	Returns the number of polygons. More...

virtual Uint32	polygon_corners_size (Polygon_handle_struct p) const =0
	Returns the number of vertices for a given polygon `p`. More...

virtual Sint32	set_polygon_indices (Polygon_handle_struct p, const Uint32 *indices)=0
	Sets the vertex indices of a polygon. More...

virtual Sint32	set_polygon_indices (Polygon_handle_struct p, Uint32 v0, Uint32 v1, Uint32 v2)=0
	Sets the vertex indices of a triangle. More...

virtual Sint32	set_polygon_indices (Polygon_handle_struct p, Uint32 v0, Uint32 v1, Uint32 v2, Uint32 v3)=0
	Sets the vertex indices of a quad. More...

virtual Uint32	get_polygon_index (Polygon_handle_struct p, Uint32 vertex) const =0
	Returns the index at the vertex `vertex` of polygon `p`. More...

virtual bool	is_valid_connectivity () const =0
	Indicates whether this connectivity is valid. More...

Methods related to the attached mesh attributes
virtual bool	has_attribute (Mesh_attribute_name name) const =0
	Indicates whether the connectivity has a particular mesh attribute. More...

virtual IAttribute_vector *	create_attribute_vector (Mesh_attribute_name name, Uint32 dim=1) const =0
	Creates a non-per-primitive mesh attribute. More...

virtual const IAttribute_vector *	access_attribute_vector (Mesh_attribute_name name) const =0
	Returns a non-per-primitive mesh attribute. More...

virtual IAttribute_vector *	edit_attribute_vector (Mesh_attribute_name name)=0
	Detaches and returns a non-per-primitive mesh attribute. More...

virtual Sint32	attach_attribute_vector (IAttribute_vector *attr)=0
	Attaches a given non-per-primitive mesh attribute to the mesh. More...

virtual Sint32	remove_attribute_vector (Mesh_attribute_name name)=0
	Removes a non-per-primitive mesh attribute. More...

Miscellaneous methods
virtual Connectivity_map_type	get_map_type () const =0
	Returns the type of the connectivity. More...

virtual bool	is_hole (Polygon_handle_struct p) const =0
	Indicates whether the polygon `p` represents a hole. 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< 0xebb5744c, ... >
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< 0xebb5744c, ... >
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

A connectivity class for polygon mesh geometry and their attributes.

A polygon connectivity maps vertices of a polygon mesh to indices. The vertices of the polygon mesh are identified by a pair of a polygon handle and a (local) vertex index in [0,polygon_corners_size()). Connectivities may have attached attribute vectors which use the connectivity information.

The meaning of the index associated with each vertex of the mesh is as follows: If the connectivity is the mesh connectivity, then this index identifies the point that belongs to a given vertex. Otherwise, the connectivity is called custom connectivity, and the index identifies an entry in an attribute vector that is associated with the given vertex. Note that attribute vectors can also be attached to the mesh connectivity (in which case an entry in the attribute vector is associated with the point mapped to the given vertex).

Attributes that have the same topological layout as the geometry typically use the mesh connectivity, e.g., normals for every point in the mesh. It is also possible to use an attribute connectivity with the same mapping as the mesh connectivity, however, using the mesh connectivity is more efficient. The use of a separate custom connectivity is necessary if the topological layout of the attribute is different from the geometry, e.g., for texture spaces with seams. Custom connectivities can also be useful to reduce the size of the attribute vector by sharing the same attribute value, e.g., for sharing the same normal between many points because of flat regions in the mesh.

Since the number of polygons is dictated by the mesh that the connectivity is associated with, it can only be changed by corresponding calls to the mi::neuraylib::IPolygon_mesh instance. It is possible to add points and polygons and to set the indices of the connectivities in alternating order, if so desired. The only constraint is that the largest connectivity index is smaller than the number of points (for the mesh connectivity) and smaller than the sizes of the attached attribute vectors (for all connectivities).

To create mesh attributes with the same connectivity, you can use a single connectivity and attach all these attributes to the same connectivity. However, when the mesh is retrieved from the DB no guarantee is given whether the attributes still share the connectivity or not.

Note: You must not release the mesh from which this connectivity was obtained before you release the connectivity.

See also: mi::neuraylib::IPolygon_mesh; mi::neuraylib::IAttribute_vector

Member Function Documentation

^◆ access_attribute_vector()

virtual const IAttribute_vector * mi::neuraylib::IPolygon_connectivity::access_attribute_vector ( Mesh_attribute_name name ) const

pure virtual

Returns a non-per-primitive mesh attribute.

Parameters

name	The name of the attribute, see Mesh_attribute_name. The attribute must not be a per-primitive attribute.

Returns: The requested attribute vector, or NULL in case of failure.

^◆ attach_attribute_vector()

virtual Sint32 mi::neuraylib::IPolygon_connectivity::attach_attribute_vector ( IAttribute_vector * attr )

pure virtual

Attaches a given non-per-primitive mesh attribute to the mesh.

The attribute vector must not be used any longer after it has been attached.

See also: create_attribute_vector(), edit_attribute_vector()

Returns

0: Success.
-1: Invalid parameters (NULL pointer).
-2: The attribute vector has not been acquired from this connectivity.
-3: An attribute of the same name is already attached to the mesh (or to one of its connectivities).
-4: The connectivity is invalid.
-5: The attribute vector is too small for this connectivity.

^◆ create_attribute_vector()

virtual IAttribute_vector * mi::neuraylib::IPolygon_connectivity::create_attribute_vector	(	Mesh_attribute_name	name,
		Uint32	dim = `1`
	)		const

pure virtual

Creates a non-per-primitive mesh attribute.

The attribute is not yet attached to the connectivity. It needs to be attached before it is released.

Note: It is possible to create multiple attribute vectors on the same connectivity. If this connectivity is not the mesh connectivity, i.e., the attribute is not per point, but per vertex, then the connectivity information will eventually be duplicated such that each attribute vector has its own copy. This duplication happens after re-attaching the connectivity, but before it is stored in the database or the edit cycle ends.

See also: attach_attribute_vector()

Parameters

name	The name of the attribute, see Mesh_attribute_name. The attribute must not be a per-primitive attribute.
dim	Dimension of an attribute value. Only used for those attributes that have user specifiable dimensions.

Returns: The requested attribute vector, or NULL in case of failure.

^◆ edit_attribute_vector()

virtual IAttribute_vector * mi::neuraylib::IPolygon_connectivity::edit_attribute_vector ( Mesh_attribute_name name )

pure virtual

Detaches and returns a non-per-primitive mesh attribute.

The attribute needs to be reattached before it is released. Otherwise, the attribute is effectively removed from the connectivity.

See also: attach_attribute_vector()

Parameters

name	The name of the attribute, see Mesh_attribute_name. The attribute must not be a per-primitive attribute.

Returns: The requested attribute vector, or NULL in case of failure.

^◆ get_map_type()

virtual Connectivity_map_type mi::neuraylib::IPolygon_connectivity::get_map_type ( ) const

pure virtual

Returns the type of the connectivity.

Currently, only one type is supported.

^◆ get_polygon_index()

virtual Uint32 mi::neuraylib::IPolygon_connectivity::get_polygon_index	(	Polygon_handle_struct	p,
		Uint32	vertex
	)		const

pure virtual

Returns the index at the vertex vertex of polygon p.

Returns: The requested vertex index, or 0 if p is out of bounds, or vertex exceeds the number of vertices of polygon p.

^◆ has_attribute()

virtual bool mi::neuraylib::IPolygon_connectivity::has_attribute ( Mesh_attribute_name name ) const

pure virtual

Indicates whether the connectivity has a particular mesh attribute.

Parameters

name	The name attribute to query, see Mesh_attribute_name.

Returns: true if the connectivity has this attribute, false otherwise.

^◆ is_hole()

virtual bool mi::neuraylib::IPolygon_connectivity::is_hole ( Polygon_handle_struct p ) const

pure virtual

Indicates whether the polygon p represents a hole.

^◆ is_valid_connectivity()

virtual bool mi::neuraylib::IPolygon_connectivity::is_valid_connectivity ( ) const

pure virtual

Indicates whether this connectivity is valid.

A connectivity becomes invalid after it has been (re)attached to the corresponding mesh and may no longer been used.

^◆ polygon_corners_size()

virtual Uint32 mi::neuraylib::IPolygon_connectivity::polygon_corners_size ( Polygon_handle_struct p ) const

pure virtual

Returns the number of vertices for a given polygon p.

Returns: The number of vertices, or 0 if p is out of bounds.

^◆ polygons_size()

virtual Uint32 mi::neuraylib::IPolygon_connectivity::polygons_size ( ) const

pure virtual

Returns the number of polygons.

^◆ remove_attribute_vector()

virtual Sint32 mi::neuraylib::IPolygon_connectivity::remove_attribute_vector ( Mesh_attribute_name name )

pure virtual

Removes a non-per-primitive mesh attribute.

Parameters

name	The name of the attribute, see Mesh_attribute_name. The attribute must not be a per-primitive attribute.

Returns

0: Success.
-1: There is no mesh attribute of that name on this connectivity, or the connectivity is invalid.

^◆ set_polygon_indices() [1/3]

virtual Sint32 mi::neuraylib::IPolygon_connectivity::set_polygon_indices	(	Polygon_handle_struct	p,
		const Uint32 *	indices
	)

pure virtual

Sets the vertex indices of a polygon.

Precondition: indices must contain as many indices as p has vertices.

Note: For best performance it is recommended to sort the polygons by their material index such that when looping over all polygons the material index changes as infrequently as possible.

Parameters

p	The polygon to modify.
indices	The new indices for polygon `p`.

Returns

0: Success.
-1: Invalid parameters (NULL pointer).
-3: p is out of bounds.
-4: The connectivity is no longer valid.

^◆ set_polygon_indices() [2/3]

virtual Sint32 mi::neuraylib::IPolygon_connectivity::set_polygon_indices	(	Polygon_handle_struct	p,
		Uint32	v0,
		Uint32	v1,
		Uint32	v2
	)

pure virtual

Sets the vertex indices of a triangle.

Precondition: The polygon referred to by p must be a triangle.

Note: For best performance it is recommended to sort the polygons by their material index such that when looping over all polygons the material index changes as infrequently as possible.

Parameters

p	The triangle to modify.
v0	The first new index of triangle `p`.
v1	The second new index of triangle `p`.
v2	The third new index of triangle `p`.

Returns

0: Success.
-3: p is out of bounds.
-4: The connectivity is no longer valid.

^◆ set_polygon_indices() [3/3]

virtual Sint32 mi::neuraylib::IPolygon_connectivity::set_polygon_indices	(	Polygon_handle_struct	p,
		Uint32	v0,
		Uint32	v1,
		Uint32	v2,
		Uint32	v3
	)

pure virtual

Sets the vertex indices of a quad.

Precondition: The polygon referred to by p must be a quad.

Note: For best performance it is recommended to sort the polygons by their material index such that when looping over all polygons the material index changes as infrequently as possible.

Parameters

p	The quad to modify.
v0	The first new index of quad `p`.
v1	The second new index of quad `p`.
v2	The third new index of quad `p`.
v3	The fourth new index of quad `p`.

Returns

0: Success.
-3: p is out of bounds.
-4: The connectivity is no longer valid.

Public Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ access_attribute_vector()

◆ attach_attribute_vector()

◆ create_attribute_vector()

◆ edit_attribute_vector()

◆ get_map_type()

◆ get_polygon_index()

◆ has_attribute()

◆ is_hole()

◆ is_valid_connectivity()

◆ polygon_corners_size()

◆ polygons_size()

◆ remove_attribute_vector()

◆ set_polygon_indices() [1/3]

◆ set_polygon_indices() [2/3]

◆ set_polygon_indices() [3/3]

^◆ access_attribute_vector()

^◆ attach_attribute_vector()

^◆ create_attribute_vector()

^◆ edit_attribute_vector()

^◆ get_map_type()

^◆ get_polygon_index()

^◆ has_attribute()

^◆ is_hole()

^◆ is_valid_connectivity()

^◆ polygon_corners_size()

^◆ polygons_size()

^◆ remove_attribute_vector()

^◆ set_polygon_indices() [1/3]

^◆ set_polygon_indices() [2/3]

^◆ set_polygon_indices() [3/3]