summaryrefslogtreecommitdiff
path: root/legacy/ephysics/src/lib/EPhysics.h
diff options
context:
space:
mode:
authorBruno Dilly <bdilly@profusion.mobi>2012-11-13 22:18:16 +0000
committerBruno Dilly <bdilly@profusion.mobi>2012-11-13 22:18:16 +0000
commiteab0f812905fd16c7012827ffebc28d55d4adb00 (patch)
tree481935f63534a9c6565981d3f8e8a7d5a9e83e08 /legacy/ephysics/src/lib/EPhysics.h
parentcbf0049a643860c0662d0e044219e53f44225b2b (diff)
ephysics: wrap bullet's quaternion
Useful for 3d rotations. Avoid issues found when using euler angles, like gimbal locks. SVN revision: 79252
Diffstat (limited to '')
-rw-r--r--legacy/ephysics/src/lib/EPhysics.h356
1 files changed, 322 insertions, 34 deletions
diff --git a/legacy/ephysics/src/lib/EPhysics.h b/legacy/ephysics/src/lib/EPhysics.h
index a4409a34d1..df2b3da0da 100644
--- a/legacy/ephysics/src/lib/EPhysics.h
+++ b/legacy/ephysics/src/lib/EPhysics.h
@@ -120,6 +120,319 @@ EAPI int ephysics_shutdown(void);
120 */ 120 */
121 121
122/** 122/**
123 * @defgroup EPhysics_Quaternion EPhysics Quaternion
124 * @ingroup EPhysics
125 *
126 * @{
127 *
128 * Quaternions are used to perform linear algebra rotations.
129 *
130 * Functions regarding rotation, like @ref ephysics_body_rotation_set()
131 * and @ref ephysics_body_rotation_get() would need that. Quaternions
132 * can be used to rotate evas maps as well, with evas_map_util_quat_rotate(),
133 * but in this case quaternion values need to be get with
134 * @ref ephysics_quaternion_get(), since evas don't accept
135 * EPhysics_Quaternion type.
136 *
137 * A quaternion can be created with ephysics_quaternion_new(), and many
138 * operations can be performed with that, as:
139 * @li Sum: @ref ephysics_quaternion_sum()
140 * @li Difference: @ref ephysics_quaternion_diff()
141 * @li Multiple by another quaternion: @ref ephysics_quaternion_multiply()
142 * @li Multiply by scalar: @ref ephysics_quaternion_scale()
143 * @li Divide by scalar: @ref ephysics_quaternion_inverse_scale()
144 * @li Calculate length: @ref ephysics_quaternion_length_get()
145 * @li Calculate angle between quaternions: @ref ephysics_quaternion_angle_get()
146 */
147
148/**
149 * @typedef EPhysics_Quaternion
150 *
151 * Quaternion handle, represents a quaternion to be used to rotate bodies.
152 *
153 * Created with @ref ephysics_quaternion_new() and deleted with free().
154 *
155 * @ingroup EPhysics_Quaternion
156 */
157typedef struct _EPhysics_Quaternion EPhysics_Quaternion;
158
159/**
160 * @brief
161 * Create a new quaternion.
162 *
163 * @note It should be deleted with free() after usage is concluded.
164 *
165 * This values can be modified later by quaternion operations or set directly.
166 *
167 * @param x The x coordinate.
168 * @param y The y coordinate.
169 * @param z The z coordinate.
170 * @param w The rotation.
171 * @return The created quaternion or @c NULL on error.
172 *
173 * @see ephysics_quaternion_set();
174 * @see ephysics_quaternion_axis_angle_set();
175 * @see ephysics_quaternion_euler_set();
176 * @see ephysics_quaternion_scale();
177 * @see ephysics_quaternion_sum();
178 *
179 * @ingroup EPhysics_Quaternion
180 */
181EAPI EPhysics_Quaternion *ephysics_quaternion_new(double x, double y, double z, double w);
182
183/**
184 * @brief
185 * Get quaternion values.
186 *
187 * @param quat Quaternion to get values from.
188 * @param x The x coordinate.
189 * @param y The y coordinate.
190 * @param z The z coordinate.
191 * @param w The rotation.
192 *
193 * @see ephysics_quaternion_set();
194 *
195 * @ingroup EPhysics_Quaternion
196 */
197EAPI void ephysics_quaternion_get(const EPhysics_Quaternion *quat, double *x, double *y, double *z, double *w);
198
199/**
200 * @brief
201 * Get quaternion axis and angle.
202 *
203 * @param quat Quaternion to get values from.
204 * @param nx The x component of the axis of rotation.
205 * @param ny The y component of the axis of rotation.
206 * @param nz The z component of the axis of rotation.
207 * @param a The angle of rotation.
208 *
209 * @see ephysics_quaternion_axis_angle_set();
210 * @see ephysics_quaternion_get();
211 * @see ephysics_quaternion_set();
212 *
213 * @ingroup EPhysics_Quaternion
214 */
215EAPI void ephysics_quaternion_axis_angle_get(const EPhysics_Quaternion *quat, double *nx, double *ny, double *nz, double *a);
216
217/**
218 * @brief
219 * Set quaternion values.
220 *
221 * @param quat Quaternion to be set.
222 * @param x The x coordinate.
223 * @param y The y coordinate.
224 * @param z The z coordinate.
225 * @param w The rotation.
226 *
227 * @see ephysics_quaternion_get();
228 * @see ephysics_quaternion_euler_set();
229 *
230 * @ingroup EPhysics_Quaternion
231 */
232EAPI void ephysics_quaternion_set(EPhysics_Quaternion *quat, double x, double y, double z, double w);
233
234/**
235 * @brief
236 * Set quaternion using axis angle notation.
237 *
238 * [w, x, y, z] = [cos(a/2), sin(a/2) * nx, sin(a/2)* ny, sin(a/2) * nz]
239 *
240 * @param quat Quaternion to be set.
241 * @param nx The x component of the axis of rotation.
242 * @param ny The y component of the axis of rotation.
243 * @param nz The z component of the axis of rotation.
244 * @param a The angle of rotation.
245 *
246 * @see ephysics_quaternion_axis_angle_get();
247 * @see ephysics_quaternion_set();
248 * @see ephysics_quaternion_euler_set();
249 *
250 * @ingroup EPhysics_Quaternion
251 */
252EAPI void ephysics_quaternion_axis_angle_set(EPhysics_Quaternion *quat, double nx, double ny, double nz, double a);
253
254/**
255 * @brief
256 * Set quaternion using Euler angles.
257 *
258 * It's an alternative to @ref ephysics_quaternion_set() usage. Euler angles
259 * will be converted.
260 *
261 * @param quat Quaternion to be set.
262 * @param yaw The angle around Y axis.
263 * @param pitch The angle around X axis.
264 * @param roll The angle around Z axis.
265 *
266 * @see ephysics_quaternion_get();
267 * @see ephysics_quaternion_set();
268 *
269 * @ingroup EPhysics_Quaternion
270 */
271EAPI void ephysics_quaternion_euler_set(EPhysics_Quaternion *quat, double yaw, double pitch, double roll);
272
273/**
274 * @brief
275 * Normalize the quaternion.
276 *
277 * A normalized quaternion is such that x^2 + y^2 + z^2 + w^2 = 1.
278 *
279 * @param quat Quaternion to be normalized.
280 *
281 * @ingroup EPhysics_Quaternion
282 */
283EAPI void ephysics_quaternion_normalize(EPhysics_Quaternion *quat);
284
285/**
286 * @brief
287 * Invert the quaternion.
288 *
289 * @param quat Quaternion to be inverted.
290 *
291 * @ingroup EPhysics_Quaternion
292 */
293EAPI void ephysics_quaternion_invert(EPhysics_Quaternion *quat);
294
295/**
296 * @brief
297 * Scale the quaternion.
298 *
299 * @param quat Quaternion to be scaled.
300 * @param scale The scale factor.
301 *
302 * @see ephysics_quaternion_inverse_scale()
303 *
304 * @ingroup EPhysics_Quaternion
305 */
306EAPI void ephysics_quaternion_scale(EPhysics_Quaternion *quat, double scale);
307
308/**
309 * @brief
310 * Inversely scale the quaternion.
311 *
312 * @param quat Quaternion to be scaled.
313 * @param scale The scale factor.
314 *
315 * @see ephysics_quaternion_scale()
316 *
317 * @ingroup EPhysics_Quaternion
318 */
319EAPI void ephysics_quaternion_inverse_scale(EPhysics_Quaternion *quat, double scale);
320
321/**
322 * @brief
323 * Returns a sum of two quaternions.
324 *
325 * @param quat1 First quaternion to sum.
326 * @param quat2 Second quaternion to sum.
327 * @return The sum quaternion or @c NULL on error.
328 *
329 * @note It should be freed after usage.
330 *
331 * @ingroup EPhysics_Quaternion
332 */
333EAPI EPhysics_Quaternion *ephysics_quaternion_sum(const EPhysics_Quaternion *quat1, const EPhysics_Quaternion *quat2);
334
335/**
336 * @brief
337 * Returns a difference between two quaternions.
338 *
339 * @param quat1 First quaternion.
340 * @param quat2 Second quaternion.
341 * @return The difference between @p quat1 and @p quat2, or @c NULL on error.
342 *
343 * @note It should be freed after usage.
344 *
345 * @ingroup EPhysics_Quaternion
346 */
347EAPI EPhysics_Quaternion *ephysics_quaternion_diff(const EPhysics_Quaternion *quat1, const EPhysics_Quaternion *quat2);
348
349/**
350 * @brief
351 * Multiply two quaternions.
352 *
353 * @param quat1 First quaternion.
354 * @param quat2 Second quaternion.
355 * @return The @p quat1 multiplied by @p quat2 on the right, or @c NULL
356 * on error.
357 *
358 * @note It should be freed after usage.
359 *
360 * @ingroup EPhysics_Quaternion
361 */
362EAPI EPhysics_Quaternion *ephysics_quaternion_multiply(const EPhysics_Quaternion *quat1, const EPhysics_Quaternion *quat2);
363
364/**
365 * @brief
366 * Return the quaternion which is the result of Spherical Linear Interpolation
367 * between two quaternions.
368 *
369 * Slerp interpolates assuming constant velocity.
370 *
371 * @param quat1 First quaternion.
372 * @param quat2 Second quaternion.
373 * @param ratio The ratio between @p quat1 and @p quat2 to interpolate. If
374 * @p ratio = 0, the result is @p quat1, if @p ratio = 1, the result is
375 * @p quat2.
376 * @return The result of slerp between @p quat1 and @p quat2, or @c NULL
377 * on error.
378 *
379 * @note It should be freed after usage.
380 *
381 * @ingroup EPhysics_Quaternion
382 */
383EAPI EPhysics_Quaternion *ephysics_quaternion_slerp(const EPhysics_Quaternion *quat1, const EPhysics_Quaternion *quat2, double ratio);
384
385/**
386 * @brief
387 * Return the dot product between two quaternions.
388 *
389 * @param quat1 First quaternion.
390 * @param quat2 Second quaternion.
391 * @return The dot product between @p quat1 and @p quat2 or @c 0 on error.
392 *
393 * @ingroup EPhysics_Quaternion
394 */
395EAPI double ephysics_quaternion_dot(const EPhysics_Quaternion *quat1, const EPhysics_Quaternion *quat2);
396
397/**
398 * @brief
399 * Return the angle between two quaternions.
400 *
401 * @param quat1 First quaternion.
402 * @param quat2 Second quaternion.
403 * @return The angle between @p quat1 and @p quat2 or @c 0 on error.
404 *
405 * @ingroup EPhysics_Quaternion
406 */
407EAPI double ephysics_quaternion_angle_get(const EPhysics_Quaternion *quat1, const EPhysics_Quaternion *quat2);
408
409/**
410 * @brief
411 * Return the length of the quaternion.
412 *
413 * @param quat Quaternion to get length of.
414 * @return The lenght of @p quat or @c 0 on error.
415 *
416 * @ingroup EPhysics_Quaternion
417 */
418EAPI double ephysics_quaternion_length_get(const EPhysics_Quaternion *quat);
419
420/**
421 * @brief
422 * Return the length squared of the quaternion.
423 *
424 * @param quat Quaternion to get length of.
425 * @return The lenght of @p quat or @c 0 on error.
426 *
427 * @ingroup EPhysics_Quaternion
428 */
429EAPI double ephysics_quaternion_length2_get(const EPhysics_Quaternion *quat);
430
431/**
432 * @}
433 */
434
435/**
123 * @defgroup EPhysics_Shape EPhysics Shape 436 * @defgroup EPhysics_Shape EPhysics Shape
124 * @ingroup EPhysics 437 * @ingroup EPhysics
125 * 438 *
@@ -3422,61 +3735,36 @@ EAPI void ephysics_body_linear_movement_enable_get(const EPhysics_Body *body, Ei
3422 3735
3423/** 3736/**
3424 * @brief 3737 * @brief
3425 * Get body's rotation on x, y and z axes. 3738 * Get body's rotation quaternion.
3426 * 3739 *
3427 * By default rotation is 0 degree on all axes. 3740 * By default rotation is 0 degree on all axes.
3428 * 3741 *
3429 * @note The unit used for rotation is degrees.
3430 *
3431 * @param body The physics body. 3742 * @param body The physics body.
3432 * @param rot_x The amount of degrees @p body is rotated on x axis. 3743 * @return A quaternion or @c NULL on error. It should be freed with free()
3433 * @param rot_y The amount of degrees @p body is rotated on y axis. 3744 * after usage.
3434 * @param rot_z The amount of degrees @p body is rotated on z axis.
3435 * 3745 *
3436 * @see ephysics_body_rotation_set() 3746 * @see ephysics_body_rotation_set()
3437 * @see ephysics_body_rotation_quaternion_get() 3747 * @see ephysics_quaternion_get()
3438 * 3748 *
3439 * @ingroup EPhysics_Body 3749 * @ingroup EPhysics_Body
3440 */ 3750 */
3441EAPI void ephysics_body_rotation_get(const EPhysics_Body *body, double *rot_x, double *rot_y, double *rot_z); 3751EAPI EPhysics_Quaternion *ephysics_body_rotation_get(const EPhysics_Body *body);
3442 3752
3443/** 3753/**
3444 * @brief 3754 * @brief
3445 * Set body's rotation on z axis. 3755 * Set body's rotation.
3446 * 3756 *
3447 * By default rotation is 0 degrees on all axes. 3757 * By default rotation is 0 degrees on all axes.
3448 * Negative values indicates rotation on counter clockwise direction.
3449 *
3450 * @note The unit used for rotation is degrees.
3451 * 3758 *
3452 * @param body The physics body. 3759 * @param body The physics body.
3453 * @param rot_x The amount of degrees @p body should be rotated on x axis. 3760 * @param quat Quaternion representing the rotation.
3454 * @param rot_y The amount of degrees @p body should be rotated on y axis.
3455 * @param rot_z The amount of degrees @p body should be rotated on z axis.
3456 * 3761 *
3457 * @see ephysics_body_rotation_get() 3762 * @see ephysics_body_rotation_get()
3763 * @see ephysics_quaternion_new()
3458 * 3764 *
3459 * @ingroup EPhysics_Body 3765 * @ingroup EPhysics_Body
3460 */ 3766 */
3461EAPI void ephysics_body_rotation_set(EPhysics_Body *body, double rot_x, double rot_y, double rot_z); 3767EAPI void ephysics_body_rotation_set(EPhysics_Body *body, EPhysics_Quaternion *quat);
3462
3463/**
3464 * @brief
3465 * Get body's normalized rotation quaternion (x, y, z and w).
3466 *
3467 * @param body The physics body.
3468 * @param x the x component of the imaginary part of the quaternion.
3469 * @param y the y component of the imaginary part of the quaternion.
3470 * @param z the z component of the imaginary part of the quaternion.
3471 * @param w the w component of the real part of the quaternion.
3472 *
3473 * @see ephysics_body_rotation_set()
3474 * @see ephysics_body_rotation_get()
3475 *
3476 * @ingroup EPhysics_Body
3477 */
3478EAPI void
3479ephysics_body_rotation_quaternion_get(const EPhysics_Body *body, double *x, double *y, double *z, double *w);
3480 3768
3481/** 3769/**
3482 * @brief 3770 * @brief