Kitty Graphics

Detailed Description

API for the images that programs send with the Kitty graphics protocol.

The terminal keeps every image a program sends, and every placement of an image on screen, in an image storage. Each screen (main and alternate) has its own. GhosttyKittyGraphics is a handle to the storage of the active screen. Use it to:

• Read the pixels of an image so you can draw it.
• Play animated images.
• Inspect the images and placements the storage holds.

This API doesn't tell you where to draw images. The render state does that. See "Drawing Images" below.

Setting Up

Kitty graphics are off until you give the terminal a storage limit with GHOSTTY_TERMINAL_OPT_KITTY_IMAGE_STORAGE_LIMIT. To accept PNG images, also install a PNG decoder with ghostty_sys_set() and GHOSTTY_SYS_OPT_DECODE_PNG, as in this example:

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;
}

Get the storage handle with ghostty_terminal_get() and GHOSTTY_TERMINAL_DATA_KITTY_GRAPHICS. The handle is borrowed from the terminal. It stays valid until the next call that changes the terminal, such as ghostty_terminal_vt_write() or ghostty_terminal_reset(), so get it again after each of those.

Drawing Images

Use the render state's image list to find what to draw. It lists every Kitty image on screen, however the program placed it:

• At a cell, so the image scrolls with the text.
• With placeholder cells (see "Unicode Placeholders" below).
• Relative to another image.

Each entry already has its position, size, source rectangle, layer and z-index worked out, so one drawing routine handles all of them. See "Images" in the Render State documentation for the details.

The storage only provides the pixels. Each entry in the list has an image ID. Look it up with ghostty_kitty_graphics_image(), then read the image's size, pixel format and pixels with ghostty_kitty_graphics_image_get(). The pixels are always decoded and uncompressed, so you can upload them as they are:

const char* kind_name(GhosttyRenderStateKittyPlacementKind kind) {
  switch (kind) {
  case GHOSTTY_RENDER_STATE_KITTY_PLACEMENT_KIND_VIRTUAL: return "virtual";
  case GHOSTTY_RENDER_STATE_KITTY_PLACEMENT_KIND_RELATIVE: return "relative";
  case GHOSTTY_RENDER_STATE_KITTY_PLACEMENT_KIND_FIXED: return "fixed";
  default: return "unknown";
  }
}

const char* layer_name(GhosttyRenderStateImageLayer layer) {
  switch (layer) {
  case GHOSTTY_RENDER_STATE_IMAGE_LAYER_BELOW_BACKGROUND: return "below-bg";
  case GHOSTTY_RENDER_STATE_IMAGE_LAYER_BELOW_TEXT: return "below-text";
  case GHOSTTY_RENDER_STATE_IMAGE_LAYER_ABOVE_TEXT: return "above-text";
  default: return "unknown";
  }
}

int draw_images(GhosttyRenderState state,
                GhosttyRenderStateImageIterator images,
                GhosttyTerminal terminal) {
  /* Fill the iterator from the last update. */
  if (ghostty_render_state_get(state, GHOSTTY_RENDER_STATE_DATA_IMAGE_ITERATOR,
                               &images) != GHOSTTY_SUCCESS) {
    fprintf(stderr, "Failed to get image iterator\n");
    return -1;
  }
 
  /* The storage is only needed to read pixels. */
  GhosttyKittyGraphics graphics = NULL;
  if (ghostty_terminal_get(terminal, GHOSTTY_TERMINAL_DATA_KITTY_GRAPHICS,
                           &graphics) != GHOSTTY_SUCCESS || !graphics) {
    fprintf(stderr, "Failed to get kitty graphics storage\n");
    return -1;
  }
 
  int count = 0;
  while (ghostty_render_state_image_iterator_next(images)) {
    GhosttyImageProtocol protocol;
    ghostty_render_state_image_get(
        images, GHOSTTY_RENDER_STATE_IMAGE_DATA_PROTOCOL, &protocol);
 
    /* Skip protocols this renderer doesn't support. */
    if (protocol != GHOSTTY_IMAGE_PROTOCOL_KITTY) continue;
 
    GhosttyRenderStateKittyPlacementKind kind;
    GhosttyRenderStateImageLayer layer;
    uint32_t image_id, placement_id, cols, rows, offset_x, offset_y;
    uint32_t width, height, src_x, src_y, src_width, src_height;
    uint64_t generation;
    int32_t col, row, z;
 
    GhosttyRenderStateImageData keys[] = {
      GHOSTTY_RENDER_STATE_IMAGE_DATA_IMAGE_ID,
      GHOSTTY_RENDER_STATE_IMAGE_DATA_IMAGE_GENERATION,
      GHOSTTY_RENDER_STATE_IMAGE_DATA_KITTY_KIND,
      GHOSTTY_RENDER_STATE_IMAGE_DATA_KITTY_PLACEMENT_ID,
      GHOSTTY_RENDER_STATE_IMAGE_DATA_LAYER,
      GHOSTTY_RENDER_STATE_IMAGE_DATA_Z,
      GHOSTTY_RENDER_STATE_IMAGE_DATA_VIEWPORT_COL,
      GHOSTTY_RENDER_STATE_IMAGE_DATA_VIEWPORT_ROW,
      GHOSTTY_RENDER_STATE_IMAGE_DATA_GRID_COLS,
      GHOSTTY_RENDER_STATE_IMAGE_DATA_GRID_ROWS,
      GHOSTTY_RENDER_STATE_IMAGE_DATA_CELL_OFFSET_X,
      GHOSTTY_RENDER_STATE_IMAGE_DATA_CELL_OFFSET_Y,
      GHOSTTY_RENDER_STATE_IMAGE_DATA_PIXEL_WIDTH,
      GHOSTTY_RENDER_STATE_IMAGE_DATA_PIXEL_HEIGHT,
      GHOSTTY_RENDER_STATE_IMAGE_DATA_SOURCE_X,
      GHOSTTY_RENDER_STATE_IMAGE_DATA_SOURCE_Y,
      GHOSTTY_RENDER_STATE_IMAGE_DATA_SOURCE_WIDTH,
      GHOSTTY_RENDER_STATE_IMAGE_DATA_SOURCE_HEIGHT,
    };
    void* values[] = {
      &image_id, &generation, &kind, &placement_id, &layer, &z, &col, &row,
      &cols, &rows, &offset_x, &offset_y, &width, &height,
      &src_x, &src_y, &src_width, &src_height,
    };
    size_t key_count = sizeof(keys) / sizeof(keys[0]);
    if (ghostty_render_state_image_get_multi(images, key_count, keys, values,
                                             NULL) != GHOSTTY_SUCCESS) {
      fprintf(stderr, "Failed to read image placement\n");
      return -1;
    }
 
    count++;
    printf("  image #%d: kind=%s image_id=%u placement_id=%u\n", count,
           kind_name(kind), image_id, placement_id);
    printf("    layer=%s z=%d cell=(%d,%d) cells=%ux%u offset=(%u,%u)\n",
           layer_name(layer), z, col, row, cols, rows, offset_x, offset_y);
    printf("    size=%ux%u source=(%u,%u %ux%u)\n", width, height, src_x,
           src_y, src_width, src_height);
 
    /*
     * Read the pixels to upload them as a texture. A real renderer keys
     * its textures by protocol, image ID and image generation, and only
     * gets here when it has no texture for that key yet. The generation
     * changes whenever the pixels do, so most frames skip this.
     */
    GhosttyKittyGraphicsImage image =
        ghostty_kitty_graphics_image(graphics, image_id);
    if (!image) continue;
 
    uint32_t image_width = 0, image_height = 0;
    GhosttyKittyImageFormat format = 0;
    const uint8_t* pixels = NULL;
    size_t data_len = 0;
    ghostty_kitty_graphics_image_get_multi(image, 5,
        (GhosttyKittyGraphicsImageData[]){
            GHOSTTY_KITTY_IMAGE_DATA_WIDTH,
            GHOSTTY_KITTY_IMAGE_DATA_HEIGHT,
            GHOSTTY_KITTY_IMAGE_DATA_FORMAT,
            GHOSTTY_KITTY_IMAGE_DATA_DATA_PTR,
            GHOSTTY_KITTY_IMAGE_DATA_DATA_LEN,
        },
        (void*[]){ &image_width, &image_height, &format, &pixels, &data_len },
        NULL);
    printf("    pixels: %ux%u format=%d data_len=%zu generation=%llu\n",
           image_width, image_height, format, data_len,
           (unsigned long long)generation);
  }
 
  return count;
}

