Added b2ContactId for events and access functions (#943)

`b2ContactBeginTouchEvent` now contains a `b2ContactId` you can hold
onto safely and query for the manifold. This lets you get the contact
impulses. You can use the end touch event to clear the handle.

Author: erincatto

include/box2d/box2d.h

@@ -1230,3 +1230,20 @@ B2_API float b2WheelJoint_GetMotorTorque( b2JointId jointId );
 /**@}*/
 
 /**@}*/
+
+/**
+ * @defgroup contact Contact
+ * Access to contacts
+ * @{
+ */
+
+/// Contact identifier validation. Provides validation for up to 2^32 allocations.
+B2_API bool b2Contact_IsValid( b2ContactId id );
+
+/// Get manifold for a contact. The manifold may have no points if the contact is not touching.
+B2_API b2Manifold b2Contact_GetManifold( b2ContactId contactId );
+
+/// Get the shapes associated with a contact.
+B2_API void b2Contact_GetShapeIds( b2ContactId contactId, b2ShapeId* shapeIdA, b2ShapeId* shapeIdB );
+
+/**@}*/

include/box2d/id.h

@@ -72,21 +72,31 @@ typedef struct b2JointId
 	uint16_t generation;
 } b2JointId;
 
+/// Contact id references a contact instance. This should be treated as an opaque handled.
+typedef struct b2ContactId
+{
+	int32_t index1;
+	uint16_t world0;
+	int16_t padding;
+	uint32_t generation;
+} b2ContactId;
+
 /// Use these to make your identifiers null.
 /// You may also use zero initialization to get null.
 static const b2WorldId b2_nullWorldId = B2_ZERO_INIT;
 static const b2BodyId b2_nullBodyId = B2_ZERO_INIT;
 static const b2ShapeId b2_nullShapeId = B2_ZERO_INIT;
 static const b2ChainId b2_nullChainId = B2_ZERO_INIT;
 static const b2JointId b2_nullJointId = B2_ZERO_INIT;
+static const b2ContactId b2_nullContactId = B2_ZERO_INIT;
 
 /// Macro to determine if any id is null.
 #define B2_IS_NULL( id ) ( id.index1 == 0 )
 
 /// Macro to determine if any id is non-null.
 #define B2_IS_NON_NULL( id ) ( id.index1 != 0 )
 
-/// Compare two ids for equality. Doesn't work for b2WorldId.
+/// Compare two ids for equality. Doesn't work for b2WorldId. Don't mix types.
 #define B2_ID_EQUALS( id1, id2 ) ( id1.index1 == id2.index1 && id1.world0 == id2.world0 && id1.generation == id2.generation )
 
 /// Store a world id into a uint32_t.
@@ -154,4 +164,23 @@ B2_INLINE b2JointId b2LoadJointId( uint64_t x )
 	return id;
 }
 
+/// Store a contact id into 16 bytes
+B2_INLINE void b2StoreContactId( b2ContactId id, uint32_t values[3] )
+{
+	values[0] = (uint32_t)id.index1;
+	values[1] = (uint32_t)id.world0;
+	values[2] = (uint32_t)id.generation;
+}
+
+/// Load a two uint64_t into a contact id.
+B2_INLINE b2ContactId b2LoadContactId( uint32_t values[3] )
+{
+	b2ContactId id;
+	id.index1 = (int32_t)values[0];
+	id.world0 = (uint16_t)values[1];
+	id.padding = 0;
+	id.generation = (uint32_t)values[2];
+	return id;
+}
+
 /**@}*/

include/box2d/types.h

@@ -607,7 +607,7 @@ typedef struct b2DistanceJointDef
 B2_API b2DistanceJointDef b2DefaultDistanceJointDef( void );
 
 /// A motor joint is used to control the relative motion between two bodies
-///
+/// You may move local frame A to change the target transform.
 /// A typical usage is to control the movement of a dynamic body with respect to the ground.
 /// @ingroup motor_joint
 typedef struct b2MotorJointDef
@@ -633,7 +633,7 @@ typedef struct b2MotorJointDef
 B2_API b2MotorJointDef b2DefaultMotorJointDef( void );
 
 /// A mouse joint is used to make a point on a body track a specified world point.
-///
+/// You may move local frame A to change the target point.
 /// This a soft constraint and allows the constraint to stretch without
 /// applying huge forces. This also applies rotation constraint heuristic to improve control.
 /// @ingroup mouse_joint
@@ -677,10 +677,8 @@ B2_API b2FilterJointDef b2DefaultFilterJointDef( void );
 
 /// Prismatic joint definition
 ///
