Package com.jme3.math

Class Matrix3f

java.lang.Object
com.jme3.math.Matrix3f
All Implemented Interfaces:
Savable, Serializable, Cloneable

public final class Matrix3f extends Object implements Savable, Cloneable, Serializable
A 3x3 matrix composed of 9 single-precision elements, used to represent linear transformations of 3-D coordinates, such as rotations, reflections, and scaling.

Element numbering is (row, column), so m01 is the element in row 0, column 1.

For pure rotations, the Quaternion class provides a more efficient representation.

With one exception, the methods with names ending in "Local" modify the current instance. They are used to avoid creating garbage.

See Also:
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final Matrix3f
    Shared instance of the identity matrix (diagonals = 1, other elements = 0).
    protected float
    The element in row 0, column 0.
    protected float
    The element in row 0, column 1.
    protected float
    The element in row 0, column 2.
    protected float
    The element in row 1, column 0.
    protected float
    The element in row 1, column 1.
    protected float
    The element in row 1, column 2.
    protected float
    The element in row 2, column 0.
    protected float
    The element in row 2, column 1.
    protected float
    The element in row 2, column 2.
    static final Matrix3f
    Shared instance of the all-zero matrix.
  • Constructor Summary

    Constructors
    Constructor
    Description
    Instantiates an identity matrix (diagonals = 1, other elements = 0).
    Matrix3f(float m00, float m01, float m02, float m10, float m11, float m12, float m20, float m21, float m22)
    Instantiates a matrix with specified elements.
    Instantiates a copy of the matrix argument.
  • Method Summary

    Modifier and Type
    Method
    Description
    void
    Replaces all 9 elements with their absolute values.
    Returns the adjoint as a new matrix.
    Returns the adjoint in the specified storage.
    Creates a copy.
    float
    Returns the determinant.
    boolean
    Tests for exact equality with the argument, distinguishing -0 from 0.
    void
    fillFloatArray(float[] f, boolean columnMajor)
    Copies the matrix to the 1st 9 elements of the specified array.
    fillFloatBuffer(FloatBuffer fb, boolean columnMajor)
    Copies the matrix to the specified FloatBuffer, starting at its current position.
    void
    fromAngleAxis(float angle, Vector3f axis)
    Sets all 9 elements to form a pure rotation matrix with the specified rotation angle and axis of rotation.
    void
    fromAngleNormalAxis(float angle, Vector3f axis)
    Sets all 9 elements to form a rotation matrix with the specified rotation angle and normalized axis of rotation.
    void
    fromAxes(Vector3f uAxis, Vector3f vAxis, Vector3f wAxis)
    Configures from the specified column vectors.
    void
    Configures a rotation matrix that rotates the specified start direction to the specified end direction.
    void
    get(float[] data, boolean rowMajor)
    Copies the matrix to the specified array.
    float
    get(int i, int j)
    Returns the element at the specified position.
    getColumn(int i)
    Returns the specified column.
    getColumn(int i, Vector3f store)
    Returns the specified column.
    getRow(int i)
    Returns the specified row.
    getRow(int i, Vector3f store)
    Returns the specified row.
    int
    Returns a hash code.
    Returns the multiplicative inverse as a new matrix.
    Returns the multiplicative inverse in the specified storage.
    Inverts the matrix and returns the (modified) current instance.
    boolean
    Tests for exact identity.
    void
    Configures as an identity matrix (diagonals = 1, other elements = 0).
    Multiplies with the argument matrix and returns the product as a new instance.
    mult(Matrix3f mat, Matrix3f product)
    Multiplies with the specified matrix and returns the product in a 3rd matrix.
    Applies the linear transformation to the vector argument and returns the result as a new vector.
    mult(Vector3f vec, Vector3f product)
    Applies the linear transformation to specified vector and stores the result in another vector.
    multLocal(float scale)
    Multiplies by the scalar argument and returns the (modified) current instance.
    Multiplies by the matrix argument and returns the (modified) current instance.
    Applies the linear transformation to the vector argument and returns the (modified) argument.
    Normalizes the matrix and returns the result in the argument.
    Normalizes the matrix and returns the (modified) current instance.
    void
    read(JmeImporter importer)
    De-serializes from the specified importer, for example when loading from a J3O file.
    void
    scale(Vector3f scale)
    Scales each column by the corresponding element of the argument.
    set(float[] matrix)
    Copies all 9 elements from the array argument, in row-major order.
    set(float[][] matrix)
    Copies all 9 elements from the specified 2-dimensional array.
    set(float[] matrix, boolean rowMajor)
    Copies all 9 elements from the specified array.
    set(int i, int j, float value)
    Sets the specified element.
    set(Matrix3f matrix)
    Copies the matrix argument.
    set(Quaternion quaternion)
    Configures as a rotation matrix equivalent to the argument.
    setColumn(int i, Vector3f column)
    Sets the specified column.
    setRow(int i, Vector3f row)
    Sets the specified row.
    Copies the matrix to a new FloatBuffer.
    Returns a string representation of the matrix, which is unaffected.
    Transposes the matrix and returns the (modified) current instance.
    Transposes the matrix and returns the (modified) current instance.
    Returns the transpose as a new instance.
    void
    Serializes to the specified exporter, for example when saving to a J3O file.
    Sets all elements to zero.

    Methods inherited from class java.lang.Object

    finalize, getClass, notify, notifyAll, wait, wait, wait
  • Field Details

    • m00

      protected float m00
      The element in row 0, column 0.
    • m01

      protected float m01
      The element in row 0, column 1.
    • m02

      protected float m02
      The element in row 0, column 2.
    • m10

      protected float m10
      The element in row 1, column 0.
    • m11

      protected float m11
      The element in row 1, column 1.
    • m12

      protected float m12
      The element in row 1, column 2.
    • m20

      protected float m20
      The element in row 2, column 0.
    • m21

      protected float m21
      The element in row 2, column 1.
    • m22

      protected float m22
      The element in row 2, column 2.
    • ZERO

      public static final Matrix3f ZERO
      Shared instance of the all-zero matrix. Do not modify!
    • IDENTITY

      public static final Matrix3f IDENTITY
      Shared instance of the identity matrix (diagonals = 1, other elements = 0). Do not modify!
  • Constructor Details

    • Matrix3f

      public Matrix3f()
      Instantiates an identity matrix (diagonals = 1, other elements = 0).
    • Matrix3f

      public Matrix3f(float m00, float m01, float m02, float m10, float m11, float m12, float m20, float m21, float m22)
      Instantiates a matrix with specified elements.
      Parameters:
      m00 - the desired value for row 0, column 0
      m01 - the desired value for row 0, column 1
      m02 - the desired value for row 0, column 2
      m10 - the desired value for row 1, column 0
      m11 - the desired value for row 1, column 1
      m12 - the desired value for row 1, column 2
      m20 - the desired value for row 2, column 0
      m21 - the desired value for row 2, column 1
      m22 - the desired value for row 2, column 2
    • Matrix3f

      public Matrix3f(Matrix3f mat)
      Instantiates a copy of the matrix argument. If the argument is null, an identity matrix is produced.
      Parameters:
      mat - the matrix to copy (unaffected) or null for identity
  • Method Details

    • absoluteLocal

      public void absoluteLocal()
      Replaces all 9 elements with their absolute values.
    • set

      public Matrix3f set(Matrix3f matrix)
      Copies the matrix argument. If the argument is null, the current instance is set to identity (diagonals = 1, other elements = 0).
      Parameters:
      matrix - the matrix to copy (unaffected) or null for identity
      Returns:
      the (modified) current instance (for chaining)
    • get

      public float get(int i, int j)
      Returns the element at the specified position. The matrix is unaffected.
      Parameters:
      i - the row index (0, 1, or 2)
      j - the column index (0, 1, or 2)
      Returns:
      the value of the element at (i, j)
      Throws:
      IllegalArgumentException - if either index isn't 0, 1, or 2
    • get

      public void get(float[] data, boolean rowMajor)
      Copies the matrix to the specified array. The matrix is unaffected.

      If the array has 16 elements, then the matrix is treated as if it contained the 1st 3 rows and 1st 3 columns of a 4x4 matrix.

      Parameters:
      data - storage for the elements (not null, length=9 or 16)
      rowMajor - true to store the elements in row-major order (m00, m01, ...) or false to store them in column-major order (m00, m10, ...)
      Throws:
      IndexOutOfBoundsException - if data doesn't have 9 or 16 elements
      See Also:
    • normalize

      public Matrix3f normalize(Matrix3f store)
      Normalizes the matrix and returns the result in the argument. The current instance is unaffected, unless it's store.
      Parameters:
      store - storage for the result, or null for a new Matrix3f
      Returns:
      either store or a new Matrix3f
    • normalizeLocal

      public Matrix3f normalizeLocal()
      Normalizes the matrix and returns the (modified) current instance.
      Returns:
      the (modified) current instance (for chaining)
    • getColumn

      public Vector3f getColumn(int i)
      Returns the specified column. The matrix is unaffected.

      If the matrix is a pure rotation, each column contains one of the basis vectors.

      Parameters:
      i - the column index (0, 1, or 2)
      Returns:
      a new Vector3f
      Throws:
      IllegalArgumentException - if i isn't 0, 1, or 2
      See Also:
    • getColumn

      public Vector3f getColumn(int i, Vector3f store)
      Returns the specified column. The matrix is unaffected.

      If the matrix is a pure rotation, each column contains one of the basis vectors.

      Parameters:
      i - the column index (0, 1, or 2)
      store - storage for the result, or null for a new Vector3f
      Returns:
      either store or a new Vector3f
      Throws:
      IllegalArgumentException - if i isn't 0, 1, or 2
      See Also:
    • getRow

      public Vector3f getRow(int i)
      Returns the specified row. The matrix is unaffected.
      Parameters:
      i - the row index (0, 1, or 2)
      Returns:
      a new Vector3f
      Throws:
      IllegalArgumentException - if i isn't 0, 1, or 2
    • getRow

      public Vector3f getRow(int i, Vector3f store)
      Returns the specified row. The matrix is unaffected.
      Parameters:
      i - the row index (0, 1, or 2)
      store - storage for the result, or null for a new Vector3f
      Returns:
      either store or a new Vector3f
      Throws:
      IllegalArgumentException - if i isn't 0, 1, or 2
    • toFloatBuffer

      public FloatBuffer toFloatBuffer()
      Copies the matrix to a new FloatBuffer. The matrix is unaffected.
      Returns:
      a new, rewound FloatBuffer containing all 9 elements in row-major order (m00, m01, ...)
    • fillFloatBuffer

      public FloatBuffer fillFloatBuffer(FloatBuffer fb, boolean columnMajor)
      Copies the matrix to the specified FloatBuffer, starting at its current position. The matrix is unaffected.
      Parameters:
      fb - storage for the elements (not null, must have space to put 9 more floats)
      columnMajor - true to store the elements in column-major order (m00, m10, ...) or false to store them in row-major order (m00, m01, ...)
      Returns:
      fb, its position advanced by 9
    • fillFloatArray

      public void fillFloatArray(float[] f, boolean columnMajor)
      Copies the matrix to the 1st 9 elements of the specified array. The matrix is unaffected.
      Parameters:
      f - storage for the elements (not null, length≥9)
      columnMajor - true to store the elements in column-major order (m00, m10, ...) or false to store them in row-major order (m00, m01, ...)
      See Also:
    • setColumn

      public Matrix3f setColumn(int i, Vector3f column)
      Sets the specified column.
      Parameters:
      i - which column to set (0, 1, or 2)
      column - the desired element values (unaffected) or null for none
      Returns:
      the (modified) current instance (for chaining)
      Throws:
      IllegalArgumentException - if i isn't 0, 1, or 2
    • setRow

      public Matrix3f setRow(int i, Vector3f row)
      Sets the specified row.
      Parameters:
      i - which row to set (0, 1, or 2)
      row - the desired element values (unaffected) or null for none
      Returns:
      the (modified) current instance (for chaining)
      Throws:
      IllegalArgumentException - if i isn't 0, 1, or 2
    • set

      public Matrix3f set(int i, int j, float value)
      Sets the specified element.
      Parameters:
      i - the row index (0, 1, or 2)
      j - the column index (0, 1, or 2)
      value - desired value for the element at (i, j)
      Returns:
      the (modified) current instance (for chaining)
      Throws:
      IllegalArgumentException - if either index isn't 0, 1, or 2
    • set

      public Matrix3f set(float[][] matrix)
      Copies all 9 elements from the specified 2-dimensional array.
      Parameters:
      matrix - the input array (not null, length=3, the first element having length=3, the other elements having length≥3, unaffected)
      Returns:
      the (modified) current instance (for chaining)
      Throws:
      IllegalArgumentException - if the array is the wrong size
    • fromAxes

      public void fromAxes(Vector3f uAxis, Vector3f vAxis, Vector3f wAxis)
      Configures from the specified column vectors. If the vectors form an orthonormal basis, the result will be a pure rotation matrix.
      Parameters:
      uAxis - the desired value for column 0 (not null, unaffected)
      vAxis - the desired value for column 1 (not null, unaffected)
      wAxis - the desired value for column 2 (not null, unaffected)
      See Also:
    • set

      public Matrix3f set(float[] matrix)
      Copies all 9 elements from the array argument, in row-major order.
      Parameters:
      matrix - the input array (not null, length=9, unaffected)
      Returns:
      the (modified) current instance (for chaining)
      Throws:
      IllegalArgumentException - if the array has length != 9
    • set

      public Matrix3f set(float[] matrix, boolean rowMajor)
      Copies all 9 elements from the specified array.
      Parameters:
      matrix - the input array (not null, length=9, unaffected)
      rowMajor - true to read the elements in row-major order (m00, m01, ...) or false to read them in column-major order (m00, m10, ...)
      Returns:
      the (modified) current instance (for chaining)
      Throws:
      IllegalArgumentException - if the array has length != 9
    • set

      public Matrix3f set(Quaternion quaternion)
      Configures as a rotation matrix equivalent to the argument.
      Parameters:
      quaternion - the input quaternion (not null, unaffected)
      Returns:
      the (modified) current instance (for chaining)
    • loadIdentity

      public void loadIdentity()
      Configures as an identity matrix (diagonals = 1, other elements = 0).
    • isIdentity

      public boolean isIdentity()
      Tests for exact identity. The matrix is unaffected.
      Returns:
      true if all diagonals = 1 and all other elements = 0 or -0, otherwise false
    • fromAngleAxis

      public void fromAngleAxis(float angle, Vector3f axis)
      Sets all 9 elements to form a pure rotation matrix with the specified rotation angle and axis of rotation. This method creates garbage, so use fromAngleNormalAxis(float, com.jme3.math.Vector3f) if the axis is known to be normalized.
      Parameters:
      angle - the desired rotation angle (in radians)
      axis - the desired axis of rotation (not null, unaffected)
    • fromAngleNormalAxis

      public void fromAngleNormalAxis(float angle, Vector3f axis)
      Sets all 9 elements to form a rotation matrix with the specified rotation angle and normalized axis of rotation. If the axis might not be normalized, use fromAngleAxis(float, com.jme3.math.Vector3f) instead.
      Parameters:
      angle - the desired rotation angle (in radians)
      axis - the desired axis of rotation (not null, length=1, unaffected)
    • mult

      public Matrix3f mult(Matrix3f mat)
      Multiplies with the argument matrix and returns the product as a new instance. The current instance is unaffected.

      Note that matrix multiplication is noncommutative, so generally q * p != p * q.

      Parameters:
      mat - the right factor (not null, unaffected)
      Returns:
      this times mat (a new Matrix3f)
    • mult

      public Matrix3f mult(Matrix3f mat, Matrix3f product)
      Multiplies with the specified matrix and returns the product in a 3rd matrix. The current instance is unaffected unless it's product.

      Note that matrix multiplication is noncommutative, so generally q * p != p * q.

      It is safe for mat and product to be the same object.

      Parameters:
      mat - the right factor (not null, unaffected unless it's product)
      product - storage for the product, or null for a new Matrix3f
      Returns:
      this times mat (either product or a new Matrix3f)
    • mult

      public Vector3f mult(Vector3f vec)
      Applies the linear transformation to the vector argument and returns the result as a new vector. The matrix is unaffected.

      This can also be described as multiplying the matrix by a column vector.

      Parameters:
      vec - the coordinates to transform (not null, unaffected)
      Returns:
      a new Vector3f
    • mult

      public Vector3f mult(Vector3f vec, Vector3f product)
      Applies the linear transformation to specified vector and stores the result in another vector. The matrix is unaffected.

      This can also be described as multiplying the matrix by a column vector.

      It is safe for vec and product to be the same object.

      Parameters:
      vec - the coordinates to transform (not null, unaffected unless it's product)
      product - storage for the result, or null for a new Vector3f
      Returns:
      either product or a new Vector3f
    • multLocal

      public Matrix3f multLocal(float scale)
      Multiplies by the scalar argument and returns the (modified) current instance.
      Parameters:
      scale - the scaling factor
      Returns:
      the (modified) current instance (for chaining)
    • multLocal

      public Vector3f multLocal(Vector3f vec)
      Applies the linear transformation to the vector argument and returns the (modified) argument. If the argument is null, null is returned.

      Despite the name, the current instance is unaffected.

      Parameters:
      vec - the vector to transform (modified if not null)
      Returns:
      vec or null
    • multLocal

      public Matrix3f multLocal(Matrix3f mat)
      Multiplies by the matrix argument and returns the (modified) current instance.

      Note that matrix multiplication is noncommutative, so generally q * p != p * q.

      Parameters:
      mat - the right factor (not null, unaffected unless it's this)
      Returns:
      the (modified) current instance
    • transposeLocal

      public Matrix3f transposeLocal()
      Transposes the matrix and returns the (modified) current instance.
      Returns:
      the (modified) current instance
    • invert

      public Matrix3f invert()
      Returns the multiplicative inverse as a new matrix. If the current instance is singular, an all-zero matrix is returned. In either case, the current instance is unaffected.
      Returns:
      a new Matrix3f
    • invert

      public Matrix3f invert(Matrix3f store)
      Returns the multiplicative inverse in the specified storage. If the current instance is singular, an all-zero matrix is returned. In either case, the current instance is unaffected.

      If this and store are the same object, the result is undefined. Use invertLocal() instead.

      Parameters:
      store - storage for the result, or null for a new Matrix3f
      Returns:
      either store or a new Matrix3f
    • invertLocal

      public Matrix3f invertLocal()
      Inverts the matrix and returns the (modified) current instance. If the current instance is singular, all elements will be set to zero.
      Returns:
      the (modified) current instance (for chaining)
    • adjoint

      public Matrix3f adjoint()
      Returns the adjoint as a new matrix. The current instance is unaffected.
      Returns:
      a new Matrix3f
    • adjoint

      public Matrix3f adjoint(Matrix3f store)
      Returns the adjoint in the specified storage. The current instance is unaffected.

      If this and store are the same object, the result is undefined.

      Parameters:
      store - storage for the result, or null for a new Matrix3f
      Returns:
      either store or a new Matrix3f
    • determinant

      public float determinant()
      Returns the determinant. The matrix is unaffected.
      Returns:
      the determinant
    • zero

      public Matrix3f zero()
      Sets all elements to zero.
      Returns:
      the (modified) current instance (for chaining)
    • transpose

      public Matrix3f transpose()
      Transposes the matrix and returns the (modified) current instance.

      This method is inconsistent with JME naming conventions, but has been preserved for backwards compatibility. To preserve the current instance, transposeNew().

      TODO deprecate in favor of transposeLocal()

      Returns:
      the (modified) current instance (for chaining)
    • transposeNew

      public Matrix3f transposeNew()
      Returns the transpose as a new instance. The current instance is unaffected.
      Returns:
      a new Matrix3f
    • toString

      public String toString()
      Returns a string representation of the matrix, which is unaffected. For example, the identity matrix is represented by:
       Matrix3f
       [
        1.0  0.0  0.0
        0.0  1.0  0.0
        0.0  0.0  1.0
       ]
       
      Overrides:
      toString in class Object
      Returns:
      the string representation (not null, not empty)
    • hashCode

      public int hashCode()
      Returns a hash code. If two matrices have identical values, they will have the same hash code. The matrix is unaffected.
      Overrides:
      hashCode in class Object
      Returns:
      a 32-bit value for use in hashing
      See Also:
    • equals

      public boolean equals(Object o)
      Tests for exact equality with the argument, distinguishing -0 from 0. If o is null, false is returned. Either way, the current instance is unaffected.
      Overrides:
      equals in class Object
      Parameters:
      o - the object to compare (may be null, unaffected)
      Returns:
      true if this and o have identical values, otherwise false
    • write

      public void write(JmeExporter e) throws IOException
      Serializes to the specified exporter, for example when saving to a J3O file. The current instance is unaffected.
      Specified by:
      write in interface Savable
      Parameters:
      e - the exporter to use (not null)
      Throws:
      IOException - from the exporter
    • read

      public void read(JmeImporter importer) throws IOException
      De-serializes from the specified importer, for example when loading from a J3O file.
      Specified by:
      read in interface Savable
      Parameters:
      importer - the importer to use (not null)
      Throws:
      IOException - from the importer
    • fromStartEndVectors

      public void fromStartEndVectors(Vector3f start, Vector3f end)
      Configures a rotation matrix that rotates the specified start direction to the specified end direction.

      See Tomas Möller, John F. Hughes "Efficiently Building a Matrix to Rotate One Vector to Another" Journal of Graphics Tools, 4(4):1-4, 1999.

      Parameters:
      start - the start direction (not null, length=1, unaffected)
      end - the end direction (not null, length=1, unaffected)
    • scale

      public void scale(Vector3f scale)
      Scales each column by the corresponding element of the argument.
      Parameters:
      scale - the scale factors: X scales column 0, Y scales column 1, Z scales column 2 (not null, unaffected)
    • clone

      public Matrix3f clone()
      Creates a copy. The current instance is unaffected.
      Overrides:
      clone in class Object
      Returns:
      a new instance, equivalent to the current one