example: add c-vt-kitty-graphics

Demonstrates the sys interface for Kitty Graphics Protocol PNG support. The example installs a PNG decode callback via ghostty_sys_set, creates a terminal with image storage enabled, and sends an inline 1x1 PNG image through vt_write. Snippet markers are wired up to the sys.h doxygen docs.
2026-08-29 18:41:40 +00:00 · 2026-04-06 07:49:49 -07:00
parent d7fa92088c
commit 64340c62bf
6 changed files with 222 additions and 0 deletions
--- a/example/c-vt-kitty-graphics/src/main.c
+++ b/example/c-vt-kitty-graphics/src/main.c
@@ -0,0 +1,125 @@
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <string.h>
+#include <ghostty/vt.h>
+
+//! [kitty-graphics-decode-png]
+/**
+ * Minimal PNG decoder callback for the sys interface.
+ *
+ * A real implementation would use a PNG library (libpng, stb_image, etc.)
+ * to decode the PNG data. This example uses a hardcoded 1x1 red pixel
+ * since we know exactly what image we're sending.
+ *
+ * WARNING: This is only an example for providing a callback, it DOES NOT 
+ * actually decode the PNG it is passed. It hardcodes a response.
+ */
+bool decode_png(void* userdata,
+                const GhosttyAllocator* allocator,
+                const uint8_t* data,
+                size_t data_len,
+                GhosttySysImage* out) {
+  int* count = (int*)userdata;
+  (*count)++;
+  printf("  decode_png called (size=%zu, call #%d)\n", data_len, *count);
+
+  /* Allocate RGBA pixel data through the provided allocator. */
+  const size_t pixel_len = 4;  /* 1x1 RGBA */
+  uint8_t* pixels = ghostty_alloc(allocator, pixel_len);
+  if (!pixels) return false;
+
+  /* Fill with red (R=255, G=0, B=0, A=255). */
+  pixels[0] = 255;
+  pixels[1] = 0;
+  pixels[2] = 0;
+  pixels[3] = 255;
+
+  out->width = 1;
+  out->height = 1;
+  out->data = pixels;
+  out->data_len = pixel_len;
+  return true;
+}
+//! [kitty-graphics-decode-png]
+
+//! [kitty-graphics-write-pty]
+/**
+ * write_pty callback to capture terminal responses.
+ *
+ * The Kitty graphics protocol sends an APC response back to the pty
+ * when an image is loaded (unless suppressed with q=2).
+ */
+void on_write_pty(GhosttyTerminal terminal,
+                  void* userdata,
+                  const uint8_t* data,
+                  size_t len) {
+  (void)terminal;
+  (void)userdata;
+  printf("  response (%zu bytes): ", len);
+  fwrite(data, 1, len, stdout);
+  printf("\n");
+}
+//! [kitty-graphics-write-pty]
+
+//! [kitty-graphics-main]
+int main() {
+  /* Install the PNG decoder via the sys interface. */
+  int decode_count = 0;
+  ghostty_sys_set(GHOSTTY_SYS_OPT_USERDATA, &decode_count);
+  ghostty_sys_set(GHOSTTY_SYS_OPT_DECODE_PNG, (const void*)decode_png);
+
+  /* Create a terminal with Kitty graphics enabled. */
+  GhosttyTerminal terminal = NULL;
+  GhosttyTerminalOptions opts = {
+    .cols = 80,
+    .rows = 24,
+    .max_scrollback = 0,
+  };
+  if (ghostty_terminal_new(NULL, &terminal, opts) != GHOSTTY_SUCCESS) {
+    fprintf(stderr, "Failed to create terminal\n");
+    return 1;
+  }
+
+  /* Set a storage limit to enable Kitty graphics. */
+  uint64_t storage_limit = 64 * 1024 * 1024;  /* 64 MiB */
+  ghostty_terminal_set(terminal, GHOSTTY_TERMINAL_OPT_KITTY_IMAGE_STORAGE_LIMIT,
+                       &storage_limit);
+
+  /* Install write_pty to see the protocol response. */
+  ghostty_terminal_set(terminal, GHOSTTY_TERMINAL_OPT_WRITE_PTY,
+                       (const void*)on_write_pty);
+
+  /*
+   * Send a Kitty graphics command with an inline 1x1 PNG image.
+   *
+   * The escape sequence is:
+   *   ESC _G a=T,f=100,q=1; <base64 PNG data> ESC \
+   *
+   * Where:
+   *   a=T   — transmit and display
+   *   f=100 — PNG format
+   *   q=1   — request a response (q=0 would suppress it)
+   */
+  printf("Sending Kitty graphics PNG image:\n");
+  const char* kitty_cmd =
+    "\x1b_Ga=T,f=100,q=1;"
+    "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAA"
+    "DUlEQVR4nGP4z8DwHwAFAAH/iZk9HQAAAABJRU5ErkJggg=="
+    "\x1b\\";
+  ghostty_terminal_vt_write(terminal, (const uint8_t*)kitty_cmd,
+                            strlen(kitty_cmd));
+
+  printf("PNG decode calls: %d\n", decode_count);
+
+  /* Clean up. */
+  ghostty_terminal_free(terminal);
+
+  /* Clear the sys callbacks. */
+  ghostty_sys_set(GHOSTTY_SYS_OPT_DECODE_PNG, NULL);
+  ghostty_sys_set(GHOSTTY_SYS_OPT_USERDATA, NULL);
+
+  return 0;
+}
+//! [kitty-graphics-main]