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