cl-textrender

Text layout for Common Lisp. cl-textrender takes a string and one or more fonts and turns them into lines of positioned glyphs. It handles paragraphs, bidirectional text, line breaking, shaping, font fallback, styled spans, tabs, justification, ellipsis and vertical text. It also answers what a text editor needs to know: where the caret goes, which character a click lands on, what a selection covers, and where the arrow keys move the caret.

Layout draws nothing. It returns glyph IDs and unhinted positions in resolution-independent units, for any renderer: one that draws from glyph outlines (Slug, vector output), from distance fields, or from a texture of rasterized glyphs. Optional systems provide the last two, and a CPU rasterizer for images and debugging.

It is built on cl-icu, for bidi, line breaks, graphemes and scripts, and cl-harfbuzz, for shaping and outlines. FreeType is needed only by the optional raster systems.

(asdf:load-system :cl-textrender)

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

(tr:with-font (font "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf"
                    :size 16)             ; 16 layout units per em
  (let ((layout (tr:layout-text "Hello, wide world" font :width 90)))
    (list (map 'list (lambda (line)
                       (subseq (tr:layout-string layout)
                               (tr:line-start line)
                               (tr:line-end line)))
               (tr:layout-lines layout))
          (tr:layout-width layout)
          (tr:layout-height layout)
          (tr:hit-test layout 30 25))))   ; a click on the second line
;; => (("Hello, wide " "world") 90.0 37.25 15)

Pages

Start here

• Getting Started: installing, loading, and a first program.
• Concepts: fonts and layout units, text indexes and graphemes, logical and visual order, and the layout, line, run and glyph a layout is made of.

Guides

• Fonts: faces and fonts, loading them from files or memory, sizes, collections, variable fonts, metrics, single glyphs, lifetimes, and what renderers keep with them.
• Laying Out Text: layout-text, wrapping, alignment, direction, paragraphs, line spacing, and reading the result.
• Styled Text and Fallback: font fallback lists, styled spans, OpenType features, and lines of mixed sizes.
• Typography: tabs, justification, and cutting text short with an ellipsis, by lines or within a line.
• Vertical Text: columns of CJK text, with sideways Latin.
• Coordinates and Units: layout units, screen and world space, and placing glyph outlines on the page.
• Carets and Selection: caret positions, hit testing, selection rectangles, and moving the caret like an editor.
• Glyph Outlines: outlines for Slug, MSDF and vector renderers, their orientation, and the outlines a font keeps.
• Raster Backend: cl-textrender/raster, drawing layouts on the CPU with FreeType.
• Glyph Atlas: cl-textrender/atlas, glyphs rasterized once and packed into a texture atlas.
• Distance Field Atlas: cl-textrender/sdf, glyphs made into multi-channel distance fields for outlines, glows and shadows.
• Recipes: images, colored text, SVG, a text field, labels that fit a box, text in world space, and drawing from a distance field.

Reference

• API Reference: every exported symbol of cl-textrender.
• Backend API Reference: every exported symbol of cl-textrender/raster, cl-textrender/atlas and cl-textrender/sdf.
• Errors: textrender-error, and every error cl-textrender reports.
• Threads and Lifetimes: what may be shared between threads, what holds what and when it is freed, and what allocates.
• How Layout Works: the layout pipeline step by step, for the curious and for contributors.
• Limitations: what cl-textrender does not do yet.
• Platforms and Testing: requirements, the Lisp implementation, and running the test suite.

Systems

System	What it is
cl-textrender	Layout, hit testing and glyph outlines. Use this one. Needs HarfBuzz and ICU.
cl-textrender/raster	Draws layouts and glyphs into coverage bitmaps on the CPU, with FreeType.
cl-textrender/atlas	Glyphs rasterized once and packed into a cl-atlas atlas, for renderers that draw text from a texture.
cl-textrender/sdf	Glyphs made into MTSDF distance fields by cl-sdf and packed into a cl-atlas atlas.
cl-textrender/test	The Parachute test suite.

Each system has a package of the same name. The packages have no global nicknames, which would take names from every package in the image: give them local nicknames in your own package. The examples in this wiki call cl-textrender tr, as above, and name the optional systems' packages in full. In your own code, local nicknames keep all of them short:

(defpackage #:my-game
  (:use #:cl)
  (:local-nicknames (#:tr #:cl-textrender)
                    (#:raster #:cl-textrender/raster)
                    (#:glyphs #:cl-textrender/atlas)
                    (#:fields #:cl-textrender/sdf)))

License

MIT.