summaryrefslogtreecommitdiff
path: root/examples/manual.zig
diff options
context:
space:
mode:
Diffstat (limited to 'examples/manual.zig')
-rw-r--r--examples/manual.zig312
1 files changed, 312 insertions, 0 deletions
diff --git a/examples/manual.zig b/examples/manual.zig
new file mode 100644
index 0000000..7a53533
--- /dev/null
+++ b/examples/manual.zig
@@ -0,0 +1,312 @@
+//! 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;
+
+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]";
+ 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`]";
+};
+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 {
+ 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, .{});
+ 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 });
+}
+
+/// 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 });
+}