codecraft 0.1.1

//! A frame profiler: what the last few hundred frames were spent on.
//!
//! Ported from `radcas_profiler`, which is a Rust rewrite of Alexander
//! Sannikov's LegitProfiler (<https://github.com/Raikiri/LegitProfiler>, MIT).
//! The model is the original's: each frame contributes a list of named spans,
//! a ring buffer keeps the recent history, and the chart draws one stacked
//! column per frame beside a legend ordered by how expensive each span has
//! been across the window.
//!
//! Two things changed on the way in. It draws with this project's UI
//! primitives rather than radcas's, so a span is a [`QuadInstance`] and a
//! label goes through [`font`]; and every span says whether it is [`Cpu`] or
//! [`Gpu`] work, which the chart then keeps in **separate bands with separate
//! scales**. A shared scale is unreadable -- the two routinely differ by an
//! order of magnitude -- and a shared band is worse, because the one question
//! you bring to a profiler is *which side is the frame waiting on*.
//!
//! [`Cpu`]: Lane::Cpu
//! [`Gpu`]: Lane::Gpu
use std::time::Instant;

use crate::ecs::Resource;
use crate::ui::atlas::Atlas;
use crate::ui::color::{Alpha, Color, linear_rgba};
use crate::ui::font::{self, Face};
use crate::ui::renderer2d::{NO_ICON, QuadInstance};

/// Which side of the machine a span was spent on.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
pub enum Lane {
    #[default]
    Cpu,
    Gpu,
}

impl Lane {
    pub const ALL: [Lane; 2] = [Lane::Cpu, Lane::Gpu];

    pub fn label(self) -> &'static str {
        match self {
            Lane::Cpu => "CPU",
            Lane::Gpu => "GPU",
        }
    }

    /// The family a lane's spans are coloured from.
    ///
    /// Warm for the processor, cool for the card. Two families rather than one
    /// palette, so a glance at the chart says which side is busy before a
    /// single label has been read -- which is the whole point of splitting
    /// them.
    pub fn palette(self) -> &'static [Color] {
        match self {
            Lane::Cpu => &CPU_COLORS,
            Lane::Gpu => &GPU_COLORS,
        }
    }

    /// The colour for the `index`th distinct span in this lane.
    pub fn color(self, index: usize) -> Color {
        let palette = self.palette();
        palette[index % palette.len()]
    }
}

/// Warm: oranges through to red.
const CPU_COLORS: [Color; 5] = [
    Color::srgb(0.90, 0.55, 0.20),
    Color::srgb(0.85, 0.35, 0.25),
    Color::srgb(0.95, 0.72, 0.30),
    Color::srgb(0.75, 0.28, 0.35),
    Color::srgb(0.98, 0.85, 0.45),
];

/// Cool: teals through to violet.
const GPU_COLORS: [Color; 5] = [
    Color::srgb(0.25, 0.65, 0.85),
    Color::srgb(0.30, 0.80, 0.70),
    Color::srgb(0.45, 0.50, 0.90),
    Color::srgb(0.20, 0.45, 0.70),
    Color::srgb(0.55, 0.75, 0.95),
];

/// One measured span within a frame. Times are milliseconds from frame start.
#[derive(Clone, Debug, PartialEq)]
pub struct Span {
    pub name: String,
    pub lane: Lane,
    pub start: f64,
    pub end: f64,
}

impl Span {
    pub fn length(&self) -> f64 {
        (self.end - self.start).max(0.0)
    }
}

/// What one frame cost, in one lane.
#[derive(Clone, Default, Debug)]
struct Frame {
    spans: Vec<Span>,
    total: f64,
}

/// Aggregate for one span name across the retained window.
#[derive(Clone, Debug)]
struct Stat {
    name: String,
    worst: f64,
    /// Where it sits in the legend, kept stable while it is present so entries
    /// do not jump about between frames.
    slot: usize,
}

/// The rolling history of one lane.
struct Band {
    lane: Lane,
    frames: Vec<Frame>,
    /// Ring cursor: the next slot to write.
    cursor: usize,
    stats: Vec<Stat>,
    /// Full-scale frame time for the vertical axis, in milliseconds.
    scale: f64,
}

