Detailed Description

Represents the state required to render a visible screen (a viewport) of a terminal instance. This is stateful and optimized for repeated updates from a single terminal instance and only updating dirty regions of the screen.

The key design principle of this API is that it only needs read/write access to the terminal instance during the update call. This allows the render state to minimally impact terminal IO performance and also allows the renderer to be safely multi-threaded (as long as a lock is held during the update call to ensure exclusive access to the terminal instance).

The basic usage of this API is:

Create an empty render state
Update it from a terminal instance whenever you need.
Read from the render state to get the data needed to draw your frame.

Dirty Tracking

Dirty tracking is a key feature of the render state that allows renderers to efficiently determine what parts of the screen have changed and only redraw changed regions.

The render state API keeps track of dirty state at two independent layers: a global dirty state that indicates whether the entire frame is clean, partially dirty, or fully dirty, and a per-row dirty state that allows tracking which rows in a partially dirty frame have changed.

The user of the render state API is expected to unset both of these. The update call does not unset dirty state, it only updates it.

An extremely important detail: setting one dirty state doesn't unset the other. For example, setting the global dirty state to false does not reset the row-level dirty flags. So, the caller of the render state API must be careful to manage both layers of dirty state correctly.

Examples

Creating and updating render state

  // Create a terminal and render state, then update the render state
  // from the terminal. The render state captures a snapshot of everything
  // needed to draw a frame.
  GhosttyTerminal terminal = NULL;
  GhosttyTerminalOptions terminal_opts = {
      .cols = 40,
      .rows = 5,
      .max_scrollback = 10000,
  };
  result = ghostty_terminal_new(NULL, &terminal, terminal_opts);
  assert(result == GHOSTTY_SUCCESS);
 
  GhosttyRenderState render_state = NULL;
  result = ghostty_render_state_new(NULL, &render_state);
  assert(result == GHOSTTY_SUCCESS);
 
  // Feed some styled content into the terminal.
  const char* content =
      "Hello, \033[1;32mworld\033[0m!\r\n"     // bold green "world"
      "\033[4munderlined\033[0m text\r\n"       // underlined text
      "\033[38;2;255;128;0morange\033[0m\r\n";  // 24-bit orange fg
  ghostty_terminal_vt_write(
      terminal, (const uint8_t*)content, strlen(content));
 
  result = ghostty_render_state_update(render_state, terminal);
  assert(result == GHOSTTY_SUCCESS);

Checking dirty state

  // Check the global dirty state to decide how much work the renderer
  // needs to do. After rendering, reset it to false.
  GhosttyRenderStateDirty dirty;
  result = ghostty_render_state_get(
      render_state, GHOSTTY_RENDER_STATE_DATA_DIRTY, &dirty);
  assert(result == GHOSTTY_SUCCESS);
 
  switch (dirty) {
    case GHOSTTY_RENDER_STATE_DIRTY_FALSE:
      printf("Frame is clean, nothing to draw.\n");
      break;
    case GHOSTTY_RENDER_STATE_DIRTY_PARTIAL:
      printf("Partial redraw needed.\n");
      break;
    case GHOSTTY_RENDER_STATE_DIRTY_FULL:
      printf("Full redraw needed.\n");
      break;
  }

Reading colors

  // Retrieve colors (background, foreground, palette) from the render
  // state. These are needed to resolve palette-indexed cell colors.
  GhosttyRenderStateColors colors =
      GHOSTTY_INIT_SIZED(GhosttyRenderStateColors);
  result = ghostty_render_state_colors_get(render_state, &colors);
  assert(result == GHOSTTY_SUCCESS);
 
  printf("Background: #%02x%02x%02x\n",
         colors.background.r, colors.background.g, colors.background.b);
  printf("Foreground: #%02x%02x%02x\n",
         colors.foreground.r, colors.foreground.g, colors.foreground.b);

