text, font, fill

tape
@profile(t1);
import fs from "fs";
import gfx from "gfx";
import font from "font";
import fill from "fill";
import text from "text";
import io from "io";

/* What text works in: the caller's memory, no allocation inside */
struct TextMemory {
    glyphs: [256]text.Glyph;
    atlas: [65536]u8;
    edges: [2048]fill.Edge;
    order: [2048]i32;
    active: [2048]i32;
    cov: [512]u32;
    outline: font.Outline;
    filler: fill.Filler;
}

var mem: TextMemory;

fn main() -> i32 {
    let bytes: string = fs.read_file("C:/Windows/Fonts/arial.ttf") or { return 1; };
    let face: font.Face = font.open(bytes) or { io.println("not a font: {err}"); return 2; };
    fill.init(&mem.filler, mem.edges[0..2048], mem.order[0..2048], mem.active[0..2048], mem.cov[0..512]);
    var c: text.Context;
    text.init(&c, &face, 24, mem.glyphs[0..256], mem.atlas[0..65536], &mem.outline, &mem.filler);

    var s: gfx.Surface = gfx.new_surface(320, 64, gfx.Format.Rgbx) or { return 3; };
    s.clear(#FFFFFF);
    let t: text.Target = text.target(s.pixels() as *u32, s.width, s.height, s.stride, true);
    let end_x: i64 = text.draw(&c, &t, 10, 40, 0x202020, 255, "Hyvää päivää, tape!");
    io.println("drawn {end_x - 10} px wide; measure says {text.measure(&c, "Hyvää päivää, tape!")}");
    s.free();
    return 0;
}

Three modules draw TrueType text: font reads the font file, fill turns outlines into anti-aliased coverage, and text caches glyphs and draws lines of UTF-8. They allocate nothing: you give them their memory, so the same code runs in a program, in a kernel and on Uusi. gfx’s own draw_text is a small bitmap font; use these for real fonts at any size.

font

FunctionDoes
open(bytes) -> Face or FontErrorRead a TrueType file (.ttf); the Face borrows bytes, so keep them
open_at(bytes, index), face_count(bytes)A font collection’s (.ttc) faces: face index, and how many there are
glyph_box(&face, glyph, &box) -> boolThe glyph’s bounding box in font units
glyph_index(&face, code_point) -> i64The glyph for a code point (0: the font has none)
advance(&face, glyph), left_bearing(&face, glyph)Metrics in font units
kerning(&face, left, right)The kerning between two glyphs, font units: the font’s GPOS pair kerning, or its older kern table
small_cap(&face, glyph)The glyph’s small capital, when the font has them (GSUB smcp); the glyph itself otherwise
scale(units, px, face.units_per_em)Font units to pixels at px pixels per em
outline(&face, glyph, &o)The glyph’s contours into an Outline

face.ascender, descender (negative) and line_gap are in font units, like face.x_height (the height of a lowercase x; 0 when the font doesn’t say) and face.x_min and x_max (the widest any glyph reaches). OpenType fonts with CFF outlines (.otf that start OTTO) are refused with NotTrueType; a damaged font gives an error, never a crash. The errors print as what went wrong ("{err}": “not a TrueType font”). A font of colour bitmaps only (Noto Color Emoji’s usual build) opens too: its glyphs have no outlines, colorfont draws them.

text

FunctionDoes
init(&c, &face, px, glyphs, atlas, &outline, &filler)A context for face at px pixels per em, caching in glyphs and atlas
target(pixels, width, height, stride, bgr) -> TargetPixels to draw on, opaque (a gfx.Surface of format Rgbx)
target_alpha(pixels, width, height, stride, bgr) -> TargetPixels with alpha to draw on (format Argb)
draw(&c, &target, x, baseline_y, rgb, alpha, s) -> i64Draw one line of UTF-8; the x after it
measure(&c, s) -> i64Its width in pixels
draw_tracked, measure_trackedThe same with extra spacing after each glyph (26.6 pixels)
draw_fx, measure_fxPositions and widths in 26.6 fixed point, for a layout that adds them up
draw_glyph_fx(&c, &target, x26, baseline_y, rgb, alpha, glyph) -> i64One glyph by its index (a substitute you looked up yourself) at a 26.6 pen; the pen after it
use_fallback(&c, &emoji)Draw what c’s font lacks, and every emoji, from another context (the same size, an emoji font)
init_colors(&colors, records, atlas, &painter), use_colors(&c, &colors)A cache for colour glyphs, and a context drawing its font’s colour glyphs through it
cluster_end(s, at), cluster_start(s, at)Where the character (grapheme cluster) at at ends, and where the one before at starts

c.ascent, c.descent and c.line_height are in pixels: the next line’s baseline is c.line_height below. rgb is 0xRRGGBB and alpha 0 to 255. A target clips to its clip_x, clip_y, clip_w, clip_h rectangle (the whole surface from target). bgr: true means the pixels are 0xRRGGBB words, as a gfx.Surface and Windows bitmaps are.

A target from target_alpha (its field alpha is true) has the pixel’s alpha in the word’s top byte, whichever bgr says, and colours unmultiplied. Text blends as gfx does on an Argb surface, with coverage times alpha as the source’s alpha: over an opaque pixel it stays opaque, and over a transparent one the pixel gets the colour you asked for with the coverage as its alpha. A pixel no glyph covers is left as it is. A target from target is for opaque pixels: it writes 0 to the top byte, so on an Argb surface it makes what it touches transparent. The words can’t say which they are (an Rgbx word’s top byte is 0 as well), so you choose:

tape
var s: gfx.Surface = gfx.new_surface(64, 32, gfx.Format.Argb) or { return 3; };
s.clear(#102030FF);
let t: text.Target = text.target_alpha(s.pixels() as *u32, s.width, s.height, s.stride, true);
text.draw(&c, &t, 4, 24, 0xFF0000, 255, "H");     // every pixel still has alpha FF

Glyphs are drawn at quarter-pixel positions and kerned, so text keeps the font’s spacing. When the cache’s memory is full it starts over: give it room for the sizes you use (64 bytes a glyph record, 256 KiB of atlas for a few sizes of interface text).

Text is drawn a character at a time, a character being a grapheme cluster: an emoji sequence (👨‍👩‍👧‍👦, 👍🏽, 🇫🇮, 1️⃣), a letter with its combining marks, CR LF. An emoji is shaped and drawn in colour from the context’s fallback when its own font isn’t an emoji font; a code point the font lacks comes from the fallback too, and a joiner or variation selector nobody draws is skipped instead of showing a box. A letter’s marks are glyphs of their own, unpositioned; no ligatures or right-to-left text.

tape
struct ColorMemory {
    records: [512]text.ColorGlyph;
    atlas: [262144]u32;          // 1 MB of colour glyphs
    ... and a colorfont.Painter's layers, masks and bitmap buffer
}
text.init(&emoji, &emoji_face, 24, ...);         // an emoji font, the same size
text.init_colors(&colors, cm.records[0..512], cm.atlas[0..262144], &painter);
text.use_colors(&emoji, &colors);
text.use_fallback(&c, &emoji);
text.draw(&c, &t, 10, 40, 0x202020, 255, "Moi 👋🏽 🇫🇮");

The colour cache is shared by any number of contexts and starts over when full, like the glyph cache; the painter (colorfont) decides the largest emoji it draws. widgets sets all of this up with the platform’s emoji font.

fill

fill is the rasterizer under text, for any outline: lines, quadratic and cubic curves in 26.6 fixed-point pixels (fill.ONE is one pixel, y down), filled into an 8-bit coverage Mask with the nonzero or even-odd rule.

FunctionDoes
init(&f, edges, order, active, cov)A filler working in your arrays (a few hundred edges for a glyph)
begin(&f, width, height)Start a shape the size of the mask
line, quad, cubicAdd its segments
fill(&f, &mask, rule)Write the coverage (0 to 255 a pixel)

More edges than the arrays hold set f.overflow instead of writing past them. Shapes stay within 32767 pixels of the mask’s corner.

For paths, strokes and gradients on top of fill, see draw; for SVG files, svg.

Last modified: