API Reference

Every exported symbol of the package cl-textrender, by topic, which the examples call tr through a local nickname (see Home). The optional systems are in the Backend API Reference.

Positions, sizes and metrics are single-floats in layout units. Text indexes are integers from 0 to the length of the text, and glyph IDs integers from 0 below 2^32, as HarfBuzz numbers glyphs. Y coordinates follow the layout's :y-axis convention. Every function declares the types of its arguments, which SBCL checks as it is entered: one of the wrong type, or a keyword argument outside its documented choices, signals a type-error, and given as a constant makes SBCL warn as it compiles the call. Every other failure signals textrender-error; see Errors.

• Conditions
• Faces
• What renderers keep
• Fonts
• Layout
• Layouts, lines, runs and glyphs
• Hit testing
• Outlines
• Cached outlines

Conditions

textrender-error condition

Signalled when a cl-textrender call cannot succeed: a font file that cannot be read, a destroyed face or font, a span or index outside the text, an OpenType feature that cannot be parsed. Errors from the libraries underneath are reported as this condition, in cl-textrender's terms. Its report is the message, then the hint on a line of its own. Subtype of error. See Errors.

textrender-error-message condition → string

What went wrong, in terms of the call that failed.

textrender-error-hint condition → string or nil

What to do about it.

Faces

face class

A typeface: face index of a font file or of font data in memory, with the variations of a variable font it is drawn with. Make one with make-face or with-face; face-font gives it at a size. A face holds foreign objects, which are freed once nothing holds the face or any of its fonts, or at once by destroy-face. Renderers keep what they make from it with face-cache. A face may be shared between threads. Prints with its full name, such as #<CL-TEXTRENDER:FACE DejaVu Sans {1203AE7FD3}>.

make-face source &key (index 0) variations → face

Return a face for face index of source.

• source: a file name, pathname, or octet vector holding a TrueType, OpenType or collection file. An octet vector is kept, for backends that open the font again: do not modify it afterwards.
• index: the face in a collection; 0 for a single font.
• variations: an alist of axis tags and values, such as (("wght" . 700)), for a variable font.

Signals textrender-error if source cannot be read or is not a font, or lacks the face or axes asked for.

face-font face size → font

face at size layout units per em, a positive real: the same font each time for one size, since a face keeps the fonts made from it. Signals textrender-error if face has been destroyed.

destroy-face face → (no values)

Free face and the fonts made from it now, rather than once nothing holds them, and release what renderers keep with them. Layouts made with its fonts keep their glyph positions, but cannot be laid out or drawn again. Destroying a face twice does nothing.

with-face (var source &rest args) &body body macro

Evaluate body with var bound to a face made from source and args, as make-face takes them, and destroy it when body is left.

face-live-p face → boolean

True if face has not been destroyed.

face-source face → string, pathname or octet vector

The source the face was made from.

face-index face → integer

The face index the face was made with.

face-variations face → list

The variation alist the face was made with.

face-units-per-em face → integer

The face's design units per em.

face-glyph-count face → integer

How many glyphs the face has. Its glyph IDs run from 0 below this count.

face-cache face key make → object

What face keeps under key, a renderer's cache-key: what make, a function of no arguments, returned the first time. For what a renderer makes from a face's glyphs at any size. It goes with face, or with key once forget-cache-key forgets it. make may return a second value, a function of no arguments that releases the foreign or GPU parts of the first; it runs when face is destroyed or collected, or key forgotten, on whatever thread that happens on, and must not refer to face, its fonts or anything that holds them. Finding an object kept before allocates nothing. Signals textrender-error if face has been destroyed. See Fonts.

What renderers keep

cache-key structure

A key under which faces and fonts keep what one renderer, rasterizer or atlas makes from them, with face-cache and font-cache. It knows the faces and fonts that keep something under it through weak pointers, so it keeps none of them alive. Any number of threads may cache under a key at once; forget it while none does.

make-cache-key &key for → cache-key

Return a new cache key. Forget it with forget-cache-key when what it was made for goes, as when a renderer is released. Given for, an instance of a class or a structure, the object it is made for, the key is forgotten once the collector takes for, on a thread of the collector's choosing, for an object that needs no releasing, as a rasterizer; the key must then not be what refers to for.

forget-cache-key key → (no values)

Have every face and font that keeps something under key forget it, at once, running the functions that release what they kept, so that faces and fonts that outlive what key was made for keep nothing it made, nor it. Faces and fonts destroyed or collected before released theirs then. A release function that signals an error is reported as a warning, and the rest still run. key may be used again afterwards, as a new key.

