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.

Author: kpreid

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

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<L> {
     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<L> QuerySetDescriptor<L> {
     }
 }
 
-/// 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<L> QuerySetDescriptor<L> {
 #[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.
-    Occlusion,
-    /// Query returns up to 5 64-bit numbers based on the given flags.
+    /// 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).
     ///
-    /// See [`PipelineStatisticsTypes`]'s documentation for more information
-    /// on how they get resolved.
+    /// 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.
     ///
-    /// [`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.
+    #[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,
+
+    /// A timestamp query records a GPU-timestamp value
+    /// at which a certain command started or 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
+    /// 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()`]
+    ///
+    /// 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! {

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,

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);

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)]

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);