cMesh Class Reference
[Scenegraph]

cMesh represents a collection of vertices, triangles, materials, and texture properties that can be rendered graphically and haptically. More...

#include <CMesh.h>

Inheritance diagram for cMesh:

[legend]

List of all members.

Public Member Functions
	cMesh (cWorld *a_world)
	Constructor of cMesh.
virtual	~cMesh ()
	Destructor of cMesh.
cWorld *	getParentWorld () const
	Get parent world.
void	setParentWorld (cWorld *a_world)
	Set parent world.
virtual bool	loadFromFile (const string &a_fileName)
	Load a 3D object file (CHAI currently supports .obj and .3ds files).
unsigned int	newVertex (const double a_x, const double a_y, const double a_z)
	Create a new vertex and add it to the vertex list.
unsigned int	newVertex (const cVector3d &a_pos)
	Create a new vertex and add it to the vertex list.
void	addVertices (const cVector3d *a_vertexPositions, const unsigned int &a_numVertices)
	Add an array of vertices to the vertex list given an array of vertex positions.
bool	removeVertex (const unsigned int a_index)
	Remove the vertex at the specified position in my vertex array.
cVertex *	getVertex (unsigned int a_index, bool a_includeChildren=false)
	Access the vertex at the specified position in my vertex array (and maybe my childrens' arrays).
const cVertex *	getVertex (unsigned int a_index, bool a_includeChildren=false) const
	Access the vertex at the specified position in my vertex array (and maybe my childrens' arrays).
unsigned int	getNumVertices (bool a_includeChildren=false) const
	Read the number of stored vertices, optionally including those of my children.
virtual vector< cVertex > *	pVertices ()
	Access my vertex list directly (use carefully).
virtual const vector< cVertex > *	pVertices () const
	Access my vertex list directly (use carefully).
virtual vector< cVertex > *	pVerticesNonEmpty ()
	Access the first non-empty vertex list in any of my children (use carefully).
unsigned int	newTriangle (const unsigned int a_indexVertex0, const unsigned int a_indexVertex1, const unsigned int a_indexVertex2)
	Create a new triangle by passing vertex indices.
unsigned int	newTriangle (const cVector3d &a_vertex0, const cVector3d &a_vertex1, const cVector3d &a_vertex2)
	Create a new triangle and three new vertices by passing vertex positions.
bool	removeTriangle (const unsigned int a_index)
	Remove a triangle from my triangle array.
cTriangle *	getTriangle (unsigned int a_index, bool a_includeChildren=false)
	Access the triangle at the specified position in my triangle array.
unsigned int	getNumTriangles (bool a_includeChildren=false) const
	Read the number of stored triangles, optionally including those of my children.
void	clear ()
	Clear all triangles and vertices of mesh.
vector< cTriangle > *	pTriangles ()
	Access my triangle array directly (use carefully).
virtual void	setTransparencyLevel (const float a_level, const bool a_applyToTextures=false, const bool a_affectChildren=true)
	Set the alpha value at each vertex and in all of my material colors.
void	setVertexColor (const cColorf &a_color, const bool a_affectChildren=true)
	Set color of each vertex, optionally propagating the operation to my children.
void	useDisplayList (const bool a_useDisplayList, const bool a_affectChildren=true)
	Enable or disable the use of a display list for rendering, optionally propagating the operation to my children.
void	useVertexArrays (const bool a_useVertexArrays, const bool a_affectChildren=true)
	Enable or disable the use vertex arrays for rendering, optionally propagating the operation to my children.
bool	getDisplayListEnabled () const
	Ask whether I'm currently rendering with a display list.
void	invalidateDisplayList (const bool a_affectChildren=true)
	Invalidate any existing display lists.
void	setShowNormals (const bool &a_showNormals, const bool a_affectChildren=true, const bool a_trianglesOnly=false)
	Enable or disable the rendering of vertex normals, optionally propagating the operation to my children.
bool	getShowNormals () const
	Returns whether rendering of normals is enabled.
void	setNormalsProperties (const double a_length, const cColorf &a_color, const bool a_affectChildren)
	Set graphic properties for normal-rendering, optionally propagating the operation to my children.
bool	getColorsEnabled () const
	Are vertex colors currently enabled?
virtual void	onDisplayReset (const bool a_affectChildren=true)
	Re-initializes textures and display lists.
virtual void	createBruteForceCollisionDetector (bool a_affectChildren, bool a_useNeighbors)
	Set up a brute force collision detector for this mesh and (optionally) for its children.
virtual void	createAABBCollisionDetector (double a_radius, bool a_affectChildren, bool a_useNeighbors)
	Set up an AABB collision detector for this mesh and (optionally) its children.
virtual void	createSphereTreeCollisionDetector (double a_radius, bool a_affectChildren, bool a_useNeighbors)
	Set up a sphere tree collision detector for this mesh and (optionally) its children.
void	createTriangleNeighborList (bool a_affectChildren)
	Create a lists for neighbor triangles for each triangle of the mesh.
void	findNeighbors (std::vector< cTriangle * > *search1, std::vector< cTriangle * > *search2, const int &v1, const int &v2)
	Search for triangle neighbors.
void	computeAllNormals (const bool a_affectChildren=false)
	Compute all triangle normals, optionally propagating the operation to my children.
void	extrude (const double a_extrudeDistance, const bool a_affectChildren=false, const bool a_updateCollisionDetector=false)
	Extrude each vertex of the mesh by some amount along its normal.
virtual void	offsetVertices (const cVector3d &a_offset, const bool a_affectChildren=false, const bool a_updateCollisionDetector=true)
virtual void	scaleObject (const cVector3d &a_scaleFactors)
	Scale vertices and normals by the specified scale factors and re-normalize.
virtual cMesh *	createMesh () const
	Simple method used to create a new (empty) mesh of my type.
virtual void	renderMesh (const int a_renderMode=0)
	Render triangles, material and texture properties.
virtual cVector3d	getCenterOfMass (const bool a_includeChildren=0)
	Compute the center of mass of this mesh, based on vertex positions.
virtual void	reverseAllNormals (const bool a_affectChildren=0)
	Reverse all normals on this model.
virtual void	removeRedundantTriangles (const bool a_affectChildren=0)
	Remove redundant triangles from this model.
Protected Member Functions
virtual void	render (const int a_renderMode=0)
	Render the mesh itself.
virtual void	renderNormals (const bool a_trianglesOnly=true)
	Draw a small line for each vertex normal.
virtual void	updateGlobalPositions (const bool a_frameOnly)
	Update the global position of each of my vertices.
virtual void	updateBoundaryBox ()
	Update my boundary box dimensions based on my vertices.
Protected Attributes
cWorld *	m_parentWorld
	Parent world.
bool	m_showNormals
	If true, then normals are displayed.
bool	m_showNormalsForTriangleVerticesOnly
	If true, normals are displayed only for vertices that are used in triangles.
cColorf	m_showNormalsColor
	Color used to render lines representing normals.
double	m_showNormalsLength
	Length of each normal (for graphic rendering of normals).
bool	m_useDisplayList
	Should we use a display list to render this mesh?
bool	m_useVertexArrays
	Should we use vertex arrays to render this mesh?
int	m_displayList
	The openGL display list used to draw this mesh, if display lists are enabled.
vector< cVertex >	m_vertices
	Array of vertices.
list< unsigned int >	m_freeVertices
	List of free slots in the vertex array.
vector< cTriangle >	m_triangles
	Array of triangles.
list< unsigned int >	m_freeTriangles
	List of free slots in the triangle array.

---

Detailed Description

cMesh represents a collection of vertices, triangles, materials, and texture properties that can be rendered graphically and haptically.

---

Constructor & Destructor Documentation

cMesh::cMesh

(

cWorld *

a_world

)

Constructor of cMesh.

Constructor of cMesh

Parameters:

a_world

Pointer to parent world.

---

Member Function Documentation

void cMesh::addVertices	(	const cVector3d *	a_vertexPositions,
		const unsigned int &	a_numVertices
	)

Add an array of vertices to the vertex list given an array of vertex positions.

Create a new vertex for each supplied position and add it to the vertex list.

Parameters:

	a_vertexPositions	List of vertex positions to add
	a_numVertices	Number of vertices in a_vertexPositions

void cMesh::clear

(

)

Clear all triangles and vertices of mesh.

Clear all triangles and vertices.

void cMesh::computeAllNormals

(

const bool

a_affectChildren = false

)

Compute all triangle normals, optionally propagating the operation to my children.

Compute surface normals for every vertex in the mesh, by averaging the face normals of the triangle that include each vertex.

Parameters:

a_affectChildren

If true, then children are also updated.

void cMesh::createAABBCollisionDetector	(	double	a_radius,
		bool	a_affectChildren,
		bool	a_useNeighbors
	)			[virtual]

Set up an AABB collision detector for this mesh and (optionally) its children.

Set up an AABB collision detector for this mesh and (optionally) its children

Parameters:

	a_radius	Bounding radius.
	a_affectChildren	Create collision detectors for children?
	a_useNeighbors	Create neighbor lists?

void cMesh::createBruteForceCollisionDetector	(	bool	a_affectChildren,
		bool	a_useNeighbors
	)			[virtual]

Set up a brute force collision detector for this mesh and (optionally) for its children.

Set up a Brute Force collision detector for this mesh and (optionally) its children

Parameters:

	a_affectChildren	Create collision detectors for children?
	a_useNeighbors	Create neighbor lists?

void cMesh::createSphereTreeCollisionDetector	(	double	a_radius,
		bool	a_affectChildren,
		bool	a_useNeighbors
	)			[virtual]

Set up a sphere tree collision detector for this mesh and (optionally) its children.

Set up a sphere tree collision detector for this mesh and (optionally) its children

Parameters:

	a_radius	Bounding radius.
	a_affectChildren	Create collision detectors for children?
	a_useNeighbors	Create neighbor lists?

void cMesh::createTriangleNeighborList

(

bool

a_affectChildren

)

Create a lists for neighbor triangles for each triangle of the mesh.

Set up for each triangle a list of neighbor triangles

Parameters:

a_affectChildren

Create neighborlists for children?

void cMesh::extrude	(	const double	a_extrudeDistance,
		const bool	a_affectChildren = false,
		const bool	a_updateCollisionDetector = false
	)

Extrude each vertex of the mesh by some amount along its normal.

Extrude each vertex of the mesh by some amount along its normal

Parameters:

	a_extrudeDistance	Distance to move each vertex
	a_affectChildren	If true, children are also modified.
	a_updateCollisionDetector	If true, this mesh's collision detector is re-initialized

void cMesh::findNeighbors	(	std::vector< cTriangle * > *	search1,
		std::vector< cTriangle * > *	search2,
		const int &	v1,
		const int &	v2
	)

Search for triangle neighbors.

Find pairs of neighboring triangles that share specific vertices, given vectors of those triangles sorted by the x-coordinates of those vertices (first, second, or third), using a merge join. We define two triangles to be neighbors if and only if they have a common vertex (within some distance tolerance). In this function, we are only concerned about matching triangles whose vertex v1 in search1 is shared (within tolerance) with vertex v2 in search2; this function should be called once for each possible combination (order doesn't matter) of v1=0..2 and v2=0..2 to find all neighbors. Two shared vertices must have equal x-coordinates (within tolerance), which allows us to check for matches using a merge join on lists sorted by x-coordinate. (Using y-coordinates or z-coordinates would have been equally valid.)

Parameters:

	search1	First vector of triangles, sorted by x-coords of some vertex.
	search2	Second vector of triangles, sorted by x-coords of some vertex.
	v1	Which vertex the first vector is sorted by (0, 1, or 2).
	v2	Which vertex the second vector is sorted by (0, 1, or 2).

cVector3d cMesh::getCenterOfMass

(

const bool

a_includeChildren = 0

)

[virtual]

Compute the center of mass of this mesh, based on vertex positions.

Compute the center of mass of this mesh, based on vertex positions.

Parameters:

a_includeChildren

If true, then childrens' COM's are reflected.

unsigned int cMesh::getNumTriangles

(

bool

a_includeChildren = false

)

const

Read the number of stored triangles, optionally including those of my children.

Returns the number of triangles contained in this mesh, optionally including its children.

Parameters:

a_includeChildren

If true, then children are also included.

unsigned int cMesh::getNumVertices

(

bool

a_includeChildren = false

)

const

Read the number of stored vertices, optionally including those of my children.

Returns the number of vertices contained in this mesh, optionally including its children.

Parameters:

a_includeChildren

If true, then children are also included.

cTriangle * cMesh::getTriangle	(	unsigned int	a_index,
		bool	a_includeChildren = false
	)

Access the triangle at the specified position in my triangle array.

Returns the specified triangle... if a_includeChildren is false, I just index into my triangle array (no boundary checking, since this is called often).

If a_includeChildren is true, I start counting through my own triangle array, then each of my children... in the process, I'm going to call getNumTriangles(true) on each of my children, so this is a recursive and unbounded (though generally fast) version of this method.

Parameters:

	a_index	The index of the requested triangle
	a_includeChildren	If true, then children are also included.

cVertex * cMesh::getVertex	(	unsigned int	a_index,
		bool	a_includeChildren = false
	)

Access the vertex at the specified position in my vertex array (and maybe my childrens' arrays).

Returns the specified vertex... if a_includeChildren is false, I just index into my vertex array (no boundary checking, since this is called often).

If a_includeChildren is true, I start counting through my own vertex array, then each of my children... in the process, I'm going to call getNumVertices(true) on each of my children, so this is a recursive and unbounded (though generally fast) version of this method.

Parameters:

	a_index	The index of the requested vertex
	a_includeChildren	If true, then children are also included.

void cMesh::invalidateDisplayList

(

const bool

a_affectChildren = true

)

Invalidate any existing display lists.

Invalidate any existing display lists. You should call this on if you're using display lists and you modify mesh options, vertex positions, etc.

Parameters:

a_affectChildren

If true all children are updated

bool cMesh::loadFromFile

(

const string &

a_fileName

)

[virtual]

Load a 3D object file (CHAI currently supports .obj and .3ds files).

Load a 3D mesh file. CHAI currently supports .obj and .3ds files.

Parameters:

a_fileName

Filename of 3d image.

Returns:

Return true is file loaded correctly. Otherwise return FALSE.

unsigned int cMesh::newTriangle	(	const cVector3d &	a_vertex0,
		const cVector3d &	a_vertex1,
		const cVector3d &	a_vertex2
	)

Create a new triangle and three new vertices by passing vertex positions.

Create a new triangle and three new vertices by passing vertex positions

Parameters:

	a_vertex0	Position of vertex 0.
	a_vertex1	Position of vertex 1.
	a_vertex2	Position of vertex 2.

Returns:

Return index position of new triangle.

unsigned int cMesh::newTriangle	(	const unsigned int	a_indexVertex0,
		const unsigned int	a_indexVertex1,
		const unsigned int	a_indexVertex2
	)

Create a new triangle by passing vertex indices.

Create a new triangle and three new vertices by passing vertex indices

Parameters:

	a_indexVertex0	index position of vertex 0.
	a_indexVertex1	index position of vertex 1.
	a_indexVertex2	index position of vertex 2.

Returns:

Return the index of the new triangle in my triangle array

unsigned int cMesh::newVertex	(	const double	a_x,
		const double	a_y,
		const double	a_z
	)

Create a new vertex and add it to the vertex list.

Create a new vertex and add it to the vertex list.

Parameters:

	a_x	X coordinate of vertex.
	a_y	Y coordinate of vertex.
	a_z	Z coordinate of vertex.

Returns:

Return index position of new vertex.

void cMesh::offsetVertices	(	const cVector3d &	a_offset,
		const bool	a_affectChildren = false,
		const bool	a_updateCollisionDetector = true
	)			[virtual]

Shifts all vertex positions by the specified amount.
Use setPos() if you want to move the whole mesh for rendering.

Shifts all vertex positions by the specified amount.

Use setPos() if you want to move the whole mesh for rendering.

Parameters:

	a_offset	Translation to apply to each vertex
	a_affectChildren	If true, children are also modified.
	a_updateCollisionDetector	If true, this mesh's collision detector is re-initialized

void cMesh::onDisplayReset

(

const bool

a_affectChildren = true

)

[virtual]

Re-initializes textures and display lists.

Users can call this function when it's necessary to re-initialize the OpenGL context; e.g. re-initialize textures and display lists. Subclasses should perform whatever re-initialization they need to do.

Parameters:

a_affectChildren

If true all children are updated

Reimplemented from cGenericObject.

vector< cVertex > * cMesh::pVerticesNonEmpty

(

)

[virtual]

Access the first non-empty vertex list in any of my children (use carefully).

Access the first vertex list in any of my children (use carefully)

void cMesh::removeRedundantTriangles

(

const bool

a_affectChildren = 0

)

[virtual]

Remove redundant triangles from this model.

Remove redundant triangles from this model. Does not use vertex positions at all, just removed triangles with redundant indices and obviously- degenerate triangles.

Parameters:

a_affectChildren

If true, children are also modified.

bool cMesh::removeTriangle

(

const unsigned int

a_index

)

Remove a triangle from my triangle array.

Remove a vertex from the vertex array by passing its index number.

Parameters:

a_index

Index number of vertex.

Returns:

Return true if operation succeeded.

bool cMesh::removeVertex

(

const unsigned int

a_index

)

Remove the vertex at the specified position in my vertex array.

Remove the vertex at the specified position in my vertex array

Parameters:

a_index

Index number of vertex.

Returns:

Return true if operation succeeded.

void cMesh::render

(

const int

a_renderMode = 0

)

[protected, virtual]

Render the mesh itself.

Render this mesh in OpenGL. This method actually just prepares some OpenGL state, and uses renderMesh to actually do the rendering.

Parameters:

a_renderMode

Rendering mode (see cGenericObject)

Reimplemented from cGenericObject.

Reimplemented in cGELMesh.

void cMesh::renderMesh

(

const int

a_renderMode = 0

)

[virtual]

Render triangles, material and texture properties.

Render the mesh itself. This function is declared public to allow sharing of data among meshes, which is not possible given most implementations of 'protected'. But it should only be accessed from within render() or derived versions of render().

void cMesh::renderNormals

(

const bool

a_trianglesOnly = true

)

[protected, virtual]

Draw a small line for each vertex normal.

Render a graphic representation of each normal of the mesh.

void cMesh::reverseAllNormals

(

const bool

a_affectChildren = 0

)

[virtual]

Reverse all normals on this model.

Reverse the normal for every vertex on this model. Useful for models that started with inverted faces and thus gave inward-pointing normals.

Parameters:

a_affectChildren

If true, children are also modified.

void cMesh::scaleObject

(

const cVector3d &

a_scaleFactors

)

[virtual]

Scale vertices and normals by the specified scale factors and re-normalize.

Resize the current mesh by scaling all my vertex positions. If you want to move vertices along their normals, use the extrude() function.

Parameters:

a_scaleFactors

x,y,z scale factors.

Reimplemented from cGenericObject.

void cMesh::setNormalsProperties	(	const double	a_length,
		const cColorf &	a_color,
		const bool	a_affectChildren
	)

Set graphic properties for normal-rendering, optionally propagating the operation to my children.

Define the way normals are graphically rendered, optionally propagating the operation to my children

Parameters:

	a_length	Length of normals
	a_color	Color of normals
	a_affectChildren	If true, then children also modified.

void cMesh::setShowNormals	(	const bool &	a_showNormals,
		const bool	a_affectChildren = true,
		const bool	a_trianglesOnly = false
	)

Enable or disable the rendering of vertex normals, optionally propagating the operation to my children.

Enable or disable the graphic rendering of normal vectors at each vertex, optionally propagating the operation to my children

Parameters:

	a_showNormals	If true, normal vectors are rendered graphically
	a_affectChildren	If true, then children also modified
	a_trianglesOnly	If true, normals are rendered only at vertices that are used in triangles.

void cMesh::setTransparencyLevel	(	const float	a_level,
		const bool	a_applyToTextures = false,
		const bool	a_affectChildren = true
	)			[virtual]

Set the alpha value at each vertex and in all of my material colors.

Set the alpha value at each vertex, in all of my material colors, optionally propagating the operation to my children.

Using the 'apply to textures' option causes the actual texture alpha values to be over-written in my texture, if it exists.

[Editor's note: the 'apply to textures' option is not currently enabled, since (a) it's a silly way to control transparency and (b) not all textures have an alpha channel.]

Parameters:

	a_level	Level of transparency ranging from 0.0 to 1.0.
	a_applyToTextures	If true, then apply changes to texture
	a_affectChildren	If true, then children also modified.

Reimplemented from cGenericObject.

void cMesh::setVertexColor	(	const cColorf &	a_color,
		const bool	a_affectChildren = true
	)

Set color of each vertex, optionally propagating the operation to my children.

Set color of each vertex.

Parameters:

	a_color	New color to be applied to each vertex
	a_affectChildren	If true, then children also modified.

void cMesh::updateBoundaryBox

(

)

[protected, virtual]

Update my boundary box dimensions based on my vertices.

Compute the axis-aligned boundary box that encloses all triangles in this mesh

Reimplemented from cGenericObject.

void cMesh::updateGlobalPositions

(

const bool

a_frameOnly

)

[protected, virtual]

Update the global position of each of my vertices.

Compute the global position of all vertices

Parameters:

a_frameOnly

If false, the global position of all vertices is computed, otherwise this function does nothing.

Reimplemented from cGenericObject.

void cMesh::useDisplayList	(	const bool	a_useDisplayList,
		const bool	a_affectChildren = true
	)

Enable or disable the use of a display list for rendering, optionally propagating the operation to my children.

This enables the use of display lists for mesh rendering. This should significantly speed up rendering for large meshes, but it means that any changes you make to any cMesh options or any vertex positions will not take effect until you invalidate the existing display list (by calling invalidateDisplayList()).

In general, if you aren't having problems with rendering performance, don't bother with this; you don't want to worry about having to invalidate display lists every time you change a tiny option.

Parameters:

	a_useDisplayList	If true, this mesh will be rendered with a display list
	a_affectChildren	If true, then children also modified.

void cMesh::useVertexArrays	(	const bool	a_useVertexArrays,
		const bool	a_affectChildren = true
	)

Enable or disable the use vertex arrays for rendering, optionally propagating the operation to my children.

This enables the use of vertex arrays for mesh rendering. This mode can be faster than the classical approach, however crashes sometime occur on certain types of graphic cards.

In general, if you aren't having problems with rendering performance, don't bother with this.

Parameters:

	a_useVertexArrays	If true, this mesh will be rendered using vertex array technique
	a_affectChildren	If true, then children also modified.

---

The documentation for this class was generated from the following files:

• D:/CHAI3D/build-2-0-0/2.0.0/win32/src/scenegraph/CMesh.h
• D:/CHAI3D/build-2-0-0/2.0.0/win32/src/scenegraph/CMesh.cpp