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
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
//! Opt-in, bounded runtime summaries. Timings are CPU wall times, not GPU timers.
use crate::Error;
use serde::Serialize;
use std::{path::PathBuf, time::Duration};
/// Enables diagnostics with a game-defined stable workload identifier.
#[derive(Clone, Debug)]
pub struct DiagnosticsConfig {
/// ASCII workload ID; compare identical workloads and settings.
pub workload: String,
/// Optional JSON report destination, written after the run, outside timings.
pub output: Option<PathBuf>,
}
impl DiagnosticsConfig {
/// Creates an in-memory report. No per-frame output or sample vector is stored.
pub fn new(workload: impl Into<String>) -> Self {
Self {
workload: workload.into(),
output: None,
}
}
pub(crate) fn validate(&self) -> Result<(), Error> {
if self.workload.is_empty()
|| self.workload.len() > 128
|| !self
.workload
.bytes()
.all(|b| b.is_ascii_alphanumeric() || b"._-/".contains(&b))
{
return Err(Error::Config(
"diagnostic workload must be 1..=128 ASCII letters/digits or ._-/".into(),
));
}
if self
.output
.as_ref()
.is_some_and(|p| p.as_os_str().is_empty())
{
return Err(Error::Config(
"diagnostic output path cannot be empty".into(),
));
}
Ok(())
}
}
/// Successful SDK submissions, not hardware draw calls. Raw raylib calls are excluded.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize)]
pub struct DrawCounters {
/// Color/depth clear requests.
pub clears: u64,
/// Camera passes in two dimensions.
pub world_2d_passes: u64,
/// Camera passes in three dimensions.
pub world_3d_passes: u64,
/// UI passes.
pub ui_passes: u64,
/// Explicit raw passes; submissions inside cannot be counted.
pub raw_passes: u64,
/// 2D rectangles, circles and lines.
pub primitives_2d: u64,
/// 3D boxes, wireframes, spheres and lines.
pub primitives_3d: u64,
/// Mesh submissions, including constituent meshes of imported models.
pub meshes: u64,
/// Imported model requests.
pub models: u64,
/// World textures and UI icons.
pub textures: u64,
/// UI rectangles, circles and button focus outlines.
pub ui_primitives: u64,
/// UI text requests; glyph counts are not tracked.
pub text: u64,
}
impl DrawCounters {
pub(crate) fn add(&mut self, other: Self) {
macro_rules! add { ($($f:ident),*) => { $(self.$f = self.$f.saturating_add(other.$f);)* }; }
add!(
clears,
world_2d_passes,
world_3d_passes,
ui_passes,
raw_passes,
primitives_2d,
primitives_3d,
meshes,
models,
textures,
ui_primitives,
text
);
}
}
/// Live resources owned by Assets, excluding game-owned native handles and raylib defaults.
/// Bytes describe logical payloads, not driver allocation size or total VRAM.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize)]
pub struct ResourceCounts {
/// Live custom font handles.
pub fonts: u64,
/// Cached font atlas textures, including adaptive size variants.
pub font_atlases: u64,
/// RGBA font atlas payload bytes, excluding CPU outline storage.
pub font_bytes: u64,
/// Standalone cached textures.
pub textures: u64,
/// Imported models.
pub models: u64,
/// Loaded sounds; audio storage bytes are not estimated.
pub sounds: u64,
/// Generated meshes.
pub meshes: u64,
/// Custom shaders plus the SDK material shader when initialized.
pub shaders: u64,
/// Game material descriptions.
pub materials: u64,
/// Standalone texture payload bytes, including mip levels.
pub texture_bytes: u64,
/// Generated vertex/attribute/index buffer payload bytes, including fallback UVs.
pub generated_mesh_bytes: u64,
/// Standard imported geometry arrays; excludes animations, bones and model textures.
pub model_geometry_bytes: u64,
}
impl ResourceCounts {
pub(crate) fn maximize(&mut self, other: Self) {
macro_rules! max { ($($f:ident),*) => { $(self.$f = self.$f.max(other.$f);)* }; }
max!(
fonts,
font_atlases,
font_bytes,
textures,
models,
sounds,
meshes,
shaders,
materials,
texture_bytes,
generated_mesh_bytes,
model_geometry_bytes
);
}
}
/// Constant-space timing summary, with explicit nanosecond units.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize)]
pub struct TimingStats {
/// Number of samples.
pub samples: u64,
/// Saturating total nanoseconds; divide by samples for the mean.
pub total_ns: u64,
/// Minimum, zero when empty.
pub min_ns: u64,
/// Maximum, zero when empty.
pub max_ns: u64,
}
impl TimingStats {
/// Adds a wall-time sample without allocation. Totals saturate rather than wrap.
pub fn record(&mut self, elapsed: Duration) {
let ns = elapsed.as_nanos().min(u128::from(u64::MAX)) as u64;
self.min_ns = if self.samples == 0 {
ns
} else {
self.min_ns.min(ns)
};
self.max_ns = self.max_ns.max(ns);
self.samples = self.samples.saturating_add(1);
self.total_ns = self.total_ns.saturating_add(ns);
}
}
/// Settings required to interpret a run. Machine/driver provenance comes from benchmark scripts.
#[derive(Clone, Debug, Serialize)]
pub struct RunSettings {
/// Compiled window backend.
pub backend: &'static str,
/// OS target.
pub os: &'static str,
/// Architecture target.
pub arch: &'static str,
/// SDK version.
pub sdk_version: &'static str,
/// OpenGL vendor, renderer and version strings from the active context.
pub graphics: [String; 3],
/// Initial logical window dimensions.
pub window_size: (u32, u32),
/// Reference UI dimensions.
pub reference_size: [f32; 2],
/// Viewport policy.
pub scale_mode: &'static str,
/// Fixed simulation frequency.
pub fixed_hz: u32,
/// Catch-up limit.
pub max_catch_up: u32,
/// Requested effective render cap, zero for uncapped.
pub target_fps: u32,
/// Requested effective display synchronization; driver behavior may differ.
pub vsync: bool,
/// Last offscreen render size, including DPI/viewport effects.
pub render_size: (u32, u32),
/// Internal world resolution multiplier per dimension.
pub render_scale: f32,
/// Offscreen world edge filter, serialized by its stable setting name.
pub anti_aliasing: &'static str,
/// Native composition dimensions.
pub output_size: (u32, u32),
/// Conservative steady-state render target allocation estimate.
pub render_target_bytes: u64,
}
/// JSON schema 1. Reports retain totals/extrema instead of unbounded frame samples.
#[derive(Clone, Debug, Serialize)]
pub struct DiagnosticsReport {
/// Schema version, currently 1.
pub schema_version: u32,
/// Stable game-provided workload ID.
pub workload: String,
/// Effective settings and target information.
pub settings: RunSettings,
/// Presented frames, excluding minimized polling.
pub frames: u64,
/// Executed fixed updates.
pub updates: u64,
/// Time discarded by catch-up, nanoseconds.
pub dropped_ns: u64,
/// Complete active-frame wall time, including presentation and enabled diagnostics.
pub frame: TimingStats,
/// Individual game fixed-update callback wall times.
pub update: TimingStats,
/// Target preparation, clear and game draw callback, excluding presentation.
pub render: TimingStats,
/// Window presentation including EndDrawing, swaps, frame cap and driver stalls.
pub present: TimingStats,
/// Aggregate SDK submissions; excludes the runner's presentation blit.
pub draws: DrawCounters,
/// Last sampled resources, before teardown.
pub resources: ResourceCounts,
/// Per-field resource high-water marks, sampled after init and each active frame.
pub peak_resources: ResourceCounts,
}
impl DiagnosticsReport {
pub(crate) fn new(
config: &DiagnosticsConfig,
settings: RunSettings,
resources: ResourceCounts,
) -> Self {
Self {
schema_version: 1,
workload: config.workload.clone(),
settings,
frames: 0,
updates: 0,
dropped_ns: 0,
frame: TimingStats::default(),
update: TimingStats::default(),
render: TimingStats::default(),
present: TimingStats::default(),
draws: DrawCounters::default(),
resources,
peak_resources: resources,
}
}
pub(crate) fn record_frame(&mut self, draws: DrawCounters, resources: ResourceCounts) {
self.frames = self.frames.saturating_add(1);
self.draws.add(draws);
self.resources = resources;
self.peak_resources.maximize(resources);
}
/// Serializes schema 1 outside measured frames. Serialization failures propagate.
pub fn write_json(&self, output: impl std::io::Write) -> Result<(), serde_json::Error> {
serde_json::to_writer_pretty(output, self)
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn timings_and_counters_saturate_and_peaks_do_not_sum() {
let mut t = TimingStats::default();
t.record(Duration::from_nanos(20));
t.record(Duration::from_nanos(10));
assert_eq!(
t,
TimingStats {
samples: 2,
total_ns: 30,
min_ns: 10,
max_ns: 20
}
);
t.record(Duration::MAX);
assert_eq!(t.total_ns, u64::MAX);
let mut draws = DrawCounters {
meshes: u64::MAX,
..Default::default()
};
draws.add(DrawCounters {
meshes: 1,
textures: 2,
..Default::default()
});
assert_eq!(draws.meshes, u64::MAX);
assert_eq!(draws.textures, 2);
let mut resources = ResourceCounts {
meshes: 4,
..Default::default()
};
resources.maximize(ResourceCounts {
meshes: 2,
texture_bytes: 100,
..Default::default()
});
assert_eq!(resources.meshes, 4);
assert_eq!(resources.texture_bytes, 100);
}
#[test]
fn workload_validation_and_json_write_errors_are_explicit() {
for id in ["", "contains spaces", "a\n", &"x".repeat(129)] {
assert!(DiagnosticsConfig::new(id).validate().is_err());
}
DiagnosticsConfig::new("mesh/default-100.v1")
.validate()
.unwrap();
assert!(serde_json::to_writer(std::io::sink(), &DrawCounters::default()).is_ok());
}
#[test]
fn report_schema_is_stable_and_output_errors_propagate() {
let settings = RunSettings {
backend: "test",
os: "test",
arch: "test",
sdk_version: "0.0.1",
graphics: std::array::from_fn(|_| "test".into()),
window_size: (64, 64),
reference_size: [64.0; 2],
scale_mode: "fit",
fixed_hz: 120,
max_catch_up: 8,
target_fps: 0,
vsync: false,
render_size: (64, 64),
render_scale: 1.0,
anti_aliasing: "none",
output_size: (64, 64),
render_target_bytes: 64 * 64 * 8,
};
let mut report = DiagnosticsReport::new(
&DiagnosticsConfig::new("fixture.v1"),
settings,
ResourceCounts::default(),
);
report.record_frame(
DrawCounters {
meshes: 4,
..Default::default()
},
ResourceCounts {
generated_mesh_bytes: 100,
..Default::default()
},
);
report.record_frame(
DrawCounters {
meshes: 2,
..Default::default()
},
ResourceCounts::default(),
);
report.frame.record(Duration::from_nanos(50));
let mut bytes = Vec::new();
report.write_json(&mut bytes).unwrap();
let json: serde_json::Value = serde_json::from_slice(&bytes).unwrap();
let mut keys: Vec<_> = json
.as_object()
.unwrap()
.keys()
.map(String::as_str)
.collect();
keys.sort_unstable();
assert_eq!(
keys,
[
"draws",
"dropped_ns",
"frame",
"frames",
"peak_resources",
"present",
"render",
"resources",
"schema_version",
"settings",
"update",
"updates",
"workload"
]
);
assert_eq!(json["schema_version"], 1);
assert_eq!(json["frames"], 2);
assert_eq!(json["draws"]["meshes"], 6);
assert_eq!(json["resources"]["generated_mesh_bytes"], 0);
assert_eq!(json["peak_resources"]["generated_mesh_bytes"], 100);
assert_eq!(json["frame"]["total_ns"], 50);
struct Rejected;
impl std::io::Write for Rejected {
fn write(&mut self, _: &[u8]) -> std::io::Result<usize> {
Err(std::io::Error::from(std::io::ErrorKind::BrokenPipe))
}
fn flush(&mut self) -> std::io::Result<()> {
Ok(())
}
}
assert!(report.write_json(Rejected).unwrap_err().is_io());
}
}