Struct GpuTimestampProfiler 

pub struct GpuTimestampProfiler { /* private fields */ }

Opt-in GPU timestamp profiler backed by a single wgpu::QuerySet.

Each pass consumes two adjacent timestamp slots (start, end). After recording, call Self::resolve to copy the query results into a staging buffer, map it, and decode the raw u64 timestamps into PassTiming structs.

See the module-level documentation for usage.

Implementations

impl GpuTimestampProfiler

pub fn try_new(ctx: &GpuContext, capacity: u32) -> Option<Self>

Attempt to construct a profiler with capacity timestamp slots.

capacity is rounded up to the nearest even number (and clamped to a minimum of 2) because each pass uses one start slot and one end slot.

Returns None if the adapter does not support both wgpu::Features::TIMESTAMP_QUERY and wgpu::Features::TIMESTAMP_QUERY_INSIDE_ENCODERS. Callers must enable these features in the crate::context::GpuContextConfig used to create the context (see the module-level docs).

pub fn dummy(period_ns: f32) -> Self

Test-only constructor that allocates no GPU resources.

Useful for unit tests that need to exercise the PassTiming types or the disabled-path branches without touching wgpu. All recording methods become no-ops and Self::resolve returns an empty vector.

pub fn is_enabled(&self) -> bool

Returns true if this profiler is actively recording GPU timestamps.

pub fn period_ns(&self) -> f32

Timestamp period in nanoseconds per tick, as reported by wgpu::Queue::get_timestamp_period.

pub fn capacity(&self) -> u32

Total number of timestamp slots available in the query set.

pub fn next_slot(&self) -> u32

Index of the next free start slot. Always even when the profiler is in a consistent recording state.

pub fn begin_pass( &mut self, encoder: &mut CommandEncoder, label: &str, ) -> Option<u32>

Records the start timestamp for a pass labelled label.

Returns the slot index that was used (which is also the index of the start–end pair). Pass this value to Self::end_pass to record the matching end timestamp.

Returns None when:

• the profiler is disabled (constructed via Self::dummy), or
• the query set capacity has been exhausted.

pub fn end_pass(&self, encoder: &mut CommandEncoder, start_slot: u32)

Records the end timestamp for a pass at start_slot + 1.

Silently no-ops when the profiler is disabled or has no query set. The caller is responsible for passing the slot index returned by the matching Self::begin_pass call.

pub fn resolve(&mut self, ctx: &GpuContext) -> GpuResult<Vec<PassTiming>>

Resolves all recorded timestamps and decodes them into per-pass PassTiming entries.

Steps:

1. Encodes a resolve_query_set + copy_buffer_to_buffer command sequence to move the timestamps from the GPU-side query set into a CPU-mappable staging buffer.
2. Submits the command buffer.
3. Maps the staging buffer for reading, blocking on wgpu::Device::poll until the mapping completes.
4. Converts each raw u64 tick to nanoseconds using Self::period_ns and computes duration_us.

Returns an empty Vec if the profiler is disabled or no passes were recorded.

Errors

Returns GpuError::ExecutionFailed when the device poll, the buffer mapping callback, or the channel that delivers the mapping result fails.

pub fn pass_labels(&self) -> &[String]

Returns the recorded pass labels in registration order.

pub fn reset(&mut self)

Clears all recorded labels and resets the next-slot pointer back to zero, allowing the same query-set capacity to be re-used for another round of measurements.

Note that the underlying wgpu::QuerySet storage is not re-allocated; previously written timestamps remain in the resolve buffer until overwritten by subsequent write_timestamp calls.

Trait Implementations

impl Debug for GpuTimestampProfiler

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

Formats the value using the given formatter.