From 87e8d3dee3bd57d28c42672d35ae214bbc058b9a Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Mon, 16 Nov 2026 23:01:20 -0300 Subject: README: talks in the Animation section: the Deck, gates, sub-animations, slides, a talk with a widget, export holds; the player's new keys --- README.md | 131 ++++++++++++++++++++++++++++++++++++++++----- examples/vecanim/README.md | 15 +++--- 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`, -- cgit v1.3