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.

See also: graphene_quaternion_t.

## 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

e | 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

e | 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

e | 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

e | 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

e | 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.

See also: `graphene_euler_get_x()`

#### Parameters

e | 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.

See also: `graphene_euler_get_y()`

#### Parameters

e | 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.

See also: `graphene_euler_get_z()`

#### Parameters

e | 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