com.threed.jpct
Class Matrix

java.lang.Object
  extended by com.threed.jpct.Matrix
All Implemented Interfaces:
java.io.Serializable

public class Matrix
extends java.lang.Object
implements java.io.Serializable

This is jPCT's basic class for working with 4x4 matrices. All matrices in jPCT-AE are row major.

See Also:
Serialized Form

Constructor Summary
Matrix()
          Creates a new matrix and sets it to the identity matrix.
Matrix(Matrix m)
          Creates a matrix from a given one.
 
Method Summary
 Matrix cloneMatrix()
          Creates a copy of this matrix.
 boolean equals(java.lang.Object obj)
           
 float[] fillDump(float[] dump)
          Dumps a matrix row-wise into a given float[16]-array and returns it.
 float get(int row, int col)
          Returns the value at a position in the matrix.
 float[] getDump()
          Dumps a matrix row-wise into a float[16]-array.
 SimpleVector getTranslation()
          Returns the translation this matrix would represent when viewed as a translation matrix.
 SimpleVector getTranslation(SimpleVector toFill)
          Returns the translation this matrix would represent when viewed as a translation matrix.
 SimpleVector getXAxis()
          Returns the x-axis this matrix would represent when viewed as a rotation matrix.
 SimpleVector getXAxis(SimpleVector toFill)
          Returns the x-axis this matrix would represent when viewed as a rotation matrix.
 SimpleVector getYAxis()
          Returns the y-axis this matrix would represent when viewed as a rotation matrix.
 SimpleVector getYAxis(SimpleVector toFill)
          Returns the y-axis this matrix would represent when viewed as a rotation matrix.
 SimpleVector getZAxis()
          Returns the z-axis this matrix would represent when viewed as a rotation matrix.
 SimpleVector getZAxis(SimpleVector toFill)
          Returns the z-axis this matrix would represent when viewed as a rotation matrix.
 int hashCode()
           
 void interpolate(Matrix source, Matrix dest, float weight)
          Fills the matrix with data interpolated between the source and the destination matrix.
 Matrix invert()
          Calculates the inverse of this matrix.
 Matrix invert(Matrix dst)
          Calculates the inverse of this matrix and fills the result into the given matrix (which will be returned in addition).
 Matrix invert3x3()
          Calculates the inverse of this matrix as if this matrix would be a 3x3 one (instead of the 4x4 it actually is).
 Matrix invert3x3(Matrix toFill)
          Calculates the inverse of this matrix as if this matrix would be a 3x3 one (instead of the 4x4 it actually is).
 boolean isIdentity()
          Returns true, if this matrix is the identity matrix.
 void matMul(Matrix maty)
          Multiplies this matrix with another one.
 void orthonormalize()
          Orthonormalizes a matrix using the Gramm-Schmidt orthonormalization algorithm.
 void rotateAxis(SimpleVector axis, float angle)
          Rotates the matrix around an arbitrary axis.
 void rotateX(float w)
          Rotates the matrix around the X-axis (counter clockwise for positive w).
 void rotateY(float w)
          Rotates the matrix around the Y-axis (clockwise for positive w).
 void rotateZ(float w)
          Rotates the matrix around the Z-axis (counter clockwise for positive w).
 void scalarMul(float scalar)
          Multiplies this matrix with a scalar (the left upper 3x3 part only).
 void set(int row, int col, float value)
          Injects a value directly into the matrix at a position.
 void setColumn(int col, float v1, float v2, float v3, float v4)
          Inject values directly into a matrix' column.
 void setDump(float[] dump)
          Reimports a dumped matrix (or every data from a float[16]-array) into a Matrix.
 void setIdentity()
          (Re-)sets this matrix to the identity matrix.
 void setOrientation(SimpleVector dir, SimpleVector up)
          Sets the orientation of a rotation matrix by giving a direction and an up-vector.
 void setRow(int row, float v1, float v2, float v3, float v4)
          Inject values directly into a matrix' row.
 void setTo(Matrix source)
          Sets this matrix' values to the ones of the source matrix.
 java.lang.String toString()
           
 void transformToGL()
          Transforms a matrix from jPCT's coordinate system into OpenGL's (and vice versa)
 void translate(float x, float y, float z)
          Applies a translation to this matrix.
 void translate(SimpleVector trans)
          Applies a translation to this matrix.
 Matrix transpose()
          Calculates the transposed matrix of this matrix.
 
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Matrix

