This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

API Reference

Everything cl-gmath exports. Every function's docstring says the same: (describe 'cl-gmath:mat4-look-at).

In the signatures, &optional result stands for the optional last argument every function that returns a vector, matrix or quaternion takes: the value is written into result, which may be one of the arguments of its type, and returned, and nothing is allocated. See Results and Allocation. Scalars may be any real.

Every type has a counterpart of doubles, and every function one for them, named with each type's d, such as dvec3+ and dmat4*dvec4; see Doubles below.

Thread rules for all of it: functions keep no state; a value may be read from several threads at once, and a value being written belongs to one thread.

Types

Type	Is
vec2, vec3, vec4	(simple-array single-float (2)), (3) and (4): X, Y, Z and W. Also a typed structure over that array, whose accessors read the components.
quat	(simple-array single-float (4)): X, Y and Z, the vector part, then W, the real part. The same type as vec4.
mat3, mat4	(simple-array single-float (9)) and (16): elements column by column.
mat3x2	(simple-array single-float (6)): a 2D affine transform's elements column by column, the X axis, the Y axis and the origin.
float-array	A specialised array of single floats of any length, as batch routines take.

Making values

Function	Returns
(make-vec2 &key x y), (make-vec3 &key x y z), (make-vec4 &key x y z w)	A new vector of the components given by keyword, any reals; those not given are 0.
(make-quat &key x y z w)	A new quaternion of the components given by keyword; X, Y and Z are 0 if not given, and W 1, so by default the identity.
(make-mat3 &rest elements), (make-mat3x2 &rest elements), (make-mat4 &rest elements)	A new matrix of 9, 6 or 16 elements, any reals, column by column. Signals gmath-error for another count.
(mat3-identity &optional result), (mat3x2-identity &optional result), (mat4-identity &optional result), (quat-identity &optional result)	The identity.
(vec3-copy vector &optional result), and vec2-, vec4-, mat3-, mat3x2-, mat4-, quat-copy	A copy.
(vec3-set vector x y z), and vec2-set, vec4-set	The vector, its components set to the reals.

Components and elements

Accessor	Reads
(vec2-x vector), (vec2-y vector)	X or Y of a vec2.
(vec3-x vector), (vec3-y vector), (vec3-z vector)	X, Y or Z of a vec3.
(vec4-x vector), (vec4-y vector), (vec4-z vector), (vec4-w vector)	X, Y, Z or W of a vec4.
(quat-x quaternion), (quat-y quaternion), (quat-z quaternion), (quat-w quaternion)	X, Y, Z or W, the real part, of a quat.
(mref matrix row column)	The element of a mat3, mat3x2 or mat4 of either precision at row and column, from 0. Signals gmath-error outside the matrix.

setf writes each: a component with a single float, as its array holds, and an element with any real. Each accessor checks for its own type.

Vectors

Each exists as vec2-, vec3- and vec4-; shown for vec3.

Function	Returns
(vec3+ a b &optional result), (vec3- a b &optional result)	The sum; a minus b.
(vec3* a b &optional result), (vec3/ a b &optional result)	The product and the quotient, per component.
(vec3-scale vector scale &optional result)	The vector times a real.
(vec3-negate vector &optional result)	The vector negated.
(vec3-min a b &optional result), (vec3-max a b &optional result)	The lesser and the greater per component.
(vec3-lerp a b s &optional result)	The fraction s of the way from a to b.
(vec3-normalize vector &optional result)	The vector scaled to length 1; a zero vector stays zero.
(vec3-dot a b)	The dot product.
(vec3-length vector), (vec3-length-squared vector)	The length, and its square.
(vec3-distance a b), (vec3-distance-squared a b)	The distance between two points, and its square.
(vec3-angle a b)	The angle between two vectors, in radians, from 0 to π; 0 if either is zero.
(vec3-reflect incident normal &optional result)	incident reflected off a surface whose unit normal is normal.
(vec3-project vector onto &optional result)	The part of vector along onto, which need not be unit; zero onto a zero vector.
(vec3-project-on-plane vector normal &optional result)	vector less its part along normal, which need not be unit; vector itself for a zero normal.
(vec3-clamp-length vector max-length &optional result)	vector shortened to max-length, a real of 0 or more, if it is longer.
(vec3-move-toward from to delta &optional result)	The point delta further from from toward to, but no further than to.
(vec3-approx= a b &optional (epsilon 1e-5))	True if no component differs by more than epsilon.
(vec3-cross a b &optional result)	The cross product. vec3 only.

