com.jme.math
Class Matrix4f

java.lang.Object
  extended by com.jme.math.Matrix4f
All Implemented Interfaces:
Savable, java.io.Serializable, java.lang.Cloneable

public class Matrix4f
extends java.lang.Object
implements java.io.Serializable, Savable, java.lang.Cloneable

Matrix4f defines and maintains a 4x4 matrix in row major order. This matrix is intended for use in a translation and rotational capacity. It provides convenience methods for creating the matrix from a multitude of sources. Matrices are stored assuming column vectors on the right, with the translation in the rightmost column. Element numbering is row,column, so m03 is the zeroth row, third column, which is the "x" translation part. This means that the implicit storage order is column major. However, the get() and set() functions on float arrays default to row major order!

Author:
Mark Powell, Joshua Slack
See Also:
Serialized Form

Field Summary
 float m00
           
 float m01
           
 float m02
           
 float m03
           
 float m10
           
 float m11
           
 float m12
           
 float m13
           
 float m20
           
 float m21
           
 float m22
           
 float m23
           
 float m30
           
 float m31
           
 float m32
           
 float m33
           
 
Constructor Summary
Matrix4f()
          Constructor instantiates a new Matrix that is set to the identity matrix.
Matrix4f(float[] array)
          Create a new Matrix4f, given data in column-major format.
Matrix4f(float m00, float m01, float m02, float m03, float m10, float m11, float m12, float m13, float m20, float m21, float m22, float m23, float m30, float m31, float m32, float m33)
          constructs a matrix with the given values.
Matrix4f(Matrix4f mat)
          Constructor instantiates a new Matrix that is set to the provided matrix.
 
Method Summary
 Matrix4f add(Matrix4f mat)
           
 void addLocal(Matrix4f mat)
          add adds the values of a parameter matrix to this matrix.
 Matrix4f adjoint()
          Returns a new matrix representing the adjoint of this matrix.
 Matrix4f adjoint(Matrix4f store)
          Places the adjoint of this matrix in store (creates store if null.)
 void angleRotation(Vector3f angles)
          angleRotation sets this matrix to that of a rotation about three axes (x, y, z).
 Matrix4f clone()
           
 void copy(Matrix4f matrix)
          copy transfers the contents of a given matrix to this matrix.
 float determinant()
          determinant generates the determinate of this matrix.
