gl-math

A small math library aimed at gamedev that provides 4x4 float matrix, vector, and quaternion operations. Uses the hypermath library.

• matchable

Documentation

gl-math provides a number of functions for working with 4x4 matrices (plus a handful of others). The functionality is similar to what can be found in the glm egg, but with some notable differences:

• Matrix functions only operate on 4x4 matrices
• Matrix functions can accept either f32vectors or pointers
• No container is used to represent matrices

Additionally, gl-math is one fifth the compiled size of glm, has a more straight-forward code-base, and complete documentation.

gl-math expects matrices, vectors, and quaternions to be f32vectors or pointers. f32vectors must be 16 elements long, 3 elements long, or 4 elements long for matrices, vectors, or quaternions, respectively. The memory pointed to should likewise be an array of 16, 3, or 4 floats . If a function accepts more than one matrix, vector, or quaternion, all must be of the same type.

gl-math operates on matrices in a column-major fashion in correspondence with OpenGL (e.g. translation components are at indices 12, 13, and 14). Vectors are arranged as ((x y z)), and quaternions as ((x y z w)).

Matrix operations

print-mat4 MATRIXprocedure

Prints the given MATRIX to (current-output-port).

copy-mat4 MATRIX #!optional RESULTprocedure

Make a copy of MATRIX. If the matrix RESULT is given, it will be modified to contain the contents of MATRIX. If RESULT is #t, MATRIX must be an f32vector and the returned value will be an f32vector located in non-garbage-collected memory (the memory will still be freed when there are no more references to the matrix). If RESULT is not provided, MATRIX must be an f32vector and the returned value will be an f32vector located in normal garbage collected memory.

m* A B #!optional RESULTprocedure

Multiply matrix A by matrix B. If the matrix RESULT is given, it will be modified to contain the results of the multiplication. If RESULT is #t, A and B must be f32vectors and the returned value will be an f32vector located in non-garbage-collected memory (the memory will still be freed when there are no more references to the matrix). If RESULT is not provided, A and B must be f32vectors and the returned value will be an f32vector located in normal garbage collected memory.

m*s A S #!optional RESULTprocedure

Multiply matrix A by scalar S. If the matrix RESULT is given, it will be modified to contain the results of the multiplication. If RESULT is #t, A must be an f32vector and the returned value will be an f32vector located in non-garbage-collected memory (the memory will still be freed when there are no more references to the matrix). If RESULT is not provided, A must be an f32vector and the returned value will be an f32vector located in normal garbage collected memory.

m+ A B #!optional RESULTprocedure

Add matrix A with matrix B. If the matrix RESULT is given, it will be modified to contain the results of the multiplication. If RESULT is #t, A and B must be f32vectors and the returned value will be an f32vector located in non-garbage-collected memory (the memory will still be freed when there are no more references to the matrix). If RESULT is not provided, A and B must be f32vectors and the returned value will be an f32vector located in normal garbage collected memory.

m- A B #!optional RESULTprocedure

Subtract matrix B from matrix A. If the matrix RESULT is given, it will be modified to contain the results of the multiplication. If RESULT is #t, A and B must be f32vectors and the returned value will be an f32vector located in non-garbage-collected memory (the memory will still be freed when there are no more references to the matrix). If RESULT is not provided, A and B must be f32vectors and the returned value will be an f32vector located in normal garbage collected memory.

mat4-identity #!optional RESULTprocedure

Return an identity matrix. If RESULT is #t, the returned value will be an f32vector located in non-garbage-collected memory (the memory will still be freed when there are no more references to the matrix). If RESULT is not provided, the returned value will be an f32vector located in normal garbage collected memory.

translation VECTOR #!optional RESULTprocedure

Return the translation matrix given by VECTOR. If RESULT is #t, the returned value will be an f32vector located in non-garbage-collected memory (the memory will still be freed when there are no more references to the matrix). If RESULT is not provided, the returned value will be an f32vector located in normal garbage collected memory.

translate VECTOR MATRIXprocedure

Translate MATRIX by VECTOR.

x-rotation ANGLE #!optional RESULTprocedure

