From 592736efa032dac220167df0678fa074f5e07fcc Mon Sep 17 00:00:00 2001 From: Kevin Reid Date: Mon, 22 Dec 2025 09:04:28 -0800 Subject: [PATCH] Expand query set documentation. This is intended to provide all the information necessary to make use of occlusion and timestamp queries, without needing to read example code or the WebGPU spec. --- CHANGELOG.md | 6 +++ wgpu-types/src/lib.rs | 71 ++++++++++++++++++++++++++------- wgpu/src/api/command_encoder.rs | 15 +++++-- wgpu/src/api/compute_pass.rs | 5 +++ wgpu/src/api/query_set.rs | 19 ++++++++- wgpu/src/api/render_pass.rs | 5 +++ 6 files changed, 101 insertions(+), 20 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d43658d5b..f43d84da9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -45,6 +45,12 @@ Bottom level categories: - Added support for cooperative load/store operations in shaders. Currently only WGSL on the input and SPIR-V, METAL, and WGSL on the output are supported. By @kvark in [#8251](https://github.com/gfx-rs/wgpu/issues/8251). +### Documentation + +#### General + +- Expanded documentation of `QuerySet`, `QueryType`, and `resolve_query_set()` describing how to use queries. By @kpreid in [#8776](https://github.com/gfx-rs/wgpu/pull/8776). + ## v28.0.0 (2025-12-17) ### Major Changes diff --git a/wgpu-types/src/lib.rs b/wgpu-types/src/lib.rs index 8501a6c82..bd98d2ded 100644 --- a/wgpu-types/src/lib.rs +++ b/wgpu-types/src/lib.rs @@ -203,7 +203,7 @@ pub const IMMEDIATE_DATA_ALIGNMENT: u32 = 4; #[doc(hidden)] pub const STORAGE_BINDING_SIZE_ALIGNMENT: u32 = 4; -/// Maximum queries in a [`QuerySetDescriptor`]. +/// Maximum number of query result slots that can be requested in a [`QuerySetDescriptor`]. pub const QUERY_SET_MAX_QUERIES: u32 = 4096; /// Size in bytes of a single piece of [query] data. @@ -467,7 +467,7 @@ pub struct QuerySetDescriptor { pub label: L, /// Kind of query that this query set should contain. pub ty: QueryType, - /// Total count of queries the set contains. Must not be zero. + /// Total number of query result slots the set contains. Must not be zero. /// Must not be greater than [`QUERY_SET_MAX_QUERIES`]. pub count: u32, } @@ -484,7 +484,9 @@ impl QuerySetDescriptor { } } -/// Type of query contained in a [`QuerySet`]. +/// Type of queries contained in a [`QuerySet`]. +/// +/// Each query set may contain any number of queries, but they must all be of the same type. /// /// Corresponds to [WebGPU `GPUQueryType`]( /// https://gpuweb.github.io/gpuweb/#enumdef-gpuquerytype). @@ -493,27 +495,66 @@ impl QuerySetDescriptor { #[derive(Copy, Clone, Debug)] #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))] pub enum QueryType { - /// Query returns a single 64-bit number, serving as an occlusion boolean. + /// An occlusion query reports whether any of the fragments drawn within the scope of the query + /// passed all per-fragment tests (i.e. were not occluded). + /// + /// Occlusion queries are performed by setting [`RenderPassDescriptor::occlusion_query_set`], + /// then calling [`RenderPass::begin_occlusion_query()`] and + /// [`RenderPass::end_occlusion_query()`]. + /// The query writes to a single result slot in the query set, whose value will be either 0 or 1 + /// as a boolean. + /// + #[doc = link_to_wgpu_docs!(["`RenderPassDescriptor::occlusion_query_set`"]: "struct.RenderPassDescriptor.html#structfield.occlusion_query_set")] + #[doc = link_to_wgpu_docs!(["`RenderPass::begin_occlusion_query()`"]: "struct.RenderPass.html#structfield.begin_occlusion_query")] + #[doc = link_to_wgpu_docs!(["`RenderPass::end_occlusion_query()`"]: "struct.RenderPass.html#structfield.end_occlusion_query")] Occlusion, - /// Query returns up to 5 64-bit numbers based on the given flags. + + /// A timestamp query records a GPU-timestamp value + /// at which a certain command started or finished executing. /// - /// See [`PipelineStatisticsTypes`]'s documentation for more information - /// on how they get resolved. + /// Timestamp queries are performed by any one of: + /// * Setting [`ComputePassDescriptor::timestamp_writes`] + /// * Setting [`RenderPassDescriptor::timestamp_writes`] + /// * Calling [`CommandEncoder::write_timestamp()`] + /// * Calling [`RenderPass::write_timestamp()`] + /// * Calling [`ComputePass::write_timestamp()`] /// - /// [`Features::PIPELINE_STATISTICS_QUERY`] must be enabled to use this query type. - PipelineStatistics(PipelineStatisticsTypes), - /// Query returns a 64-bit number indicating the GPU-timestamp - /// where all previous commands have finished executing. - /// - /// Must be multiplied by [`Queue::get_timestamp_period`][Qgtp] to get - /// the value in nanoseconds. Absolute values have no meaning, - /// but timestamps can be subtracted to get the time it takes + /// Each timestamp query writes to a single result slot in the query set. + /// The timestamp value must be multiplied by [`Queue::get_timestamp_period()`][Qgtp] to get + /// the time in nanoseconds. + /// Absolute values have no meaning, but timestamps can be subtracted to get the time it takes /// for a string of operations to complete. + /// Timestamps may overflow and wrap to 0, resulting in occasional spurious negative deltas. + /// + /// Additionally, passes may be executed in parallel or out of the order they were submitted; + /// this does not affect their results but is observable via these timestamps. /// /// [`Features::TIMESTAMP_QUERY`] must be enabled to use this query type. /// + #[doc = link_to_wgpu_docs!(["`CommandEncoder::write_timestamp()`"]: "struct.CommandEncoder.html#method.write_timestamp")] + #[doc = link_to_wgpu_docs!(["`ComputePass::write_timestamp()`"]: "struct.ComputePass.html#method.write_timestamp")] + #[doc = link_to_wgpu_docs!(["`RenderPass::write_timestamp()`"]: "struct.RenderPass.html#method.write_timestamp")] + #[doc = link_to_wgpu_docs!(["`ComputePassDescriptor::timestamp_writes`"]: "struct.ComputePassDescriptor.html#structfield.timestamp_writes")] + #[doc = link_to_wgpu_docs!(["`RenderPassDescriptor::timestamp_writes`"]: "struct.RenderPassDescriptor.html#structfield.timestamp_writes")] #[doc = link_to_wgpu_docs!(["Qgtp"]: "struct.Queue.html#method.get_timestamp_period")] Timestamp, + + /// A pipeline statistics query records information about the execution of pipelines; + /// see [`PipelineStatisticsTypes`]'s documentation for details. + /// + /// Pipeline statistics queries are performed by: + /// + /// * [`ComputePass::begin_pipeline_statistics_query()`] + /// * [`RenderPass::begin_pipeline_statistics_query()`] + /// + /// A single query may occupy up to 5 result slots in the query set, based on the flags given + /// here. + /// + /// [`Features::PIPELINE_STATISTICS_QUERY`] must be enabled to use this query type. + /// + #[doc = link_to_wgpu_docs!(["`ComputePass::begin_pipeline_statistics_query()`"]: "struct.ComputePass.html#method.begin_pipeline_statistics_query")] + #[doc = link_to_wgpu_docs!(["`RenderPass::begin_pipeline_statistics_query()`"]: "struct.RenderPass.html#method.begin_pipeline_statistics_query")] + PipelineStatistics(PipelineStatisticsTypes), } bitflags::bitflags! { diff --git a/wgpu/src/api/command_encoder.rs b/wgpu/src/api/command_encoder.rs index 9f3daf06a..ac4486ae2 100644 --- a/wgpu/src/api/command_encoder.rs +++ b/wgpu/src/api/command_encoder.rs @@ -217,12 +217,19 @@ impl CommandEncoder { self.inner.pop_debug_group(); } - /// Resolves a query set, writing the results into the supplied destination buffer. + /// Copies query results stored in `query_set` into `destination` so that they can be read + /// by compute shaders or buffer operations. /// - /// Occlusion and timestamp queries are 8 bytes each (see [`crate::QUERY_SIZE`]). For pipeline statistics queries, - /// see [`PipelineStatisticsTypes`] for more information. + /// * `query_range` is the range of query result indices to copy from `query_set`. + /// Occlusion and timestamp queries occupy 1 result index each; + /// for pipeline statistics queries, see [`PipelineStatisticsTypes`]. + /// * `destination_offset` is the offset within `destination` to start writing at. + /// It must be a multiple of [`QUERY_RESOLVE_BUFFER_ALIGNMENT`]. /// - /// `destination_offset` must be aligned to [`QUERY_RESOLVE_BUFFER_ALIGNMENT`]. + /// The length of the data written to `destination` will be 8 bytes ([`QUERY_SIZE`]) + /// times the number of elements in `query_range`. + /// + /// For further information about using queries, see [`QuerySet`]. pub fn resolve_query_set( &mut self, query_set: &QuerySet, diff --git a/wgpu/src/api/compute_pass.rs b/wgpu/src/api/compute_pass.rs index 0d1dcf585..cbd970be9 100644 --- a/wgpu/src/api/compute_pass.rs +++ b/wgpu/src/api/compute_pass.rs @@ -143,6 +143,11 @@ impl ComputePass<'_> { impl ComputePass<'_> { /// Start a pipeline statistics query on this compute pass. It can be ended with /// `end_pipeline_statistics_query`. Pipeline statistics queries may not be nested. + /// + /// The amount of information collected by this query, and the space occupied in the query set, + /// is determined by the [`PipelineStatisticsTypes`] the query set was created with. + /// `query_index` is the index of the first query result slot that will be written to, and + /// `query_set` must have sufficient size to hold all results written starting at that slot. pub fn begin_pipeline_statistics_query(&mut self, query_set: &QuerySet, query_index: u32) { self.inner .begin_pipeline_statistics_query(&query_set.inner, query_index); diff --git a/wgpu/src/api/query_set.rs b/wgpu/src/api/query_set.rs index dc89330f1..70bd0fad2 100644 --- a/wgpu/src/api/query_set.rs +++ b/wgpu/src/api/query_set.rs @@ -2,7 +2,24 @@ use crate::*; /// Handle to a query set. /// -/// It can be created with [`Device::create_query_set`]. +/// A `QuerySet` is an opaque, mutable storage location for the results of queries: +/// which are small pieces of information extracted from other operations such as render passes. +/// See [`QueryType`] for what types of information can be collected. +/// +/// Each query writes data into one or more result slots in the `QuerySet`, which must be created +/// with a sufficient number of slots for that usage. Each result slot is a an unsigned 64-bit +/// number. +/// +/// Using queries consists of the following steps: +/// +/// 1. Create a `QuerySet` of the appropriate type and number of query result slots +/// using [`Device::create_query_set()`]. +/// 2. Pass the `QuerySet` to the commands which will write to it. +/// See [`QueryType`] for the possible commands. +/// 3. Execute the command [`CommandEncoder::resolve_query_set()`]. +/// This converts the opaque data stored in a `QuerySet` into [`u64`]s stored in a [`Buffer`]. +/// 4. Make use of that buffer, such as by copying its contents to the CPU +/// or reading it from a compute shader. /// /// Corresponds to [WebGPU `GPUQuerySet`](https://gpuweb.github.io/gpuweb/#queryset). #[derive(Debug, Clone)] diff --git a/wgpu/src/api/render_pass.rs b/wgpu/src/api/render_pass.rs index 634168021..3bd24d2c5 100644 --- a/wgpu/src/api/render_pass.rs +++ b/wgpu/src/api/render_pass.rs @@ -555,6 +555,11 @@ impl RenderPass<'_> { /// Start a pipeline statistics query on this render pass. It can be ended with /// [`end_pipeline_statistics_query`](Self::end_pipeline_statistics_query). /// Pipeline statistics queries may not be nested. + /// + /// The amount of information collected by this query, and the space occupied in the query set, + /// is determined by the [`PipelineStatisticsTypes`] the query set was created with. + /// `query_index` is the index of the first query result slot that will be written to, and + /// `query_set` must have sufficient size to hold all results written starting at that slot. pub fn begin_pipeline_statistics_query(&mut self, query_set: &QuerySet, query_index: u32) { self.inner .begin_pipeline_statistics_query(&query_set.inner, query_index);