WebGPU

1. Introduction

This section is non-normative.

Graphics Processing Units, or GPUs for short, have been essential in enabling rich rendering and computational applications in personal computing. WebGPU is an API that exposes the capabilities of GPU hardware for the Web. The API is designed from the ground up to efficiently map to (post-2014) native GPU APIs. WebGPU is not related to WebGL and does not explicitly target OpenGL ES.

WebGPU sees physical GPU hardware as GPUAdapters. It provides a connection to an adapter via GPUDevice, which manages resources, and the device’s GPUQueues, which execute commands. GPUDevice may have its own memory with high-speed access to the processing units. GPUBuffer and GPUTexture are the physical resources backed by GPU memory. GPUCommandBuffer and GPURenderBundle are containers for user-recorded commands. GPUShaderModule contains shader code. The other resources, such as GPUSampler or GPUBindGroup, configure the way physical resources are used by the GPU.

GPUs execute commands encoded in GPUCommandBuffers by feeding data through a pipeline, which is a mix of fixed-function and programmable stages. Programmable stages execute shaders, which are special programs designed to run on GPU hardware. Most of the state of a pipeline is defined by a GPURenderPipeline or a GPUComputePipeline object. The state not included in these pipeline objects is set during encoding with commands, such as beginRenderPass() or setBlendConstant().

2. Malicious use considerations

This section is non-normative. It describes the risks associated with exposing this API on the Web.

2.1. Security Considerations

The security requirements for WebGPU are the same as ever for the web, and are likewise non-negotiable. The general approach is strictly validating all the commands before they reach GPU, ensuring that a page can only work with its own data.

2.1.1. CPU-based undefined behavior

A WebGPU implementation translates the workloads issued by the user into API commands specific to the target platform. Native APIs specify the valid usage for the commands (for example, see vkCreateDescriptorSetLayout) and generally don’t guarantee any outcome if the valid usage rules are not followed. This is called "undefined behavior", and it can be exploited by an attacker to access memory they don’t own, or force the driver to execute arbitrary code.

In order to disallow insecure usage, the range of allowed WebGPU behaviors is defined for any input. An implementation has to validate all the input from the user and only reach the driver with the valid workloads. This document specifies all the error conditions and handling semantics. For example, specifying the same buffer with intersecting ranges in both "source" and "destination" of copyBufferToBuffer() results in GPUCommandEncoder generating an error, and no other operation occurring.

See § 22 Errors & Debugging for more information about error handling.

2.1.2. GPU-based undefined behavior

WebGPU shaders are executed by the compute units inside GPU hardware. In native APIs, some of the shader instructions may result in undefined behavior on the GPU. In order to address that, the shader instruction set and its defined behaviors are strictly defined by WebGPU. When a shader is provided to createShaderModule(), the WebGPU implementation has to validate it before doing any translation (to platform-specific shaders) or transformation passes.

2.1.3. Uninitialized data

Generally, allocating new memory may expose the leftover data of other applications running on the system. In order to address that, WebGPU conceptually initializes all the resources to zero, although in practice an implementation may skip this step if it sees the developer initializing the contents manually. This includes variables and shared workgroup memory inside shaders.

The precise mechanism of clearing the workgroup memory can differ between platforms. If the native API does not provide facilities to clear it, the WebGPU implementation transforms the compute shader to first do a clear across all invocations, synchronize them, and continue executing developer’s code.

2.1.4. Out-of-bounds access in shaders

Shaders can access physical resources either directly (for example, as a "uniform" GPUBufferBinding), or via texture units, which are fixed-function hardware blocks that handle texture coordinate conversions. Validation in the WebGPU API can only guarantee that all the inputs to the shader are provided and they have the correct usage and types. The WebGPU API can not guarantee that the data is accessed within bounds if the texture units are not involved.

In order to prevent the shaders from accessing GPU memory an application doesn’t own, the WebGPU implementation may enable a special mode (called "robust buffer access") in the driver that guarantees that the access is limited to buffer bounds.

Alternatively, an implementation may transform the shader code by inserting manual bounds checks. When this path is taken, the out-of-bound checks only apply to array indexing. They aren’t needed for plain field access of shader structures due to the minBindingSize validation on the host side.

If the shader attempts to load data outside of physical resource bounds, the implementation is allowed to:

1. return a value at a different location within the resource bounds

