Your First Terminal
Let’s create a simple terminal that processes real bytes and produces a rendered screen. There’s no GUI or real pty attached to it, to keep the example simple and focused on libghostty-vt.
Every feature in libghostty-vt builds on the basics shown here: the function call style, error handling, and option setting. If you go through this page, then you’ll be able to easily adopt the remainder of the library.
We’ll walk through rust-vt-stream.
Installing shows how to build it, and in the repo it’s one
cargo run.
Create a Terminal
let mut terminal = Terminal::new(80, 24)?;
Full code: rust-vt-stream/src/main.rs.
Terminal::new() takes the size in columns and rows. If you want to use a
custom allocator, use Terminal::new_with_alloc(). See Memory.
libghostty-vt functions never crash your program by design, given valid use of
the API. All failure scenarios including allocation failures are handled and
returned, and libghostty-vt never puts itself into a corrupt state. Always check
the Result of every function.
Write Bytes
// Feed VT data into the terminal
terminal.vt_write(b"Hello, World!\r\n");
// ANSI color codes: ESC[1;32m = bold green, ESC[0m = reset
terminal.vt_write(b"\x1b[1;32mGreen Text\x1b[0m\r\n");
// Cursor positioning: ESC[1;1H = move to row 1, column 1
terminal.vt_write(b"\x1b[1;1HTop-left corner\r\n");
// Cursor movement: ESC[5B = move down 5 lines
terminal.vt_write(b"\x1b[5B");
terminal.vt_write(b"Moved down!\r\n");
// Erase line: ESC[2K = clear entire line
terminal.vt_write(b"\x1b[2K");
terminal.vt_write(b"New content\r\n");
// Multiple lines
terminal.vt_write(b"Line A\r\nLine B\r\nLine C\r\n");
Full code: rust-vt-stream/src/main.rs.
Terminal::vt_write() takes the raw bytes a program wrote (e.g. from a
pty, session recording, network, etc.). libghostty-vt parses all escape
sequences and applies their logic appropriately to the terminal state. Above,
\x1b[1;32m turns on bold green. \x1b[5B moves the cursor down five rows.
This call never fails, which is why there’s no result to check. You also don’t need to line your writes up with anything. A sequence or a UTF-8 character can be split across two calls and the parser picks up where it left off.
It is safe to pass untrusted data to this function. Bad input gets skipped. By default, without any effects, untrusted data can’t cause any damage. Memory usage is bounded and no side effects are possible. libghostty-vt is fuzzed 24/7 with multiple dedicated machines to keep this function safe against all forms of data input.
Your program can widen this. Be careful with effects, such as clipboard reads, and with the options that let Kitty images load from files or shared memory. Anything you read back, such as the title, also came from untrusted data, so treat it that way.
Note the end of each line is \r\n, not just \n. In terminal emulators, a
\n alone just moves the cursor down. It doesn’t move it back to the first
column.
You rarely see this because a pty normally turns a program’s \n into \r\n in
the kernel line discipline logic. But if you feed in bytes that didn’t come
through a pty, such as a text file, that’s now your job. Beware!
Read the Screen
Warning
The formatter is only for simple snapshots of the screen, such as saving it to a file or printing it once. Don’t use it for a real, live render. Use a render state instead. See Draw the Screen.
// Get the final terminal state as a plain string using the formatter
let mut formatter = fmt::Formatter::new(&terminal)?;
formatter.set_format(fmt::Format::Plain)?.set_trim(true)?;
let buf = formatter.format_alloc(None)?;
println!("{}", buf.escape_ascii());
Full code: rust-vt-stream/src/main.rs.
A terminal screen is a grid of cells with styles, wide characters, wrapped rows, etc. The formatter processes this grid state and produces the screen state into a format requested: plain text, HTML, VT sequences.
A new formatter by default emits plain text with trailing whitespace trimmed, so
the two Formatter::set_* calls here only show you where those options
are.
The program prints this:
Top-left corner
Green Text
Moved down!
New content
Line A
Line B
Line C
Notice what’s missing. We wrote Hello, World! first, but Top-left corner
went on top of it after the cursor moved to row 1. This shows that the
formatter is processing a real terminal screen.
Draw the Screen
The RenderState API exists to build a high-performance, low-latency, frame-by-frame renderer. It can be used as the foundation for CPU or GPU rendering. It does dirty tracking, viewport handling, smooth scroll handling, and more.
// Create these once and reuse them for every frame.
let mut render_state = RenderState::new()?;
let mut rows = RowIterator::new()?;
let mut cells = CellIterator::new()?;
// Capture the frame. This is the only step that reads the terminal.
let snapshot = render_state.update(&terminal)?;
// Visit only the rows that changed. In the first frame, that's all of them.
let mut row_iter = rows.update(&snapshot)?;
while let Some((_y, row)) = row_iter.next_dirty() {
let mut cell_iter = cells.update(row)?;
while let Some(cell) = cell_iter.next() {
let style = cell.style()?;
let mut graphemes = String::new();
cell.graphemes_utf8(&mut graphemes)?;
// A real renderer draws the cell here. We print it, with its bold
// style, which the plain text from the formatter didn't have.
if graphemes.is_empty() {
print!(" ");
continue;
}
if style.bold {
print!("\x1b[1m");
}
print!("{graphemes}");
if style.bold {
print!("\x1b[0m");
}
}
println!();
}
// The frame is drawn, so the next one only reports new changes.
snapshot.clean()?;
Full code: rust-vt-stream/src/main.rs.
A real renderer repeats three steps for every frame: update, draw, clean. Create the handles once, outside of that loop.
RenderState::update() is the only step that touches the terminal, which
creates a Snapshot of the render state. After that, you draw from the
snapshot alone, so your renderer doesn’t get in the way of the program writing
to the terminal. The update only redoes what changed. Because only update needs
access to the terminal, this is the only critical area that requires a lock for
multi-threaded terminal and renderers.
Note
Unlike the C API, in Rust we make a clear distinction between a
RowIteratorand aRowIteration. While the iterator can be reused over and over again, the iteration only reflects its current state, after being fed up-to-date data. This is to prevent users from accessing stale or invalid state when iterators aren’t yet ready.This design is symmetrical across all handles of the render state API:
Handle created on startup State on each frame RenderStateSnapshotRowIteratorRowIterationCellIteratorCellIterationImageIteratorImageIteration
RowIteration::next_dirty() skips the rows that didn’t change, which is most of
them in most frames. Once you’ve drawn a complete frame, Snapshot::clean()
marks it as done. An update never clears the dirty state, so without this call
every row stays dirty.
This program draws by printing, so you see the same screen as the formatter
printed, except that Green Text is now bold. It’s still not green, because we
didn’t read the colors. See Rendering for the colors, the cursor, and
how to share a terminal with a renderer thread.
Drop Everything
libghostty-vt does allocate at times, and they need to be dropped. Fortunately, the Rust bindings use Rust’s lifetime and RAII rules as much as possible to drop them in the correct order.
The buffer from Formatter::format_alloc() is yours. You can drop it whenever
you want, as long as the buffer does not outlive the allocator it that gave
its memory. See Allocating and Dropping Buffers.
The formatter borrows the terminal, so the terminal has to outlive it. Drop the formatter first.
The render state and its iterators are yours too. The borrow checker should be able to ensure they are dropped in order.
The terminal should be dropped last.
The rules for handles are the same across the whole library. See Handles.