Detailed Description

API for inspecting images and placements stored via the Kitty graphics protocol.

The central object is GhosttyKittyGraphics, an opaque handle to the image storage associated with a terminal's active screen. From it you can iterate over placements and look up individual images.

Obtaining a KittyGraphics Handle

A GhosttyKittyGraphics handle is obtained from a terminal via ghostty_terminal_get() with GHOSTTY_TERMINAL_DATA_KITTY_GRAPHICS. The handle is borrowed from the terminal and remains valid until the next mutating terminal call (e.g. ghostty_terminal_vt_write() or ghostty_terminal_reset()).

Before images can be stored, Kitty graphics must be enabled on the terminal by setting a non-zero storage limit with GHOSTTY_TERMINAL_OPT_KITTY_IMAGE_STORAGE_LIMIT, and a PNG decoder callback must be installed via ghostty_sys_set() with GHOSTTY_SYS_OPT_DECODE_PNG.

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

Iterating Placements

Placements are inspected through a GhosttyKittyGraphicsPlacementIterator. The typical workflow is:

Create an iterator with ghostty_kitty_graphics_placement_iterator_new().
Populate it from the storage with ghostty_kitty_graphics_get() using GHOSTTY_KITTY_GRAPHICS_DATA_PLACEMENT_ITERATOR.
Optionally filter by z-layer with ghostty_kitty_graphics_placement_iterator_set().
Advance with ghostty_kitty_graphics_placement_next() and read per-placement data with ghostty_kitty_graphics_placement_get().
For each placement, look up its image with ghostty_kitty_graphics_image() to access pixel data and dimensions.
Free the iterator with ghostty_kitty_graphics_placement_iterator_free().

Looking Up Images

Given an image ID (obtained from a placement via GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_IMAGE_ID), call ghostty_kitty_graphics_image() to get a GhosttyKittyGraphicsImage handle. From this handle, ghostty_kitty_graphics_image_get() provides the image dimensions, pixel format, compression, and a borrowed pointer to the raw pixel data.

Rendering Helpers

Several functions assist with rendering a placement:

ghostty_kitty_graphics_placement_pixel_size() — rendered pixel dimensions accounting for source rect and aspect ratio.
ghostty_kitty_graphics_placement_grid_size() — number of grid columns and rows the placement occupies.
ghostty_kitty_graphics_placement_viewport_pos() — viewport-relative grid position (may be negative for partially scrolled placements).
ghostty_kitty_graphics_placement_source_rect() — resolved source rectangle in pixels, clamped to image bounds.
ghostty_kitty_graphics_placement_rect() — bounding rectangle as a GhosttySelection.

Lifetime and Thread Safety

All handles borrowed from the terminal (GhosttyKittyGraphics, GhosttyKittyGraphicsImage) are invalidated by any mutating terminal call. The placement iterator is independently owned and must be freed by the caller, but the data it yields is only valid while the underlying terminal is not mutated.

Example

