1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
// Stats HUD schema.
use crate::ecs::asset_id::AssetId;
use crate::ecs::asset_id::de_opt_asset_ref;
/// Requests the default on-screen stats HUD. Drives a set of
/// [TextLabel](#textlabel) chips with live engine stats, refreshed on a fixed
/// interval.
///
/// Each label field, when set, receives one chip: `fps_label` the averaged
/// frame rate, `vram_label` the GPU-memory use, `ram_label` the host process
/// memory (resident set size, against the memory budget when known), `ev_label`
/// the auto-exposure value, and `edr_label` the HDR headroom multiplier. Chips
/// whose stat is unavailable stay blank. The frame-rate and GPU-memory chips
/// are shown or hidden from the in-game video settings ("Display performance
/// stats"); the host-memory, exposure, and HDR chips show whenever their
/// reading is available.
///
/// The chips are packed into a tight strip anchored at the top-left of the
/// window, left to right in the order fps, vram, ram, ev, edr; a blank chip
/// reserves no width, so hidden readouts leave no gap. Their on-screen position
/// is fixed by the engine rather than the authored coordinates.
///
/// Developer-facing readouts (per-pass GPU timings, cursor position, live
/// camera pose) live on the separate [DebugHud](#debughud), toggled with F1.
///
/// A world that declares a [MainMenu](#mainmenu) receives a `StatHud` from the
/// build when it declares none, since the menu's performance-stats toggles
/// drive the chips, and any label field left unset receives a chip at start.
/// So the example below is only needed to restyle the chips or run a HUD
/// without a menu. Declare an [EngineDefaults](#enginedefaults) with
/// `"hud": false` to leave the chips unfilled.
#[derive(Debug, Clone, Default, serde::Serialize, serde::Deserialize)]
#[serde(default)]
pub struct StatHud {
/// [TextLabel](#textlabel) that receives the frame-rate chip text.
#[serde(deserialize_with = "de_opt_asset_ref")]
pub fps_label: Option<AssetId>,
/// [TextLabel](#textlabel) that receives the GPU-memory chip text.
#[serde(deserialize_with = "de_opt_asset_ref")]
pub vram_label: Option<AssetId>,
/// [TextLabel](#textlabel) that receives the host-memory (RSS) chip text.
#[serde(deserialize_with = "de_opt_asset_ref")]
pub ram_label: Option<AssetId>,
/// [TextLabel](#textlabel) that receives the auto-exposure chip text.
#[serde(deserialize_with = "de_opt_asset_ref")]
pub ev_label: Option<AssetId>,
/// [TextLabel](#textlabel) that receives the HDR-headroom chip text.
#[serde(deserialize_with = "de_opt_asset_ref")]
pub edr_label: Option<AssetId>,
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn a_blank_hud_claims_no_labels() {
// Each chip is opt-in, so an unset slot suppresses that readout instead
// of drawing it somewhere arbitrary.
let h = StatHud::default();
assert!(h.fps_label.is_none());
assert!(h.vram_label.is_none());
assert!(h.ram_label.is_none());
assert!(h.ev_label.is_none());
assert!(h.edr_label.is_none());
}
#[test]
fn each_chip_binds_its_own_label_and_round_trips_through_postcard() {
crate::test_support::install_resolvers();
let h: StatHud = serde_json::from_str(
r#"{"fps_label":"fps_chip","vram_label":"vram","ram_label":"","ev_label":3,
"edr_label":"edr_chip"}"#,
)
.unwrap();
assert_eq!(h.fps_label, Some(AssetId(8)));
assert_eq!(h.vram_label, Some(AssetId(4)));
assert_eq!(h.ram_label, None);
assert_eq!(h.ev_label, Some(AssetId(3)));
assert_eq!(h.edr_label, Some(AssetId(8)));
let bytes = postcard::to_allocvec(&h).unwrap();
let back: StatHud = postcard::from_bytes(&bytes).unwrap();
assert_eq!(back.fps_label, Some(AssetId(8)));
assert_eq!(back.ram_label, None);
assert_eq!(back.ev_label, Some(AssetId(3)));
}
}