io7m | single-page | multi-page | epub | jtensors User Manual 11.0.0
2.1. Vectors
Previous
2. Conventions
Up
2.3. Quaternions
Next

# 2.2. Matrices

- 2.2.1. Computation Types
- 2.2.2. Storage Types
- 2.2.3. Phantom Types

## 2.2.1. Computation Types

1
The com.io7m.jtensors package provides square computation matrices with single-precision (float) elements, and double-precision (double) elements. Each matrix type is available in 2x2, 3x3, and 4x4 versions. The package unambiguously identifies the matrix types by using the following naming conventions for the types (given as a simple EBNF grammar):

### 2.2.1.2. Matrix type naming

    prefix       = "Matrix" | "PMatrix"
    size         = "2x2" | "3x3" | "4x4" ;
    element_type = "F" | "D" ;
    type         = prefix , size , element_type ;

3
Computation matrices are always immutable and are defined in such a way to allow the Java virtual machine to efficiently inline all matrix method calls and to eliminate the allocations of intermediate matrices via escape analysis.
4
The available matrix types include:

### 2.2.1.5. Matrix types

- Matrix2x2D
- Matrix3x3D
- Matrix4x4D
- Matrix2x2F
- Matrix3x3F
- Matrix4x4F
- PMatrix2x2D
- PMatrix3x3D
- PMatrix4x4D
- PMatrix2x2F
- PMatrix3x3F
- PMatrix4x4F

## 2.2.2. Storage Types

1
The com.io7m.jtensors package provides mutable storage matrices. A storage matrix is a mutable matrix upon which only very simple get and set operations are defined. The intention is to allow all intermediate computations to be written with immutable computation matrices, with the final results of those computations being written to storage matrices in order to, for example, be passed directly to native code without requiring copying.
2
To enumerate the available storage matrix types, see the API documentation for the MatrixStorageType interface.
3
Matrix data is stored in column-major format [1], in whatever is the platform's native byte order. For an m x m square matrix, assuming that each element of the matrix uses n bytes, the first byte of the element at row r and column c (assuming 0 <= r < m and 0 <= c < m) can be found by (c * m * n) + (r * n).

### 2.2.2.4. Column-major storage memory layout

5
So, the element at row 0, column 0 would be stored in bytes [0 .. 3]. The element at row 1, column 0 would be stored in bytes [4 .. 7]. The element at row 0, column 1 would be stored in bytes [16 .. 19], and so on.

## 2.2.3. Phantom Types

1
As with the vector types, the com.io7m.jtensors package provides copies of all the existing matrix types indexed by a pair of phantom type parameters.
2
Conceptually, a matrix can be considered as storing a transform from coordinate space T0 to space T1. For a 4x4 matrix in the com.io7m.jtensors package, this is denoted by the type PMatrix4x4D<T0,T1>. It then follows that when matrices are concatenated via multiplications, their type parameters are translated accordingly. For example, a matrix PMatrix4x4D<T0,T1> multiplied by a matrix PMatrix4x4D<T1,T2> results in a matrix of type PMatrix4x4D<T0,T2>. Inverting a matrix results in a matrix that represents the inverse of the original transform that the matrix represented. For example, inverting a matrix of type PMatrix4x4D<T0,T1> results in a matrix of type PMatrix4x4D<T1,T0>.
3
Type parameters are also translated across multiplications by vectors. A multiplication of a vector of type PVector4D<T0> by a matrix of type PMatrix4x4D<T0,T1> results in a vector of type PVector4D<T1>.
4
Being able to track the types of transforms at this level of detail is invaluable when using systems such as OpenGL, where accidentally mixing up matrices tends to result in visual anomalies that can be extremely hard to track down. By explicitly denoting coordinate spaces with empty types, it's possible to statically prevent all bugs involving accidentally mixing up matrices. It's also possible to prevent the incorrect construction of matrices [2]. Additionally, with each matrix labelled by the type of transform it represents, code becomes self-documenting.

### 2.2.3.5. Static tracking of transforms

    interface WorldSpace { }
    interface ViewSpace { }
    interface ObjectSpace { }

    PMatrix4x4D<ObjectSpace, WorldSpace> matrix_model;
    PMatrix4x4D<WorldSpace, ViewSpace> matrix_view;
    PMatrix4x4D<ObjectSpace, ViewSpace> matrix_modelview;

    // Correct!
    matrix_modelview = PMatrices4x4D.multiply (matrix_view, matrix_model);

    // Correct!
    Optional<PMatrix4x4D<ViewSpace, WorldSpace>> matrix_view_inverse =
      PMatrices4x4D.invert(matrix_view);

    // Compilation error: The resulting matrix would be of type PMatrix4x4D<ViewSpace, ObjectSpace>
    // matrix_modelview = PMatrices4x4D.multiply (matrix_model, matrix_view);

## Footnotes

1 | The convention used by most programs using the OpenGL API. References to this footnote: 1
2 | It is common for people to make mistakes with matrix multiplication: The order of matrices is effectively the reverse of the order in which the transforms will be applied. References to this footnote: 1

2.1. Vectors
Previous
2. Conventions
Up
2.3. Quaternions
Next
io7m | single-page | multi-page | epub | jtensors User Manual 11.0.0