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 is designed to later support multi-threaded use via Web Workers. As such, it is designed not to open the users to modern high-precision timing attacks. Some of the objects, like GPUBuffer or GPUQueue, have shared state which can be simultaneously accessed. This allows race conditions to occur, similar to those of accessing a SharedArrayBuffer from multiple Web Workers, which makes the thread scheduling observable.

WebGPU addresses this by limiting the ability to deserialize (or share) objects only to the agents inside the agent cluster, and only if the cross-origin isolated policies are in place. This restriction matches the mitigations against the malicious SharedArrayBuffer use. Similarly, the user agent may also serialize the agents sharing any handles to prevent any concurrency entirely.

In the end, the attack surface for races on shared state in WebGPU will be a small subset of the SharedArrayBuffer attacks.

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, asserts that the key Bar exists.

Editorial note: Some phrasing in this spec may currently assume this resolves to undefined if Bar doesn’t exist.

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/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 Interfaces

A WebGPU interface defines a WebGPU object. It can be used:

• On the content timeline where it was created, where it is a JavaScript-exposed WebIDL interface.

• On all other timelines, where only immutable properties can be accessed.

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

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.

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.

Any interface which includes GPUObjectBase is a WebGPU interface.

interface mixin GPUObjectBase {
    attribute USVString label;
};

GPUObjectBase has the following immutable properties:

[[internals]], of type internal object, readonly, overridable

The internal object.

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

For each interface that subtypes GPUObjectBase, this may be overridden with a subtype of internal object. This slot is initially set to an uninitialized object of that type.

