Getting Started

Requirements

• SBCL.
• No foreign libraries and no Lisp dependencies. The test suite uses parachute.
• To get outlines from fonts, something that produces them. cl-textrender's glyph-outline produces exactly the form cl-sdf takes; see Contours and Fill Rules.

Systems

System	What it holds	Depends on
cl-sdf	Everything: geometry, edge coloring, field generation, point queries.	Nothing
cl-sdf/test	The test suite and the msdfgen reference fixtures.	cl-sdf, parachute

The package is cl-sdf. It has no global nickname, which would take a name from every package in the image: give it a local nickname in your own package. The examples in this wiki write sdf:, and run in a package like this one:

(defpackage #:my-renderer
  (:use #:cl)
  (:local-nicknames (#:sdf #:cl-sdf)))
(in-package #:my-renderer)

Installing with stift

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

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

Then stift exec your Lisp. The stiftfile pins the commit; stift update https://fakehacker.cc/dxtr/cl-sdf.git moves the pin to the newest commit of its branch.

Without stift, clone the repository somewhere ASDF looks, such as ~/common-lisp/.

Loading

(asdf:load-system :cl-sdf)

A first field

;; A triangle, counterclockwise: a list of contours, each a list of segments.
(let* ((triangle '(((:line 0 0 1 0) (:line 1 0 0.5 1) (:line 0.5 1 0 0))))
       (field (sdf:generate-msdf triangle 32 32 :padding 0.25)))
  (list (sdf:field-width field) (sdf:field-height field) (sdf:field-channels field)
        (sdf:field-bounds field)))
;; => (32 32 3 (-0.25d0 -0.25d0 1.25d0 1.25d0))

field-octets gives the field as bytes, one per channel, for a UNORM texture. Most GPUs cannot sample three-channel 8-bit textures, so for upload either use generate-mtsdf, which has four channels, or pad the bytes to four channels yourself; see Reading Fields.

From here:

• Concepts explains what the channels hold and how spread works.
• Generating Fields explains every option of the generators.
• Drawing with Fields has the shader arithmetic.

Running the tests

From cl-sdf's directory:

stift test

asdf:test-system signals an error if any test fails, so the command exits unsuccessfully in scripts and CI. The suite needs no GPU, no font, no C++ compiler and no network: the msdfgen reference output it compares against is checked in as Lisp data. See Development.