GitCorner

Code

ossartcraftlightcraft🌐
5a24289898fd
//! How long the loupe takes to show each photo it is stepped to, measured on the frames it draws.
//!
//! Culling is stepping through photos, so the number that matters is the time from the step (the
//! first frame that draws the new photo) to the first frame that shows something of it, to the
//! first frame with a full-size picture (the camera's embedded JPEG or a cached render) and to the
//! first frame with LightCraft's own render. `ui.inspect` → `perf.loupeSteps` reports the latest
//! steps; `perf-scratch`-style drivers turn them into medians and p95 without the control
//! channel's own round trip in the numbers.

use std::collections::VecDeque;

use lightcraft_catalog::PhotoId;
use serde_json::{Value, json};

/// Steps kept for `ui.inspect`.
const KEEP: usize = 256;

/// A photo left sooner than this (s) after it was stepped to was skipped past: the user is
/// holding an arrow key or tapping through.
pub const FAST_STEP_SECS: f64 = 0.25;
/// While stepping fast, how long a photo has to stay before its render is started (s). Until then
/// the loupe shows its camera JPEG or thumbnail, and the workers make the next ones' instead of
/// starting a full raw develop that the next step throws away.
pub const SETTLE_SECS: f64 = 0.12;

/// One photo's way onto the screen (times in ms since the frame it was stepped to).
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct StepTiming {
    pub photo: PhotoId,
    /// First frame that drew anything of the photo (often the grid thumbnail, magnified).
    pub any_ms: Option<f64>,
    /// What that was.
    pub any_source: &'static str,
    /// First frame with a full-size stand-in or better: the camera's JPEG, a cached render, the render.
    pub full_ms: Option<f64>,
    pub full_source: &'static str,
    /// First frame with LightCraft's own render of the photo (`render` or `cached`).
    pub sharp_ms: Option<f64>,
    /// How long the photo stayed in the loupe (ms): a step taken before `sharp_ms` was skipped past.
    pub dwell_ms: f64,
}

impl StepTiming {
    fn to_json(self) -> Value {
        json!({
            "photo": self.photo.0,
            "anyMs": self.any_ms,
            "anySource": self.any_source,
            "fullMs": self.full_ms,
            "fullSource": self.full_source,
            "sharpMs": self.sharp_ms,
            "dwellMs": self.dwell_ms,
        })
    }
}

/// The loupe's step timings.
#[derive(Debug, Default)]
pub struct LoupeTiming {
    current: Option<(f64, StepTiming)>,
    done: VecDeque<StepTiming>,
    /// Steps finished since the app started (never lowered when old ones leave `done`): a driver's
    /// cursor for the steps made after it looked.
    total: u64,
    /// Whether the loupe drew a photo in the frame being drawn ([`LoupeTiming::end_frame`]).
    drawn: bool,
    /// How long the photo before the current one stayed (ms), when the loupe stepped to it from
    /// that photo; `None` when the loupe opened on it (from the grid, or coming back to the loupe).
    stepped_from: Option<f64>,
}

/// Sources that show the photo at full size: the camera's JPEG, a cached or a fresh render.
fn full_size(source: &str) -> bool {
    matches!(source, "embedded" | "cached" | "render" | "preview")
}

impl LoupeTiming {
    /// The loupe drew `photo` from `source` (what [`crate::panels::detail`] reports in
    /// `loupe_shown`) in the frame that started at `now` (s).
    pub fn observe(&mut self, photo: PhotoId, source: &'static str, now: f64) {
        self.drawn = true;
        if self.current.as_ref().is_none_or(|(_, t)| t.photo != photo) {
            let stepped = self.current.is_some();
            self.finish(now);
            self.stepped_from = if stepped { self.done.back().map(|t| t.dwell_ms) } else { None };
            let t = StepTiming { photo, any_ms: None, any_source: "none", full_ms: None, full_source: "none", sharp_ms: None, dwell_ms: 0.0 };
            self.current = Some((now, t));
        }
        let Some((since, t)) = self.current.as_mut() else { return };
        let ms = ((now - *since) * 1000.0).max(0.0);
        if !ms.is_finite() {
            return;
        }
        t.dwell_ms = ms;
        if source != "none" && t.any_ms.is_none() {
            t.any_ms = Some(ms);
            t.any_source = source;
        }
        if full_size(source) && t.full_ms.is_none() {
            t.full_ms = Some(ms);
            t.full_source = source;
        }
        if matches!(source, "render" | "cached") && t.sharp_ms.is_none() {
            t.sharp_ms = Some(ms);
        }
    }