[[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.

3.1.3. Internal Objects

An internal object tracks state of WebGPU objects that may only be used on the device timeline, in device timeline slots, which may be mutable.

device timeline slot

An internal slot which is only accessible from 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. These steps may have been issued from a content timeline algorithm on any of multiple agents.

Note: An "agent" refers to a JavaScript "thread" (i.e. main thread, or Web Worker).

3.1.4. 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 become invalid.

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

• GPUAdapter.requestAdapterInfo()

• GPUDevice.createComputePipelineAsync()

• GPUDevice.createRenderPipelineAsync()

• GPUBuffer.mapAsync()

• GPUShaderModule.getCompilationInfo()

• GPUQueue.onSubmittedWorkDone()

• 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).

• 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.3.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.

• UV coordinates are used to sample textures, and have two dimensions:

  • 0 ≤ u ≤ 1.0

  • 0 ≤ v ≤ 1.0

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

  • (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.

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.

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 on GPU with an internal usage:

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

Writable 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 an output attachment 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.

Generally, when an implementation processes an operation that uses a subresource in a different way than its current usage allows, it schedules a transition of the resource into the new state. In some cases, like within an open GPURenderPassEncoder, such a transition is impossible due to the hardware limitations. We define these places as usage scopes.

The main usage rule is, for any one subresource, its list of internal usages within one usage scope must be a compatible usage list.

For example, binding the same buffer for storage as well as for input within the same GPURenderPassEncoder would put the encoder as well as the owning GPUCommandEncoder into the error state. This combination of usages does not make a compatible usage list.

Note: race condition of multiple writable storage buffer/texture usages in a single usage scope is allowed.

The subresources of textures included in the views provided to GPURenderPassColorAttachment.view and GPURenderPassColorAttachment.resolveTarget are considered to be used as attachment for the usage scope of this render pass.

3.4.4. Synchronization

For each subresource of a physical resource, its set of internal usage flags is tracked on the Queue timeline.

On the Queue timeline, there is an ordered sequence of usage scopes. For the duration of each scope, the set of internal usage flags of any given subresource is constant. A subresource may transition to new usages at the boundaries between usage scopes.

This specification defines the following usage scopes:

• Outside of a pass (in GPUCommandEncoder), each (non-state-setting) command is one usage scope (e.g. copyBufferToTexture()).

• 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 command. Within a dispatch, for each bind group slot that is used by the current GPUComputePipeline's [[layout]], every subresource referenced by that bind group is "used" in the usage scope. State-setting compute pass commands, like setBindGroup(), do not contribute directly to a usage scope; they instead 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 (state-setting or non-state-setting) command. For example, in setBindGroup(), every subresource in bindGroup is "used" in the render pass’s usage scope.

The above should probably talk about GPU commands. But we don’t have a way to reference specific GPU commands (like dispatch) yet.

During command encoding, every usage of a subresource is recorded in one of the usage scopes in the command buffer. For each usage scope, the implementation performs usage scope validation by composing the list of all internal usage flags of each subresource used in the usage scope. If any of those lists is not a compatible usage list, GPUCommandEncoder.finish() will generate a validation error.

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 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(), the adapter becomes invalid. 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.

An adapter has the following internal slots:

[[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

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

Adapters are exposed via GPUAdapter.

3.5.2. Devices

A device is the logical instantiation of an adapter, through which internal objects are created. It can be shared across multiple agents (e.g. dedicated workers).

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.

A device has the following internal slots:

[[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. 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. No better limits can be used, even if the underlying adapter can support them.

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.

Devices are exposed via GPUDevice.

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 exactly the ones which were 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.

Functionality that is part of a feature may only be used if the feature was requested at device creation (in requiredFeatures). Otherwise, using existing API surfaces in a new way typically results in a validation error, and using optional API surfaces results in the following:

• 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.

3.6.2. Limits

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

Each limit has a default value. Every adapter is guaranteed to support the default value or better. The default is used if a value is not explicitly specified in requiredLimits.

One limit value may be better than another. 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.

Note: Setting "better" limits may not necessarily be desirable, as they may have a performance impact. Because of this, and to improve portability across devices and implementations, applications should generally request the "worst" limits that work for their content (ideally, the default values).

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

3.6.2.1. GPUSupportedLimits

GPUSupportedLimits exposes the limits supported by an adapter or device. See GPUAdapter.limits and GPUDevice.limits.

[Exposed=(Window, DedicatedWorker), SecureContext]
interface GPUSupportedLimits {
    readonly attribute unsigned long maxTextureDimension1D;
    readonly attribute unsigned long maxTextureDimension2D;
    readonly attribute unsigned long maxTextureDimension3D;
    readonly attribute unsigned long maxTextureArrayLayers;
    readonly attribute unsigned long maxBindGroups;
    readonly attribute unsigned long maxBindGroupsPlusVertexBuffers;
    readonly attribute unsigned long maxBindingsPerBindGroup;
    readonly attribute unsigned long maxDynamicUniformBuffersPerPipelineLayout;
    readonly attribute unsigned long maxDynamicStorageBuffersPerPipelineLayout;
    readonly attribute unsigned long maxSampledTexturesPerShaderStage;
    readonly attribute unsigned long maxSamplersPerShaderStage;
    readonly attribute unsigned long maxStorageBuffersPerShaderStage;
    readonly attribute unsigned long maxStorageTexturesPerShaderStage;
    readonly attribute unsigned long maxUniformBuffersPerShaderStage;
    readonly attribute unsigned long long maxUniformBufferBindingSize;
    readonly attribute unsigned long long maxStorageBufferBindingSize;
    readonly attribute unsigned long minUniformBufferOffsetAlignment;
    readonly attribute unsigned long minStorageBufferOffsetAlignment;
    readonly attribute unsigned long maxVertexBuffers;
    readonly attribute unsigned long long maxBufferSize;
    readonly attribute unsigned long maxVertexAttributes;
    readonly attribute unsigned long maxVertexBufferArrayStride;
    readonly attribute unsigned long maxInterStageShaderComponents;
    readonly attribute unsigned long maxInterStageShaderVariables;
    readonly attribute unsigned long maxColorAttachments;
    readonly attribute unsigned long maxColorAttachmentBytesPerSample;
    readonly attribute unsigned long maxComputeWorkgroupStorageSize;
    readonly attribute unsigned long maxComputeInvocationsPerWorkgroup;
    readonly attribute unsigned long maxComputeWorkgroupSizeX;
    readonly attribute unsigned long maxComputeWorkgroupSizeY;
    readonly attribute unsigned long maxComputeWorkgroupSizeZ;
    readonly attribute unsigned long maxComputeWorkgroupsPerDimension;
};

3.6.2.2. GPUSupportedFeatures

GPUSupportedFeatures is a setlike interface. Its set entries are the GPUFeatureName values of the features supported by an adapter or device. It must only contain strings from the GPUFeatureName enum.

[Exposed=(Window, DedicatedWorker), SecureContext]
interface GPUSupportedFeatures {
    readonly setlike<DOMString>;
};

if (adapter.features.has('unknown-feature')) {
    // Use unknown-feature
} else {
    console.warn('unknown-feature is not supported by this adapter.');
}

3.6.2.3. WGSLLanguageFeatures

WGSLLanguageFeatures is the setlike interface of navigator.gpu.wgslLanguageFeatures. Its set entries are the string names of the WGSL language extensions supported by the implementation (regardless of the adapter or device).

[Exposed=(Window, DedicatedWorker), SecureContext]
interface WGSLLanguageFeatures {
    readonly setlike<DOMString>;
};

3.6.2.4. GPUAdapterInfo

GPUAdapterInfo exposes various identifying information about an adapter.

None of the members in GPUAdapterInfo are guaranteed to be populated. It is at the user agent’s discretion which values to reveal, and it is likely that on some devices none of the values will be populated. As such, applications must be able to handle any possible GPUAdapterInfo values, including the absence of those values.

For privacy considerations, see § 2.2.6 Adapter Identifiers.

[Exposed=(Window, DedicatedWorker), SecureContext]
interface GPUAdapterInfo {
    readonly attribute DOMString vendor;
    readonly attribute DOMString architecture;
    readonly attribute DOMString device;
    readonly attribute DOMString description;
};

GPUAdapterInfo has the following attributes:

vendor, of type DOMString, readonly

The name of the vendor of the adapter, if available. Empty string otherwise.

architecture, of type DOMString, readonly

The name of the family or class of GPUs the adapter belongs to, if available. Empty string otherwise.

device, of type DOMString, readonly

A vendor-specific identifier for the adapter, if available. Empty string otherwise.

Note: This is a value that represents the type of adapter. For example, it may be a PCI device ID. It does not uniquely identify a given piece of hardware like a serial number.

description, of type DOMString, readonly

A human readable string describing the adapter as reported by the driver, if available. Empty string otherwise.

Note: Because no formatting is applied to description attempting to parse this value is not recommended. Applications which change their behavior based on the GPUAdapterInfo, such as applying workarounds for known driver issues, should rely on the other fields when possible.

3.7. 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.

3.8. Origin Restrictions

WebGPU allows accessing image data stored in images, videos, and canvases. Restrictions are imposed on the use of cross-domain media, because shaders can be used to indirectly deduce the contents of textures which have been uploaded to the GPU.

WebGPU disallows uploading an image source if it is not origin-clean.

This also implies that the origin-clean flag for a canvas rendered using WebGPU will never be set to false.

For more information on issuing CORS requests for image and video elements, consult:

• HTML § 2.5.4 CORS settings attributes

• HTML § 4.8.3 The img element img

• HTML § 4.8.11 Media elements HTMLMediaElement

3.9. Task Sources

3.9.1. WebGPU Task Source

WebGPU defines a new task source called the WebGPU task source. It is used for the uncapturederror event and GPUDevice.lost.

3.9.2. Automatic Expiry Task Source

WebGPU defines a new task source called the automatic expiry task source. It is used for the automatic, timed expiry (destruction) of certain objects:

• GPUTextures returned by getCurrentTexture()

• GPUExternalTextures created from HTMLVideoElements

Tasks from the automatic expiry task source should be processed with high priority; in particular, once queued, they should run before user-defined (JavaScript) tasks.

3.10. Color Spaces and Encoding

WebGPU does not provide color management. All values within WebGPU (such as texture elements) are raw numeric values, not color-managed color values.

WebGPU does interface with color-managed outputs (via GPUCanvasConfiguration) and inputs (via copyExternalImageToTexture() and importExternalTexture()). Thus, color conversion must be performed between the WebGPU numeric values and the external color values. Each such interface point locally defines an encoding (color space, transfer function, and alpha premultiplication) in which the WebGPU numeric values are to be interpreted.

WebGPU allows all of the color spaces in the PredefinedColorSpace enum. Note, each color space is defined over an extended range, as defined by the referenced CSS definitions, to represent color values outside of its space (in both chrominance and luminance).

An out-of-gamut premultiplied RGBA value is one where any of the R/G/B channel values exceeds the alpha channel value. For example, the premultiplied sRGB RGBA value [1.0, 0, 0, 0.5] represents the (unpremultiplied) color [2, 0, 0] with 50% alpha, written rgb(srgb 2 0 0 / 50%) in CSS. Just like any color value outside the sRGB color gamut, this is a well defined point in the extended color space (except when alpha is 0, in which case there is no color). However, when such values are output to a visible canvas, the result is undefined (see GPUCanvasAlphaMode "premultiplied").

3.10.1. Color Space Conversions

A color is converted between spaces by translating its representation in one space to a representation in another according to the definitions above.

If the source value has fewer than 4 RGBA channels, the missing green/blue/alpha channels are set to 0, 0, 1, respectively, before converting for color space/encoding and alpha premultiplication. After conversion, if the destination needs fewer than 4 channels, the additional channels are ignored.

Note: Grayscale images generally represent RGB values (V, V, V), or RGBA values (V, V, V, A) in their color space.

Colors are not lossily clamped during conversion: converting from one color space to another will result in values outside the range [0, 1] if the source color values were outside the range of the destination color space’s gamut. For an sRGB destination, for example, this can occur if the source is rgba16float, in a wider color space like Display-P3, or is premultiplied and contains out-of-gamut values.

Similarly, if the source value has a high bit depth (e.g. PNG with 16 bits per component) or extended range (e.g. canvas with float16 storage), these colors are preserved through color space conversion, with intermediate computations having at least the precision of the source.

3.10.2. Color Space Conversion Elision

If the source and destination of a color space/encoding conversion are the same, then conversion is not necessary. In general, if any given step of the conversion is an identity function (no-op), implementations should elide it, for performance.

For optimal performance, applications should set their color space and encoding options so that the number of necessary conversions is minimized throughout the process. For various image sources of GPUImageCopyExternalImage:

• ImageBitmap:

  • Premultiplication is controlled via premultiplyAlpha.

  • Color space is controlled via colorSpaceConversion.

• 2d canvas:

  • Always premultiplied.

  • Color space is controlled via the colorSpace context creation attribute.

• WebGL canvas:

  • Premultiplication is controlled via the premultipliedAlpha option in WebGLContextAttributes.

  • Color space is controlled via the WebGLRenderingContext's drawingBufferColorSpace state.

Note: Check browser implementation support for these features before relying on them.

3.11. Numeric conversions from JavaScript to WGSL

Several parts of the WebGPU API (pipeline-overridable constants and render pass clear values) take numeric values from WebIDL (double or float) and convert them to WGSL values (bool, i32, u32, f32, f16).

4. Initialization

4.1. navigator.gpu

A GPU object is available in the Window and DedicatedWorkerGlobalScope contexts through the Navigator and WorkerNavigator interfaces respectively and is exposed via navigator.gpu:

interface mixin NavigatorGPU {
    [SameObject, SecureContext] readonly attribute GPU gpu;
};
Navigator includes NavigatorGPU;
WorkerNavigator includes NavigatorGPU;

NavigatorGPU has the following attributes:

gpu, of type GPU, readonly

A global singleton providing top-level entry points like requestAdapter().

4.2. GPU

GPU is the entry point to WebGPU.

[Exposed=(Window, DedicatedWorker), SecureContext]
interface GPU {
    Promise<GPUAdapter?> requestAdapter(optional GPURequestAdapterOptions options = {});
    GPUTextureFormat getPreferredCanvasFormat();
    [SameObject] readonly attribute WGSLLanguageFeatures wgslLanguageFeatures;
};

GPU has the following methods and attributes:

requestAdapter(options)

Requests an adapter from the user agent. The user agent chooses whether to return an adapter, and, if so, chooses according to the provided options.

Called on: GPU this.

Arguments:

Arguments for the GPU.requestAdapter(options) method.

Parameter	Type	Nullable	Optional	Description
options	GPURequestAdapterOptions	✘	✔	Criteria used to select the adapter.

Returns: Promise<GPUAdapter?>

Content timeline steps:

1. Let contentTimeline be the current Content timeline.

2. Let promise be a new promise.

3. Issue the initialization steps on the Device timeline of this.

4. Return promise.

Device timeline initialization steps:

1. Let adapter be null.

2. If the user agent chooses to return an adapter, it should:

   1. Set adapter to a valid adapter, chosen according to the rules in § 4.2.2 Adapter Selection and the criteria in options, adhering to § 4.2.1 Adapter Capability Guarantees.

      The supported limits of the adapter must adhere to the requirements defined in § 3.6.2 Limits.

   2. If adapter meets the criteria of a fallback adapter set adapter.[[fallback]] to true.

3. Issue the subsequent steps on contentTimeline.

Content timeline steps:

1. If adapter is not null:

   1. Resolve promise with a new GPUAdapter encapsulating adapter.

2. Otherwise, Resolve promise with null.

getPreferredCanvasFormat()

Returns an optimal GPUTextureFormat for displaying 8-bit depth, standard dynamic range content on this system. Must only return "rgba8unorm" or "bgra8unorm".

The returned value can be passed as the format to configure() calls on a GPUCanvasContext to ensure the associated canvas is able to display its contents efficiently.

Note: Canvases which are not displayed to the screen may or may not benefit from using this format.

Called on: GPU this.

Returns: GPUTextureFormat

Content timeline steps:

1. Return either "rgba8unorm" or "bgra8unorm", depending on which format is optimal for displaying WebGPU canvases on this system.

wgslLanguageFeatures, of type WGSLLanguageFeatures, readonly

The names of supported WGSL language extensions. Supported language extensions are automatically enabled.

Adapters may become invalid ("expire") at any time. Upon any change in the system’s state that could affect the result of any requestAdapter() call, the user agent should expire all previously-returned adapters. For example:

• A physical adapter is added/removed (via plug/unplug, driver update, hang recovery, etc.)

• The system’s power configuration has changed (laptop unplugged, power settings changed, etc.)

Note: User agents may choose to expire adapters often, even when there has been no system state change (e.g. seconds or minutes after the adapter was created). This can help obfuscate real system state changes, and make developers more aware that calling requestAdapter() again is always necessary before calling requestDevice(). If an application does encounter this situation, standard device-loss recovery handling should allow it to recover.

const gpuAdapter = await navigator.gpu.requestAdapter();

4.2.1. Adapter Capability Guarantees

Any GPUAdapter returned by requestAdapter() must provide the following guarantees:

• At least one of the following must be true:

  • "texture-compression-bc" is supported.

  • Both "texture-compression-etc2" and "texture-compression-astc" are supported.

• All supported limits must be either the default value or better.

• All alignment-class limits must be powers of 2.

• maxBindingsPerBindGroup must be must be ≥ (max bindings per shader stage × max shader stages per pipeline), where:

  • max bindings per shader stage is (maxSampledTexturesPerShaderStage + maxSamplersPerShaderStage + maxStorageBuffersPerShaderStage + maxStorageTexturesPerShaderStage + maxUniformBuffersPerShaderStage).

  • max shader stages per pipeline is 2, because a GPURenderPipeline supports both a vertex and fragment shader.

  Note: maxBindingsPerBindGroup does not reflect a fundamental limit; implementations should raise it to conform to this requirement, rather than lowering the other limits.

• maxBindGroups must be ≤ maxBindGroupsPlusVertexBuffers.

• maxVertexBuffers must be ≤ maxBindGroupsPlusVertexBuffers.

• minUniformBufferOffsetAlignment and minStorageBufferOffsetAlignment must both be ≥ 32 bytes.

  Note: 32 bytes would be the alignment of vec4<f64>. See WebGPU Shading Language § 13.4.1 Alignment and Size.

• maxUniformBufferBindingSize must be ≤ maxBufferSize.

• maxStorageBufferBindingSize must be ≤ maxBufferSize.

• maxStorageBufferBindingSize must be a multiple of 4 bytes.

• maxVertexBufferArrayStride must be a multiple of 4 bytes.

• maxComputeWorkgroupSizeX must be ≤ maxComputeInvocationsPerWorkgroup.

• maxComputeWorkgroupSizeY must be ≤ maxComputeInvocationsPerWorkgroup.

• maxComputeWorkgroupSizeZ must be ≤ maxComputeInvocationsPerWorkgroup.

• maxComputeInvocationsPerWorkgroup must be ≤ maxComputeWorkgroupSizeX × maxComputeWorkgroupSizeY × maxComputeWorkgroupSizeZ.

4.2.2. Adapter Selection

GPURequestAdapterOptions provides hints to the user agent indicating what configuration is suitable for the application.

dictionary GPURequestAdapterOptions {
    GPUPowerPreference powerPreference;
    boolean forceFallbackAdapter = false;
};

enum GPUPowerPreference {
    "low-power",
    "high-performance",
};

GPURequestAdapterOptions has the following members:

powerPreference, of type GPUPowerPreference

Optionally provides a hint indicating what class of adapter should be selected from the system’s available adapters.

The value of this hint may influence which adapter is chosen, but it must not influence whether an adapter is returned or not.

Note: The primary utility of this hint is to influence which GPU is used in a multi-GPU system. For instance, some laptops have a low-power integrated GPU and a high-performance discrete GPU. This hint may also affect the power configuration of the selected GPU to match the requested power preference.

Note: Depending on the exact hardware configuration, such as battery status and attached displays or removable GPUs, the user agent may select different adapters given the same power preference. Typically, given the same hardware configuration and state and powerPreference, the user agent is likely to select the same adapter.

It must be one of the following values:

undefined (or not present)

Provides no hint to the user agent.

"low-power"

Indicates a request to prioritize power savings over performance.

Note: Generally, content should use this if it is unlikely to be constrained by drawing performance; for example, if it renders only one frame per second, draws only relatively simple geometry with simple shaders, or uses a small HTML canvas element. Developers are encouraged to use this value if their content allows, since it may significantly improve battery life on portable devices.

"high-performance"

Indicates a request to prioritize performance over power consumption.

Note: By choosing this value, developers should be aware that, for devices created on the resulting adapter, user agents are more likely to force device loss, in order to save power by switching to a lower-power adapter. Developers are encouraged to only specify this value if they believe it is absolutely necessary, since it may significantly decrease battery life on portable devices.

forceFallbackAdapter, of type boolean, defaulting to false

When set to true indicates that only a fallback adapter may be returned. If the user agent does not support a fallback adapter, will cause requestAdapter() to resolve to null.

Note: requestAdapter() may still return a fallback adapter if forceFallbackAdapter is set to false and either no other appropriate adapter is available or the user agent chooses to return a fallback adapter. Developers that wish to prevent their applications from running on fallback adapters should check the GPUAdapter.isFallbackAdapter attribute prior to requesting a GPUDevice.

const gpuAdapter = await navigator.gpu.requestAdapter({
    powerPreference: 'high-performance'
});

4.3. GPUAdapter

A GPUAdapter encapsulates an adapter, and describes its capabilities (features and limits).

To get a GPUAdapter, use requestAdapter().

[Exposed=(Window, DedicatedWorker), SecureContext]
interface GPUAdapter {
    [SameObject] readonly attribute GPUSupportedFeatures features;
    [SameObject] readonly attribute GPUSupportedLimits limits;
    readonly attribute boolean isFallbackAdapter;

    Promise<GPUDevice> requestDevice(optional GPUDeviceDescriptor descriptor = {});
    Promise<GPUAdapterInfo> requestAdapterInfo();
};

GPUAdapter has the following attributes:

features, of type GPUSupportedFeatures, readonly

The set of values in this.[[adapter]].[[features]].

limits, of type GPUSupportedLimits, readonly

The limits in this.[[adapter]].[[limits]].

isFallbackAdapter, of type boolean, readonly

Returns the value of [[adapter]].[[fallback]].

GPUAdapter has the following internal slots:

[[adapter]], of type adapter, readonly

The adapter to which this GPUAdapter refers.

GPUAdapter has the following methods:

requestDevice(descriptor)

Requests a device from the adapter.

This is a one-time action: if a device is returned successfully, the adapter becomes invalid.

Called on: GPUAdapter this.

Arguments:

Arguments for the GPUAdapter.requestDevice(descriptor) method.

Parameter	Type	Nullable	Optional	Description
descriptor	GPUDeviceDescriptor	✘	✔	Description of the GPUDevice to request.

Returns: Promise<GPUDevice>

Content timeline steps:

1. Let contentTimeline be the current Content timeline.

2. Let promise be a new promise.

3. Let adapter be this.[[adapter]].

4. Issue the initialization steps to the Device timeline of this.

5. Return promise.

Device timeline initialization steps:

1. If any of the following requirements are unmet:

   • The set of values in descriptor.requiredFeatures must be a subset of those in adapter.[[features]].

   Then issue the following steps on contentTimeline and return:

   Content timeline steps:

   1. Reject promise with a TypeError.

   Note: This is the same error that is produced if a feature name isn’t known by the browser at all (in its GPUFeatureName definition). This converges the behavior when the browser doesn’t support a feature with the behavior when a particular adapter doesn’t support a feature.

2. If any of the following requirements are unmet:

   • Each key in descriptor.requiredLimits must be the name of a member of supported limits.

   • For each limit name key in the keys of supported limits: Let value be descriptor.requiredLimits[key].

     • value must be no better than the value of that limit in adapter.[[limits]].

     • If the limit’s class is alignment, value must be a power of 2 less than 2³².

   Then issue the following steps on contentTimeline and return:

   Content timeline steps:

   1. Reject promise with an OperationError.

3. If adapter is invalid, or the user agent otherwise cannot fulfill the request:

   1. Let device be a new device.

   2. Lose the device(device, "unknown").

      Note: This makes adapter invalid, if it wasn’t already.

      Note: User agents should consider issuing developer-visible warnings in most or all cases when this occurs. Applications should perform reinitialization logic starting with requestAdapter().

   Otherwise:

   1. Let device be a new device with the capabilities described by descriptor.

   2. Make adapter.[[adapter]] invalid.

4. Issue the subsequent steps on contentTimeline.

Content timeline steps:

1. Resolve promise with a new GPUDevice object device.

   Note: If the device is already lost because the adapter could not fulfill the request, device.lost has already resolved before promise resolves.

requestAdapterInfo()

Requests the GPUAdapterInfo for this GPUAdapter.

Note: Adapter info values are returned with a Promise to give user agents an opportunity to perform potentially long-running checks in the future.

Called on: GPUAdapter this.

Returns: Promise<GPUAdapterInfo>

Content timeline steps:

1. Let promise be a new promise.

2. Let adapter be this.[[adapter]].

3. Run the following steps in parallel:

   1. Resolve promise with a new adapter info for adapter.

4. Return promise.

const gpuAdapter = await navigator.gpu.requestAdapter();
const gpuDevice = await gpuAdapter.requestDevice();

4.3.1. GPUDeviceDescriptor

GPUDeviceDescriptor describes a device request.

dictionary GPUDeviceDescriptor
         : GPUObjectDescriptorBase {
    sequence<GPUFeatureName> requiredFeatures = [];
    record<DOMString, GPUSize64> requiredLimits = {};
    GPUQueueDescriptor defaultQueue = {};
};

GPUDeviceDescriptor has the following members:

requiredFeatures, of type sequence<GPUFeatureName>, defaulting to []

Specifies the features that are required by the device request. The request will fail if the adapter cannot provide these features.

Exactly the specified set of features, and no more or less, will be allowed in validation of API calls on the resulting device.

requiredLimits, of type record<DOMString, GPUSize64>, defaulting to {}

Specifies the limits that are required by the device request. The request will fail if the adapter cannot provide these limits.

Each key must be the name of a member of supported limits. Exactly the specified limits, and no better or worse, will be allowed in validation of API calls on the resulting device.

defaultQueue, of type GPUQueueDescriptor, defaulting to {}

The descriptor for the default GPUQueue.

const gpuAdapter = await navigator.gpu.requestAdapter();

const requiredFeatures = [];
if (gpuAdapter.features.has('texture-compression-astc')) {
    requiredFeatures.push('texture-compression-astc')
}

const gpuDevice = await gpuAdapter.requestDevice({
    requiredFeatures
});

const gpuAdapter = await navigator.gpu.requestAdapter();

if (gpuAdapter.limits.maxColorAttachmentBytesPerSample < 64) {
    // When the desired limit isn’t supported, take action to either fall back to a code
    // path that does not require the higher limit or notify the user that their device
    // does not meet minimum requirements.
}

// Request higher limit of max color attachments bytes per sample.
const gpuDevice = await gpuAdapter.requestDevice({
    requiredLimits: { maxColorAttachmentBytesPerSample: 64 },
});

4.3.1.1. GPUFeatureName

Each GPUFeatureName identifies a set of functionality which, if available, allows additional usages of WebGPU that would have otherwise been invalid.

enum GPUFeatureName {
    "depth-clip-control",
    "depth32float-stencil8",
    "texture-compression-bc",
    "texture-compression-etc2",
    "texture-compression-astc",
    "timestamp-query",
    "indirect-first-instance",
    "shader-f16",
    "rg11b10ufloat-renderable",
    "bgra8unorm-storage",
    "float32-filterable",
};

4.4. GPUDevice

A GPUDevice encapsulates a device and exposes the functionality of that device.

GPUDevice is the top-level interface through which WebGPU interfaces are created.

To get a GPUDevice, use requestDevice().

[Exposed=(Window, DedicatedWorker), SecureContext]
interface GPUDevice : EventTarget {
    [SameObject] readonly attribute GPUSupportedFeatures features;
    [SameObject] readonly attribute GPUSupportedLimits limits;

    [SameObject] readonly attribute GPUQueue queue;

    undefined destroy();

    GPUBuffer createBuffer(GPUBufferDescriptor descriptor);
    GPUTexture createTexture(GPUTextureDescriptor descriptor);
    GPUSampler createSampler(optional GPUSamplerDescriptor descriptor = {});
    GPUExternalTexture importExternalTexture(GPUExternalTextureDescriptor descriptor);

    GPUBindGroupLayout createBindGroupLayout(GPUBindGroupLayoutDescriptor descriptor);
    GPUPipelineLayout createPipelineLayout(GPUPipelineLayoutDescriptor descriptor);
    GPUBindGroup createBindGroup(GPUBindGroupDescriptor descriptor);

    GPUShaderModule createShaderModule(GPUShaderModuleDescriptor descriptor);
    GPUComputePipeline createComputePipeline(GPUComputePipelineDescriptor descriptor);
    GPURenderPipeline createRenderPipeline(GPURenderPipelineDescriptor descriptor);
    Promise<GPUComputePipeline> createComputePipelineAsync(GPUComputePipelineDescriptor descriptor);
    Promise<GPURenderPipeline> createRenderPipelineAsync(GPURenderPipelineDescriptor descriptor);

    GPUCommandEncoder createCommandEncoder(optional GPUCommandEncoderDescriptor descriptor = {});
    GPURenderBundleEncoder createRenderBundleEncoder(GPURenderBundleEncoderDescriptor descriptor);

    GPUQuerySet createQuerySet(GPUQuerySetDescriptor descriptor);
};
GPUDevice includes GPUObjectBase;

GPUDevice has the following attributes:

features, of type GPUSupportedFeatures, readonly

A set containing the GPUFeatureName values of the features supported by the device (i.e. the ones with which it was created).

limits, of type GPUSupportedLimits, readonly

Exposes the limits supported by the device (which are exactly the ones with which it was created).

queue, of type GPUQueue, readonly

The primary GPUQueue for this device.

The [[device]] for a GPUDevice is the device that the GPUDevice refers to.

GPUDevice has the methods listed in its WebIDL definition above. Those not defined here are defined elsewhere in this document.

destroy()

Destroys the device, preventing further operations on it. Outstanding asynchronous operations will fail.

Note: It is valid to destroy a device multiple times.

Called on: GPUDevice this.

Content timeline steps:

1. unmap() all GPUBuffers from this device.

2. Issue the subsequent steps on the Device timeline of this.

Device timeline steps:

1. Once all currently-enqueued operations on any queue on this device are completed, issue the subsequent steps on the current timeline.

1. Lose the device(this.[[device]], "destroyed").

Note: Since no further operations can be enqueued on this device, implementations can abort outstanding asynchronous operations immediately and free resource allocations, including mapped memory that was just unmapped.

4.5. Example

let gpuDevice = null;

async function initializeWebGPU() {
    // Check to ensure the user agent supports WebGPU.
    if (!('gpu' in navigator)) {
        console.error("User agent doesn’t support WebGPU.");
        return false;
    }

    // Request an adapter.
    const gpuAdapter = await navigator.gpu.requestAdapter();

    // requestAdapter may resolve with null if no suitable adapters are found.
    if (!gpuAdapter) {
        console.error('No WebGPU adapters found.');
        return false;
    }

    // Request a device.
    // Note that the promise will reject if invalid options are passed to the optional
    // dictionary. To avoid the promise rejecting always check any features and limits
    // against the adapters features and limits prior to calling requestDevice().
    gpuDevice = await gpuAdapter.requestDevice();

    // requestDevice will never return null, but if a valid device request can’t be
    // fulfilled for some reason it may resolve to a device which has already been lost.
    // Additionally, devices can be lost at any time after creation for a variety of reasons
    // (ie: browser resource management, driver updates), so it’s a good idea to always
    // handle lost devices gracefully.
    gpuDevice.lost.then((info) => {
        console.error(`WebGPU device was lost: ${info.message}`);

        gpuDevice = null;

        // Many causes for lost devices are transient, so applications should try getting a
        // new device once a previous one has been lost unless the loss was caused by the
        // application intentionally destroying the device. Note that any WebGPU resources
        // created with the previous device (buffers, textures, etc) will need to be
        // re-created with the new one.
        if (info.reason != 'destroyed') {
            initializeWebGPU();
        }
    });

    onWebGPUInitialized();

    return true;
}

function onWebGPUInitialized() {
    // Begin creating WebGPU resources here...
}

initializeWebGPU();

5. Buffers

5.1. GPUBuffer

A GPUBuffer represents a block of memory that can be used in GPU operations. Data is stored in linear layout, meaning that each byte of the allocation can be addressed by its offset from the start of the GPUBuffer, subject to alignment restrictions depending on the operation. Some GPUBuffers can be mapped which makes the block of memory accessible via an ArrayBuffer called its mapping.

GPUBuffers are created via createBuffer(). Buffers may be mappedAtCreation.

[Exposed=(Window, DedicatedWorker), SecureContext]
interface GPUBuffer {
    readonly attribute GPUSize64Out size;
    readonly attribute GPUFlagsConstant usage;

    readonly attribute GPUBufferMapState mapState;

    Promise<undefined> mapAsync(GPUMapModeFlags mode, optional GPUSize64 offset = 0, optional GPUSize64 size);
    ArrayBuffer getMappedRange(optional GPUSize64 offset = 0, optional GPUSize64 size);
    undefined unmap();

    undefined destroy();
};
GPUBuffer includes GPUObjectBase;

enum GPUBufferMapState {
    "unmapped",
    "pending",
    "mapped",
};

GPUBuffer has the following immutable properties:

size, of type GPUSize64Out, readonly

The length of the GPUBuffer allocation in bytes.

usage, of type GPUFlagsConstant, readonly

The allowed usages for this GPUBuffer.

[[internals]], of type buffer internals, readonly, override

GPUBuffer has the following content timeline properties:

mapState, of type GPUBufferMapState, readonly

The current GPUBufferMapState of the buffer:

"unmapped"

The buffer is not mapped for use by this.getMappedRange().

"pending"

A mapping of the buffer has been requested, but is pending. It may succeed, or fail validation in mapAsync().

"mapped"

The buffer is mapped and this.getMappedRange() may be used.

The getter steps are:

Content timeline steps:

1. If this.[[mapping]] is not null, return "mapped".

2. If this.[[pending_map]] is not null, return "pending".

3. Return "unmapped".

[[pending_map]], of type Promise<void> or null, initially null

The Promise returned by the currently-pending mapAsync() call.

There is never more than one pending map, because mapAsync() will refuse immediately if a request is already in flight.

[[mapping]], of type active buffer mapping or null, initially null

Set if and only if the buffer is currently mapped for use by getMappedRange(). Null otherwise (even if there is a [[pending_map]]).

An active buffer mapping is a structure with the following fields:

data, of type Data Block

The mapping for this GPUBuffer. This data is accessed through ArrayBuffers which are views onto this data, returned by getMappedRange() and stored in views.

mode, of type GPUMapModeFlags

The GPUMapModeFlags of the map, as specified in the corresponding call to mapAsync() or createBuffer().

range, of type tuple [unsigned long long, unsigned long long]

The range of this GPUBuffer that is mapped.

views, of type list<ArrayBuffer>

The ArrayBuffers returned via getMappedRange() to the application. They are tracked so they can be detached when unmap() is called.

To initialize an active buffer mapping with mode mode and range range:

1. Let size be range[1] - range[0].

2. Let data be ? CreateByteDataBlock(size).

   NOTE:

   This may result in a RangeError being thrown. For consistency and predictability:

   • For any size at which new ArrayBuffer() would succeed at a given moment, this allocation should succeed at that moment.

   • For any size at which new ArrayBuffer() deterministically throws a RangeError, this allocation should as well.

3. Return an active buffer mapping with:

   • data set to data.

   • mode set to mode.

   • range set to range.

   • views set to [].

GPUBuffer's internal object is buffer internals, which extends internal object with the following device timeline slots:

state

The current internal state of the buffer:

"available"

The buffer may be used in queue operations (unless it is invalid).

"unavailable"

The buffer may not be used in queue operations due to being mapped.

"destroyed"

The buffer may not be used in any operations due to being destroy()ed.

5.1.1. GPUBufferDescriptor

dictionary GPUBufferDescriptor
         : GPUObjectDescriptorBase {
    required GPUSize64 size;
    required GPUBufferUsageFlags usage;
    boolean mappedAtCreation = false;
};

GPUBufferDescriptor has the following members:

size, of type GPUSize64

The size of the buffer in bytes.

usage, of type GPUBufferUsageFlags

The allowed usages for the buffer.

mappedAtCreation, of type boolean, defaulting to false

If true creates the buffer in an already mapped state, allowing getMappedRange() to be called immediately. It is valid to set mappedAtCreation to true even if usage does not contain MAP_READ or MAP_WRITE. This can be used to set the buffer’s initial data.

Guarantees that even if the buffer creation eventually fails, it will still appear as if the mapped range can be written/read to until it is unmapped.

5.1.2. Buffer Usages

typedef [EnforceRange] unsigned long GPUBufferUsageFlags;
[Exposed=(Window, DedicatedWorker), SecureContext]
namespace GPUBufferUsage {
    const GPUFlagsConstant MAP_READ      = 0x0001;
    const GPUFlagsConstant MAP_WRITE     = 0x0002;
    const GPUFlagsConstant COPY_SRC      = 0x0004;
    const GPUFlagsConstant COPY_DST      = 0x0008;
    const GPUFlagsConstant INDEX         = 0x0010;
    const GPUFlagsConstant VERTEX        = 0x0020;
    const GPUFlagsConstant UNIFORM       = 0x0040;
    const GPUFlagsConstant STORAGE       = 0x0080;
    const GPUFlagsConstant INDIRECT      = 0x0100;
    const GPUFlagsConstant QUERY_RESOLVE = 0x0200;
};

The GPUBufferUsage flags determine how a GPUBuffer may be used after its creation:

MAP_READ

The buffer can be mapped for reading. (Example: calling mapAsync() with GPUMapMode.READ)

May only be combined with COPY_DST.

MAP_WRITE

The buffer can be mapped for writing. (Example: calling mapAsync() with GPUMapMode.WRITE)

May only be combined with COPY_SRC.

COPY_SRC

The buffer can be used as the source of a copy operation. (Examples: as the source argument of a copyBufferToBuffer() or copyBufferToTexture() call.)

COPY_DST

The buffer can be used as the destination of a copy or write operation. (Examples: as the destination argument of a copyBufferToBuffer() or copyTextureToBuffer() call, or as the target of a writeBuffer() call.)

INDEX

The buffer can be used as an index buffer. (Example: passed to setIndexBuffer().)

VERTEX

The buffer can be used as a vertex buffer. (Example: passed to setVertexBuffer().)

UNIFORM

The buffer can be used as a uniform buffer. (Example: as a bind group entry for a GPUBufferBindingLayout with a buffer.type of "uniform".)

STORAGE

The buffer can be used as a storage buffer. (Example: as a bind group entry for a GPUBufferBindingLayout with a buffer.type of "storage" or "read-only-storage".)

INDIRECT

The buffer can be used as to store indirect command arguments. (Examples: as the indirectBuffer argument of a drawIndirect() or dispatchWorkgroupsIndirect() call.)

QUERY_RESOLVE

The buffer can be used to capture query results. (Example: as the destination argument of a resolveQuerySet() call.)

5.1.3. Buffer Creation

createBuffer(descriptor)

Creates a GPUBuffer.

Called on: GPUDevice this.

Arguments:

Arguments for the GPUDevice.createBuffer(descriptor) method.

Parameter	Type	Nullable	Optional	Description
descriptor	GPUBufferDescriptor	✘	✘	Description of the GPUBuffer to create.

Returns: GPUBuffer

Content timeline steps:

1. Let [b, bi] be ! create a new WebGPU object(this, GPUBuffer, descriptor).

2. Set b.size to descriptor.size.

3. Set b.usage to descriptor.usage.

4. If descriptor.mappedAtCreation is true:

   1. Set b.[[mapping]] to ? initialize an active buffer mapping with mode WRITE and range [0, descriptor.size].

5. Issue the initialization steps on the Device timeline of this.

6. Return b.

Device timeline initialization steps:

1. If any of the following requirements are unmet, generate a validation error, make bi invalid, and stop.

   • device must be valid.

   • descriptor.usage must not be 0.

   • descriptor.usage must be a subset of device’s allowed buffer usages.

   • If descriptor.usage contains MAP_READ:

     • descriptor.usage must contain no other flags except COPY_DST.

   • If descriptor.usage contains MAP_WRITE:

     • descriptor.usage must contain no other flags except COPY_SRC.

   • If descriptor.size must be ≤ device.[[device]].[[limits]].maxBufferSize.

   • If descriptor.mappedAtCreation is true:

     • descriptor.size must be a multiple of 4.

Note: If buffer creation fails, and descriptor.mappedAtCreation is false, any calls to mapAsync() will reject, so any resources allocated to enable mapping can and may be discarded or recycled.

1. If descriptor.mappedAtCreation is true:

   1. Set bi.state to "unavailable".

   Else:

   1. Set bi.state to "available".

2. Create a device allocation for bi where each byte is zero.

   If the allocation fails without side-effects, generate an out-of-memory error, make bi invalid, and return.

const buffer = gpuDevice.createBuffer({
    size: 128,
    usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST
});

5.1.4. Buffer Destruction

An application that no longer requires a GPUBuffer can choose to lose access to it before garbage collection by calling destroy(). Destroying a buffer also unmaps it, freeing any memory allocated for the mapping.

Note: This allows the user agent to reclaim the GPU memory associated with the GPUBuffer once all previously submitted operations using it are complete.

destroy()

Destroys the GPUBuffer.

Note: It is valid to destroy a buffer multiple times.

Called on: GPUBuffer this.

Returns: undefined

Content timeline steps:

1. Call this.unmap().

2. Issue the subsequent steps on the Device timeline of this.[[device]].

Device timeline steps:

1. Set this.[[internals]].state to "destroyed".

Note: Since no further operations can be enqueued using this buffer, implementations can free resource allocations, including mapped memory that was just unmapped.

5.2. Buffer Mapping

An application can request to map a GPUBuffer so that they can access its content via ArrayBuffers that represent part of the GPUBuffer's allocations. Mapping a GPUBuffer is requested asynchronously with mapAsync() so that the user agent can ensure the GPU finished using the GPUBuffer before the application can access its content. A mapped GPUBuffer cannot be used by the GPU and must be unmapped using unmap() before work using it can be submitted to the Queue timeline.

Once the GPUBuffer is mapped, the application can synchronously ask for access to ranges of its content with getMappedRange(). The returned ArrayBuffer can only be detached by unmap() (directly, or via GPUBuffer.destroy() or GPUDevice.destroy()), and cannot be transferred. A TypeError is thrown by any other operation that attempts to do so.

typedef [EnforceRange] unsigned long GPUMapModeFlags;
[Exposed=(Window, DedicatedWorker), SecureContext]
namespace GPUMapMode {
    const GPUFlagsConstant READ  = 0x0001;
    const GPUFlagsConstant WRITE = 0x0002;
};

The GPUMapMode flags determine how a GPUBuffer is mapped when calling mapAsync():

READ

Only valid with buffers created with the MAP_READ usage.

Once the buffer is mapped, calls to getMappedRange() will return an ArrayBuffer containing the buffer’s current values. Changes to the returned ArrayBuffer will be discarded after unmap() is called.

WRITE

Only valid with buffers created with the MAP_WRITE usage.

Once the buffer is mapped, calls to getMappedRange() will return an ArrayBuffer containing the buffer’s current values. Changes to the returned ArrayBuffer will be stored in the GPUBuffer after unmap() is called.

Note: Since the MAP_WRITE buffer usage may only be combined with the COPY_SRC buffer usage, mapping for writing can never return values produced by the GPU, and the returned ArrayBuffer will only ever contain the default initialized data (zeros) or data written by the webpage during a previous mapping.

mapAsync(mode, offset, size)

Maps the given range of the GPUBuffer and resolves the returned Promise when the GPUBuffer's content is ready to be accessed with getMappedRange().

The resolution of the returned Promise only indicates that the buffer has been mapped. It does not guarantee the completion of any other operations visible to the content timeline, and in particular does not imply that any other Promise returned from onSubmittedWorkDone() or mapAsync() on other GPUBuffers have resolved.

The resolution of the Promise returned from onSubmittedWorkDone() does imply the completion of mapAsync() calls made prior to that call, on GPUBuffers last used exclusively on that queue.

Called on: GPUBuffer this.

Arguments:

Arguments for the GPUBuffer.mapAsync(mode, offset, size) method.

Parameter	Type	Nullable	Optional	Description
mode	GPUMapModeFlags	✘	✘	Whether the buffer should be mapped for reading or writing.
offset	GPUSize64	✘	✔	Offset in bytes into the buffer to the start of the range to map.
size	GPUSize64	✘	✔	Size in bytes of the range to map.

Returns: Promise<undefined>

Content timeline steps:

1. Let contentTimeline be the current Content timeline.

2. If this.[[pending_map]] is not null:

   1. Return a promise rejected with OperationError.

3. Let p be a new Promise.

4. Set this.[[pending_map]] to p.

5. Issue the validation steps on the Device timeline of this.[[device]].

6. Return p.

Device timeline validation steps:

1. If size is undefined:

   1. Let rangeSize be max(0, this.size - offset).

   Otherwise:

   1. Let rangeSize be size.

2. If any of the following conditions are unsatisfied:

   • this is a valid GPUBuffer.

   • this.[[internals]].state is "available".

   • offset is a multiple of 8.

   • rangeSize is a multiple of 4.

   • offset + rangeSize ≤ this.size

   • mode contains only bits defined in GPUMapMode.

   • mode contains exactly one of READ or WRITE.

   • If mode contains READ then this.usage must contain MAP_READ.

   • If mode contains WRITE then this.usage must contain MAP_WRITE.

   Then:

   1. Issue the map failure steps on contentTimeline.

   2. Generate a validation error.

   3. Return.

3. Set this.[[internals]].state to "unavailable".

   Note: Since the buffer is mapped, its contents cannot change between this completion and unmap().

4. If this.[[device]] is lost, or when it becomes lost:

   1. Issue the map failure steps on contentTimeline.

   Otherwise, at an unspecified point:

   • after the completion of currently-enqueued operations that use this,

   • and no later than the next device timeline operation after the device timeline becomes informed of the completion of all currently-enqueued operations (regardless of whether they use this),

   run the following steps:

   1. Let internalStateAtCompletion be this.[[internals]].state.

      Note: If, and only if, at this point the buffer has become "available" again due to an unmap() call, then [[pending_map]] != p below, so mapping will not succeed in the steps below.

   2. Let dataForMappedRegion be the contents of this starting at offset offset, for rangeSize bytes.

   3. Issue the map success steps on the contentTimeline.

Content timeline map success steps:

1. If this.[[pending_map]] != p:

   Note: The map has been cancelled by unmap().

   1. Assert p is rejected.

   2. Return.

2. Assert p is pending.

3. Assert internalStateAtCompletion is "unavailable".

4. Let mapping be initialize an active buffer mapping with mode mode and range [offset, offset + rangeSize].

   If this allocation fails:

   1. Set this.[[pending_map]] to null, and reject p with a RangeError.

   2. Return.

5. Set the content of mapping.data to dataForMappedRegion.

6. Set this.[[mapping]] to mapping.

7. Set this.[[pending_map]] to null, and resolve p.

Content timeline map failure steps:

1. If this.[[pending_map]] != p:

   Note: The map has been cancelled by unmap().

   1. Assert p is already rejected.

   2. Return.

2. Assert p is still pending.

3. Set this.[[pending_map]] to null, and reject p with an OperationError.

getMappedRange(offset, size)

Returns an ArrayBuffer with the contents of the GPUBuffer in the given mapped range.

Called on: GPUBuffer this.

Arguments:

Arguments for the GPUBuffer.getMappedRange(offset, size) method.

Parameter	Type	Nullable	Optional	Description
offset	GPUSize64	✘	✔	Offset in bytes into the buffer to return buffer contents from.
size	GPUSize64	✘	✔	Size in bytes of the ArrayBuffer to return.

Returns: ArrayBuffer

Content timeline steps:

1. If size is missing:

   1. Let rangeSize be max(0, this.size - offset).

   Otherwise, let rangeSize be size.

2. If any of the following conditions are unsatisfied, throw an OperationError and stop.

   • this.[[mapping]] is not null.

   • offset is a multiple of 8.

   • rangeSize is a multiple of 4.

   • offset ≥ this.[[mapping]].range[0].

   • offset + rangeSize ≤ this.[[mapping]].range[1].

   • [offset, offset + rangeSize) does not overlap another range in this.[[mapping]].views.

   Note: It is always valid to get mapped ranges of a GPUBuffer that is mappedAtCreation, even if it is invalid, because the Content timeline might not know it is invalid.

3. Let data be this.[[mapping]].data.

4. Let view be ! create an ArrayBuffer of size rangeSize, but with its pointer mutably referencing the content of data at offset (offset - [[mapping]].range[0]).

   Note: A RangeError may not be thrown here, because the data has already been allocated during mapAsync() or createBuffer().

5. Set view.[[ArrayBufferDetachKey]] to "WebGPUBufferMapping".

   Note: This causes a TypeError to be thrown if an attempt is made to DetachArrayBuffer, except by unmap().

6. Append view to this.[[mapping]].views.

7. Return view.

Note: User agents should consider issuing a developer-visible warning if getMappedRange() succeeds without having checked the status of the map, by waiting for mapAsync() to succeed, querying a mapState of "mapped", or waiting for a later onSubmittedWorkDone() call to succeed.

unmap()

Unmaps the mapped range of the GPUBuffer and makes it’s contents available for use by the GPU again.

Called on: GPUBuffer this.

Returns: undefined

Content timeline steps:

1. If this.[[pending_map]] is not null:

   1. Reject this.[[pending_map]] with an AbortError.

   2. Set this.[[pending_map]] to null.

2. If this.[[mapping]] is null:

   1. Return.

3. For each ArrayBuffer ab in this.[[mapping]].views:

   1. Perform DetachArrayBuffer(ab, "WebGPUBufferMapping").

4. Let bufferUpdate be null.

5. If this.[[mapping]].mode contains WRITE:

   1. Set bufferUpdate to { data: this.[[mapping]].data, offset: this.[[mapping]].range[0] }.

   Note: When a buffer is mapped without the WRITE mode, then unmapped, any local modifications done by the application to the mapped ranges ArrayBuffer are discarded and will not affect the content of later mappings.

6. Set this.[[mapping]] to null.

7. Issue the subsequent steps on the Device timeline of this.[[device]].

Device timeline steps:

1. If this.[[device]] is invalid, return.

2. If bufferUpdate is not null:

   1. Issue the following steps on the Queue timeline of this.[[device]].queue:

      Queue timeline steps:

      1. Update the contents of this at offset bufferUpdate.offset with the data bufferUpdate.data.

3. Set this.[[internals]].state to "available".

6. Textures and Texture Views

6.1. GPUTexture

Remove this definition: texture

One texture consists of one or more texture subresources, each uniquely identified by a mipmap level and, for 2d textures only, array layer and aspect.

A texture subresource is a subresource: each can be used in different internal usages within a single usage scope.

Each subresource in a mipmap level is approximately half the size, in each spatial dimension, of the corresponding resource in the lesser level (see logical miplevel-specific texture extent). The subresource in level 0 has the dimensions of the texture itself. These are typically used to represent levels of detail of a texture. GPUSampler and WGSL provide facilities for selecting and interpolating between levels of detail, explicitly or automatically.

A "2d" texture may be an array of array layers. Each subresource in a layer is the same size as the corresponding resources in other layers. For non-2d textures, all subresources have an array layer index of 0.

Each subresource has an aspect. Color textures have just one aspect: color. Depth-or-stencil format textures may have multiple aspects: a depth aspect, a stencil aspect, or both, and may be used in special ways, such as in depthStencilAttachment and in "depth" bindings.

A "3d" texture may have multiple slices, each being the two-dimensional image at a particular z value in the texture. Slices are not separate subresources.

[Exposed=(Window, DedicatedWorker), SecureContext]
interface GPUTexture {
    GPUTextureView createView(optional GPUTextureViewDescriptor descriptor = {});

    undefined destroy();

    readonly attribute GPUIntegerCoordinateOut width;
    readonly attribute GPUIntegerCoordinateOut height;
    readonly attribute GPUIntegerCoordinateOut depthOrArrayLayers;
    readonly attribute GPUIntegerCoordinateOut mipLevelCount;
    readonly attribute GPUSize32Out sampleCount;
    readonly attribute GPUTextureDimension dimension;
    readonly attribute GPUTextureFormat format;
    readonly attribute GPUFlagsConstant usage;
};
GPUTexture includes GPUObjectBase;

GPUTexture has the following attributes:

width, of type GPUIntegerCoordinateOut, readonly

The width of this GPUTexture.

height, of type GPUIntegerCoordinateOut, readonly

The height of this GPUTexture.

depthOrArrayLayers, of type GPUIntegerCoordinateOut, readonly

The depth or layer count of this GPUTexture.

mipLevelCount, of type GPUIntegerCoordinateOut, readonly

The number of mip levels of this GPUTexture.

sampleCount, of type GPUSize32Out, readonly

The number of sample count of this GPUTexture.

dimension, of type GPUTextureDimension, readonly

The dimension of the set of texel for each of this GPUTexture's subresources.

format, of type GPUTextureFormat, readonly

The format of this GPUTexture.

usage, of type GPUFlagsConstant, readonly

The allowed usages for this GPUTexture.

GPUTexture has the following internal slots:

[[size]], of type GPUExtent3D

The size of the texture (same as the width, height, and depthOrArrayLayers attributes).

[[viewFormats]], of type sequence<GPUTextureFormat>

The set of GPUTextureFormats that can be used GPUTextureViewDescriptor.format when creating views on this GPUTexture.

[[destroyed]], of type boolean, initially false

If the texture is destroyed, it can no longer be used in any operation, and its underlying memory can be freed.

The logical miplevel-specific texture extent of a texture is the size of the texture in texels at a specific miplevel. It is calculated by this procedure:

The physical miplevel-specific texture extent of a texture is the size of the texture in texels at a specific miplevel that includes the possible extra padding to form complete texel blocks in the texture. It is calculated by this procedure:

6.1.1. GPUTextureDescriptor

dictionary GPUTextureDescriptor
         : GPUObjectDescriptorBase {
    required GPUExtent3D size;
    GPUIntegerCoordinate mipLevelCount = 1;
    GPUSize32 sampleCount = 1;
    GPUTextureDimension dimension = "2d";
    required GPUTextureFormat format;
    required GPUTextureUsageFlags usage;
    sequence<GPUTextureFormat> viewFormats = [];
};

GPUTextureDescriptor has the following members:

size, of type GPUExtent3D

The width, height, and depth or layer count of the texture.

mipLevelCount, of type GPUIntegerCoordinate, defaulting to 1

The number of mip levels the texture will contain.

sampleCount, of type GPUSize32, defaulting to 1

The sample count of the texture. A sampleCount > 1 indicates a multisampled texture.

dimension, of type GPUTextureDimension, defaulting to "2d"

Whether the texture is one-dimensional, an array of two-dimensional layers, or three-dimensional.

format, of type GPUTextureFormat

The format of the texture.

usage, of type GPUTextureUsageFlags

The allowed usages for the texture.

viewFormats, of type sequence<GPUTextureFormat>, defaulting to []

Specifies what view format values will be allowed when calling createView() on this texture (in addition to the texture’s actual format).

NOTE:

Adding a format to this list may have a significant performance impact, so it is best to avoid adding formats unnecessarily.

The actual performance impact is highly dependent on the target system; developers must test various systems to find out the impact on their particular application. For example, on some systems any texture with a format or viewFormats entry including "rgba8unorm-srgb" will perform less optimally than a "rgba8unorm" texture which does not. Similar caveats exist for other formats and pairs of formats on other systems.

Formats in this list must be texture view format compatible with the texture format.

Two GPUTextureFormats format and viewFormat are texture view format compatible if:

• format equals viewFormat, or

• format and viewFormat differ only in whether they are srgb formats (have the -srgb suffix).

enum GPUTextureDimension {
    "1d",
    "2d",
    "3d",
};

"1d"

Specifies a texture that has one dimension, width.

"2d"

Specifies a texture that has a width and height, and may have layers. Only "2d" textures may have mipmaps, be multisampled, use a compressed or depth/stencil format, and be used as a render attachment.

"3d"

Specifies a texture that has a width, height, and depth.

6.1.2. Texture Usages

typedef [EnforceRange] unsigned long GPUTextureUsageFlags;
[Exposed=(Window, DedicatedWorker), SecureContext]
namespace GPUTextureUsage {
    const GPUFlagsConstant COPY_SRC          = 0x01;
    const GPUFlagsConstant COPY_DST          = 0x02;
    const GPUFlagsConstant TEXTURE_BINDING   = 0x04;
    const GPUFlagsConstant STORAGE_BINDING   = 0x08;
    const GPUFlagsConstant RENDER_ATTACHMENT = 0x10;
};

The GPUTextureUsage flags determine how a GPUTexture may be used after its creation:

COPY_SRC

The texture can be used as the source of a copy operation. (Examples: as the source argument of a copyTextureToTexture() or copyTextureToBuffer() call.)

COPY_DST

The texture can be used as the destination of a copy or write operation. (Examples: as the destination argument of a copyTextureToTexture() or copyBufferToTexture() call, or as the target of a writeTexture() call.)

TEXTURE_BINDING

The texture can be bound for use as a sampled texture in a shader (Example: as a bind group entry for a GPUTextureBindingLayout.)

STORAGE_BINDING

The texture can be bound for use as a storage texture in a shader (Example: as a bind group entry for a GPUStorageTextureBindingLayout.)

RENDER_ATTACHMENT

The texture can be used as a color or depth/stencil attachment in a render pass. (Example: as a GPURenderPassColorAttachment.view or GPURenderPassDepthStencilAttachment.view.)

6.1.3. Texture Creation

createTexture(descriptor)

Creates a GPUTexture.

Called on: GPUDevice this.

Arguments:

Arguments for the GPUDevice.createTexture(descriptor) method.

Parameter	Type	Nullable	Optional	Description
descriptor	GPUTextureDescriptor	✘	✘	Description of the GPUTexture to create.

Returns: GPUTexture

Content timeline steps:

1. ? validate GPUExtent3D shape(descriptor.size).

2. ? Validate texture format required features of descriptor.format with this.[[device]].

3. ? Validate texture format required features of each element of descriptor.viewFormats with this.[[device]].

4. Let t be a new GPUTexture object.

5. Set t.width to descriptor.size.width.

6. Set t.height to descriptor.size.height.

7. Set t.depthOrArrayLayers to descriptor.size.depthOrArrayLayers.

8. Set t.mipLevelCount to descriptor.mipLevelCount.

9. Set t.sampleCount to descriptor.sampleCount.

10. Set t.dimension to descriptor.dimension.

11. Set t.format to descriptor.format.

12. Set t.usage to descriptor.usage.

13. Issue the initialization steps on the Device timeline of this.

14. Return t.

Device timeline initialization steps:

1. If any of the following conditions are unsatisfied generate a validation error, make t invalid, and stop.

   • validating GPUTextureDescriptor(this, descriptor) returns true.

2. Set t.[[size]] to descriptor.size.

3. Set t.[[viewFormats]] to descriptor.viewFormats.

const texture = gpuDevice.createTexture({
    size: { width: 16, height: 16 },
    format: 'rgba8unorm',
    usage: GPUTextureUsage.TEXTURE_BINDING,
});

6.1.4. Texture Destruction

An application that no longer requires a GPUTexture can choose to lose access to it before garbage collection by calling destroy().

Note: This allows the user agent to reclaim the GPU memory associated with the GPUTexture once all previously submitted operations using it are complete.

destroy()

Destroys the GPUTexture.

Called on: GPUTexture this.

Returns: undefined

Content timeline steps:

1. Set this.[[destroyed]] to true.

6.2. GPUTextureView

A GPUTextureView is a view onto some subset of the texture subresources defined by a particular GPUTexture.

[Exposed=(Window, DedicatedWorker), SecureContext]
interface GPUTextureView {
};
GPUTextureView includes GPUObjectBase;

GPUTextureView has the following internal slots:

[[texture]]

The GPUTexture into which this is a view.

[[descriptor]]

The GPUTextureViewDescriptor describing this texture view.

All optional fields of GPUTextureViewDescriptor are defined.

[[renderExtent]]

For renderable views, this is the effective GPUExtent3DDict for rendering.

Note: this extent depends on the baseMipLevel.