Michael Heilmann's Arcadia Math

This is the documentation for Michael Heilmann's Arcadia Math. Arcadia Math provides matrix and vector math used in the fields of audials and visuals.

Files

You can find the sources of Arcadia Math in my GitHub repository https://github.com/michaelheilmann/arcadia. The subdirectory of Arcadia Math in the repository is here https://github.com/michaelheilmann/arcadia/tree/main/repository/Math.

The (sources of the) library resides in the directory https://github.com/michaelheilmann/arcadia/tree/main/repository/Math/Library
The (sources of) tests reside in the directory https://github.com/michaelheilmann/arcadia/tree/main/repository/Math/Tests
The (sources of this very documentation you are reading) documentation reside in the directory https://github.com/michaelheilmann/arcadia/tree/main/repository/Math/Documentation

Arcadia Math supports various platforms (including but not restricted to Windows, Linux, and many more), however, we currently only officially support Windows. For instructions on how to build, test, and use Arcadia Math, refer to README.md in the root folder of the repository.

Further References

Arcadia Math relies on Arcadia Ring 2.

Documentation

Arcadia_Math_VectorNumberOfElementsElementType

Arcadia_Math_VectorNumberOfElementsSuffixElementType extends Arcadia_Object.

Arcadia_Math_VectorNumberOfElementsElementType is a mutable representation of a column vector. The vector has NumberOfElements elements, the elements are of type Type.

The above types are defined for NumberOfElements = n where n is three or four.

The following table lists the combinations of Type and Suffix for which the above types are defined

ElementType	Type
`Real32Value`	`Arcadia_Real32Value`
`Real64Value`	`Arcadia_Real64Value`

Arcadia_Math_MatrixNumberOfColumnsxNumberOfRowsElementTypeSuffix

Arcadia_Math_MatrixNumberOfColumnsxNumberOfRowsElementTypeSuffix extends Arcadia_Object.

Arcadia_Math_MatrixNumberOfColumnsxNumberOfRowsElementTypeSuffix is a mutable representation of a matrix. The matrix has NumberOfColumns columns and NumberOfRows rows, the elements are of a type indicated by ElementTypeSuffix.

ElementTypeSuffix indicates the Arcadia type of the elements. The following table lists the ElementTypeSuffix and the corresponding Arcadia types of the elements.

ElementTypeSuffix	ElementType
`Real32Value`	`Arcadia_Real32Value`
`Real64Value`	`Arcadia_Real64Value`

The above types are defined for NumberOfColumns = n and NumberOfRows = n where n is three or four.

Arcadia_Math_MatrixNumberOfColumnsxNumberOfRowsElementTypeSuffix_setIdentity


  void

  Arcadia_Math_MatrixNumberOfColumnsxNumberOfRowsElementTypeSuffix_setIdentity

    (

      Arcadia_Thread* thread,

      Arcadia_Math_MatrixNumberOfColumnsxNumberOfRowsElementTypeSuffix* self

    )

Assign the elements of this Arcadia_Math_MatrixNumberOfColumnsxNumberOfRowsElementTypeSuffix object the values of the identity matrix. The identity matrix is defined as \[ \forall i, j \in [1,n] c_{i,j} = \begin{cases} 1 & \text{if } i = j,\\ 0 & \text{otherwise} \end{cases} \]

Parameters

Arcadia_Thread* thread

A pointer to the Arcadia_Thread object.

Arcadia_Math_MatrixNumberOfColumnsxNumberOfRowsElementTypeSuffix* self

A pointer to this Arcadia_Math_MatrixNumberOfColumnsxNumberOfRowsElementTypeSuffix object.

Arcadia_Math_MatrixNumberOfColumnsxNumberOfRowsElementTypeSuffix_setOrthographicProjection


  void

  Arcadia_Math_MatrixNumberOfColumnsxNumberOfRowsElementTypeSuffix_setOrthographicProjection

    (

      Arcadia_Thread* thread,

      Arcadia_Math_MatrixNumberOfColumnsxNumberOfRowsElementTypeSuffix* self,

      ElementType left,

      ElementType right,

      ElementType bottom,

      ElementType top,

      ElementType near,

      ElementType far

    )

Assign the elements of this Arcadia_Math_MatrixNumberOfColumnsxNumberOfRowsElementTypeSuffix object the values of an orthographic projection matrix. This function is defined for \(4 \times 4\).

