three-rs 0.3.0

A port of three.js core and its WebGPURenderer to Rust on wgpu, graded against three.js's own end-to-end pixel comparison.
Documentation
//! Port of `three.js/src/core/Timer.js`.

use crate::utils::time::now_ms;

/// `Timer` — three.js' successor to `Clock`, and the only one of the two any
/// graded example page uses (nine of the thirty-nine construct a
/// `new THREE.Timer()`; none construct a `Clock`).
///
/// Its point over `Clock` is that [`update`](Self::update) is the one place
/// the clock is read, so [`get_delta`](Self::get_delta) and
/// [`get_elapsed`](Self::get_elapsed) can be called any number of times in a
/// simulation step and answer the same thing.
///
/// # What is left out
///
/// `connect( document )` / `disconnect()` and their Page Visibility handling.
/// Five of the nine pages call `timer.connect( document )`; all it does is
/// register a `visibilitychange` listener that calls
/// [`reset`](Self::reset) when the tab comes back, so that a tab left in the
/// background does not produce one enormous delta. There is no document here —
/// the crate is host-agnostic and the browser shell drives frames from
/// `requestAnimationFrame`, which a hidden tab does not fire — so a host that
/// wants that behaviour calls [`reset`](Self::reset) itself. Nothing about
/// `update`/`getDelta`/`getElapsed` differs.
#[derive(Debug, Clone)]
pub struct Timer {
    previous_time: f64,
    current_time: f64,
    start_time: f64,
    delta: f64,
    elapsed: f64,
    timescale: f64,
}

impl Default for Timer {
    fn default() -> Self {
        Self::new()
    }
}

impl Timer {
    /// `new Timer()`. `_startTime = performance.now()`, so the first
    /// `update()` after construction has a delta of "however long init took",
    /// exactly as on the page.
    pub fn new() -> Self {
        Self {
            previous_time: 0.0,
            current_time: 0.0,
            start_time: now_ms(),
            delta: 0.0,
            elapsed: 0.0,
            timescale: 1.0,
        }
    }

    /// `getDelta()` — the last step's length, in seconds.
    pub fn get_delta(&self) -> f64 {
        self.delta / 1000.0
    }

    /// `getElapsed()` — the sum of every delta so far, in seconds.
    pub fn get_elapsed(&self) -> f64 {
        self.elapsed / 1000.0
    }

    /// `getTimescale()`.
    pub fn get_timescale(&self) -> f64 {
        self.timescale
    }

    /// `setTimescale( timescale )` — scales the delta `update()` computes.
    pub fn set_timescale(&mut self, timescale: f64) -> &mut Self {
        self.timescale = timescale;
        self
    }

    /// `reset()` — forget the gap since the last `update()`, so the next step
    /// is short rather than however long the timer was ignored for.
    pub fn reset(&mut self) -> &mut Self {
        self.current_time = now_ms() - self.start_time;
        self
    }

    /// `update()` with no `timestamp`: read the clock.
    pub fn update(&mut self) -> &mut Self {
        self.update_with(None)
    }

    /// `update( timestamp )` — the `requestAnimationFrame` argument, in
    /// milliseconds on the same origin as `performance.now()`.
    ///
    /// A host that wants a fixed simulation step passes
    /// `start + n * step` here; there is no separate fixed-delta mode in
    /// r186's `Timer`.
    pub fn update_with(&mut self, timestamp: Option<f64>) -> &mut Self {
        self.previous_time = self.current_time;
        self.current_time = timestamp.unwrap_or_else(now_ms) - self.start_time;

        self.delta = (self.current_time - self.previous_time) * self.timescale;
        // `_elapsed is the accumulation of all previous deltas`.
        self.elapsed += self.delta;

        self
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::testing::pin_time;

    #[test]
    fn a_pinned_clock_gives_a_zero_delta_forever() {
        pin_time(Some(0.0));
        let mut timer = Timer::new();
        for _ in 0..4 {
            timer.update();
            assert_eq!(timer.get_delta(), 0.0);
            assert_eq!(timer.get_elapsed(), 0.0);
        }
        pin_time(None);
    }

    #[test]
    fn deltas_accumulate_into_elapsed() {
        pin_time(Some(1000.0));
        let mut timer = Timer::new();

        pin_time(Some(1016.0));
        timer.update();
        assert!((timer.get_delta() - 0.016).abs() < 1e-12);
        assert!((timer.get_elapsed() - 0.016).abs() < 1e-12);

        pin_time(Some(1048.0));
        timer.update();
        assert!((timer.get_delta() - 0.032).abs() < 1e-12);
        assert!((timer.get_elapsed() - 0.048).abs() < 1e-12);

        pin_time(None);
    }

    #[test]
    fn timescale_scales_the_delta() {
        pin_time(Some(0.0));
        let mut timer = Timer::new();
        timer.set_timescale(0.5);

        pin_time(Some(100.0));
        timer.update();
        assert!((timer.get_delta() - 0.05).abs() < 1e-12);

        pin_time(None);
    }

    #[test]
    fn reset_drops_the_gap_since_the_last_update() {
        pin_time(Some(0.0));
        let mut timer = Timer::new();

        // A long pause the host does not want charged to the next step.
        pin_time(Some(10_000.0));
        timer.reset();
        pin_time(Some(10_016.0));
        timer.update();
        assert!((timer.get_delta() - 0.016).abs() < 1e-12);

        pin_time(None);
    }

    #[test]
    fn an_explicit_timestamp_replaces_the_clock() {
        pin_time(Some(0.0));
        let mut timer = Timer::new();
        timer.update_with(Some(500.0));
        assert!((timer.get_delta() - 0.5).abs() < 1e-12);
        pin_time(None);
    }
}