(package private) static boolean equalIdentity(Matrix4f mat)
           
 boolean equals(java.lang.Object o)
          are these two matrices the same? they are is they both have the same mXX values.
 java.nio.FloatBuffer fillFloatBuffer(java.nio.FloatBuffer fb)
          fillFloatBuffer fills a FloatBuffer object with the matrix data.
 java.nio.FloatBuffer fillFloatBuffer(java.nio.FloatBuffer fb, boolean columnMajor)
          fillFloatBuffer fills a FloatBuffer object with the matrix data.
 void fromAngleAxis(float angle, Vector3f axis)
          fromAngleAxis sets this matrix4f to the values specified by an angle and an axis of rotation.
 void fromAngleNormalAxis(float angle, Vector3f axis)
          fromAngleNormalAxis sets this matrix4f to the values specified by an angle and a normalized axis of rotation.
 void get(float[] matrix)
          get retrieves the values of this object into a float array in row-major order.
 void get(float[] matrix, boolean rowMajor)
          set retrieves the values of this object into a float array.
 float get(int i, int j)
          get retrieves a value from the matrix at the given position.
 java.lang.Class<? extends Matrix4f> getClassTag()
           
 float[] getColumn(int i)
          getColumn returns one of three columns specified by the parameter.
 float[] getColumn(int i, float[] store)
          getColumn returns one of three columns specified by the parameter.
 int hashCode()
          hashCode returns the hash code value as an integer and is supported for the benefit of hashing based collection classes such as Hashtable, HashMap, HashSet etc.
 void inverseRotateVect(Vector3f vec)
          inverseRotateVect rotates a given Vector3f by the rotation part of this matrix.
 void inverseTranslateVect(float[] vec)
          inverseTranslateVect translates a given Vector3f by the translation part of this matrix.
 void inverseTranslateVect(Vector3f data)
          inverseTranslateVect translates a given Vector3f by the translation part of this matrix.
 Matrix4f invert()
          Inverts this matrix as a new Matrix4f.
 Matrix4f invert(Matrix4f store)
          Inverts this matrix and stores it in the given store.
 Matrix4f invertLocal()
          Inverts this matrix locally.
 boolean isIdentity()
           
 void loadIdentity()
          loadIdentity sets this matrix to the identity matrix, namely all zeros with ones along the diagonal.
 Matrix4f mult(float scalar)
           
 float[] mult(float[] vec4f)
          mult multiplies an array of 4 floats against this rotation matrix.
 Matrix4f mult(float scalar, Matrix4f store)
           
 Matrix4f mult(Matrix4f in2)
          mult multiplies this matrix with another matrix.
 Matrix4f mult(Matrix4f in2, Matrix4f store)
          mult multiplies this matrix with another matrix.
 Quaternion mult(Quaternion vec, Quaternion store)
          mult multiplies a quaternion about a matrix.
 Vector3f mult(Vector3f vec)
          mult multiplies a vector about a rotation matrix.
 Vector3f mult(Vector3f vec, Vector3f store)
          mult multiplies a vector about a rotation matrix and adds translation.
 float[] multAcross(float[] vec4f)
          mult multiplies an array of 4 floats against this rotation matrix.
 Vector3f multAcross(Vector3f vec, Vector3f store)
          mult multiplies a vector about a rotation matrix.
 void multLocal(float scalar)
          mult multiplies this matrix by a scalar.
 Matrix4f multLocal(Matrix4f in2)
          mult multiplies this matrix with another matrix.
 void multLocal(Quaternion rotation)
           
 void read(JMEImporter e)
           
 Matrix4f readFloatBuffer(java.nio.FloatBuffer fb)
          readFloatBuffer reads value for this matrix from a FloatBuffer.
 Matrix4f readFloatBuffer(java.nio.FloatBuffer fb, boolean columnMajor)
          readFloatBuffer reads value for this matrix from a FloatBuffer.
 void rotateVect(Vector3f vec)
           
 void scale(Vector3f scale)
          Apply a scale to this matrix.
 void set(float[] matrix)
          set sets the values of this matrix from an array of values assuming that the data is rowMajor order;
 void set(float[][] matrix)
          set sets the values of this matrix from an array of values.
 void set(float[] matrix, boolean rowMajor)
          set sets the values of this matrix from an array of values;
 void set(int i, int j, float value)
          set places a given value into the matrix at the given position.
 Matrix4f set(Matrix4f matrix)
          set sets the values of this matrix from another matrix.
 void setColumn(int i, float[] column)
          setColumn sets a particular column of this matrix to that represented by the provided vector.
 void setInverseRotationDegrees(float[] angles)
          setInverseRotationDegrees builds an inverted rotation from Euler angles that are in degrees.
 void setInverseRotationRadians(float[] angles)
          setInverseRotationRadians builds an inverted rotation from Euler angles that are in radians.
 void setInverseTranslation(float[] translation)
          setInverseTranslation will set the matrix's inverse translation values.
 void setRotationQuaternion(Quaternion quat)
          setRotationQuaternion builds a rotation from a Quaternion.
 void setTranslation(float[] translation)
          setTranslation will set the matrix's translation values.
 void setTranslation(float x, float y, float z)
          setTranslation will set the matrix's translation values.
 void setTranslation(Vector3f translation)
          setTranslation will set the matrix's translation values.
 java.nio.FloatBuffer toFloatBuffer()
          toFloatBuffer returns a FloatBuffer object that contains the matrix data.
 java.nio.FloatBuffer toFloatBuffer(boolean columnMajor)
          toFloatBuffer returns a FloatBuffer object that contains the matrix data.
 Matrix3f toRotationMatrix()
           
 void toRotationMatrix(Matrix3f mat)
           
 Quaternion toRotationQuat()
           
 void toRotationQuat(Quaternion q)
           
 java.lang.String toString()
          toString returns the string representation of this object.
 Vector3f toTranslationVector()
           
 void toTranslationVector(Vector3f vector)
           
 void translateVect(Vector3f data)
          inverseTranslateVect translates a given Vector3f by the translation part of this matrix.
 Matrix4f transpose()
           
 Matrix4f transposeLocal()
          transpose locally transposes this Matrix.
 void write(JMEExporter e)
           
 Matrix4f zero()
          Sets all of the values in this matrix to zero.
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

