The jtensors package implements a set of efficient vector, matrix, and quaternion classes intended for use in computer graphics applications.

The package uses simple and efficient algorithms for all operations. The package also provides matrices that are backed by direct memory, allowing for zero-copy sharing of structures with native code.

Many of the matrix functions also provide interfaces that allow for preallocation of all storage, reducing garbage collector pressure in code with soft-realtime constraints.

The package includes a large battery of automated tests that attempt to verify the correctness of the included implementations. As of the time of writing, the tests manage 100% coverage for all code.

The project can be compiled and installed with Maven:

$ mvn -C clean install

Regular releases are made to the Central Repository, so it's possible to use the io7m-jtensors package in your projects with the following Maven dependency:

<dependency>
  <groupId>com.io7m.jtensors</groupId>
  <artifactId>io7m-jtensors-core</artifactId>
  <version>6.0.2</version>
</dependency>

All io7m.com packages use Semantic Versioning [0], which implies that it is always safe to use version ranges with an exclusive upper bound equal to the next major version - the API of the package will not change in a backwards-incompatible manner before the next major version.

The jtensors package provides vectors with single-precision (float) elements, double-precision (double) elements, integer (int), and long integer (long) elements. Each vector type is available in two, three, and four element versions. Each vector type is available in mutable or immutable versions. The package unambiguously identifies the vector types by using the following naming conventions for the types (given as a simple EBNF grammar):

A comprehensive list of the available vector types is as follows:

If a function only needs to read from a value of a vector 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 vector 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 vector.

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):

A comprehensive list of the available matrix types is as follows:

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.

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).

As an example, a 4x4 matrix with 4 byte elements would be stored in memory as shown in the following diagram:

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.

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:

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.

The package uses the following matrices to define rotations around each axis:

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]:

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.

The jtensors package provides quaternions with single-precision (float) elements, and double-precision (double) elements. Each quaternion type is available in mutable or immutable versions. The package unambiguously identifies the quaternion types by using the following naming conventions for the types (given as a simple EBNF grammar):

A comprehensive list of the available quaternion types is as follows:

The included quaternion types and functions have consistent semantics and assumptions with regards to rotation and coordinate systems as the Matrix types, and functions are provided to convert between matrices and quaternions.

If a function only needs to read from a value of a quaternion 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 quaternion 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 quaternion.