Return the rotation matrix given by a rotation of ANGLE radians around the x-axis. If RESULT is #t, the returned value will be an f32vector located in non-garbage-collected memory (the memory will still be freed when there are no more references to the matrix). If RESULT is not provided, the returned value will be an f32vector located in normal garbage collected memory.

rotate-x ANGLE MATRIXprocedure

Rotate MATRIX around the x-axis by ANGLE radians.

y-rotation ANGLE #!optional RESULTprocedure

Return the rotation matrix given by a rotation of ANGLE radians around the y-axis. If RESULT is #t, the returned value will be an f32vector located in non-garbage-collected memory (the memory will still be freed when there are no more references to the matrix). If RESULT is not provided, the returned value will be an f32vector located in normal garbage collected memory.

rotate-y ANGLE MATRIXprocedure

Rotate MATRIX around the y-axis by ANGLE radians.

z-rotation ANGLE #!optional RESULTprocedure

Return the rotation matrix given by a rotation of ANGLE radians around the z-axis. If RESULT is #t, the returned value will be an f32vector located in non-garbage-collected memory (the memory will still be freed when there are no more references to the matrix). If RESULT is not provided, the returned value will be an f32vector located in normal garbage collected memory.

rotate-z ANGLE MATRIXprocedure

Rotate MATRIX around the z-axis by ANGLE radians.

axis-angle-rotation AXIS ANGLE #!optional RESULTprocedure

Return the rotation matrix given by a rotation of ANGLE radians around the vector AXIS. If RESULT is #t, the returned value will be an f32vector located in non-garbage-collected memory (the memory will still be freed when there are no more references to the matrix). If RESULT is not provided, the returned value will be an f32vector located in normal garbage collected memory.

rotate-axis-angle AXIS ANGLE MATRIXprocedure

Rotate MATRIX around the vector AXIS by ANGLE radians.

quaternion-rotation Q #!optional RESULTprocedure

Return the rotation matrix given by the quaternion Q. If RESULT is #t, the returned value will be an f32vector located in non-garbage-collected memory (the memory will still be freed when there are no more references to the matrix). If RESULT is not provided, the returned value will be an f32vector located in normal garbage collected memory.

rotate-quaternion Q MATRIXprocedure

Rotate MATRIX by the quaternion Q.

ypr-rotation YAW PITCH ROLL #!optional RESULTprocedure

Return the rotation matrix given by rotating by ROLL radians around the z-axis followed by PITCH radians around the x-axis followed by YAW radians around the y-axis. If RESULT is #t, the returned value will be an f32vector located in non-garbage-collected memory (the memory will still be freed when there are no more references to the matrix). If RESULT is not provided, the returned value will be an f32vector located in normal garbage collected memory.

rotate-ypr YAW PITCH ROLL MATRIXprocedure

Rotate MATRIX by ROLL radians around the z-axis followed by PITCH radians around the x-axis followed by YAW radians around the y-axis.

2d-scaling SCALE-X SCALE-Y #!optional RESULTprocedure

Return the matrix created by scaling the x and y axes by SCALE-X and SCALE-Y. If RESULT is #t, the returned value will be an f32vector located in non-garbage-collected memory (the memory will still be freed when there are no more references to the matrix). If RESULT is not provided, the returned value will be an f32vector located in normal garbage collected memory.

scale-2d SCALE-X SCALE-Y MATRIXprocedure

Scale the x and y axis of MATRIX by SCALE-X and SCALE-Y.

3d-scaling SCALE-X SCALE-Y SCALE-Z #!optional RESULTprocedure

Return the matrix created by scaling the x, y and z axes by SCALE-X, SCALE-Y, and SCALE-Z. If RESULT is #t, the returned value will be an f32vector located in non-garbage-collected memory (the memory will still be freed when there are no more references to the matrix). If RESULT is not provided, the returned value will be an f32vector located in normal garbage collected memory.

scale-3d SCALE-X SCALE-Y SCALE-Z MATRIXprocedure

Scale the x, y, and z axis of MATRIX by SCALE-X, SCALE-Y, and SCALE-Z.

scaling SCALE #!optional RESULTprocedure