-/// This requires defining a line of motion using an axis and an anchor point.
-/// The definition uses local anchor points and a local axis so that the initial
-/// configuration can violate the constraint slightly. The joint translation is zero
-/// when the local anchor points coincide in world space.
+/// Body B may slide along the x-axis in local frame A. Body B cannot rotate relative to body A.
+/// The joint translation is zero when the local frame origins coincide in world space.
 /// @ingroup prismatic_joint
 typedef struct b2PrismaticJointDef
 {
@@ -733,8 +731,7 @@ B2_API b2PrismaticJointDef b2DefaultPrismaticJointDef( void );
 /// initial configuration can violate the constraint slightly. You also need to
 /// specify the initial relative angle for joint limits. This helps when saving
 /// and loading a game.
-/// The local anchor points are measured from the body's origin
-/// rather than the center of mass because:
+/// The local anchor points are measured from the body's origin rather than the center of mass because:
 /// 1. you might not know where the center of mass will be
 /// 2. if you add/remove shapes from a body and recompute the mass, the joints will be broken
 /// @ingroup revolute_joint
@@ -815,10 +812,8 @@ B2_API b2WeldJointDef b2DefaultWeldJointDef( void );
 
 /// Wheel joint definition
 ///
-/// This requires defining a line of motion using an axis and an anchor point.
-/// The definition uses local  anchor points and a local axis so that the initial
-/// configuration can violate the constraint slightly. The joint translation is zero
-/// when the local anchor points coincide in world space.
+/// Body B is a wheel that may rotate freely and slide along the local x-axis in frame A.
+/// The joint translation is zero when the local frame origins coincide in world space.
 /// @ingroup wheel_joint
 typedef struct b2WheelJointDef
 {
@@ -959,8 +954,13 @@ typedef struct b2ContactBeginTouchEvent
 	/// Id of the second shape
 	b2ShapeId shapeIdB;
 
+	/// The transient contact id. This contact maybe destroyed automatically by Box2D when the world is modified or simulated.
+	/// Used b2Contact_IsValid before using this id.
+	b2ContactId contactId;
+
 	/// The initial contact manifold. This is recorded before the solver is called,
-	/// so all the impulses will be zero.
+	/// so all the impulses will be zero. You can use the contact id to access the manifold impulses
+	/// using b2Contact_GetManifold.
 	b2Manifold manifold;
 } b2ContactBeginTouchEvent;
 
@@ -979,6 +979,9 @@ typedef struct b2ContactEndTouchEvent
 	///	@warning this shape may have been destroyed
 	///	@see b2Shape_IsValid
 	b2ShapeId shapeIdB;
+
+	/// Id of the contact
+	b2ContactId contactId;
 } b2ContactEndTouchEvent;
 
 /// A hit touch event is generated when two shapes collide with a speed faster than the hit speed threshold.

samples/sample_events.cpp

@@ -806,7 +806,7 @@ class FootSensor : public Sample
 	int m_overlapCount;
 };
 
-static int sampleCharacterSensor = RegisterSample( "Events", "Foot Sensor", FootSensor::Create );
+static int sampleFootSensor = RegisterSample( "Events", "Foot Sensor", FootSensor::Create );
 
 struct BodyUserData
 {
@@ -2082,3 +2082,106 @@ class JointEvent : public Sample
 };
 
 static int sampleBreakableJoint = RegisterSample( "Events", "Joint", JointEvent::Create );
+
+class PersistentContact : public Sample
+{
+public:
+	explicit PersistentContact( SampleContext* context )
+		: Sample( context )
+	{
+		if ( m_context->restart == false )
+		{
+			m_context->camera.m_center = { 0.0f, 6.0f };
+			m_context->camera.m_zoom = 7.5f;
+		}
+
+		{
+			b2BodyDef bodyDef = b2DefaultBodyDef();
+			b2BodyId groundId = b2CreateBody( m_worldId, &bodyDef );
+
+			b2Vec2 points[22];
+			float x = 10.0f;
+			for ( int i = 0; i < 20; ++i )
+			{
+				points[i] = { x, 0.0f };
+				x -= 1.0f;
+			}
+
+			points[20] = { -9.0f, 10.0f };
+			points[21] = { 10.0f, 10.0f };
+
+			b2ChainDef chainDef = b2DefaultChainDef();
+			chainDef.points = points;
+			chainDef.count = 22;
+			chainDef.isLoop = true;
+
+			b2CreateChain( groundId, &chainDef );
+		}
+
+		{
+			b2BodyDef bodyDef = b2DefaultBodyDef();
+			bodyDef.type = b2_dynamicBody;
+			bodyDef.position = { -8.0f, 1.0f };
+			bodyDef.linearVelocity = { 2.0f, 0.0f };
+
+			b2BodyId bodyId = b2CreateBody( m_worldId, &bodyDef );
+
+			b2ShapeDef shapeDef = b2DefaultShapeDef();
+			shapeDef.enableContactEvents = true;
+			b2Circle circle = { { 0.0f, 0.0f }, 0.5f };
+			b2CreateCircleShape( bodyId, &shapeDef, &circle );
+		}
+
+		m_contactId = b2_nullContactId;
+	}
+
+	void Step() override
+	{
+		Sample::Step();
+
+		b2ContactEvents events = b2World_GetContactEvents( m_worldId );
+		for ( int i = 0; i < events.beginCount && i < 1; ++i )
+		{
+			b2ContactBeginTouchEvent event = events.beginEvents[i];
+			m_contactId = events.beginEvents[i].contactId;
+		}
+
+		for ( int i = 0; i < events.endCount; ++i )
+		{
+			if ( B2_ID_EQUALS( m_contactId, events.endEvents[i].contactId ) )
+			{
+				m_contactId = b2_nullContactId;
+				break;
+			}
+		}
+
+		if (B2_IS_NON_NULL(m_contactId) && b2Contact_IsValid(m_contactId))
+		{
+			b2Manifold manifold = b2Contact_GetManifold( m_contactId );
+
+			for (int i = 0; i < manifold.pointCount; ++i)
+			{
+				const b2ManifoldPoint* manifoldPoint = manifold.points + i;
+				b2Vec2 p1 = manifoldPoint->point;
+				b2Vec2 p2 = p1 + manifoldPoint->totalNormalImpulse * manifold.normal;
+				m_draw->DrawSegment( p1, p2, b2_colorCrimson );
+				m_draw->DrawPoint( p1, 6.0f, b2_colorCrimson );
+				m_draw->DrawString( p1, "%.2f", manifoldPoint->totalNormalImpulse );
+			}
+		}
+		else
+		{
+			m_contactId = b2_nullContactId;
+		}
+
+	}
+
+	static Sample* Create( SampleContext* context )
+	{
+		return new PersistentContact( context );
+	}
+
+	b2ContactId m_contactId;
+};
+
+static int samplePersistentContact = RegisterSample( "Events", "Persistent Contact", PersistentContact::Create );