Don't also draw images from this API's placement iterator. The render state's list already includes those placements, so they would be drawn twice. See "Inspecting the Storage" below for what the iterator is for.

Knowing What Changed

Most frames don't change any image, so a renderer can skip most of its image work. Two values tell you what to redo:

• GHOSTTY_RENDER_STATE_DATA_IMAGE_PLACEMENTS_GENERATION belongs to the render state's whole list. It tells you when to read the list again, for example after an image moved because the text scrolled.
• GHOSTTY_KITTY_IMAGE_DATA_GENERATION belongs to a single image. It tells you when to upload that image's pixels again. It changes when a program sends the image again and on every animation frame. The render state reports the same value for each entry as GHOSTTY_RENDER_STATE_IMAGE_DATA_IMAGE_GENERATION, so you can check your texture cache without touching the storage.

Use the image generation as part of your texture cache key. Don't rely on the image's size or data length instead: a program can send new pixels with the same size under the same ID.

Here is a frame loop that reads the list only when it changed:

int run_frames(GhosttyTerminal terminal) {
  /* Create the render state and the image iterator once, and reuse them. */
  GhosttyRenderState state = NULL;
  if (ghostty_render_state_new(NULL, &state) != GHOSTTY_SUCCESS) {
    fprintf(stderr, "Failed to create render state\n");
    return 1;
  }
  GhosttyRenderStateImageIterator images = NULL;
  if (ghostty_render_state_image_iterator_new(NULL, &images) !=
      GHOSTTY_SUCCESS) {
    fprintf(stderr, "Failed to create image iterator\n");
    ghostty_render_state_free(state);
    return 1;
  }
 
  /* The flag makes sure the first frame always reads the list. */
  uint64_t last_generation = 0;
  bool have_draw_list = false;
 
  int result = 0;
  for (int frame = 1; frame <= 3; frame++) {
    if (frame == 3) {
      /* Move to the bottom row and print two newlines to scroll. */
      const char* scroll = "\x1b[24;1H\r\n\r\n";
      ghostty_terminal_vt_write(terminal, (const uint8_t*)scroll,
                                strlen(scroll));
    }
 
    if (ghostty_render_state_update(state, terminal) != GHOSTTY_SUCCESS) {
      fprintf(stderr, "Failed to update render state\n");
      result = 1;
      break;
    }
 
    uint64_t generation = 0;
    ghostty_render_state_get(
        state, GHOSTTY_RENDER_STATE_DATA_IMAGE_PLACEMENTS_GENERATION,
        &generation);
    if (have_draw_list && generation == last_generation) {
      printf("\nFrame %d: no image changed, keep drawing the last list\n",
             frame);
      continue;
    }
    last_generation = generation;
    have_draw_list = true;
 
    printf("\nFrame %d: images changed, reading the list:\n", frame);
    int count = draw_images(state, images, terminal);
    if (count < 0) {
      result = 1;
      break;
    }
    printf("Total images: %d\n", count);
  }
 
  ghostty_render_state_image_iterator_free(images);
  ghostty_render_state_free(state);
  return result;
}

The storage also has a generation of its own, GHOSTTY_KITTY_GRAPHICS_DATA_GENERATION. It changes whenever a program sends, places or deletes an image, but not when images only move on screen. It can't tell you when to read the render state's list again. It is useful for work that only depends on what the storage holds, such as freeing textures of images that were deleted.

The two storage generations are never reused, not even across the main and alternate screens, terminal resets, or different terminals. That makes either one safe to use as a cache key on its own. The render state's placements generation is different: only compare it with the last value you read from the same render state.

Animation

The Kitty graphics protocol lets programs send images with several frames and ask the terminal to play them, much like an animated GIF. The terminal stores every frame, but it does not keep its own timer. Your application drives playback by calling ghostty_kitty_graphics_animation_tick().

Each call shows whichever frame is due at the time you pass in. When an image moves to a new frame, two things change:

• GHOSTTY_KITTY_IMAGE_DATA_DATA_PTR returns the pixels of the new frame.
• GHOSTTY_KITTY_IMAGE_DATA_GENERATION returns a new value.

If you already cache textures by image generation (see "Knowing What Changed" above), new frames appear without any extra work.

The tick also tells you when the next frame is due. Use that time to schedule a single redraw instead of calling the tick in a loop:

1. Call the tick each time you prepare a frame to draw, as long as the storage holds at least one image.
2. If it returns GHOSTTY_SUCCESS, schedule one redraw at the returned time. Don't schedule it sooner than your shortest frame interval (for example 8 ms for a 120 Hz display).
3. If it returns GHOSTTY_NO_VALUE, nothing is playing. Don't schedule anything.

You never need to watch for animations starting. A program starts or resumes playback by writing a command to the terminal, and that write already gives you a reason to redraw. The tick on that redraw picks up the animation. A terminal with no playing animations costs nothing extra.

Here is a helper that follows these steps. A renderer calls it once per frame and uses the result to schedule the next redraw:

/* The shortest time between two redraws. About 8 ms suits a 120 Hz display. */
#define MIN_FRAME_INTERVAL_MS 8

int64_t tick_animations(GhosttyKittyGraphics graphics, uint64_t now_ms) {
  uint64_t next_ms = 0;
  if (ghostty_kitty_graphics_animation_tick(graphics, now_ms, &next_ms) !=
      GHOSTTY_SUCCESS) {
    return -1;
  }
 
  /* next_ms is an absolute time. Turn it into a delay from now. */
  uint64_t delay_ms = next_ms > now_ms ? next_ms - now_ms : 0;
  if (delay_ms < MIN_FRAME_INTERVAL_MS) delay_ms = MIN_FRAME_INTERVAL_MS;
  return (int64_t)delay_ms;
}

The example below plays a two-frame animation with that helper. It uses a pretend clock so that it runs instantly:

