# sb-cga

SB-CGA is courtesy of Steel Bank Studio Ltd and written by Nikodemus Siivola.

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.

## 1 Overview

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

## 2 Vectors

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