Return the matrix created by scaling the x, y and z axes by SCALE. If RESULT is #t, the returned value will be an f32vector located in non-garbage-collected memory (the memory will still be freed when there are no more references to the matrix). If RESULT is not provided, the returned value will be an f32vector located in normal garbage collected memory.

scale SCALE MATRIXprocedure

Scale the x, y, and z axis of MATRIX by SCALE.

flip-x MATRIXprocedure

Flip (mirror) MATRIX along the x-axis.

flip-y MATRIXprocedure

Flip (mirror) MATRIX along the y-axis.

flip-z MATRIXprocedure

Flip (mirror) MATRIX along the z-axis.

translate-rotate-scale-2d VECTOR ANGLE SCALE #!optional RESULTprocedure

Efficiently create a matrix translated by VECTOR, rotated around the z-axis by ANGLE radians, then scaled by SCALE. If the matrix RESULT is given, it will be modified to contain the result. If RESULT is #t, the returned value will be an f32vector located in non-garbage-collected memory (the memory will still be freed when there are no more references to the matrix). If RESULT is not provided, the returned value will be an f32vector located in normal garbage collected memory.

transpose MATRIX #!optional RESULTprocedure

Transpose MATRIX. If the matrix RESULT is given, it will be modified to contain the result. If RESULT is #t, MATRIX must be an f32vector and the returned value will be an f32vector located in non-garbage-collected memory (the memory will still be freed when there are no more references to the matrix). If RESULT is not provided, MATRIX must be an f32vector and the returned value will be an f32vector located in normal garbage collected memory.

inverse MATRIX #!optional RESULTprocedure

Invert MATRIX. If the matrix RESULT is given, it will be modified to contain the result. If RESULT is #t, MATRIX must be an f32vector and the returned value will be an f32vector located in non-garbage-collected memory (the memory will still be freed when there are no more references to the matrix). If RESULT is not provided, MATRIX must be an f32vector and the returned value will be an f32vector located in normal garbage collected memory.

fast-inverse-transpose MATRIX #!optional RESULTprocedure

Efficiently inverse the transpose the unscaled MATRIX. If MATRIX has been scaled, this will produce incorrect results: inverse then transpose should be used instead. If the matrix RESULT is given, it will be modified to contain the result. If RESULT is #t, MATRIX must be an f32vector and the returned value will be an f32vector located in non-garbage-collected memory (the memory will still be freed when there are no more references to the matrix). If RESULT is not provided, MATRIX must be an f32vector and the returned value will be an f32vector located in normal garbage collected memory.

Projection matrices

ortho WIDTH HEIGHT NEAR FAR #!optional RESULTprocedure

Create an orthographic projection matrix. If the matrix RESULT is given, it will be modified to contain the result. If RESULT is #t, the returned value will be an f32vector located in non-garbage-collected memory (the memory will still be freed when there are no more references to the matrix). If RESULT is not provided, the returned value will be an f32vector located in normal garbage collected memory.

ortho-viewport LEFT RIGHT NEAR FAR VIEWPORT-LEFT VIEWPORT-RIGHT VIEWPORT-BOTTOM VIEWPORT-TOP #!optional RESULTprocedure

Create an orthographic projection matrix mapping the LEFT, RIGHT, TOP, BOTTOM, NEAR, FAR cube to a viewport of VIEWPORT-LEFT, VIEWPORT-RIGHT, VIEWPORT-TOP, VIEWPORT-BOTTOM. If the matrix RESULT is given, it will be modified to contain the result. If RESULT is #t, the returned value will be an f32vector located in non-garbage-collected memory (the memory will still be freed when there are no more references to the matrix). If RESULT is not provided, the returned value will be an f32vector located in normal garbage collected memory.

perspective WIDTH HEIGHT NEAR FAR ANGLE #!optional RESULTprocedure

Create an perspective projection matrix with a field of view of ANGLE degrees. If the matrix RESULT is given, it will be modified to contain the result. If RESULT is #t, the returned value will be an f32vector located in non-garbage-collected memory (the memory will still be freed when there are no more references to the matrix). If RESULT is not provided, the returned value will be an f32vector located in normal garbage collected memory.