The projection matrix is defined as

\[ \begin{matrix} a & 0 & 0 & u \\ 0 & b & 0 & v \\ 0 & 0 & c & w \\ 0 & 0 & 0 & 1 \end{matrix} \] where

\(a = \frac{2}{right-left}\)
\(b = \frac{2}{top-bottom}\)
\(c = -\frac{2}{far - near}\)
\(u = -\frac{right + left}{right - left}\)
\(v = -\frac{top + bottom}{top - bottom}\)
\(w = -\frac{far + near}{far - near}\)

The resulting matrix sets up the axes as follows:

the positive z-axis points out of the canvas (negative z-axis points into the canvas)
the positive x-axis points to the right
the positive y-axis points to the top

ElementTypeSuffix indicates the Arcadia type of the elements and parameters denoted by ElementType. The following table lists the ElementTypeSuffix and the corresponding ElementType.

ElementTypeSuffix	ElementType
`Real32Value`	`Arcadia_Real32Value`
`Real64Value`	`Arcadia_Real64Value`

Parameters

Arcadia_Thread* thread

A pointer to the Arcadia_Thread object.

Arcadia_Math_MatrixNumberOfColumnsxNumberOfRowsElementTypeSuffix* self

A pointer to this Arcadia_Math_MatrixNumberOfColumnsxNumberOfRowsElementTypeSuffix object.

ElementType left

The coordinate of the left clipping plane.

ElementType right

The coordinate of the right clipping plane.

ElementType bottom

The coordinate of the bottom clipping plane.

ElementType top

The coordinate of the top clipping plane.

ElementType near

The coordinate of the near clipping plane.

ElementType far

The coordinate of the far clipping plane.

Arcadia_Math_MatrixNumberOfColumnsxNumberOfRowsElementTypeSuffix_setPerspectiveProjection


  void

  Arcadia_Math_MatrixNumberOfColumnsxNumberOfRowsElementTypeSuffix_setOrthographicProjection

    (

      Arcadia_Thread* thread,

      Arcadia_Math_MatrixNumberOfColumnsxNumberOfRowsElementTypeSuffix* self,

      ElementType fieldOfView,

      ElementType aspectRatio,

      ElementType near,

      ElementType far

    )

Assign the elements of this Arcadia_Math_MatrixNumberOfColumnsxNumberOfRowsElementTypeSuffix object the values of a perspective projection matrix. This function is defined for \(4 \times 4\).

The projection matrix is defined as

\[ \begin{matrix} \frac{f}{\textit{aspectRatio}} & 0 & 0 & 0 \\ 0 & f & 0 & 0 \\ 0 & 0 & \frac{\textit{near} + \textit{far}}{\textit{near} - \textit{far}} & \frac{2 \cdot \textit{near} \cdot \textit{far}}{\textit{near} - \textit{far}} \\ 0 & 0 & -1 & 0 \end{matrix} \] where \(f = \cot\left(\frac{\textit{fieldOfView}}{2}\right)\).

The resulting matrix sets up the axes as follows:

the positive z-axis points out of the canvas (negative z-axis points into the canvas)
the positive x-axis points to the right
the positive y-axis points to the top

ElementTypeSuffix indicates the Arcadia type of the elements and parameters denoted by ElementType. The following table lists the ElementTypeSuffix and the corresponding ElementType.

ElementTypeSuffix	ElementType
`Real32Value`	`Arcadia_Real32Value`
`Real64Value`	`Arcadia_Real64Value`

Parameters

Arcadia_Thread* thread

A pointer to the Arcadia_Thread object.

Arcadia_Math_MatrixNumberOfColumnsxNumberOfRowsElementTypeSuffix* self

A pointer to this Arcadia_Math_MatrixNumberOfColumnsxNumberOfRowsElementTypeSuffix object.

ElementType fieldOfView

The field of view angle, in degrees, in the y-direction. Must be positive. In other terms: the angle between a plane passing through the camera position as well as the top of your canvas and another plane passing through the camera position and the bottom of the canvas. The bigger this angle is the more you can see of the world - but at the same time, the object you can see become smaller.

ElementType aspectRatio

The aspect ratio which determines the field of view in the x-direction. The aspect ratio is the ratio of width and height. Must be positive. Typical canvas have aspect ratios of 4:3 or 16:9.

ElementType near

The distance of the viewer to the near clipping plane. Must be positive. Must be less than far or nothing is displayed

