NVIDIA Iray SDK API nvidia_logo_transpbg.gif Up
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
mi::neuraylib::IPolygon_mesh Class Referenceabstract

Interface representing a polygon mesh. More...

+ Inheritance diagram for mi::neuraylib::IPolygon_mesh:

Public Member Functions

Methods related to points
virtual Uint32 points_size () const =0
 Returns the number of points in the mesh. More...
 
virtual Uint32 points_capacity () const =0
 Returns the number of points for which space is allocated in the mesh. More...
 
virtual void reserve_points (Uint32 n)=0
 Reserves space for at least n points. More...
 
virtual Sint32 point (Uint32 index, Float32_3_struct &p) const =0
 Returns the coordinates of the point of index index in the output parameter p. More...
 
virtual Sint32 point (Uint32 index, Float64_3_struct &p) const =0
 Returns the coordinates of the point of index index in the output parameter p. More...
 
virtual Uint32 append_point (const Float32_3_struct &p)=0
 Adds a point p to the end of all points and returns the index of the new point. More...
 
virtual Uint32 append_point (const Float64_3_struct &p)=0
 Adds a point p to the end of all points and returns the index of the new point. More...
 
virtual Sint32 set_point (Uint32 index, const Float32_3_struct &p)=0
 Sets the point of index index to the new point p. More...
 
virtual Sint32 set_point (Uint32 index, const Float64_3_struct &p)=0
 Sets the point of index index to the new point p. More...
 
Methods related to polygons
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 bool is_hole (Polygon_handle_struct p) const =0
 Indicates whether the polygon p represents a hole. More...
 
virtual Uint32 indices_size () const =0
 Returns the total number of indices, i.e., the sum of the number of vertices of all polygons. More...
 
virtual bool is_polygon_size_constant () const =0
 Indicates whether all polygons have the same number of vertices. More...
 
virtual Polygon_handle_struct add_polygon (Uint32 num_vertices, bool hole=false)=0
 Adds a polygon to the mesh. More...
 
Methods related to the mesh connectivity
virtual const
IPolygon_connectivity
access_mesh_connectivity () const =0
 Returns the mesh connectivity. More...
 
virtual IPolygon_connectivityedit_mesh_connectivity ()=0
 Detaches and returns the mesh connectivity. More...
 
virtual Sint32 attach_mesh_connectivity (IPolygon_connectivity *connectivity)=0
 Attaches the mesh connectivity to the mesh. More...
 
Methods related to custom connectivities
virtual IPolygon_connectivitycreate_connectivity (Connectivity_map_type map_type=CONNECTIVITY_MAP_GENERIC)=0
 Creates a new connectivity for non-per-primitive attributes. More...
 
virtual const
IPolygon_connectivity
access_connectivity (Mesh_attribute_name name) const =0
 Returns the connectivity for a given mesh attribute. More...
 
virtual IPolygon_connectivityedit_connectivity (Mesh_attribute_name name)=0
 Detaches and returns the connectivity for a given mesh attribute. More...
 
virtual Sint32 attach_connectivity (IPolygon_connectivity *connectivity)=0
 Attaches a given connectivity to the mesh. More...
 
virtual Sint32 remove_connectivity (Mesh_attribute_name name)=0
 Removes the connectivity for a non-per-primitive mesh attribute. More...
 
Methods related to per-primitive attributes
virtual bool has_attribute (Mesh_attribute_name name) const =0
 Indicates whether the mesh has a particular mesh attribute (per-primitive or other types) More...
 
virtual IAttribute_vectorcreate_attribute_vector (Mesh_attribute_name name, Uint32 dim=1)=0
 Creates a per-primitive mesh attribute. More...
 
virtual const IAttribute_vectoraccess_attribute_vector (Mesh_attribute_name name) const =0
 Returns a per-primitive mesh attribute. More...
 
virtual IAttribute_vectoredit_attribute_vector (Mesh_attribute_name name)=0
 Detaches and returns a per-primitive mesh attribute. More...
 
virtual Sint32 attach_attribute_vector (IAttribute_vector *attribute_vector)=0
 Attaches a given per-primitive mesh attribute to the mesh. More...
 
virtual Sint32 remove_attribute_vector (Mesh_attribute_name name)=0
 Removes a per-primitive mesh attribute. More...
 
