com.io7m.jtensors

Class MatrixM4x4D

java.lang.Object

com.io7m.jtensors.MatrixM4x4D

public final class MatrixM4x4D
extends Object

Functions over 4x4 mutable matrix types with double elements.

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	MatrixM4x4D.ContextMM4D The ContextMM4D type contains the minimum storage required for all of the functions of the MatrixM4x4D class.

Method Summary

Modifier and Type	Method and Description
static <M extends MatrixWritable4x4DType> M	add(MatrixReadable4x4DType m0, MatrixReadable4x4DType m1, M out) Elementwise add of matrices m0 and m1.
static <M extends MatrixWritable4x4DType & MatrixReadable4x4DType> M	addInPlace(M m0, MatrixReadable4x4DType m1) Elementwise add of matrices m0 and m1, returning the result in m0.
static <M extends MatrixWritable4x4DType> M	addRowScaled(MatrixM4x4D.ContextMM4D context, MatrixReadable4x4DType 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 MatrixWritable4x4DType & MatrixReadable4x4DType> M	addRowScaledInPlace(MatrixM4x4D.ContextMM4D 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 out.
static boolean	compareElements(MatrixReadable4x4DType m0, MatrixReadable4x4DType m1) Compare matrices.
static <M extends MatrixWritable4x4DType> M	copy(MatrixReadable4x4DType input, M output) Copy the contents of the matrix input to the matrix output, completely replacing all elements.
static double	determinant(MatrixReadable4x4DType m) Calculate the determinant of the matrix m.
static <M extends MatrixWritable4x4DType> M	exchangeRows(MatrixM4x4D.ContextMM4D context, MatrixReadable4x4DType 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 MatrixWritable4x4DType & MatrixReadable4x4DType> M	exchangeRowsInPlace(MatrixM4x4D.ContextMM4D 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(MatrixReadable4x4DType m) Hash matrices.
static <M extends MatrixWritable4x4DType> boolean	invert(MatrixM4x4D.ContextMM4D context, MatrixReadable4x4DType m, M out) Calculate the inverse of the matrix m, saving the resulting matrix to out.
static <M extends MatrixWritable4x4DType & MatrixReadable4x4DType> boolean	invertInPlace(MatrixM4x4D.ContextMM4D context, M m) Calculate the inverse of the matrix m, saving the resulting matrix to m.
static <M extends MatrixWritable4x4DType> void	lookAt(MatrixM4x4D.ContextMM4D context, VectorReadable3DType origin, VectorReadable3DType target, VectorReadable3DType up, M out_matrix) Calculate a matrix representing a "camera" looking from the point origin to the point target.
static <M extends MatrixWritable4x4DType> M	makeRotation(double angle, VectorReadable3DType axis, M out) Generate a matrix that represents a rotation of angle radians around the axis axis and save to out.
static <M extends MatrixWritable4x4DType> M	makeTranslation2D(VectorReadable2DType 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 MatrixWritable4x4DType> 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 MatrixWritable4x4DType> M	makeTranslation3D(VectorReadable3DType 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 MatrixWritable4x4DType> 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 MatrixWritable4x4DType> M	multiply(MatrixReadable4x4DType m0, MatrixReadable4x4DType m1, M out) Multiply the matrix m0 with the matrix m1, writing the result to out.
static <M extends MatrixWritable4x4DType & MatrixReadable4x4DType> M	multiplyInPlace(M m0, MatrixReadable4x4DType m1) Multiply the matrix m0 with the matrix m1, writing the result to m0.
static <V extends VectorWritable4DType> V	multiplyVector4D(MatrixM4x4D.ContextMM4D context, MatrixReadable4x4DType m, VectorReadable4DType v, V out) Multiply the matrix m with the vector v, writing the resulting vector to out.
static <M extends MatrixWritable4x4DType> M	scale(MatrixReadable4x4DType 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 MatrixWritable4x4DType & MatrixReadable4x4DType> 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 MatrixWritable4x4DType> M	scaleRow(MatrixM4x4D.ContextMM4D context, MatrixReadable4x4DType 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 MatrixWritable4x4DType & MatrixReadable4x4DType> M	scaleRowInPlace(MatrixM4x4D.ContextMM4D 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 MatrixWritable4x4DType> M	setIdentity(M m) Set the given matrix m to the identity matrix.
static <M extends MatrixWritable4x4DType> M	setZero(M m) Set the given matrix m to the zero matrix.
static void	showElements(MatrixReadable4x4DType m, StringBuilder sb) Show matrices.
static double	trace(MatrixReadable4x4DType m) Return the trace of the matrix m.
static <M extends MatrixWritable4x4DType> M	transpose(MatrixReadable4x4DType m, M out) Transpose the given matrix m, writing the resulting matrix to out.
static <M extends MatrixWritable4x4DType & MatrixReadable4x4DType> 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

compareElements

public static boolean compareElements(MatrixReadable4x4DType m0,
                                      MatrixReadable4x4DType 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(MatrixReadable4x4DType 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(MatrixReadable4x4DType 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

add

public static <M extends MatrixWritable4x4DType> M add(MatrixReadable4x4DType m0,
                                                       MatrixReadable4x4DType 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 MatrixWritable4x4DType & MatrixReadable4x4DType> M addInPlace(M m0,
                                                                                       MatrixReadable4x4DType 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

addRowScaled

public static <M extends MatrixWritable4x4DType> M addRowScaled(MatrixM4x4D.ContextMM4D context,
                                                                MatrixReadable4x4DType 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

addRowScaledInPlace

public static <M extends MatrixWritable4x4DType & MatrixReadable4x4DType> M addRowScaledInPlace(MatrixM4x4D.ContextMM4D 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 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

Returns:

out

copy

public static <M extends MatrixWritable4x4DType> M copy(MatrixReadable4x4DType 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(MatrixReadable4x4DType m)

Calculate the determinant of the matrix m.

Parameters:

m - The input matrix

Returns:

The determinant.

exchangeRowsInPlace

public static <M extends MatrixWritable4x4DType & MatrixReadable4x4DType> M exchangeRowsInPlace(MatrixM4x4D.ContextMM4D 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 MatrixWritable4x4DType> M exchangeRows(MatrixM4x4D.ContextMM4D context,
                                                                MatrixReadable4x4DType 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 MatrixWritable4x4DType & MatrixReadable4x4DType> boolean invertInPlace(MatrixM4x4D.ContextMM4D 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(MatrixReadable4x4DType)

invert

public static <M extends MatrixWritable4x4DType> boolean invert(MatrixM4x4D.ContextMM4D context,
                                                                MatrixReadable4x4DType 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(MatrixReadable4x4DType)

lookAt

public static <M extends MatrixWritable4x4DType> void lookAt(MatrixM4x4D.ContextMM4D context,
                                                             VectorReadable3DType origin,
                                                             VectorReadable3DType target,
                                                             VectorReadable3DType 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 MatrixWritable4x4DType> M makeRotation(double angle,
                                                                VectorReadable3DType 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

makeTranslation2D

public static <M extends MatrixWritable4x4DType> M makeTranslation2D(VectorReadable2DType 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 MatrixWritable4x4DType> 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

makeTranslation3D

public static <M extends MatrixWritable4x4DType> M makeTranslation3D(VectorReadable3DType 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 MatrixWritable4x4DType> 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 MatrixWritable4x4DType> M multiply(MatrixReadable4x4DType m0,
                                                            MatrixReadable4x4DType 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 MatrixWritable4x4DType & MatrixReadable4x4DType> M multiplyInPlace(M m0,
                                                                                            MatrixReadable4x4DType 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

multiplyVector4D

public static <V extends VectorWritable4DType> V multiplyVector4D(MatrixM4x4D.ContextMM4D context,
                                                                  MatrixReadable4x4DType m,
                                                                  VectorReadable4DType 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.

Formally, this can be considered to be premultiplication of the column vector v with the matrix m.

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 MatrixWritable4x4DType> M scale(MatrixReadable4x4DType 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:

m

scaleInPlace

public static <M extends MatrixWritable4x4DType & MatrixReadable4x4DType> 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 MatrixWritable4x4DType & MatrixReadable4x4DType> M scaleRowInPlace(MatrixM4x4D.ContextMM4D 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 MatrixWritable4x4DType> M scaleRow(MatrixM4x4D.ContextMM4D context,
                                                            MatrixReadable4x4DType 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 MatrixWritable4x4DType> M setIdentity(M m)

Set the given matrix m to the identity matrix.

Type Parameters:

M - The precise type of matrix

Parameters:

m - The matrix

Returns:

m

setZero

public static <M extends MatrixWritable4x4DType> 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(MatrixReadable4x4DType 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 MatrixWritable4x4DType> M transpose(MatrixReadable4x4DType 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 MatrixWritable4x4DType & MatrixReadable4x4DType> 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