The same for the other sizes: vec2+, vec2-, vec2*, vec2/, vec2-scale, vec2-negate, vec2-min, vec2-max, vec2-lerp, vec2-normalize, vec2-dot, vec2-length, vec2-length-squared, vec2-distance, vec2-distance-squared, vec2-angle, vec2-reflect, vec2-project, vec2-project-on-plane, vec2-clamp-length, vec2-move-toward, vec2-approx=, vec2-copy, vec2-set; and vec4+, vec4-, vec4*, vec4/, vec4-scale, vec4-negate, vec4-min, vec4-max, vec4-lerp, vec4-normalize, vec4-dot, vec4-length, vec4-length-squared, vec4-distance, vec4-distance-squared, vec4-angle, vec4-reflect, vec4-project, vec4-project-on-plane, vec4-clamp-length, vec4-move-toward, vec4-approx=, vec4-copy, vec4-set.

Matrices

Each exists as mat3- and mat4-; shown for mat4.

Function	Returns
(mat4* a b &optional result)	The product A B: applies b, then a.
(mat4*vec4 matrix vector &optional result), (mat3*vec3 matrix vector &optional result)	The matrix times a column vector.
(mat4-transpose matrix &optional result)	The transpose.
(mat4-determinant matrix)	The determinant.
(mat4-inverse matrix &optional result)	The inverse. Signals gmath-error for a singular matrix.
(mat4-approx= a b &optional (epsilon 1e-5))	True if no element differs by more than epsilon.
(mat3-from-mat4 matrix &optional result)	The upper left 3x3: rotation and scale, without translation.
(mat3-normal-matrix matrix &optional result)	The matrix that transforms normals for a model mat4: the inverse transpose of its upper left 3x3. Signals gmath-error if that is singular.

The same for mat3: mat3*, mat3*vec3, mat3-transpose, mat3-determinant, mat3-inverse, mat3-approx= and mat3-copy.

2D affine transforms

See 2D Transforms.

Function	Returns
(mat3x2* a b &optional result)	The product A B: applies b, then a.
(mat3x2-translation offset &optional result)	The mat3x2 that moves by the vec2 offset.
(mat3x2-rotation angle &optional result)	The mat3x2 that turns by angle, in radians, from +X toward +Y.
(mat3x2-scaling scale &optional result)	The mat3x2 that scales by the vec2 scale.
(mat3x2-compose translation angle scale &optional result)	The mat3x2 that scales, then turns, then moves: a 2D node's transform.
(mat3x2-transform-point matrix point &optional result)	The vec2 point transformed.
(mat3x2-transform-direction matrix direction &optional result)	The vec2 direction transformed without the translation.
(mat3x2-inverse matrix &optional result)	The inverse. Signals gmath-error for a singular matrix.
(mat3x2-determinant matrix)	The factor by which it scales areas, negative if it mirrors them.
(mat3x2-approx= a b &optional (epsilon 1e-5))	True if no element differs by more than epsilon.
(mat3-from-mat3x2 matrix &optional result)	The mat3 of homogeneous 2D points that transforms as it does: it with the bottom row 0 0 1.
(mat3x2-from-mat3 matrix &optional result)	The mat3x2 of a mat3's top two rows.

Quaternions

Function	Returns
(quat-from-axis-angle axis angle &optional result)	The rotation by angle, in radians, about the vec3 axis, which need not be normalised. Signals gmath-error for a zero axis.
(quat* a b &optional result)	The Hamilton product: rotates by b, then a.
(quat-rotate quaternion vector &optional result)	The vec3 rotated by a unit quaternion.
(quat-slerp a b s &optional result)	The rotation the fraction s of the way from a to b, along the shorter arc.
(quat-conjugate quaternion &optional result)	The vector part negated: for a rotation, the opposite rotation.
(quat-inverse quaternion &optional result)	The inverse. Signals gmath-error for the zero quaternion.
(quat-normalize quaternion &optional result)	Scaled to length 1. Signals gmath-error for the zero quaternion.
(quat-length quaternion), (quat-dot a b)	The length and the dot product, as 4-vectors.
(quat-approx= a b &optional (epsilon 1e-5))	True if no component differs by more than epsilon; a quaternion and its negation differ here.

Transforms

Function	Returns the mat4 that
(mat4-translation offset &optional result)	translates by the vec3 offset.
(mat4-scaling scale &optional result)	scales by the vec3 scale.
(mat4-rotation axis angle &optional result)	rotates by angle about axis. Signals gmath-error for a zero axis.
(mat4-rotation-x angle &optional result), -y, -z	rotates about an axis.
(mat4-from-quat quaternion &optional result)	rotates as a unit quaternion does.
(mat4-compose translation rotation scale &optional result)	scales by a vec3, rotates by a unit quat, then translates by a vec3.

