sb-cga

Most vector operations are done using special-purpose SSE2 primitives on SBCL/x86-64, and portable Common Lisp elsewhere.

Vector interface consists of two parts. The high-level interface always returns a freshly consed vector, whereas the low-level interface expects a new vector to store its results into.

Low level interface also implicitly trusts that argument counts and types are correct – bad things are liable to happen if those assumptions are violated, whereas the high-level operations should signal reasonable errors in such situations.

The system is fairly good about combining nested high-level operations into low-level ones with minimal consing, and given proper dynamic-extent declarations can also stack allocate results of vector operations on SBCL at least – including intermediate results.

User code should primarily use the high-level interface, and dip into the low level code only when absolutely necessary for performance.

2.1 Type and Constructors

— Type: vec

A 3d vector of single floats.

— Function: vec x y z

Allocate a 3d vector [x, y, z].

— Function: copy-vec vec

Allocate a fresh copy of vec.

— Function: alloc-vec

Allocate a zero-initialized vec.

2.2 Comparing Vectors

— Function: vec= a b

Return true if vec A and vec b are elementwise identical.

— Function: vec~ a b &optional epsilon

Return true if vec A and vec b are elementwise within epsilon of each other. epsilon defaults to +default-epsilon+.

2.3 Vector Algebra

— Function: vec+ a b

Add vec A and vec b, return result as a freshly allocated vec.

— Function: vec- a b

Substract vec b from vec A, return result as a freshly allocated vec.

— Function: vec* a f

Multiply vec A with single-float f, return result as a freshly allocated vec.

— Function: vec/ a f

Divide vec A by single-float f, return result as a freshly allocated vec.

— Function: vec-length a

Length of vec A.

— Function: normalize a

Normalize vec A, return result as a freshly allocated vec.

— Function: dot-product a b

Compute dot product vec A and vec b.

— Function: cross-product a b

Cross product of 3d vector A and 3d vector b, return result as a freshly allocated vec.

— Function: hadamard-product a b

Compute hadamard product (elementwise product) of vec A and vec b, return result as a freshly allocated vec.

— Function: vec-lerp a b f

Linear interpolate vec A and vec b using single-float f as the interpolation factor, return result as a freshly allocated vec.

— Function: vec-max vec &rest vecs

Elementwise maximum of vec and vecs, return result as a freshly allocated vec.

— Function: vec-min vec &rest vecs

Elementwise minimum of vec and vecs, return result as a freshly allocated vec.

— Function: adjust-vec point direction distance

Multiply vec direction by single-float distance adding the result to vec point. Return result as a freshly allocated vec.

2.4 Transformations

— Function: transform-bounds v1 v2 matrix

Transform the axis-aligned bounding box specified by its extreme corners v1 and v2 using matrix. Return new extreme corners (minimum and maximum coordinates) as freshly allocted VECs, as the primary and secondary value.

— Function: transform-direction vec matrix

Apply transformation matrix to vec ignoring the translation component, return result as a freshly allocated vec.

— Function: transform-point vec matrix

Apply transformation matrix to vec, return result as a freshly allocated vec.

2.5 Low-Level Interface

— Function: %copy-vec result vec

Copy contents of vec into result, return result. Unsafe.

— Function: %vec+ result a b

Add vec A and b, store result in vec result. Return result. Unsafe

— Function: %vec- result a b

Substract vec b from vec A, store result in vec result. Return result. Unsafe.

— Function: %vec* result a f

Multiply vec A with single-float f, store result in vec result. Return result. Unsafe.

— Function: %vec/ result a f

Divide vec A by single-float f, store result in vec result. Return result. Unsafe.

— Function: %normalize result a

Normalize vec A, store result into vec result. Return result. Unsafe.

— Function: %hadamard-product result a b

Compute hadamard product (elementwise product) of vec A and vec b, store result in vec result. Return result. Unsafe.

— Function: %vec-lerp result a b f

Linear interpolate vec A and vec b using single-float f as the interpolation factor, store result in vec result. Return result. Unsafe.

— Function: %vec-max result a b

