Cogl.Quaternion

Fields

Name

Type

Access

Description

padding0

float

r

padding1

float

r

padding2

float

r

padding3

float

r

w

float

r/w

based on the angle of rotation it is cos(𝜃/2)

x

float

r/w

based on the angle of rotation and x component of the axis of rotation it is sin(𝜃/2)*axis.x

y

float

r/w

based on the angle of rotation and y component of the axis of rotation it is sin(𝜃/2)*axis.y

z

float

r/w

based on the angle of rotation and z component of the axis of rotation it is sin(𝜃/2)*axis.z

Methods

class

equal (v1, v2)

copy ()

dot_product (b)

free ()

get_rotation_angle ()

get_rotation_axis ()

init (angle, x, y, z)

init_from_angle_vector (angle, axis3f)

init_from_array (array)

init_from_euler (euler)

init_from_matrix (matrix)

init_from_quaternion (src)

init_from_x_rotation (angle)

init_from_y_rotation (angle)

init_from_z_rotation (angle)

init_identity ()

invert ()

multiply (left, right)

nlerp (a, b, t)

normalize ()

pow (exponent)

slerp (a, b, t)

squad (prev, a, b, next, t)

Details

class Cogl.Quaternion

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 [w (x, y, z)].

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:

[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:

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

and a unit quaternion satisfies this equation:

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:

classmethod equal(v1, v2)
Parameters:
Returns:

True if the quaternions are equal else False.

Return type:

int

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.

New in version 2.0.

copy()
Returns:

A newly allocated Cogl.Quaternion which should be freed using Cogl.Quaternion.free()

Return type:

Cogl.Quaternion

Allocates a new Cogl.Quaternion on the stack and initializes it with the same values as self.

New in version 2.0.

dot_product(b)
Parameters:

b (Cogl.Quaternion) – A Cogl.Quaternion

Return type:

float

New in version 2.0.

free()

Frees a Cogl.Quaternion that was previously allocated via Cogl.Quaternion.copy().

New in version 2.0.

get_rotation_angle()
Return type:

float

New in version 2.0.

get_rotation_axis()
Returns:

an allocated 3-float array

Return type:

vector3: float

New in version 2.0.

init(angle, x, y, z)
Parameters:

  • angle (float) – The angle you want to rotate around the given axis

  • x (float) – The x component of your axis vector about which you want to rotate.

  • y (float) – The y component of your axis vector about which you want to rotate.

  • z (float) – The z component of your axis vector about which you want to rotate.

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

New in version 2.0.

init_from_angle_vector(angle, axis3f)
Parameters:

  • angle (float) – The angle to rotate around axis3f

  • axis3f (float) – your 3 component axis vector about which you want to rotate.

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

New in version 2.0.

init_from_array(array)
Parameters:

array (float) – An array of 4 floats w,(x,y,z)

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

New in version 2.0.

init_from_euler(euler)
Parameters:

euler (Cogl.Euler) – A Cogl.Euler with which to initialize the quaternion

New in version 2.0.

init_from_matrix(matrix)
Parameters:

matrix (Cogl.Matrix) – A rotation matrix with which to initialize the quaternion

Initializes a quaternion from a rotation matrix.

New in version 1.10.

init_from_quaternion(src)
Parameters:

src (Cogl.Quaternion) – A Cogl.Quaternion with which to initialize self

New in version 2.0.

init_from_x_rotation(angle)
Parameters:

angle (float) – The angle to rotate around the x axis

XXX: check which direction this rotates

New in version 2.0.

init_from_y_rotation(angle)
Parameters:

angle (float) – The angle to rotate around the y axis

New in version 2.0.

init_from_z_rotation(angle)
Parameters:

angle (float) – The angle to rotate around the z axis

New in version 2.0.

init_identity()

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

New in version 2.0.

invert()

New in version 2.0.

multiply(left, right)
Parameters:

This combines the rotations of two quaternions into self. 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.

It is possible to multiply the a quaternion in-place, so self can be equal to a but can’t be equal to b.

New in version 2.0.

nlerp(a, b, t)
Parameters:

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

normalize()

New in version 2.0.

pow(exponent)
Parameters:

exponent (float) – the exponent

New in version 2.0.

slerp(a, b, t)
Parameters:

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

squad(prev, a, b, next, t)
Parameters:

New in version 2.0.