cl-ft2

Common Lisp bindings for FreeType 2: open fonts, scale them, load glyphs, read metrics, kerning and outlines, render bitmaps (antialiased, monochrome, LCD, SDF, color), stroke glyphs, stroke and rasterize outlines of your own, and drive variable fonts.

(asdf:load-system :cl-ft2)

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

(ft2:with-library (lib)
  (ft2:with-face (face lib "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf")
    (setf (ft2:face-size face) 32)
    (ft2:bitmap-data (ft2:char-bitmap face #\A))))
;; => #2A((0 0 ...) ...)   ; an (unsigned-byte 8) coverage array, top row first

The examples in this wiki call cl-ft2 by the local nickname ft2, given as here; cl-ft2 defines no global nickname.

Two layers

Package	What it is
cl-ft2	The Lisp-idiomatic API. It returns Lisp values (strings, keywords, integers and exact rationals), copies bitmaps into Lisp arrays, tracks object lifetimes, and turns every FreeType error into a freetype-error condition.
cl-ft2/ffi	The raw layer underneath, on cl-ffi. It transcribes the covered part of the C API directly (FT_Load_Glyph → ft-load-glyph) and does no error checking or memory management.

Most programs only need cl-ft2. The FFI layer is there for FreeType features that cl-ft2 does not wrap. library-handle and face-handle connect the two layers.

Contents

Start here

• Installation: requirements, loading, platforms
• Getting started: a guided tour from opening a font to drawing text
• Core concepts: units, the glyph slot, coordinate systems, lifetimes, threads

Reference

• Library and faces: make-library, open-face, face properties and global metrics
• Sizes and transforms: face-size, face-strike, face-transform-matrix, face-transform-delta
• Character maps: char-index, charmaps, iterating characters, glyph names
• Glyphs and metrics: load-glyph, load-char, load flags, hinting targets, metrics, advances, kerning
• Rendering and bitmaps: char-bitmap, render-glyph, glyph-bitmap, pixel modes
• Outlines: glyph-outline, glyph-control-box, and outlines of your own: make-outline, stroke-outline, render-outline
• Glyph objects and strokers: copy-glyph, transform-glyph, stroke-glyph
• Font variations: axes, named instances, design and normalized coordinates
• Errors: freetype-error and what each kind means
• Face dependents: building other libraries' objects on a face (HarfBuzz hb-ft)
• FFI layer: the raw cl-ft2/ffi package
• API index: every exported symbol, alphabetically

Guides

• Cookbook: drawing a line of text, glyph atlases, outlined and bold text, SDF, variable fonts, fonts in memory
• Scope and limitations: what cl-ft2 leaves to HarfBuzz, ICU and your own code
• Development: running the tests, the test fonts, CI

At a glance

• Runtime requirement: the libfreetype shared library, version 2.13.1 or newer. On Windows, cl-ft2 carries its own. The build needs no C compiler, no headers and no groveller.
• Dependencies: cl-ffi, uiop. The tests also use parachute.
• Lisp: SBCL. The code has no implementation-specific parts: those are cl-ffi's.
• License: MIT.
• Source: https://fakehacker.cc/dxtr/cl-ft2

Related projects

cl-ft2 is the rasterising layer of a text stack:

• cl-harfbuzz shapes text. Its optional cl-harfbuzz/ft2 system builds HarfBuzz fonts on cl-ft2 faces (see Face dependents).
• cl-icu handles bidi, script runs, line breaking and normalization.
• cl-textrender lays text out on cl-icu and cl-harfbuzz, and has an optional raster backend on cl-ft2.