Fonts

font class

A face at a size, used for layout. face-font gives a face's font at a size; make-font and with-font make one with a face of its own. A font holds foreign objects, which are freed once nothing holds it, or at once by destroy-font. A font keeps its face, and a layout its fonts. Renderers keep what they make from it with font-cache. A font may be shared between threads, and several threads may lay out text with it at once. Prints with its full name and size, such as #<CL-TEXTRENDER:FONT DejaVu Sans 16.0 {12048F6D83}>.

make-font source &key (size 16) (index 0) variations → font

Return a font for face index of source at size layout units per em, with a face of its own, as make-face makes it from source, index and variations. Make a face with make-face instead to have several sizes share it. Signals textrender-error as make-face does.

destroy-font font → (no values)

Free font now, rather than once nothing holds it, and release what renderers keep with it; and its face too, if make-font made it. Layouts made with it keep their glyphs and positions, but cannot be laid out or drawn again. Destroying a font twice does nothing.

with-font (var source &rest args) &body body macro

Evaluate body with var bound to a font made from source and args, as make-font takes them, and destroy it when body is left.

font-live-p font → boolean

True if font has not been destroyed.

font-face font → face

The face font is a size of.

font-size font → single-float

The size in layout units per em.

font-units-per-em font → integer

The design units per em of the font's face.

font-ascent font → single-float

The distance from the baseline to the top of the line.

font-descent font → single-float

The distance from the baseline to the bottom of the line, positive.

font-line-gap font → single-float

The extra space the font asks for between lines.

font-line-height font → single-float

The default distance between baselines: ascent + descent + line gap.

font-cache font key make → object

As face-cache, for what a renderer makes from a font's glyphs at its size, which goes with font, or with key, a cache-key, once it is forgotten. make's release function must not refer to font, its face or anything that holds them. Signals textrender-error if font has been destroyed.

font-glyph-id font char → integer or nil

The glyph ID font draws char, a character or code point, with, or nil if it has none, as when a malformed font's character map points past its last glyph. This is the font's own character map, without shaping: use it for single glyphs such as a caret or a bullet, and layout-text for text. Signals textrender-error if font has been destroyed.

font-glyph-advance font glyph-id → single-float

The horizontal advance of glyph glyph-id in font, before any shaping adjustment such as kerning. An ID font does not have gives .notdef's advance. Signals textrender-error if font has been destroyed.

font-glyph-count font → integer

How many glyphs the font's face has. Its glyph IDs run from 0 below this count.

font-glyph-or-notdef font glyph-id → integer

glyph-id if font has that glyph, or else 0, the ID of its .notdef glyph, usually an empty box. Every function that takes a glyph ID answers for this glyph, so an ID the font does not have gets .notdef's advance, outline, image and field, never an error. A renderer that keeps what it makes by glyph ID keys it by this ID, so that every ID the font lacks shares .notdef's.

Layout

layout-text text font &key width (wrap t) (align :start) (direction :auto) (line-spacing 1.0) (y-axis :down) spans (orientation :horizontal) tab-stops max-lines (ellipsis "…") into → layout

Lay out the string text and return a layout.

