com.jogamp.opengl.math

Class Quaternion

• ```public class Quaternion
extends Object```
Quaternion implementation supporting Gimbal-Lock free rotations.

All matrix operation provided are in column-major order, as specified in the OpenGL fixed function pipeline, i.e. compatibility profile. See `FloatUtil`.

See Matrix-FAQ

• Field Summary

Fields
Modifier and Type Field and Description
`static float` `ALLOWED_DEVIANCE`
Quaternion Epsilon, used with equals method to determine if two Quaternions are close enough to be considered equal.
• Constructor Summary

Constructors
Constructor and Description
`Quaternion()`
```Quaternion(float x, float y, float z, float w)```
`Quaternion(Quaternion q)`
• Method Summary

Methods
Modifier and Type Method and Description
`Quaternion` `add(Quaternion q)`
`Quaternion` `conjugate()`
Conjugates this quaternion `[-x, -y, -z, w]`.
`float[]` ```copyMatrixColumn(int index, float[] result, int resultOffset)```
`float` ```dot(float x, float y, float z, float w)```
Returns the dot product of this quaternion with the given x,y,z and w components.
`float` `dot(Quaternion quat)`
Returns the dot product of this quaternion with the given quaternion
`boolean` `equals(Object o)`
`float` `getW()`
`float` `getX()`
`float` `getY()`
`float` `getZ()`
`int` `hashCode()`
`Quaternion` `invert()`
Invert the quaternion If rotational, will produce a the inverse rotation
`boolean` `isIdentity()`
Returns `true` if this quaternion has identity.
`boolean` `isRotationMatrix3f(float[] m)`
Check if the the 3x3 matrix (param) is in fact an affine rotational matrix
`float` `magnitude()`
Return the magnitude of this quaternion, i.e.
`float` `magnitudeSquared()`
See `magnitude()` for special handling of `epsilon`, which is not applied here.
`Quaternion` `mult(Quaternion q)`
Multiply this quaternion by the param quaternion
`Quaternion` `normalize()`
Normalize a quaternion required if to be used as a rotational quaternion.
`Quaternion` ```rotateByAngleNormalAxis(float angle, float axisX, float axisY, float axisZ)```
Rotate this quaternion by the given angle and axis.
`Quaternion` `rotateByAngleX(float angle)`
Rotate this quaternion around X axis with the given angle in radians
`Quaternion` `rotateByAngleY(float angle)`
Rotate this quaternion around Y axis with the given angle in radians
`Quaternion` `rotateByAngleZ(float angle)`
Rotate this quaternion around Z axis with the given angle in radians
`Quaternion` `rotateByEuler(float[] angradXYZ)`
Rotates this quaternion from the given Euler rotation array `angradXYZ` in radians.
`Quaternion` ```rotateByEuler(float bankX, float headingY, float attitudeZ)```
Rotates this quaternion from the given Euler rotation angles in radians.
`float[]` ```rotateVector(float[] vecOut, int vecOutOffset, float[] vecIn, int vecInOffset)```
Rotate the given vector by this quaternion
`Quaternion` `scale(float n)`
Scale this quaternion by a constant
`Quaternion` ```set(float x, float y, float z, float w)```
Set all values of this quaternion using the given components.
`Quaternion` `set(Quaternion src)`
Set all values of this quaternion using the given src.
`Quaternion` ```setFromAngleAxis(float angle, float[] vector, float[] tmpV3f)```
Initialize this quaternion with given non-normalized axis vector and rotation angle
`Quaternion` ```setFromAngleNormalAxis(float angle, float[] vector)```
Initialize this quaternion with given normalized axis vector and rotation angle
`Quaternion` ```setFromAxes(float[] xAxis, float[] yAxis, float[] zAxis)```
Initializes this quaternion to represent a rotation formed by the given three orthogonal axes.
`Quaternion` `setFromEuler(float[] angradXYZ)`
Initializes this quaternion from the given Euler rotation array `angradXYZ` in radians.
`Quaternion` ```setFromEuler(float bankX, float headingY, float attitudeZ)```
Initializes this quaternion from the given Euler rotation angles in radians.
`Quaternion` ```setFromMatrix(float[] m, int m_off)```
Initializes this quaternion from a 4x4 column rotation matrix
`Quaternion` ```setFromMatrix(float m00, float m01, float m02, float m10, float m11, float m12, float m20, float m21, float m22)```
Compute the quaternion from a 3x3 column rotation matrix
`Quaternion` ```setFromNormalVectors(float[] v1, float[] v2, float[] tmpPivotVec)```
Initialize this quaternion from two normalized vectors
`Quaternion` ```setFromVectors(float[] v1, float[] v2, float[] tmpPivotVec, float[] tmpNormalVec)```
Initialize this quaternion from two vectors
`Quaternion` `setIdentity()`
Set this quaternion to identity (x=0,y=0,z=0,w=1)
`Quaternion` ```setLookAt(float[] directionIn, float[] upIn, float[] xAxisOut, float[] yAxisOut, float[] zAxisOut)```
Set this quaternion to equal the rotation required to point the z-axis at direction and the y-axis to up.
`Quaternion` ```setSlerp(Quaternion a, Quaternion b, float changeAmnt)```
Set this quaternion to a spherical linear interpolation between the given start and end quaternions by the given change amount.
`void` `setW(float w)`
`void` `setX(float x)`
`void` `setY(float y)`
`void` `setZ(float z)`
`Quaternion` `subtract(Quaternion q)`
Subtract a quaternion
`float` `toAngleAxis(float[] axis)`
Transform the rotational quaternion to axis based rotation angles
`void` ```toAxes(float[] xAxis, float[] yAxis, float[] zAxis, float[] tmpMat4)```
Extracts this quaternion's orthogonal rotation axes.
`float[]` `toEuler(float[] result)`
Transform this quaternion to Euler rotation angles in radians (pitchX, yawY and rollZ).
`float[]` ```toMatrix(float[] matrix, int mat_offset)```
Transform this quaternion to a normalized 4x4 column matrix representing the rotation.
`String` `toString()`
• Methods inherited from class java.lang.Object