frustum LEFT RIGHT BOTTOM TOP NEAR FAR #!optional RESULTprocedure

Create a perspective projection matrix defined by a frustum with a near side of LEFT, RIGHT, TOP, BOTTOM, NEAR, and a far side at FAR. If the matrix RESULT is given, it will be modified to contain the result. If RESULT is #t, the returned value will be an f32vector located in non-garbage-collected memory (the memory will still be freed when there are no more references to the matrix). If RESULT is not provided, the returned value will be an f32vector located in normal garbage collected memory.

frustum-viewport LEFT RIGHT BOTTOM TOP NEAR FAR VIEWPORT-LEFT VIEWPORT-RIGHT VIEWPORT-BOTTOM VIEWPORT-TOP #!optional RESULTprocedure

Create a perspective projection matrix mapping the LEFT, RIGHT, TOP, BOTTOM, NEAR, FAR frustum to a viewport of VIEWPORT-LEFT, VIEWPORT-RIGHT, VIEWPORT-BOTTOM, VIEWPORT-TOP. If the matrix RESULT is given, it will be modified to contain the result. If RESULT is #t, the returned value will be an f32vector located in non-garbage-collected memory (the memory will still be freed when there are no more references to the matrix). If RESULT is not provided, the returned value will be an f32vector located in normal garbage collected memory.

Camera functions

look-at EYE OBJ UP #!optional RESULTprocedure

Create a “look-at” style camera matrix. The camera is positioned at point EYE, pointing towards the point OBJ. UP defines the camera’s up vector. If the matrix RESULT is given, it will be modified to contain the result. If RESULT is #t, the returned value will be an f32vector located in non-garbage-collected memory (the memory will still be freed when there are no more references to the matrix). If RESULT is not provided, the returned value will be an f32vector located in normal garbage collected memory.

camera-inverse CAMERA #!optional RESULTprocedure

Invert CAMERA in an efficient fashion. This allows the camera to be constructed in an intuitive fashion by translating and rotating before inverting in order to position the scene properly. This function is far faster than the general inverse function, but the matrix CAMERA must only be a matrix representing a translation and a rotation (no scaling). If the matrix RESULT is given, it will be modified to contain the result. If RESULT is #t, CAMERA must be an f32vector and the returned value will be an f32vector located in non-garbage-collected memory (the memory will still be freed when there are no more references to the matrix). If RESULT is not provided, CAMERA must be an f32vector and the returned value will be an f32vector located in normal garbage collected memory.

Vector operations

make-point X Y Z #!optional NON-GC?procedure
point-x POINTprocedure
point-y POINTprocedure
point-z POINTprocedure
point-x-set! POINTprocedure
point-y-set! POINTprocedure
point-z-set! POINTprocedure

Vector constructor, getters, and setters. If NON-GC? is #t, the point is created in a non-garbage-collected area (the memory will still be freed when there are no more references to the vector).

v+ A B #!optional RESULTprocedure

Return the result of the addition of vectors A and B. If the vector RESULT is given, it will be modified to contain the result. If RESULT is #t the returned value will be an f32vector located in non-garbage-collected memory (the memory will still be freed when there are no more references to the matrix). If RESULT is not provided, the returned value will be an f32vector located in normal garbage collected memory.

v- A B #!optional RESULTprocedure

Return the result of the subtraction of vector B from A. If the vector RESULT is given, it will be modified to contain the result. If RESULT is #t the returned value will be an f32vector located in non-garbage-collected memory (the memory will still be freed when there are no more references to the matrix). If RESULT is not provided, the returned value will be an f32vector located in normal garbage collected memory.

v* V S #!optional RESULTprocedure

Return the result of the multiplication of vector A with scalar S. If the vector RESULT is given, it will be modified to contain the result. If RESULT is #t the returned value will be an f32vector located in non-garbage-collected memory (the memory will still be freed when there are no more references to the matrix). If RESULT is not provided, the returned value will be an f32vector located in normal garbage collected memory.

cross-product A B #!optional RESULTprocedure

