Grid Reference

Detailed Description

A grid reference is a resolved reference to a specific cell position in the terminal's internal page structure. Obtain a grid reference from ghostty_terminal_grid_ref(), then extract the cell or row via ghostty_grid_ref_cell() and ghostty_grid_ref_row().

A grid reference is only valid until the next update to the terminal instance. There is no guarantee that a grid reference will remain valid after ANY operation, even if a seemingly unrelated part of the grid is changed, so any information related to the grid reference should be read and cached immediately after obtaining the grid reference.

This API is not meant to be used as the core of render loop. It isn't built to sustain the framerates needed for rendering large screens. Use the render state API for that.

Example

int main() {
  // Create a small terminal
  GhosttyTerminal terminal;
  GhosttyTerminalOptions opts = {
    .cols = 10,
    .rows = 3,
    .max_scrollback = 0,
  };
  GhosttyResult result = ghostty_terminal_new(NULL, &terminal, opts);
  assert(result == GHOSTTY_SUCCESS);
 
  // Write some content so the grid has interesting data
  const char *text = "Hello!\r\n"    // Row 0: H e l l o !
                     "World\r\n"     // Row 1: W o r l d
                     "\033[1mBold";   // Row 2: B o l d (bold style)
  ghostty_terminal_vt_write(
      terminal, (const uint8_t *)text, strlen(text));
 
  // Get terminal dimensions
  uint16_t cols, rows;
  ghostty_terminal_get(terminal, GHOSTTY_TERMINAL_DATA_COLS, &cols);
  ghostty_terminal_get(terminal, GHOSTTY_TERMINAL_DATA_ROWS, &rows);
 
  // Traverse the entire grid using grid refs
  for (uint16_t row = 0; row < rows; row++) {
    printf("Row %u: ", row);
    for (uint16_t col = 0; col < cols; col++) {
      // Resolve the point to a grid reference
      GhosttyGridRef ref = GHOSTTY_INIT_SIZED(GhosttyGridRef);
      GhosttyPoint pt = {
        .tag = GHOSTTY_POINT_TAG_ACTIVE,
        .value = { .coordinate = { .x = col, .y = row } },
      };
      result = ghostty_terminal_grid_ref(terminal, pt, &ref);
      assert(result == GHOSTTY_SUCCESS);
 
      // Read the cell from the grid ref
      GhosttyCell cell;
      result = ghostty_grid_ref_cell(&ref, &cell);
      assert(result == GHOSTTY_SUCCESS);
 
      // Check if the cell has text
      bool has_text = false;
      ghostty_cell_get(cell, GHOSTTY_CELL_DATA_HAS_TEXT, &has_text);
 
      if (has_text) {
        uint32_t codepoint = 0;
        ghostty_cell_get(cell, GHOSTTY_CELL_DATA_CODEPOINT, &codepoint);
        printf("%c", (char)codepoint);
      } else {
        printf(".");
      }
    }
 
    // Also inspect the row for wrap state
    GhosttyGridRef ref = GHOSTTY_INIT_SIZED(GhosttyGridRef);
    GhosttyPoint pt = {
      .tag = GHOSTTY_POINT_TAG_ACTIVE,
      .value = { .coordinate = { .x = 0, .y = row } },
    };
    ghostty_terminal_grid_ref(terminal, pt, &ref);
 
    GhosttyRow grid_row;
    ghostty_grid_ref_row(&ref, &grid_row);
 
    bool wrap = false;
    ghostty_row_get(grid_row, GHOSTTY_ROW_DATA_WRAP, &wrap);
    printf(" (wrap=%s", wrap ? "true" : "false");
 
    // Check the style of the first cell with text
    GhosttyStyle style = GHOSTTY_INIT_SIZED(GhosttyStyle);
    ghostty_grid_ref_style(&ref, &style);
    printf(", bold=%s)\n", style.bold ? "true" : "false");
  }
 
  ghostty_terminal_free(terminal);
  return 0;
}

