diff options
| author | Gabriel Schneider <[email protected]> | 2026-11-17 01:37:18 -0300 |
|---|---|---|
| committer | Gabriel Schneider <[email protected]> | 2026-11-17 12:15:01 -0300 |
| commit | 62d9f89eabf0a15c3d05d04f22d6b1810582be3f (patch) | |
| tree | 14c887c016324d2caf2e17238256eac213995d52 | |
| parent | f555cf75c08ed84c90ebf366a0edea4479bf8f1c (diff) | |
| download | sketchbook-62d9f89eabf0a15c3d05d04f22d6b1810582be3f.tar.gz sketchbook-62d9f89eabf0a15c3d05d04f22d6b1810582be3f.zip | |
examples: manual's second slide, ADD's row 80 /0 ib becomes SUB's 80 /5 ib
The manual example is a talk in two slides now: Figure 2-1 as before,
then, once it clears, page 132 of the SDM's Vol. 2 (ADD) fades in with
its opcode table taken out; the table is written back row by row (the
column rules drawn down, then each row with the rule above it); the
camera goes to 80 /0 ib ADD r/m8, imm8 as the rest greys; its opcode
cell is tinted; closer in, the 0 after the slash morphs into the 5 of
SUB's row from page 1400 while 80, / and ib hold still; then the rest of
the row follows (ADD into SUB, Add into Subtract, to into from, imm8 and
r/m8. sliding to their places) and the page around it becomes page
1400; at the end ADD's row comes back over SUB's, what differs is
marked, and a line says why (one opcode byte, the ModR/M reg field picks
the operation). Seven steps; the talk is 66 s exported.
The pages and rows are checked against the PDF (pdftotext): ADD is page
132, SUB page 1400, and the rows' word boxes and the page's own rule
shapes give the rectangles, in points, turned into the page's units by
one function. Page 1400 stands 20 units higher, so its row (182-197 pt)
lies on ADD's (167-182). The page draws a table's text row by row, left
to right, and its rules after all of its text, so a row part writes in
reading order. The column rules run the whole table, so their centres
all fall in one row (83 /0 ib, at 265 pt): a band a point high through
265 takes the seven of them first, and nothing else. Each row is cut in
the same eight pieces on both pages (the digit, the rest of the opcode,
the instruction, the three short columns, the description word by word)
and each piece morphs into its own: a morph pairs shapes by index, so
the whole row (44 shapes into 51) would send every glyph after Add
across the row.
test/manual.script goes on through slide 2 with pixel checks (the table
gone and back, the cell's tint, a step back to the exact picture before
the digit's morph, the marks at the end) and checks three more exported
frames of it, the same in both exports. The bench now times pages 132
and 1400 too (2118 and 2040 shapes: parse 10.0 and 10.3 ms, CPU draw
2.8, GPU record 1.2, in budget). The README's examples list and the
manual's paragraphs say so, and how a table's column rules are taken.
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_016Y9MNBECMWcJD5pdS4SR6T
| -rw-r--r-- | README.md | 22 | ||||
| -rw-r--r-- | examples/manual.zig | 171 | ||||
| -rw-r--r-- | test/manual.script | 70 |
3 files changed, 243 insertions, 20 deletions
@@ -32,7 +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). +- [`manual.zig`](examples/manual.zig): Figure 2-1 of the Intel SDM comes alive, then ADD's opcode table is written row by row and its `80 /0 ib` turns into SUB's `80 /5 ib`: PDF pages as vector shapes and parts of them (`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; @@ -576,7 +576,8 @@ 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 +SDM: header and footer, the text from the top, then the figures; a +table's text row by row, left to right, and its rules after all of it). 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 @@ -601,17 +602,24 @@ 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 +with whichever holds its centre: keep areas inside the rules. A table's +column rules run its whole height, so their centres all lie in one row: +take them first, with a band a point high through that centre. 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 +`examples/manual.zig` is a talk in two slides on the SDM (Vol. 2). On +Figure 2-1 (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. Then ADD's opcode table +(page 132) is written row by row; its row `80 /0 ib ADD r/m8, imm8`, +cut in pieces, becomes SUB's from page 1400, laid so that the rows +coincide: first the digit after the slash alone, then the rest, a morph +per piece, so the glyphs that stay hold still; the two rows end one over +the other. `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 diff --git a/examples/manual.zig b/examples/manual.zig index 8b11247..7a53533 100644 --- a/examples/manual.zig +++ b/examples/manual.zig @@ -1,15 +1,21 @@ -//! 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. +//! Two pages of the Intel SDM (Vol. 2) as a talk, in two slides. The +//! pages are Typst's import of the PDF, every glyph and rule a vector +//! shape; what moves are `part`s of them, 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). +//! +//! 1. Figure 2-1, the instruction format (page 31), comes alive: `83 C0 +//! 01`, `add eax, 1`, is written below, its bytes fly into their +//! fields, and C0 splits into its ModR/M bits. +//! 2. ADD's opcode table (page 132) is written row by row; its row `80 /0 +//! ib` becomes SUB's `80 /5 ib` (page 1400): the digit first, alone, +//! then the rest of the row, and the two rows end one over the other. //! //! 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 +//! ] / [ next / previous slide const std = @import("std"); const anim = @import("anim"); const pdf: ?[]const u8 = @import("manual").pdf; @@ -32,6 +38,11 @@ pub const typst = struct { 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]"; + pub const add_page = "#image(\"" ++ (pdf orelse "") ++ "\", page: 132)"; + pub const sub_page = "#image(\"" ++ (pdf orelse "") ++ "\", page: 1400)"; + pub const table_title = "#text(font: \"New Computer Modern\", size: 40pt, fill: rgb(\"#ece6e2\"))[ADD, then SUB]"; + pub const table_from = "#text(font: \"New Computer Modern\", size: 16pt, fill: rgb(\"#8c8c8c\"))[IntelĀ® 64 and IA-32 SDM, Vol. 2, pages 132 and 1400]"; + pub const group = "#text(font: \"New Computer Modern\", size: 11pt, fill: rgb(\"#555555\"))[One opcode byte, 80: the reg field of the ModR/M byte picks the operation]"; }; 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`]"; @@ -74,6 +85,16 @@ const footnotes: Area = .{ .x = -8, .y = 70.7, .w = 453, .h = 56 }; const char = 0.6 * 14 * 4.0 / 3.0; fn talk(s: *anim.Frame) void { + s.slide(); + instructionFormat(s); + s.pause(); + s.clear(.{ .seconds = 0.8 }); + s.slide(); + opcodeTable(s); +} + +/// Slide 1: Figure 2-1 comes alive. +fn instructionFormat(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, .{}); @@ -153,3 +174,139 @@ fn talk(s: *anim.Frame) void { // 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 }); } + +/// PDF points, a box from the top left of a 612 x 792 pt page, as an area +/// in the page's units. +fn onPage(x0: f32, y0: f32, x1: f32, y1: f32) Area { + return .{ .x = ((x0 + x1) / 2 - 306) * 4.0 / 3.0, .y = ((y0 + y1) / 2 - 396) * 4.0 / 3.0, .w = (x1 - x0) * 4.0 / 3.0, .h = (y1 - y0) * 4.0 / 3.0 }; +} + +/// ADD's opcode table on page 132, in points: the y of each of its +/// horizontal rules, from the top of the header row to the foot of the +/// last. The page draws the table's text row by row, left to right, and +/// its rules after all of its text; a row is taken with the rule above +/// it, so it is written with it. +const add_rules = [_]f32{ 82, 107, 122, 137, 152, 167, 182, 197, 212, 227, 253, 268, 283, 298, 313, 328, 343, 358, 373, 388, 403, 418, 433, 448 }; +/// The column rules run the table's whole height, so their centres all +/// lie in one row (`83 /0 ib`, at 265 pt) and would go with it: a band +/// one point high through 265 takes them first, and nothing else. +const column_rules = onPage(40, 264.5, 565, 265.5); +/// The row `80 /0 ib ADD r/m8, imm8`, between the rules at 167 and 182. +/// SUB's `80 /5 ib SUB r/m8, imm8` is a row lower on page 1400 (182 to +/// 197), so that page stands 15 pt (20 units) higher: the rows coincide. +const row = 5; +const sub_y = -20; +/// Each of the two rows in the same eight pieces, in points across (from +/// `pdftotext -bbox`): the digit after the slash (`0`, `5`; its glyph's +/// centre is at 67.5 in both), then the spans between these cuts: the +/// rest of the opcode (`80 /`, `ib`), the instruction, the three short +/// columns, and the description, word by word (`Add`, `imm8`, `to`, +/// `r/m8.`; `Subtract`, `imm8`, `from`, `r/m8.`). +const add_cuts = [_]f32{ 46.5, 144, 256, 376, 395, 418, 428.5, 557 }; +const sub_cuts = [_]f32{ 46.5, 144, 256, 376, 412.5, 436, 457, 557 }; +const digit = 0; +/// The pieces that morph with the row, and those that are the same glyphs +/// in the same places in both rows, and hold. +const follow = [_]usize{ 2, 4, 5, 6, 7 }; +const same = [_]usize{ 1, 3 }; +/// What differs, marked at the end, in points across: the digit, the +/// mnemonic, and two words of the description (ADD's, then SUB's). +const add_differs = [_][2]f32{ .{ 65.5, 70.5 }, .{ 146, 166 }, .{ 377, 395 }, .{ 418, 428.5 } }; +const sub_differs = [_][2]f32{ .{ 65.5, 70.5 }, .{ 146, 166 }, .{ 377, 412.5 }, .{ 436, 457 } }; +/// How far below ADD's row SUB's goes at the end, in units (a row is 20). +const gap = 30; + +/// Piece `i` of a row between `y0` and `y1` (points) cut at `cuts`. +fn piece(cuts: []const f32, i: usize, y0: f32, y1: f32) Area { + return if (i == digit) onPage(65.5, y0, 70.5, y1) else onPage(cuts[i - 1], y0, cuts[i], y1); +} + +/// Slide 2: ADD's opcode table, written row by row, and its row `80 /0 ib` +/// turned into SUB's `80 /5 ib`. +fn opcodeTable(s: *anim.Frame) void { + const paper = s.rect(.{ .w = 816, .h = 1056, .fill = 0xffffff }); + const add = s.typst(typst.add_page, .{}); + const sub = s.typst(typst.sub_page, .{ .y = sub_y }); + const title = s.typst(typst.table_title, .{ .x = -700, .y = -380 }); + const from = s.typst(typst.table_from, .{ .x = -700, .y = -325 }); + // Tints, laid before the parts so that they draw over them: the + // row's opcode cell, and what differs, over ADD's row and over SUB's + // where it ends. + const cell = onPage(46, 167, 144.6, 182); + const tint = s.rect(.{ .x = cell.x, .y = cell.y, .w = cell.w, .h = cell.h, .fill = 0x58c4dd60 }); + var marks: [add_differs.len + sub_differs.len]anim.Obj = undefined; + for (&marks, add_differs ++ sub_differs, 0..) |*m, d, i| { + const a = onPage(d[0], 167, d[1], 182); + const down: f32 = if (i < add_differs.len) 0 else gap; + m.* = s.rect(.{ .x = a.x, .y = a.y + down, .w = a.w, .h = a.h, .fill = 0xf7d96f80 }); + } + + // The table comes out of the page before it shows, to be written in: + // the column rules, then each row (the last with the rule under it + // too). And SUB's row out of its page, piece by piece. + const columns = s.part(add, column_rules); + var rows: [add_rules.len - 1]anim.Obj = undefined; + for (&rows, 0..) |*r, i| { + const foot = if (i == rows.len - 1) add_rules[i + 1] + 0.5 else add_rules[i + 1] - 0.5; + r.* = s.part(add, onPage(40, add_rules[i] - 0.5, 565, foot)); + } + var subs: [add_cuts.len]anim.Obj = undefined; + for (&subs, 0..) |*p, i| p.* = s.part(sub, piece(&sub_cuts, i, 182.5, 196.5)); + + s.play(.{anim.camera(.{ .zoom = 0.65, .x = 0, .y = 0 })}, .{ .seconds = 0 }); + s.play(.{ title.write(), from.fadeIn(), paper.fadeIn(), add.fadeIn() }, .{ .seconds = 2 }); + s.pause(); + + // The table, row by row. + s.play(.{columns.create()}, .{ .seconds = 0.6 }); + for (rows) |r| s.play(.{r.write()}, .{ .seconds = 0.25 }); + s.pause(); + + // Onto the row 80 /0 ib, cut in its pieces; the rest greys. + const at = onPage(40, add_rules[row] - 0.5, 565, add_rules[row + 1] - 0.5); + var adds: [add_cuts.len]anim.Obj = undefined; + for (&adds, 0..) |*p, i| { + const a = piece(&add_cuts, i, 167.5, 181.5); + p.* = s.part(rows[row], .{ .x = a.x - at.x, .y = a.y - at.y, .w = a.w, .h = a.h }); + } + var grey: [rows.len + 5]anim.Animation = undefined; + for (rows, 0..) |r, i| grey[i] = r.move(.{ .opacity = 0.25 }); + grey[rows.len..].* = .{ columns.move(.{ .opacity = 0.25 }), add.move(.{ .opacity = 0.25 }), title.fadeOut(), from.fadeOut(), anim.camera(.{ .zoom = 1.7, .x = at.x, .y = at.y }) }; + s.play(grey, .{ .seconds = 1.5 }); + s.pause(); + + // Its opcode cell, and the opcode in it: the digit and the rest. + s.play(.{ tint.fadeIn(), adds[digit].indicate(), adds[1].indicate() }, .{}); + s.pause(); + + // Close in (a little right of the cell, to stay on the paper): the + // digit after the slash, and only it, becomes SUB's. + s.play(.{anim.camera(.{ .zoom = 4, .x = cell.x + 40, .y = at.y })}, .{}); + s.play(.{adds[digit].transformInto(subs[digit])}, .{ .seconds = 1.5 }); + s.pause(); + + // The rest of the row follows, and the page around it is SUB's. + var swap: [rows.len + follow.len + 3]anim.Animation = undefined; + for (rows, 0..) |r, i| swap[i] = r.fadeOut(); + for (follow, 0..) |i, j| swap[rows.len + j] = adds[i].transformInto(subs[i]); + swap[rows.len + follow.len ..].* = .{ columns.fadeOut(), add.fadeOut(), anim.camera(.{ .zoom = 1.7, .x = at.x, .y = at.y }) }; + s.play(swap, .{ .seconds = 2 }); + s.play(.{ sub.fadeIn(), sub.move(.{ .opacity = 0.25 }) }, .{}); + s.pause(); + + // ADD's row again, and SUB's under it: the pieces that morphed come + // back, SUB's that held (the same glyphs as ADD's) come out from + // under them, what differs is marked, and why. + const group = s.typst(typst.group, .{ .x = at.x, .y = at.y + gap + 40 }); + const back = [_]usize{digit} ++ follow; + var both: [back.len + same.len + subs.len + 3]anim.Animation = undefined; + for (back, 0..) |i, j| both[j] = adds[i].fadeIn(); + for (same, 0..) |i, j| both[back.len + j] = subs[i].fadeIn(); + for (subs, 0..) |p, i| both[back.len + same.len + i] = p.move(.{ .y = piece(&sub_cuts, i, 182.5, 196.5).y + sub_y + gap }); + both[both.len - 3 ..].* = .{ sub.fadeOut(), tint.fadeOut(), anim.camera(.{ .zoom = 1.8, .x = at.x, .y = at.y + gap + 10 }) }; + s.play(both, .{ .seconds = 1.5 }); + var why: [marks.len + 1]anim.Animation = undefined; + for (marks, 0..) |m, i| why[i] = m.fadeIn(); + why[marks.len] = group.write(); + s.play(why, .{ .seconds = 1.5 }); +} diff --git a/test/manual.script b/test/manual.script index 3bc3c73..707e5cc 100644 --- a/test/manual.script +++ b/test/manual.script @@ -1,6 +1,7 @@ # 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). +# Figure 2-1, then ADD's row 80 /0 ib becoming SUB's 80 /5 ib, 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 @@ -57,17 +58,74 @@ 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. +# Back to the page, filled in: the end of slide 1. key space -frames 120 +await deck.waiting true expect deck.log.len 12 -expect deck.waiting false +expect deck.slide 1 screenshot .zig-cache/manual/end.png expect-different-screenshot .zig-cache/manual/page.png .zig-cache/manual/end.png 470 260 340 120 +# Slide 2: ADD's page, its opcode table out of it. +key space +await deck.waiting true +expect deck.slide 2 +expect deck.log.len 13 +screenshot .zig-cache/manual/add.png +expect-pixel .zig-cache/manual/add.png 640 300 255 255 255 255 2 +# The table, written in row by row. +key space +await deck.waiting true +screenshot .zig-cache/manual/table.png +expect-different-screenshot .zig-cache/manual/add.png .zig-cache/manual/table.png 415 90 445 310 +# Onto the row 80 /0 ib, then its opcode cell tinted. +key space +await deck.waiting true +screenshot .zig-cache/manual/row.png +expect-pixel .zig-cache/manual/row.png 230 362 255 255 255 255 2 +key space +await deck.waiting true +screenshot .zig-cache/manual/cell.png +expect-pixel .zig-cache/manual/cell.png 230 362 192 233 242 255 3 +# The digit after the slash becomes SUB's 5, closer in; back a step is the +# picture before it (the bar under it aside: it shows the time). +key space +await deck.waiting true +expect deck.log.len 17 +screenshot .zig-cache/manual/digit.png +expect-different-screenshot .zig-cache/manual/cell.png .zig-cache/manual/digit.png 0 0 1280 680 +key page_up +expect deck.log.len 16 +frames 2 +screenshot .zig-cache/manual/undone.png +expect-same-screenshot .zig-cache/manual/cell.png .zig-cache/manual/undone.png 2 0 0 1280 680 +key space +await deck.waiting true +expect deck.log.len 17 +# The rest of the row follows, on SUB's page. +key space +await deck.waiting true +screenshot .zig-cache/manual/sub.png +expect-different-screenshot .zig-cache/manual/digit.png .zig-cache/manual/sub.png 0 0 1280 680 +# ADD's row over SUB's, what differs marked: the end of the talk. +key space +frames 240 +expect deck.log.len 19 +expect deck.waiting false +screenshot .zig-cache/manual/rows.png +expect-pixel .zig-cache/manual/rows.png 75 300 251 236 183 255 3 +expect-pixel .zig-cache/manual/rows.png 962 357 251 236 183 255 3 # Exported ({a}, {b}: 10 fps, half size), each step held 1.5 s: the same -# frames twice, and the talk moves through them. +# frames twice, and the talk moves through them (Figure 2-1 at 4, 20 and +# 34 s; ADD's table being written at 45, its digit morphing at 56.5, the two +# rows at the end, 66). 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-same-screenshot {a}/000450.png {b}/000450.png +expect-same-screenshot {a}/000565.png {b}/000565.png +expect-same-screenshot {a}/000660.png {b}/000660.png expect-different-screenshot {a}/000040.png {a}/000200.png expect-different-screenshot {a}/000200.png {a}/000340.png +expect-different-screenshot {a}/000340.png {a}/000450.png +expect-different-screenshot {a}/000450.png {a}/000565.png +expect-different-screenshot {a}/000565.png {a}/000660.png |
