Package icyllis.arc3d.core

# Class Quaternion

java.lang.Object
icyllis.arc3d.core.Quaternion

public class Quaternion extends Object
Represents a Quaternion, mostly used for rotations.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected float`
  `w`
  `protected float`
  `x`
  `protected float`
  `y`
  `protected float`
  `z`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Quaternion()`
  Create a zero quaternion.
  `Quaternion(float x, float y, float z, float w)`
  Create a quaternion with given components.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `add(Quaternion q)`
  Add a quaternion to this quaternion.
  `void`
  `conjugate()`
  Conjugate this quaternion `[-x, -y, -z, w]`.
  `Quaternion`
  `copy()`
  `static Quaternion`
  `copy(Quaternion q)`
  Create a copy of `q` if it's not null, or an identity quaternion otherwise.
  `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 q)`
  Returns the dot product of this quaternion with the given quaternion.
  `boolean`
  `equals(Object o)`
  `int`
  `hashCode()`
  `static Quaternion`
  `identity()`
  Create a new identity quaternion.
  `void`
  `inverse()`
  Calculate the inverse of this quaternion.
  `boolean`
  `isApproxEqual(Quaternion q)`
  Returns whether this quaternion is equivalent to given quaternion.
  `boolean`
  `isIdentity()`
  Calculate whether this quaternion is equivalent to an identity quaternion.
  `boolean`
  `isNormalized()`
  Returns whether this quaternion is normalized.
  `float`
  `length()`
  Returns the magnitude of this quaternion, namely the 2-norm (euclidean norm) or the length.
  `float`
  `lengthSq()`
  `static Quaternion`
  `makeAxisAngle(float axisX, float axisY, float axisZ, float angle)`
  Create a quaternion from the given axis and angle.
  `static Quaternion`
  `makeAxisAngle(Vector3 axis, float angle)`
  Create a quaternion from the given axis and angle.
  `static Quaternion`
  `makeEulerAngles(float rotationX, float rotationY, float rotationZ)`
  Create a quaternion from the given Euler rotation angles in radians.
  `void`
  `multiply(float s)`
  Multiply this quaternion by a factor.
  `void`
  `multiply(Quaternion q)`
  Multiply this quaternion by some other quaternion.
  `void`
  `negate()`
  Negate this quaternion `[-x, -y, -z, -w]`.
  `void`
  `normalize()`
  Normalize this quaternion to unit length.
  `void`
  `rotateByAxis(float axisX, float axisY, float axisZ, float angle)`
  Rotate this quaternion by the given axis and angle.
  `void`
  `rotateByAxis(Vector3 axis, float angle)`
  Rotate this quaternion by the given axis and angle.
  `void`
  `rotateByEuler(float rotationX, float rotationY, float rotationZ)`
  Rotates this quaternion from the given Euler rotation angles in radians.
  `void`
  `rotateX(float angle)`
  Rotate this quaternion around X axis with the given angle in radians.
  `void`
  `rotateY(float angle)`
  Rotate this quaternion around Y axis with the given angle in radians.
  `void`
  `rotateZ(float angle)`
  Rotate this quaternion around Z axis with the given angle in radians.
  `void`
  `set(float x, float y, float z, float w)`
  Set all values of this quaternion using the given components.
  `void`
  `set(Quaternion q)`
  Set all values of this quaternion using the given quaternion.
  `void`
  `setFromAxisAngle(float axisX, float axisY, float axisZ, float angle)`
  Set this quaternion components from the given axis and angle.
  `void`
  `setFromAxisAngle(Vector3 axis, float angle)`
  Set this quaternion components from the given axis and angle.
  `void`
  `setFromEulerAngles(float rotationX, float rotationY, float rotationZ)`
  Set this quaternion components from the given Euler rotation angles in radians.
  `void`
  `setIdentity()`
  Set this quaternion to the identity quaternion `[0, 0, 0, 1]`.
  `void`
  `setZero()`
  Set this quaternion to the zero quaternion.
  `void`
  `slerp(Quaternion a, float t)`
  Set this quaternion to a spherical linear interpolation between this and given quaternion by a factor.
  `void`
  `slerp(Quaternion a, Quaternion b, float t)`
  Set this quaternion to a spherical linear interpolation between two quaternions by the given factor.
  `void`
  `subtract(Quaternion q)`
  Subtract a quaternion from this quaternion.
  `float`
  `toAxisAngle(float[] axis)`
  Transform the rotational quaternion to axis based rotation angles.
  `float`
  `toAxisAngle(Vector3 axis)`
  Transform the rotational quaternion to axis based rotation angles.
  `void`
  `toEulerAngles(float[] angles)`
  Transform this quaternion to Euler rotation angles in radians (pitchX, yawY and rollZ).
  `void`
  `toEulerAngles(Vector3 result)`
  Transform this quaternion to Euler rotation angles in radians (pitchX, yawY and rollZ).
  `Matrix3`
  `toMatrix3()`
  Transform this quaternion to a normalized 3x3 row-major matrix representing the rotation.
  `Matrix3`
  `toMatrix3(Matrix3 out)`
  Transform this quaternion to a normalized 3x3 row-major matrix representing the rotation.
  `Matrix4`
  `toMatrix4()`
  Transform this quaternion to a normalized 4x4 row-major matrix representing the rotation.
  `Matrix4`
  `toMatrix4(Matrix4 out)`
  Transform this quaternion to a normalized 4x4 row-major matrix representing the rotation.
  `String`
  `toString()`

  ### Methods inherited from class java.lang.Object

  `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- ## Field Details

  - ### x

    protected float x

  - ### y

    protected float y

  - ### z

    protected float z

  - ### w

    protected float w

- ## Constructor Details

  - ### Quaternion

    public Quaternion()
    Create a zero quaternion.

  - ### Quaternion

    public Quaternion(float x, float y, float z, float w)
    Create a quaternion with given components.
    Parameters:
      `x` - the x-component of the quaternion
      `y` - the y-component of the quaternion
      `z` - the z-component of the quaternion
      `w` - the w-component of the quaternion

- ## Method Details

  - ### copy

    @Nonnull public static Quaternion copy(@Nullable Quaternion q)
    Create a copy of `q` if it's not null, or an identity quaternion otherwise.
    Parameters:
      `q` - the quaternion to copy from
    Returns:
      a copy of the quaternion

  - ### identity

    @Nonnull public static Quaternion identity()
    Create a new identity quaternion.
    Returns:
      an identity quaternion

  - ### makeEulerAngles

    @Nonnull public static Quaternion makeEulerAngles(float rotationX, float rotationY, float rotationZ)
    Create a quaternion from the given Euler rotation angles in radians. The returned quaternion will be a normalized rotational quaternion.
    Parameters:
      `rotationX` - the Euler pitch angle in radians. (rotation about the X axis)
      `rotationY` - the Euler yaw angle in radians. (rotation about the Y axis)
      `rotationZ` - the Euler roll angle in radians. (rotation about the Z axis)
    Returns:
      the resulting quaternion

  - ### makeAxisAngle

    @Nonnull public static Quaternion makeAxisAngle(@Nonnull Vector3 axis, float angle)
    Create a quaternion from the given axis and angle. The axis must be a normalized (unit) vector.
    Parameters:
      `axis` - the rotation axis
      `angle` - rotation angle in radians
    Returns:
      the resulting quaternion

  - ### makeAxisAngle

    @Nonnull public static Quaternion makeAxisAngle(float axisX, float axisY, float axisZ, float angle)
    Create a quaternion from the given axis and angle. The axis must be a normalized (unit) vector.
    Parameters:
      `axisX` - x-coordinate of rotation axis
      `axisY` - y-coordinate of rotation axis
      `axisZ` - z-coordinate of rotation axis
      `angle` - rotation angle in radians
    Returns:
      the resulting quaternion

  - ### set

    public void set(float x, float y, float z, float w)
    Set all values of this quaternion using the given components.
    Parameters:
      `x` - the x-component to set
      `y` - the y-component to set
      `z` - the z-component to set
      `w` - the w-component to set

  - ### set

    public void set(@Nonnull Quaternion q)
    Set all values of this quaternion using the given quaternion.
    Parameters:
      `q` - the quaternion to copy from

  - ### add

    public void add(@Nonnull Quaternion q)
    Add a quaternion to this quaternion.
    Parameters:
      `q` - the quaternion to add

  - ### subtract

    public void subtract(@Nonnull Quaternion q)
    Subtract a quaternion from this quaternion.
    Parameters:
      `q` - the quaternion to subtract

  - ### multiply

    public void multiply(float s)
    Multiply this quaternion by a factor.
    Parameters:
      `s` - the factor to multiply.

  - ### multiply

    public void multiply(@Nonnull Quaternion q)
    Multiply this quaternion by some other quaternion.
    Parameters:
      `q` - the quaternion to multiply with

  - ### length

    public float length()
    Returns the magnitude of this quaternion, namely the 2-norm (euclidean norm) or the length.
    Returns:
      the magnitude of this quaternion

  - ### lengthSq

    public float lengthSq()

  - ### dot

    public 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 float dot(@Nonnull Quaternion q)
    Returns the dot product of this quaternion with the given quaternion.
    Parameters:
      `q` - the quaternion to dot product with.

  - ### inverse

    public void inverse()
    Calculate the inverse of this quaternion. If rotational, it will produce the inverse rotation.

  - ### isNormalized

    public boolean isNormalized()
    Returns whether this quaternion is normalized.
    Returns:
      `true` if is normalized, `false` otherwise

  - ### normalize

    public void normalize()
    Normalize this quaternion to unit length.

  - ### setZero

    public void setZero()
    Set this quaternion to the zero quaternion.

  - ### isIdentity

    public boolean isIdentity()
    Calculate whether this quaternion is equivalent to an identity quaternion.
    Returns:
      `true` if this quaternion is identity.

  - ### setIdentity

    public void setIdentity()
    Set this quaternion to the identity quaternion `[0, 0, 0, 1]`.

  - ### conjugate

    public void conjugate()
    Conjugate this quaternion `[-x, -y, -z, w]`.

  - ### negate

    public void negate()
    Negate this quaternion `[-x, -y, -z, -w]`.

  - ### slerp

    public void slerp(@Nonnull Quaternion a, float t)
    Set this quaternion to a spherical linear interpolation between this and given quaternion by a factor. The two quaternions should be rotational so they should be normalized. This method does not normalize this quaternion.
    Parameters:
      `a` - the end quaternion
      `t` - a value between 0.0 and 1.0 representing interpolation

  - ### slerp

    public void slerp(@Nonnull Quaternion a, @Nonnull Quaternion b, float t)
    Set this quaternion to a spherical linear interpolation between two quaternions by the given factor. The two quaternions should be rotational so they should be normalized. This method does not normalize this quaternion.
    Parameters:
      `a` - the start quaternion
      `b` - the end quaternion
      `t` - a value between 0.0 and 1.0 representing interpolation

  - ### rotateByAxis

    public void rotateByAxis(@Nonnull Vector3 axis, float angle)
    Rotate this quaternion by the given axis and angle. The axis must be a normalized (unit) vector.
    Parameters:
      `axis` - the rotation axis
      `angle` - rotation angle in radians

  - ### rotateByAxis

    public void rotateByAxis(float axisX, float axisY, float axisZ, float angle)
    Rotate this quaternion by the given axis and angle. The axis must be a normalized (unit) vector.
    Parameters:
      `axisX` - x-coordinate of rotation axis
      `axisY` - y-coordinate of rotation axis
      `axisZ` - z-coordinate of rotation axis
      `angle` - rotation angle in radians

  - ### rotateX

    public void rotateX(float angle)
    Rotate this quaternion around X axis with the given angle in radians.
    Parameters:
      `angle` - rotation angle in radians

  - ### rotateY

    public void rotateY(float angle)
    Rotate this quaternion around Y axis with the given angle in radians.
    Parameters:
      `angle` - rotation angle in radians

  - ### rotateZ

    public void rotateZ(float angle)
    Rotate this quaternion around Z axis with the given angle in radians.
    Parameters:
      `angle` - rotation angle in radians

  - ### rotateByEuler

    public void rotateByEuler(float rotationX, float rotationY, float rotationZ)
    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:

    - x - pitch - `rotateX(float)`
    - y - yaw - `rotateY(float)`
    - z - roll - `rotateZ(float)`
    Parameters:
      `rotationX` - the Euler pitch angle in radians. (rotation about the X axis)
      `rotationY` - the Euler yaw angle in radians. (rotation about the Y axis)
      `rotationZ` - the Euler roll angle in radians. (rotation about the Z axis)
    See Also:
      - `rotateY(float)`
      - `rotateZ(float)`
      - `rotateX(float)`

  - ### setFromAxisAngle

    public void setFromAxisAngle(@Nonnull Vector3 axis, float angle)
    Set this quaternion components from the given axis and angle. The axis must be a normalized (unit) vector.
    Parameters:
      `axis` - the rotation axis
      `angle` - rotation angle in radians

  - ### setFromAxisAngle

    public void setFromAxisAngle(float axisX, float axisY, float axisZ, float angle)
    Set this quaternion components from the given axis and angle. The axis must be a normalized (unit) vector.
    Parameters:
      `axisX` - x-coordinate of rotation axis
      `axisY` - y-coordinate of rotation axis
      `axisZ` - z-coordinate of rotation axis
      `angle` - rotation angle in radians

  - ### setFromEulerAngles

    public void setFromEulerAngles(float rotationX, float rotationY, float rotationZ)
    Set this quaternion components from the given Euler rotation angles in radians.
    Parameters:
      `rotationX` - the Euler pitch angle in radians. (rotation about the X axis)
      `rotationY` - the Euler yaw angle in radians. (rotation about the Y axis)
      `rotationZ` - the Euler roll angle in radians. (rotation about the Z axis)

  - ### toAxisAngle

    public float toAxisAngle(@Nonnull Vector3 axis)
    Transform the rotational quaternion to axis based rotation angles.
    Parameters:
      `axis` - the vector for storing the axis coordinates.
    Returns:
      the rotation angle in radians.

  - ### toAxisAngle

    public float toAxisAngle(@Nonnull float[] axis)
    Transform the rotational quaternion to axis based rotation angles.
    Parameters:
      `axis` - the array for storing the axis coordinates.
    Returns:
      the rotation angle in radians.

  - ### toEulerAngles

    public void toEulerAngles(@Nonnull Vector3 result)
    Transform this quaternion to Euler rotation angles in radians (pitchX, yawY and rollZ).
    Parameters:
      `result` - the vector for storing the result.

  - ### toEulerAngles

    public void toEulerAngles(@Nonnull float[] angles)
    Transform this quaternion to Euler rotation angles in radians (pitchX, yawY and rollZ).
    Parameters:
      `angles` - the array for storing the result.

  - ### toMatrix3

    @Nonnull public Matrix3 toMatrix3()
    Transform this quaternion to a normalized 3x3 row-major matrix representing the rotation.
    Returns:
      the resulting matrix

  - ### toMatrix4

    @Nonnull public Matrix4 toMatrix4()
    Transform this quaternion to a normalized 4x4 row-major matrix representing the rotation.
    Returns:
      the resulting matrix

  - ### toMatrix3

    @Nonnull public Matrix3 toMatrix3(@Nullable Matrix3 out)
    Transform this quaternion to a normalized 3x3 row-major matrix representing the rotation. If recycle matrix is null, a new matrix will be returned.
    Parameters:
      `out` - a matrix for storing the result
    Returns:
      the resulting matrix

  - ### toMatrix4

    @Nonnull public Matrix4 toMatrix4(@Nullable Matrix4 out)
    Transform this quaternion to a normalized 4x4 row-major matrix representing the rotation. If recycle matrix is null, a new matrix will be returned.
    Parameters:
      `out` - a matrix for storing the result
    Returns:
      the resulting matrix

  - ### isApproxEqual

    public boolean isApproxEqual(@Nonnull Quaternion q)
    Returns whether this quaternion is equivalent to given quaternion.
    Parameters:
      `q` - the quaternion to compare.
    Returns:
      `true` if this quaternion is equivalent to other one.

  - ### equals

    public boolean equals(Object o)
    Overrides:
      `equals` in class `Object`

  - ### hashCode

    public int hashCode()
    Overrides:
      `hashCode` in class `Object`

  - ### toString

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

  - ### copy

    @Nonnull public Quaternion copy()