m00

public float m00

m01

public float m01

m02

public float m02

m03

public float m03

m10

public float m10

m11

public float m11

m12

public float m12

m13

public float m13

m20

public float m20

m21

public float m21

m22

public float m22

m23

public float m23

m30

public float m30

m31

public float m31

m32

public float m32

m33

public float m33
Constructor Detail

Matrix4f

public Matrix4f()
Constructor instantiates a new Matrix that is set to the identity matrix.


Matrix4f

public Matrix4f(float m00,
                float m01,
                float m02,
                float m03,
                float m10,
                float m11,
                float m12,
                float m13,
                float m20,
                float m21,
                float m22,
                float m23,
                float m30,
                float m31,
                float m32,
                float m33)
constructs a matrix with the given values.


Matrix4f

public Matrix4f(float[] array)
Create a new Matrix4f, given data in column-major format.

Parameters:
array - An array of 16 floats in column-major format (translation in elements 12, 13 and 14).

Matrix4f

public Matrix4f(Matrix4f mat)
Constructor instantiates a new Matrix that is set to the provided matrix. This constructor copies a given Matrix. If the provided matrix is null, the constructor sets the matrix to the identity.

Parameters:
mat - the matrix to copy.
Method Detail

copy

public void copy(Matrix4f matrix)
copy transfers the contents of a given matrix to this matrix. If a null matrix is supplied, this matrix is set to the identity matrix.

Parameters:
matrix - the matrix to copy.

get

public void get(float[] matrix)
get retrieves the values of this object into a float array in row-major order.

Parameters:
matrix - the matrix to set the values into.

get

public void get(float[] matrix,
                boolean rowMajor)
set retrieves the values of this object into a float array.

Parameters:
matrix - the matrix to set the values into.
rowMajor - whether the outgoing data is in row or column major order.

get

public float get(int i,
                 int j)
get retrieves a value from the matrix at the given position. If the position is invalid a JmeException is thrown.

Parameters:
i - the row index.
j - the colum index.
Returns:
the value at (i, j).

getColumn

public float[] getColumn(int i)
getColumn returns one of three columns specified by the parameter. This column is returned as a float array of length 4.

Parameters:
i - the column to retrieve. Must be between 0 and 3.
Returns:
the column specified by the index.

getColumn

public float[] getColumn(int i,
                         float[] store)
getColumn returns one of three columns specified by the parameter. This column is returned as a float[4].

Parameters:
i - the column to retrieve. Must be between 0 and 3.
store - the float array to store the result in. if null, a new one is created.
Returns:
the column specified by the index.

setColumn

public void setColumn(int i,
                      float[] column)
setColumn sets a particular column of this matrix to that represented by the provided vector.

Parameters:
i - the column to set.
column - the data to set.

set

public void set(int i,
                int j,
                float value)
set places a given value into the matrix at the given position. If the position is invalid a JmeException is thrown.

Parameters:
i - the row index.
j - the colum index.
value - the value for (i, j).

set

public void set(float[][] matrix)
set sets the values of this matrix from an array of values.

Parameters:
matrix - the matrix to set the value to.
Throws:
JmeException - if the array is not of size 16.

set

public Matrix4f set(Matrix4f matrix)
set sets the values of this matrix from another matrix.

Parameters:
matrix - the matrix to read the value from.

set

public void set(float[] matrix)
set sets the values of this matrix from an array of values assuming that the data is rowMajor order;

Parameters:
matrix - the matrix to set the value to.

set

public void set(float[] matrix,
                boolean rowMajor)
