Skip to main content

sim_engine/renderer/
gpu_timing.rs

1//! Opt-in, bounded render-pass timestamp collection without GPU waits.
2
3use std::sync::Arc;
4use std::sync::atomic::{AtomicU8, AtomicU64, Ordering};
5use std::time::{Duration, Instant};
6
7const CAPACITY: usize = 8;
8const QUERY_BYTES: u64 = 16;
9const FREE: u8 = 0;
10const RESERVED: u8 = 1;
11const MAPPING: u8 = 2;
12const READY: u8 = 3;
13const FAILED: u8 = 4;
14static NEXT_ID: AtomicU64 = AtomicU64::new(1);
15
16pub(super) fn requested_features(available: wgpu::Features, requested: bool) -> wgpu::Features {
17    if requested {
18        available & wgpu::Features::TIMESTAMP_QUERY
19    } else {
20        wgpu::Features::empty()
21    }
22}
23
24#[cfg(test)]
25pub(super) use tests::assert_gpu_timing_contract;
26
27/// Availability of the explicitly requested render-pass GPU diagnostics.
28#[derive(Debug, Clone, Copy, PartialEq, Eq)]
29pub enum GpuTimingStatus {
30    /// Timing was not requested; no queries or readback resources are created.
31    Disabled,
32    /// Timing was requested but is unavailable on the current logical device.
33    /// Unsupported features, an unusable timestamp period or a polling failure
34    /// produce this state. CPU submission/wait time is never substituted.
35    Unavailable,
36    /// Timestamp queries are active; individual samples can still be dropped
37    /// when the fixed ring is full or rejected when readback fails.
38    Enabled,
39}
40
41/// Render pass measured by a sample, not CPU uploads or presentation latency.
42#[derive(Debug, Clone, Copy, PartialEq, Eq)]
43pub enum GpuTimingSource {
44    /// A retained 3D scene's offscreen surface and mathematical-edge pass.
45    Scene3d,
46    /// A heterogeneous composed frame's surface render pass, including MSAA
47    /// resolution but excluding acquisition, scanout and separate 3D passes.
48    FrameComposer,
49}
50
51/// Opaque correlation key returned by a submitted render report.
52///
53/// Keys are monotonic and never reused across renderer instances or recovery.
54/// A key identifies a submitted pass, not confirmed monitor scanout. Match the
55/// complete key to its report when excluding warmup or unrelated work.
56#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
57pub struct GpuTimingId(u64);
58
59impl GpuTimingId {
60    /// Returns the process-local sequence value for diagnostics and logs.
61    pub const fn get(self) -> u64 {
62        self.0
63    }
64}
65
66/// One completed GPU render-pass interval obtained from hardware timestamps.
67#[derive(Debug, Clone, Copy, PartialEq, Eq)]
68pub struct GpuTimingSample {
69    id: GpuTimingId,
70    source: GpuTimingSource,
71    elapsed: Duration,
72}
73
74impl GpuTimingSample {
75    /// Returns the originating submitted report's correlation key.
76    pub const fn id(self) -> GpuTimingId {
77        self.id
78    }
79
80    /// Returns the measured pass category.
81    pub const fn source(self) -> GpuTimingSource {
82        self.source
83    }
84
85    /// Returns `(end_tick - begin_tick) * timestamp_period`, rounded to the
86    /// nearest representable nanosecond. Timestamp resolution is backend/device
87    /// dependent; a zero interval is possible below that resolution. Uploads,
88    /// query resolution/readback, queue waits and presentation are excluded.
89    pub const fn elapsed(self) -> Duration {
90        self.elapsed
91    }
92}
93
94/// Fixed-capacity result of one nonblocking GPU-diagnostics collection.
95///
96/// At most eight completed samples are returned, ordered by their correlation
97/// keys. Later submissions may complete first; match IDs rather than treating
98/// collection order as frame order. This value allocates no sample array.
99#[derive(Debug, Clone, Copy)]
100pub struct GpuTimingBatch {
101    samples: [GpuTimingSample; CAPACITY],
102    count: usize,
103    collection_cpu: Duration,
104}
105
106impl GpuTimingBatch {
107    fn empty() -> Self {
108        Self {
109            samples: [GpuTimingSample {
110                id: GpuTimingId(0),
111                source: GpuTimingSource::Scene3d,
112                elapsed: Duration::ZERO,
113            }; CAPACITY],
114            count: 0,
115            collection_cpu: Duration::ZERO,
116        }
117    }
118
119    /// Returns completed valid samples from this collection only.
120    pub fn samples(&self) -> &[GpuTimingSample] {
121        &self.samples[..self.count]
122    }
123
124    /// Returns CPU time spent polling once, copying up to 128 timestamp bytes,
125    /// validating intervals and unmapping. The poll does not wait for the GPU,
126    /// but may perform backend maintenance or invoke other ready callbacks.
127    pub const fn collection_cpu(self) -> Duration {
128        self.collection_cpu
129    }
130}
131
132/// Current-device bounded diagnostics resource and loss accounting.
133///
134/// Counters reset during renderer recovery; previously pending samples are
135/// discarded. Query/resolve/map operations add measurement overhead. Buffer
136/// bytes below are nominal, excluding driver alignment, query storage and
137/// callback/backend allocation overhead. No render-thread GPU waits occur.
138#[derive(Debug, Clone, Copy)]
139pub struct GpuTimingStatistics {
140    status: GpuTimingStatus,
141    pending: usize,
142    submitted: u64,
143    completed: u64,
144    dropped: u64,
145    map_failures: u64,
146    invalid_samples: u64,
147    poll_failures: u64,
148    collection_cpu: Duration,
149    timestamp_period_nanoseconds: Option<f64>,
150}
151
152impl GpuTimingStatistics {
153    /// Returns whether timing was requested and is usable on this device.
154    pub const fn status(self) -> GpuTimingStatus {
155        self.status
156    }
157
158    /// Maximum simultaneously reserved/submitted samples; zero when unavailable.
159    pub const fn capacity(self) -> usize {
160        if matches!(self.status, GpuTimingStatus::Enabled) {
161            CAPACITY
162        } else {
163            0
164        }
165    }
166
167    /// Reserved, mapping or completed-but-not-yet-collected ring entries.
168    pub const fn pending(self) -> usize {
169        self.pending
170    }
171
172    /// Submitted timestamp intervals, including eventual failures or invalid data.
173    pub const fn submitted(self) -> u64 {
174        self.submitted
175    }
176
177    /// Valid samples delivered through collection batches.
178    pub const fn completed(self) -> u64 {
179        self.completed
180    }
181
182    /// Passes not sampled because all slots were occupied or IDs were exhausted.
183    /// Disabled/unavailable timing does not increment this counter.
184    pub const fn dropped(self) -> u64 {
185        self.dropped
186    }
187
188    /// Failed asynchronous maps or mapped-range access attempts.
189    pub const fn map_failures(self) -> u64 {
190        self.map_failures
191    }
192
193    /// Rejected intervals, including end-before-start/wrapped timestamps and
194    /// durations outside the representable range. No zero substitute is emitted.
195    pub const fn invalid_samples(self) -> u64 {
196        self.invalid_samples
197    }
198
199    /// Device-poll failures; these disable the ring until renderer recovery.
200    pub const fn poll_failures(self) -> u64 {
201        self.poll_failures
202    }
203
204    /// Nominal bytes in eight 16-byte resolve and eight 16-byte readback buffers.
205    pub const fn gpu_buffer_bytes(self) -> usize {
206        self.capacity() * QUERY_BYTES as usize * 2
207    }
208
209    /// Number of timestamp query slots; query-set driver storage is not exposed.
210    pub const fn query_count(self) -> usize {
211        self.capacity() * 2
212    }
213
214    /// Bytes queued for query resolution and readback copies over submitted
215    /// samples. Each sample resolves and copies exactly two 64-bit timestamps;
216    /// these diagnostic transfers are separate from scene upload statistics.
217    pub const fn readback_bytes(self) -> u64 {
218        self.submitted.saturating_mul(QUERY_BYTES)
219    }
220
221    /// Sum of collection CPU costs, separate from measured GPU pass intervals.
222    pub const fn collection_cpu(self) -> Duration {
223        self.collection_cpu
224    }
225
226    /// Nanoseconds per raw query tick, or `None` when timing is unavailable.
227    pub const fn timestamp_period_nanoseconds(self) -> Option<f64> {
228        self.timestamp_period_nanoseconds
229    }
230}
231
232struct Slot {
233    resolve: wgpu::Buffer,
234    readback: wgpu::Buffer,
235    state: Arc<AtomicU8>,
236    request: Option<(GpuTimingId, GpuTimingSource)>,
237}
238
239struct Ring {
240    queries: wgpu::QuerySet,
241    slots: [Slot; CAPACITY],
242    period: f64,
243}
244
245pub(super) struct GpuTimingCollector {
246    ring: Option<Ring>,
247    statistics: GpuTimingStatistics,
248}
249
250impl GpuTimingCollector {
251    /// A fixed ring is only constructed after optional TIMESTAMP_QUERY has been
252    /// requested on the actual device. Unrequested timing has no GPU resource cost.
253    pub(super) fn new(device: &wgpu::Device, queue: &wgpu::Queue, requested: bool) -> Self {
254        let feature_enabled =
255            requested && device.features().contains(wgpu::Features::TIMESTAMP_QUERY);
256        let period = if feature_enabled {
257            f64::from(queue.get_timestamp_period())
258        } else {
259            0.0
260        };
261        let enabled = feature_enabled && period.is_finite() && period > 0.0;
262        let status = if enabled {
263            GpuTimingStatus::Enabled
264        } else if requested {
265            GpuTimingStatus::Unavailable
266        } else {
267            GpuTimingStatus::Disabled
268        };
269        let ring = enabled.then(|| Ring {
270            queries: device.create_query_set(&wgpu::QuerySetDescriptor {
271                label: Some("sim-engine bounded GPU timestamps"),
272                ty: wgpu::QueryType::Timestamp,
273                count: (CAPACITY * 2) as u32,
274            }),
275            slots: std::array::from_fn(|_| Slot {
276                resolve: device.create_buffer(&wgpu::BufferDescriptor {
277                    label: Some("sim-engine GPU timestamp resolve"),
278                    size: QUERY_BYTES,
279                    usage: wgpu::BufferUsages::QUERY_RESOLVE | wgpu::BufferUsages::COPY_SRC,
280                    mapped_at_creation: false,
281                }),
282                readback: device.create_buffer(&wgpu::BufferDescriptor {
283                    label: Some("sim-engine GPU timestamp readback"),
284                    size: QUERY_BYTES,
285                    usage: wgpu::BufferUsages::MAP_READ | wgpu::BufferUsages::COPY_DST,
286                    mapped_at_creation: false,
287                }),
288                state: Arc::new(AtomicU8::new(FREE)),
289                request: None,
290            }),
291            period,
292        });
293        Self {
294            ring,
295            statistics: GpuTimingStatistics {
296                status,
297                pending: 0,
298                submitted: 0,
299                completed: 0,
300                dropped: 0,
301                map_failures: 0,
302                invalid_samples: 0,
303                poll_failures: 0,
304                collection_cpu: Duration::ZERO,
305                timestamp_period_nanoseconds: enabled.then_some(period),
306            },
307        }
308    }
309
310    pub(super) fn reserve(&mut self, source: GpuTimingSource) -> Option<GpuTimingReservation> {
311        let ring = self.ring.as_mut()?;
312        let Some(index) = ring
313            .slots
314            .iter()
315            .position(|slot| slot.state.load(Ordering::Acquire) == FREE)
316        else {
317            self.statistics.dropped = self.statistics.dropped.saturating_add(1);
318            return None;
319        };
320        let Ok(sequence) = NEXT_ID.fetch_update(Ordering::Relaxed, Ordering::Relaxed, |value| {
321            value.checked_add(1)
322        }) else {
323            self.statistics.dropped = self.statistics.dropped.saturating_add(1);
324            return None;
325        };
326        let id = GpuTimingId(sequence);
327        let slot = &mut ring.slots[index];
328        slot.request = Some((id, source));
329        slot.state.store(RESERVED, Ordering::Release);
330        Some(GpuTimingReservation {
331            queries: ring.queries.clone(),
332            resolve: slot.resolve.clone(),
333            readback: slot.readback.clone(),
334            state: Arc::clone(&slot.state),
335            query_start: (index * 2) as u32,
336            id,
337            submitted: false,
338        })
339    }
340
341    /// Called immediately after queue submission, before exposing the report ID.
342    pub(super) fn submitted(&mut self, reservation: GpuTimingReservation) -> GpuTimingId {
343        self.statistics.submitted = self.statistics.submitted.saturating_add(1);
344        reservation.submitted()
345    }
346
347    pub(super) fn statistics(&self) -> GpuTimingStatistics {
348        let mut statistics = self.statistics;
349        statistics.pending = self.ring.as_ref().map_or(0, |ring| {
350            ring.slots
351                .iter()
352                .filter(|slot| slot.state.load(Ordering::Acquire) != FREE)
353                .count()
354        });
355        statistics
356    }
357
358    pub(super) fn collect(&mut self, device: &wgpu::Device) -> GpuTimingBatch {
359        let mut batch = GpuTimingBatch::empty();
360        if self.ring.is_none() {
361            return batch;
362        }
363        let started = Instant::now();
364        if device.poll(wgpu::PollType::Poll).is_err() {
365            self.statistics.poll_failures = self.statistics.poll_failures.saturating_add(1);
366            self.statistics.status = GpuTimingStatus::Unavailable;
367            self.statistics.timestamp_period_nanoseconds = None;
368            // A late old-device callback owns only its old atomic cell. Dropping
369            // the complete ring prevents it from completing a reused request.
370            self.ring = None;
371        } else if let Some(ring) = &mut self.ring {
372            for slot in &mut ring.slots {
373                match slot.state.load(Ordering::Acquire) {
374                    READY => {
375                        match slot.readback.get_mapped_range(0..QUERY_BYTES) {
376                            Ok(bytes) => {
377                                if let Some(elapsed) = elapsed_from_bytes(&bytes, ring.period) {
378                                    if let Some((id, source)) = slot.request {
379                                        batch.samples[batch.count] = GpuTimingSample {
380                                            id,
381                                            source,
382                                            elapsed,
383                                        };
384                                        batch.count += 1;
385                                        self.statistics.completed =
386                                            self.statistics.completed.saturating_add(1);
387                                    }
388                                } else {
389                                    self.statistics.invalid_samples =
390                                        self.statistics.invalid_samples.saturating_add(1);
391                                }
392                                // Release the borrowed view before unmapping.
393                                // Failed/cancelled mappings are already unmapped;
394                                // calling unmap there produces a validation error.
395                                drop(bytes);
396                                slot.readback.unmap();
397                            }
398                            Err(_) => {
399                                self.statistics.map_failures =
400                                    self.statistics.map_failures.saturating_add(1);
401                            }
402                        }
403                        slot.request = None;
404                        slot.state.store(FREE, Ordering::Release);
405                    }
406                    FAILED => {
407                        self.statistics.map_failures =
408                            self.statistics.map_failures.saturating_add(1);
409                        slot.request = None;
410                        slot.state.store(FREE, Ordering::Release);
411                    }
412                    _ => {}
413                }
414            }
415        }
416        batch.samples[..batch.count].sort_unstable_by_key(|sample| sample.id);
417        batch.collection_cpu = started.elapsed();
418        self.statistics.collection_cpu = self
419            .statistics
420            .collection_cpu
421            .saturating_add(batch.collection_cpu);
422        batch
423    }
424}
425
426/// Owns its slot until cancellation or submission. Only fixed-size GPU handles
427/// are cloned; the callback captures one bounded completion cell, never a queue.
428pub(super) struct GpuTimingReservation {
429    queries: wgpu::QuerySet,
430    resolve: wgpu::Buffer,
431    readback: wgpu::Buffer,
432    state: Arc<AtomicU8>,
433    query_start: u32,
434    id: GpuTimingId,
435    submitted: bool,
436}
437
438impl GpuTimingReservation {
439    pub(super) fn timestamp_writes(&self) -> wgpu::RenderPassTimestampWrites<'_> {
440        wgpu::RenderPassTimestampWrites {
441            query_set: &self.queries,
442            beginning_of_pass_write_index: Some(self.query_start),
443            end_of_pass_write_index: Some(self.query_start + 1),
444        }
445    }
446
447    /// Called after the timed pass ends, in the same encoder. Individual resolve
448    /// buffers use offset zero, satisfying the stricter query-resolve alignment.
449    pub(super) fn resolve(&self, encoder: &mut wgpu::CommandEncoder) {
450        encoder.resolve_query_set(
451            &self.queries,
452            self.query_start..self.query_start + 2,
453            &self.resolve,
454            0,
455        );
456        encoder.copy_buffer_to_buffer(&self.resolve, 0, &self.readback, 0, QUERY_BYTES);
457    }
458
459    fn submitted(mut self) -> GpuTimingId {
460        self.submitted = true;
461        self.state.store(MAPPING, Ordering::Release);
462        let state = Arc::clone(&self.state);
463        self.readback
464            .map_async(wgpu::MapMode::Read, 0..QUERY_BYTES, move |result| {
465                state.store(
466                    if result.is_ok() { READY } else { FAILED },
467                    Ordering::Release,
468                );
469            });
470        self.id
471    }
472}
473
474impl Drop for GpuTimingReservation {
475    fn drop(&mut self) {
476        if !self.submitted {
477            self.state.store(FREE, Ordering::Release);
478        }
479    }
480}
481
482fn elapsed_from_bytes(bytes: &[u8], period: f64) -> Option<Duration> {
483    let begin = u64::from_ne_bytes(bytes.get(..8)?.try_into().ok()?);
484    let end = u64::from_ne_bytes(bytes.get(8..16)?.try_into().ok()?);
485    let ticks = end.checked_sub(begin)?;
486    if !period.is_finite() || period <= 0.0 {
487        return None;
488    }
489    // Round in nanoseconds first: converting an exact half-nanosecond through
490    // fractional seconds can shift the tie downward through binary rounding.
491    let nanoseconds = (ticks as f64 * period).round();
492    Duration::try_from_secs_f64(nanoseconds / 1_000_000_000.0).ok()
493}
494
495#[cfg(test)]
496mod tests {
497    use super::*;
498
499    fn interval(begin: u64, end: u64) -> [u8; 16] {
500        let mut bytes = [0; 16];
501        bytes[..8].copy_from_slice(&begin.to_ne_bytes());
502        bytes[8..].copy_from_slice(&end.to_ne_bytes());
503        bytes
504    }
505
506    #[test]
507    fn timestamp_conversion_subtracts_integer_ticks_before_float_rounding() {
508        let bytes = interval(u64::MAX - 10, u64::MAX);
509        assert_eq!(
510            elapsed_from_bytes(&bytes, 2.5),
511            Some(Duration::from_nanos(25))
512        );
513        assert_eq!(
514            elapsed_from_bytes(&interval(100, 103), 0.5),
515            Some(Duration::from_nanos(2))
516        );
517        assert_eq!(
518            elapsed_from_bytes(&interval(5, 5), 1.0),
519            Some(Duration::ZERO)
520        );
521    }
522
523    #[test]
524    fn timestamp_conversion_rejects_invalid_data_instead_of_fabricating_zero() {
525        assert_eq!(elapsed_from_bytes(&[0; 15], 1.0), None);
526        assert_eq!(elapsed_from_bytes(&interval(10, 2), 1.0), None);
527        for period in [0.0, -1.0, f64::NAN, f64::INFINITY] {
528            assert_eq!(elapsed_from_bytes(&interval(10, 20), period), None);
529        }
530        assert_eq!(elapsed_from_bytes(&interval(0, u64::MAX), f64::MAX), None);
531    }
532
533    #[test]
534    fn empty_collection_has_bounded_inline_storage_and_no_reported_time() {
535        let batch = GpuTimingBatch::empty();
536        assert!(batch.samples().is_empty());
537        assert_eq!(batch.collection_cpu(), Duration::ZERO);
538        assert_eq!(batch.samples.len(), CAPACITY);
539    }
540
541    /// Root calls this with a separately requested TIMESTAMP_QUERY device when
542    /// supported, and may also call it with its ordinary feature-disabled device.
543    /// The fixture never requests an adapter/window or changes a runtime option.
544    pub(in crate::renderer) fn assert_gpu_timing_contract(
545        device: &wgpu::Device,
546        queue: &wgpu::Queue,
547    ) {
548        let ((mut disabled, unavailable_request), allocations) =
549            crate::test_allocations::count(|| {
550                let mut disabled = GpuTimingCollector::new(device, queue, false);
551                let unavailable_request = disabled.reserve(GpuTimingSource::Scene3d);
552                assert!(disabled.collect(device).samples().is_empty());
553                (disabled, unavailable_request)
554            });
555        assert_eq!(
556            allocations, 0,
557            "disabled GPU diagnostics must allocate nothing"
558        );
559        assert!(unavailable_request.is_none());
560        assert_eq!(disabled.statistics().status(), GpuTimingStatus::Disabled);
561        assert_eq!(disabled.statistics().capacity(), 0);
562        assert_eq!(disabled.statistics().gpu_buffer_bytes(), 0);
563        assert_eq!(disabled.statistics().query_count(), 0);
564        assert_eq!(disabled.statistics().readback_bytes(), 0);
565        assert_eq!(disabled.statistics().collection_cpu(), Duration::ZERO);
566        assert_eq!(disabled.collect(device).collection_cpu(), Duration::ZERO);
567
568        let mut collector = GpuTimingCollector::new(device, queue, true);
569        if !device.features().contains(wgpu::Features::TIMESTAMP_QUERY) {
570            assert_eq!(
571                collector.statistics().status(),
572                GpuTimingStatus::Unavailable
573            );
574            assert!(collector.reserve(GpuTimingSource::FrameComposer).is_none());
575            assert!(collector.collect(device).samples().is_empty());
576            assert_eq!(collector.statistics().gpu_buffer_bytes(), 0);
577            assert_eq!(collector.statistics().query_count(), 0);
578            assert_eq!(collector.statistics().timestamp_period_nanoseconds(), None);
579            assert_eq!(collector.statistics().dropped(), 0);
580            eprintln!("sim-engine GPU timestamps: unavailable on feature-disabled device");
581            return;
582        }
583        assert_eq!(collector.statistics().status(), GpuTimingStatus::Enabled);
584        assert_eq!(collector.statistics().capacity(), CAPACITY);
585        assert_eq!(collector.statistics().gpu_buffer_bytes(), 256);
586        assert_eq!(collector.statistics().query_count(), 16);
587        assert!(collector.collect(device).samples().is_empty());
588
589        let canceled = collector.reserve(GpuTimingSource::Scene3d).unwrap();
590        let canceled_id = canceled.id;
591        assert_eq!(collector.statistics().pending(), 1);
592        drop(canceled);
593        assert_eq!(collector.statistics().pending(), 0);
594        assert_eq!(collector.statistics().submitted(), 0);
595        assert!(collector.collect(device).samples().is_empty());
596
597        let fixture = Workload::new(device);
598        let requests: Vec<_> = (0..CAPACITY)
599            .map(|index| {
600                let source = if index % 2 == 0 {
601                    GpuTimingSource::Scene3d
602                } else {
603                    GpuTimingSource::FrameComposer
604                };
605                let id = fixture.submit(device, queue, &mut collector, source);
606                assert!(id > canceled_id);
607                (id, source)
608            })
609            .collect();
610        // Completed-but-uncollected entries still occupy slots. No hidden poll
611        // or unbounded result queue allows a ninth sample to overwrite them.
612        assert_eq!(collector.statistics().pending(), CAPACITY);
613        assert!(collector.reserve(GpuTimingSource::Scene3d).is_none());
614        assert_eq!(collector.statistics().dropped(), 1);
615        let samples = drain(&mut collector, device, CAPACITY);
616        for (id, source) in requests {
617            let sample = samples.iter().find(|sample| sample.id() == id).unwrap();
618            assert_eq!(sample.source(), source);
619            assert!(
620                sample.elapsed() > Duration::ZERO,
621                "real draw work must be measured"
622            );
623        }
624        assert_eq!(collector.statistics().pending(), 0);
625        assert_eq!(collector.statistics().submitted(), CAPACITY as u64);
626        assert_eq!(collector.statistics().completed(), CAPACITY as u64);
627        assert_eq!(collector.statistics().readback_bytes(), 128);
628        assert_eq!(collector.statistics().map_failures(), 0);
629        assert_eq!(collector.statistics().invalid_samples(), 0);
630        assert_eq!(collector.statistics().poll_failures(), 0);
631        assert!(collector.collect(device).samples().is_empty());
632
633        // Cancel a real async map before collecting it. Depending on scheduling,
634        // cancellation reaches either the map callback or mapped-range access;
635        // both must count one failure and release the slot without a fake sample.
636        let _failed_id = fixture.submit(device, queue, &mut collector, GpuTimingSource::Scene3d);
637        for slot in &collector.ring.as_ref().unwrap().slots {
638            if slot.state.load(Ordering::Acquire) != FREE {
639                slot.readback.unmap();
640            }
641        }
642        let failed = drain(&mut collector, device, 0);
643        assert!(failed.is_empty());
644        assert_eq!(collector.statistics().map_failures(), 1);
645        let reused = fixture.submit(
646            device,
647            queue,
648            &mut collector,
649            GpuTimingSource::FrameComposer,
650        );
651        let samples = drain(&mut collector, device, 1);
652        assert_eq!(samples[0].id(), reused);
653        assert_eq!(samples[0].source(), GpuTimingSource::FrameComposer);
654        assert_eq!(collector.statistics().map_failures(), 1);
655
656        // Replacing a ring while an old map is pending models logical-device
657        // recovery without requiring a second physical adapter. Old callbacks
658        // retain only old cells; their completion cannot enter the new batch.
659        let stale = fixture.submit(device, queue, &mut collector, GpuTimingSource::Scene3d);
660        drop(collector);
661        let mut replacement = GpuTimingCollector::new(device, queue, true);
662        assert!(replacement.collect(device).samples().is_empty());
663        assert_eq!(replacement.statistics().submitted(), 0);
664        assert_eq!(replacement.statistics().completed(), 0);
665        assert_eq!(replacement.statistics().pending(), 0);
666        let current = fixture.submit(
667            device,
668            queue,
669            &mut replacement,
670            GpuTimingSource::FrameComposer,
671        );
672        assert!(current > stale);
673        let samples = drain(&mut replacement, device, 1);
674        assert_eq!(samples[0].id(), current);
675        assert_eq!(samples[0].source(), GpuTimingSource::FrameComposer);
676        assert!(replacement.collect(device).samples().is_empty());
677        eprintln!(
678            "sim-engine GPU timestamp contract: bounded 8-slot correlation, saturation, cancellation, failed map and replacement passed; period_ns={:?}",
679            replacement.statistics().timestamp_period_nanoseconds()
680        );
681    }
682
683    fn drain(
684        collector: &mut GpuTimingCollector,
685        device: &wgpu::Device,
686        expected: usize,
687    ) -> Vec<GpuTimingSample> {
688        let deadline = Instant::now() + Duration::from_secs(20);
689        let mut samples = Vec::new();
690        loop {
691            samples.extend_from_slice(collector.collect(device).samples());
692            if collector.statistics().pending() == 0 {
693                break;
694            }
695            assert!(
696                Instant::now() < deadline,
697                "timestamp callbacks did not finish"
698            );
699            std::thread::yield_now();
700        }
701        assert_eq!(samples.len(), expected);
702        samples
703    }
704
705    struct Workload {
706        _target: wgpu::Texture,
707        view: wgpu::TextureView,
708        pipeline: wgpu::RenderPipeline,
709    }
710
711    impl Workload {
712        fn new(device: &wgpu::Device) -> Self {
713            let target = device.create_texture(&wgpu::TextureDescriptor {
714                label: Some("sim-engine timestamp fixture target"),
715                size: wgpu::Extent3d {
716                    width: 256,
717                    height: 256,
718                    depth_or_array_layers: 1,
719                },
720                mip_level_count: 1,
721                sample_count: 1,
722                dimension: wgpu::TextureDimension::D2,
723                format: wgpu::TextureFormat::Rgba8Unorm,
724                usage: wgpu::TextureUsages::RENDER_ATTACHMENT,
725                view_formats: &[],
726            });
727            let view = target.create_view(&wgpu::TextureViewDescriptor::default());
728            let shader = device.create_shader_module(wgpu::ShaderModuleDescriptor {
729                label: Some("sim-engine timestamp fixture work"),
730                source: wgpu::ShaderSource::Wgsl(
731                    "
732                    @vertex fn vertex(@builtin(vertex_index) index: u32) -> @builtin(position) vec4<f32> {
733                        let positions = array(vec2(-1.0, -1.0), vec2(3.0, -1.0), vec2(-1.0, 3.0));
734                        return vec4(positions[index], 0.0, 1.0);
735                    }
736                    @fragment fn fragment(@builtin(position) position: vec4<f32>) -> @location(0) vec4<f32> {
737                        var value = position.xy / 256.0;
738                        for (var i = 0u; i < 16u; i += 1u) {
739                            value = fract(value * vec2(1.73, 1.31) + vec2(0.11, 0.07));
740                        }
741                        return vec4(value, 0.5, 0.25);
742                    }
743                    "
744                    .into(),
745                ),
746            });
747            let pipeline = device.create_render_pipeline(&wgpu::RenderPipelineDescriptor {
748                label: Some("sim-engine timestamp fixture pipeline"),
749                layout: None,
750                vertex: wgpu::VertexState {
751                    module: &shader,
752                    entry_point: Some("vertex"),
753                    compilation_options: wgpu::PipelineCompilationOptions::default(),
754                    buffers: &[],
755                },
756                primitive: wgpu::PrimitiveState::default(),
757                depth_stencil: None,
758                multisample: wgpu::MultisampleState::default(),
759                fragment: Some(wgpu::FragmentState {
760                    module: &shader,
761                    entry_point: Some("fragment"),
762                    compilation_options: wgpu::PipelineCompilationOptions::default(),
763                    targets: &[Some(wgpu::ColorTargetState {
764                        format: wgpu::TextureFormat::Rgba8Unorm,
765                        blend: Some(wgpu::BlendState::ALPHA_BLENDING),
766                        write_mask: wgpu::ColorWrites::ALL,
767                    })],
768                }),
769                multiview_mask: None,
770                cache: None,
771            });
772            Self {
773                _target: target,
774                view,
775                pipeline,
776            }
777        }
778
779        fn submit(
780            &self,
781            device: &wgpu::Device,
782            queue: &wgpu::Queue,
783            collector: &mut GpuTimingCollector,
784            source: GpuTimingSource,
785        ) -> GpuTimingId {
786            let reservation = collector.reserve(source).unwrap();
787            let mut encoder = device.create_command_encoder(&wgpu::CommandEncoderDescriptor {
788                label: Some("sim-engine timestamp fixture encoder"),
789            });
790            {
791                let mut pass = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
792                    label: Some("sim-engine timestamp fixture pass"),
793                    color_attachments: &[Some(wgpu::RenderPassColorAttachment {
794                        view: &self.view,
795                        depth_slice: None,
796                        resolve_target: None,
797                        ops: wgpu::Operations {
798                            load: wgpu::LoadOp::Clear(wgpu::Color::BLACK),
799                            store: wgpu::StoreOp::Store,
800                        },
801                    })],
802                    depth_stencil_attachment: None,
803                    timestamp_writes: Some(reservation.timestamp_writes()),
804                    occlusion_query_set: None,
805                    multiview_mask: None,
806                });
807                pass.set_pipeline(&self.pipeline);
808                for _ in 0..16 {
809                    pass.draw(0..3, 0..1);
810                }
811            }
812            reservation.resolve(&mut encoder);
813            queue.submit([encoder.finish()]);
814            collector.submitted(reservation)
815        }
816    }
817}