io7m
io7m-jtensors 6.0.0
io7m-jtensors 6.0.0 Documentation

- 1. Package Information
  - 1.1. Orientation
  - 1.2. Installation
  - 1.3. Platform Specific Issues
  - 1.4. License
- 2. Usage & Conventions
  - 2.1. Vectors
  - 2.2. Matrices
  - 2.3. Quaternions
  - 2.4. Subclassing
- 3. API Reference
  - 3.1. Javadoc

1
Package Information

- 1.1. Orientation
  - 1.1.1. Overview
  - 1.1.2. Efficiency
  - 1.1.3. Correctness
- 1.2. Installation
  - 1.2.1. Source compilation
  - 1.2.2. Maven
- 1.3. Platform Specific Issues
- 1.4. License

1.1
Orientation
1.1.1
Overview
1
The jtensors package implements a set of efficient vector, matrix, and quaternion classes intended for use in computer graphics applications.
1.1.2
Efficiency
1
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.
2
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.
1.1.3
Correctness
1
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.
1.2
Installation
1.2.1
Source compilation
1
The project can be compiled and installed with Maven:
2

    $ mvn -C clean install

1.2.2
Maven
1
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:
2

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

3
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.
1.3
Platform Specific Issues
1
There are currently no known platform-specific issues.
1.4
License
1
All files distributed with the io7m-jtensors package are placed under the following license:

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

    Permission to use, copy, modify, and/or distribute this software for any
    purpose with or without fee is hereby granted, provided that the above
    copyright notice and this permission notice appear in all copies.

    THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
    WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
    MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
    ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
    WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
    ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
    OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

2
Usage & Conventions

- 2.1. Vectors
  - 2.1.1. Types
  - 2.1.2. Access control
- 2.2. Matrices
  - 2.2.1. Types
  - 2.2.2. Storage
  - 2.2.3. Rotations & Handedness
  - 2.2.4. Access control
- 2.3. Quaternions
  - 2.3.1. Types
  - 2.3.2. Rotations & Handedness
  - 2.3.3. Access control
- 2.4. Subclassing

2.1
Vectors

- 2.1.1. Types
- 2.1.2. Access control

2.1.1
Types
1
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):
2.1.1.1. Vector type naming

    mutability   = "M" | "I" ;
    size         = "2" | "3" | "4" ;
    element_type = "I" | "L" | "F" | "D" ;
    type         = "Vector" , mutability , size , element_type ;

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

- VectorM2D
- VectorM2F
- VectorM2I
- VectorM2L
- VectorM3D
- VectorM3F
- VectorM3I
- VectorM3L
- VectorM4D
- VectorM4F
- VectorM4I
- VectorM4L
- VectorI2D
- VectorI2F
- VectorI2I
- VectorI2L
- VectorI3D
- VectorI3F
- VectorI3I
- VectorI3L
- VectorI4D
- VectorI4F
- VectorI4I
- VectorI4L

2.1.2
Access control
1
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.
2.1.2.1. Available vector Readable types

- VectorReadable2I
- VectorReadable2F
- VectorReadable2D
- VectorReadable2L
- VectorReadable3I
- VectorReadable3F
- VectorReadable3D
- VectorReadable3L
- VectorReadable4I
- VectorReadable4F
- VectorReadable4D
- VectorReadable4L

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

2.3
Quaternions

- 2.3.1. Types
- 2.3.2. Rotations & Handedness
- 2.3.3. Access control

2.3.1
Types
1
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):
2.3.1.1. Quaternion type naming

    mutability   = "M" | "I" ;
    size         = "4" ;
    element_type = "F" | "D" ;
    type         = "Quaternion" , mutability , size , element_type ;

2
A comprehensive list of the available quaternion types is as follows:
2.3.1.2. Available quaternion types

- QuaternionM4D
- QuaternionM4F
- QuaternionI4D
- QuaternionI4F

2.3.2
Rotations & Handedness
1
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.
2.3.3
Access control
1
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.
2.3.3.1. Available quaternion Readable types

- QuaternionReadable4F
- QuaternionReadable4D

2.4
Subclassing
1
The types in the jtensors package are not marked as final, despite all of their methods being final. The intention is to allow users of the types to subclass them with the intention of adding "phantom" type parameters [5] in order to distinguish between semantically distinct (but structurally identical) values at compile time.
3
API Reference

- 3.1. Javadoc

3.1
Javadoc
1
API documentation for the package is provided via the included Javadoc.

[0]
http://semver.org
[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.
[5]
http://io7m.com/documents/java/tt1-pt/