## Quaternions (Rotations)

Quaternions (Rotations) — Functions for initializing and manipulating quaternions.

## Synopsis

                        CoglQuaternion;
    void                cogl_quaternion_init_identity       (CoglQuaternion *quaternion);
    void                cogl_quaternion_init                (CoglQuaternion *quaternion,
                                                             float angle,
                                                             float x,
                                                             float y,
                                                             float z);
    void                cogl_quaternion_init_from_angle_vector
                                                            (CoglQuaternion *quaternion,
                                                             float angle,
                                                             const CoglVector3 *axis);
    void                cogl_quaternion_init_from_array     (CoglQuaternion *quaternion,
                                                             const float *array);
    void                cogl_quaternion_init_from_x_rotation
                                                            (CoglQuaternion *quaternion,
                                                             float angle);
    void                cogl_quaternion_init_from_y_rotation
                                                            (CoglQuaternion *quaternion,
                                                             float angle);
    void                cogl_quaternion_init_from_z_rotation
                                                            (CoglQuaternion *quaternion,
                                                             float angle);
    gboolean            cogl_quaternion_equal               (gconstpointer v1,
                                                             gconstpointer v2);
    CoglQuaternion *    cogl_quaternion_copy                (const CoglQuaternion *src);
    void                cogl_quaternion_free                (CoglQuaternion *quaternion);
    float               cogl_quaternion_get_rotation_angle  (const CoglQuaternion *quaternion);
    void                cogl_quaternion_get_rotation_axis   (const CoglQuaternion *quaternion,
                                                             CoglVector3 *vector);
    void                cogl_quaternion_normalize           (CoglQuaternion *quaternion);
    float               cogl_quaternion_dot_product         (const CoglQuaternion *a,
                                                             const CoglQuaternion *b);
    void                cogl_quaternion_invert              (CoglQuaternion *quaternion);
    void                cogl_quaternion_multiply            (CoglQuaternion *result,
                                                             const CoglQuaternion *left,
                                                             const CoglQuaternion *right);
    void                cogl_quaternion_pow                 (CoglQuaternion *quaternion,
                                                             float exponent);
    void                cogl_quaternion_slerp               (CoglQuaternion *result,
                                                             const CoglQuaternion *a,
                                                             const CoglQuaternion *b,
                                                             float t);
    void                cogl_quaternion_nlerp               (CoglQuaternion *result,
                                                             const CoglQuaternion *a,
                                                             const CoglQuaternion *b,
                                                             float t);
    void                cogl_quaternion_squad               (CoglQuaternion *result,
                                                             const CoglQuaternion *prev,
                                                             const CoglQuaternion *a,
                                                             const CoglQuaternion *b,
                                                             const CoglQuaternion *next,
                                                             float t);
    const CoglQuaternion * cogl_get_static_identity_quaternion
                                                            (void);
    const CoglQuaternion * cogl_get_static_zero_quaternion  (void);

## Description

Quaternions have become a standard form for representing 3D rotations and have some nice properties when compared with other representation such as (roll,pitch,yaw) Euler angles. They can be used to interpolate between different rotations and they don't suffer from a problem called "Gimbal lock" where two of the axis of rotation may become aligned and you loose a degree of freedom. (http://en.wikipedia.org/wiki/Gimbal_lock).

## Details

### CoglQuaternion

    typedef struct {
      float w;

      float x;
      float y;
      float z;

      float padding0;
      float padding1;
      float padding2;
      float padding3;
    } CoglQuaternion;

A quaternion is comprised of a scalar component and a 3D vector component. The scalar component is normally referred to as w and the vector might either be referred to as v or a (for axis) or expanded with the individual components: (x, y, z) A full quaternion would then be written as <pre>[w (x, y, z)]</pre>.

Quaternions can be considered to represent an axis and angle pair although sadly these numbers are buried somewhat under some maths...

For the curious you can see here that a given axis (a) and angle (𝜃) pair are represented in a quaternion as follows:

    1

    [w=cos(𝜃/2) ( x=sin(𝜃/2)*a.x, y=sin(𝜃/2)*a.y, z=sin(𝜃/2)*a.x )]

Unit Quaternions: When using Quaternions to represent spatial orientations for 3D graphics it's always assumed you have a unit quaternion. The magnitude of a quaternion is defined as:

    1

    sqrt (w² + x² + y² + z²)

and a unit quaternion satisfies this equation:

    1

    w² + x² + y² + z² = 1

Thankfully most of the time we don't actually have to worry about the maths that goes on behind the scenes but if you are curious to learn more here are some external references:

- http://mathworld.wolfram.com/Quaternion.html
- http://www.gamedev.net/reference/articles/article1095.asp
- http://www.cprogramming.com/tutorial/3d/quaternions.html
- http://www.isner.com/tutorials/quatSpells/quaternion_spells_12.htm
- 3D Maths Primer for Graphics and Game Development ISBN-10: 1556229119
- http://www.cs.caltech.edu/courses/cs171/quatut.pdf
- http://www.j3d.org/matrix_faq/matrfaq_latest.html#Q56

@w: based on the angle of rotation it is cos(𝜃/2) @x: based on the angle of rotation and x component of the axis of rotation it is sin(𝜃/2)*axis.x @y: based on the angle of rotation and y component of the axis of rotation it is sin(𝜃/2)*axis.y @z: based on the angle of rotation and z component of the axis of rotation it is sin(𝜃/2)*axis.z

### cogl_quaternion_init_identity ()

    void                cogl_quaternion_init_identity       (CoglQuaternion *quaternion);

Initializes the quaternion with the canonical quaternion identity [1 (0, 0, 0)] which represents no rotation. Multiplying a quaternion with this identity leaves the quaternion unchanged.

You might also want to consider using `cogl_get_static_identity_quaternion()`.

`quaternion` : | An uninitialized CoglQuaternion

Since 2.0

### cogl_quaternion_init ()

    void                cogl_quaternion_init                (CoglQuaternion *quaternion,
                                                             float angle,
                                                             float x,
                                                             float y,
                                                             float z);

Initializes a quaternion that rotates `angle` degrees around the axis vector (`x`, `y`, `z`). The axis vector does not need to be normalized.

`quaternion` : | An uninitialized CoglQuaternion
`angle` : | The angle you want to rotate around the given axis
`x` : | The x component of your axis vector about which you want to rotate.
`y` : | The y component of your axis vector about which you want to rotate.
`z` : | The z component of your axis vector about which you want to rotate.
Returns : | A normalized, unit quaternion representing an orientation rotated `angle` degrees around the axis vector (`x`, `y`, `z`)

Since 2.0

### cogl_quaternion_init_from_angle_vector ()

    void                cogl_quaternion_init_from_angle_vector
                                                            (CoglQuaternion *quaternion,
                                                             float angle,
                                                             const CoglVector3 *axis);

Initializes a quaternion that rotates `angle` degrees around the given `axis` vector. The axis vector does not need to be normalized.

`quaternion` : | An uninitialized CoglQuaternion
`axis` : | your axis vector about which you want to rotate.
Returns : | A normalized, unit quaternion representing an orientation rotated `angle` degrees around the given `axis` vector.

Since 2.0

### cogl_quaternion_init_from_array ()

    void                cogl_quaternion_init_from_array     (CoglQuaternion *quaternion,
                                                             const float *array);

Initializes a [w (x, y,z)] quaternion directly from an array of 4 floats: [w,x,y,z].

`quaternion` : | A CoglQuaternion
`array` : | An array of 4 floats (x,y,z),w

Since 2.0

### cogl_quaternion_init_from_x_rotation ()

    void                cogl_quaternion_init_from_x_rotation
                                                            (CoglQuaternion *quaternion,
                                                             float angle);

XXX: check which direction this rotates

`quaternion` : | An uninitialized CoglQuaternion
`angle` : | The angle to rotate around the x axis

Since 2.0

### cogl_quaternion_init_from_y_rotation ()

    void                cogl_quaternion_init_from_y_rotation
                                                            (CoglQuaternion *quaternion,
                                                             float angle);

`quaternion` : | An uninitialized CoglQuaternion
`angle` : | The angle to rotate around the y axis

Since 2.0

### cogl_quaternion_init_from_z_rotation ()

    void                cogl_quaternion_init_from_z_rotation
                                                            (CoglQuaternion *quaternion,
                                                             float angle);

`quaternion` : | An uninitialized CoglQuaternion
`angle` : | The angle to rotate around the y axis

Since 2.0

### cogl_quaternion_equal ()

    gboolean            cogl_quaternion_equal               (gconstpointer v1,
                                                             gconstpointer v2);

Compares that all the components of quaternions `a` and `b` are equal.

An epsilon value is not used to compare the float components, but the == operator is at least used so that 0 and -0 are considered equal.

`v1` : | A CoglQuaternion
`v2` : | A CoglQuaternion
Returns : | `TRUE` if the quaternions are equal else `FALSE`.

Since 2.0

### cogl_quaternion_copy ()

    CoglQuaternion *    cogl_quaternion_copy                (const CoglQuaternion *src);

Allocates a new CoglQuaternion on the stack and initializes it with the same values as `src`.

`src` : | A CoglQuaternion
Returns : | A newly allocated CoglQuaternion which should be freed using `cogl_quaternion_free()`

Since 2.0