Methods related to the bounding box
virtual Bbox3_struct get_bbox () const =0
 Returns the bounding box of the polygon mesh. More...
 
virtual Bbox3_struct get_tight_bbox (const Float64_4_4_struct &transformation_matrix) const =0
 Returns the bounding box of the polygon mesh after transformation. More...
 
Methods related to displacement
virtual void set_maximum_displacement (Float32 displacement)=0
 Sets the maximum displacement of the polygon mesh. More...
 
virtual Float32 get_maximum_displacement () const =0
 Returns the maximum displacement of the polygon mesh. More...
 

Additional Inherited Members

- Public Types inherited from mi::base::Interface_declare< 0x598d264b, 0x1d1f, 0x40c9, 0x88, 0xe6, 0x54, 0x19, 0x30, 0x08, 0xc7, 0xb2, neuraylib::IScene_element >
typedef Interface_declare< id1,
id2, id3, id4, id5, id6, id7,
id8, id9, id10, id11,
neuraylib::IScene_element
Self
 Own type. More...
 
typedef Uuid_t< id1, id2, id3,
id4, id5, id6, id7, id8, id9,
id10, id11 > 
IID
 Declares the interface ID (IID) of this interface. More...
 
- Static Public Member Functions inherited from mi::base::Interface_declare< 0x598d264b, 0x1d1f, 0x40c9, 0x88, 0xe6, 0x54, 0x19, 0x30, 0x08, 0xc7, 0xb2, neuraylib::IScene_element >
static bool compare_iid (const Uuid &iid)
 Compares the interface ID iid against the interface ID of this interface and of its ancestors. More...
 

Detailed Description

Interface representing a polygon mesh.

Polygon meshes are represented in an indexed format where polygons are a finite sequence of indices pointing into an array of points. Points and polygons are stored with consecutive indices, starting with the index 0 each. Both, points and polygons, can then be referred to by their index numbers. For type safety, polygon indices are represented using mi::neuraylib::Polygon_handle instead of plain integers.

This interface provides methods to add points and polygons, and to specify the location of the points. It does not directly provide methods to map the vertices of the polygons to the points. This needs to be done via the polygon connectivity (see edit_mesh_connectivity()).

Polygons with holes can be represented, too. The holes are represented in the same way as polygons themselves, but a flag (see add_polygon()) distinguishes them from the polygons (or more precise, from the outer boundary of polygons). Note that the orientation of holes does not matter.

In addition to regular attributes (see mi::neuraylib::IAttribute_set), meshes can also have mesh attributes. 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 (see mi::neuraylib::Mesh_attribute_name and mi::neuraylib::IAttribute_vector for details).

Per-primitive attributes can be directly used with the methods of this interface, namely create_attribute_vector(), access_attribute_vector(), edit_attribute_vector(), and attach_attribute_vector().

Per-point and per-vertex attributes require the use of a connectivity instead. Per-point attributes use the mesh connectivity (see edit_mesh_connectivity() and related methods), whereas per-vertex attributes use custom connectivities (see create_connectivity() and related methods).

This mesh interface supports the incremental construction of a mesh. Points and polygons can be added one at a time and in alternating order, if so desired. The only constraint is that polygons shall only refer to point indices of points that have been added already.

The deletion of once added elements is not supported.

See also the "approx" attribute on mi::neuraylib::IAttribute_set for information how to control the tessellation of the polygon mesh.

See Also
mi::neuraylib::IPolygon_connectivity
mi::neuraylib::IAttribute_vector

Example: Create a mesh with a single quad with one normal and four texture coordinates

