wgpu_examples/timestamp_queries/
mod.rs

1//! Sample demonstrating different kinds of gpu timestamp queries.
2//!
3//! Timestamp queries are typically used to profile how long certain operations take on the GPU.
4//! wgpu has several ways of performing gpu timestamp queries:
5//! * passing `wgpu::RenderPassTimestampWrites`/`wgpu::ComputePassTimestampWrites` during render/compute pass creation.
6//!   This writes timestamps for the beginning and end of a given pass.
7//!   (enabled with wgpu::Features::TIMESTAMP_QUERY)
8//! * `wgpu::CommandEncoder::write_timestamp` writes a timestamp between any commands recorded on an encoder.
9//!   (enabled with wgpu::Features::TIMESTAMP_QUERY_INSIDE_ENCODERS)
10//! * `wgpu::RenderPass/ComputePass::write_timestamp` writes a timestamp within commands of a render pass.
11//!   Note that some GPU architectures do not support this.
12//!   (native only, enabled with wgpu::Features::TIMESTAMP_QUERY_INSIDE_PASSES)
13//!
14//! Any timestamp is written to a `wgpu::QuerySet` which needs to be resolved to a buffer with `wgpu::BufferUsages::QUERY_RESOLVE`.
15//! Since this usage is incompatible with `wgpu::BufferUsages::MAP_READ` we need to copy the resolved timestamps to a separate buffer afterwards.
16//!
17//! The period, i.e. the unit of time, of the timestamps in wgpu is undetermined and needs to be queried with `wgpu::Queue::get_timestamp_period`
18//! in order to get comparable results.
19
20use wgpu::util::DeviceExt;
21
22struct Queries {
23    set: wgpu::QuerySet,
24    resolve_buffer: wgpu::Buffer,
25    destination_buffer: wgpu::Buffer,
26    num_queries: u64,
27    next_unused_query: u32,
28}
29
30struct QueryResults {
31    encoder_timestamps: [u64; 2],
32    render_start_end_timestamps: [u64; 2],
33    render_inside_timestamp: Option<u64>,
34    compute_start_end_timestamps: [u64; 2],
35    compute_inside_timestamp: Option<u64>,
36}
37
38impl QueryResults {
39    // Queries:
40    // * encoder timestamp start
41    // * encoder timestamp end
42    // * render start
43    // * render in-between (optional)
44    // * render end
45    // * compute start
46    // * compute in-between (optional)
47    // * compute end
48    const NUM_QUERIES: u64 = 8;
49
50    #[expect(
51        clippy::redundant_closure,
52        reason = "false positive for `get_next_slot`, which needs to be used by reference"
53    )]
54    fn from_raw_results(timestamps: Vec<u64>, timestamps_inside_passes: bool) -> Self {
55        assert_eq!(timestamps.len(), Self::NUM_QUERIES as usize);
56
57        let mut next_slot = 0;
58        let mut get_next_slot = || {
59            let slot = timestamps[next_slot];
60            next_slot += 1;
61            slot
62        };
63
64        let mut encoder_timestamps = [0, 0];
65        encoder_timestamps[0] = get_next_slot();
66        let render_start_end_timestamps = [get_next_slot(), get_next_slot()];
67        let render_inside_timestamp = timestamps_inside_passes.then(|| get_next_slot());
68        let compute_start_end_timestamps = [get_next_slot(), get_next_slot()];
69        let compute_inside_timestamp = timestamps_inside_passes.then(|| get_next_slot());
70        encoder_timestamps[1] = get_next_slot();
71
72        QueryResults {
73            encoder_timestamps,
74            render_start_end_timestamps,
75            render_inside_timestamp,
76            compute_start_end_timestamps,
77            compute_inside_timestamp,
78        }
79    }
80
81    fn print(&self, queue: &wgpu::Queue) {
82        let period = queue.get_timestamp_period();
83        let elapsed_us = |start, end: u64| end.wrapping_sub(start) as f64 * period as f64 / 1000.0;
84
85        println!(
86            "Elapsed time before render until after compute: {:.2} μs",
87            elapsed_us(self.encoder_timestamps[0], self.encoder_timestamps[1]),
88        );
89        println!(
90            "Elapsed time render pass: {:.2} μs",
91            elapsed_us(
92                self.render_start_end_timestamps[0],
93                self.render_start_end_timestamps[1]
94            )
95        );
96        if let Some(timestamp) = self.render_inside_timestamp {
97            println!(
98                "Elapsed time first triangle: {:.2} μs",
99                elapsed_us(self.render_start_end_timestamps[0], timestamp)
100            );
101        }
102        println!(
103            "Elapsed time compute pass: {:.2} μs",
104            elapsed_us(
105                self.compute_start_end_timestamps[0],
106                self.compute_start_end_timestamps[1]
107            )
108        );
109        if let Some(timestamp) = self.compute_inside_timestamp {
110            println!(
111                "Elapsed time after first dispatch: {:.2} μs",
112                elapsed_us(self.compute_start_end_timestamps[0], timestamp)
113            );
114        }
115    }
116}
117
118impl Queries {
119    fn new(device: &wgpu::Device, num_queries: u64) -> Self {
120        Queries {
121            set: device.create_query_set(&wgpu::QuerySetDescriptor {
122                label: Some("Timestamp query set"),
123                count: num_queries as _,
124                ty: wgpu::QueryType::Timestamp,
125            }),
126            resolve_buffer: device.create_buffer(&wgpu::BufferDescriptor {
127                label: Some("query resolve buffer"),
128                size: size_of::<u64>() as u64 * num_queries,
129                usage: wgpu::BufferUsages::COPY_SRC | wgpu::BufferUsages::QUERY_RESOLVE,
130                mapped_at_creation: false,
131            }),
132            destination_buffer: device.create_buffer(&wgpu::BufferDescriptor {
133                label: Some("query dest buffer"),
134                size: size_of::<u64>() as u64 * num_queries,
135                usage: wgpu::BufferUsages::COPY_DST | wgpu::BufferUsages::MAP_READ,
136                mapped_at_creation: false,
137            }),
138            num_queries,
139            next_unused_query: 0,
140        }
141    }
142
143    fn resolve(&self, encoder: &mut wgpu::CommandEncoder) {
144        encoder.resolve_query_set(
145            &self.set,
146            // TODO(https://github.com/gfx-rs/wgpu/issues/3993): Musn't be larger than the number valid queries in the set.
147            0..self.next_unused_query,
148            &self.resolve_buffer,
149            0,
150        );
151        encoder.copy_buffer_to_buffer(
152            &self.resolve_buffer,
153            0,
154            &self.destination_buffer,
155            0,
156            self.resolve_buffer.size(),
157        );
158    }
159
160    fn wait_for_results(&self, device: &wgpu::Device) -> Vec<u64> {
161        self.destination_buffer
162            .slice(..)
163            .map_async(wgpu::MapMode::Read, |_| ());
164        device.poll(wgpu::PollType::wait()).unwrap();
165
166        let timestamps = {
167            let timestamp_view = self
168                .destination_buffer
169                .slice(..(size_of::<u64>() as wgpu::BufferAddress * self.num_queries))
170                .get_mapped_range();
171            bytemuck::cast_slice(&timestamp_view).to_vec()
172        };
173
174        self.destination_buffer.unmap();
175
176        timestamps
177    }
178}
179
180async fn run() {
181    // Instantiates instance of wgpu
182    let instance = wgpu::Instance::new(&wgpu::InstanceDescriptor::from_env_or_default());
183
184    // `request_adapter` instantiates the general connection to the GPU
185    let adapter = instance
186        .request_adapter(&wgpu::RequestAdapterOptions::default())
187        .await
188        .expect("Failed to request adapter.");
189
190    // Check timestamp features.
191    let features = adapter.features()
192        & (wgpu::Features::TIMESTAMP_QUERY | wgpu::Features::TIMESTAMP_QUERY_INSIDE_PASSES);
193    if features.contains(wgpu::Features::TIMESTAMP_QUERY) {
194        println!("Adapter supports timestamp queries.");
195    } else {
196        println!("Adapter does not support timestamp queries, aborting.");
197        return;
198    }
199    let timestamps_inside_passes = features.contains(wgpu::Features::TIMESTAMP_QUERY_INSIDE_PASSES);
200    if timestamps_inside_passes {
201        println!("Adapter supports timestamp queries within passes.");
202    } else {
203        println!("Adapter does not support timestamp queries within passes.");
204    }
205
206    // `request_device` instantiates the feature specific connection to the GPU, defining some parameters,
207    //  `features` being the available features.
208    let (device, queue) = adapter
209        .request_device(&wgpu::DeviceDescriptor {
210            label: None,
211            required_features: features,
212            required_limits: wgpu::Limits::downlevel_defaults(),
213            experimental_features: wgpu::ExperimentalFeatures::disabled(),
214            memory_hints: wgpu::MemoryHints::MemoryUsage,
215            trace: wgpu::Trace::Off,
216        })
217        .await
218        .unwrap();
219
220    let queries = submit_render_and_compute_pass_with_queries(&device, &queue);
221    let raw_results = queries.wait_for_results(&device);
222    println!("Raw timestamp buffer contents: {raw_results:?}");
223    QueryResults::from_raw_results(raw_results, timestamps_inside_passes).print(&queue);
224}
225
226fn submit_render_and_compute_pass_with_queries(
227    device: &wgpu::Device,
228    queue: &wgpu::Queue,
229) -> Queries {
230    let mut encoder =
231        device.create_command_encoder(&wgpu::CommandEncoderDescriptor { label: None });
232
233    let mut queries = Queries::new(device, QueryResults::NUM_QUERIES);
234    let shader = device.create_shader_module(wgpu::include_wgsl!("shader.wgsl"));
235
236    if device
237        .features()
238        .contains(wgpu::Features::TIMESTAMP_QUERY_INSIDE_ENCODERS)
239    {
240        encoder.write_timestamp(&queries.set, queries.next_unused_query);
241        queries.next_unused_query += 1;
242    }
243
244    // Render two triangles and profile it.
245    render_pass(
246        device,
247        &shader,
248        &mut encoder,
249        &queries.set,
250        &mut queries.next_unused_query,
251    );
252
253    // Compute a hash function on a single thread a bunch of time and profile it.
254    compute_pass(
255        device,
256        &shader,
257        &mut encoder,
258        &queries.set,
259        &mut queries.next_unused_query,
260    );
261
262    if device
263        .features()
264        .contains(wgpu::Features::TIMESTAMP_QUERY_INSIDE_ENCODERS)
265    {
266        encoder.write_timestamp(&queries.set, queries.next_unused_query);
267        queries.next_unused_query += 1;
268    }
269
270    queries.resolve(&mut encoder);
271    queue.submit(Some(encoder.finish()));
272
273    queries
274}
275
276fn compute_pass(
277    device: &wgpu::Device,
278    module: &wgpu::ShaderModule,
279    encoder: &mut wgpu::CommandEncoder,
280    query_set: &wgpu::QuerySet,
281    next_unused_query: &mut u32,
282) {
283    let storage_buffer = device.create_buffer_init(&wgpu::util::BufferInitDescriptor {
284        label: Some("Storage Buffer"),
285        contents: bytemuck::cast_slice(&[42]),
286        usage: wgpu::BufferUsages::STORAGE,
287    });
288    let compute_pipeline = device.create_compute_pipeline(&wgpu::ComputePipelineDescriptor {
289        label: None,
290        layout: None,
291        module,
292        entry_point: Some("main_cs"),
293        compilation_options: Default::default(),
294        cache: None,
295    });
296    let bind_group_layout = compute_pipeline.get_bind_group_layout(0);
297    let bind_group = device.create_bind_group(&wgpu::BindGroupDescriptor {
298        label: None,
299        layout: &bind_group_layout,
300        entries: &[wgpu::BindGroupEntry {
301            binding: 0,
302            resource: storage_buffer.as_entire_binding(),
303        }],
304    });
305
306    let mut cpass = encoder.begin_compute_pass(&wgpu::ComputePassDescriptor {
307        label: None,
308        timestamp_writes: Some(wgpu::ComputePassTimestampWrites {
309            query_set,
310            beginning_of_pass_write_index: Some(*next_unused_query),
311            end_of_pass_write_index: Some(*next_unused_query + 1),
312        }),
313    });
314    *next_unused_query += 2;
315    cpass.set_pipeline(&compute_pipeline);
316    cpass.set_bind_group(0, &bind_group, &[]);
317    cpass.dispatch_workgroups(1, 1, 1);
318    if device
319        .features()
320        .contains(wgpu::Features::TIMESTAMP_QUERY_INSIDE_PASSES)
321    {
322        cpass.write_timestamp(query_set, *next_unused_query);
323        *next_unused_query += 1;
324    }
325    cpass.dispatch_workgroups(1, 1, 1);
326}
327
328fn render_pass(
329    device: &wgpu::Device,
330    module: &wgpu::ShaderModule,
331    encoder: &mut wgpu::CommandEncoder,
332    query_set: &wgpu::QuerySet,
333    next_unused_query: &mut u32,
334) {
335    let format = wgpu::TextureFormat::Rgba8Unorm;
336
337    let pipeline_layout = device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
338        label: None,
339        bind_group_layouts: &[],
340        push_constant_ranges: &[],
341    });
342
343    let render_pipeline = device.create_render_pipeline(&wgpu::RenderPipelineDescriptor {
344        label: None,
345        layout: Some(&pipeline_layout),
346        vertex: wgpu::VertexState {
347            module,
348            entry_point: Some("vs_main"),
349            compilation_options: Default::default(),
350            buffers: &[],
351        },
352        fragment: Some(wgpu::FragmentState {
353            module,
354            entry_point: Some("fs_main"),
355            compilation_options: Default::default(),
356            targets: &[Some(format.into())],
357        }),
358        primitive: wgpu::PrimitiveState::default(),
359        depth_stencil: None,
360        multisample: wgpu::MultisampleState::default(),
361        multiview: None,
362        cache: None,
363    });
364    let render_target = device.create_texture(&wgpu::TextureDescriptor {
365        label: Some("rendertarget"),
366        size: wgpu::Extent3d {
367            width: 512,
368            height: 512,
369            depth_or_array_layers: 1,
370        },
371        mip_level_count: 1,
372        sample_count: 1,
373        dimension: wgpu::TextureDimension::D2,
374        format,
375        usage: wgpu::TextureUsages::RENDER_ATTACHMENT,
376        view_formats: &[format],
377    });
378    let render_target_view = render_target.create_view(&wgpu::TextureViewDescriptor::default());
379
380    let mut rpass = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
381        label: None,
382        color_attachments: &[Some(wgpu::RenderPassColorAttachment {
383            view: &render_target_view,
384            depth_slice: None,
385            resolve_target: None,
386            ops: wgpu::Operations {
387                load: wgpu::LoadOp::Clear(wgpu::Color::GREEN),
388                store: wgpu::StoreOp::Store,
389            },
390        })],
391        depth_stencil_attachment: None,
392        timestamp_writes: Some(wgpu::RenderPassTimestampWrites {
393            query_set,
394            beginning_of_pass_write_index: Some(*next_unused_query),
395            end_of_pass_write_index: Some(*next_unused_query + 1),
396        }),
397        occlusion_query_set: None,
398    });
399    *next_unused_query += 2;
400
401    rpass.set_pipeline(&render_pipeline);
402
403    rpass.draw(0..3, 0..1);
404    if device
405        .features()
406        .contains(wgpu::Features::TIMESTAMP_QUERY_INSIDE_PASSES)
407    {
408        rpass.write_timestamp(query_set, *next_unused_query);
409        *next_unused_query += 1;
410    }
411
412    rpass.draw(0..3, 0..1);
413}
414
415pub fn main() {
416    #[cfg(not(target_arch = "wasm32"))]
417    {
418        env_logger::init();
419        pollster::block_on(run());
420    }
421    #[cfg(target_arch = "wasm32")]
422    {
423        std::panic::set_hook(Box::new(console_error_panic_hook::hook));
424        console_log::init().expect("could not initialize logger");
425        wasm_bindgen_futures::spawn_local(run());
426    }
427}
428
429#[cfg(test)]
430pub mod tests {
431    use wgpu_test::{gpu_test, FailureCase, GpuTestConfiguration};
432
433    use super::{submit_render_and_compute_pass_with_queries, QueryResults};
434
435    #[gpu_test]
436    pub static TIMESTAMPS_PASS_BOUNDARIES: GpuTestConfiguration = GpuTestConfiguration::new()
437        .parameters(
438            wgpu_test::TestParameters::default()
439                .limits(wgpu::Limits::downlevel_defaults())
440                .features(wgpu::Features::TIMESTAMP_QUERY),
441        )
442        .run_sync(|ctx| test_timestamps(ctx, false, false));
443
444    #[gpu_test]
445    pub static TIMESTAMPS_ENCODER: GpuTestConfiguration = GpuTestConfiguration::new()
446        .parameters(
447            wgpu_test::TestParameters::default()
448                .limits(wgpu::Limits::downlevel_defaults())
449                .features(
450                    wgpu::Features::TIMESTAMP_QUERY
451                        | wgpu::Features::TIMESTAMP_QUERY_INSIDE_ENCODERS,
452                )
453                // see https://github.com/gfx-rs/wgpu/issues/2521
454                .expect_fail(FailureCase::always().panic("unexpected timestamp").flaky()),
455        )
456        .run_sync(|ctx| test_timestamps(ctx, true, false));
457
458    #[gpu_test]
459    pub static TIMESTAMPS_PASSES: GpuTestConfiguration = GpuTestConfiguration::new()
460        .parameters(
461            wgpu_test::TestParameters::default()
462                .limits(wgpu::Limits::downlevel_defaults())
463                .features(
464                    wgpu::Features::TIMESTAMP_QUERY
465                        | wgpu::Features::TIMESTAMP_QUERY_INSIDE_ENCODERS
466                        | wgpu::Features::TIMESTAMP_QUERY_INSIDE_PASSES,
467                )
468                // see https://github.com/gfx-rs/wgpu/issues/2521
469                .expect_fail(FailureCase::always().panic("unexpected timestamp").flaky()),
470        )
471        .run_sync(|ctx| test_timestamps(ctx, true, true));
472
473    fn test_timestamps(
474        ctx: wgpu_test::TestingContext,
475        timestamps_on_encoder: bool,
476        timestamps_inside_passes: bool,
477    ) {
478        let queries = submit_render_and_compute_pass_with_queries(&ctx.device, &ctx.queue);
479        let raw_results = queries.wait_for_results(&ctx.device);
480        let QueryResults {
481            encoder_timestamps,
482            render_start_end_timestamps,
483            render_inside_timestamp,
484            compute_start_end_timestamps,
485            compute_inside_timestamp,
486        } = QueryResults::from_raw_results(raw_results, timestamps_inside_passes);
487
488        // Timestamps may wrap around, so can't really only reason about deltas!
489        // Making things worse, deltas are allowed to be zero.
490        let render_delta =
491            render_start_end_timestamps[1].wrapping_sub(render_start_end_timestamps[0]);
492        let compute_delta =
493            compute_start_end_timestamps[1].wrapping_sub(compute_start_end_timestamps[0]);
494        let encoder_delta = encoder_timestamps[1].wrapping_sub(encoder_timestamps[0]);
495
496        if timestamps_on_encoder {
497            assert!(encoder_delta > 0, "unexpected timestamp");
498            assert!(
499                encoder_delta >= render_delta + compute_delta,
500                "unexpected timestamp"
501            );
502        }
503        if let Some(render_inside_timestamp) = render_inside_timestamp {
504            assert!(
505                render_inside_timestamp >= render_start_end_timestamps[0],
506                "unexpected timestamp"
507            );
508            assert!(
509                render_inside_timestamp <= render_start_end_timestamps[1],
510                "unexpected timestamp"
511            );
512        }
513        if let Some(compute_inside_timestamp) = compute_inside_timestamp {
514            assert!(
515                compute_inside_timestamp >= compute_start_end_timestamps[0],
516                "unexpected timestamp"
517            );
518            assert!(
519                compute_inside_timestamp <= compute_start_end_timestamps[1],
520                "unexpected timestamp"
521            );
522        }
523    }
524}