chipmunk 5.3.4.5 → 6.1.3.0.rc1

data/ext/chipmunk/chipmunk_unsafe.h

@@ -19,8 +19,6 @@
  * SOFTWARE.
  */
 
-
-
 /* This header defines a number of "unsafe" operations on Chipmunk objects.
  * In this case "unsafe" is referring to operations which may reduce the
  * physical accuracy or numerical stability of the simulation, but will not
@@ -32,6 +30,12 @@
  * persistent velocities. Probably not what you meant, but perhaps close enough.
  */
 
+/// @defgroup unsafe Chipmunk Unsafe Shape Operations
+/// These functions are used for mutating collision shapes.
+/// Chipmunk does not have any way to get velocity information on changing shapes,
+/// so the results will be unrealistic. You must explicity include the chipmunk_unsafe.h header to use them.
+/// @{
+
 #ifndef CHIPMUNK_UNSAFE_HEADER
 #define CHIPMUNK_UNSAFE_HEADER
 
@@ -39,16 +43,21 @@
 extern "C" {
 #endif
 
+/// Set the radius of a circle shape.
 void cpCircleShapeSetRadius(cpShape *shape, cpFloat radius);
+/// Set the offset of a circle shape.
 void cpCircleShapeSetOffset(cpShape *shape, cpVect offset);
 
+/// Set the endpoints of a segment shape.
 void cpSegmentShapeSetEndpoints(cpShape *shape, cpVect a, cpVect b);
+/// Set the radius of a segment shape.
 void cpSegmentShapeSetRadius(cpShape *shape, cpFloat radius);
 
+/// Set the vertexes of a poly shape.
 void cpPolyShapeSetVerts(cpShape *shape, int numVerts, cpVect *verts, cpVect offset);
 
 #ifdef __cplusplus
 }
 #endif
-
 #endif
+/// @}

data/ext/chipmunk/constraints/cpConstraint.h

@@ -19,80 +19,136 @@
  * SOFTWARE.
  */
 
-// TODO: Comment me!
-	
-extern cpFloat cp_constraint_bias_coef;
+/// @defgroup cpConstraint cpConstraint
+/// @{
 
-struct cpConstraintClass;
-struct cpConstraint;
+typedef struct cpConstraintClass cpConstraintClass;
 
-typedef void (*cpConstraintPreStepFunction)(struct cpConstraint *constraint, cpFloat dt, cpFloat dt_inv);
-typedef void (*cpConstraintApplyImpulseFunction)(struct cpConstraint *constraint);
-typedef cpFloat (*cpConstraintGetImpulseFunction)(struct cpConstraint *constraint);
+typedef void (*cpConstraintPreStepImpl)(cpConstraint *constraint, cpFloat dt);
+typedef void (*cpConstraintApplyCachedImpulseImpl)(cpConstraint *constraint, cpFloat dt_coef);
+typedef void (*cpConstraintApplyImpulseImpl)(cpConstraint *constraint, cpFloat dt);
+typedef cpFloat (*cpConstraintGetImpulseImpl)(cpConstraint *constraint);
 
-typedef struct cpConstraintClass {
-	cpConstraintPreStepFunction preStep;
-	cpConstraintApplyImpulseFunction applyImpulse;
-	cpConstraintGetImpulseFunction getImpulse;
-} cpConstraintClass;
+/// @private
+struct cpConstraintClass {
+	cpConstraintPreStepImpl preStep;
+	cpConstraintApplyCachedImpulseImpl applyCachedImpulse;
+	cpConstraintApplyImpulseImpl applyImpulse;
+	cpConstraintGetImpulseImpl getImpulse;
+};
 