// The points of the quad
point[0] = mi::Float32_3( 0.0f, 0.0f, 0.0f);
point[0] = mi::Float32_3( 1.0f, 0.0f, 0.0f);
point[0] = mi::Float32_3( 1.0f, 1.0f, 0.0f);
point[0] = mi::Float32_3( 0.0f, 0.0f, 0.0f);
// The normal of the quad
mi::Float32_3 normal( 0.0f, 0.0f, 1.0f);
// The texture coordinates for the quad
mi::Float32_2 tex_coord[4];
tex_coord[0] = mi::Float32_2( 0.0f, 0.0f);
tex_coord[0] = mi::Float32_2( 1.0f, 0.0f);
tex_coord[0] = mi::Float32_2( 1.0f, 1.0f);
tex_coord[0] = mi::Float32_2( 0.0f, 1.0f);
transaction->create<mi::neuraylib::IPolygon_mesh>( "Polygon_mesh"));
// Create the points of the mesh
for( mi::Uint32 i = 0; i < 4; ++i)
mesh->append_point( point[i]);
// Create the quad and add the mapping of its vertices to points via the mesh connectivity
mi::neuraylib::Polygon_handle polygon_handle( mesh->add_polygon( 4));
mesh->edit_mesh_connectivity());
mesh_connectivity->set_polygon_indices( polygon_handle, 0, 1, 2, 3);
// Create an attribute vector for 2-dimensional texture coordinates
mesh_connectivity->create_attribute_vector( mi::neuraylib::ATTR_TEXTURE, 2));
for( mi::Uint32 i = 0; i < 4; ++i)
texture_coordinates->append_float32( &tex_coord[i].x, 2);
mesh_connectivity->attach_attribute_vector( texture_coordinates.get());
// Attach the mesh connectivity back to mesh
mesh->attach_mesh_connectivity( mesh_connectivity.get());
// Create a custom connectivity for normals to share the same normal for all vertices
mesh->create_connectivity( mi::neuraylib::CONNECTIVITY_MAP_GENERIC));
normal_connectivity->set_polygon_indices( polygon_handle, 0, 0, 0, 0);
// Create an attribute vector for normals
normal_connectivity->create_attribute_vector( mi::neuraylib::ATTR_NORMAL, 1));
normals->append_vector3( normal);
normal_connectivity->attach_attribute_vector( normals.get());
// Attach the custom connectivity to the mesh
mesh->attach_connectivity( normal_connectivity.get());

Member Function Documentation

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

Returns a per-primitive mesh attribute.

Parameters
nameThe name of the attribute, see Mesh_attribute_name. The attribute must be a per-primitive attribute.
Returns
The requested attribute vector, or NULL in case of failure.
virtual const IPolygon_connectivity* mi::neuraylib::IPolygon_mesh::access_connectivity ( Mesh_attribute_name  name) const
pure virtual

Returns the connectivity for a given mesh attribute.

Parameters
nameThe name of the attribute to return the connectivity for, see Mesh_attribute_name.
Returns
The connectivity for name, or NULL if there is no such attribute, or the attribute is a per-primitive attribute.
virtual const IPolygon_connectivity* mi::neuraylib::IPolygon_mesh::access_mesh_connectivity ( ) const
pure virtual

Returns the mesh connectivity.

Returns
The mesh connectivity, or NULL if it currently not attached.
virtual Polygon_handle_struct mi::neuraylib::IPolygon_mesh::add_polygon ( Uint32  num_vertices,
bool  hole = false 
)
pure virtual

Adds a polygon to the mesh.

Afterwards all connectivities and attributes must be updated accordingly.

Parameters
num_verticesThe number of vertices of this polygon.
holeFlag that identifies holes.
Returns
A handle for the new polygon, or a default-constructed handle if num_vertices < 3.
virtual Uint32 mi::neuraylib::IPolygon_mesh::append_point ( const Float32_3_struct p)
pure virtual

Adds a point p to the end of all points and returns the index of the new point.

The mesh class provides several overloaded versions for different parameter types. No information about the underlying storage is specified. The caller should use the best matching call for the caller's data representation.

virtual Uint32 mi::neuraylib::IPolygon_mesh::append_point ( const Float64_3_struct p)
pure virtual

Adds a point p to the end of all points and returns the index of the new point.

The mesh class provides several overloaded versions for different parameter types. No information about the underlying storage is specified. The caller should use the best matching call for the caller's data representation.

virtual Sint32 mi::neuraylib::IPolygon_mesh::attach_attribute_vector ( IAttribute_vector attribute_vector)
pure virtual

Attaches a given 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 mesh.
  • -3: The attribute vector is not a per-primitive attribute vector.
  • -4: The attribute vector is a per-primitive attribute vector and the number of elements does not match the number of polygons of the mesh.
  • -5: An attribute of the same name is already attached to the mesh (or to one of its connectivities).
virtual Sint32 mi::neuraylib::IPolygon_mesh::attach_connectivity ( IPolygon_connectivity connectivity)
pure virtual