impl Band {
    fn new(lane: Lane, frames: usize) -> Self {
        Self {
            lane,
            frames: vec![Frame::default(); frames.max(1)],
            cursor: 0,
            stats: Vec::new(),
            scale: FRAME_BUDGET,
        }
    }

    fn push(&mut self, spans: Vec<Span>) {
        let total = spans.iter().map(|span| span.end).fold(0.0f64, f64::max);
        let at = self.cursor;
        self.frames[at] = Frame { spans, total };
        self.cursor = (self.cursor + 1) % self.frames.len();

        // Rescaled to the window's peak, with headroom so the tallest column
        // does not sit flush against the top. Never below the frame budget,
        // so a quiet window still shows where sixty frames a second is and a
        // spike is visibly a spike rather than a full-height bar.
        let peak = self.frames.iter().map(|frame| frame.total).fold(0.0, f64::max);
        self.scale = (peak * 1.15).max(FRAME_BUDGET);

        self.rebuild_stats();
    }

    fn current(&self) -> &Frame {
        &self.frames[(self.cursor + self.frames.len() - 1) % self.frames.len()]
    }

    fn total(&self) -> f64 {
        self.current().total
    }

    /// Per-name worst over the window, most expensive first.
    ///
    /// Ordered by the worst rather than the latest, which keeps the legend
    /// steady when a span's cost moves about frame to frame -- and a legend
    /// that reorders every frame is one nobody can read.
    fn rebuild_stats(&mut self) {
        let mut stats: Vec<Stat> = Vec::new();
        for frame in &self.frames {
            for span in &frame.spans {
                match stats.iter_mut().find(|stat| stat.name == span.name) {
                    Some(stat) => stat.worst = stat.worst.max(span.length()),
                    None => stats.push(Stat {
                        name: span.name.clone(),
                        worst: span.length(),
                        slot: 0,
                    }),
                }
            }
        }
        stats.sort_by(|a, b| b.worst.total_cmp(&a.worst));
        for (index, stat) in stats.iter_mut().enumerate() {
            stat.slot = index;
        }
        self.stats = stats;
    }

    fn slot(&self, name: &str) -> usize {
        self.stats
            .iter()
            .find(|stat| stat.name == name)
            .map(|stat| stat.slot)
            .unwrap_or(0)
    }

    /// The colour a span is drawn in: its place in the legend, in its own
    /// lane's family.
    fn color(&self, name: &str) -> Color {
        self.lane.color(self.slot(name))
    }
}

/// What sixty frames a second allows, in milliseconds. The line the chart
/// draws across itself, and the floor the axis never scales below.
const FRAME_BUDGET: f64 = 1000.0 / 60.0;

/// How many frames of history to keep.
const HISTORY: usize = 240;

/// A span being timed, which records itself when it is let go.
///
/// Held rather than called twice, so a span cannot be opened and never closed
/// -- which in a profiler shows up as a missing bar rather than as an error.
pub struct Timing<'a> {
    profiler: &'a mut Profiler,
    name: &'static str,
    lane: Lane,
    start: Instant,
}

impl Drop for Timing<'_> {
    fn drop(&mut self) {
        let started = self.profiler.frame_start;
        let from = self.start.duration_since(started).as_secs_f64() * 1000.0;
        let to = self.start.elapsed().as_secs_f64() * 1000.0 + from;
        self.profiler.record(Span {
            name: self.name.to_string(),
            lane: self.lane,
            start: from,
            end: to,
        });
    }
}

/// The profiler: what this frame has cost so far, and the window behind it.
#[derive(Resource)]
pub struct Profiler {
    /// Whether it is running. Off by default: timing costs a little, and a
    /// profiler nobody asked for is a panel over the game.
    pub on: bool,
    bands: Vec<Band>,
    /// This frame's spans, until [`end_frame`](Self::end_frame) files them.
    pending: Vec<Span>,
    frame_start: Instant,
}

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

