This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Backend API Reference

Every exported symbol of the optional systems, by package. The core library is in the API Reference.

• Raster backend: cl-textrender/raster
• Glyph atlas: cl-textrender/atlas
• Distance field atlas: cl-textrender/sdf

Coverage images are 2D arrays of (unsigned-byte 8) indexed by row, then column. scale is pixels per layout unit. Regions, pages and atlases are cl-atlas's: read them with cl-atlas:region-page, region-x, region-y, region-width, region-height and region-uv, and upload pages with cl-atlas:take-page-changes and copy-page-region.

Raster backend

System and package cl-textrender/raster, on cl-ft2 (FreeType). See Raster Backend.

rasterizer class

Rasterizes glyphs of cl-textrender fonts with FreeType. Make one with make-rasterizer. What it makes is kept with the faces and fonts it draws, and goes with them, or with the rasterizer once the collector takes it: each face's FreeType library and face, and each font's glyph images. So it holds no foreign resources and needs no releasing. May be used from any number of threads at once; the glyphs of one face are drawn one at a time.

make-rasterizer &key (hinting :light) → rasterizer

A new rasterizer. hinting is :light, which aligns glyphs to the pixel grid vertically only and keeps the layout's advances, or :none.

rasterizer-hinting rasterizer → :light or :none

How the rasterizer hints glyphs.

rasterize-glyph rasterizer font glyph-id &key (scale 1) (subpixel 0) rotated → coverage, left, top

Draw glyph glyph-id of font at scale, with its origin subpixel quarters of a pixel (0 to 3) right of a pixel boundary, turned 90° clockwise if rotated. Returns its coverage, and the pixel offsets of the coverage's top-left corner from the glyph's origin, left to the right and top upwards. Color glyphs give their alpha. The result is cached, and the same array is returned on later calls without allocating: do not modify it. An ID font does not have gives .notdef's image, kept once for them all. Signals cl-textrender:textrender-error if FreeType cannot draw the glyph, as for a damaged outline.

rasterize-glyph-afresh rasterizer font glyph-id &key (scale 1) (subpixel 0) rotated → coverage, left, top

Draw the glyph as rasterize-glyph does, but into a new coverage array that rasterizer does not keep, for a cache of your own, as the glyph atlas packs glyphs into atlases that go by scale. Allocates the coverage at every call.

map-layout-glyphs function rasterizer layout &key (scale 1) (x 0) (y 0) → (no values)

Call function for each glyph of layout that has ink, drawn at scale with the layout's top left at pixel x, y, which may be fractional. function gets the glyph's coverage, the whole pixel column and row of the coverage's top-left corner, and the cl-textrender:glyph. Rows grow downwards from the top of the layout, whatever its y axis. Each glyph's x is rounded to a quarter of a pixel and drawn at that offset, and its y to a whole pixel. Once every glyph has been drawn before, this allocates nothing.

render-layout rasterizer layout &key (scale 1) → coverage

layout drawn at scale as one coverage image, rows from the top of the layout: layout-height by layout-width layout units times scale, rounded up. Glyphs combine by the larger coverage; ink outside the image is clipped.

rasterizer-glyph-count rasterizer font → integer

The number of glyph images of font that rasterizer keeps.

Glyph atlas

System and package cl-textrender/atlas, on cl-textrender/raster and cl-atlas. See Glyph Atlas.

glyph-atlas class

Glyphs rasterized once and packed into cl-atlas atlases of one byte of coverage a texel, one for each font and scale. Make one with make-glyph-atlas. What it makes is kept with the fonts it draws, and goes with them, with the last hold on its scale, or with the glyph atlas once the collector takes it, so it holds no foreign resources and needs no releasing. May be used from any number of threads at once; release a scale while no thread asks for glyphs at it.

make-glyph-atlas &key (page-size 512) (hinting :light) → glyph-atlas

A glyph atlas whose atlases' pages are page-size texels square. hinting is :light or :none, as for make-rasterizer.

hold-scale glyph-atlas scale → (no values)

Take a hold on scale, a positive real, for a view that draws glyphs at it, as a game's viewport holds the scale of its window and zoom: the scale's glyphs stay until every hold is released. Scales are compared with =. Holds are counted, so views that draw at one scale share its glyphs. Allocates only the first time scale is drawn at or held.

release-scale glyph-atlas scale → boolean

Release a hold hold-scale took on scale, as its view draws at another scale or goes. With the last hold, every font frees its atlas at scale, as Godot 4.5 frees an oversampling level's glyphs with its last reference; glyphs asked for at scale after are rasterized again. Returns true if that was the last hold. Signals cl-textrender:textrender-error if scale is not held. Release a scale while no thread asks for glyphs at it.

scale-holds glyph-atlas scale → integer

How many holds on scale are not released: 0 for a scale not held.

font-atlas glyph-atlas font &key (scale 1) → cl-atlas:atlas

