Getting Started

Requirements

• SBCL. cl-atlas is plain Common Lisp: it needs no foreign library and no other Lisp library.
• For the tests: stift, which fetches Parachute and cl-threads, pinned by commit in the stiftfile. cl-threads is there only to test that threads can share an atlas.

Loading

(asdf:load-system :cl-atlas)

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

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

A first atlas

An atlas holds images of one kind: one byte a texel for coverage, such as glyphs', or four for colour. An image is a 2D array of octets, indexed by row and then by byte.

(defun square (size &optional (value 255))
  "Return an image of SIZE by SIZE texels of one byte, each VALUE."
  (make-array (list size size) :element-type '(unsigned-byte 8) :initial-element value))

(let* ((atlas (atlas:make-atlas :page-size 64))
       (small (atlas:atlas-add atlas (square 12)))
       (large (atlas:atlas-add atlas (square 20) :data :large)))
  (list (list (atlas:region-x small) (atlas:region-y small))
        (list (atlas:region-x large) (atlas:region-y large) (atlas:region-data large))
        (multiple-value-list (atlas:take-page-changes (atlas:atlas-page atlas 0)))))
;; => ((0 0) (13 0 :LARGE) (0 0 33 20))

1. make-atlas makes an atlas whose pages are 64 texels square, one byte a texel. It has no pages yet.
2. atlas-add packs the first image at the top left of a new page, and returns its region: where it went.
3. The second image goes right of the first, with one texel of padding between them. :data rides along on its region, for whatever the renderer needs with it, such as a glyph's offsets from its origin.
4. take-page-changes returns the rectangle of the page that changed since it was last asked, here both images. A renderer uploads that rectangle to the page's texture before drawing; see Uploading Pages.

To pack an image only the first time it is needed, give it a key; see the cache.

Running the tests

stift test

CI runs the suite on SBCL, on Linux.