Functions
GHOSTTY_API GhosttyResult	ghostty_grid_ref_cell (const GhosttyGridRef *ref, GhosttyCell *out_cell)
GHOSTTY_API GhosttyResult	ghostty_grid_ref_row (const GhosttyGridRef *ref, GhosttyRow *out_row)
GHOSTTY_API GhosttyResult	ghostty_grid_ref_graphemes (const GhosttyGridRef *ref, uint32_t *buf, size_t buf_len, size_t *out_len)
GHOSTTY_API GhosttyResult	ghostty_grid_ref_hyperlink_uri (const GhosttyGridRef *ref, uint8_t *buf, size_t buf_len, size_t *out_len)
GHOSTTY_API GhosttyResult	ghostty_grid_ref_style (const GhosttyGridRef *ref, GhosttyStyle *out_style)

Data Structures
struct	GhosttyGridRef

Function Documentation

ghostty_grid_ref_cell()

GHOSTTY_API GhosttyResult ghostty_grid_ref_cell	(	const GhosttyGridRef *	ref,
		GhosttyCell *	out_cell )

Get the cell from a grid reference.

Parameters

	ref	Pointer to the grid reference
[out]	out_cell	On success, set to the cell at the ref's position (may be NULL)

Returns

GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the ref's node is NULL

Examples

c-vt-grid-traverse/src/main.c.

ghostty_grid_ref_graphemes()

GHOSTTY_API GhosttyResult ghostty_grid_ref_graphemes	(	const GhosttyGridRef *	ref,
		uint32_t *	buf,
		size_t	buf_len,
		size_t *	out_len )

Get the grapheme cluster codepoints for the cell at the grid reference's position.

Writes the full grapheme cluster (the cell's primary codepoint followed by any combining codepoints) into the provided buffer. If the cell has no text, out_len is set to 0 and GHOSTTY_SUCCESS is returned.

If the buffer is too small (or NULL), the function returns GHOSTTY_OUT_OF_SPACE and writes the required number of codepoints to out_len. The caller can then retry with a sufficiently sized buffer.

Parameters

	ref	Pointer to the grid reference
	buf	Output buffer of uint32_t codepoints (may be NULL)
	buf_len	Number of uint32_t elements in the buffer
[out]	out_len	On success, the number of codepoints written. On GHOSTTY_OUT_OF_SPACE, the required buffer size in codepoints.

Returns

GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the ref's node is NULL, GHOSTTY_OUT_OF_SPACE if the buffer is too small

ghostty_grid_ref_hyperlink_uri()

GHOSTTY_API GhosttyResult ghostty_grid_ref_hyperlink_uri	(	const GhosttyGridRef *	ref,
		uint8_t *	buf,
		size_t	buf_len,
		size_t *	out_len )

Get the hyperlink URI for the cell at the grid reference's position.

Writes the URI bytes into the provided buffer. If the cell has no hyperlink, out_len is set to 0 and GHOSTTY_SUCCESS is returned.

If the buffer is too small (or NULL), the function returns GHOSTTY_OUT_OF_SPACE and writes the required number of bytes to out_len. The caller can then retry with a sufficiently sized buffer.

Parameters

	ref	Pointer to the grid reference
	buf	Output buffer for the URI bytes (may be NULL)
	buf_len	Size of the output buffer in bytes
[out]	out_len	On success, the number of bytes written. On GHOSTTY_OUT_OF_SPACE, the required buffer size in bytes.

Returns

GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the ref's node is NULL, GHOSTTY_OUT_OF_SPACE if the buffer is too small

ghostty_grid_ref_row()

GHOSTTY_API GhosttyResult ghostty_grid_ref_row	(	const GhosttyGridRef *	ref,
		GhosttyRow *	out_row )

Get the row from a grid reference.

Parameters

	ref	Pointer to the grid reference
[out]	out_row	On success, set to the row at the ref's position (may be NULL)

Returns

GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the ref's node is NULL

Examples

c-vt-grid-traverse/src/main.c.

ghostty_grid_ref_style()

GHOSTTY_API GhosttyResult ghostty_grid_ref_style	(	const GhosttyGridRef *	ref,
		GhosttyStyle *	out_style )

Get the style of the cell at the grid reference's position.

Parameters

	ref	Pointer to the grid reference
[out]	out_style	On success, set to the cell's style (may be NULL)

Returns

GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the ref's node is NULL

Examples

c-vt-grid-traverse/src/main.c.