set sets the values of this matrix from an array of values;

Parameters:
matrix - the matrix to set the value to.
rowMajor - whether the incoming data is in row or column major order.

transpose

public Matrix4f transpose()

transposeLocal

public Matrix4f transposeLocal()
transpose locally transposes this Matrix.

Returns:
this object for chaining.

toFloatBuffer

public java.nio.FloatBuffer toFloatBuffer()
toFloatBuffer returns a FloatBuffer object that contains the matrix data.

Returns:
matrix data as a FloatBuffer.

toFloatBuffer

public java.nio.FloatBuffer toFloatBuffer(boolean columnMajor)
toFloatBuffer returns a FloatBuffer object that contains the matrix data.

Parameters:
columnMajor - if true, this buffer should be filled with column major data, otherwise it will be filled row major.
Returns:
matrix data as a FloatBuffer. The position is set to 0 for convenience.

fillFloatBuffer

public java.nio.FloatBuffer fillFloatBuffer(java.nio.FloatBuffer fb)
fillFloatBuffer fills a FloatBuffer object with the matrix data.

Parameters:
fb - the buffer to fill, must be correct size
Returns:
matrix data as a FloatBuffer.

fillFloatBuffer

public java.nio.FloatBuffer fillFloatBuffer(java.nio.FloatBuffer fb,
                                            boolean columnMajor)
fillFloatBuffer fills a FloatBuffer object with the matrix data.

Parameters:
fb - the buffer to fill, starting at current position. Must have room for 16 more floats.
columnMajor - if true, this buffer should be filled with column major data, otherwise it will be filled row major.
Returns:
matrix data as a FloatBuffer. (position is advanced by 16 and any limit set is not changed).

readFloatBuffer

public Matrix4f readFloatBuffer(java.nio.FloatBuffer fb)
readFloatBuffer reads value for this matrix from a FloatBuffer.

Parameters:
fb - the buffer to read from, must be correct size
Returns:
this data as a FloatBuffer.

readFloatBuffer

public Matrix4f readFloatBuffer(java.nio.FloatBuffer fb,
                                boolean columnMajor)
readFloatBuffer reads value for this matrix from a FloatBuffer.

Parameters:
fb - the buffer to read from, must be correct size
columnMajor - if true, this buffer should be filled with column major data, otherwise it will be filled row major.
Returns:
this data as a FloatBuffer.

loadIdentity

public void loadIdentity()
loadIdentity sets this matrix to the identity matrix, namely all zeros with ones along the diagonal.


fromAngleAxis

public void fromAngleAxis(float angle,
                          Vector3f axis)
fromAngleAxis sets this matrix4f to the values specified by an angle and an axis of rotation. This method creates an object, so use fromAngleNormalAxis if your axis is already normalized.

Parameters:
angle - the angle to rotate (in radians).
axis - the axis of rotation.

fromAngleNormalAxis

public void fromAngleNormalAxis(float angle,
                                Vector3f axis)
fromAngleNormalAxis sets this matrix4f to the values specified by an angle and a normalized axis of rotation.

Parameters:
angle - the angle to rotate (in radians).
axis - the axis of rotation (already normalized).

multLocal

public void multLocal(float scalar)
mult multiplies this matrix by a scalar.

Parameters:
scalar - the scalar to multiply this matrix by.

mult

public Matrix4f mult(float scalar)

mult

public Matrix4f mult(float scalar,
                     Matrix4f store)

mult

public Matrix4f mult(Matrix4f in2)
mult multiplies this matrix with another matrix. The result matrix will then be returned. This matrix will be on the left hand side, while the parameter matrix will be on the right.

Parameters:
in2 - the matrix to multiply this matrix by.
Returns:
the resultant matrix

mult

public Matrix4f mult(Matrix4f in2,
                     Matrix4f store)
mult multiplies this matrix with another matrix. The result matrix will then be returned. This matrix will be on the left hand side, while the parameter matrix will be on the right.

Parameters:
in2 - the matrix to multiply this matrix by.
store - where to store the result. It is safe for in2 and store to be the same object.
Returns:
the resultant matrix

