Struct FrameTimer 

pub struct FrameTimer { /* private fields */ }

Frame timing control for consistent animation speeds.

FrameTimer manages the timing of animation frames, ensuring animations run at a consistent frame rate regardless of system performance. It provides accurate FPS measurement and graceful frame dropping when the system falls behind.

Creating a Timer

use dotmax::animation::FrameTimer;

// Standard 60 FPS animation
let timer_60fps = FrameTimer::new(60);

// Slower 30 FPS for less CPU usage
let timer_30fps = FrameTimer::new(30);

// High refresh rate
let timer_120fps = FrameTimer::new(120);

FPS Validation

Target FPS is clamped to the valid range (1-240). Invalid values are silently corrected:

use dotmax::animation::FrameTimer;

let timer = FrameTimer::new(0);  // Clamped to 1 FPS
assert_eq!(timer.target_fps(), 1);

let timer = FrameTimer::new(500);  // Clamped to 240 FPS
assert_eq!(timer.target_fps(), 240);

Implementations

impl FrameTimer

pub fn new(target_fps: u32) -> Self

Creates a new frame timer targeting the specified FPS.

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

Arguments

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

Examples

use dotmax::animation::FrameTimer;

// Create a 60 FPS timer (16.67ms per frame)
let timer = FrameTimer::new(60);
assert_eq!(timer.target_fps(), 60);

// Frame duration is calculated automatically
let duration_ms = timer.target_frame_time().as_secs_f64() * 1000.0;
assert!((duration_ms - 16.67).abs() < 0.01);

use dotmax::animation::FrameTimer;

// Invalid values are clamped
let timer = FrameTimer::new(0);
assert_eq!(timer.target_fps(), 1);  // Clamped to minimum

pub fn wait_for_next_frame(&mut self)

Waits until the next frame should begin.

This method calculates the elapsed time since the last frame and sleeps for the remaining duration to maintain the target frame rate. If the system is behind schedule (frame took longer than target), no sleep occurs and the frame is considered “dropped”.

Frame Dropping

When a frame takes longer than the target duration:

• No sleep occurs (the frame is already late)
• A debug log is emitted via tracing
• The actual frame time is recorded (affects actual_fps())
• No “catch-up” is attempted

Examples

use dotmax::animation::FrameTimer;

let mut timer = FrameTimer::new(60);

loop {
    // Do rendering work...

    // Wait for next frame - blocks until frame time elapsed
    timer.wait_for_next_frame();
}

pub fn actual_fps(&self) -> f32

Returns the actual FPS based on recent frame times.

This calculates a rolling average of the frame rate over the last 60 frames (approximately 1 second at 60fps). The average provides a stable reading that smooths out individual frame variations.

Returns

• The rolling average FPS as an f32
• 0.0 if no frames have been recorded yet

Examples

use dotmax::animation::FrameTimer;

let timer = FrameTimer::new(60);

// No frames recorded yet
assert_eq!(timer.actual_fps(), 0.0);

use dotmax::animation::FrameTimer;

let mut timer = FrameTimer::new(60);

// After running some frames
for _ in 0..60 {
    timer.wait_for_next_frame();
}

// Should be close to 60 FPS
let fps = timer.actual_fps();
println!("Actual FPS: {:.1}", fps);

pub fn frame_time(&self) -> Duration

Returns the duration of the most recent frame.

This is useful for debugging and performance monitoring, showing exactly how long the last frame took to complete.

Returns

• The duration of the most recent frame
• Duration::ZERO if no frames have been completed

Examples

use dotmax::animation::FrameTimer;
use std::time::Duration;

let timer = FrameTimer::new(60);

// No frames recorded yet
assert_eq!(timer.frame_time(), Duration::ZERO);

use dotmax::animation::FrameTimer;

let mut timer = FrameTimer::new(60);
timer.wait_for_next_frame();

// Check the actual frame duration
let frame_ms = timer.frame_time().as_millis();
println!("Last frame: {}ms", frame_ms);

pub const fn target_fps(&self) -> u32

Returns the target FPS this timer was configured with.

Examples

use dotmax::animation::FrameTimer;

let timer = FrameTimer::new(60);
assert_eq!(timer.target_fps(), 60);

let timer = FrameTimer::new(30);
assert_eq!(timer.target_fps(), 30);

pub const fn target_frame_time(&self) -> Duration

Returns the target duration for each frame.

This is calculated as 1.0 / target_fps seconds. For example, at 60 FPS, the target frame time is approximately 16.67ms.

Examples

use dotmax::animation::FrameTimer;
use std::time::Duration;

let timer = FrameTimer::new(60);
let target_ms = timer.target_frame_time().as_secs_f64() * 1000.0;
assert!((target_ms - 16.67).abs() < 0.1);

let timer = FrameTimer::new(30);
let target_ms = timer.target_frame_time().as_secs_f64() * 1000.0;
assert!((target_ms - 33.33).abs() < 0.1);

pub fn reset(&mut self)

Resets the timer state, clearing frame history.

This is useful when:

• Pausing and resuming an animation
• Switching between different animation phases
• Recovering from a long pause

After reset, actual_fps() will return 0.0 and frame_time() will return Duration::ZERO until new frames are recorded.

Examples

use dotmax::animation::FrameTimer;

let mut timer = FrameTimer::new(60);

// Run some frames
for _ in 0..60 {
    timer.wait_for_next_frame();
}
assert!(timer.actual_fps() > 0.0);

// Reset clears history
timer.reset();
assert_eq!(timer.actual_fps(), 0.0);

Trait Implementations

impl Debug for FrameTimer

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

Formats the value using the given formatter.

impl Default for FrameTimer

fn default() -> Self

Creates a frame timer with the default target of 60 FPS.

Examples

use dotmax::animation::FrameTimer;

let timer = FrameTimer::default();
assert_eq!(timer.target_fps(), 60);