Struct TerminalGrid 

pub struct TerminalGrid { /* private fields */ }

A high-performance terminal grid renderer using instanced rendering.

TerminalGrid renders a grid of terminal cells using GL instanced drawing. Each cell can display a character from a font atlas with customizable foreground and background colors. The renderer uses a 2D texture array to efficiently store glyph data and supports real-time updates of cell content.

Implementations

impl TerminalGrid

pub fn cell_iter(&self, selection: CellQuery) -> CellIterator

Zero-allocation iterator over cell indices for a given selection range and mode.

Creates an efficient iterator that yields cell indices and newline indicators without allocating intermediate collections.

Returns

Iterator yielding (cell_index, needs_newline_after) tuples.

pub fn get_text(&self, selection: CellQuery) -> CompactString

Extracts text content from the terminal based on the selection query.

Retrieves the text within the selection range, optionally trimming trailing whitespace from each line based on the query configuration.

Arguments

• selection - Query defining the selection range and options

Returns

The selected text as a CompactString, or empty string if no selection.

impl TerminalGrid

pub fn new( gl: &Context, atlas: FontAtlas, screen_size: (i32, i32), pixel_ratio: f32, glsl_version: &GlslVersion, ) -> Result<TerminalGrid, Error>

pub fn delete(self, gl: &Context)

Deletes all GPU resources owned by this terminal grid.

This must be called before dropping the TerminalGrid to avoid GPU resource leaks on native OpenGL targets. On WASM, WebGL context teardown handles cleanup automatically, but explicit deletion is still recommended.

pub fn set_fallback_glyph(&mut self, fallback: &str)

Sets the fallback glyph for missing characters.

pub fn replace_atlas(&mut self, gl: &Context, atlas: FontAtlas)

Replaces the current font atlas with a new one, translating all existing glyph IDs to the new atlas.

This method handles the transition between atlases by:

1. Looking up the symbol for each existing glyph ID in the old atlas
2. Resolving the corresponding glyph slot in the new atlas
3. Updating double-width glyphs (emoji, wide chars) across both cells
4. Resizing the grid if cell dimensions changed

pub fn atlas(&self) -> &FontAtlas

Returns the FontAtlas used by this terminal grid.

pub fn atlas_mut(&mut self) -> &mut FontAtlas

Returns a mutable reference to the font atlas.

pub fn set_bg_alpha(&mut self, gl: &Context, alpha: f32)

Sets the background opacity for terminal cells.

When less than 1.0, cell backgrounds become semi-transparent, allowing content rendered behind the terminal grid to show through. Text remains fully opaque regardless of this setting.

The change takes effect on the next call to resize or when the UBO data is next uploaded.

pub fn canvas_size(&self) -> (i32, i32)

Returns the canvas size in pixels.

pub fn cell_size(&self) -> (i32, i32)

Returns the effective cell dimensions in pixels (base size * cell scale).

pub fn css_cell_size(&self) -> (f32, f32)

Returns the cell dimensions in CSS pixels (effective size / device pixel ratio).

Use this for converting browser mouse coordinates (which are in CSS pixels) to terminal grid coordinates.

pub fn terminal_size(&self) -> (u16, u16)

Returns the size of the terminal grid in cells.

pub fn render(&self, gl: &Context, state: &mut GlState) -> Result<(), Error>

Renders the terminal grid in a single call.

This is a convenience method that constructs a RenderContext and executes the full Drawable lifecycle (prepare → draw → cleanup). For advanced use cases such as compositing with other GL content, use the Drawable trait methods directly.

pub fn cell_data_mut(&mut self, x: u16, y: u16) -> Option<&mut CellDynamic>

Returns a mutable reference to the cell data at the specified cell coordinates.

pub fn selection_tracker(&self) -> SelectionTracker

Returns the active selection state of the terminal grid.

pub fn cell_count(&self) -> usize

Returns the total number of cells in the terminal grid.

pub fn update_cells<'a>( &mut self, cells: impl Iterator<Item = CellData<'a>>, ) -> Result<(), Error>

Updates the content of terminal cells with new data.

pub fn update_cells_by_position<'a>( &mut self, cells: impl Iterator<Item = (u16, u16, CellData<'a>)>, ) -> Result<(), Error>

pub fn update_cells_by_index<'a>( &mut self, cells: impl Iterator<Item = (usize, CellData<'a>)>, ) -> Result<(), Error>

pub fn update_cell( &mut self, x: u16, y: u16, cell_data: CellData<'_>, ) -> Result<(), Error>

pub fn update_cell_by_index( &mut self, idx: usize, cell_data: CellData<'_>, ) -> Result<(), Error>

pub fn flush_cells(&mut self, gl: &Context) -> Result<(), Error>

Flushes pending cell updates to the GPU.

pub fn resize( &mut self, gl: &Context, canvas_size: (i32, i32), pixel_ratio: f32, ) -> Result<(), Error>

Resizes the terminal grid to fit the new canvas dimensions.

pub fn recreate_resources( &mut self, gl: &Context, glsl_version: &GlslVersion, ) -> Result<(), Error>

Recreates all GPU resources after a context loss.

Note: After a context loss, old GL resources are already invalid, so we skip explicit deletion and just create fresh resources.

pub fn recreate_atlas_texture(&mut self, gl: &Context) -> Result<(), Error>

Recreates the font atlas texture after a context loss.

pub fn base_glyph_id(&self, symbol: &str) -> Option<u16>

Returns the base glyph identifier for a given symbol.

Trait Implementations

impl Debug for TerminalGrid

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Drawable for TerminalGrid

fn prepare(&self, context: &mut RenderContext<'_>) -> Result<(), Error>

Prepares the object for rendering.

fn draw(&self, context: &mut RenderContext<'_>)

Performs the actual rendering.

fn cleanup(&self, context: &mut RenderContext<'_>)

Cleans up after rendering.