multLocal

public Matrix4f multLocal(Matrix4f in2)
mult multiplies this matrix with another matrix. The results are stored internally and a handle to this matrix will then be returned. This matrix will be on the left hand side, while the parameter matrix will be on the right.

Parameters:
in2 - the matrix to multiply this matrix by.
Returns:
the resultant matrix

mult

public Vector3f mult(Vector3f vec)
mult multiplies a vector about a rotation matrix. The resulting vector is returned as a new Vector3f.

Parameters:
vec - vec to multiply against.
Returns:
the rotated vector.

mult

public Vector3f mult(Vector3f vec,
                     Vector3f store)
mult multiplies a vector about a rotation matrix and adds translation. The resulting vector is returned.

Parameters:
vec - vec to multiply against.
store - a vector to store the result in. Created if null is passed.
Returns:
the rotated vector.

multAcross

public Vector3f multAcross(Vector3f vec,
                           Vector3f store)
mult multiplies a vector about a rotation matrix. The resulting vector is returned.

Parameters:
vec - vec to multiply against.
store - a vector to store the result in. created if null is passed.
Returns:
the rotated vector.

mult

public Quaternion mult(Quaternion vec,
                       Quaternion store)
mult multiplies a quaternion about a matrix. The resulting vector is returned.

Parameters:
vec - vec to multiply against.
store - a quaternion to store the result in. created if null is passed.
Returns:
store = this * vec

mult

public float[] mult(float[] vec4f)
mult multiplies an array of 4 floats against this rotation matrix. The results are stored directly in the array. (vec4f x mat4f)

Parameters:
vec4f - float array (size 4) to multiply against the matrix.
Returns:
the vec4f for chaining.

multAcross

public float[] multAcross(float[] vec4f)
mult multiplies an array of 4 floats against this rotation matrix. The results are stored directly in the array. (vec4f x mat4f)

Parameters:
vec4f - float array (size 4) to multiply against the matrix.
Returns:
the vec4f for chaining.

invert

public Matrix4f invert()
Inverts this matrix as a new Matrix4f.

Returns:
The new inverse matrix

invert

public Matrix4f invert(Matrix4f store)
Inverts this matrix and stores it in the given store.

Returns:
The store

invertLocal

public Matrix4f invertLocal()
Inverts this matrix locally.

Returns:
this

adjoint

public Matrix4f adjoint()
Returns a new matrix representing the adjoint of this matrix.

Returns:
The adjoint matrix

adjoint

public Matrix4f adjoint(Matrix4f store)
Places the adjoint of this matrix in store (creates store if null.)

Parameters:
store - The matrix to store the result in. If null, a new matrix is created.
Returns:
store

determinant

public float determinant()
determinant generates the determinate of this matrix.

Returns:
the determinate

zero

public Matrix4f zero()
Sets all of the values in this matrix to zero.

Returns:
this matrix

add

public Matrix4f add(Matrix4f mat)

addLocal

public void addLocal(Matrix4f mat)
add adds the values of a parameter matrix to this matrix.

Parameters:
mat - the matrix to add to this.

toTranslationVector

public Vector3f toTranslationVector()

toTranslationVector

public void toTranslationVector(Vector3f vector)

toRotationQuat

public Quaternion toRotationQuat()

toRotationQuat

public void toRotationQuat(Quaternion q)

toRotationMatrix

public Matrix3f toRotationMatrix()

toRotationMatrix

public void toRotationMatrix(Matrix3f mat)

setTranslation

public void setTranslation(float[] translation)
setTranslation will set the matrix's translation values.

Parameters:
translation - the new values for the translation.
Throws:
JmeException - if translation is not size 3.

setTranslation

public void setTranslation(float x,
                           float y,
                           float z)
setTranslation will set the matrix's translation values.

Parameters:
x - value of the translation on the x axis
y - value of the translation on the y axis
z - value of the translation on the z axis

setTranslation

public void setTranslation(Vector3f translation)
setTranslation will set the matrix's translation values.

Parameters:
translation - the new values for the translation.

setInverseTranslation

