2.2.5 Matrices

The (chickadee math matrix) module provides an interface for working with the most common type of matrices in game development: 4x4 transformation matrices.

2.2.5.1 Another Note About Performance

Much like the vector API, the matrix API is commonly used in performance critical code paths. In order to reduce the amount of garbage generated and improve matrix multiplication performance, there are many procedures that perform in-place modifications of matrix objects.

2.2.5.2 Matrix Operations

Procedure: make-matrix4 aa ab ac ad ba bb bc bd ca cb cc cd da db dc dd

Return a new 4x4 matrix initialized with the given 16 values in column-major format.

Procedure: make-null-matrix4

Return a new 4x4 matrix with all values initialized to 0.

Procedure: make-identity-matrix4

Return a new 4x4 identity matrix. Any matrix multiplied by the identity matrix yields the original matrix. This procedure is equivalent to the following code:

(make-matrix4 1 0 0 0
              0 1 0 0
              0 0 1 0
              0 0 0 1)

Procedure: matrix4? obj

Return #t if obj is a 4x4 matrix.

Procedure: matrix4* . matrices

Return a new 4x4 matrix containing the product of multiplying all of the given matrices.

Note: Remember that matrix multiplication is not commutative!

Procedure: orthographic-projection left right top bottom near far

Return a new 4x4 matrix that represents an orthographic (2D) projection for the horizontal clipping plane top and bottom, the vertical clipping plane top and bottom, and the depth clipping plane near and far.

Procedure: perspective-projection fov aspect-ratio near far

Return a new 4x4 matrix that represents a perspective (3D) projection with a field of vision of fov radians, an aspect ratio of aspect-ratio, and a depth clipping plane defined by near and far.

Procedure: matrix4-translate x

Return a new 4x4 matrix that represents a translation by x, a 2D vector, a 3D vector, or a rectangle (in which case the bottom-left corner of the rectangle is used).

Procedure: matrix4-scale s

Return a new 4x4 matrix that represents a scaling along the X, Y, and Z axes by the scaling factor s, a real number.

Procedure: matrix4-rotate q

Return a new 4x4 matrix that represents a rotation about an arbitrary axis defined by the quaternion q.

Procedure: matrix4-rotate-z theta

Return a new 4x4 matrix that represents a rotation about the Z axis by theta radians.

Procedure: matrix4-identity! matrix

Modify matrix in-place to contain the identity matrix.

Procedure: matrix4-mult! dest a b

Multiply the 4x4 matrix a by the 4x4 matrix b and store the result in the 4x4 matrix dest.

Procedure: matrix4-translate! matrix x

Modify matrix in-place to contain a translation by x, a 2D vector, a 3D vector, or a rectangle (in which case the bottom-left corner of the rectangle is used).

Procedure: matrix4-scale! matrix s

Modify matrix in-place to contain a scaling along the X, Y, and Z axes by the scaling factor s, a real number.

Procedure: matrix4-rotate! matrix q

Modify matrix in-place to contain a rotation about an arbitrary axis defined by the quaternion q.

Procedure: matrix4-rotate-z! matrix theta

Modify matrix in-place to contain a rotation about the Z axis by theta radians.

Procedure: matrix4-2d-transform! matrix [#:origin] [#:position] [#:rotation] [#:scale] [#:skew]

Modify matrix in-place to contain the transformation described by position, a 2D vector or rectangle, rotation, a scalar representing a rotation about the Z axis, scale, a 2D vector, and skew, a 2D vector. The transformation happens with respect to origin, a 2D vector. If an argument is not provided, that particular transformation will not be included in the result.

Procedure: transform! matrix v

Modify the 2D vector v in-place by multiplying it by the 4x4 matrix matrix.