+/// Callback function type that gets called before solving a joint.
+typedef void (*cpConstraintPreSolveFunc)(cpConstraint *constraint, cpSpace *space);
+/// Callback function type that gets called after solving a joint.
+typedef void (*cpConstraintPostSolveFunc)(cpConstraint *constraint, cpSpace *space);
 
 
-typedef struct cpConstraint {
+/// Opaque cpConstraint struct.
+struct cpConstraint {
 	CP_PRIVATE(const cpConstraintClass *klass);
 	
-	cpBody *a, *b;
+	/// The first body connected to this constraint.
+	cpBody *a;
+	/// The second body connected to this constraint.
+	cpBody *b;
+	
+	CP_PRIVATE(cpSpace *space);
+	
+	CP_PRIVATE(cpConstraint *next_a);
+	CP_PRIVATE(cpConstraint *next_b);
+	
+	/// The maximum force that this constraint is allowed to use.
+	/// Defaults to infinity.
 	cpFloat maxForce;
-	cpFloat biasCoef;
+	/// The rate at which joint error is corrected.
+	/// Defaults to pow(1.0 - 0.1, 60.0) meaning that it will
+	/// correct 10% of the error every 1/60th of a second.
+	cpFloat errorBias;
+	/// The maximum rate at which joint error is corrected.
+	/// Defaults to infinity.
 	cpFloat maxBias;
 	
+	/// Function called before the solver runs.
+	/// Animate your joint anchors, update your motor torque, etc.
+	cpConstraintPreSolveFunc preSolve;
+	
+	/// Function called after the solver runs.
+	/// Use the applied impulse to perform effects like breakable joints.
+	cpConstraintPostSolveFunc postSolve;
+	
+	/// User definable data pointer.
+	/// Generally this points to your the game object class so you can access it
+	/// when given a cpConstraint reference in a callback.
 	cpDataPointer data;
-} cpConstraint;
-
-#ifdef CP_USE_DEPRECATED_API_4
-typedef cpConstraint cpJoint;
-#endif
+};
 
+/// Destroy a constraint.
 void cpConstraintDestroy(cpConstraint *constraint);
+/// Destroy and free a constraint.
 void cpConstraintFree(cpConstraint *constraint);
 
-static inline void
-cpConstraintActivateBodies(cpConstraint *constraint)
+/// @private
+static inline void cpConstraintActivateBodies(cpConstraint *constraint)
 {
 	cpBody *a = constraint->a; if(a) cpBodyActivate(a);
 	cpBody *b = constraint->b; if(b) cpBodyActivate(b);
 }
 
-static inline cpFloat
-cpConstraintGetImpulse(cpConstraint *constraint)
+/// @private
+#define CP_DefineConstraintStructGetter(type, member, name) \
+static inline type cpConstraint##Get##name(const cpConstraint *constraint){return constraint->member;}
+
+/// @private
+#define CP_DefineConstraintStructSetter(type, member, name) \
+static inline void cpConstraint##Set##name(cpConstraint *constraint, type value){ \
+	cpConstraintActivateBodies(constraint); \
+	constraint->member = value; \
+}
+
+/// @private
+#define CP_DefineConstraintStructProperty(type, member, name) \
+CP_DefineConstraintStructGetter(type, member, name) \
+CP_DefineConstraintStructSetter(type, member, name)
+
+CP_DefineConstraintStructGetter(cpSpace*, CP_PRIVATE(space), Space)
+
+CP_DefineConstraintStructGetter(cpBody*, a, A)
+CP_DefineConstraintStructGetter(cpBody*, b, B)
+CP_DefineConstraintStructProperty(cpFloat, maxForce, MaxForce)
+CP_DefineConstraintStructProperty(cpFloat, errorBias, ErrorBias)
+CP_DefineConstraintStructProperty(cpFloat, maxBias, MaxBias)
+CP_DefineConstraintStructProperty(cpConstraintPreSolveFunc, preSolve, PreSolveFunc)
+CP_DefineConstraintStructProperty(cpConstraintPostSolveFunc, postSolve, PostSolveFunc)
+CP_DefineConstraintStructProperty(cpDataPointer, data, UserData)
+
+// Get the last impulse applied by this constraint.
+static inline cpFloat cpConstraintGetImpulse(cpConstraint *constraint)
 {
 	return constraint->CP_PRIVATE(klass)->getImpulse(constraint);
 }
 
-#define cpConstraintCheckCast(constraint, struct) \
-	cpAssert(constraint->CP_PRIVATE(klass) == struct##GetClass(), "Constraint is not a "#struct);
+/// @}
 
+#define cpConstraintCheckCast(constraint, struct) \
+	cpAssertHard(constraint->CP_PRIVATE(klass) == struct##GetClass(), "Constraint is not a "#struct)
 
 #define CP_DefineConstraintGetter(struct, type, member, name) \
-static inline type \
-struct##Get##name(const cpConstraint *constraint){ \
+static inline type struct##Get##name(const cpConstraint *constraint){ \
 	cpConstraintCheckCast(constraint, struct); \
 	return ((struct *)constraint)->member; \
-} \
+}
 
 #define CP_DefineConstraintSetter(struct, type, member, name) \