public void setInverseTranslation(float[] translation)
setInverseTranslation will set the matrix's inverse translation values.

Parameters:
translation - the new values for the inverse translation.
Throws:
JmeException - if translation is not size 3.

angleRotation

public void angleRotation(Vector3f angles)
angleRotation sets this matrix to that of a rotation about three axes (x, y, z). Where each axis has a specified rotation in degrees. These rotations are expressed in a single Vector3f object.

Parameters:
angles - the angles to rotate.

setRotationQuaternion

public void setRotationQuaternion(Quaternion quat)
setRotationQuaternion builds a rotation from a Quaternion.

Parameters:
quat - the quaternion to build the rotation from.
Throws:
java.lang.NullPointerException - if quat is null.

setInverseRotationRadians

public void setInverseRotationRadians(float[] angles)
setInverseRotationRadians builds an inverted rotation from Euler angles that are in radians.

Parameters:
angles - the Euler angles in radians.
Throws:
JmeException - if angles is not size 3.

setInverseRotationDegrees

public void setInverseRotationDegrees(float[] angles)
setInverseRotationDegrees builds an inverted rotation from Euler angles that are in degrees.

Parameters:
angles - the Euler angles in degrees.
Throws:
JmeException - if angles is not size 3.

inverseTranslateVect

public void inverseTranslateVect(float[] vec)
inverseTranslateVect translates a given Vector3f by the translation part of this matrix.

Parameters:
vec - the Vector3f data to be translated.
Throws:
JmeException - if the size of the Vector3f is not 3.

inverseTranslateVect

public void inverseTranslateVect(Vector3f data)
inverseTranslateVect translates a given Vector3f by the translation part of this matrix.

Parameters:
data - the Vector3f to be translated.
Throws:
JmeException - if the size of the Vector3f is not 3.

translateVect

public void translateVect(Vector3f data)
inverseTranslateVect translates a given Vector3f by the translation part of this matrix.

Parameters:
data - the Vector3f to be translated.
Throws:
JmeException - if the size of the Vector3f is not 3.

inverseRotateVect

public void inverseRotateVect(Vector3f vec)
inverseRotateVect rotates a given Vector3f by the rotation part of this matrix.

Parameters:
vec - the Vector3f to be rotated.

rotateVect

public void rotateVect(Vector3f vec)

toString

public java.lang.String toString()
toString returns the string representation of this object. It is in a format of a 4x4 matrix. For example, an identity matrix would be represented by the following string. com.jme.math.Matrix3f
[
1.0 0.0 0.0 0.0
0.0 1.0 0.0 0.0
0.0 0.0 1.0 0.0
0.0 0.0 0.0 1.0
]

Overrides:
toString in class java.lang.Object
Returns:
the string representation of this object.

hashCode

public int hashCode()
hashCode returns the hash code value as an integer and is supported for the benefit of hashing based collection classes such as Hashtable, HashMap, HashSet etc.

Overrides:
hashCode in class java.lang.Object
Returns:
the hashcode for this instance of Matrix4f.
See Also:
Object.hashCode()

equals

public boolean equals(java.lang.Object o)
are these two matrices the same? they are is they both have the same mXX values.

Overrides:
equals in class java.lang.Object
Parameters:
o - the object to compare for equality
Returns:
true if they are equal

write

public void write(JMEExporter e)
           throws java.io.IOException
Specified by:
write in interface Savable
Throws:
java.io.IOException

read

public void read(JMEImporter e)
          throws java.io.IOException
Specified by:
read in interface Savable
Throws:
java.io.IOException

getClassTag

public java.lang.Class<? extends Matrix4f> getClassTag()
Specified by:
getClassTag in interface Savable

isIdentity

public boolean isIdentity()
Returns:
true if this matrix is identity

scale

public void scale(Vector3f scale)
Apply a scale to this matrix.

Parameters:
scale - the scale to apply

equalIdentity

static final boolean equalIdentity(Matrix4f mat)

multLocal

public void multLocal(Quaternion rotation)

clone

public Matrix4f clone()
Overrides:
clone in class java.lang.Object