net.jinx.math
Class Matrix4

java.lang.Object
  net.jinx.math.Matrix4

public class Matrix4
extends java.lang.Object

Matrix4 is a 4x4 matrix class intended for graphical tranformation operations, however, it isn't designed in the typical fashion of most graphical Matrix classes I've seen. It's immutable, just like the rest of the classes in this package. I may change that in the future; I'm not sure, because making it mutable would make the API faster, but prone to errors such as accidentally overwriting a Matrix4 at the wrong time (I usually prefer ease of use, since modern machines are so darn fast and Java's garbage collector is much better than it used to be).

API Stability: Beta.

Field Summary

static Matrix4

IDENTITY The indetity Matrix4 is usually your starting point for building a transformation Matrix4.

Constructor Summary

Matrix4(float[] values)
Constructs a Matrix4 using an array of floats.

Matrix4(Quaternion r1, Quaternion r2, Quaternion r3, Quaternion r4)
Constructs a Matrix4 from four Quaternions.

Method Summary

Matrix4	add(Matrix4 m)
Matrix4	applyPerspective(float d) Applies a perspective transformation and returns the result.
boolean	equals(java.lang.Object obj)
float	get(int row, int col) Returns a given element of this Matrix.
Matrix4	multiply(float v) Multiplies this Matrix4 by v.
Matrix4	multiply(Matrix4 m) Multiplies m (the multiplicand) by this (the multiplier).
static Matrix4	perspectiveMatrix(float d) Constructs a perspective transformation Matrix.
Matrix4	rotate(Quaternion q) Applies a rotation transformation and returns the result.
Matrix4	rotate(Vector v) Applies a rotation transformation and returns the result.
Matrix4	rotateX(float t) Applies a rotation transformation and returns the result.
Matrix4	rotateY(float t) Applies a rotation transformation and returns the result.
Matrix4	rotateZ(float t) Applies a rotation transformation and returns the result.
static Matrix4	rotationMatrix(float x, float y, float z) Constructs a rotation Matrix4.
static Matrix4	rotationMatrix(Quaternion q) Constructs a rotation Matrix4 for q.
static Matrix4	rotationMatrix(Vector v) Constructs a rotation Matrix4 for v.
Matrix4	scale(float s) Applies a scale transformation and returns the result.
Matrix4	scale(float x, float y, float z) Applies a scale transformation and returns the result.
Matrix4	scale(Vector v) Applies a scale transformation and returns the result.
static Matrix4	scalingMatrix(float s) Constructs a scaling Matrix.
static Matrix4	scalingMatrix(float vx, float vy, float vz) Constructs a scaling Matrix.
static Matrix4	scalingMatrix(Vector v) Constructs a scaling Matrix.
Matrix4	subtract(Matrix4 m)
float[]	toFloatArray() Converts this Matrix4 to a column ordered float array.
java.lang.String	toString()
void	transform(float[] v) Transforms v as though it were either a Vector or a Quaternion (depending on length), modifying the array with the result.
void	transform(float[][] va) Transforms a vertex array.
float[]	transform(float xv, float yv, float zv) Transforms the parameters as though they were a Vector and returns the result.
float[]	transform(float xv, float yv, float zv, float wv) Transforms vx, vy, vz, and vw as though they were a Quaternion and returns the result.
Quaternion	transform(Quaternion v) Transforms v and returns the result.
Quaternion[]	transform(Quaternion[] v) Transforms an array of Quaternions and returns the result.
Vector	transform(Vector v) Transforms v and returns the result.
Vector[]	transform(Vector[] v) Transforms an array of Vectors and returns the result.
Matrix4	translate(Vector v) Applies a translation transformation and returns the result.
static Matrix4	translationMatrix(float x, float y, float z) Constructs a translation Matrix4.
static Matrix4	translationMatrix(Vector v) Constructs a translation Matrix.
Matrix4	transpose() Returns a transposed version of this Matrix.
static Matrix4	xRotationMatrix(float t) Constructs a rotation Matrix4 for rotating around the X axis.
static Matrix4	yRotationMatrix(float t) Constructs a rotation Matrix4 for rotating around the Y axis.
static Matrix4	zRotationMatrix(float t) Constructs a rotation Matrix4 for rotating around the Z axis.

Methods inherited from class java.lang.Object

clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

IDENTITY

public static final Matrix4 IDENTITY

The indetity Matrix4 is usually your starting point for building a transformation Matrix4.

Constructor Detail

Matrix4

public Matrix4(Quaternion r1,
               Quaternion r2,
               Quaternion r3,
               Quaternion r4)

Constructs a Matrix4 from four Quaternions.

Parameters:

r1 - the first row.

r2 - the first row.

r3 - the first row.

r4 - the first row.

Matrix4

public Matrix4(float[] values)

Constructs a Matrix4 using an array of floats.

Parameters:

values - the floats to use, in column order.

Method Detail

equals

public boolean equals(java.lang.Object obj)

Overrides:

equals in class java.lang.Object

get

public float get(int row,
                 int col)

Returns a given element of this Matrix. The indices are not zero based, like an array. They're one based, because that is the natural, mathematical way to look at it (at least according to the references I've read).