### cogl_quaternion_free ()

    void                cogl_quaternion_free                (CoglQuaternion *quaternion);

Frees a CoglQuaternion that was previously allocated via `cogl_quaternion_copy()`.

`quaternion` : | A CoglQuaternion

Since 2.0

### cogl_quaternion_get_rotation_angle ()

    float               cogl_quaternion_get_rotation_angle  (const CoglQuaternion *quaternion);

`quaternion` : | A CoglQuaternion

Since 2.0

### cogl_quaternion_get_rotation_axis ()

    void                cogl_quaternion_get_rotation_axis   (const CoglQuaternion *quaternion,
                                                             CoglVector3 *vector);

`quaternion` : | A CoglQuaternion

Since 2.0

### cogl_quaternion_normalize ()

    void                cogl_quaternion_normalize           (CoglQuaternion *quaternion);

`quaternion` : | A CoglQuaternion

Since 2.0

### cogl_quaternion_dot_product ()

    float               cogl_quaternion_dot_product         (const CoglQuaternion *a,
                                                             const CoglQuaternion *b);

`quaternion` : | A CoglQuaternion

Since 2.0

### cogl_quaternion_invert ()

    void                cogl_quaternion_invert              (CoglQuaternion *quaternion);

`quaternion` : | A CoglQuaternion

Since 2.0

### cogl_quaternion_multiply ()

    void                cogl_quaternion_multiply            (CoglQuaternion *result,
                                                             const CoglQuaternion *left,
                                                             const CoglQuaternion *right);

This combines the rotations of two quaternions into `result`. The operation is not commutative so the order is important because AxB != BxA. Cogl follows the standard convention for quaternions here so the rotations are applied `right` to `left`. This is similar to the combining of matrices.

`result` : | The destination CoglQuaternion
`left` : | The second CoglQuaternion rotation to apply
`right` : | The first CoglQuaternion rotation to apply

Since 2.0

### cogl_quaternion_pow ()

    void                cogl_quaternion_pow                 (CoglQuaternion *quaternion,
                                                             float exponent);

`quaternion` : | A CoglQuaternion

Since 2.0

### cogl_quaternion_slerp ()

    void                cogl_quaternion_slerp               (CoglQuaternion *result,
                                                             const CoglQuaternion *a,
                                                             const CoglQuaternion *b,
                                                             float t);

Performs a spherical linear interpolation between two quaternions.

Noteable properties:

- commutative: No
- constant velocity: Yes
- torque minimal (travels along the surface of the 4-sphere): Yes
- more expensive than `cogl_quaternion_nlerp()`

### cogl_quaternion_nlerp ()

    void                cogl_quaternion_nlerp               (CoglQuaternion *result,
                                                             const CoglQuaternion *a,
                                                             const CoglQuaternion *b,
                                                             float t);

Performs a normalized linear interpolation between two quaternions. That is it does a linear interpolation of the quaternion components and then normalizes the result. This will follow the shortest arc between the two orientations (just like the `slerp()` function) but will not progress at a constant speed. Unlike `slerp()` nlerp is commutative which is useful if you are blending animations together. (I.e. nlerp (tmp, a, b) followed by nlerp (result, tmp, d) is the same as nlerp (tmp, a, d) followed by nlerp (result, tmp, b)). Finally nlerp is cheaper than slerp so it can be a good choice if you don't need the constant speed property of the `slerp()` function.

Notable properties:

- commutative: Yes
- constant velocity: No
- torque minimal (travels along the surface of the 4-sphere): Yes
- faster than `cogl_quaternion_slerp()`

`result` : | The destination CoglQuaternion
`a` : | The first CoglQuaternion
`b` : | The second CoglQuaternion
`t` : | The factor in the range [0,1] used to interpolate between quaterion `a` and `b`.

### cogl_quaternion_squad ()

    void                cogl_quaternion_squad               (CoglQuaternion *result,
                                                             const CoglQuaternion *prev,
                                                             const CoglQuaternion *a,
                                                             const CoglQuaternion *b,
                                                             const CoglQuaternion *next,
                                                             float t);

Since 2.0

### cogl_get_static_identity_quaternion ()

    const CoglQuaternion * cogl_get_static_identity_quaternion
                                                            (void);

Returns a pointer to a singleton quaternion constant describing the canonical identity [1 (0, 0, 0)] which represents no rotation.

If you multiply a quaternion with the identity quaternion you will get back the same value as the original quaternion.

Returns : | A pointer to an identity quaternion

Since 2.0

### cogl_get_static_zero_quaternion ()

    const CoglQuaternion * cogl_get_static_zero_quaternion  (void);

Returns : | a pointer to a singleton quaternion constant describing a rotation of 180 degrees around a degenerate axis: [0 (0, 0, 0)]

Since 2.0