Struct MatrixRainState 

pub struct MatrixRainState { /* private fields */ }

Per-frame animation state for a MatrixRain widget.

Holds one stream per terminal column, a seeded RNG, timing bookkeeping, and a cached terminal color count. The same state instance must be passed across consecutive renders so the animation continues from frame to frame.

MatrixRainState is Send but not Sync — it’s designed for single-threaded use (render takes &mut self).

Example

use matrix_rain::{MatrixConfig, MatrixRain, MatrixRainState};
use ratatui::buffer::Buffer;
use ratatui::layout::Rect;
use ratatui::widgets::StatefulWidget;

let cfg = MatrixConfig::default();
let mut state = MatrixRainState::with_seed(42);
let mut buf = Buffer::empty(Rect::new(0, 0, 40, 12));
MatrixRain::new(&cfg).render(Rect::new(0, 0, 40, 12), &mut buf, &mut state);
assert_eq!(state.streams_len(), 40);

Implementations

impl MatrixRainState

pub fn new() -> Self

Create a new state seeded from system entropy.

Use with_seed instead when you need reproducible output (snapshot tests, screenshots, --seed in the binary).

Requires the std feature (entropy comes from getrandom). no_std callers must use with_seed.

pub fn with_seed(seed: u64) -> Self

Create a new state with a deterministic RNG seed.

Two states constructed with the same seed and driven through the same area/config sequence produce identical streams.

Example

use matrix_rain::MatrixRainState;
let a = MatrixRainState::with_seed(42);
let b = MatrixRainState::with_seed(42);
assert_eq!(a.streams_len(), b.streams_len());

pub fn tick(&mut self)

Advance the animation by exactly one frame, regardless of wall-clock time. Bypasses pause.

Uses the area and configuration cached by the most recent MatrixRain::render call; before the first render, this is a silent no-op. last_tick is not touched, so mixing manual ticks with wall-clock-driven renders will drift over time — pick one driving mode per session.

pub fn reset(&mut self)

Clear streams, timing, cached area/config, frame counter, and the paused flag. RNG state and cached color count are preserved.

After reset, the next render is treated as a first render (applies exactly one tick).

pub fn pause(&mut self)

Pause wall-clock-driven advance. Subsequent render() / advance() calls still handle resize and paint the current state, but do not move streams forward. Manual tick() is unaffected. Idempotent.

pub fn resume(&mut self)

Resume wall-clock-driven advance after a pause(). Discards any previously-recorded last_tick/accum so the next render is treated as a first render (exactly one tick applied) — preventing the catch-up-cap stutter that an accumulated pause-time would otherwise trigger. Idempotent.

pub fn is_paused(&self) -> bool

Returns whether wall-clock advance is currently suppressed.

pub fn streams_len(&self) -> usize

Returns the number of column streams currently allocated.

After a render into a non-empty area, this equals area.width as usize. After a render into an empty area (width == 0 or height == 0), returns 0.

pub fn set_color_count(&mut self, count: u16)

Override the cached terminal color count, suppressing auto-detection on the next render. Useful for forcing a specific gradient tier (16-color collapse for accessibility, 256-color quantization, or u16::MAX for the smooth-interpolation path) and for deterministic testing where TERM/COLORTERM should not influence rendering.

Trait Implementations

impl Default for MatrixRainState

Available on crate feature std only.

fn default() -> Self

Returns the “default value” for a type.