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

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

• 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()`.

 e

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 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 [nullable]

#### Returns

the initialized graphene_euler_t.

[transfer none]

Since: 1.2

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

 a b

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

 e

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

 e

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

 e

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

 e

#### 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()`

 e

#### 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()`

 e

#### 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()`

 e

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