Parameters:

row - the row to access.

col - the column to access.

Returns:

the value of the accessed element.

transpose

public Matrix4 transpose()

Returns a transposed version of this Matrix.

Returns:

the resulting Matrix.

transform

public void transform(float[][] va)

Transforms a vertex array. See the net.jinx.video.model.VertexUtil class in the modeler's API docs for more information.

Parameters:

va - the vertex array.

transform

public void transform(float[] v)

Transforms v as though it were either a Vector or a Quaternion (depending on length), modifying the array with the result.

Parameters:

v - the float array.

transform

public float[] transform(float xv,
                         float yv,
                         float zv)

Transforms the parameters as though they were a Vector and returns the result.

Parameters:

xv - the X component.

yv - the Y component.

zv - the Z component.

Returns:

the resulting float array.

transform

public float[] transform(float xv,
                         float yv,
                         float zv,
                         float wv)

Transforms vx, vy, vz, and vw as though they were a Quaternion and returns the result.

Parameters:

xv - the X component.

yv - the Y component.

zv - the Z component.

wv - the W component.

Returns:

the resulting float array.

transform

public Vector[] transform(Vector[] v)

Transforms an array of Vectors and returns the result.

Parameters:

v - the arracy of Vectors to transform.

Returns:

the resulting Vector array.

transform

public Vector transform(Vector v)

Transforms v and returns the result.

Parameters:

v - the Vector to transform.

Returns:

the resulting Vector.

transform

public Quaternion[] transform(Quaternion[] v)

Transforms an array of Quaternions and returns the result.

Parameters:

v - the arracy of Quaternions to transform.

Returns:

the resulting Quaternion array.

transform

public Quaternion transform(Quaternion v)

Transforms v and returns the result.

Parameters:

v - the Quaternion to transform.

Returns:

the resulting Quaternion.

add

public Matrix4 add(Matrix4 m)

subtract

public Matrix4 subtract(Matrix4 m)

multiply

public Matrix4 multiply(float v)

Multiplies this Matrix4 by v.

Parameters:

v - the float to multiply by.

Returns:

the resulting Matrix4.

multiply

public Matrix4 multiply(Matrix4 m)

Multiplies m (the multiplicand) by this (the multiplier). The order of operations for this is important! Reversing the order will not work the same! In addition, Java will not take care of the ordering for you. You must be very careful to order your operations the way they need to occur!

Parameters:

m - the multiplicand.

Returns:

the resulting Matrix.

translate

public Matrix4 translate(Vector v)

Applies a translation transformation and returns the result.

Parameters:

v - the Vector holding values for translation along the three axes.

Returns:

the resulting Matrix. This one isn't modified.

scale

public Matrix4 scale(Vector v)

Applies a scale transformation and returns the result.

Parameters:

v - the Vector containing scaling factors for the three axes.

Returns:

the resulting Matrix. This one isn't modified.

scale

public Matrix4 scale(float s)

Applies a scale transformation and returns the result.

Parameters:

s - the scaling factor for all three axes.

Returns:

the resulting Matrix. This one isn't modified.

scale

public Matrix4 scale(float x,
                     float y,
                     float z)

Applies a scale transformation and returns the result.

Parameters:

x - the scaling factor along the X axis.

y - the scaling factor along the Y axis.

z - the scaling factor along the Z axis.

Returns:

the resulting Matrix. This one isn't modified.