2. return a value vector of "(0, 0, 0, X)" with any "X"

3. partially discard the draw or dispatch call

If the shader attempts to write data outside of physical resource bounds, the implementation is allowed to:

1. write the value to a different location within the resource bounds

2. discard the write operation

3. partially discard the draw or dispatch call

2.1.5. Invalid data

When uploading floating-point data from CPU to GPU, or generating it on the GPU, we may end up with a binary representation that doesn’t correspond to a valid number, such as infinity or NaN (not-a-number). The GPU behavior in this case is subject to the accuracy of the GPU hardware implementation of the IEEE-754 standard. WebGPU guarantees that introducing invalid floating-point numbers would only affect the results of arithmetic computations and will not have other side effects.

2.1.6. Driver bugs

GPU drivers are subject to bugs like any other software. If a bug occurs, an attacker could possibly exploit the incorrect behavior of the driver to get access to unprivileged data. In order to reduce the risk, the WebGPU working group will coordinate with GPU vendors to integrate the WebGPU Conformance Test Suite (CTS) as part of their driver testing process, like it was done for WebGL. WebGPU implementations are expected to have workarounds for some of the discovered bugs, and disable WebGPU on drivers with known bugs that can’t be worked around.

2.1.7. Timing attacks

2.1.7.1. Content-timeline timing

WebGPU does not expose new states to JavaScript (the content timeline) which are shared between agents in an agent cluster. Content timeline states such as [[mapping]] only change during explicit content timeline tasks, like in plain JavaScript.

2.1.7.2. Device/queue-timeline timing

Writable storage buffers and other cross-invocation communication may be usable to construct high-precision timers on the queue timeline.

The optional "timestamp-query" feature also provides high precision timing of GPU operations. To mitigate security and privacy concerns, the timing query values are aligned to a lower precision: see current queue timestamp. Note in particular:

• The device timeline typically runs in a process that is shared by multiple origins, so cross-origin isolation (provided by COOP/COEP) does not provide isolation of device/queue-timeline timers.

• Queue timeline work is issued from the device timeline, and may execute on GPU hardware that does not provide the isolation expected of CPU processes (such as Meltdown mitigations).

• GPU hardware is not typically susceptible to Spectre-style attacks, but WebGPU may be implemented in software, and software implementations may run in a shared process, preventing isolation-based mitigations.

2.1.8. Row hammer attacks

Row hammer is a class of attacks that exploit the leaking of states in DRAM cells. It could be used on GPU. WebGPU does not have any specific mitigations in place, and relies on platform-level solutions, such as reduced memory refresh intervals.

2.1.9. Denial of service

WebGPU applications have access to GPU memory and compute units. A WebGPU implementation may limit the available GPU memory to an application, in order to keep other applications responsive. For GPU processing time, a WebGPU implementation may set up "watchdog" timer that makes sure an application doesn’t cause GPU unresponsiveness for more than a few seconds. These measures are similar to those used in WebGL.

2.1.10. Workload identification

WebGPU provides access to constrained global resources shared between different programs (and web pages) running on the same machine. An application can try to indirectly probe how constrained these global resources are, in order to reason about workloads performed by other open web pages, based on the patterns of usage of these shared resources. These issues are generally analogous to issues with Javascript, such as system memory and CPU execution throughput. WebGPU does not provide any additional mitigations for this.

2.1.11. Memory resources

WebGPU exposes fallible allocations from machine-global memory heaps, such as VRAM. This allows for probing the size of the system’s remaining available memory (for a given heap type) by attempting to allocate and watching for allocation failures.

GPUs internally have one or more (typically only two) heaps of memory shared by all running applications. When a heap is depleted, WebGPU would fail to create a resource. This is observable, which may allow a malicious application to guess what heaps are used by other applications, and how much they allocate from them.

2.1.12. Computation resources

If one site uses WebGPU at the same time as another, it may observe the increase in time it takes to process some work. For example, if a site constantly submits compute workloads and tracks completion of work on the queue, it may observe that something else also started using the GPU.

A GPU has many parts that can be tested independently, such as the arithmetic units, texture sampling units, atomic units, etc. A malicious application may sense when some of these units are stressed, and attempt to guess the workload of another application by analyzing the stress patterns. This is analogous to the realities of CPU execution of Javascript.

2.1.13. Abuse of capabilities