Reading cursor state

  // Read cursor position and visual style from the render state.
  bool cursor_visible = false;
  ghostty_render_state_get(
      render_state, GHOSTTY_RENDER_STATE_DATA_CURSOR_VISIBLE,
      &cursor_visible);
 
  bool cursor_in_viewport = false;
  ghostty_render_state_get(
      render_state, GHOSTTY_RENDER_STATE_DATA_CURSOR_VIEWPORT_HAS_VALUE,
      &cursor_in_viewport);
 
  if (cursor_visible && cursor_in_viewport) {
    uint16_t cx, cy;
    ghostty_render_state_get(
        render_state, GHOSTTY_RENDER_STATE_DATA_CURSOR_VIEWPORT_X, &cx);
    ghostty_render_state_get(
        render_state, GHOSTTY_RENDER_STATE_DATA_CURSOR_VIEWPORT_Y, &cy);
 
    GhosttyRenderStateCursorVisualStyle style;
    ghostty_render_state_get(
        render_state, GHOSTTY_RENDER_STATE_DATA_CURSOR_VISUAL_STYLE,
        &style);
 
    const char* style_name = "unknown";
    switch (style) {
      case GHOSTTY_RENDER_STATE_CURSOR_VISUAL_STYLE_BAR:
        style_name = "bar";
        break;
      case GHOSTTY_RENDER_STATE_CURSOR_VISUAL_STYLE_BLOCK:
        style_name = "block";
        break;
      case GHOSTTY_RENDER_STATE_CURSOR_VISUAL_STYLE_UNDERLINE:
        style_name = "underline";
        break;
      case GHOSTTY_RENDER_STATE_CURSOR_VISUAL_STYLE_BLOCK_HOLLOW:
        style_name = "hollow";
        break;
    }
    printf("Cursor at (%u, %u), style: %s\n", cx, cy, style_name);
  }

Iterating rows and cells

  // Iterate rows via the row iterator. For each dirty row, iterate its
  // cells, read codepoints/graphemes and styles, and emit ANSI-colored
  // output as a simple "renderer".
  GhosttyRenderStateRowIterator row_iter = NULL;
  result = ghostty_render_state_row_iterator_new(NULL, &row_iter);
  assert(result == GHOSTTY_SUCCESS);
 
  result = ghostty_render_state_get(
      render_state, GHOSTTY_RENDER_STATE_DATA_ROW_ITERATOR, &row_iter);
  assert(result == GHOSTTY_SUCCESS);
 
  GhosttyRenderStateRowCells cells = NULL;
  result = ghostty_render_state_row_cells_new(NULL, &cells);
  assert(result == GHOSTTY_SUCCESS);
 
  int row_index = 0;
  while (ghostty_render_state_row_iterator_next(row_iter)) {
    // Check per-row dirty state; a real renderer would skip clean rows.
    bool row_dirty = false;
    ghostty_render_state_row_get(
        row_iter, GHOSTTY_RENDER_STATE_ROW_DATA_DIRTY, &row_dirty);
 
    printf("Row %2d [%s]: ", row_index,
           row_dirty ? "dirty" : "clean");
 
    // Get cells for this row (reuses the same cells handle).
    result = ghostty_render_state_row_get(
        row_iter, GHOSTTY_RENDER_STATE_ROW_DATA_CELLS, &cells);
    assert(result == GHOSTTY_SUCCESS);
 
    while (ghostty_render_state_row_cells_next(cells)) {
      // Get the grapheme length; 0 means the cell is empty.
      uint32_t grapheme_len = 0;
      ghostty_render_state_row_cells_get(
          cells, GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_GRAPHEMES_LEN,
          &grapheme_len);
 
      if (grapheme_len == 0) {
        putchar(' ');
        continue;
      }
 
      // Read the style for this cell. Returns the default style for
      // cells that have no explicit styling.
      GhosttyStyle style = GHOSTTY_INIT_SIZED(GhosttyStyle);
      ghostty_render_state_row_cells_get(
          cells, GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_STYLE, &style);
 
      // Resolve foreground color for this cell.
      GhosttyColorRgb fg =
          resolve_color(style.fg_color, &colors, colors.foreground);
 
      // Emit ANSI true-color escape for the foreground.
      printf("\033[38;2;%u;%u;%um", fg.r, fg.g, fg.b);
      if (style.bold) printf("\033[1m");
      if (style.underline) printf("\033[4m");
 
      // Read grapheme codepoints into a buffer and print them.
      // The buffer must be at least grapheme_len elements.
      uint32_t codepoints[16];
      uint32_t len = grapheme_len < 16 ? grapheme_len : 16;
      ghostty_render_state_row_cells_get(
          cells, GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_GRAPHEMES_BUF,
          codepoints);
 
      for (uint32_t i = 0; i < len; i++) {
        // Simple ASCII print; a real renderer would handle UTF-8.
        if (codepoints[i] < 128)
          putchar((char)codepoints[i]);
        else
          printf("U+%04X", codepoints[i]);
      }
 
      printf("\033[0m");  // Reset style after each cell.
    }
 
    printf("\n");
 
    // Clear per-row dirty flag after "rendering" it.
    bool clean = false;
    ghostty_render_state_row_set(
        row_iter, GHOSTTY_RENDER_STATE_ROW_OPTION_DIRTY, &clean);
 
    row_index++;
  }

