libghostty: C APIs for Kitty Graphics inspection

[mitchellh]

This adds a C API for inspecting Kitty graphics image storage, images, and placements from a terminal instance.

I think this is enough of the API surface area for a renderer to draw images. But I'll have to add it to Ghostling to be sure.

Example

#include <stdint.h>
#include <stdio.h>
#include <ghostty/vt.h>

/* After creating a terminal and transmitting a Kitty graphics image... */

/* Get the kitty graphics storage from the terminal. */
GhosttyKittyGraphics graphics = NULL;
ghostty_terminal_get(terminal, GHOSTTY_TERMINAL_DATA_KITTY_GRAPHICS, &graphics);

/* Iterate over all placements. */
GhosttyKittyGraphicsPlacementIterator iter = NULL;
ghostty_kitty_graphics_placement_iterator_new(NULL, &iter);
ghostty_kitty_graphics_get(graphics,
    GHOSTTY_KITTY_GRAPHICS_DATA_PLACEMENT_ITERATOR, &iter);

while (ghostty_kitty_graphics_placement_next(iter)) {
  uint32_t image_id = 0;
  ghostty_kitty_graphics_placement_get(iter,
      GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_IMAGE_ID, &image_id);

  /* Look up the image and query its properties. */
  GhosttyKittyGraphicsImage image = ghostty_kitty_graphics_image(graphics, image_id);
  uint32_t width = 0, height = 0;
  GhosttyKittyImageFormat format = 0;
  ghostty_kitty_image_get(image, GHOSTTY_KITTY_IMAGE_DATA_WIDTH, &width);
  ghostty_kitty_image_get(image, GHOSTTY_KITTY_IMAGE_DATA_HEIGHT, &height);
  ghostty_kitty_image_get(image, GHOSTTY_KITTY_IMAGE_DATA_FORMAT, &format);
  printf("image %u: %ux%u format=%d\n", image_id, width, height, format);

  /* Compute rendered pixel size and grid size. */
  uint32_t px_w, px_h, cols, rows;
  ghostty_kitty_graphics_placement_pixel_size(iter, image, terminal, &px_w, &px_h);
  ghostty_kitty_graphics_placement_grid_size(iter, image, terminal, &cols, &rows);
  printf("  rendered: %ux%u px, %ux%u cells\n", px_w, px_h, cols, rows);
}

ghostty_kitty_graphics_placement_iterator_free(iter);

API

Functions

Function	Description
ghostty_kitty_graphics_get	Query data from a kitty graphics storage (e.g. placement iterator)
ghostty_kitty_graphics_image	Look up an image by its image ID
ghostty_kitty_graphics_image_get	Query image properties (ID, dimensions, format, compression, pixel data)
ghostty_kitty_graphics_placement_iterator_new	Create a new placement iterator
ghostty_kitty_graphics_placement_iterator_free	Free a placement iterator
ghostty_kitty_graphics_placement_next	Advance the iterator to the next placement
ghostty_kitty_graphics_placement_get	Query placement properties (image ID, offsets, source rect, z-index, etc.)
ghostty_kitty_graphics_placement_rect	Compute the bounding grid rectangle for a placement
ghostty_kitty_graphics_placement_pixel_size	Compute the rendered pixel dimensions of a placement
ghostty_kitty_graphics_placement_grid_size	Compute the grid cell dimensions of a placement

Types

Type	Description
GhosttyKittyGraphics	Opaque handle to image storage (borrowed from terminal)
GhosttyKittyGraphicsImage	Opaque handle to a single image
GhosttyKittyGraphicsPlacementIterator	Opaque handle to a placement iterator
GhosttyKittyGraphicsData	Enum for ghostty_kitty_graphics_get data kinds
GhosttyKittyGraphicsImageData	Enum for ghostty_kitty_image_get data kinds
GhosttyKittyGraphicsPlacementData	Enum for ghostty_kitty_graphics_placement_get data kinds
GhosttyKittyImageFormat	Image pixel format (RGB, RGBA, PNG, gray, gray+alpha)
GhosttyKittyImageCompression	Image compression (none, zlib)