ElementType far

The distance of the viewer to the far clipping plane. Must be positive. Must be greater than near.

Arcadia_Math_MatrixNumberOfColumnsxNumberOfRowsElementTypeSuffix_setRotationX


  void

  Arcadia_Math_MatrixNumberOfColumnsxNumberOfRowsElementTypeSuffix_setRotationX

    (

      Arcadia_Thread* thread,

      Arcadia_Math_MatrixNumberOfColumnsxNumberOfRowsElementTypeSuffix* self,

      ElementType angle

    )

Assign the elements of this Arcadia_Math_MatrixNumberOfColumnsxNumberOfRowsElementTypeSuffix object the values of a rotation matrix. This matrix represents a counter-clockwise rotation by angle degrees around the x-axis. This function is defined for \(4 \times 4\).

The rotation matrix is defined as \[ \begin{matrix} 1 & 0 & 0 & 0 \\ 0 & c & -s & 0 \\ 0 & s & c & 0 \\ 0 & 0 & 0 & 1 \end{matrix} \] where \(c=\cos(a)\) and \(s=\sin(a)\).

ElementTypeSuffix indicates the Arcadia type of the elements and parameters denoted by ElementType. The following table lists the ElementTypeSuffix and the corresponding ElementType.

ElementTypeSuffix	ElementType
`Real32Value`	`Arcadia_Real32Value`
`Real64Value`	`Arcadia_Real64Value`

Parameters

Arcadia_Thread* thread

A pointer to the Arcadia_Thread object.

Arcadia_Math_MatrixNumberOfColumnsxNumberOfRowsElementTypeSuffix* self

A pointer to this Arcadia_Math_MatrixNumberOfColumnsxNumberOfRowsElementTypeSuffix object.

ElementType angle

The angle of rotation, in degrees.

Arcadia_Math_MatrixNumberOfColumnsxNumberOfRowsElementTypeSuffix_setRotationY


  void

  Arcadia_Math_MatrixNumberOfColumnsxNumberOfRowsElementTypeSuffix_setRotationY

    (

      Arcadia_Thread* thread,

      Arcadia_Math_MatrixNumberOfColumnsxNumberOfRowsElementTypeSuffix* self,

      ElementType angle

    )

Assign the elements of this Arcadia_Math_MatrixNumberOfColumnsxNumberOfRowsElementTypeSuffix object the values of a rotation matrix. This matrix represents a counter-clockwise rotation by angle degrees around the y-axis. This function is defined for \(4 \times 4\).

The rotation matrix is defined as \[ \begin{matrix} c & 0 & s & 0 \\ 0 & 1 & 0 & 0 \\ -s & 0 & c & 0 \\ 0 & 0 & 0 & 1 \end{matrix} \] where \(c=\cos(a)\) and \(s=\sin(a)\).

ElementTypeSuffix indicates the Arcadia type of the elements and parameters denoted by ElementType. The following table lists the ElementTypeSuffix and the corresponding ElementType.

ElementTypeSuffix	ElementType
`Real32Value`	`Arcadia_Real32Value`
`Real64Value`	`Arcadia_Real64Value`

Parameters

Arcadia_Thread* thread

A pointer to the Arcadia_Thread object.

Arcadia_Math_MatrixNumberOfColumnsxNumberOfRowsElementTypeSuffix* self

A pointer to this Arcadia_Math_MatrixNumberOfColumnsxNumberOfRowsElementTypeSuffix object.

ElementType angle

The angle of rotation, in degrees.

Arcadia_Math_MatrixNumberOfColumnsxNumberOfRowsElementTypeSuffix_setRotationZ


  void

  Arcadia_Math_MatrixNumberOfColumnsxNumberOfRowsElementTypeSuffix_setRotationZ

    (

      Arcadia_Thread* thread,

      Arcadia_Math_MatrixNumberOfColumnsxNumberOfRowsElementTypeSuffix* self,

      ElementType angle

    )

Assign the elements of this Arcadia_Math_MatrixNumberOfColumnsxNumberOfRowsElementTypeSuffix object the values of a rotation matrix. This matrix represents a counter-clockwise rotation by angle degrees around the z-axis. This function is defined for \(4 \times 4\).

