summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/text.md86
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.