com.io7m.jtensors

Class MatrixM4x4F

java.lang.Object

com.io7m.jtensors.MatrixM4x4F

public final class MatrixM4x4F
extends Object

A 4x4 mutable matrix type with float elements.

Values of type MatrixM4x4F are backed by direct memory, with the rows and columns of the matrices being stored in column-major format. This allows the matrices to be passed to OpenGL directly, without requiring transposition.

Values of this type cannot be accessed safely from multiple threads without explicit synchronization.

See "Mathematics for 3D Game Programming and Computer Graphics" 2nd Ed for the derivations of most of the code in this class (ISBN: 1-58450-277-0).

See http://en.wikipedia.org/wiki/Row_equivalence#Elementary_row_operations for the three elementary operations defined on matrices.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	MatrixM4x4F.ContextMM4F The ContextMM4F type contains the minimum storage required for all of the functions of the MatrixM4x4F class.

Method Summary

Modifier and Type	Method and Description
static <M extends MatrixWritable4x4FType> M	add(MatrixReadable4x4FType m0, MatrixReadable4x4FType m1, M out) Elementwise add of matrices m0 and m1.
static <M extends MatrixWritable4x4FType & MatrixReadable4x4FType> M	addInPlace(M m0, MatrixReadable4x4FType m1) Elementwise add of matrices m0 and m1, returning the result in m0.
static <M extends MatrixWritable4x4FType> M	addRowScaled(MatrixM4x4F.ContextMM4F context, MatrixReadable4x4FType m, int row_a, int row_b, int row_c, double r, M out) Add the values in row row_b to the values in row row_a scaled by r, saving the resulting row in row row_c of the matrix out.
static <M extends MatrixWritable4x4FType & MatrixReadable4x4FType> M	addRowScaledInPlace(MatrixM4x4F.ContextMM4F context, M m, int row_a, int row_b, int row_c, double r) Add the values in row row_b to the values in row row_a scaled by r, saving the resulting row in row row_c of the matrix m.
static boolean	compareElements(MatrixReadable4x4FType m0, MatrixReadable4x4FType m1) Compare matrices.
static <M extends MatrixWritable4x4FType> M	copy(MatrixReadable4x4FType input, M output) Copy the contents of the matrix input to the matrix output, completely replacing all elements.
static double	determinant(MatrixReadable4x4FType m) Calculate the determinant of the matrix m.
static <M extends MatrixWritable4x4FType> M	exchangeRows(MatrixM4x4F.ContextMM4F context, MatrixReadable4x4FType m, int row_a, int row_b, M out) Exchange two rows row_a and row row_b of the matrix m, saving the exchanged rows to out .
static <M extends MatrixWritable4x4FType & MatrixReadable4x4FType> M	exchangeRowsInPlace(MatrixM4x4F.ContextMM4F context, M m, int row_a, int row_b) Exchange the row row_a and row row_b of the matrix m, saving the exchanged rows to m.
static int	hashElements(MatrixReadable4x4FType m) Hash matrices.
static <M extends MatrixWritable4x4FType> boolean	invert(MatrixM4x4F.ContextMM4F context, MatrixReadable4x4FType m, M out) Calculate the inverse of the matrix m, saving the resulting matrix to out.
static <M extends MatrixWritable4x4FType & MatrixReadable4x4FType> boolean	invertInPlace(MatrixM4x4F.ContextMM4F context, M m) Calculate the inverse of the matrix m, saving the resulting matrix to m.
static <M extends MatrixWritable4x4FType> void	lookAt(MatrixM4x4F.ContextMM4F context, VectorReadable3FType origin, VectorReadable3FType target, VectorReadable3FType up, M out_matrix) Calculate a matrix representing a "camera" looking from the point origin to the point target.
static <M extends MatrixWritable4x4FType> M	makeRotation(double angle, VectorReadable3FType axis, M out) Generate a matrix that represents a rotation of angle radians around the axis axis and save to out.
static <M extends MatrixWritable4x4FType> M	makeTranslation2F(VectorReadable2FType v, M out) Generate a matrix that represents a translation of (v.x, v.y) from the origin, and save to out.
static <M extends MatrixWritable4x4FType> M	makeTranslation2I(VectorReadable2IType v, M out) Generate a matrix that represents a translation of (v.x, v.y) from the origin, and save to out.
static <M extends MatrixWritable4x4FType> M	makeTranslation3F(VectorReadable3FType v, M out) Generate a matrix that represents a translation of (v.x, v.y, v.z) from the origin, and save to out.
static <M extends MatrixWritable4x4FType> M	makeTranslation3I(VectorReadable3IType v, M out) Generate a matrix that represents a translation of (v.x, v.y, v.z) from the origin, and save to out.
static <M extends MatrixWritable4x4FType> M	multiply(MatrixReadable4x4FType m0, MatrixReadable4x4FType m1, M out) Multiply the matrix m0 with the matrix m1, writing the result to out.
static <M extends MatrixWritable4x4FType & MatrixReadable4x4FType> M	multiplyInPlace(M m0, MatrixReadable4x4FType m1) Multiply the matrix m0 with the matrix m1, writing the result to m0.
static <V extends VectorWritable4FType> V	multiplyVector4F(MatrixM4x4F.ContextMM4F context, MatrixReadable4x4FType m, VectorReadable4FType v, V out) Multiply the matrix m with the vector v, writing the resulting vector to out.
static <M extends MatrixWritable4x4FType> M	scale(MatrixReadable4x4FType m, double r, M out) Scale all elements of the matrix m by the scaling value r, saving the result in out.
static <M extends MatrixWritable4x4FType & MatrixReadable4x4FType> M	scaleInPlace(M m, double r) Scale all elements of the matrix m by the scaling value r, saving the result in m.
static <M extends MatrixWritable4x4FType> M	scaleRow(MatrixM4x4F.ContextMM4F context, MatrixReadable4x4FType m, int row, double r, M out) Scale row row of the matrix m by r , saving the result to row r of out.
static <M extends MatrixWritable4x4FType & MatrixReadable4x4FType> M	scaleRowInPlace(MatrixM4x4F.ContextMM4F context, M m, int row, double r) Scale row row of the matrix m by r , saving the result to row r of m.
static <M extends MatrixWritable4x4FType> M	setIdentity(M m) Set the given matrix m to the identity matrix.
static <M extends MatrixWritable4x4FType> M	setZero(M m) Set the given matrix m to the zero matrix.
static void	showElements(MatrixReadable4x4FType m, StringBuilder sb) Show matrices.
static double	trace(MatrixReadable4x4FType m) Return the trace of the matrix m.
static <M extends MatrixWritable4x4FType> M	transpose(MatrixReadable4x4FType m, M out) Transpose the given matrix m, writing the resulting matrix to out.
static <M extends MatrixWritable4x4FType & MatrixReadable4x4FType> M	transposeInPlace(M m) Transpose the given matrix m, writing the resulting matrix to m.