Malicious sites could abuse the capabilities exposed by WebGPU to run computations that don’t benefit the user or their experience and instead only benefit the site. Examples would be hidden crypto-mining, password cracking or rainbow tables computations.

It is not possible to guard against these types of uses of the API because the browser is not able to distinguish between valid workloads and abusive workloads. This is a general problem with all general-purpose computation capabilities on the Web: JavaScript, WebAssembly or WebGL. WebGPU only makes some workloads easier to implement, or slightly more efficient to run than using WebGL.

To mitigate this form of abuse, browsers can throttle operations on background tabs, could warn that a tab is using a lot of resource, and restrict which contexts are allowed to use WebGPU.

User agents can heuristically issue warnings to users about high power use, especially due to potentially malicious usage. If a user agent implements such a warning, it should include WebGPU usage in its heuristics, in addition to JavaScript, WebAssembly, WebGL, and so on.

2.2. Privacy Considerations

The privacy considerations for WebGPU are similar to those of WebGL. GPU APIs are complex and must expose various aspects of a device’s capabilities out of necessity in order to enable developers to take advantage of those capabilities effectively. The general mitigation approach involves normalizing or binning potentially identifying information and enforcing uniform behavior where possible.

A user agent must not reveal more than 32 distinguishable configurations or buckets.

2.2.1. Machine-specific features and limits

WebGPU can expose a lot of detail on the underlying GPU architecture and the device geometry. This includes available physical adapters, many limits on the GPU and CPU resources that could be used (such as the maximum texture size), and any optional hardware-specific capabilities that are available.

User agents are not obligated to expose the real hardware limits, they are in full control of how much the machine specifics are exposed. One strategy to reduce fingerprinting is binning all the target platforms into a few number of bins. In general, the privacy impact of exposing the hardware limits matches the one of WebGL.

The default limits are also deliberately high enough to allow most applications to work without requesting higher limits. All the usage of the API is validated according to the requested limits, so the actual hardware capabilities are not exposed to the users by accident.

2.2.2. Machine-specific artifacts

There are some machine-specific rasterization/precision artifacts and performance differences that can be observed roughly in the same way as in WebGL. This applies to rasterization coverage and patterns, interpolation precision of the varyings between shader stages, compute unit scheduling, and more aspects of execution.

Generally, rasterization and precision fingerprints are identical across most or all of the devices of each vendor. Performance differences are relatively intractable, but also relatively low-signal (as with JS execution performance).

Privacy-critical applications and user agents should utilize software implementations to eliminate such artifacts.

2.2.3. Machine-specific performance

Another factor for differentiating users is measuring the performance of specific operations on the GPU. Even with low precision timing, repeated execution of an operation can show if the user’s machine is fast at specific workloads. This is a fairly common vector (present in both WebGL and Javascript), but it’s also low-signal and relatively intractable to truly normalize.

WebGPU compute pipelines expose access to GPU unobstructed by the fixed-function hardware. This poses an additional risk for unique device fingerprinting. User agents can take steps to dissociate logical GPU invocations with actual compute units to reduce this risk.

2.2.4. User Agent State

This specification doesn’t define any additional user-agent state for an origin. However it is expected that user agents will have compilation caches for the result of expensive compilation like GPUShaderModule, GPURenderPipeline and GPUComputePipeline. These caches are important to improve the loading time of WebGPU applications after the first visit.

For the specification, these caches are indifferentiable from incredibly fast compilation, but for applications it would be easy to measure how long createComputePipelineAsync() takes to resolve. This can leak information across origins (like "did the user access a site with this specific shader") so user agents should follow the best practices in storage partitioning.

The system’s GPU driver may also have its own cache of compiled shaders and pipelines. User agents may want to disable these when at all possible, or add per-partition data to shaders in ways that will make the GPU driver consider them different.

2.2.5. Driver bugs

In addition to the concerns outlined in Security Considerations, driver bugs may introduce differences in behavior that can be observed as a method of differentiating users. The mitigations mentioned in Security Considerations apply here as well, including coordinating with GPU vendors and implementing workarounds for known issues in the user agent.

2.2.6. Adapter Identifiers

Past experience with WebGL has demonstrated that developers have a legitimate need to be able to identify the GPU their code is running on in order to create and maintain robust GPU-based content. For example, to identify adapters with known driver bugs in order to work around them or to avoid features that perform more poorly than expected on a given class of hardware.