    /// Whether the user is stepping fast and `photo` (being drawn in the frame at `now`) has not
    /// stayed [`SETTLE_SECS`] yet: the photo before it was left within [`FAST_STEP_SECS`].
    pub fn settling(&self, photo: PhotoId, now: f64) -> bool {
        let (since, prev_dwell) = match &self.current {
            // the first frame of a step: `observe` has not seen this photo yet
            Some((since, t)) if t.photo != photo => (now, (now - since) * 1000.0),
            // (a photo the loupe opened on, not stepped to, never settles: the step that ended by
            // leaving the loupe is not its predecessor)
            Some((since, _)) => (*since, self.stepped_from.unwrap_or(f64::INFINITY)),
            None => return false,
        };
        prev_dwell.is_finite() && prev_dwell < FAST_STEP_SECS * 1000.0 && now - since < SETTLE_SECS
    }

    /// The loupe is not showing a photo any more (the grid is up).
    pub fn left(&mut self, now: f64) {
        self.finish(now);
    }

    /// A frame (started at `now`) was drawn: when the loupe drew no photo in it (the grid, Compare, Survey,
    /// Reference, People or the slideshow is up), the photo it showed was left then, so time away from the
    /// loupe never counts as time on that photo.
    pub fn end_frame(&mut self, now: f64) {
        if !std::mem::take(&mut self.drawn) {
            self.left(now);
        }
    }

    fn finish(&mut self, now: f64) {
        if let Some((since, mut t)) = self.current.take() {
            let dwell = (now - since) * 1000.0;
            if dwell.is_finite() {
                t.dwell_ms = dwell.max(t.dwell_ms);
            }
            if self.done.len() >= KEEP {
                self.done.pop_front();
            }
            self.done.push_back(t);
            self.total = self.total.saturating_add(1);
        }
    }

    /// The finished steps, oldest first (the latest [`KEEP`]), how many have finished in all, and the photo on screen now.
    pub fn to_json(&self) -> Value {
        json!({
            "steps": self.done.iter().map(|t| t.to_json()).collect::<Vec<_>>(),
            "total": self.total,
            "current": self.current.as_ref().map(|(_, t)| t.to_json()),
        })
    }

