diff options
| author | Can Celik <ogulcancelik@gmail.com> | 2026-09-10 21:51:57 +0300 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2026-09-10 21:51:57 +0300 |
| commit | 425c86179791cd32e2d4ce0ae7f269940b4b0663 (patch) | |
| tree | e52c4383a6d69216cbe2a32638bf90841d7e2189 /vendor/libghostty-vt/src/terminal/kitty/graphics_animation.zig | |
| parent | 90e947a6e26e02f10ec7f1694c4eb5b78a86406b (diff) | |
chore: upgrade libghostty and preserve terminal behavior (#3906)
Diffstat (limited to 'vendor/libghostty-vt/src/terminal/kitty/graphics_animation.zig')
| -rw-r--r-- | vendor/libghostty-vt/src/terminal/kitty/graphics_animation.zig | 149 |
1 files changed, 149 insertions, 0 deletions
diff --git a/vendor/libghostty-vt/src/terminal/kitty/graphics_animation.zig b/vendor/libghostty-vt/src/terminal/kitty/graphics_animation.zig new file mode 100644 index 00000000..0822a451 --- /dev/null +++ b/vendor/libghostty-vt/src/terminal/kitty/graphics_animation.zig @@ -0,0 +1,149 @@ +//! Kitty graphics protocol animation support. +//! +//! https://sw.kovidgoyal.net/kitty/graphics-protocol/#animation +//! +//! An animation is a set of frames attached to an existing image. +//! Frame 1 (the "root frame") is the image's own base data. Frames +//! 2..N are stored here. Unlike Kitty, which stores frames as delta +//! rectangles in a disk cache and composes them lazily, we compose +//! every frame eagerly into a full image-sized RGBA buffer at load +//! time. This trades some memory for a much simpler model: a frame is +//! always ready to display and there are no reference chains to +//! maintain, coalesce, or garbage collect. Frame storage is bounded +//! by the same byte limit as image storage. +//! +//! To keep composition to a single pixel format, an image is +//! converted to RGBA the first time an animation command composes +//! into it, and all transmitted frame data is converted to RGBA +//! before composition. Blending an opaque (alpha=255) source pixel +//! degenerates to a copy, so this loses no information relative to +//! Kitty's separate RGB/RGBA paths. The pixel-level primitives +//! (conversion, fill, rectangle composition) live in +//! graphics_pixel.zig. + +const std = @import("std"); +const Allocator = std.mem.Allocator; + +/// The gap assigned to a newly created frame when the command doesn't +/// specify one (z omitted or z=0). Taken from Kitty (DEFAULT_GAP). +pub const default_gap_ms: u32 = 40; + +/// Animation state for a single image. Heap-allocated and owned by +/// the Image. This is created lazily by the first animation command that +/// needs it. +pub const Animation = struct { + /// The frames following the root frame: `frames.items[i]` is + /// protocol frame number `i + 2`. The root frame (frame 1) is the + /// image's base data and is not stored here. + frames: std.ArrayListUnmanaged(Frame) = .empty, + + /// The gap of the root frame in milliseconds. Zero means gapless: + /// the frame is skipped during playback. Kitty creates the root + /// frame with a zero gap; the client gives it one with a=a,r=1,z=N. + root_gap_ms: u32 = 0, + + /// The zero-based index of the frame currently displayed: 0 is + /// the root frame, i >= 1 is frames.items[i - 1]. + current_index: u32 = 0, + + /// Playback state. Every image starts stopped (client-driven). + state: State = .stopped, + + /// Maximum number of loops to play (0 = infinite). Set from the + /// a=a v key as v-1, per the protocol's off-by-one encoding. + max_loops: u32 = 0, + + /// Number of completed loops since playback started. + current_loop: u32 = 0, + + /// Timestamp in milliseconds (on the ticker's clock, see + /// ImageStorage.animationTick) when the current frame was shown. + /// Null means "not yet shown"; the next tick stamps it. + frame_shown_at_ms: ?u64 = null, + + pub const State = enum { + /// Not advancing; frames change only via a=a c=N (client-driven). + stopped, + /// Advancing, but playback parks on the last frame waiting + /// for more frames instead of looping (a=a s=2). + loading, + /// Advancing and looping (a=a s=3). + running, + }; + + pub const Frame = struct { + /// Fully composed pixel data, always image width * height * 4 + /// bytes of RGBA. + data: []u8, + + /// Milliseconds this frame is displayed before advancing. + /// Zero means gapless: skipped during playback. + gap_ms: u32, + }; + + pub fn deinit(self: *Animation, alloc: Allocator) void { + for (self.frames.items) |frame| alloc.free(frame.data); + self.frames.deinit(alloc); + } + + /// The total number of frames including the root frame. + pub fn frameCount(self: *const Animation) u32 { + return @intCast(self.frames.items.len + 1); + } + + /// The gap of the frame at the given zero-based index. + pub fn gapAt(self: *const Animation, index: u32) u32 { + if (index == 0) return self.root_gap_ms; + return self.frames.items[index - 1].gap_ms; + } + + /// Set the gap of the frame at the given zero-based index. + pub fn setGapAt(self: *Animation, index: u32, gap_ms: u32) void { + if (index == 0) { + self.root_gap_ms = gap_ms; + } else { + self.frames.items[index - 1].gap_ms = gap_ms; + } + } + + /// The sum of all frame gaps. An animation with a zero duration + /// (every frame gapless) never advances; this doubles as the + /// guard that keeps the gapless-skip loop in animationTick from + /// spinning forever, exactly like Kitty's animation_duration. + pub fn durationMs(self: *const Animation) u64 { + var total: u64 = self.root_gap_ms; + for (self.frames.items) |frame| total += frame.gap_ms; + return total; + } + + /// Bytes of frame data held by this animation, counted against + /// the image storage limit. + pub fn frameBytes(self: *const Animation) usize { + var total: usize = 0; + for (self.frames.items) |frame| total += frame.data.len; + return total; + } +}; + +test "animation gap helpers" { + const testing = std.testing; + const alloc = testing.allocator; + + var anim: Animation = .{}; + defer anim.deinit(alloc); + try anim.frames.append(alloc, .{ + .data = try alloc.alloc(u8, 4), + .gap_ms = 100, + }); + + try testing.expectEqual(@as(u32, 2), anim.frameCount()); + try testing.expectEqual(@as(u32, 0), anim.gapAt(0)); + try testing.expectEqual(@as(u32, 100), anim.gapAt(1)); + try testing.expectEqual(@as(u64, 100), anim.durationMs()); + try testing.expectEqual(@as(usize, 4), anim.frameBytes()); + + anim.setGapAt(0, 40); + anim.setGapAt(1, 60); + try testing.expectEqual(@as(u64, 100), anim.durationMs()); + try testing.expectEqual(@as(u32, 40), anim.root_gap_ms); +} |
