Struct TimestampRing 

pub struct TimestampRing { /* private fields */ }

A ring of per-frame GPU timestamp query sets — see the module header.

Implementations

impl TimestampRing

pub fn new(device: &Device, queue: &Queue, spans: usize, label: &str) -> Self

A ring timing spans named spans per frame, over DEFAULT_PASS_CAPACITY passes.

Inert — no GPU resource created at all — when device was not created with wgpu::Features::TIMESTAMP_QUERY, which is every build that did not compile perf-trace in and every adapter that does not offer the feature.

pub fn with_capacity( device: &Device, queue: &Queue, spans: usize, passes: usize, label: &str, ) -> Self

Self::new with an explicit per-frame pass capacity.

pub fn inert(spans: usize) -> Self

A ring that measures nothing, for a device without TIMESTAMP_QUERY and for a caller that wants the gpu_q=0 shape without a GPU at all.

pub fn is_active(&self) -> bool

Whether this ring holds real query sets, i.e. whether a frame line should report gpu_q=1.

pub fn spans(&self) -> usize

How many named spans a frame is split into.

pub fn timestamp_period_ns(&self) -> f32

Nanoseconds per timestamp tick, 0.0 on an inert ring.

pub fn latest(&self) -> Option<GpuFrameSpans>

The most recently harvested frame’s spans, or None before the first reading lands (and forever on an inert ring).

The reading lags the CPU frame that asks for it by up to RING_FRAMES frames — the price of never blocking on a map. In steady state one fresh reading lands per frame, so the lag is a constant offset rather than a gap in the series; Self::harvested is how a consumer tells a repeat from a fresh reading.

pub fn harvested(&self) -> u64

How many frame readings this ring has harvested.

pub fn begin_frame(&mut self, device: &Device)

Advances onto the next slot and harvests whatever the frame that last used it left mapped.

Polls device once, without blocking: a map that has not landed leaves its slot alone and the frame goes untimed rather than stalling on it.

pub fn pass_writes(&self, span: usize) -> Option<RenderPassTimestampWrites<'_>>

The timestamp_writes for one pass belonging to span.

Each call takes a fresh query pair, so a span made of several passes (the frame’s own strip passes, a layer’s page rounds) sums correctly. None — an untimed pass — when the ring is inert, the slot was not free this frame, span is out of range, or the frame has already used its pass capacity.

pub fn resolve(&self, encoder: &mut CommandEncoder)

Records, into the caller’s encoder, the query resolve and the copy into the mappable readback buffer of every earlier frame whose GPU work has completed. The caller submits that encoder.

Never the frame in progress: its passes have not run yet when this encoder is submitted, and a resolve in the same command buffer can read the last pass’s end sample before the GPU writes it (see the module doc’s Resolved only once the frame’s GPU work has completed). Works whether or not this frame is itself timed, so a run of untimed frames still drains the ring.

Only the pairs actually taken are resolved: an untouched query resolves to whatever the driver left there, and reading it back would be inventing a span rather than measuring one.

pub fn end_frame(&mut self)

Call after submitting the encoder Self::resolve was recorded into.

Requests the map of every slot that encoder resolved — what a later Self::begin_frame harvests — and asks the queue to report when this frame’s own work completes, which is what lets a later frame resolve it.

Allocation per timed frame is unchanged from a same-frame resolve: one boxed map callback and one boxed completion callback, each holding a clone of an Arc the slot allocated once.

pub fn abandon_frame(&mut self)

Closes a frame that was refused before its encoder was submitted.

Nothing was recorded and nothing will be, so the slot goes straight back to idle without waiting on a completion — resolving queries no pass ever wrote would harvest an earlier frame’s ticks as if they were this one’s. Any earlier frame’s resolve Self::resolve put into that unsubmitted encoder is forgotten too, so the next frame records it again.

Trait Implementations

impl Debug for TimestampRing

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.