summaryrefslogtreecommitdiff
path: root/src/term/TerminalImages.zig
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-16 23:37:14 -0300
committerGabriel Schneider <[email protected]>2026-11-17 12:15:01 -0300
commite4fbb97a506ca2a4b469b6e2e13ecba6e516272c (patch)
tree9872f6ecfea4192c88e49e3439061a686bd6d9ed /src/term/TerminalImages.zig
parentf25313ebb776aa4cca2dfbc49d3d3ff96dae161d (diff)
downloadpardes-e4fbb97a506ca2a4b469b6e2e13ecba6e516272c.tar.gz
pardes-e4fbb97a506ca2a4b469b6e2e13ecba6e516272c.zip
term: the terminal's own files move into src/term/ (terminal.zig, screen_state.zig, echo.zig, TerminalImages.zig), as they are: names and signatures kept, only the import paths change (theirs to ../, pardes.zig's, panes.zig's, tape.zig's, replica.zig's and Kind.zig's to term/), the comments that name them by path follow, and the embedded sources serve terminal.zig at src/term/terminal.zig; the first step of docs/next-terminal.md's Phase 0, a move, nothing else
Diffstat (limited to 'src/term/TerminalImages.zig')
-rw-r--r--src/term/TerminalImages.zig380
1 files changed, 380 insertions, 0 deletions
diff --git a/src/term/TerminalImages.zig b/src/term/TerminalImages.zig
new file mode 100644
index 00000000..6894945c
--- /dev/null
+++ b/src/term/TerminalImages.zig
@@ -0,0 +1,380 @@
+//! A terminal pane's kitty graphics: the images its program sent (yazi's
+//! previews, `kitten icat`) drawn where it placed them. ghostty-vt keeps
+//! the images and placements; this reads them each frame, cuts each one
+//! into the cell rows it covers, clipped to the rows the pane shows, and
+//! hands them on as placements, each at its exact pixels: a frontend draws
+//! them, or draws them as glyph art (Art.zig), as an image pane's.
+//! Both kinds of placement are drawn: one on a cell (`a=T`/`a=p`), which
+//! moves with the text it was put on, and a virtual one (`U=1`) shown
+//! through the U+10EEEE placeholder cells the program prints.
+const std = @import("std");
+const ghostty_vt = @import("ghostty-vt");
+const pardes = @import("../pardes.zig");
+const zstbi = @import("zstbi");
+const wuffs = @import("wuffs");
+
+const TerminalImages = @This();
+const gfx = ghostty_vt.kitty.graphics;
+const PixelRect = @import("../surface.zig").RectPx;
+
+/// The bytes ghostty-vt may hold for one screen's images (it evicts the
+/// oldest past this): a 4K picture in RGBA, with room for a second.
+pub const storage_limit = 64 * 1024 * 1024;
+
+/// This pane asks for its images as glyph art even where pixels could be
+/// drawn (the Petscii builtin).
+petscii: bool = false,
+/// Pixels in RGBA for images ghostty-vt holds in another format (RGB,
+/// grey): only for images on screen, dropped the frame they are not.
+converted: std.AutoHashMapUnmanaged(u32, Converted) = .empty,
+/// When the next frame of a playing animation (a=a) is due, in ms on the
+/// core's clock (`Pardes.stepped_ns`): the core wakes for it (nextWake).
+animation_due_ms: ?u64 = null,
+
+const Converted = struct { generation: u64, rgba: []u8, used: bool = true };
+
+/// One image's rectangle in the pane, in pixels from the viewport's top
+/// left corner (above or left of it is negative).
+const Rect = struct { x: i64, y: i64, w: i64, h: i64 };
+
+/// The runs of Kitty placeholder cells between two pins, one row's run at a
+/// time, as ghostty's own `kitty.graphics.unicode.placementIterator` gave
+/// them before it moved into its RenderState, which pardes does not keep.
+const PlaceholderRuns = struct {
+ rows: ghostty_vt.PageList.RowIterator,
+ row: ?ghostty_vt.Pin,
+ /// Where the scan of `row` resumes: a run ended by an incompatible
+ /// placeholder starts the next one there.
+ x: usize = 0,
+
+ fn init(top: ghostty_vt.Pin, bottom: ghostty_vt.Pin) PlaceholderRuns {
+ var rows = top.rowIterator(.right_down, bottom);
+ const row = rows.next();
+ return .{ .rows = rows, .row = row };
+ }
+
+ fn next(self: *PlaceholderRuns) ?gfx.unicode.Placement {
+ while (self.row) |row| {
+ if (!row.rowAndCell().row.kitty_virtual_placeholder) {
+ self.advance();
+ continue;
+ }
+ var run: ?gfx.unicode.IncompletePlacement = null;
+ var first: usize = 0;
+ const cells = row.cells(.all);
+ while (self.x < cells.len) : (self.x += 1) {
+ const cell = &cells[self.x];
+ if (cell.codepoint() != gfx.unicode.placeholder) {
+ if (run) |done| return complete(row, first, done);
+ continue;
+ }
+ const style = row.style(cell);
+ const curr: gfx.unicode.IncompletePlacement = .init(&style, row.grapheme(cell) orelse &.{});
+ if (run) |*prev| {
+ if (!prev.append(&curr)) return complete(row, first, prev.*);
+ } else {
+ run = curr.start();
+ first = self.x;
+ }
+ }
+ self.advance();
+ if (run) |done| return complete(row, first, done);
+ }
+ return null;
+ }
+
+ fn advance(self: *PlaceholderRuns) void {
+ self.row = self.rows.next();
+ self.x = 0;
+ }
+
+ fn complete(row: ghostty_vt.Pin, x: usize, run: gfx.unicode.IncompletePlacement) gfx.unicode.Placement {
+ var pin = row;
+ pin.x = @intCast(x);
+ return .{
+ .pin = pin,
+ .image_id = run.imageId(),
+ .placement_id = run.placement_id orelse 0,
+ .col = run.col.?,
+ .row = run.row.?,
+ .width = run.width,
+ .height = 1,
+ };
+ }
+};
+
+pub fn deinit(ti: *TerminalImages, gpa: std.mem.Allocator) void {
+ var conv = ti.converted.valueIterator();
+ while (conv.next()) |c| gpa.free(c.rgba);
+ ti.converted.deinit(gpa);
+}
+
+/// Accept PNG (`f=100`) as well as raw pixels: ghostty-vt built as a
+/// library decodes none itself. wuffs does it (ghostty's, linked for it).
+pub fn installPngDecoder() void {
+ ghostty_vt.sys.decode_png = &decodePng;
+}
+
+/// The longest side a PNG is kept at: a pane is at most a screenful of
+/// cells, and a multi-thousand-pixel picture only costs its memory.
+const max_dim: u32 = 1280;
+
+/// stb_image_resize has its allocator (`start`): before, a PNG is refused.
+var started = false;
+
+/// Once at startup and exit, with what the resize allocates from.
+pub fn start(gpa: std.mem.Allocator) void {
+ // Refused only when started twice with a resize still alive: PNGs then stay refused.
+ zstbi.init(gpa) catch return;
+ started = true;
+}
+pub fn stop() void {
+ started = false;
+ zstbi.deinit();
+}
+
+fn decodePng(gpa: std.mem.Allocator, bytes: []const u8) ghostty_vt.sys.DecodeError!ghostty_vt.sys.Image {
+ if (!started) return error.InvalidData;
+ // Bounded before decoding: a few KB of PNG can name gigapixels. The
+ // signature, then IHDR first: its length, type, width and height.
+ if (bytes.len < 24 or !std.mem.startsWith(u8, bytes, "\x89PNG\r\n\x1a\n") or !std.mem.eql(u8, bytes[12..16], "IHDR")) return error.InvalidData;
+ const w = std.mem.readInt(u32, bytes[16..20], .big);
+ const h = std.mem.readInt(u32, bytes[20..24], .big);
+ if (@as(u64, w) * h > pardes.memory.limits.image_decode_pixels) return error.InvalidData;
+ const got = wuffs.png.decode(gpa, bytes) catch return error.InvalidData;
+ if (got.data.len != @as(usize, got.width) * got.height * 4) {
+ gpa.free(got.data);
+ return error.InvalidData;
+ }
+ const longest = @max(got.width, got.height);
+ if (longest <= max_dim) return .{ .width = got.width, .height = got.height, .data = got.data };
+ defer gpa.free(got.data);
+ const img: zstbi.Image = .{ .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 };
+ var scaled = img.resize(@intCast(@max(1, @as(u64, got.width) * max_dim / longest)), @intCast(@max(1, @as(u64, got.height) * max_dim / longest))) catch return error.InvalidData;
+ defer scaled.deinit();
+ return .{ .width = scaled.width, .height = scaled.height, .data = gpa.dupe(u8, scaled.data) catch return error.InvalidData };
+}
+
+/// Draw the active screen's images. `rows_of[v]` is the body row the
+/// viewport's row `v` is shown on, if it is shown; `cols` how many of its
+/// columns the body shows, from `tx`.
+pub fn draw(
+ ti: *TerminalImages,
+ p: *pardes.Pardes,
+ s: *pardes.Surface,
+ vt: *ghostty_vt.Terminal,
+ pane_id: u8,
+ serial: u32,
+ tx: u16,
+ body_y: u16,
+ cols: u16,
+ rows_of: []const ?u16,
+) void {
+ var conv = ti.converted.valueIterator();
+ while (conv.next()) |c| c.used = false;
+ defer ti.prune(p.gpa);
+
+ const screen = vt.screens.active;
+ const storage = &screen.kitty_images;
+ // Animations step on the core's clock, as this frame shows them; the
+ // shown frame is `renderData()` (a new `generation` each step, which
+ // the caches key on).
+ const now_ms = p.clock.stepped_ns / std.time.ns_per_ms;
+ ti.animation_due_ms = if (storage.animationTick(vt.io(), now_ms)) |delay| now_ms +| delay else null;
+ const pages = &screen.pages;
+ const top = pages.getTopLeft(.viewport);
+ const bottom = pages.getBottomRight(.viewport) orelse return;
+ const cw: u32 = @max(1, p.view().cell_pixels.w);
+ const ch: u32 = @max(1, p.view().cell_pixels.h);
+ const ctx: Ctx = .{ .ti = ti, .p = p, .pane = pane_id, .serial = serial, .tx = tx, .body_y = body_y, .cols = cols, .rows_of = rows_of, .cw = cw, .ch = ch };
+ // Handed on lowest z first (the storage's order is a hash map's), the
+ // order a shell draws them in; equal z keeps the order they came in.
+ const first = s.placements.items.len;
+ defer std.sort.insertion(pardes.Placement, s.placements.items[first..], {}, struct {
+ fn lessThan(_: void, a: pardes.Placement, b: pardes.Placement) bool {
+ return a.z < b.z;
+ }
+ }.lessThan);
+
+ // Virtual placements: shown through the placeholder cells, one run of
+ // them on a row at a time. The placeholders themselves are not text.
+ var runs: PlaceholderRuns = .init(top, bottom);
+ while (runs.next()) |run| {
+ const at = pages.pointFromPin(.viewport, run.pin) orelse continue;
+ const v = at.viewport.y;
+ if (v >= rows_of.len) continue;
+ const row = rows_of[v] orelse continue;
+ for (@as(usize, at.viewport.x)..@as(usize, at.viewport.x) + run.width) |x| {
+ if (x >= cols) break;
+ const cell = s.at(tx + @as(u16, @intCast(x)), body_y + row);
+ cell.text[0] = ' ';
+ cell.len = 1;
+ }
+ const img = storage.imageById(run.image_id) orelse continue;
+ const target = storage.placeholderTarget(run.image_id, run.placement_id) orelse continue;
+ const rp = run.renderPlacement(&target.placement, &img, cw, ch) catch continue;
+ if (rp.dest_width == 0 or rp.dest_height == 0 or rp.source_width == 0 or rp.source_height == 0) continue;
+ ctx.place(img, target.placement.z, .{ .x = rp.source_x, .y = rp.source_y, .w = rp.source_width, .h = rp.source_height }, .{
+ .x = @as(i64, at.viewport.x) * cw + rp.offset_x,
+ .y = @as(i64, v) * ch + rp.offset_y,
+ .w = rp.dest_width,
+ .h = rp.dest_height,
+ });
+ }
+
+ // Placements on a cell: they move with the text they were put on, and
+ // go where it goes, above the viewport or off the screen.
+ const origin = pages.pointFromPin(.screen, top) orelse return;
+ var it = storage.placements.iterator();
+ while (it.next()) |entry| {
+ const placed = entry.value_ptr.*;
+ // A placement relative to another (P=/Q=) sits at its chain's root
+ // plus the chain's cell offsets (H=/V=), as ghostty's renderer puts it.
+ var dx: i64 = 0;
+ var dy: i64 = 0;
+ const pin = switch (placed.location) {
+ .pin => |pin| pin,
+ .virtual => continue,
+ .relative => |rel| root: {
+ const chain = storage.resolveChain(rel) orelse continue;
+ dx = chain.horizontal_offset;
+ dy = chain.vertical_offset;
+ break :root switch (chain.root.location) {
+ .pin => |pin| pin,
+ // ponytail: a chain rooted on a virtual placement (shown
+ // through placeholders) is not drawn; ghostty anchors it at
+ // the placeholder run.
+ .virtual, .relative => continue,
+ };
+ },
+ };
+ const img = storage.images.get(entry.key_ptr.image_id) orelse continue;
+ const at = pages.pointFromPin(.screen, pin.*) orelse continue;
+ const size = placed.pixelSize(img, vt);
+ const sx = @min(placed.source_x, img.width);
+ const sy = @min(placed.source_y, img.height);
+ const sw = if (placed.source_width > 0) @min(placed.source_width, img.width - sx) else img.width - sx;
+ const sh = if (placed.source_height > 0) @min(placed.source_height, img.height - sy) else img.height - sy;
+ if (size.width == 0 or size.height == 0 or sw == 0 or sh == 0) continue;
+ ctx.place(img, placed.z, .{ .x = sx, .y = sy, .w = sw, .h = sh }, .{
+ .x = (@as(i64, at.screen.x) + dx) * cw + placed.x_offset,
+ .y = (@as(i64, at.screen.y) - @as(i64, origin.screen.y) + dy) * ch + placed.y_offset,
+ .w = size.width,
+ .h = size.height,
+ });
+ }
+}
+
+const Ctx = struct {
+ ti: *TerminalImages,
+ p: *pardes.Pardes,
+ pane: u8,
+ serial: u32,
+ tx: u16,
+ body_y: u16,
+ cols: u16,
+ rows_of: []const ?u16,
+ cw: u32,
+ ch: u32,
+
+ /// Draw `src` of `img` over `dst`, one cell row of it at a time: a row
+ /// is shown, or not, or shown elsewhere, as the body lays it out.
+ fn place(ctx: Ctx, img: gfx.Image, z: i32, src: PixelRect, dst: Rect) void {
+ const cw: i64 = ctx.cw;
+ const ch: i64 = ctx.ch;
+ const x0 = @max(dst.x, 0);
+ const x1 = @min(dst.x + dst.w, @as(i64, ctx.cols) * cw);
+ if (x1 <= x0) return;
+ const rgba = ctx.ti.pixelsOf(ctx.p.gpa, img) orelse return;
+ const first_row = @divFloor(@max(dst.y, 0), ch);
+ const last_row = @min(@divFloor(dst.y + dst.h - 1, ch), @as(i64, @intCast(ctx.rows_of.len)) - 1);
+ var v = first_row;
+ while (v <= last_row) : (v += 1) {
+ const row = ctx.rows_of[@intCast(v)] orelse continue;
+ const y0 = @max(dst.y, v * ch);
+ const y1 = @min(dst.y + dst.h, (v + 1) * ch);
+ if (y1 <= y0) continue;
+ // The source pixels under this piece, by the same scale.
+ const piece: PixelRect = .{
+ .x = src.x + @as(u32, @intCast(@divFloor((x0 - dst.x) * src.w, dst.w))),
+ .y = src.y + @as(u32, @intCast(@divFloor((y0 - dst.y) * src.h, dst.h))),
+ .w = @max(1, @as(u32, @intCast(@divFloor((x1 - x0) * src.w, dst.w)))),
+ .h = @max(1, @as(u32, @intCast(@divFloor((y1 - y0) * src.h, dst.h)))),
+ };
+ const c0: u16 = @intCast(@divFloor(x0, cw));
+ const c1: u16 = @intCast(@divFloor(x1 + cw - 1, cw));
+ _ = ctx.p.appendPlacement(.{
+ .pane = ctx.pane,
+ .raster = .of(rgba, img.width, img.height),
+ .src = piece,
+ .dst = .{ .x = ctx.tx + c0, .y = ctx.body_y + row, .w = c1 - c0, .h = 1 },
+ .at = .{
+ .x = @intCast(x0 - @as(i64, c0) * cw),
+ .y = @intCast(y0 - v * ch),
+ .w = @intCast(x1 - x0),
+ .h = @intCast(y1 - y0),
+ },
+ .key = pardes.Placement.keyOf(ctx.serial, img.id, @truncate(img.generation)),
+ .z = z,
+ .art = .{ .glyph = ctx.ti.petscii },
+ });
+ }
+ }
+};
+
+/// The image's pixels as RGBA: its own bytes when it is held so.
+fn pixelsOf(ti: *TerminalImages, gpa: std.mem.Allocator, img: gfx.Image) ?[]const u8 {
+ const n = @as(usize, img.width) * img.height;
+ if (n == 0) return null;
+ const data = img.renderData().bytes() orelse return null;
+ if (img.format == .rgba) return if (data.len == n * 4) data else null;
+ const gop = ti.converted.getOrPut(gpa, img.id) catch return null;
+ if (gop.found_existing) {
+ if (gop.value_ptr.generation == img.generation) {
+ gop.value_ptr.used = true;
+ return gop.value_ptr.rgba;
+ }
+ gpa.free(gop.value_ptr.rgba);
+ _ = ti.converted.remove(img.id);
+ return ti.pixelsOf(gpa, img);
+ }
+ const out = convert(gpa, img, n) orelse {
+ _ = ti.converted.remove(img.id);
+ return null;
+ };
+ gop.value_ptr.* = .{ .generation = img.generation, .rgba = out };
+ return out;
+}
+
+fn convert(gpa: std.mem.Allocator, img: gfx.Image, n: usize) ?[]u8 {
+ const depth: usize = switch (img.format) {
+ .rgb => 3,
+ .gray_alpha => 2,
+ .gray => 1,
+ else => return null,
+ };
+ const data = img.renderData().bytes() orelse return null;
+ if (data.len != n * depth) return null;
+ const out = gpa.alloc(u8, n * 4) catch return null;
+ for (0..n) |i| {
+ const px = data[i * depth ..][0..depth];
+ out[i * 4 ..][0..4].* = switch (depth) {
+ 3 => .{ px[0], px[1], px[2], 255 },
+ 2 => .{ px[0], px[0], px[0], px[1] },
+ else => .{ px[0], px[0], px[0], 255 },
+ };
+ }
+ return out;
+}
+
+/// Drop what this frame did not draw: the caches hold only what is shown.
+fn prune(ti: *TerminalImages, gpa: std.mem.Allocator) void {
+ while (true) {
+ var conv = ti.converted.iterator();
+ const stale = while (conv.next()) |entry| {
+ if (!entry.value_ptr.used) break entry.key_ptr.*;
+ } else break;
+ gpa.free(ti.converted.get(stale).?.rgba);
+ _ = ti.converted.remove(stale);
+ }
+}