concinnity_core/components/
debug_hud.rs

1// Developer debug HUD schema.
2
3use crate::ecs::asset_id::AssetId;
4use crate::ecs::asset_id::de_opt_asset_ref;
5
6/// Requests the developer debug HUD: a set of [TextLabel](#textlabel) chips
7/// with diagnostic readouts, anchored to the top-right of the window and
8/// toggled with F1 (hidden by default).
9///
10/// Each label field, when set, receives one chip: `passes_label` a multi-line
11/// list of the heaviest rendering steps of the last frame, `mouse_label` the
12/// cursor position in window pixels, `camera_label` the live camera pose
13/// (position, yaw, pitch) in the exact form a fixed viewpoint is reproduced
14/// with, and `sys_label` the worker-thread and host-memory budgets (the job
15/// pool's thread count, and the process resident set against the memory
16/// budget). Chips whose stat is unavailable stay blank. The chips stack
17/// vertically from the top-right corner in the order cursor, then camera, then
18/// system, then passes (passes is last because its height varies with the
19/// frame's step count), so their on-screen position is fixed by the engine
20/// rather than the authored coordinates.
21///
22/// The always-on frame-rate and GPU-memory readouts live on the separate
23/// [StatHud](#stathud).
24///
25/// Every rendering world receives a `DebugHud` and its chip labels at build
26/// time when it declares none, so the example below is only needed to restyle
27/// the chips. The HUD only activates in developer contexts: a debug build of
28/// the host binary, or a world launched through `cn debug`; release builds
29/// leave it inert even when declared. Declare an
30/// [EngineDefaults](#enginedefaults) with `"debug_hud": false` to remove it
31/// from the build entirely.
32#[derive(Debug, Clone, Default, serde::Serialize, serde::Deserialize)]
33#[serde(default)]
34pub struct DebugHud {
35    /// [TextLabel](#textlabel) that receives the per-step GPU-timing chip text.
36    #[serde(deserialize_with = "de_opt_asset_ref")]
37    pub passes_label: Option<AssetId>,
38    /// [TextLabel](#textlabel) that receives the cursor-position chip text.
39    #[serde(deserialize_with = "de_opt_asset_ref")]
40    pub mouse_label: Option<AssetId>,
41    /// [TextLabel](#textlabel) that receives the live camera-pose chip text.
42    #[serde(deserialize_with = "de_opt_asset_ref")]
43    pub camera_label: Option<AssetId>,
44    /// [TextLabel](#textlabel) that receives the thread / memory budget chip text.
45    #[serde(deserialize_with = "de_opt_asset_ref")]
46    pub sys_label: Option<AssetId>,
47}
48
49#[cfg(test)]
50mod tests {
51    use super::*;
52
53    #[test]
54    fn a_blank_hud_claims_no_labels() {
55        // Every chip is opt-in: an unset slot means that readout is suppressed
56        // rather than drawn somewhere arbitrary.
57        let h = DebugHud::default();
58        assert!(h.passes_label.is_none());
59        assert!(h.mouse_label.is_none());
60        assert!(h.camera_label.is_none());
61        assert!(h.sys_label.is_none());
62    }
63
64    #[test]
65    fn each_chip_binds_its_own_label_and_round_trips_through_postcard() {
66        crate::test_support::install_resolvers();
67        let h: DebugHud = serde_json::from_str(
68            r#"{"passes_label":"passes_chip","mouse_label":"","camera_label":"cam","sys_label":6}"#,
69        )
70        .unwrap();
71        assert_eq!(h.passes_label, Some(AssetId(11)));
72        assert_eq!(h.mouse_label, None);
73        assert_eq!(h.camera_label, Some(AssetId(3)));
74        assert_eq!(h.sys_label, Some(AssetId(6)));
75
76        let bytes = postcard::to_allocvec(&h).unwrap();
77        let back: DebugHud = postcard::from_bytes(&bytes).unwrap();
78        assert_eq!(back.passes_label, Some(AssetId(11)));
79        assert_eq!(back.mouse_label, None);
80        assert_eq!(back.sys_label, Some(AssetId(6)));
81    }
82}
concinnity_core/components/debug_hud.rs

concinnity_core/components/
debug_hud.rs
