summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-17 02:09:32 -0300
committerGabriel Schneider <[email protected]>2026-11-17 12:15:01 -0300
commit13a6f2f920c3b6d69362720318a404900f27cdf6 (patch)
tree3af339d1c683b545bb8faf0e57243f35f3c7bc82
parent2241a5d2dab43ee1effd17bf662597edca781977 (diff)
parent62d9f89eabf0a15c3d05d04f22d6b1810582be3f (diff)
downloadsketchbook-13a6f2f920c3b6d69362720318a404900f27cdf6.tar.gz
sketchbook-13a6f2f920c3b6d69362720318a404900f27cdf6.zip
Merge the sketch's file tree and the manual's second slide
Verb tables, state as files, fs verbs in every sketch binary; with the opcode-table slide of examples/manual.zig. No conflicts; zig build test: 180/180 steps, 144/144 tests. Co-Authored-By: Claude Fable 5.2 <[email protected]> Claude-Session: https://claude.ai/code/session_016Y9MNBECMWcJD5pdS4SR6T
-rw-r--r--README.md22
-rw-r--r--examples/manual.zig171
-rw-r--r--test/manual.script70
3 files changed, 243 insertions, 20 deletions
diff --git a/README.md b/README.md
index 406cd49..042a261 100644
--- a/README.md
+++ b/README.md
@@ -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;
@@ -606,7 +606,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
@@ -631,17 +632,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