But exposing adapter identifiers also naturally expands the amount of fingerprinting information available, so there’s a desire to limit the precision with which we identify the adapter.

There are several mitigations that can be applied to strike a balance between enabling robust content and preserving privacy. First is that user agents can reduce the burden on developers by identifying and working around known driver issues, as they have since browsers began making use of GPUs.

When adapter identifiers are exposed by default they should be as broad as possible while still being useful. Possibly identifying, for example, the adapter’s vendor and general architecture without identifying the specific adapter in use. Similarly, in some cases identifiers for an adapter that is considered a reasonable proxy for the actual adapter may be reported.

In cases where full and detailed information about the adapter is useful (for example: when filing bug reports) the user can be asked for consent to reveal additional information about their hardware to the page.

Finally, the user agent will always have the discretion to not report adapter identifiers at all if it considers it appropriate, such as in enhanced privacy modes.

3. Fundamentals

3.1. Conventions

3.1.1. Syntactic Shorthands

In this specification, the following syntactic shorthands are used:

The . ("dot") syntax, common in programming languages.

The phrasing "Foo.Bar" means "the Bar member of the value (or interface) Foo." If Foo is an ordered map and Bar does not exist in Foo, returns undefined.

The phrasing "Foo.Bar is provided" means "the Bar member exists in the map value Foo"

The ?. ("optional chaining") syntax, adopted from JavaScript.

The phrasing "Foo?.Bar" means "if Foo is null or undefined or Bar does not exist in Foo, undefined; otherwise, Foo.Bar".

For example, where buffer is a GPUBuffer, buffer?.\[[device]].\[[adapter]] means "if buffer is null or undefined, then undefined; otherwise, the \[[adapter]] internal slot of the \[[device]] internal slot of buffer.

The ?? ("nullish coalescing") syntax, adopted from JavaScript.

The phrasing "x ?? y" means "x, if x is not null or undefined, and y otherwise".

slot-backed attribute

A WebIDL attribute which is backed by an internal slot of the same name. It may or may not be mutable.

3.1.2. WebGPU Objects

A WebGPU object consists of a WebGPU Interface and an internal object.

The WebGPU interface defines the public interface and state of the WebGPU object. It can be used on the content timeline where it was created, where it is a JavaScript-exposed WebIDL interface.

Any interface which includes GPUObjectBase is a WebGPU interface.

The internal object tracks the state of the WebGPU object on the device timeline. All reads/writes to the mutable state of an internal object occur from steps executing on a single well-ordered device timeline.

The following special property types can be defined on WebGPU objects:

immutable property

A read-only slot set during initialization of the object. It can be accessed from any timeline.

Note: Since the slot is immutable, implementations may have a copy on multiple timelines, as needed. Immutable properties are defined in this way to avoid describing multiple copies in this spec.

If named [[with brackets]], it is an internal slot.
If named withoutBrackets, it is a readonly slot-backed attribute of the WebGPU interface.

content timeline property

A property which is only accessible from the content timeline where the object was created.

If named [[with brackets]], it is an internal slot.
If named withoutBrackets, it is a slot-backed attribute of the WebGPU interface.

device timeline property

A property which tracks state of the internal object and is only accessible from the device timeline where the object was created. device timeline properties may be mutable.

Device timeline properties are named [[with brackets]], and are internal slots.

queue timeline property

A property which tracks state of the internal object and is only accessible from the queue timeline where the object was created. queue timeline properties may be mutable.

Queue timeline properties are named [[with brackets]], and are internal slots.

interface mixin GPUObjectBase {
    attribute USVString label;
};

GPUObjectBase has the following immutable properties:

[[device]], of type device, readonly

The device that owns the internal object.

Operations on the contents of this object assert they are running on the device timeline, and that the device is valid.

GPUObjectBase has the following content timeline properties:

label, of type USVString

A developer-provided label which is used in an implementation-defined way. It can be used by the browser, OS, or other tools to help identify the underlying internal object to the developer. Examples include displaying the label in GPUError messages, console warnings, browser developer tools, and platform debugging utilities.

NOTE:

Implementations should use labels to enhance error messages by using them to identify WebGPU objects.

However, this need not be the only way of identifying objects: implementations should also use other available information, especially when no label is available. For example:

• The label of the parent GPUTexture when printing a GPUTextureView.

• The label of the parent GPUCommandEncoder when printing a GPURenderPassEncoder or GPUComputePassEncoder.

• The label of the source GPUCommandEncoder when printing a GPUCommandBuffer.

• The label of the source GPURenderBundleEncoder when printing a GPURenderBundle.

NOTE:

The label is a property of the GPUObjectBase. Two GPUObjectBase "wrapper" objects have completely separate label states, even if they refer to the same underlying object (for example returned by getBindGroupLayout()). The label property will not change except by being set from JavaScript.

This means one underlying object could be associated with multiple labels. This specification does not define how the label is propagated to the device timeline. How labels are used is completely implementation-defined: error messages could show the most recently set label, all known labels, or no labels at all.

It is defined as a USVString because some user agents may supply it to the debug facilities of the underlying native APIs.

GPUObjectBase has the following device timeline properties:

[[valid]], of type boolean, initially true.

If true, indicates that the internal object is valid to use.

3.1.3. Object Descriptors

An object descriptor holds the information needed to create an object, which is typically done via one of the create* methods of GPUDevice.

dictionary GPUObjectDescriptorBase {
    USVString label = "";
};

GPUObjectDescriptorBase has the following members:

label, of type USVString, defaulting to ""

The initial value of GPUObjectBase.label.

3.2. Asynchrony

3.2.1. Invalid Internal Objects & Contagious Invalidity

Object creation operations in WebGPU don’t return promises, but nonetheless are internally asynchronous. Returned objects refer to internal objects which are manipulated on a device timeline. Rather than fail with exceptions or rejections, most errors that occur on a device timeline are communicated through GPUErrors generated on the associated device.

Internal objects are either valid or invalid. An invalid object will never become valid at a later time, but some valid objects may be invalidated.

Objects are invalid from creation if it wasn’t possible to create them. This can happen, for example, if the object descriptor doesn’t describe a valid object, or if there is not enough memory to allocate a resource. It can also happen if an object is created with or from another invalid object (for example calling createView() on an invalid GPUTexture) (for example the GPUTexture of a createView() call): this case is referred to as contagious invalidity.

Internal objects of most types cannot become invalid after they are created, but still may become unusable, e.g. if the owning device is lost or destroyed, or the object has a special internal state, like buffer state "destroyed".

Internal objects of some types can become invalid after they are created; specifically, devices, adapters, GPUCommandBuffers, and command/pass/bundle encoders.

3.2.2. Promise Ordering

Several operations in WebGPU return promises.

• GPU.requestAdapter()

• GPUAdapter.requestDevice()

• GPUDevice.createComputePipelineAsync()

• GPUDevice.createRenderPipelineAsync()

• GPUShaderModule.getCompilationInfo()

• GPUQueue.onSubmittedWorkDone()

• GPUBuffer.mapAsync()

• GPUDevice.lost

• GPUDevice.popErrorScope()

WebGPU does not make any guarantees about the order in which these promises settle (resolve or reject), except for the following:

• For some GPUQueue q, if p1 = q.onSubmittedWorkDone() is called before p2 = q.onSubmittedWorkDone(), then p1 must settle before p2.
• For some GPUQueue q and GPUBuffer b on the same GPUDevice, if p1 = b.mapAsync() is called before p2 = q.onSubmittedWorkDone(), then p1 must settle before p2.

Applications must not rely on any other promise settlement ordering.

3.3. Coordinate Systems

Rendering operations use the following coordinate systems:

• Normalized device coordinates (or NDC) have three dimensions, where:

  • -1.0 ≤ x ≤ 1.0

  • -1.0 ≤ y ≤ 1.0

  • 0.0 ≤ z ≤ 1.0

  • The bottom-left corner is at (-1.0, -1.0, z).

  Note: Whether z = 0 or z = 1 is treated as the near plane is application specific. The above diagram presents z = 0 as the near plane but the observed behavior is determined by a combination of the projection matrices used by shaders, the depthClearValue, and the depthCompare function.

• Clip space coordinates have four dimensions: (x, y, z, w)

  • Clip space coordinates are used for the the clip position of a vertex (i.e. the position output of a vertex shader), and for the clip volume.

  • Normalized device coordinates and clip space coordinates are related as follows: If point p = (p.x, p.y, p.z, p.w) is in the clip volume, then its normalized device coordinates are (p.x ÷ p.w, p.y ÷ p.w, p.z ÷ p.w).

