diff options
| author | Gabriel Schneider <[email protected]> | 2026-11-17 03:54:44 -0300 |
|---|---|---|
| committer | Gabriel Schneider <[email protected]> | 2026-11-17 12:15:01 -0300 |
| commit | 1229dae433b0036547b1e28e76af645b1b57d7a0 (patch) | |
| tree | 156b08b72a8f72b63ce6d6392434d1819a5892b4 /docs | |
| parent | 7100c95a2a42e69fac9e834ddcca4524ee026b1f (diff) | |
| download | sketchbook-1229dae433b0036547b1e28e76af645b1b57d7a0.tar.gz sketchbook-1229dae433b0036547b1e28e76af645b1b57d7a0.zip | |
docs/text.md: sketchbook's text on pardes's rasterizer, the design
The calls a sketch has after the move to FreeType and HarfBuzz, what each
existing call becomes, where shaping and metrics run (one host entry,
textRun, served as data and reached from update through the glue; a
sketch's tests link the same static library), sizes under textScaled,
the faces and their one fallback, the renderer's atlas and batching, and
what the web does (canvas measureText). Recorded for review before the
code.
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_016Y9MNBECMWcJD5pdS4SR6T
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/text.md | 86 |
1 files changed, 86 insertions, 0 deletions
diff --git a/docs/text.md b/docs/text.md new file mode 100644 index 0000000..a4f2856 --- /dev/null +++ b/docs/text.md @@ -0,0 +1,86 @@ +# Text on pardes's rasterizer + +pardes draws better text than sketchbook did (Pango and Cairo, a texture a +string, sampled LINEAR). Its rasterizer is now sketchbook's: FreeType with +LIGHT hinting, 8-bit coverage, sampled NEAREST onto whole device pixels and +mixed once, no gamma (vendor/font.c, unchanged); HarfBuzz shapes. Pango, +Cairo, glib and fontconfig leave the build. + +## The calls a sketch has + +| Call | Where | What | +| --- | --- | --- | +| `f.text`, `f.textIn`, `f.print` | draw | as before: a line from its top left, scale 1 a 13 px face; a `\n` now starts a line | +| `f.textScaled(face, x, y, scale, raster, ...)` | draw | laid out at `raster`, drawn at `scale`, unsnapped | +| `f.paragraph(x, y, bytes, .{...})` | draw | draws a paragraph and returns its `Layout` | +| `sk.text.layout(bytes, .{...})` | anywhere | the same paragraph's `Layout`, nothing drawn | +| `sk.text.size(face, scale, bytes)` | anywhere | width and height, `layout` with no width | +| `sk.text.font(bytes)` | anywhere | a sketch's own face from TTF/OTF bytes, a `Face` beyond the ten | +| `host.textSize`, `host.textSizeIn` | draw | kept: `sk.text.size` for one line | + +A paragraph (`sk.text.Paragraph`): `face`, `scale`, `color`, `width` (wrap +at spaces to it; 0: lines end only at `\n`), `align` (left, center, +right), `spans` (from a byte index on: a colour, a face, a scale; each +runs to the next), `reveal` (draw only the first N glyphs), `caret` (a byte +index). `Layout` is `w`, `h`, `lines`, `glyphs` and the caret's `x`, `y`, +`h`. A glyph, for `reveal` and `glyphs`, is a codepoint. + +## Where shaping and metrics run + +Metrics are a pure function of (font bytes, size, text): HarfBuzz's +advances at the canvas size, each rounded to a whole pixel (as Pango's +rounded positions were), and the line box FreeType gives the face at that +size (pardes's cell height and ascent). They do not depend on the display: +a paragraph wraps the same on a 1x and a 2x screen. + +- **One entry, served as data.** The host serves `textRun(face, scale, + bytes, xs)`: each byte's x from the run's start, its width, ascent and + line height. `sk.text` does the rest (wrap, align, spans, reveal, + caret) in plain Zig over it, once for every host. The sketch library + reaches the host through a pointer the glue sets before each call into + the sketch, so `update` (pure: same bytes in, same numbers out) measures + too. A sketch's test binary has no host: `app.addTest` links + `sketchbook-text` (FreeType, HarfBuzz and the shim, a static library the + host links as well) and `sk.text` calls it directly. FreeType is not in + a sketch's library, so a reload does not grow. +- **Drawn is measured.** Native drawing shapes the run with the same call, + then places each glyph at its canvas position times the display's density, + rastered at the device size. At 2x a glyph is a 2x raster at twice its 1x + place: the spacing is the 1x layout's, the shapes are sharp. +- **Replays** depend on the font bytes (vendor/fonts, or a sketch's) and the + pinned FreeType and HarfBuzz: the same on every native platform. The SDL + debug font off Linux is gone; the faces are built in everywhere. + +## Sizes and transforms + +Any scale per span; a glyph is rastered at its own size. Text has no +rotation in sketchbook (anim's text stays level), so two cases remain: +upright text, NEAREST, every glyph on a whole device pixel; `textScaled` +(a camera zooming), glyphs rastered at the size drawn, placed unsnapped at +the `raster` layout's positions scaled, LINEAR, so letters glide and keep +their places. A supersampled target rasters at its 4x density, as before. + +## Fonts + +The ten faces of `sk.Face` from vendor/fonts by bytes, plus a sketch's own +(`sk.text.font`, copied, deduplicated by bytes). A codepoint a face lacks +comes from one fallback: JetBrains Mono NL for the Go faces and a sketch's, +Go Mono for JetBrains Mono's; else the face's missing-glyph box. No +fontconfig, no system fonts, no bidi (left to right only), no colour emoji, +no CJK or Arabic (neither family has them). `SKETCHBOOK_FONT` goes. + +## The renderer + +The host keeps one 2048x2048 coverage atlas (shelves of glyph ink boxes, +trimmed; full means cleared and refilled, pardes's policy) in an RGBA +texture, white premultiplied by coverage, and draws the text commands of a +run of consecutive ones as one geometry call, vertex colours carrying the +ink. pardes's `Atlas` is not used for packing: its slots are grid cells of +one body size; its rasterizer (`ui_font_raster`) and `inkBounds` are. + +## The web + +Canvas text stays. `textRun` is canvas `measureText` (prefix widths, so +drawn is measured there too), the faces are the page's `monospace` and +`sans-serif` in the face's weight and style, a sketch's font a `FontFace` +from its bytes. Web widths are not native widths, and are fractional. |
