cl-atlas

cl-atlas packs many small images, such as glyphs or icons, into a few large pages, which a renderer uploads as textures and draws from. It packs the images, caches them by any key, and tells which part of each page changed since it was last uploaded. It knows nothing of GPUs or text, and depends on nothing.

(asdf:load-system :cl-atlas)

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

;; An image is a 2D array of octets, rows by bytes.
(defun square (size)
  (make-array (list size size) :element-type '(unsigned-byte 8) :initial-element 255))

(let* ((atlas (atlas:make-atlas :page-size 512 :channels 1))
       ;; Packed the first time a key is asked for, the same region after.
       (region (atlas:atlas-find-or-add atlas '(:square 12) (lambda () (square 12))))
       (page (atlas:region-page region)))
  (list (atlas:page-index page) (atlas:region-x region) (atlas:region-y region)
        (multiple-value-list (atlas:region-uv region))
        ;; Before drawing: the rectangle of the page to upload.
        (multiple-value-list (atlas:take-page-changes page))))
;; => (0 0 0 (0.0 0.0 0.0234375 0.0234375) (0 0 12 12))

What it gives you

• Packing. A skyline packer puts each image into the first page with room, with empty texels right of and below it, so that filtering one image never reads its neighbour. When every page is full, the atlas adds one. Pages never grow and regions never move, so the texture coordinates a renderer recorded stay right.
• A cache by any key. atlas-find-or-add makes an image the first time its key is asked for, comparing keys with equal, and returns the same region every time after: a glyph at a size, an icon by name.
• Uploads. Each page remembers the rectangle that changed since it was last asked, and reads its texels out the way a texture upload takes them.
• Threads. Any number of threads may share an atlas. Images are made outside its lock, so the workers of a job pool can rasterize at once.

Pages

Page	What it covers
Getting Started	Requirements, loading, a first atlas, running the tests
Atlases and Regions	Making an atlas, images, regions and texture coordinates, the cache, pages, how packing works, clearing
Uploading Pages	What a renderer does each frame: a texture per page and the changes to upload, with cl-gfx
Threads	What may be shared, and making images on many threads at once
Errors	atlas-error, and what each message means
API Reference	Every exported symbol

Used by

• cl-textrender's cl-textrender/atlas and cl-textrender/sdf, which pack glyphs and their distance fields, with the font or face they belong to as the atlas's data.
• Pyssel, whose 2D painters upload the pages of its fonts' atlases to textures.

Status

Built in step 14 of the engine's build order, for glyphs. An atlas only grows: there is no eviction yet, and atlas-clear starts one over.

Licence

MIT. See LICENSE in the repository.