The Grid
The grid is what’s on the terminal: rows of cells, each holding text and a style. This page is how you read it.
The hard part isn’t reading a cell. It’s naming one. “Row 3” means one thing to a program moving its cursor, another to someone scrolled back through history, and another to a tool walking the whole scrollback. And the grid moves under you. A write can scroll a row into history, a resize can reflow it, and pruning can throw it away.
So there are two ideas here. A point names a position in one of four coordinate systems. A grid reference is what a point resolves to: one actual cell. An untracked reference is a snapshot that dies on the next change to the terminal. A tracked reference follows its cell, and the terminal pays a little for that on every change.
This isn’t how you draw. Grid references aren’t built to sustain the framerates needed to render a large screen. Use Render State for that. If you only want the text out, use Formatter. This page is for reading particular cells, and for anything that has to keep pointing at one.
Coordinates
A GhosttyPoint is a coordinate plus a tag that says which coordinate system it’s in:
| Tag | Top-left is | What it covers |
|---|---|---|
point::Space::Active | The top of the active area | The area where the cursor can move, at the terminal’s full height. |
point::Space::Viewport | The top of what you’re showing | The visible viewport. This changes when it’s scrolled. |
point::Space::Screen | The oldest row of scrollback | The full screen including scrollback, through the last written row. |
point::Space::History | The oldest row of scrollback | Scrollback only. It ends at the row just before the active area. |
Here’s how they line up on a 24-row terminal with 100 rows of scrollback:
screen y history y active y
+----------------+
| scrollback | 0 0
| | ... ...
| | 99 99
+----------------+
| active area | 100 0
| | ... ...
| | 123 23
+----------------+
The viewport is a 24-row window onto all of that. Scrolled to the bottom, it’s the same rows as the active area. See Scrollback for moving it.
x is the column and y is the row, and both start at zero. y is 32 bits
wide because a row in scrollback can be a long way from the top.
Terminal::grid_ref() resolves a point to a grid reference:
use libghostty_vt::point::{Point, Coordinate};
let point = Point::Active(Coordinate { x: 4, y: 0 });
if let Ok(grid_ref) = terminal.grid_ref(point) {
let cell = grid_ref.cell().unwrap();
}
A point that’s out of bounds returns Error::InvalidValue. Lookups with the
active and viewport tags are fast. The screen and history tags may have to walk
the full scrollback page list to find the row, so they can be expensive with a
large scrollback.
Terminal::point_from_grid_ref() goes the other way. Not every cell exists
in every coordinate system, though. A cell in scrollback has no active
coordinates, and a cell that has scrolled out of view has no viewport
coordinates. In those cases you get None. This is the only way to
get a cell’s position.
Cells, rows and styles
A grid reference gets you everything about its cell:
| Function | What you get |
|---|---|
GridRef::cell() | The Cell. |
GridRef::row() | The Row it’s on. |
GridRef::graphemes() | The full grapheme cluster, as codepoints. |
GridRef::hyperlink_uri() | The hyperlink URI, if it has one. |
GridRef::style() | The Style. |
A Style describes how a cell looks: its foreground, background and
underline colors, plus flags for bold, italic, underline and other decorations.
A cell only holds a style id, Cell::style_id(). Use GridRef::style()
to get the full style.
This walks the whole grid, reading each cell’s text, each row’s wrap state, and a style:
fn main() -> Result<(), Error> {
// Create a small terminal
let mut terminal = Terminal::new(10, 3)?;
// Write some content so the grid has interesting data
terminal.vt_write(b"Hello!\r\n"); // Row 0: H e l l o !
terminal.vt_write(b"World\r\n"); // Row 1: W o r l d
terminal.vt_write(b"\x1b[1mBold"); // Row 2: B o l d (bold style)
// Get terminal dimensions
let cols = terminal.cols()?;
let rows = u32::from(terminal.rows()?);
// Traverse the entire grid using grid refs
for row in 0..rows {
print!("Row {row}: ");
for col in 0..cols {
// Resolve the point to a grid reference
let point = Point::Active(Coordinate { x: col, y: row });
let grid_ref = terminal.grid_ref(point)?;
// Read the cell from the grid ref
let cell = grid_ref.cell()?;
// Check if the cell has text
if cell.has_text()? {
let codepoint = cell.codepoint()?;
print!("{codepoint}");
} else {
print!(".");
}
}
// Also inspect the row for wrap state
let point = Point::Active(Coordinate { x: 0, y: row });
let grid_ref = terminal.grid_ref(point)?;
let row = grid_ref.row()?;
print!(" (wrap={}", row.is_wrapped()?);
// Check the style of the first cell with text
let style = grid_ref.style()?;
print!(", bold={}", style.bold);
}
Ok(())
}
Full program: rust-vt-grid-traverse/src/main.rs
Untracked references
A GridRef is untracked. It’s a value that snapshots one cell, and you
don’t free it.
It’s only valid until the next call that changes the terminal. That includes
Terminal::vt_write() and Terminal::resize(). There’s no guarantee it
survives any change, even one to a part of the grid that looks unrelated.
So get one, read what you need, and cache the values. Don’t keep the reference.
An untracked reference costs you the initial lookup and nothing after that. It’s a one-time snapshot, so it has no effect on the terminal’s ongoing performance.
Tracked references
A TrackedGridRef follows its cell. Scrolling, scrollback pruning, resize
and reflow, and other terminal changes all update it automatically. Create one
with Terminal::track_grid_ref().
Each tracked reference adds bookkeeping to every terminal change, so use them sparingly. They’re for long-lived anchors such as selections, search state, marks and bookmarks in your application.
To read cell data, snapshot it first with TrackedGridRef::snapshot().
What you get back is an untracked reference with the same short life as any
other. TrackedGridRef::point() gets you the position without that step.
fn codepoint_at_tracked_ref(
terminal: &Terminal<'_, '_>,
tracked: &TrackedGridRef,
) -> Result<char, Error> {
let snapshot = tracked
.snapshot(terminal)?
.expect("tracked grid ref should be active");
let cell = snapshot.cell()?;
assert!(cell.has_text()?);
cell.codepoint()
}
fn main() -> Result<(), Error> {
let mut terminal = Terminal::new(8, 3)?;
terminal.vt_write(b"alpha\r\nbravo\r\ncharlie");
let alpha = Point::Active(Coordinate { x: 0, y: 0 });
let mut tracked = terminal.track_grid_ref(alpha)?;
// Writing another line scrolls the original "alpha" row into scrollback.
// The tracked ref still follows the same cell.
terminal.vt_write(b"\r\ndelta");
assert!(tracked.has_value());
println!(
"tracked codepoint after scroll: {}",
codepoint_at_tracked_ref(&terminal, &tracked)?
);
let screen = tracked
.point(Space::Screen)?
.expect("tracked point should be on screen");
println!("tracked screen point: {},{}", screen.x, screen.y);
// Resetting the terminal discards the old grid contents. The tracked
// handle remains valid, but no longer has a meaningful location.
terminal.reset();
assert!(!tracked.has_value());
assert!(tracked.snapshot(&terminal)?.is_none());
// The same handle can be moved to a new point after it loses its value.
terminal.vt_write(b"echo");
let echo = Point::Active(Coordinate { x: 0, y: 0 });
tracked.set(&mut terminal, echo)?;
assert!(tracked.has_value());
println!(
"tracked codepoint after reset/set: {}",
codepoint_at_tracked_ref(&terminal, &tracked)?
);
Ok(())
}
Full program: rust-vt-grid-ref-tracked/src/main.rs
When a tracked reference loses its cell
A tracked reference can still lose its place. That happens when the grid under
it is reset, pruned, or otherwise discarded in a way that can’t be mapped to a
meaningful new cell. TrackedGridRef::has_value() then returns false, and
TrackedGridRef::snapshot() and TrackedGridRef::point() return None.
The handle is still valid. Move it to a new point with TrackedGridRef::set().
Primary and alternate screens
A tracked reference belongs to the screen that was active when you created it or
last set it. Converting it to a point uses that screen, even if the terminal has
since switched between primary and alternate. TrackedGridRef::set()
resolves the new point against the screen that’s active now, so it can move the
reference from one screen to the other.
Dropping
Tracked references are yours, and you can drop them after the terminal is gone. If the terminal is dropped first, the handle stays valid for the tracked reference functions only: it reports no value, and it can still be freed.
When a reference dies
| Untracked | Tracked | |
|---|---|---|
| Terminal changes | Invalid. Don’t touch it again. | Follows the cell. |
| Its cell is discarded | Invalid. | Valid, but has no value until you set it again. |
| Terminal is freed | Invalid. | Valid, but has no value. You still have to free it. |
| Cost | One lookup. | Bookkeeping on every terminal change for as long as it exists. |