void print_image(GhosttyKittyGraphics graphics, uint32_t image_id) {
  GhosttyKittyGraphicsImage image =
      ghostty_kitty_graphics_image(graphics, image_id);
  const uint8_t* pixels = NULL;
  uint64_t generation = 0;
  ghostty_kitty_graphics_image_get(image, GHOSTTY_KITTY_IMAGE_DATA_DATA_PTR,
                                   &pixels);
  ghostty_kitty_graphics_image_get(image, GHOSTTY_KITTY_IMAGE_DATA_GENERATION,
                                   &generation);
  printf("pixel=(%u,%u,%u) generation=%llu", pixels[0], pixels[1], pixels[2],
         (unsigned long long)generation);
}

int run_animation(GhosttyTerminal terminal) {
  /*
   * These commands set up the animation:
   *
   *   a=T  Send a red 1x1 RGBA image with ID 2 and display it.
   *   a=f  Add a blue second frame that shows for 40 ms.
   *   a=a  Make the first frame show for 30 ms. It starts at 0 ms,
   *        which would mean the frame is skipped.
   *   a=a  Start playing on a loop (s=3).
   *
   * q=2 tells the terminal not to send replies.
   */
  const char* cmds =
    "\x1b_Ga=T,f=32,i=2,s=1,v=1,q=2;/wAA/w==\x1b\\"
    "\x1b_Ga=f,f=32,i=2,s=1,v=1,z=40,q=2;AAD//w==\x1b\\"
    "\x1b_Ga=a,i=2,r=1,z=30,q=2\x1b\\"
    "\x1b_Ga=a,i=2,s=3,q=2\x1b\\";
  ghostty_terminal_vt_write(terminal, (const uint8_t*)cmds, strlen(cmds));
 
  GhosttyKittyGraphics graphics = NULL;
  if (ghostty_terminal_get(terminal, GHOSTTY_TERMINAL_DATA_KITTY_GRAPHICS,
                           &graphics) != GHOSTTY_SUCCESS || !graphics) {
    fprintf(stderr, "Failed to get kitty graphics storage\n");
    return 1;
  }
 
  /* Draw three frames, following each delay. */
  uint64_t now_ms = 0;
  for (int i = 0; i < 3; i++) {
    int64_t delay_ms = tick_animations(graphics, now_ms);
 
    /*
     * The tick invalidates image handles, so print_image() looks the
     * image up again. The generation changes whenever the frame does.
     */
    printf("  t=%llu ms: ", (unsigned long long)now_ms);
    print_image(graphics, 2);
    printf(", next redraw in %lld ms\n", (long long)delay_ms);
 
    now_ms += (uint64_t)delay_ms;
  }
 
  /* Stop playback (s=1). Once stopped, the tick asks for no redraws. */
  const char* stop = "\x1b_Ga=a,i=2,s=1,q=2\x1b\\";
  ghostty_terminal_vt_write(terminal, (const uint8_t*)stop, strlen(stop));
 
  /* Writing to the terminal invalidates the storage handle. Get it again. */
  ghostty_terminal_get(terminal, GHOSTTY_TERMINAL_DATA_KITTY_GRAPHICS,
                       &graphics);
  if (tick_animations(graphics, now_ms) < 0) {
    printf("  t=%llu ms: stopped, no redraw needed\n",
           (unsigned long long)now_ms);
  }
 
  return 0;
}

Unicode Placeholders

A program can place an image with text instead of at a cell. It creates a virtual placement, which has no position of its own, and prints placeholder characters (U+10EEEE) where the image should appear. The image then moves with those characters, like text. Programs such as tmux use this so that images scroll, move and disappear along with the text around them.

Only the cells know where these images are, so the storage can't tell you. The render state finds the placeholder cells and lists each part of the image like any other entry, so you draw them the same way as every other image. See "Kitty Graphics Placeholders" in the Render State documentation.

Inspecting the Storage

A GhosttyKittyGraphicsPlacementIterator lists every placement in the storage, including placements that are off screen and virtual placements. Use it for tools such as debuggers or tests that need to see what the storage holds. A renderer doesn't need it.

1. Create an iterator with ghostty_kitty_graphics_placement_iterator_new().
2. Fill it from the storage with ghostty_kitty_graphics_get() and GHOSTTY_KITTY_GRAPHICS_DATA_PLACEMENT_ITERATOR.
3. Optionally limit it to one layer with ghostty_kitty_graphics_placement_iterator_set().
4. Move to each placement with ghostty_kitty_graphics_placement_next() and read its values with ghostty_kitty_graphics_placement_get().
5. Free the iterator with ghostty_kitty_graphics_placement_iterator_free().

These functions work out the geometry of the iterator's current placement from the storage:

• ghostty_kitty_graphics_placement_pixel_size(): the size to draw the image at, in pixels.
• ghostty_kitty_graphics_placement_grid_size(): the number of columns and rows of cells it covers.
• ghostty_kitty_graphics_placement_viewport_pos(): the top-left cell, relative to the viewport.
• ghostty_kitty_graphics_placement_source_rect(): the part of the image to draw, in image pixels.
• ghostty_kitty_graphics_placement_rect(): the cells it covers, as a GhosttySelection.
• ghostty_kitty_graphics_placement_render_info(): all of the above except the selection, in one call.

They only know about placements at a cell, and placements relative to one. They can't find virtual placements, or placements relative to a virtual placement, because those depend on the cells. The render state gives the same values for every entry in its list, so prefer it whenever you are drawing.

Lifetime and Thread Safety

All handles borrowed from the terminal (GhosttyKittyGraphics, GhosttyKittyGraphicsImage) become invalid after any call that changes the terminal. The placement iterator belongs to you and must be freed, but the values it returns are only valid until the terminal changes.

Example