`getClass, notify, notifyAll, wait, wait, wait`
• Field Detail

• ALLOWED_DEVIANCE

`public static final float ALLOWED_DEVIANCE`
Quaternion Epsilon, used with equals method to determine if two Quaternions are close enough to be considered equal.

Using 9.999999974752427E-7f, which is ~10 times `FloatUtil.EPSILON`.

Constant Field Values
• Constructor Detail

• Quaternion

`public Quaternion()`
• Quaternion

`public Quaternion(Quaternion q)`
• Quaternion

```public Quaternion(float x,
float y,
float z,
float w)```
• Method Detail

• magnitudeSquared

`public final float magnitudeSquared()`
See `magnitude()` for special handling of `epsilon`, which is not applied here.
Returns:
the squared magnitude of this quaternion.
• getW

`public final float getW()`
• setW

`public final void setW(float w)`
• getX

`public final float getX()`
• setX

`public final void setX(float x)`
• getY

`public final float getY()`
• setY

`public final void setY(float y)`
• getZ

`public final float getZ()`
• setZ

`public final void setZ(float z)`
• dot

```public final float dot(float x,
float y,
float z,
float w)```
Returns the dot product of this quaternion with the given x,y,z and w components.
• dot

`public final float dot(Quaternion quat)`
Returns the dot product of this quaternion with the given quaternion
• setIdentity

`public final Quaternion setIdentity()`
Set this quaternion to identity (x=0,y=0,z=0,w=1)
Returns:
this quaternion for chaining.
• normalize

`public final Quaternion normalize()`
Normalize a quaternion required if to be used as a rotational quaternion.

Implementation Details:

Returns:
this quaternion for chaining.
• conjugate

`public Quaternion conjugate()`
Conjugates this quaternion `[-x, -y, -z, w]`.
Returns:
this quaternion for chaining.
Matrix-FAQ Q49
• invert

`public final Quaternion invert()`
Invert the quaternion If rotational, will produce a the inverse rotation

Implementation Details:

Returns:
this quaternion for chaining.
Matrix-FAQ Q50
• set

`public final Quaternion set(Quaternion src)`
Set all values of this quaternion using the given src.
Returns:
this quaternion for chaining.
• set

```public final Quaternion set(float x,
float y,
float z,
float w)```
Set all values of this quaternion using the given components.
Returns:
this quaternion for chaining.

`public final Quaternion add(Quaternion q)`
Parameters:
`q` - quaternion
Returns:
this quaternion for chaining.
• subtract

`public final Quaternion subtract(Quaternion q)`
Subtract a quaternion
Parameters:
`q` - quaternion
Returns:
this quaternion for chaining.
• mult

`public final Quaternion mult(Quaternion q)`
Multiply this quaternion by the param quaternion
Parameters:
`q` - a quaternion to multiply with
Returns:
this quaternion for chaining.
Matrix-FAQ Q53, euclideanspace.com-QuaternionMul
• scale