impl Profiler {
    pub fn new() -> Self {
        Self {
            on: false,
            bands: Lane::ALL
                .into_iter()
                .map(|lane| Band::new(lane, HISTORY))
                .collect(),
            pending: Vec::new(),
            frame_start: Instant::now(),
        }
    }

    /// Starts a frame. Everything timed after this is measured from here.
    pub fn begin_frame(&mut self) {
        self.frame_start = Instant::now();
        self.pending.clear();
    }

    /// Files this frame's spans into the history.
    pub fn end_frame(&mut self) {
        if !self.on {
            self.pending.clear();
            return;
        }
        let spans = std::mem::take(&mut self.pending);
        for band in &mut self.bands {
            let lane = band.lane;
            band.push(
                spans
                    .iter()
                    .filter(|span| span.lane == lane)
                    .cloned()
                    .collect(),
            );
        }
    }

    /// How long after this frame started `at` was, in milliseconds.
    ///
    /// For work timed with a plain `Instant` rather than with a held
    /// [`Timing`] -- which most of the frame is, because the guard borrows
    /// the profiler and the frame needs the app.
    pub fn since_frame_start(&self, at: Instant) -> f64 {
        at.saturating_duration_since(self.frame_start).as_secs_f64() * 1000.0
    }

    /// Times a stretch of work on one side of the machine.
    ///
    /// ```no_run
    /// # use codecraft::ui::components::profiler::{Lane, Profiler};
    /// # fn demo(profiler: &mut Profiler) {
    /// let _timing = profiler.time("physics", Lane::Cpu);
    /// // ... the work ...
    /// # }
    /// ```
    pub fn time(&mut self, name: &'static str, lane: Lane) -> Timing<'_> {
        let start = Instant::now();
        Timing {
            profiler: self,
            name,
            lane,
            start,
        }
    }

    /// Files a span measured somewhere else -- the GPU, most of all, whose
    /// timings arrive from a query rather than from a clock this thread can
    /// read.
    pub fn record(&mut self, span: Span) {
        if self.on {
            self.pending.push(span);
        }
    }

    /// What each lane cost on the last filed frame.
    pub fn totals(&self) -> Vec<(Lane, f64)> {
        self.bands
            .iter()
            .map(|band| (band.lane, band.total()))
            .collect()
    }

    fn band(&self, lane: Lane) -> &Band {
        self.bands
            .iter()
            .find(|band| band.lane == lane)
            .unwrap_or(&self.bands[0])
    }
}

/// Where the panel sits and how big it is.
const MARGIN: f32 = 16.0;
const WIDTH: f32 = 420.0;
const LEGEND: f32 = 210.0;
/// How tall one lane's chart is, and the gap between the two.
const BAND_HEIGHT: f32 = 88.0;
const BAND_GAP: f32 = 22.0;
const PADDING: f32 = 8.0;

/// A column and the gap after it.
const COLUMN: f32 = 2.0;
const COLUMN_GAP: f32 = 0.0;

/// A legend row, and the swatch on it.
const ROW: f32 = 13.0;
const SWATCH: f32 = 8.0;
const LABEL_SIZE: f32 = 1.5;

/// Draws the profiler into `quads`, top-right of a `width` by `height` frame.
///
/// One band per lane, stacked, each with its own axis: see the module note for
/// why they are not one chart.
pub fn draw(
    profiler: &Profiler,
    quads: &mut Vec<QuadInstance>,
    atlas: &mut Atlas,
    face: &Face,
    width: f32,
    _height: f32,
) {
    if !profiler.on {
        return;
    }

    let panel_width = WIDTH + LEGEND + PADDING * 2.0;
    let panel_height =
        (BAND_HEIGHT + BAND_GAP) * Lane::ALL.len() as f32 - BAND_GAP + PADDING * 2.0;
    let x = width - panel_width - MARGIN;
    let y = MARGIN;

    quads.push(flat(
        x,
        y,
        panel_width,
        panel_height,
        Color::srgba(0.04, 0.05, 0.08, 0.88),
    ));

    for (index, lane) in Lane::ALL.into_iter().enumerate() {
        let top = y + PADDING + index as f32 * (BAND_HEIGHT + BAND_GAP);
        draw_band(
            profiler.band(lane),
            quads,
            atlas,
            face,
            x + PADDING,
            top,
            WIDTH,
            BAND_HEIGHT,
        );
    }
}

/// One lane: its name and total, the columns, the budget line, and the legend.
fn draw_band(
    band: &Band,
    quads: &mut Vec<QuadInstance>,
    atlas: &mut Atlas,
    face: &Face,
    x: f32,
    y: f32,
    width: f32,
    height: f32,
) {
    // The heading says which side this is, in that side's own colour, so the
    // two bands are told apart without reading the word.
    font::push_text(
        quads,
        atlas,
        face,
        &format!("{} {:.2} MS", band.lane.label(), band.total()),
        x,
        y - font::text_height(LABEL_SIZE) - 3.0,
        LABEL_SIZE,
        band.lane.color(0),
    );

    quads.push(flat(x, y, width, height, Color::srgba(0.0, 0.0, 0.0, 0.35)));

    // Where sixty frames a second sits on this axis. Off the top once the
    // window has been slower than that throughout, which is itself the answer
    // to a question somebody is asking.
    let budget = 1.0 - (FRAME_BUDGET / band.scale).clamp(0.0, 1.0) as f32;
    quads.push(flat(
        x,
        y + height * budget,
        width,
        1.0,
        Color::srgba(0.55, 0.58, 0.66, 0.55),
    ));

    let stride = COLUMN + COLUMN_GAP;
    let columns = ((width / stride).floor().max(1.0) as usize).min(band.frames.len());
    for column in 0..columns {
        // Column 0 is the oldest drawn, so walk back from the newest: the
        // frame that just happened is the one at the right-hand edge.
        let age = columns - 1 - column;
        let at = (band.cursor + band.frames.len() - 1 - age) % band.frames.len();
        let frame = &band.frames[at];

        let cx = x + column as f32 * stride;
        for span in &frame.spans {
            let from = (span.start / band.scale).clamp(0.0, 1.0) as f32;
            let to = (span.end / band.scale).clamp(0.0, 1.0) as f32;
            let top = y + height * (1.0 - to);
            let bottom = y + height * (1.0 - from);
            if bottom - top < 0.5 {
                continue;
            }
            quads.push(flat(
                cx,
                top,
                COLUMN,
                bottom - top,
                band.color(&span.name),
            ));
        }
    }

    // The legend, one row per span in the newest frame, at its stable slot.
    let legend_x = x + width + 18.0;
    let rows = (height / ROW).floor().max(1.0) as usize;
    let newest = x + columns.saturating_sub(1) as f32 * stride + COLUMN;

    for span in &band.current().spans {
        let slot = band.slot(&span.name);
        if slot >= rows {
            continue;
        }
        let row_y = y + slot as f32 * ROW;
        let color = band.color(&span.name);

        // An elbow back to this span's band in the newest column, so a colour
        // can be matched to a bar at a glance. Two straight runs rather than
        // the original's diagonal: the UI draws axis-aligned quads, and an
        // elbow is honest about that instead of pretending to be a line.
        let middle = ((span.start + span.end) * 0.5 / band.scale).clamp(0.0, 1.0) as f32;
        let from_y = y + height * (1.0 - middle);
        let to_y = row_y + SWATCH * 0.5;
        let elbow = newest + (legend_x - newest) * 0.5;
        let faint = color.with_alpha(0.5);
        quads.push(flat(newest, from_y, elbow - newest, 1.0, faint));
        quads.push(flat(
            elbow,
            from_y.min(to_y),
            1.0,
            (to_y - from_y).abs().max(1.0),
            faint,
        ));
        quads.push(flat(elbow, to_y, legend_x - elbow, 1.0, faint));

        quads.push(flat(legend_x, row_y + 1.0, SWATCH, SWATCH, color));
        font::push_text(
            quads,
            atlas,
            face,
            &format!("{:.2} {}", span.length(), span.name),
            legend_x + SWATCH + 5.0,
            row_y,
            LABEL_SIZE,
            color,
        );
    }
}

/// A flat coloured rectangle: no atlas, no sampling.
fn flat(x: f32, y: f32, width: f32, height: f32, color: Color) -> QuadInstance {
    QuadInstance {
        pos: [x, y],
        size: [width.max(0.0), height.max(0.0)],
        color: linear_rgba(color),
        uv: NO_ICON,
    }
}

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