The rotation matrix is defined as \[ \begin{matrix} c & -s & 0 & 0 \\ s & c & 0 & 0 \\ 0 & 0 & 1 & 0 \\ 0 & 0 & 0 & 1 \end{matrix} \] where \(c=\cos(a)\) and \(s=\sin(a)\).

ElementTypeSuffix indicates the Arcadia type of the elements and parameters denoted by ElementType. The following table lists the ElementTypeSuffix and the corresponding ElementType.

ElementTypeSuffix	ElementType
`Real32Value`	`Arcadia_Real32Value`
`Real64Value`	`Arcadia_Real64Value`

Parameters

Arcadia_Thread* thread

A pointer to the Arcadia_Thread object.

Arcadia_Math_MatrixNumberOfColumnsxNumberOfRowsElementTypeSuffix* self

A pointer to this Arcadia_Math_MatrixNumberOfColumnsxNumberOfRowsElementTypeSuffix object.

ElementType angle

The angle of rotation, in degrees.

Arcadia_Math_MatrixNumberOfColumnsxNumberOfRowsElementTypeSuffix_setScaling


  void

  Arcadia_Math_MatrixNumberOfColumnsxNumberOfRowsElementTypeSuffix_setScaling

    (

      Arcadia_Thread* thread,

      Arcadia_Math_MatrixNumberOfColumnsxNumberOfRowsElementTypeSuffix* self,

      ElementType x,

      ElementType y,

      ElementType z

    )

Assign the elements of this Arcadia_Math_MatrixNumberOfColumnsxNumberOfRowsElementTypeSuffix object the values of a scaling matrix. This matrix represents a scalings along the x-, y-, and z-axis. This function is defined for \(4 \times 4\).

The rotation matrix is defined as \[ \begin{matrix} x & 0 & 0 & 0 \\ 0 & y & 0 & 0 \\ 0 & 0 & z & 0 \\ 0 & 0 & 0 & 1 \end{matrix} \]

ElementTypeSuffix indicates the Arcadia type of the elements and parameters denoted by ElementType. The following table lists the ElementTypeSuffix and the corresponding ElementType.

ElementTypeSuffix	ElementType
`Real32Value`	`Arcadia_Real32Value`
`Real64Value`	`Arcadia_Real64Value`

Parameters

Arcadia_Thread* thread

A pointer to the Arcadia_Thread object.

Arcadia_Math_MatrixNumberOfColumnsxNumberOfRowsElementTypeSuffix* self

A pointer to this Arcadia_Math_MatrixNumberOfColumnsxNumberOfRowsElementTypeSuffix object.

ElementType x

The scaling along the x-axis.

ElementType y

The scaling along the y-axis.

ElementType z

The scaling along the z-axis.

Arcadia_Math_MatrixNumberOfColumnsxNumberOfRowsElementTypeSuffix_setTranslation


  void

  Arcadia_Math_MatrixNumberOfColumnsxNumberOfRowsElementTypeSuffix_setTranslation

    (

      Arcadia_Thread* thread,

      Arcadia_Math_MatrixNumberOfColumnsxNumberOfRowsElementTypeSuffixValue* self,

      ElementType x,

      ElementType y,

      ElementType z

    )

Assign the elements of this Arcadia_Math_MatrixNumberOfColumnsxNumberOfRowsElementTypeSuffixValue object the values of a translation matrix. This function is defined for \(4 \times 4\). The translation matrix for \f(4 \times \) matrices is defined as

\[ \begin{matrix} 1 & 0 & 0 & x \\ 0 & 1 & 0 & y \\ 0 & 0 & 1 & z \\ 0 & 0 & 0 & 1 \end{matrix} \]

where \(x\), \(y\), and \(z\) is the translation along the x, y, and z axis, respectively.

ElementTypeSuffix indicates the Arcadia type of the elements and parameters denoted by ElementType. The following table lists the ElementTypeSuffix and the corresponding ElementType.

ElementTypeSuffix	ElementType
`Real32Value`	`Arcadia_Real32Value`
`Real64Value`	`Arcadia_Real64Value`

Parameters

Arcadia_Thread* thread

A pointer to the Arcadia_Thread object.

Arcadia_Math_MatrixNumberOfColumnsxNumberOfRowsElementTypeSuffix* self

A pointer to this Arcadia_Math_MatrixNumberOfColumnsxNumberOfRowsElementTypeSuffix object.

ElementType x

The translation along the x-axis.

ElementType y

The translation along the y-axis.

ElementType z

