From 71e5a0f4a8685b385fac762995d45575b638179f Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Thu, 5 Nov 2026 22:21:45 -0300 Subject: kinds #1, the paint contract: a picture over the cells is one Placement (raster: ptr, w, h, stride; src in pixels; dst in the frame's cells; at, where in them in pixels, or none for the frontend to fit; key, the pixels' identity by pane serial, page and revision; a terminal program's kitty z; dirty, the rows changed since an older key; art, the pane's Petscii, Palette and Ascii), where ImagePlace carried native.{revision, page, fit, pan_x, pan_y, geometry, pixel_offset_y, paper_bg, exact}, cell rects and an ImageCacheKey of three shapes by build; a PDF strip's scroll is its body region's scroll_px, whose fraction the window draws as pixel_offset_y was; glyph art leaves the core for src/Art.zig, the frontends' (the matcher, both palettes and a cache by key, ex image.zig's GlyphArt and TerminalImages' glyph cache): the core always hands an image pane, a PDF's pages and a terminal's kitty images as placements, whatever the frontend shows, and the tty draws them as glyph art without kitty graphics or when the pane asks, the window when the pane asks; the four words set the same pane bytes as before and the frontend reads them off the placement, so config.zig, builtins.zig and exec.zig are untouched; /screen lists a frame's placements as images (only a frame with pictures has the field); no golden changes: the snapshot goldens are the tty's, which draws the same art (images.snap and tagbottomimage.snap pass unchanged, and the tty's bytes for an image, its Palette and its Ascii are byte-identical to the base's), no /screen golden holds a picture, and the window's goldens hash the same; tests: kitty.zig's glyph-art case becomes its core half (a placement over the 8x4 cells, the cells the pane's) with the art in tui.zig's own test, terminal.zig's glyph-art case the same, surface.zig's two ImageCacheKey cases one keyOf case, the GlyphArt cases move to Art.zig with a frame case; gates: core-test 959/959, behaviour-test 244/244, unit-test 1486/1487 tui and 1530/1531 gui, pane-test 171/172, snap all ok, process-test 0 of 37 failed on both, hxdiff 19 and hxparity 6 mismatches by the base's names, replicas, gui-golden, monkey-gui, kitty-test 44/44, kitty-harness and image-harness on both, daemon.py main and window-clients Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_016Y9MNAtZenFv4weoMD3cge --- src/surface.zig | 180 ++++++++++++++++++++++---------------------------------- 1 file changed, 71 insertions(+), 109 deletions(-) (limited to 'src/surface.zig') diff --git a/src/surface.zig b/src/surface.zig index 3716df4f..ef1679a5 100644 --- a/src/surface.zig +++ b/src/surface.zig @@ -7,12 +7,10 @@ const uucode = @import("uucode"); const vaxis = @import("vaxis"); const panes = @import("panes.zig"); const config = @import("config.zig"); -const pdf_enabled = panes.Pdf.enabled; const image = @import("image.zig"); const MAX_PANES = pardes.MAX_PANES; const Layer = @import("Layer.zig"); const MAX_TAG_LAYERS = pardes.MAX_TAG_LAYERS; -const CellPixels = pardes.CellPixels; pub const Color = union(enum) { default, index: u8, rgb: [3]u8 }; @@ -72,123 +70,83 @@ test "cell visual equality ignores dead grapheme tail bytes" { try std.testing.expect(a.visuallyEqual(&b)); } -pub const ImageCacheKey = if (pdf_enabled) struct { - serial: u32, - page: u32, - revision: u32, +/// A rectangle in pixels. +pub const RectPx = image.PixelRect; - pub fn eql(a: @This(), b: @This()) bool { - return a.serial == b.serial and a.page == b.page and - a.revision == b.revision; +/// A rectangle in the frame's cells. +pub const RectCell = struct { x: u16 = 0, y: u16 = 0, w: u16 = 0, h: u16 = 0 }; + +/// The pixels a placement shows: RGBA, straight alpha, `stride` bytes a +/// row. They are the pane's, and stay put until its next frame. +pub const Raster = struct { + ptr: [*]const u8, + w: u32, + h: u32, + stride: u32, + + pub fn of(rgba: []const u8, w: usize, h: usize) Raster { + return .{ .ptr = rgba.ptr, .w = @intCast(w), .h = @intCast(h), .stride = @intCast(w * 4) }; } -} else struct { - serial: u32, - pub fn eql(a: @This(), b: @This()) bool { - return a.serial == b.serial; + pub fn bytes(r: Raster) []const u8 { + return r.ptr[0 .. @as(usize, r.stride) * r.h]; } }; -/// Dynamic placement exists only for native PDF pages. Static image panes need -/// only their pane identity, so feature-off builds carry a zero-bit payload. -pub const NativePlacement = if (pdf_enabled) struct { - revision: u32 = 0, - page: u32 = 0, - fit: image.NativeFit = .contain, - pan_x: u16 = 0, - pan_y: u16 = 0, - /// Continuous-document pages supply their already-clipped geometry. - /// Static images and legacy callers leave this null and derive fit/pan. - geometry: ?image.NativeGeometry = null, - /// Subpixel vertical displacement retained from proportional SDL wheel dy. - pixel_offset_y: f32 = 0, - /// Separate paper behind straight-alpha PDF content; null for other images. - paper_bg: ?[3]u8 = null, - /// `geometry` is the whole of it: `src` drawn into `dst`, scaled as - /// it says. A terminal pane's kitty graphics come this way, one cell - /// row at a time, already clipped (TerminalImages.zig). - exact: bool = false, -} else struct {}; - -pub const ImagePatch = struct { from: u32, y: u32, h: u32 }; - -pub const ImagePlace = struct { +/// A picture over the frame's cells, which a frontend realises: the window +/// as a texture kept by `key`, the tty as a kitty image, or either as glyph +/// art in `dst`'s cells (Art.zig, the frontends' own) where it cannot show +/// pixels or the pane asks for art. The frame lists them a pane at a time, +/// lowest first. +pub const Placement = struct { pane: u8, - /// Pane slots are reused. This identity makes a cached GPU texture or - /// kitty image unambiguously belong to the pane which supplied the bytes. - serial: u32, - native: NativePlacement = .{}, - x: u16, - y: u16, - w: u16, - h: u16, - rgba: []const u8, - iw: usize, - ih: usize, - /// A terminal's kitty graphics stacking order (`z=`): the surface lists - /// a pane's images lowest first, so a shell drawing them in order puts - /// a higher one over a lower; below 0 the program means it under the - /// text, which the tty passes on to the outer terminal (the GUI draws - /// every image over the cells still). 0 for every other image. + raster: Raster, + /// The part of `raster` shown. + src: RectPx, + /// The cells it lies over, which clip it. + dst: RectCell, + /// Where it goes in `dst`, in pixels from `dst`'s top left corner; + /// null: the frontend fits `src` there, no larger than it is, at the + /// top left (as glyph art, centred). + at: ?RectPx = null, + /// The pixels' identity (`keyOf`): one key is one picture, so a + /// frontend keeps what it uploaded under it. + key: u64, + /// A terminal program's kitty `z=`: below 0 it is under the text, + /// which a tty passes on to the terminal outside. z: i32 = 0, - /// Rows [y, y+h) of `rgba` are the only ones that differ from the - /// same pane page at revision `from`: a shell still holding that one may - /// update just these rows instead of taking the whole image again. - patch: ?ImagePatch = null, - - pub fn cacheKey(place: ImagePlace) ImageCacheKey { - if (comptime pdf_enabled) - return .{ - .serial = place.serial, - .page = place.native.page, - .revision = place.native.revision, - }; - return .{ .serial = place.serial }; - } -}; + /// Rows of `raster` that alone differ from the picture under the key + /// `from`: a frontend still holding that one updates those rows. + dirty: ?Dirty = null, + art: Art = .{}, + + pub const Dirty = struct { from: u64, y: u32, h: u32 }; + + /// How the pane wants it drawn as glyph art: the Petscii, Palette and + /// Ascii words on an image pane, Petscii and TermImages on a terminal. + pub const Art = struct { + /// Glyph art even where pixels could be shown (Petscii on). + glyph: bool = false, + palette: Palette = .commodore, + /// Letters and signs among the glyphs, not only blocks and lines. + ascii: bool = true, + + pub const Palette = enum { commodore, terminal }; + }; -test "pixel attachment cache key follows both pane lifetime and rendered revision" { - if (comptime pdf_enabled) { - const first = ImageCacheKey{ .serial = 41, .page = 7, .revision = 3 }; - try std.testing.expect(first.eql(.{ .serial = 41, .page = 7, .revision = 3 })); - try std.testing.expect(!first.eql(.{ .serial = 41, .page = 8, .revision = 3 })); - try std.testing.expect(!first.eql(.{ .serial = 41, .page = 7, .revision = 4 })); - try std.testing.expect(!first.eql(.{ .serial = 42, .page = 7, .revision = 3 })); - } else { - const first = ImageCacheKey{ .serial = 41 }; - try std.testing.expect(first.eql(.{ .serial = 41 })); - try std.testing.expect(!first.eql(.{ .serial = 42 })); + /// A pane's picture `page` (a PDF's page, a terminal's image id; 0 for + /// an image) as of `revision`. + pub fn keyOf(serial: u32, page: u32, revision: u32) u64 { + return std.hash.Wyhash.hash(0, std.mem.asBytes(&[3]u32{ serial, page, revision })); } - try std.testing.expectEqual(pdf_enabled, @hasField(ImageCacheKey, "revision")); - try std.testing.expectEqual(pdf_enabled, @hasField(NativePlacement, "fit")); - try std.testing.expectEqual(pdf_enabled, @hasField(CellPixels, "w")); - if (comptime !pdf_enabled) { - try std.testing.expectEqual(@as(usize, 4), @sizeOf(ImageCacheKey)); - try std.testing.expectEqual(@as(usize, 0), @sizeOf(NativePlacement)); - try std.testing.expectEqual(@as(usize, 0), @sizeOf(CellPixels)); - try std.testing.expectEqual(@as(usize, 0), @sizeOf(panes.Pdf.PointerDrag)); - } -} +}; -test "pixel attachment fit and pan do not invalidate cached pixels" { - if (comptime !pdf_enabled) return; - var place = ImagePlace{ - .pane = 0, - .serial = 41, - .native = .{ .revision = 3 }, - .x = 0, - .y = 0, - .w = 1, - .h = 1, - .rgba = &.{ 0, 0, 0, 255 }, - .iw = 1, - .ih = 1, - }; - const key = place.cacheKey(); - place.native.fit = .width; - place.native.pan_x = 1234; - place.native.pan_y = 65535; - try std.testing.expect(key.eql(place.cacheKey())); +test "a placement's key follows its pane, its page and the revision of its pixels, and nothing of where it goes" { + const first = Placement.keyOf(41, 7, 3); + try std.testing.expectEqual(first, Placement.keyOf(41, 7, 3)); + try std.testing.expect(first != Placement.keyOf(41, 8, 3)); + try std.testing.expect(first != Placement.keyOf(41, 7, 4)); + try std.testing.expect(first != Placement.keyOf(42, 7, 3)); } /// One part of the frame and where it is, placed once by `draw.place` @@ -250,6 +208,10 @@ pub const Region = struct { /// 0 for a terminal or a picture), which a frontend's glide follows. line: i32 = 0, doc: u64 = 0, + /// A body drawn as a strip of pictures (a PDF): how far down the strip + /// it shows, in pixels. Its placements are laid at the whole pixel; a + /// pixel frontend draws them the fraction higher. + scroll_px: f64 = 0, /// Cells the column-move rail takes off the right edge while it runs /// there: layers and pixel shells stop short of them, the grid does not. clip: u16 = 0, @@ -322,7 +284,7 @@ pub const Surface = struct { cells: []Cell = &.{}, /// bar: draw an insert-style thin cursor instead of the block cursor: ?struct { x: u16, y: u16, bar: bool = false } = null, - images: std.ArrayList(ImagePlace) = .empty, + placements: std.ArrayList(Placement) = .empty, pub fn tagLayers(s: *const Surface) []const Layer { return &s.tag_layers; -- cgit v1.3