The following example creates a terminal, places one image at a cell and another with placeholder cells, lists both from the render state, and reads each image's pixels from the storage:

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;
  if (ghostty_terminal_new(NULL, &terminal, 80, 24) != GHOSTTY_SUCCESS) {
    fprintf(stderr, "Failed to create terminal\n");
    return 1;
  }
 
  /* Set the cell size in pixels. Image sizes depend on it. */
  ghostty_terminal_resize(terminal, 80, 24, 8, 16);
 
  /* 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);
 
  /* Move the cursor to row 10 so the images have room to scroll up. */
  const char* move = "\x1b[10;1H";
  ghostty_terminal_vt_write(terminal, (const uint8_t*)move, strlen(move));
 
  /*
   * Send a 1x1 PNG image and place it at the cursor. The image is
   * attached to that cell, so it moves when the text moves.
   *
   * The escape sequence is:
   *   ESC _G a=T,f=100,q=1; <base64 PNG data> ESC \
   *
   * Where:
   *   a=T    transmit the image and place it
   *   f=100  the data is a PNG
   *   q=1    only reply on errors (q=0 would also reply on success)
   */
  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);
 
  /*
   * Show a second image with placeholder cells. First send a green 1x1
   * image with ID 3 and give it a virtual placement 2 columns wide and
   * 1 row tall (U=1). Then, on the next row, print two placeholder
   * characters (U+10EEEE) where the image should appear:
   *
   *   ESC[38;5;3m    the foreground color says which image: ID 3
   *   U+0305 U+0305  the first cell shows row 0, column 0 of the image
   *   U+0305 U+030D  the second cell shows row 0, column 1
   *
   * The image moves with those cells, like text.
   */
  const char* placeholder_cmds =
    "\x1b_Ga=T,U=1,f=32,i=3,s=1,v=1,c=2,r=1,q=2;AP8A/w==\x1b\\"
    "\r\n\x1b[38;5;3m"
    "\xf4\x8e\xbb\xae\xcc\x85\xcc\x85"
    "\xf4\x8e\xbb\xae\xcc\x85\xcc\x8d"
    "\x1b[39m";
  ghostty_terminal_vt_write(terminal, (const uint8_t*)placeholder_cmds,
                            strlen(placeholder_cmds));
 
  /*
   * The storage has a generation of its own. It changes when a program
   * sends, places or deletes an image, but not when images only move on
   * screen. That is why the frames below use the render state's
   * placements generation to know when to read the list again.
   */
  GhosttyKittyGraphics graphics = NULL;
  if (ghostty_terminal_get(terminal, GHOSTTY_TERMINAL_DATA_KITTY_GRAPHICS,
                           &graphics) != GHOSTTY_SUCCESS || !graphics) {
    fprintf(stderr, "Failed to get kitty graphics storage\n");
    return 1;
  }
  uint64_t storage_generation = 0;
  ghostty_kitty_graphics_get(graphics, GHOSTTY_KITTY_GRAPHICS_DATA_GENERATION,
                             &storage_generation);
  printf("\nStorage generation: %llu\n",
         (unsigned long long)storage_generation);
 
  /* Find what to draw from the render state, over three frames. */
  if (run_frames(terminal) != 0) return 1;
 
  /* Animate a second image by driving the animation tick. */
  printf("\nPlaying an animation:\n");
  if (run_animation(terminal) != 0) return 1;
 
  /* 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;
}

Typedefs
typedef struct GhosttyKittyGraphicsImpl *	GhosttyKittyGraphics
typedef const struct GhosttyKittyGraphicsImageImpl *	GhosttyKittyGraphicsImage
typedef struct GhosttyKittyGraphicsPlacementIteratorImpl *	GhosttyKittyGraphicsPlacementIterator

Enumerations
enum	GhosttyKittyGraphicsData { GHOSTTY_KITTY_GRAPHICS_DATA_INVALID = 0 , GHOSTTY_KITTY_GRAPHICS_DATA_PLACEMENT_ITERATOR = 1 , GHOSTTY_KITTY_GRAPHICS_DATA_GENERATION = 2 , GHOSTTY_KITTY_GRAPHICS_DATA_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE }
enum	GhosttyKittyGraphicsPlacementData {   GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_INVALID = 0 , GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_IMAGE_ID = 1 , GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_PLACEMENT_ID = 2 , GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_IS_VIRTUAL = 3 ,   GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_X_OFFSET = 4 , GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_Y_OFFSET = 5 , GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_SOURCE_X = 6 , GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_SOURCE_Y = 7 ,   GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_SOURCE_WIDTH = 8 , GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_SOURCE_HEIGHT = 9 , GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_COLUMNS = 10 , GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_ROWS = 11 ,   GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_Z = 12 , GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE }
enum	GhosttyKittyPlacementLayer { GHOSTTY_KITTY_PLACEMENT_LAYER_ALL = 0 , GHOSTTY_KITTY_PLACEMENT_LAYER_BELOW_BG = 1 , GHOSTTY_KITTY_PLACEMENT_LAYER_BELOW_TEXT = 2 , GHOSTTY_KITTY_PLACEMENT_LAYER_ABOVE_TEXT = 3 , GHOSTTY_KITTY_PLACEMENT_LAYER_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE }
enum	GhosttyKittyGraphicsPlacementIteratorOption { GHOSTTY_KITTY_GRAPHICS_PLACEMENT_ITERATOR_OPTION_LAYER = 0 , GHOSTTY_KITTY_GRAPHICS_PLACEMENT_ITERATOR_OPTION_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE }
enum	GhosttyKittyImageFormat
enum	GhosttyKittyImageCompression
enum	GhosttyKittyGraphicsImageData {   GHOSTTY_KITTY_IMAGE_DATA_INVALID = 0 , GHOSTTY_KITTY_IMAGE_DATA_ID = 1 , GHOSTTY_KITTY_IMAGE_DATA_NUMBER = 2 , GHOSTTY_KITTY_IMAGE_DATA_WIDTH = 3 ,   GHOSTTY_KITTY_IMAGE_DATA_HEIGHT = 4 , GHOSTTY_KITTY_IMAGE_DATA_FORMAT = 5 , GHOSTTY_KITTY_IMAGE_DATA_COMPRESSION = 6 , GHOSTTY_KITTY_IMAGE_DATA_DATA_PTR = 7 ,   GHOSTTY_KITTY_IMAGE_DATA_DATA_LEN = 8 , GHOSTTY_KITTY_IMAGE_DATA_GENERATION = 9 , GHOSTTY_KITTY_IMAGE_DATA_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE }

Functions
GHOSTTY_API GhosttyResult	ghostty_kitty_graphics_get (GhosttyKittyGraphics graphics, GhosttyKittyGraphicsData data, void *out)
GHOSTTY_API GhosttyResult	ghostty_kitty_graphics_animation_tick (GhosttyKittyGraphics graphics, uint64_t now_ms, uint64_t *next_ms)
GHOSTTY_API GhosttyKittyGraphicsImage	ghostty_kitty_graphics_image (GhosttyKittyGraphics graphics, uint32_t image_id)
GHOSTTY_API GhosttyResult	ghostty_kitty_graphics_image_get (GhosttyKittyGraphicsImage image, GhosttyKittyGraphicsImageData data, void *out)
GHOSTTY_API GhosttyResult	ghostty_kitty_graphics_image_get_multi (GhosttyKittyGraphicsImage image, size_t count, const GhosttyKittyGraphicsImageData *keys, void **values, size_t *out_written)
GHOSTTY_API GhosttyResult	ghostty_kitty_graphics_placement_iterator_new (const GhosttyAllocator *allocator, GhosttyKittyGraphicsPlacementIterator *out_iterator)
GHOSTTY_API void	ghostty_kitty_graphics_placement_iterator_free (GhosttyKittyGraphicsPlacementIterator iterator)
GHOSTTY_API GhosttyResult	ghostty_kitty_graphics_placement_iterator_set (GhosttyKittyGraphicsPlacementIterator iterator, GhosttyKittyGraphicsPlacementIteratorOption option, const void *value)
GHOSTTY_API bool	ghostty_kitty_graphics_placement_next (GhosttyKittyGraphicsPlacementIterator iterator)
GHOSTTY_API GhosttyResult	ghostty_kitty_graphics_placement_get (GhosttyKittyGraphicsPlacementIterator iterator, GhosttyKittyGraphicsPlacementData data, void *out)
GHOSTTY_API GhosttyResult	ghostty_kitty_graphics_placement_get_multi (GhosttyKittyGraphicsPlacementIterator iterator, size_t count, const GhosttyKittyGraphicsPlacementData *keys, void **values, size_t *out_written)
GHOSTTY_API GhosttyResult	ghostty_kitty_graphics_placement_rect (GhosttyKittyGraphicsPlacementIterator iterator, GhosttyKittyGraphicsImage image, GhosttyTerminal terminal, GhosttySelection *out_selection)
GHOSTTY_API GhosttyResult	ghostty_kitty_graphics_placement_pixel_size (GhosttyKittyGraphicsPlacementIterator iterator, GhosttyKittyGraphicsImage image, GhosttyTerminal terminal, uint32_t *out_width, uint32_t *out_height)
GHOSTTY_API GhosttyResult	ghostty_kitty_graphics_placement_grid_size (GhosttyKittyGraphicsPlacementIterator iterator, GhosttyKittyGraphicsImage image, GhosttyTerminal terminal, uint32_t *out_cols, uint32_t *out_rows)
GHOSTTY_API GhosttyResult	ghostty_kitty_graphics_placement_viewport_pos (GhosttyKittyGraphicsPlacementIterator iterator, GhosttyKittyGraphicsImage image, GhosttyTerminal terminal, int32_t *out_col, int32_t *out_row)
GHOSTTY_API GhosttyResult	ghostty_kitty_graphics_placement_source_rect (GhosttyKittyGraphicsPlacementIterator iterator, GhosttyKittyGraphicsImage image, uint32_t *out_x, uint32_t *out_y, uint32_t *out_width, uint32_t *out_height)
GHOSTTY_API GhosttyResult	ghostty_kitty_graphics_placement_render_info (GhosttyKittyGraphicsPlacementIterator iterator, GhosttyKittyGraphicsImage image, GhosttyTerminal terminal, GhosttyKittyGraphicsPlacementRenderInfo *out_info)

Data Structures
struct	GhosttyKittyGraphicsPlacementRenderInfo

Typedef Documentation

GhosttyKittyGraphics

typedef struct GhosttyKittyGraphicsImpl* GhosttyKittyGraphics

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()).

Examples

c-vt-kitty-graphics/src/main.c.

Definition at line 150 of file types.h.

GhosttyKittyGraphicsImage

typedef const struct GhosttyKittyGraphicsImageImpl* GhosttyKittyGraphicsImage

Opaque handle to a Kitty graphics image.

Obtained via ghostty_kitty_graphics_image() with an image ID. The pointer is borrowed from the storage and remains valid until the next mutating terminal call.

Examples

c-vt-kitty-graphics/src/main.c.

Definition at line 161 of file types.h.

GhosttyKittyGraphicsPlacementIterator

typedef struct GhosttyKittyGraphicsPlacementIteratorImpl* GhosttyKittyGraphicsPlacementIterator

Opaque handle to a Kitty graphics placement iterator.

Definition at line 168 of file types.h.

Enumeration Type Documentation

GhosttyKittyGraphicsData

enum GhosttyKittyGraphicsData

Queryable data kinds for ghostty_kitty_graphics_get().

Enumerator
GHOSTTY_KITTY_GRAPHICS_DATA_INVALID	Invalid / sentinel value.
GHOSTTY_KITTY_GRAPHICS_DATA_PLACEMENT_ITERATOR	Populate a pre-allocated placement iterator with placement data from the storage. Iterator data is only valid as long as the underlying terminal is not mutated. Output type: GhosttyKittyGraphicsPlacementIterator *
GHOSTTY_KITTY_GRAPHICS_DATA_GENERATION	A value that changes whenever a program sends, replaces, places or deletes an image. It is 0 if nothing has changed the storage yet, which means the storage is empty. If the value matches the last one you read, the storage holds the same images and placements as before. The placements may still have moved on screen, because scrolling and resizing move them without changing the storage. So this value can't tell you when to read the render state's image list again. For that, use GHOSTTY_RENDER_STATE_DATA_IMAGE_PLACEMENTS_GENERATION. See "Knowing What Changed" in the Kitty Graphics documentation. A value is never reused, not even by another screen, after a reset, or by another terminal. You can use it as a cache key on its own. Output type: uint64_t *

Definition at line 238 of file kitty_graphics.h.

GhosttyKittyGraphicsImageData

enum GhosttyKittyGraphicsImageData

Queryable data kinds for ghostty_kitty_graphics_image_get().

Enumerator
GHOSTTY_KITTY_IMAGE_DATA_INVALID	Invalid / sentinel value.
GHOSTTY_KITTY_IMAGE_DATA_ID	The image ID. Output type: uint32_t *
GHOSTTY_KITTY_IMAGE_DATA_NUMBER	The image number. Output type: uint32_t *
GHOSTTY_KITTY_IMAGE_DATA_WIDTH	Image width in pixels. Output type: uint32_t *
GHOSTTY_KITTY_IMAGE_DATA_HEIGHT	Image height in pixels. Output type: uint32_t *
GHOSTTY_KITTY_IMAGE_DATA_FORMAT	Pixel format of the image. Never GHOSTTY_KITTY_IMAGE_FORMAT_PNG; PNG payloads are decoded to RGBA before storage. Output type: GhosttyKittyImageFormat *
GHOSTTY_KITTY_IMAGE_DATA_COMPRESSION	Compression of the image. Always GHOSTTY_KITTY_IMAGE_COMPRESSION_NONE; compressed payloads are inflated before storage. Output type: GhosttyKittyImageCompression *
GHOSTTY_KITTY_IMAGE_DATA_DATA_PTR	Borrowed pointer to the raw pixel data. Valid as long as the underlying terminal is not mutated. Returns GHOSTTY_NO_VALUE when the image metadata is resident but its pixel payload is pending. The data is always fully decoded, uncompressed pixels in the format reported by GHOSTTY_KITTY_IMAGE_DATA_FORMAT: zlib payloads are inflated and PNG payloads are decoded to RGBA at transmission time, before the image is stored. Consumers can upload this directly to the GPU without any decode step. For an animated image (Kitty graphics animation, actions a=f/a=a) this is the pixel data of the current animation frame. The image's GHOSTTY_KITTY_IMAGE_DATA_GENERATION changes whenever the current frame changes, so generation-keyed caches remain coherent. Output type: const uint8_t **
GHOSTTY_KITTY_IMAGE_DATA_DATA_LEN	Length of the raw pixel data in bytes. Always equal to width * height * bytes-per-pixel for the reported format. For a pending image, this is the expected length reserved against the storage limit even though DATA_PTR is not available yet. Output type: size_t *
GHOSTTY_KITTY_IMAGE_DATA_GENERATION	A value that changes whenever this image's pixels may have changed: when a program sends the image or replaces it, and when an animation moves to a new frame. Use it as part of your texture cache key. If it matches the texture you have, you don't need to read the pixels again. The render state reports the same value for each of its entries as GHOSTTY_RENDER_STATE_IMAGE_DATA_IMAGE_GENERATION. Don't use the image's size or data length to detect changes instead. A program can send new pixels of the same size under the same ID. A value is never reused, not even by another image, another screen, or another terminal. It is never 0 for a stored image, so you can use 0 to mean "no texture yet". One case doesn't change this value. When a program finishes sending an image whose pixels were still on the way, the image keeps its value, and GHOSTTY_KITTY_IMAGE_DATA_DATA_PTR starts returning the pixels. GHOSTTY_KITTY_GRAPHICS_DATA_GENERATION changes when that happens, so read DATA_PTR again then. Output type: uint64_t *

Examples

c-vt-kitty-graphics/src/main.c.

Definition at line 462 of file kitty_graphics.h.

GhosttyKittyGraphicsPlacementData

enum GhosttyKittyGraphicsPlacementData

Queryable data kinds for ghostty_kitty_graphics_placement_get().

Enumerator
GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_INVALID	Invalid / sentinel value.
GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_IMAGE_ID	The image ID this placement belongs to. Output type: uint32_t *
GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_PLACEMENT_ID	The placement ID. Output type: uint32_t *
GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_IS_VIRTUAL	Whether this is a virtual placement, which a program shows with Unicode placeholder cells. A virtual placement appears wherever its placeholder cells are, so the storage has no position for it. The render state's image list positions it from its cells like any other placement, so a renderer doesn't need to check this. See "Unicode Placeholders" in the Kitty Graphics documentation. Output type: bool *
GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_X_OFFSET	Pixel offset from the left edge of the cell. Output type: uint32_t *
GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_Y_OFFSET	Pixel offset from the top edge of the cell. Output type: uint32_t *
GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_SOURCE_X	Source rectangle x origin in pixels. Output type: uint32_t *
GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_SOURCE_Y	Source rectangle y origin in pixels. Output type: uint32_t *
GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_SOURCE_WIDTH	Source rectangle width in pixels (0 = full image width). Output type: uint32_t *
GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_SOURCE_HEIGHT	Source rectangle height in pixels (0 = full image height). Output type: uint32_t *
GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_COLUMNS	Number of columns this placement occupies. Output type: uint32_t *
GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_ROWS	Number of rows this placement occupies. Output type: uint32_t *
GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_Z	Z-index for this placement. Output type: int32_t *

Definition at line 278 of file kitty_graphics.h.

GhosttyKittyGraphicsPlacementIteratorOption

enum GhosttyKittyGraphicsPlacementIteratorOption

Settable options for ghostty_kitty_graphics_placement_iterator_set().

Enumerator
GHOSTTY_KITTY_GRAPHICS_PLACEMENT_ITERATOR_OPTION_LAYER	Only return placements in one layer. See GhosttyKittyPlacementLayer. Input type: GhosttyKittyPlacementLayer *

Definition at line 410 of file kitty_graphics.h.

GhosttyKittyImageCompression

enum GhosttyKittyImageCompression

Compression of a Kitty graphics image.

Note that stored images are always decompressed: GHOSTTY_KITTY_IMAGE_COMPRESSION_ZLIB_DEFLATE payloads are inflated before storage, so ghostty_kitty_graphics_image_get() always reports GHOSTTY_KITTY_IMAGE_COMPRESSION_NONE. Consumers never need to inflate image data themselves.

Definition at line 451 of file kitty_graphics.h.

GhosttyKittyImageFormat

enum GhosttyKittyImageFormat

Pixel format of a Kitty graphics image.

Note that stored images are always fully decoded: GHOSTTY_KITTY_IMAGE_FORMAT_PNG is never returned by ghostty_kitty_graphics_image_get() because PNG payloads are decoded to GHOSTTY_KITTY_IMAGE_FORMAT_RGBA before storage. The PNG value exists only for protocol-level completeness.

Examples

c-vt-kitty-graphics/src/main.c.

Definition at line 431 of file kitty_graphics.h.

GhosttyKittyPlacementLayer

enum GhosttyKittyPlacementLayer

A layer to limit the storage placement iterator to, set with GHOSTTY_KITTY_GRAPHICS_PLACEMENT_ITERATOR_OPTION_LAYER.

The Kitty graphics protocol picks a placement's layer from its z-index, as each value below describes. This filter is only for the storage iterator. To draw, use the layer the render state gives each entry (GHOSTTY_RENDER_STATE_IMAGE_DATA_LAYER). It follows the same rules, and it also covers virtual placements, which are always drawn below the text.

Enumerator
GHOSTTY_KITTY_PLACEMENT_LAYER_ALL	Every placement. This is the default.
GHOSTTY_KITTY_PLACEMENT_LAYER_BELOW_BG	Placements drawn below the cell backgrounds: z < INT32_MIN / 2.
GHOSTTY_KITTY_PLACEMENT_LAYER_BELOW_TEXT	Placements drawn above the cell backgrounds and below the text: INT32_MIN / 2 <= z < 0.
GHOSTTY_KITTY_PLACEMENT_LAYER_ABOVE_TEXT	Placements drawn above the text: z >= 0.

Definition at line 389 of file kitty_graphics.h.

Function Documentation

ghostty_kitty_graphics_animation_tick()

GHOSTTY_API GhosttyResult ghostty_kitty_graphics_animation_tick	(	GhosttyKittyGraphics	graphics,
		uint64_t	now_ms,
		uint64_t *	next_ms )

Advance playing animations and get the time of the next frame.

Every playing animation moves to the frame that is due at now_ms. An animation moves forward at most one frame per call. If calls arrive late, playback slows down rather than skipping frames.

Images that moved to a new frame get a new GHOSTTY_KITTY_IMAGE_DATA_GENERATION, and their GHOSTTY_KITTY_IMAGE_DATA_DATA_PTR returns the new frame's pixels.

Time is measured in milliseconds on a clock you choose, such as the time since your application started. The clock must only move forward, and you must keep using the same clock with the same starting point for as long as the terminal exists. The time written to next_ms uses the same clock.

This call changes the image storage. Like ghostty_terminal_vt_write(), it invalidates any GhosttyKittyGraphicsImage handles and image data pointers you are holding, so look images up again afterwards. The GhosttyKittyGraphics handle itself stays valid.

Call this once each time you prepare a frame to draw, not in a loop. The "Animation" section of Kitty Graphics explains how to schedule redraws with the returned time and includes an example.

Parameters

	graphics	The kitty graphics handle
	now_ms	The current time in milliseconds
[out]	next_ms	Set to the time the next frame is due, in milliseconds on the same clock as now_ms. Only written when the function returns GHOSTTY_SUCCESS.

Returns

GHOSTTY_SUCCESS if an animation is playing and next_ms was set, GHOSTTY_NO_VALUE if nothing is playing or Kitty graphics are disabled at build time, GHOSTTY_INVALID_VALUE if next_ms is NULL

Examples

c-vt-kitty-graphics/src/main.c.

References ghostty_kitty_graphics_animation_tick().

Referenced by ghostty_kitty_graphics_animation_tick().

ghostty_kitty_graphics_get()

GHOSTTY_API GhosttyResult ghostty_kitty_graphics_get	(	GhosttyKittyGraphics	graphics,
		GhosttyKittyGraphicsData	data,
		void *	out )

Get data from a kitty graphics storage instance.

The output pointer must be of the appropriate type for the requested data kind.

Returns GHOSTTY_NO_VALUE when Kitty graphics are disabled at build time.

Parameters

	graphics	The kitty graphics handle
	data	The type of data to extract
[out]	out	Pointer to store the extracted data

Returns

GHOSTTY_SUCCESS on success

Examples

c-vt-kitty-graphics/src/main.c.

References ghostty_kitty_graphics_get().

Referenced by ghostty_kitty_graphics_get().

ghostty_kitty_graphics_image()

GHOSTTY_API GhosttyKittyGraphicsImage ghostty_kitty_graphics_image	(	GhosttyKittyGraphics	graphics,
		uint32_t	image_id )

Look up a Kitty graphics image by its image ID.

Returns NULL if no image with the given ID exists or if Kitty graphics are disabled at build time.

Parameters

graphics	The kitty graphics handle
image_id	The image ID to look up

Returns

An opaque image handle, or NULL if not found

Examples

c-vt-kitty-graphics/src/main.c.

References ghostty_kitty_graphics_image().

Referenced by ghostty_kitty_graphics_image().

ghostty_kitty_graphics_image_get()

GHOSTTY_API GhosttyResult ghostty_kitty_graphics_image_get	(	GhosttyKittyGraphicsImage	image,
		GhosttyKittyGraphicsImageData	data,
		void *	out )

Get data from a Kitty graphics image.

The output pointer must be of the appropriate type for the requested data kind.

Parameters

	image	The image handle (NULL returns GHOSTTY_INVALID_VALUE)
	data	The data kind to query
[out]	out	Pointer to receive the queried value

Returns

GHOSTTY_SUCCESS on success

Examples

c-vt-kitty-graphics/src/main.c.

References ghostty_kitty_graphics_image_get().

Referenced by ghostty_kitty_graphics_image_get().

ghostty_kitty_graphics_image_get_multi()

GHOSTTY_API GhosttyResult ghostty_kitty_graphics_image_get_multi	(	GhosttyKittyGraphicsImage	image,
		size_t	count,
		const GhosttyKittyGraphicsImageData *	keys,
		void **	values,
		size_t *	out_written )

Get multiple data fields from a Kitty graphics image in a single call.

This is an optimization over calling ghostty_kitty_graphics_image_get() repeatedly, particularly useful in environments with high per-call overhead such as FFI or Cgo.

Each element in the keys array specifies a data kind, and the corresponding element in the values array receives the result. The type of each values[i] pointer must match the output type documented for keys[i].

Processing stops at the first error; on success out_written is set to count, on error it is set to the index of the failing key (i.e. the number of values successfully written).

Parameters

	image	The image handle (NULL returns GHOSTTY_INVALID_VALUE)
	count	Number of key/value pairs
	keys	Array of data kinds to query
	values	Array of output pointers (types must match each key's documented output type)
[out]	out_written	On return, receives the number of values successfully written (may be NULL)

Returns

GHOSTTY_SUCCESS if all queries succeed

Examples

c-vt-kitty-graphics/src/main.c.

References ghostty_kitty_graphics_image_get_multi().

Referenced by ghostty_kitty_graphics_image_get_multi().

ghostty_kitty_graphics_placement_get()

GHOSTTY_API GhosttyResult ghostty_kitty_graphics_placement_get	(	GhosttyKittyGraphicsPlacementIterator	iterator,
		GhosttyKittyGraphicsPlacementData	data,
		void *	out )

Get data from the current placement in a placement iterator.

Call ghostty_kitty_graphics_placement_next() at least once before calling this function.

Parameters

	iterator	The iterator handle (NULL returns GHOSTTY_INVALID_VALUE)
	data	The data kind to query
[out]	out	Pointer to receive the queried value

Returns

GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the iterator is NULL or not positioned on a placement

References ghostty_kitty_graphics_placement_get().

Referenced by ghostty_kitty_graphics_placement_get().

ghostty_kitty_graphics_placement_get_multi()

GHOSTTY_API GhosttyResult ghostty_kitty_graphics_placement_get_multi	(	GhosttyKittyGraphicsPlacementIterator	iterator,
		size_t	count,
		const GhosttyKittyGraphicsPlacementData *	keys,
		void **	values,
		size_t *	out_written )

Get multiple data fields from the current placement in a single call.

This is an optimization over calling ghostty_kitty_graphics_placement_get() repeatedly, particularly useful in environments with high per-call overhead such as FFI or Cgo.

Each element in the keys array specifies a data kind, and the corresponding element in the values array receives the result. The type of each values[i] pointer must match the output type documented for keys[i].

Processing stops at the first error; on success out_written is set to count, on error it is set to the index of the failing key (i.e. the number of values successfully written).

Parameters

	iterator	The iterator handle (NULL returns GHOSTTY_INVALID_VALUE)
	count	Number of key/value pairs
	keys	Array of data kinds to query
	values	Array of output pointers (types must match each key's documented output type)
[out]	out_written	On return, receives the number of values successfully written (may be NULL)

Returns

GHOSTTY_SUCCESS if all queries succeed

References ghostty_kitty_graphics_placement_get_multi().

Referenced by ghostty_kitty_graphics_placement_get_multi().

ghostty_kitty_graphics_placement_grid_size()

GHOSTTY_API GhosttyResult ghostty_kitty_graphics_placement_grid_size	(	GhosttyKittyGraphicsPlacementIterator	iterator,
		GhosttyKittyGraphicsImage	image,
		GhosttyTerminal	terminal,
		uint32_t *	out_cols,
		uint32_t *	out_rows )

Compute the grid cell size of the current placement.

Returns the number of columns and rows that the placement occupies in the terminal grid. If the placement specifies explicit columns and rows, those are returned directly; otherwise they are calculated from the pixel size and cell dimensions.

Parameters

	iterator	The placement iterator positioned on a placement
	image	The image handle for this placement's image
	terminal	The terminal handle
[out]	out_cols	On success, receives the number of columns
[out]	out_rows	On success, receives the number of rows

Returns

GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if any handle is NULL or the iterator is not positioned, GHOSTTY_NO_VALUE when Kitty graphics are disabled

References ghostty_kitty_graphics_placement_grid_size().

Referenced by ghostty_kitty_graphics_placement_grid_size().

ghostty_kitty_graphics_placement_iterator_free()

GHOSTTY_API void ghostty_kitty_graphics_placement_iterator_free

(

GhosttyKittyGraphicsPlacementIterator

iterator

)

Free a placement iterator.

Parameters

iterator

The iterator handle to free (may be NULL)

References ghostty_kitty_graphics_placement_iterator_free().

Referenced by ghostty_kitty_graphics_placement_iterator_free().

ghostty_kitty_graphics_placement_iterator_new()

GHOSTTY_API GhosttyResult ghostty_kitty_graphics_placement_iterator_new	(	const GhosttyAllocator *	allocator,
		GhosttyKittyGraphicsPlacementIterator *	out_iterator )

Create a new placement iterator instance.

All fields except the allocator are left undefined until populated via ghostty_kitty_graphics_get() with GHOSTTY_KITTY_GRAPHICS_DATA_PLACEMENT_ITERATOR.

Parameters

	allocator	Pointer to allocator, or NULL to use the default allocator
[out]	out_iterator	On success, receives the created iterator handle

Returns

GHOSTTY_SUCCESS on success, GHOSTTY_OUT_OF_MEMORY on allocation failure

References ghostty_kitty_graphics_placement_iterator_new().

Referenced by ghostty_kitty_graphics_placement_iterator_new().

ghostty_kitty_graphics_placement_iterator_set()

GHOSTTY_API GhosttyResult ghostty_kitty_graphics_placement_iterator_set	(	GhosttyKittyGraphicsPlacementIterator	iterator,
		GhosttyKittyGraphicsPlacementIteratorOption	option,
		const void *	value )

Set an option on a placement iterator.

Use GHOSTTY_KITTY_GRAPHICS_PLACEMENT_ITERATOR_OPTION_LAYER with a GhosttyKittyPlacementLayer value to filter placements by z-layer. The filter is applied during iteration: ghostty_kitty_graphics_placement_next() will skip placements that do not match the configured layer.

The default layer is GHOSTTY_KITTY_PLACEMENT_LAYER_ALL (no filtering).

Parameters

iterator	The iterator handle (NULL returns GHOSTTY_INVALID_VALUE)
option	The option to set
value	Pointer to the value (type depends on option; NULL returns GHOSTTY_INVALID_VALUE)

Returns

GHOSTTY_SUCCESS on success

References ghostty_kitty_graphics_placement_iterator_set().

Referenced by ghostty_kitty_graphics_placement_iterator_set().

ghostty_kitty_graphics_placement_next()

GHOSTTY_API bool ghostty_kitty_graphics_placement_next

(

GhosttyKittyGraphicsPlacementIterator

iterator

)

Advance the placement iterator to the next placement.

If a layer filter has been set via ghostty_kitty_graphics_placement_iterator_set(), only placements matching that layer are returned.

Parameters

iterator

The iterator handle (may be NULL)

Returns

true if advanced to the next placement, false if at the end

References ghostty_kitty_graphics_placement_next().

Referenced by ghostty_kitty_graphics_placement_next().

ghostty_kitty_graphics_placement_pixel_size()

GHOSTTY_API GhosttyResult ghostty_kitty_graphics_placement_pixel_size	(	GhosttyKittyGraphicsPlacementIterator	iterator,
		GhosttyKittyGraphicsImage	image,
		GhosttyTerminal	terminal,
		uint32_t *	out_width,
		uint32_t *	out_height )

Compute the rendered pixel size of the current placement.

Takes into account the placement's source rectangle, specified columns/rows, and aspect ratio to calculate the final rendered pixel dimensions.

Parameters

	iterator	The placement iterator positioned on a placement
	image	The image handle for this placement's image
	terminal	The terminal handle
[out]	out_width	On success, receives the width in pixels
[out]	out_height	On success, receives the height in pixels

Returns

GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if any handle is NULL or the iterator is not positioned, GHOSTTY_NO_VALUE when Kitty graphics are disabled

References ghostty_kitty_graphics_placement_pixel_size().

Referenced by ghostty_kitty_graphics_placement_pixel_size().

ghostty_kitty_graphics_placement_rect()

GHOSTTY_API GhosttyResult ghostty_kitty_graphics_placement_rect	(	GhosttyKittyGraphicsPlacementIterator	iterator,
		GhosttyKittyGraphicsImage	image,
		GhosttyTerminal	terminal,
		GhosttySelection *	out_selection )

Compute the grid rectangle occupied by the current placement.

Uses the placement's pin, the image dimensions, and the terminal's cell/pixel geometry to calculate the bounding rectangle. Virtual placements (unicode placeholders) return GHOSTTY_NO_VALUE.

Parameters

	terminal	The terminal handle
	image	The image handle for this placement's image
	iterator	The placement iterator positioned on a placement
[out]	out_selection	On success, receives the bounding rectangle as a selection with rectangle=true

Returns

GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if any handle is NULL or the iterator is not positioned, GHOSTTY_NO_VALUE for virtual placements or when Kitty graphics are disabled

References ghostty_kitty_graphics_placement_rect().

Referenced by ghostty_kitty_graphics_placement_rect().

ghostty_kitty_graphics_placement_render_info()

GHOSTTY_API GhosttyResult ghostty_kitty_graphics_placement_render_info	(	GhosttyKittyGraphicsPlacementIterator	iterator,
		GhosttyKittyGraphicsImage	image,
		GhosttyTerminal	terminal,
		GhosttyKittyGraphicsPlacementRenderInfo *	out_info )

Get all of the geometry of the current placement in one call.

This fills in a GhosttyKittyGraphicsPlacementRenderInfo with the pixel size, grid size, viewport position and source rectangle. Set its size with GHOSTTY_INIT_SIZED first.

This is for inspecting the storage. To draw, use the render state's image list instead. It gives the same values for every image on screen, including virtual placements and placements relative to them. If you draw from both, images are drawn twice. See "Drawing Images" in the Kitty Graphics documentation.

The call succeeds even when the placement isn't in the viewport. Check viewport_visible before using viewport_col and viewport_row.

Parameters

	iterator	The placement iterator, moved to a placement
	image	The image of this placement
	terminal	The terminal the storage belongs to
[out]	out_info	Receives the geometry

Returns

GHOSTTY_SUCCESS on success. GHOSTTY_INVALID_VALUE if any handle or out_info is NULL, the iterator is not on a placement, or out_info->size is too small. GHOSTTY_NO_VALUE if Kitty graphics are disabled at build time.

References ghostty_kitty_graphics_placement_render_info().

Referenced by ghostty_kitty_graphics_placement_render_info().

ghostty_kitty_graphics_placement_source_rect()

GHOSTTY_API GhosttyResult ghostty_kitty_graphics_placement_source_rect	(	GhosttyKittyGraphicsPlacementIterator	iterator,
		GhosttyKittyGraphicsImage	image,
		uint32_t *	out_x,
		uint32_t *	out_y,
		uint32_t *	out_width,
		uint32_t *	out_height )

Get the resolved source rectangle for the current placement.

Applies kitty protocol semantics: a width or height of 0 in the placement means "use the full image dimension", and the resulting rectangle is clamped to the actual image bounds. The returned values are in pixels and are ready to use for texture sampling.

Parameters

	iterator	The placement iterator positioned on a placement
	image	The image handle for this placement's image
[out]	out_x	Source rect x origin in pixels
[out]	out_y	Source rect y origin in pixels
[out]	out_width	Source rect width in pixels
[out]	out_height	Source rect height in pixels

Returns

GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if any handle is NULL or the iterator is not positioned

References ghostty_kitty_graphics_placement_source_rect().

Referenced by ghostty_kitty_graphics_placement_source_rect().

ghostty_kitty_graphics_placement_viewport_pos()

GHOSTTY_API GhosttyResult ghostty_kitty_graphics_placement_viewport_pos	(	GhosttyKittyGraphicsPlacementIterator	iterator,
		GhosttyKittyGraphicsImage	image,
		GhosttyTerminal	terminal,
		int32_t *	out_col,
		int32_t *	out_row )

Get the top-left cell of the current placement, relative to the viewport.

This is for inspecting the storage. To draw, use the render state's image list instead. It positions every image on screen, including virtual placements and placements relative to them, and covers overscan rows. If you draw from both, images are drawn twice. See "Drawing Images" in the Kitty Graphics documentation.

The row is negative when the top of the placement scrolled above the viewport. For example, an image 4 rows tall that scrolled up by 2 rows has a row of -2. Its top 2 rows are above the viewport and its bottom 2 rows are still visible.

Parameters

	iterator	The placement iterator, moved to a placement
	image	The image of this placement
	terminal	The terminal the storage belongs to
[out]	out_col	On success, receives the column
[out]	out_row	On success, receives the row, which can be negative

Returns

GHOSTTY_SUCCESS if any part of the placement is in the viewport. GHOSTTY_NO_VALUE if it is entirely outside the viewport, if it is a virtual placement or relative to one, or if Kitty graphics are disabled at build time. GHOSTTY_INVALID_VALUE if any handle is NULL or the iterator is not on a placement.

References ghostty_kitty_graphics_placement_viewport_pos().

Referenced by ghostty_kitty_graphics_placement_viewport_pos().