Choose a default 'safe' collision margin for very small convex collision shapes, in particular btBoxShape and btCylinderShape

and add some documentation in btConvexInternalShape.h
Thanks to Simon Lundmark for the suggestion

Fixes http://code.google.com/p/bullet/issues/detail?id=349

src/BulletCollision/CollisionShapes/btBox2dShape.h

@@ -83,6 +83,7 @@ public:
 	}
 
 
+	///a btBox2dShape is a flat 2D box in the X-Y plane (Z extents are zero)
 	btBox2dShape( const btVector3& boxHalfExtents) 
 		: btPolyhedralConvexShape(),
 		m_centroid(0,0,0)
@@ -97,6 +98,11 @@ public:
 		m_normals[2].setValue(0,1,0);
 		m_normals[3].setValue(-1,0,0);
 
+		btScalar minDimension = boxHalfExtents.getX();
+		if (minDimension>boxHalfExtents.getY())
+			minDimension = boxHalfExtents.getY();
+		setSafeMargin(minDimension);
+
 		m_shapeType = BOX_2D_SHAPE_PROXYTYPE;
 		btVector3 margin(getMargin(),getMargin(),getMargin());
 		m_implicitShapeDimensions = (boxHalfExtents * m_localScaling) - margin;

src/BulletCollision/CollisionShapes/btBoxShape.cpp

@@ -14,8 +14,18 @@ subject to the following restrictions:
 */
 #include "btBoxShape.h"
 
+btBoxShape::btBoxShape( const btVector3& boxHalfExtents) 
+: btPolyhedralConvexShape()
+{
+	m_shapeType = BOX_SHAPE_PROXYTYPE;
+
+	setSafeMargin(boxHalfExtents);
+
+	btVector3 margin(getMargin(),getMargin(),getMargin());
+	m_implicitShapeDimensions = (boxHalfExtents * m_localScaling) - margin;
+};
+
 
-//{ 
 
 
 void btBoxShape::getAabb(const btTransform& t,btVector3& aabbMin,btVector3& aabbMax) const

src/BulletCollision/CollisionShapes/btBoxShape.h

@@ -80,13 +80,7 @@ public:
 	}
 
 
-	btBoxShape( const btVector3& boxHalfExtents) 
-		: btPolyhedralConvexShape()
-	{
-		m_shapeType = BOX_SHAPE_PROXYTYPE;
-		btVector3 margin(getMargin(),getMargin(),getMargin());
-		m_implicitShapeDimensions = (boxHalfExtents * m_localScaling) - margin;
-	};
+	btBoxShape( const btVector3& boxHalfExtents);
 
 	virtual void setMargin(btScalar collisionMargin)
 	{

src/BulletCollision/CollisionShapes/btCollisionMargin.h

@@ -16,8 +16,9 @@ subject to the following restrictions:
 #ifndef BT_COLLISION_MARGIN_H
 #define BT_COLLISION_MARGIN_H
 
-//used by Gjk and some other algorithms
-
+///The CONVEX_DISTANCE_MARGIN is a default collision margin for convex collision shapes derived from btConvexInternalShape.
+///This collision margin is used by Gjk and some other algorithms
+///Note that when creating small objects, you need to make sure to set a smaller collision margin, using the 'setMargin' API
 #define CONVEX_DISTANCE_MARGIN btScalar(0.04)// btScalar(0.1)//;//btScalar(0.01)
 
 

src/BulletCollision/CollisionShapes/btConvexInternalShape.h

@@ -21,6 +21,11 @@ subject to the following restrictions:
 
 
 ///The btConvexInternalShape is an internal base class, shared by most convex shape implementations.
+///The btConvexInternalShape uses a default collision margin set to CONVEX_DISTANCE_MARGIN.
+///This collision margin used by Gjk and some other algorithms, see also btCollisionMargin.h
+///Note that when creating small shapes (derived from btConvexInternalShape), 
+///you need to make sure to set a smaller collision margin, using the 'setMargin' API
+///There is a automatic mechanism 'setSafeMargin' used by btBoxShape and btCylinderShape
 class btConvexInternalShape : public btConvexShape
 {
 
@@ -62,6 +67,23 @@ public:
 		m_implicitShapeDimensions = dimensions;
 	}
 
+	void	setSafeMargin(btScalar minDimension, btScalar defaultMarginMultiplier = 0.1f)
+	{
+		btScalar safeMargin = defaultMarginMultiplier*minDimension;
+		if (safeMargin < getMargin())
+		{
+			setMargin(safeMargin);
+		}
+	}
+	void	setSafeMargin(const btVector3& halfExtents, btScalar defaultMarginMultiplier = 0.1f)
+	{
+		//see http://code.google.com/p/bullet/issues/detail?id=349
+		//this margin check could could be added to other collision shapes too,
+		//or add some assert/warning somewhere
+		btScalar minDimension=halfExtents[halfExtents.minAxis()]; 		
+		setSafeMargin(minDimension, defaultMarginMultiplier);
+	}
+
 	///getAabb's default implementation is brute force, expected derived classes to implement a fast dedicated version
 	void getAabb(const btTransform& t,btVector3& aabbMin,btVector3& aabbMax) const
 	{

src/BulletCollision/CollisionShapes/btCylinderShape.cpp

@@ -19,6 +19,8 @@ btCylinderShape::btCylinderShape (const btVector3& halfExtents)
 :btConvexInternalShape(),
 m_upAxis(1)
 {
+	setSafeMargin(halfExtents);
+
 	btVector3 margin(getMargin(),getMargin(),getMargin());
 	m_implicitShapeDimensions = (halfExtents * m_localScaling) - margin;
 	m_shapeType = CYLINDER_SHAPE_PROXYTYPE;