Struct AdaptiveDoubleBuffer 

pub struct AdaptiveDoubleBuffer { /* private fields */ }

Adaptive double-buffered render target with allocation efficiency.

Wraps DoubleBuffer with capacity tracking to minimize allocations during resize storms. Key strategies:

1. Over-allocation headroom: Allocate slightly more than needed to handle minor size increases without reallocation.
2. Shrink threshold: Only shrink if new size is significantly smaller than allocated capacity (prevents thrashing at size boundaries).
3. Logical vs physical dimensions: Track both the current view size and the allocated capacity separately.

Invariants

1. capacity_width >= logical_width and capacity_height >= logical_height
2. Logical dimensions represent the actual usable area for rendering.
3. Physical capacity may exceed logical dimensions by up to ADAPTIVE_GROWTH_FACTOR.
4. Shrink only occurs when logical size drops below ADAPTIVE_SHRINK_THRESHOLD * capacity.

Failure Modes

Condition	Behavior	Rationale
Capacity overflow	Clamp to u16::MAX	Prevents panic on extreme sizes
Zero dimensions	Delegate to DoubleBuffer (panic)	Invalid state

Performance

• resize() is O(1) when the new size fits within capacity.
• resize() is O(width × height) when reallocation is required.
• Target: < 5% allocation overhead during resize storms.

Implementations

impl AdaptiveDoubleBuffer

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

Create a new adaptive buffer with the given logical dimensions.

Initial capacity is set with growth headroom applied.

Panics

Panics if width or height is 0.

pub fn swap(&mut self)

O(1) swap: the current buffer becomes previous, and vice versa.

After swapping, call current_mut().clear() to prepare for the next frame.

pub fn current(&self) -> &Buffer

Reference to the current (in-progress) frame buffer.

Note: The buffer may have larger dimensions than the logical size. Use logical_width() and logical_height() for rendering bounds.

pub fn current_mut(&mut self) -> &mut Buffer

Mutable reference to the current (in-progress) frame buffer.

pub fn previous(&self) -> &Buffer

Reference to the previous (last-presented) frame buffer.

pub fn width(&self) -> u16

Logical width (the usable rendering area).

pub fn height(&self) -> u16

Logical height (the usable rendering area).

pub fn capacity_width(&self) -> u16

Allocated capacity width (may be larger than logical width).

pub fn capacity_height(&self) -> u16

Allocated capacity height (may be larger than logical height).

pub fn stats(&self) -> &AdaptiveStats

Get allocation statistics.

pub fn reset_stats(&mut self)

Reset allocation statistics.

pub fn resize(&mut self, width: u16, height: u16) -> bool

Resize the logical dimensions. Returns true if dimensions changed.

This method minimizes allocations by:

1. Reusing existing capacity when the new size fits.
2. Only reallocating on significant shrink (below threshold).
3. Applying growth headroom to avoid immediate reallocation on growth.

Performance

• O(1) when new size fits within existing capacity.
• O(width × height) when reallocation is required.

pub fn dimensions_match(&self, width: u16, height: u16) -> bool

Check whether logical dimensions match the given values.

pub fn logical_bounds(&self) -> Rect

Get the logical bounding rect (for scissoring/rendering).

pub fn memory_efficiency(&self) -> f64

Calculate memory efficiency (logical cells / capacity cells).

Trait Implementations

impl Debug for AdaptiveDoubleBuffer

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

Formats the value using the given formatter.