Getting Started

Requirements

• SBCL. On x86-64, and on ARM64 from SBCL 2.6.7, cl-gmath loads the sb-simd contrib, which comes with SBCL; elsewhere it needs nothing. It uses no foreign library.
• For the tests: stift, which fetches Parachute, pinned by commit in the stiftfile.

Loading

(asdf:load-system :cl-gmath)

(defpackage #:example
  (:use #:cl)
  (:local-nicknames (#:gm #:cl-gmath)))
(in-package #:example)

The examples in this wiki use the nickname gm for cl-gmath.

First steps

Values are made by make- functions named for their type, a vector from its components given by keyword, and print as the arrays they are:

(gm:make-vec3 :x 1 :y 2 :z 3)                                            ; => #(1.0 2.0 3.0)
(gm:vec3+ (gm:make-vec3 :x 1 :y 2 :z 3) (gm:make-vec3 :x 4 :y 5 :z 6))   ; => #(5.0 7.0 9.0)
(gm:vec3-length (gm:make-vec3 :x 3 :y 4))                                ; => 5.0
(gm:vec3-cross (gm:make-vec3 :x 1) (gm:make-vec3 :y 1))                  ; => #(0.0 0.0 1.0)
(gm:vec3-y (gm:make-vec3 :x 1 :y 2 :z 3))                                ; => 2.0
(typep (gm:make-vec3) '(simple-array single-float (3)))                  ; => T

Arguments that are scalars may be any real, and components not given are 0. Components are stored as single floats, and setf of an accessor such as vec3-y writes one with a single float. A matrix moves points:

(gm:mat4-transform-point (gm:mat4-translation (gm:make-vec3 :x 1 :y 2 :z 3)) (gm:make-vec3))
;; => #(1.0 2.0 3.0)

Next, read Conventions: which way the axes point, and in which order matrices apply.

Running the tests

stift test

The tests check every operation, that every call given a result allocates nothing, and that every SIMD kernel the processor has computes exactly what the scalar code computes. Where there is no SIMD path, as in a scalar build, there are no kernels to compare, and those checks are left out. CI runs the suite on SBCL on x86-64 Linux, and on ARM64, for the NEON kernels, under QEMU's user-mode emulation.

Without an ARM64 machine, QEMU runs the suite the same way, with an ARM64 SBCL of 2.6.7 or later, such as Alpine's, unpacked with Alpine's minimal root file system into a directory, here sysroot. stift's setup file, which stift setup writes and names, sets the build list up in that SBCL too:

qemu-aarch64 -L sysroot sysroot/usr/bin/sbcl --non-interactive \
  --eval "(load \"$(stift setup)\")" --eval '(asdf:test-system :cl-gmath)'