• font: a font, or a non-empty list of fonts: each grapheme is drawn from the first that has glyphs for all of it.
• width: a positive real, the longest a line may be (the column height, in vertical text), or nil: each paragraph on one line, as long as it is.
• wrap: true to wrap lines at width; nil to keep each paragraph on one line and cut a line longer than width short, at the last grapheme boundary where it fits with ellipsis after it.
• align: :start or :end, which follow each paragraph's direction, :left, :right, :center, or :justify, which widens the spaces of every line but a paragraph's last to fill width.
• direction: the base direction, :auto (each paragraph's first strong character decides), :ltr or :rtl.
• line-spacing: a positive real multiplying each line's height. The extra space is split above and below the line.
• y-axis: :down for screen space, y growing down from the top, or :up for world space, every y negated.
• spans: a list of (start end &key font features data). font is a font or fallback list, features a list of OpenType feature strings such as "smcp" or "-liga", and data anything, passed to the glyphs and runs. Later spans override earlier ones where they overlap, key by key.
• orientation: :horizontal, or :vertical for columns read top to bottom and stacked right to left.
• tab-stops: nil for a stop every eight spaces of the first font, a positive real interval, or a list of increasing positions, continuing every eight spaces after the last.
• max-lines: a positive integer limiting the number of lines, or nil.
• ellipsis: the string that ends the last line when max-lines leaves text out, and a line cut short with wrap nil, or nil for none. It takes the style of the last character kept, and each of its graphemes a font from that style's fallback list.
• into: a layout layout-text made before, laid out again in place and returned, rather than a new layout, its lines, runs, glyphs and rectangles reused. A simple line laid out again so allocates nothing, once the layout has held one as long: text without spans, horizontal and left to right, in one script beside common characters such as digits and punctuation, without tabs or paragraph separators, each character a grapheme of its own with a glyph in the first font, that fits width, with a width and line-spacing of single-floats if given. It is laid out to the same positions as in a new layout. See Laying Out Text.

Signals textrender-error for a malformed span, a font list that holds something other than fonts, tab stops that do not increase, a destroyed font, or a feature string HarfBuzz cannot parse, and a type-error for an empty font list or a tab stop that is not a positive real. See Laying Out Text.

layout-glyphs layout → simple-vector

Every glyph of layout in a fresh vector, line by line and in visual order along each line.

do-glyphs (glyph layout &optional result) &body body macro

Evaluate body with glyph bound to each glyph of layout, line by line and in visual order along each line, then return result. The body is in an implicit nil block, so return leaves early. Allocates nothing.

Layouts, lines, runs and glyphs

Their accessors read them; none can be set. They change only as layout-text lays their layout out again, with into, in place. layout-lines, line-runs and run-glyphs return adjustable vectors with fill pointers, which a layout laid out again fills anew: read them with aref, length, across or do-glyphs, not svref.

layout structure

The result of layout-text. Only reading functions take it, so it may be read from any number of threads; but layout-text's into lays it out again in place, so lay a layout out again only where no other thread reads it.

Accessor	Value
layout-string	The text laid out.
layout-font	The font or font list layout-text was given.
layout-lines	A vector of lines, top to bottom (right to left in vertical text).
layout-width	The width: width, or the widest line, in horizontal text; the total width of the columns in vertical text.
layout-height	The height: the sum of the line heights in horizontal text; width, or the longest column, in vertical text.
layout-y-axis	:down or :up.
layout-orientation	:horizontal or :vertical.
layout-truncated-p	True if text was left out: lines past max-lines, or what lines cut short with wrap nil cut off.

line structure

A line of laid-out text, or a column in vertical text.

Accessor	Value
line-start, line-end	The text range the line covers, including trailing whitespace and, on a paragraph's last line, the paragraph separator.
line-direction	The paragraph's direction, :ltr or :rtl. Always :ltr in vertical text.
line-runs	A vector of runs in visual order.
line-baseline	Horizontal text: the baseline's y. Vertical text: the x of the column's central baseline.
line-box	A rect: the line's share of the layout, as long as the layout along the line and as thick as the line across it. In horizontal text, the layout's width by the line's height; in vertical text, the column.
line-content	A rect: the stretch of the line box its visible content takes up, from the first glyph to the last, trailing whitespace left out. Across the line it spans the line box.
line-ascent, line-descent	The largest ascent and descent among the fonts on the line.
line-truncated-p	True for a line cut short to fit an ellipsis. Such a line covers only the text it shows.

run structure

A run of glyphs with one direction, script, font and style.

Accessor	Value
run-start, run-end	The text range the run covers. Equal for an ellipsis.
run-direction	:ltr, :rtl, or :ttb for upright vertical text.
run-script	The ISO 15924 code of the run's script, such as "Latn", or nil for an ellipsis.
run-font	The font the run's glyphs come from.
run-data	The data of the run's style.
run-glyphs	A vector of glyphs in visual order along the line.
run-box	A rect: the stretch of the line box the run takes up, trailing whitespace included.

glyph structure

A glyph placed by layout.

Accessor	Value
glyph-id	The glyph index in glyph-font.
glyph-text-index	The index in the text of the first character the glyph came from. For an ellipsis glyph, the index where the text was cut.
glyph-x, glyph-y	The position of the glyph's origin on the baseline.
glyph-advance	The glyph's advance along the line.
glyph-font	The font the glyph is from: a fallback font, if the style's first font lacked it.
glyph-data	The data of the glyph's style.
glyph-rotated-p	True for a glyph in vertical text drawn turned 90° clockwise.

rect structure

A rectangle, as line-box, line-content, run-box and selection-rectangles return them. rect-x and rect-y are its smallest coordinates, in the layout's y-axis convention, and rect-width and rect-height its size. Rectangles are made during layout, so reading a line's or run's allocates nothing.

Hit testing

caret-position layout index → position, low, high

Where to draw the caret at index: its position along the line, and the two edges of the line across it. In horizontal text, x and the y of the line's top and bottom; in vertical text, y and the x of the column's left and right. The caret is at the leading edge of character index (its left edge in left-to-right text, its right edge in right-to-left text, its top in vertical text), or at the end of a line, at the trailing edge of the last character. An index inside a grapheme is moved back to the grapheme's start. Signals textrender-error for an index past the end of the text.

caret-segment layout index → x0, y0, x1, y1

The caret at index as a line segment across its line.

hit-test layout x y → index

The caret index nearest the point x, y: the nearest grapheme boundary on the line at that point, or on the first or last line for points beyond the text. On a wrapped line, a point past its end gives the index before its last grapheme, so that the caret stays on that line.

selection-rectangles layout start end → list of rects

The rectangles covering the text from start to end, one per contiguous visual stretch on each line, so a selection across bidi runs comes out in pieces. start and end may come in either order; equal bounds give (). Signals textrender-error for an index past the end of the text.

move-caret layout index direction &optional goal → index, goal

Move the caret at index one step in direction, :left, :right, :up or :down, as an editor's arrow keys do. Along a line (left and right; up and down in vertical text) the caret moves visually, one grapheme at a time, continuing onto the next or previous line at a line's end. Across lines it moves to the caret stop nearest goal, a position along the line (x, or y in vertical text), on the adjacent line. The second value is the goal to pass to the next move: the caret's new position after a move along a line, the goal kept after a move across lines. Without goal, the caret's own position is the goal. A caret in text left out moves from the end of the line before it, where it is drawn.

next-caret-index layout index → index

The caret stop after index, in logical order, or index at the end of the text.

previous-caret-index layout index → index

The caret stop before index, in logical order, or index at the start of the text.

line-at-index layout index → line

The line holding the caret at index: the line whose range contains it, or, for the end of the text or an index in text left out, the line before it, at whose end the caret is.

Outlines

outline structure

A glyph outline, in layout units of its font, y up, relative to the glyph's origin on the baseline.

Accessor	Value
outline-contours	A list of closed contours, each a list of segments with explicit start points: (:line x0 y0 x1 y1), (:quadratic x0 y0 cx cy x1 y1) or (:cubic x0 y0 c1x c1y c2x c2y x1 y1).
outline-xmin, outline-ymin, outline-xmax, outline-ymax	The bounds of every point, control points included; all zero for an empty outline.

glyph-outline font glyph-id &key quadratic tolerance → outline

The outline of glyph glyph-id in font. With quadratic true, cubic segments are replaced by quadratics within tolerance layout units of them: by default, or with nil, a thousandth of an em. An ID font does not have gives .notdef's outline. Signals textrender-error if font has been destroyed.

outline-empty-p outline → boolean

True if outline has no contours, as for a space.

outline-quadratics outline &key tolerance → (simple-array single-float (*))

outline's curves packed for a quadratic-only renderer: six floats per curve, x0 y0 cx cy x1 y1, contour after contour. Lines become quadratics with their control point at their middle. Cubics are approximated within tolerance layout units; signals textrender-error if outline has cubics and no tolerance is given.

outline-signed-area outline → single-float

The signed area outline encloses: positive where its outer contours run counterclockwise (y up), negative where clockwise. Holes count against their contours. Exact for all three segment kinds.

outline-orientation outline → :counterclockwise, :clockwise or nil

The direction outline's outer contours run in, with y up, or nil for an empty outline. TrueType glyphs are clockwise, CFF glyphs counterclockwise.

orient-outline outline direction → outline

outline with its outer contours running in direction, :counterclockwise or :clockwise, and its holes the other way. Returns outline itself if it already runs that way, or is empty. Assumes the glyph is consistent with itself, as font glyphs are.

Cached outlines

A font keeps the outlines asked of it with these, and frees them with itself. Both may be called from any thread.

cached-outline font glyph-id &key quadratic → outline

The outline of glyph glyph-id in font, as glyph-outline returns it with the default tolerance, computed only on the first request. Do not modify the result. An ID font does not have gives .notdef's, kept once for them all. Finding one kept before allocates nothing.

cached-quadratics font glyph-id → (simple-array single-float (*))

The outline-quadratics of the quadratic outline of glyph glyph-id in font, computed only on the first request. Do not modify the result. An ID font does not have gives .notdef's, kept once for them all. Finding them kept before allocates nothing.