Struct PrerenderedAnimation 

pub struct PrerenderedAnimation { /* private fields */ }

Pre-rendered animation for optimal playback performance.

PrerenderedAnimation stores a sequence of BrailleGrid frames that can be played back at a specified frame rate with zero computation during playback. This is ideal for loading spinners, intro animations, and caching expensive computations.

Memory Usage

Each frame uses approximately width × height bytes. For a typical 80×24 terminal, that’s about 2KB per frame. A 10-second animation at 30fps (300 frames) uses approximately 600KB.

Example

use dotmax::animation::PrerenderedAnimation;
use dotmax::BrailleGrid;

// Create animation with target frame rate
let mut animation = PrerenderedAnimation::new(30);

// Add pre-computed frames
let grid = BrailleGrid::new(10, 5).unwrap();
animation.add_frame(grid);

assert_eq!(animation.frame_count(), 1);
assert_eq!(animation.frame_rate(), 30);

Implementations

impl PrerenderedAnimation

pub fn new(frame_rate: u32) -> Self

Creates a new empty pre-rendered animation with the specified frame rate.

The frame rate is clamped to the valid range (1-240). Values outside this range are silently corrected to the nearest valid value.

Arguments

• frame_rate - Target frames per second (1-240, clamped if out of range)

Examples

use dotmax::animation::PrerenderedAnimation;

// Standard 30 FPS animation
let animation = PrerenderedAnimation::new(30);
assert_eq!(animation.frame_rate(), 30);
assert_eq!(animation.frame_count(), 0);

// Values are clamped to valid range
let animation = PrerenderedAnimation::new(0);
assert_eq!(animation.frame_rate(), 1);  // Clamped to minimum

let animation = PrerenderedAnimation::new(500);
assert_eq!(animation.frame_rate(), 240);  // Clamped to maximum

pub fn add_frame(&mut self, frame: BrailleGrid) -> &mut Self

Adds a frame to the animation.

Frames are stored by value (owned BrailleGrid). There is no validation on frame dimensions - mixed sizes are allowed for flexibility.

Arguments

• frame - The BrailleGrid to add to the animation

Returns

&mut Self for builder-style method chaining.

Examples

use dotmax::animation::PrerenderedAnimation;
use dotmax::BrailleGrid;

let mut animation = PrerenderedAnimation::new(30);

// Add frames with chaining
animation
    .add_frame(BrailleGrid::new(10, 5).unwrap())
    .add_frame(BrailleGrid::new(10, 5).unwrap())
    .add_frame(BrailleGrid::new(10, 5).unwrap());

assert_eq!(animation.frame_count(), 3);

pub fn frame_count(&self) -> usize

Returns the number of stored frames.

Examples

use dotmax::animation::PrerenderedAnimation;
use dotmax::BrailleGrid;

let animation = PrerenderedAnimation::new(30);
assert_eq!(animation.frame_count(), 0);

let mut animation = PrerenderedAnimation::new(30);
animation.add_frame(BrailleGrid::new(10, 5).unwrap());
assert_eq!(animation.frame_count(), 1);

pub const fn frame_rate(&self) -> u32

Returns the target frame rate (FPS).

Examples

use dotmax::animation::PrerenderedAnimation;

let animation = PrerenderedAnimation::new(60);
assert_eq!(animation.frame_rate(), 60);

pub fn play(&self, renderer: &mut TerminalRenderer) -> Result<(), DotmaxError>

Plays the animation once from start to finish.

Renders all frames at the specified frame rate using FrameTimer for consistent timing. Returns immediately if no frames are stored.

Arguments

• renderer - The TerminalRenderer to render frames to

Returns

• Ok(()) - Animation played successfully
• Err(DotmaxError) - Rendering failed

Errors

Returns DotmaxError::Terminal if rendering to the terminal fails.

Examples

use dotmax::animation::PrerenderedAnimation;
use dotmax::BrailleGrid;
use dotmax::TerminalRenderer;

let mut animation = PrerenderedAnimation::new(30);
// ... add frames ...

let mut renderer = TerminalRenderer::new()?;
animation.play(&mut renderer)?;

pub fn play_loop( &self, renderer: &mut TerminalRenderer, ) -> Result<(), DotmaxError>

Plays the animation in a continuous loop until Ctrl+C is pressed.

Loops seamlessly with no pause between repetitions. Stops gracefully when Ctrl+C is detected, returning Ok(()) rather than an error.

Arguments

• renderer - The TerminalRenderer to render frames to

Returns

• Ok(()) - Animation stopped (either Ctrl+C or empty)
• Err(DotmaxError) - Rendering failed

Errors

Returns DotmaxError::Terminal if rendering to the terminal fails.

Ctrl+C Handling

The loop checks for Ctrl+C before each frame using non-blocking event polling. When detected, the function returns Ok(()) gracefully - not an error.

Examples

use dotmax::animation::PrerenderedAnimation;
use dotmax::BrailleGrid;
use dotmax::TerminalRenderer;

let mut animation = PrerenderedAnimation::new(30);
// ... add frames ...

let mut renderer = TerminalRenderer::new()?;
println!("Press Ctrl+C to stop");
animation.play_loop(&mut renderer)?;  // Runs until Ctrl+C

pub fn save_to_file(&self, path: &Path) -> Result<(), DotmaxError>

Saves the animation to a file.

Uses a simple binary format (see module documentation for details). Creates parent directories if they don’t exist.

Arguments

• path - The file path to save to

Returns

• Ok(()) - Animation saved successfully
• Err(DotmaxError) - I/O error occurred

Errors

Returns DotmaxError::Terminal (wrapping io::Error) if:

• Directory creation fails
• File creation fails
• Write operations fail

File Format

See module-level documentation for the complete file format specification.

Examples

use dotmax::animation::PrerenderedAnimation;
use dotmax::BrailleGrid;
use std::path::Path;

let mut animation = PrerenderedAnimation::new(30);
animation.add_frame(BrailleGrid::new(80, 24).unwrap());

animation.save_to_file(Path::new("my_animation.dmax"))?;

pub fn load_from_file(path: &Path) -> Result<Self, DotmaxError>

Loads an animation from a file.

Validates the file format and returns appropriate errors for invalid files.

Arguments

• path - The file path to load from

Returns

• Ok(PrerenderedAnimation) - Animation loaded successfully
• Err(DotmaxError) - File not found, invalid format, or I/O error

Errors

Returns DotmaxError::Terminal (wrapping io::Error) if:

• File not found
• Permission denied
• Invalid magic bytes (not a DMAX file)
• Truncated or corrupted data

Examples

use dotmax::animation::PrerenderedAnimation;
use std::path::Path;

let animation = PrerenderedAnimation::load_from_file(Path::new("my_animation.dmax"))?;
println!("Loaded {} frames at {} FPS", animation.frame_count(), animation.frame_rate());

Trait Implementations

impl Debug for PrerenderedAnimation

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

Formats the value using the given formatter.