Elementwise maximum of vec A and vec b, store result in vec result.

— Function: %vec-min result a b

Elementwise minimum of vec A and vec b, store result in vec result.

— Function: %adjust-vec result point direction distance

Multiply vec direction by single-float distance adding the result to vec point. Store result in result, and return it.

— Function: %transform-direction result vec matrix

Apply transformation matrix to vec, store result in result. Return result. Unsafe.

— Function: %transform-point result vec matrix

Apply transformation matrix to vec, store result in result. Return result. Unsafe.

3 Matrices

Transforming vectors using matrices as discussed above uses special purpose SSE2 primitives on SBCL/x86-64, and portable Common Lisp elsewhere.

Matrix algebra has otherwise not been specifically optimized, but should be reasoanably performant for the most part. If you find it substandard for your needs, let us know.

3.1 Type and Constructors

— Type: matrix

4x4 matrix of single floats, represented as a one-dimensional vector stored in column-major order.

— Function: matrix m11 m12 m13 m14 m21 m22 m23 m24 m31 m32 m33 m34 m41 m42 m43 m44

Construct matrix with the given elements (arguments are provided in row major order.)

— Function: identity-matrix

Construct an identity matrix.

— Function: zero-matrix

Construct a zero matrix.

— Function: reorient v1 v2

Construct a transformation matrix to reorient v1 with v2.

— Function: rotate-around v radians

Construct a rotation matrix that rotates by radians around vec v. 4th element of v is ignored.

— Function: rotate* x y z

Construct a rotation matrix from rotation factors x, y, z.

— Function: rotate vec

Construct a rotation matrix using first three elements of vec as the rotation factors.

— Function: scale* x y z

Construct a scaling matrix from scaling factors x, y, and z.

— Function: scale vec

Construct a scaling matrix using first threee elements of vec as the scaling factors.

— Function: translate* x y z

Construct a translation matrix from translation factors x, y and z.

— Function: translate vec

Construct a translation matrix using first three elements of vec as the translation factors.

— Constant: +identity-matrix+

Constant identity matrix.

3.2 Comparing and Accessing Matrices

— Function: matrix= m1 m2

Return true if matrix m1 is elementwise equal to matrix m1.

— Function: matrix~ m1 m2 &optional epsilon

Return true if matrix m1 and matrix m2 are elementwise within epsilon of each other. epsilon defaults to +default-epsilon+

— Function: matrixp object

Return true of object is a matrix.

— Function: mref matrix row column

Accessor for value in the specificed row and column in matrix.

3.3 Matrix Algebra

— Function: matrix* &rest matrices

Multiply matrices. The result might not be freshly allocated if all, or all but one multiplicant is an identity matrix.

— Function: inverse-matrix matrix

Inverse of matrix. Signals an error if there is no inverse.

— Function: matrix-determinant matrix

Determinant of matrix.

— Function: transpose-matrix matrix

Transpose of matrix.

4 Root Solvers

Interface described here is liable to be refactored. See new-roots.lisp in the sources for the possible shape of things to come.

— Function: cubic-roots-above limit a b c d

Real-valued roots greater than limit for Ax^3+Bx^2+Cx+D. Smallest positive root is returned as primary value, and others in increasing order. limit indicates lack of a real-valued root above limit.

— Function: cubic-roots a b c d

Real-valued roots for Ax^2+Bx+C. Smallest real root is returned as primary value, and the others as the successive values. NaN indicates lack of a real-valued root.

— Function: quadratic-roots-above limit a b c

Real-valued roots greater than limit for Ax^2+Bx+C. Smallest positive root is returned as primary value, and the other as secondary. limit indicates lack of a real-valued root above limit.

— Function: quadratic-roots a b c

Real-valued roots for Ax^2+Bx+C. Smallest real root is returned as primary value, and the other as the secondary. In case of a double root both the primary and secondary values are the same. NaN indicates lack of a real-valued root.

5 Miscellany

— Constant: +default-epsilon+

Used as a liminal value to work around floating point inaccuracy.

— Function: cbrt float

Cube root of float.