diff --git a/proposals/README.md b/proposals/README.md new file mode 100644 index 0000000000..3c3bc10a28 --- /dev/null +++ b/proposals/README.md @@ -0,0 +1,26 @@ +# WebGPU Extension Proposals + +The documents in this directory are +[WebGPU extension documents](https://gpuweb.github.io/gpuweb/#extension-documents) +which describe **non-normative, non-standardized draft proposals** to add functionality to WebGPU. + +These proposals **may or may not be under active consideration**. +Check the "roadmap" of an extension document to understand its status. + +These proposals are **not stable** and may change at any time. They may be: + +- In-development proposals which are not easily contained in a GitHub pull request, HackMD, or similar. +- Inactive proposals which are not under active consideration but could be considered later. + +If the group agrees that it never intends to consider a proposal in the future, it should be +removed from this directory (and may be migrated outside of the WebGPU community group). + +## New Proposals + +Copy the format of an existing proposal. Proposals may be informal, as they are never normative. +However, be sure to include a **detailed roadmap** to set expectations for developers, and, as +appropriate, include: + +- WebGPU spec changes (including feature flags) +- WGSL spec changes (including enable directives) +- Links to context (like corresponding Vulkan/D3D12/Metal features) and past discussions diff --git a/proposals/pipeline-statistics-query.md b/proposals/pipeline-statistics-query.md new file mode 100644 index 0000000000..1c773743d6 --- /dev/null +++ b/proposals/pipeline-statistics-query.md @@ -0,0 +1,64 @@ +# Pipeline Statistics Queries + +**Roadmap:** This extension is **not under active consideration**, but may be considered later. +WebGPU implementations **must not** expose this functionality; doing so is a spec violation. +Note however, an implementation might provide an option (e.g. command line flag) to enable a draft +implementation, for developers who want to test this proposal or use its functionality for locally +profiling their application performance. + +## WebGPU Spec Changes + +**Feature flags:** `"pipeline-statistics-query"` + +``` +partial dictionary GPUQuerySetDescriptor { + sequence pipelineStatistics = []; +}; + +enum GPUPipelineStatisticName { + "vertex-shader-invocations", + "clipper-invocations", + "clipper-primitives-out", + "fragment-shader-invocations", + "compute-shader-invocations", +}; + +partial interface GPUComputePassEncoder { + undefined beginPipelineStatisticsQuery(GPUQuerySet querySet, GPUSize32 queryIndex); + undefined endPipelineStatisticsQuery(); +}; + +partial interface GPURenderPassEncoder { + undefined beginPipelineStatisticsQuery(GPUQuerySet querySet, GPUSize32 queryIndex); + undefined endPipelineStatisticsQuery(); +}; +``` + +- `GPUQuerySetDescriptor.pipelineStatistics`: + The set of `GPUPipelineStatisticName` values in this sequence defines which pipeline statistics will be returned in the new query set. + - Must be empty if the query set type is not `"pipeline-statistics"`. + - Must not contain duplicate entries. +- `beginPipelineStatisticsQuery(querySet, queryIndex)`: + Begins recording pipeline statistics to write into `querySet` at index `queryIndex`. + - If the feature is not enabled, throws a `TypeError`. + - Fails if a pipeline statistics query is already open. +- `endPipelineStatisticsQuery()`: + Ends recording the current pipeline statistics query. + - If the feature is not enabled, throws a `TypeError`. + - Fails if a pipeline statistics query is not open. + - Fails if the pass is not open. +- In `createQuerySet()`: + - If the query set type is `"pipeline-statistics"` but the feature is not enabled, throws a `TypeError`. +- In `resolveQuerySet()`: + When resolving a pipeline statistics query, each result is written as a `GPUSize64`, and the number and order of the results written to GPU buffer matches the number and order of `GPUPipelineStatisticName`s specified in `GPUQuerySetDescriptor.pipelineStatistics`. +- In `GPUComputePassEncoder`/`GPURenderPassEncoder`.`end()`: + - Fails if a pipeline statistics query is still open. + +## WGSL Spec Changes + +**Enable directive(s):** N/A + +## References + +- +- diff --git a/spec/index.bs b/spec/index.bs index e3ad25e18a..b66d8917ae 100644 --- a/spec/index.bs +++ b/spec/index.bs @@ -1666,6 +1666,18 @@ interface GPUAdapterInfo { +## Extension Documents ## {#extension-documents} + +"Extension Documents" are additional documents which describe new functionality which is +non-normative and **not part of the WebGPU/WGSL specifications**. +They describe functionality that builds upon these specifications, often including one or more new +API [=feature=] flags and/or WGSL `enable` directives, or interactions with other draft +web specifications. + +WebGPU implementations **must not** expose extension functionality; doing so is a spec violation. +New functionality does not become part of the WebGPU standard until it is integrated +into the WebGPU specification (this document) and/or WGSL specification. + ## Origin Restrictions ## {#origin-restrictions} WebGPU allows accessing image data stored in images, videos, and canvases.