-static inline void \
-struct##Set##name(cpConstraint *constraint, type value){ \
+static inline void struct##Set##name(cpConstraint *constraint, type value){ \
 	cpConstraintCheckCast(constraint, struct); \
 	cpConstraintActivateBodies(constraint); \
 	((struct *)constraint)->member = value; \
-} \
+}
 
 #define CP_DefineConstraintProperty(struct, type, member, name) \
 CP_DefineConstraintGetter(struct, type, member, name) \
 CP_DefineConstraintSetter(struct, type, member, name)
 
-// Built in Joint types
 #include "cpPinJoint.h"
 #include "cpSlideJoint.h"
 #include "cpPivotJoint.h"

data/ext/chipmunk/{cpDampedRotarySpring.h → constraints/cpDampedRotarySpring.h}

@@ -19,10 +19,14 @@
  * SOFTWARE.
  */
 
+/// @defgroup cpDampedRotarySpring cpDampedRotarySpring
+/// @{
+
 typedef cpFloat (*cpDampedRotarySpringTorqueFunc)(struct cpConstraint *spring, cpFloat relativeAngle);
 
-const cpConstraintClass *cpDampedRotarySpringGetClass();
+const cpConstraintClass *cpDampedRotarySpringGetClass(void);
 
+/// @private
 typedef struct cpDampedRotarySpring {
 	cpConstraint constraint;
 	cpFloat restAngle;
@@ -34,13 +38,19 @@ typedef struct cpDampedRotarySpring {
 	cpFloat w_coef;
 	
 	cpFloat iSum;
+	cpFloat jAcc;
 } cpDampedRotarySpring;
 
-cpDampedRotarySpring *cpDampedRotarySpringAlloc(void);
-cpDampedRotarySpring *cpDampedRotarySpringInit(cpDampedRotarySpring *joint, cpBody *a, cpBody *b, cpFloat restAngle, cpFloat stiffness, cpFloat damping);
-cpConstraint *cpDampedRotarySpringNew(cpBody *a, cpBody *b, cpFloat restAngle, cpFloat stiffness, cpFloat damping);
+/// Allocate a damped rotary spring.
+cpDampedRotarySpring* cpDampedRotarySpringAlloc(void);
+/// Initialize a damped rotary spring.
+cpDampedRotarySpring* cpDampedRotarySpringInit(cpDampedRotarySpring *joint, cpBody *a, cpBody *b, cpFloat restAngle, cpFloat stiffness, cpFloat damping);
+/// Allocate and initialize a damped rotary spring.
+cpConstraint* cpDampedRotarySpringNew(cpBody *a, cpBody *b, cpFloat restAngle, cpFloat stiffness, cpFloat damping);
+
+CP_DefineConstraintProperty(cpDampedRotarySpring, cpFloat, restAngle, RestAngle)
+CP_DefineConstraintProperty(cpDampedRotarySpring, cpFloat, stiffness, Stiffness)
+CP_DefineConstraintProperty(cpDampedRotarySpring, cpFloat, damping, Damping)
+CP_DefineConstraintProperty(cpDampedRotarySpring, cpDampedRotarySpringTorqueFunc, springTorqueFunc, SpringTorqueFunc)
 
-CP_DefineConstraintProperty(cpDampedRotarySpring, cpFloat, restAngle, RestAngle);
-CP_DefineConstraintProperty(cpDampedRotarySpring, cpFloat, stiffness, Stiffness);
-CP_DefineConstraintProperty(cpDampedRotarySpring, cpFloat, damping, Damping);
-CP_DefineConstraintProperty(cpDampedRotarySpring, cpDampedRotarySpringTorqueFunc, springTorqueFunc, SpringTorqueFunc);
+/// @}

data/ext/chipmunk/{cpDampedSpring.h → constraints/cpDampedSpring.h}

@@ -19,13 +19,17 @@
  * SOFTWARE.
  */
 
-struct cpDampedSpring;
+/// @defgroup cpDampedSpring cpDampedSpring
+/// @{
 
-typedef cpFloat (*cpDampedSpringForceFunc)(struct cpConstraint *spring, cpFloat dist);
+typedef struct cpDampedSpring cpDampedSpring;
 
-const cpConstraintClass *cpDampedSpringGetClass();
+typedef cpFloat (*cpDampedSpringForceFunc)(cpConstraint *spring, cpFloat dist);
 
-typedef struct cpDampedSpring {
+const cpConstraintClass *cpDampedSpringGetClass(void);
+
+/// @private
+struct cpDampedSpring {
 	cpConstraint constraint;
 	cpVect anchr1, anchr2;
 	cpFloat restLength;
@@ -39,15 +43,22 @@ typedef struct cpDampedSpring {
 	cpVect r1, r2;
 	cpFloat nMass;
 	cpVect n;
-} cpDampedSpring;
-
-cpDampedSpring *cpDampedSpringAlloc(void);
-cpDampedSpring *cpDampedSpringInit(cpDampedSpring *joint, cpBody *a, cpBody *b, cpVect anchr1, cpVect anchr2, cpFloat restLength, cpFloat stiffness, cpFloat damping);
-cpConstraint *cpDampedSpringNew(cpBody *a, cpBody *b, cpVect anchr1, cpVect anchr2, cpFloat restLength, cpFloat stiffness, cpFloat damping);
-
-CP_DefineConstraintProperty(cpDampedSpring, cpVect, anchr1, Anchr1);
-CP_DefineConstraintProperty(cpDampedSpring, cpVect, anchr2, Anchr2);
-CP_DefineConstraintProperty(cpDampedSpring, cpFloat, restLength, RestLength);
-CP_DefineConstraintProperty(cpDampedSpring, cpFloat, stiffness, Stiffness);
-CP_DefineConstraintProperty(cpDampedSpring, cpFloat, damping, Damping);
-CP_DefineConstraintProperty(cpDampedSpring, cpDampedSpringForceFunc, springForceFunc, SpringForceFunc);
+	
+	cpFloat jAcc;
+};
+
+/// Allocate a damped spring.
+cpDampedSpring* cpDampedSpringAlloc(void);
+/// Initialize a damped spring.
+cpDampedSpring* cpDampedSpringInit(cpDampedSpring *joint, cpBody *a, cpBody *b, cpVect anchr1, cpVect anchr2, cpFloat restLength, cpFloat stiffness, cpFloat damping);
+/// Allocate and initialize a damped spring.
+cpConstraint* cpDampedSpringNew(cpBody *a, cpBody *b, cpVect anchr1, cpVect anchr2, cpFloat restLength, cpFloat stiffness, cpFloat damping);
+
+CP_DefineConstraintProperty(cpDampedSpring, cpVect, anchr1, Anchr1)
+CP_DefineConstraintProperty(cpDampedSpring, cpVect, anchr2, Anchr2)
+CP_DefineConstraintProperty(cpDampedSpring, cpFloat, restLength, RestLength)
+CP_DefineConstraintProperty(cpDampedSpring, cpFloat, stiffness, Stiffness)
+CP_DefineConstraintProperty(cpDampedSpring, cpFloat, damping, Damping)
+CP_DefineConstraintProperty(cpDampedSpring, cpDampedSpringForceFunc, springForceFunc, SpringForceFunc)
+
+/// @}

data/ext/chipmunk/constraints/cpGearJoint.h

@@ -19,8 +19,12 @@
  * SOFTWARE.
  */
 
-const cpConstraintClass *cpGearJointGetClass();
+/// @defgroup cpGearJoint cpGearJoint
+/// @{
 
+const cpConstraintClass *cpGearJointGetClass(void);
+
+/// @private
 typedef struct cpGearJoint {
 	cpConstraint constraint;
 	cpFloat phase, ratio;
@@ -29,13 +33,19 @@ typedef struct cpGearJoint {
 	cpFloat iSum;
 		
 	cpFloat bias;
-	cpFloat jAcc, jMax;
+	cpFloat jAcc;
 } cpGearJoint;
 
-cpGearJoint *cpGearJointAlloc(void);
-cpGearJoint *cpGearJointInit(cpGearJoint *joint, cpBody *a, cpBody *b, cpFloat phase, cpFloat ratio);
-cpConstraint *cpGearJointNew(cpBody *a, cpBody *b, cpFloat phase, cpFloat ratio);
+/// Allocate a gear joint.
+cpGearJoint* cpGearJointAlloc(void);
+/// Initialize a gear joint.
+cpGearJoint* cpGearJointInit(cpGearJoint *joint, cpBody *a, cpBody *b, cpFloat phase, cpFloat ratio);
+/// Allocate and initialize a gear joint.
+cpConstraint* cpGearJointNew(cpBody *a, cpBody *b, cpFloat phase, cpFloat ratio);
 
-CP_DefineConstraintProperty(cpGearJoint, cpFloat, phase, Phase);
-CP_DefineConstraintGetter(cpGearJoint, cpFloat, ratio, Ratio);
+CP_DefineConstraintProperty(cpGearJoint, cpFloat, phase, Phase)
+CP_DefineConstraintGetter(cpGearJoint, cpFloat, ratio, Ratio)
+/// Set the ratio of a gear joint.
 void cpGearJointSetRatio(cpConstraint *constraint, cpFloat value);
+
+/// @}

data/ext/chipmunk/constraints/cpGrooveJoint.h

@@ -19,8 +19,12 @@
  * SOFTWARE.
  */
 
-const cpConstraintClass *cpGrooveJointGetClass();
+/// @defgroup cpGrooveJoint cpGrooveJoint
+/// @{
 
+const cpConstraintClass *cpGrooveJointGetClass(void);
+
+/// @private
 typedef struct cpGrooveJoint {
 	cpConstraint constraint;
 	cpVect grv_n, grv_a, grv_b;
@@ -29,20 +33,25 @@ typedef struct cpGrooveJoint {
 	cpVect grv_tn;
 	cpFloat clamp;
 	cpVect r1, r2;
-	cpVect k1, k2;
+	cpMat2x2 k;
 	
 	cpVect jAcc;
-	cpFloat jMaxLen;
 	cpVect bias;
 } cpGrooveJoint;
 
-cpGrooveJoint *cpGrooveJointAlloc(void);
-cpGrooveJoint *cpGrooveJointInit(cpGrooveJoint *joint, cpBody *a, cpBody *b, cpVect groove_a, cpVect groove_b, cpVect anchr2);
-cpConstraint *cpGrooveJointNew(cpBody *a, cpBody *b, cpVect groove_a, cpVect groove_b, cpVect anchr2);
-
+/// Allocate a groove joint.
+cpGrooveJoint* cpGrooveJointAlloc(void);
+/// Initialize a groove joint.
+cpGrooveJoint* cpGrooveJointInit(cpGrooveJoint *joint, cpBody *a, cpBody *b, cpVect groove_a, cpVect groove_b, cpVect anchr2);
+/// Allocate and initialize a groove joint.
+cpConstraint* cpGrooveJointNew(cpBody *a, cpBody *b, cpVect groove_a, cpVect groove_b, cpVect anchr2);
 
-CP_DefineConstraintGetter(cpGrooveJoint, cpVect, grv_a, GrooveA);
+CP_DefineConstraintGetter(cpGrooveJoint, cpVect, grv_a, GrooveA)
+/// Set endpoint a of a groove joint's groove
 void cpGrooveJointSetGrooveA(cpConstraint *constraint, cpVect value);
-CP_DefineConstraintGetter(cpGrooveJoint, cpVect, grv_b, GrooveB);
+CP_DefineConstraintGetter(cpGrooveJoint, cpVect, grv_b, GrooveB)
+/// Set endpoint b of a groove joint's groove
 void cpGrooveJointSetGrooveB(cpConstraint *constraint, cpVect value);
-CP_DefineConstraintProperty(cpGrooveJoint, cpVect, anchr2, Anchr2);
+CP_DefineConstraintProperty(cpGrooveJoint, cpVect, anchr2, Anchr2)
+
+/// @}

data/ext/chipmunk/constraints/cpPinJoint.h

@@ -19,8 +19,12 @@
  * SOFTWARE.
  */
  
-const cpConstraintClass *cpPinJointGetClass();
+/// @defgroup cpPinJoint cpPinJoint
+/// @{
 
+const cpConstraintClass *cpPinJointGetClass(void);
+
+/// @private
 typedef struct cpPinJoint {
 	cpConstraint constraint;
 	cpVect anchr1, anchr2;
@@ -30,14 +34,19 @@ typedef struct cpPinJoint {
 	cpVect n;
 	cpFloat nMass;
 	
-	cpFloat jnAcc, jnMax;
+	cpFloat jnAcc;
 	cpFloat bias;
 } cpPinJoint;
 
-cpPinJoint *cpPinJointAlloc(void);
-cpPinJoint *cpPinJointInit(cpPinJoint *joint, cpBody *a, cpBody *b, cpVect anchr1, cpVect anchr2);
-cpConstraint *cpPinJointNew(cpBody *a, cpBody *b, cpVect anchr1, cpVect anchr2);
+/// Allocate a pin joint.
+cpPinJoint* cpPinJointAlloc(void);
+/// Initialize a pin joint.
+cpPinJoint* cpPinJointInit(cpPinJoint *joint, cpBody *a, cpBody *b, cpVect anchr1, cpVect anchr2);
+/// Allocate and initialize a pin joint.
+cpConstraint* cpPinJointNew(cpBody *a, cpBody *b, cpVect anchr1, cpVect anchr2);
+
+CP_DefineConstraintProperty(cpPinJoint, cpVect, anchr1, Anchr1)
+CP_DefineConstraintProperty(cpPinJoint, cpVect, anchr2, Anchr2)
+CP_DefineConstraintProperty(cpPinJoint, cpFloat, dist, Dist)
 
-CP_DefineConstraintProperty(cpPinJoint, cpVect, anchr1, Anchr1);
-CP_DefineConstraintProperty(cpPinJoint, cpVect, anchr2, Anchr2);
-CP_DefineConstraintProperty(cpPinJoint, cpFloat, dist, Dist);
+///@}

data/ext/chipmunk/constraints/cpPivotJoint.h

@@ -19,24 +19,33 @@
  * SOFTWARE.
  */
 
-const cpConstraintClass *cpPivotJointGetClass();
+/// @defgroup cpPivotJoint cpPivotJoint
+/// @{
 
+const cpConstraintClass *cpPivotJointGetClass(void);
+
+/// @private
 typedef struct cpPivotJoint {
 	cpConstraint constraint;
 	cpVect anchr1, anchr2;
 	
 	cpVect r1, r2;
-	cpVect k1, k2;
+	cpMat2x2 k;
 	
 	cpVect jAcc;
-	cpFloat jMaxLen;
 	cpVect bias;
 } cpPivotJoint;
 
-cpPivotJoint *cpPivotJointAlloc(void);
-cpPivotJoint *cpPivotJointInit(cpPivotJoint *joint, cpBody *a, cpBody *b, cpVect anchr1, cpVect anchr2);
-cpConstraint *cpPivotJointNew(cpBody *a, cpBody *b, cpVect pivot);
-cpConstraint *cpPivotJointNew2(cpBody *a, cpBody *b, cpVect anchr1, cpVect anchr2);
+/// Allocate a pivot joint
+cpPivotJoint* cpPivotJointAlloc(void);
+/// Initialize a pivot joint.
+cpPivotJoint* cpPivotJointInit(cpPivotJoint *joint, cpBody *a, cpBody *b, cpVect anchr1, cpVect anchr2);
+/// Allocate and initialize a pivot joint.
+cpConstraint* cpPivotJointNew(cpBody *a, cpBody *b, cpVect pivot);
+/// Allocate and initialize a pivot joint with specific anchors.
+cpConstraint* cpPivotJointNew2(cpBody *a, cpBody *b, cpVect anchr1, cpVect anchr2);
+
+CP_DefineConstraintProperty(cpPivotJoint, cpVect, anchr1, Anchr1)
+CP_DefineConstraintProperty(cpPivotJoint, cpVect, anchr2, Anchr2)
 
-CP_DefineConstraintProperty(cpPivotJoint, cpVect, anchr1, Anchr1);
-CP_DefineConstraintProperty(cpPivotJoint, cpVect, anchr2, Anchr2);
+/// @}