com.threed.jpct

Class Matrix

java.lang.Object

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

Constructors

Constructor and Description
Matrix() Creates a new matrix and sets it to the identity matrix.
Matrix(Matrix m) Creates a matrix from a given one.

Method Summary

Modifier and Type	Method and Description
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)