Attaches a given connectivity to the mesh.

This implicitly binds all attributes of the connectivity to the mesh. The connectivity must not be used any longer after it has been attached.

See Also
create_connectivity(), edit_connectivity()
Returns
  • 0: Success.
  • -1: Invalid parameters (NULL pointer).
  • -2: The connectivity has not been created by or acquired from this mesh.
  • -3: The connectivity is already attached to the mesh.
  • -4: The connectivity is inconsistent (at least one index is too large for one of the attached attribute vectors).
virtual Sint32 mi::neuraylib::IPolygon_mesh::attach_mesh_connectivity ( IPolygon_connectivity connectivity)
pure virtual

Attaches the mesh connectivity to the mesh.

This implicitly binds all attributes of the connectivity to the mesh. The connectivity must not be used any longer after it has been attached.

See Also
edit_mesh_connectivity()
Returns
  • 0: Success.
  • -1: Invalid parameters (NULL pointer).
  • -2: The mesh connectivity has not been acquired from this mesh.
  • -3: The mesh connectivity of this mesh has already been attached.
  • -4: The mesh connectivity is inconsistent (at least one index is too large for the number of points or one of the attached attribute vectors).
  • -5: The connectivity is not a mesh connectivity.
virtual IAttribute_vector* mi::neuraylib::IPolygon_mesh::create_attribute_vector ( Mesh_attribute_name  name,
Uint32  dim = 1 
)
pure virtual

Creates a per-primitive mesh attribute.

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

See Also
attach_attribute_vector()
Parameters
nameThe name of the attribute, see Mesh_attribute_name. The attribute must be a per-primitive attribute.
dimDimension 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.
virtual IPolygon_connectivity* mi::neuraylib::IPolygon_mesh::create_connectivity ( Connectivity_map_type  map_type = CONNECTIVITY_MAP_GENERIC)
pure virtual

Creates a new connectivity for non-per-primitive attributes.

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

See Also
attach_connectivity()
virtual IAttribute_vector* mi::neuraylib::IPolygon_mesh::edit_attribute_vector ( Mesh_attribute_name  name)
pure virtual

Detaches and returns a per-primitive mesh attribute.

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

See Also
attach_attribute_vector()
Parameters
nameThe name of the attribute, see Mesh_attribute_name. The attribute must be a per-primitive attribute.
Returns
The requested attribute vector, or NULL in case of failure.
virtual IPolygon_connectivity* mi::neuraylib::IPolygon_mesh::edit_connectivity ( Mesh_attribute_name  name)
pure virtual

Detaches and returns the connectivity for a given mesh attribute.

The connectivity needs to be reattached before it is released.

See Also
attach_connectivity()
Parameters
nameThe name of the attribute to return the connectivity for, see Mesh_attribute_name.
Returns
The connectivity for name, or NULL if there is no such attribute, or the attribute is a per-primitive attribute.
virtual IPolygon_connectivity* mi::neuraylib::IPolygon_mesh::edit_mesh_connectivity ( )
pure virtual

Detaches and returns the mesh connectivity.

The connectivity needs to be reattached before it is released.

See Also
attach_mesh_connectivity()
Returns
The mesh connectivity, or NULL if it currently not attached.
virtual Bbox3_struct mi::neuraylib::IPolygon_mesh::get_bbox ( ) const
pure virtual

Returns the bounding box of the polygon mesh.

virtual Float32 mi::neuraylib::IPolygon_mesh::get_maximum_displacement ( ) const
pure virtual

Returns the maximum displacement of the polygon mesh.

See Also
set_maximum_displacement()
virtual Bbox3_struct mi::neuraylib::IPolygon_mesh::get_tight_bbox ( const Float64_4_4_struct transformation_matrix) const
pure virtual

Returns the bounding box of the polygon mesh after transformation.

Parameters
transformation_matrixThe world-to-object space transformation matrix that is applied to the object before the bounding box is computed.
virtual bool mi::neuraylib::IPolygon_mesh::has_attribute ( Mesh_attribute_name  name) const
pure virtual

Indicates whether the mesh has a particular mesh attribute (per-primitive or other types)

Parameters
nameThe name of the attribute to query, see Mesh_attribute_name.
Returns
true if the mesh has this attribute, false otherwise.
virtual Uint32 mi::neuraylib::IPolygon_mesh::indices_size ( ) const
pure virtual