Methods inherited from class java.lang.Object

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

Method Detail

add

public static <M extends MatrixWritable4x4FType> M add(MatrixReadable4x4FType m0,
                                                       MatrixReadable4x4FType m1,
                                                       M out)

Elementwise add of matrices m0 and m1.

Type Parameters:

M - The precise type of matrix

Parameters:

m0 - The left input matrix

m1 - The right input matrix

out - The output matrix

Returns:

out

addInPlace

public static <M extends MatrixWritable4x4FType & MatrixReadable4x4FType> M addInPlace(M m0,
                                                                                       MatrixReadable4x4FType m1)

Elementwise add of matrices m0 and m1, returning the result in m0.

Type Parameters:

M - The precise type of matrix

Parameters:

m0 - The left input matrix

m1 - The right input matrix

Returns:

m0

addRowScaledInPlace

public static <M extends MatrixWritable4x4FType & MatrixReadable4x4FType> M addRowScaledInPlace(MatrixM4x4F.ContextMM4F context,
                                                                                                M m,
                                                                                                int row_a,
                                                                                                int row_b,
                                                                                                int row_c,
                                                                                                double r)

Add the values in row row_b to the values in row row_a scaled by r, saving the resulting row in row row_c of the matrix m.

This is one of the three elementary operations defined on matrices.

