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 --- examples/manual.zig | 155 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 155 insertions(+) create mode 100644 examples/manual.zig (limited to 'examples') 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 }); +} -- 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(-) (limited to 'examples') 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