Inherits from NSObject
Declared in NGLQuaternion.h

Overview

Quaternion is a complex number used to make rotations in a 3D space avoiding the Gimbal Lock issue.

There is a great polemic around the quaternions and euler angles about 3D rotations. In the NinevehGL the quaternion is THE class of rotations, because here quaternions can does much more than just rotate a matrix.

NGLQuaternion is the first class in the NinevehGL’s Render Chain to use cache. The cache concept in NinevehGL means that the render’s performance will be boosted to compute each 3D change individually. By doing so, only some parts of the entire rendering will be updated and submitted to the core of OpenGL.

Besides, the NGLQuaternion can easily manage and convert global and local rotations. It even can work with Euler angles or vector as input to rotations. NGLQuaternion is fast and could be performed thousand, even millions times at each frame with no impacts to the frame rate.

Set the quaternion using the a vector axis is better. But if you need to set 3 times (one for each x,y,z coordinate) is advisable to use the euler angles, because the number of multiplications to construct the final quaternion will be less.

Tasks

Properties

angle

The the angle that compound this NGLQuaternion.

@property (nonatomic, readonly) float angle

Discussion

The the angle that compound this NGLQuaternion.

Declared In

NGLQuaternion.h

axis

The vector value of this NGLQuaternion.

@property (nonatomic, readonly) NGLvec3 axis

Discussion

The vector value of this NGLQuaternion.

Declared In

NGLQuaternion.h

euler

Returns the Euler representation of this NGLQuaternion. The returning values will be in degrees and with a range of -180º to 180º.

@property (nonatomic, readonly) NGLvec3 euler

Discussion

Returns the Euler representation of this NGLQuaternion. The returning values will be in degrees and with a range of -180º to 180º.

Declared In

NGLQuaternion.h

matrix

Returns a pointer to the equivalent matrix based on this quaternion object. The returning matrix is:

@property (nonatomic, readonly) NGLmat4 *matrix

Discussion

Returns a pointer to the equivalent matrix based on this quaternion object. The returning matrix is:

  • Orthogonal matrix;
  • Right hand oriented;
  • Ordered by Euler Rotation order (Y,Z,X)

The full formula is:


|w²+x²-y²-z²      2xy-2zw         2xz+2yw       0|
| 2xy+2zw       w²-x²+y²-z²       2yz-2xw       0|
| 2xz-2yw         2yz+2xw       w²-x²-y²+z²     0|
|    0               0               0          1|

As 3D rotation just need unit quaternions, the matrix could be optimized to:


|1-2y²-2z²        2xy-2zw         2xz+2yw       0|
| 2xy+2zw        1-2x²-2z²        2yz-2xw       0|
| 2xz-2yw         2yz+2xw        1-2x²-2y²      0|
|    0               0               0          1|

Declared In

NGLQuaternion.h

Instance Methods

identity

Resets the current quaternion to the identity quaternion.

- (void)identity

Discussion

Resets the current quaternion to the identity quaternion.

The identity quaternion means a rotation of 0 in three axis. The identity quaternion results generates identity matrix.

Declared In

NGLQuaternion.h

invert

Inverts the current quaternion.

- (void)invert

Discussion

Inverts the current quaternion.

This operations is also known as “conjugate quaternion”.

Declared In

NGLQuaternion.h

rotateByAxis:angle:mode:

Adds a new rotation to the current quaternion according to the mode.

- (void)rotateByAxis:(NGLvec3)vec angle:(float)degrees mode:(NGLAddMode)mode

Parameters

vec

A vector representing the rotation in 3D space. This axis is the direction of the rotation.

degrees

The angle to make the rotation in degrees.

mode

The mode in which the new rotation will be assigned.

Discussion

Adds a new rotation to the current quaternion according to the mode.

The new rotation is defined by a vector and an angle of rotation around its own pivot.

Declared In

NGLQuaternion.h

rotateByEuler:mode:

rotateByEuler:mode:

- (void)rotateByEuler:(NGLvec3)vec mode:(NGLAddMode)mode

Parameters

vec

A vector containing the X, Y and Z values to the rotation. These values need to be in degrees.

mode

The mode in which the new rotation will be assigned.

Discussion

rotateByEuler:mode:

Adds a new rotation to the current quaternion according to the mode.

The new rotation is defined by a vector representing the Euler Rotation. The order of rotation will be the Euler Rotation Order (Y,Z,X).

This method is slightly more expensive than rotateByAxis:angle:mode: method.

Declared In

NGLQuaternion.h

rotateByMatrix:mode:

Adds a new rotation to the current quaternion according to the mode.

- (void)rotateByMatrix:(NGLmat4)mat mode:(NGLAddMode)mode

Parameters

mat

A matrix (4x4) containing the rotation values.

mode

The mode in which the new rotation will be assigned.

Discussion

Adds a new rotation to the current quaternion according to the mode.

The new rotation is defined by an orthogonal matrix. Only the rotation elements will be used from the matrix.

Declared In

NGLQuaternion.h

rotateByQuaternionVector:mode:

Adds a new rotation to the current quaternion according to the mode.

- (void)rotateByQuaternionVector:(NGLvec4)quaternion mode:(NGLAddMode)mode

Parameters

quaternion

The components are in order X, Y, Z and W, the W is also known as “angle”.

mode

The mode in which the new rotation will be assigned.

Discussion

Adds a new rotation to the current quaternion according to the mode.

The values will be normalized to follow the quaternion rules, even if they are already normalized.

Declared In

NGLQuaternion.h