CollisionManifold Class Reference

A collection of collision points, usually between two rigid objects. More...

#include <rimCollisionManifold.h>

List of all members.

Public Member Functions

 CollisionManifold ()
 Create a new empty collision manifold with the default collision point array size.
 CollisionManifold (int newCollisionPointArraySize)
 Create a new empty collision manifold with the specified collision point array size.
 CollisionManifold (const CollisionManifold &manifold)
 Create a new collision manifold from another, copying its contents.
 ~CollisionManifold ()
 Destroy a collision manifold, deallocating all previously-allocated collision points.
CollisionManifoldoperator= (const CollisionManifold &manifold)
 Assign the contents of one collision manifold to another.
void addPoint (const CollisionPoint &point)
 Add a new collision point object to this manifold.
void addPoint (const CollisionPair &pair, const Vector3 &point1, const Vector3 &point2, const Vector3 &normal, Real distance)
 Create a new collision point and add it to this manifold.
CollisionPointgetPoint (int index)
 Get the collision point at the specified index of the collision manifold.
const CollisionPointgetPoint (int index) const
 Get the collision point at the specified index of the collision manifold.
int getNumberOfPoints () const
 Get the number of collision points that this manifold contains.
void clearPoints ()
 Clear all collision points that this collision manifold contains.

Private Attributes

CollisionPointcollisionPoints
 The array of collision points that this manifold contains.
int numCollisionPoints
 An integer representing the number of actual collision points in the manifold.
int collisionPointArraySize
 The size of the internal collision point array.

Static Private Attributes

static const int DEFAULT_COLLISION_POINT_ARRAY_SIZE = 4
 A static member indicating the default capacity of a collision manifold's point array.


Detailed Description

A collection of collision points, usually between two rigid objects.

This class is used to contain all of the collision points which are between two rigid objects. It essentially wraps a dynamic array of collision points and allows users to add collision points, clear all collision points in the manifold, as well as get the collision point at a certain index in that array. Basically, this class is a glorified simple array for collision points. For performance reasons, the collision points in the manifold are allocated contiguously in order to increase the cache-coherency of the class. This is done at the expense of a few more copy operations, but it is nothing compared to the performance hit of dynamically allocating each collision point.


Constructor & Destructor Documentation

CollisionManifold::CollisionManifold (  )  [inline]

Create a new empty collision manifold with the default collision point array size.

This constructor creates a default empty collision manifold with space for DEFAULT_COLLISION_POINT_ARRAY_SIZE collision points. This class constant indicates the default capacity of the collision point array. Its definition should be checked for its most current value. The points are allocated contiguously to increase cache-coherency at the expense of more copy operations.

CollisionManifold::CollisionManifold ( int  newCollisionPointArraySize  )  [inline]

Create a new empty collision manifold with the specified collision point array size.

This constructor creates a default empty collision manifold with space for the specified number of collision points. This value is clamped to the range of [0,infinity) such that the collision point array size cannot be negative. The points are allocated contiguously to increase cache-coherency at the expense of more copy operations.

Parameters:
newCollisionPointArraySize - the desired capacity for the collision manifold.

CollisionManifold::CollisionManifold ( const CollisionManifold manifold  )  [inline]

Create a new collision manifold from another, copying its contents.

This copy constructor creates a new collision manifold from an existing one by copying the collision points that the other manifold contains.

Parameters:
manifold - the collision manifold to be copied.

CollisionManifold::~CollisionManifold (  )  [inline]

Destroy a collision manifold, deallocating all previously-allocated collision points.


Member Function Documentation

CollisionManifold& CollisionManifold::operator= ( const CollisionManifold manifold  )  [inline]

Assign the contents of one collision manifold to another.

void CollisionManifold::addPoint ( const CollisionPoint point  )  [inline]

Add a new collision point object to this manifold.

