Getting Started

Requirements

• SBCL.
• cl-slug itself has no dependencies.
• cl-slug/clsl, the shaders, needs clsl, a shading language in Common Lisp, which needs no foreign library. Programs compile for Vulkan with clsl/vulkan.
• To draw, a GPU API. cl-slug fills textures; any API that takes a 16-bit float texture and a 16-bit unsigned integer texture works. The examples use cl-gfx on Vulkan.

Systems

System	What it holds	Depends on
cl-slug	The band builder: stores, shapes, the two textures' data.	Nothing
cl-slug/clsl	The Slug pixel shader as clsl shader functions.	cl-slug, clsl
cl-slug/test	The test suite.	cl-slug, cl-slug/clsl, clsl/vulkan, cl-threads, parachute

The packages are cl-slug and cl-slug/clsl. The examples use the local nickname slug for cl-slug:

(defpackage #:my-renderer
  (:use #:cl)
  (:local-nicknames (#:slug #:cl-slug)))

Installing with stift

cl-slug is not on Quicklisp. Require it in your project's stiftfile with stift:

stift get https://fakehacker.cc/dxtr/cl-slug.git

The shaders need clsl too, which is not on Quicklisp either, and clsl needs cl-threads. cl-slug's own stiftfile requires both, so they come along as indirect entries. Then stift exec your Lisp.

A different cl-slug is on Quicklisp. Quicklisp's dist has an unrelated library of the same name, from 2018, that makes URL slugs out of strings. stift never finds it: it finds systems only in the build list. A Lisp that loads Quicklisp, though, finds that one wherever this cl-slug is missing, and the first sign is a confusing error about a symbol missing from the package CL-SLUG. Without stift, clone this cl-slug where ASDF looks before Quicklisp, such as ~/common-lisp/.

Loading

(asdf:load-system :cl-slug)       ; the band builder
(asdf:load-system :cl-slug/clsl)  ; and the shaders, for clsl

A first shape

(defvar *store* (cl-slug:make-store))

;; A triangle in ems, y up: three curves of six numbers, X0 Y0 CX CY X1 Y1.
(defvar *triangle*
  (cl-slug:store-add *store* #(0.1 0.1  0.5 0.1  0.9 0.1
                               0.9 0.1  0.7 0.5  0.5 0.9
                               0.5 0.9  0.3 0.5  0.1 0.1)))

*triangle*
;; => #<CL-SLUG:SHAPE 3 curves, 1 by 1 band {...}>

From here:

• Concepts explains what a store, a shape and the two textures are.
• Shapes and Curves says how to give curves, and how to get them from a font.
• Drawing on the GPU draws a shape with cl-gfx, start to finish.

Running the tests

From cl-slug's directory:

stift test

The suite needs no GPU. It runs the pixel shader's algorithm on the CPU, reading the texture data as it would be uploaded, and compares its coverage with winding numbers computed from the curves. It also compiles slug-coverage with clsl, which needs nothing outside Lisp, and checks that it takes the pixel's size from derivatives, reads the textures unfiltered and loops over each band's curves. CI runs it on Debian forky with SBCL 2.6.9.