SB-CGA is maintained in Git:

git clone git://github.com/nikodemus/sb-cga.git

will get you a local copy.

http://github.com/nikodemus/sb-cga

is the GitHub project page.

This documentation – and SB-CGA itself – is still a work in progress.

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.

— 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+`

.

— 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`

.

— 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`

.

— 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: **%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.

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.

— 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: **rotate-around**` v radians`

Construct a rotation matrix that rotates by

`radians`

around`vec`

`v`

. 4th element of`v`

is ignored.

— Function: **rotate**` vec`

Construct a rotation matrix using first three elements of

`vec`

as the rotation factors.

— Function: **scale**` vec`

Construct a scaling matrix using first threee elements of

`vec`

as the scaling factors.

— Function: **translate**` vec`

Construct a translation matrix using first three elements of

`vec`

as the translation factors.

— 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: **matrix***` &rest matrices`

Multiply

`matrices`

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

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.