Function	Returns
(mat4-transform-point matrix point &optional result)	The vec3 point transformed by an affine matrix; its bottom row is ignored.
(mat4-transform-direction matrix direction &optional result)	The vec3 direction transformed without the translation.
(mat4-project-point matrix point &optional result)	The point transformed and divided by W. Signals gmath-error if W is 0.

Cameras and projections

The projections map into Vulkan's clip space, where Y points down, so the top of the view is at clip Y −1.

Function	Returns
(mat4-look-at eye target up &optional result)	The view matrix of a camera at eye looking at target, up pointing up on the screen. Signals gmath-error if eye is target or up is parallel to the line between them.
(mat4-perspective fov-y aspect near far &optional result)	The perspective projection, depth reversed: near at 1, far at 0. near and far are positive; signals gmath-error unless near < far.
(mat4-perspective-infinite fov-y aspect near &optional result)	The same with the far plane at infinity; near is positive.
(mat4-orthographic left right bottom top near far &optional result)	The orthographic projection of a box, depth reversed, top at clip Y −1. Signals gmath-error for a box without a size.

2D, as mat3s of homogeneous points

Function	Returns
(mat3-translation-2d offset &optional result)	The mat3 that translates 2D points by the vec2 offset.
(mat3-rotation-2d angle &optional result)	The mat3 that rotates 2D points by angle, from +X toward +Y.
(mat3-scaling-2d scale &optional result)	The mat3 that scales 2D points by the vec2 scale.
(mat3-transform-point-2d matrix point &optional result)	The vec2 point transformed by a 2D affine mat3.
(mat3-transform-direction-2d matrix direction &optional result)	The vec2 direction transformed without the translation.

Single numbers

Of any reals; see Single Numbers.

Function	Returns
(clamp value low high)	value kept from low to high. Signals gmath-error if low is more than high.
(lerp a b s)	The fraction s of the way from a to b.
(inverse-lerp a b value)	The fraction of the way from a to b that value is. Signals gmath-error if a and b are equal.
(remap value from-low from-high to-low to-high)	value carried from one range to another. Signals gmath-error if from-low and from-high are equal.
(smoothstep edge0 edge1 x)	0 to 1 along 3t² − 2t³ between the edges. Signals gmath-error if they are equal.
(move-toward from to delta)	from moved delta toward to, but no further than to.

Batches

Each works on the items from start below end, by default all, stores them at the same places in destination, which may be the source, returns destination, and allocates nothing. See Batches and SIMD.

Function	Does
(mat4-transform-points matrix source destination &key start end)	Transforms the points, x, y and z each, of a float-array.
(mat4-transform-directions matrix source destination &key start end)	The same for directions, without the translation.
(mat4*-batch matrix matrices destination &key start end)	Multiplies matrix by each matrix, 16 floats each, of a float-array.

Doubles

See Doubles.

Name	Is
dvec2, dvec3, dvec4, dquat, dmat3, dmat3x2, dmat4	The types of doubles: (simple-array double-float (n)), laid out as their counterparts of single floats.
double-array	A specialised array of doubles of any length, as the batches of doubles take.
dvec3+, dmat4*, dquat-slerp, dmat4-transform-points and so on	Every function above for doubles, named with each type's d.
dvec2-x to dvec4-w, dquat-x to dquat-w	The components of doubles, which setf writes with doubles.
(dvec3-from-vec3 value &optional result), and the same for vec2, vec4, mat3, mat3x2, mat4 and quat	The value in doubles, exactly.
(vec3-from-dvec3 value &optional result), and the same for the others	The value in single floats, each component rounded to the nearest.

Angles

Function	Returns
(radians degrees)	An angle in degrees, in radians: a double for a double, otherwise a single float.
(degrees radians)	An angle in radians, in degrees: a double for a double, otherwise a single float.

Conditions

gmath-error

Signalled when an operation has no answer for its arguments. (gmath-error-message condition) returns what to change. See Errors.

Features

Feature	Means
:cl-gmath-simd	Set when cl-gmath is compiled with its SIMD kernels: on SBCL on x86-64, and on ARM64 from SBCL 2.6.7. Which kernels run is chosen when an image starts.
:cl-gmath-scalar	Push it before cl-gmath is compiled to build without SIMD.