concinnity-engine 0.19.53

//! Default stats-HUD overlay behavior. An internal system (not a declarable
//! asset): `World::start` constructs one from the world's `StatHud` component
//! and it writes live engine stats into that component's `TextLabel` chips.
//!
//! The frame-rate and GPU-memory chips are gated by the in-game video setting
//! "Display performance stats" (published by `GraphicsSystem` as the `HudPrefs`
//! resource); the exposure and HDR chips show whenever their feature is active.
//! Developer readouts (passes / cursor / camera) live on `DebugHud`.

use concinnity_core::components::StatHud;
use concinnity_core::components::TextLabel;
use concinnity_core::ecs::Ref;
use concinnity_core::ecs::asset_id::AssetId;
use concinnity_core::ecs::{Access, FrameTime, HudPrefs, PipelineContext, StepResult, System};

use super::rate_window::RateWindow;

// How often the chip text is rebuilt, in seconds. The frame rate is averaged
// over this window so the number is readable rather than flickering.
const EMIT_INTERVAL_SECS: f32 = 0.5;

// Build the frame-rate chip text from a frame count over an elapsed window.
fn fps_text(frames: u32, elapsed_secs: f32) -> String {
    let fps = if elapsed_secs > 0.0 {
        frames as f32 / elapsed_secs
    } else {
        0.0
    };
    format!("FPS {fps:.0}")
}

// Build the blocked-on-GPU chip text from the frame's `gpu_wait_us`: the
// fence / semaphore and swapchain-acquire time inside the backend's draw call.
// It is the share of the graphics system's CPU span that was waiting rather
// than working, so a GPU-bound frame reads near the frame time here.
fn gpu_wait_text(micros: u32) -> String {
    if micros < 1000 {
        format!("GPU WAIT {micros} us")
    } else {
        format!("GPU WAIT {:.1} ms", micros as f32 / 1000.0)
    }
}

// Build the GPU-memory chip text from a byte count.
fn vram_text(bytes: u64) -> String {
    format!("VRAM {} MB", bytes / (1024 * 1024))
}

// Build the host-memory chip text from the process resident set size, with the
// memory budget appended as `/ {budget} MB` when the budget resource is
// available. `None` RSS (an unsupported platform, or the editor's in-memory
// preview that does not query it) blanks the chip so the HUD shows no stale
// reading; a known RSS without a budget still reports the bare figure.
fn ram_text(rss: Option<u64>, budget_mib: Option<u64>) -> String {
    let Some(rss) = rss else {
        return String::new();
    };
    let rss_mib = rss / (1024 * 1024);
    match budget_mib {
        Some(budget) => format!("RAM {rss_mib} / {budget} MB"),
        None => format!("RAM {rss_mib} MB"),
    }
}

// Build the exposure-value chip text from the current auto-exposure EMA
// reading, or `None` when auto-exposure is not active for this world.
fn ev_text(ev: Option<f32>) -> String {
    match ev {
        Some(v) if v.is_finite() => format!("EV {v:+.2}"),
        _ => String::new(),
    }
}

// Build the EDR-headroom chip text from the active panel's maximum
// extended-range multiplier. `None` on SDR (the chip then stays empty so
// the HUD strip has no orphan reading on a non-HDR display).
fn edr_text(max_edr: Option<f32>) -> String {
    match max_edr {
        Some(v) if v.is_finite() && v > 0.0 => format!("EDR x{v:.1}"),
        _ => String::new(),
    }
}

