Added more Doxygen comments for classes in src/BulletCollision/CollisionShapes

src/BulletCollision/CollisionShapes/btBoxShape.h

@@ -22,7 +22,7 @@ subject to the following restrictions:
 #include "LinearMath/btPoint3.h"
 #include "LinearMath/btMinMax.h"
 
-///btBoxShape implements both a feature based (vertex/edge/plane) and implicit (getSupportingVertex) Box
+///The btBoxShape is a box primitive around the origin, its sides axis aligned with length specified by half extents, in local shape coordinates. When used as part of a btCollisionObject or btRigidBody it will be an oriented box in world space.
 class btBoxShape: public btPolyhedralConvexShape
 {
 

src/BulletCollision/CollisionShapes/btBvhTriangleMeshShape.h

@@ -21,8 +21,10 @@ subject to the following restrictions:
 #include "LinearMath/btAlignedAllocator.h"
 
 
-///Bvh Concave triangle mesh is a static-triangle mesh shape with Bounding Volume Hierarchy optimization.
-///Uses an interface to access the triangles to allow for sharing graphics/physics triangles.
+///The btBvhTriangleMeshShape is a static-triangle mesh shape with several optimizations, such as bounding volume hierarchy and cache friendly traversal for PlayStation 3 Cell SPU. It is recommended to enable useQuantizedAabbCompression for better memory usage.
+///It takes a triangle mesh as input, for example a btTriangleMesh or btTriangleIndexVertexArray. The btBvhTriangleMeshShape class allows for triangle mesh deformations by a refit or partialRefit method.
+///Instead of building the bounding volume hierarchy acceleration structure, it is also possible to serialize (save) and deserialize (load) the structure from disk.
+///See Demos\ConcaveDemo\ConcavePhysicsDemo.cpp for an example.
 ATTRIBUTE_ALIGNED16(class) btBvhTriangleMeshShape : public btTriangleMeshShape
 {
 

src/BulletCollision/CollisionShapes/btCapsuleShape.h

@@ -20,9 +20,9 @@ subject to the following restrictions:
 #include "BulletCollision/BroadphaseCollision/btBroadphaseProxy.h" // for the types
 
 
-///btCapsuleShape represents a capsule around the Y axis
-///A more general solution that can represent capsules is the btMultiSphereShape
-///the total height is height+2*radius, so the height is just the height between the center of each 'sphere' of the capsule caps.
+///The btCapsuleShape represents a capsule around the Y axis, there is also the btCapsuleShapeX aligned around the X axis and btCapsuleShapeZ around the Z axis.
+///The total height is height+2*radius, so the height is just the height between the center of each 'sphere' of the capsule caps.
+///The btCapsuleShape is a convex hull of two spheres. The btMultiSphereShape is a more general collision shape that takes the convex hull of multiple sphere, so it can also represent a capsule when just using two spheres.
 class btCapsuleShape : public btConvexInternalShape
 {
 protected:

src/BulletCollision/CollisionShapes/btCollisionShape.h

@@ -22,7 +22,7 @@ subject to the following restrictions:
 #include "LinearMath/btPoint3.h"
 #include "BulletCollision/BroadphaseCollision/btBroadphaseProxy.h" //for the shape types
 
-///btCollisionShape provides interface for collision shapes that can be shared among btCollisionObjects.
+///The btCollisionShape class provides an interface for collision shapes that can be shared among btCollisionObjects.
 class btCollisionShape
 {
 

src/BulletCollision/CollisionShapes/btCompoundShape.h

@@ -46,7 +46,7 @@ SIMD_FORCE_INLINE bool operator==(const btCompoundShapeChild& c1, const btCompou
 }
 
 /// btCompoundShape allows to store multiple other btCollisionShapes
-/// This allows for concave collision objects. This is more general then the Static Concave btTriangleMeshShape.
+/// This allows for moving concave collision objects. This is more general then the static concave btBvhTriangleMeshShape.
 ATTRIBUTE_ALIGNED16(class) btCompoundShape	: public btCollisionShape
 {
 	//btAlignedObjectArray<btTransform>		m_childTransforms;

src/BulletCollision/CollisionShapes/btConcaveShape.h

@@ -21,8 +21,8 @@ subject to the following restrictions:
 #include "btTriangleCallback.h"
 
 
-///Concave shape proves an interface concave shapes that can produce triangles that overlapping a given AABB.
-///Static triangle mesh, infinite plane, height field/landscapes are example that implement this interface.
+///The btConcaveShape class provides an interface for non-moving (static) concave shapes.
+///It has been implemented by the btStaticPlaneShape, btBvhTriangleMeshShape and btHeightfieldTerrainShape.
 class btConcaveShape : public btCollisionShape
 {
 protected:

src/BulletCollision/CollisionShapes/btConeShape.h

@@ -19,7 +19,7 @@ subject to the following restrictions:
 #include "btConvexInternalShape.h"
 #include "BulletCollision/BroadphaseCollision/btBroadphaseProxy.h" // for the types
 
-///btConeShape implements a Cone shape, around the Y axis
+///The btConeShape implements a cone shape primitive, centered around the origin and aligned with the Y axis. The btConeShapeX is aligned around the X axis and btConeShapeZ around the Z axis.
 class btConeShape : public btConvexInternalShape
 
 {

src/BulletCollision/CollisionShapes/btConvexHullShape.h

@@ -20,10 +20,8 @@ subject to the following restrictions:
 #include "BulletCollision/BroadphaseCollision/btBroadphaseProxy.h" // for the types
 #include "LinearMath/btAlignedObjectArray.h"
 
-///ConvexHullShape implements an implicit (getSupportingVertex) Convex Hull of a Point Cloud (vertices)
-///No connectivity is needed. localGetSupportingVertex iterates linearly though all vertices.
-///on modern hardware, due to cache coherency this isn't that bad. Complex algorithms tend to trash the cash.
-///(memory is much slower then the cpu)
+///The btConvexHullShape implements an implicit convex hull of an array of vertices.
+///Bullet provides a general and fast collision detector for convex shapes based on GJK and EPA using localGetSupportingVertex.
 ATTRIBUTE_ALIGNED16(class) btConvexHullShape : public btPolyhedralConvexShape
 {
 	btAlignedObjectArray<btPoint3>	m_points;

src/BulletCollision/CollisionShapes/btConvexInternalShape.h

@@ -4,7 +4,7 @@
 
 #include "btConvexShape.h"
 
-///btConvexInternalShape carries some additional data, shared by most implementations
+///The btConvexInternalShape is an internal base class, shared by most convex shape implementations.
 class btConvexInternalShape : public btConvexShape
 {
 

src/BulletCollision/CollisionShapes/btConvexShape.h

@@ -28,9 +28,8 @@ subject to the following restrictions:
 struct btConvexCastResult;
 #define MAX_PREFERRED_PENETRATION_DIRECTIONS 10
 
-/// btConvexShape is an abstract shape interface.
-/// It describes general convex shapes using the localGetSupportingVertex interface
-/// used in combination with GJK or btConvexCast
+/// The btConvexShape is an abstract shape interface, implemented by all convex shapes such as btBoxShape, btConvexHullShape etc.
+/// It describes general convex shapes using the localGetSupportingVertex interface, used by collision detectors such as btGjkPairDetector.
 ATTRIBUTE_ALIGNED16(class) btConvexShape : public btCollisionShape
 {
 

src/BulletCollision/CollisionShapes/btConvexTriangleMeshShape.h

@@ -6,8 +6,8 @@
 #include "BulletCollision/BroadphaseCollision/btBroadphaseProxy.h" // for the types
 
 
-/// btConvexTriangleMeshShape is a convex hull of a triangle mesh. If you just have a point cloud, you can use btConvexHullShape instead.
-/// It uses the btStridingMeshInterface instead of a point cloud. This can avoid the duplication of the triangle mesh data.
+/// The btConvexTriangleMeshShape is a convex hull of a triangle mesh, but the performance is not as good as btConvexHullShape.
+/// A small benefit of this class is that it uses the btStridingMeshInterface, so you can avoid the duplication of the triangle mesh data. Nevertheless, most users should use the much better performing btConvexHullShape instead.
 class btConvexTriangleMeshShape : public btPolyhedralConvexShape
 {
 

src/BulletCollision/CollisionShapes/btCylinderShape.h

@@ -20,7 +20,7 @@ subject to the following restrictions:
 #include "BulletCollision/BroadphaseCollision/btBroadphaseProxy.h" // for the types
 #include "LinearMath/btVector3.h"
 
-/// implements cylinder shape interface
+/// The btCylinderShape class implements a cylinder shape primitive, centered around the origin. Its central axis aligned with the Y axis. btCylinderShapeX is aligned with the X axis and btCylinderShapeZ around the Z axis.
 class btCylinderShape : public btBoxShape
 
 {

src/BulletCollision/CollisionShapes/btEmptyShape.h

@@ -26,8 +26,8 @@ subject to the following restrictions:
 
 
 
-/// btEmptyShape is a collision shape without actual collision detection. 
-///It can be replaced by another shape during runtime
+/// The btEmptyShape is a collision shape without actual collision detection shape, so most users should ignore this class.
+/// It can be replaced by another shape during runtime, but the inertia tensor should be recomputed.
 class btEmptyShape	: public btConcaveShape
 {
 public:

src/BulletCollision/CollisionShapes/btHeightfieldTerrainShape.h

@@ -18,7 +18,8 @@ subject to the following restrictions:
 
 #include "btConcaveShape.h"
 
-///btHeightfieldTerrainShape simulates a 2D heightfield terrain 
+///The btHeightfieldTerrainShape simulates a 2D heightfield terrain collision shape. You can also use the more general btBvhTriangleMeshShape instead.
+///An example implementation of btHeightfieldTerrainShape is provided in Demos/VehicleDemo/VehicleDemo.cpp
 class btHeightfieldTerrainShape : public btConcaveShape
 {
 protected:

src/BulletCollision/CollisionShapes/btMinkowskiSumShape.h

@@ -19,7 +19,7 @@ subject to the following restrictions:
 #include "btConvexInternalShape.h"
 #include "BulletCollision/BroadphaseCollision/btBroadphaseProxy.h" // for the types
 
-/// btMinkowskiSumShape represents implicit (getSupportingVertex) based minkowski sum of two convex implicit shapes.
+/// The btMinkowskiSumShape is only for advanced users. This shape represents implicit based minkowski sum of two convex implicit shapes.
 class btMinkowskiSumShape : public btConvexInternalShape
 {
 

src/BulletCollision/CollisionShapes/btMultiSphereShape.h

@@ -21,7 +21,8 @@ subject to the following restrictions:
 
 #define MAX_NUM_SPHERES 5
 
-///btMultiSphereShape represents implicit convex hull of a collection of spheres (using getSupportingVertex)
+///The btMultiSphereShape represents the convex hull of a collection of spheres. You can create special capsules or other smooth volumes.
+///It is possible to animate the spheres for deformation.
 class btMultiSphereShape : public btConvexInternalShape
 
 {

src/BulletCollision/CollisionShapes/btMultimaterialTriangleMeshShape.h

@@ -21,8 +21,7 @@ subject to the following restrictions:
 #include "btBvhTriangleMeshShape.h"
 #include "btMaterial.h"
 
-///BvhTriangleMaterialMeshShape extends BvhTriangleMeshShape.
-///Its main contribution is the interface into a material array.
+///The BvhTriangleMaterialMeshShape extends the btBvhTriangleMeshShape. Its main contribution is the interface into a material array, which allows per-triangle friction and restitution.
 ATTRIBUTE_ALIGNED16(class) btMultimaterialTriangleMeshShape : public btBvhTriangleMeshShape
 {
     btAlignedObjectArray <btMaterial*> m_materialList;

src/BulletCollision/CollisionShapes/btOptimizedBvh.h

@@ -21,7 +21,7 @@ subject to the following restrictions:
 class btStridingMeshInterface;
 
 
-///OptimizedBvh extends the btQuantizedBvh to create AABB tree for triangle meshes, through the btStridingMeshInterface.
+///The btOptimizedBvh extends the btQuantizedBvh to create AABB tree for triangle meshes, through the btStridingMeshInterface.
 ATTRIBUTE_ALIGNED16(class) btOptimizedBvh : public btQuantizedBvh
 {
 	

src/BulletCollision/CollisionShapes/btPolyhedralConvexShape.h

@@ -21,7 +21,7 @@ subject to the following restrictions:
 #include "btConvexInternalShape.h"
 
 
-///PolyhedralConvexShape is an interface class for feature based (vertex/edge/face) convex shapes.
+///The btPolyhedralConvexShape is an internal interface class for polyhedral convex shapes.
 class btPolyhedralConvexShape : public btConvexInternalShape
 {
 

src/BulletCollision/CollisionShapes/btShapeHull.h

@@ -22,7 +22,9 @@ subject to the following restrictions:
 #include "BulletCollision/CollisionShapes/btConvexShape.h"
 
 
-///btShapeHull takes a btConvexShape, builds the convex hull using btConvexHull and provides triangle indices and vertices.
+///The btShapeHull class takes a btConvexShape, builds a simplified convex hull using btConvexHull and provides triangle indices and vertices.
+///It can be useful for to simplify a complex convex object and for visualization of a non-polyhedral convex object.
+///It approximates the convex hull using the supporting vertex of 42 directions.
 class btShapeHull
 {
 public:

src/BulletCollision/CollisionShapes/btSphereShape.h

@@ -19,7 +19,7 @@ subject to the following restrictions:
 #include "btConvexInternalShape.h"
 #include "BulletCollision/BroadphaseCollision/btBroadphaseProxy.h" // for the types
 
-///btSphereShape implements an implicit (getSupportingVertex) Sphere
+///The btSphereShape implements an implicit sphere, centered around a local origin with radius.
 ATTRIBUTE_ALIGNED16(class) btSphereShape : public btConvexInternalShape
 
 {

src/BulletCollision/CollisionShapes/btStaticPlaneShape.h

@@ -19,8 +19,7 @@ subject to the following restrictions:
 #include "btConcaveShape.h"
 
 
-///StaticPlaneShape simulates an 'infinite' plane by dynamically reporting triangles approximated by intersection of the plane with the AABB.
-///Assumed is that the other objects is not also infinite, so a reasonable sized AABB.
+///The btStaticPlaneShape simulates an infinite non-moving (static) collision plane.
 class btStaticPlaneShape : public btConcaveShape
 {
 protected:

src/BulletCollision/CollisionShapes/btStridingMeshInterface.h

@@ -29,7 +29,8 @@ typedef enum PHY_ScalarType {
 	PHY_FIXEDPOINT88
 } PHY_ScalarType;
 
-///	btStridingMeshInterface is the interface class for high performance access to triangle meshes
+///	The btStridingMeshInterface is the interface class for high performance generic access to triangle meshes, used in combination with btBvhTriangleMeshShape and some other collision shapes.
+/// Using index striding of 3*sizeof(integer) it can use triangle arrays, using index striding of 1*sizeof(integer) it can handle triangle strips.
 /// It allows for sharing graphics and collision meshes. Also it provides locking/unlocking of graphics meshes that are in gpu memory.
 class  btStridingMeshInterface
 {

src/BulletCollision/CollisionShapes/btTetrahedronShape.h

@@ -21,7 +21,7 @@ subject to the following restrictions:
 #include "BulletCollision/BroadphaseCollision/btBroadphaseProxy.h"
 
 
-///BU_Simplex1to4 implements feature based and implicit simplex of up to 4 vertices (tetrahedron, triangle, line, vertex).
+///The btBU_Simplex1to4 implements tetrahedron, triangle, line, vertex collision shapes. In most cases it is better to use btConvexHullShape instead.
 class btBU_Simplex1to4 : public btPolyhedralConvexShape
 {
 protected:

src/BulletCollision/CollisionShapes/btTriangleBuffer.cpp

@@ -16,14 +16,7 @@ subject to the following restrictions:
 #include "btTriangleBuffer.h"
 
 
-///example usage of this class:
-//			btTriangleBuffer	triBuf;
-//			concaveShape->processAllTriangles(&triBuf,aabbMin, aabbMax);
-//			for (int i=0;i<triBuf.getNumTriangles();i++)
-//			{
-//				const btTriangle& tri = triBuf.getTriangle(i);
-//				//do something useful here with the triangle
-//			}
+
 
 
 

src/BulletCollision/CollisionShapes/btTriangleBuffer.h

@@ -29,6 +29,14 @@ struct	btTriangle
 };
 
 ///btTriangleBuffer can be useful to collect and store overlapping triangles between AABB and concave objects that support 'processAllTriangles'
+///Example usage of this class:
+///			btTriangleBuffer	triBuf;
+///			concaveShape->processAllTriangles(&triBuf,aabbMin, aabbMax);
+///			for (int i=0;i<triBuf.getNumTriangles();i++)
+///			{
+///				const btTriangle& tri = triBuf.getTriangle(i);
+///				//do something useful here with the triangle
+///			}
 class btTriangleBuffer : public btTriangleCallback
 {
 

src/BulletCollision/CollisionShapes/btTriangleCallback.h

@@ -19,6 +19,8 @@ subject to the following restrictions:
 #include "LinearMath/btVector3.h"
 
 
+///The btTriangleCallback provides a callback for each overlapping triangle when calling processAllTriangles.
+///This callback is called by processAllTriangles for all btConcaveShape derived class, such as  btBvhTriangleMeshShape, btStaticPlaneShape and btHeightfieldTerrainShape.
 class btTriangleCallback
 {
 public:

src/BulletCollision/CollisionShapes/btTriangleIndexVertexArray.h

@@ -21,9 +21,8 @@ subject to the following restrictions:
 #include "LinearMath/btScalar.h"
 
 
-///IndexedMesh indexes into existing vertex and index arrays, in a similar way OpenGL glDrawElements
-///instead of the number of indices, we pass the number of triangles
-///todo: explain with pictures
+///The btIndexedMesh indexes a single vertex and index array. Multiple btIndexedMesh objects can be passed into a btTriangleIndexVertexArray using addIndexedMesh.
+///Instead of the number of indices, we pass the number of triangles.
 ATTRIBUTE_ALIGNED16( struct)	btIndexedMesh
 {
 	BT_DECLARE_ALIGNED_ALLOCATOR();
@@ -44,7 +43,7 @@ ATTRIBUTE_ALIGNED16( struct)	btIndexedMesh
 
 typedef btAlignedObjectArray<btIndexedMesh>	IndexedMeshArray;
 
-///TriangleIndexVertexArray allows to use multiple meshes, by indexing into existing triangle/index arrays.
+///The btTriangleIndexVertexArray allows to access multiple triangle meshes, by indexing into existing triangle/index arrays.
 ///Additional meshes can be added using addIndexedMesh
 ///No duplcate is made of the vertex/index data, it only indexes into external vertex/index arrays.
 ///So keep those arrays around during the lifetime of this btTriangleIndexVertexArray.

src/BulletCollision/CollisionShapes/btTriangleIndexVertexMaterialArray.h

@@ -41,7 +41,7 @@ ATTRIBUTE_ALIGNED16( struct)	btMaterialProperties
 
 typedef btAlignedObjectArray<btMaterialProperties>	MaterialArray;
 
-///TriangleIndexVertexMaterialArray is built on TriangleIndexVertexArray
+///Teh btTriangleIndexVertexMaterialArray is built on TriangleIndexVertexArray
 ///The addition of a material array allows for the utilization of the partID and
 ///triangleIndex that are returned in the ContactAddedCallback.  As with
 ///TriangleIndexVertexArray, no duplicate is made of the material data, so it

src/BulletCollision/CollisionShapes/btTriangleMesh.h

@@ -21,10 +21,10 @@ subject to the following restrictions:
 #include "LinearMath/btVector3.h"
 #include "LinearMath/btAlignedObjectArray.h"
 
-///btTriangleMesh provides storage for a concave triangle mesh. It can be used as data for the btTriangleMeshShape.
+///The btTriangleMesh class is a convenience class derived from btTriangleIndexVertexArray, that provides storage for a concave triangle mesh. It can be used as data for the btBvhTriangleMeshShape.
 ///It allows either 32bit or 16bit indices, and 4 (x-y-z-w) or 3 (x-y-z) component vertices.
-///btTriangleMesh will duplicate/keep all mesh data. 
-///If you prefer, you can avoid using btTriangleMesh and directly use btTriangleIndexVertexArray or derive your own class from btStridingMeshInterface. This allows to share render and collision meshes.
+///If you want to share triangle/index data between graphics mesh and collision mesh (btBvhTriangleMeshShape), you can directly use btTriangleIndexVertexArray or derive your own class from btStridingMeshInterface.
+///Performance of btTriangleMesh and btTriangleIndexVertexArray used in a btBvhTriangleMeshShape is the same.
 class btTriangleMesh : public btTriangleIndexVertexArray
 {
 	btAlignedObjectArray<btVector3>	m_4componentVertices;

src/BulletCollision/CollisionShapes/btTriangleMeshShape.h

@@ -20,7 +20,7 @@ subject to the following restrictions:
 #include "btStridingMeshInterface.h"
 
 
-///Concave triangle mesh interface. Don't use this class directly, use btBvhTriangleMeshShape instead.
+///The btTriangleMeshShape is an internal concave triangle mesh interface. Don't use this class directly, use btBvhTriangleMeshShape instead.
 class btTriangleMeshShape : public btConcaveShape
 {
 protected:

src/BulletCollision/CollisionShapes/btUniformScalingShape.h

@@ -19,6 +19,8 @@ subject to the following restrictions:
 #include "btConvexShape.h"
 #include "BulletCollision/BroadphaseCollision/btBroadphaseProxy.h" // for the types
 
+///The btUniformScalingShape allows to re-use uniform scaled instances of btConvexShape in a memory efficient way.
+///Istead of using btUniformScalingShape, it is better to use the non-uniform setLocalScaling method on convex shapes that implement it.
 class btUniformScalingShape : public btConvexShape
 {
 	btConvexShape*	m_childConvexShape;