Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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:

  1. Create an empty render state.
  2. Update it from a terminal whenever you need a new frame. This returns a snapshot of the render state.
  3. 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:

  1. Set a Terminal::on_render_hold() callback on the terminal.
  2. 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().
  3. Don’t update the render state again until the hold ends. You can keep drawing it in the meantime, and it won’t change.
  4. 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:

  1. A row with the same id is in the new update.
  2. 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);
}