// Draws the default stats HUD: an `FPS` chip, a `GPU WAIT` chip, a `VRAM` chip,
// an `EV` chip (when auto-exposure is on), and an `EDR` chip (when the renderer
// is on the HDR display path), each written into its own `TextLabel`. Give the
// labels a `background` color for the boxed look.
//
// The `FPS`, `GPU WAIT`, and `VRAM` chips are shown or hidden from the in-game
// video settings ("Display performance stats" + per-readout toggles); the `EV`
// and `EDR` chips appear automatically whenever their feature is active. The
// per-system timing breakdown, cursor position, and camera pose are on the
// separate `DebugHud` (F1).
//
// `GPU WAIT` is the microseconds the CPU spent blocked on the GPU inside the
// backend's per-frame draw call (the frames-in-flight fence or semaphore, plus
// the swapchain / drawable acquire). It is part of the graphics system's own
// CPU span, so subtracting it from that span gives the CPU work the frame did;
// a GPU-bound frame reads near the frame time here and near zero when the CPU
// is the bottleneck. Rides the same "Display performance stats" toggle as `FPS`.
//
// `VRAM` is the render device's current allocation; on Apple Silicon's
// unified memory that is its share of system RAM. Filled on Metal
// (`MTLDevice.currentAllocatedSize`), DirectX
// (`IDXGIAdapter3::QueryVideoMemoryInfo(LOCAL).CurrentUsage`), and Vulkan
// (`VK_EXT_memory_budget`).
//
// `EV` is the adapted exposure value the auto-exposure EMA settled on for
// the most recent frame (the multiplier the post-process stack uses is
// `2^ev`). Filled when the world's `PostProcessConfig` enables auto-exposure;
// the chip stays blank otherwise so a world without auto-exposure has no orphan
// reading.
//
// `EDR` is the active panel's maximum extended-range color-component
// multiplier (e.g. `EDR x2.0` on an HDR400 panel, `x8.0` on HDR1000).
// Filled on Metal when `PostProcessConfig.hdr_display = true` AND the
// platform reports an EDR headroom above SDR reference white; the chip
// stays blank on SDR or when the HDR request fell back.
//
// ```jsonl
// ["Font",{"$id":"hud_font","size_px":20}]
// ["TextLabel",{"$id":"fps_chip","font":"hud_font","x":10,"y":10,"scale":0.7,"color":[1,1,1],"background":[0,0.22,0.08,0.85],"padding":5}]
// ["TextLabel",{"$id":"gpu_wait_chip","font":"hud_font","x":92,"y":10,"scale":0.7,"color":[1,1,1],"background":[0,0.22,0.08,0.85],"padding":5}]
// ["TextLabel",{"$id":"vram_chip","font":"hud_font","x":232,"y":10,"scale":0.7,"color":[1,1,1],"background":[0,0.22,0.08,0.85],"padding":5}]
// ["TextLabel",{"$id":"ev_chip","font":"hud_font","x":332,"y":10,"scale":0.7,"color":[1,1,1],"background":[0,0.22,0.08,0.85],"padding":5}]
// ["TextLabel",{"$id":"edr_chip","font":"hud_font","x":412,"y":10,"scale":0.7,"color":[1,1,1],"background":[0,0.22,0.08,0.85],"padding":5}]
// ["StatHud",{"$id":"hud","fps_label":"fps_chip","gpu_wait_label":"gpu_wait_chip","vram_label":"vram_chip","ev_label":"ev_chip","edr_label":"edr_chip"}]
// ```
#[derive(Debug)]
pub(crate) struct StatHudSystem {
    fps_label: Option<AssetId>,
    gpu_wait_label: Option<AssetId>,
    vram_label: Option<AssetId>,
    ram_label: Option<AssetId>,
    ev_label: Option<AssetId>,
    edr_label: Option<AssetId>,
    // The frame-rate averaging window, which also paces the emit.
    window: RateWindow,
    // Most recent blocked-on-GPU sample for one frame, microseconds.
    gpu_wait_us: u32,
    // Most recent GPU-memory sample, bytes.
    vram_bytes: u64,
    // Most recent host resident-set size, bytes; `None` when the platform
    // query is unavailable (the chip is then blanked). Sampled on the throttled
    // emit tick, not per frame, so the syscall runs at most twice a second.
    ram_bytes: Option<u64>,
    // Most recent auto-exposure EV; `None` when auto-exposure is not active
    // for this world (the chip is then blanked).
    ev: Option<f32>,
    // Most recent panel EDR multiplier; `None` on the SDR path (the chip
    // is then blanked).
    max_edr: Option<f32>,
}

impl StatHudSystem {
    // Build the HUD from a world's `StatHud` request component.
    pub(crate) fn new(config: StatHud) -> Self {
        Self {
            fps_label: config.fps_label.map(Ref::id),
            gpu_wait_label: config.gpu_wait_label.map(Ref::id),
            vram_label: config.vram_label.map(Ref::id),
            ram_label: config.ram_label.map(Ref::id),
            ev_label: config.ev_label.map(Ref::id),
            edr_label: config.edr_label.map(Ref::id),
            window: RateWindow::default(),
            gpu_wait_us: 0,
            vram_bytes: 0,
            ram_bytes: None,
            ev: None,
            max_edr: None,
        }
    }

