4
* A Low Level GPU Graphics and Utilities API
6
* Copyright (C) 2010 Intel Corporation.
8
* Permission is hereby granted, free of charge, to any person
9
* obtaining a copy of this software and associated documentation
10
* files (the "Software"), to deal in the Software without
11
* restriction, including without limitation the rights to use, copy,
12
* modify, merge, publish, distribute, sublicense, and/or sell copies
13
* of the Software, and to permit persons to whom the Software is
14
* furnished to do so, subject to the following conditions:
16
* The above copyright notice and this permission notice shall be
17
* included in all copies or substantial portions of the Software.
19
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
20
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
21
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
22
* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
23
* BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
24
* ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
25
* CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
29
* Robert Bragg <robert@linux.intel.com>
33
#include "cogl-config.h"
36
#include <cogl-util.h>
37
#include <cogl-euler.h>
38
#include <cogl-matrix.h>
39
#include "cogl-gtype-private.h"
44
COGL_GTYPE_DEFINE_BOXED (Euler, euler,
49
cogl_euler_init (CoglEuler *euler,
54
euler->heading = heading;
60
cogl_euler_init_from_matrix (CoglEuler *euler,
61
const CoglMatrix *matrix)
64
* Extracting a canonical Euler angle from a matrix:
65
* (where it is assumed the matrix contains no scaling, mirroring or
68
* A Euler angle is a combination of three rotations around mutually
69
* perpendicular axis. For this algorithm they are:
71
* Heading: A rotation about the Y axis by an angle H:
76
* Pitch: A rotation around the X axis by an angle P:
81
* Roll: A rotation about the Z axis by an angle R:
86
* When multiplied as matrices this gives:
87
* | cosHcosR+sinHsinPsinR sinRcosP -sinHcosR+cosHsinPsinR|
88
* M = |-cosHsinR+sinHsinPcosR cosRcosP sinRsinH+cosHsinPcosB|
89
* | sinHcosP -sinP cosHcosP |
91
* Given that there are an infinite number of ways to represent
92
* a given orientation, the "canonical" Euler angle is any such that:
97
* M[3][2] = -sinP lets us immediately solve for P = asin(-M[3][2])
98
* (Note: asin has a range of +-90)
100
* This means we can use M[3][1] to calculate sinH:
101
* sinH = M[3][1]/cosP
102
* And use M[3][3] to calculate cosH:
103
* cosH = M[3][3]/cosP
104
* This lets us calculate H = atan2(sinH,cosH), but we optimise this:
105
* 1st note: atan2(x, y) does: atan(x/y) and uses the sign of x and y to
106
* determine the quadrant of the final angle.
107
* 2nd note: we know cosP is > 0 (ignoring cosP == 0)
108
* Therefore H = atan2((M[3][1]/cosP) / (M[3][3]/cosP)) can be simplified
109
* by skipping the division by cosP since it won't change the x/y ratio
110
* nor will it change their sign. This gives:
111
* H = atan2(M[3][1], M[3][3])
112
* R is computed in the same way as H from M[1][2] and M[2][2] so:
113
* R = atan2(M[1][2], M[2][2])
114
* Note: If cosP were == 0 then H and R could not be calculated as above
115
* because all the necessary matrix values would == 0. In other words we are
116
* pitched vertically and so H and R would now effectively rotate around the
117
* same axis - known as "Gimbal lock". In this situation we will set all the
118
* rotation on H and set R = 0.
119
* So with P = R = 0 we have cosP = 0, sinR = 0 and cosR = 1
120
* We can substitute those into the above equation for M giving:
122
* |sinHsinP 0 cosHsinP|
124
* And calculate H as atan2 (-M[3][2], M[1][1])
128
float H; /* heading */
132
/* NB: CoglMatrix provides struct members named according to the
133
* [row][column] indexed. So matrix->zx is row 3 column 1. */
136
/* Determine the Pitch, avoiding domain errors with asin () which
137
* might occur due to previous imprecision in manipulating the
141
else if (sinP >= 1.0f)
146
/* If P is too close to 0 then we have hit Gimbal lock */
149
H = atan2f (-matrix->zy, matrix->xx);
154
H = atan2f (matrix->zx, matrix->zz);
155
R = atan2f (matrix->xy, matrix->yy);
164
cogl_euler_equal (const void *v1, const void *v2)
166
const CoglEuler *a = v1;
167
const CoglEuler *b = v2;
169
_COGL_RETURN_VAL_IF_FAIL (v1 != NULL, FALSE);
170
_COGL_RETURN_VAL_IF_FAIL (v2 != NULL, FALSE);
175
return (a->heading == b->heading &&
176
a->pitch == b->pitch &&
181
cogl_euler_copy (const CoglEuler *src)
185
CoglEuler *new = g_slice_new (CoglEuler);
186
memcpy (new, src, sizeof (float) * 3);
194
cogl_euler_free (CoglEuler *euler)
196
g_slice_free (CoglEuler, euler);