    #[cfg(test)]
    fn steps(&self) -> Vec<StepTiming> {
        self.done.iter().copied().collect()
    }
}

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

    #[test]
    fn a_step_records_when_each_kind_of_picture_first_showed() {
        let mut l = LoupeTiming::default();
        l.observe(PhotoId(1), "none", 10.0);
        l.observe(PhotoId(1), "thumb", 10.016);
        l.observe(PhotoId(1), "embedded", 10.040);
        l.observe(PhotoId(1), "embedded", 10.056);
        l.observe(PhotoId(1), "render", 11.0);
        l.observe(PhotoId(2), "thumb", 12.0);
        let s = l.steps();
        assert_eq!(s.len(), 1);
        let t = s[0];
        assert_eq!(t.photo, PhotoId(1));
        assert_eq!((t.any_source, t.full_source), ("thumb", "embedded"));
        assert!((t.any_ms.unwrap() - 16.0).abs() < 0.01);
        assert!((t.full_ms.unwrap() - 40.0).abs() < 0.01);
        assert!((t.sharp_ms.unwrap() - 1000.0).abs() < 0.01);
        assert!((t.dwell_ms - 2000.0).abs() < 0.01);
        assert_eq!(l.to_json()["current"]["photo"], 2);
    }

    #[test]
    fn stepping_fast_holds_the_render_back_until_the_photo_stays() {
        let mut l = LoupeTiming::default();
        // the first photo opened: no step before it
        assert!(!l.settling(PhotoId(1), 0.0));
        l.observe(PhotoId(1), "embedded", 0.0);
        // a deliberate step (the photo before stayed 2 s): render at once
        assert!(!l.settling(PhotoId(2), 2.0));
        l.observe(PhotoId(2), "embedded", 2.0);
        // held arrow: the photo before stayed 33 ms
        assert!(l.settling(PhotoId(3), 2.033));
        l.observe(PhotoId(3), "thumb", 2.033);
        assert!(l.settling(PhotoId(3), 2.1));
        // …until this one has stayed long enough
        assert!(!l.settling(PhotoId(3), 2.033 + SETTLE_SECS + 0.001));
    }

    /// Leaving the loupe soon after a step and coming back on another photo is not a fast step
    /// (CodeRabbit on #3077): the photo the loupe opens on renders at once, on every frame.
    #[test]
    fn coming_back_to_the_loupe_on_another_photo_is_not_a_fast_step() {
        let mut l = LoupeTiming::default();
        l.observe(PhotoId(1), "embedded", 0.0);
        l.end_frame(0.0);
        // the grid is up after 100 ms on the photo
        l.end_frame(0.1);
        assert!(!l.settling(PhotoId(2), 0.2), "the first frame back");
        l.observe(PhotoId(2), "thumb", 0.2);
        l.end_frame(0.2);
        assert!(!l.settling(PhotoId(2), 0.25), "nor the frames after it");
        // a fast step from there still settles
        l.observe(PhotoId(2), "embedded", 0.25);
        assert!(l.settling(PhotoId(3), 0.3));
        l.observe(PhotoId(3), "thumb", 0.3);
        assert!(l.settling(PhotoId(3), 0.35));
    }

    /// A frame without the loupe finishes the photo it showed: coming back to it later starts a new step, and
    /// neither counts the time away (CodeRabbit on #3055).
    #[test]
    fn leaving_the_loupe_finishes_its_photo() {
        let mut l = LoupeTiming::default();
        l.observe(PhotoId(1), "embedded", 10.0);
        l.end_frame(10.0);
        l.observe(PhotoId(1), "embedded", 10.5);
        l.end_frame(10.5);
        assert!(l.steps().is_empty(), "frames that draw the loupe keep the step open");
        // the grid is up from 11 s to 60 s
        l.end_frame(11.0);
        l.end_frame(60.0);
        let s = l.steps();
        assert_eq!(s.len(), 1);
        assert!((s[0].dwell_ms - 1000.0).abs() < 0.01, "dwell ends when the loupe went: {}", s[0].dwell_ms);
        // back in the loupe on the same photo: a new step, timed from its return
        l.observe(PhotoId(1), "render", 60.0);
        l.observe(PhotoId(1), "render", 60.2);
        l.end_frame(60.2);
        assert_eq!(l.steps().len(), 1);
        assert_eq!(l.to_json()["current"]["sharpMs"], 0.0);
        assert!((l.to_json()["current"]["dwellMs"].as_f64().unwrap() - 200.0).abs() < 0.01);
    }

    #[test]
    fn a_photo_stepped_past_has_no_sharp_time_and_the_list_is_bounded() {
        let mut l = LoupeTiming::default();
        for i in 0..(KEEP as u64 + 10) {
            l.observe(PhotoId(i), "thumb", i as f64 * 0.033);
        }
        l.left(1000.0);
        let s = l.steps();
        assert_eq!(s.len(), KEEP);
        // the count of steps goes on past the kept list: a driver's cursor (CodeRabbit on #3077)
        assert_eq!(l.to_json()["total"], KEEP as u64 + 10);
        assert!(s.iter().all(|t| t.sharp_ms.is_none() && t.full_ms.is_none()));
        // a non-finite clock never poisons the record
        l.observe(PhotoId(9999), "render", f64::NAN);
        l.observe(PhotoId(9999), "render", f64::INFINITY);
        assert!(l.to_json().is_object());
    }
}