Resetting dirty state after rendering

  // After finishing the frame, reset the global dirty state so the next
  // update can report changes accurately.
  GhosttyRenderStateDirty clean_state = GHOSTTY_RENDER_STATE_DIRTY_FALSE;
  result = ghostty_render_state_set(
      render_state, GHOSTTY_RENDER_STATE_OPTION_DIRTY, &clean_state);
  assert(result == GHOSTTY_SUCCESS);

Typedefs
typedef struct GhosttyRenderState *	GhosttyRenderState
typedef struct GhosttyRenderStateRowIterator *	GhosttyRenderStateRowIterator
typedef struct GhosttyRenderStateRowCells *	GhosttyRenderStateRowCells

Enumerations
enum	GhosttyRenderStateDirty { GHOSTTY_RENDER_STATE_DIRTY_FALSE = 0 , GHOSTTY_RENDER_STATE_DIRTY_PARTIAL = 1 , GHOSTTY_RENDER_STATE_DIRTY_FULL = 2 }
enum	GhosttyRenderStateCursorVisualStyle { GHOSTTY_RENDER_STATE_CURSOR_VISUAL_STYLE_BAR = 0 , GHOSTTY_RENDER_STATE_CURSOR_VISUAL_STYLE_BLOCK = 1 , GHOSTTY_RENDER_STATE_CURSOR_VISUAL_STYLE_UNDERLINE = 2 , GHOSTTY_RENDER_STATE_CURSOR_VISUAL_STYLE_BLOCK_HOLLOW = 3 }
enum	GhosttyRenderStateData { GHOSTTY_RENDER_STATE_DATA_INVALID = 0 , GHOSTTY_RENDER_STATE_DATA_COLS = 1 , GHOSTTY_RENDER_STATE_DATA_ROWS = 2 , GHOSTTY_RENDER_STATE_DATA_DIRTY = 3 , GHOSTTY_RENDER_STATE_DATA_ROW_ITERATOR = 4 , GHOSTTY_RENDER_STATE_DATA_COLOR_BACKGROUND = 5 , GHOSTTY_RENDER_STATE_DATA_COLOR_FOREGROUND = 6 , GHOSTTY_RENDER_STATE_DATA_COLOR_CURSOR = 7 , GHOSTTY_RENDER_STATE_DATA_COLOR_CURSOR_HAS_VALUE = 8 , GHOSTTY_RENDER_STATE_DATA_COLOR_PALETTE = 9 , GHOSTTY_RENDER_STATE_DATA_CURSOR_VISUAL_STYLE = 10 , GHOSTTY_RENDER_STATE_DATA_CURSOR_VISIBLE = 11 , GHOSTTY_RENDER_STATE_DATA_CURSOR_BLINKING = 12 , GHOSTTY_RENDER_STATE_DATA_CURSOR_PASSWORD_INPUT = 13 , GHOSTTY_RENDER_STATE_DATA_CURSOR_VIEWPORT_HAS_VALUE = 14 , GHOSTTY_RENDER_STATE_DATA_CURSOR_VIEWPORT_X = 15 , GHOSTTY_RENDER_STATE_DATA_CURSOR_VIEWPORT_Y = 16 , GHOSTTY_RENDER_STATE_DATA_CURSOR_VIEWPORT_WIDE_TAIL = 17 }
enum	GhosttyRenderStateOption { GHOSTTY_RENDER_STATE_OPTION_DIRTY = 0 }
enum	GhosttyRenderStateRowData { GHOSTTY_RENDER_STATE_ROW_DATA_INVALID = 0 , GHOSTTY_RENDER_STATE_ROW_DATA_DIRTY = 1 , GHOSTTY_RENDER_STATE_ROW_DATA_RAW = 2 , GHOSTTY_RENDER_STATE_ROW_DATA_CELLS = 3 }
enum	GhosttyRenderStateRowOption { GHOSTTY_RENDER_STATE_ROW_OPTION_DIRTY = 0 }
enum	GhosttyRenderStateRowCellsData { GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_INVALID = 0 , GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_RAW = 1 , GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_STYLE = 2 , GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_GRAPHEMES_LEN = 3 , GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_GRAPHEMES_BUF = 4 }