Return the result of the cross product between the vectors A and B. If the vector RESULT is given, it will be modified to contain the result. If RESULT is #t the returned value will be an f32vector located in non-garbage-collected memory (the memory will still be freed when there are no more references to the matrix). If RESULT is not provided, the returned value will be an f32vector located in normal garbage collected memory.

dot-product A Bprocedure

Return the result of the dot product between the vectors A and B.

vector-magnitude Vprocedure

Return the magnitude of vector V.

normalize! Vprocedure

Destructively normalize the vector V.

m*vector! MATRIX VECTORprocedure

Destructively multiply VECTOR by MATRIX.

(m*vector-array! MATRIX VECTORS stride: [STRIDE] length: [LENGTH])procedure

Destructively multiply the array of 3 element floats VECTORS by MATRIX. VECTORS may be given as an f32vector, a u8vector or a pointer. The keyword STRIDE specifies the number of elements between consecutive vectors, given in number of floats (which must be at least 3) when VECTORS is an f32vector and in bytes when VECTORS is a u8vector or a pointer. When VECTORS is given as a pointer, the keyword LENGTH must be provided, specifying the number of vectors in VECTORS.

lerp A B T #!optional RESULTprocedure

Linear interpolation between the points A and B with the interpolation parameter T which must be between 0 and 1. If the vector RESULT is given, it will be modified to contain the result. If RESULT is #t the returned value will be an f32vector located in non-garbage-collected memory (the memory will still be freed when there are no more references to the matrix). If RESULT is not provided, the returned value will be an f32vector located in normal garbage collected memory.

Quaternion operations

Quaternions are expected to be normalized before they are used in certain functions (quaternion-normalize! may be used to do so). All the provided functions that create quaternions, create unit quaternions.

The order of quaternion cross-multiplication is the inverse of the “standard” order, so a quaternion that has undergone a series or rotations will represent the same rotation as a marix that has gone through the same series, in the same order.

make-quaternion X Y Z W #!optional NON-GC?procedure
quaternion-x POINTprocedure
quaternion-y POINTprocedure
quaternion-z POINTprocedure
quaternion-w POINTprocedure
quaternion-x-set! POINTprocedure
quaternion-y-set! POINTprocedure
quaternion-z-set! POINTprocedure
quaternion-w-set! POINTprocedure

Quaternion constructor, getters, and setters. If NON-GC is #t, the quaternion is created in a non-garbage-collected area (the memory will still be freed when there are no more references to the quaternion).

quaternion-normalize! Qprocedure

Destructively normalize the quaternion Q.

quaternion-inverse Q #!optional RESULTprocedure

Return the inverse of the unit quaternion Q. If the quaternion RESULT is given, it will be modified to contain the result. If RESULT is #t the returned value will be an f32vector located in non-garbage-collected memory (the memory will still be freed when there are no more references to the matrix). If RESULT is not provided, the returned value will be an f32vector located in normal garbage collected memory.

quaternion-cross-product A B #!optional RESULTprocedure

Return the cross-product of the quaternions A and B. If the quaternion RESULT is given, it will be modified to contain the result. If RESULT is #t the returned value will be an f32vector located in non-garbage-collected memory (the memory will still be freed when there are no more references to the matrix). If RESULT is not provided, the returned value will be an f32vector located in normal garbage collected memory.

quaternion-axis-angle-rotation AXIS ANGLE #!optional RESULTprocedure

Return the quaternion corresponding to a rotation of ANGLE radians around the vector AXIS. If the quaternion RESULT is given, it will be modified to contain the result. If RESULT is #t the returned value will be an f32vector located in non-garbage-collected memory (the memory will still be freed when there are no more references to the matrix). If RESULT is not provided, the returned value will be an f32vector located in normal garbage collected memory.

quaternion-rotate-axis-angle AXIS ANGLE Qprocedure

Rotate the quaternion Q by a rotation of ANGLE radians around the vector AXIS.

quaternion-x-rotation ANGLE #!optional RESULTprocedure

Return the quaternion corresponding to a rotation of ANGLE radians around the x-axis. If the quaternion RESULT is given, it will be modified to contain the result. If RESULT is #t the returned value will be an f32vector located in non-garbage-collected memory (the memory will still be freed when there are no more references to the matrix). If RESULT is not provided, the returned value will be an f32vector located in normal garbage collected memory.

