diff options
Diffstat (limited to 'examples/manual.zig')
| -rw-r--r-- | examples/manual.zig | 312 |
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 }); +} |
