Struct Buffer 

pub struct Buffer {
    pub degradation: DegradationLevel,
    /* private fields */
}

A 2D grid of terminal cells.

Example

use ftui_render::buffer::Buffer;
use ftui_render::cell::Cell;

let mut buffer = Buffer::new(80, 24);
buffer.set(0, 0, Cell::from_char('H'));
buffer.set(1, 0, Cell::from_char('i'));

Fields

degradation: DegradationLevel

Current degradation level for this frame.

Widgets read this during rendering to decide how much visual fidelity to provide. Set by the runtime before calling Model::view().

Implementations

impl Buffer

pub fn new(width: u16, height: u16) -> Self

Create a new buffer with the given dimensions.

All cells are initialized to the default (empty cell with white foreground and transparent background).

Panics

Panics if width or height is 0.

pub const fn width(&self) -> u16

Buffer width in cells.

pub const fn height(&self) -> u16

Buffer height in cells.

pub fn len(&self) -> usize

Total number of cells.

pub fn is_empty(&self) -> bool

Check if the buffer is empty (should never be true for valid buffers).

pub const fn bounds(&self) -> Rect

Bounding rect of the entire buffer.

pub fn content_height(&self) -> u16

Return the height of content (last non-empty row + 1).

Rows are considered empty only if all cells are the default cell. Returns 0 if the buffer contains no content.

pub fn mark_all_dirty(&mut self)

Mark all rows as dirty (e.g., after a full clear or bulk write).

pub fn clear_dirty(&mut self)

Reset all dirty flags and spans to clean.

Call this after the diff has consumed the dirty state (between frames).

pub fn is_row_dirty(&self, y: u16) -> bool

Check if a specific row is dirty.

pub fn dirty_rows(&self) -> &[bool]

Get the dirty row flags as a slice.

Each element corresponds to a row: true means the row was modified since the last clear_dirty() call.

pub fn dirty_row_count(&self) -> usize

Count the number of dirty rows.

pub fn dirty_span_stats(&self) -> DirtySpanStats

Summarize dirty-span stats for logging/telemetry.

pub fn dirty_span_config(&self) -> DirtySpanConfig

Access the dirty-span configuration.

pub fn set_dirty_span_config(&mut self, config: DirtySpanConfig)

Update dirty-span configuration (clears existing spans when changed).

pub fn get(&self, x: u16, y: u16) -> Option<&Cell>

Get a reference to the cell at (x, y).

Returns None if coordinates are out of bounds.

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

Get a mutable reference to the cell at (x, y).

Returns None if coordinates are out of bounds. Proactively marks the row dirty since the caller may mutate the cell.

pub fn get_unchecked(&self, x: u16, y: u16) -> &Cell

Get a reference to the cell at (x, y) without bounds checking.

Panics

Panics in debug mode if coordinates are out of bounds. May cause undefined behavior in release mode if out of bounds.

pub fn set_fast(&mut self, x: u16, y: u16, cell: Cell)

Fast-path cell write for the common case.

Bypasses scissor intersection, opacity blending, and overlap cleanup when all of the following hold:

• The cell is single-width (width() <= 1) and not a continuation
• The cell background is either fully opaque or fully transparent (bg.a() == 255 || bg.a() == 0)
• Only the base scissor is active (no nested push)
• Only the base opacity is active (no nested push)
• The existing cell at the target is also single-width and not a continuation

Falls through to [set()] for any non-trivial case, so behavior is always identical to calling set() directly.

pub fn set(&mut self, x: u16, y: u16, cell: Cell)

Set the cell at (x, y).

This method:

• Respects the current scissor region (skips if outside)
• Applies the current opacity stack to cell colors
• Does nothing if coordinates are out of bounds
• Automatically sets CONTINUATION cells for multi-width content
• Atomic wide writes: If a wide character doesn’t fully fit in the scissor region/bounds, NOTHING is written.

For bulk operations without scissor/opacity/safety, use [set_raw].

pub fn set_raw(&mut self, x: u16, y: u16, cell: Cell)

