summaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'README.md')
-rw-r--r--README.md93
1 files changed, 85 insertions, 8 deletions
diff --git a/README.md b/README.md
index 9665fc1..58dae6c 100644
--- a/README.md
+++ b/README.md
@@ -32,6 +32,7 @@ The standalone example packages live in [`examples/`](examples/):
- [`micscope`](examples/micscope/): records the microphone or opens sound files, plays them either way, and shows waveform, spectrogram and spectrum; a tuner.
- [`spheres`](examples/spheres/): the three-body problem on the GPU, each body a voice synthesised by a compute shader.
- [`talk.zig`](examples/talk.zig): a talk with a slider in it, a sketch that runs its own `anim.Deck` (`zig build test-talk` plays it).
+- [`manual.zig`](examples/manual.zig): Figure 2-1 of the Intel SDM comes alive, a PDF page as vector shapes and parts of it (`zig build manual -Dmanual=PDF`; see Animation, PDF pages and parts).
Run `zig build run` inside a package, with `zig build lib --watch` in a second
terminal for hot reload. `zig build test` runs its headless checks;
@@ -121,7 +122,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`, `microphone`, `pixels`, `gpu`,
+`imageAt`, `target`, `blend`, `text`, `print`, `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
@@ -180,7 +181,8 @@ it records.
`f.download(buffer, .{ .size = n, .key = k })` reads a GPU buffer back
without stalling: the bytes arrive in a later frame's `in.downloads`, a
frame or two behind. For measurements a shader made (a pitch, a level),
-not for pixels.
+not for pixels; sound a shader made goes to the speakers with
+`f.audioBuffer` (see sound, below), which does not wait a frame.
Geometry and colors are duck-typed. Anything with `x`/`y` is a point, anything
that also has `w`/`h` (or `width`/`height`) is a rect, in any number type, and
@@ -455,8 +457,31 @@ topping its queue up to 2048 samples (about 43 ms) ahead of the device,
so what `draw` declares is heard up to that much later.
`f.audio(key, samples, .{})` streams PCM, and `input.stream(key)` reports
-what the host has queued and played: the sketch chooses how far ahead it
-keeps a stream. `f.microphone()` keeps the default recording device open
+what the host has queued and played, and its `underruns` (pushes that found
+it empty though the frame before had pushed to it: each a gap). The sketch
+chooses how far ahead it keeps a stream; `input.lead` is how far the host
+would: the slowest of the last 64 frames' worth of samples (a stream is fed
+once a frame), plus the device's pull (what it takes from a stream at once,
+1024 samples by SDL's default), plus half a pull for each recent underrun.
+A sketch that makes its sound as it goes pushes `in.lead -|
+in.stream(key).queued` a frame, and a change it makes is heard after what
+is queued ahead of it, about a pull: 19 to 27 ms after `draw` on this
+machine at 60 Hz. `SDL_AUDIO_DEVICE_SAMPLE_FRAMES=256` in the environment
+asks SDL for 5 ms pulls instead, and a change leaves in about 6.5 ms (on
+PipeWire every client then runs at that size). `f.audioBuffer(key, buffer, .{ .count
+= n })` streams `n` samples a compute shader wrote (f32 from `.offset`
+bytes): the host reads them back within the frame, waiting for the GPU's
+work so far (about 0.2 ms), and queues them. A GPU synth is then:
+
+```zig
+const n: u32 = @min(f.in.lead -| f.in.stream(1).queued, max_block);
+if (n > 0) {
+ f.compute(.{ .kernel = synth, .readwrite = &.{ss.block}, .uniforms = ..., .groups = .{ (n + 63) / 64, 1, 1 } });
+ f.audioBuffer(1, ss.block, .{ .count = n });
+}
+```
+
+(`examples/spheres` is one.) `f.microphone()` keeps the default recording device open
while declared, and the next frame's `input.microphone` holds what it heard
(to `draw` only: it is a device, not an event, so it does not replay).
`host.samples(audio)` gives a loaded sound's samples, mono at
@@ -529,8 +554,8 @@ fn wobble(now: anim.Now, swing: anim.Value) anim.Pose {
```
Objects are added (`typst`, `svg`, `rect`, `circle`, `line`, `arrow`,
-`polygon`, `custom`) and show in the order they were added; each call
-returns a handle. Animations are methods of the handle: `write`, `create`,
+`polygon`, `custom`, and `part` of another) and show in the order they
+were added; each call returns a handle. Animations are methods of the handle: `write`, `create`,
`fadeIn`, `fadeOut`, `transformInto`, `move(.{ .x, .y, .scale, .rotation,
.opacity })`, `scaleTo`, `rotate`, `indicate`; plus `anim.camera(...)` and
`value.to(x)`. `play` runs a tuple (or array) of them together; its
@@ -573,6 +598,55 @@ file, reads `scene.typst_sources`, compiles each with `typst compile`
(cached by content in `.zig-cache/typst`) and embeds the SVGs. Nothing
scans files, and a scene without Typst needs no `typst`.
+**PDF pages and parts.** Typst imports a page of a PDF as vector paths,
+so a page is a Typst object like any other:
+`s.typst("#image(\"/home/me/sdm.pdf\", page: 31)", .{})`. Typst runs with
+`/` as its root, so an absolute path names the file where it lies; the
+file is not part of the cache key, so one changed in place needs its entry
+in `.zig-cache/typst` gone. Text is outlines: every glyph is a filled
+shape (nothing to search or select), drawn crisp at any camera zoom, and
+`write` reveals the shapes in the order the PDF draws them (in the Intel
+SDM: header and footer, the text from the top, then the figures). A page
+costs what its shapes do: Figure 2-1's page of the SDM is 2.1 MB of SVG
+and 1954 shapes, parsed once, 6-12 ms, the first frame it shows; then, at
+1280x720 in a release build, 0.9-1.7 ms a frame to record for the GPU
+(0.4 ms on the GPU itself) or 2-5 ms on the CPU renderer. A table of
+contents, dot leaders and all, is five times that: show a part of it.
+`zig build bench` times the page beside the simple objects, with a budget
+of its own. An SVG a Typst object includes (`image("x.svg")`) is kept the
+same way.
+
+`s.part(page, .{ .x, .y, .w, .h })` takes the shapes whose bounds' centre
+lies in a rectangle out of an object, as an object of its own, so a field
+of a figure or a row of a table can glow, be written, fly off or morph
+while the page around it stays. The rectangle is in the object's units,
+its centre and size: the literal `s.rect` takes to cover the same place
+when the object stands at the origin at scale 1. Pick it with the guides
+(G: lay the page at the origin, at scale 1, and read the pointer), or
+from `pdftotext -bbox -f N -l N file.pdf -`, whose points from the
+top-left of a W x H pt page are `(x - W/2) * 4/3` across and
+`(y - H/2) * 4/3` down. The part stands where its shapes stood, around
+the rectangle's centre (so `indicate`, `scaleTo` and `rotate` turn it in
+place), and shows as the object does after the plays laid so far: taken
+from a page that has faded in, it is there. The object draws the rest
+from then on, at every instant. A shape goes to the first part that
+takes it, so a rule that crosses several fields (a box's outline) stays
+with whichever holds its centre: keep areas inside the rules. Parts of
+parts, and of any vector object, work the same way, and share the
+object's geometry (a page is parsed once however many parts it gives).
+`transformInto` morphs into the whole of its target, so a morph's result
+can be split by parts taken after it: `c0.transformInto(bits)`, then
+`s.part(bits, ...)` for each run of bits.
+
+`examples/manual.zig` is a talk on Figure 2-1 of the SDM (Vol. 2, page
+31): the fields of the instruction format glow in turn, `83 C0 01` is
+written below, each byte flies into its field and `C0` splits into
+`11 000 000` over Mod, Reg and R/M. `zig build manual` plays it in a
+window; the PDF is `-Dmanual=PATH` (`~/01-resources/intel-devref-ii.pdf`
+by default), never part of the repository: without it the example builds
+a scene that says so, and its script (`test/manual.script`, in `zig build
+test` when the file is there) is skipped.
+
**Custom objects** are drawn by the scene's own code with 2D commands
(`sk.draw`, `f.fill`, `f.text`): what is runtime data, a register table, a
memory grid, a code panel. `s.custom(&data, pose)` adds one, where `data`
@@ -1135,8 +1209,11 @@ Add `.sketchbook = .{ .path = "..." }` to your `build.zig.zon`.
silent there, whatever its sound (loaded, decoded or made with
`newSound`), and so are groups' gains; `decodeSound` gives `.none`, and
`loadSound` knows only sounds the page decoded (opened or dropped
- files). What does sound: streams (`f.audio`) and the microphone, mixed
- on the main thread (a ScriptProcessor), so a busy page can crackle.
+ files). What does sound: streams (`f.audio`, `f.audioBuffer`) and the
+ microphone, mixed on the main thread (a ScriptProcessor), so a busy page
+ can crackle. A GPU buffer streamed there arrives a frame or two later
+ (WebGPU reads back only asynchronously), counted as queued meanwhile, and
+ `in.lead` is a fixed 100 ms.
The reusable GPU executor and the pardes integration are described in
[docs/pardes-rendering.md](docs/pardes-rendering.md), including the remaining