Struct AnimationLoop 

pub struct AnimationLoop<F>
where
    F: FnMut(u64, &mut BrailleGrid) -> Result<bool, DotmaxError>,
{ /* private fields */ }

High-level animation loop abstraction.

AnimationLoop provides a simple builder-pattern API for creating terminal animations. It handles all the complexity of double-buffering, frame timing, and terminal management automatically.

Type Parameter

• F: The frame callback type, which must implement FnMut(u64, &mut BrailleGrid) -> Result<bool, DotmaxError>

Examples

Basic animation with default 60 FPS:

use dotmax::animation::AnimationLoop;

let mut frame_count = 0;
AnimationLoop::new(80, 24)
    .on_frame(|frame, buffer| {
        buffer.set_dot((frame as usize * 2) % 160, 48)?;
        Ok(frame < 100)  // Run for 100 frames
    })
    .run()?;

Animation with custom FPS:

use dotmax::animation::AnimationLoop;

AnimationLoop::new(80, 24)
    .fps(30)  // 30 FPS for less CPU usage
    .on_frame(|frame, buffer| {
        // Draw something each frame
        Ok(true)
    })
    .run()?;

Implementations

impl AnimationLoop<fn(u64, &mut BrailleGrid) -> Result<bool, DotmaxError>>

pub const fn new(width: usize, height: usize) -> AnimationLoopBuilder

Creates a new animation loop builder with the specified dimensions.

The dimensions specify the size of the braille grid in terminal cells (characters wide × lines tall). Each cell contains an 8-dot braille character (2×4 dots), so a 80×24 grid provides 160×96 dot resolution.

Arguments

• width - Width in terminal cells (characters)
• height - Height in terminal cells (lines)

Returns

An AnimationLoopBuilder with default settings (60 FPS).

Examples

use dotmax::animation::AnimationLoop;

// Standard terminal size (80×24)
let builder = AnimationLoop::new(80, 24);

// Larger buffer for detailed graphics
let large = AnimationLoop::new(120, 40);

impl<F> AnimationLoop<F>

where F: FnMut(u64, &mut BrailleGrid) -> Result<bool, DotmaxError>,

pub fn run(&mut self) -> Result<(), DotmaxError>

Runs the animation loop until stopped.

This method blocks until:

• The callback returns Ok(false)
• The callback returns Err(...)
• Ctrl+C is pressed

The method handles all terminal setup (raw mode, alternate screen, cursor hiding) and cleanup automatically, even on error.

Returns

• Ok(()) on normal exit (callback returned false or Ctrl+C)
• Err(...) if the callback returns an error or terminal I/O fails

Errors

Returns DotmaxError::Terminal if:

• Terminal initialization fails (raw mode, alternate screen)
• Rendering to terminal fails during animation
• Terminal cleanup fails on exit

Returns the error from the callback if it returns Err(...).

Terminal State

On entry:

• Enables raw mode for unbuffered input
• Enters alternate screen to preserve original content
• Hides cursor for clean animation

On exit (any path):

• Shows cursor
• Leaves alternate screen
• Disables raw mode

Examples

use dotmax::animation::AnimationLoop;

AnimationLoop::new(80, 24)
    .fps(60)
    .on_frame(|frame, buffer| {
        buffer.set_dot(frame as usize % 160, 48)?;
        Ok(frame < 100)  // Stop after 100 frames
    })
    .run()?;

pub const fn width(&self) -> usize

Returns the animation width in terminal cells.

Examples

use dotmax::animation::AnimationLoop;

let anim = AnimationLoop::new(80, 24)
    .on_frame(|_, _| Ok(false));
assert_eq!(anim.width(), 80);

pub const fn height(&self) -> usize

Returns the animation height in terminal cells.

Examples

use dotmax::animation::AnimationLoop;

let anim = AnimationLoop::new(80, 24)
    .on_frame(|_, _| Ok(false));
assert_eq!(anim.height(), 24);

pub const fn target_fps(&self) -> u32

Returns the target FPS for this animation.

This is the FPS set via the builder, not the actual achieved FPS (which depends on system performance).

Examples

use dotmax::animation::AnimationLoop;

// Default FPS is 60
let anim = AnimationLoop::new(80, 24)
    .on_frame(|_, _| Ok(false));
assert_eq!(anim.target_fps(), 60);

// Custom FPS
let anim = AnimationLoop::new(80, 24)
    .fps(30)
    .on_frame(|_, _| Ok(false));
assert_eq!(anim.target_fps(), 30);