From 10115489f8988cf6a649707202a51757708883a2 Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Tue, 17 Nov 2026 00:59:53 -0300 Subject: svg: an image that is an SVG document in a data URI is drawn Typst places an SVG image, and a PDF page imported with image(), as an whose href is the document in base64; svg.zig skipped every , so any Typst object holding one silently lost it. The parser now decodes such a document and walks it into the same drawing, mapped into the image's x, y, width and height (stretched with preserveAspectRatio="none", else fitted and centered, as SVG says), with its own ids, gradients and percentages and nothing inherited from around it but opacity. It is not clipped to its box (a PDF page never draws outside itself, and a clip per shape costs the renderers a pass over every contour). Raster images still draw nothing. The root's view box and size come from one function both documents use. Tests: a unit test at the end of svg.zig (ids of its own, stretched and fitted corners, a PNG skipped); two corpus cases for zig build diff, image.svg (two data-URI images, one stretched and turned, beside an outer gradient that shares an id with an inner one) and typst-image.typ (two SVGs placed by Typst): both renderers match resvg (mean 0.09-0.11). Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_016Y9MNBECMWcJD5pdS4SR6T --- src/vector/svg.zig | 96 +++++++++++++++++++++++++++++++++++++++++------- test/svg/image.svg | 9 +++++ test/svg/typst-image.typ | 6 +++ 3 files changed, 98 insertions(+), 13 deletions(-) create mode 100644 test/svg/image.svg create mode 100644 test/svg/typst-image.typ diff --git a/src/vector/svg.zig b/src/vector/svg.zig index 31d9b15..f1b7daf 100644 --- a/src/vector/svg.zig +++ b/src/vector/svg.zig @@ -4,11 +4,12 @@ //! `ellipse`, `line`, `polyline`, `polygon`. Styling: presentation //! attributes and `style="..."`, inherited as SVG specifies; solid colors, //! linear and radial gradients; fill rules; stroke width, caps, joins, miter -//! limit and dashes; `opacity`, `fill-opacity`, `stroke-opacity`. +//! limit and dashes; `opacity`, `fill-opacity`, `stroke-opacity`. Images +//! that are SVG documents in base64 data URIs (Typst's SVG and PDF images). //! //! Not supported: text (Typst outlines it), filters, masks, clipping, -//! patterns, markers, images, CSS stylesheets. Group opacity is approximated -//! by multiplying it into each shape. +//! patterns, markers, raster images, CSS stylesheets. Group opacity is +//! approximated by multiplying it into each shape. const std = @import("std"); const geom = @import("math"); const Drawing = @import("Drawing.zig"); @@ -23,23 +24,26 @@ pub fn parse(arena: std.mem.Allocator, source: []const u8) Error!Drawing { const root = doc.root orelse return error.InvalidSvg; if (!std.mem.eql(u8, doc.nodes.items[root].name, "svg")) return error.InvalidSvg; - var p: Parser = .{ .doc = &doc, .b = .init(arena), .arena = arena, .view = .{} }; - const n = doc.nodes.items[root]; - const w = doc.attr(n, "width"); - const h = doc.attr(n, "height"); + const port = viewport(&doc, doc.nodes.items[root]); + var p: Parser = .{ .doc = &doc, .b = .init(arena), .arena = arena, .view = port.view }; + try p.children(root, .identity, .{}); + return p.b.finish(port.view, port.width, port.height); +} + +/// A root `svg` element's view box and size in pixels, each standing in +/// for the other when missing. +fn viewport(doc: *const Document, n: Node) struct { view: geom.Rect, width: f32, height: f32 } { var view: geom.Rect = .{}; if (doc.attr(n, "viewBox")) |vb| { var nums = Numbers{ .text = vb }; view = .{ .x = nums.next() orelse 0, .y = nums.next() orelse 0, .w = nums.next() orelse 0, .h = nums.next() orelse 0 }; } - var width = if (w) |v| lengthPx(v, view.w) else view.w; - var height = if (h) |v| lengthPx(v, view.h) else view.h; + var width = if (doc.attr(n, "width")) |v| lengthPx(v, view.w) else view.w; + var height = if (doc.attr(n, "height")) |v| lengthPx(v, view.h) else view.h; if (view.w <= 0 or view.h <= 0) view = .{ .w = width, .h = height }; if (width <= 0) width = view.w; if (height <= 0) height = view.h; - p.view = view; - try p.children(root, .identity, .{}); - return p.b.finish(view, width, height); + return .{ .view = view, .width = width, .height = height }; } // --------------------------------------------------------------------------- @@ -183,7 +187,7 @@ const Parser = struct { fn element(p: *Parser, index: u32, parent_transform: Affine, parent: Inherited) Error!void { const n = p.doc.nodes.items[index]; const name = n.name; - const skip = [_][]const u8{ "defs", "symbol", "linearGradient", "radialGradient", "clipPath", "mask", "pattern", "marker", "style", "title", "desc", "metadata", "filter", "text", "image", "foreignObject" }; + const skip = [_][]const u8{ "defs", "symbol", "linearGradient", "radialGradient", "clipPath", "mask", "pattern", "marker", "style", "title", "desc", "metadata", "filter", "text", "foreignObject" }; for (skip) |s| if (std.mem.eql(u8, name, s)) return; if (p.depth > 64) return; var inherited = parent; @@ -229,6 +233,52 @@ const Parser = struct { } return p.element(target, transform, inherited); } + if (std.mem.eql(u8, name, "image")) { + // An SVG as a base64 data URI, Typst's way to place an SVG or a + // PDF page: its document, mapped into the image's box. Raster + // images draw nothing. + const href = p.doc.attr(n, "href") orelse p.doc.attr(n, "xlink:href") orelse return; + const prefix = "data:image/svg+xml;base64,"; + if (!std.mem.startsWith(u8, href, prefix)) return; + const decoder = std.base64.standard.Decoder; + const bytes = try p.arena.alloc(u8, decoder.calcSizeForSlice(href[prefix.len..]) catch return); + decoder.decode(bytes, href[prefix.len..]) catch return; + var doc = Document.parse(p.arena, bytes) catch |err| switch (err) { + error.OutOfMemory => return err, + error.InvalidSvg => return, + }; + const root = doc.root orelse return; + if (!std.mem.eql(u8, doc.nodes.items[root].name, "svg")) return; + const port = viewport(&doc, doc.nodes.items[root]); + const v = port.view; + const w = if (p.doc.attr(n, "width")) |a| lengthPx(a, p.view.w) else port.width; + const h = if (p.doc.attr(n, "height")) |a| lengthPx(a, p.view.h) else port.height; + if (v.w <= 0 or v.h <= 0 or w <= 0 or h <= 0) return; + transform = transform.mul(.translate(p.number(n, "x"), p.number(n, "y"))); + // Stretched with `preserveAspectRatio="none"`, else centered at + // the largest scale that fits; drawn unclipped. + if (std.mem.startsWith(u8, std.mem.trim(u8, p.doc.attr(n, "preserveAspectRatio") orelse "", " "), "none")) { + transform = transform.mul(.scale(w / v.w, h / v.h)); + } else { + const s = @min(w / v.w, h / v.h); + transform = transform.mul(.translate((w - v.w * s) / 2, (h - v.h * s) / 2)).mul(.scale(s, s)); + } + transform = transform.mul(.translate(-v.x, -v.y)); + // A document of its own: its ids, gradients and percentages, and + // nothing inherited but opacity. + const outer = p.*; + defer { + p.doc = outer.doc; + p.view = outer.view; + p.gradients = outer.gradients; + } + p.doc = &doc; + p.view = v; + p.gradients = .empty; + p.depth += 1; + defer p.depth -= 1; + return p.children(root, transform, .{ .style = .{ .opacity = inherited.style.opacity } }); + } const b = &p.b; if (std.mem.eql(u8, name, "path")) { @@ -766,3 +816,23 @@ test "colors and lengths" { try std.testing.expectEqual(@as(f32, 20), parseLength("15pt")); try std.testing.expectEqual(@as(f32, 0.5), parseOpacity("50%")); } + +test "an SVG image in a data URI: its own ids, placed, stretched or fitted" { + var arena: std.heap.ArenaAllocator = .init(std.testing.allocator); + defer arena.deinit(); + // + const inner = "data:image/svg+xml;base64,PHN2ZyB2aWV3Qm94PSIwIDAgMTAgMjAiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+PGRlZnM+PHBhdGggaWQ9InAiIGQ9Ik0wIDBoMTB2MjBoLTEweiIvPjwvZGVmcz48dXNlIGhyZWY9IiNwIiBmaWxsPSIjMDBmZjAwIi8+PC9zdmc+"; + const d = try parse(arena.allocator(), "" ++ + "" ++ + "" ++ + ""); + try std.testing.expectEqual(@as(usize, 2), d.shapes.len); + for (d.shapes) |shape| try std.testing.expectEqual(Drawing.Color{ 0, 1, 0, 1 }, shape.style.fill.color); + // The far corner (10, 20) of the image's own path: stretched to the + // box's corner, or fitted into its middle. + for (d.shapes, [_]geom.Vec{ .{ 25, 25 }, .{ 20, 25 } }) |shape, corner| { + const far = d.cubicsOf(d.subpathsOf(shape)[0])[1][3]; + try std.testing.expectEqual(geom.vec(10, 20), far); + try std.testing.expectEqual(corner, shape.transform.apply(far)); + } +} diff --git a/test/svg/image.svg b/test/svg/image.svg new file mode 100644 index 0000000..f5a5d8e --- /dev/null +++ b/test/svg/image.svg @@ -0,0 +1,9 @@ + + + + + + + diff --git a/test/svg/typst-image.typ b/test/svg/typst-image.typ new file mode 100644 index 0000000..2c88207 --- /dev/null +++ b/test/svg/typst-image.typ @@ -0,0 +1,6 @@ +// An SVG placed by Typst: an with the document as a data URI. +#set page(width: auto, height: auto, margin: 6pt, fill: none) +#stack(dir: ltr, spacing: 8pt, + image("use.svg", width: 120pt), + image("gradients.svg", width: 80pt, height: 60pt, fit: "stretch"), +) -- cgit v1.3 From cfedacb6d8c1e194575d5b5c62d2a724bdf2add6 Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Tue, 17 Nov 2026 01:01:25 -0300 Subject: anim: Typst runs with / as its root, so a source can name any file The Typst step ran in .zig-cache/typst with Typst's default root, the directory of the file it compiles, so a source could name no file but one in the cache: #image("/home/me/manual.pdf", page: 31) failed with "would escape the project root". It now runs with --root /, which makes an absolute path in a source the file's own path; relative paths still resolve in the cache, as before. Why / and not the build root: the file a scene names (a manual, a paper) lives where its owner keeps it, outside any project, and a copy or link under the project is one jj add away from being committed. / is safe in that Typst only reads what a source names, and a scene's sources are its author's code, compiled by a build that can already read and run anything. The cache is still keyed by preamble and source alone: a file changed in place keeps its old SVG until its cache entry goes (typst.zig says so). Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_016Y9MNBECMWcJD5pdS4SR6T --- src/anim/typst.zig | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/src/anim/typst.zig b/src/anim/typst.zig index d9df734..05a0d4e 100644 --- a/src/anim/typst.zig +++ b/src/anim/typst.zig @@ -50,12 +50,18 @@ pub fn generate(comptime SceneFile: type, comptime sources: []const []const u8, try out.writeFile(io, .{ .sub_path = "typst.zig", .data = module }); } -/// Runs `typst compile` on `preamble ++ source` and caches the SVG. +/// Runs `typst compile` on `preamble ++ source` and caches the SVG. The +/// root is `/`, so an absolute path in a source is the file's own path +/// (`#image("/home/me/manual.pdf", page: 31)`) and a relative one is +/// in the cache. Typst only reads what a source names, and a scene's +/// sources are its author's code, built by a build that can already read +/// anything. A file named this way is not part of the cache key: changed +/// in place, it keeps its old SVG until its entry in the cache goes. fn compile(gpa: std.mem.Allocator, io: std.Io, cache: std.Io.Dir, name: []const u8, preamble: []const u8, source: []const u8) ![]const u8 { const typ = try std.fmt.allocPrint(gpa, "{s}.typ", .{name}); try cache.writeFile(io, .{ .sub_path = typ, .data = try std.mem.concat(gpa, u8, &.{ preamble, "\n", source, "\n" }) }); const result = try std.process.run(gpa, io, .{ - .argv = &.{ "typst", "compile", "--format", "svg", typ, name }, + .argv = &.{ "typst", "compile", "--root", "/", "--format", "svg", typ, name }, .cwd = .{ .dir = cache }, }); if (result.term != .exited or result.term.exited != 0) { -- cgit v1.3 From d302e4887c4c3fa534fec73a2141d3dc78436ccd Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Tue, 17 Nov 2026 01:05:46 -0300 Subject: anim: part, the shapes of an object inside a rectangle as an object of their own s.part(of, .{ .x, .y, .w, .h }) takes the shapes of an object whose bounds' centre lies in the rectangle (x, y its centre, in the object's units: the same literal s.rect would lay over it standing at the origin at scale 1) and makes them an object, around the rectangle's centre, so indicate, scaleTo and rotate turn it about itself. The object draws the rest from then on (its new cut), so a part can be written in, moved away or morphed while the page around it stays. A part stands where its shapes stood and shows as the object does after the plays laid so far: taken from a page that has faded in, it is there; taken first, it fades in with nothing until played. A shape goes to the first part that takes it; parts of parts work the same way. transformInto morphs into the whole of its target, as if nothing were cut from it, so a morph's result can be split into parts taken after it (which then stand where they were and show as it does). How: Source.part holds the object as it was (a pointer: in a compiled scene to a comptime constant, in a live one into the frame's arena) and the area; Object.cut lists the areas taken from it; both are in the object's id. anim.sift makes either drawing out of the whole one, sharing its geometry; the Painter sifts its cached whole, so a page is parsed once however many parts it gives. In a compiled scene the part follows its object through the plays laid before it was taken (keys copied, moved by the area's centre at the object's scale and rotation); in a live one it starts from the object's shown and settled poses. build now also moves a shape's clip with its centring (it moved the shape and left the clip behind). Test, at the end of root.zig: a row of three squares, the right one taken once the row has faded in, then each moved: the compiled and the live scene agree at every instant, the part fades with the row, stands where its square stood, and the row keeps the other two. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_016Y9MNBECMWcJD5pdS4SR6T --- src/anim/Painter.zig | 12 +++- src/anim/root.zig | 186 +++++++++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 190 insertions(+), 8 deletions(-) diff --git a/src/anim/Painter.zig b/src/anim/Painter.zig index b5d492f..f317dc1 100644 --- a/src/anim/Painter.zig +++ b/src/anim/Painter.zig @@ -56,11 +56,13 @@ pub fn fit(canvas: sk.Rect) f32 { } /// Object `o`'s drawing, centered on its origin, and its bounds. -fn built(p: *Painter, o: anim.Object, svgs: anytype) !Built { +fn built(p: *Painter, o: anim.Object, svgs: anytype) anim.BuildError!Built { const id = o.id(); if (p.drawings.get(id)) |b| return b; const arena = p.arena.?.allocator(); - const d = try anim.build(arena, o, svgs); + // A part, or what is left of an object parts were taken from: shapes + // of a whole drawing, which is built (parsed) once. + const d = if (o.source == .part or o.cut.len > 0) try anim.sift(arena, (try p.built(o.whole(), svgs)).drawing, o) else try anim.build(arena, o, svgs); const b: Built = .{ .drawing = d, .bounds = d.bounds().rect() }; try p.drawings.put(arena, id, b); return b; @@ -122,7 +124,11 @@ fn paintLayers(p: *Painter, layers: anytype, f: *sk.Frame, shot: anim.Shot, svgs // Morphing: from where this object began the transform to where // its target will stand. const morph = shot.morphs[i]; - const target = (try p.built(shot.objects[pose.into], svgs)).drawing; + // Into the whole target, parts and all: parts taken from it + // once it is made stand where they were and show as it does. + var into = shot.objects[pose.into]; + into.cut = &.{}; + const target = (try p.built(into, svgs)).drawing; const between = try vector.morph.between(f.scratch, d, world.mul(model(morph.from)), target, world.mul(model(morph.to)), pose.morph); try r.draw(between, .identity, pose.opacity); shapes += between.shapes.len; diff --git a/src/anim/root.zig b/src/anim/root.zig index 4acecb3..560d71b 100644 --- a/src/anim/root.zig +++ b/src/anim/root.zig @@ -141,6 +141,9 @@ pub const Source = union(enum) { polygon: []const [2]f32, /// Drawn by the scene's own code (`custom`). custom: Custom, + /// The shapes of `of` whose bounds' centre lies in `area` (in `of`'s + /// units), around the area's centre (`part`). + part: struct { of: *const Object, area: vector.geom.Rect }, }; /// An object the scene draws itself with 2D commands (`f.fill`, `sk.draw`, @@ -225,6 +228,8 @@ pub const Object = struct { fill: ?u32 = null, stroke: ?u32 = null, width: f32 = 4, + /// Areas whose shapes parts were taken from it: it draws the rest. + cut: []const vector.geom.Rect = &.{}, /// Identifies what the object looks like (not where it is), to cache /// its drawing by. @@ -238,11 +243,25 @@ pub const Object = struct { .circle => |c| h.update(std.mem.asBytes(&c.r)), .line => |l| h.update(std.mem.asBytes(&[_]f32{ l.dx, l.dy, @floatFromInt(@intFromBool(l.arrow)) })), .custom => |c| h.update(std.mem.asBytes(&[_]usize{ @intFromPtr(c.draw), @intFromPtr(c.ctx) })), + .part => |p| { + h.update(std.mem.asBytes(&p.of.id())); + h.update(std.mem.asBytes(&p.area)); + }, } h.update(std.mem.asBytes(&[_]u64{ o.fill orelse 1 << 32, o.stroke orelse 1 << 32 })); h.update(std.mem.asBytes(&o.width)); + h.update(std.mem.sliceAsBytes(o.cut)); return h.final(); } + + /// What a part or a cut object is drawn from (`sift`): the object + /// without its cut, or the one a part was taken from. + pub fn whole(o: Object) Object { + if (o.cut.len == 0) return o.source.part.of.*; + var w = o; + w.cut = &.{}; + return w; + } }; /// Pose fields to animate towards; the others stay as they are. @@ -526,6 +545,25 @@ const adding = struct { } }; +/// `part`'s area: `.x`, `.y` its centre (0 when left out), `.w`, `.h`. +fn areaOf(spec: anytype) vector.geom.Rect { + const w: f32 = spec.w; + const h: f32 = spec.h; + return .{ .x = number(spec, "x", 0) - w / 2, .y = number(spec, "y", 0) - h / 2, .w = w, .h = h }; +} + +/// Where a part whose origin is `c` in its object's units stands, when the +/// object stands at `p`. +fn partPose(p: Pose, c: vector.geom.Vec) Pose { + var q = p; + const at = vector.geom.Affine.rotate(p.rotation).apply(c * vector.geom.splat(p.scale)); + q.x += at[0]; + q.y += at[1]; + q.into = Pose.none; + q.morph = 0; + return q; +} + fn primitive(source: Source, spec: anytype) Object { var pose: Pose = .{}; inline for (.{ "x", "y", "scale", "rotation", "opacity", "visible" }) |name| { @@ -553,13 +591,36 @@ pub const Builder = struct { values: []const f32 = &.{}, plays: []const Play = &.{}, updaters: []const Updater = &.{}, + /// Parts, each following its object through the plays laid before it + /// was taken. + follows: []const Follow = &.{}, /// Where the next play starts. cursor: f32 = 0, + const Follow = struct { obj: u16, of: u16, plays: usize, at: vector.geom.Vec }; + pub fn add(b: *Builder, o: Object) Obj { b.objects = b.objects ++ .{o}; return @fromBackingInt(@intCast(b.objects.len - 1)); } + + /// The shapes of `of` whose bounds' centre lies in `area` (`.x`, `.y` + /// its centre, `.w`, `.h`, in `of`'s units: those of `s.rect` laid + /// over `of` at the origin, at scale 1), as an object of their own, + /// around the area's centre; `of` draws the rest. It stands where they + /// stood and shows as `of` does after the plays so far; plays after it + /// move one or the other. A shape goes to the first part that takes it. + pub fn part(b: *Builder, of: Obj, area: anytype) Obj { + const i = @backingInt(of); + const r = areaOf(area); + const whole = b.objects[i]; + var cut = whole; + cut.cut = whole.cut ++ .{r}; + b.objects = b.objects[0..i] ++ .{cut} ++ b.objects[i + 1 ..]; + const o = b.add(.{ .source = .{ .part = .{ .of = &whole, .area = r } }, .pose = partPose(whole.pose, r.center()) }); + b.follows = b.follows ++ .{Follow{ .obj = @backingInt(o), .of = i, .plays = b.plays.len, .at = r.center() }}; + return o; + } pub const svg = adding.svg; pub const typst = adding.typst; pub const rect = adding.rect; @@ -620,13 +681,23 @@ pub fn Scene(comptime construct: fn (*Builder) void) type { var value_keys: [recorded.values.len][]const Key(f32) = @splat(&.{}); var camera_keys: []const Key(Camera) = &.{}; var marks: []const f32 = &.{}; - for (recorded.plays) |play| { + for (recorded.plays, 0..) |play, played| { var buf: [2 * play.animations.len]Change = undefined; + var touched: [n]bool = @splat(false); for (changes(&buf, &poses, play.animations)) |c| { const k = play.key(Pose, c.from, c.to, c.ease); keys[c.obj] = keys[c.obj] ++ .{k}; poses[c.obj] = k.at(k.end); + touched[c.obj] = true; } + for (recorded.follows) |f| if (played < f.plays and touched[f.of]) { + var k = keys[f.of][keys[f.of].len - 1]; + k.from = partPose(k.from, f.at); + k.to = partPose(k.to, f.at); + keys[f.obj] = keys[f.obj] ++ .{k}; + poses[f.obj] = k.at(k.end); + touched[f.obj] = true; + }; for (play.animations) |a| if (a == .value) { const i = @backingInt(a.value.value); value_keys[i] = value_keys[i] ++ .{play.key(f32, values[i], a.value.to, null)}; @@ -723,9 +794,12 @@ fn latest(comptime P: type, keys: []const Key(P), t: f32) ?Key(P) { return found; } +pub const BuildError = error{ TypstNotCompiled, CustomHasNoDrawing } || vector.svg.Error; + /// The drawing of an object, centered on its origin, in pixels at scale 1. /// `compiled` has `find(source) ?[]const u8` for Typst objects' SVGs. -pub fn build(arena: std.mem.Allocator, o: Object, compiled: anytype) !Drawing { +pub fn build(arena: std.mem.Allocator, o: Object, compiled: anytype) BuildError!Drawing { + if (o.source == .part or o.cut.len > 0) return sift(arena, try build(arena, o.whole(), compiled), o); const document: ?[]const u8 = switch (o.source) { .svg => |bytes| bytes, .typst => |source| compiled.find(source) orelse return error.TypstNotCompiled, @@ -738,8 +812,14 @@ pub fn build(arena: std.mem.Allocator, o: Object, compiled: anytype) !Drawing { // Keep the SVG's pixel size (Typst's points are 4/3 px), centered. const s = if (d.view.w > 0) d.width / d.view.w else 1; const c = d.view.center(); + const centring = vector.geom.Affine.scale(s, s).mul(.translate(-c[0], -c[1])); const shapes = try arena.dupe(Drawing.Shape, d.shapes); - for (shapes) |*shape| shape.transform = vector.geom.Affine.scale(s, s).mul(.translate(-c[0], -c[1])).mul(shape.transform); + for (shapes) |*shape| { + shape.transform = centring.mul(shape.transform); + if (shape.clip) |*q| for (q) |*v| { + v.* = centring.apply(v.*); + }; + } var out = d; out.shapes = shapes; out.view = .{ .x = -d.view.w * s / 2, .y = -d.view.h * s / 2, .w = d.view.w * s, .h = d.view.h * s }; @@ -779,13 +859,43 @@ pub fn build(arena: std.mem.Allocator, o: Object, compiled: anytype) !Drawing { style.stroke = .none; } }, - .svg, .typst, .custom => unreachable, + .svg, .typst, .custom, .part => unreachable, } try b.endShape(.identity, style); const r = @max(extent(o.source), 1); return b.finish(.{ .x = -r, .y = -r, .w = 2 * r, .h = 2 * r }, 2 * r, 2 * r); } +/// The drawing of a part, or of an object parts were taken from, out of +/// `whole`, the drawing of `o.whole()`: the shapes whose bounds' centre +/// lies in the part's area, around the area's centre; or those in none of +/// the object's `cut`, where they were. Shapes and geometry are shared. +pub fn sift(arena: std.mem.Allocator, whole: Drawing, o: Object) error{OutOfMemory}!Drawing { + const areas: []const vector.geom.Rect = if (o.cut.len > 0) o.cut else &.{o.source.part.area}; + const keep_inside = o.cut.len == 0; + const c: vector.geom.Vec = if (keep_inside) areas[0].center() else .{ 0, 0 }; + const to = vector.geom.Affine.translate(-c[0], -c[1]); + var shapes: std.ArrayList(Drawing.Shape) = .empty; + for (whole.shapes) |shape| { + const b = whole.shapeBounds(shape); + const mid = shape.transform.apply((b.min + b.max) * vector.geom.splat(0.5)); + const inside = for (areas) |a| { + if (mid[0] >= a.x and mid[0] < a.x + a.w and mid[1] >= a.y and mid[1] < a.y + a.h) break true; + } else false; + if (inside != keep_inside) continue; + var kept = shape; + kept.transform = to.mul(shape.transform); + if (kept.clip) |*q| for (q) |*v| { + v.* = to.apply(v.*); + }; + try shapes.append(arena, kept); + } + var out = whole; + out.shapes = shapes.items; + if (keep_inside) out.view = .{ .x = -areas[0].w / 2, .y = -areas[0].h / 2, .w = areas[0].w, .h = areas[0].h }; + return out; +} + fn extent(s: Source) f32 { return switch (s) { .rect => |r| @max(r.w, r.h) / 2, @@ -796,7 +906,7 @@ fn extent(s: Source) f32 { for (pts) |p| m = @max(m, @max(@abs(p[0]), @abs(p[1]))); break :blk m; }, - .svg, .typst, .custom => 0, + .svg, .typst, .custom, .part => 0, }; } @@ -912,6 +1022,19 @@ pub const Frame = struct { pub const polygon = adding.polygon; pub const custom = adding.custom; + /// The shapes of `of` inside `area`, as an object of their own, showing + /// as `of` does now; `of` draws the rest (see `Builder.part`). + pub fn part(s: *Frame, of: Obj, area: anytype) Obj { + const i = @backingInt(of); + const r = areaOf(area); + const whole = s.new(s.objects.items[i]); + s.objects.items[i].cut = std.mem.concat(s.arena, vector.geom.Rect, &.{ whole.cut, &.{r} }) catch @panic("anim: out of memory"); + const o = s.add(.{ .source = .{ .part = .{ .of = whole, .area = r } }, .pose = partPose(whole.pose, r.center()) }); + s.settled.items[@backingInt(o)] = partPose(s.settled.items[i], r.center()); + s.shown.items[@backingInt(o)] = partPose(s.shown.items[i], r.center()); + return o; + } + pub fn value(s: *Frame, initial: f32) Value { s.push(&s.values, .{ .settled = initial, .shown = initial }); return @fromBackingInt(@intCast(s.values.items.len - 1)); @@ -1800,3 +1923,56 @@ test "beside runs alongside the main line; clear fades out what shows" { const gone = try live.shot(arena.allocator(), .{ .t = 2 }); try std.testing.expect(!gone.poses[0].visible and !gone.poses[1].visible and gone.duration == 2); } + +/// Three squares, 100 units each, the middle one red; the right one is +/// taken as a part once the row shows, then each moves its own way. +fn partScene(s: anytype) void { + const row = s.svg( + \\ + \\ + , .{ .x = 10, .scale = 2 }); + s.play(.{row.fadeIn()}, .{}); + const right = s.part(row, .{ .x = 100, .w = 80, .h = 80 }); + s.play(.{ right.move(.{ .y = 50 }), row.move(.{ .x = 0 }) }, .{}); +} + +test "a part takes its shapes from its object, stands where they stood and follows it until taken" { + var arena: std.heap.ArenaAllocator = .init(std.testing.allocator); + defer arena.deinit(); + const compiled = Scene(struct { + fn construct(s: *Builder) void { + partScene(s); + } + }.construct); + const live = Live(struct { + fn frame(s: *Frame) void { + partScene(s); + } + }.frame, struct {}); + for ([_]f32{ 0, 0.5, 1, 1.5, 2, 3 }) |t| { + const a = try compiled.shot(arena.allocator(), .{ .t = t }); + const b = try live.shot(arena.allocator(), .{ .t = t }); + try std.testing.expectEqualSlices(Pose, a.poses, b.poses); + try std.testing.expectEqual(a.objects[0].id(), b.objects[0].id()); + try std.testing.expectEqual(a.objects[1].id(), b.objects[1].id()); + } + // Fading in with the row, before it was taken; where the right square + // stood (10 + 2 * 100) once it was; then on its own. + try std.testing.expectEqual(compiled.pose(0, 0.5).opacity, compiled.pose(1, 0.5).opacity); + try std.testing.expectEqual(Pose{ .x = 210, .scale = 2, .visible = true }, compiled.pose(1, 1)); + try std.testing.expectEqual(@as(f32, 50), compiled.pose(1, 2).y); + try std.testing.expectEqual(@as(f32, 0), compiled.pose(0, 2).x); + try std.testing.expectEqual(@as(f32, 210), compiled.pose(1, 2).x); + // The row keeps two squares; the part is the third, around its centre. + const no_typst = struct { + fn find(_: []const u8) ?[]const u8 { + return null; + } + }; + const rest = try build(arena.allocator(), compiled.objects[0], no_typst); + const taken = try build(arena.allocator(), compiled.objects[1], no_typst); + try std.testing.expectEqual(@as(usize, 2), rest.shapes.len); + try std.testing.expectEqual(@as(usize, 1), taken.shapes.len); + try std.testing.expectEqual(vector.geom.Rect{ .x = -50, .y = -50, .w = 100, .h = 100 }, taken.bounds().rect()); + try std.testing.expectEqual(vector.geom.Rect{ .x = -150, .y = -50, .w = 200, .h = 100 }, rest.bounds().rect()); +} -- cgit v1.3 From 9d10fc880bf4e62f8421d351ce15bddeec075322 Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Tue, 17 Nov 2026 01:10:28 -0300 Subject: examples: manual, Figure 2-1 of the Intel SDM comes alive, as a talk examples/manual.zig is a live scene with pauses, played by the stock player: page 31 of the SDM's Vol. 2 (Typst's import of the PDF, every glyph a shape) fades in on paper beside a title; the camera closes on Figure 2-1, the instruction format, while the rest of the page greys and its footnotes go; each field (Prefixes, Opcode, ModR/M, SIB, Displacement, Immediate) is tinted and glows in turn; 83 C0 01, add eax, 1, is written below; each byte flies into its field as the fields it has none for fade; C0 morphs down the arrow into the ModR/M byte's boxes as 11000000, which splits into 11, 000 and 000 over Mod, Reg and R/M, each with what it says (direct, /0 ADD, EAX); and the camera goes back to the page, filled in. Twelve steps, 18 s played straight. The labels, the ModR/M boxes, the figure and its footnotes are parts of the page, by rectangles in the page's units read off pdftotext -bbox (points to units: (pt - 306) * 4/3, (pt - 396) * 4/3) and checked with the guides; each tint is the s.rect of its label's rectangle. The bits are parts of a Typst object, cut by character (0.6 em of DejaVu Sans Mono at 14 pt). The PDF is never committed. build.zig's -Dmanual names it, by default ~/01-resources/intel-devref-ii.pdf; when the file is not there the scene is one line saying how to build with it. zig build manual plays it in a window. test/manual.script, run by zig build test (and test-manual) only when the file is there, steps through the talk with pixel checks (the paper, a tint where it should be and not where it should not, a step back) and exports it twice at 10 fps, the same frames both times. zig build bench also times the manual's page (its one #image source, when the build has the PDF), with a budget of its own for a drawing of over 1000 shapes: parse under 25 ms, CPU draw under 10, GPU record under 4, at 1280x720. Measured: 6.4, 1.9 and 0.77 ms on a quiet run; 14.8, 3.5 and 1.4 at load average 34; once 28.6 ms to parse, at that load, which failed it (the simple objects' 1 ms is as sensitive: 0.87 ms then). The manual's simple objects are not benched: a two-glyph 83 fitted to the whole canvas takes 1.1-1.2 ms on the CPU. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_016Y9MNBECMWcJD5pdS4SR6T --- build.zig | 29 +++++++++- examples/manual.zig | 155 ++++++++++++++++++++++++++++++++++++++++++++++++++++ test/manual.script | 73 +++++++++++++++++++++++++ tools/bench.zig | 101 +++++++++++++++++++++------------- 4 files changed, 318 insertions(+), 40 deletions(-) create mode 100644 examples/manual.zig create mode 100644 test/manual.script diff --git a/build.zig b/build.zig index 02d312e..08db674 100644 --- a/build.zig +++ b/build.zig @@ -300,6 +300,31 @@ pub fn build(b: *Build) void { test_talk.dependOn(&talk_check.run.step); test_step.dependOn(&talk_check.run.step); + // The manual example: Figure 2-1 of the Intel SDM, Vol. 2, page 31, as + // a talk in the stock player. The PDF is named, never committed: built + // without it, the scene says so, and only its script needs it. + const pdf = b.option([]const u8, "manual", "The Intel SDM Vol. 2 PDF for the manual example (default ~/01-resources/intel-devref-ii.pdf)") orelse + b.pathJoin(&.{ b.graph.environ_map.get("HOME") orelse "/", "01-resources", "intel-devref-ii.pdf" }); + const have_pdf = if (std.Io.Dir.cwd().access(b.graph.io, pdf, .{})) true else |_| false; + const manual_options = b.addOptions(); + manual_options.addOption(?[]const u8, "pdf", if (have_pdf) pdf else null); + const manual = sb.addScene(.{ .root_source_file = b.path("examples/manual.zig"), .imports = &.{.{ .name = "manual", .module = manual_options.createModule() }} }); + const manual_lib = manual.app.addLibrary(); + b.step("manual", "Play the manual example in a window (-Dmanual=PDF, Vol. 2 of the Intel SDM)").dependOn(&manual.app.addRun(manual_lib, .{ .state = ".zig-cache/manual.state" }).step); + test_step.dependOn(&manual_lib.step); + if (have_pdf) { + const manual_exe = manual.app.addExecutable(); + const manual_script = manual.app.addScript(manual_exe, b.path("test/manual.script"), .{}); + // Two exports (a frame cap apiece, so the build runs both), which + // quit at the end, as the stock player does. + for ([_][]const u8{ "a", "b" }, [_]u64{ 1000, 1001 }) |define, cap| { + manual_script.addArg("--define"); + manual_script.addPrefixedDirectoryArg(b.fmt("{s}=", .{define}), manual.app.addExport(manual_exe, .{ .fps = 10, .frames = cap, .size = .{ 640, 360 } }).frames); + } + b.step("test-manual", "Play the manual example through its steps, and export it twice").dependOn(&manual_script.step); + test_step.dependOn(&manual_script.step); + } + // Both vector renderers against resvg, through the host (tools/svgdiff.py). const svgview = sb.app(.{ .name = "svgview", .root_source_file = b.path("test/svgview.zig"), .imports = &.{.{ .name = "vector", .module = sb.modules.vector }} }); const diff = b.addSystemCommand(&.{ "python3", "tools/svgdiff.py" }); @@ -324,11 +349,13 @@ pub fn build(b: *Build) void { .{ .name = "anim", .module = sb.modules.anim }, .{ .name = "scene", .module = compiled.module }, .{ .name = "typst", .module = compiled.typst }, + .{ .name = "manual", .module = manual.module }, + .{ .name = "manual_typst", .module = manual.typst }, }, }), })); bench.has_side_effects = true; - b.step("bench", "Time parsing and drawing a scene's Typst (release mode, must be under 1ms)").dependOn(&bench.step); + b.step("bench", "Time parsing and drawing scenes' Typst (release mode: a simple object under 1ms, a PDF page in its own budget)").dependOn(&bench.step); // After the tests above, not beside them: it measures time. for (test_step.dependencies.items) |step| bench.step.dependOn(step); test_step.dependOn(&bench.step); diff --git a/examples/manual.zig b/examples/manual.zig new file mode 100644 index 0000000..8b11247 --- /dev/null +++ b/examples/manual.zig @@ -0,0 +1,155 @@ +//! A page of the Intel SDM as a talk: Figure 2-1, the instruction format +//! (Vol. 2, page 31), comes alive. The page is Typst's import of the PDF, +//! every glyph and rule a vector shape; the fields are `part`s of it, cut +//! out by rectangles in the page's units (read off the player's guides and +//! `pdftotext -bbox`, points to units: (pt - 306) * 4/3 across, (pt - 396) +//! * 4/3 down). `83 C0 01`, `add eax, 1`, is written below, its bytes fly +//! into their fields, and C0 splits into its ModR/M bits. +//! +//! The PDF is the build's `-Dmanual` (`~/01-resources/intel-devref-ii.pdf` +//! by default) and is never committed; without it the scene says so. +//! +//! click, space, page down next step page up back +const std = @import("std"); +const anim = @import("anim"); +const pdf: ?[]const u8 = @import("manual").pdf; + +pub const name = "manual"; +pub const hold = 1.5; +pub const typst_preamble = + \\#set page(width: auto, height: auto, margin: 0pt, fill: none) + \\#set text(font: "DejaVu Sans Mono", size: 14pt, fill: rgb("#c0392b")) +; +pub const typst = struct { + pub const page = "#image(\"" ++ (pdf orelse "") ++ "\", page: 31)"; + pub const title = "#text(font: \"New Computer Modern\", size: 40pt, fill: rgb(\"#ece6e2\"))[Figure 2-1, alive]"; + pub const from = "#text(font: \"New Computer Modern\", size: 16pt, fill: rgb(\"#8c8c8c\"))[IntelĀ® 64 and IA-32 SDM, Vol. 2, page 31]"; + pub const add = "#text(fill: rgb(\"#555555\"))[add eax, 1]"; + pub const b83 = "83"; + pub const c0 = "C0"; + pub const b01 = "01"; + pub const bits = "11000000"; + pub const direct = "#text(size: 8pt, fill: rgb(\"#555555\"))[direct]"; + pub const is_add = "#text(size: 8pt, fill: rgb(\"#555555\"))[/0 ADD]"; + pub const eax = "#text(size: 8pt, fill: rgb(\"#555555\"))[EAX]"; +}; +const missing = struct { + pub const note = "#text(font: \"New Computer Modern\", size: 24pt, fill: rgb(\"#ece6e2\"))[No manual: build with `-Dmanual=/path/to/intel-sdm-vol2.pdf`]"; +}; +pub const scene = anim.Live(if (pdf == null) placeholder else talk, if (pdf == null) missing else typst); + +fn placeholder(s: *anim.Frame) void { + s.play(.{s.typst(missing.note, .{}).write()}, .{}); +} + +/// Rectangles in the page's units, as `s.part` and `s.rect` take them. +const Area = struct { x: f32, y: f32, w: f32, h: f32 }; + +/// The labels of the figure's top row of fields: Prefixes, Opcode, +/// ModR/M, SIB, Displacement, Immediate (inside the rules, which stay). +const fields = [_]Area{ + .{ .x = -199.5, .y = -110.7, .w = 69.3, .h = 33.3 }, + .{ .x = -127.5, .y = -110.7, .w = 69.3, .h = 33.3 }, + .{ .x = -55.5, .y = -110.7, .w = 69.3, .h = 33.3 }, + .{ .x = 16.5, .y = -110.7, .w = 69.3, .h = 33.3 }, + .{ .x = 100.5, .y = -110.7, .w = 93.3, .h = 33.3 }, + .{ .x = 184.9, .y = -110.7, .w = 70.1, .h = 33.3 }, +}; +const opcode = 1; +const modrm = 2; +const immediate = 5; +/// The ModR/M byte's own boxes: Mod, Reg/Opcode, R/M. +const bit_boxes = [_]Area{ + .{ .x = -144.0, .y = 5.3, .w = 33.3, .h = 25.3 }, + .{ .x = -102.0, .y = 5.3, .w = 45.3, .h = 25.3 }, + .{ .x = -53.7, .y = 5.3, .w = 46.0, .h = 25.3 }, +}; +/// The ModR/M byte's three boxes together, across. +const byte_x = -95.7; +/// The figure: both rows of boxes, the arrows and the notes; and its +/// footnotes, under it. +const figure: Area = .{ .x = -7.3, .y = -54.7, .w = 468, .h = 160 }; +const footnotes: Area = .{ .x = -8, .y = 70.7, .w = 453, .h = 56 }; +/// `11000000` in its own units: 8 characters of 0.6 em at 14 pt. +const char = 0.6 * 14 * 4.0 / 3.0; + +fn talk(s: *anim.Frame) void { + // The page, whole, on paper; the camera far enough out to see it all. + const paper = s.rect(.{ .w = 816, .h = 1056, .fill = 0xffffff }); + const page = s.typst(typst.page, .{}); + const title = s.typst(typst.title, .{ .x = -700, .y = -380 }); + const from = s.typst(typst.from, .{ .x = -700, .y = -325 }); + // A tint over each field's label box (the same rectangle as its part), + // laid before the parts so that they draw over it. + var tints: [fields.len]anim.Obj = undefined; + for (&tints, fields) |*t, f| t.* = s.rect(.{ .x = f.x, .y = f.y, .w = f.w, .h = f.h, .fill = 0x58c4dd60 }); + s.play(.{anim.camera(.{ .zoom = 0.65 })}, .{ .seconds = 0 }); + s.play(.{ title.write(), from.fadeIn(), paper.fadeIn(), page.fadeIn() }, .{ .seconds = 2 }); + s.pause(); + + // Onto the figure. Its labels, the ModR/M byte's boxes, the figure + // around them and its footnotes become parts of the page; the rest of + // the page greys, and the footnotes go, to make room. + var labels: [fields.len]anim.Obj = undefined; + for (&labels, fields) |*l, f| l.* = s.part(page, f); + var boxes: [bit_boxes.len]anim.Obj = undefined; + for (&boxes, bit_boxes) |*b, area| b.* = s.part(page, area); + _ = s.part(page, figure); + const notes = s.part(page, footnotes); + s.play(.{ anim.camera(.{ .zoom = 2.3, .x = -7, .y = -35 }), page.move(.{ .opacity = 0.25 }), notes.fadeOut(), title.fadeOut(), from.fadeOut() }, .{ .seconds = 1.5 }); + s.pause(); + + // Each field in turn. + for (labels, tints, 0..) |label, tint, i| { + if (i > 0) s.play(.{ tints[i - 1].fadeOut(), label.indicate(), tint.fadeIn() }, .{}) else s.play(.{ label.indicate(), tint.fadeIn() }, .{}); + s.pause(); + } + s.play(.{tints[fields.len - 1].fadeOut()}, .{ .seconds = 0.5 }); + + // An instruction: add eax, 1. + const b83 = s.typst(typst.b83, .{ .x = -40, .y = 70 }); + const c0 = s.typst(typst.c0, .{ .y = 70 }); + const b01 = s.typst(typst.b01, .{ .x = 40, .y = 70 }); + const add = s.typst(typst.add, .{ .x = 150, .y = 70 }); + s.play(.{ b83.write(), c0.write(), b01.write(), add.write() }, .{ .seconds = 1.5, .lag = 0.3 }); + s.pause(); + + // Each byte flies into its field; the fields it has none for fade. + var flights: [fields.len + 3]anim.Animation = undefined; + for (labels, 0..) |label, i| flights[i] = switch (i) { + opcode, modrm, immediate => label.fadeOut(), + else => label.move(.{ .opacity = 0.3 }), + }; + flights[6] = b83.move(.{ .x = fields[opcode].x, .y = fields[opcode].y, .scale = 1.3 }); + flights[7] = c0.move(.{ .x = fields[modrm].x, .y = fields[modrm].y, .scale = 1.3 }); + flights[8] = b01.move(.{ .x = fields[immediate].x, .y = fields[immediate].y, .scale = 1.3 }); + s.play(flights, .{ .seconds = 1.5, .lag = 0.2 }); + s.pause(); + + // C0 is a ModR/M byte: down the arrow into its boxes, as bits. + const bits = s.typst(typst.bits, .{ .x = byte_x, .y = bit_boxes[0].y }); + s.play(.{ boxes[0].fadeOut(), boxes[1].fadeOut(), boxes[2].fadeOut(), c0.transformInto(bits) }, .{ .seconds = 1.5 }); + s.pause(); + + // 11 000 000: mod, reg, r/m, each into its box, and what it says. + const mod = s.part(bits, .{ .x = -3 * char, .w = 2 * char, .h = 40 }); + const reg = s.part(bits, .{ .x = -0.5 * char, .w = 3 * char, .h = 40 }); + const rm = s.part(bits, .{ .x = 2.5 * char, .w = 3 * char, .h = 40 }); + const says = [_]anim.Obj{ + s.typst(typst.direct, .{ .x = bit_boxes[0].x, .y = 28 }), + s.typst(typst.is_add, .{ .x = bit_boxes[1].x, .y = 28 }), + s.typst(typst.eax, .{ .x = bit_boxes[2].x, .y = 28 }), + }; + s.play(.{ + mod.move(.{ .x = bit_boxes[0].x }), + reg.move(.{ .x = bit_boxes[1].x }), + rm.move(.{ .x = bit_boxes[2].x }), + says[0].write(), + says[1].write(), + says[2].write(), + }, .{ .seconds = 1.5 }); + s.pause(); + + // Back to the page, filled in. + s.play(.{ anim.camera(.{ .zoom = 0.65, .x = 0, .y = 0 }), page.move(.{ .opacity = 1 }), notes.fadeIn(), add.fadeOut(), title.fadeIn(), from.fadeIn() }, .{ .seconds = 1.5 }); +} diff --git a/test/manual.script b/test/manual.script new file mode 100644 index 0000000..3bc3c73 --- /dev/null +++ b/test/manual.script @@ -0,0 +1,73 @@ +# The manual example (examples/manual.zig) on Vol. 2 of the Intel SDM: +# Figure 2-1 stepped through in the stock player, and exported twice. +# Built only when the PDF is there (-Dmanual). +frames 150 +expect deck.waiting true +expect deck.log.len 0 +screenshot .zig-cache/manual/page.png +# The page on its paper, the whole of it in view. +expect-pixel .zig-cache/manual/page.png 400 650 255 255 255 255 2 +# Onto the figure; the rest of the page greys. +key space +await deck.waiting true +screenshot .zig-cache/manual/figure.png +expect-pixel .zig-cache/manual/figure.png 460 160 255 255 255 255 2 +# Each field in turn, tinted: the third is ModR/M. +key space +await deck.waiting true +key space +await deck.waiting true +key space +await deck.waiting true +expect deck.log.len 4 +screenshot .zig-cache/manual/modrm.png +expect-pixel .zig-cache/manual/modrm.png 460 160 192 233 242 255 3 +expect-pixel .zig-cache/manual/modrm.png 300 160 255 255 255 255 2 +# Back a step: Opcode's tint again, ModR/M's gone. +key page_up +expect deck.log.len 3 +frames 2 +screenshot .zig-cache/manual/opcode.png +expect-pixel .zig-cache/manual/opcode.png 460 160 255 255 255 255 2 +expect-pixel .zig-cache/manual/opcode.png 300 160 192 233 242 255 3 +key space +await deck.waiting true +key space +await deck.waiting true +key space +await deck.waiting true +key space +await deck.waiting true +# 83 C0 01 written below, where the footnotes were. +key space +await deck.waiting true +screenshot .zig-cache/manual/bytes.png +# Into their fields: ModR/M's label gives way to C0. +key space +await deck.waiting true +screenshot .zig-cache/manual/flown.png +expect-different-screenshot .zig-cache/manual/bytes.png .zig-cache/manual/flown.png 440 140 180 90 +# C0 down into its boxes as bits, then split over Mod, Reg and R/M. +key space +await deck.waiting true +screenshot .zig-cache/manual/bits.png +expect-pixel .zig-cache/manual/bits.png 527 185 255 255 255 255 2 +key space +await deck.waiting true +screenshot .zig-cache/manual/split.png +expect-different-screenshot .zig-cache/manual/bits.png .zig-cache/manual/split.png 280 420 310 70 +expect deck.log.len 11 +# Back to the page, filled in, and the end of the talk. +key space +frames 120 +expect deck.log.len 12 +expect deck.waiting false +screenshot .zig-cache/manual/end.png +expect-different-screenshot .zig-cache/manual/page.png .zig-cache/manual/end.png 470 260 340 120 +# Exported ({a}, {b}: 10 fps, half size), each step held 1.5 s: the same +# frames twice, and the talk moves through them. +expect-same-screenshot {a}/000040.png {b}/000040.png +expect-same-screenshot {a}/000200.png {b}/000200.png +expect-same-screenshot {a}/000340.png {b}/000340.png +expect-different-screenshot {a}/000040.png {a}/000200.png +expect-different-screenshot {a}/000200.png {a}/000340.png diff --git a/tools/bench.zig b/tools/bench.zig index faa769e..5412866 100644 --- a/tools/bench.zig +++ b/tools/bench.zig @@ -1,17 +1,29 @@ //! How long a frame of vector graphics takes, per stage, in release mode: //! parsing the SVG, turning it into polygons and coverage (CPU backend), or //! into a GPU pass description (GPU backend; the GPU's own time is not -//! measured here). +//! measured here). The objects: the compiled test scene's, and the manual +//! example's page of the Intel SDM (when the build has the PDF), thousands +//! of shapes, with a budget of its own. const std = @import("std"); const vector = @import("vector"); const scene = @import("scene").scene; const typst = @import("typst"); +const manual = @import("manual").scene; +const manual_typst = @import("manual_typst"); const width = 1280; const height = 720; const runs = 300; /// Drawings up to this many shapes count as simple: they must take < 1ms. const simple_shapes = 30; +/// Drawings of more count as a page (Figure 2-1's page of the SDM is 1954 +/// shapes; measured on a loaded 16-core machine: parse 6-12 ms, CPU draw +/// 2-5 ms, GPU record 0.85-1.7 ms). Parsing is once per object, drawing +/// every frame. +const page_shapes = 1000; +const page_parse_ms = 25; +const page_cpu_ms = 10; +const page_gpu_ms = 4; /// Stand-in for `sketch.Host`: the renderers only need images (and to free /// the GPU backend's paint buffer, which this bench never makes). @@ -34,48 +46,59 @@ pub fn main(init: std.process.Init) !void { defer objects_arena.deinit(); const shot = try scene.shot(objects_arena.allocator(), .{ .t = 0 }); for (shot.objects, 0..) |object, index| if (object.source == .typst) { - const svg = typst.find(object.source.typst).?; - var arena: std.heap.ArenaAllocator = .init(gpa); - defer arena.deinit(); - var cpu: vector.Renderer(.cpu) = try .init(gpa, Host{}, width, height); - defer cpu.deinit(Host{}); - var gpu: vector.Renderer(.gpu) = try .init(gpa, Host{}, width, height); - defer gpu.deinit(Host{}); - const Frame = struct { scratch: std.mem.Allocator }; - - var parse_ns: [runs]u64 = undefined; - var cpu_ns: [runs]u64 = undefined; - var gpu_ns: [runs]u64 = undefined; - var shapes: usize = 0; - for (0..runs) |i| { - _ = arena.reset(.retain_capacity); - const t0 = now(io); - const d = try vector.svg.parse(arena.allocator(), svg); - const t1 = now(io); - // Fit to the canvas, as large as it goes: the worst case. - const m = vector.fit(d, .{ .w = width, .h = height }); - cpu.begin(Frame{ .scratch = arena.allocator() }, .{ 0, 0, 0, 1 }); - try cpu.draw(d, m, 1); - const t2 = now(io); - gpu.begin(Frame{ .scratch = arena.allocator() }, .{ 0, 0, 0, 1 }); - try gpu.draw(d, m, 1); - std.mem.doNotOptimizeAway(gpu.target.pass()); - const t3 = now(io); - parse_ns[i] = t1 - t0; - cpu_ns[i] = t2 - t1; - gpu_ns[i] = t3 - t2; - shapes = d.shapes.len; - } - const p = median(&parse_ns); - const c = median(&cpu_ns); - const g = median(&gpu_ns); - std.debug.print("{d:>2} {s:<21} {d:>7} {d:>8.3}ms {d:>8.3}ms {d:>8.3}ms {d:>8.3}ms\n", .{ index, label(object.source.typst), shapes, ms(p), ms(c), ms(g), ms(p + c) }); - if (shapes <= simple_shapes and (p + c > std.time.ns_per_ms or p + g > std.time.ns_per_ms)) failed = true; + if (try bench(gpa, io, index, object.source.typst, typst.find(object.source.typst).?)) failed = true; + }; + // The manual's page of the SDM, when the build has the PDF. + for (manual.typst_sources, 0..) |source, index| if (std.mem.startsWith(u8, source, "#image(")) { + if (try bench(gpa, io, index, source, manual_typst.find(source).?)) failed = true; }; - std.debug.print("\nup to {d} shapes must parse and draw in under 1ms at {d}x{d}, filling the canvas.\n", .{ simple_shapes, width, height }); + std.debug.print("\nup to {d} shapes must parse and draw in under 1ms at {d}x{d}, filling the canvas;\n", .{ simple_shapes, width, height }); + std.debug.print("a page (over {d}) parse in under {d}ms, draw on the CPU in {d}ms and record for the GPU in {d}ms.\n", .{ page_shapes, page_parse_ms, page_cpu_ms, page_gpu_ms }); if (failed) return error.TooSlow; } +/// Times one SVG, prints its line, and says whether it is over budget. +fn bench(gpa: std.mem.Allocator, io: std.Io, index: usize, source: []const u8, svg: []const u8) !bool { + var arena: std.heap.ArenaAllocator = .init(gpa); + defer arena.deinit(); + var cpu: vector.Renderer(.cpu) = try .init(gpa, Host{}, width, height); + defer cpu.deinit(Host{}); + var gpu: vector.Renderer(.gpu) = try .init(gpa, Host{}, width, height); + defer gpu.deinit(Host{}); + const Frame = struct { scratch: std.mem.Allocator }; + + var parse_ns: [runs]u64 = undefined; + var cpu_ns: [runs]u64 = undefined; + var gpu_ns: [runs]u64 = undefined; + var shapes: usize = 0; + for (0..runs) |i| { + _ = arena.reset(.retain_capacity); + const t0 = now(io); + const d = try vector.svg.parse(arena.allocator(), svg); + const t1 = now(io); + // Fit to the canvas, as large as it goes: the worst case. + const m = vector.fit(d, .{ .w = width, .h = height }); + cpu.begin(Frame{ .scratch = arena.allocator() }, .{ 0, 0, 0, 1 }); + try cpu.draw(d, m, 1); + const t2 = now(io); + gpu.begin(Frame{ .scratch = arena.allocator() }, .{ 0, 0, 0, 1 }); + try gpu.draw(d, m, 1); + std.mem.doNotOptimizeAway(gpu.target.pass()); + const t3 = now(io); + parse_ns[i] = t1 - t0; + cpu_ns[i] = t2 - t1; + gpu_ns[i] = t3 - t2; + shapes = d.shapes.len; + } + const p = median(&parse_ns); + const c = median(&cpu_ns); + const g = median(&gpu_ns); + std.debug.print("{d:>2} {s:<21} {d:>7} {d:>8.3}ms {d:>8.3}ms {d:>8.3}ms {d:>8.3}ms\n", .{ index, label(source), shapes, ms(p), ms(c), ms(g), ms(p + c) }); + if (shapes <= simple_shapes) return p + c > std.time.ns_per_ms or p + g > std.time.ns_per_ms; + if (shapes > page_shapes) return p > page_parse_ms * std.time.ns_per_ms or c > page_cpu_ms * std.time.ns_per_ms or g > page_gpu_ms * std.time.ns_per_ms; + return false; +} + /// The start of a Typst source's first line. fn label(source: []const u8) []const u8 { const line = source[0 .. std.mem.indexOfScalar(u8, source, '\n') orelse source.len]; -- cgit v1.3 From 562b503d5007e3afe1de426fc1175eadfbbb45c4 Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Tue, 17 Nov 2026 01:01:34 -0300 Subject: audio: a GPU buffer streamed within the frame, at a lead the host measures A compute shader's output was heard only after the sketch read it back (f.download, a frame later) and pushed it behind a lead of its own choosing; spheres kept 100 ms, and a change it made left for the device 96 ms later on average (measured, dummy driver, 60 Hz). f.audioBuffer(key, buffer, .{ .count, .offset }) streams `count` f32 a shader wrote: the host copies them back while it runs the frame's commands, waiting on the copy's fence (Executor.read: 0.2 ms on average here, 2 ms at the 99th percentile on a loaded machine), and queues them on the stream, so nothing is in flight between frames and the sketch keeps no books. Input.lead says how far ahead to make sound: the slowest of the last 64 frames' worth of samples (timed between the ends of the frames' commands, where the pushes are), plus the device's pull (what SDL takes from a stream at once, read from the device: 1024 here), plus half a pull for each underrun, a sample less each frame after; capped at 8192. A sketch pushes `in.lead -| in.stream(key).queued` a frame, and its change leaves after about what is queued ahead of it, a pull: 19 to 27 ms on average with SDL's 1024-sample pulls, 6.3 to 6.5 ms with 256 (SDL_AUDIO_DEVICE_SAMPLE_FRAMES; 17 under heavy load). Stream.underruns counts the pushes that found a stream empty though the frame before had fed it (a gap). The voices keep their 2048 samples: mixed to the lead, a one-shot longer than it is mixed over several frames, and voices.script's expect-audio and expect-no-audio, which look one frame at a time, failed. On the web, audio.buffer reads the buffer back with mapAsync and queues it on arrival, in order, counting it as queued meanwhile; in.lead stays at 100 ms there. The measurements (a probe patched into the host for the purpose, kept out of the tree) are in the 02-pardes-code scratch, .scratch/sketch/gpusynth. Tests: the lead's arithmetic (audio.zig, in test-audio's filter); spheres' play script checks its stream is fed. zig build test: 164/164 steps, 49/49 tests run (the rest cached); zig build test-audio: 48/48 steps, with the voices sketch's wasm, so web.zig compiles; voices.script passes four runs in four. web/host.js: node --check only, no browser run. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_016Y9MNBECMWcJD5pdS4SR6T --- README.md | 39 +++++++++++++++++++---- src/abi.zig | 14 +++++++++ src/gpu/Executor.zig | 26 +++++++++++++++ src/host/Host.zig | 5 +++ src/host/audio.zig | 89 ++++++++++++++++++++++++++++++++++++++++++++++++---- src/sketch/root.zig | 7 +++++ src/sketch/web.zig | 6 ++++ web/host.js | 22 +++++++++++-- 8 files changed, 193 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 8cf2998..73f0311 100644 --- a/README.md +++ b/README.md @@ -125,7 +125,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`, `env`, `log`, `textSize`). Commands may be built @@ -174,7 +174,8 @@ Store holds, say). `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 @@ -449,8 +450,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 @@ -1109,8 +1133,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 diff --git a/src/abi.zig b/src/abi.zig index 35c399b..271c6dc 100644 --- a/src/abi.zig +++ b/src/abi.zig @@ -165,6 +165,9 @@ pub const Stream = struct { queued: u32 = 0, /// Samples pushed since the stream was last cleared. pushed: u64 = 0, + /// Pushes that found it empty though the frame before had pushed to + /// it: each a gap in its sound. + underruns: u32 = 0, }; /// Everything a sketch learns about the world for one call. @@ -218,6 +221,11 @@ pub const Input = struct { keys: std.StaticBitSet(256) = .empty, streams: []const Stream = &.{}, sample_rate: u32 = 48_000, + /// How many samples a stream should hold after this frame's push, as + /// the host measures it: enough to outlast the slowest recent frame and + /// the device's next pull, and more after an underrun. A sketch that + /// makes its sound as it goes pushes `lead -| stream(key).queued`. + lead: u32 = 4800, /// Mono samples at `sample_rate` recorded since the previous frame, while /// `draw` declares `Command.microphone`. Only `draw` sees them: they come /// from a device, not from events, so they do not replay. @@ -377,6 +385,12 @@ pub const Command = union(enum) { voice: Voice, /// Mono samples at `Input.sample_rate` for stream `key`. audio: struct { key: u32, samples: []const f32, clear: bool = false }, + /// `count` mono samples (f32) that a compute shader left in `buffer` + /// at `offset`, for stream `key`: queued like `audio`'s once the GPU + /// has made them. Natively that is within this frame (the host waits + /// for the GPU's work so far); on the web they arrive a frame or two + /// later and count as queued meanwhile. + audio_buffer: struct { key: u32, buffer: Buffer, offset: u32 = 0, count: u32 }, /// The gain of a group of voices (`Voice.group`) this frame; a group /// not given one plays at 1. Declared like a voice, so it replays. gain: struct { group: u3, gain: f32 }, diff --git a/src/gpu/Executor.zig b/src/gpu/Executor.zig index 460b2d5..797dcbf 100644 --- a/src/gpu/Executor.zig +++ b/src/gpu/Executor.zig @@ -503,6 +503,32 @@ pub fn download(g: *Gpu, d: @FieldType(abi.Command, "download")) !void { }; } +/// Copies `out.len` bytes of a buffer from `offset` back now, waiting for +/// the GPU to finish the work submitted before (sound that must be queued +/// this frame). +pub fn read(g: *Gpu, buffer: abi.Buffer, offset: u32, out: []u8) !void { + const source = g.storage(buffer) orelse return error.UnknownBuffer; + const size: u32 = @intCast(out.len); + if (size == 0 or @as(u64, offset) + size > source.size) return error.DownloadOutOfBounds; + const transfer = for (g.spare.items, 0..) |t, i| { + if (t.size >= size) break g.spare.swapRemove(i); + } else Transfer{ + .buffer = c.SDL_CreateGPUTransferBuffer(g.device, &.{ .usage = c.SDL_GPU_TRANSFERBUFFERUSAGE_DOWNLOAD, .size = size, .props = 0 }) orelse return error.GpuBuffer, + .size = size, + }; + defer g.spare.append(g.gpa, transfer) catch c.SDL_ReleaseGPUTransferBuffer(g.device, transfer.buffer); + const cmd = c.SDL_AcquireGPUCommandBuffer(g.device) orelse return error.GpuCommandBuffer; + const copy = c.SDL_BeginGPUCopyPass(cmd); + c.SDL_DownloadFromGPUBuffer(copy, &.{ .buffer = source.buffer, .offset = offset, .size = size }, &.{ .transfer_buffer = transfer.buffer, .offset = 0 }); + c.SDL_EndGPUCopyPass(copy); + const fence = c.SDL_SubmitGPUCommandBufferAndAcquireFence(cmd) orelse return error.GpuSubmit; + defer c.SDL_ReleaseGPUFence(g.device, fence); + if (!c.SDL_WaitForGPUFences(g.device, true, &fence, 1)) return error.GpuFence; + const mapped: [*]const u8 = @ptrCast(c.SDL_MapGPUTransferBuffer(g.device, transfer.buffer, false) orelse return error.GpuMap); + defer c.SDL_UnmapGPUTransferBuffer(g.device, transfer.buffer); + @memcpy(out, mapped[0..size]); +} + /// The downloads the GPU has finished, copied into `arena`, in the order /// they were asked for. pub fn collect(g: *Gpu, arena: std.mem.Allocator) ![]const abi.Download { diff --git a/src/host/Host.zig b/src/host/Host.zig index 4f1214a..dc21cc0 100644 --- a/src/host/Host.zig +++ b/src/host/Host.zig @@ -478,6 +478,7 @@ fn draw(self: *Host, now: u64, started: u64) !u64 { } } self.input.streams = self.audio.streamStatus(); + self.input.lead = self.audio.lead; self.input.sample_rate = sound.sample_rate; self.input.microphone = self.audio.record(arena); self.input.downloads = if (self.passes) |*g| try g.collect(arena) else &.{}; @@ -505,6 +506,10 @@ fn draw(self: *Host, now: u64, started: u64) !u64 { .voice => |voice| self.audio.declare(voice), .gain => |g| self.audio.gains[g.group] = g.gain, .audio => |a| self.audio.push(a.key, a.samples, a.clear), + .audio_buffer => |a| if (self.passes) |*g| if (a.count > 0) { + const samples = try arena.alloc(f32, a.count); + if (g.read(a.buffer, a.offset, std.mem.sliceAsBytes(samples))) self.audio.push(a.key, samples, false) else |err| self.print("gpu audio: {t} ({s})", .{ err, c.SDL_GetError() }); + }, .quit => self.quit = true, .gpu => |pass| if (self.passes) |*g| self.runGpu(g, pass) catch |err| self.print("gpu pass: {t} ({s})", .{ err, c.SDL_GetError() }), .post_process => |p| if (self.passes) |*g| self.runPostProcess(g, p.source, p.target, p.effect) catch |err| self.print("gpu postprocess: {t} ({s})", .{ err, c.SDL_GetError() }), diff --git a/src/host/audio.zig b/src/host/audio.zig index bf5fdc4..e95e38e 100644 --- a/src/host/audio.zig +++ b/src/host/audio.zig @@ -28,6 +28,19 @@ pub const Audio = struct { heard_gains: [8]f32 = @splat(1), streams: std.ArrayList(Stream) = .empty, status: std.ArrayList(abi.Stream) = .empty, + /// Samples the device takes from each stream at once. + pull: u32 = 1024, + /// The wall-clock time (ns) between the ends of the last frames' + /// commands, where pushes are done; and when the last ended. + intervals: [64]u64 = @splat(0), + frame: u64 = 0, + last_frame: u64 = 0, + /// Grown by underruns, shrinking back while there are none. + margin: u32 = 0, + /// A stream ran dry since the lead was last worked out. + dry: bool = false, + /// `Input.lead`: see `lead`. + lead: u32 = 4800, scope: Scope = .{}, /// The default recording device, bound to this stream while declared. microphone: ?*c.SDL_AudioStream = null, @@ -44,12 +57,25 @@ pub const Audio = struct { /// Mixed since a script last asked (`expect-audio`). sounded: bool = false, }; - const Stream = struct { key: u32, out: *c.SDL_AudioStream, pushed: u64 = 0 }; + const Stream = struct { + key: u32, + out: *c.SDL_AudioStream, + pushed: u64 = 0, + /// Pushed to this frame, and the last. + fed: bool = false, + was_fed: bool = false, + underruns: u32 = 0, + }; pub fn open(self: *Audio) !void { const device = c.SDL_OpenAudioDevice(c.SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK, &spec); if (device == 0) return error.OpenAudio; self.device = device; + var format: c.SDL_AudioSpec = undefined; + var frames: c_int = 0; + if (c.SDL_GetAudioDeviceFormat(device, &format, &frames) and frames > 0 and format.freq > 0) { + self.pull = @intCast(@divFloor(@as(i64, frames) * sample_rate + format.freq - 1, format.freq)); + } self.voices_out = try self.bind(); self.scope.attach(device) catch {}; } @@ -176,9 +202,18 @@ pub const Audio = struct { if (clear) { _ = c.SDL_ClearAudioStream(s.out); s.pushed = 0; + s.was_fed = false; } if (samples.len == 0) return; + // Fed last frame and empty now: the device came up short since + // (counted at the push, as a pull before it would hide it by the + // next frame). + if (s.was_fed and !s.fed and c.SDL_GetAudioStreamQueued(s.out) == 0) { + s.underruns += 1; + self.dry = true; + } if (c.SDL_PutAudioStreamData(s.out, samples.ptr, @intCast(samples.len * @sizeOf(f32)))) s.pushed += samples.len; + s.fed = true; } fn streamFor(self: *Audio, key: u32) ?*Stream { @@ -192,14 +227,22 @@ pub const Audio = struct { return &self.streams.items[self.streams.items.len - 1]; } - /// Drops undeclared voices, keeps the voice mix queued ahead, and opens - /// or closes the microphone. + /// Drops undeclared voices, works out the lead for the next frame, keeps + /// the voice mix queued ahead, and opens or closes the microphone. pub fn endFrame(self: *Audio) void { self.reconcileMicrophone(); var i: usize = 0; while (i < self.voices.items.len) { if (self.voices.items[i].seen) i += 1 else _ = self.voices.swapRemove(i); } + const now = c.SDL_GetTicksNS(); + if (self.last_frame != 0) { + self.intervals[self.frame % self.intervals.len] = now -| self.last_frame; + self.frame += 1; + } + self.last_frame = now; + self.lead = lead(self.intervals, self.pull, &self.margin, self.dry); + self.dry = false; const out = self.voices_out orelse return; const queued = c.SDL_GetAudioStreamQueued(out); if (queued < 0) return; @@ -257,16 +300,33 @@ pub const Audio = struct { return false; } + /// The streams as a frame starts. pub fn streamStatus(self: *Audio) []const abi.Stream { self.status.clearRetainingCapacity(); - for (self.streams.items) |s| { - const queued = c.SDL_GetAudioStreamQueued(s.out); - self.status.append(self.gpa, .{ .key = s.key, .queued = @intCast(@divFloor(@max(queued, 0), @sizeOf(f32))), .pushed = s.pushed }) catch {}; + for (self.streams.items) |*s| { + const queued: u32 = @intCast(@divFloor(@max(c.SDL_GetAudioStreamQueued(s.out), 0), @sizeOf(f32))); + s.was_fed = s.fed; + s.fed = false; + self.status.append(self.gpa, .{ .key = s.key, .queued = queued, .pushed = s.pushed, .underruns = s.underruns }) catch {}; } return self.status.items; } }; +/// How many samples to keep queued: the slowest of the last frames' worth +/// (pushes come once a frame, `intervals` apart), plus the device's pull +/// (it takes that much at once), plus `margin`: half a pull more at each +/// underrun (`dry`), back down by a sample a frame. +fn lead(intervals: [64]u64, pull: u32, margin: *u32, dry: bool) u32 { + var slowest: u64 = 0; + for (intervals) |ns| slowest = @max(slowest, ns); + margin.* = if (dry) @min(margin.* + pull / 2, max_lead) else margin.* -| 1; + const frame: u32 = @intCast(@min(slowest * sample_rate / std.time.ns_per_s, 1 << 20)); + return @min(frame + pull + margin.*, max_lead); +} +/// 170 ms: a frame slower than that is a stall, not a pace. +const max_lead = 8192; + /// Where the voice mix stops being passed through: -2.5 dBFS. Quieter /// mixes keep their true volume to the bit; a clip normalised to full scale /// only has its peaks bent (1 comes out at 0.875). @@ -462,3 +522,20 @@ test "voices at another rate are resampled linearly, and a group's gain scales i try std.testing.expect(out[0] > 0.375 and out[0] < 0.38); try std.testing.expectEqual(@as(f32, 0.5), out[1023]); } + +test "the lead the mixer gives streams outlasts the slowest recent frame and the device's pull, more after an underrun" { + const expectEqual = std.testing.expectEqual; + var intervals: [64]u64 = @splat(20 * std.time.ns_per_ms); + var margin: u32 = 0; + // 50 Hz and a pull of 1024: a frame's 960 samples and the pull. + try expectEqual(@as(u32, 960 + 1024), lead(intervals, 1024, &margin, false)); + // One 50 ms frame in the window sets it. + intervals[5] = 50 * std.time.ns_per_ms; + try expectEqual(@as(u32, 2400 + 1024), lead(intervals, 1024, &margin, false)); + // An underrun adds half a pull, which goes a sample a frame. + try expectEqual(@as(u32, 2400 + 1024 + 512), lead(intervals, 1024, &margin, true)); + try expectEqual(@as(u32, 2400 + 1024 + 511), lead(intervals, 1024, &margin, false)); + // A stall is not a pace: the lead stops at 170 ms. + intervals[6] = std.time.ns_per_s; + try expectEqual(@as(u32, max_lead), lead(intervals, 1024, &margin, false)); +} diff --git a/src/sketch/root.zig b/src/sketch/root.zig index d15046d..0ab04a7 100644 --- a/src/sketch/root.zig +++ b/src/sketch/root.zig @@ -219,6 +219,13 @@ pub const Frame = struct { pub fn audio(f: *Frame, key: u32, samples: []const f32, options: struct { clear: bool = false }) void { f.emit(.{ .audio = .{ .key = key, .samples = samples, .clear = options.clear } }); } + /// Streams `count` samples a compute shader wrote to `buffer` (f32 from + /// `offset`) on stream `key`, as `audio` streams samples: a GPU synth's + /// output, heard without a readback of the sketch's own. Make + /// `in.lead -| in.stream(key).queued` of them a frame. + pub fn audioBuffer(f: *Frame, key: u32, buffer: abi.Buffer, options: struct { offset: u32 = 0, count: u32 }) void { + f.emit(.{ .audio_buffer = .{ .key = key, .buffer = buffer, .offset = options.offset, .count = options.count } }); + } pub fn pixels(f: *Frame, img: Image, w: u32, h: u32, rgba: []const u8, options: struct { premultiplied: bool = false }) void { f.emit(.{ .pixels = .{ .image = img, .w = w, .h = h, .rgba = rgba, .premultiplied = options.premultiplied } }); } diff --git a/src/sketch/web.zig b/src/sketch/web.zig index 62a173a..a035117 100644 --- a/src/sketch/web.zig +++ b/src/sketch/web.zig @@ -48,6 +48,8 @@ const js = struct { extern "gpu" fn download(id: u32, offset: u32, size: u32, key: u32) void; extern "audio" fn rate() u32; extern "audio" fn push(key: u32, ptr: [*]const f32, len: usize, clear: u32) void; + /// `count` samples from a GPU buffer, queued on arrival. + extern "audio" fn buffer(key: u32, id: u32, offset: u32, count: u32) void; extern "audio" fn queued(key: u32) u32; /// Keeps the microphone open; it answers through `sk_microphone`. extern "audio" fn listen() void; @@ -225,6 +227,10 @@ fn Driver(comptime App: type) type { s.pushed += v.samples.len; js.push(v.key, v.samples.ptr, v.samples.len, @intFromBool(v.clear)); }, + .audio_buffer => |v| { + stream(v.key).pushed += v.count; + js.buffer(v.key, @backingInt(v.buffer), v.offset, v.count); + }, .microphone => js.listen(), .upload => |v| _ = js.write(@backingInt(v.buffer), v.offset, v.bytes.ptr, v.bytes.len), .compute => |v| { diff --git a/web/host.js b/web/host.js index efc335d..32bdbfb 100644 --- a/web/host.js +++ b/web/host.js @@ -314,13 +314,16 @@ const gpu = { // Reads a buffer back; it reaches the sketch before a later frame. arrived: [], download(id, offset, size, key) { + gpu.read(id, offset, size, bytes => gpu.arrived.push({key, bytes})); + }, + read(id, offset, size, then) { const staging = gpu.spare.find(b => b.size >= size) ?? gpu.device.createBuffer({size: Math.max(size, 256), usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST}); gpu.spare = gpu.spare.filter(b => b !== staging); const commands = gpu.device.createCommandEncoder(); commands.copyBufferToBuffer(gpu.buffers[id], offset, staging, 0, size); gpu.device.queue.submit([commands.finish()]); staging.mapAsync(GPUMapMode.READ, 0, size).then(() => { - gpu.arrived.push({key, bytes: new Uint8Array(staging.getMappedRange(0, size)).slice()}); + then(new Uint8Array(staging.getMappedRange(0, size)).slice()); staging.unmap(); gpu.spare.push(staging); }, () => {}); @@ -392,7 +395,8 @@ const sound = { } }, queue(key) { - if (!sound.queues.has(key)) sound.queues.set(key, {chunks: [], at: 0, queued: 0}); + // `waiting`: GPU buffers on their way, in order (counted as queued). + if (!sound.queues.has(key)) sound.queues.set(key, {chunks: [], waiting: [], at: 0, queued: 0}); return sound.queues.get(key); }, listen() { @@ -660,9 +664,21 @@ const imports = { push(key, ptr, len, clear) { if (len) sound.hint(); const q = sound.queue(key); - if (clear) { q.chunks = []; q.at = 0; q.queued = 0; } + if (clear) { q.chunks = []; q.waiting = []; q.at = 0; q.queued = 0; } if (len) { q.chunks.push(new Float32Array(wasm.memory.buffer.slice(ptr, ptr + len * 4))); q.queued += len; } }, + buffer(key, id, offset, count) { + if (!gpu.buffers[id]) return; + sound.hint(); + const q = sound.queue(key); + const chunk = {samples: null}; + q.waiting.push(chunk); + q.queued += count; + gpu.read(id, offset, count * 4, bytes => { + chunk.samples = new Float32Array(bytes.buffer); + while (q.waiting.length && q.waiting[0].samples) q.chunks.push(q.waiting.shift().samples); + }); + }, queued: key => sound.queues.get(key)?.queued ?? 0, listen: () => sound.listen(), }, -- cgit v1.3 From f555cf75c08ed84c90ebf366a0edea4479bf8f1c Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Tue, 17 Nov 2026 01:19:32 -0300 Subject: README: PDF pages and parts, in the Animation section A paragraph on a PDF page as a Typst object: the absolute path Typst's root / allows, and that the cache does not see the file change; text as outlines; the order write follows; what a page costs, measured on Figure 2-1's page (parse once 6-12 ms, 0.9-1.7 ms a frame to record for the GPU, 0.4 ms on it, 2-5 ms on the CPU renderer), a table of contents five times that, and the bench's page budget. One on part: the rectangle (centre and size in the object's units, the literal s.rect takes), how to pick it (the guides, or pdftotext -bbox and the points to units sum), where the part stands and when it shows, the rest drawn by the object, a shape to the first part, rules crossing fields, and transformInto into the whole target so a morph can be split. One on examples/manual.zig, -Dmanual and what happens without the PDF. The examples list names it, and the objects list names part. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_016Y9MNBECMWcJD5pdS4SR6T --- README.md | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 52 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 8cf2998..bf2aacb 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; @@ -523,8 +524,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 @@ -567,6 +568,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` -- cgit v1.3 From 8e8110e357b22bbbc2d1e566f24d2e33e6ecb0fe Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Tue, 17 Nov 2026 01:01:34 -0300 Subject: spheres: its sound streamed from the GPU's block, at the host's lead The synth block goes to the speakers with f.audioBuffer, made to keep in.lead queued; in_flight, discard and lead_seconds are gone, and a chord's jump is the stream's clear alone (nothing is on its way back to drop). The block is still read back, a frame later, for the scope. The sound is the same: with the block fixed at 800 samples a frame, the play script and a script that plays every chord key (seven jumps) push the same samples before and after, to the bit (849600 and 1164007 of them), the new one a frame sooner. A change leaves for the device in 19 to 27 ms on average (three one-minute runs on a loaded machine) instead of 96 (dummy driver, 60 Hz, SDL's 1024-sample pulls). The empty Store declaration the brief mentioned is not in this sketch (main.zig says "No Store"); nothing was touched there. Tests: zig build test, 75/75 steps, 3/3 tests (its play script now also expects the stream fed). Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_016Y9MNBECMWcJD5pdS4SR6T --- examples/spheres/README.md | 10 ++++++---- examples/spheres/src/main.zig | 31 +++++++++---------------------- examples/spheres/test/play.script | 2 ++ 3 files changed, 17 insertions(+), 26 deletions(-) diff --git a/examples/spheres/README.md b/examples/spheres/README.md index 3c65666..30023de 100644 --- a/examples/spheres/README.md +++ b/examples/spheres/README.md @@ -17,10 +17,12 @@ Everything moves on the GPU: | `sprite.*`, `trail.*`, `fade.frag` | The sky: the cloud as layered dust on a long exposure, system 0's bodies as glows, and their trails as ribbons tapering with age. | | `link.*` | The coupling: a ribbon from modulator to carrier, as bright as the coupling, with pulses flowing along it. | -The sound reaches the speakers by a readback (`f.download`) about two -frames later; the CPU only queues it, and hands it to sketchbook's `scope` -module (the views micscope uses) for the oscilloscope, spectrum and -spectrogram. +The sound goes from the GPU's block straight to the speakers +(`f.audioBuffer`): the host reads it back in the same frame and keeps the +lead it measures queued (`in.lead`), so a change is heard in about two +device pulls rather than 100 ms. A second readback (`f.download`), a frame +later, hands it to sketchbook's `scope` module (the views micscope uses) +for the oscilloscope, spectrum and spectrogram. ## From motion to sound diff --git a/examples/spheres/src/main.zig b/examples/spheres/src/main.zig index 60b498f..062aebd 100644 --- a/examples/spheres/src/main.zig +++ b/examples/spheres/src/main.zig @@ -27,8 +27,6 @@ pub const height = 800; /// The audio stream's key. const stream = 1; -/// How much sound is kept queued ahead: synthesised, read back, queued. -const lead_seconds = 0.1; /// Systems integrated: system 0 and its cloud. const systems = layouts.max_systems; /// How far apart the copies start. @@ -87,8 +85,6 @@ const Travel = struct { to: chords.Pick, speed: f64 }; pub const Session = struct { reset: sk.Handled = .{}, started: bool = false, - /// Synthesised samples not back from the GPU yet. - in_flight: usize = 0, /// System 0 as last read back, and whether it has been. lead: layouts.Lead = std.mem.zeroes(layouts.Lead), have_lead: bool = false, @@ -113,8 +109,6 @@ pub const Session = struct { travel: ?Travel = null, /// The snapshot whose chord is held. held: ?chords.Pick = null, - /// Samples still to come back from before a chord was chosen, dropped. - discard: usize = 0, gpu: Gpu = .{}, }; @@ -418,18 +412,13 @@ pub fn draw(s: *const State, ss: *Session, f: *sk.Frame) void { const g = &ss.gpu; setup(g, f); - // What came back: sound for the speakers and the scope, and system 0. + // What came back: the sound, for the scope, and system 0. for (in.downloads) |d| switch (@as(Readback, @enumFromInt(d.key))) { .audio => { const samples = std.mem.bytesAsSlice(f32, d.bytes[0 .. d.bytes.len / 4 * 4]); const aligned = f.scratch.alloc(f32, samples.len) catch continue; for (aligned, samples) |*to, from| to.* = from; - ss.in_flight -|= aligned.len; - // Sound made before a chord was chosen is not played. - const dropped = @min(ss.discard, aligned.len); - ss.discard -= dropped; - f.audio(stream, aligned[dropped..], .{}); - ss.scope.push(aligned[dropped..]); + ss.scope.push(aligned); }, .lead => if (d.bytes.len >= @sizeOf(layouts.Lead)) { ss.lead = std.mem.bytesToValue(layouts.Lead, d.bytes[0..@sizeOf(layouts.Lead)]); @@ -456,7 +445,6 @@ pub fn draw(s: *const State, ss: *Session, f: *sk.Frame) void { ss.held = pick; ss.travel = .{ .to = pick, .speed = @max(@abs(pick.time() - ss.time) / 1.2, 2) }; f.audio(stream, &.{}, .{ .clear = true }); - ss.discard = ss.in_flight; } }; @@ -517,13 +505,12 @@ pub fn draw(s: *const State, ss: *Session, f: *sk.Frame) void { ss.trail_filled = @min(ss.trail_filled + trail.points, layouts.trail); f.download(g.lead, .{ .size = @sizeOf(layouts.Lead), .key = @intFromEnum(Readback.lead) }); - // The sound: enough to keep `lead_seconds` queued, counting what is - // still on its way back from the GPU. - const queued = in.stream(stream).queued + ss.in_flight; - const want: usize = @min(@as(usize, @intFromFloat(lead_seconds * rate)) -| queued, layouts.max_block); + // The sound: as much as keeps the host's lead queued, streamed straight + // from the GPU's block; and read back for the scope. + const want: u32 = @min(in.lead -| in.stream(stream).queued, layouts.max_block); if (want > 0) { const params = gpu.uniform(f.scratch, layouts.SynthParams{ - .count = @intCast(want), + .count = want, .mode = @intFromEnum(s.mode), .rate = @floatCast(rate), // Loud enough for a phone's speaker; tanh rounds the peaks off. @@ -535,11 +522,11 @@ pub fn draw(s: *const State, ss: *Session, f: *sk.Frame) void { .readonly = &.{ g.voices, g.phases }, .readwrite = &.{g.block}, .uniforms = params, - .groups = .{ @intCast((want + 63) / 64), 1, 1 }, + .groups = .{ (want + 63) / 64, 1, 1 }, }); f.compute(.{ .label = "advance.comp", .kernel = advance_kernel, .readwrite = &.{ g.voices, g.phases }, .uniforms = params }); - f.download(g.block, .{ .size = @intCast(want * @sizeOf(f32)), .key = @intFromEnum(Readback.audio) }); - ss.in_flight += want; + f.audioBuffer(stream, g.block, .{ .count = want }); + f.download(g.block, .{ .size = want * @sizeOf(f32), .key = @intFromEnum(Readback.audio) }); } const l = Layout.of(in.width, in.height, s.instrument); diff --git a/examples/spheres/test/play.script b/examples/spheres/test/play.script index 1b06372..8dbe978 100644 --- a/examples/spheres/test/play.script +++ b/examples/spheres/test/play.script @@ -1,6 +1,8 @@ # Plays each preset and synthesis mode headless; screenshots land in # .zig-cache/spheres/ for review. frames 120 +# The GPU's blocks reach the speakers' stream. +expect-audio 1 expect running true expect preset figure_eight screenshot .zig-cache/spheres/figure-eight.png -- cgit v1.3