• Framebuffer coordinates address the pixels in the framebuffer

  • They have two dimensions.

  • Each pixel extends 1 unit in x and y dimensions.

  • The top-left corner is at (0.0, 0.0).

  • x increases to the right.

  • y increases down.

  • See § 17 Render Passes and § 23.2.5 Rasterization.

• Viewport coordinates combine framebuffer coordinates in x and y dimensions, with depth in z.

  • Normally 0.0 ≤ z ≤ 1.0, but this can be modified by setting [[viewport]].minDepth and maxDepth via setViewport()

• Fragment coordinates match viewport coordinates.

• Texture coordinates, sometimes called "UV coordinates" in 2D, are used to sample textures and have a number of components matching the texture dimension.

  • 0 ≤ u ≤ 1.0

  • 0 ≤ v ≤ 1.0

  • 0 ≤ w ≤ 1.0

  • (0.0, 0.0, 0.0) is in the first texel in texture memory address order.

  • (1.0, 1.0, 1.0) is in the last texel texture memory address order.

• Window coordinates, or present coordinates, match framebuffer coordinates, and are used when interacting with an external display or conceptually similar interface.

Note: WebGPU’s coordinate systems match DirectX’s coordinate systems in a graphics pipeline.

3.4. Programming Model

3.4.1. Timelines

WebGPU’s behavior is described in terms of "timelines". Each operation (defined as algorithms) occurs on a timeline. Timelines clearly define both the order of operations, and which state is available to which operations.

Note: This "timeline" model describes the constraints of the multi-process models of browser engines (typically with a "content process" and "GPU process"), as well as the GPU itself as a separate execution unit in many implementations. Implementing WebGPU does not require timelines to execute in parallel, so does not require multiple processes, or even multiple threads. (It does require concurrency for cases like get a copy of the image contents of a context which synchronously blocks on another timeline to complete.)

Content timeline

Associated with the execution of the Web script. It includes calling all methods described by this specification.

To issue steps to the content timeline from an operation on GPUDevice device, queue a global task for GPUDevice device with those steps.

Device timeline

Associated with the GPU device operations that are issued by the user agent. It includes creation of adapters, devices, and GPU resources and state objects, which are typically synchronous operations from the point of view of the user agent part that controls the GPU, but can live in a separate OS process.

Queue timeline

Associated with the execution of operations on the compute units of the GPU. It includes actual draw, copy, and compute jobs that run on the GPU.

Timeline-agnostic

Associated with any of the above timelines

Steps may be issued to any timeline if they only operate on immutable properties or arguments passed from the calling steps.

In this specification, asynchronous operations are used when the return value depends on work that happens on any timeline other than the Content timeline. They are represented by promises and events in API.

3.4.2. Memory Model

This section is non-normative.

Once a GPUDevice has been obtained during an application initialization routine, we can describe the WebGPU platform as consisting of the following layers:

1. User agent implementing the specification.

2. Operating system with low-level native API drivers for this device.

3. Actual CPU and GPU hardware.

Each layer of the WebGPU platform may have different memory types that the user agent needs to consider when implementing the specification:

• The script-owned memory, such as an ArrayBuffer created by the script, is generally not accessible by a GPU driver.

• A user agent may have different processes responsible for running the content and communication to the GPU driver. In this case, it uses inter-process shared memory to transfer data.

• Dedicated GPUs have their own memory with high bandwidth, while integrated GPUs typically share memory with the system.

Most physical resources are allocated in the memory of type that is efficient for computation or rendering by the GPU. When the user needs to provide new data to the GPU, the data may first need to cross the process boundary in order to reach the user agent part that communicates with the GPU driver. Then it may need to be made visible to the driver, which sometimes requires a copy into driver-allocated staging memory. Finally, it may need to be transferred to the dedicated GPU memory, potentially changing the internal layout into one that is most efficient for GPUs to operate on.

All of these transitions are done by the WebGPU implementation of the user agent.

Note: This example describes the worst case, while in practice the implementation may not need to cross the process boundary, or may be able to expose the driver-managed memory directly to the user behind an ArrayBuffer, thus avoiding any data copies.

3.4.3. Resource Usages

A physical resource can be used with an internal usage by a GPU command:

input

Buffer with input data for draw or dispatch calls. Preserves the contents. Allowed by buffer INDEX, buffer VERTEX, or buffer INDIRECT.

constant

Resource bindings that are constant from the shader point of view. Preserves the contents. Allowed by buffer UNIFORM or texture TEXTURE_BINDING.

storage

Read/write storage resource binding. Allowed by buffer STORAGE or texture STORAGE_BINDING.

storage-read

Read-only storage resource bindings. Preserves the contents. Allowed by buffer STORAGE or texture STORAGE_BINDING.

attachment

Texture used as a read/write output attachment or write-only resolve target in a render pass. Allowed by texture RENDER_ATTACHMENT.

attachment-read

Texture used as a read-only attachment in a render pass. Preserves the contents. Allowed by texture RENDER_ATTACHMENT.

We define subresource to be either a whole buffer, or a texture subresource.

Enforcing that the usages are only combined into a compatible usage list allows the API to limit when data races can occur in working with memory. That property makes applications written against WebGPU more likely to run without modification on different platforms.

3.4.4. Synchronization

A usage scope is a map from subresource to list<internal usage>>. Each usage scope covers a range of operations which may execute in a concurrent fashion with each other, and therefore may only use subresources in consistent compatible usage lists within the scope.

Usage scopes are constructed and validated during encoding:

• in dispatchWorkgroups()

• in dispatchWorkgroupsIndirect()

• at GPURenderPassEncoder.end()

• at GPURenderBundleEncoder.finish()

The usage scopes are as follows:

• In a compute pass, each dispatch command (dispatchWorkgroups() or dispatchWorkgroupsIndirect()) is one usage scope.

  A subresource is used in the usage scope if it is potentially accessible by the dispatched invocations, including:

  • All subresources referenced by bind groups in slots used by the current GPUComputePipeline’s [[layout]]

  • Buffers used directly by dispatch calls (such as indirect buffers)

  Note: State-setting compute pass commands, like setBindGroup(), do not contribute their bound resources directly to a usage scope: they only change the state that is checked in dispatch commands.

• One render pass is one usage scope.

  A subresource is used in the usage scope if it’s referenced by any command, including state-setting commands (unlike in compute passes), including:

  • Buffers set by setVertexBuffer()

  • Buffers set by setIndexBuffer()

  • All subresources referenced by bind groups set by setBindGroup()

  • Buffers used directly by draw calls (such as indirect buffers)

Note: Copy commands are standalone operations and don’t use usage scopes for validation. They implement their own validation to prevent self-races.

3.5. Core Internal Objects

3.5.1. Adapters

An adapter identifies an implementation of WebGPU on the system: both an instance of compute/rendering functionality on the platform underlying a browser, and an instance of a browser’s implementation of WebGPU on top of that functionality.

Adapters are exposed via GPUAdapter.

Adapters do not uniquely represent underlying implementations: calling requestAdapter() multiple times returns a different adapter object each time.

Each adapter object can only be used to create one device: upon a successful requestDevice() call, the adapter’s [[state]] changes to "consumed". Additionally, adapter objects may expire at any time.

Note: This ensures applications use the latest system state for adapter selection when creating a device. It also encourages robustness to more scenarios by making them look similar: first initialization, reinitialization due to an unplugged adapter, reinitialization due to a test GPUDevice.destroy() call, etc.

An adapter may be considered a fallback adapter if it has significant performance caveats in exchange for some combination of wider compatibility, more predictable behavior, or improved privacy. It is not required that a fallback adapter is available on every system.

adapter has the following immutable properties:

[[features]], of type ordered set<GPUFeatureName>, readonly

The features which can be used to create devices on this adapter.

[[limits]], of type supported limits, readonly

The best limits which can be used to create devices on this adapter.

Each adapter limit must be the same or better than its default value in supported limits.

[[fallback]], of type boolean, readonly

If set to true indicates that the adapter is a fallback adapter.

[[xrCompatible]], of type boolean

If set to true indicates that the adapter was requested with compatibility with WebXR sessions.

adapter has the following device timeline properties:

[[state]], initially "valid"

"valid"

The adapter can be used to create a device.

"consumed"

The adapter has already been used to create a device, and cannot be used again.

"expired"

The adapter has expired for some other reason.

3.5.2. Devices

A device is the logical instantiation of an adapter, through which internal objects are created.

