summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--README.md139
1 files changed, 104 insertions, 35 deletions
diff --git a/README.md b/README.md
index 733cc3d..cf784cb 100644
--- a/README.md
+++ b/README.md
@@ -123,7 +123,7 @@ Session (a trail in an offscreen image) is stale then; repaint it from
State.
`draw` gets a `Frame`: `clear`, `fill`, `shape`, `shapeColors`, `image`,
-`imageAt`, `target`, `blend`, `text`, `print`, `clip`, `canvas`, `cursor`, `voice`, `gain`, `audio`, `audioBuffer`, `microphone`, `pixels`, `gpu`,
+`imageAt`, `target`, `blend`, `text`, `textIn`, `textScaled`, `print`, `paragraph`, `clip`, `canvas`, `cursor`, `voice`, `gain`, `audio`, `audioBuffer`, `microphone`, `pixels`, `gpu`,
`compute`, `upload`, `download`, `openFile`, `run`, `quit`, plus the three allocators and
`f.host` (`loadImage`, `decodeImage`, `newImage`, `newBuffer`, `loadSound`,
`decodeSound`, `newSound`, `samples`, `readFile`, `appendFile`, `writeFile`, `env`, `log`, `textSize`). Commands may be built
@@ -131,36 +131,8 @@ from locals: the methods copy what they keep (text, GPU descriptions,
uniforms) into scratch. Bulk data (vertices, samples, pixels, uploads) is
not copied and must outlive the frame: scratch or session memory.
-`f.text(x, y, scale, bytes, color)` draws one line from its top left
-corner; scale 1 is a 13 px monospace face (8 px a character on a 16 px
-line), and any scale works, 1.5 or 7.25. `f.host.textSize(scale, bytes)`
-is the width and line height it covers, for laying out tables and code.
-Natively the text is shaped by Pango and drawn at the canvas's own pixels,
-with advances rounded to whole pixels at that size: sharp at any size, but
-a width is not a multiple of the scale (ten digits are 80 px at scale 1,
-230 at scale 3), so measure at the scale drawn. The font is Go Mono, built
-in; `SKETCHBOOK_FONT="JetBrains Mono"` in the environment puts an
-installed family before it. On the web it is the page's `monospace`, 8 px a
-character.
-
-`f.textIn(face, x, y, scale, bytes, color)` is the same line in another
-face of the Go family, all six bundled in the binary (`sk.Face`): `.mono`,
-`.mono_bold`, `.mono_italic` for data and code, `.sans`, `.sans_medium`,
-`.sans_bold` for what is said about it; and `.code`, `.code_bold`,
-`.code_italic`, `.code_medium` are JetBrains Mono NL (no ligatures),
-bundled too, for programs. `f.host.textSizeIn(face, scale, bytes)`
-measures a line. The seven monospaced faces advance alike (0.6 em: whole pixels at 20, 25, 30, 35, 45
-and 60 px and at their doubles), so columns of text need no measuring;
-JetBrains Mono's line box is taller (ascent 1.02 em, where Go's is 0.945).
-The web host draws every face as its one.
-
-Text is shaped for the size it is drawn at, so under a camera that zooms
-its letters would shift against each other from frame to frame.
-`f.textScaled(face, x, y, scale, raster, bytes, color)` lays the line out
-and rasterizes it at `raster` and draws that at `scale`, unsnapped: give it
-the scale the move ends on (the larger of its ends) while the camera
-moves, and `textIn` again once it rests. One texture serves the whole
-move. The web host ignores `raster`.
+`f.text(x, y, scale, bytes, color)` draws text from its top left corner,
+scale 1 a 13 px face; measuring, paragraphs and faces are in Text, below.
`f.openFile("open", .{ .pattern = "wav;flac" })` shows the system's file
dialog; the answer comes back as the console line `open <path>`, so it
@@ -200,6 +172,98 @@ own type:
The drawing layer below is the exception: new, and typed (`sk.math.Vec`,
`sk.Color`), so decl literals and completion work.
+## Text
+
+`f.text(x, y, scale, bytes, color)` draws text from its top left corner;
+scale 1 is a 13 px face (Go Mono: 8 px a character, a 16 px line), any
+scale works, 1.5 or 7.25, and a `\n` starts a line. `f.textIn(face, ...)`
+is the same in another face (`sk.Face`): `.mono`, `.mono_bold`,
+`.mono_italic` for data and code, `.sans`, `.sans_medium`, `.sans_bold`
+for what is said about it (the Go family), and `.code`, `.code_bold`,
+`.code_italic`, `.code_medium`, JetBrains Mono NL (no ligatures: `->` stays
+two characters), for programs. All ten are built into the host. The
+monospaced faces advance alike (0.6 em: whole pixels at 20, 25, 30, 35, 45
+and 60 px and their doubles), so columns need no measuring; JetBrains
+Mono's line box is taller (ascent 1.02 em, where Go's is 0.945). `f.print`
+formats into `f.text`.
+
+Measuring is a pure function of the font, the size and the bytes, so it
+works anywhere, `update` and tests included, and gives the same numbers on
+every native platform:
+
+```zig
+const size = sk.text.size(.mono, 1, "0123456789"); // .{ 80, 16 }: width, height
+const l = sk.text.layout(s.line, .{ .width = 300, .@"align" = .center }); // l.w, l.h, l.lines
+```
+
+`sk.text.layout(bytes, paragraph)` lays a paragraph out without drawing
+it; `f.paragraph(x, y, bytes, paragraph)` draws it and returns the same
+`Layout`, its positions from `x`, `y`. A `sk.text.Paragraph` has `face`,
+`scale`, `color`; `width` (wrap at spaces to it; 0: lines end only at
+`\n`; a word wider than it stays whole); `align` (`.left`, `.center`,
+`.right`, within `width`, or the widest line when it is 0); `spans` (each
+from its `start` byte to the next: a `color`, a `face`, a `scale`, null for
+the paragraph's own); `reveal` (only the first N glyphs drawn, the layout
+still the whole text's: typewriter text costs nothing extra); and `caret`
+(a byte index). The `Layout` is `w`, `h`, `lines`, `glyphs` (a glyph is a
+codepoint) and `caret`: the left of the caret's glyph, the top of its line
+and the line's height. `f.host.textSize(scale, bytes)` and
+`textSizeIn(face, scale, bytes)` still measure one line.
+
+Advances are whole pixels at the size drawn (HarfBuzz's, each rounded), so
+a width is not a multiple of the scale (ten digits are 80 px at scale 1,
+230 at scale 3): measure at the scale drawn. The line box is FreeType's at
+that size. Measuring never depends on the display: a paragraph wraps the
+same at any window size or density.
+
+`sk.text.font(bytes)` is a face for a sketch's own TTF or OTF bytes
+(copied; the same bytes give the same face), null if they are not a font;
+call it where the bytes are, `setup` say, and keep the face. A glyph a face
+lacks comes from one fallback, JetBrains Mono NL (Go Mono for JetBrains
+Mono's faces); else it is the face's missing-glyph box. There is no bidi
+(text runs left to right), no colour emoji, and no system font: neither
+family has CJK, Arabic or Hebrew.
+
+Natively the text is shaped by HarfBuzz and rasterized by pardes's
+`vendor/font.c` (FreeType, light hinting, 8-bit coverage, no gamma) at the
+device size it is drawn, each glyph on a whole device pixel, sampled
+nearest, from one glyph atlas: changing text rasterizes only glyphs not
+seen before, and a frame's text is one draw. `docs/text.md` is the design.
+
+Text is shaped for the size it is drawn at, so under a camera that zooms
+its letters would shift against each other from frame to frame.
+`f.textScaled(face, x, y, scale, raster, bytes, color)` lays the line out
+at `raster` and draws it at `scale`: each glyph rastered at the size drawn,
+at the `raster` layout's place scaled, not snapped to a pixel and sampled
+smoothly, so the letters glide and keep their places. Give it the scale
+the move ends on while the camera moves, and `textIn` again once it rests.
+The web host ignores `raster`.
+
+On the web, text is the canvas's, in the page's `monospace` and
+`sans-serif` in each face's weight and style (a sketch's font a
+`FontFace` from its bytes, drawn in a fallback until the browser has
+loaded it), measured with `measureText`, so what is drawn is what is
+measured there too; but the page's fonts are not the bundled ones, so web
+widths and line heights differ from native ones and are fractional.
+
+Recipes, for a game and an editor:
+
+```zig
+// A centred label in a rect: measure, then centre the block vertically.
+const p: sk.text.Paragraph = .{ .width = r.w, .@"align" = .center, .scale = 2 };
+const l = sk.text.layout("Unlock", p);
+_ = f.paragraph(r.x, r.y + @round((r.h - l.h) / 2), "Unlock", p);
+
+// Dialogue wrapped in a box and typed out: State counts glyphs in update
+// (`s.shown += 1` a tick), draw reveals them; one layout, no new rasters.
+_ = f.paragraph(box.x, box.y, line, .{ .width = box.w, .face = .sans, .reveal = s.shown });
+const done = s.shown >= sk.text.layout(line, .{ .width = box.w, .face = .sans }).glyphs; // in update too
+
+// A caret and per-token colours and sizes in source text.
+const drawn = f.paragraph(x, y, source, .{ .face = .code, .spans = tokens, .caret = cursor });
+f.fill(sk.Rect{ .x = drawn.caret.x, .y = drawn.caret.y, .w = 1, .h = drawn.caret.h }, 0xffcc00);
+```
+
## Drawing shapes
Circles, lines and polygons are one host command, `Command.shape`: a
@@ -1126,7 +1190,7 @@ and returns plain `std.Build` objects:
| `app.addRun(lib, .{})` | the generic host running the installed library, its files in `.sketchbook/` |
| `app.addScript(exe_or_lib, file, .{})` | a headless, fresh-state scripted run, of the executable or of the library through the host (so the script can `reload` it) |
| `app.addExport(exe, .{ .fps, .frames, .size })` | a headless export of the executable's frames, as PNGs in `.frames`, a directory of the cache |
-| `app.addTest(.{})` | tests with the app importable as `app` |
+| `app.addTest(.{})` | tests with the app importable as `app`, linked with `sb.text` (FreeType, HarfBuzz and `vendor/text.c`), so they measure text as the host does |
| `app.addReloadCheck(.{ .script, .edits })` | a check that the app hot-reloads with State kept (below) |
`sketchbook.init(b, .{ ..., .script_optimize = .ReleaseSafe })` builds
@@ -1214,7 +1278,10 @@ for `zig build test-web`, Chrome.
`sb.modules` (`abi`, `sketch`, `host`, `vector`, `scope`, `anim`, and
`cloud9`, the 9P library, whose `Fsys` lets an app's tests dial its own
-executable as `fs` does), `sb.host_exe` is exposed for anything else.
+executable as `fs` does), `sb.host_exe` is exposed for anything else. `sb.text` is the static
+library the host measures and draws text with (FreeType and HarfBuzz, the
+packages pardes pins, built from source: no system font library is
+needed), which `app.addTest` links.
Add `.sketchbook = .{ .path = "..." }` to your `build.zig.zon`.
## Known limits
@@ -1288,7 +1355,9 @@ them with the native screenshots (`tools/chrome.mjs`), and times 5000
circles a frame (software Canvas2D here: about 12 ms as 5000 shapes, 8 ms
batched).
-And the rest: `test/text.zig` (a box of `textSize` under each line),
+And the rest: `test/text.zig` (a box of `textSize` under each line, and a
+wrapped, centred paragraph with spans and a caret; `zig build test-text`
+with `sk.text`'s tests and the atlas's rasters against pardes's),
`test/export.zig` (two builds export the same frames, frame k at k/fps;
the raw stream's length; a video from ffmpeg with as many frames), and the
`anim` player on its two test scenes: the live one checks, pixel by
@@ -1330,7 +1399,7 @@ calls out; tests disable their zones too. The wrapper follows Pardes's small
Zig Tracy binding. Forward the same option through dependencies that also
initialize Sketchbook so the build shares one host/client module.
-ASCII text caches coverage independently of animated ink. The pinned SDL Vulkan
+Text rasterizes each glyph once into one atlas, whatever its ink. The pinned SDL Vulkan
patch keeps memory relocation disabled and lets small transfer buffers share
allocations, avoiding hundreds of dedicated allocation frees during presentation.