    fn span(name: &str, lane: Lane, start: f64, end: f64) -> Span {
        Span {
            name: name.to_string(),
            lane,
            start,
            end,
        }
    }

    fn running() -> Profiler {
        let mut profiler = Profiler::new();
        profiler.on = true;
        profiler
    }

    /// Nothing is recorded until it is switched on: a profiler that costs
    /// something when nobody is looking at it is a profiler that changes what
    /// it is measuring.
    #[test]
    fn a_profiler_that_is_off_records_nothing() {
        let mut profiler = Profiler::new();
        profiler.begin_frame();
        profiler.record(span("draw", Lane::Cpu, 0.0, 4.0));
        profiler.end_frame();

        assert_eq!(profiler.totals(), vec![(Lane::Cpu, 0.0), (Lane::Gpu, 0.0)]);
    }

    #[test]
    fn a_frame_is_filed_when_it_ends() {
        let mut profiler = running();
        profiler.begin_frame();
        profiler.record(span("update", Lane::Cpu, 0.0, 3.0));
        profiler.record(span("draw", Lane::Gpu, 0.0, 7.0));
        profiler.end_frame();

        assert_eq!(profiler.totals(), vec![(Lane::Cpu, 3.0), (Lane::Gpu, 7.0)]);
    }

    /// The whole reason for two bands: the sides are kept apart, and a slow
    /// GPU frame does not flatten the CPU chart.
    #[test]
    fn the_lanes_are_kept_apart_and_scaled_apart() {
        let mut profiler = running();
        profiler.begin_frame();
        profiler.record(span("update", Lane::Cpu, 0.0, 1.0));
        profiler.record(span("draw", Lane::Gpu, 0.0, 90.0));
        profiler.end_frame();

        let cpu = profiler.band(Lane::Cpu);
        let gpu = profiler.band(Lane::Gpu);
        assert_eq!(cpu.current().spans.len(), 1, "one span each");
        assert_eq!(gpu.current().spans.len(), 1);
        assert!(
            gpu.scale > cpu.scale * 4.0,
            "a ninety millisecond GPU frame must not set the CPU axis: \
             cpu {} against gpu {}",
            cpu.scale,
            gpu.scale,
        );
    }