Type Parameters:

M - The precise type of matrix

Parameters:

context - Preallocated storage

m - The input matrix

row_a - The row on the lefthand side of the addition

row_b - The row on the righthand side of the addition

row_c - The destination row

r - The scaling value

Returns:

m

addRowScaled

public static <M extends MatrixWritable4x4FType> M addRowScaled(MatrixM4x4F.ContextMM4F context,
                                                                MatrixReadable4x4FType m,
                                                                int row_a,
                                                                int row_b,
                                                                int row_c,
                                                                double r,
                                                                M out)

Add the values in row row_b to the values in row row_a scaled by r, saving the resulting row in row row_c of the matrix out. The function uses storage preallocated in context to avoid any new allocations.

This is one of the three elementary operations defined on matrices.

Type Parameters:

M - The precise type of matrix

Parameters:

context - Preallocated storage

m - The input matrix

row_a - The row on the lefthand side of the addition

row_b - The row on the righthand side of the addition

row_c - The destination row

r - The scaling value

out - The output matrix

Returns:

out

copy

public static <M extends MatrixWritable4x4FType> M copy(MatrixReadable4x4FType input,
                                                        M output)

Copy the contents of the matrix input to the matrix output, completely replacing all elements.

Type Parameters:

M - The precise type of matrix

Parameters:

input - The input vector

output - The output vector

Returns:

output

determinant

public static double determinant(MatrixReadable4x4FType m)

Calculate the determinant of the matrix m.

Parameters:

m - The input matrix

Returns:

The determinant.

exchangeRowsInPlace

public static <M extends MatrixWritable4x4FType & MatrixReadable4x4FType> M exchangeRowsInPlace(MatrixM4x4F.ContextMM4F context,
                                                                                                M m,
                                                                                                int row_a,
                                                                                                int row_b)

Exchange the row row_a and row row_b of the matrix m, saving the exchanged rows to m. The function uses storage preallocated in context to avoid allocating memory.

This is one of the three elementary operations defined on matrices.

Type Parameters:

M - The precise type of matrix

Parameters:

context - Preallocated storage

m - The input matrix

row_a - The first row

row_b - The second row

Returns:

m

exchangeRows

public static <M extends MatrixWritable4x4FType> M exchangeRows(MatrixM4x4F.ContextMM4F context,
                                                                MatrixReadable4x4FType m,
                                                                int row_a,
                                                                int row_b,
                                                                M out)

Exchange two rows row_a and row row_b of the matrix m, saving the exchanged rows to out .

The function uses storage preallocated in context to avoid allocating memory.

This is one of the three elementary operations defined on matrices.

Type Parameters:

M - The precise type of matrix

Parameters:

context - Preallocated storage

m - The input matrix

row_a - The first row

row_b - The second row

out - The output matrix

Returns:

out

invertInPlace

public static <M extends MatrixWritable4x4FType & MatrixReadable4x4FType> boolean invertInPlace(MatrixM4x4F.ContextMM4F context,
                                                                                                M m)

Calculate the inverse of the matrix m, saving the resulting matrix to m. The function returns Some(out) iff it was possible to invert the matrix, and None otherwise. It is not possible to invert a matrix that has a determinant of 0. The function uses preallocated storage in context to avoid allocating memory. If the function returns None, m is untouched.

Type Parameters:

M - The precise type of matrix

Parameters:

context - Preallocated storage

m - The input matrix

Returns:

true iff the matrix was invertible

See Also:

determinant(MatrixReadable4x4FType)

invert

public static <M extends MatrixWritable4x4FType> boolean invert(MatrixM4x4F.ContextMM4F context,
                                                                MatrixReadable4x4FType m,
                                                                M out)

Calculate the inverse of the matrix m, saving the resulting matrix to out. The function returns Some(out) iff it was possible to invert the matrix, and None otherwise. It is not possible to invert a matrix that has a determinant of 0. The function uses preallocated storage in context to avoid allocating memory. If the function returns None, m is untouched.

Type Parameters:

