diff options
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. |
