diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 204 |
1 files changed, 198 insertions, 6 deletions
@@ -347,7 +347,8 @@ geometry; and `vector.Renderer(.gpu)` or `vector.Renderer(.cpu)`. The CPU backend computes exact coverage and runs anywhere, wasm included. The GPU backend describes one pass (8× MSAA, gradients in a shader): convex fills drawn directly, the rest stencil-then-cover, all batched into layers of -non-overlapping fills, a few draws per layer whatever the shape count. Both are tested against resvg (see `sketches/vecanim` in the game repository). +non-overlapping fills, a few draws per layer whatever the shape count. +Both are tested against resvg (`zig build diff`, below). **GPU work is data.** A sketch describes pipelines (shader code, vertex layout, blend, stencil) and passes (`f.gpu(.{ .image, .pipelines, .draws, @@ -382,6 +383,161 @@ while declared, and the next frame's `input.microphone` holds what it heard Sounds decode with single-file C libraries in `vendor/` (dr_wav, dr_flac, 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 +`sb.addScene` builds the player around it: + +```zig +const std = @import("std"); +const anim = @import("anim"); + +pub const typst_preamble = "#set text(fill: white)"; +pub const scene = anim.Scene(construct); + +fn construct(s: *anim.Builder) void { + const eq = s.typst("$ a^2 + b^2 = c^2 $", .{ .y = 220, .scale = 1.4 }); + const eq2 = s.typst("$ c = sqrt(a^2 + b^2) $", .{ .y = 220, .scale = 1.4 }); + const square = s.rect(.{ .w = 180, .h = 180, .x = -320, .stroke = anim.blue }); + s.play(.{eq.write()}, .{}); + s.play(.{ square.create(), square.rotate(std.math.pi / 4.0) }, .{ .seconds = 1.5 }); + s.play(.{eq.transformInto(eq2)}, .{}); + s.wait(1); + + // Updaters run every frame, on top of the timeline. Their extra + // arguments are bound here, like a closure's captures. + const swing = s.value(0); + s.always(square, wobble, .{swing}); + s.play(.{ swing.to(0.3), anim.camera(.{ .zoom = 1.4 }) }, .{ .ease = anim.ease.outBack }); +} + +fn wobble(now: anim.Now, swing: anim.Value) anim.Pose { + var p = now.pose; + p.rotation += now.value(swing) * @sin(now.t * 4); + return p; +} +``` + +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`, +`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 +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 +camera zoom 1, the origin in the middle, y down. + +A scene is one of two kinds, which share every call: + +- **Compiled** (`anim.Scene(construct)`): `construct` runs at comptime, + and what it recorded is played once, still at comptime, into keyframes + per object: a `from` and a `to` pose (plain structs), a time span and an + easing. Drawing an instant is a lookup and a `tween.lerp`, then the + object's updaters. The whole timeline is data before the first frame, a + morph can look ahead to where its target ends, a broken scene is a + compile error, and Typst strings are written inline. +- **Live** (`anim.Live(frame, typst)`): `frame(s: *anim.Frame)` runs every + 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. + +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 +scene and a compiled one with the same timeline show the same poses at +every instant. + +**Typst.** `s.typst(source, pose)` takes Typst markup; the scene's +`typst_preamble` goes in front of each (by default a transparent page +that fits its content). The build runs a generator that imports the scene +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`. + +**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` +has `pub fn draw(self: *const T, f: *sk.Frame, at: anim.Placed) void`. It +is an object like the others: the same camera, pose, `play`, `fadeIn`, +`move` and place in the order. + +```zig +const Bar = struct { + level: f32, + + pub fn draw(b: *const Bar, f: *sk.Frame, at: anim.Placed) void { + // In the object's own units, around its origin. + sk.draw.rect(f, .{ .x = -100, .y = -20, .w = 200, .h = 40 }, at.pen(.{ .stroke = .white, .width = 2 })); + sk.draw.rect(f, .{ .x = -100, .y = -20, .w = 200 * b.level, .h = 40 }, at.pen(.{ .fill = .hex(0xf0ac5f) })); + at.text(f, -100, 26, 1.5, "rax", .white); + } +}; + +fn frame(s: *anim.Frame) void { + const bar = s.new(Bar{ .level = 0 }); // lives for this frame + const obj = s.custom(bar, .{ .x = -200 }); + const level = s.value(0); + s.play(.{ obj.fadeIn(), level.to(1) }, .{}); + s.play(.{obj.move(.{ .x = 200, .scale = 1.5 })}, .{}); + bar.level = s.get(level); // after the plays: as it stands now +} +``` + +`at` (`anim.Placed`) is where the object stands: `xf`, its units to +canvas pixels (camera, then pose); `scale`, pixels per unit; `pose` +(`opacity`; `drawn`, 0 to 1 while a `write` or `create` plays, to reveal +by; `highlight`); `stage`, scene units to pixels; `t`; and `value(v)`, +every `Value` now, which is how a compiled scene's custom object (its +data a constant) moves. `at.pen(pen)` is a `sk.draw.Pen` in the object's +units at its opacity, `at.text` and `at.textSize` are `f.text` and +`host.textSize` likewise. Text scales and moves with the object but does +not turn. A custom object has no outline to `transformInto`. + +Vector objects are drawn on the GPU into an image, then the image onto +the canvas; a custom object draws onto the canvas directly. So the +picture is built in runs: the vector objects up to a custom one, that +object's 2D commands, the vector objects after it, and so on, each run +its own image (8x multisampled, at the canvas's size: about 140 MiB of +GPU memory at 1920x1080 and 560 at 3840x2160, so add custom objects next +to each other in the order where it does not matter). Within its `draw`, +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: + +```sh +zig build export -- frames --size 3840x2160 +zig build export -- - --size 1920x1080 --fps 60 | + ffmpeg -f rawvideo -pix_fmt rgba -s 1920x1080 -r 60 -i - -pix_fmt yuv420p scene.mp4 +``` + +A package of scenes is a few lines of `build.zig`: + +```zig +const sb = sketchbook.init(b, .{ .target = target, .optimize = optimize }); +const scene = sb.addScene(.{ .root_source_file = b.path("scenes/intro.zig") }); +_ = scene.app.addSteps(.{ .scripts = &.{b.path("test/intro.script")} }); +``` + +`scene.app` is an app like any other (`run` with hot reload: save the +scene and the animation carries on from the same instant; `lib`, `web`, +`export`, `e2e`), named after the scene file; `.imports` are modules for +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. + ## The host - **Hot reload.** It watches the library file and loads each new build through @@ -458,7 +614,11 @@ stb_vorbis): WAV, FLAC and Ogg Vorbis, chosen by content. for the canvas (`in.window_width`/`height`, and the first canvas): a sketch that sets its canvas to the room exports at any size. An export keeps state files of its own and removes them, so it can run beside a - player. `--export` plays no script. + player. `--export` plays no script. In a release build on an RTX 3050, + an `anim` scene takes 6 ms a frame as raw RGBA and 21 as PNG at + 1920x1080, 19 and 73 at 3840x2160; with ffmpeg encoding x264 from the + pipe, 11 and 41. The PNG encoder is the slow part: pipe, when the frames + are only on their way to a video. - **GPU.** The host's 2D renderer runs on an SDL GPU device, which also runs sketches' GPU passes. Without a GPU it falls back to any renderer. `--profile-gpu` times every upload, dispatch and pass alone on an idle @@ -527,6 +687,7 @@ and returns plain `std.Build` objects: | Call | Returns | | --- | --- | +| `sb.addScene(.{ .root_source_file, .name, .imports })` | an `anim` scene file's player: `.app`, and `.module` and `.typst` (its Typst as SVG) | | `app.addLibrary()` | the hot-reloadable shared library | | `app.addExecutable()` | host and sketch linked into one binary | | `app.addScriptExecutable()` | the same, built in `script_optimize` mode, as `e2e` plays scripts with | @@ -613,11 +774,14 @@ languages. Tools: `glslc` (shaderc, or the Vulkan SDK's) for shaders, for web builds with shaders `naga` (`cargo install naga-cli`; found on PATH or in cargo's -directory), and for `serve`, `miniserve` and `openssl`. This repository's -own tests also run `node` (noise on wasm32, under WASI) and, for `zig build -test-web`, Chrome. +directory), `typst` for scenes with Typst in them, and for `serve`, +`miniserve` and `openssl`. This repository's own tests also run `node` +(noise on wasm32, under WASI), `typst`, `resvg` and `python3` with numpy +and Pillow (the renderers against resvg), `ffmpeg` if there is one, and, +for `zig build test-web`, Chrome. -`sb.modules`, `sb.host_exe` and `sb.probe_exe` are exposed for anything else. +`sb.modules` (`abi`, `sketch`, `host`, `vector`, `scope`, `anim`), +`sb.host_exe` and `sb.probe_exe` are exposed for anything else. Add `.sketchbook = .{ .path = "..." }` to your `build.zig.zon`. ## Known limits @@ -674,3 +838,31 @@ test-web` draws the shape and render cases in headless Chrome, compares 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), +`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 +pixel, that a custom object sits over the vector object added before it +and under the one added after, moves, fades and zooms with the timeline +and camera, on both renderers; the compiled one is also exported at half +size. + +`zig build diff` (part of `test`) renders a corpus (`test/svg`: every +path command, fill rules, joins, caps, dashes, transforms, opacity, +gradients, symbols, and Typst documents) with resvg as the reference, and +with both vector backends through the real host, headless +(`test/svgview.zig`, `tools/svgdiff.py`). Every case is under 0.7 mean +channel error, with no more than 0.01% of pixels off by more than 48; +side-by-side images land in `.zig-cache/svgdiff`. Two details make the +reference fair: resvg samples coverage on four sub-scanlines, so it +renders at 4x and is box-filtered down (padded to whole blocks, not +squeezed); and sizes in `pt` make it round to whole pixels before +scaling, so the harness gives it unit-free sizes. + +`zig build bench` (part of `test`, after the rest) times each Typst +object of the compiled test scene at 1280x720, the drawing filling the +canvas, in release mode, and fails if a simple one (30 shapes) takes 1 ms +to parse and draw: an equation of 8 shapes parses in 0.02 ms, draws on the +CPU in 0.25 ms, and is recorded as a GPU pass in 0.02 ms (the GPU's own +time is not measured). |
