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

    All Methods Static Methods Concrete Methods
    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`

Copyright © 2017 <code@io7m.com> http://io7m.com