M - The precise type of matrix

Parameters:

context - Preallocated storage

m - The input matrix

out - The output matrix

Returns:

true iff the matrix was invertible

See Also:

determinant(MatrixReadable4x4FType)

lookAt

public static <M extends MatrixWritable4x4FType> void lookAt(MatrixM4x4F.ContextMM4F context,
                                                             VectorReadable3FType origin,
                                                             VectorReadable3FType target,
                                                             VectorReadable3FType up,
                                                             M out_matrix)

Calculate a matrix representing a "camera" looking from the point origin to the point target. target must represent the "up" vector for the camera. Usually, this is simply a unit vector (0, 1, 0) representing the Y axis.

The function uses preallocated storage from context.

The view is expressed as a rotation and translation matrix, written to out_matrix.

Type Parameters:

M - The precise type of matrix

Parameters:

context - Preallocated storage

out_matrix - The output matrix

origin - The position of the viewer

target - The target being viewed

up - The up vector

makeRotation

public static <M extends MatrixWritable4x4FType> M makeRotation(double angle,
                                                                VectorReadable3FType axis,
                                                                M out)

Generate a matrix that represents a rotation of angle radians around the axis axis and save to out.

The function assumes a right-handed coordinate system and therefore a positive rotation around any axis represents a counter-clockwise rotation around that axis.

Type Parameters:

M - The precise type of matrix

Parameters:

angle - The angle in radians

axis - The axis

out - The output matrix

Returns:

out

makeTranslation2F

public static <M extends MatrixWritable4x4FType> M makeTranslation2F(VectorReadable2FType v,
                                                                     M out)

Generate a matrix that represents a translation of (v.x, v.y) from the origin, and save to out.

Type Parameters:

M - The precise type of matrix

Parameters:

v - The translation vector

out - The output matrix

Returns:

out

makeTranslation2I

public static <M extends MatrixWritable4x4FType> M makeTranslation2I(VectorReadable2IType v,
                                                                     M out)

Generate a matrix that represents a translation of (v.x, v.y) from the origin, and save to out.

Type Parameters:

M - The precise type of matrix

Parameters:

v - The translation vector

out - The output matrix

Returns:

out

makeTranslation3F

public static <M extends MatrixWritable4x4FType> M makeTranslation3F(VectorReadable3FType v,
                                                                     M out)

Generate a matrix that represents a translation of (v.x, v.y, v.z) from the origin, and save to out.

Type Parameters:

M - The precise type of matrix

Parameters:

v - The translation vector

out - The output matrix

Returns:

out

makeTranslation3I

public static <M extends MatrixWritable4x4FType> M makeTranslation3I(VectorReadable3IType v,
                                                                     M out)

Generate a matrix that represents a translation of (v.x, v.y, v.z) from the origin, and save to out.

Type Parameters:

M - The precise type of matrix

Parameters:

v - The translation vector

out - The output matrix

Returns:

out

multiply

public static <M extends MatrixWritable4x4FType> M multiply(MatrixReadable4x4FType m0,
                                                            MatrixReadable4x4FType m1,
                                                            M out)

Multiply the matrix m0 with the matrix m1, writing the result to out.

Type Parameters:

M - The precise type of matrix

Parameters:

m0 - The left input vector

m1 - The right input vector

out - The output vector

Returns:

out

multiplyInPlace

public static <M extends MatrixWritable4x4FType & MatrixReadable4x4FType> M multiplyInPlace(M m0,
                                                                                            MatrixReadable4x4FType m1)

Multiply the matrix m0 with the matrix m1, writing the result to m0.

Type Parameters:

M - The precise type of matrix

Parameters:

m0 - The left input vector

m1 - The right input vector

Returns:

out

multiplyVector4F

public static <V extends VectorWritable4FType> V multiplyVector4F(MatrixM4x4F.ContextMM4F context,
                                                                  MatrixReadable4x4FType m,
                                                                  VectorReadable4FType v,
                                                                  V out)

Multiply the matrix m with the vector v, writing the resulting vector to out. The function uses preallocated storage in context to avoid allocating memory.

Type Parameters:

V - The precise type of writable vector

