Rendering
A render state is a copy of everything you need to draw one frame: the rows, the cells, the cursor, and the colors.
Why a copy? Your renderer and your IO are usually on different threads. The terminal changes every time the program writes a byte, and you can’t draw from something that is changing underneath you. You could hold a lock for the whole frame, but then the program stalls while you draw.
With a render state you take the lock, update, and let go. Everything after that reads only from the render state.
It’s also built for being updated over and over from the same terminal. An update only redoes what changed, and it tells you what changed so you can redraw only that.
If you only want the screen as text, you don’t need this page. Use the Formatter instead. Images have their own guide, Images.
Drawing a frame
There are three steps:
- Create an empty render state.
- Update it from a terminal whenever you need a new frame. This returns a snapshot of the render state.
- Read from the snapshot to draw.
// 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.
let mut terminal = Terminal::new(40, 5)?;
let mut render_state = RenderState::new()?;
// Feed some styled content into the terminal.
terminal.vt_write(b"Hello, \x1b[1;32mworld\x1b[0m!\r\n"); // bold green "world"
terminal.vt_write(b"\x1b[4munderlined\x1b[0m text\r\n"); // underlined text
terminal.vt_write(b"\x1b[38;2;255;128;0morange\x1b[0m\r\n"); // 24-bit orange fg
// Select "underlined" on the second row. Render state exposes this
// later as a row-local selected cell range.
let selection_start = terminal.grid_ref(Point::Active(Coordinate { x: 0, y: 1 }))?;
let selection_end = terminal.grid_ref(Point::Active(Coordinate { x: 9, y: 1 }))?;
let selection = terminal.select(selection_start, selection_end, false);
terminal.set_selection(Some(selection))?;
let snapshot = render_state.update(&terminal)?;
Full program: rust-vt-render/src/main.rs
Now read what you need. The colors come as one struct:
// Retrieve colors (background, foreground, palette) from the render
// state. These are needed to resolve palette-indexed cell colors.
let colors = snapshot.colors()?;
println!(
"Background: #{:02x}{:02x}{:02x}",
colors.background.r, colors.background.g, colors.background.b
);
println!(
"Foreground: #{:02x}{:02x}{:02x}",
colors.foreground.r, colors.foreground.g, colors.foreground.b
);
Full program: rust-vt-render/src/main.rs
So does the cursor:
// Read all cursor state in one call.
let cursor = snapshot.cursor()?;
if cursor.visible
&& let Some(viewport) = cursor.viewport
{
let style_name = match cursor.visual_style {
CursorVisualStyle::Bar => "bar",
CursorVisualStyle::Block => "block",
CursorVisualStyle::Underline => "underline",
CursorVisualStyle::BlockHollow => "hollow",
_ => "unknown",
};
println!(
"Cursor at ({}, {}), style: {}",
viewport.x, viewport.y, style_name
);
}
Full program: rust-vt-render/src/main.rs
Rows and cells have their own iterators. Row and cell data is only valid until the next update.
// 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".
let mut rows = RowIterator::new()?;
let mut cells = CellIterator::new()?;
let mut row_it = rows.update(&snapshot)?;
while let Some((y, row)) = row_it.next_dirty() {
print!("Row {y} [dirty]: ");
// Query the row-local selection range. Rows without a selection return
// `None`; selected rows return inclusive start/end columns.
if let Some(selection) = row.selection()? {
print!("selection={}..{}", selection.start_x, selection.end_x);
}
// Get cells for this row (reuses the same cells handle).
let mut cell_it = cells.update(row)?;
while let Some(cell) = cell_it.next() {
// Get the graphemes of this cell.
let graphemes = cell.graphemes()?;
if graphemes.is_empty() {
print!(" ");
continue;
}
// Read the style for this cell. Returns the default style for
// cells that have no explicit styling.
let style = cell.style()?;
// Resolve foreground color for this cell.
let fg = cell.fg_color()?.unwrap_or(colors.foreground);
// Emit ANSI true-color escape for the foreground.
print!("\x1b[38;2;{};{};{}m", fg.r, fg.g, fg.b);
if style.bold {
print!("\x1b[1m");
}
if style.underline != Underline::None {
print!("\x1b[4m");
}
// Print the read grapheme codepoints.
// In a real renderer you would reuse a grapheme buffer for this step.
print!("{}", String::from_iter(graphemes));
print!("\x1b[0m"); // Reset style after each cell.
}
println!();
}
Full program: rust-vt-render/src/main.rs
Two-phase updates
RenderState::update() needs exclusive access to the terminal for the
whole call. If a renderer thread shares a lock with an IO thread, you can hold
that lock for less time by splitting the update in two.
RenderState::begin_update() needs the terminal and returns a render::Update
object. render::Update::end() finishes any work that was deferred, and it
only touches memory the render state owns. So lock, begin, unlock, and then end
while the IO thread goes back to modifying the terminal:
let update = {
let terminal = terminal_mutex.lock().unwrap();
render_state.begin_update(&terminal)
};
let snapshot = update.end();
Every begin needs an end before you read the render state, because it’s
incomplete until then. RenderState::update() is the same as calling the two
back to back.
Dirty tracking
Most frames change very little, so the render state tracks what changed and you redraw only that.
There are two independent layers. A global state says if the frame is clean, partially dirty or fully dirty. A flag on each row says which rows changed in a partially dirty frame.
// Check the global dirty state to decide how much work the renderer
// needs to do. After rendering, reset it to false.
match snapshot.dirty()? {
Dirty::Clean => println!("Frame is clean, nothing to draw."),
Dirty::Partial => println!("Partial redraw needed."),
Dirty::Full => println!("Full redraw needed."),
}
Full program: rust-vt-render/src/main.rs
An update only ever sets dirty state, it never clears it. That’s your job. Once
you’ve drawn a complete frame, Snapshot::clean clears both layers in one
call:
// After successfully rendering the complete frame, clear both the global
// and per-row dirty state in one call.
snapshot.clean()?;
Full program: rust-vt-render/src/main.rs
If you only use part of a frame, clear what you used with
Snapshot::set_dirty() and RowIteration::set_dirty() instead.
Be careful here, because clearing one layer doesn’t clear the other. Setting the
global state to false leaves every row flag as it was, so you have to manage
both.
Render holds
A render hold is the time between a program asking the terminal to stop updating the screen and letting it update again.
Programs use holds to avoid flicker. A full-screen program usually redraws in several steps: clear, draw the text, move the cursor. If you draw halfway through, the person using your terminal sees a broken frame. So the program starts a hold, draws everything, and releases it. The screen should keep showing the last finished frame the whole time and then switch to the new one all at once.
Today the only way to start a hold is synchronized output (DEC private mode
2026, Mode::SYNC_OUTPUT). The callback is named for what you should do
rather than for that mode, so that other sources of holds can be added later.
RenderState::update() doesn’t check for any of this. It always captures
the terminal as it is right now, so a renderer that updates on every draw shows
half-drawn frames. To avoid that:
- Set a
Terminal::on_render_hold()callback on the terminal. - When a hold begins, update the render state from inside the callback. At that
moment the terminal holds exactly the frame the program wants left on screen.
Nothing after the start of the hold has been processed yet, even if more
bytes follow in the same
Terminal::vt_write(). - Don’t update the render state again until the hold ends. You can keep drawing it in the meantime, and it won’t change.
- End the hold yourself if it lasts too long.
You need the timeout. The terminal has no clock, so it never ends a hold on its own, and a program that crashes or forgets to release its hold would freeze your screen forever. One second is a common limit. When it expires, reset the mode yourself and go back to updating normally. Setting the mode again during a hold does nothing, so a program can’t keep pushing your deadline back.
Why a callback? You could check Mode::SYNC_OUTPUT before each draw and
skip the update when it’s set. That’s simpler, but it has two problems. First,
the frame left on screen is whatever you happened to draw last, which can be
older than what the program intended or even half-drawn. Second, if the program
releases a hold and starts the next one between two of your draws, you never see
the mode turn off, and the finished frame in between is lost. A program that
draws continuously can then look frozen. Capturing the frame when each hold
begins avoids both.
You’re free to ignore a hold whenever live content matters more, such as when someone scrolls or starts a selection.
Like every callback, this one runs on the thread that called
Terminal::vt_write(). If another thread draws the render state, protect
the update in the callback the same way you protect any other access to it.
Overscan
By default, a render state captures exactly the rows visible in the viewport. That’s all you need if you draw whole rows, so most programs can skip this section.
Some renderers draw the grid shifted by a fraction of a row, usually to scroll smoothly. While the grid is shifted, part of a row just outside the viewport shows at one edge, and you need that row’s content to draw it. Overscan captures extra rows above and below the viewport for this.
Request it with RenderState::set_overscan(). The request applies to every
update after you set it, and you should expect a full redraw on the update after
a change. The row iterator then visits the extra rows along with the viewport,
from top to bottom. RowIteration::viewport_y() tells you where
each row belongs: rows above the viewport are negative, viewport rows are 0
through snapshot.rows() - 1, and rows below the viewport start at snapshot.rows().
Extra rows are only captured when they exist. There’s nothing above the first
line of scrollback, and there’s nothing below the viewport while it’s scrolled
to the bottom, which is the usual case. After an update, Snapshot::overscan()
reports how many rows were actually captured on each side. Don’t shift the grid
toward a side where nothing was captured.
Extra rows carry the same data as viewport rows, including cells, styles, dirty flags and selection. The cursor is only reported when it’s inside the viewport.
The render state doesn’t store the scroll position. If you need it, read
Terminal::scrollbar() or Terminal::viewport_active() at the same time as you
call RenderState::begin_update(), while you have exclusive access to the
terminal. The values then describe the same moment as the render state.
This draws one frame of a smooth scroll. offset_px comes from your own scroll
animation. It’s how far the grid is shifted up, from zero up to but not
including one row height.
// Once, when setting up the render state. One row below the viewport
// is enough to draw the partially visible row at the bottom edge.
render_state.set_overscan(Overscan { above: 0, below: 1 })?;
// Each frame.
let snapshot = render_state.update(&terminal)?;
let captured = snapshot.overscan()?;
// With no row below the viewport, there is nothing to scroll into.
if captured.below == 0 { offset_px = 0; }
let mut row_iter = rows.update(&snapshot)?;
while let Some(row) = row_iter.next() {
let y = row.viewport_y()?;
draw_row(row, y * cell_height - offset_px);
}
Row identity
Every row has an id, RowIteration::id(), that stays with the row
as it moves. When the viewport scrolls by one row, each row shows up one
position higher or lower in the next update but keeps its id. Ids work with or
without overscan.
Ids let you keep expensive per-row work, such as shaped text or a prepared texture, in your own cache keyed by id. You can reuse a cached entry when both of these are true:
- A row with the same id is in the new update.
- That row’s dirty flag isn’t set.
The dirty flag is conservative. A row can be marked dirty even though its content didn’t change. For example, every row is currently marked dirty after the viewport scrolls. Rebuilding a dirty row is always correct.
An id disappears when its row is no longer captured, is removed from scrollback, or is changed in place by the terminal, for example when a program scrolls only part of the screen. Ids are never reused, so an old id can never match a different row. You can throw away cache entries for ids that no longer appear.
while let Some(row) = row_iter.next() {
let id = row.id()?;
// `cache` is your own map from row id to prepared row.
let prepared = if row.dirty()? { None } else { cache.find(id) };
let prepared = prepared.or_else(|| cache.prepare(id, row));
draw_prepared_row(prepared);
}