summaryrefslogtreecommitdiff
path: root/examples/manual.zig
blob: 7a53533fd1a0daf8b2aa743ef7143af4cc10a9cc (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
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 });
}