Quaternion: Graphene Reference Manual

## Quaternion Quaternion — Quaternion operations |

## Functions

graphene_quaternion_t * | graphene_quaternion_alloc ()
void | graphene_quaternion_free ()
graphene_quaternion_t * | graphene_quaternion_init ()
graphene_quaternion_t * | graphene_quaternion_init_identity ()
graphene_quaternion_t * | graphene_quaternion_init_from_quaternion ()
graphene_quaternion_t * | graphene_quaternion_init_from_vec4 ()
graphene_quaternion_t * | graphene_quaternion_init_from_matrix ()
graphene_quaternion_t * | graphene_quaternion_init_from_angles ()
graphene_quaternion_t * | graphene_quaternion_init_from_radians ()
graphene_quaternion_t * | graphene_quaternion_init_from_angle_vec3 ()
graphene_quaternion_t * | graphene_quaternion_init_from_euler ()
void | graphene_quaternion_to_vec4 ()
void | graphene_quaternion_to_matrix ()
void | graphene_quaternion_to_angles ()
void | graphene_quaternion_to_radians ()
void | graphene_quaternion_to_angle_vec3 ()
bool | graphene_quaternion_equal ()
float | graphene_quaternion_dot ()
void | graphene_quaternion_invert ()
void | graphene_quaternion_normalize ()
void | graphene_quaternion_slerp ()

## Types and Values

| graphene_quaternion_t

## Includes

    #include <graphene.h>

## Description

Quaternions are a mathematical entity that can be used to represent rotation transformations in 3D space; unlike the usual Euler representation with roll, pitch, and yaw, quaternions do not suffer from the so-called "Gimbal Lock" problem.

See also: graphene_euler_t

## Functions

### graphene_quaternion_alloc ()

    graphene_quaternion_t *
    graphene_quaternion_alloc (void);

Allocates a new graphene_quaternion_t.

The contents of the returned value are undefined.

[constructor]

#### Returns

the newly allocated graphene_quaternion_t.

[transfer full]

Since: 1.0

### graphene_quaternion_free ()

    void
    graphene_quaternion_free (graphene_quaternion_t *q);

Releases the resources allocated by `graphene_quaternion_alloc()`.

#### Parameters

q | a graphene_quaternion_t |

Since: 1.0

### graphene_quaternion_init ()

    graphene_quaternion_t *
    graphene_quaternion_init (graphene_quaternion_t *q,
                              float x,
                              float y,
                              float z,
                              float w);

Initializes a graphene_quaternion_t using the given four values.

#### Parameters

q | a graphene_quaternion_t |
x | the first component of the quaternion |
y | the second component of the quaternion |
z | the third component of the quaternion |
w | the fourth component of the quaternion |

#### Returns

the initialized quaternion.

[transfer none]

Since: 1.0

### graphene_quaternion_init_identity ()

    graphene_quaternion_t *
    graphene_quaternion_init_identity (graphene_quaternion_t *q);

Initializes a graphene_quaternion_t using the identity transformation.

#### Parameters

q | a graphene_quaternion_t |

#### Returns

the initialized quaternion.

[transfer none]

Since: 1.0

### graphene_quaternion_init_from_quaternion ()

    graphene_quaternion_t *
    graphene_quaternion_init_from_quaternion
                                   (graphene_quaternion_t *q,
                                    const graphene_quaternion_t *src);

Initializes a graphene_quaternion_t with the values from `src` .

#### Parameters

q | a graphene_quaternion_t |
src | a graphene_quaternion_t |

#### Returns

the initialized quaternion.

[transfer none]

Since: 1.0

### graphene_quaternion_init_from_vec4 ()

    graphene_quaternion_t *
    graphene_quaternion_init_from_vec4 (graphene_quaternion_t *q,
                                        const graphene_vec4_t *src);

Initializes a graphene_quaternion_t with the values from `src` .

#### Parameters

q | a graphene_quaternion_t |
src | a graphene_vec4_t |

#### Returns

the initialized quaternion.

[transfer none]

Since: 1.0

### graphene_quaternion_init_from_matrix ()

    graphene_quaternion_t *
    graphene_quaternion_init_from_matrix (graphene_quaternion_t *q,
                                          const graphene_matrix_t *m);

Initializes a graphene_quaternion_t using the rotation components of a transformation matrix.

#### Parameters

q | a graphene_quaternion_t |
m | a graphene_matrix_t |

#### Returns

the initialized quaternion.

[transfer none]

Since: 1.0

### graphene_quaternion_init_from_angles ()

    graphene_quaternion_t *
    graphene_quaternion_init_from_angles (graphene_quaternion_t *q,
                                          float deg_x,
                                          float deg_y,
                                          float deg_z);

Initializes a graphene_quaternion_t using the values of the Euler angles on each axis.

See also: `graphene_quaternion_init_from_euler()`

#### Parameters

q | a graphene_quaternion_t |
deg_x | rotation angle on the X axis (yaw), in degrees |
deg_y | rotation angle on the Y axis (pitch), in degrees |
deg_z | rotation angle on the Z axis (roll), in degrees |

#### Returns

the initialized quaternion.

[transfer none]

Since: 1.0

### graphene_quaternion_init_from_radians ()

    graphene_quaternion_t *
    graphene_quaternion_init_from_radians (graphene_quaternion_t *q,
                                           float rad_x,
                                           float rad_y,
                                           float rad_z);

Initializes a graphene_quaternion_t using the values of the Euler angles on each axis.

See also: `graphene_quaternion_init_from_euler()`

#### Parameters

q | a graphene_quaternion_t |
rad_x | rotation angle on the X axis (yaw), in radians |
rad_y | rotation angle on the Y axis (pitch), in radians |
rad_z | rotation angle on the Z axis (roll), in radians |