Functions
GhosttyResult	ghostty_render_state_new (const GhosttyAllocator allocator, GhosttyRenderState state)
void	ghostty_render_state_free (GhosttyRenderState state)
GhosttyResult	ghostty_render_state_update (GhosttyRenderState state, GhosttyTerminal terminal)
GhosttyResult	ghostty_render_state_get (GhosttyRenderState state, GhosttyRenderStateData data, void *out)
GhosttyResult	ghostty_render_state_set (GhosttyRenderState state, GhosttyRenderStateOption option, const void *value)
GhosttyResult	ghostty_render_state_colors_get (GhosttyRenderState state, GhosttyRenderStateColors *out_colors)
GhosttyResult	ghostty_render_state_row_iterator_new (const GhosttyAllocator allocator, GhosttyRenderStateRowIterator out_iterator)
void	ghostty_render_state_row_iterator_free (GhosttyRenderStateRowIterator iterator)
bool	ghostty_render_state_row_iterator_next (GhosttyRenderStateRowIterator iterator)
GhosttyResult	ghostty_render_state_row_get (GhosttyRenderStateRowIterator iterator, GhosttyRenderStateRowData data, void *out)
GhosttyResult	ghostty_render_state_row_set (GhosttyRenderStateRowIterator iterator, GhosttyRenderStateRowOption option, const void *value)
GhosttyResult	ghostty_render_state_row_cells_new (const GhosttyAllocator allocator, GhosttyRenderStateRowCells out_cells)
bool	ghostty_render_state_row_cells_next (GhosttyRenderStateRowCells cells)
GhosttyResult	ghostty_render_state_row_cells_select (GhosttyRenderStateRowCells cells, uint16_t x)
GhosttyResult	ghostty_render_state_row_cells_get (GhosttyRenderStateRowCells cells, GhosttyRenderStateRowCellsData data, void *out)
void	ghostty_render_state_row_cells_free (GhosttyRenderStateRowCells cells)

Data Structures
struct	GhosttyRenderStateColors

Typedef Documentation

◆ GhosttyRenderState

typedef struct GhosttyRenderState* GhosttyRenderState

Opaque handle to a render state instance.

Definition at line 89 of file render.h.

◆ GhosttyRenderStateRowCells

typedef struct GhosttyRenderStateRowCells* GhosttyRenderStateRowCells

Opaque handle to render-state row cells.

Definition at line 103 of file render.h.

◆ GhosttyRenderStateRowIterator

typedef struct GhosttyRenderStateRowIterator* GhosttyRenderStateRowIterator

Opaque handle to a render-state row iterator.

Definition at line 96 of file render.h.

Enumeration Type Documentation

◆ GhosttyRenderStateCursorVisualStyle

enum GhosttyRenderStateCursorVisualStyle

Visual style of the cursor.

