NGLQuaternion Class Reference
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

angle
The the angle that compound this NGLQuaternion.
property 
axis
The vector value of this NGLQuaternion.
property 
euler
Returns the Euler representation of this NGLQuaternion. The returning values will be in degrees and with a range of 180º to 180º.
property 
matrix
Returns a pointer to the equivalent matrix based on this quaternion object. The returning matrix is:
property 
– identity
Resets the current quaternion to the identity quaternion.

– invert
Inverts the current quaternion.

– rotateByAxis:angle:mode:
Adds a new rotation to the current quaternion according to the mode.

– rotateByEuler:mode:
rotateByEuler:mode:

– rotateByMatrix:mode:
Adds a new rotation to the current quaternion according to the mode.

– rotateByQuaternionVector:mode:
Adds a new rotation to the current quaternion according to the mode.
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² 2xy2zw 2xz+2yw 0  2xy+2zw w²x²+y²z² 2yz2xw 0  2xz2yw 2yz+2xw w²x²y²+z² 0  0 0 0 1
As 3D rotation just need unit quaternions, the matrix could be optimized to:
12y²2z² 2xy2zw 2xz+2yw 0  2xy+2zw 12x²2z² 2yz2xw 0  2xz2yw 2yz+2xw 12x²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