 |
libghostty
|
|
libghostty
|
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.
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.
Placements are inspected through a GhosttyKittyGraphicsPlacementIterator. The typical workflow is:
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.
Several functions assist with rendering a placement:
Generation stamps allow renderers to cheaply detect whether Kitty graphics state changed between frames:
Stamps are unique and monotonically increasing process-wide, so caches keyed on a generation value never alias across screens (main/alternate), resets, or terminals.
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.
The following example creates a terminal, sends a Kitty graphics image, then iterates placements and prints image metadata:
Typedefs | |
| typedef struct GhosttyKittyGraphicsImpl * | GhosttyKittyGraphics |
| typedef const struct GhosttyKittyGraphicsImageImpl * | GhosttyKittyGraphicsImage |
| typedef struct GhosttyKittyGraphicsPlacementIteratorImpl * | GhosttyKittyGraphicsPlacementIterator |
Data Structures | |
| struct | GhosttyKittyGraphicsPlacementRenderInfo |
| 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()).
| 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.
| typedef struct GhosttyKittyGraphicsPlacementIteratorImpl* GhosttyKittyGraphicsPlacementIterator |
Opaque handle to a Kitty graphics placement iterator.
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 | Generation stamp of the last content mutation to this storage: any image transmit/replace, placement add, or delete. Zero means the storage has never been mutated (and is therefore empty). If the generation is unchanged since a previous query, the set of placements and all image data are identical, so placement iteration and image staleness checks can be skipped entirely. Note that placement geometry may still have changed (scrolling and resizing move placements without changing the storage contents), so rendering geometry such as ghostty_kitty_graphics_placement_render_info() must still be recomputed for frames marked dirty. Stamps are unique and monotonically increasing process-wide: a value observed from any storage never recurs for different content, even across screen switches (main vs. alternate screen have independent storages) or terminal resets. It is therefore safe to key caches on this value alone. Output type: uint64_t * |
Definition at line 132 of file kitty_graphics.h.
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. 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. 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. Output type: size_t * |
| GHOSTTY_KITTY_IMAGE_DATA_GENERATION | Generation stamp assigned when this image was added to (or replaced in) the storage. A changed generation for a given image ID means the pixel contents may have changed even when the dimensions, format, and data length are identical (e.g. a retransmission of the same image ID), so texture caches must key staleness on this value rather than on size heuristics. Stamps are unique and monotonically increasing process-wide and are drawn from the same sequence as GHOSTTY_KITTY_GRAPHICS_DATA_GENERATION. Never zero for a stored image, so zero can be used as an "empty" sentinel by callers. Output type: uint64_t * |
Definition at line 342 of file kitty_graphics.h.
Queryable data kinds for ghostty_kitty_graphics_placement_get().
Definition at line 175 of file kitty_graphics.h.
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 290 of file kitty_graphics.h.
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 331 of file kitty_graphics.h.
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.
Definition at line 311 of file kitty_graphics.h.
Z-layer classification for kitty graphics placements.
Based on the kitty protocol z-index conventions:
Definition at line 277 of file kitty_graphics.h.
| 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.
| graphics | The kitty graphics handle | |
| data | The type of data to extract | |
| [out] | out | Pointer to store the extracted data |
| 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.
| graphics | The kitty graphics handle |
| image_id | The image ID to look up |
| 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.
| image | The image handle (NULL returns GHOSTTY_INVALID_VALUE) | |
| data | The data kind to query | |
| [out] | out | Pointer to receive the queried value |
| 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).
| 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) |
| 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.
| iterator | The iterator handle (NULL returns GHOSTTY_INVALID_VALUE) | |
| data | The data kind to query | |
| [out] | out | Pointer to receive the queried value |
| 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).
| 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) |
| 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.
| 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 |
| GHOSTTY_API void ghostty_kitty_graphics_placement_iterator_free | ( | GhosttyKittyGraphicsPlacementIterator | iterator | ) |
Free a placement iterator.
| iterator | The iterator handle to free (may be NULL) |
| 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.
| Memory Management | Pointer to allocator, or NULL to use the default allocator | |
| [out] | out_iterator | On success, receives the created iterator handle |
| 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).
| 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) |
| 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.
| iterator | The iterator handle (may be NULL) |
| 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.
| 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 |
| 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.
| 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 |
| 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.
| 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 |
| 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.
| 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 |
| 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.
| 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) |
1.16.1