 |
libghostty-vt 0.0.0
|
|
libghostty-vt 0.0.0
|
Find out what changed since the last frame and read the rows and cells to draw. More...
Find out what changed since the last frame and read the rows and cells to draw.
A render state is a copy of everything you need to draw one frame: the rows, the cells, the cursor, and the colors. It only needs the terminal during an update, so everything after that can happen while the terminal keeps working.
Use this when you draw the terminal yourself.
Full program: c-vt-render/src/main.c
See Rendering for how to draw a frame, track what changed, respect render holds, and use overscan and row identity. See Images for drawing images.
Typedefs | |
| typedef struct GhosttyRenderStateImpl * | GhosttyRenderState |
| typedef struct GhosttyRenderStateRowIteratorImpl * | GhosttyRenderStateRowIterator |
| typedef struct GhosttyRenderStateRowCellsImpl * | GhosttyRenderStateRowCells |
| typedef struct GhosttyRenderStateImageIteratorImpl * | GhosttyRenderStateImageIterator |
Macros | |
| #define | GHOSTTY_IMAGE_LAYER_MASK_BELOW_BACKGROUND (1u << GHOSTTY_IMAGE_LAYER_BELOW_BACKGROUND) |
| #define | GHOSTTY_IMAGE_LAYER_MASK_BELOW_TEXT (1u << GHOSTTY_IMAGE_LAYER_BELOW_TEXT) |
| #define | GHOSTTY_IMAGE_LAYER_MASK_ABOVE_TEXT (1u << GHOSTTY_IMAGE_LAYER_ABOVE_TEXT) |
Data Structures | |
| struct | GhosttyRenderStateOverscan |
| struct | GhosttyRenderStateRowId |
| struct | GhosttyRenderStateRowSelection |
| struct | GhosttyRenderStateCursor |
| struct | GhosttyRenderStateColors |
Lifecycle | |
| GHOSTTY_API GhosttyResult | ghostty_render_state_new (const GhosttyAllocator *allocator, GhosttyRenderState *state) |
| GHOSTTY_API void | ghostty_render_state_free (GhosttyRenderState state) |
Updating | |
| GHOSTTY_API GhosttyResult | ghostty_render_state_update (GhosttyRenderState state, GhosttyTerminal terminal) |
| GHOSTTY_API GhosttyResult | ghostty_render_state_begin_update (GhosttyRenderState state, GhosttyTerminal terminal) |
| GHOSTTY_API GhosttyResult | ghostty_render_state_end_update (GhosttyRenderState state) |
| GHOSTTY_API GhosttyResult | ghostty_render_state_clean (GhosttyRenderState state) |
Reading State | |
| GHOSTTY_API GhosttyResult | ghostty_render_state_get (GhosttyRenderState state, GhosttyRenderStateData data, void *out) |
| GHOSTTY_API GhosttyResult | ghostty_render_state_get_multi (GhosttyRenderState state, size_t count, const GhosttyRenderStateData *keys, void **values, size_t *out_written) |
| GHOSTTY_API GhosttyResult | ghostty_render_state_set (GhosttyRenderState state, GhosttyRenderStateOption option, const void *value) |
Rows | |
| GHOSTTY_API GhosttyResult | ghostty_render_state_row_iterator_new (const GhosttyAllocator *allocator, GhosttyRenderStateRowIterator *out_iterator) |
| GHOSTTY_API void | ghostty_render_state_row_iterator_free (GhosttyRenderStateRowIterator iterator) |
| GHOSTTY_API bool | ghostty_render_state_row_iterator_next (GhosttyRenderStateRowIterator iterator) |
| GHOSTTY_API bool | ghostty_render_state_row_iterator_next_dirty (GhosttyRenderStateRowIterator iterator, uint16_t *out_y) |
| GHOSTTY_API GhosttyResult | ghostty_render_state_row_get (GhosttyRenderStateRowIterator iterator, GhosttyRenderStateRowData data, void *out) |
| GHOSTTY_API GhosttyResult | ghostty_render_state_row_get_multi (GhosttyRenderStateRowIterator iterator, size_t count, const GhosttyRenderStateRowData *keys, void **values, size_t *out_written) |
| GHOSTTY_API GhosttyResult | ghostty_render_state_row_set (GhosttyRenderStateRowIterator iterator, GhosttyRenderStateRowOption option, const void *value) |
Cells | |
| GHOSTTY_API GhosttyResult | ghostty_render_state_row_cells_new (const GhosttyAllocator *allocator, GhosttyRenderStateRowCells *out_cells) |
| GHOSTTY_API bool | ghostty_render_state_row_cells_next (GhosttyRenderStateRowCells cells) |
| GHOSTTY_API GhosttyResult | ghostty_render_state_row_cells_select (GhosttyRenderStateRowCells cells, uint16_t x) |
| GHOSTTY_API GhosttyResult | ghostty_render_state_row_cells_get (GhosttyRenderStateRowCells cells, GhosttyRenderStateRowCellsData data, void *out) |
| GHOSTTY_API GhosttyResult | ghostty_render_state_row_cells_get_multi (GhosttyRenderStateRowCells cells, size_t count, const GhosttyRenderStateRowCellsData *keys, void **values, size_t *out_written) |
| GHOSTTY_API void | ghostty_render_state_row_cells_free (GhosttyRenderStateRowCells cells) |
Images | |
| GHOSTTY_API GhosttyResult | ghostty_render_state_image_iterator_new (const GhosttyAllocator *allocator, GhosttyRenderStateImageIterator *out_iterator) |
| GHOSTTY_API void | ghostty_render_state_image_iterator_free (GhosttyRenderStateImageIterator iterator) |
| GHOSTTY_API bool | ghostty_render_state_image_iterator_next (GhosttyRenderStateImageIterator iterator) |
| GHOSTTY_API GhosttyResult | ghostty_render_state_image_get (GhosttyRenderStateImageIterator iterator, GhosttyRenderStateImageData data, void *out) |
| GHOSTTY_API GhosttyResult | ghostty_render_state_image_get_multi (GhosttyRenderStateImageIterator iterator, size_t count, const GhosttyRenderStateImageData *keys, void **values, size_t *out_written) |
| typedef struct GhosttyRenderStateImpl* GhosttyRenderState |
Opaque handle to a render state instance.
| typedef struct GhosttyRenderStateImageIteratorImpl* GhosttyRenderStateImageIterator |
Opaque handle to an iterator over the image placements of a render state.
| typedef struct GhosttyRenderStateRowCellsImpl* GhosttyRenderStateRowCells |
Opaque handle to render-state row cells.
| typedef struct GhosttyRenderStateRowIteratorImpl* GhosttyRenderStateRowIterator |
Opaque handle to a render-state row iterator.
| enum GhosttyImageLayer |
Where an image is drawn relative to the terminal's text.
Draw each frame from the bottom up, in this order:
Within a layer, draw images in order of their z-index, lowest first.
A Kitty graphics placement's layer comes from its z-index. Each value below lists its z-index range. For example, a placement with z-index -1 is in GHOSTTY_IMAGE_LAYER_BELOW_TEXT.
The render state reports each image's layer with GHOSTTY_RENDER_STATE_IMAGE_DATA_LAYER. To visit only some layers with the Kitty graphics placement iterator, build a mask from the GHOSTTY_IMAGE_LAYER_MASK_* macros and set it with GHOSTTY_KITTY_GRAPHICS_PLACEMENT_ITERATOR_OPT_LAYER.
| enum GhosttyImageProtocol |
The image protocols that a terminal supports.
The render state uses this to say which protocol each image placement came from (see GHOSTTY_RENDER_STATE_IMAGE_DATA_PROTOCOL). Use it to decide where to read the image's pixels. Unlike the other image types here, the name has no RenderState prefix, because the protocol isn't specific to the render state.
New protocols may be added in later versions. Skip placements with a protocol you don't support.
| Enumerator | |
|---|---|
| GHOSTTY_IMAGE_PROTOCOL_KITTY | The Kitty graphics protocol. Read the image with ghostty_kitty_graphics_image(). |
Queryable data kinds for ghostty_render_state_get().
| Enumerator | |
|---|---|
| GHOSTTY_RENDER_STATE_DATA_INVALID | Invalid / sentinel value. |
| GHOSTTY_RENDER_STATE_DATA_COLS | Viewport width in cells (uint16_t). |
| GHOSTTY_RENDER_STATE_DATA_ROWS | Viewport height in cells (uint16_t). This does not include overscan rows. |
| GHOSTTY_RENDER_STATE_DATA_DIRTY | Current dirty state (GhosttyRenderStateDirty). |
| GHOSTTY_RENDER_STATE_DATA_ROW_ITERATOR | Populate a pre-allocated GhosttyRenderStateRowIterator with row data from the render state (GhosttyRenderStateRowIterator). Row data is only valid as long as the underlying render state is not updated. It is unsafe to use row data after updating the render state. The iterator visits every row the last update captured, from top to bottom. This is exactly the viewport unless overscan was requested with GHOSTTY_RENDER_STATE_OPT_OVERSCAN. |
| GHOSTTY_RENDER_STATE_DATA_COLOR_BACKGROUND | Default/current background color (GhosttyColorRgb). |
| GHOSTTY_RENDER_STATE_DATA_COLOR_FOREGROUND | Default/current foreground color (GhosttyColorRgb). |
| GHOSTTY_RENDER_STATE_DATA_COLOR_CURSOR | Cursor color when explicitly set by terminal state (GhosttyColorRgb). Returns GHOSTTY_INVALID_VALUE if no explicit cursor color is set; use COLOR_CURSOR_HAS_VALUE to check first. |
| GHOSTTY_RENDER_STATE_DATA_COLOR_CURSOR_HAS_VALUE | Whether an explicit cursor color is set (bool). |
| GHOSTTY_RENDER_STATE_DATA_COLOR_PALETTE | The active 256-color palette (GhosttyColorRgb[256]). |
| GHOSTTY_RENDER_STATE_DATA_CURSOR_VISUAL_STYLE | The visual style of the cursor (GhosttyCursorStyle). |
| GHOSTTY_RENDER_STATE_DATA_CURSOR_VISIBLE | Whether the cursor is visible based on terminal modes (bool). |
| GHOSTTY_RENDER_STATE_DATA_CURSOR_BLINKING | Whether the cursor should blink based on terminal modes (bool). |
| GHOSTTY_RENDER_STATE_DATA_CURSOR_PASSWORD_INPUT | Whether the cursor is at a password input field (bool). |
| GHOSTTY_RENDER_STATE_DATA_CURSOR_VIEWPORT_HAS_VALUE | Whether the cursor is visible within the viewport (bool). If false, the cursor viewport position values are undefined. |
| GHOSTTY_RENDER_STATE_DATA_CURSOR_VIEWPORT_X | Cursor viewport x position in cells (uint16_t). Only valid when CURSOR_VIEWPORT_HAS_VALUE is true. |
| GHOSTTY_RENDER_STATE_DATA_CURSOR_VIEWPORT_Y | Cursor viewport y position in cells (uint16_t). Only valid when CURSOR_VIEWPORT_HAS_VALUE is true. |
| GHOSTTY_RENDER_STATE_DATA_CURSOR_VIEWPORT_WIDE_TAIL | Whether the cursor is on the tail of a wide character (bool). Only valid when CURSOR_VIEWPORT_HAS_VALUE is true. |
| GHOSTTY_RENDER_STATE_DATA_CURSOR | All cursor state in one sized struct (GhosttyRenderStateCursor). Initialize the output with GHOSTTY_INIT_SIZED before querying. |
| GHOSTTY_RENDER_STATE_DATA_COLORS | All render-state colors in one sized struct (GhosttyRenderStateColors). Initialize the output with GHOSTTY_INIT_SIZED before querying. |
| GHOSTTY_RENDER_STATE_DATA_OVERSCAN | How many overscan rows the last update captured on each side (GhosttyRenderStateOverscan). This is never more than the request. It is less when those rows don't exist: above is smaller near the top of the scrollback, and below is zero while the viewport is scrolled to the bottom. |
| GHOSTTY_RENDER_STATE_DATA_OVERSCAN_REQUEST | The overscan request most recently set with GHOSTTY_RENDER_STATE_OPT_OVERSCAN (GhosttyRenderStateOverscan). The next update uses this request. Both sides are zero if it was never set. |
| GHOSTTY_RENDER_STATE_DATA_IMAGE_ITERATOR | Populate an existing GhosttyRenderStateImageIterator with the image placements found by the last update. See Drawing images. |
| GHOSTTY_RENDER_STATE_DATA_IMAGE_PLACEMENTS_GENERATION | A value (uint64_t) that changes whenever an update changes the placements that GHOSTTY_RENDER_STATE_DATA_IMAGE_ITERATOR returns. If it matches the value from the last time you read the iterator, the placements are the same and you don't need to read them again. See Knowing what changed for an example and for exactly when the value changes. The value belongs to the whole list. To know when the pixels of a single image changed, use GHOSTTY_RENDER_STATE_IMAGE_DATA_IMAGE_GENERATION. Only compare the value for equality. It is always 0 when Kitty graphics are disabled. |
Dirty state of a render state after update.
Data you can read about the current placement of an image iterator with ghostty_render_state_image_get().
The type in parentheses is the type that the out pointer must point to. All pixel values use the cell size set with ghostty_terminal_resize().
Some values only apply to one protocol, and have the protocol in their name. For example, GHOSTTY_RENDER_STATE_IMAGE_DATA_KITTY_KIND only applies to Kitty graphics placements. Reading one of these for a placement from another protocol returns GHOSTTY_NO_VALUE.
| Enumerator | |
|---|---|
| GHOSTTY_RENDER_STATE_IMAGE_DATA_INVALID | Invalid value. Querying it returns GHOSTTY_INVALID_VALUE. |
| GHOSTTY_RENDER_STATE_IMAGE_DATA_PROTOCOL | The protocol the image came from (GhosttyImageProtocol). |
| GHOSTTY_RENDER_STATE_IMAGE_DATA_IMAGE_ID | The ID of the image to draw (uint32_t). IDs are only unique within one protocol, so look the image up in the storage of its protocol. For Kitty graphics, use ghostty_kitty_graphics_image(). |
| GHOSTTY_RENDER_STATE_IMAGE_DATA_IMAGE_GENERATION | The generation of the image's contents (uint64_t). It changes whenever the image's pixels change, including when an animation moves to a new frame. Use it as part of your texture cache key, with the protocol and image ID: if it matches the texture you have, you don't need to read the pixels again. For Kitty graphics, this is the same value as GHOSTTY_KITTY_GRAPHICS_IMAGE_DATA_GENERATION. To know when the list of placements as a whole changed, use GHOSTTY_RENDER_STATE_DATA_IMAGE_PLACEMENTS_GENERATION. |
| GHOSTTY_RENDER_STATE_IMAGE_DATA_LAYER | The layer to draw the image in (GhosttyImageLayer). |
| GHOSTTY_RENDER_STATE_IMAGE_DATA_Z | The z-index (int32_t), which orders images within a layer. Images with a lower z-index are drawn first. The value comes from the image's protocol. For Kitty graphics, it is the z-index the program asked for, and virtual placements are always -1. |
| GHOSTTY_RENDER_STATE_IMAGE_DATA_VIEWPORT_COL | The column of the top-left cell (int32_t), where 0 is the leftmost column of the viewport. Fixed and relative placements are reported at their full size, so they can start to the left of the viewport, which gives a negative value. Virtual placements never do. See Images partly outside the captured rows. |
| GHOSTTY_RENDER_STATE_IMAGE_DATA_VIEWPORT_ROW | The row of the top-left cell (int32_t), where 0 is the top row of the viewport. A placement in an overscan row above the viewport has a negative row, the same as GHOSTTY_RENDER_STATE_ROW_DATA_VIEWPORT_Y. Fixed and relative placements are reported at their full size, so they can also start above the first overscan row. Virtual placements are always inside the captured rows. See Images partly outside the captured rows. |
| GHOSTTY_RENDER_STATE_IMAGE_DATA_GRID_COLS | The number of columns of cells the placement covers (uint32_t). |
| GHOSTTY_RENDER_STATE_IMAGE_DATA_GRID_ROWS | The number of rows of cells the placement covers (uint32_t). |
| GHOSTTY_RENDER_STATE_IMAGE_DATA_CELL_OFFSET_X | How far the image starts from the left edge of the top-left cell, in pixels (uint32_t). For a virtual placement, an image that is narrower than its cells is centered, so this can be larger than a cell is wide. For fixed and relative placements, this is the offset the program asked for, limited to less than one cell. |
| GHOSTTY_RENDER_STATE_IMAGE_DATA_CELL_OFFSET_Y | How far the image starts from the top edge of the top-left cell, in pixels (uint32_t). For a virtual placement, an image that is shorter than its cells is centered, so this can be larger than a cell is tall. For fixed and relative placements, this is the offset the program asked for, limited to less than one cell. |
| GHOSTTY_RENDER_STATE_IMAGE_DATA_PIXEL_WIDTH | The width to draw the image at, in pixels (uint32_t). |
| GHOSTTY_RENDER_STATE_IMAGE_DATA_PIXEL_HEIGHT | The height to draw the image at, in pixels (uint32_t). |
| GHOSTTY_RENDER_STATE_IMAGE_DATA_SOURCE_X | The left edge of the part of the image to draw, in image pixels (uint32_t). |
| GHOSTTY_RENDER_STATE_IMAGE_DATA_SOURCE_Y | The top edge of the part of the image to draw, in image pixels (uint32_t). |
| GHOSTTY_RENDER_STATE_IMAGE_DATA_SOURCE_WIDTH | The width of the part of the image to draw, in image pixels (uint32_t). Scale it to PIXEL_WIDTH when drawing. |
| GHOSTTY_RENDER_STATE_IMAGE_DATA_SOURCE_HEIGHT | The height of the part of the image to draw, in image pixels (uint32_t). Scale it to PIXEL_HEIGHT when drawing. |
| GHOSTTY_RENDER_STATE_IMAGE_DATA_KITTY_PLACEMENT_ID | Kitty graphics only: the placement ID (uint32_t), or 0 if there isn't one. For a virtual placement, this is the placement ID that the placeholder cells ask for. Cells that don't ask for one show the image's virtual placement, whichever it is, and report 0. For a fixed or relative placement, this is the ID the program gave it, or 0 if it didn't give one. |
| GHOSTTY_RENDER_STATE_IMAGE_DATA_KITTY_KIND | Kitty graphics only: the kind of placement (GhosttyRenderStateKittyPlacementKind). |
The kinds of Kitty graphics placements in a render state's image list.
Read with GHOSTTY_RENDER_STATE_IMAGE_DATA_KITTY_KIND. Most renderers can draw every kind the same way. The kind is useful when you need to tell them apart, for example for debugging.
| Enumerator | |
|---|---|
| GHOSTTY_RENDER_STATE_KITTY_PLACEMENT_KIND_VIRTUAL | Part of a virtual placement: one run of neighboring placeholder cells in a single row. It is always one row tall. |
| GHOSTTY_RENDER_STATE_KITTY_PLACEMENT_KIND_RELATIVE | A placement that a program positioned relative to another placement, its parent. Kitty graphics lets a program attach one image to another so that they move together. The parent is either a virtual or a fixed placement, possibly through a chain of other relative placements. With a virtual parent, the position depends on the placeholder cells. It is measured from the top-left corner of the parent's cells on screen. That is the leftmost column and the topmost row that any of its cells use, which matches Kitty. If none of those cells are in the captured rows (the viewport plus any overscan), the relative placement is not included. With a fixed parent, the position is measured from the parent's cell. The relative placement is included at its full size when any part of it is in the captured rows, even if the parent isn't, so it may need to be clipped when drawn. See Relative placements. |
| GHOSTTY_RENDER_STATE_KITTY_PLACEMENT_KIND_FIXED | A placement at a cell on the screen. It scrolls with the text, like a line of output would. Its z-index is the one the program chose, so it can be in any layer. It is included at its full size when any part of it is in the captured rows, so it may need to be clipped when drawn. See Images partly outside the captured rows. |
Settable options for ghostty_render_state_set().
| Enumerator | |
|---|---|
| GHOSTTY_RENDER_STATE_OPT_INVALID | Not a real option. ghostty_render_state_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_RENDER_STATE_OPT_DIRTY | Set dirty state (GhosttyRenderStateDirty). Each update sets this value itself, so there is no default to restore and a NULL value returns GHOSTTY_INVALID_VALUE. |
| GHOSTTY_RENDER_STATE_OPT_OVERSCAN | Request overscan rows above and below the viewport (GhosttyRenderStateOverscan). The request takes effect on the next update and stays in effect until it is changed. Both sides are zero by default, which captures only the viewport. A NULL value restores that default. The rows of the last update can still be read after changing the request. Expect a full redraw on the update after a change. See Overscan. |
Queryable data kinds for ghostty_render_state_row_cells_get().
| Enumerator | |
|---|---|
| GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_INVALID | Invalid / sentinel value. |
| GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_RAW | The raw cell value (GhosttyCell). |
| GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_STYLE | The style for the current cell (GhosttyStyle). |
| GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_GRAPHEMES_LEN | The total number of grapheme codepoints including the base codepoint (uint32_t). Returns 0 if the cell has no text. |
| GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_GRAPHEMES_BUF | Copy the cell's grapheme codepoints into a buffer you provide (GhosttyCodepointBuffer). The base codepoint comes first, followed by any extra codepoints. Up to cap codepoints are written, and len is set to the total number of codepoints in the cell. If they do not all fit, this returns GHOSTTY_OUT_OF_SPACE and the buffer holds the first cap of them. A cell with no text returns GHOSTTY_SUCCESS with len set to 0. uint32_t codepoints[16];
GhosttyCodepointBuffer graphemes = {.ptr = codepoints, .cap = 16};
cells, GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_GRAPHEMES_BUF, &graphemes);
if (result == GHOSTTY_OUT_OF_SPACE) {
// The cell has graphemes.len codepoints, but only the first 16
// were written. Retry with a larger buffer to get the rest.
}
GHOSTTY_API GhosttyResult ghostty_render_state_row_cells_get(GhosttyRenderStateRowCells cells, GhosttyRenderStateRowCellsData data, void *out) @ GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_GRAPHEMES_BUF Definition render.h:1032 Definition types.h:518 |
| GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_BG_COLOR | The resolved background color of the cell (GhosttyColorRgb). Flattens the three possible sources: content-tag bg_color_rgb, content-tag bg_color_palette (looked up in the palette), or the style's bg_color. Returns GHOSTTY_INVALID_VALUE if the cell has no background color, in which case you should use whatever default background color it wants (e.g. the terminal background). |
| GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_FG_COLOR | The resolved foreground color of the cell (GhosttyColorRgb). Resolves palette indices through the palette. Bold color handling is not applied; you should handle bold styling separately. Returns GHOSTTY_INVALID_VALUE if the cell has no explicit foreground color, in which case you should use whatever default foreground color it wants (e.g. the terminal foreground). |
| GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_SELECTED | Whether the cell is contained within the current selection (bool). This returns true when the cell's column is within the current row's row-local selection range, and false otherwise. Rendering policy for selected cells (colors, inversion, etc.) is left to you. Renderers that can draw cells in spans may be more efficient querying GHOSTTY_RENDER_STATE_ROW_DATA_SELECTION once per row and applying that range directly, avoiding one C API call per cell for selection state. |
| GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_HAS_STYLING | Whether the cell has any explicit styling (bool). This is equivalent to querying the raw cell's GHOSTTY_CELL_DATA_HAS_STYLING value, but avoids materializing the raw GhosttyCell for renderers that only need to know whether fetching the full style is necessary. |
| GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_GRAPHEMES_UTF8 | Encode the current cell's full grapheme cluster as UTF-8 into a caller-provided buffer (GhosttyBuffer). The base codepoint is encoded first, followed by any extra grapheme codepoints. Returns GHOSTTY_SUCCESS with len=0 when the cell has no text. If ptr is NULL or cap is too small for a non-empty cell, returns GHOSTTY_OUT_OF_SPACE without writing any bytes and sets len to the required buffer size in bytes. |
Queryable data kinds for ghostty_render_state_row_get().
| Enumerator | |
|---|---|
| GHOSTTY_RENDER_STATE_ROW_DATA_INVALID | Invalid / sentinel value. |
| GHOSTTY_RENDER_STATE_ROW_DATA_DIRTY | Whether the current row is dirty (bool). |
| GHOSTTY_RENDER_STATE_ROW_DATA_RAW | The raw row value (GhosttyRow). |
| GHOSTTY_RENDER_STATE_ROW_DATA_CELLS | Populate a pre-allocated GhosttyRenderStateRowCells with cell data for the current row (GhosttyRenderStateRowCells). Cell data is only valid as long as the underlying render state is not updated. It is unsafe to use cell data after updating the render state. |
| GHOSTTY_RENDER_STATE_ROW_DATA_SELECTION | Row-local selected cell range (GhosttyRenderStateRowSelection). |
| GHOSTTY_RENDER_STATE_ROW_DATA_CELLS_RAW | A borrowed view of the raw cell values for the current row (GhosttyCellsView). One value per column, identical to querying GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_RAW for each cell. The view is only valid as long as the underlying render state is not updated; it is unsafe to use after updating the render state. This is the bulk alternative to iterating cells one at a time. It lets callers with expensive call boundaries (e.g. WebAssembly embedders) read an entire row with a single call. Bit positions aren't protected by ABI, so callers should parse them out of the manifest from ghostty_type_json. Callers with access to the C header or without high FFI costs should use ghostty_cell_get. |
| GHOSTTY_RENDER_STATE_ROW_DATA_VIEWPORT_Y | The row's position relative to the top of the viewport (int32_t). Viewport rows are 0 through rows - 1. Overscan rows above the viewport are negative, and overscan rows below it start at rows. Without overscan, this equals the y reported by ghostty_render_state_row_iterator_next_dirty(). |
| GHOSTTY_RENDER_STATE_ROW_DATA_ID | The row's identity across updates (GhosttyRenderStateRowId). This works with or without overscan. See Row identity. |
Settable options for ghostty_render_state_row_set().
| Enumerator | |
|---|---|
| GHOSTTY_RENDER_STATE_ROW_OPT_INVALID | Not a real option. ghostty_render_state_row_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_RENDER_STATE_ROW_OPT_DIRTY | Set dirty state for the current row (bool). Each update sets this value itself, so there is no default to restore and a NULL value returns GHOSTTY_INVALID_VALUE. |
| GHOSTTY_API GhosttyResult ghostty_render_state_begin_update | ( | GhosttyRenderState | state, |
| GhosttyTerminal | terminal ) |
Begin an update of a render state instance from a terminal.
Every begin must be completed with a ghostty_render_state_end_update call before the render state is read.
This two-phase structure exists for callers that synchronize access to the terminal state (e.g. with a lock shared with an IO thread): only this function requires terminal access, so a caller can hold its lock for this call only and then call ghostty_render_state_end_update after releasing it. The end phase exclusively reads and writes memory owned by the render state, so it is safe to call while the terminal is being modified.
Work that doesn't require terminal access may be deferred to the end phase to keep this call (and therefore lock hold time) as short as possible. You must treat the render state as incomplete until ghostty_render_state_end_update is called.
This consumes terminal/screen dirty state in the same way as the internal render state update path.
| state | The render state handle (NULL returns GHOSTTY_INVALID_VALUE) |
| terminal | The terminal handle to read from (NULL returns GHOSTTY_INVALID_VALUE) |
| GHOSTTY_API GhosttyResult ghostty_render_state_clean | ( | GhosttyRenderState | state | ) |
Mark all dirty render-state data as consumed.
This sets the global dirty state to GHOSTTY_RENDER_STATE_DIRTY_FALSE and clears every per-row dirty flag. It is idempotent and does not modify cell contents or dirty state owned by the terminal. Call this only after a complete frame has been rendered successfully; partial consumers should use ghostty_render_state_set() and ghostty_render_state_row_set() instead.
| state | The render state handle (NULL returns GHOSTTY_INVALID_VALUE) |
| GHOSTTY_API GhosttyResult ghostty_render_state_end_update | ( | GhosttyRenderState | state | ) |
Complete a prior ghostty_render_state_begin_update call by performing any deferred work.
This only reads and writes memory owned by the render state, so it is safe to call while the terminal is being modified (no terminal synchronization is required). Calling this without a prior begin is a safe no-op.
| state | The render state handle (NULL returns GHOSTTY_INVALID_VALUE) |
| GHOSTTY_API void ghostty_render_state_free | ( | GhosttyRenderState | state | ) |
Free a render state instance.
Releases all resources associated with the render state. After this call, the render state handle becomes invalid.
| state | The render state handle to free (may be NULL) |
| GHOSTTY_API GhosttyResult ghostty_render_state_get | ( | GhosttyRenderState | state, |
| GhosttyRenderStateData | data, | ||
| void * | out ) |
Get a value from a render state.
The out pointer must point to a value of the type corresponding to the requested data kind (see GhosttyRenderStateData).
| state | The render state handle (NULL returns GHOSTTY_INVALID_VALUE) | |
| data | The data kind to query | |
| [out] | out | Pointer to receive the queried value |
| GHOSTTY_API GhosttyResult ghostty_render_state_get_multi | ( | GhosttyRenderState | state, |
| size_t | count, | ||
| const GhosttyRenderStateData * | keys, | ||
| void ** | values, | ||
| size_t * | out_written ) |
Get multiple data fields from a render state 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_render_state_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.
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).
| state | The render state 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_render_state_image_get | ( | GhosttyRenderStateImageIterator | iterator, |
| GhosttyRenderStateImageData | data, | ||
| void * | out ) |
Read one value from the current placement of an image iterator.
The out pointer must point to a value of the type listed for data in GhosttyRenderStateImageData. To read several values at once, use ghostty_render_state_image_get_multi().
| iterator | The iterator handle, moved to a placement with ghostty_render_state_image_iterator_next() | |
| data | The value to read | |
| [out] | out | Pointer that receives the value |
| GHOSTTY_API GhosttyResult ghostty_render_state_image_get_multi | ( | GhosttyRenderStateImageIterator | iterator, |
| size_t | count, | ||
| const GhosttyRenderStateImageData * | keys, | ||
| void ** | values, | ||
| size_t * | out_written ) |
Read several values from the current placement of an image iterator in one 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_render_state_image_get() once per key, so use whichever reads better.
values[i] receives the value for keys[i]. The keys are read in order, and reading stops at the first error.
| iterator | The iterator handle, moved to a placement with ghostty_render_state_image_iterator_next() | |
| count | The number of keys and values | |
| keys | The values to read | |
| values | Output pointers, one for each key | |
| [out] | out_written | If not NULL, receives the number of values written before any error |
| GHOSTTY_API void ghostty_render_state_image_iterator_free | ( | GhosttyRenderStateImageIterator | iterator | ) |
Free an image iterator.
| iterator | The iterator handle to free (may be NULL) |
| GHOSTTY_API GhosttyResult ghostty_render_state_image_iterator_new | ( | const GhosttyAllocator * | allocator, |
| GhosttyRenderStateImageIterator * | out_iterator ) |
Create a new image iterator.
The iterator starts out empty. Fill it from a render state with ghostty_render_state_get() and GHOSTTY_RENDER_STATE_DATA_IMAGE_ITERATOR. You can keep one iterator for the lifetime of your renderer and fill it again after every update. See Drawing images for a complete example.
| allocator | Pointer to allocator, or NULL to use the default allocator | |
| [out] | out_iterator | On success, receives the created iterator handle |
| GHOSTTY_API bool ghostty_render_state_image_iterator_next | ( | GhosttyRenderStateImageIterator | iterator | ) |
Move an image iterator to the next image placement.
Call this before reading the first placement, and keep calling it until it returns false.
The order of placements is not the order to draw them in. Sort them by layer (GHOSTTY_RENDER_STATE_IMAGE_DATA_LAYER) and then by z-index (GHOSTTY_RENDER_STATE_IMAGE_DATA_Z) first.
Only placements with something to draw are returned. For example, placements of an image the terminal hasn't fully received yet are skipped.
The iterator reads from the render state that filled it. After the next update of that render state, fill the iterator again before using it.
| iterator | The iterator handle (NULL returns false) |
| GHOSTTY_API GhosttyResult ghostty_render_state_new | ( | const GhosttyAllocator * | allocator, |
| GhosttyRenderState * | state ) |
Create a new render state instance.
| allocator | Pointer to allocator, or NULL to use the default allocator |
| state | Pointer to store the created render state handle |
| GHOSTTY_API void ghostty_render_state_row_cells_free | ( | GhosttyRenderStateRowCells | cells | ) |
Free a row cells instance.
| cells | The row cells handle to free (may be NULL) |
| GHOSTTY_API GhosttyResult ghostty_render_state_row_cells_get | ( | GhosttyRenderStateRowCells | cells, |
| GhosttyRenderStateRowCellsData | data, | ||
| void * | out ) |
Get a value from the current cell in a render-state row cells iterator.
The out pointer must point to a value of the type corresponding to the requested data kind (see GhosttyRenderStateRowCellsData). Call ghostty_render_state_row_cells_next() or ghostty_render_state_row_cells_select() at least once before calling this function.
| cells | The row cells handle to query (NULL returns GHOSTTY_INVALID_VALUE) | |
| data | The data kind to query | |
| [out] | out | Pointer to receive the queried value |
| GHOSTTY_API GhosttyResult ghostty_render_state_row_cells_get_multi | ( | GhosttyRenderStateRowCells | cells, |
| size_t | count, | ||
| const GhosttyRenderStateRowCellsData * | keys, | ||
| void ** | values, | ||
| size_t * | out_written ) |
Get multiple data fields from the current cell 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_render_state_row_cells_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.
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).
| cells | The row cells 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_render_state_row_cells_new | ( | const GhosttyAllocator * | allocator, |
| GhosttyRenderStateRowCells * | out_cells ) |
Create a new row cells instance.
All fields except the allocator are left undefined until populated via ghostty_render_state_row_get() with GHOSTTY_RENDER_STATE_ROW_DATA_CELLS.
You can reuse this value repeatedly with ghostty_render_state_row_get() to avoid allocating a new cells container for every row.
| allocator | Pointer to allocator, or NULL to use the default allocator | |
| [out] | out_cells | On success, receives the created row cells handle |
| GHOSTTY_API bool ghostty_render_state_row_cells_next | ( | GhosttyRenderStateRowCells | cells | ) |
Move a render-state row cells iterator to the next cell.
Returns true if the iterator moved successfully and cell data is available to read at the new position.
| cells | The row cells handle to advance (may be NULL) |
| GHOSTTY_API GhosttyResult ghostty_render_state_row_cells_select | ( | GhosttyRenderStateRowCells | cells, |
| uint16_t | x ) |
Move a render-state row cells iterator to a specific column.
Positions the iterator at the given x (column) index so that subsequent reads return data for that cell.
| cells | The row cells handle to reposition (NULL returns GHOSTTY_INVALID_VALUE) |
| x | The zero-based column index to select |
| GHOSTTY_API GhosttyResult ghostty_render_state_row_get | ( | GhosttyRenderStateRowIterator | iterator, |
| GhosttyRenderStateRowData | data, | ||
| void * | out ) |
Get a value from the current row in a render-state row iterator.
The out pointer must point to a value of the type corresponding to the requested data kind (see GhosttyRenderStateRowData). Call ghostty_render_state_row_iterator_next() or ghostty_render_state_row_iterator_next_dirty() at least once before calling this function.
| iterator | The iterator handle to query (NULL returns GHOSTTY_INVALID_VALUE) | |
| data | The data kind to query | |
| [out] | out | Pointer to receive the queried value |
| GHOSTTY_API GhosttyResult ghostty_render_state_row_get_multi | ( | GhosttyRenderStateRowIterator | iterator, |
| size_t | count, | ||
| const GhosttyRenderStateRowData * | keys, | ||
| void ** | values, | ||
| size_t * | out_written ) |
Get multiple data fields from the current row 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_render_state_row_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.
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 void ghostty_render_state_row_iterator_free | ( | GhosttyRenderStateRowIterator | iterator | ) |
Free a render-state row iterator.
| iterator | The iterator handle to free (may be NULL) |
| GHOSTTY_API GhosttyResult ghostty_render_state_row_iterator_new | ( | const GhosttyAllocator * | allocator, |
| GhosttyRenderStateRowIterator * | out_iterator ) |
Create a new row iterator instance.
All fields except the allocator are left undefined until populated via ghostty_render_state_get() with GHOSTTY_RENDER_STATE_DATA_ROW_ITERATOR.
| allocator | Pointer to allocator, or NULL to use the default allocator | |
| [out] | out_iterator | On success, receives the created iterator handle |
| GHOSTTY_API bool ghostty_render_state_row_iterator_next | ( | GhosttyRenderStateRowIterator | iterator | ) |
Move a render-state row iterator to the next row.
Rows are visited in order from top to bottom with no gaps. Without overscan, the first row is the top row of the viewport. With overscan, the first row is the highest captured row above the viewport (see GHOSTTY_RENDER_STATE_OPT_OVERSCAN). Returns true if the iterator moved successfully and row data is available to read at the new position.
| iterator | The iterator handle to advance (may be NULL) |
| GHOSTTY_API bool ghostty_render_state_row_iterator_next_dirty | ( | GhosttyRenderStateRowIterator | iterator, |
| uint16_t * | out_y ) |
Move a render-state row iterator to the next row requiring a redraw.
If the global dirty state is GHOSTTY_RENDER_STATE_DIRTY_FALSE, this returns false. If it is GHOSTTY_RENDER_STATE_DIRTY_PARTIAL, clean rows are skipped. If it is GHOSTTY_RENDER_STATE_DIRTY_FULL, every remaining row is returned regardless of its per-row dirty flag. Rows are returned in ascending viewport order. This function does not clear any dirty state.
| iterator | The iterator handle to advance (NULL returns false) | |
| [out] | out_y | Receives the row's position in the iterator when true is returned (NULL returns false). It is not modified when false is returned. Without overscan, this is the viewport y. With overscan, it counts from the highest captured row, so use GHOSTTY_RENDER_STATE_ROW_DATA_VIEWPORT_Y to place the row. |
| GHOSTTY_API GhosttyResult ghostty_render_state_row_set | ( | GhosttyRenderStateRowIterator | iterator, |
| GhosttyRenderStateRowOption | option, | ||
| const void * | value ) |
Set an option on the current row in a render-state row iterator.
The value pointer must point to a value of the type corresponding to the requested option kind (see GhosttyRenderStateRowOption). Call ghostty_render_state_row_iterator_next() or ghostty_render_state_row_iterator_next_dirty() at least once before calling this function.
| iterator | The iterator handle to update (NULL returns GHOSTTY_INVALID_VALUE) | |
| option | The option to set | |
| [in] | value | Pointer to the value to set. Row options have no default to restore, so NULL returns GHOSTTY_INVALID_VALUE. |
| GHOSTTY_API GhosttyResult ghostty_render_state_set | ( | GhosttyRenderState | state, |
| GhosttyRenderStateOption | option, | ||
| const void * | value ) |
Set an option on a render state.
The value pointer must point to a value of the type corresponding to the requested option kind (see GhosttyRenderStateOption).
Passing NULL for value restores the option's default. Options that have no default, such as GHOSTTY_RENDER_STATE_OPT_DIRTY, return GHOSTTY_INVALID_VALUE for NULL instead.
| state | The render state handle (NULL returns GHOSTTY_INVALID_VALUE) | |
| option | The option to set | |
| [in] | value | Pointer to the value to set, or NULL to restore the option's default |
| GHOSTTY_API GhosttyResult ghostty_render_state_update | ( | GhosttyRenderState | state, |
| GhosttyTerminal | terminal ) |
Update a render state instance from a terminal.
This consumes terminal/screen dirty state in the same way as the internal render state update path.
This is a convenience function that performs a full update in one call, equivalent to ghostty_render_state_begin_update immediately followed by ghostty_render_state_end_update. Callers that hold a lock over the terminal state should prefer calling the two phases directly so that the lock is only held for the begin phase.
| state | The render state handle (NULL returns GHOSTTY_INVALID_VALUE) |
| terminal | The terminal handle to read from (NULL returns GHOSTTY_INVALID_VALUE) |
| #define GHOSTTY_IMAGE_LAYER_MASK_ABOVE_TEXT (1u << GHOSTTY_IMAGE_LAYER_ABOVE_TEXT) |
| #define GHOSTTY_IMAGE_LAYER_MASK_BELOW_BACKGROUND (1u << GHOSTTY_IMAGE_LAYER_BELOW_BACKGROUND) |
| #define GHOSTTY_IMAGE_LAYER_MASK_BELOW_TEXT (1u << GHOSTTY_IMAGE_LAYER_BELOW_TEXT) |
1.17.0