 |
libghostty-vt 0.0.0
|
|
libghostty-vt 0.0.0
|
Read the images that programs send with the Kitty graphics protocol. More...
Read the images that programs send with the Kitty graphics protocol.
GhosttyKittyGraphics is a handle to the image storage of the active screen, where the terminal keeps every image a program sends with the Kitty graphics protocol.
Read it from a terminal with GHOSTTY_TERMINAL_DATA_KITTY_GRAPHICS. Use it to read pixels, play animations, and inspect what the storage holds. It doesn't tell you where to draw. The render state does that.
Full program: c-vt-kitty-graphics/src/main.c
See Images for how to set up, decode PNGs, and draw images.
Typedefs | |
| typedef struct GhosttyKittyGraphicsImpl * | GhosttyKittyGraphics |
| typedef const struct GhosttyKittyGraphicsImageImpl * | GhosttyKittyGraphicsImage |
| typedef struct GhosttyKittyGraphicsPlacementIteratorImpl * | GhosttyKittyGraphicsPlacementIterator |
Data Structures | |
| struct | GhosttyKittyGraphicsPlacementRenderInfo |
Storage | |
| 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) |
Images | |
| 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) |
Placements | |
| 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) |
| 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 |
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. 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 48 of file kitty_graphics.h.
Queryable data kinds for ghostty_kitty_graphics_image_get().
| Enumerator | |
|---|---|
| GHOSTTY_KITTY_GRAPHICS_IMAGE_DATA_INVALID | Invalid / sentinel value. |
| GHOSTTY_KITTY_GRAPHICS_IMAGE_DATA_ID | The image ID. Output type: uint32_t * |
| GHOSTTY_KITTY_GRAPHICS_IMAGE_DATA_NUMBER | The image number. Output type: uint32_t * |
| GHOSTTY_KITTY_GRAPHICS_IMAGE_DATA_WIDTH | Image width in pixels. Output type: uint32_t * |
| GHOSTTY_KITTY_GRAPHICS_IMAGE_DATA_HEIGHT | Image height in pixels. Output type: uint32_t * |
| GHOSTTY_KITTY_GRAPHICS_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_GRAPHICS_IMAGE_DATA_COMPRESSION | Compression of the image. Always GHOSTTY_KITTY_IMAGE_COMPRESSION_NONE; compressed payloads are inflated before storage. Output type: GhosttyKittyImageCompression * |
| GHOSTTY_KITTY_GRAPHICS_IMAGE_DATA_PIXELS | The image's pixel data. The string points into memory owned by the terminal and stays valid until the terminal is next modified. Its length is always width * height * bytes per pixel for the reported format. Returns GHOSTTY_NO_VALUE if the image's pixels have not arrived yet. The expected size is still available through GHOSTTY_KITTY_GRAPHICS_IMAGE_DATA_EXPECTED_LEN. The data is always fully decoded, uncompressed pixels in the format reported by GHOSTTY_KITTY_GRAPHICS_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_GRAPHICS_IMAGE_DATA_GENERATION changes whenever the current frame changes, so generation-keyed caches remain coherent. GhosttyString pixels;
image, GHOSTTY_KITTY_GRAPHICS_IMAGE_DATA_PIXELS, &pixels) ==
}
GHOSTTY_API GhosttyResult ghostty_kitty_graphics_image_get(GhosttyKittyGraphicsImage image, GhosttyKittyGraphicsImageData data, void *out) @ GHOSTTY_KITTY_GRAPHICS_IMAGE_DATA_PIXELS Definition kitty_graphics.h:355 Definition types.h:439 Output type: GhosttyString * |
| GHOSTTY_KITTY_GRAPHICS_IMAGE_DATA_EXPECTED_LEN | The size of the image's pixel data in bytes, which is width * height * bytes per pixel for the reported format. This is available even before the pixels arrive, when GHOSTTY_KITTY_GRAPHICS_IMAGE_DATA_PIXELS still returns GHOSTTY_NO_VALUE. In that case the image already counts this many bytes against the storage limit. Once the pixels arrive, this equals the length of GHOSTTY_KITTY_GRAPHICS_IMAGE_DATA_PIXELS. Output type: size_t * |
| GHOSTTY_KITTY_GRAPHICS_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_GRAPHICS_IMAGE_DATA_PIXELS starts returning the pixels. GHOSTTY_KITTY_GRAPHICS_DATA_GENERATION changes when that happens, so read PIXELS again then. Output type: uint64_t * |
Definition at line 273 of file kitty_graphics.h.
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 Placeholders. 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 88 of file kitty_graphics.h.
Settable options for ghostty_kitty_graphics_placement_iterator_set().
| Enumerator | |
|---|---|
| GHOSTTY_KITTY_GRAPHICS_PLACEMENT_ITERATOR_OPT_INVALID | Not a real option. ghostty_kitty_graphics_placement_iterator_set() returns GHOSTTY_INVALID_VALUE for it. Its value is 0, so a zeroed or uninitialized variable is never mistaken for a real option. |
| GHOSTTY_KITTY_GRAPHICS_PLACEMENT_ITERATOR_OPT_LAYER | Only visit placements in the chosen layers. The value is a mask with one bit for each GhosttyImageLayer. Combine the GHOSTTY_IMAGE_LAYER_MASK_* macros with | to choose layers. For example, this visits every placement except the ones drawn below the cell backgrounds: uint32_t mask = GHOSTTY_IMAGE_LAYER_MASK_BELOW_TEXT |
iterator, GHOSTTY_KITTY_GRAPHICS_PLACEMENT_ITERATOR_OPT_LAYER, &mask);
GHOSTTY_API GhosttyResult ghostty_kitty_graphics_placement_iterator_set(GhosttyKittyGraphicsPlacementIterator iterator, GhosttyKittyGraphicsPlacementIteratorOption option, const void *value) @ GHOSTTY_KITTY_GRAPHICS_PLACEMENT_ITERATOR_OPT_LAYER Definition kitty_graphics.h:227 #define GHOSTTY_IMAGE_LAYER_MASK_BELOW_TEXT Definition types.h:422 #define GHOSTTY_IMAGE_LAYER_MASK_ABOVE_TEXT Definition types.h:426 A mask of 0 or a NULL value turns the filter off, and the iterator visits every placement. This is the default. A mask with a bit that matches no layer returns GHOSTTY_INVALID_VALUE and keeps the current filter. Each placement's layer comes from its z-index, using the ranges listed in GhosttyImageLayer. This filter only applies to the storage iterator. To draw images, use the layer the render state reports for each entry (GHOSTTY_RENDER_STATE_IMAGE_DATA_LAYER). The render state uses the same ranges and also includes virtual placements, which are always drawn below the text. Input type: const uint32_t * |
Definition at line 190 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 262 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 242 of file kitty_graphics.h.
| 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_GRAPHICS_IMAGE_DATA_GENERATION, and their GHOSTTY_KITTY_GRAPHICS_IMAGE_DATA_PIXELS 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. Animation explains how to schedule redraws with the returned time and includes an example.
| 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. |
| 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_UNSUPPORTED 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.
Use this when each call into the library is expensive, for example from WebAssembly or from another language through its foreign function interface. It reads every key in one call. From C in the same process it costs the same as calling ghostty_kitty_graphics_image_get() once per key, so use whichever reads better.
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.
Use this when each call into the library is expensive, for example from WebAssembly or from another language through its foreign function interface. It reads every key in one call. From C in the same process it costs the same as calling ghostty_kitty_graphics_placement_get() once per key, so use whichever reads better.
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.
| allocator | 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_OPT_LAYER to visit only the placements in some layers. ghostty_kitty_graphics_placement_next() then skips every placement outside those layers. By default, the iterator visits every placement.
| iterator | The iterator handle (NULL returns GHOSTTY_INVALID_VALUE) |
| option | The option to set |
| value | Pointer to the value. Its type depends on the option. NULL resets the option to its default. |
| 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 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.
The call succeeds even when the placement isn't in the viewport. Check viewport_visible before using viewport_col and viewport_row.
| 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 |
| 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 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.
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.
| 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 |
1.17.0