Quaternion

Quaternion — Quaternion operations

Functions

Types and Values

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

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

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

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

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

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

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

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, and returns the conjugate quaternion of q .

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

void
graphene_quaternion_add (const graphene_quaternion_t *a,
                         const graphene_quaternion_t *b,
                         graphene_quaternion_t *res);

Adds two graphene_quaternion_t a and b .

Parameters

a

a graphene_quaternion_t

 

b

a graphene_quaternion_t

 

res

the result of the operation.

[out caller-allocates]

Since: 1.10


graphene_quaternion_multiply ()

void
graphene_quaternion_multiply (const graphene_quaternion_t *a,
                              const graphene_quaternion_t *b,
                              graphene_quaternion_t *res);

Multiplies two graphene_quaternion_t a and b .

Parameters

a

a graphene_quaternion_t

 

b

a graphene_quaternion_t

 

res

the result of the operation.

[out caller-allocates]

Since: 1.10


graphene_quaternion_scale ()

void
graphene_quaternion_scale (const graphene_quaternion_t *q,
                           float factor,
                           graphene_quaternion_t *res);

Scales all the elements of a graphene_quaternion_t q using the given scalar factor.

Parameters

q

a graphene_quaternion_t

 

factor

a scaling factor

 

res

the result of the operation.

[out caller-allocates]

Since: 1.10


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