Devices are exposed via GPUDevice.

A device is the exclusive owner of all internal objects created from it: when the device becomes invalid (is lost or destroyed), it and all objects created on it (directly, e.g. createTexture(), or indirectly, e.g. createView()) become implicitly unusable.

device has the following immutable properties:

[[adapter]], of type adapter, readonly

The adapter from which this device was created.

[[features]], of type ordered set<GPUFeatureName>, readonly

The features which can be used on this device, as computed at creation. No additional features can be used, even if the underlying adapter can support them.

[[limits]], of type supported limits, readonly

The limits which can be used on this device, as computed at creation. No better limits can be used, even if the underlying adapter can support them.

device has the following content timeline properties:

[[content device]], of type GPUDevice, readonly

The Content timeline GPUDevice interface which this device is associated with.

Any time the user agent needs to revoke access to a device, it calls lose the device(device, "unknown") on the device’s device timeline, potentially ahead of other operations currently queued on that timeline.

If an operation fails with side effects that would observably change the state of objects on the device or potentially corrupt internal implementation/driver state, the device should be lost to prevent these changes from being observable.

Note: For all device losses not initiated by the application (via destroy()), user agents should consider issuing developer-visible warnings unconditionally, even if the lost promise is handled. These scenarios should be rare, and the signal is vital to developers because most of the WebGPU API tries to behave like nothing is wrong to avoid interrupting the runtime flow of the application: no validation errors are raised, most promises resolve normally, etc.

3.6. Optional Capabilities

WebGPU adapters and devices have capabilities, which describe WebGPU functionality that differs between different implementations, typically due to hardware or system software constraints. A capability is either a feature or a limit.

A user agent must not reveal more than 32 distinguishable configurations or buckets.

The capabilities of an adapter must conform to § 4.2.1 Adapter Capability Guarantees.

Only supported capabilities may be requested in requestDevice(); requesting unsupported capabilities results in failure.

The capabilities of a device are determined in "a new device" by starting with the adapter’s defaults (no features and the default supported limits) and adding capabilities as requested in requestDevice(). These capabilities are enforced regardless of the capabilities of the adapter.

For privacy considerations, see § 2.2.1 Machine-specific features and limits.

3.6.1. Features

A feature is a set of optional WebGPU functionality that is not supported on all implementations, typically due to hardware or system software constraints.

All features are optional, but adapters make some guarantees about their availability (see § 4.2.1 Adapter Capability Guarantees).

A device supports the exact set of features determined at creation (see § 3.6 Optional Capabilities). API calls perform validation according to these features (not the adapter’s features):

• Using existing API surfaces in a new way typically results in a validation error.

• There are several types of optional API surface:

  • Using a new method or enum value always throws a TypeError.

  • Using a new dictionary member with a (correctly-typed) non-default value typically results in a validation error.

  • Using a new WGSL enable directive always results in a createShaderModule() validation error.

See the Feature Index for a description of the functionality each feature enables.

Note: Enabling features may not necessarily be desirable, as doing so may have a performance impact. Because of this, and to improve portability across devices and implementations, applications should generally only request features that they may actually require.

3.6.2. Limits

Each limit is a numeric limit on the usage of WebGPU on a device.

Note: Setting "better" limits may not necessarily be desirable, as doing so may have a performance impact. Because of this, and to improve portability across devices and implementations, applications should generally only request limits better than the defaults if they may actually require them.

Each limit has a default value.

Adapters are always guaranteed to support the defaults or better (see § 4.2.1 Adapter Capability Guarantees).

A device supports the exact set of limits determined at creation (see § 3.6 Optional Capabilities). API calls perform validation according to these limits (not the adapter’s limits), no better or worse.

For any given limit, some values are better than others. A better limit value always relaxes validation, enabling strictly more programs to be valid. For each limit class, "better" is defined.

Different limits have different limit classes:

maximum

The limit enforces a maximum on some value passed into the API.

Higher values are better.

May only be set to values ≥ the default. Lower values are clamped to the default.

alignment

The limit enforces a minimum alignment on some value passed into the API; that is, the value must be a multiple of the limit.

Lower values are better.

May only be set to powers of 2 which are ≤ the default. Values which are not powers of 2 are invalid. Higher powers of 2 are clamped to the default.

A supported limits object has a value for every limit defined by WebGPU: