Euler: Graphene Reference Manual

Euler

Euler — Euler angles

Functions

graphene_euler_t *	graphene_euler_alloc ()
void	graphene_euler_free ()
graphene_euler_t *	graphene_euler_init ()
graphene_euler_t *	graphene_euler_init_with_order ()
graphene_euler_t *	graphene_euler_init_from_matrix ()
graphene_euler_t *	graphene_euler_init_from_quaternion ()
graphene_euler_t *	graphene_euler_init_from_vec3 ()
graphene_euler_t *	graphene_euler_init_from_euler ()
graphene_euler_t *	graphene_euler_init_from_radians ()
bool	graphene_euler_equal ()
float	graphene_euler_get_x ()
float	graphene_euler_get_y ()
float	graphene_euler_get_z ()
graphene_euler_order_t	graphene_euler_get_order ()
float	graphene_euler_get_alpha ()
float	graphene_euler_get_beta ()
float	graphene_euler_get_gamma ()
void	graphene_euler_to_vec3 ()
void	graphene_euler_to_matrix ()
void	graphene_euler_to_quaternion ()
void	graphene_euler_reorder ()

Types and Values

	graphene_euler_t
enum	graphene_euler_order_t

Includes

#include <graphene.h>

Description

The graphene_euler_t structure defines a rotation along three axes using three angles. It also optionally can describe the order of the rotations.

Euler's rotation theorem states that, in three-dimensional space, any displacement of a rigid body such that a point on the rigid body remains fixed, is equivalent to a single rotation about some axis that runs through the fixed point. The angles on each axis can be placed in a vector of three components—α, β, and γ—called the *Euler angle vector*. Each rotation described by these components results in a rotation matrix:

1
2
3

rot(α) = A
rot(β) = B
rot(γ) = G

The resulting rotation matrix expressed by the Euler angle vector is given by the product of each rotation matrix:

1	G × B × A = R

In order to specify the meaning of an Euler angle vector, we need to assign each axis of rotation to the corresponding α, β, and γ components, for instance X, Y, and Z.

Additionally, we need to specify whether the rotations move the axes as they are applied, also known as intrinsic, or relative rotations; or if the axes stay fixed and the vectors move within the axis frame, also known as extrinsic, or static rotations. For instance, a static rotation alongside the ZYX axes will be interpreted as relative to extrinsic coordinate axes, and be performed, in order, about the Z, Y, and finally X axis. A relative rotation alongside the ZXZ axes will be interpreted as relative to intrinsic coordinate axes, and be performed, in order, about the Z axis, about the rotated X axis, and finally about the rotated Z axis.

Finally, we need to define the direction of the rotation, or the handedness of the coordinate system. In the case of Graphene, the direction is given by the right-hand rule, which means all rotations are counterclockwise.

Rotations described Euler angles are typically immediately understandable, compared to rotations expressed using quaternions, but they are susceptible of "Gimbal lock" — the loss of one degree of freedom caused by two axis on the same plane. You typically should use graphene_euler_t to expose rotation angles in your API, or to store them, but use graphene_quaternion_t to apply rotations to modelview matrices, or interpolate between initial and final rotation transformations.

For more information, see:

http://en.wikipedia.org/wiki/Rotation_matrix
http://en.wikipedia.org/wiki/Euler_angles
http://mathworld.wolfram.com/EulerAngles.html
"Representing Attitude with Euler Angles and Quaternions: A Reference" by James Diebel, 2006
"Graphics Gems IV", edited by Paul Heckbert, Academic Press, 1994.

Functions

graphene_euler_alloc ()

graphene_euler_t *
graphene_euler_alloc (void);

Allocates a new graphene_euler_t.

The contents of the returned structure are undefined.

[constructor]

Returns

the newly allocated graphene_euler_t.

[transfer full]

Since: 1.2

graphene_euler_free ()

void
graphene_euler_free (graphene_euler_t *e);

Frees the resources allocated by graphene_euler_alloc().

Parameters

a graphene_euler_t

Since: 1.2

graphene_euler_init ()

graphene_euler_t *
graphene_euler_init (graphene_euler_t *e,
                     float x,
                     float y,
                     float z);

Initializes a graphene_euler_t using the given angles.

The order of the rotations is GRAPHENE_EULER_ORDER_DEFAULT.

Parameters

e	the graphene_euler_t to initialize
x	rotation angle on the X axis, in degrees
y	rotation angle on the Y axis, in degrees
z	rotation angle on the Z axis, in degrees

Returns

the initialized graphene_euler_t.

[transfer none]

Since: 1.2

graphene_euler_init_with_order ()

graphene_euler_t *
graphene_euler_init_with_order (graphene_euler_t *e,
                                float x,
                                float y,
                                float z,
                                graphene_euler_order_t order);

Initializes a graphene_euler_t with the given angles and order .

Parameters

e	the graphene_euler_t to initialize
x	rotation angle on the X axis, in degrees
y	rotation angle on the Y axis, in degrees
z	rotation angle on the Z axis, in degrees
order	the order used to apply the rotations

Returns

the initialized graphene_euler_t.

[transfer none]

Since: 1.2

graphene_euler_init_from_matrix ()

graphene_euler_t *
graphene_euler_init_from_matrix (graphene_euler_t *e,
                                 const graphene_matrix_t *m,
                                 graphene_euler_order_t order);

Initializes a graphene_euler_t using the given rotation matrix.

If the graphene_matrix_t m is NULL, the graphene_euler_t will be initialized with all angles set to 0.

Parameters

e	the graphene_euler_t to initialize
m	a rotation matrix.	[nullable]
order	the order used to apply the rotations

Returns

the initialized graphene_euler_t.

[transfer none]

Since: 1.2

graphene_euler_init_from_quaternion ()

graphene_euler_t *
graphene_euler_init_from_quaternion (graphene_euler_t *e,
                                     const graphene_quaternion_t *q,
                                     graphene_euler_order_t order);

Initializes a graphene_euler_t using the given normalized quaternion.

If the graphene_quaternion_t q is NULL, the graphene_euler_t will be initialized with all angles set to 0.

Parameters

e	a graphene_euler_t
q	a normalized graphene_quaternion_t.	[nullable]
order	the order used to apply the rotations

Returns

the initialized graphene_euler_t.

[transfer none]

Since: 1.2

graphene_euler_init_from_vec3 ()

graphene_euler_t *
graphene_euler_init_from_vec3 (graphene_euler_t *e,
                               const graphene_vec3_t *v,
                               graphene_euler_order_t order);

Initializes a graphene_euler_t using the angles contained in a graphene_vec3_t.

If the graphene_vec3_t v is NULL, the graphene_euler_t will be initialized with all angles set to 0.

Parameters

e	the graphene_euler_t to initialize
v	a graphene_vec3_t containing the rotation angles in degrees.	[nullable]
order	the order used to apply the rotations

Returns

the initialized graphene_euler_t.

[transfer none]

Since: 1.2

graphene_euler_init_from_euler ()

graphene_euler_t *
graphene_euler_init_from_euler (graphene_euler_t *e,
                                const graphene_euler_t *src);

Initializes a graphene_euler_t using the angles and order of another graphene_euler_t.

If the graphene_euler_t src is NULL, this function is equivalent to calling graphene_euler_init() with all angles set to 0.

Parameters

e	the graphene_euler_t to initialize
src	a graphene_euler_t.	[nullable]

Returns

the initialized graphene_euler_t.

[transfer none]

Since: 1.2

graphene_euler_init_from_radians ()

graphene_euler_t *
graphene_euler_init_from_radians (graphene_euler_t *e,
                                  float x,
                                  float y,
                                  float z,
                                  graphene_euler_order_t order);

Initializes a graphene_euler_t using the given angles and order of rotation.

Parameters

e	the graphene_euler_t to initialize
x	rotation angle on the X axis, in radians
y	rotation angle on the Y axis, in radians
z	rotation angle on the Z axis, in radians
order	order of rotations

Returns

the initialized graphene_euler_t.

[transfer none]

Since: 1.10

graphene_euler_equal ()

bool
graphene_euler_equal (const graphene_euler_t *a,
                      const graphene_euler_t *b);

Checks if two graphene_euler_t are equal.

Parameters

a	a graphene_euler_t
b	a graphene_euler_t

Returns

true if the two graphene_euler_t are equal

Since: 1.2

graphene_euler_get_x ()

float
graphene_euler_get_x (const graphene_euler_t *e);

Retrieves the rotation angle on the X axis, in degrees.

Parameters

a graphene_euler_t

Returns

the rotation angle

Since: 1.2

graphene_euler_get_y ()

float
graphene_euler_get_y (const graphene_euler_t *e);

Retrieves the rotation angle on the Y axis, in degrees.

Parameters

a graphene_euler_t

Returns

the rotation angle

Since: 1.2

graphene_euler_get_z ()

float
graphene_euler_get_z (const graphene_euler_t *e);

Retrieves the rotation angle on the Z axis, in degrees.

Parameters

a graphene_euler_t

Returns

the rotation angle

Since: 1.2

graphene_euler_get_order ()

graphene_euler_order_t
graphene_euler_get_order (const graphene_euler_t *e);

Retrieves the order used to apply the rotations described in the graphene_euler_t structure, when converting to and from other structures, like graphene_quaternion_t and graphene_matrix_t.

This function does not return the GRAPHENE_EULER_ORDER_DEFAULT enumeration value; it will return the effective order of rotation instead.

Parameters

a graphene_euler_t

Returns

the order used to apply the rotations

Since: 1.2

graphene_euler_get_alpha ()

float
graphene_euler_get_alpha (const graphene_euler_t *e);

Retrieves the first component of the Euler angle vector, depending on the order of rotation.

Parameters

a graphene_euler_t

Returns

the first component of the Euler angle vector, in radians

Since: 1.10

graphene_euler_get_beta ()

float
graphene_euler_get_beta (const graphene_euler_t *e);

Retrieves the second component of the Euler angle vector, depending on the order of rotation.

Parameters

a graphene_euler_t

Returns

the second component of the Euler angle vector, in radians

Since: 1.10

graphene_euler_get_gamma ()

float
graphene_euler_get_gamma (const graphene_euler_t *e);

Retrieves the third component of the Euler angle vector, depending on the order of rotation.

Parameters

a graphene_euler_t

Returns

the third component of the Euler angle vector, in radians

Since: 1.10

graphene_euler_to_vec3 ()

void
graphene_euler_to_vec3 (const graphene_euler_t *e,
                        graphene_vec3_t *res);

Retrieves the angles of a graphene_euler_t and initializes a graphene_vec3_t with them.

Parameters

e	a graphene_euler_t
res	return location for a graphene_vec3_t.	[out caller-allocates]

Since: 1.2

graphene_euler_to_matrix ()

void
graphene_euler_to_matrix (const graphene_euler_t *e,
                          graphene_matrix_t *res);

Converts a graphene_euler_t into a transformation matrix expressing the extrinsic composition of rotations described by the Euler angles.

The rotations are applied over the reference frame axes in the order associated with the graphene_euler_t; for instance, if the order used to initialize e is GRAPHENE_EULER_ORDER_XYZ:

the first rotation moves the body around the X axis with an angle φ
the second rotation moves the body around the Y axis with an angle of ϑ
the third rotation moves the body around the Z axis with an angle of ψ

The rotation sign convention is right-handed, to preserve compatibility between Euler-based, quaternion-based, and angle-axis-based rotations.

Parameters

e	a graphene_euler_t
res	return location for a graphene_matrix_t.	[out caller-allocates]

Since: 1.2

graphene_euler_to_quaternion ()

void
graphene_euler_to_quaternion (const graphene_euler_t *e,
                              graphene_quaternion_t *res);

Converts a graphene_euler_t into a graphene_quaternion_t.

Parameters

e	a graphene_euler_t
res	return location for a graphene_quaternion_t.	[out caller-allocates]

Since: 1.10

graphene_euler_reorder ()

void
graphene_euler_reorder (const graphene_euler_t *e,
                        graphene_euler_order_t order,
                        graphene_euler_t *res);

Reorders a graphene_euler_t using order .

This function is equivalent to creating a graphene_quaternion_t from the given graphene_euler_t, and then converting the quaternion into another graphene_euler_t.

Parameters

e	a graphene_euler_t
order	the new order
res	return location for the reordered graphene_euler_t.	[out caller-allocates]

Since: 1.2

Types and Values

graphene_euler_t

typedef struct {
} graphene_euler_t;

Describe a rotation using Euler angles.

The contents of the graphene_euler_t structure are private and should never be accessed directly.

Since: 1.2

enum graphene_euler_order_t

Specify the order of the rotations on each axis.

The GRAPHENE_EULER_ORDER_DEFAULT value is special, and is used as an alias for one of the other orders.

Members

GRAPHENE_EULER_ORDER_DEFAULT	Rotate in the default order; the default order is one of the following enumeration values
GRAPHENE_EULER_ORDER_XYZ	Rotate in the X, Y, and Z order. Deprecated in Graphene 1.10, it's an alias for `GRAPHENE_EULER_ORDER_SXYZ`
GRAPHENE_EULER_ORDER_YZX	Rotate in the Y, Z, and X order. Deprecated in Graphene 1.10, it's an alias for `GRAPHENE_EULER_ORDER_SYZX`
GRAPHENE_EULER_ORDER_ZXY	Rotate in the Z, X, and Y order. Deprecated in Graphene 1.10, it's an alias for `GRAPHENE_EULER_ORDER_SZXY`
GRAPHENE_EULER_ORDER_XZY	Rotate in the X, Z, and Y order. Deprecated in Graphene 1.10, it's an alias for `GRAPHENE_EULER_ORDER_SXZY`
GRAPHENE_EULER_ORDER_YXZ	Rotate in the Y, X, and Z order. Deprecated in Graphene 1.10, it's an alias for `GRAPHENE_EULER_ORDER_SYXZ`
GRAPHENE_EULER_ORDER_ZYX	Rotate in the Z, Y, and X order. Deprecated in Graphene 1.10, it's an alias for `GRAPHENE_EULER_ORDER_SZYX`
GRAPHENE_EULER_ORDER_SXYZ	Defines a static rotation along the X, Y, and Z axes (Since: 1.10)
GRAPHENE_EULER_ORDER_SXYX	Defines a static rotation along the X, Y, and X axes (Since: 1.10)
GRAPHENE_EULER_ORDER_SXZY	Defines a static rotation along the X, Z, and Y axes (Since: 1.10)
GRAPHENE_EULER_ORDER_SXZX	Defines a static rotation along the X, Z, and X axes (Since: 1.10)
GRAPHENE_EULER_ORDER_SYZX	Defines a static rotation along the Y, Z, and X axes (Since: 1.10)
GRAPHENE_EULER_ORDER_SYZY	Defines a static rotation along the Y, Z, and Y axes (Since: 1.10)
GRAPHENE_EULER_ORDER_SYXZ	Defines a static rotation along the Y, X, and Z axes (Since: 1.10)
GRAPHENE_EULER_ORDER_SYXY	Defines a static rotation along the Y, X, and Y axes (Since: 1.10)
GRAPHENE_EULER_ORDER_SZXY	Defines a static rotation along the Z, X, and Y axes (Since: 1.10)
GRAPHENE_EULER_ORDER_SZXZ	Defines a static rotation along the Z, X, and Z axes (Since: 1.10)
GRAPHENE_EULER_ORDER_SZYX	Defines a static rotation along the Z, Y, and X axes (Since: 1.10)
GRAPHENE_EULER_ORDER_SZYZ	Defines a static rotation along the Z, Y, and Z axes (Since: 1.10)
GRAPHENE_EULER_ORDER_RZYX	Defines a relative rotation along the Z, Y, and X axes (Since: 1.10)
GRAPHENE_EULER_ORDER_RXYX	Defines a relative rotation along the X, Y, and X axes (Since: 1.10)
GRAPHENE_EULER_ORDER_RYZX	Defines a relative rotation along the Y, Z, and X axes (Since: 1.10)
GRAPHENE_EULER_ORDER_RXZX	Defines a relative rotation along the X, Z, and X axes (Since: 1.10)
GRAPHENE_EULER_ORDER_RXZY	Defines a relative rotation along the X, Z, and Y axes (Since: 1.10)
GRAPHENE_EULER_ORDER_RYZY	Defines a relative rotation along the Y, Z, and Y axes (Since: 1.10)
GRAPHENE_EULER_ORDER_RZXY	Defines a relative rotation along the Z, X, and Y axes (Since: 1.10)
GRAPHENE_EULER_ORDER_RYXY	Defines a relative rotation along the Y, X, and Y axes (Since: 1.10)
GRAPHENE_EULER_ORDER_RYXZ	Defines a relative rotation along the Y, X, and Z axes (Since: 1.10)
GRAPHENE_EULER_ORDER_RZXZ	Defines a relative rotation along the Z, X, and Z axes (Since: 1.10)
GRAPHENE_EULER_ORDER_RXYZ	Defines a relative rotation along the X, Y, and Z axes (Since: 1.10)
GRAPHENE_EULER_ORDER_RZYZ	Defines a relative rotation along the Z, Y, and Z axes (Since: 1.10)

Since: 1.2