summaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-16 23:59:29 -0300
committerGabriel Schneider <[email protected]>2026-11-17 12:15:01 -0300
commitaabb92d26f6b46cd4c482e0e2cbc8e9e9751db0d (patch)
treef5139ed90cf1747f3aa3aaa0f6266bab2a335c10 /README.md
parentc7ebfb6d18c44fec676da3d683e0b4e54001bd21 (diff)
parentbc6fe168278957ad15cf87826c8410e7358e0849 (diff)
downloadsketchbook-aabb92d26f6b46cd4c482e0e2cbc8e9e9751db0d.tar.gz
sketchbook-aabb92d26f6b46cd4c482e0e2cbc8e9e9751db0d.zip
Merge the session recorder and the talk primitives
Recording (sessions, marks, clips, the reload speed-ups under them) and anim's Deck with its example talk, together; no conflicts; zig build test: 161/161 steps, 127/127 tests. Co-Authored-By: Claude Fable 5.2 <[email protected]> Claude-Session: https://claude.ai/code/session_016Y9MNBECMWcJD5pdS4SR6T
Diffstat (limited to 'README.md')
-rw-r--r--README.md131
1 files changed, 117 insertions, 14 deletions
diff --git a/README.md b/README.md
index 6c123a2..1400f2a 100644
--- a/README.md
+++ b/README.md
@@ -29,6 +29,7 @@ The standalone example packages live in [`examples/`](examples/):
- [`noc`](examples/noc/): 21 Nature of Code sketches. Select one with `-Dsketch=flocking`.
- [`shaders`](examples/shaders/): five shader examples in both Zig and GLSL.
- [`vecanim`](examples/vecanim/): vector animation scenes. Select one with `-Dscene=scenes/live.zig`.
+- [`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).
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;
@@ -439,8 +440,8 @@ stb_vorbis): WAV, FLAC and Ogg Vorbis, chosen by content.
## Animation
The `anim` module (`sb.modules.anim`) is manim-style animation written as
-code: Typst for text and math, shapes, cameras, morphs, slide-style
-pauses, and objects the scene draws itself. A scene is one file, and
+code: Typst for text and math, shapes, cameras, morphs, talks that wait
+for clicks, and objects the scene draws itself. A scene is one file, and
`sb.addScene` builds the player around it:
```zig
@@ -480,8 +481,8 @@ returns a handle. Animations are methods of the handle: `write`, `create`,
.opacity })`, `scaleTo`, `rotate`, `indicate`; plus `anim.camera(...)` and
`value.to(x)`. `play` runs a tuple (or array) of them together; its
options are `.seconds`, `.ease` (any `fn (f32) f32`) and `.lag` (manim's
-lag ratio). `wait` moves time on, `pause()` holds the player there until a
-click, like a slide. Positions are scene units: 1280x720 of them show at
+lag ratio). `wait` moves time on; in a live scene, `pause()` makes what
+follows wait for a click (see Talks). Positions are scene units: 1280x720 of them show at
camera zoom 1, the origin in the middle, y down. The page behind them is
the scene file's `pub const background = 0xRRGGBB` (manim's grey without
one).
@@ -499,13 +500,15 @@ A scene is one of two kinds, which share every call:
frame, at runtime. Each `play` takes effect at once against `s.t`, so the
code after it reads and changes what shows, with no callbacks:
`s.pose(obj).y = ...`, `s.get(value)`, `s.camera()`, the mouse
- (`s.pointer`), the wall clock (`s.clock`, which runs on through pauses)
- or any runtime data. Its Typst sources are the declarations of the
- namespace it is given, since the build cannot run it to find them.
+ (`s.pointer`), the time (`s.t`, which runs on while a pause waits) or
+ any runtime data. Its Typst sources are the declarations of the
+ namespace it is given (or a tuple of namespaces), since the build cannot
+ run it to find them.
Both answer the player the same way (`shot`: objects, poses, values,
-camera, plays and pauses at an instant), so the only state is `t`, and
-scrubbing, seeking and hot reload are free. A test checks that a live
+camera, plays and gates at an instant), so the only state is the time and
+the pauses clicked through, and scrubbing, seeking and hot reload are
+free. A test checks that a live
scene and a compiled one with the same timeline show the same poses at
every instant.
@@ -566,11 +569,16 @@ a custom object's commands keep their own order.
**The player** (`src/anim/player.zig`) fits the scene's frame into the
canvas, and its canvas is the room it has: the window, or an export's
-`--size`. Keys: space pause, click to continue after a `pause`, left/right
-previous/next play, `,`/`.` step a frame, home/end, up/down speed, B GPU or
-CPU renderer, L loop, G guides (boxes, origins and the scene's axes, in
-scene units); drag and wheel to look around, R to reset the view. Exported,
-it plays through once, without pauses or controls, and quits at the end:
+`--size`. Its State is an `anim.Deck` (`deck.t`, `deck.playing`, ...)
+and the viewer's settings. Keys: click, space or page down for the next
+step of a talk (space plays and pauses a scene with no pause), page up or
+backspace back a step, `]`/`[` the next/previous slide, P play/pause,
+left/right previous/next play, `,`/`.` step a frame, home/end, up/down
+speed, B GPU or CPU renderer, L loop (a talk holds its end instead), G
+guides (boxes, origins and the scene's axes, in scene units); drag and
+wheel to look around, R to reset the view. Exported, it plays through once without controls, each pause
+held for the scene file's `pub const hold` seconds (1 without one), and
+quits at the end:
```sh
zig build export -- frames --size 3840x2160
@@ -593,6 +601,101 @@ the scene file besides `anim` and `sketch`. `test/scene_live.zig` and
`test/scene_compiled.zig` are small scenes of each kind, with a custom
object.
+### Talks
+
+A talk is a live scene that waits: run from the top every frame, it is a
+function of its time and of the gates opened so far. Time never stops at
+a gate. What was laid before it (plays still running, a `loop`, code
+reading `s.t`) carries on, and what comes after waits in the future until
+the gate opens. So a talk seeks, steps back and hot-reloads like any live
+scene.
+
+- `s.pause()` waits for the presenter's next step (a click, space, page
+ down). A click while a step plays finishes it, like Keynote: the
+ picture jumps to where the next pause is laid; the next click opens it.
+ Back cuts to the picture held before the last click.
+- `s.gate(open)` waits for anything: it opens on the first frame at or
+ after it is reached on which `open` is not null, and returns that value
+ from then on (null before), a choice to branch on:
+ `const pick = s.gate(app.answer) orelse return;`. Code after a closed
+ gate would show nothing, so `orelse return` is the usual end. A gate
+ opens only in `update`, from what `update` sees (events and State), so
+ a recording replays to the same talk. One click opens one gate.
+- `s.beside(f, args)` runs `f(s, args...)`, plays and all, from the
+ cursor, and leaves the cursor where it was: what follows runs alongside
+ (`s.beside(anim.Frame.clear, .{.{}})` fades a slide out while the next
+ one writes). `s.loop(f, args)` plays `f` again and again from the
+ cursor until the gate laid right after it opens; the cycle running then
+ completes. `f` only plays, and ends where it began. `s.clear(options)`
+ fades out everything that shows.
+- `s.slide()` begins a slide. Next/previous slide goes to a slide's
+ resting picture: held at its first gate (the end of the slide if it has
+ none), every gate before it opened at once (a choice with 0) or undone.
+
+The playhead is `anim.Deck`, plain data (`t`, `playing`, `speed`, `hold`,
+and `log`, each gate opened: how long after it was reached, and its
+value), so hot reload, snapshots, replay, scripts and the console see it
+like any field; `deck.waiting`, `deck.slide`, `deck.gates` and
+`deck.duration` say where the talk stands. The stock player keeps one, and
+any sketch can keep its own beside its data: its `update` decides which
+events ask for what (`anim.Ask`: `next`, `back`, `next_slide`,
+`back_slide`, `to`, `end`), so the deck never owns the keyboard. The talk
+takes the sketch's data after the frame: in `update` as `*App`, so the
+talk may change it, and when drawn as `*const App`, so drawing cannot.
+`anim.mutable(app)` is the app to write to, null when drawn; `s.events`
+are this update's events in scene units (none when drawn); a widget laid
+out before the pause it waits at takes a click by setting `s.next =
+false`. `anim.Painter` draws a shot as the player does:
+
+```zig
+pub const typst = struct { pub const law = "$ x'' + 2 zeta x' + x = 0 $"; };
+pub const scene = struct { pub const typst_sources = anim.sources(.{typst}); }; // for sb.addTypst
+pub const State = struct { deck: anim.Deck = .{}, app: App = .{} };
+pub const Session = struct { painter: anim.Painter = .{} };
+const App = struct { presses: u32 = 0 };
+const button: sk.Rect = .{ .x = -30, .y = 150, .w = 60, .h = 60 }; // scene units
+
+pub fn update(s: *State, in: *const sk.Input) void {
+ s.deck.update(in, .{ .next = in.mouseReleased(.left) != null, .back = in.pressed(sk.Key.left) }, talk, .{&s.app});
+}
+
+pub fn draw(s: *const State, ss: *Session, f: *sk.Frame) void {
+ const shot = s.deck.shot(f.scratch, f.in, .{ 0, 0 }, talk, .{&s.app}) catch return;
+ ss.painter.paint(f, shot, @import("typst"), .{}) catch {};
+}
+
+fn talk(s: *anim.Frame, app: anytype) void {
+ const law = s.typst(typst.law, .{});
+ s.play(.{law.write()}, .{});
+ s.loop(pulse, .{law}); // runs on while the deck waits
+ s.pause();
+ const knob = s.circle(.{ .r = 30, .y = 180, .fill = anim.blue });
+ s.play(.{knob.fadeIn()}, .{});
+ if (anim.mutable(app)) |a| for (s.events) |e| if (e.kind == .mouse_up and button.contains(e.x, e.y)) {
+ a.presses += 1; // the knob's click, not the presenter's next
+ s.next = false;
+ };
+ const many = s.gate(if (s.next) @intFromBool(app.presses > 2) else null) orelse return; // a choice
+ s.play(.{if (many == 1) knob.scaleTo(2) else knob.fadeOut()}, .{});
+}
+
+fn pulse(s: *anim.Frame, o: anim.Obj) void {
+ s.play(.{o.indicate()}, .{ .seconds = 1.5 });
+}
+```
+
+`sb.addTypst(module)` compiles the Typst of a module that declares
+`scene.typst_sources` (a module of the sketch's file without the `typst`
+import, see `build.zig`'s talk). Gates are known by the order they are
+reached: insert a pause above where a talk stands and it lands a step
+earlier. An edit that moves the last opened gate (a step above retimed)
+moves `t` with it on reload, so the presenter stays on the same step, as
+far into it. Exported (`in.exporting`), every gate opens `deck.hold`
+seconds after it is reached, in the first frame's run, so the video shows
+each wait for that long, loops running, and the frames are the same every
+run; a sketch quits at `deck.t >= shot.duration`. `examples/talk.zig` is
+a talk with a slider, a loop, a choice, two slides and `beside`.
+
## The host
- **Hot reload.** It watches the library file and loads each new build through