Parameters:

context - Preallocated storage

m - The input matrix

v - The input vector

out - The output vector

Returns:

out

scale

public static <M extends MatrixWritable4x4FType> M scale(MatrixReadable4x4FType m,
                                                         double r,
                                                         M out)

Scale all elements of the matrix m by the scaling value r, saving the result in out.

Type Parameters:

M - The precise type of matrix

Parameters:

out - The output matrix

m - The input matrix

r - The scaling value

Returns:

out

scaleInPlace

public static <M extends MatrixWritable4x4FType & MatrixReadable4x4FType> M scaleInPlace(M m,
                                                                                         double r)

Scale all elements of the matrix m by the scaling value r, saving the result in m.

Type Parameters:

M - The precise type of matrix

Parameters:

m - The input matrix

r - The scaling value

Returns:

m

scaleRowInPlace

public static <M extends MatrixWritable4x4FType & MatrixReadable4x4FType> M scaleRowInPlace(MatrixM4x4F.ContextMM4F context,
                                                                                            M m,
                                                                                            int row,
                                                                                            double r)

Scale row row of the matrix m by r , saving the result to row r of m. The function uses preallocated storage in context to avoid allocating memory.

This is one of the three elementary operations defined on matrices.

Type Parameters:

M - The precise type of matrix

Parameters:

context - Preallocated storage

m - The input matrix

row - The index of the row (0 <= row < 4)

r - The scaling value

Returns:

m

scaleRow

public static <M extends MatrixWritable4x4FType> M scaleRow(MatrixM4x4F.ContextMM4F context,
                                                            MatrixReadable4x4FType m,
                                                            int row,
                                                            double r,
                                                            M out)

Scale row row of the matrix m by r , saving the result to row r of out. The function uses preallocated storage in context to avoid allocating memory.

This is one of the three elementary operations defined on matrices.

Type Parameters:

M - The precise type of matrix

Parameters:

context - Preallocated storage

m - The input matrix

row - The index of the row (0 <= row < 4)

r - The scaling value

out - The output matrix

Returns:

out

setIdentity

public static <M extends MatrixWritable4x4FType> M setIdentity(M m)

Set the given matrix m to the identity matrix.

Type Parameters:

M - The precise type of matrix

Parameters:

m - The input matrix

Returns:

m

setZero

public static <M extends MatrixWritable4x4FType> M setZero(M m)

Set the given matrix m to the zero matrix.

Type Parameters:

M - The precise type of matrix

Parameters:

m - The matrix

Returns:

m

trace

public static double trace(MatrixReadable4x4FType m)

Return the trace of the matrix m. The trace is defined as the sum of the diagonal elements of the matrix.

Parameters:

m - The input matrix

Returns:

The trace of the matrix

Since:

5.0.0

transpose

public static <M extends MatrixWritable4x4FType> M transpose(MatrixReadable4x4FType m,
                                                             M out)

Transpose the given matrix m, writing the resulting matrix to out.

Type Parameters:

M - The precise type of matrix

Parameters:

m - The input matrix

out - The output matrix

Returns:

out

transposeInPlace

public static <M extends MatrixWritable4x4FType & MatrixReadable4x4FType> M transposeInPlace(M m)

Transpose the given matrix m, writing the resulting matrix to m.

Type Parameters:

M - The precise type of matrix

Parameters:

m - The input matrix

Returns:

m

compareElements

public static boolean compareElements(MatrixReadable4x4FType m0,
                                      MatrixReadable4x4FType m1)

Compare matrices.

Parameters:

m0 - The left matrix

m1 - The right matrix

Returns:

true if all elements of m0 are equal to m1.

Since:

7.0.0

hashElements

public static int hashElements(MatrixReadable4x4FType m)

Hash matrices.

Parameters:

m - The input matrix

Returns:

The hash of all the elements of m

Since:

7.0.0

showElements

public static void showElements(MatrixReadable4x4FType m,
                                StringBuilder sb)

Show matrices. Print all of the elements of m in square-bracketed matrix form.

Parameters:

m - The input matrix

sb - The string builder

Since:

7.0.0