Errors

cl-gmath signals gmath-error when an operation has no answer for its arguments, with a message that says what to change. gmath-error-message returns the message. The messages of doubles name their types, such as DMAT4.

Arguments of the wrong type signal type-error instead, such as a vec4 given to vec3+. So does an argument outside the range its function declares: a negative max-length for vec3-clamp-length and its kin, a near that is not positive for mat4-perspective and mat4-perspective-infinite, or a negative :start or :end for a batch. So does a component written with anything but a float of its vector's precision, such as (setf (gm:vec3-x v) 1); see Vectors. SBCL usually reports these when the call is compiled, and otherwise when it runs, before the function does anything.

Messages

Inverting a singular matrix, with mat4-inverse, mat3-inverse or mat3x2-inverse, or mat3-normal-matrix of a model matrix that scales an axis to nothing:

This MAT4 is singular, with a determinant of 0, so it has no inverse: #(0.0 0.0 0.0 0.0 0.0 1.0 0.0 0.0 0.0 0.0 1.0 0.0 0.0 0.0 0.0 1.0)

A rotation about no axis, with quat-from-axis-angle or mat4-rotation:

A rotation needs an axis, and #(0.0 0.0 0.0) is the zero vector.

A camera that looks nowhere, with mat4-look-at:

The camera's EYE and TARGET are the same point, #(1.0 1.0 1.0), so it looks nowhere.

The camera's UP, #(0.0 1.0 0.0), is parallel to the direction it looks in, so it gives no up on the screen.  Choose another UP.

A projection without depth, with mat4-perspective or mat4-orthographic:

A projection needs NEAR < FAR, not NEAR 10 and FAR 1.

An orthographic projection needs a box with a size: LEFT 0 and RIGHT 0, BOTTOM 0 and TOP 1, NEAR 0 and FAR 1 must differ.

A point in the camera's plane, with mat4-project-point:

The point #(0.0 0.0 0.0) projects to W = 0, which has no place in normalised device coordinates.

The zero quaternion, with quat-normalize or quat-inverse:

The zero quaternion stands for no rotation and cannot be normalised.

The zero quaternion has no inverse.

An element outside a matrix, with mref:

Row 3 and column 0 are not both within this matrix, whose rows run from 0 to 2 and columns from 0 to 2.

A matrix of the wrong number of elements, with gm:make-mat3, gm:make-mat3x2 or gm:make-mat4:

MAKE-MAT4 takes 16 elements, column by column, not 3.

A range the wrong way round or without a size, with clamp, inverse-lerp, remap or smoothstep:

CLAMP's LOW, 10, is more than its HIGH, 0: give them the other way round.

INVERSE-LERP needs two different ends, not 1 twice.

REMAP needs a range to map from whose ends differ, not FROM-LOW and FROM-HIGH both 2.

SMOOTHSTEP needs two different edges, not 1 twice.

A batch that does not fit its array:

GM:MAT4-TRANSFORM-POINTS takes 3 floats per item, but an array of 4 holds no whole number of them.

GM:MAT4-TRANSFORM-POINTS was given the range 1 to 3 of an array of 2 items.

What is not an error

• Normalising a zero vector returns the zero vector, as in Godot.
• Projecting onto a zero vector gives the zero vector, and projecting onto a plane whose normal is zero leaves the vector as it is.
• The angle with a zero vector is 0.
• Floating-point traps stay as the Lisp sets them: dividing by a zero component with vec3/ signals division-by-zero, a Lisp arithmetic error, not a gmath-error.