Returns the total number of indices, i.e., the sum of the number of vertices of all polygons.

virtual bool mi::neuraylib::IPolygon_mesh::is_hole ( Polygon_handle_struct  p) const
pure virtual

Indicates whether the polygon p represents a hole.

virtual bool mi::neuraylib::IPolygon_mesh::is_polygon_size_constant ( ) const
pure virtual

Indicates whether all polygons have the same number of vertices.

virtual Sint32 mi::neuraylib::IPolygon_mesh::point ( Uint32  index,
Float32_3_struct p 
) const
pure virtual

Returns the coordinates of the point of index index in the output parameter p.

The mesh class provides several overloaded versions for different parameter types. No information about the underlying storage is specified. The caller should use the best matching call for the caller's data representation.

Returns
  • 0: Success.
  • -1: index is out of bounds.
virtual Sint32 mi::neuraylib::IPolygon_mesh::point ( Uint32  index,
Float64_3_struct p 
) const
pure virtual

Returns the coordinates of the point of index index in the output parameter p.

The mesh class provides several overloaded versions for different parameter types. No information about the underlying storage is specified. The caller should use the best matching call for the caller's data representation.

Returns
  • 0: Success.
  • -1: index is out of bounds.
virtual Uint32 mi::neuraylib::IPolygon_mesh::points_capacity ( ) const
pure virtual

Returns the number of points for which space is allocated in the mesh.

One can add points_capacity() - points_size() many points to the mesh before internal reallocation may become necessary.

See Also
reserve_points().
virtual Uint32 mi::neuraylib::IPolygon_mesh::points_size ( ) const
pure virtual

Returns the number of points in the mesh.

virtual Uint32 mi::neuraylib::IPolygon_mesh::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.
virtual Uint32 mi::neuraylib::IPolygon_mesh::polygons_size ( ) const
pure virtual

Returns the number of polygons.

virtual Sint32 mi::neuraylib::IPolygon_mesh::remove_attribute_vector ( Mesh_attribute_name  name)
pure virtual

Removes a per-primitive mesh attribute.

Parameters
nameThe name of the attribute, see Mesh_attribute_name. The attribute must be a per-primitive attribute.
Returns
  • 0: Success.
  • -1: There is no per-primitive attribute of the given name.
virtual Sint32 mi::neuraylib::IPolygon_mesh::remove_connectivity ( Mesh_attribute_name  name)
pure virtual

Removes the connectivity for a non-per-primitive mesh attribute.

If there are several mesh attributes attached to the same connectivity, only the given mesh attribute will be removed and the connectivity itself remains. Otherwise, removal of the connectivity implies removal of the corresponding mesh attribute.

Parameters
nameThe name of the attribute to remove the connectivity for, see Mesh_attribute_name.
Returns
  • 0: Success.
  • -1: There is no connectivity for the given mesh attribute.
virtual void mi::neuraylib::IPolygon_mesh::reserve_points ( Uint32  n)
pure virtual

Reserves space for at least n points.

Sets the internal capacity to at least n points before reallocation may become necessary. The number of points currently stored is not changed by this method.

See Also
points_capacity().
virtual void mi::neuraylib::IPolygon_mesh::set_maximum_displacement ( Float32  displacement)
pure virtual

Sets the maximum displacement of the polygon mesh.

This value is the maximum absolute value of any displacement applied to the object (defaults to 0.0). The bounding box of the object will be expanded all around by this value.

virtual Sint32 mi::neuraylib::IPolygon_mesh::set_point ( Uint32  index,
const Float32_3_struct p 
)
pure virtual

Sets the point of index index to the new point p.

The mesh class provides several overloaded versions for different parameter types. No information about the underlying storage is specified. The caller should use the best matching call for the caller's data representation.

Returns
  • 0: Success.
  • -1: index is out of bounds.
virtual Sint32 mi::neuraylib::IPolygon_mesh::set_point ( Uint32  index,
const Float64_3_struct p 
)
pure virtual

Sets the point of index index to the new point p.

The mesh class provides several overloaded versions for different parameter types. No information about the underlying storage is specified. The caller should use the best matching call for the caller's data representation.

Returns
  • 0: Success.
  • -1: index is out of bounds.