summaryrefslogtreecommitdiff
path: root/anim/src/theme.zig
blob: 9b18e59bc255b86aa2d4249c141ca1251e75bebd (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
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
//! canim's look, as numbers: grounds and inks, the marks that mean something,
//! type sizes, component metrics, and how long things take.
//! `design/README.md` gives the reasons; `design/mock/` shows them drawn.
//!
//! Units are logical: the canvas is 1920 by 1080 of them whatever the export
//! size, so a 4K master draws each as two pixels and nothing here changes.
//! Colours are 0xRRGGBB and opaque. Nothing is tinted by alpha: an accent's
//! quiet form is its own colour (its ember), because gold blended over lapis
//! goes grey. The one translucent thing is `color.veil`.

const std = @import("std");

pub const Rect = struct { x: f32, y: f32, w: f32, h: f32 };

// ---------------------------------------------------------------- canvas

pub const canvas = struct {
    pub const width = 1920;
    pub const height = 1080;
    /// Only the page, and the kernel's ground, come nearer an edge than this.
    pub const margin_x = 64;
    pub const margin_y = 48;
    /// Twelve columns of 120 with gutters of 32 fill the 1792 between the margins.
    pub const columns = 12;
    pub const column = 120;
    pub const gutter = 32;
    /// Between panels one above another in a column.
    pub const row_gap = 12;
    /// The module: cells, rows, tags and code lines are multiples of 12.
    pub const unit = 12;

    /// Where the context and the lens go: 35 rows of 24. (Revision 2: the
    /// running head is gone, and its rows went to the stage.)
    pub const stage: Rect = .{ .x = 64, .y = 48, .w = 1792, .h = 840 };
    /// The clock: a rule the width of the stage over the caption, gold
    /// along it as far as the recording has run, the count under its right end.
    pub const clock_y = 900;
    /// Where the narrator's sentence goes. No data is ever drawn below y = 888:
    /// the player's controls and its subtitles cover this band.
    pub const caption: Rect = .{ .x = 64, .y = 912, .w = 1792, .h = 120 };
    /// Baselines: a one-line caption, then the two lines of a two-line one.
    pub const caption_baseline = [3]f32{ 990, 964, 1018 };
    /// A caption line is no wider: about 64 characters at `size.caption`.
    pub const caption_max_width = 1400;
};

/// Left edge of column `i` (0 to 11).
pub fn colX(i: u8) f32 {
    return @floatFromInt(@as(u32, canvas.margin_x) + @as(u32, i) * (canvas.column + canvas.gutter));
}

/// Width of `n` columns with the gutters between them.
pub fn span(n: u8) f32 {
    return @floatFromInt(@as(u32, n) * canvas.column + (@as(u32, n) - 1) * canvas.gutter);
}

/// `n` columns starting at column `first`, `y` below the stage's top, `h` tall.
pub fn cols(first: u8, n: u8, y: f32, h: f32) Rect {
    return .{ .x = colX(first), .y = canvas.stage.y + y, .w = span(n), .h = h };
}

/// How views share the stage. The order in each is the order of abstraction:
/// source is leftmost, then the CPU, then memory; a lower level is never left
/// of or above a higher one, and the kernel is always underneath.
pub const layout = struct {
    /// Two columns of 880. The program column: the lens, the source, the
    /// disassembly, top to bottom (the idea, its text, its instructions).
    /// The state column: what they act on, the same in every frame of
    /// every scene.
    pub const program = cols(0, 6, 0, canvas.stage.h);
    pub const state = cols(6, 6, 0, canvas.stage.h);

    /// The state column: every register (sixteen, rip, the flags), eight
    /// words of stack, three frames of backtrace.
    pub const registers = rows(state, 0, 18);
    pub const stack = below(registers, 8);
    pub const backtrace = below(stack, 3);

    /// How the program column is shared: the one thing about the layout a
    /// scene chooses. `lens` has no height where there is none.
    pub const Split = struct { lens: Rect, source: Rect, disasm: Rect };
    pub const split = struct {
        /// The machine alone: the source over the disassembly, eight
        /// instructions above the pc and eight below.
        pub const none: Split = .{ .lens = .{ .x = program.x, .y = program.y, .w = program.w, .h = 0 }, .source = rows(program, 0, 14), .disasm = below(rows(program, 0, 14), 17) };
        /// The default: the machine is the subject, the lens beside it.
        /// (The user's direction after the design's revision: more of the
        /// disassembly, so the source's window is shorter than the design's.)
        pub const beside: Split = shared(312, 8, 10);
        /// The idea is the subject: the lens a size up.
        pub const subject: Split = shared(432, 5, 8);

        fn shared(lens_h: f32, source_rows: f32, disasm_rows: f32) Split {
            const lens: Rect = .{ .x = program.x, .y = program.y, .w = program.w, .h = lens_h };
            const source: Rect = .{ .x = program.x, .y = lens.y + lens.h + canvas.row_gap, .w = program.w, .h = panelH(source_rows) };
            return .{ .lens = lens, .source = source, .disasm = below(source, disasm_rows) };
        }
    };

    /// A panel of `n` rows: a tag, the padding, the rows.
    pub fn panelH(n: f32) f32 {
        return metric.context.tag + 2 * metric.context.pad + n * metric.context.row;
    }

    fn rows(column: Rect, y: f32, n: f32) Rect {
        return .{ .x = column.x, .y = column.y + y, .w = column.w, .h = panelH(n) };
    }

    fn below(r: Rect, n: f32) Rect {
        return .{ .x = r.x, .y = r.y + r.h + canvas.row_gap, .w = r.w, .h = panelH(n) };
    }
};


// ---------------------------------------------------------------- colour

pub const color = struct {
    /// The page: lapis, deep. Panels' bodies are the page too.
    pub const page: u24 = 0x0a1030;
    /// Tags, cells, cards, node bodies: anything that is a thing on the page.
    pub const raised: u24 = 0x16245f;
    /// Rules round panels, hollow cells, wedges, dividers, and the fill of
    /// bookkeeping (allocator headers, pages merely present). 2 units wide as a
    /// line; never the only carrier of anything, it is the first thing a
    /// low-bitrate stream loses.
    pub const rule: u24 = 0x3a4a8a;
    /// The kernel's ground: vellum. Solid vellum means kernel at every scale
    /// (the slab, a block on the timeline, a row of the page map) and nothing else.
    pub const kernel: u24 = 0xeee6d2;

    pub const text = struct {
        /// Titles, and a value in flight.
        pub const bright: u24 = 0xfff8e8;
        /// Anything to be read. 14.9:1 on the page, 11.6:1 on `raised`.
        pub const primary: u24 = 0xeee6d2;
        /// Names, notes, things said about the data. 7.8:1 and 6.1:1.
        pub const dim: u24 = 0x9aa6d9;
        /// Furniture: leading zeros, the unchanging end of an address, line
        /// numbers, column heads. 4.5:1 and 3.5:1; never the only carrier.
        pub const faint: u24 = 0x6a7ab8;
        /// Letters on a solid accent.
        pub const ink: u24 = 0x050a24;
    };

    /// On the kernel's ground the page's colour is the ink, accents stay solid
    /// inside a 2 unit ink frame, and there are no embers.
    pub const on_kernel = struct {
        pub const ink: u24 = 0x0a1030;
        pub const dim: u24 = 0x4a5488;
        pub const rule: u24 = 0xb9ad8e;
        /// A byte the kernel changed a moment ago (the ember's stand-in).
        pub const held: u24 = 0xf3b9a0;
    };

    /// Source code. Hue on letters is syntax and nothing else, and it is quiet:
    /// keywords are also bold, comments also italic. The four are pardes's
    /// classes (`kw`, `str` and `num`, `comment`); its `bg`, `fg` and `lineno`
    /// are `page`, `text.primary` and `text.faint`.
    pub const code = struct {
        pub const plain: u24 = 0xeee6d2;
        pub const keyword: u24 = 0xc0dcff;
        pub const literal: u24 = 0xb5e8c8;
        pub const comment: u24 = 0x9aa6d9;
    };

    /// A pointer is coloured by the memory it points into, as pwndbg colours
    /// it: the stack yellow, the heap blue, code red, writable data purple;
    /// a constant, and a number that is no pointer, plain. Memory that is
    /// both writable and executable is code's colour, underlined.
    /// (The debugger's whole context on screen: the user's direction, ahead
    /// of the design's revision for it, which wins where it differs.)
    pub const region = struct {
        pub const stack: u24 = 0xf2d675;
        pub const heap: u24 = 0x86b6ff;
        pub const code_: u24 = 0xff8f9a;
        pub const data: u24 = 0xd59cf5;
        pub const rodata: u24 = 0xeee6d2;
        pub const number: u24 = 0xeee6d2;
    };
    /// A string a pointer leads to, in quotes.
    pub const string: u24 = 0xb5e8c8;

    /// Where execution was: the last three places, newest first, gold cooling.
    pub const trail = [3]u24{ 0xae9350, 0x746235, 0x463b20 };

    /// Pigments: which object, thread or variable this is, the same in every
    /// view. Dark bodies under `text.primary` (4.5:1 or better), so the bright
    /// marks still read on top of them. Use them in this order, at most four in
    /// a scene; only the first two are safe apart for every viewer, so each
    /// also carries its name.
    pub const pigment = [6]u24{
        0x8a5e0c, // ochre
        0x17707c, // teal
        0xa03060, // madder
        0x1c7450, // malachite
        0x6a3fb0, // violet
        0x2f5fc4, // azurite
    };

    /// Drawn over everything that is not the subject, to dim it.
    pub const veil: u24 = page;
    pub const veil_alpha: f32 = 0.65;
};

/// What a mark means. The same everywhere: a byte, a register, a source line,
/// a tree node, a page, a block of time.
pub const Role = enum {
    /// Where execution is: the line, the instruction, rip, the newest frame.
    current,
    /// Written by this step; in its ember, changed within the last few.
    write,
    /// Read by this step.
    read,
    /// Holds an address, and the arrow to it.
    pointer,
    /// Handed out by an allocator.
    allocated,
    /// Handed back. No colour: its bytes are still there, and nobody owns them.
    freed,
    /// A signal, a failed call. Write's colour in a hazard band, always named.
    fault,
    /// What the narration is about now: framed, and the rest veiled.
    attention,
    /// A value on its way from one place to another.
    flow,
    /// Bytes the recording never observed.
    unknown,
    /// The other side of the system call boundary.
    kernel,
};

/// How a role is drawn. No two roles share a form, so none is told by hue alone.
pub const Form = enum {
    /// A solid plaque on the thing's label and its ember across the row.
    plaque,
    /// A solid fill with ink letters, cooling to its ember and a solid bar along the bottom.
    fill,
    /// A frame, with its ember inside.
    frame,
    /// A frame round the bytes and an arrow from it, elbows filleted, head filled.
    arrow,
    /// Its ember inside a solid frame.
    block,
    /// Nothing inside a dashed frame; hatched where there is room.
    hollow,
    /// Diagonal bands of `solid` and ink round an ink plaque that names it.
    hazard,
    /// A bright frame, and the veil over everything else.
    spotlight,
    /// A thin arrow that is gone a second after it lands.
    thin_arrow,
    /// Two small squares where the digits would be.
    dots,
    /// The ground itself.
    ground,
};

pub const Mark = struct {
    /// Full strength: a strike's fill, a plaque, a stroke.
    solid: u24,
    /// The quiet form: a fill under `text.primary`. `solid` again where a role has none.
    ember: u24,
    /// Letters on `solid`.
    on_solid: u24,
    form: Form,
};

pub fn mark(role: Role) Mark {
    const t = color.text;
    return switch (role) {
        .current => .{ .solid = 0xe8c46a, .ember = 0x4a3d1c, .on_solid = t.ink, .form = .plaque },
        .write => .{ .solid = 0xff6a4a, .ember = 0x5a2218, .on_solid = t.ink, .form = .fill },
        .read => .{ .solid = 0x6fd6e6, .ember = 0x1c4652, .on_solid = t.ink, .form = .frame },
        .pointer => .{ .solid = 0xd59cf5, .ember = 0x45305a, .on_solid = t.ink, .form = .arrow },
        .allocated => .{ .solid = 0x7fdc9a, .ember = 0x1f4a33, .on_solid = t.ink, .form = .block },
        // The dashed frame, and the hatch.
        .freed => .{ .solid = t.dim, .ember = color.rule, .on_solid = t.ink, .form = .hollow },
        // The band, and the plaque inside it, lettered in `text.bright`.
        .fault => .{ .solid = 0xff6a4a, .ember = t.ink, .on_solid = t.ink, .form = .hazard },
        .attention => .{ .solid = t.bright, .ember = t.bright, .on_solid = t.ink, .form = .spotlight },
        .flow => .{ .solid = t.primary, .ember = t.primary, .on_solid = t.ink, .form = .thin_arrow },
        .unknown => .{ .solid = t.faint, .ember = t.faint, .on_solid = t.ink, .form = .dots },
        .kernel => .{ .solid = color.kernel, .ember = color.kernel, .on_solid = color.on_kernel.ink, .form = .ground },
    };
}

pub const roles = [_]Role{ .current, .write, .read, .pointer, .allocated, .freed, .fault, .attention, .flow, .unknown, .kernel };

/// WCAG relative luminance of 0xRRGGBB.
pub fn luminance(rgb: u24) f64 {
    var sum: f64 = 0;
    const weight = [3]f64{ 0.2126, 0.7152, 0.0722 };
    for (weight, 0..) |w, i| {
        const shift: u5 = @intCast(16 - 8 * i);
        const c = @as(f64, @floatFromInt((rgb >> shift) & 0xff)) / 255.0;
        sum += w * (if (c <= 0.04045) c / 12.92 else std.math.pow(f64, (c + 0.055) / 1.055, 2.4));
    }
    return sum;
}

/// WCAG contrast of two colours, 1 to 21.
pub fn contrast(a: u24, b: u24) f64 {
    const x = luminance(a);
    const y = luminance(b);
    return (@max(x, y) + 0.05) / (@min(x, y) + 0.05);
}

// ------------------------------------------------------------------ type

/// The Go fonts (Bigelow & Holmes; BSD-3-Clause, the Go licence), from
/// golang.org/x/image/font/gofont/ttfs or the `ttf-go` package. Mono is for
/// what the machine holds, sans for what is said about it.
pub const Face = struct { family: []const u8, file: []const u8 };
pub const font = struct {
    /// Data and code. The renderer's built-in face.
    pub const mono: Face = .{ .family = "Go Mono", .file = "Go-Mono.ttf" };
    /// Keywords, a struck value, the letters on a plaque.
    pub const mono_bold: Face = .{ .family = "Go Mono", .file = "Go-Mono-Bold.ttf" };
    /// Comments.
    pub const mono_italic: Face = .{ .family = "Go Mono", .file = "Go-Mono-Italic.ttf" };
    /// Captions, notes.
    pub const sans: Face = .{ .family = "Go", .file = "Go-Regular.ttf" };
    /// Tags, labels, the running head.
    pub const sans_medium: Face = .{ .family = "Go Medium", .file = "Go-Medium.ttf" };
    /// Titles.
    pub const sans_bold: Face = .{ .family = "Go", .file = "Go-Bold.ttf" };
};

pub const size = struct {
    /// Mono sizes are multiples of 5: Go Mono advances 0.6 em, so a character
    /// is a whole number of units (15, 18, 21, 27, 36), a hex pair is 36, and
    /// the layout is the same arithmetic at 1080p and at 4K.
    pub const mono = struct {
        /// The debugger's context, where a lot is on screen at once:
        /// chains of pointers, the disassembly, the stack.
        pub const context = 20;
        /// Address gutters, types, small tags. Furniture.
        pub const small = 25;
        /// Bytes, words, registers, code. The smallest size for anything the
        /// narration depends on; nothing mono that must be read is smaller.
        pub const data = 30;
        /// Values in nodes and chunks.
        pub const value = 35;
        /// A value in flight.
        pub const flight = 45;
        /// Values in hero cells, a system call's name.
        pub const hero = 60;
    };
    pub const sans = struct {
        /// Notes in a tag, glosses, the level rail. Furniture: lost at 480p, and that is allowed.
        pub const micro = 18;
        /// A panel's title.
        pub const tag = 20;
        /// A sentence beside a row: a gloss the narration also says aloud.
        pub const note = 24;
        /// Tags, names beside rows, the running head, legend names. The
        /// smallest sans for anything that identifies something.
        pub const label = 28;
        pub const kicker = 30;
        /// The narrator's sentence; code inside it is mono at 35.
        pub const caption = 40;
        pub const caption_leading = 54;
        pub const subtitle = 44;
        pub const title = 116;
        pub const title_leading = 128;
    };
    /// Nothing that must be read is smaller, in either face.
    pub const min_read = 20;
    /// Nothing at all is smaller.
    pub const min_any = 18;
};

/// Width of one Go Mono character at a mono size.
pub fn monoAdvance(mono_size: u16) u16 {
    return mono_size * 3 / 5;
}

/// Hex is set in groups of four digits, half a character apart, lower case,
/// no `0x`. A register is 16 digits, an address 12 (or its last 8 in a narrow
/// panel whose tag gives the rest); leading zeros are `text.faint`, and in an
/// address gutter only the last group is `text.primary`.
pub fn hexWidth(digits: u16, mono_size: u16) u16 {
    const adv = monoAdvance(mono_size);
    return digits * adv + (digits / 4 - 1) * ((adv + 1) / 2);
}

/// Baseline that centres capitals and digits of `text_size` in a box at `y`, `h` tall.
pub fn baseline(y: f32, h: f32, text_size: f32) f32 {
    return y + h / 2 + 0.36 * text_size;
}

// --------------------------------------------------------------- strokes

pub const stroke = struct {
    /// Rules, hollow cells, the gap between cells. The thinnest line there is.
    pub const rule = 2;
    /// Frames (read, allocated, freed, attention), flows, brackets.
    /// The thinnest line that carries meaning.
    pub const line = 3;
    /// Pointer arrows and pointer frames, tree and graph edges.
    pub const arrow = 4;
    /// The bar under a cooled change, a crossing into the kernel.
    pub const heavy = 6;
    /// A pointer's head: a filled triangle, length and width.
    pub const head = [2]f32{ 18, 16 };
    pub const flow_head = [2]f32{ 16, 14 };
    pub const crossing_head = [2]f32{ 24, 24 };
    /// Arrows turn square corners with this fillet.
    pub const elbow_radius = 12;
    /// Arrows sharing a lane sit this far apart, the longest outermost.
    pub const lane_pitch = 22;
    /// Freed outlines and links on their way out: on, off.
    pub const dash = [2]f32{ 12, 8 };
    /// The hatch in a freed block: band width and pitch, at 45 degrees.
    pub const hatch = [2]f32{ 5, 20 };
    /// A fault's band: each colour's width, at 45 degrees.
    pub const hazard = 12;
    /// Elision marks and the dots of an unknown byte: squares this big.
    pub const dot = 6;
};

// ------------------------------------------------------------ components

pub const metric = struct {
    /// A panel is an acme window: a tag with a square box, a rule, a body.
    pub const panel = struct {
        pub const tag_h = 48;
        /// The box: filled `current` in the panel the narration is in, hollow elsewhere.
        pub const box = 20;
        pub const box_inset = 14;
        pub const title_x = 48;
        pub const title_baseline = 34;
        pub const pad_x = 20;
        pub const pad_y = 16;
    };

    /// One byte: two hex digits in a 46 square on a 48 pitch.
    pub const byte = struct {
        pub const pitch = 48;
        pub const side = 46;
        /// A character over its byte, for strings: this tall.
        pub const text_h = 84;
    };
    /// Memory rows, bytes or words: 60 apart, which leaves room for a pointer's frame.
    pub const row_pitch = 60;
    /// A word is drawn on the footprint of its bytes (8 of them: 382 wide), so
    /// bytes and their number can change into each other in place.
    pub const pointer_frame_outset = 6;
    /// The bar along the bottom of a cooled change.
    pub const ember_bar = 6;
    /// Bytes not shown: three dots and a note, this tall.
    pub const elision_h = 24;
    /// Left of an address gutter: register and variable marks that point at the row.
    pub const mark_lane = 88;
    /// Between gutter and bytes: where pointer arrows run.
    pub const arrow_lane = 52;

    /// Registers, and any table of names and values.
    pub const table = struct {
        pub const row_h = 48;
        pub const name_x = 18;
        /// The value cell overhangs its digits by this on each side.
        pub const value_pad = 10;
        pub const flag = [2]f32{ 60, 36 };
        pub const flag_gap = 12;
    };
    /// Shown unless a scene says otherwise, in this order: where it is, the
    /// result, the arguments, the frame. Any other register appears when a
    /// step touches it and leaves once its ember has gone.
    pub const default_registers = [_][]const u8{ "rip", "rax", "rdi", "rsi", "rdx", "rcx", "rsp", "rbp" };
    pub const default_flags = [_][]const u8{ "CF", "ZF", "SF", "OF" };
    /// The registers' rows, in pwndbg's order: sixteen, rip, the flags.
    pub const all_registers = [_][]const u8{ "rax", "rbx", "rcx", "rdx", "rsi", "rdi", "rbp", "rsp", "r8", "r9", "r10", "r11", "r12", "r13", "r14", "r15", "rip", "flags" };

    /// The context: every panel of it is rows of 24 under a tag of 24.
    pub const context = struct {
        pub const row = 24;
        pub const tag = 24;
        /// Above and below the rows; at a panel's sides.
        pub const pad = 6;
        pub const side = 12;
        /// A register's name: five characters. Its value starts here.
        pub const name_w = 60;
        pub const chain_x = 72;
        /// Both arrows of a chain: a 2-unit shaft, a head 8 by 10.
        pub const arrow_w = 30;
        pub const arrow_head = [2]f32{ 8, 10 };
        /// Between groups of four hex digits: half an advance.
        pub const group_gap = 6;
        /// Changed a moment ago: a tick at the value's left.
        pub const tick = 4;
        pub const read_frame = 2;
        pub const pulse_outset = 3;
        pub const string_min = 6;
        pub const source_chars = 67;
    };

    pub const code = struct {
        pub const line_h = 48;
        /// Line numbers: three digits and this, then the code.
        pub const gutter_pad = 16;
        pub const text_gap = 20;
        /// Characters a panel of n columns holds at `size.mono.data`: write the
        /// C for a video to fit the panel it will be shown in.
        pub const chars_in_5_columns = 34;
        pub const chars_in_6_columns = 42;
        pub const chars_in_7_columns = 51;
        /// The trail bar at the left edge, and the instruction marker in an unfolded line.
        pub const trail_bar = 6;
        pub const unfold_indent = 36;
        pub const instruction_bar = 8;
    };

    /// Call stack cards, newest on top.
    pub const card = struct {
        pub const h = 56;
        pub const gap = 12;
        pub const spine = 12;
    };
    /// A linked-list node: value, then a pointer compartment.
    pub const node = struct {
        pub const w = 180;
        pub const h = 72;
        pub const pointer_w = 72;
        /// The square in the pointer compartment that its arrow leaves from.
        pub const origin = 14;
    };
    /// Tree and graph nodes: circles; the tree's levels this far apart.
    pub const tree = struct {
        pub const radius = 24;
        pub const radius_solo = 36;
        pub const level = 54;
        pub const badge = 28;
    };
    /// Array cells: in a panel among others, and as the subject.
    pub const cell = [2]f32{ 96, 84 };
    pub const hero_cell = [2]f32{ 168, 132 };
    /// A value in flight: its card.
    pub const flight_card = [2]f32{ 100, 60 };

    /// The heap, to scale.
    pub const heap = struct {
        pub const units_per_byte = 4;
        pub const strip_h = 88;
        pub const strip_h_stacked = 56;
    };
    /// The page map: one square a page.
    pub const page = struct {
        pub const pitch = 24;
        pub const side = 22;
        pub const row_pitch = 42;
    };
    /// The system call strip: time spent in the kernel hangs below the line.
    pub const timeline = struct {
        pub const baseline = 3;
        pub const block_h = 44;
        pub const min_block = 12;
        pub const min_gap = 16;
        pub const now = 4;
    };
    pub const legend = struct {
        pub const sample_w = 94;
        pub const text_x = 110;
        pub const row_h = 96;
    };
    /// A plaque: a name in a box (hollow for a value, filled for a place).
    pub const plaque = struct {
        pub const h = 40;
        pub const pad = 12;
    };

    /// No panel shows more rows of data than this; past it, elide or zoom.
    pub const max_rows = 10;
    /// No scene tracks more objects by pigment.
    pub const max_pigments = 4;
};

// ---------------------------------------------------------------- motion

pub const Ease = enum {
    /// Time itself: the progress line, a counter, the playhead; and opacity.
    linear,
    /// Things that answer the program: the mark, cards, tags, arrows
    /// growing, rows making room. Quickest a quarter of the way in.
    standard,
    /// A fade that arrives rising.
    enter,
    /// A fade that leaves.
    exit,
    /// Things with weight: a value in flight, the camera, a layout, a
    /// colour cooling. Quickest at the middle.
    glide,
};

/// Control points x1, y1, x2, y2 of the curve from (0, 0) to (1, 1).
pub fn bezier(e: Ease) [4]f32 {
    return switch (e) {
        .linear => .{ 0, 0, 1, 1 },
        .standard => .{ 0.3, 0, 0.2, 1 },
        .enter => .{ 0, 0, 0.2, 1 },
        .exit => .{ 0.4, 0, 1, 1 },
        .glide => .{ 0.45, 0, 0.55, 1 },
    };
}

/// Progress at time `t`, both 0 to 1. Fits vecanim's `.ease` (`fn (f32) f32`)
/// once the curve is bound: `fn standard(t: f32) f32 { return theme.ease(.standard, t); }`.
pub fn ease(e: Ease, t: f32) f32 {
    if (t <= 0) return 0;
    if (t >= 1) return 1;
    const p = bezier(e);
    var lo: f32 = 0;
    var hi: f32 = 1;
    var s: f32 = t;
    for (0..24) |_| {
        s = (lo + hi) / 2;
        if (cubic(p[0], p[2], s) < t) lo = s else hi = s;
    }
    return cubic(p[1], p[3], s);
}

fn cubic(a: f32, b: f32, s: f32) f32 {
    const r = 1 - s;
    return 3 * r * r * s * a + 3 * r * s * s * b + s * s * s;
}

/// The one overshoot there is: a struck cell's edges go out this many
/// units on every side and come back, `t` from 0 to 1 over
/// `time.strike.pulse`. An outset, not a scale: the same on a byte and on a
/// register, and the digits do not move.
pub fn pulse(t: f32) f32 {
    return 4 * @sin(std.math.pi * std.math.clamp(t, 0, 1));
}

/// Seconds. Export at 60 frames a second; every figure is a whole number of frames.
pub const time = struct {
    pub const fps = 60;

    /// A colour changing where nothing moves.
    pub const snap = 0.10;
    /// Leaving; a small change of state.
    pub const quick = 0.20;
    /// The current mark moving to the next row; `step_per_row` more for
    /// each further row, `step_max` at most. Further than
    /// `current_jump_rows`, or into or out of a call, it jumps.
    pub const step = 0.20;
    pub const step_per_row = 2.0 / 60.0;
    pub const step_max = 0.40;
    /// Something moving within a panel, up to 400 units.
    pub const move = 0.40;
    /// Something moving between panels, or further.
    pub const travel = 0.60;
    /// Panels changing layout.
    pub const layout = 0.80;
    /// A camera move up to twice or down to half the scale; a larger one.
    pub const camera = 1.20;
    pub const camera_far = 1.60;

    /// A step is a sentence. Fire: the mark's plaque pulses on the line
    /// about to run, and nothing else moves.
    pub const fire = 0.20;
    /// Then its effects, a level at a time, this far apart: the registers,
    /// memory, the idea drawn from them.
    pub const cascade = 0.30;
    /// Then they are read: this long after the last strike, `read_more`
    /// for each further value, `read_most` in all.
    pub const read_value = 0.60;
    pub const read_more = 0.20;
    pub const read_most = 1.40;
    /// Then the mark advances (`step`), and the next line is read.
    pub const rest = 0.40;

    /// A write: armed (a frame round the cell, the old value still in
    /// it), struck (the fill fades in, with a pulse of its edges), held
    /// solid until the mark leaves the line, cooled to its ember and bar,
    /// kept while the thing has changed within `ember_steps` steps (or
    /// `ember_seconds` where time runs free), then gone.
    pub const strike = struct {
        pub const arm = 0.20;
        pub const in = 0.10;
        pub const pulse = 0.20;
        pub const hold = 0.50;
        pub const cool = 0.40;
        pub const ember_steps = 3;
        pub const ember_seconds = 4.0;
        pub const out = 0.60;
    };
    /// A read: framed for the step, never pulsed.
    pub const read = struct {
        pub const in = 0.10;
        pub const min_hold = 0.50;
        pub const out = 0.30;
    };
    /// The current marker slides to a neighbour and jumps (out, then in) further than this many rows.
    pub const current_jump_rows = 8;
    pub const current_jump = 0.10;
    /// A pointer changing target: the head travels; the old path stays dashed, then goes.
    pub const redirect = struct {
        pub const head = 0.40;
        pub const ghost_hold = 0.80;
        pub const ghost_out = 0.30;
        /// What the arrow lands on is framed bright, this long.
        pub const landing = 0.20;
    };
    /// A value moving: lift, fly an arc, land with a strike. The place it left keeps its digits, faint.
    pub const flight = struct {
        pub const lift = 0.10;
        pub const lift_scale = 1.12;
        /// How long it flies, by how far: to 200 units, to 400, beyond.
        pub const near = 0.50;
        pub const mid = 0.60;
        pub const far = 0.80;
        /// Of two that fly together, the second sets off this much later.
        pub const second = 0.10;
        /// The arc's height as a share of the distance, and its limits in units.
        pub const arc = 0.25;
        pub const arc_min = 34;
        pub const arc_max = 120;
        /// A flow's arrow outlives the landing by this.
        pub const linger = 1.0;
    };
    /// The veil that dims everything but the subject.
    pub const veil = 0.30;
    /// A telescope extends: the links after one that changed are followed
    /// again one at a time, this far apart.
    pub const unroll = 4.0 / 60.0;
    /// A tie between two panes: this long to draw (after what it leaves
    /// from has struck), and to go, as the marks advance.
    pub const link = struct {
        pub const in = 0.40;
        pub const out = 0.30;
    };
    /// A source line opening into its instructions, and closing.
    pub const unfold = 0.40;
    /// A wedge drawing from a thing to its enlargement.
    pub const wedge = 0.30;
    /// A caption leaves, then nothing, then the next arrives rising this
    /// many units; never typed out, never crossfaded. The stage stays
    /// still `caption_lead` after it (`caption_lead_first` after a scene's
    /// first): the eye reads, then is shown.
    pub const caption_out = 0.20;
    pub const caption_gap = 0.10;
    pub const caption_in = 0.30;
    pub const caption_rise = 8;
    pub const caption_lead = 1.00;
    pub const caption_lead_first = 2.00;

    /// Things arriving together start this far apart, in reading order, and
    /// the last starts no later than `stagger_max` after the first.
    pub const stagger = 2.0 / 60.0;
    pub const stagger_max = 0.30;
    /// The same as a lag ratio for vecanim's `.lag`, for `n` things over `seconds`.
    pub fn lag(n: u32, seconds: f32) f32 {
        if (n < 2) return 0;
        const total: f32 = @min(stagger * @as(f32, @floatFromInt(n - 1)), stagger_max);
        return total / (seconds * @as(f32, @floatFromInt(n - 1)));
    }

    /// Pacing. A beat is the unit of stillness.
    pub const beat = 0.50;
    /// What a step that writes one value comes to. Not a pace: a walked
    /// step is as long as its content (`cursor.reading`).
    pub const walk = 1.50;
    /// Once the pattern is known: the mark and structures eased, values
    /// as embers. `run_max_steps` at most; beyond that, sprint.
    pub const run = 0.30;
    pub const run_max_steps = 24;
    /// What moves at a run (the mark, a card, an arrow) takes this long.
    pub const run_ease = 8.0 / 60.0;
    /// A hurried step with this long or more is still a whole sentence,
    /// said faster; with less, it is a run.
    pub const walk_least = 0.70;
    /// A return's follow-through: its card is struck with the result,
    /// leaves, and the cards under it move up, before the hold begins.
    pub const returning = 0.90;
    /// At this a step or faster, single changes are not drawn: structures
    /// grow, embers, and a counter.
    pub const sprint = 4.0 / 60.0;
    /// A phrase (a trip round a loop, a call and its return) ends with a rest.
    pub const phrase_rest = 0.50;
    pub const phrase_rest_running = 0.20;
    /// A change of pace is never a switch: each step of it is this much
    /// of the one before.
    pub const ramp = 0.6;
    /// Stillness at a scene's opening, for the picture to be read:
    /// `establish` and `establish_per_panel` for each panel.
    pub const establish = 1.00;
    pub const establish_per_panel = 0.50;
    /// Stillness after the stage is rearranged, and on the last picture.
    pub const settle = 0.80;
    pub const before_cut = 2.00;
    /// A camera move: its target framed (`camera_before`), the rest of
    /// the stage cleared (`camera_clear`), the move, then still
    /// (`camera_after`). Never longer than `camera_dwell_max` nearer
    /// without a change.
    pub const camera_before = 0.40;
    pub const camera_clear = 0.30;
    pub const camera_after = 0.60;
    pub const camera_dwell_max = 2.00;

    /// How long a caption of `chars` characters stays up, at least.
    pub fn caption(chars: u32) f32 {
        return 1.5 + 0.06 * @as(f32, @floatFromInt(chars));
    }
};

/// The camera only ever shows the frame, a panel, or a few cells; it never turns.
pub const camera = struct {
    pub const scales = [4]f32{ 1, 1.5, 2, 4 };
    /// Units a second, at most, at scale 1.
    pub const max_speed = 1200;
};

/// At once: one thing moves because the program did something, and at most
/// two more move because of it. The camera and the layout move alone.
pub const max_moving = 3;

// ----------------------------------------------------------------- tests

const expect = std.testing.expect;

test "text reads on its grounds" {
    const t = color.text;
    try expect(contrast(t.primary, color.page) >= 11);
    try expect(contrast(t.primary, color.raised) >= 11);
    try expect(contrast(t.dim, color.page) >= 7);
    try expect(contrast(t.dim, color.raised) >= 6);
    try expect(contrast(t.faint, color.page) >= 4.5);
    try expect(contrast(t.faint, color.raised) >= 3.5);
    try expect(contrast(color.on_kernel.ink, color.kernel) >= 11);
    try expect(contrast(color.on_kernel.dim, color.kernel) >= 5.5);
    for ([_]u24{ color.code.plain, color.code.keyword, color.code.literal, color.code.comment }) |c|
        try expect(contrast(c, color.page) >= 7);
    for (color.pigment) |p| try expect(contrast(t.primary, p) >= 4.5);
}

test "every mark stands off the page, and letters read on it" {
    for (roles) |r| {
        const m = mark(r);
        try expect(contrast(m.solid, color.page) >= 4.5);
        try expect(contrast(m.on_solid, m.solid) >= 4.5);
        // A role with a quiet form: text reads on it, and it is not the page.
        if (m.ember != m.solid and r != .freed and r != .fault) {
            try expect(contrast(color.text.primary, m.ember) >= 7);
            try expect(contrast(m.ember, color.page) >= 1.4);
        }
    }
    // The strokes that carry meaning on their own.
    for ([_]Role{ .current, .write, .read, .pointer, .allocated }) |r|
        try expect(contrast(mark(r).solid, color.page) >= 6.5);
    try expect(contrast(color.text.ink, mark(.write).solid) >= 6.5);
}

test "no two roles are drawn the same way" {
    for (roles, 0..) |a, i| for (roles[i + 1 ..]) |b| try expect(mark(a).form != mark(b).form);
}

test "mono advances are whole units" {
    const m = size.mono;
    for ([_]u16{ m.context, m.small, m.data, m.value, m.flight, m.hero }) |s| try expect(s % 5 == 0);
    try expect(monoAdvance(m.context) == 12 and m.context >= size.min_read);
    try expect(monoAdvance(m.data) == 18);
    try expect(hexWidth(16, m.data) == 315);
    try expect(hexWidth(12, m.small) == 196);
    // A byte's two digits fit its cell; a register's sixteen fit a word's footprint.
    try expect(2 * monoAdvance(m.data) <= metric.byte.side - 8);
    try expect(hexWidth(16, m.data) <= 8 * metric.byte.pitch - 2 - 24);
    try expect(m.data >= size.min_read and size.sans.label >= size.min_read and size.sans.micro >= size.min_any);
}

test "layouts fill the stage" {
    try expect(colX(11) + canvas.column == canvas.width - canvas.margin_x);
    try expect(span(12) == canvas.stage.w);
    try expect(layout.program.w == 880 and layout.state.x == 976);
    // The state column: 468, 228 and 108, twelve apart.
    try expect(layout.registers.h == 468 and layout.stack.h == 228 and layout.backtrace.h == 108);
    try expect(layout.backtrace.y + layout.backtrace.h <= canvas.stage.y + canvas.stage.h);
    for ([_]layout.Split{ layout.split.none, layout.split.beside, layout.split.subject }) |split| {
        try expect(split.disasm.y + split.disasm.h <= canvas.stage.y + canvas.stage.h);
        try expect(split.source.y >= split.lens.y + split.lens.h);
    }
    try expect(layout.split.beside.source.h == 228 and layout.split.beside.disasm.h == 276);
}

test "easing runs from 0 to 1 without turning back" {
    for ([_]Ease{ .linear, .standard, .enter, .exit, .glide }) |e| {
        try expect(ease(e, 0) == 0 and ease(e, 1) == 1);
        var last: f32 = 0;
        for (1..61) |i| {
            const v = ease(e, @as(f32, @floatFromInt(i)) / 60);
            try expect(v >= last - 1e-4 and v <= 1 + 1e-4);
            last = v;
        }
    }
    try expect(@abs(ease(.linear, 0.3) - 0.3) < 1e-3);
    // `standard` is ahead of time and `glide` is symmetrical.
    try expect(ease(.standard, 0.5) > 0.6);
    try expect(@abs(ease(.glide, 0.5) - 0.5) < 1e-3);
    try expect(pulse(0.5) > 3.9 and pulse(0) == 0);
}

test "durations are whole frames" {
    const t = time;
    for ([_]f32{ t.snap, t.quick, t.step, t.step_per_row, t.step_max, t.move, t.travel, t.layout, t.camera, t.camera_far, t.fire, t.cascade, t.read_value, t.read_more, t.rest, t.strike.arm, t.strike.in, t.strike.pulse, t.strike.hold, t.strike.cool, t.strike.out, t.read.out, t.current_jump, t.flight.lift, t.flight.near, t.flight.second, t.veil, t.unfold, t.wedge, t.caption_in, t.caption_out, t.caption_gap, t.walk, t.run, t.sprint, t.phrase_rest, t.before_cut }) |d| {
        const frames = d * t.fps;
        try expect(@abs(frames - @round(frames)) < 1e-3);
    }
    try expect(t.lag(1, 0.4) == 0);
    try expect(@abs(t.lag(8, 0.4) * 0.4 * 7 - 7 * t.stagger) < 1e-4);
    try expect(@abs(t.lag(40, 0.4) * 0.4 * 39 - t.stagger_max) < 1e-4);
}