The following example creates a terminal, sends a Kitty graphics image, then iterates placements and prints image metadata:

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 cell pixel dimensions so kitty graphics can compute grid sizes. */
  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);
 
  /*
   * 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);
 
  /* Query the kitty graphics storage to verify the image was stored. */
  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;
  }
  printf("\nKitty graphics storage is available.\n");
 
  /* Iterate placements to find the image ID. */
  GhosttyKittyGraphicsPlacementIterator iter = NULL;
  if (ghostty_kitty_graphics_placement_iterator_new(NULL, &iter) != GHOSTTY_SUCCESS) {
    fprintf(stderr, "Failed to create placement iterator\n");
    return 1;
  }
  if (ghostty_kitty_graphics_get(graphics,
          GHOSTTY_KITTY_GRAPHICS_DATA_PLACEMENT_ITERATOR, &iter) != GHOSTTY_SUCCESS) {
    fprintf(stderr, "Failed to get placement iterator\n");
    return 1;
  }
 
  int placement_count = 0;
  while (ghostty_kitty_graphics_placement_next(iter)) {
    placement_count++;
    uint32_t image_id = 0;
    uint32_t placement_id = 0;
    bool is_virtual = false;
    int32_t z = 0;
 
    ghostty_kitty_graphics_placement_get_multi(iter, 4,
        (GhosttyKittyGraphicsPlacementData[]){
            GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_IMAGE_ID,
            GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_PLACEMENT_ID,
            GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_IS_VIRTUAL,
            GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_Z,
        },
        (void*[]){ &image_id, &placement_id, &is_virtual, &z },
        NULL);
 
    printf("  placement #%d: image_id=%u placement_id=%u virtual=%s z=%d\n",
           placement_count, image_id, placement_id,
           is_virtual ? "true" : "false", z);
 
    /* Look up the image and print its properties. */
    GhosttyKittyGraphicsImage image =
        ghostty_kitty_graphics_image(graphics, image_id);
    if (!image) {
      fprintf(stderr, "Failed to look up image %u\n", image_id);
      return 1;
    }
 
    uint32_t width = 0, height = 0, number = 0;
    GhosttyKittyImageFormat format = 0;
    size_t data_len = 0;
 
    ghostty_kitty_graphics_image_get_multi(image, 5,
        (GhosttyKittyGraphicsImageData[]){
            GHOSTTY_KITTY_IMAGE_DATA_NUMBER,
            GHOSTTY_KITTY_IMAGE_DATA_WIDTH,
            GHOSTTY_KITTY_IMAGE_DATA_HEIGHT,
            GHOSTTY_KITTY_IMAGE_DATA_FORMAT,
            GHOSTTY_KITTY_IMAGE_DATA_DATA_LEN,
        },
        (void*[]){ &number, &width, &height, &format, &data_len },
        NULL);
 
    printf("    image: number=%u size=%ux%u format=%d data_len=%zu\n",
           number, width, height, format, data_len);
 
    /* Compute the rendered pixel size and grid size. */
    uint32_t px_w = 0, px_h = 0, cols = 0, rows = 0;
    if (ghostty_kitty_graphics_placement_pixel_size(iter, image, terminal,
            &px_w, &px_h) == GHOSTTY_SUCCESS) {
      printf("    rendered pixel size: %ux%u\n", px_w, px_h);
    }
    if (ghostty_kitty_graphics_placement_grid_size(iter, image, terminal,
            &cols, &rows) == GHOSTTY_SUCCESS) {
      printf("    grid size: %u cols x %u rows\n", cols, rows);
    }
  }
  printf("Total placements: %d\n", placement_count);
  ghostty_kitty_graphics_placement_iterator_free(iter);
 
  /* 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_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
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_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE }

Functions
GHOSTTY_API GhosttyResult	ghostty_kitty_graphics_get (GhosttyKittyGraphics graphics, GhosttyKittyGraphicsData data, void *out)
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 107 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 118 of file types.h.

◆ GhosttyKittyGraphicsPlacementIterator

typedef struct GhosttyKittyGraphicsPlacementIteratorImpl* GhosttyKittyGraphicsPlacementIterator

Opaque handle to a Kitty graphics placement iterator.

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

Definition at line 125 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 *

Definition at line 110 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. Output type: GhosttyKittyImageFormat *
GHOSTTY_KITTY_IMAGE_DATA_COMPRESSION	Compression of the image. 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. Output type: const uint8_t **
GHOSTTY_KITTY_IMAGE_DATA_DATA_LEN	Length of the raw pixel data in bytes. Output type: size_t *

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

Definition at line 285 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 (unicode placeholder). 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 *

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

Definition at line 130 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

Set the z-layer filter for the iterator.

Input type: GhosttyKittyPlacementLayer *

Definition at line 245 of file kitty_graphics.h.

◆ GhosttyKittyImageCompression

enum GhosttyKittyImageCompression

Compression of a Kitty graphics image.

Definition at line 274 of file kitty_graphics.h.

◆ GhosttyKittyImageFormat

enum GhosttyKittyImageFormat

Pixel format of a Kitty graphics image.

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

Definition at line 260 of file kitty_graphics.h.

◆ GhosttyKittyPlacementLayer

enum GhosttyKittyPlacementLayer

Z-layer classification for kitty graphics placements.

Based on the kitty protocol z-index conventions:

BELOW_BG: z < INT32_MIN/2 (drawn below cell background)
BELOW_TEXT: INT32_MIN/2 <= z < 0 (above background, below text)
ABOVE_TEXT: z >= 0 (above text)
ALL: no filtering (current behavior)

Definition at line 232 of file kitty_graphics.h.

Function Documentation

◆ 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.

◆ 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.

◆ 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

◆ 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.

◆ 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

◆ 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

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

◆ 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

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

◆ 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)

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

◆ 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

	Memory Management	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

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

◆ 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

◆ 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

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

◆ 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

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

◆ 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

◆ 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 rendering geometry for a placement in a single call.

Combines pixel size, grid size, viewport position, and source rectangle into one struct. Initialize with GHOSTTY_INIT_SIZED(GhosttyKittyGraphicsPlacementRenderInfo).

When viewport_visible is false, the placement is fully off-screen or is a virtual placement; viewport_col and viewport_row may contain meaningless values in that case.

Parameters

	iterator	The iterator positioned on a placement
	image	The image handle for this placement's image
	Terminal	The terminal handle
[out]	out_info	Pointer to receive the rendering geometry

Returns: GHOSTTY_SUCCESS on success

◆ 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

◆ 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 viewport-relative grid position of the current placement.

Converts the placement's internal pin to viewport-relative column and row coordinates. The returned coordinates represent the top-left corner of the placement in the viewport's grid coordinate space.

The row value can be negative when the placement's origin has scrolled above the top of the viewport. For example, a 4-row image that has scrolled up by 2 rows returns row=-2, meaning its top 2 rows are above the visible area but its bottom 2 rows are still on screen. Embedders should use these coordinates directly when computing the destination rectangle for rendering; the embedder is responsible for clipping the portion of the image that falls outside the viewport.

Returns GHOSTTY_SUCCESS for any placement that is at least partially visible in the viewport. Returns GHOSTTY_NO_VALUE when the placement is completely outside the viewport (its bottom edge is above the viewport or its top edge is at or below the last viewport row), or when the placement is a virtual (unicode placeholder) placement.

Parameters

	iterator	The placement iterator positioned on a placement
	image	The image handle for this placement's image
	Terminal	The terminal handle
[out]	out_col	On success, receives the viewport-relative column
[out]	out_row	On success, receives the viewport-relative row (may be negative for partially visible placements)

Returns: GHOSTTY_SUCCESS on success, GHOSTTY_NO_VALUE if fully off-screen or virtual, GHOSTTY_INVALID_VALUE if any handle is NULL or the iterator is not positioned

Detailed Description

Obtaining a KittyGraphics Handle

Iterating Placements

Looking Up Images

Rendering Helpers

Lifetime and Thread Safety

Example

Typedefs

Enumerations

Functions

Data Structures

Typedef Documentation

◆ GhosttyKittyGraphics

◆ GhosttyKittyGraphicsImage

◆ GhosttyKittyGraphicsPlacementIterator

Enumeration Type Documentation

◆ GhosttyKittyGraphicsData

◆ GhosttyKittyGraphicsImageData

◆ GhosttyKittyGraphicsPlacementData

◆ GhosttyKittyGraphicsPlacementIteratorOption

◆ GhosttyKittyImageCompression

◆ GhosttyKittyImageFormat

◆ GhosttyKittyPlacementLayer

Function Documentation

◆ ghostty_kitty_graphics_get()

◆ ghostty_kitty_graphics_image()

◆ ghostty_kitty_graphics_image_get()

◆ ghostty_kitty_graphics_image_get_multi()

◆ ghostty_kitty_graphics_placement_get()

◆ ghostty_kitty_graphics_placement_get_multi()

◆ ghostty_kitty_graphics_placement_grid_size()

◆ ghostty_kitty_graphics_placement_iterator_free()

◆ ghostty_kitty_graphics_placement_iterator_new()

◆ ghostty_kitty_graphics_placement_iterator_set()

◆ ghostty_kitty_graphics_placement_next()

◆ ghostty_kitty_graphics_placement_pixel_size()

◆ ghostty_kitty_graphics_placement_rect()

◆ ghostty_kitty_graphics_placement_render_info()

◆ ghostty_kitty_graphics_placement_source_rect()

◆ ghostty_kitty_graphics_placement_viewport_pos()