    // Write `text` into the TextLabel with the given id, if it exists.
    fn write_chip(ctx: &mut PipelineContext, id: Option<AssetId>, text: String) {
        crate::ecs::by_asset_id::update::<TextLabel>(ctx, id, |l| l.content = text);
    }
}

impl System for StatHudSystem {
    fn access(&self) -> Access {
        Access::new()
            .writes_components(crate::component_mask![TextLabel])
            .reads_resources(crate::resource_mask![
                concinnity_core::ecs::EntityById,
                HudPrefs,
                FrameTime,
                crate::app::budget::MemoryBudget,
            ])
    }

    fn step(&mut self, ctx: &mut PipelineContext) -> StepResult {
        // Per-chip visibility from the "Display performance stats" video
        // settings, published each frame by GraphicsSystem. Absent (a HUD-only
        // unit test with no GraphicsSystem) -> both shown, matching the old
        // default-visible behavior.
        let (show_fps, show_vram) = ctx
            .resource::<HudPrefs>()
            .map_or((true, true), |p| (p.show_fps, p.show_vram));

        self.gpu_wait_us = ctx.profile.render.gpu_wait_us;
        self.vram_bytes = ctx.profile.render.vram_bytes;
        self.ev = ctx.profile.render.auto_exposure_ev;
        self.max_edr = ctx.profile.render.max_edr;

        let dt = ctx.resource::<FrameTime>().copied().unwrap_or_default().dt;
        if let Some((frames, elapsed)) = self.window.tick(dt, EMIT_INTERVAL_SECS) {
            // Host resident-set size + memory budget, sampled here (on the
            // throttled tick) so the syscall runs at most every EMIT_INTERVAL_SECS
            // rather than every frame. The budget resource is absent in the
            // editor's in-memory preview, so `ram_text` reports the bare RSS then.
            self.ram_bytes = crate::app::sysmem::process_resident_bytes();
            let budget_mib = ctx
                .resource::<crate::app::budget::MemoryBudget>()
                .map(|b| b.budget_mib());
            // A blank chip reads as empty content -> the renderer draws neither
            // text nor the background box, so a disabled chip fully disappears.
            Self::write_chip(
                ctx,
                self.fps_label,
                if show_fps {
                    fps_text(frames, elapsed)
                } else {
                    String::new()
                },
            );
            Self::write_chip(
                ctx,
                self.vram_label,
                if show_vram {
                    vram_text(self.vram_bytes)
                } else {
                    String::new()
                },
            );
            Self::write_chip(
                ctx,
                self.gpu_wait_label,
                if show_fps {
                    gpu_wait_text(self.gpu_wait_us)
                } else {
                    String::new()
                },
            );
            Self::write_chip(ctx, self.ram_label, ram_text(self.ram_bytes, budget_mib));
            Self::write_chip(ctx, self.ev_label, ev_text(self.ev));
            Self::write_chip(ctx, self.edr_label, edr_text(self.max_edr));
        }
        StepResult::Continue
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::ecs::SYSTEMS;
    use concinnity_core::ecs::Ref;
    use concinnity_core::ecs::World;

    #[test]
    fn fps_text_averages_frames_over_window() {
        // 60 frames in 1.0 s -> 60 FPS.
        assert_eq!(fps_text(60, 1.0), "FPS 60");
        // 75 frames in 0.5 s -> 150 FPS.
        assert_eq!(fps_text(75, 0.5), "FPS 150");
    }

    #[test]
    fn fps_text_handles_zero_window() {
        assert_eq!(fps_text(0, 0.0), "FPS 0");
    }

    #[test]
    fn vram_text_reports_whole_megabytes() {
        assert_eq!(vram_text(0), "VRAM 0 MB");
        assert_eq!(vram_text(512 * 1024 * 1024), "VRAM 512 MB");
        // Truncates to whole MB.
        assert_eq!(vram_text(1024 * 1024 + 1), "VRAM 1 MB");
    }

    #[test]
    fn ram_text_reports_rss_with_budget_when_known() {
        // Known RSS and budget render as "used / budget MB", both truncated to
        // whole MiB.
        assert_eq!(
            ram_text(Some(512 * 1024 * 1024), Some(16384)),
            "RAM 512 / 16384 MB"
        );
    }

    #[test]
    fn ram_text_reports_bare_rss_without_a_budget() {
        // No budget resource (the editor's in-memory preview): report the RSS
        // alone rather than a dangling "/ MB".
        assert_eq!(ram_text(Some(256 * 1024 * 1024), None), "RAM 256 MB");
    }

    #[test]
    fn ram_text_blanks_when_rss_unavailable() {
        // `None` RSS (an unsupported platform): the chip stays empty rather than
        // showing a stale or zeroed figure.
        assert_eq!(ram_text(None, Some(16384)), "");
        assert_eq!(ram_text(None, None), "");
    }

    #[test]
    fn ev_text_formats_signed_value_with_two_decimals() {
        // Positive bias keeps the leading "+" so the sign is unambiguous on
        // screen.
        assert_eq!(ev_text(Some(1.25)), "EV +1.25");
        assert_eq!(ev_text(Some(-0.5)), "EV -0.50");
        assert_eq!(ev_text(Some(0.0)), "EV +0.00");
    }

    #[test]
    fn ev_text_blanks_when_auto_exposure_off() {
        // `None` means the world did not opt in to auto-exposure; the chip
        // stays empty so the HUD doesn't show a stale or misleading value.
        assert_eq!(ev_text(None), "");
    }

    #[test]
    fn ev_text_blanks_on_non_finite_values() {
        // A backend bug could leave the EV at NaN or infinity; render blank
        // rather than print "NaN" in the HUD.
        assert_eq!(ev_text(Some(f32::NAN)), "");
        assert_eq!(ev_text(Some(f32::INFINITY)), "");
    }

    #[test]
    fn edr_text_formats_multiplier_with_one_decimal() {
        // HDR400-class panels typically report 2.0; HDR1000-class 8.0+.
        // One decimal place keeps the chip narrow and unambiguous.
        assert_eq!(edr_text(Some(2.0)), "EDR x2.0");
        assert_eq!(edr_text(Some(8.5)), "EDR x8.5");
    }

    #[test]
    fn edr_text_blanks_when_sdr() {
        // `None` from the renderer means the SDR path is active: the chip
        // should not show an "EDR x1.0" reading because there is no HDR
        // headroom in play.
        assert_eq!(edr_text(None), "");
    }

    #[test]
    fn edr_text_blanks_on_invalid_values() {
        // Defensive: a backend reporting non-finite or non-positive max_edr
        // should not surface as "EDR xNaN" / "EDR x-1.0" on screen.
        assert_eq!(edr_text(Some(f32::NAN)), "");
        assert_eq!(edr_text(Some(f32::INFINITY)), "");
        assert_eq!(edr_text(Some(0.0)), "");
        assert_eq!(edr_text(Some(-1.0)), "");
    }

    // A StatHud component spawns the internal HUD system.
    #[test]
    fn stat_hud_component_spawns_internal_system() {
        use concinnity_core::components::StatHud;
        use concinnity_core::ecs::World;

        let mut world = World::new();
        world.add_component(StatHud::default());
        world.start(SYSTEMS).unwrap();
        let names: Vec<&str> = world.systems().iter().map(|s| s.name()).collect();
        assert_eq!(names, ["StatHud"]);
    }

    #[test]
    fn no_stat_hud_no_system() {
        use concinnity_core::ecs::World;

        let mut world = World::new();
        world.start(SYSTEMS).unwrap();
        assert!(world.systems().is_empty());
    }

    // A world carrying a StatHud wired to fps + vram + ram chips and their
    // labels.
    fn hud_world() -> World {
        let mut world = World::new();
        world.add_component(StatHud {
            fps_label: Some(Ref::new(AssetId(1))),
            vram_label: Some(Ref::new(AssetId(2))),
            ram_label: Some(Ref::new(AssetId(3))),
            gpu_wait_label: Some(Ref::new(AssetId(4))),
            ..StatHud::default()
        });
        for id in [1u32, 2, 3, 4] {
            world.push_identified(AssetId(id), TextLabel::default());
        }
        world
    }

    fn chip(world: &World, id: u32) -> String {
        world
            .get_by_id::<TextLabel>(AssetId(id))
            .map(|l| l.content.clone())
            .unwrap_or_default()
    }

    // Once the averaging window elapses, the step body writes the FPS and VRAM
    // chips (both shown when no HudPrefs is published).
    #[test]
    fn emit_window_writes_fps_and_vram_chips() {
        let mut world = hud_world();
        world.start(SYSTEMS).unwrap();
        world.insert_resource(FrameTime {
            dt: 1.0,
            elapsed: 0.0,
        });
        world.step();
        assert!(chip(&world, 1).starts_with("FPS "), "{}", chip(&world, 1));
        assert_eq!(chip(&world, 2), "VRAM 0 MB");
    }

    // Frames shorter than the window leave the chips alone until their
    // accumulated time reaches it, and the FPS chip averages over that span.
    #[test]
    fn emit_waits_for_the_window_and_averages_its_frames() {
        let mut world = hud_world();
        world.start(SYSTEMS).unwrap();
        world.insert_resource(FrameTime {
            dt: 0.125,
            elapsed: 0.0,
        });
        for _ in 0..3 {
            world.step();
        }
        assert_eq!(chip(&world, 1), "", "no emit before the window closes");
        world.step();
        assert_eq!(chip(&world, 1), "FPS 8");
    }

    // The RAM chip is always-on (not gated by HudPrefs): on a platform that
    // reports RSS it fills with a "RAM ..." reading, and the published
    // MemoryBudget resource appends the "/ budget MB" tail.
    #[test]
    fn emit_window_writes_ram_chip_with_budget() {
        use crate::app::budget::MemoryBudget;

        let mut world = hud_world();
        world.start(SYSTEMS).unwrap();
        // The budget defaults to a fraction of total RAM, so derive the expected
        // MiB from the same value rather than assuming it equals total RAM.
        let budget = MemoryBudget::compute(Some(16 * 1024 * 1024 * 1024), 0);
        world.insert_resource(budget);
        world.insert_resource(FrameTime {
            dt: 1.0,
            elapsed: 0.0,
        });
        world.step();
        // RSS is available on macOS / Linux / Windows; other targets report
        // `None`, blanking the chip (so the assertion is platform-gated).
        if cfg!(any(
            target_os = "macos",
            target_os = "linux",
            target_os = "windows"
        )) {
            let ram = chip(&world, 3);
            assert!(ram.starts_with("RAM "), "{ram}");
            assert!(
                ram.ends_with(&format!(" / {} MB", budget.budget_mib())),
                "{ram}"
            );
        }
    }

    // The HudPrefs resource (published by GraphicsSystem) gates each chip: with
    // both off, the fps and vram chips blank on the next emit.
    #[test]
    fn hud_prefs_hide_fps_and_vram_chips() {
        use concinnity_core::ecs::HudPrefs;

        let mut world = hud_world();
        world.start(SYSTEMS).unwrap();
        world.insert_resource(HudPrefs {
            show_fps: false,
            show_vram: false,
        });
        world.insert_resource(FrameTime {
            dt: 1.0,
            elapsed: 0.0,
        });
        world.step();
        assert_eq!(chip(&world, 1), "", "fps chip hidden");
        assert_eq!(chip(&world, 2), "", "vram chip hidden");
        assert_eq!(chip(&world, 4), "", "gpu wait chip hidden");
    }

    // Sub-millisecond waits stay in microseconds so a CPU-bound frame is
    // legible; anything longer reads as milliseconds like the passes chip.
    #[test]
    fn gpu_wait_text_switches_unit_at_a_millisecond() {
        assert_eq!(gpu_wait_text(0), "GPU WAIT 0 us");
        assert_eq!(gpu_wait_text(999), "GPU WAIT 999 us");
        assert_eq!(gpu_wait_text(12_400), "GPU WAIT 12.4 ms");
    }

    // The chip tracks `RenderStats.gpu_wait_us`, which is what separates a
    // GPU-bound frame from a CPU-bound one in the graphics system's own span.
    #[test]
    fn emit_window_writes_the_gpu_wait_chip() {
        let mut world = hud_world();
        world.start(SYSTEMS).unwrap();
        world.insert_resource(FrameTime {
            dt: 1.0,
            elapsed: 0.0,
        });
        world.step();
        assert_eq!(chip(&world, 4), "GPU WAIT 0 us");
    }
}