Module com.github.stephengold.joltjni
Package com.github.stephengold.joltjni

Class Quat

java.lang.Object
com.github.stephengold.joltjni.Quat
All Implemented Interfaces:
QuatArg
public final class Quat extends Object implements QuatArg
A math object used to represent rotations and orientations in 3-dimensional space, without risk of gimbal lock. Each quaternion has 4 single-precision components: 3 imaginary ones (X, Y, and Z) and a real one (W).

Mathematically speaking, quaternions are an extension of complex numbers.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Quat()
    Instantiate an identity quaternion (0,0,0,1).
    Quat(float[] array)
    Instantiate a quaternion from the specified array.
    Quat(float x, float y, float z, float w)
    Instantiate a quaternion with specified components.
    Quat(QuatArg original)
    Instantiate a copy of the argument.
    Quat(Vec3Arg v, float w)
    Instantiate a quaternion based on a Vec3Arg.
    Quat(FloatBuffer buffer)
    Instantiate from a buffer.

  • Method Summary

    Modifier and Type
    Method
    Description
    Quat
    conjugated()
    Return the conjugate.
    float
    getW()
    Return the real (W) component in single precision.
    float
    getX()
    Return the first imaginary (X) component in single precision.
    float
    getY()
    Return the 2nd imaginary (Y) component in single precision.
    float
    getZ()
    Return the 3rd imaginary (Z) component in single precision.
    boolean
    isFinite()
    Test whether the quaternion contains infinities or NaNs.
    boolean
    isNormalized()
    Test whether the quaternion is normalized to within a tolerance of 10^-5.
    boolean
    isNormalized(float tolerance)
    Test whether the quaternion is normalized to within the specified tolerance.
    boolean
    isRotationIdentity()
    Test whether the quaternion represents an identity rotation.
    boolean
    isZero()
    Test whether the quaternion is zero.
    float
    length()
    Return the length.
    float
    lengthSq()
    Return the squared length.
    void
    loadIdentity()
    Set the current quaternion to identity.
    Quat
    normalized()
    Generate a normalized quaternion that represents the same rotation.
    void
    put(FloatBuffer storeBuffer)
    Write all 4 components to the specified buffer in XYZW order and advance the buffer's position by 4.
    Vec3
    rotateAxisX()
    Apply the rotation to (1,0,0).
    Vec3
    rotateAxisY()
    Apply the rotation to (0,1,0).
    Vec3
    rotateAxisZ()
    Apply the rotation to (0,0,1).
    void
    set(float[] array)
    Set all 4 components from the specified array.
    void
    set(float x, float y, float z, float w)
    Set all 4 components to specified values.
    void
    set(QuatArg source)
    Copy all 4 components from the argument.
    static Quat
    sEulerAngles(float x, float y, float z)
    Create a rotation quaternion from the specified Tait-Bryan angles, applying the rotations in x-y-z extrinsic order or z-y'-x" intrinsic order.
    static Quat
    sEulerAngles(Vec3Arg angles)
    Create a rotation quaternion from the specified Tait-Bryan angles, applying the rotations in x-y-z extrinsic order or z-y'-x" intrinsic order.
    static Quat
    sFromTo(Vec3Arg from, Vec3Arg to)
    Create a rotation quaternion that rotates from to to.
    static Quat
    sIdentity()
    Create an identity quaternion (0,0,0,1).
    static Quat
    sRandom(RandomNumberEngine engine)
    Generate a pseudo-random unit quaternion.
    static Quat
    sRotation(Vec3Arg axis, float angle)
    Create a rotation quaternion from a normalized rotation axis.
    String
    toString()
    Return a string representation of the quaternion, which is unaffected.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Constructor Details

    • Quat

      public Quat()
      Instantiate an identity quaternion (0,0,0,1).

    • Quat

      public Quat(float x, float y, float z, float w)
      Instantiate a quaternion with specified components.
      Parameters:
      x - the desired X component
      y - the desired Y component
      z - the desired Z component
      w - the desired W component

    • Quat

      public Quat(float[] array)
      Instantiate a quaternion from the specified array.
      Parameters:
      array - the desired component values (in XYZW order, not null, length≥4, unaffected)

    • Quat

      public Quat(FloatBuffer buffer)
      Instantiate from a buffer.
      Parameters:
      buffer - the desired component values (not null, unaffected, capacity≥4)

    • Quat

      public Quat(QuatArg original)
      Instantiate a copy of the argument.
      Parameters:
      original - the quaternion to copy (not null, unaffected)

    • Quat

      public Quat(Vec3Arg v, float w)
      Instantiate a quaternion based on a Vec3Arg.
      Parameters:
      v - the desired XYZ components
      w - the desired W component

  • Method Details

    • loadIdentity

      public void loadIdentity()
      Set the current quaternion to identity.

    • set

      public void set(float x, float y, float z, float w)
      Set all 4 components to specified values.
      Parameters:
      x - the desired X component
      y - the desired Y component
      z - the desired Z component
      w - the desired W component

    • set

      public void set(float[] array)
      Set all 4 components from the specified array.
      Parameters:
      array - the desired component values (in XYZW order, not null, length≥4, unaffected)

    • set

      public void set(QuatArg source)
      Copy all 4 components from the argument.
      Parameters:
      source - the quaternion to copy (not null, unaffected)

    • sEulerAngles

      public static Quat sEulerAngles(float x, float y, float z)
      Create a rotation quaternion from the specified Tait-Bryan angles, applying the rotations in x-y-z extrinsic order or z-y'-x" intrinsic order.
      Parameters:
      x - the desired rotation around the X axis (in radians)
      y - the desired rotation around the Y axis (in radians)
      z - the desired rotation around the Z axis (in radians)
      Returns:
      a new quaternion

    • sEulerAngles

      public static Quat sEulerAngles(Vec3Arg angles)
      Create a rotation quaternion from the specified Tait-Bryan angles, applying the rotations in x-y-z extrinsic order or z-y'-x" intrinsic order.
      Parameters:
      angles - the desired rotation around each axis (in radians, not null, unaffected)
      Returns:
      a new quaternion

    • sFromTo

      public static Quat sFromTo(Vec3Arg from, Vec3Arg to)
      Create a rotation quaternion that rotates from to to.
      Parameters:
      from - the first direction vector (not null, unaffected)
      to - the 2nd direction vector (not null, unaffected)
      Returns:
      a new quaternion

    • sIdentity

      public static Quat sIdentity()
      Create an identity quaternion (0,0,0,1).
      Returns:
      a new quaternion

    • sRandom

      public static Quat sRandom(RandomNumberEngine engine)
      Generate a pseudo-random unit quaternion.
      Parameters:
      engine - the generator to use (not null)
      Returns:
      a new unit quaternion

    • sRotation

      public static Quat sRotation(Vec3Arg axis, float angle)
      Create a rotation quaternion from a normalized rotation axis.
      Parameters:
      axis - the desired rotation axis (not null, normalized)
      angle - the desired rotation angle (in radians)
      Returns:
      a new quaternion

    • conjugated

      public Quat conjugated()
      Return the conjugate. The current object is unaffected.
      Specified by:
      conjugated in interface QuatArg
      Returns:
      a new object

    • getW

      public float getW()
      Return the real (W) component in single precision. The quaternion is unaffected.
      Specified by:
      getW in interface QuatArg
      Returns:
      the component value

    • getX

      public float getX()
      Return the first imaginary (X) component in single precision. The quaternion is unaffected.
      Specified by:
      getX in interface QuatArg
      Returns:
      the component value

    • getY

      public float getY()
      Return the 2nd imaginary (Y) component in single precision. The quaternion is unaffected.
      Specified by:
      getY in interface QuatArg
      Returns:
      the component value

    • getZ

      public float getZ()
      Return the 3rd imaginary (Z) component in single precision. The quaternion is unaffected.
      Specified by:
      getZ in interface QuatArg
      Returns:
      the component value

    • isFinite

      public boolean isFinite()
      Test whether the quaternion contains infinities or NaNs. The quaternion is unaffected.
      Specified by:
      isFinite in interface QuatArg
      Returns:
      false if one or more infinities or NaNs, otherwise true

    • isNormalized

      public boolean isNormalized()
      Test whether the quaternion is normalized to within a tolerance of 10^-5. The quaternion is unaffected.
      Specified by:
      isNormalized in interface QuatArg
      Returns:
      true if normalized, otherwise false

    • isNormalized

      public boolean isNormalized(float tolerance)
      Test whether the quaternion is normalized to within the specified tolerance. The quaternion is unaffected.
      Specified by:
      isNormalized in interface QuatArg
      Parameters:
      tolerance - the desired tolerance (default=1e-5)
      Returns:
      true if normalized, otherwise false

    • isRotationIdentity

      public boolean isRotationIdentity()
      Test whether the quaternion represents an identity rotation. The quaternion is unaffected.
      Specified by:
      isRotationIdentity in interface QuatArg
      Returns:
      true if the real component is a non-zero number and the imaginary components are all zero, otherwise false

    • isZero

      public boolean isZero()
      Test whether the quaternion is zero. The quaternion is unaffected.
      Specified by:
      isZero in interface QuatArg
      Returns:
      true if exactly zero, otherwise false

    • length

      public float length()
      Return the length. The quaternion is unaffected.
      Specified by:
      length in interface QuatArg
      Returns:
      the length

    • lengthSq

      public float lengthSq()
      Return the squared length. The quaternion is unaffected.
      Specified by:
      lengthSq in interface QuatArg
      Returns:
      the squared length

    • normalized

      public Quat normalized()
      Generate a normalized quaternion that represents the same rotation. The current object is unaffected.
      Specified by:
      normalized in interface QuatArg
      Returns:
      a new quaternion

    • put

      public void put(FloatBuffer storeBuffer)
      Write all 4 components to the specified buffer in XYZW order and advance the buffer's position by 4. The quaternion is unaffected.
      Specified by:
      put in interface QuatArg
      Parameters:
      storeBuffer - the destination buffer (not null)

    • rotateAxisX

      public Vec3 rotateAxisX()
      Apply the rotation to (1,0,0). The quaternion is assumed to be normalized and is unaffected.
      Specified by:
      rotateAxisX in interface QuatArg
      Returns:
      a new vector

    • rotateAxisY

      public Vec3 rotateAxisY()
      Apply the rotation to (0,1,0). The quaternion is assumed to be normalized and is unaffected.
      Specified by:
      rotateAxisY in interface QuatArg
      Returns:
      a new vector

    • rotateAxisZ

      public Vec3 rotateAxisZ()
      Apply the rotation to (0,0,1). The quaternion is assumed to be normalized and is unaffected.
      Specified by:
      rotateAxisZ in interface QuatArg
      Returns:
      a new vector

    • toString

      public String toString()
      Return a string representation of the quaternion, which is unaffected. For example, an identity quaternion is represented by: 
       Quat(0.0 0.0 0.0 1.0)
      Overrides:
      toString in class Object
      Returns:
      the string representation (not null, not empty)