The translation along the z-axis.

Arcadia_Math_MatrixNumberOfColumnsxNumberOfRowsElementTypeSuffix_setZero


  void

  Arcadia_Math_MatrixNumberOfColumnsxNumberOfRowsElementTypeSuffix_setZero

    (

      Arcadia_Thread* thread,

      Arcadia_Math_MatrixNumberOfColumnsxNumberOfRowsElementTypeSuffix* self

    )

Assign the elements of this Arcadia_Math_MatrixNumberOfColumnsxNumberOfRowsElementTypeSuffix object the values of the zero matrix. The zero matrix is defined as \[ \forall i, j \in [1,n] c_{i,j} = 0 \]

Parameters

Arcadia_Thread* thread

A pointer to the Arcadia_Thread object.

Arcadia_Math_MatrixNumberOfColumnsxNumberOfRowsElementTypeSuffix* self

A pointer to this Arcadia_Math_MatrixNumberOfColumnsxNumberOfRowsElementTypeSuffix object.

Matrix Operations and Affine Transformations

Include Arcadia/Math/Include.h. All operations below are available for Real32 and Real64; substitute the corresponding suffix and scalar type in the signatures. Matrix elements are indexed as elements[row][column]. Transformations multiply column vectors: result = matrix * vector. Consequently, in A * B, transformation B acts first.

Transpose

void Arcadia_Math_Matrix4Real32_transpose
  (Arcadia_Thread* thread, Arcadia_Math_Matrix4Real32* self,
   Arcadia_Math_Matrix4Real32* other);

Assigns self[i][j] = other[j][i]. The destination and source may be the same object. With distinct objects, the source is unchanged. No managed objects are allocated.

Determinant

Arcadia_Real32Value Arcadia_Math_Matrix4Real32_getDeterminant
  (Arcadia_Thread* thread, Arcadia_Math_Matrix4Real32* self);

Returns the determinant of a 4 by 4 matrix by cofactor expansion. Does not modify the matrix or allocate managed objects. Singular matrices are valid inputs; no division or arbitrary singularity tolerance is used. Floating-point rounding applies, so a computed determinant is not a general-purpose numerical invertibility test.

Point Transformation

void Arcadia_Math_Matrix4x4Real32_transformPoint
  (Arcadia_Thread* thread, Arcadia_Math_Matrix4Real32* self,
   Arcadia_Math_Vector3Real32* point);

Transforms the point in place by the first three components of self * (point.x, point.y, point.z, 1). Translation participates. The matrix must describe an affine transformation. The function does not validate the last row and performs no perspective divide; it is not a projection operation.

Direction Transformation

void Arcadia_Math_Matrix4x4Real32_transformDirection
  (Arcadia_Thread* thread, Arcadia_Math_Matrix4Real32* self,
   Arcadia_Math_Vector3Real32* direction);

Transforms the direction in place by the upper-left 3 by 3 matrix, equivalent to the first three components of self * (direction.x, direction.y, direction.z, 0) for finite inputs. Translation is ignored. Scaling affects length; the result is not normalized. Normal vectors generally require an inverse-transpose transformation instead.

Both point and direction operations preserve the matrix, capture input components before assigning the result, and allocate no managed objects.

Look-at View Matrix

void Arcadia_Math_Matrix4x4Real32_setLookAt
  (Arcadia_Thread* thread, Arcadia_Math_Matrix4Real32* self,
   Arcadia_Math_Vector3Real32* source, Arcadia_Math_Vector3Real32* target,
   Arcadia_Math_Vector3Real32* up);

Constructs a right-handed world-to-view matrix looking along negative view-space Z. The source maps to the origin and the target lies on the negative Z axis. The supplied up vector need not be unit length or perpendicular to the viewing direction.

f = normalize(target - source)
r = normalize(cross(f, normalize(up)))
u = cross(r, f)

V = [ r.x   r.y   r.z  -dot(r, source) ]
    [ u.x   u.y   u.z  -dot(u, source) ]
    [-f.x  -f.y  -f.z   dot(f, source) ]
    [ 0     0     0     1              ]

Raises Arcadia_Status_ArgumentValueInvalid for a zero or non-finite viewing/up direction or a zero cross product (parallel directions). No angular tolerance is imposed. Computations whose direction lengths overflow also raise this status. Failure leaves the destination unchanged. Input vectors are never modified and no managed objects are allocated.