libghostty: introduce the kitty graphics opaque type

include/ghostty/vt.h

@@ -125,6 +125,7 @@ extern "C" {
 #include <ghostty/vt/style.h>
 #include <ghostty/vt/sys.h>
 #include <ghostty/vt/key.h>
+#include <ghostty/vt/kitty_graphics.h>
 #include <ghostty/vt/modes.h>
 #include <ghostty/vt/mouse.h>
 #include <ghostty/vt/paste.h>

include/ghostty/vt/kitty_graphics.h

@@ -0,0 +1,40 @@
+/**
+ * @file kitty_graphics.h
+ *
+ * Kitty graphics protocol image storage.
+ */
+
+#ifndef GHOSTTY_VT_KITTY_GRAPHICS_H
+#define GHOSTTY_VT_KITTY_GRAPHICS_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** @defgroup kitty_graphics Kitty Graphics
+ *
+ * Opaque handle to the Kitty graphics image storage associated with a
+ * terminal screen.
+ *
+ * @{
+ */
+
+/**
+ * Opaque handle to a Kitty graphics image storage.
+ *
+ * Obtained via ghostty_terminal_get() with
+ * GHOSTTY_TERMINAL_DATA_KITTY_GRAPHICS. The pointer is borrowed from
+ * the terminal and remains valid until the next mutating terminal call
+ * (e.g. ghostty_terminal_vt_write() or ghostty_terminal_reset()).
+ *
+ * @ingroup kitty_graphics
+ */
+typedef struct GhosttyKittyGraphicsImpl* GhosttyKittyGraphics;
+
+/** @} */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* GHOSTTY_VT_KITTY_GRAPHICS_H */

include/ghostty/vt/terminal.h

@@ -16,6 +16,7 @@
 #include <ghostty/vt/modes.h>
 #include <ghostty/vt/size_report.h>
 #include <ghostty/vt/grid_ref.h>
+#include <ghostty/vt/kitty_graphics.h>
 #include <ghostty/vt/screen.h>
 #include <ghostty/vt/point.h>
 #include <ghostty/vt/style.h>
@@ -839,6 +840,19 @@ typedef enum {
    * Output type: bool *
    */
   GHOSTTY_TERMINAL_DATA_KITTY_IMAGE_MEDIUM_SHARED_MEM = 29,
+
+  /**
+   * The Kitty graphics image storage for the active screen.
+   *
+   * Returns a borrowed pointer to the image storage. The pointer is valid
+   * until the next mutating terminal call (e.g. ghostty_terminal_vt_write()
+   * or ghostty_terminal_reset()).
+   *
+   * Returns GHOSTTY_NO_VALUE when Kitty graphics are disabled at build time.
+   *
+   * Output type: GhosttyKittyGraphics *
+   */
+  GHOSTTY_TERMINAL_DATA_KITTY_GRAPHICS = 30,
 } GhosttyTerminalData;
 
 /**

src/terminal/c/kitty_graphics.zig

@@ -0,0 +1,8 @@
+const build_options = @import("terminal_options");
+const kitty_gfx = @import("../kitty/graphics_storage.zig");
+
+/// C: GhosttyKittyGraphics
+pub const KittyGraphics = if (build_options.kitty_graphics)
+    *kitty_gfx.ImageStorage
+else
+    *anyopaque;

src/terminal/c/main.zig

@@ -8,6 +8,7 @@ pub const color = @import("color.zig");
 pub const focus = @import("focus.zig");
 pub const formatter = @import("formatter.zig");
 pub const grid_ref = @import("grid_ref.zig");
+pub const kitty_graphics = @import("kitty_graphics.zig");
 pub const types = @import("types.zig");
 pub const modes = @import("modes.zig");
 pub const osc = @import("osc.zig");
@@ -161,6 +162,7 @@ test {
     _ = cell;
     _ = color;
     _ = grid_ref;
+    _ = kitty_graphics;
     _ = row;
     _ = focus;
     _ = formatter;

src/terminal/c/terminal.zig

@@ -8,6 +8,7 @@ const Stream = @import("../stream_terminal.zig").Stream;
 const ScreenSet = @import("../ScreenSet.zig");
 const PageList = @import("../PageList.zig");
 const kitty = @import("../kitty/key.zig");
+const kitty_gfx_c = @import("kitty_graphics.zig");
 const modes = @import("../modes.zig");
 const point = @import("../point.zig");
 const size = @import("../size.zig");
@@ -515,6 +516,9 @@ pub fn mode_set(
     return .success;
 }
 
+/// C: GhosttyKittyGraphics
+pub const KittyGraphics = kitty_gfx_c.KittyGraphics;
+
 /// C: GhosttyTerminalScreen
 pub const TerminalScreen = ScreenSet.Key;
 
@@ -553,6 +557,7 @@ pub const TerminalData = enum(c_int) {
     kitty_image_medium_file = 27,
     kitty_image_medium_temp_file = 28,
     kitty_image_medium_shared_mem = 29,
+    kitty_graphics = 30,
 
     /// Output type expected for querying the data of the given kind.
     pub fn OutType(comptime self: TerminalData) type {
@@ -580,6 +585,7 @@ pub const TerminalData = enum(c_int) {
             .kitty_image_medium_temp_file,
             .kitty_image_medium_shared_mem,
             => bool,
+            .kitty_graphics => KittyGraphics,
         };
     }
 };
@@ -664,6 +670,10 @@ fn getTyped(
             if (comptime !build_options.kitty_graphics) return .no_value;
             out.* = t.screens.active.kitty_images.image_limits.shared_memory;
         },
+        .kitty_graphics => {
+            if (comptime !build_options.kitty_graphics) return .no_value;
+            out.* = &t.screens.active.kitty_images;
+        },
     }
 
     return .success;