Skip to content
A library for 2D, 3D, and 4D vectors in CL.
Common Lisp
Branch: master
Clone or download
Latest commit eef737b Jan 7, 2020
Type Name Latest commit message Commit time
Failed to load latest commit information.
doc Fix doc refs Dec 16, 2018
.gitattributes Update license to zlib. Jun 22, 2019
.travis.yml Caching breaks things bad. May 22, 2018
3d-vectors-logo.png logo Sep 7, 2016
3d-vectors-test.asd Update license to zlib. Jun 22, 2019
3d-vectors.asd Update license to zlib. Jun 22, 2019
LICENSE Update license to zlib. Jun 22, 2019 Implement swizzle writers. Apr 5, 2018
documentation.lisp Add vec-from-vector Mar 18, 2019
ops.lisp Fix Lerp Jan 7, 2020
package.lisp Add vec-from-vector Mar 18, 2019
ssa.lisp Remove all SSA stuff for now since it's not really used anyway. Oct 10, 2016
staple.ext.lisp Improve docs by filtering out the swizzlers from the index. Dec 16, 2018
test.lisp Use test-toplevel. May 22, 2018
toolkit.lisp Fix print-case variance Dec 16, 2018

About 3d-vectors

This is a library for vector math in 3D space. It contains most of the vector operations one would usually expect out of such a library and offers them both in non-modifying and modifying versions where applicable. It also tries to be efficient where plausible. Each vector is made up of floats, which by default are single-floats, as they do not require value boxing on most modern systems and compilers. Despite the name of this library, 2D and 4D vectors are supported as well.

How To

Load it through ASDF or Quicklisp

(ql:quickload :3d-vectors)
(use-package :3d-vectors)

Create a vector:

(vec 0 0 0)

Vectors always use floats. Where sensible, operations should accept real numbers for convenience. All vector operations are prefixed with a v to allow importing the package without conflicts.

(v+ (vec 1 2 3) 4 5 6)

3d-vectors implements pretty much all vector operations you might need, including comparators, dot and cross product, and rotation. There's also modifying variants of all operators, which have the same name, except they are prefixed by an n.

(let ((v (vec 0 0 0)))
  (nv* (nv+ v (vec 1 2 3)) 3)

vecs are dumpable, meaning you can insert them as literals into your code and they will be properly saved to and restored from a FASL.

The type vec includes all three subtypes vec2, vec3, and vec4. Each of the three also has its own accessors that are suffixed with the dimension number. While the standard vx, vy, vz, and vw will result in the lower-level variants through an etypecase, it is usually a good idea to use vx2 etc if the type is already known to avoid unnecessary dispatch or branch elimination.

While most of the operations work on all three variants, you cannot intermix them. For example, (v+ (vec 1 2) (vec 1 2 3)) will signal an error. This is because it is often ambiguous and thus likely confusing as to what might happen in such a case. Should the result be upgraded to a vec3 or downgraded to a vec2? In order to avoid this ambiguity, it is simply left up to you to ensure proper types.

One convenient way to switch around between the types and generally flip around the vector fields is swizzling: similar to the single-field accessors, there's multi-field readers that construct a new vector from the specified fields of the necessary length.

(vxy (vec 1 2 3))    ; => (vec2 1 2)
(vxy_ (vec 1 2))     ; => (vec3 1 2 0)
(vwwx (vec 1 2 3 4)) ; => (vec3 4 4 1)

The _ can be used anywhere within swizzle operators in order to pad the vector with a zero. You can also use the swizzle operators as accessors to set multiple fields of a vector at once.

If you require higher precision than single-floats ensure, you can add :3d-vectors-double-floats to *features* and recompile the library (asdf:compile-system :3d-vectors :force T). Similarly, if you want to switch back to single-floats, you can remove the feature and recompile. Both at the same time is not supported as it would increase complexity in the library massively and make certain operations much slower.

Also See

  • 3d-matrices for Matrix operations in conjunction with this library.
You can’t perform that action at this time.