quaternion-rotate-x ANGLE Qprocedure

Rotate the quaternion Q by a rotation of ANGLE radians around the x-axis.

quaternion-y-rotation ANGLE #!optional RESULTprocedure

Return the quaternion corresponding to a rotation of ANGLE radians around the y-axis. If the quaternion RESULT is given, it will be modified to contain the result. If RESULT is #t the returned value will be an f32vector located in non-garbage-collected memory (the memory will still be freed when there are no more references to the matrix). If RESULT is not provided, the returned value will be an f32vector located in normal garbage collected memory.

quaternion-rotate-y ANGLE Qprocedure

Rotate the quaternion Q by a rotation of ANGLE radians around the y-axis.

quaternion-z-rotation ANGLE #!optional RESULTprocedure

Return the quaternion corresponding to a rotation of ANGLE radians around the z-axis. If the quaternion RESULT is given, it will be modified to contain the result. If RESULT is #t the returned value will be an f32vector located in non-garbage-collected memory (the memory will still be freed when there are no more references to the matrix). If RESULT is not provided, the returned value will be an f32vector located in normal garbage collected memory.

quaternion-rotate-z ANGLE Qprocedure

Rotate the quaternion Q by a rotation of ANGLE radians around the z-axis.

quaternion-ypr-rotation YAW PITCH ROLL #!optional RESULTprocedure

Return the quaternion corresponding to a rotation of ROLL radians around the z-axis followed by PITCH radians around the x-axis followed by YAW radians around the y-axis. If the quaternion RESULT is given, it will be modified to contain the result. If RESULT is #t the returned value will be an f32vector located in non-garbage-collected memory (the memory will still be freed when there are no more references to the matrix). If RESULT is not provided, the returned value will be an f32vector located in normal garbage collected memory.

quaternion-rotate-ypr YAW PITCH ROLL Qprocedure

Rotate the quaternion Q by ROLL radians around the z-axis followed by PITCH radians around the x-axis followed by YAW radians around the y-axis.

quaternion-rotate-point! Q Pprocedure

Destructively rotate the point P by the unit quaternion Q.

slerp A B T #!optional RESULTprocedure

Spherical linear interpolation between the quaternions A and B with the interpolation parameter T which must be between 0 and 1. If the quaternion RESULT is given, it will be modified to contain the result. If RESULT is #t the returned value will be an f32vector located in non-garbage-collected memory (the memory will still be freed when there are no more references to the matrix). If RESULT is not provided, the returned value will be an f32vector located in normal garbage collected memory.

Angle operations

Converts ANGLE from degrees to radians.

Converts ANGLE from radians to degrees.

piconstant
pi/2constant

Example

```
(import chicken scheme)
(use gl-math)

(define projection-matrix
(perspective 640 480 0.1 100 70))

(define view-matrix
(look-at (make-point 1 0 3)
(make-point 0 0 0)
(make-point 0 1 0)))

(define model-matrix (mat4-identity))

(print-mat4 (m* projection-matrix
(m* view-matrix model-matrix)))```

Version history

7 August 2014

8 October 2014

Version 0.5.2

10 September 2014

Version 0.5.0

2 September 2014

• Many new vector and quaternion functions
• Functions that previously accepted vectors as individual floats, now accept them as f32vectors

30 August 2014

Version 0.4.0

27 July 2014

Version 0.3.2

21 July 2014

• Allow pointer to array of vectors to be passed to m*vector-array!
• Fix error forms

Version 0.3.1

23 June 2014

• Matrix vector multiplication

Version 0.2.0

21 June 2014

• Each transformation function now has two variants: one that initializes a matrix, and one that operates on a matrix
• Provide pi/2
• Provide quaternion and YPR rotation
• Fix optional arguments for matrix operations
• Fix a bug in look-at

Version 0.1.0

17 June 2014

• Initial release

Source repository

Source available on GitHub.

Bug reports and patches welcome! Bugs can be reported via GitHub or to alex.n.charlton at gmail.

Alex Charlton

BSD