io7m
io7m-jtensors 6.0.1
2.2
Matrices

- 2.2.1. Types
- 2.2.2. Storage
- 2.2.3. Rotations & Handedness
- 2.2.4. Access control

2.2.1
Types
1
The jtensors package provides only square matrix types with single-precision (float) elements, and double-precision (double) elements. Matrices are currently only available in mutable form. 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.1. Matrix type naming

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

2
A comprehensive list of the available matrix types is as follows:
2.2.1.2. Available vector types

- MatrixM2x2D
- MatrixM2x2F
- MatrixM3x3D
- MatrixM3x3F
- MatrixM4x4D
- MatrixM4x4F

2.2.2
Storage
1
All of the currently available matrix types are stored in direct memory [1]. This allows for zero-copy passing of the matrix data to native code [2]. Use of direct memory does incur an extra cost with regards to creation and deletion of matrices, and some functions in the package do require temporary matrices in order to work. Therefore, the package provides Context types that allow the user to pre-allocate storage that the functions can reuse an unlimited number of times. The package typically defines one Context type per class. See the MatrixM4x4D.Context type for a concrete example; any function in the MatrixM4x4D class that takes a Context as an argument can be depended upon not to allocate more memory. Note that the Context type cannot be shared across threads and is completely opaque outside of the jtensors package.
2.2.2.1. Context usage

    MatrixM4x4D.Context context = new MatrixM4x4D.Context();
    MatrixM4x4D mi = new MatrixM4x4D();
    MatrixM4x4D mo = new MatrixM4x4D();

    MatrixM4x4D.invertWithContext(context, mi, mo);
    MatrixM4x4D.invertWithContext(context, mo, mi);

2
Matrix data is stored in column-major format [3], 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).
3
As an example, a 4x4 matrix with 4 byte elements would be stored in memory as shown in the following diagram:
2.2.2.2. Column-major storage memory layout
4
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
Rotations & Handedness
1
Any of the matrix functions that deal with rotations assume a right-handed coordinate system. This matches the system used by OpenGL (and most mathematics literature). A right-handed coordinate system assumes that if the viewer is standing at the origin and looking towards negative infinity on the Z axis, then the X axis runs horizontally (left towards negative infinity and right towards positive infinity), and the Y axis runs vertically (down towards negative infinity and up towards positive infinity). The following image demonstrates this axis configuration:
2.2.3.1. Right-handed coordinate system
2
The jtensors package adheres to the convention that a positive rotation around an axis represents a counter-clockwise rotation when viewing the system along the negative direction of the axis in question.
2.2.3.2. Right-handed rotations
3
The package uses the following matrices to define rotations around each axis:
2.2.3.3. Rotation of r radians around the X axis
2.2.3.4. Rotation of r radians around the Y axis
2.2.3.5. Rotation of r radians around the Z axis
4
Which results in the following matrix for rotating r radians around the axis given by (x, y, z), assuming s = sin(r) and c = cos(r) [4]:
2.2.3.6. Rotation of r radians around an arbitrary axis
2.2.4
Access control
1
If a function only needs to read from a value of a matrix type, then it would be desirable to be able to statically enforce this fact. Therefore, the package provides a set of Readable interfaces that all matrix types implement. By writing a function that takes a value of a type implementing a Readable interface, the programmer is implicitly stating that this function does not modify the matrix.
2.2.4.1. Available matrix Readable types

- MatrixReadable2x2F
- MatrixReadable2x2D
- MatrixReadable3x3F
- MatrixReadable3x3D
- MatrixReadable4x4F
- MatrixReadable4x4D

[1]
See ByteBuffer.allocateDirect(int).
[2]
Typically, the OpenGL API.
[3]
The convention used by most programs using the OpenGL API.
[4]
See Mathematics for 3D Game Programming and Computer Graphics 3rd Edition, section 4.3.1 for the derivation.