Next: , Previous: , Up: Math   [Contents][Index]


2.2.4 Matrices

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

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.4.1 3x3 Matrices

Procedure: make-matrix3 aa ab ac ba bb bc ca cb cc

Return a new 3x3 initialized with the given 9 values in column-major format.

Procedure: make-null-matrix3

Return a new 3x3 matrix with all values initialized to 0.

Procedure: make-identity-matrix3

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

(make-matrix3 1 0 0
              0 1 0
              0 0 1)
Procedure: matrix3? obj

Return #t if obj is a 3x3 matrix.

Procedure: matrix3* . matrices

Return a new 3x3 matrix containing the product of multiplying all of the given matrices.

Note: Remember that matrix multiplication is not commutative!

Procedure: matrix3-translate v

Return a new 3x3 matrix that represents a translation by v, a 2D vector.

Procedure: matrix3-scale s

Return a new 3x3 matrix that represents a scaling along the x and y axes by the scaling factor s, a number or 2D vector.

Procedure: matrix3-rotate angle

Return a new 3x3 matrix that represents a rotation by angle radians.

Procedure: matrix3-transform matrix v

Return a new 2D vector that is v as transformed by the 3x3 matrix matrix.

The following procedures perform in-place, destructive updates to 3x3 matrix objects:

Procedure: matrix3-identity! matrix

Modify matrix in-place to contain the identity matrix.

Procedure: matrix3-mult! dest a b

Multiply the 3x3 matrix a by the 3x3 matrix b and store the result in the 3x3 matrix dest.

Procedure: matrix3-translate! matrix v

Modify matrix in-place to contain a translation by v, a 2D vector.

Procedure: matrix3-scale! matrix s

Modify matrix in-place to contain a scaling along the x and y axes by the scaling factor s, a number or 2D vector.

Procedure: matrix3-rotate! matrix angle

Modify matrix in-place to contain a rotation by angle radians.

Procedure: matrix3-transform! matrix v

Modify the 2D vector v in-place to contain v as transformed by the 3x3 matrix matrix.

2.2.4.2 4x4 Matrices

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: matrix4-transform! matrix v

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


Next: , Previous: , Up: Math   [Contents][Index]