#### Returns

the initialized quaternion.

[transfer none]

Since: 1.0

### graphene_quaternion_init_from_angle_vec3 ()

    graphene_quaternion_t *
    graphene_quaternion_init_from_angle_vec3
                                   (graphene_quaternion_t *q,
                                    float angle,
                                    const graphene_vec3_t *axis);

Initializes a graphene_quaternion_t using an `angle` on a specific `axis` .

#### Parameters

q | a graphene_quaternion_t |
angle | the rotation on a given axis, in degrees |
axis | the axis of rotation, expressed as a vector |

#### Returns

the initialized quaternion.

[transfer none]

Since: 1.0

### graphene_quaternion_init_from_euler ()

    graphene_quaternion_t *
    graphene_quaternion_init_from_euler (graphene_quaternion_t *q,
                                         const graphene_euler_t *e);

Initializes a graphene_quaternion_t using the given graphene_euler_t.

#### Parameters

q | the graphene_quaternion_t to initialize |
e | a graphene_euler_t |

#### Returns

the initialized graphene_quaternion_t.

[transfer none]

Since: 1.2

### graphene_quaternion_to_vec4 ()

    void
    graphene_quaternion_to_vec4 (const graphene_quaternion_t *q,
                                 graphene_vec4_t *res);

Copies the components of a graphene_quaternion_t into a graphene_vec4_t.

#### Parameters

q | a graphene_quaternion_t |
res | return location for a graphene_vec4_t. | [out caller-allocates]

Since: 1.0

### graphene_quaternion_to_matrix ()

    void
    graphene_quaternion_to_matrix (const graphene_quaternion_t *q,
                                   graphene_matrix_t *m);

Converts a quaternion into a transformation matrix expressing the rotation defined by the graphene_quaternion_t.

#### Parameters

q | a graphene_quaternion_t |
m | a graphene_matrix_t. | [out caller-allocates]

Since: 1.0

### graphene_quaternion_to_angles ()

    void
    graphene_quaternion_to_angles (const graphene_quaternion_t *q,
                                   float *deg_x,
                                   float *deg_y,
                                   float *deg_z);

Converts a graphene_quaternion_t to its corresponding rotations on the Euler angles on each axis.

#### Parameters

q | a graphene_quaternion_t |
deg_x | return location for the rotation angle on the X axis (yaw), in degrees. | [out][optional]
deg_y | return location for the rotation angle on the Y axis (pitch), in degrees. | [out][optional]
deg_z | return location for the rotation angle on the Z axis (roll), in degrees. | [out][optional]

Since: 1.2

### graphene_quaternion_to_radians ()

    void
    graphene_quaternion_to_radians (const graphene_quaternion_t *q,
                                    float *rad_x,
                                    float *rad_y,
                                    float *rad_z);

Converts a graphene_quaternion_t to its corresponding rotations on the Euler angles on each axis.

#### Parameters

q | a graphene_quaternion_t |
rad_x | return location for the rotation angle on the X axis (yaw), in radians. | [out][optional]
rad_y | return location for the rotation angle on the Y axis (pitch), in radians. | [out][optional]
rad_z | return location for the rotation angle on the Z axis (roll), in radians. | [out][optional]

Since: 1.2

### graphene_quaternion_to_angle_vec3 ()

    void
    graphene_quaternion_to_angle_vec3 (const graphene_quaternion_t *q,
                                       float *angle,
                                       graphene_vec3_t *axis);

Converts a quaternion into an `angle` , `axis` pair.

#### Parameters

q | a graphene_quaternion_t |
angle | return location for the angle, in degrees. | [out]
axis | return location for the rotation axis. | [out caller-allocates]

Since: 1.0

### graphene_quaternion_equal ()

    bool
    graphene_quaternion_equal (const graphene_quaternion_t *a,
                               const graphene_quaternion_t *b);

Checks whether the given quaternions are equal.

#### Parameters

a | a graphene_quaternion_t |
b | a graphene_quaternion_t |

#### Returns

`true` if the quaternions are equal

Since: 1.0

### graphene_quaternion_dot ()

    float
    graphene_quaternion_dot (const graphene_quaternion_t *a,
                             const graphene_quaternion_t *b);

Computes the dot product of two graphene_quaternion_t.

#### Parameters

a | a graphene_quaternion_t |
b | a graphene_quaternion_t |

#### Returns

the value of the dot products

Since: 1.0

### graphene_quaternion_invert ()

    void
    graphene_quaternion_invert (const graphene_quaternion_t *q,
                                graphene_quaternion_t *res);

Inverts a graphene_quaternion_t.

#### Parameters

q | a graphene_quaternion_t |
res | return location for the inverted quaternion. | [out caller-allocates]

Since: 1.0

### graphene_quaternion_normalize ()

    void
    graphene_quaternion_normalize (const graphene_quaternion_t *q,
                                   graphene_quaternion_t *res);

Normalizes a graphene_quaternion_t.

#### Parameters

q | a graphene_quaternion_t |
res | return location for the normalized quaternion. | [out caller-allocates]

Since: 1.0

### graphene_quaternion_slerp ()

    void
    graphene_quaternion_slerp (const graphene_quaternion_t *a,
                               const graphene_quaternion_t *b,
                               float factor,
                               graphene_quaternion_t *res);

Interpolates between the two given quaternions using a spherical linear interpolation, or SLERP, using the given interpolation `factor` .

#### Parameters

a | a graphene_quaternion_t |
b | a graphene_quaternion_t |
factor | the linear interpolation factor |
res | return location for the interpolated quaternion. | [out caller-allocates]

Since: 1.0

## Types and Values

### graphene_quaternion_t

    typedef struct {
    } graphene_quaternion_t;

A quaternion.

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

Since: 1.0