rotateX

public Matrix4 rotateX(float t)

Applies a rotation transformation and returns the result.

Parameters:

t - the angle of rotation used to rotate around the X axis.

Returns:

the resulting Matrix. This one isn't modified.

rotateY

public Matrix4 rotateY(float t)

Applies a rotation transformation and returns the result.

Parameters:

t - the angle of rotation used to rotate around the Y axis.

Returns:

the resulting Matrix. This one isn't modified.

rotateZ

public Matrix4 rotateZ(float t)

Applies a rotation transformation and returns the result.

Parameters:

t - the angle of rotation used to rotate around the Z axis.

Returns:

the resulting Matrix. This one isn't modified.

rotate

public Matrix4 rotate(Vector v)

Applies a rotation transformation and returns the result.

Parameters:

v - the Vector representing the rotation.

Returns:

the resulting Matrix. This one isn't modified.

rotate

public Matrix4 rotate(Quaternion q)

Applies a rotation transformation and returns the result.

Parameters:

q - the Quaternion representing the rotation.

Returns:

the resulting Matrix. This one isn't modified.

applyPerspective

public Matrix4 applyPerspective(float d)

Applies a perspective transformation and returns the result.

Parameters:

d - the distance from the viewpoint to the viewpane.

Returns:

the resulting Matrix. This one isn't modified.

toFloatArray

public float[] toFloatArray()

Converts this Matrix4 to a column ordered float array.

Returns:

the array.

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

translationMatrix

public static Matrix4 translationMatrix(Vector v)

Constructs a translation Matrix.

Parameters:

v - the Vector to translate by.

Returns:

the Matrix.

translationMatrix

public static Matrix4 translationMatrix(float x,
                                        float y,
                                        float z)

Constructs a translation Matrix4.

Parameters:

x - the x translation.

y - the y translation.

z - the z translation.

Returns:

the Matrix.

scalingMatrix

public static Matrix4 scalingMatrix(float s)

Constructs a scaling Matrix.

Parameters:

s - the scaling factor all three axes.

Returns:

the Matrix.

scalingMatrix

public static Matrix4 scalingMatrix(Vector v)

Constructs a scaling Matrix.

Parameters:

v - the scaling Vector with factors for the three axes.

Returns:

the Matrix.

scalingMatrix

public static Matrix4 scalingMatrix(float vx,
                                    float vy,
                                    float vz)

Constructs a scaling Matrix.

Parameters:

vx - the scaling factor along the X axis.

vy - the scaling factor along the Y axis.

vz - the scaling factor along the Z axis.

Returns:

the Matrix.

xRotationMatrix

public static Matrix4 xRotationMatrix(float t)

Constructs a rotation Matrix4 for rotating around the X axis.

Parameters:

t - (short for theta) the angle of rotation.

Returns:

the Matrix.

yRotationMatrix

public static Matrix4 yRotationMatrix(float t)

Constructs a rotation Matrix4 for rotating around the Y axis.

Parameters:

t - (short for theta) the angle of rotation.

Returns:

the Matrix.

zRotationMatrix

public static Matrix4 zRotationMatrix(float t)

Constructs a rotation Matrix4 for rotating around the Z axis.

Parameters:

t - (short for theta) the angle of rotation.

Returns:

the Matrix.

perspectiveMatrix

public static Matrix4 perspectiveMatrix(float d)

Constructs a perspective transformation Matrix.

Parameters:

d - the distance from the viewpoint and the viewing plane.

Returns:

the Matrix.

rotationMatrix

public static Matrix4 rotationMatrix(Vector v)

Constructs a rotation Matrix4 for v. Each component of v describes how much to rotate around it's axis.

Parameters:

v - the Vector describing a 3D rotation.

Returns:

the Matrix.

rotationMatrix

public static Matrix4 rotationMatrix(float x,
                                     float y,
                                     float z)

Constructs a rotation Matrix4. Each parameter describes how much to rotate around it's axis.

Parameters:

x - the x rotation.

y - the y rotation.

z - the z rotation.

Returns:

the Matrix.

rotationMatrix

public static Matrix4 rotationMatrix(Quaternion q)

Constructs a rotation Matrix4 for q.

Parameters:

q - the Quaternion being used to represent a 3D rotation.

Returns:

the Matrix.