summaryrefslogtreecommitdiff
path: root/src/image.zig
blob: 215bfc25a0a0d9b94ee4027975e6d46eb5b07500 (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
//! Image decoding, pixel placement, and the image pane.
const std = @import("std");
const builtin = @import("builtin");
const zstbi = @import("zstbi");
const pdf_enabled = @import("pardes_config").mupdf;
const pardes = @import("pardes.zig");
const config = @import("config.zig");
const filesystem = @import("fs.zig");
/// cap the longest side before keeping/transmitting: a pane is at most a
/// screenful of cells, multi-thousand-pixel photos waste decode/transmit time
const MAX_DIM: u32 = 1280;

pub const PaletteMode = pardes.Placement.Art.Palette;

/// How a native pixel attachment is placed in its pane body. `contain` is the
/// historical image-pane policy: shrink only when necessary and keep the
/// image at the top left. The axis-specific modes may enlarge, letterbox the
/// unconstrained axis, or crop it when it overflows.
pub const NativeFit = if (pdf_enabled) enum { contain, width, height } else enum { contain };

pub const PixelRect = struct {
    x: u32 = 0,
    y: u32 = 0,
    w: u32 = 0,
    h: u32 = 0,
};

pub const PixelPoint = struct { x: u32, y: u32 };

/// Source pixels and their destination inside a pane body's pixel rectangle.
/// Both rectangles are half-open. Rounding is always toward the inside, so a
/// backend can draw this result without a backend-specific overflow clip.
pub const NativeGeometry = struct {
    src: PixelRect,
    dst: PixelRect,

    /// Map a destination pixel back into the retained source crop. This is the
    /// same integer transform the texture rectangle describes; points in a
    /// letterbox return null.
    pub fn sourcePoint(self: NativeGeometry, x: u32, y: u32) ?PixelPoint {
        if (self.src.w == 0 or self.src.h == 0 or self.dst.w == 0 or self.dst.h == 0) return null;
        if (x < self.dst.x or y < self.dst.y) return null;
        const dx = x - self.dst.x;
        const dy = y - self.dst.y;
        if (dx >= self.dst.w or dy >= self.dst.h) return null;
        return .{
            .x = self.src.x + @as(u32, @intCast(@as(u64, dx) * self.src.w / self.dst.w)),
            .y = self.src.y + @as(u32, @intCast(@as(u64, dy) * self.src.h / self.dst.h)),
        };
    }
};

fn panOffset(overflow: u32, pan: u16) u32 {
    if (overflow == 0 or pan == 0) return 0;
    if (pan == std.math.maxInt(u16)) return overflow;
    // Round, rather than truncate, so the midpoint is the visual midpoint.
    return @intCast((@as(u64, overflow) * pan + std.math.maxInt(u16) / 2) / std.math.maxInt(u16));
}

fn fitWidth(src_w: u32, src_h: u32, body_w: u32, body_h: u32, pan_y: u16) ?NativeGeometry {
    const scaled_h = @as(u64, src_h) * body_w;
    if (scaled_h <= @as(u64, body_h) * src_w) {
        const full_h: u32 = @intCast(@max(1, scaled_h / src_w));
        return .{
            .src = .{ .w = src_w, .h = src_h },
            .dst = .{ .y = (body_h - full_h) / 2, .w = body_w, .h = full_h },
        };
    }

    // Retain the largest whole source-pixel crop which cannot extend beyond
    // the body at this scale. The sub-pixel remainder becomes at most a small
    // centered letterbox instead of leaking into an adjacent cell in Kitty.
    const crop_h_wide = @as(u64, body_h) * src_w / body_w;
    if (crop_h_wide == 0) return null;
    const crop_h: u32 = @min(src_h, @as(u32, @intCast(crop_h_wide)));
    const dst_h: u32 = @min(body_h, @max(1, @as(u32, @intCast(@as(u64, crop_h) * body_w / src_w))));
    return .{
        .src = .{
            .y = panOffset(src_h - crop_h, pan_y),
            .w = src_w,
            .h = crop_h,
        },
        .dst = .{ .y = (body_h - dst_h) / 2, .w = body_w, .h = dst_h },
    };
}

fn fitHeight(src_w: u32, src_h: u32, body_w: u32, body_h: u32, pan_x: u16) ?NativeGeometry {
    const scaled_w = @as(u64, src_w) * body_h;
    if (scaled_w <= @as(u64, body_w) * src_h) {
        const full_w: u32 = @intCast(@max(1, scaled_w / src_h));
        return .{
            .src = .{ .w = src_w, .h = src_h },
            .dst = .{ .x = (body_w - full_w) / 2, .w = full_w, .h = body_h },
        };
    }

    const crop_w_wide = @as(u64, body_w) * src_h / body_h;
    if (crop_w_wide == 0) return null;
    const crop_w: u32 = @min(src_w, @as(u32, @intCast(crop_w_wide)));
    const dst_w: u32 = @min(body_w, @max(1, @as(u32, @intCast(@as(u64, crop_w) * body_h / src_h))));
    return .{
        .src = .{
            .x = panOffset(src_w - crop_w, pan_x),
            .w = crop_w,
            .h = src_h,
        },
        .dst = .{ .x = (body_w - dst_w) / 2, .w = dst_w, .h = body_h },
    };
}

/// Compute native image placement without floating point. Source dimensions
/// are limited to u32 because SDL's texture API and Kitty's crop parameters
/// cannot describe anything larger. Kitty applies the stricter u16 check at
/// its protocol boundary.
pub fn nativeGeometry(
    iw: usize,
    ih: usize,
    body_pixel_w: u32,
    body_pixel_h: u32,
    fit: NativeFit,
    pan_x: u16,
    pan_y: u16,
) ?NativeGeometry {
    if (comptime !pdf_enabled) {
        return containGeometry(iw, ih, body_pixel_w, body_pixel_h);
    }
    if (iw == 0 or ih == 0 or body_pixel_w == 0 or body_pixel_h == 0 or
        iw > std.math.maxInt(u32) or ih > std.math.maxInt(u32)) return null;

    const src_w: u32 = @intCast(iw);
    const src_h: u32 = @intCast(ih);
    return switch (fit) {
        .width => fitWidth(src_w, src_h, body_pixel_w, body_pixel_h, pan_y),
        .height => fitHeight(src_w, src_h, body_pixel_w, body_pixel_h, pan_x),
        // Pan is not contain's: it keeps the top-left placement.
        .contain => containGeometry(iw, ih, body_pixel_w, body_pixel_h),
    };
}

/// The ordinary image-pane policy: shrunk only when it must be, at the top
/// left. The scale ratios are compared without floating point: the tighter
/// bound is exact, the other rounded inward.
pub fn containGeometry(iw: usize, ih: usize, max_w: u32, max_h: u32) ?NativeGeometry {
    if (iw == 0 or ih == 0 or max_w == 0 or max_h == 0 or
        iw > std.math.maxInt(u32) or ih > std.math.maxInt(u32)) return null;

    const src_w: u32 = @intCast(iw);
    const src_h: u32 = @intCast(ih);
    if (src_w <= max_w and src_h <= max_h) return .{
        .src = .{ .w = src_w, .h = src_h },
        .dst = .{ .w = src_w, .h = src_h },
    };
    const dst: PixelRect = if (@as(u64, max_w) * src_h <= @as(u64, max_h) * src_w)
        .{
            .w = max_w,
            .h = @intCast(@max(1, @as(u64, src_h) * max_w / src_w)),
        }
    else
        .{
            .w = @intCast(@max(1, @as(u64, src_w) * max_h / src_h)),
            .h = max_h,
        };
    return .{ .src = .{ .w = src_w, .h = src_h }, .dst = dst };
}

test "native image contain keeps aspect, bounds, top-left, and small-image size" {
    try std.testing.expectEqual(PixelRect{ .w = 40, .h = 20 }, containGeometry(400, 200, 40, 40).?.dst);
    try std.testing.expectEqual(PixelRect{ .w = 20, .h = 40 }, containGeometry(200, 400, 40, 40).?.dst);
    try std.testing.expectEqual(PixelRect{ .w = 17, .h = 9 }, containGeometry(17, 9, 40, 40).?.dst);
    try std.testing.expect(containGeometry(17, 9, 0, 40) == null);

    const odd = containGeometry(403, 211, 101, 47).?;
    try std.testing.expectEqual(PixelRect{ .w = 89, .h = 47 }, odd.dst);
    try std.testing.expectEqual(PixelRect{ .w = 403, .h = 211 }, odd.src);
}

test "native fit width handles portrait crop, pan extrema, and landscape letterbox" {
    if (comptime !pdf_enabled) return;
    const top = nativeGeometry(600, 1000, 800, 600, .width, 0, 0).?;
    try std.testing.expectEqual(PixelRect{ .w = 600, .h = 450 }, top.src);
    try std.testing.expectEqual(PixelRect{ .w = 800, .h = 600 }, top.dst);

    const middle = nativeGeometry(600, 1000, 800, 600, .width, 0, 32768).?;
    try std.testing.expectEqual(@as(u32, 275), middle.src.y);
    const bottom = nativeGeometry(600, 1000, 800, 600, .width, 65535, 65535).?;
    try std.testing.expectEqual(@as(u32, 550), bottom.src.y);

    const landscape = nativeGeometry(1000, 600, 800, 600, .width, 0, 65535).?;
    try std.testing.expectEqual(PixelRect{ .w = 1000, .h = 600 }, landscape.src);
    try std.testing.expectEqual(PixelRect{ .y = 60, .w = 800, .h = 480 }, landscape.dst);
}

test "native fit height handles portrait letterbox and landscape crop" {
    if (comptime !pdf_enabled) return;
    const portrait = nativeGeometry(600, 1000, 800, 600, .height, 65535, 0).?;
    try std.testing.expectEqual(PixelRect{ .w = 600, .h = 1000 }, portrait.src);
    try std.testing.expectEqual(PixelRect{ .x = 220, .w = 360, .h = 600 }, portrait.dst);

    const left = nativeGeometry(1000, 600, 800, 600, .height, 0, 0).?;
    try std.testing.expectEqual(PixelRect{ .w = 800, .h = 600 }, left.src);
    try std.testing.expectEqual(PixelRect{ .w = 800, .h = 600 }, left.dst);
    const right = nativeGeometry(1000, 600, 800, 600, .height, 65535, 0).?;
    try std.testing.expectEqual(@as(u32, 200), right.src.x);
}

test "native fit odd ratios round inward and map points through letterboxes and crops" {
    if (comptime !pdf_enabled) return;
    const width = nativeGeometry(403, 211, 101, 47, .width, 0, 32768).?;
    try std.testing.expectEqual(PixelRect{ .y = 12, .w = 403, .h = 187 }, width.src);
    try std.testing.expectEqual(PixelRect{ .w = 101, .h = 46 }, width.dst);
    const mapped = width.sourcePoint(100, 45).?;
    try std.testing.expect(mapped.x < width.src.x + width.src.w);
    try std.testing.expect(mapped.y < width.src.y + width.src.h);
    try std.testing.expect(width.sourcePoint(101, 46) == null);

    const height = nativeGeometry(403, 211, 101, 47, .height, 32768, 0).?;
    try std.testing.expectEqual(PixelRect{ .w = 403, .h = 211 }, height.src);
    try std.testing.expectEqual(PixelRect{ .x = 6, .w = 89, .h = 47 }, height.dst);
    try std.testing.expect(height.sourcePoint(5, 20) == null);
    try std.testing.expect(height.sourcePoint(6, 20) != null);
}

test "native geometry rejects dimensions which its backend contract cannot represent" {
    try std.testing.expect(containGeometry(0, 10, 20, 20) == null);
    if (@bitSizeOf(usize) > 32) try std.testing.expect(containGeometry(@as(usize, std.math.maxInt(u32)) + 1, 10, 20, 20) == null);
    if (comptime pdf_enabled) {
        try std.testing.expect(nativeGeometry(10, 10, 0, 20, .width, 0, 0) == null);
        if (@bitSizeOf(usize) > 32)
            try std.testing.expect(nativeGeometry(@as(usize, std.math.maxInt(u32)) + 1, 10, 20, 20, .height, 0, 0) == null);
    }
}

test "native geometry is total at extreme accepted aspect ratios" {
    if (comptime !pdf_enabled) return;
    const largest = std.math.maxInt(u32);
    try std.testing.expect(nativeGeometry(1, largest, largest, 1, .width, 0, 65535) == null);
    try std.testing.expect(nativeGeometry(largest, 1, 1, largest, .height, 65535, 0) == null);

    const wide = nativeGeometry(largest, 1, largest, 1, .width, 0, 0).?;
    try std.testing.expectEqual(PixelRect{ .w = largest, .h = 1 }, wide.dst);
    const tall = nativeGeometry(1, largest, 1, largest, .height, 0, 0).?;
    try std.testing.expectEqual(PixelRect{ .w = 1, .h = largest }, tall.dst);
}

/// call once at startup / exit (stb_image's allocator shim)
pub fn start(io: std.Io, gpa: std.mem.Allocator) void {
    zstbi.init(io, gpa);
    started = true;
}
pub fn stop() void {
    started = false;
    zstbi.deinit();
}

/// stb_image has its allocator (`start`): before, nothing of it may run.
var started = false;

extern fn stbi_info_from_memory(buffer: [*]const u8, len: c_int, x: *c_int, y: *c_int, comp: *c_int) c_int;

/// stb_image's header reader.
fn stbiInfo(bytes: []const u8, w: *c_int, h: *c_int, c: *c_int) bool {
    return stbi_info_from_memory(bytes.ptr, @intCast(bytes.len), w, h, c) == 1;
}

/// PNG and JPEG are ghostty's decoders (wuffs, which ghostty-vt links for
/// kitty graphics) wherever ghostty-vt is in the build; stb_image is then
/// compiled without them, and without the inflate only its PNG used
/// (build.zig, docs/shared-libs.md). Other formats, and builds without
/// ghostty-vt, are stb_image's.
const wuffs_images = @hasDecl(@import("pardes_config"), "wuffs_images") and @import("pardes_config").wuffs_images;
const wuffs = if (wuffs_images) @import("wuffs") else struct {};

const Format = enum { png, jpeg, other };

fn format(bytes: []const u8) Format {
    if (std.mem.startsWith(u8, bytes, "\x89PNG\r\n\x1a\n")) return .png;
    if (bytes.len >= 3 and bytes[0] == 0xff and bytes[1] == 0xd8 and bytes[2] == 0xff) return .jpeg;
    return .other;
}

const Size = struct { w: usize, h: usize };

/// An image's size from its header alone, before anything is decoded.
fn headerSize(bytes: []const u8) ?Size {
    if (comptime wuffs_images) switch (format(bytes)) {
        .png => {
            // The signature, then IHDR first: length, type, width, height.
            if (bytes.len < 24 or !std.mem.eql(u8, bytes[12..16], "IHDR")) return null;
            return .{ .w = std.mem.readInt(u32, bytes[16..20], .big), .h = std.mem.readInt(u32, bytes[20..24], .big) };
        },
        .jpeg => return jpegSize(bytes),
        .other => {},
    };
    var iw: c_int = 0;
    var ih: c_int = 0;
    var ic: c_int = 0;
    if (!stbiInfo(bytes, &iw, &ih, &ic)) return null;
    return .{ .w = @intCast(@max(0, iw)), .h = @intCast(@max(0, ih)) };
}

/// A JPEG's size, from its first start-of-frame segment (any SOFn but the
/// DHT, JPG and DAC markers that share their range).
fn jpegSize(bytes: []const u8) ?Size {
    var at: usize = 2;
    while (at + 4 <= bytes.len) {
        if (bytes[at] != 0xff) return null;
        const marker = bytes[at + 1];
        // Fill bytes, and the markers that stand alone.
        if (marker == 0xff) {
            at += 1;
            continue;
        }
        if (marker == 0x01 or (marker >= 0xd0 and marker <= 0xd7)) {
            at += 2;
            continue;
        }
        const len = std.mem.readInt(u16, bytes[at + 2 ..][0..2], .big);
        if (len < 2) return null;
        const sof = marker >= 0xc0 and marker <= 0xcf and marker != 0xc4 and marker != 0xc8 and marker != 0xcc;
        if (sof) {
            if (at + 9 > bytes.len) return null;
            return .{ .w = std.mem.readInt(u16, bytes[at + 7 ..][0..2], .big), .h = std.mem.readInt(u16, bytes[at + 5 ..][0..2], .big) };
        }
        if (marker == 0xda) return null; // scan data before any frame
        at += 2 + len;
    }
    return null;
}

/// Whether `bytes` are an image `decode` can read, from its header alone.
pub fn readable(bytes: []const u8) bool {
    if (bytes.len == 0 or bytes.len > std.math.maxInt(c_int)) return false;
    var w: c_int = 0;
    var h: c_int = 0;
    var c: c_int = 0;
    if (!started) return true; // ponytail: no stb_image yet (a unit test), so no judging
    if (comptime wuffs_images) if (format(bytes) != .other) return headerSize(bytes) != null;
    return stbiInfo(bytes, &w, &h, &c);
}

/// decode + downscale to RGBA, gpa-owned. Returns null on any failure — the
/// pane then simply shows a blank body.
const Decoded = struct { rgba: []u8, w: usize, h: usize };

pub fn decode(gpa: std.mem.Allocator, bytes: []const u8) ?Decoded {
    // stb_image allocates through what `start` gave it: before that, a call
    // jumps through a null pointer (a terminal's PNG in a core no shell set up).
    if (!started) return null;
    if (bytes.len == 0 or bytes.len > std.math.maxInt(c_int)) return null;
    // Bounded before decoding: a few KB of PNG can name gigapixels.
    const size = headerSize(bytes) orelse return null;
    const pixels = std.math.mul(usize, size.w, size.h) catch return null;
    if (pixels > @import("memory.zig").limits.image_decode_pixels) return null;
    if (comptime wuffs_images) switch (format(bytes)) {
        inline .png, .jpeg => |f| {
            const got = @field(wuffs, @tagName(f)).decode(gpa, bytes) catch return null;
            defer gpa.free(got.data);
            if (got.data.len != @as(usize, got.width) * got.height * 4) return null;
            return finish(gpa, .{
                .data = got.data,
                .width = got.width,
                .height = got.height,
                .num_components = 4,
                .bytes_per_component = 1,
                .bytes_per_row = got.width * 4,
                .is_hdr = false,
            });
        },
        .other => {},
    };
    var img = zstbi.Image.loadFromMemory(bytes, 4) catch return null; // 4 = RGBA
    defer img.deinit();
    return finish(gpa, img);
}

/// The decoded RGBA, scaled to MAX_DIM at most, in a gpa copy.
fn finish(gpa: std.mem.Allocator, img: zstbi.Image) ?Decoded {
    var scaled: ?zstbi.Image = null;
    defer if (scaled) |*s| s.deinit();
    const longest = @max(img.width, img.height);
    const src: *const zstbi.Image = if (longest > MAX_DIM) blk: {
        const nw = @max(1, img.width * MAX_DIM / longest);
        const nh = @max(1, img.height * MAX_DIM / longest);
        scaled = img.resize(nw, nh);
        break :blk &scaled.?;
    } else &img;
    const rgba = gpa.dupe(u8, src.data) catch return null;
    return .{ .rgba = rgba, .w = src.width, .h = src.height };
}

test "PNG and JPEG decode through wuffs, sized from their headers first; other formats through stb_image" {
    const gpa = std.testing.allocator;
    start(std.testing.io, gpa);
    defer stop();
    const dec = std.base64.standard.Decoder;
    const Fixture = struct { b64: []const u8, w: usize, h: usize, rgb: [3]u8, tolerance: u8 };
    const fixtures = [_]Fixture{
        // 4x2, red left, blue right (a hand-built PNG).
        .{ .b64 = "iVBORw0KGgoAAAANSUhEUgAAAAQAAAACCAIAAADwyuo0AAAAE0lEQVR4nGP4z8AARGDiPwMyBwBnsgf5Q2OaZwAAAABJRU5ErkJggg==", .w = 4, .h = 2, .rgb = .{ 255, 0, 0 }, .tolerance = 0 },
        // 16x8 of (200,30,30), baseline and progressive (Pillow, quality 95).
        .{ .b64 = "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAIBAQEBAQIBAQECAgICAgQDAgICAgUEBAMEBgUGBgYFBgYGBwkIBgcJBwYGCAsICQoKCgoKBggLDAsKDAkKCgr/2wBDAQICAgICAgUDAwUKBwYHCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgr/wAARCAAIABADASIAAhEBAxEB/8QAHwAAAQUBAQEBAQEAAAAAAAAAAAECAwQFBgcICQoL/8QAtRAAAgEDAwIEAwUFBAQAAAF9AQIDAAQRBRIhMUEGE1FhByJxFDKBkaEII0KxwRVS0fAkM2JyggkKFhcYGRolJicoKSo0NTY3ODk6Q0RFRkdISUpTVFVWV1hZWmNkZWZnaGlqc3R1dnd4eXqDhIWGh4iJipKTlJWWl5iZmqKjpKWmp6ipqrKztLW2t7i5usLDxMXGx8jJytLT1NXW19jZ2uHi4+Tl5ufo6erx8vP09fb3+Pn6/8QAHwEAAwEBAQEBAQEBAQAAAAAAAAECAwQFBgcICQoL/8QAtREAAgECBAQDBAcFBAQAAQJ3AAECAxEEBSExBhJBUQdhcRMiMoEIFEKRobHBCSMzUvAVYnLRChYkNOEl8RcYGRomJygpKjU2Nzg5OkNERUZHSElKU1RVVldYWVpjZGVmZ2hpanN0dXZ3eHl6goOEhYaHiImKkpOUlZaXmJmaoqOkpaanqKmqsrO0tba3uLm6wsPExcbHyMnK0tPU1dbX2Nna4uPk5ebn6Onq8vP09fb3+Pn6/9oADAMBAAIRAxEAPwD5Dooor8LP9VD/2Q==", .w = 16, .h = 8, .rgb = .{ 200, 30, 30 }, .tolerance = 6 },
        .{ .b64 = "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAIBAQEBAQIBAQECAgICAgQDAgICAgUEBAMEBgUGBgYFBgYGBwkIBgcJBwYGCAsICQoKCgoKBggLDAsKDAkKCgr/2wBDAQICAgICAgUDAwUKBwYHCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgr/wgARCAAIABADASIAAhEBAxEB/8QAFQABAQAAAAAAAAAAAAAAAAAAAAf/xAAVAQEBAAAAAAAAAAAAAAAAAAAGCP/aAAwDAQACEAMQAAABkIC1V//EABQQAQAAAAAAAAAAAAAAAAAAABD/2gAIAQEAAQUCP//EABQRAQAAAAAAAAAAAAAAAAAAAAD/2gAIAQMBAT8Bf//EABQRAQAAAAAAAAAAAAAAAAAAAAD/2gAIAQIBAT8Bf//EABQQAQAAAAAAAAAAAAAAAAAAABD/2gAIAQEABj8CP//EABQQAQAAAAAAAAAAAAAAAAAAABD/2gAIAQEAAT8hP//aAAwDAQACAAMAAAAQA//EABQRAQAAAAAAAAAAAAAAAAAAAAD/2gAIAQMBAT8Qf//EABQRAQAAAAAAAAAAAAAAAAAAAAD/2gAIAQIBAT8Qf//EABQQAQAAAAAAAAAAAAAAAAAAABD/2gAIAQEAAT8QP//Z", .w = 16, .h = 8, .rgb = .{ 200, 30, 30 }, .tolerance = 6 },
    };
    for (fixtures) |f| {
        const bytes = try gpa.alloc(u8, try dec.calcSizeForSlice(f.b64));
        defer gpa.free(bytes);
        try dec.decode(bytes, f.b64);
        try std.testing.expect(readable(bytes));
        const size = headerSize(bytes).?;
        try std.testing.expectEqual(Size{ .w = f.w, .h = f.h }, size);
        const got = decode(gpa, bytes) orelse return error.NotDecoded;
        defer gpa.free(got.rgba);
        try std.testing.expectEqual(f.w, got.w);
        try std.testing.expectEqual(f.h, got.h);
        for (got.rgba[0..3], f.rgb) |have, want| try std.testing.expect(@max(have, want) - @min(have, want) <= f.tolerance);
        try std.testing.expectEqual(@as(u8, 255), got.rgba[3]);
    }
    // A PPM still goes through stb_image.
    const ppm = "P6\n2 1\n255\n\x0d\x4d\xe7\x0d\x4d\xe7";
    try std.testing.expectEqual(Format.other, format(ppm));
    const got = decode(gpa, ppm) orelse return error.NotDecoded;
    defer gpa.free(got.rgba);
    try std.testing.expectEqualSlices(u8, &.{ 0x0d, 0x4d, 0xe7, 255 }, got.rgba[0..4]);
    // Truncated headers are no image, never a read past the end.
    try std.testing.expect(headerSize("\x89PNG\r\n\x1a\n\x00\x00") == null);
    try std.testing.expect(headerSize("\xff\xd8\xff\xe0\x00\x10JFIF") == null);
    try std.testing.expect(decode(gpa, "\xff\xd8\xff\xe0\x00\x10JFIF") == null);
}

// ---- the image pane ----

pub const State = struct {
    /// What the replay digest leaves out (src/walk.zig): the picture as
    /// decoded from its bytes, off the loop as the render first wants it.
    pub const replica = .{ .derived = .{ "tried", "rgba", "iw", "ih", "decoder", "decoded", "answer" } };
    path: []u8,
    /// Petscii, Palette and Ascii: how a frontend draws the picture as
    /// glyph art (`Placement.Art`), which the core never does.
    glyph_art: bool = false,
    pmode: PaletteMode = .commodore,
    ascii: bool = true,
    tried: bool = false,
    rgba: []u8 = &.{},
    iw: usize = 0,
    ih: usize = 0,
    /// Dump-loaded bytes, decoded lazily by the same path as a disk image.
    raw: []u8 = &.{},
    /// The decode under way off the loop (ensureDecoded), and its answer.
    decoder: ?std.Thread = null,
    decoded: std.atomic.Value(bool) = .init(false),
    answer: ?Decoded = null,

    pub fn deinit(state: *State, gpa: std.mem.Allocator) void {
        if (state.decoder) |t| t.join();
        if (state.answer) |a| gpa.free(a.rgba);
        gpa.free(state.path);
        if (state.rgba.len > 0) gpa.free(state.rgba);
        if (state.raw.len > 0) gpa.free(state.raw);
        state.* = undefined;
    }
};

/// Construct an image pane from a path and optionally transferred dump bytes.
/// `raw` must be image_gpa-owned and ownership transfers only on success.
/// Without them the file is read here, not at the first draw: a draw
/// must not go out into the host (`pardes.turn`), and the path may be a
/// mount this editor serves. A file that cannot be read draws blank.
pub fn create(p: *pardes.Pardes, id: usize, path: []const u8, raw: []u8) !*pardes.Pane {
    var bytes = raw;
    var read_here = false;
    if (bytes.len == 0) {
        // The slot stays ours across the read: another request may
        // make a pane meanwhile.
        p.reserved_slots[id] = true;
        defer p.reserved_slots[id] = false;
        if (filesystem.read(p, path)) |from_disk| {
            defer p.gpa.free(from_disk);
            bytes = try p.image_gpa.dupe(u8, from_disk);
            read_here = true;
        } else |_| {}
    }
    errdefer if (read_here) p.image_gpa.free(bytes);
    const path_copy = try p.image_gpa.dupe(u8, path);
    errdefer p.image_gpa.free(path_copy);
    const pane = try p.newDocPane(id);
    pane.image = .{ .path = path_copy, .raw = bytes };
    return pane;
}

/// Image renderer choices are pane-local, not global Config values. Keep them
/// queryable where they apply: the live tag beside the image's path.
/// `glyphs`: whether the picture is drawn as glyph art, which a terminal
/// with no graphics does whatever `glyph_art` says.
pub fn tagPrefix(arena: std.mem.Allocator, state: *const State, glyphs: bool) ![]u8 {
    return std.fmt.allocPrint(
        arena,
        "{s} petscii:{s} palette:{s} ascii:{s} {s}",
        .{
            config.tag_image,
            if (glyphs) "on" else "off",
            @tagName(state.pmode),
            if (state.ascii) "on" else "off",
            state.path,
        },
    );
}

/// The picture decoded off the loop: the first draw starts a thread and
/// draws the pane without it (its tag and frame at once); the frames after
/// it look (Pardes.nextWake asks for them) and the picture lands on the
/// first one after the decode (80 ms in ReleaseSafe, 290 in Debug, for the
/// docs' screenshot: all of it once on the frame before).
/// ponytail: a thread a picture; a pool if many open at once.
fn ensureDecoded(p: *pardes.Pardes, state: *State) void {
    if (state.decoder) |t| {
        if (!state.decoded.load(.acquire)) return;
        t.join();
        state.decoder = null;
    }
    if (state.answer) |decoded| {
        state.answer = null;
        state.rgba = decoded.rgba;
        state.iw = decoded.w;
        state.ih = decoded.h;
    }
    if (state.tried) return;
    state.tried = true;
    if (state.raw.len == 0) return; // nothing was readable at open
    const Work = struct {
        fn run(gpa: std.mem.Allocator, st: *State) void {
            st.answer = decode(gpa, st.raw);
            st.decoded.store(true, .release);
        }
    };
    if (comptime !builtin.is_test) {
        if (std.Thread.spawn(.{}, Work.run, .{ p.image_gpa, state })) |t| {
            state.decoder = t;
            return;
        } else |_| {}
    }
    Work.run(p.image_gpa, state);
    ensureDecoded(p, state);
}

/// The picture over the body's cells, left for the frontend to fit (or
/// to draw as glyph art).
pub fn draw(p: *pardes.Pardes, state: *State, pane_id: u8, serial: u32, x: u16, y: u16, cols: u16, rows: u16) void {
    ensureDecoded(p, state);
    if (state.rgba.len == 0 or cols == 0 or rows == 0) return;
    _ = p.appendPlacement(.{
        .pane = pane_id,
        .raster = .of(state.rgba, state.iw, state.ih),
        .src = .{ .w = @intCast(state.iw), .h = @intCast(state.ih) },
        .dst = .{ .x = x, .y = y, .w = cols, .h = rows },
        .key = pardes.Placement.keyOf(serial, 0, 0),
        .art = .{ .glyph = state.glyph_art, .palette = state.pmode, .ascii = state.ascii },
    });
}