Set the cell at (x, y) without scissor or opacity processing.

This is faster but bypasses clipping and transparency. Does nothing if coordinates are out of bounds.

pub fn fill(&mut self, rect: Rect, cell: Cell)

Fill a rectangular region with the given cell.

Respects scissor region and applies opacity.

pub fn clear(&mut self)

Clear all cells to the default.

pub fn reset_for_frame(&mut self)

Reset per-frame state and clear all cells.

This restores scissor/opacity stacks to their base values to ensure each frame starts from a clean rendering state.

pub fn clear_with(&mut self, cell: Cell)

Clear all cells to the given cell.

pub fn cells(&self) -> &[Cell]

Get raw access to the cell slice.

This is useful for diffing against another buffer.

pub fn cells_mut(&mut self) -> &mut [Cell]

Get mutable raw access to the cell slice.

Marks all rows dirty since caller may modify arbitrary cells.

pub fn row_cells(&self, y: u16) -> &[Cell]

Get the cells for a single row as a slice.

Panics

Panics if y >= height.

pub fn push_scissor(&mut self, rect: Rect)

Push a scissor (clipping) region onto the stack.

The effective scissor is the intersection of all pushed rects. If the intersection is empty, no cells will be drawn.

pub fn pop_scissor(&mut self)

Pop a scissor region from the stack.

Does nothing if only the base scissor remains.

pub fn current_scissor(&self) -> Rect

Get the current effective scissor region.

pub fn scissor_depth(&self) -> usize

Get the scissor stack depth.

pub fn push_opacity(&mut self, opacity: f32)

Push an opacity multiplier onto the stack.

The effective opacity is the product of all pushed values. Values are clamped to [0.0, 1.0].

pub fn pop_opacity(&mut self)

Pop an opacity value from the stack.

Does nothing if only the base opacity remains.

pub fn current_opacity(&self) -> f32

Get the current effective opacity.

pub fn opacity_depth(&self) -> usize

Get the opacity stack depth.

pub fn copy_from( &mut self, src: &Buffer, src_rect: Rect, dst_x: u16, dst_y: u16, )

Copy a rectangular region from another buffer.

Copies cells from src at src_rect to this buffer at dst_pos. Respects scissor region.

pub fn content_eq(&self, other: &Buffer) -> bool

Check if two buffers have identical content.

Trait Implementations

impl Clone for Buffer

fn clone(&self) -> Buffer

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Buffer

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

Formats the value using the given formatter.

impl Default for Buffer

fn default() -> Self

Create a 1x1 buffer (minimum size).

impl Draw for Buffer

fn draw_horizontal_line(&mut self, x: u16, y: u16, width: u16, cell: Cell)

Draw a horizontal line of cells.

fn draw_vertical_line(&mut self, x: u16, y: u16, height: u16, cell: Cell)

Draw a vertical line of cells.

fn draw_rect_filled(&mut self, rect: Rect, cell: Cell)

Draw a filled rectangle.

fn draw_rect_outline(&mut self, rect: Rect, cell: Cell)

Draw a rectangle outline using a single cell character.

fn print_text(&mut self, x: u16, y: u16, text: &str, base_cell: Cell) -> u16

Print text at the given coordinates using the cell’s colors/attrs.

fn print_text_clipped( &mut self, x: u16, y: u16, text: &str, base_cell: Cell, max_x: u16, ) -> u16

Print text with a right-side clipping boundary.

fn draw_border(&mut self, rect: Rect, chars: BorderChars, base_cell: Cell)

Draw a border around a rectangle using the given characters.

fn draw_box( &mut self, rect: Rect, chars: BorderChars, border_cell: Cell, fill_cell: Cell, )

Draw a border and fill the interior.

fn paint_area( &mut self, rect: Rect, fg: Option<PackedRgba>, bg: Option<PackedRgba>, )

Set all cells in a rectangular area to the given fg/bg/attrs without changing cell content.

impl PartialEq for Buffer

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for Buffer