Quaternion (JOGL API -- 2.3 Specification)

java.lang.Object
- com.jogamp.opengl.math.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

See euclideanspace.com-Quaternion

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)

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)` Add a quaternion
`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.
    
    See Also:
    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.
  - magnitude
```
public final float magnitude()
```
    Return the magnitude of this quaternion, i.e. sqrt(magnitude())
    A magnitude of zero shall equal identity, as performed by normalize().
    
    Implementation Details:
    - returns 0f if magnitudeSquared() is is zero using epsilon
    - returns 1f if magnitudeSquared() is equals 1f using epsilon
  - 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
  - isIdentity
```
public final boolean isIdentity()
```
    Returns true if this quaternion has identity.
    Implementation uses epsilon to compare W against 1f and X, Y and Z against zero.
  - 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:
    - setIdentity() if magnitude() is is zero using epsilon
    Returns:
    this quaternion for chaining.
  - conjugate
```
public Quaternion conjugate()
```
    Conjugates this quaternion [-x, -y, -z, w].
    
    Returns:
    this quaternion for chaining.
    See Also:
    Matrix-FAQ Q49
  - invert
```
public final Quaternion invert()
```
    Invert the quaternion If rotational, will produce a the inverse rotation
    Implementation Details:
    - conjugates if magnitudeSquared() is is equals 1f using epsilon
    Returns:
    this quaternion for chaining.
    See Also:
    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.
  - add
```
public final Quaternion add(Quaternion q)
```
    Add a quaternion
    
    Parameters:
    q - quaternion
    
    Returns:
    this quaternion for chaining.
    See Also:
    euclideanspace.com-QuaternionAdd
  - subtract
```
public final Quaternion subtract(Quaternion q)
```
    Subtract a quaternion
    
    Parameters:
    q - quaternion
    
    Returns:
    this quaternion for chaining.
    See Also:
    euclideanspace.com-QuaternionAdd
  - 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.
    See Also:
    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.
    See Also:
    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
    - y - heading
    - z - attitude
    For details see rotateByEuler(float, float, float).
    Parameters:
    angradXYZ - euler angel array in radians
    
    Returns:
    this quaternion for chaining.
    See Also:
    rotateByEuler(float, float, float)
  - rotateByEuler
```
public final Quaternion rotateByEuler(float bankX,
                       float headingY,
                       float attitudeZ)
```
    Rotates this quaternion from the given Euler rotation angles in radians.
    The rotations are applied in the given order and using chained rotation per axis:
    - y - heading - rotateByAngleY(float)
    - z - attitude - rotateByAngleZ(float)
    - x - bank - rotateByAngleX(float)
    Implementation Details:
    - NOP if all angles are is zero using epsilon
    - result is normalize()ed
    Parameters:
    bankX - the Euler pitch angle in radians. (rotation about the X axis)
    headingY - the Euler yaw angle in radians. (rotation about the Y axis)
    attitudeZ - the Euler roll angle in radians. (rotation about the Z axis)
    
    Returns:
    this quaternion for chaining.
    See Also:
    rotateByAngleY(float), rotateByAngleZ(float), rotateByAngleX(float), setFromEuler(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
    See Also:
    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.
    See Also:
    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:
    - result is normalize()ed
    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.
    See Also:
    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:
    - setIdentity() if square vector-length is is zero using epsilon
    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:
    - setIdentity() if square vector-length is is zero using epsilon
    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:
    - setIdentity() if axis is is zero using epsilon
    Parameters:
    angle - rotation angle (rads)
    vector - axis vector not normalized
    tmpV3f - float[3] temp storage to normalize vector
    
    Returns:
    this quaternion for chaining.
    See Also:
    Matrix-FAQ Q56, toAngleAxis(float[])
  - setFromAngleNormalAxis
```
public final Quaternion setFromAngleNormalAxis(float angle,
                                float[] vector)
```
    Initialize this quaternion with given normalized axis vector and rotation angle
    Implementation Details:
    - setIdentity() if axis is is zero using epsilon
    Parameters:
    angle - rotation angle (rads)
    vector - axis vector normalized
    
    Returns:
    this quaternion for chaining.
    See Also:
    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:
    the rotation angle in radians
    See Also:
    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
    - y - heading
    - z - attitude
    For details see setFromEuler(float, float, float).
    Parameters:
    angradXYZ - euler angel array in radians
    
    Returns:
    this quaternion for chaining.
    See Also:
    setFromEuler(float, float, float)
  - setFromEuler
```
public final Quaternion setFromEuler(float bankX,
                      float headingY,
                      float attitudeZ)
```
    Initializes this quaternion from the given Euler rotation angles in radians.
    The rotations are applied in the given order:
    - y - heading
    - z - attitude
    - x - bank
    Implementation Details:
    - setIdentity() if all angles are is zero using epsilon
    - result is normalize()ed
    Parameters:
    bankX - the Euler pitch angle in radians. (rotation about the X axis)
    headingY - the Euler yaw angle in radians. (rotation about the Y axis)
    attitudeZ - the Euler roll angle in radians. (rotation about the Z axis)
    
    Returns:
    this quaternion for chaining.
    See Also:
    Matrix-FAQ Q60, Gems, euclideanspace.com-eulerToQuaternion, toEuler(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..
    See Also:
    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
    See Graphics Gems Code,
    MatrixTrace.
    
    Buggy Matrix-FAQ Q55
    
    Parameters:
    m - 4x4 column matrix
    
    Returns:
    this quaternion for chaining.
    See Also:
    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
    See Graphics Gems Code,
    MatrixTrace.
    
    Buggy Matrix-FAQ Q55
    
    Returns:
    this quaternion for chaining.
    See Also:
    toMatrix(float[], int)
  - toMatrix
```
public final float[] toMatrix(float[] matrix,
               int mat_offset)
```
    Transform this quaternion to a normalized 4x4 column matrix representing the rotation.
    Implementation Details:
    - makes identity matrix if magnitudeSquared() is is zero using epsilon
    Parameters:
    matrix - float[16] store for the resulting normalized column matrix 4x4
    mat_offset -
    
    Returns:
    the given matrix store
    See Also:
    Matrix-FAQ Q54, setFromMatrix(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

Class Quaternion

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

ALLOWED_DEVIANCE

Constructor Detail

Quaternion

Quaternion

Quaternion

Method Detail

magnitudeSquared

magnitude

getW

setW

getX

setX

getY

setY

getZ

setZ

dot

dot

isIdentity

setIdentity

normalize

conjugate

invert

set

set

add

subtract

mult

scale

rotateByAngleNormalAxis

rotateByAngleX

rotateByAngleY

rotateByAngleZ

rotateByEuler

rotateByEuler

rotateVector

setSlerp

setLookAt

setFromVectors

setFromNormalVectors

setFromAngleAxis

setFromAngleNormalAxis

toAngleAxis

setFromEuler

setFromEuler

toEuler

setFromMatrix

setFromMatrix

toMatrix

copyMatrixColumn

setFromAxes

toAxes

isRotationMatrix3f

equals

hashCode

toString