com.jogamp.opengl.math

## Class Quaternion

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

  - ### 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`

Copyright 2010 JogAmp Community.