physics library version update
[spacedolphin:spacedolphin.git] / lib / chipmunk / include / chipmunk / cpBody.h
1 /* Copyright (c) 2007 Scott Lembcke
2  * 
3  * Permission is hereby granted, free of charge, to any person obtaining a copy
4  * of this software and associated documentation files (the "Software"), to deal
5  * in the Software without restriction, including without limitation the rights
6  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
7  * copies of the Software, and to permit persons to whom the Software is
8  * furnished to do so, subject to the following conditions:
9  * 
10  * The above copyright notice and this permission notice shall be included in
11  * all copies or substantial portions of the Software.
12  * 
13  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
14  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
15  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
16  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
17  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
18  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
19  * SOFTWARE.
20  */
21
22 /// @defgroup cpBody cpBody
23 /// Chipmunk's rigid body type. Rigid bodies hold the physical properties of an object like
24 /// it's mass, and position and velocity of it's center of gravity. They don't have an shape on their own.
25 /// They are given a shape by creating collision shapes (cpShape) that point to the body.
26 /// @{
27
28 /// Rigid body velocity update function type.
29 typedef void (*cpBodyVelocityFunc)(cpBody *body, cpVect gravity, cpFloat damping, cpFloat dt);
30 /// Rigid body position update function type.
31 typedef void (*cpBodyPositionFunc)(cpBody *body, cpFloat dt);
32
33 /// Used internally to track information on the collision graph.
34 /// @private
35 typedef struct cpComponentNode {
36         cpBody *root;
37         cpBody *next;
38         cpFloat idleTime;
39 } cpComponentNode;
40
41 /// Chipmunk's rigid body struct.
42 struct cpBody {
43         /// Function that is called to integrate the body's velocity. (Defaults to cpBodyUpdateVelocity)
44         cpBodyVelocityFunc velocity_func;
45         
46         /// Function that is called to integrate the body's position. (Defaults to cpBodyUpdatePosition)
47         cpBodyPositionFunc position_func;
48         
49         /// Mass of the body.
50         /// Must agree with cpBody.m_inv! Use cpBodySetMass() when changing the mass for this reason.
51         cpFloat m;
52         /// Mass inverse.
53         cpFloat m_inv;
54         
55         /// Moment of inertia of the body.
56         /// Must agree with cpBody.i_inv! Use cpBodySetMoment() when changing the moment for this reason.
57         cpFloat i;
58         /// Moment of inertia inverse.
59         cpFloat i_inv;
60         
61         /// Position of the rigid body's center of gravity.
62         cpVect p;
63         /// Velocity of the rigid body's center of gravity.
64         cpVect v;
65         /// Force acting on the rigid body's center of gravity.
66         cpVect f;
67         
68         /// Rotation of the body around it's center of gravity in radians.
69         /// Must agree with cpBody.rot! Use cpBodySetAngle() when changing the angle for this reason.
70         cpFloat a;
71         /// Angular velocity of the body around it's center of gravity in radians/second.
72         cpFloat w;
73         /// Torque applied to the body around it's center of gravity.
74         cpFloat t;
75         
76         /// Cached unit length vector representing the angle of the body.
77         /// Used for fast rotations using cpvrotate().
78         cpVect rot;
79         
80         /// User definable data pointer.
81         /// Generally this points to your the game object class so you can access it
82         /// when given a cpBody reference in a callback.
83         cpDataPointer data;
84         
85         /// Maximum velocity allowed when updating the velocity.
86         cpFloat v_limit;
87         /// Maximum rotational rate (in radians/second) allowed when updating the angular velocity.
88         cpFloat w_limit;
89         
90         CP_PRIVATE(cpVect v_bias);
91         CP_PRIVATE(cpFloat w_bias);
92         
93         CP_PRIVATE(cpSpace *space);
94         
95         CP_PRIVATE(cpShape *shapeList);
96         CP_PRIVATE(cpArbiter *arbiterList);
97         CP_PRIVATE(cpConstraint *constraintList);
98         
99         CP_PRIVATE(cpComponentNode node);
100 };
101
102 /// Allocate a cpBody.
103 cpBody* cpBodyAlloc(void);
104 /// Initialize a cpBody.
105 cpBody* cpBodyInit(cpBody *body, cpFloat m, cpFloat i);
106 /// Allocate and initialize a cpBody.
107 cpBody* cpBodyNew(cpFloat m, cpFloat i);
108
109 /// Initialize a static cpBody.
110 cpBody* cpBodyInitStatic(cpBody *body);
111 /// Allocate and initialize a static cpBody.
112 cpBody* cpBodyNewStatic(void);
113
114 /// Destroy a cpBody.
115 void cpBodyDestroy(cpBody *body);
116 /// Destroy and free a cpBody.
117 void cpBodyFree(cpBody *body);
118
119 /// Check that the properties of a body is sane. (Only in debug mode)
120 #ifdef NDEBUG
121         #define cpBodyAssertSane(body)
122 #else
123         void cpBodySanityCheck(cpBody *body);
124         #define cpBodyAssertSane(body) cpBodySanityCheck(body)
125 #endif
126
127 // Defined in cpSpace.c
128 /// Wake up a sleeping or idle body.
129 void cpBodyActivate(cpBody *body);
130 /// Wake up any sleeping or idle bodies touching a static body.
131 void cpBodyActivateStatic(cpBody *body, cpShape *filter);
132
133 /// Force a body to fall asleep immediately.
134 void cpBodySleep(cpBody *body);
135 /// Force a body to fall asleep immediately along with other bodies in a group.
136 void cpBodySleepWithGroup(cpBody *body, cpBody *group);
137
138 /// Returns true if the body is sleeping.
139 static inline cpBool cpBodyIsSleeping(const cpBody *body)
140 {
141         return (CP_PRIVATE(body->node).root != ((cpBody*)0));
142 }
143
144 /// Returns true if the body is static.
145 static inline cpBool cpBodyIsStatic(const cpBody *body)
146 {
147         return CP_PRIVATE(body->node).idleTime == INFINITY;
148 }
149
150 /// Returns true if the body has not been added to a space.
151 /// Note: Static bodies are a subtype of rogue bodies.
152 static inline cpBool cpBodyIsRogue(const cpBody *body)
153 {
154         return (body->CP_PRIVATE(space) == ((cpSpace*)0));
155 }
156
157
158 #define CP_DefineBodyStructGetter(type, member, name) \
159 static inline type cpBodyGet##name(const cpBody *body){return body->member;}
160
161 #define CP_DefineBodyStructSetter(type, member, name) \
162 static inline void cpBodySet##name(cpBody *body, const type value){ \
163         cpBodyActivate(body); \
164         body->member = value; \
165         cpBodyAssertSane(body); \
166 }
167
168 #define CP_DefineBodyStructProperty(type, member, name) \
169 CP_DefineBodyStructGetter(type, member, name) \
170 CP_DefineBodyStructSetter(type, member, name)
171
172 // TODO add to docs
173 CP_DefineBodyStructGetter(cpSpace*, CP_PRIVATE(space), Space)
174
175 CP_DefineBodyStructGetter(cpFloat, m, Mass)
176 /// Set the mass of a body.
177 void cpBodySetMass(cpBody *body, cpFloat m);
178
179 CP_DefineBodyStructGetter(cpFloat, i, Moment)
180 /// Set the moment of a body.
181 void cpBodySetMoment(cpBody *body, cpFloat i);
182
183 CP_DefineBodyStructGetter(cpVect, p, Pos)
184 /// Set the position of a body.
185 void cpBodySetPos(cpBody *body, cpVect pos);
186 CP_DefineBodyStructProperty(cpVect, v, Vel)
187 CP_DefineBodyStructProperty(cpVect, f, Force)
188 CP_DefineBodyStructGetter(cpFloat, a, Angle)
189 /// Set the angle of a body.
190 void cpBodySetAngle(cpBody *body, cpFloat a);
191 CP_DefineBodyStructProperty(cpFloat, w, AngVel)
192 CP_DefineBodyStructProperty(cpFloat, t, Torque)
193 CP_DefineBodyStructGetter(cpVect, rot, Rot)
194 CP_DefineBodyStructProperty(cpFloat, v_limit, VelLimit)
195 CP_DefineBodyStructProperty(cpFloat, w_limit, AngVelLimit)
196 CP_DefineBodyStructProperty(cpDataPointer, data, UserData)
197
198 /// Default Integration functions.
199 void cpBodyUpdateVelocity(cpBody *body, cpVect gravity, cpFloat damping, cpFloat dt);
200 void cpBodyUpdatePosition(cpBody *body, cpFloat dt);
201
202 /// Convert body relative/local coordinates to absolute/world coordinates.
203 static inline cpVect cpBodyLocal2World(const cpBody *body, const cpVect v)
204 {
205         return cpvadd(body->p, cpvrotate(v, body->rot));
206 }
207
208 /// Convert body absolute/world coordinates to  relative/local coordinates.
209 static inline cpVect cpBodyWorld2Local(const cpBody *body, const cpVect v)
210 {
211         return cpvunrotate(cpvsub(v, body->p), body->rot);
212 }
213
214 /// Set the forces and torque or a body to zero.
215 void cpBodyResetForces(cpBody *body);
216 /// Apply an force (in world coordinates) to the body at a point relative to the center of gravity (also in world coordinates).
217 void cpBodyApplyForce(cpBody *body, const cpVect f, const cpVect r);
218 /// Apply an impulse (in world coordinates) to the body at a point relative to the center of gravity (also in world coordinates).
219 void cpBodyApplyImpulse(cpBody *body, const cpVect j, const cpVect r);
220
221 /// Get the velocity on a body (in world units) at a point on the body in world coordinates.
222 cpVect cpBodyGetVelAtWorldPoint(cpBody *body, cpVect point);
223 /// Get the velocity on a body (in world units) at a point on the body in local coordinates.
224 cpVect cpBodyGetVelAtLocalPoint(cpBody *body, cpVect point);
225
226
227 /// Get the kinetic energy of a body.
228 static inline cpFloat cpBodyKineticEnergy(const cpBody *body)
229 {
230         // Need to do some fudging to avoid NaNs
231         cpFloat vsq = cpvdot(body->v, body->v);
232         cpFloat wsq = body->w*body->w;
233         return (vsq ? vsq*body->m : 0.0f) + (wsq ? wsq*body->i : 0.0f);
234 }
235
236 /// Body/shape iterator callback function type. 
237 typedef void (*cpBodyShapeIteratorFunc)(cpBody *body, cpShape *shape, void *data);
238 /// Call @c func once for each shape attached to @c body and added to the space.
239 void cpBodyEachShape(cpBody *body, cpBodyShapeIteratorFunc func, void *data);
240
241 /// Body/constraint iterator callback function type. 
242 typedef void (*cpBodyConstraintIteratorFunc)(cpBody *body, cpConstraint *constraint, void *data);
243 /// Call @c func once for each constraint attached to @c body and added to the space.
244 void cpBodyEachConstraint(cpBody *body, cpBodyConstraintIteratorFunc func, void *data);
245
246 /// Body/arbiter iterator callback function type. 
247 typedef void (*cpBodyArbiterIteratorFunc)(cpBody *body, cpArbiter *arbiter, void *data);
248 /// Call @c func once for each arbiter that is currently active on the body.
249 void cpBodyEachArbiter(cpBody *body, cpBodyArbiterIteratorFunc func, void *data);
250
251 ///@}