summaryrefslogtreecommitdiff
path: root/docs/text.md
blob: 6ee3c96cce242c86c6687a3a209b4ead1fd81c0d (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
# 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.places(bytes, .{...}, out)` | anywhere | `layout`, and each byte's place (where a caret before it sits) in `out` |
| `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.