The atlas glyph-atlas packs font's glyphs at scale into, whose pages the renderer uploads. Made the first time: font keeps it, and frees it with itself, or as the last hold on scale is released. Allocates nothing once made.

atlas-font atlas → cl-textrender:font

The font whose glyphs atlas, made by a glyph atlas, holds, so a page of it leads to the font. Signals cl-textrender:textrender-error for an atlas a glyph atlas did not make.

atlas-scale atlas → real

The scale at which atlas, made by a glyph atlas, holds its font's glyphs.

glyph-atlas-page-size glyph-atlas → integer

The width and height of the pages, in texels.

glyph-atlas-hinting glyph-atlas → :light or :none

How the glyphs are hinted.

glyph-region glyph-atlas font glyph-id &key (scale 1) (subpixel 0) rotated → cl-atlas:region

The region of font's atlas at scale holding glyph glyph-id of font, rasterized as rasterize-glyph draws it with the same arguments. The glyph is rasterized and packed the first time it is asked for at scale; finding it after allocates nothing. A glyph without ink has an empty region, whose page is nil. An ID font does not have gives .notdef's region, packed once for them all. Signals cl-textrender:textrender-error if the glyph cannot be rasterized, as for a damaged outline.

glyph-image-offset region → left, top

Where the image in region, from glyph-region, sits relative to its glyph's origin: its top-left corner is left pixels right of the origin and top pixels above it.

map-layout-glyphs function glyph-atlas layout &key (scale 1) (x 0) (y 0) → (no values)

Call function for each glyph of layout that has ink, drawn at scale with the layout's top left at pixel x, y, which may be fractional. function gets the glyph's region in its font's atlas at scale, the whole pixel column and row where the region's top left goes, and the cl-textrender:glyph. Positions are those the raster backend's map-layout-glyphs gives. Glyphs are rasterized as they are first met; once they all have been, this allocates nothing.

Distance field atlas

System and package cl-textrender/sdf, on cl-sdf and cl-atlas. See Distance Field Atlas.

field-atlas class

Glyphs made into multi-channel true signed distance fields (MTSDF) once and packed into cl-atlas atlases of four bytes a texel, one for each face. Red, green and blue hold the multi-channel distance, whose median draws the glyph; alpha holds the true distance. Every channel maps a distance from −spread ems (0) through the edge (0.5) to +spread ems (1), positive inside. What it makes is kept with the faces it draws, and goes with them, or with the field atlas once the collector takes it, so it holds no foreign resources and needs no releasing. May be used from any number of threads at once, and fields for different glyphs are made in parallel.

make-field-atlas &key (page-size 512) (texels-per-em 32) (spread 1/4) → field-atlas

A field atlas whose faces' pages are page-size texels square, and whose fields span an em with texels-per-em texels and reach spread ems beyond each glyph's outline.

face-atlas field-atlas face → cl-atlas:atlas

The atlas field-atlas packs face's fields into, whose pages the renderer uploads as RGBA8 textures. Made the first time: face keeps it, and frees it with itself. Its cl-atlas:atlas-data is face, so a page of it leads to the face. Allocates nothing once made.

field-atlas-page-size field-atlas → integer

The width and height of the pages, in texels.

field-atlas-texels-per-em field-atlas → integer

How many texels of a field span an em.

field-atlas-spread field-atlas → single-float

How far, in ems, a field reaches beyond the outline on every side.

glyph-region field-atlas font glyph-id → cl-atlas:region

The region of the atlas of font's face holding the distance field of glyph glyph-id, made the first time any font of that face asks for it, whatever its size. Making one takes milliseconds; finding it after allocates nothing. A glyph without ink has an empty region. An ID font does not have gives .notdef's region, made once for them all. Signals cl-textrender:textrender-error if the glyph's outline cannot be made into a field.

glyph-field-bounds region → left, bottom, right, top

The rectangle of ems the field in region covers, y up from the glyph's origin on the baseline: the region's left texel column starts at left and its top row at top. All zero for a glyph without ink.

map-layout-fields function field-atlas layout &key (scale 1) (x 0) (y 0) → (no values)

Call function for each glyph of layout that has ink, drawn at scale with the layout's top left at pixel x, y. function gets eight arguments: the glyph's region; the pixel position x, y of the corner of the field's first texel (its top left in the atlas); the vector ux, uy the field's rows run along; the vector vx, vy its columns run down; and the cl-textrender:glyph. The field covers the quad from x, y to x + ux + vx, y + uy + vy. A glyph turned in vertical text gets its quad turned too. Rows grow downwards from the top of the layout, whatever its y axis, and positions are exact. Fields are made as they are first met; once they all have been, this allocates nothing.

Internal

The package cl-textrender/sys, part of the core system, holds the implementation-specific code: the locks and the finalizers that free faces and fonts. It is internal: not for users.