Enumerator
GHOSTTY_RENDER_STATE_CURSOR_VISUAL_STYLE_BAR	Bar cursor (DECSCUSR 5, 6).
GHOSTTY_RENDER_STATE_CURSOR_VISUAL_STYLE_BLOCK	Block cursor (DECSCUSR 1, 2).
GHOSTTY_RENDER_STATE_CURSOR_VISUAL_STYLE_UNDERLINE	Underline cursor (DECSCUSR 3, 4).
GHOSTTY_RENDER_STATE_CURSOR_VISUAL_STYLE_BLOCK_HOLLOW	Hollow block cursor.

Definition at line 126 of file render.h.

◆ GhosttyRenderStateData

enum GhosttyRenderStateData

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).
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.
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 (GhosttyRenderStateCursorVisualStyle).
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.

Definition at line 145 of file render.h.

◆ GhosttyRenderStateDirty

enum GhosttyRenderStateDirty

Dirty state of a render state after update.

Enumerator
GHOSTTY_RENDER_STATE_DIRTY_FALSE	Not dirty at all; rendering can be skipped.
GHOSTTY_RENDER_STATE_DIRTY_PARTIAL	Some rows changed; renderer can redraw incrementally.
GHOSTTY_RENDER_STATE_DIRTY_FULL	Global state changed; renderer should redraw everything.

Definition at line 110 of file render.h.

◆ GhosttyRenderStateOption

enum GhosttyRenderStateOption

Settable options for ghostty_render_state_set().

Enumerator
GHOSTTY_RENDER_STATE_OPTION_DIRTY	Set dirty state (GhosttyRenderStateDirty).

Definition at line 216 of file render.h.

◆ GhosttyRenderStateRowCellsData

enum GhosttyRenderStateRowCellsData

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	Write grapheme codepoints into a caller-provided buffer (uint32_t*). The buffer must be at least graphemes_len elements. The base codepoint is written first, followed by any extra codepoints.

Definition at line 499 of file render.h.

◆ GhosttyRenderStateRowData

enum GhosttyRenderStateRowData

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.

Definition at line 226 of file render.h.

◆ GhosttyRenderStateRowOption

enum GhosttyRenderStateRowOption

Settable options for ghostty_render_state_row_set().

Enumerator
GHOSTTY_RENDER_STATE_ROW_OPTION_DIRTY	Set dirty state for the current row (bool).

Definition at line 248 of file render.h.

Function Documentation

◆ ghostty_render_state_colors_get()

GhosttyResult ghostty_render_state_colors_get	(	GhosttyRenderState	state,
		GhosttyRenderStateColors *	out_colors )

Get the current color information from a render state.

This writes as many fields as fit in the caller-provided sized struct. out_colors->size must be set by the caller (typically via GHOSTTY_INIT_SIZED(GhosttyRenderStateColors)).

Parameters

	state	The render state handle (NULL returns GHOSTTY_INVALID_VALUE)
[out]	out_colors	Sized output struct to receive render-state colors

Returns: GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if state or out_colors is NULL, or if out_colors->size is smaller than sizeof(size_t)

◆ ghostty_render_state_free()

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.

Parameters

state The render state handle to free (may be NULL)

◆ ghostty_render_state_get()

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

Parameters

	state	The render state 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 state is NULL or data is not a recognized enum value

◆ ghostty_render_state_new()

GhosttyResult ghostty_render_state_new	(	const GhosttyAllocator *	allocator,
		GhosttyRenderState *	state )

Create a new render state instance.

Parameters

Memory Management	Pointer to allocator, or NULL to use the default allocator
state	Pointer to store the created render state handle

Returns: GHOSTTY_SUCCESS on success, GHOSTTY_OUT_OF_MEMORY on allocation failure

◆ ghostty_render_state_row_cells_free()

void ghostty_render_state_row_cells_free ( GhosttyRenderStateRowCells cells )

Free a row cells instance.

Parameters

cells The row cells handle to free (may be NULL)

◆ ghostty_render_state_row_cells_get()

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.

Parameters

	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

Returns: GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if cells is NULL or the iterator is not positioned on a cell

◆ ghostty_render_state_row_cells_new()

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.

Parameters

	Memory Management	Pointer to allocator, or NULL to use the default allocator
