# 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

CHAI3D 2.0.0 documentation
Please address any questions to support@chai3d.org
(C) 2003-2009 - CHAI 3D
All Rights Reserved.