com.io7m.jtensors

Class MatrixM3x3D

java.lang.Object

com.io7m.jtensors.MatrixM3x3D

public final class MatrixM3x3D
extends Object

A 3x3 mutable matrix type with double elements.

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

Method Summary

Modifier and Type	Method and Description
static <M extends MatrixWritable3x3DType> M	add(MatrixReadable3x3DType m0, MatrixReadable3x3DType m1, M out) Elementwise add of matrices m0 and m1.
static <M extends MatrixWritable3x3DType & MatrixReadable3x3DType> M	addInPlace(M m0, MatrixReadable3x3DType m1) Elementwise add of matrices m0 and m1, returning the result in m0.
static <M extends MatrixWritable3x3DType> M	addRowScaled(MatrixM3x3D.ContextMM3D c, MatrixReadable3x3DType 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 MatrixWritable3x3DType & MatrixReadable3x3DType> M	addRowScaledInPlace(MatrixM3x3D.ContextMM3D c, 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(MatrixReadable3x3DType m0, MatrixReadable3x3DType m1) Compare matrices.
static <M extends MatrixWritable3x3DType> M	copy(MatrixReadable3x3DType input, M output) Copy the contents of the matrix input to the matrix output, completely replacing all elements.
static double	determinant(MatrixReadable3x3DType m) Calculate the determinant of the matrix m.
static <M extends MatrixWritable3x3DType> M	exchangeRows(MatrixM3x3D.ContextMM3D c, MatrixReadable3x3DType m, int row_a, int row_b, M out) Exchange the row row_a and row row_b of the matrix m, saving the exchanged rows to out.
static <M extends MatrixWritable3x3DType & MatrixReadable3x3DType> M	exchangeRowsInPlace(MatrixM3x3D.ContextMM3D c, 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(MatrixReadable3x3DType m) Hash matrices.
static <M extends MatrixWritable3x3DType> boolean	invert(MatrixM3x3D.ContextMM3D c, MatrixReadable3x3DType m, M out) Calculate the inverse of the matrix m, saving the resulting matrix to out.
static <M extends MatrixWritable3x3DType & MatrixReadable3x3DType> boolean	invertInPlace(MatrixM3x3D.ContextMM3D c, M m) Calculate the inverse of the matrix m, saving the resulting matrix to m.
static <M extends MatrixWritable3x3DType,V extends VectorWritable3DType> void	lookAt(MatrixM3x3D.ContextMM3D context, VectorReadable3DType origin, VectorReadable3DType target, VectorReadable3DType up, M out_matrix, V out_translation) Calculate a rotation and translation representing a "camera" looking from the point origin to the point target.
static <M extends MatrixWritable3x3DType> 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 MatrixWritable3x3DType> M	makeTranslation2D(VectorReadable2DType v, M out) Create a translation matrix that represents a translation by the vector v, writing the resulting matrix to out.
static <M extends MatrixWritable3x3DType> M	makeTranslation2I(VectorReadable2IType v, M out) Create a translation matrix that represents a translation by the vector v, writing the resulting matrix to out.
static <M extends MatrixWritable3x3DType> M	multiply(MatrixReadable3x3DType m0, MatrixReadable3x3DType m1, M out) Multiply the matrix m0 with the matrix m1, writing the result to out.
static <M extends MatrixWritable3x3DType & MatrixReadable3x3DType> M	multiplyInPlace(M m0, MatrixReadable3x3DType m1) Multiply the matrix m0 with the matrix m1, writing the result to m0.
static <V extends VectorWritable3DType> V	multiplyVector3D(MatrixM3x3D.ContextMM3D c, MatrixReadable3x3DType m, VectorReadable3DType v, V out) Multiply the matrix m with the vector v, writing the resulting vector to out.
static <M extends MatrixWritable3x3DType> M	scale(MatrixReadable3x3DType 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 MatrixWritable3x3DType & MatrixReadable3x3DType> 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 MatrixWritable3x3DType> M	scaleRow(MatrixM3x3D.ContextMM3D c, MatrixReadable3x3DType m, int row, double r, M out) Scale row r of the matrix m by r, saving the result to row r of out.
static <M extends MatrixWritable3x3DType & MatrixReadable3x3DType> M	scaleRowInPlace(MatrixM3x3D.ContextMM3D c, M m, int row, double r) Scale row r of the matrix m by r, saving the result to row r of m.
static <M extends MatrixWritable3x3DType> M	setIdentity(M m) Set the given matrix m to the identity matrix.
static <M extends MatrixWritable3x3DType> M	setZero(M m) Set the given matrix m to the zero matrix.
static void	showElements(MatrixReadable3x3DType m, StringBuilder sb) Show matrices.
static double	trace(MatrixReadable3x3DType m) Return the trace of the matrix m.
static <M extends MatrixWritable3x3DType> M	transpose(MatrixReadable3x3DType m, M out) Transpose the given matrix m, writing the resulting matrix to out.
static <M extends MatrixWritable3x3DType & MatrixReadable3x3DType> 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 MatrixWritable3x3DType> M add(MatrixReadable3x3DType m0,
                                                       MatrixReadable3x3DType 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 MatrixWritable3x3DType & MatrixReadable3x3DType> M addInPlace(M m0,
                                                                                       MatrixReadable3x3DType 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 MatrixWritable3x3DType> M addRowScaled(MatrixM3x3D.ContextMM3D c,
                                                                MatrixReadable3x3DType 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.

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

Type Parameters:

M - The precise type of matrix

Parameters:

c - 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 MatrixWritable3x3DType & MatrixReadable3x3DType> M addRowScaledInPlace(MatrixM3x3D.ContextMM3D c,
                                                                                                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:

c - 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

copy

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

Calculate the determinant of the matrix m.

Parameters:

m - The input matrix

Returns:

The determinant

exchangeRows

public static <M extends MatrixWritable3x3DType> M exchangeRows(MatrixM3x3D.ContextMM3D c,
                                                                MatrixReadable3x3DType m,
                                                                int row_a,
                                                                int row_b,
                                                                M out)

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

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

Type Parameters:

M - The precise type of matrix

Parameters:

c - Preallocated storage

m - The input matrix

row_a - The first row

row_b - The second row

out - The output matrix

Returns:

out

exchangeRowsInPlace

public static <M extends MatrixWritable3x3DType & MatrixReadable3x3DType> M exchangeRowsInPlace(MatrixM3x3D.ContextMM3D c,
                                                                                                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.

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

Type Parameters:

M - The precise type of matrix

Parameters:

c - Preallocated storage

m - The input matrix

row_a - The first row

row_b - The second row

Returns:

m

invert

public static <M extends MatrixWritable3x3DType> boolean invert(MatrixM3x3D.ContextMM3D c,
                                                                MatrixReadable3x3DType 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. If the function returns None, m is untouched.

Type Parameters:

M - The precise type of matrix

Parameters:

c - Preallocated storage

m - The input matrix

out - The output matrix

Returns:

true iff the matrix was invertible

See Also:

determinant(MatrixReadable3x3DType)

invertInPlace

public static <M extends MatrixWritable3x3DType & MatrixReadable3x3DType> boolean invertInPlace(MatrixM3x3D.ContextMM3D c,
                                                                                                M m)

Calculate the inverse of the matrix m, saving the resulting matrix to m. The function returns Some(m) 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. If the function returns None, m is untouched.

Type Parameters:

M - The precise type of matrix

Parameters:

c - Preallocated storage

m - The input matrix

Returns:

true iff the matrix was invertible

See Also:

determinant(MatrixReadable3x3DType)

lookAt

public static <M extends MatrixWritable3x3DType,V extends VectorWritable3DType> void lookAt(MatrixM3x3D.ContextMM3D context,
                                                                                            VectorReadable3DType origin,
                                                                                            VectorReadable3DType target,
                                                                                            VectorReadable3DType up,
                                                                                            M out_matrix,
                                                                                            V out_translation)

Calculate a rotation and translation 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 matrix and a translation vector, written to out_matrix and out_translation, respectively.

Type Parameters:

M - The precise type of matrix

V - The precise type of vector

Parameters:

context - Preallocated storage

out_matrix - The output matrix

out_translation - The output translation

origin - The position of the viewer

target - The target being viewed

up - The up vector

makeRotation

public static <M extends MatrixWritable3x3DType> 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

Since:

7.0.0

makeTranslation2D

public static <M extends MatrixWritable3x3DType> M makeTranslation2D(VectorReadable2DType v,
                                                                     M out)

Create a translation matrix that represents a translation by the vector v, writing the resulting matrix 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 MatrixWritable3x3DType> M makeTranslation2I(VectorReadable2IType v,
                                                                     M out)

Create a translation matrix that represents a translation by the vector v, writing the resulting matrix 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 MatrixWritable3x3DType> M multiply(MatrixReadable3x3DType m0,
                                                            MatrixReadable3x3DType 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 MatrixWritable3x3DType & MatrixReadable3x3DType> M multiplyInPlace(M m0,
                                                                                            MatrixReadable3x3DType 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

multiplyVector3D

public static <V extends VectorWritable3DType> V multiplyVector3D(MatrixM3x3D.ContextMM3D c,
                                                                  MatrixReadable3x3DType m,
                                                                  VectorReadable3DType v,
                                                                  V out)

Multiply the matrix m with the vector v, writing the resulting vector to out.

Type Parameters:

V - The precise type of writable vector

Parameters:

c - Preallocated storage

m - The input matrix

v - The input vector

out - The output vector

Returns:

out

scale

public static <M extends MatrixWritable3x3DType> M scale(MatrixReadable3x3DType 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:

m - The input matrix

r - The scaling value

out - The output matrix

Returns:

out

scaleInPlace

public static <M extends MatrixWritable3x3DType & MatrixReadable3x3DType> 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

scaleRow

public static <M extends MatrixWritable3x3DType> M scaleRow(MatrixM3x3D.ContextMM3D c,
                                                            MatrixReadable3x3DType m,
                                                            int row,
                                                            double r,
                                                            M out)

Scale row r of the matrix m by r, saving the result to row r of out.

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

Type Parameters:

M - The precise type of matrix

Parameters:

c - Preallocated storage

m - The input matrix

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

r - The scaling value

out - The output matrix

Returns:

out

scaleRowInPlace

public static <M extends MatrixWritable3x3DType & MatrixReadable3x3DType> M scaleRowInPlace(MatrixM3x3D.ContextMM3D c,
                                                                                            M m,
                                                                                            int row,
                                                                                            double r)

Scale row r of the matrix m by r, saving the result to row r of m.

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

Type Parameters:

M - The precise type of matrix

Parameters:

c - Preallocated storage

m - The input matrix

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

r - The scaling value

Returns:

m

setIdentity

public static <M extends MatrixWritable3x3DType> 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 MatrixWritable3x3DType> M setZero(M m)

Set the given matrix m to the zero matrix.

Type Parameters:

M - The precise type of matrix

Parameters:

m - The input matrix

Returns:

m

trace

public static double trace(MatrixReadable3x3DType 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 MatrixWritable3x3DType> M transpose(MatrixReadable3x3DType 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 MatrixWritable3x3DType & MatrixReadable3x3DType> 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(MatrixReadable3x3DType m0,
                                      MatrixReadable3x3DType 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(MatrixReadable3x3DType 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(MatrixReadable3x3DType 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