[out]	out_cells	On success, receives the created row cells handle

Returns: GHOSTTY_SUCCESS on success, GHOSTTY_OUT_OF_MEMORY on allocation failure

◆ ghostty_render_state_row_cells_next()

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.

Parameters

cells The row cells handle to advance (may be NULL)

Returns: true if advanced to the next cell, false if cells is NULL or if the iterator has reached the end

◆ ghostty_render_state_row_cells_select()

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.

Parameters

cells	The row cells handle to reposition (NULL returns GHOSTTY_INVALID_VALUE)
x	The zero-based column index to select

Returns: GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if cells is NULL or x is out of range

◆ ghostty_render_state_row_get()

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() at least once before calling this function.

Parameters

	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

Returns: GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if iterator is NULL or the iterator is not positioned on a row

◆ ghostty_render_state_row_iterator_free()

void ghostty_render_state_row_iterator_free ( GhosttyRenderStateRowIterator iterator )

Free a render-state row iterator.

Parameters

iterator The iterator handle to free (may be NULL)

◆ ghostty_render_state_row_iterator_new()

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.

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

◆ ghostty_render_state_row_iterator_next()

bool ghostty_render_state_row_iterator_next ( GhosttyRenderStateRowIterator iterator )

Move a render-state row iterator to the next row.

Returns true if the iterator moved successfully and row data is available to read at the new position.

Parameters

iterator The iterator handle to advance (may be NULL)

Returns: true if advanced to the next row, false if iterator is NULL or if the iterator has reached the end

◆ ghostty_render_state_row_set()

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() at least once before calling this function.

Parameters

	iterator	The iterator handle to update (NULL returns GHOSTTY_INVALID_VALUE)
	option	The option to set
[in]	value	Pointer to the value to set (NULL returns GHOSTTY_INVALID_VALUE)

Returns: GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if iterator is NULL or the iterator is not positioned on a row

◆ ghostty_render_state_set()

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

Parameters

	state	The render state handle (NULL returns GHOSTTY_INVALID_VALUE)
	option	The option to set
[in]	value	Pointer to the value to set (NULL returns GHOSTTY_INVALID_VALUE)

Returns: GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if state or value is NULL

◆ ghostty_render_state_update()

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.

Parameters

state	The render state handle (NULL returns GHOSTTY_INVALID_VALUE)
Terminal	The terminal handle to read from (NULL returns GHOSTTY_INVALID_VALUE)

Returns: GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if state or Terminal is NULL, GHOSTTY_OUT_OF_MEMORY if updating the state requires allocation and that allocation fails

Detailed Description

Dirty Tracking

Examples

Creating and updating render state

Checking dirty state

Reading colors

Reading cursor state

Iterating rows and cells

Resetting dirty state after rendering

Typedefs

Enumerations

Functions

Data Structures

Typedef Documentation

◆ GhosttyRenderState

◆ GhosttyRenderStateRowCells

◆ GhosttyRenderStateRowIterator

Enumeration Type Documentation

◆ GhosttyRenderStateCursorVisualStyle

◆ GhosttyRenderStateData

◆ GhosttyRenderStateDirty

◆ GhosttyRenderStateOption

◆ GhosttyRenderStateRowCellsData

◆ GhosttyRenderStateRowData

◆ GhosttyRenderStateRowOption

Function Documentation

◆ ghostty_render_state_colors_get()

◆ ghostty_render_state_free()

◆ ghostty_render_state_get()

◆ ghostty_render_state_new()

◆ ghostty_render_state_row_cells_free()

◆ ghostty_render_state_row_cells_get()

◆ ghostty_render_state_row_cells_new()

◆ ghostty_render_state_row_cells_next()

◆ ghostty_render_state_row_cells_select()

◆ ghostty_render_state_row_get()

◆ ghostty_render_state_row_iterator_free()

◆ ghostty_render_state_row_iterator_new()

◆ ghostty_render_state_row_iterator_next()

◆ ghostty_render_state_row_set()

◆ ghostty_render_state_set()

◆ ghostty_render_state_update()