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 ()
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 ()
void | graphene_euler_to_vec3 ()
void | graphene_euler_to_matrix ()
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 axis using three angles. It also optionally can describe the order of the rotations.

Rotations described Euler angles are 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.

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_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_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 left-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_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 |
GRAPHENE_EULER_ORDER_YZX | Rotate in the Y, Z, and X order |
GRAPHENE_EULER_ORDER_ZXY | Rotate in the Z, X, and Y order |
GRAPHENE_EULER_ORDER_XZY | Rotate in the X, Z, and Y order |
GRAPHENE_EULER_ORDER_YXZ | Rotate in the Y, X, and Z order |
GRAPHENE_EULER_ORDER_ZYX | Rotate in the Z, Y, and X order |

Since: 1.2