This method adds a previously allocated collision point object to the collision manifold array by copying its contents to one of the pre-existing elements in the array. If there is not enough space in the object's collision point array, then the capacity of the array is doubled and the new collision point is added as normal. A call to this method results in an increase of 1 to the number of collision points contained in the collision manifold.

Parameters:
point - the new collision point object to add to the manifold.

void CollisionManifold::addPoint ( const CollisionPair pair,
const Vector3 point1,
const Vector3 point2,
const Vector3 normal,
Real  distance 
) [inline]

Create a new collision point and add it to this manifold.

This method creates a new collision point object and adds it to the internal collision point array by copying its contents to one of the pre-existing elements in the array. If there is not enough space in the manifold's collision point array, then the capacity of the array is doubled and the new collision point is added as normal. A call to this method results in an increase of 1 to the number of collision points contained in the collision manifold.

Parameters:
shape1 - the first colliding shape that the new collision point corresponds to.
shape2 - the second colliding shape that the new collision point corresponds to.
point1 - the colliding point on the surface of the first shape.
point2 - the colliding point on the surface of the second shape.
normal - the surface normal at the point of collision.
distance - the distance between the two colliding shapes (usually negative).

CollisionPoint& CollisionManifold::getPoint ( int  index  )  [inline]

Get the collision point at the specified index of the collision manifold.

Bounds-checking is not performed in this method, so it is possible to access out-of-bounds indices. Indices are of the standard form index = {0, 1, .., N-1} where N is the number of collision points in the manifold. Accessing out-out-bounds indices should be avoided at all costs as it can cause memory problems. The decision to avoid bounds-checking was done in order to allow collision points to be accessed as efficiently as possible. This may change in future versions once it can be better ascertained if the additional overhead would be noticeable. This const version of the indexed point accessor method allows modification of the specified collision point.

Parameters:
index - the index of the collision point to retrieve.
Returns:
the collision point at the specified index.

const CollisionPoint& CollisionManifold::getPoint ( int  index  )  const [inline]

Get the collision point at the specified index of the collision manifold.

Bounds-checking is not performed in this method, so it is possible to access out-of-bounds indices. Indices are of the standard form index = {0, 1, .., N-1} where N is the number of collision points in the manifold. Accessing out-out-bounds indices should be avoided at all costs as it can cause memory problems. The decision to avoid bounds-checking was done in order to allow collision points to be accessed as efficiently as possible. This may change in future versions once it can be better ascertained if the additional overhead would be noticeable. This const version of the indexed point accessor method disallows modification of the specified collision point.

Parameters:
index - the index of the collision point to retrieve.
Returns:
the collision point at the specified index.

int CollisionManifold::getNumberOfPoints (  )  const [inline]

Get the number of collision points that this manifold contains.

void CollisionManifold::clearPoints (  )  [inline]

Clear all collision points that this collision manifold contains.

This method is very efficient because all that it does is just set the number of collision points to zero, leaving the previously allocated collision points unaffected. Therefore, the capacity of the collision point array is preserved as well.


Member Data Documentation

CollisionPoint* CollisionManifold::collisionPoints [private]

The array of collision points that this manifold contains.

It has the number of elements specified by the collisionPointArraySize data member.

int CollisionManifold::numCollisionPoints [private]

An integer representing the number of actual collision points in the manifold.

This value does not include all collision points that have been allocated in the collision point array. It only indicates the number of collision points that the user has added to the manifold. This value cannot be less than zero.

int CollisionManifold::collisionPointArraySize [private]

The size of the internal collision point array.

This value indicates the capacity of the collision point array. It is always positive.

const int CollisionManifold::DEFAULT_COLLISION_POINT_ARRAY_SIZE = 4 [static, private]

A static member indicating the default capacity of a collision manifold's point array.

A value of 4 was choosen, because very few collision shapes will ever have more than 4 collision points at any one time. If there is a need for more points, then the collision point array is resized to double its original value.


The documentation for this class was generated from the following file:
Generated on Tue Aug 26 00:03:18 2008 for Rim Physics by  doxygen 1.5.4