`public final Quaternion scale(float n)`
Scale this quaternion by a constant
Parameters:
`n` - a float constant
Returns:
this quaternion for chaining.
euclideanspace.com-QuaternionScale
• rotateByAngleNormalAxis

```public Quaternion rotateByAngleNormalAxis(float angle,
float axisX,
float axisY,
float axisZ)```
Rotate this quaternion by the given angle and axis.

The axis must be a normalized vector.

A rotational quaternion is made from the given angle and axis.

Parameters:
`angle` - in radians
`axisX` - x-coord of rotation axis
`axisY` - y-coord of rotation axis
`axisZ` - z-coord of rotation axis
Returns:
this quaternion for chaining.
• rotateByAngleX

`public Quaternion rotateByAngleX(float angle)`
Rotate this quaternion around X axis with the given angle in radians
Parameters:
`angle` - in radians
Returns:
this quaternion for chaining.
• rotateByAngleY

`public Quaternion rotateByAngleY(float angle)`
Rotate this quaternion around Y axis with the given angle in radians
Parameters:
`angle` - in radians
Returns:
this quaternion for chaining.
• rotateByAngleZ

`public Quaternion rotateByAngleZ(float angle)`
Rotate this quaternion around Z axis with the given angle in radians
Parameters:
`angle` - in radians
Returns:
this quaternion for chaining.
• rotateByEuler

`public final Quaternion rotateByEuler(float[] angradXYZ)`
Rotates this quaternion from the given Euler rotation array `angradXYZ` in radians.

The `angradXYZ` array is laid out in natural order:

• x - bank
• z - attitude

For details see `rotateByEuler(float, float, float)`.
Parameters:
`angradXYZ` - euler angel array in radians
Returns:
this quaternion for chaining.
`rotateByEuler(float, float, float)`
• rotateVector

```public final float[] rotateVector(float[] vecOut,
int vecOutOffset,
float[] vecIn,
int vecInOffset)```
Rotate the given vector by this quaternion
Parameters:
`vecOut` - result float[3] storage for rotated vector, maybe equal to vecIn for in-place rotation
`vecOutOffset` - offset in result storage
`vecIn` - float[3] vector to be rotated
`vecInOffset` - offset in vecIn
Returns:
the given vecOut store for chaining
Matrix-FAQ Q63
• setSlerp

```public final Quaternion setSlerp(Quaternion a,
Quaternion b,
float changeAmnt)```
Set this quaternion to a spherical linear interpolation between the given start and end quaternions by the given change amount.

Note: Method does not normalize this quaternion!

Parameters:
`a` - start quaternion
`b` - end quaternion
`changeAmnt` - float between 0 and 1 representing interpolation.
Returns:
this quaternion for chaining.
euclideanspace.com-QuaternionSlerp
• setLookAt

```public Quaternion setLookAt(float[] directionIn,
float[] upIn,
float[] xAxisOut,
float[] yAxisOut,
float[] zAxisOut)```
Set this quaternion to equal the rotation required to point the z-axis at direction and the y-axis to up.

Implementation generates a 3x3 matrix and is equal with ProjectFloat's lookAt(..).

Implementation Details:

Parameters:
`directionIn` - where to look at
`upIn` - a vector indicating the local up direction.
`xAxisOut` - vector storing the orthogonal x-axis of the coordinate system.
`yAxisOut` - vector storing the orthogonal y-axis of the coordinate system.
`zAxisOut` - vector storing the orthogonal z-axis of the coordinate system.
Returns:
this quaternion for chaining.
euclideanspace.com-LookUp
• setFromVectors

```public final Quaternion setFromVectors(float[] v1,
float[] v2,
float[] tmpPivotVec,
float[] tmpNormalVec)```
Initialize this quaternion from two vectors
```   q = (s,v) = (v1•v2 , v1 × v2),
angle = angle(v1, v2) = v1•v2
axis = normal(v1 x v2)
```

Implementation Details:

Parameters:
`v1` - not normalized
`v2` - not normalized
`tmpPivotVec` - float[3] temp storage for cross product
`tmpNormalVec` - float[3] temp storage to normalize vector
Returns:
this quaternion for chaining.
• setFromNormalVectors

```public final Quaternion setFromNormalVectors(float[] v1,
float[] v2,
float[] tmpPivotVec)```
Initialize this quaternion from two normalized vectors
```   q = (s,v) = (v1•v2 , v1 × v2),
angle = angle(v1, v2) = v1•v2
axis = v1 x v2
```

Implementation Details:

Parameters:
`v1` - normalized
`v2` - normalized
`tmpPivotVec` - float[3] temp storage for cross product
Returns:
this quaternion for chaining.
• setFromAngleAxis

```public final Quaternion setFromAngleAxis(float angle,
float[] vector,
float[] tmpV3f)```
Initialize this quaternion with given non-normalized axis vector and rotation angle

Implementation Details:

Parameters:
`angle` - rotation angle (rads)
`vector` - axis vector not normalized
`tmpV3f` - float[3] temp storage to normalize vector
Returns:
this quaternion for chaining.
Matrix-FAQ Q56, `toAngleAxis(float[])`
• toAngleAxis

`public final float toAngleAxis(float[] axis)`
Transform the rotational quaternion to axis based rotation angles
Parameters:
`axis` - float[3] storage for computed axis
Returns:
`setFromAngleAxis(float, float[], float[])`
• setFromEuler

`public final Quaternion setFromEuler(float[] angradXYZ)`
Initializes this quaternion from the given Euler rotation array `angradXYZ` in radians.

The `angradXYZ` array is laid out in natural order:

• x - bank
• z - attitude

For details see `setFromEuler(float, float, float)`.
Parameters:
`angradXYZ` - euler angel array in radians
Returns:
this quaternion for chaining.
`setFromEuler(float, float, float)`
• toEuler

`public float[] toEuler(float[] result)`
Transform this quaternion to Euler rotation angles in radians (pitchX, yawY and rollZ).
Parameters:
`result` - the float[] array storing the computed angles.
Returns:
the double[] array, filled with heading, attitude and bank in that order..
euclideanspace.com-quaternionToEuler, `setFromEuler(float, float, float)`
• setFromMatrix

```public final Quaternion setFromMatrix(float[] m,
int m_off)```
Initializes this quaternion from a 4x4 column rotation matrix

Buggy Matrix-FAQ Q55

Parameters:
`m` - 4x4 column matrix
Returns:
this quaternion for chaining.
`toMatrix(float[], int)`
• setFromMatrix

```public Quaternion setFromMatrix(float m00,
float m01,
float m02,
float m10,
float m11,
float m12,
float m20,
float m21,
float m22)```
Compute the quaternion from a 3x3 column rotation matrix

Buggy Matrix-FAQ Q55

Returns:
this quaternion for chaining.
`toMatrix(float[], int)`
• copyMatrixColumn

```public float[] copyMatrixColumn(int index,
float[] result,
int resultOffset)```
Parameters:
`index` - the 3x3 rotation matrix column to retrieve from this quaternion (normalized). Must be between 0 and 2.
`result` - the vector object to store the result in.
Returns:
the result column-vector for chaining.
• setFromAxes

```public final Quaternion setFromAxes(float[] xAxis,
float[] yAxis,
float[] zAxis)```
Initializes this quaternion to represent a rotation formed by the given three orthogonal axes.

No validation whether the axes are orthogonal is performed.

Parameters:
`xAxis` - vector representing the orthogonal x-axis of the coordinate system.
`yAxis` - vector representing the orthogonal y-axis of the coordinate system.
`zAxis` - vector representing the orthogonal z-axis of the coordinate system.
Returns:
this quaternion for chaining.
• toAxes

```public void toAxes(float[] xAxis,
float[] yAxis,
float[] zAxis,
float[] tmpMat4)```
Extracts this quaternion's orthogonal rotation axes.
Parameters:
`xAxis` - vector representing the orthogonal x-axis of the coordinate system.
`yAxis` - vector representing the orthogonal y-axis of the coordinate system.
`zAxis` - vector representing the orthogonal z-axis of the coordinate system.
`tmpMat4` - temporary float[4] matrix, used to transform this quaternion to a matrix.
• isRotationMatrix3f

`public final boolean isRotationMatrix3f(float[] m)`
Check if the the 3x3 matrix (param) is in fact an affine rotational matrix
Parameters:
`m` - 3x3 column matrix
Returns:
true if representing a rotational matrix, false otherwise
• equals

`public boolean equals(Object o)`
Overrides:
`equals` in class `Object`
Parameters:
`o` - the object to compare for equality
Returns:
true if this quaternion and the provided quaternion have roughly the same x, y, z and w values.
• hashCode

`public final int hashCode()`
Overrides:
`hashCode` in class `Object`
• toString

`public String toString()`
Overrides:
`toString` in class `Object`