    /// And they are coloured apart, which is what says which is which before
    /// anything has been read.
    #[test]
    fn the_lanes_are_coloured_apart() {
        for slot in 0..8 {
            assert_ne!(
                Lane::Cpu.color(slot),
                Lane::Gpu.color(slot),
                "slot {slot} is the same colour on both sides",
            );
        }
        for cpu in CPU_COLORS {
            assert!(
                !GPU_COLORS.contains(&cpu),
                "{cpu:?} is in both families",
            );
        }
    }

    /// The axis never drops below the frame budget, so the line that says
    /// "sixty a second" is always somewhere on the chart.
    #[test]
    fn the_axis_never_hides_the_frame_budget() {
        let mut profiler = running();
        profiler.begin_frame();
        profiler.record(span("tiny", Lane::Cpu, 0.0, 0.01));
        profiler.end_frame();

        assert!(profiler.band(Lane::Cpu).scale >= FRAME_BUDGET);
    }

    /// A spike does raise it, or the spike would be a full-height bar with
    /// nothing to compare it to.
    #[test]
    fn a_spike_raises_the_axis() {
        let mut profiler = running();
        profiler.begin_frame();
        profiler.record(span("stall", Lane::Cpu, 0.0, 100.0));
        profiler.end_frame();

        assert!(profiler.band(Lane::Cpu).scale > 100.0);
    }

