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

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

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