summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-16 23:01:20 -0300
committerGabriel Schneider <[email protected]>2026-11-17 12:15:01 -0300
commit87e8d3dee3bd57d28c42672d35ae214bbc058b9a (patch)
tree1a58def35f4347685b52cf1be771b9d89b25f309
parent6b07c3b2ee86592a28a713b4c6c40007c28eb6b8 (diff)
downloadsketchbook-87e8d3dee3bd57d28c42672d35ae214bbc058b9a.tar.gz
sketchbook-87e8d3dee3bd57d28c42672d35ae214bbc058b9a.zip
README: talks in the Animation section: the Deck, gates, sub-animations, slides, a talk with a widget, export holds; the player's new keys
-rw-r--r--README.md131
-rw-r--r--examples/vecanim/README.md15
2 files changed, 125 insertions, 21 deletions
diff --git a/README.md b/README.md
index 225f87c..fb0beb4 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
diff --git a/examples/vecanim/README.md b/examples/vecanim/README.md
index 7627fe4..cc6dc0e 100644
--- a/examples/vecanim/README.md
+++ b/examples/vecanim/README.md
@@ -18,18 +18,19 @@ zig build export -- - --size 3840x2160 --fps 60 |
ffmpeg -f rawvideo -pix_fmt rgba -s 3840x2160 -r 60 -i - -pix_fmt yuv420p intro.mp4
```
-Keys: space pause, click to continue after a `pause`, left/right
-previous/next play, `,`/`.` step a frame, home/end, up/down speed, B GPU/CPU,
-L loop, G guides (bounding boxes, origins and the scene's axes, with scene
-coordinates and the pointer's); drag and wheel to look around, R to reset
-the view.
+Keys: click, space or page down for the next step of a scene that pauses
+(space plays and pauses one that does not), page up back a step, `]`/`[`
+next/previous slide, P play/pause, left/right previous/next play, `,`/`.`
+step a frame, home/end, up/down speed, B GPU/CPU, L loop, G guides
+(bounding boxes, origins and the scene's axes, with scene coordinates and
+the pointer's); drag and wheel to look around, R to reset the view.
- `scenes/intro.zig`, compiled: shapes, Pythagoras morphing from one
equation to the next, a camera move with an updater swinging an arrow,
Typst math and a paragraph.
- `scenes/live.zig`, live, presented like slides: a wave of dots whose
- height the timeline animates, whose phase is the wall clock, and which
- rise to meet the mouse.
+ height the timeline animates, whose phase runs on while a pause waits,
+ and which rise to meet the mouse.
`build.zig` lists the scenes with the script `zig build test` plays each
through (screenshots in `.zig-cache/e2e`). `-Dscene` picks the one `run`,