public Matrix()
Creates a new matrix and sets it to the identity matrix.


Matrix

public Matrix(Matrix m)
Creates a matrix from a given one. The new matrix will bi initialized with the same values that the source matrix has.

Parameters:
m - the source matrix
Method Detail

isIdentity

public final boolean isIdentity()
Returns true, if this matrix is the identity matrix.

Returns:
boolean true if it is, otherwise false

setIdentity

public final void setIdentity()
(Re-)sets this matrix to the identity matrix.


setOrientation

public final void setOrientation(SimpleVector dir,
                                 SimpleVector up)
Sets the orientation of a rotation matrix by giving a direction and an up-vector.

Parameters:
dir - the direction
up - the up-vector

scalarMul

public final void scalarMul(float scalar)
Multiplies this matrix with a scalar (the left upper 3x3 part only).

Parameters:
scalar - the scalar to multiply with

matMul

public final void matMul(Matrix maty)
Multiplies this matrix with another one.

Parameters:
maty - the matrix to multiply with

rotateX

public final void rotateX(float w)
Rotates the matrix around the X-axis (counter clockwise for positive w).

Parameters:
w - the rotation angle in radians

rotateY

public final void rotateY(float w)
Rotates the matrix around the Y-axis (clockwise for positive w).

Parameters:
w - the rotation angle in radians

rotateZ

public final void rotateZ(float w)
Rotates the matrix around the Z-axis (counter clockwise for positive w).

Parameters:
w - the rotation angle in radians

rotateAxis

public final void rotateAxis(SimpleVector axis,
                             float angle)
Rotates the matrix around an arbitrary axis. The method is more powerful than the normal rotate-around-an-axis methods, but also a bit slower. The resulting matrix will be orthonormalized to ensure numerical accuracy.

Parameters:
axis - a direction-vector pointing into the axis direction
angle - the angle of the rotation in radians

interpolate

public final void interpolate(Matrix source,
                              Matrix dest,
                              float weight)
Fills the matrix with data interpolated between the source and the destination matrix. The interpolation is (source*(1-weight)+dest*weigth), so it's a simple linear interpolation. The interpolated matrix is orthonormal. However, it's possible that the interpolation will result in a NaN-Matrix, if the matrices to interpolate are too different from each other. Keep that in mind...

Parameters:
source - the source matrix
dest - the destination matrix
weight - the weight of the destination matrix (0-1)

getTranslation

public final SimpleVector getTranslation()
Returns the translation this matrix would represent when viewed as a translation matrix.

Returns:
the translation

getTranslation

public final SimpleVector getTranslation(SimpleVector toFill)
Returns the translation this matrix would represent when viewed as a translation matrix.

Parameters:
toFill - the SimpleVector to fill with the result. This will also be returned.
Returns:
the translation

getXAxis

public final SimpleVector getXAxis()
Returns the x-axis this matrix would represent when viewed as a rotation matrix.

Returns:
the x-axis

getYAxis

public final SimpleVector getYAxis()
Returns the y-axis this matrix would represent when viewed as a rotation matrix.

Returns:
the y-axis

getZAxis

public final SimpleVector getZAxis()
Returns the z-axis this matrix would represent when viewed as a rotation matrix.

Returns:
the z-axis

getXAxis

public final SimpleVector getXAxis(SimpleVector toFill)
Returns the x-axis this matrix would represent when viewed as a rotation matrix. This method fills the given SimpleVector in addition to returning it.

Parameters:
toFill - the vector to fill
Returns:
the x-axis

getYAxis

public final SimpleVector getYAxis(SimpleVector toFill)
Returns the y-axis this matrix would represent when viewed as a rotation matrix. This method fills the given SimpleVector in addition to returning it.

Parameters:
toFill - the vector to fill
Returns:
the y-axis

getZAxis

public final SimpleVector getZAxis(SimpleVector toFill)
Returns the z-axis this matrix would represent when viewed as a rotation matrix. This method fills the given SimpleVector in addition to returning it.