    /// Ordered by the worst across the window, not by this frame, so the
    /// legend does not reorder itself while it is being read.
    #[test]
    fn the_legend_orders_by_the_worst_it_has_seen() {
        let mut profiler = running();
        profiler.begin_frame();
        profiler.record(span("fast", Lane::Cpu, 0.0, 1.0));
        profiler.record(span("slow", Lane::Cpu, 1.0, 9.0));
        profiler.end_frame();
        // Now "slow" is cheap and "fast" is dear, but the order holds.
        profiler.begin_frame();
        profiler.record(span("fast", Lane::Cpu, 0.0, 2.0));
        profiler.record(span("slow", Lane::Cpu, 2.0, 2.5));
        profiler.end_frame();

        let band = profiler.band(Lane::Cpu);
        assert_eq!(band.slot("slow"), 0);
        assert_eq!(band.slot("fast"), 1);
    }

    /// A name keeps its colour between frames, or the chart flickers.
    #[test]
    fn a_span_keeps_its_colour() {
        let mut profiler = running();
        for _ in 0..3 {
            profiler.begin_frame();
            profiler.record(span("draw", Lane::Cpu, 0.0, 5.0));
            profiler.record(span("update", Lane::Cpu, 5.0, 6.0));
            profiler.end_frame();
        }
        let band = profiler.band(Lane::Cpu);
        assert_eq!(band.color("draw"), Lane::Cpu.color(0));
        assert_eq!(band.color("update"), Lane::Cpu.color(1));
    }

    /// The ring wraps rather than growing without end.
    #[test]
    fn the_history_wraps() {
        let mut profiler = running();
        for i in 0..HISTORY + 10 {
            profiler.begin_frame();
            profiler.record(span("draw", Lane::Cpu, 0.0, i as f64 % 5.0 + 1.0));
            profiler.end_frame();
        }
        assert_eq!(profiler.band(Lane::Cpu).frames.len(), HISTORY);
    }

    /// A held timing files itself when it is let go, so a span cannot be
    /// opened and left open.
    #[test]
    fn a_timing_files_itself_when_it_is_dropped() {
        let mut profiler = running();
        profiler.begin_frame();
        {
            let _timing = profiler.time("work", Lane::Cpu);
            std::thread::sleep(std::time::Duration::from_millis(2));
        }
        profiler.end_frame();

        let band = profiler.band(Lane::Cpu);
        assert_eq!(band.current().spans.len(), 1);
        assert!(
            band.total() >= 1.5,
            "it should have measured the sleep: {}",
            band.total(),
        );
    }

    /// Every column and every bar has to land inside the chart, whatever the
    /// numbers were: a bar running out of the panel is worse than no bar.
    #[test]
    fn nothing_is_drawn_outside_the_chart() {
        let mut profiler = running();
        for _ in 0..20 {
            profiler.begin_frame();
            profiler.record(span("huge", Lane::Cpu, 0.0, 4000.0));
            profiler.record(span("draw", Lane::Gpu, 0.0, 8.0));
            profiler.end_frame();
        }

        let mut quads = Vec::new();
        let mut atlas = Atlas::new();
        let face = Face::default();
        draw(&profiler, &mut quads, &mut atlas, &face, 1280.0, 720.0);

        assert!(!quads.is_empty(), "it should have drawn something");
        for quad in &quads {
            assert!(
                quad.pos[0] >= 0.0 && quad.pos[1] >= 0.0,
                "a quad started off the frame: {:?}",
                quad.pos,
            );
            assert!(
                quad.pos[0] + quad.size[0] <= 1280.0 + 1.0,
                "a quad ran off the right: {:?} {:?}",
                quad.pos,
                quad.size,
            );
        }
    }

    /// And nothing at all is drawn while it is off.
    #[test]
    fn a_profiler_that_is_off_draws_nothing() {
        let profiler = Profiler::new();
        let mut quads = Vec::new();
        let mut atlas = Atlas::new();
        draw(
            &profiler,
            &mut quads,
            &mut atlas,
            &Face::default(),
            1280.0,
            720.0,
        );
        assert!(quads.is_empty());
    }
}