Parameters:
toFill - the vector to fill
Returns:
the z-axis

get

public final float get(int row,
                       int col)
Returns the value at a position in the matrix.

Parameters:
row - the row
col - the column
Returns:
the value at this position, 0 if it's out of bounds.

translate

public final void translate(SimpleVector trans)
Applies a translation to this matrix.

Parameters:
trans - the translation

translate

public final void translate(float x,
                            float y,
                            float z)
Applies a translation to this matrix. This implementation should help to avoid the unnecessary creation of a SimpleVector if the coordinates already exist as three seperated ones.

Parameters:
x - the x component of the translation
y - the y component of the translation
z - the z component of the translation

cloneMatrix

public final Matrix cloneMatrix()
Creates a copy of this matrix.

Returns:
the copied matrix

invert

public final Matrix invert()
Calculates the inverse of this matrix.

Returns:
the inverse

invert

public final Matrix invert(Matrix dst)
Calculates the inverse of this matrix and fills the result into the given matrix (which will be returned in addition).

Parameters:
dst - the matrix to fill with the result.
Returns:
the inverse

invert3x3

public final Matrix invert3x3()
Calculates the inverse of this matrix as if this matrix would be a 3x3 one (instead of the 4x4 it actually is). This can be useful to invert matrices that are rotation matrices only, because they usually can be treated as 3x3 and it's much faster to do it this way than to use the normal invert()-method. In case of doubt, one may be better off using the normal invert()-method though.

Returns:
the inverse
See Also:
invert()

invert3x3

public final Matrix invert3x3(Matrix toFill)
Calculates the inverse of this matrix as if this matrix would be a 3x3 one (instead of the 4x4 it actually is). This can be useful to invert matrices that are rotation matrices only, because they usually can be treated as 3x3 and it's much faster to do it this way than to use the normal invert()-method. In case of doubt, one may be better off using the normal invert()-method though. Fills the result into the given matrix (which will be returned in addition).

Parameters:
toFill - the matrix to fill. Can't be the same instance as the matrix to invert.
Returns:
the inverse
See Also:
invert()

orthonormalize

public final void orthonormalize()
Orthonormalizes a matrix using the Gramm-Schmidt orthonormalization algorithm. This can be useful for rotation matrices to ensure that they stay orthonormal over time (i.e. after a lot of rotations have been applied to them). jPCT doesn't do this automatically, because there seems to be no need for it at the moment. But if there ever is, here is the method for doing it...


getDump

public final float[] getDump()
Dumps a matrix row-wise into a float[16]-array.

Returns:
the dump

fillDump

public final float[] fillDump(float[] dump)
Dumps a matrix row-wise into a given float[16]-array and returns it.

Returns:
the dump

setDump

public final void setDump(float[] dump)
Reimports a dumped matrix (or every data from a float[16]-array) into a Matrix.

Parameters:
dump - the "dump"

setTo

public final void setTo(Matrix source)
Sets this matrix' values to the ones of the source matrix.

Parameters:
source - the source matrix

set

public final void set(int row,
                      int col,
                      float value)
Injects a value directly into the matrix at a position.

Parameters:
row - the row
col - the column
value - the value to set

setRow

public final void setRow(int row,
                         float v1,
                         float v2,
                         float v3,
                         float v4)
Inject values directly into a matrix' row.

Parameters:
row - thw row
v1 - the first value
v2 - the second value
v3 - the third value
v4 - the fourth value

setColumn

public final void setColumn(int col,
                            float v1,
                            float v2,
                            float v3,
                            float v4)
Inject values directly into a matrix' column.

Parameters:
col - thw column
v1 - the first value
v2 - the second value
v3 - the third value
v4 - the fourth value

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object

hashCode

public int hashCode()
Overrides:
hashCode in class java.lang.Object

equals

public boolean equals(java.lang.Object obj)
Overrides:
equals in class java.lang.Object

transpose

public final Matrix transpose()
Calculates the transposed matrix of this matrix.

Returns:
the transposed matrix

transformToGL

public void transformToGL()
Transforms a matrix from jPCT's coordinate system into OpenGL's (and vice versa)