WebGPU

W3C Working Draft,

More details about this document
This version:
https://www.w3.org/TR/2022/WD-webgpu-20220627/
Latest published version:
https://www.w3.org/TR/webgpu/
Editor's Draft:
https://gpuweb.github.io/gpuweb/
Previous Versions:
History:
https://www.w3.org/standards/history/webgpu
Feedback:
public-gpu@w3.org with subject line “[webgpu] … message topic …” (archives)
GitHub
Inline In Spec
Editors:
(Mozilla)
(Google)
(Google)
Former Editor:
(Apple)
Participate:
File an issue (open issues)

Abstract

WebGPU exposes an API for performing operations, such as rendering and computation, on a Graphics Processing Unit.

Status of this document

This section describes the status of this document at the time of its publication. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

Feedback and comments on this specification are welcome. GitHub Issues are preferred for discussion on this specification. Alternatively, you can send comments to the GPU for the Web Working Group’s mailing-list, public-gpu@w3.org (archives). This draft highlights some of the pending issues that are still to be discussed in the working group. No decision has been taken on the outcome of these issues including whether they are valid.

This document was published by the GPU for the Web Working Group as a Working Draft using the Recommendation track. This document is intended to become a W3C Recommendation.

Publication as a Working Draft does not imply endorsement by W3C and its Members.

This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 2 November 2021 W3C Process Document.

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 § 21 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.

The initialization status of a resource used in a queue operation can only be known when the operation is enqueued (not when it is encoded into a command buffer, for example). Therefore, some implementations will require an unoptimized late-clear at enqueue time (e.g. clearing a texture, rather than changing GPULoadOp "load" to "clear").

As a result, all implementations should issue a developer console warning about this potential performance penalty, even if there is no penalty in that implementation.

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 on the API side can only guarantee that all the inputs to the shader are provided and they have the correct usage and types. The host API side can not guarantee that the data is accessed within bounds if the texture units are not involved.

define the host API distinct from the shader API

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

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.

WebGPU also specifies the "timestamp-query" feature, which provides high precision timing of GPU operations. The feature is optional, and a WebGPU implementation may limit its exposure only to those scenarios that are trusted. Alternatively, the timing query results could be processed by a compute shader and aligned to a lower precision.

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.

Update this section with iframe-control defaulting to "self" being a mitigation against this issue since only the top level origin (that is a bit more trusted since the user navigated to it, or is staying on it).

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.

2.2.1. Machine-specific 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. Dot Syntax

In this specification, the . ("dot") syntax, common in programming languages, is used. The phrasing "Foo.Bar" means "the Bar member of the value (or interface) Foo."

The ?. ("optional chaining") syntax, adopted from JavaScript, is also used. The phrasing "Foo?.Bar" means "if Foo is null or undefined, 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.

3.1.2. Internal Objects

An internal object is a conceptual, non-exposed WebGPU object. Internal objects track the state of an API object and hold any underlying implementation. If the state of a particular internal object can change in parallel from multiple agents, those changes are always atomic with respect to all agents.

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

3.1.3. WebGPU Interfaces

A WebGPU interface is an exposed interface which encapsulates an internal object. It provides the interface through which the internal object's state is changed.

Any interface which includes GPUObjectBase is a WebGPU interface.

interface mixin GPUObjectBase {
    attribute USVString label;
};

GPUObjectBase has the following attributes:

label, of type USVString

Initially the empty string.

A developer-provided label which 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 error/warning messages, browser developer tools, and platform debugging utilities. The user agent is free to choose if and how it will use this label.

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

GPUObjectBase has the following internal slots:

[[device]], of type device, readonly

An internal slot holding the device which owns the internal object.

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

The initial value of GPUObjectBase.label.

3.2. Invalid Internal Objects & Contagious Invalidity

Object creation operations in WebGPU are internally asynchronous, so they don’t fail with exceptions. Instead, returned objects may refer to internal objects which are either valid or invalid. An invalid object may never become valid at a later time. Some objects may become invalid during their lifetime, while most may only be invalid from creation.

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.

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, and command/pass/bundle encoders.

A given GPUObjectBase object is valid to use with a targetObject if and only if the following requirements are met:

3.3. Coordinate Systems

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

3.4. Programming Model

3.4.1. Timelines

This section is non-normative.

A computer system with a user agent at the front-end and GPU at the back-end has components working on different timelines in parallel:

Content timeline

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

Steps executed on the content timeline look like this.
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.

Steps executed on the device timeline look like this.
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.

Steps executed on the queue timeline look like this.

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

GPUComputePassEncoder.dispatchWorkgroups():
  1. User encodes a dispatchWorkgroups command by calling a method of the GPUComputePassEncoder which happens on the Content timeline.

  2. User issues GPUQueue.submit() that hands over the GPUCommandBuffer to the user agent, which processes it on the Device timeline by calling the OS driver to do a low-level submission.

  3. The submit gets dispatched by the GPU invocation scheduler onto the actual compute units for execution, which happens on the Queue timeline.

GPUDevice.createBuffer():
  1. User fills out a GPUBufferDescriptor and creates a GPUBuffer with it, which happens on the Content timeline.

  2. User agent creates a low-level buffer on the Device timeline.

GPUBuffer.mapAsync():
  1. User requests to map a GPUBuffer on the Content timeline and gets a promise in return.

  2. User agent checks if the buffer is currently used by the GPU and makes a reminder to itself to check back when this usage is over.

  3. After the GPU operating on Queue timeline is done using the buffer, the user agent maps it to memory and resolves the promise.

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:

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.

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.

Textures may consist of separate mipmap levels and array layers, which can be used differently at any given time. Each such texture subresource is uniquely identified by a texture, mipmap level, and (for 2d textures only) array layer, and aspect.

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

Some internal usages are compatible with others. A subresource can be in a state that combines multiple usages together. We consider a list U to be a compatible usage list if (and only if) it satisfies any of the following rules:

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.

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:

Logical miplevel-specific texture extent(descriptor, mipLevel)

Arguments:

Returns: GPUExtent3DDict

  1. Let extent be a new GPUExtent3DDict object.

  2. If descriptor.dimension is:

    "1d"

    Set extent.width to max(1, descriptor.size.widthmipLevel).

    Set extent.height to 1.

    Set extent.depthOrArrayLayers to descriptor.size.depthOrArrayLayers.

    "2d"

    Set extent.width to max(1, descriptor.size.widthmipLevel).

    Set extent.height to max(1, descriptor.size.heightmipLevel).

    Set extent.depthOrArrayLayers to descriptor.size.depthOrArrayLayers.

    "3d"

    Set extent.width to max(1, descriptor.size.widthmipLevel).

    Set extent.height to max(1, descriptor.size.heightmipLevel).

    Set extent.depthOrArrayLayers to max(1, descriptor.size.depthOrArrayLayersmipLevel).

  3. Return extent.

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:

Physical miplevel-specific texture extent(descriptor, mipLevel)

Arguments:

Returns: GPUExtent3DDict

  1. Let extent be a new GPUExtent3DDict object.

  2. Let logicalExtent be logical miplevel-specific texture extent(descriptor, mipLevel).

  3. If descriptor.dimension is:

    "1d"

    Set extent.width to logicalExtent.width rounded up to the nearest multiple of descriptor’s texel block width.

    Set extent.height to 1.

    Set extent.depthOrArrayLayers to logicalExtent.depthOrArrayLayers.

    "2d"

    Set extent.width to logicalExtent.width rounded up to the nearest multiple of descriptor’s texel block width.

    Set extent.height to logicalExtent.height rounded up to the nearest multiple of descriptor’s texel block height.

    Set extent.depthOrArrayLayers to logicalExtent.depthOrArrayLayers.

    "3d"

    Set extent.width to logicalExtent.width rounded up to the nearest multiple of descriptor’s texel block width.

    Set extent.height to logicalExtent.height rounded up to the nearest multiple of descriptor’s texel block height.

    Set extent.depthOrArrayLayers to logicalExtent.depthOrArrayLayers.

  4. Return extent.

3.4.4. Synchronization

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

This section will need to be revised to support multiple queues.

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:

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

The above rules mean the following example resource usages are included in usage scope validation:

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.

An adapter object may become invalid at any time. This happens inside "lose the device" and "mark adapters stale". An invalid adapter is unable to vend new devices.

Note: This mechanism ensures that various adapter-creation scenarios look similar to applications, so they can easily be robust to more scenarios with less testing: first initialization, reinitialization due to an unplugged adapter, reinitialization due to a test GPUDevice.destroy() call, etc. It also ensures applications use the latest system state to make decisions about which adapter to use.

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.

[[unmaskedIdentifiers]], of type ordered set<DOMString>

A list of names of GPUAdapterInfo fields the user agent has chosen to report for this adapter. Initially populated with the names of any GPUAdapterInfo fields the user agent has chosen to report without user consent.

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 is lost or destroyed, it and all objects created on it (directly, e.g. createTexture(), or indirectly, e.g. createView()) become implicitly unusable.

Define "ownership".

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.

When a new device device is created from adapter adapter with GPUDeviceDescriptor descriptor:

Any time the user agent needs to revoke access to a device, it calls lose the device(device, undefined).

To lose the device(device, reason):
  1. Make device.[[adapter]] invalid.

  2. Make device invalid.

  3. explain how to get from device to its "primary" GPUDevice.

  4. Resolve device.lost with a new GPUDeviceLostInfo with reason set to reason and message set to an implementation-defined value.

    Note: message should not disclose unnecessary user/system information and should never be parsed by applications.

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.

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.

Each GPUAdapter exposes a set of available features. Only those features may be requested in requestDevice().

Functionality that is part of a feature may only be used if the feature was requested at device creation. Dictionary members added to existing dictionaries by optional features are always optional at the WebIDL level; if the feature is not enabled, such members must not be set to non-default values.

Note: Though enabling a feature won’t add new IDL-required fields, it may not necessarily be backward-compatible with existing code. An optional feature can enable new validation which invalidates previously-valid code.

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.

A supported limits object has a value for every defined limit. Each adapter has a set of supported limits, and devices are created with specific supported limits in place. The device limits are enforced regardless of the adapter’s limits.

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

Limit name Type Limit class Default
maxTextureDimension1D GPUSize32 maximum 8192
The maximum allowed value for the size.width of a texture created with dimension "1d".
maxTextureDimension2D GPUSize32 maximum 8192
The maximum allowed value for the size.width and size.height of a texture created with dimension "2d".
maxTextureDimension3D GPUSize32 maximum 2048
The maximum allowed value for the size.width, size.height and size.depthOrArrayLayers of a texture created with dimension "3d".
maxTextureArrayLayers GPUSize32 maximum 256
The maximum allowed value for the size.depthOrArrayLayers of a texture created with dimension "1d" or "2d".
maxBindGroups GPUSize32 maximum 4
The maximum number of GPUBindGroupLayouts allowed in bindGroupLayouts when creating a GPUPipelineLayout.
maxDynamicUniformBuffersPerPipelineLayout GPUSize32 maximum 8
The maximum number of GPUBindGroupLayoutEntry entries across a GPUPipelineLayout which are uniform buffers with dynamic offsets. See Exceeds the binding slot limits.
maxDynamicStorageBuffersPerPipelineLayout GPUSize32 maximum 4
The maximum number of GPUBindGroupLayoutEntry entries across a GPUPipelineLayout which are storage buffers with dynamic offsets. See Exceeds the binding slot limits.
maxSampledTexturesPerShaderStage GPUSize32 maximum 16
For each possible GPUShaderStage stage, the maximum number of GPUBindGroupLayoutEntry entries across a GPUPipelineLayout which are sampled textures. See Exceeds the binding slot limits.
maxSamplersPerShaderStage GPUSize32 maximum 16
For each possible GPUShaderStage stage, the maximum number of GPUBindGroupLayoutEntry entries across a GPUPipelineLayout which are samplers. See Exceeds the binding slot limits.
maxStorageBuffersPerShaderStage GPUSize32 maximum 8
For each possible GPUShaderStage stage, the maximum number of GPUBindGroupLayoutEntry entries across a GPUPipelineLayout which are storage buffers. See Exceeds the binding slot limits.
maxStorageTexturesPerShaderStage GPUSize32 maximum 4
For each possible GPUShaderStage stage, the maximum number of GPUBindGroupLayoutEntry entries across a GPUPipelineLayout which are storage textures. See Exceeds the binding slot limits.
maxUniformBuffersPerShaderStage GPUSize32 maximum 12
For each possible GPUShaderStage stage, the maximum number of GPUBindGroupLayoutEntry entries across a GPUPipelineLayout which are uniform buffers. See Exceeds the binding slot limits.
maxUniformBufferBindingSize GPUSize64 maximum 65536 bytes
The maximum GPUBufferBinding.size for bindings with a GPUBindGroupLayoutEntry entry for which entry.buffer?.type is "uniform".
maxStorageBufferBindingSize GPUSize64 maximum 134217728 bytes (128 MiB)
The maximum GPUBufferBinding.size for bindings with a GPUBindGroupLayoutEntry entry for which entry.buffer?.type is "storage" or "read-only-storage".
minUniformBufferOffsetAlignment GPUSize32 alignment 256 bytes
The required alignment for GPUBufferBinding.offset and setBindGroup dynamicOffsets arguments for binding with a GPUBindGroupLayoutEntry entry for which entry.buffer?.type is "uniform".

Implementations must not support values less than 32 bytes.

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

minStorageBufferOffsetAlignment GPUSize32 alignment 256 bytes
The required alignment for GPUBufferBinding.offset and setBindGroup dynamicOffsets arguments for binding with a GPUBindGroupLayoutEntry entry for which entry.buffer?.type is "storage" or "read-only-storage".

Implementations must not support values less than 32 bytes.

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

maxVertexBuffers GPUSize32 maximum 8
The maximum number of buffers when creating a GPURenderPipeline.
maxVertexAttributes GPUSize32 maximum 16
The maximum number of attributes in total across buffers when creating a GPURenderPipeline.
maxVertexBufferArrayStride GPUSize32 maximum 2048 bytes
The maximum allowed arrayStride when creating a GPURenderPipeline.
maxInterStageShaderComponents GPUSize32 maximum 60
The maximum allowed number of components of input or output variables for inter-stage communication (like vertex outputs or fragment inputs).
maxInterStageShaderVariables GPUSize32 maximum 16
The maximum allowed number of input or output variables for inter-stage communication (like vertex outputs or fragment inputs).
maxColorAttachments GPUSize32 maximum 8
The maximum allowed number of color attachments in GPURenderPipelineDescriptor.fragment.targets, GPURenderPassDescriptor.colorAttachments, and GPURenderPassLayout.colorFormats.
maxComputeWorkgroupStorageSize GPUSize32 maximum 16384 bytes
The maximum number of bytes used for a compute stage GPUShaderModule entry-point.
maxComputeInvocationsPerWorkgroup GPUSize32 maximum 256
The maximum value of the product of the workgroup_size dimensions for a compute stage GPUShaderModule entry-point.
maxComputeWorkgroupSizeX GPUSize32 maximum 256
The maximum value of the workgroup_size X dimension for a compute stage GPUShaderModule entry-point.
maxComputeWorkgroupSizeY GPUSize32 maximum 256
The maximum value of the workgroup_size Y dimensions for a compute stage GPUShaderModule entry-point.
maxComputeWorkgroupSizeZ GPUSize32 maximum 64
The maximum value of the workgroup_size Z dimensions for a compute stage GPUShaderModule entry-point.
maxComputeWorkgroupsPerDimension GPUSize32 maximum 65535
The maximum value for the arguments of dispatchWorkgroups(workgroupCountX, workgroupCountY, workgroupCountZ).

Do we need to have a max per-pixel render target size?

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 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 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 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>;
};
Note: The type of the GPUSupportedFeatures set entries is DOMString to allow user agents to gracefully handle valid GPUFeatureNames which are added in later revisions of the spec but which the user agent has not been updated to recognize yet. If the set entries type was GPUFeatureName the following code would throw an TypeError rather than reporting false:
Check for support of an unrecognized feature:
if (adapter.features.has('unknown-feature')) {
    // Use unknown-feature
} else {
    console.warn('unknown-feature is not supported by this adapter.');
}
3.6.2.3. 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.

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

To create a new adapter info for a given adapter adapter, run the following steps:
  1. Let adapterInfo be a new GPUAdapterInfo.

  2. Let unmaskedValues be adapter.[[unmaskedIdentifiers]]

  3. If unmaskedValues contains "vendor" and the vendor is known:

    1. Set adapterInfo.vendor to the name of adapter’s vendor as a normalized identifier string.

    Otherwise:

    1. Set adapterInfo.vendor to the empty string or a reasonable approximation of the vendor as a normalized identifier string.

  4. If unmaskedValues contains "architecture" and the architecture is known:

    1. Set adapterInfo.architecture to a normalized identifier string representing the family or class of adapters to which adapter belongs.

    Otherwise:

    1. Set adapterInfo.architecture to the empty string or a reasonable approximation of the architecture as a normalized identifier string.

  5. If unmaskedValues contains "device" and the device is known:

    1. Set adapterInfo.device to a normalized identifier string representing a vendor-specific identifier for adapter.

    Otherwise:

    1. Set adapterInfo.device to to the empty string or a reasonable approximation of a vendor-specific identifier as a normalized identifier string.

  6. If unmaskedValues contains "description" and a description is known:

    1. Set adapterInfo.description to a description of the adapter as reported by the driver.

    Otherwise:

    1. Set adapterInfo.description to the empty string or a reasonable approximation of a description.

  7. Return adapterInfo.

A normalized identifier string is one that follows the following pattern:
a-z 0-9 -
Examples of valid normalized identifier strings include:
  • gpu

  • 3d

  • 0x3b2f

  • next-gen

  • series-x20-ultra

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

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

Consider a path for uploading srgb-encoded images into linearly-encoded textures. [Issue #gpuweb/gpuweb#1715]

A premultiplied RGBA value is super-luminant if 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) sRGB color [2, 0, 0] with alpha of 50%. 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.)

Super-luminant is a confusing term because it doesn’t really have anything to do with luminance.

3.8.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, as needed, 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 super-luminant.

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.8.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:

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

4. Initialization

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;

4.2. GPU

GPU is the entry point to WebGPU.

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

GPU has the following methods:

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

  1. Let promise be a new promise.

  2. Issue the following steps on the Device timeline of this:

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

      1. Create a valid adapter adapter, chosen according to the rules in § 4.2.1 Adapter Selection and the criteria in options.

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

      3. Resolve promise with a new GPUAdapter encapsulating adapter.

    2. Otherwise, promise resolves with null.

  3. Return promise.

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

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

GPU has the following internal slots:

[[previously_returned_adapters]], of type ordered set<adapter>

The set of adapters that have been returned via requestAdapter(). It is used, then cleared, in mark adapters stale.

Upon any change in the system’s state that could affect the result of any requestAdapter() call, the user agent should mark adapters stale. For example:

Additionally, mark adapters stale may by scheduled at any time. User agents may choose to do this often even when there has been no system state change (e.g. several seconds after the last call to requestDevice(). This has no effect on well-formed applications, obfuscates real system state changes, and makes developers more aware that calling requestAdapter() again is always necessary before calling requestDevice().

To mark adapters stale:
  1. For each adapter in navigator.gpu.[[previously_returned_adapters]]:

    1. Make adapter.[[adapter]] invalid.

  2. Empty navigator.gpu.[[previously_returned_adapters]].

Update here if an adaptersadded/adapterschanged event is introduced.

Requesting a GPUAdapter with no hints:
const gpuAdapter = await navigator.gpu.requestAdapter();

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

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.

Requesting a "high-performance" GPUAdapter:
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(optional sequence<DOMString> unmaskHints = []);
};

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.

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>

  1. Let promise be a new promise.

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

  3. Issue the following steps to the Device timeline:

    1. If any of the following requirements are unmet, reject promise with a TypeError and stop.

      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, reject promise with an OperationError and stop.

    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, undefined).

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

      3. Resolve promise with a new GPUDevice encapsulating device, and stop.

    4. Resolve promise with a new GPUDevice object encapsulating a new device with the capabilities described by descriptor.

  4. Return promise.

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 when requesting unmasked values, such as asking for user consent before returning. If no unmaskHints are specified, however, no dialogs should be displayed to the user.

Called on: GPUAdapter this.

Arguments:

Arguments for the GPUAdapter.requestAdapterInfo() method.
Parameter Type Nullable Optional Description
unmaskHints sequence<DOMString> A list of GPUAdapterInfo attribute names for which unmasked values are desired if available.

Returns: Promise<GPUAdapterInfo>

  1. Let promise be a new promise.

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

  3. Let hasActivation be true if the relevant global object for this has transient activation, and false otherwise.

  4. Run the following steps in parallel:

    1. If unmaskHints.length > 0:

      1. If hasActivation is false reject promise with a NotAllowedError and abort these steps.

      2. Let unmaskedKeys be a list of the fields specified in unmaskHints which the user agent decides to unmask, if any.

        Note: The user agent is free to use any method it deems appropriate to decide which fields to unmask.

      3. Append unmaskedKeys to adapter.[[unmaskedIdentifiers]].

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

  5. Return promise.

Requesting a GPUDevice with default features and limits:
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.

Requesting a GPUDevice with the "texture-compression-astc" feature if supported:
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
});
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",
    "bgra8unorm-storage"
};

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.
  1. Lose the device(this.[[device]], "destroyed").

  2. unmap() all GPUBuffers from this device.

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.

A GPUDevice's allowed buffer usages are:
A GPUDevice's allowed texture usages are:

4.5. Example

A more robust example of requesting a GPUAdapter and GPUDevice with error handling:
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

define buffer (internal object)

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 GPUDevice.createBuffer(descriptor) that returns a new buffer in the mapped or unmapped state.

[Exposed=(Window, DedicatedWorker), SecureContext]
interface GPUBuffer {
    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();

    readonly attribute GPUSize64 size;
    readonly attribute GPUBufferUsageFlags usage;
};
GPUBuffer includes GPUObjectBase;

GPUBuffer has the following attributes:

size, of type GPUSize64, readonly

The length of the GPUBuffer allocation in bytes.

usage, of type GPUBufferUsageFlags, readonly

The allowed usages for this GPUBuffer.

GPUBuffer has the following internal slots:

[[state]], of type buffer state

The current state of the GPUBuffer.

[[mapping]], of type ArrayBuffer or Promise or null

The mapping for this GPUBuffer. The ArrayBuffer isn’t directly accessible and is instead accessed through views into it, called the mapped ranges, that are stored in [[mapped_ranges]]

Specify [[mapping]] in term of DataBlock similarly to AllocateArrayBuffer? [Issue #gpuweb/gpuweb#605]

[[mapping_range]], of type list<unsigned long long> or null

The range of this GPUBuffer that is mapped.

[[mapped_ranges]], of type list<ArrayBuffer> or null

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

[[map_mode]], of type GPUMapModeFlags

The GPUMapModeFlags of the last call to mapAsync() (if any).

Each GPUBuffer has a current buffer state on the Content timeline which is one of the following:

Note: size and usage are immutable once the GPUBuffer has been created.

Note: GPUBuffer has a state machine with the following states. ([[mapping]], [[mapping_range]], and [[mapped_ranges]] are null when not specified.)

GPUBuffer is a reference to an internal buffer object.

5.2. Buffer Creation

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

validating GPUBufferDescriptor(device, descriptor)
  1. If device is lost return false.

  2. If any of the bits of descriptor’s usage aren’t present in device’s allowed buffer usages, return false.

  3. If both the MAP_READ and MAP_WRITE bits of descriptor’s usage attribute are set, return false.

  4. Return true.

5.2.2. Buffer Usage

typedef [EnforceRange] unsigned long GPUBufferUsageFlags;
[Exposed=(Window, DedicatedWorker)]
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.)

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

  1. Let b be a new GPUBuffer object.

  2. Set b.size to descriptor.size.

  3. Set b.usage to descriptor.usage.

  4. Issue the following steps on the Device timeline of this:

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

    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 b.[[mapping]] to a new ArrayBuffer of size b.size.

      2. Set b.[[mapping_range]] to [0, descriptor.size].

      3. Set b.[[mapped_ranges]] to [].

      4. Set b.[[state]] to mapped at creation.

      Else:

      1. Set b.[[mapping]] to null.

      2. Set b.[[mapping_range]] to null.

      3. Set b.[[mapped_ranges]] to null.

      4. Set b.[[state]] to unmapped.

    2. Set each byte of b’s allocation to zero.

  5. Return b.

Creating a 128 byte uniform buffer that can be written into:
const buffer = gpuDevice.createBuffer({
    size: 128,
    usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST
});

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

  1. If this is mapped, call this.unmap().

  2. Set this.[[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.4. 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. Once the GPUBuffer is mapped, the application can synchronously ask for access to ranges of its content with getMappedRange(). 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.

Add client-side validation that a mapped buffer can only be unmapped and destroyed on the worker on which it was mapped. Likewise getMappedRange() can only be called on that worker. [Issue #gpuweb/gpuweb#605]

A mapped range ArrayBuffer is a special type of ArrayBuffer, returned by getMappedRange(), which cannot be transferred normally. When such an ArrayBuffer ab is transferred, instead:
  1. Get a copy of the buffer source ab and create a new ArrayBuffer abCopy with those contents.

  2. Detach ab.

  3. Transfer abCopy instead.

Note: User agents should consider issue a developer warning when this happens, as transferring provides no additional functionality or performance over posting the ArrayBuffer normally.

typedef [EnforceRange] unsigned long GPUMapModeFlags;
[Exposed=(Window, DedicatedWorker)]
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().

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>

Handle error buffers once we have a description of the error monad. [Issue #gpuweb/gpuweb#605]

  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:

    Do we validate that mode contains only valid flags?

    Then:

    1. Record a validation error on the current scope.

    2. Return a promise rejected with an OperationError on the Device timeline.

  3. Let p be a new Promise.

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

  5. Set this.[[state]] to mapping pending.

  6. Set this.[[map_mode]] to mode.

  7. Enqueue an operation on the default queue’s Queue timeline that will execute the following:

    1. If this.[[state]] is mapping pending:

      1. Let m be a new ArrayBuffer of size rangeSize.

        Note: This is just a memory allocation; this ArrayBuffer object is not exposed directly.

      2. Set the content of m to the content of this’s allocation starting at offset offset and for rangeSize bytes.

      3. Set this.[[mapping]] to m.

      4. Set this.[[state]] to mapped.

      5. Set this.[[mapping_range]] to [offset, offset + rangeSize].

      6. Set this.[[mapped_ranges]] to [].

    2. Resolve p.

  8. Return p.

getMappedRange(offset, size)

Returns a mapped range 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

  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.

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

    Consider aligning mapAsync offset to 8 to match this.

  3. Let m be a new mapped range ArrayBuffer of size rangeSize pointing at the content of this.[[mapping]] at offset offset - this.[[mapping_range]][0].

  4. Append m to this.[[mapped_ranges]].

  5. Return m.

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

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

    Note: It is valid to unmap an invalid GPUBuffer that is mapped at creation because the Content timeline might not know it is an error GPUBuffer. This allows the temporary [[mapping]] memory to be freed.

  2. If this.[[state]] is mapping pending:

    1. Reject [[mapping]] with an AbortError.

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

  3. If this.[[state]] is mapped or mapped at creation:

    1. If one of the two following conditions holds:

      Then:

      1. Enqueue an operation on the default queue’s Queue timeline that updates the this.[[mapping_range]] of this’s allocation to the content of this.[[mapping]].

    2. Detach each ArrayBuffer in this.[[mapped_ranges]] from its content.

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

    4. Set this.[[mapping_range]] to null.

    5. Set this.[[mapped_ranges]] to null.

  4. Set this.[[state]] to unmapped.

Note: When a MAP_READ buffer (not currently mapped at creation) is unmapped, any local modifications done by the application to the mapped ranges ArrayBuffer are discarded and will not affect the content of follow-up mappings.

6. Textures and Texture Views

define texture (internal object)

define mipmap level, array layer, aspect, slice (concepts)

6.1. GPUTexture

GPUTextures are created via GPUDevice.createTexture(descriptor) that returns a new texture.

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

    undefined destroy();

    readonly attribute GPUIntegerCoordinate width;
    readonly attribute GPUIntegerCoordinate height;
    readonly attribute GPUIntegerCoordinate depthOrArrayLayers;
    readonly attribute GPUIntegerCoordinate mipLevelCount;
    readonly attribute GPUSize32 sampleCount;
    readonly attribute GPUTextureDimension dimension;
    readonly attribute GPUTextureFormat format;
    readonly attribute GPUTextureUsageFlags usage;
};
GPUTexture includes GPUObjectBase;

GPUTexture has the following attributes:

width, of type GPUIntegerCoordinate, readonly

The width of this GPUTexture.

height, of type GPUIntegerCoordinate, readonly

The height of this GPUTexture.

depthOrArrayLayers, of type GPUIntegerCoordinate, readonly

The depth or layer count of this GPUTexture.

mipLevelCount, of type GPUIntegerCoordinate, readonly

The number of mip levels of this GPUTexture.

sampleCount, of type GPUSize32, 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 GPUTextureUsageFlags, 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.

compute render extent(baseSize, mipLevel)

Arguments:

Returns: GPUExtent3DDict

  1. Let extent be a new GPUExtent3DDict object.

  2. Set extent.width to max(1, baseSize.widthmipLevel).

  3. Set extent.height to max(1, baseSize.heightmipLevel).

  4. Set extent.depthOrArrayLayers to 1.

  5. Return extent.

share this definition with the part of the specification that describes sampling.

6.1.1. Texture Creation

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

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

Define larger compatibility classes. [Issue #gpuweb/gpuweb#168]

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.

typedef [EnforceRange] unsigned long GPUTextureUsageFlags;
[Exposed=(Window, DedicatedWorker)]
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.)

maximum mipLevel count(dimension, size) Arguments:
  1. Calculate the max dimension value m:

  2. Return floor(log2(m)) + 1.

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

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

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

  3. Let t be a new GPUTexture object.

  4. Set t.width to descriptor.size.width.

  5. Set t.height to descriptor.size.height.

  6. Set t.depthOrArrayLayers to descriptor.size.depthOrArrayLayers.

  7. Set t.mipLevelCount to descriptor.mipLevelCount.

  8. Set t.sampleCount to descriptor.sampleCount.

  9. Set t.dimension to descriptor.dimension.

  10. Set t.format to descriptor.format.

  11. Set t.usage to descriptor.usage.

  12. Issue the following steps on the Device timeline of this:

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

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

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

  13. Return t.

validating GPUTextureDescriptor(GPUDevice this, GPUTextureDescriptor descriptor):

Return true if all of the following requirements are met, and false otherwise:

Creating a 16x16, RGBA, 2D texture with one array layer and one mip level:
const texture = gpuDevice.createTexture({
    size: { width: 16, height: 16 },
    format: 'rgba8unorm',
    usage: GPUTextureUsage.TEXTURE_BINDING,
});

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

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

6.2. GPUTextureView

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

6.2.1. Texture View Creation

dictionary GPUTextureViewDescriptor : GPUObjectDescriptorBase {
    GPUTextureFormat format;
    GPUTextureViewDimension dimension;
    GPUTextureAspect aspect = "all";
    GPUIntegerCoordinate baseMipLevel = 0;
    GPUIntegerCoordinate mipLevelCount;
    GPUIntegerCoordinate baseArrayLayer = 0;
    GPUIntegerCoordinate arrayLayerCount;
};

GPUTextureDescriptor has the following members:

format, of type GPUTextureFormat

The format of the texture view. Must be either the format of the texture or one of the viewFormats specified during its creation.

dimension, of type GPUTextureViewDimension

The dimension to view the texture as.

aspect, of type GPUTextureAspect, defaulting to "all"

Which aspect(s) of the texture are accessible to the texture view.

baseMipLevel, of type GPUIntegerCoordinate, defaulting to 0

The first (most detailed) mipmap level accessible to the texture view.

mipLevelCount, of type GPUIntegerCoordinate

How many mipmap levels, starting with baseMipLevel, are accessible to the texture view.

baseArrayLayer, of type GPUIntegerCoordinate, defaulting to 0

The index of the first array layer accessible to the texture view.

arrayLayerCount, of type GPUIntegerCoordinate

How many array layers, starting with baseArrayLayer, are accessible to the texture view.

enum GPUTextureViewDimension {
    "1d",
    "2d",
    "2d-array",
    "cube",
    "cube-array",
    "3d"
};
"1d"

The texture is viewed as a 1-dimensional image.

Corresponding WGSL types:

  • texture_1d

  • texture_storage_1d

"2d"

The texture is viewed as a single 2-dimensional image.

Corresponding WGSL types:

  • texture_2d

  • texture_storage_2d

  • texture_multisampled_2d

  • texture_depth_2d

  • texture_depth_multisampled_2d

"2d-array"

The texture view is viewed as an array of 2-dimensional images.

Corresponding WGSL types:

  • texture_2d_array

  • texture_storage_2d_array

  • texture_depth_2d_array

"cube"

The texture is viewed as a cubemap. The view has 6 array layers, corresponding to the [+X, -X, +Y, -Y, +Z, -Z] faces of the cube. Sampling is done seamlessly across the faces of the cubemap.

Corresponding WGSL types:

  • texture_cube

  • texture_depth_cube

"cube-array"

The texture is viewed as a packed array of n cubemaps, each with 6 array layers corresponding to the [+X, -X, +Y, -Y, +Z, -Z] faces of the cube. Sampling is done seamlessly across the faces of the cubemaps.

Corresponding WGSL types:

  • texture_cube_array

  • texture_depth_cube_array

"3d"

The texture is viewed as a 3-dimensional image.

Corresponding WGSL types:

  • texture_3d

  • texture_storage_3d

enum GPUTextureAspect {
    "all",
    "stencil-only",
    "depth-only"
};
"all"

All available aspects of the texture format will be accessible to the texture view. For color formats the color aspect will be accessible. For combined depth-stencil formats both the depth and stencil aspects will be accessible. Depth-or-stencil formats with a single aspect will only make that aspect accessible.

"stencil-only"

Only the stencil aspect of a depth-or-stencil format format will be accessible to the texture view.

"depth-only"

Only the depth aspect of a depth-or-stencil format format will be accessible to the texture view.

createView(descriptor)

Creates a GPUTextureView.

By default createView() will create a view with a dimension that can represent the entire texture. For example, calling createView() without specifying a dimension on a "2d" texture with more than one layer will create a "2d-array" GPUTextureView, even if an arrayLayerCount of 1 is specified.

For textures created from sources where the layer count is unknown at the time of development it is recommended that calls to createView() are provided with an explicit dimension to ensure shader compatibility.

Called on: GPUTexture this.

Arguments:

Arguments for the GPUTexture.createView(descriptor) method.
Parameter Type Nullable Optional Description
descriptor GPUTextureViewDescriptor Description of the GPUTextureView to create.

Returns: view, of type GPUTextureView.

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

  2. Let view be a new GPUTextureView object.

  3. Issue the following steps on the Device timeline of this:

    1. Set descriptor to the result of resolving GPUTextureViewDescriptor defaults for this with descriptor.

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

    3. Let view be a new GPUTextureView object.

    4. Set view.[[texture]] to this.

    5. Set view.[[descriptor]] to descriptor.

    6. If this.usage contains RENDER_ATTACHMENT:

      1. Let renderExtent be compute render extent(this.[[size]], descriptor.baseMipLevel).

      2. Set view.[[renderExtent]] to renderExtent.

  4. Return view.

When resolving GPUTextureViewDescriptor defaults for GPUTextureView texture with a GPUTextureViewDescriptor descriptor run the following steps:
  1. Let resolved be a copy of descriptor.

  2. If resolved.format is undefined,

    1. Let format be the result of resolving GPUTextureAspect( format, descriptor.aspect).

    2. If format is null:

      Otherwise:

      • Set resolved.format to format.

  3. If resolved.mipLevelCount is undefined, set resolved.mipLevelCount to texture.mipLevelCountresolved.baseMipLevel.

  4. If resolved.dimension is undefined and texture.dimension is:

    "1d"

    Set resolved.dimension to "1d".

    "2d"

    If the array layer count of texture is 1:

    Otherwise:
    "3d"

    Set resolved.dimension to "3d".

  5. If resolved.arrayLayerCount is undefined and resolved.dimension is:

    "1d", "2d", or "3d"

    Set resolved.arrayLayerCount to 1.

    "cube"

    Set resolved.arrayLayerCount to 6.

    "2d-array" or "cube-array"

    Set resolved.arrayLayerCount to the array layer count of textureresolved.baseArrayLayer.

  6. Return resolved.

To determine the array layer count of GPUTexture texture, run the following steps:
  1. If texture.dimension is:

    "1d" or "3d"

    Return 1.

    "2d"

    Return texture.depthOrArrayLayers.

Two GPUTextureView objects a and b are considered texture-view-aliasing if and only if all of the following are true:

Describe this in terms of a "set of subresources of" algorithm.

6.3. Texture Formats

The name of the format specifies the order of components, bits per component, and data type for the component.

If the format has the -srgb suffix, then sRGB conversions from gamma to linear and vice versa are applied during the reading and writing of color values in the shader. Compressed texture formats are provided by features. Their naming should follow the convention here, with the texture name as a prefix. e.g. etc2-rgba8unorm.

The texel block is a single addressable element of the textures in pixel-based GPUTextureFormats, and a single compressed block of the textures in block-based compressed GPUTextureFormats.

The texel block width and texel block height specifies the dimension of one texel block.

The texel block size of a GPUTextureFormat is the number of bytes to store one texel block. The texel block size of each GPUTextureFormat is constant except for "stencil8", "depth24plus", and "depth24plus-stencil8".

enum GPUTextureFormat {
    // 8-bit formats
    "r8unorm",
    "r8snorm",
    "r8uint",
    "r8sint",

    // 16-bit formats
    "r16uint",
    "r16sint",
    "r16float",
    "rg8unorm",
    "rg8snorm",
    "rg8uint",
    "rg8sint",

    // 32-bit formats
    "r32uint",
    "r32sint",
    "r32float",
    "rg16uint",
    "rg16sint",
    "rg16float",
    "rgba8unorm",
    "rgba8unorm-srgb",
    "rgba8snorm",
    "rgba8uint",
    "rgba8sint",
    "bgra8unorm",
    "bgra8unorm-srgb",
    // Packed 32-bit formats
    "rgb9e5ufloat",
    "rgb10a2unorm",
    "rg11b10ufloat",

    // 64-bit formats
    "rg32uint",
    "rg32sint",
    "rg32float",
    "rgba16uint",
    "rgba16sint",
    "rgba16float",

    // 128-bit formats
    "rgba32uint",
    "rgba32sint",
    "rgba32float",

    // Depth/stencil formats
    "stencil8",
    "depth16unorm",
    "depth24plus",
    "depth24plus-stencil8",
    "depth32float",

    // "depth32float-stencil8" feature
    "depth32float-stencil8",

    // BC compressed formats usable if "texture-compression-bc" is both
    // supported by the device/user agent and enabled in requestDevice.
    "bc1-rgba-unorm",
    "bc1-rgba-unorm-srgb",
    "bc2-rgba-unorm",
    "bc2-rgba-unorm-srgb",
    "bc3-rgba-unorm",
    "bc3-rgba-unorm-srgb",
    "bc4-r-unorm",
    "bc4-r-snorm",
    "bc5-rg-unorm",
    "bc5-rg-snorm",
    "bc6h-rgb-ufloat",
    "bc6h-rgb-float",
    "bc7-rgba-unorm",
    "bc7-rgba-unorm-srgb",

    // ETC2 compressed formats usable if "texture-compression-etc2" is both
    // supported by the device/user agent and enabled in requestDevice.
    "etc2-rgb8unorm",
    "etc2-rgb8unorm-srgb",
    "etc2-rgb8a1unorm",
    "etc2-rgb8a1unorm-srgb",
    "etc2-rgba8unorm",
    "etc2-rgba8unorm-srgb",
    "eac-r11unorm",
    "eac-r11snorm",
    "eac-rg11unorm",
    "eac-rg11snorm",

    // ASTC compressed formats usable if "texture-compression-astc" is both
    // supported by the device/user agent and enabled in requestDevice.
    "astc-4x4-unorm",
    "astc-4x4-unorm-srgb",
    "astc-5x4-unorm",
    "astc-5x4-unorm-srgb",
    "astc-5x5-unorm",
    "astc-5x5-unorm-srgb",
    "astc-6x5-unorm",
    "astc-6x5-unorm-srgb",
    "astc-6x6-unorm",
    "astc-6x6-unorm-srgb",
    "astc-8x5-unorm",
    "astc-8x5-unorm-srgb",
    "astc-8x6-unorm",
    "astc-8x6-unorm-srgb",
    "astc-8x8-unorm",
    "astc-8x8-unorm-srgb",
    "astc-10x5-unorm",
    "astc-10x5-unorm-srgb",
    "astc-10x6-unorm",
    "astc-10x6-unorm-srgb",
    "astc-10x8-unorm",
    "astc-10x8-unorm-srgb",
    "astc-10x10-unorm",
    "astc-10x10-unorm-srgb",
    "astc-12x10-unorm",
    "astc-12x10-unorm-srgb",
    "astc-12x12-unorm",
    "astc-12x12-unorm-srgb"
};

The depth component of the "depth24plus" and "depth24plus-stencil8" formats may be implemented as either a 24-bit unsigned normalized value (like "depth24unorm") or a 32-bit IEEE 754 floating point value (like "depth32float").

add something on GPUAdapter(?) that gives an estimate of the bytes per texel of "stencil8", "depth24plus-stencil8", and "depth32float-stencil8". [Issue #gpuweb/gpuweb#1887]

The stencil8 format may be implemented as either a real "stencil8", or "depth24stencil8", where the depth aspect is hidden and inaccessible.

Note: While the precision of depth32float channels is strictly higher than the precision of depth24unorm channels for all values in the representable range (0.0 to 1.0), note that the set of representable values is not an exact superset: for depth24unorm, 1 ULP has a constant value of 1 / (224 − 1); for depth32float, 1 ULP has a variable value no greater than 1 / (224).

A renderable format is either a color renderable format, or a depth-or-stencil format. If a format is listed in § 25.1.1 Plain color formats with RENDER_ATTACHMENT capability, it is a color renderable format. Any other format is not a color renderable format. All depth-or-stencil formats are renderable.

resolving GPUTextureAspect(format, aspect)

Arguments:

Returns: GPUTextureFormat or null

  1. If aspect is:

    "all"

    Return format.

    "depth-only"
    "stencil-only"

    If format is a depth-stencil-format: Return the aspect-specific format of format according to § 25.1.2 Depth-stencil formats or null if the aspect is not present in format.

  2. Return null.

Use of some texture formats require a feature to be enabled on the GPUDevice. Because new formats can be added to the specification, those enum values may not be known by the implementation. In order to normalize behavior across implementations, attempting to use a format that requires a feature will throw an exception if the associated feature is not enabled on the device. This makes the behavior the same as when the format is unknown to the implementation.

See § 25.1 Texture Format Capabilities for information about which GPUTextureFormats require features.

Validate texture format required features of a GPUTextureFormat format with logical device device by running the following steps:
  1. If format requires a feature and device.[[features]] does not contain the feature:

    1. Throw a TypeError.

6.4. GPUExternalTexture

A GPUExternalTexture is a sampleable texture wrapping an external video object. The contents of a GPUExternalTexture object are a snapshot and may not change, either from inside WebGPU (it is only sampleable) or from outside WebGPU (e.g. due to video frame advancement).

Update this description with canvas.

They are bound into bind group layouts using the externalTexture bind group layout entry member. External textures use several binding slots: see Exceeds the binding slot limits.

External textures can be implemented without creating a copy of the imported source, but this depends implementation-defined factors. Ownership of the underlying representation may either be exclusive or shared with other owners (such as a video decoder), but this is not visible to the application.

The underlying representation of an external texture is unobservable (except for sampling behavior) but typically may include

The configuration used may not be stable across time, systems, user agents, media sources, or frames within a single video source. In order to account for many possible representations, the binding conservatively uses the following, for each external texture:

[Exposed=(Window, DedicatedWorker), SecureContext]
interface GPUExternalTexture {
    readonly attribute boolean expired;
};
GPUExternalTexture includes GPUObjectBase;

GPUExternalTexture has the following internal slots:

[[destroyed]], of type boolean

Indicates whether the object has been destroyed (can no longer be used). Initially set to false.

[[descriptor]], of type GPUExternalTextureDescriptor

The descriptor with which the texture was created.

GPUExternalTexture has the following attributes:

expired, of type boolean, readonly

Returns the value of [[destroyed]], which indicates whether the texture has expired or not.

The GPUExternalTexture interface object (globalThis.GPUExternalTexture) has the following internal slots:

[[active_imports]], of type list<GPUExternalTexture>

A list of all imported textures which have not yet been closed. The items in list are checked during each animation frame to determine whether to close them.

6.4.1. Importing External Textures

An external texture is created from an external video object using importExternalTexture().

External textures created from HTMLVideoElements are destroyed automatically after the imported frame is no longer current, instead of manually or upon garbage collection like other resources. When an external texture expires, its expired attribute changes to true. Applications can use this to determine whether to re-import or not, if their execution is not already scheduled to match the video’s frame rate.

dictionary GPUExternalTextureDescriptor : GPUObjectDescriptorBase {
    required HTMLVideoElement source;
    PredefinedColorSpace colorSpace = "srgb";
};
importExternalTexture(descriptor)

Creates a GPUExternalTexture wrapping the provided image source.

Called on: GPUDevice this.

Arguments:

Arguments for the GPUDevice.importExternalTexture(descriptor) method.
Parameter Type Nullable Optional Description
descriptor GPUExternalTextureDescriptor Provides the external image source object (and any creation options).

Returns: GPUExternalTexture

  1. Let source be descriptor.source.

  2. Let usability be the result of checking the usability of source (which may throw an exception).

  3. If usability is bad, throw an InvalidStateError and stop.

  4. If source is not origin-clean, throw a SecurityError and stop.

  5. Let data be the result of converting the current image contents of source into the color space descriptor.colorSpace with unpremultiplied alpha.

    This may result in values outside of the range [0, 1]. If clamping is desired, it may be performed after sampling.

    Note: This is described like a copy, but may be implemented as a reference to read-only underlying data plus appropriate metadata to perform conversion later.

  6. Let result be a new GPUExternalTexture object wrapping data.

  7. Add result to GPUExternalTexture.[[active_imports]].

  8. Return result.

Immediately before the "Update the rendering" step of the HTML processing model, run the following steps to expire stale external textures:
  1. For each texture in GPUExternalTexture.[[active_imports]]:

    1. Let video be texture.[[descriptor]].source.

    2. Assert video is an HTMLVideoElement.

    3. If the latest presented frame of video is not the same frame from which texture was imported:

      1. Remove texture from GPUExternalTexture.[[active_imports]].

      2. Set texture.[[destroyed]] to true, releasing ownership of the underlying resource.

Note: An external video texture should be imported in the same task that samples the texture (which should generally be scheduled using requestVideoFrameCallback or requestAnimationFrame() depending on the application). Otherwise, a texture could get destroyed by these steps before it is used.

Rendering using an video element external texture at the page animation frame rate:
const videoElement = document.createElement('video');
// ... set up videoElement, wait for it to be ready...

let externalTexture;

function frame() {
    requestAnimationFrame(frame);

    // Re-import only if necessary
    if (!externalTexture || externalTexture.expired) {
        externalTexture = gpuDevice.importExternalTexture({
            source: videoElement
        });
    }

    // ... render using externalTexture...
}
requestAnimationFrame(frame);
Rendering using an video element external texture at the video’s frame rate, if requestVideoFrameCallback is available:
const videoElement = document.createElement('video');
// ... set up videoElement...

function frame() {
    videoElement.requestVideoFrameCallback(frame);

    // Always re-import, because we know the video frame has advanced
    const externalTexture = gpuDevice.importExternalTexture({
        source: videoElement
    });

    // ... render using externalTexture...
}
videoElement.requestVideoFrameCallback(frame);

6.4.2. Sampling External Textures

External textures are represented in WGSL with texture_external and may be read using textureLoad and textureSampleLevel.

The sampler provided to textureSampleLevel is used to sample the underlying textures. The result is in the color space set by colorSpace. It is implementation-dependent whether, for any given external texture, the sampler (and filtering) is applied before or after conversion from underlying values into the specified color space.

Note: If the internal representation is an RGBA plane, sampling behaves as on a regular 2D texture. If there are several underlying planes (e.g. Y+UV), the sampler is used to sample each underlying texture separately, prior to conversion from YUV to the specified color space.

7. Samplers

7.1. GPUSampler

A GPUSampler encodes transformations and filtering information that can be used in a shader to interpret texture resource data.

GPUSamplers are created via GPUDevice.createSampler(optional descriptor) that returns a new sampler object.

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

GPUSampler has the following internal slots:

[[descriptor]], of type GPUSamplerDescriptor, readonly

The GPUSamplerDescriptor with which the GPUSampler was created.

[[isComparison]], of type boolean

Whether the GPUSampler is used as a comparison sampler.

[[isFiltering]], of type boolean

Whether the GPUSampler weights multiple samples of a texture.

7.2. Sampler Creation

7.2.1. GPUSamplerDescriptor

A GPUSamplerDescriptor specifies the options to use to create a GPUSampler.

dictionary GPUSamplerDescriptor : GPUObjectDescriptorBase {
    GPUAddressMode addressModeU = "clamp-to-edge";
    GPUAddressMode addressModeV = "clamp-to-edge";
    GPUAddressMode addressModeW = "clamp-to-edge";
    GPUFilterMode magFilter = "nearest";
    GPUFilterMode minFilter = "nearest";
    GPUMipmapFilterMode mipmapFilter = "nearest";
    float lodMinClamp = 0;
    float lodMaxClamp = 32;
    GPUCompareFunction compare;
    [Clamp] unsigned short maxAnisotropy = 1;
};
addressModeU, of type GPUAddressMode, defaulting to "clamp-to-edge"
addressModeV, of type GPUAddressMode, defaulting to "clamp-to-edge"
addressModeW, of type GPUAddressMode, defaulting to "clamp-to-edge"

Specifies the address modes for the texture width, height, and depth coordinates, respectively.

magFilter, of type GPUFilterMode, defaulting to "nearest"

Specifies the sampling behavior when the sample footprint is smaller than or equal to one texel.

minFilter, of type GPUFilterMode, defaulting to "nearest"

Specifies the sampling behavior when the sample footprint is larger than one texel.

mipmapFilter, of type GPUMipmapFilterMode, defaulting to "nearest"

Specifies behavior for sampling between mipmap levels.

lodMinClamp, of type float, defaulting to 0
lodMaxClamp, of type float, defaulting to 32

Specifies the minimum and maximum levels of detail, respectively, used internally when sampling a texture.

compare, of type GPUCompareFunction

When provided the sampler will be a comparison sampler with the specified GPUCompareFunction.

Note: Comparison samplers may use filtering, but the sampling results will be implementation-dependent and may differ from the normal filtering rules.

maxAnisotropy, of type unsigned short, defaulting to 1

Specifies the maximum anisotropy value clamp used by the sampler.

Note: Most implementations support maxAnisotropy values in range between 1 and 16, inclusive. The used value of maxAnisotropy will be clamped to the maximum value that the platform supports.

explain how LOD is calculated and if there are differences here between platforms.

explain what anisotropic sampling is

GPUAddressMode describes the behavior of the sampler if the sample footprint extends beyond the bounds of the sampled texture.

Describe a "sample footprint" in greater detail.

enum GPUAddressMode {
    "clamp-to-edge",
    "repeat",
    "mirror-repeat"
};
"clamp-to-edge"

Texture coordinates are clamped between 0.0 and 1.0, inclusive.

"repeat"

Texture coordinates wrap to the other side of the texture.

"mirror-repeat"

Texture coordinates wrap to the other side of the texture, but the texture is flipped when the integer part of the coordinate is odd.

GPUFilterMode and GPUMipmapFilterMode describe the behavior of the sampler if the sample footprint does not exactly match one texel.

enum GPUFilterMode {
    "nearest",
    "linear"
};

enum GPUMipmapFilterMode {
    "nearest",
    "linear"
};
"nearest"

Return the value of the texel nearest to the texture coordinates.

"linear"

Select two texels in each dimension and return a linear interpolation between their values.

GPUCompareFunction specifies the behavior of a comparison sampler. If a comparison sampler is used in a shader, an input value is compared to the sampled texture value, and the result of this comparison test (0.0f for pass, or 1.0f for fail) is used in the filtering operation.

describe how filtering interacts with comparison sampling.

enum GPUCompareFunction {
    "never",
    "less",
    "equal",
    "less-equal",
    "greater",
    "not-equal",
    "greater-equal",
    "always"
};
"never"

Comparison tests never pass.

"less"

A provided value passes the comparison test if it is less than the sampled value.

"equal"

A provided value passes the comparison test if it is equal to the sampled value.

"less-equal"

A provided value passes the comparison test if it is less than or equal to the sampled value.

"greater"

A provided value passes the comparison test if it is greater than the sampled value.

"not-equal"

A provided value passes the comparison test if it is not equal to the sampled value.

"greater-equal"

A provided value passes the comparison test if it is greater than or equal to the sampled value.

"always"

Comparison tests always pass.

createSampler(descriptor)

Creates a GPUSampler.

Called on: GPUDevice this.

Arguments:

Arguments for the GPUDevice.createSampler(descriptor) method.
Parameter Type Nullable Optional Description
descriptor GPUSamplerDescriptor Description of the GPUSampler to create.

Returns: GPUSampler

  1. Let s be a new GPUSampler object.

  2. Issue the following steps on the Device timeline of this:

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

    2. Set s.[[descriptor]] to descriptor.

    3. Set s.[[isComparison]] to false if the compare attribute of s.[[descriptor]] is null or undefined. Otherwise, set it to true.

    4. Set s.[[isFiltering]] to false if none of minFilter, magFilter, or mipmapFilter has the value of "linear". Otherwise, set it to true.

  3. Return s.

Creating a GPUSampler that does trilinear filtering and repeats texture coordinates:
const sampler = gpuDevice.createSampler({
    addressModeU: 'repeat',
    addressModeV: 'repeat',
    magFilter: 'linear',
    minFilter: 'linear',
    mipmapFilter: 'linear',
});

8. Resource Binding

8.1. GPUBindGroupLayout

A GPUBindGroupLayout defines the interface between a set of resources bound in a GPUBindGroup and their accessibility in shader stages.

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

GPUBindGroupLayout has the following internal slots:

[[descriptor]]

8.1.1. Creation

A GPUBindGroupLayout is created via GPUDevice.createBindGroupLayout().

dictionary GPUBindGroupLayoutDescriptor : GPUObjectDescriptorBase {
    required sequence<GPUBindGroupLayoutEntry> entries;
};

A GPUBindGroupLayoutEntry describes a single shader resource binding to be included in a GPUBindGroupLayout.

dictionary GPUBindGroupLayoutEntry {
    required GPUIndex32 binding;
    required GPUShaderStageFlags visibility;

    GPUBufferBindingLayout buffer;
    GPUSamplerBindingLayout sampler;
    GPUTextureBindingLayout texture;
    GPUStorageTextureBindingLayout storageTexture;
    GPUExternalTextureBindingLayout externalTexture;
};

GPUBindGroupLayoutEntry dictionaries have the following members:

binding, of type GPUIndex32

A unique identifier for a resource binding within the GPUBindGroupLayout, corresponding to a GPUBindGroupEntry.binding and a @binding attribute in the GPUShaderModule.

visibility, of type GPUShaderStageFlags

A bitset of the members of GPUShaderStage. Each set bit indicates that a GPUBindGroupLayoutEntry's resource will be accessible from the associated shader stage.

buffer, of type GPUBufferBindingLayout

When not undefined, indicates the binding resource type for this GPUBindGroupLayoutEntry is GPUBufferBinding.

sampler, of type GPUSamplerBindingLayout

When not undefined, indicates the binding resource type for this GPUBindGroupLayoutEntry is GPUSampler.

texture, of type GPUTextureBindingLayout

When not undefined, indicates the binding resource type for this GPUBindGroupLayoutEntry is GPUTextureView.

storageTexture, of type GPUStorageTextureBindingLayout

When not undefined, indicates the binding resource type for this GPUBindGroupLayoutEntry is GPUTextureView.

externalTexture, of type GPUExternalTextureBindingLayout

When not undefined, indicates the binding resource type for this GPUBindGroupLayoutEntry is GPUExternalTexture.

typedef [EnforceRange] unsigned long GPUShaderStageFlags;
[Exposed=(Window, DedicatedWorker)]
namespace GPUShaderStage {
    const GPUFlagsConstant VERTEX   = 0x1;
    const GPUFlagsConstant FRAGMENT = 0x2;
    const GPUFlagsConstant COMPUTE  = 0x4;
};

GPUShaderStage contains the following flags, which describe which shader stages a corresponding GPUBindGroupEntry for this GPUBindGroupLayoutEntry will be visible to:

VERTEX

The bind group entry will be accessible to vertex shaders.

FRAGMENT

The bind group entry will be accessible to fragment shaders.

COMPUTE

The bind group entry will be accessible to compute shaders.

The binding member of a GPUBindGroupLayoutEntry is determined by which member of the GPUBindGroupLayoutEntry is defined: buffer, sampler, texture, storageTexture, or externalTexture. Only one may be defined for any given GPUBindGroupLayoutEntry. Each member has an associated GPUBindingResource type and each binding type has an associated internal usage, given by this table:

Binding member Resource type Binding type
Binding usage
buffer GPUBufferBinding "uniform" constant
"storage" storage
"read-only-storage" storage-read
sampler GPUSampler "filtering" constant
"non-filtering"
"comparison"
texture GPUTextureView "float" constant
"unfilterable-float"
"depth"
"sint"
"uint"
storageTexture GPUTextureView "write-only" storage
externalTexture GPUExternalTexture constant
The list of GPUBindGroupLayoutEntry values entries exceeds the binding slot limits of supported limits limits if the number of slots used toward a limit exceeds the supported value in limits. Each entry may use multiple slots toward multiple limits.
  1. For each entry in entries, if:

    entry.buffer?.type is "uniform" and entry.buffer?.hasDynamicOffset is true

    Consider 1 maxDynamicUniformBuffersPerPipelineLayout slot to be used.

    entry.buffer?.type is "storage" and entry.buffer?.hasDynamicOffset is true

    Consider 1 maxDynamicStorageBuffersPerPipelineLayout slot to be used.

  2. For each shader stage stage in « VERTEX, FRAGMENT, COMPUTE »:

    1. For each entry in entries for which entry.visibility contains stage, if:

      entry.buffer?.type is "uniform"

      Consider 1 maxUniformBuffersPerShaderStage slot to be used.

      entry.buffer?.type is "storage" or "read-only-storage"

      Consider 1 maxStorageBuffersPerShaderStage slot to be used.

      entry.sampler is not undefined

      Consider 1 maxSamplersPerShaderStage slot to be used.

      entry.texture is not undefined

      Consider 1 maxSampledTexturesPerShaderStage slot to be used.

      entry.storageTexture is not undefined

      Consider 1 maxStorageTexturesPerShaderStage slot to be used.

      entry.externalTexture is not undefined

      Consider 4 maxSampledTexturesPerShaderStage slot, 1 maxSamplersPerShaderStage slot, and 1 maxUniformBuffersPerShaderStage slot to be used.

enum GPUBufferBindingType {
    "uniform",
    "storage",
    "read-only-storage"
};

dictionary GPUBufferBindingLayout {
    GPUBufferBindingType type = "uniform";
    boolean hasDynamicOffset = false;
    GPUSize64 minBindingSize = 0;
};

GPUBufferBindingLayout dictionaries have the following members:

type, of type GPUBufferBindingType, defaulting to "uniform"

Indicates the type required for buffers bound to this bindings.

hasDynamicOffset, of type boolean, defaulting to false

Indicates whether this binding requires a dynamic offset.

minBindingSize, of type GPUSize64, defaulting to 0

Indicates the minimum buffer binding size.

Bindings are always validated against this size in createBindGroup().

If this is not 0, pipeline creation additionally validates that this value is large enough for the bindings declared in the shader.

If this is 0, draw/dispatch commands additionally validate that each binding in the GPUBindGroup is large enough for the bindings declared in the shader.

Note: Similar execution-time validation is theoretically possible for other binding-related fields specified for early validation, like sampleType and format, which currently can only be validated in pipeline creation. However, such execution-time validation could be costly or unnecessarily complex, so it is available only for minBindingSize which is expected to have the most ergonomic impact.

enum GPUSamplerBindingType {
    "filtering",
    "non-filtering",
    "comparison"
};

dictionary GPUSamplerBindingLayout {
    GPUSamplerBindingType type = "filtering";
};

GPUSamplerBindingLayout dictionaries have the following members:

type, of type GPUSamplerBindingType, defaulting to "filtering"

Indicates the required type of a sampler bound to this bindings.

enum GPUTextureSampleType {
    "float",
    "unfilterable-float",
    "depth",
    "sint",
    "uint"
};

dictionary GPUTextureBindingLayout {
    GPUTextureSampleType sampleType = "float";
    GPUTextureViewDimension viewDimension = "2d";
    boolean multisampled = false;
};

consider making sampleType truly optional.

GPUTextureBindingLayout dictionaries have the following members:

sampleType, of type GPUTextureSampleType, defaulting to "float"

Indicates the type required for texture views bound to this binding.

viewDimension, of type GPUTextureViewDimension, defaulting to "2d"

Indicates the required dimension for texture views bound to this binding.

multisampled, of type boolean, defaulting to false

Indicates whether or not texture views bound to this binding must be multisampled.

enum GPUStorageTextureAccess {
    "write-only"
};

dictionary GPUStorageTextureBindingLayout {
    GPUStorageTextureAccess access = "write-only";
    required GPUTextureFormat format;
    GPUTextureViewDimension viewDimension = "2d";
};

consider making format truly optional.

GPUStorageTextureBindingLayout dictionaries have the following members:

access, of type GPUStorageTextureAccess, defaulting to "write-only"

Indicates whether texture views bound to this binding will be bound for read-only or write-only access.

format, of type GPUTextureFormat

The required format of texture views bound to this binding.

viewDimension, of type GPUTextureViewDimension, defaulting to "2d"

Indicates the required dimension for texture views bound to this binding.

dictionary GPUExternalTextureBindingLayout {
};

A GPUBindGroupLayout object has the following internal slots:

[[entryMap]], of type ordered map<GPUSize32, GPUBindGroupLayoutEntry>

The map of binding indices pointing to the GPUBindGroupLayoutEntrys, which this GPUBindGroupLayout describes.

[[dynamicOffsetCount]], of type GPUSize32

The number of buffer bindings with dynamic offsets in this GPUBindGroupLayout.

[[exclusivePipeline]], of type GPUPipelineBase?, initially null

The pipeline that created this GPUBindGroupLayout, if it was created as part of a default pipeline layout. If not null, GPUBindGroups created with this GPUBindGroupLayout can only be used with the specified GPUPipelineBase.

createBindGroupLayout(descriptor)

Creates a GPUBindGroupLayout.

Called on: GPUDevice this.

Arguments:

Arguments for the GPUDevice.createBindGroupLayout(descriptor) method.
Parameter Type Nullable Optional Description
descriptor GPUBindGroupLayoutDescriptor Description of the GPUBindGroupLayout to create.

Returns: GPUBindGroupLayout

  1. For each GPUBindGroupLayoutEntry entry in descriptor.entries:

    1. If entry.storageTexture is not undefined:

      1. Validate texture format required features for entry.storageTexture.format with this.[[device]].

  2. Let layout be a new GPUBindGroupLayout object.

  3. Issue the following steps on the Device timeline of this:

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

    2. Set layout.[[descriptor]] to descriptor.

    3. Set layout.[[dynamicOffsetCount]] to the number of entries in descriptor where buffer is not undefined and buffer.hasDynamicOffset is true.

    4. For each GPUBindGroupLayoutEntry entry in descriptor.entries:

      1. Insert entry into layout.[[entryMap]] with the key of entry.binding.

  4. Return layout.

8.1.2. Compatibility

Two GPUBindGroupLayout objects a and b are considered group-equivalent if and only if all of the following conditions are satisfied:

If bind groups layouts are group-equivalent they can be interchangeably used in all contents.

8.2. GPUBindGroup

A GPUBindGroup defines a set of resources to be bound together in a group and how the resources are used in shader stages.

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

A GPUBindGroup object has the following internal slots:

[[layout]], of type GPUBindGroupLayout, readonly

The GPUBindGroupLayout associated with this GPUBindGroup.

[[entries]], of type sequence<GPUBindGroupEntry>, readonly

The set of GPUBindGroupEntrys this GPUBindGroup describes.

[[usedResources]], of type ordered map<subresource, list<internal usage>>, readonly

The set of buffer and texture subresources used by this bind group, associated with lists of the internal usage flags.

8.2.1. Bind Group Creation

A GPUBindGroup is created via GPUDevice.createBindGroup().

dictionary GPUBindGroupDescriptor : GPUObjectDescriptorBase {
    required GPUBindGroupLayout layout;
    required sequence<GPUBindGroupEntry> entries;
};

GPUBindGroupDescriptor dictionaries have the following members:

layout, of type GPUBindGroupLayout

The GPUBindGroupLayout the entries of this bind group will conform to.

entries, of type sequence<GPUBindGroupEntry>

A list of entries describing the resources to expose to the shader for each binding described by the layout.

typedef (GPUSampler or GPUTextureView or GPUBufferBinding or GPUExternalTexture) GPUBindingResource;

dictionary GPUBindGroupEntry {
    required GPUIndex32 binding;
    required GPUBindingResource resource;
};

A GPUBindGroupEntry describes a single resource to be bound in a GPUBindGroup, and has the following members:

binding, of type GPUIndex32

A unique identifier for a resource binding within the GPUBindGroup, corresponding to a GPUBindGroupLayoutEntry.binding and a @binding attribute in the GPUShaderModule.

resource, of type GPUBindingResource

The resource to bind, which may be a GPUSampler, GPUTextureView, GPUExternalTexture, or GPUBufferBinding.

dictionary GPUBufferBinding {
    required GPUBuffer buffer;
    GPUSize64 offset = 0;
    GPUSize64 size;
};

A GPUBufferBinding describes a buffer and optional range to bind as a resource, and has the following members:

buffer, of type GPUBuffer

The GPUBuffer to bind.

offset, of type GPUSize64, defaulting to 0

The offset, in bytes, from the beginning of buffer to the beginning of the range exposed to the shader by the buffer binding.

size, of type GPUSize64

The size, in bytes, of the buffer binding. If undefined, specifies the range starting at offset and ending at the end of buffer.

createBindGroup(descriptor)

Creates a GPUBindGroup.

Called on: GPUDevice this.

Arguments:

Arguments for the GPUDevice.createBindGroup(descriptor) method.
Parameter Type Nullable Optional Description
descriptor GPUBindGroupDescriptor Description of the GPUBindGroup to create.

Returns: GPUBindGroup

  1. Let bindGroup be a new GPUBindGroup object.

  2. Issue the following steps on the Device timeline of this:

    1. Let limits be this.[[device]].[[limits]].

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

      For each GPUBindGroupEntry bindingDescriptor in descriptor.entries:

    3. Let bindGroup.[[layout]] = descriptor.layout.

    4. Let bindGroup.[[entries]] = descriptor.entries.

    5. Let bindGroup.[[usedResources]] = {}.

    6. For each GPUBindGroupEntry bindingDescriptor in descriptor.entries:

      1. Let internalUsage be the binding usage for layoutBinding.

      2. Each subresource seen by resource is added to [[usedResources]] as internalUsage.

  3. Return bindGroup.

effective buffer binding size(binding)
  1. If binding.size is undefined:

    1. Return max(0, binding.buffer.size - binding.offset);

  2. Return binding.size.

Two GPUBufferBinding objects a and b are considered buffer-binding-aliasing if and only if all of the following are true:

Define how a range is formed by offset/size when size can be undefined.

8.3. GPUPipelineLayout

A GPUPipelineLayout defines the mapping between resources of all GPUBindGroup objects set up during command encoding in setBindGroup, and the shaders of the pipeline set by GPURenderCommandsMixin.setPipeline or GPUComputePassEncoder.setPipeline.

The full binding address of a resource can be defined as a trio of:

  1. shader stage mask, to which the resource is visible

  2. bind group index

  3. binding number

The components of this address can also be seen as the binding space of a pipeline. A GPUBindGroup (with the corresponding GPUBindGroupLayout) covers that space for a fixed bind group index. The contained bindings need to be a superset of the resources used by the shader at this bind group index.

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

GPUPipelineLayout has the following internal slots:

[[bindGroupLayouts]], of type list<GPUBindGroupLayout>

The GPUBindGroupLayout objects provided at creation in GPUPipelineLayoutDescriptor.bindGroupLayouts.

Note: using the same GPUPipelineLayout for many GPURenderPipeline or GPUComputePipeline pipelines guarantees that the user agent doesn’t need to rebind any resources internally when there is a switch between these pipelines.

GPUComputePipeline object X was created with GPUPipelineLayout.bindGroupLayouts A, B, C. GPUComputePipeline object Y was created with GPUPipelineLayout.bindGroupLayouts A, D, C. Supposing the command encoding sequence has two dispatches:
  1. setBindGroup(0, ...)

  2. setBindGroup(1, ...)

  3. setBindGroup(2, ...)

  4. setPipeline(X)

  5. dispatchWorkgroups()

  6. setBindGroup(1, ...)

  7. setPipeline(Y)

  8. dispatchWorkgroups()

In this scenario, the user agent would have to re-bind the group slot 2 for the second dispatch, even though neither the GPUBindGroupLayout at index 2 of GPUPipelineLayout.bindGrouplayouts, or the GPUBindGroup at slot 2, change.

should this example and the note be moved to some "best practices" document?

Note: the expected usage of the GPUPipelineLayout is placing the most common and the least frequently changing bind groups at the "bottom" of the layout, meaning lower bind group slot numbers, like 0 or 1. The more frequently a bind group needs to change between draw calls, the higher its index should be. This general guideline allows the user agent to minimize state changes between draw calls, and consequently lower the CPU overhead.

8.3.1. Creation

A GPUPipelineLayout is created via GPUDevice.createPipelineLayout().

dictionary GPUPipelineLayoutDescriptor : GPUObjectDescriptorBase {
    required sequence<GPUBindGroupLayout> bindGroupLayouts;
};

GPUPipelineLayoutDescriptor dictionaries define all the GPUBindGroupLayouts used by a pipeline, and have the following members:

bindGroupLayouts, of type sequence<GPUBindGroupLayout>

A list of GPUBindGroupLayouts the pipline will use. Each element corresponds to a @group attribute in the GPUShaderModule, with the Nth element corresponding with @group(N).

createPipelineLayout(descriptor)

Creates a GPUPipelineLayout.

Called on: GPUDevice this.

Arguments:

Arguments for the GPUDevice.createPipelineLayout(descriptor) method.
Parameter Type Nullable Optional Description
descriptor GPUPipelineLayoutDescriptor Description of the GPUPipelineLayout to create.

Returns: GPUPipelineLayout

  1. Let pl be a new GPUPipelineLayout object.

  2. Issue the following steps on the Device timeline of this:

    1. Let limits be this.[[device]].[[limits]].

    2. Let allEntries be the result of concatenating bgl.[[descriptor]].entries for all bgl in descriptor.bindGroupLayouts.

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

    4. Set the pl.[[bindGroupLayouts]] to descriptor.bindGroupLayouts.

  3. Return pl.

Note: two GPUPipelineLayout objects are considered equivalent for any usage if their internal [[bindGroupLayouts]] sequences contain GPUBindGroupLayout objects that are group-equivalent.

8.4. Example

Create a GPUBindGroupLayout that describes a binding with a uniform buffer, a texture, and a sampler. Then create a GPUBindGroup and a GPUPipelineLayout using the GPUBindGroupLayout.
const bindGroupLayout = gpuDevice.createBindGroupLayout({
    entries: [{
        binding: 0,
        visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT,
        buffer: {}
    }, {
        binding: 1,
        visibility: GPUShaderStage.FRAGMENT,
        texture: {}
    }, {
        binding: 2,
        visibility: GPUShaderStage.FRAGMENT,
        sampler: {}
    }]
});

const bindGroup = gpuDevice.createBindGroup({
    layout: bindGroupLayout,
    entries: [{
        binding: 0,
        resource: { buffer: buffer },
    }, {
        binding: 1,
        resource: texture
    }, {
        binding: 2,
        resource: sampler
    }]
});

const pipelineLayout = gpuDevice.createPipelineLayout({
    bindGroupLayouts: [bindGroupLayout]
});

9. Shader Modules

9.1. GPUShaderModule

[Exposed=(Window, DedicatedWorker), SecureContext]
interface GPUShaderModule {
    Promise<GPUCompilationInfo> compilationInfo();
};
GPUShaderModule includes GPUObjectBase;

GPUShaderModule is a reference to an internal shader module object.

9.1.1. Shader Module Creation

dictionary GPUShaderModuleDescriptor : GPUObjectDescriptorBase {
    required USVString code;
    object sourceMap;
    record<USVString, GPUShaderModuleCompilationHint> hints;
};
code, of type USVString

The WGSL source code for the shader module.

sourceMap, of type object

If defined MAY be interpreted as a source-map-v3 format.

Source maps are optional, but serve as a standardized way to support dev-tool integration such as source-language debugging [SourceMap]. WGSL names (identifiers) in source maps follow the rules defined in WGSL identifier comparison.

hints, of type record<USVString, GPUShaderModuleCompilationHint>

If defined maps an entry point name from the shader to a GPUShaderModuleCompilationHint. No validation is performed with any of these GPUShaderModuleCompilationHint. Implementations should use any information present in the GPUShaderModuleCompilationHint to perform as much compilation as is possible within createShaderModule(). Entry point names follow the rules defined in WGSL identifier comparison.

Note: Supplying information in hints does not have any observable effect, other than performance. Because a single shader module can hold multiple entry points, and multiple pipelines can be created from a single shader module, it can be more performant for an implementation to do as much compilation as possible once in createShaderModule() rather than multiple times in the multiple calls to createComputePipeline() / createRenderPipeline().

createShaderModule(descriptor)

Creates a GPUShaderModule.

Called on: GPUDevice this.

Arguments:

Arguments for the GPUDevice.createShaderModule(descriptor) method.
Parameter Type Nullable Optional Description
descriptor GPUShaderModuleDescriptor Description of the GPUShaderModule to create.

Returns: GPUShaderModule

  1. Let sm be a new GPUShaderModule object.

  2. Issue the following steps on the Device timeline of this:

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

    Describe remaining createShaderModule() validation and algorithm steps.

  3. Return sm.

User agents should not include error messages or shader text in the message text of validation errors arising here: these details are accessible via compilationInfo(). User agents should surface human-readable, formatted error details to developers for easier debugging (for example as a warning in the browser developer console, expandable to show full shader source).

As shader compilation errors should be rare in production applications, user agents could choose to surface them regardless of error handling (GPU error scopes or uncapturederror event handlers), e.g. as an expandable warning. If not, they should provide and document another way for developers to access human-readable error details, for example by adding a checkbox to show errors unconditionally, or by showing human-readable details when logging a GPUCompilationInfo object to the console.

Create a GPUShaderModule from WGSL code:
// A simple vertex and fragment shader pair that will fill the viewport with red.
const shaderSource = `
    var<private> pos : array<vec2<f32>, 3> = array<vec2<f32>, 3>(
        vec2(-1.0, -1.0), vec2(-1.0, 3.0), vec2(3.0, -1.0));

    @vertex
    fn vertexMain(@builtin(vertex_index) vertexIndex : u32) -> @builtin(position) vec4<f32> {
        return vec4(pos[input.vertexIndex], 1.0, 1.0);
    }

    @fragment
    fn fragmentMain() -> @location(0) vec4<f32> {
        return vec4(1.0, 0.0, 0.0, 1.0);
    }
`;

const shaderModule = gpuDevice.createShaderModule({
    code: shaderSource,
});
9.1.1.1. Shader Module Compilation Hints

Shader module compilation hints are optional, additional information indicating how a given GPUShaderModule entry point is intended to be used in the future. For some implementations this information may aid in compiling the shader module earlier, potentially increasing performance.

dictionary GPUShaderModuleCompilationHint {
    (GPUPipelineLayout or GPUAutoLayoutMode) layout;
};
layout, of type (GPUPipelineLayout or GPUAutoLayoutMode)

A GPUPipelineLayout that the GPUShaderModule may be used with in a future createComputePipeline() or createRenderPipeline() call. If set to "auto" the layout will be the default pipeline layout for the entry point associated with this hint will be used.

If possible, authors should be supplying the same information to createShaderModule() and createComputePipeline() / createRenderPipeline().

If an author is unable to provide hint information at the time of calling createShaderModule(), they should usually not delay calling createShaderModule(); but should instead just omit the unknown information from hints or GPUShaderModuleCompilationHint. Omitting this information may cause compilation to be deferred to createComputePipeline() / createRenderPipeline().

If an author is not confident that the hint information passed to createShaderModule() will match the information later passed to createComputePipeline() / createRenderPipeline() with that same module, they should avoid passing that information to createShaderModule(), as passing mismatched information to createShaderModule() may cause unnecessary compilations to occur.

9.1.2. Shader Module Compilation Information

enum GPUCompilationMessageType {
    "error",
    "warning",
    "info"
};

[Exposed=(Window, DedicatedWorker), Serializable, SecureContext]
interface GPUCompilationMessage {
    readonly attribute DOMString message;
    readonly attribute GPUCompilationMessageType type;
    readonly attribute unsigned long long lineNum;
    readonly attribute unsigned long long linePos;
    readonly attribute unsigned long long offset;
    readonly attribute unsigned long long length;
};

[Exposed=(Window, DedicatedWorker), Serializable, SecureContext]
interface GPUCompilationInfo {
    readonly attribute FrozenArray<GPUCompilationMessage> messages;
};

A GPUCompilationMessage is an informational, warning, or error message generated by the GPUShaderModule compiler. The messages are intended to be human readable to help developers diagnose issues with their shader code. Each message may correspond to either a single point in the shader code, a substring of the shader code, or may not correspond to any specific point in the code at all.

GPUCompilationMessage has the following attributes:

message, of type DOMString, readonly

A human-readable string containing the message generated during the shader compilation.

type, of type GPUCompilationMessageType, readonly

The severity level of the message.

If the type is "error", it corresponds to a shader-creation error.

lineNum, of type unsigned long long, readonly

The line number in the shader code the message corresponds to. Value is one-based, such that a lineNum of 1 indicates the first line of the shader code.

If the message corresponds to a substring this points to the line on which the substring begins. Must be 0 if the message does not correspond to any specific point in the shader code.

Reference WGSL spec when it defines what a line is. [Issue #gpuweb/gpuweb#2435]

linePos, of type unsigned long long, readonly

The offset, in UTF-16 code units, from the beginning of line lineNum of the shader code to the point or beginning of the substring that the message corresponds to. Value is one-based, such that a linePos of 1 indicates the first code unit of the line.

If message corresponds to a substring this points to the first UTF-16 code unit of the substring. Must be 0 if the message does not correspond to any specific point in the shader code.

offset, of type unsigned long long, readonly

The offset from the beginning of the shader code in UTF-16 code units to the point or beginning of the substring that message corresponds to. Must reference the same position as lineNum and linePos. Must be 0 if the message does not correspond to any specific point in the shader code.

length, of type unsigned long long, readonly

The number of UTF-16 code units in the substring that message corresponds to. If the message does not correspond with a substring then length must be 0.

Note: GPUCompilationMessage.lineNum and GPUCompilationMessage.linePos are one-based since the most common use for them is expected to be printing human readable messages that can be correlated with the line and column numbers shown in many text editors.

Note: GPUCompilationMessage.offset and GPUCompilationMessage.length are appropriate to pass to substr() in order to retrieve the substring of the shader code the message corresponds to.

compilationInfo()

Returns any messages generated during the GPUShaderModule's compilation.

The locations, order, and contents of messages are implementation-defined. In particular, messages may not be ordered by lineNum.

Called on: GPUShaderModule this.

Returns: Promise<GPUCompilationInfo>

Describe compilationInfo() algorithm steps.

10. Pipelines

A pipeline, be it GPUComputePipeline or GPURenderPipeline, represents the complete function done by a combination of the GPU hardware, the driver, and the user agent, that process the input data in the shape of bindings and vertex buffers, and produces some output, like the colors in the output render targets.

Structurally, the pipeline consists of a sequence of programmable stages (shaders) and fixed-function states, such as the blending modes.

Note: Internally, depending on the target platform, the driver may convert some of the fixed-function states into shader code, and link it together with the shaders provided by the user. This linking is one of the reason the object is created as a whole.

This combination state is created as a single object (by GPUDevice.createComputePipeline() or GPUDevice.createRenderPipeline()), and switched as one (by GPUComputePassEncoder.setPipeline or GPURenderCommandsMixin.setPipeline correspondingly).

10.1. Base pipelines

enum GPUAutoLayoutMode {
    "auto"
};

dictionary GPUPipelineDescriptorBase : GPUObjectDescriptorBase {
    required (GPUPipelineLayout or GPUAutoLayoutMode) layout;
};

interface mixin GPUPipelineBase {
    [NewObject] GPUBindGroupLayout getBindGroupLayout(unsigned long index);
};

GPUPipelineBase has the following internal slots:

[[layout]], of type GPUPipelineLayout

The definition of the layout of resources which can be used with this.

GPUPipelineBase has the following methods:

getBindGroupLayout(index)

Gets a GPUBindGroupLayout that is compatible with the GPUPipelineBase's GPUBindGroupLayout at index.

Called on: GPUPipelineBase this.

Arguments:

Arguments for the GPUPipelineBase.getBindGroupLayout(index) method.
Parameter Type Nullable Optional Description
index unsigned long Index into the pipeline layout’s [[bindGroupLayouts]] sequence.

Returns: GPUBindGroupLayout

  1. If indexthis.[[device]].[[limits]].maxBindGroups:

    1. Throw a RangeError.

  2. If this is not valid:

    1. Return a new error GPUBindGroupLayout.

  3. If index ≥ the size of this.[[layout]].[[bindGroupLayouts]]:

    1. Return a new error GPUBindGroupLayout.

  4. Return a new GPUBindGroupLayout object that references the same internal object as this.[[layout]].[[bindGroupLayouts]][index].

Specify this more properly once we have internal objects for GPUBindGroupLayout. Alternatively only spec is as a new internal objects that’s group-equivalent

Note: Only returning new GPUBindGroupLayout objects ensures no synchronization is necessary between the Content timeline and the Device timeline.

10.1.1. Default pipeline layout

A GPUPipelineBase object that was created with a layout set to "auto" has a default layout created and used instead.

Note: Default layouts are provided as a convenience for simple pipelines, but use of explicit layouts is recommended in most cases. Bind groups created from default layouts cannot be used with other pipelines, and the structure of the default layout may change when altering shaders, causing unexpected bind group creation errors.

To create a default pipeline layout for GPUPipelineBase pipeline, run the following steps:

  1. Let groupDescs be a sequence of device.[[limits]].maxBindGroups new GPUBindGroupLayoutDescriptor objects.

  2. For each groupDesc in groupDescs:

    1. Set groupDesc.entries to an empty sequence.

  3. For each GPUProgrammableStage stageDesc in the descriptor used to create pipeline:

    1. Let stageInfo be the "reflection information" for stageDesc.

      Define the reflection information concept so that this spec can interface with the WGSL spec and get information what the interface is for a GPUShaderModule for a specific entrypoint.

    2. Let shaderStage be the GPUShaderStageFlags for stageDesc.entryPoint in stageDesc.module.

    3. For each resource resource in stageInfo’s resource interface:

      1. Let group be resource’s "group" decoration.

      2. Let binding be resource’s "binding" decoration.

      3. Let entry be a new GPUBindGroupLayoutEntry.

      4. Set entry.binding to binding.

      5. Set entry.visibility to shaderStage.

      6. If resource is for a sampler binding:

        1. Let samplerLayout be a new GPUSamplerBindingLayout.

        2. Set entry.sampler to samplerLayout.

      7. If resource is for a comparison sampler binding:

        1. Let samplerLayout be a new GPUSamplerBindingLayout.

        2. Set samplerLayout.type to "comparison".

        3. Set entry.sampler to samplerLayout.

      8. If resource is for a buffer binding:

        1. Let bufferLayout be a new GPUBufferBindingLayout.

        2. Set bufferLayout.minBindingSize to resource’s minimum buffer binding size.

          link to a definition for "minimum buffer binding size" in the "reflection information".

        3. If resource is for a read-only storage buffer:

          1. Set bufferLayout.type to "read-only-storage".

        4. If resource is for a storage buffer:

          1. Set bufferLayout.type to "storage".

        5. Set entry.buffer to bufferLayout.

      9. If resource is for a sampled texture binding:

        1. Let textureLayout be a new GPUTextureBindingLayout.

        2. If resource is a depth texture binding:

          Else if the sampled type of resource is:

        3. Set textureLayout.viewDimension to resource’s dimension.

        4. If resource is for a multisampled texture:

          1. Set textureLayout.multisampled to true.

        5. Set entry.texture to textureLayout.

      10. If resource is for a storage texture binding:

        1. Let storageTextureLayout be a new GPUStorageTextureBindingLayout.

        2. Set storageTextureLayout.format to resource’s format.

        3. Set storageTextureLayout.viewDimension to resource’s dimension.

        4. If resource is for a write-only storage texture:

          1. Set storageTextureLayout.access to "write-only".

        5. Set entry.storageTexture to storageTextureLayout.

      11. If groupDescs[group] has an entry previousEntry with binding equal to binding:

        1. If entry has different visibility than previousEntry:

          1. Add the bits set in entry.visibility into previousEntry.visibility

        2. If resource is for a buffer binding and entry has greater buffer.minBindingSize than previousEntry:

          1. Set previousEntry.buffer.minBindingSize to entry.buffer.minBindingSize.

        3. If resource is a sampled texture binding and entry has different texture.sampleType than previousEntry and both entry and previousEntry have texture.sampleType of either "float" or "unfilterable-float":

          1. Set previousEntry.texture.sampleType to "float".

        4. If any other property is unequal between entry and previousEntry:

          1. Return null (which will cause the creation of the pipeline to fail).

      12. Else

        1. Append entry to groupDescs[group].

  4. Let groupLayouts be a new sequence.

  5. For each groupDesc in groupDescs:

    1. Let bindGroupLayout be the result of calling device.createBindGroupLayout()(groupDesc).

    2. Set bindGroupLayout.[[exclusivePipeline]] to pipeline.

    3. Append bindGroupLayout to groupLayouts.

  6. Let desc be a new GPUPipelineLayoutDescriptor.

  7. Set desc.bindGroupLayouts to groupLayouts.

  8. Return device.createPipelineLayout()(desc).

This fills the pipeline layout with empty bindgroups. Revisit once the behavior of empty bindgroups is specified.

10.1.2. GPUProgrammableStage

A GPUProgrammableStage describes the entry point in the user-provided GPUShaderModule that controls one of the programmable stages of a pipeline. Entry point names follow the rules defined in WGSL identifier comparison.

dictionary GPUProgrammableStage {
    required GPUShaderModule module;
    required USVString entryPoint;
    record<USVString, GPUPipelineConstantValue> constants;
};

typedef double GPUPipelineConstantValue; // May represent WGSL’s bool, f32, i32, u32, and f16 if enabled.

GPUProgrammableStage has the following members:

module, of type GPUShaderModule

The GPUShaderModule containing the code that this programmable stage will execute.

entryPoint, of type USVString

The name of the function in module that this stage will use to perform its work.

constants, of type record<USVString, GPUPipelineConstantValue>

Specifies the values of pipeline-overridable constants in the shader module module.

Each such pipeline-overridable constant is uniquely identified by a single pipeline-overridable constant identifier string (representing the numeric ID of the constant, if one is specified, and otherwise the constant’s identifier name). WGSL names (identifiers) in source maps follow the rules defined in WGSL identifier comparison.

The key of each key-value pair must equal the identifier string of one such constant. When the pipeline is executed, that constant will have the specified value.

Values are specified as GPUPipelineConstantValue, which is a double which is converted to the WGSL data type of the corresponding pipeline-overridable constant (bool, i32, u32, or f32) via an IDL value (boolean, long, unsigned long, or float). If the "shader-f16" feature is enabled, a pipeline-overridable constant may be of WGSL data type f16. The specified GPUPipelineConstantValue for a pipeline-overridable constant of f16 is converted to float via an IDL value, then converted to WGSL type f16 via WGSL f32 to f16 conversion defined in WGSL specification.

Pipeline-overridable constants defined in WGSL:
@id(0)    override has_point_light: bool = true; // Algorithmic control.
@id(1200) override specular_param: f32 = 2.3;    // Numeric control.
@id(1300) override gain: f32;                    // Must be overridden.
          override width: f32 = 0.0;             // Specifed at the API level
                                                 //   using the name "width".
          override depth: f32;                   // Specifed at the API level
                                                 //   using the name "depth".
                                                 //   Must be overridden.
          override height = 2 * depth;           // The default value
                                                 // (if not set at the API level),
                                                 // depends on another
                                                 // overridable constant.

Corresponding JavaScript code, providing only the overrides which are required (have no defaults):

{
    // ...
    constants: {
        1300: 2.0,  // "gain"
        depth: -1,  // "depth"
    }
}

Corresponding JavaScript code, overriding all constants:

{
    // ...
    constants: {
        0: false,   // "has_point_light"
        1200: 3.0,  // "specular_param"
        1300: 2.0,  // "gain"
        width: 20,  // "width"
        depth: -1,  // "depth"
        height: 15, // "height"
    }
}
validating GPUProgrammableStage(stage, descriptor, layout)

Arguments:

Return true if all of the following conditions are met:

A return value of false corresponds to a pipeline-creation error.

validating shader binding(binding, layout)

Arguments:

Let bindGroup be the bind group index, and bindIndex be the binding index, of the shader binding declaration variable.

Return true if all of the following conditions are satisfied:

A resource binding is considered to be statically used by a shader entry point if and only if it’s reachable by the control flow graph of the shader module, starting at the entry point.

10.2. GPUComputePipeline

A GPUComputePipeline is a kind of pipeline that controls the compute shader stage, and can be used in GPUComputePassEncoder.

Compute inputs and outputs are all contained in the bindings, according to the given GPUPipelineLayout. The outputs correspond to buffer bindings with a type of "storage" and storageTexture bindings with a type of "write-only".

Stages of a compute pipeline:

  1. Compute shader

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

10.2.1. Creation

A GPURenderPipelineDescriptor describes a compute pipeline. See § 22.2 Computing for additional details.

dictionary GPUComputePipelineDescriptor : GPUPipelineDescriptorBase {
    required GPUProgrammableStage compute;
};

GPUComputePipelineDescriptor has the following members:

compute, of type GPUProgrammableStage

Describes the compute shader entry point of the pipeline.

createComputePipeline(descriptor)

Creates a GPUComputePipeline.

Called on: GPUDevice this.

Arguments:

Arguments for the GPUDevice.createComputePipeline(descriptor) method.
Parameter Type Nullable Optional Description
descriptor GPUComputePipelineDescriptor Description of the GPUComputePipeline to create.

Returns: GPUComputePipeline

  1. Let pipeline be a new GPUComputePipeline object.

  2. Issue the following steps on the Device timeline of this:

    1. Let layout be a new default pipeline layout for pipeline if descriptor.layout is "auto", and descriptor.layout otherwise.

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

    2. Set pipeline.[[layout]] to layout.

  3. Return pipeline.

createComputePipelineAsync(descriptor)

Creates a GPUComputePipeline. The returned Promise resolves when the created pipeline is ready to be used without additional delay.

If pipeline creation fails, the returned Promise rejects with an OperationError.

Note: Use of this method is preferred whenever possible, as it prevents blocking the queue timeline work on pipeline compilation.

Called on: GPUDevice this.

Arguments:

Arguments for the GPUDevice.createComputePipelineAsync(descriptor) method.
Parameter Type Nullable Optional Description
descriptor GPUComputePipelineDescriptor Description of the GPUComputePipeline to create.

Returns: Promise<GPUComputePipeline>

  1. Let promise be a new promise.

  2. Issue the following steps on the Device timeline of this:

    1. Let pipeline be a new GPUComputePipeline created as if this.createComputePipeline() was called with descriptor;

    2. When pipeline is ready to be used or has been made invalid, resolve promise with pipeline.

  3. Return promise.

Creating a simple GPUComputePipeline:
const computePipeline = gpuDevice.createComputePipeline({
    layout: pipelineLayout,
    compute: {
        module: computeShaderModule,
        entryPoint: 'computeMain',
    }
});

10.3. GPURenderPipeline

A GPURenderPipeline is a kind of pipeline that controls the vertex and fragment shader stages, and can be used in GPURenderPassEncoder as well as GPURenderBundleEncoder.

Render pipeline inputs are:

Render pipeline outputs are:

A render pipeline is comprised of the following render stages:

  1. Vertex fetch, controlled by GPUVertexState.buffers

  2. Vertex shader, controlled by GPUVertexState

  3. Primitive assembly, controlled by GPUPrimitiveState

  4. Rasterization, controlled by GPUPrimitiveState, GPUDepthStencilState, and GPUMultisampleState

  5. Fragment shader, controlled by GPUFragmentState

  6. Stencil test and operation, controlled by GPUDepthStencilState

  7. Depth test and write, controlled by GPUDepthStencilState

  8. Output merging, controlled by GPUFragmentState.targets

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

GPURenderPipeline has the following internal slots:

[[descriptor]], of type GPURenderPipelineDescriptor

The GPURenderPipelineDescriptor describing this pipeline.

All optional fields of GPURenderPipelineDescriptor are defined.

[[writesDepth]], of type boolean

True if the pipeline writes to the depth component of the depth/stencil attachment

[[writesStencil]], of type boolean

True if the pipeline writes to the stencil component of the depth/stencil attachment

10.3.1. Creation

A GPURenderPipelineDescriptor describes a render pipeline by configuring each of the render stages. See § 22.3 Rendering for additional details.

dictionary GPURenderPipelineDescriptor : GPUPipelineDescriptorBase {
    required GPUVertexState vertex;
    GPUPrimitiveState primitive = {};
    GPUDepthStencilState depthStencil;
    GPUMultisampleState multisample = {};
    GPUFragmentState fragment;
};

GPURenderPipelineDescriptor has the following members:

vertex, of type GPUVertexState

Describes the vertex shader entry point of the pipeline and its input buffer layouts.

primitive, of type GPUPrimitiveState, defaulting to {}

Describes the primitive-related properties of the pipeline.

depthStencil, of type GPUDepthStencilState

Describes the optional depth-stencil properties, including the testing, operations, and bias.

multisample, of type GPUMultisampleState, defaulting to {}

Describes the multi-sampling properties of the pipeline.

fragment, of type GPUFragmentState

Describes the fragment shader entry point of the pipeline and its output colors. If undefined, the § 22.3.8 No Color Output mode is enabled.

createRenderPipeline(descriptor)

Creates a GPURenderPipeline.

Called on: GPUDevice this.

Arguments:

Arguments for the GPUDevice.createRenderPipeline(descriptor) method.
Parameter Type Nullable Optional Description
descriptor GPURenderPipelineDescriptor Description of the GPURenderPipeline to create.

Returns: GPURenderPipeline

  1. If descriptor.fragment is not undefined:

    1. For each non-null colorState layout descriptor in the list descriptor.fragment.targets:

      1. Validate texture format required features of colorState.format with this.[[device]].

  2. If descriptor.depthStencil is not null:

    1. Validate texture format required features of descriptor.depthStencil.format with this.[[device]].

  3. Let pipeline be a new GPURenderPipeline object.

  4. Issue the following steps on the Device timeline of this:

    1. Let layout be a new default pipeline layout for pipeline if descriptor.layout is "auto", and descriptor.layout otherwise.

    2. If any of the following conditions are unsatisfied: generate a validation error, make pipeline invalid, and stop.

    3. Set pipeline.[[descriptor]] to descriptor.

    4. Set pipeline.[[writesDepth]] to false.

    5. Set pipeline.[[writesStencil]] to false.

    6. Let depthStencil be descriptor.depthStencil.

    7. If depthStencil is not null:

      1. Set pipeline.[[writesDepth]] to depthStencil.depthWriteEnabled.

      2. If depthStencil.stencilWriteMask is not 0:

        1. Let stencilFront be depthStencil.stencilFront.

        2. Let stencilBack be depthStencil.stencilBack.

        3. Let cullMode be descriptor.primitive.cullMode.

        4. If cullMode is not "front", and any of stencilFront.passOp, stencilFront.depthFailOp, or stencilFront.failOp is not "keep":

          1. Set pipeline.[[writesStencil]] to true.

        5. If cullMode is not "back", and any of stencilBack.passOp, stencilBack.depthFailOp, or stencilBack.failOp is not "keep":

          1. Set pipeline.[[writesStencil]] to true.

    8. Set pipeline.[[layout]] to layout.

  5. Return pipeline.

need description of the render states.

createRenderPipelineAsync(descriptor)

Creates a GPURenderPipeline. The returned Promise resolves when the created pipeline is ready to be used without additional delay.

If pipeline creation fails, the returned Promise rejects with an OperationError.

Note: Use of this method is preferred whenever possible, as it prevents blocking the queue timeline work on pipeline compilation.

Called on: GPUDevice this.

Arguments:

Arguments for the GPUDevice.createRenderPipelineAsync(descriptor) method.
Parameter Type Nullable Optional Description
descriptor GPURenderPipelineDescriptor Description of the GPURenderPipeline to create.

Returns: Promise<GPURenderPipeline>

  1. Let promise be a new promise.

  2. Issue the following steps on the Device timeline of this:

    1. Let pipeline be a new GPURenderPipeline created as if this.createRenderPipeline() was called with descriptor;

    2. When pipeline is ready to be used or has been made invalid, resolve promise with pipeline.

  3. Return promise.

validating GPURenderPipelineDescriptor(descriptor, layout, device) Arguments:

Return true if all of the following conditions are satisfied:

validating inter-stage interfaces(device, descriptor)

Arguments:

Returns: boolean

  1. Let maxVertexShaderOutputComponents be device.limits.maxInterStageShaderComponents.

    1. If descriptor.primitive.topology is "point-list":

      1. Decrement maxVertexShaderOutputComponents by 1.

  2. Let maxFragmentShaderInputComponents be device.limits.maxInterStageShaderComponents.

    1. If the front_facing builtin is an input of descriptor.fragment:

      1. Decrement maxFragmentShaderInputComponents by 1.

    2. If the sample_index builtin is an input of descriptor.fragment:

      1. Decrement maxFragmentShaderInputComponents by 1.

    3. If the sample_mask builtin is an input of descriptor.fragment:

      1. Decrement maxFragmentShaderInputComponents by 1.

  3. Return true if and only if all of the following conditions are satisfied:

    • The location of each user-defined output of descriptor.vertex is less than (device.limits.maxInterStageShaderVariables).

    • The location of each user-defined input of descriptor.fragment is less than (device.limits.maxInterStageShaderVariables).

    • There are no more than maxVertexShaderOutputComponents scalar components across all user-defined outputs for descriptor.vertex. (For example, a f32 output uses 1 component, and a vec3<f32> output uses 3 components.)

    • There are no more than maxFragmentShaderInputComponents scalar components across all user-defined inputs for descriptor.fragment.

define what "compatible" means for render target formats.

Creating a simple GPURenderPipeline:
const renderPipeline = gpuDevice.createRenderPipeline({
    layout: pipelineLayout,
    vertex: {
        module: shaderModule,
        entryPoint: 'vertexMain'
    },
    fragment: {
        module: shaderModule,
        entryPoint: 'fragmentMain',
        targets: [{
            format: 'bgra8unorm',
        }],
    }
});

10.3.2. Primitive State

dictionary GPUPrimitiveState {
    GPUPrimitiveTopology topology = "triangle-list";
    GPUIndexFormat stripIndexFormat;
    GPUFrontFace frontFace = "ccw";
    GPUCullMode cullMode = "none";

    // Requires "depth-clip-control" feature.
    boolean unclippedDepth = false;
};

GPUPrimitiveState has the following members, which describe how a GPURenderPipeline constructs and rasterizes primitives from its vertex inputs:

topology, of type GPUPrimitiveTopology, defaulting to "triangle-list"

The type of primitive to be constructed from the vertex inputs.

stripIndexFormat, of type GPUIndexFormat

For strip topologies ("line-strip" or "triangle-strip"), defines the format of indices that may be used with this GPURenderPipeline. This determines the strip’s primitive restart value. See § 22.3.3 Primitive Assembly for additional details.

Required only if the pipeline is used with indexed draw calls. Not allowed with non-strip topologies.

frontFace, of type GPUFrontFace, defaulting to "ccw"

Defines which polygons are considered front-facing.

cullMode, of type GPUCullMode, defaulting to "none"

Defines which polygon orientation will be culled, if any.

unclippedDepth, of type boolean, defaulting to false

If true, indicates that depth clipping is disabled. See § 24.1 "depth-clip-control" for additional details.

Requires the "depth-clip-control" feature to be enabled.

validating GPUPrimitiveState(descriptor, features) Arguments:

Return true if all of the following conditions are satisfied:

enum GPUPrimitiveTopology {
    "point-list",
    "line-list",
    "line-strip",
    "triangle-list",
    "triangle-strip"
};

GPUPrimitiveTopology defines the primitive type draw calls made with a GPURenderPipeline will use. See § 22.3.5 Rasterization for additional details:

"point-list"

Each vertex defines a point primitive.

"line-list"

Each consecutive pair of two vertices defines a line primitive.

"line-strip"

Each vertex after the first defines a line primitive between it and the previous vertex.

"triangle-list"

Each consecutive triplet of three vertices defines a triangle primitive.

"triangle-strip"

Each vertex after the first two defines a triangle primitive between it and the previous two vertices.

enum GPUFrontFace {
    "ccw",
    "cw"
};

GPUFrontFace defines which polygons are considered front-facing by a GPURenderPipeline. See § 22.3.5.4 Polygon Rasterization for additional details:

"ccw"

Polygons with vertices whose framebuffer coordinates are given in counter-clockwise order are considered front-facing.

"cw"

Polygons with vertices whose framebuffer coordinates are given in clockwise order are considered front-facing.

enum GPUCullMode {
    "none",
    "front",
    "back"
};

GPUPrimitiveTopology defines which polygons will be culled by draw calls made with a GPURenderPipeline. See § 22.3.5.4 Polygon Rasterization for additional details:

"none"

No polygons are discarded.

"front"

Front-facing polygons are discarded.

"back"

Back-facing polygons are discarded.

Note: GPUFrontFace and GPUCullMode have no effect on "point-list", "line-list", or "line-strip" topologies.

10.3.3. Multisample State

dictionary GPUMultisampleState {
    GPUSize32 count = 1;
    GPUSampleMask mask = 0xFFFFFFFF;
    boolean alphaToCoverageEnabled = false;
};

GPUMultisampleState has the following members, which describe how a GPURenderPipeline interacts with a render pass’s multisampled attachments.

count, of type GPUSize32, defaulting to 1

Number of samples per pixel. This GPURenderPipeline will be compatible only with attachment textures (colorAttachments and depthStencilAttachment) with matching sampleCounts.

mask, of type GPUSampleMask, defaulting to 0xFFFFFFFF

Mask determining which samples are written to.

alphaToCoverageEnabled, of type boolean, defaulting to false

When true indicates that a fragment’s alpha channel should be used to generate a sample coverage mask.

validating GPUMultisampleState(descriptor) Arguments:

Return true if all of the following conditions are satisfied:

10.3.4. Fragment State

dictionary GPUFragmentState : GPUProgrammableStage {
    required sequence<GPUColorTargetState?> targets;
};
validating GPUFragmentState(GPUDevice device, GPUFragmentState descriptor)

Return true if all of the following requirements are met:

Note: The fragment shader may output more values than what the pipeline uses. If that is the case the values are ignored.

component is a valid GPUBlendComponent if it meets the following requirements:

define the area of reach for "statically used" things of GPUProgrammableStage

10.3.5. Color Target State

dictionary GPUColorTargetState {
    required GPUTextureFormat format;

    GPUBlendState blend;
    GPUColorWriteFlags writeMask = 0xF;  // GPUColorWrite.ALL
};
dictionary GPUBlendState {
    required GPUBlendComponent color;
    required GPUBlendComponent alpha;
};
typedef [EnforceRange] unsigned long GPUColorWriteFlags;
[Exposed=(Window, DedicatedWorker)]
namespace GPUColorWrite {
    const GPUFlagsConstant RED   = 0x1;
    const GPUFlagsConstant GREEN = 0x2;
    const GPUFlagsConstant BLUE  = 0x4;
    const GPUFlagsConstant ALPHA = 0x8;
    const GPUFlagsConstant ALL   = 0xF;
};
10.3.5.1. Blend State
dictionary GPUBlendComponent {
    GPUBlendOperation operation = "add";
    GPUBlendFactor srcFactor = "one";
    GPUBlendFactor dstFactor = "zero";
};

GPUBlendComponent has the following members, which describe how the color or alpha components of a fragment are blended:

operation, of type GPUBlendOperation, defaulting to "add"

Defines the GPUBlendOperation used to calculate the values written to the target attachment components.

srcFactor, of type GPUBlendFactor, defaulting to "one"

Defines the GPUBlendFactor operation to be performed on values from the fragment shader.

dstFactor, of type GPUBlendFactor, defaulting to "zero"

Defines the GPUBlendFactor operation to be performed on values from the target attachment.

The following tables use this notation to describe color components for a given fragment location:

RGBAsrc Color output by the fragment shader for the color attachment.
RGBAdst Color currently in the color attachment.
RGBAconst The current [[blend_constant]].
RGBAsrcFactor The source blend factor components, as defined by srcFactor.
RGBAdstFactor The destination blend factor components, as defined by dstFactor.
enum GPUBlendFactor {
    "zero",
    "one",
    "src",
    "one-minus-src",
    "src-alpha",
    "one-minus-src-alpha",
    "dst",
    "one-minus-dst",
    "dst-alpha",
    "one-minus-dst-alpha",
    "src-alpha-saturated",
    "constant",
    "one-minus-constant"
};

GPUBlendFactor defines how either a source or destination blend factors is calculated:

GPUBlendFactor Blend factor RGBA components
"zero" (0, 0, 0, 0)
"one" (1, 1, 1, 1)
"src" (Rsrc, Gsrc, Bsrc, Asrc)
"one-minus-src" (1 - Rsrc, 1 - Gsrc, 1 - Bsrc, 1 - Asrc)
"src-alpha" (Asrc, Asrc, Asrc, Asrc)
"one-minus-src-alpha" (1 - Asrc, 1 - Asrc, 1 - Asrc, 1 - Asrc)
"dst" (Rdst, Gdst, Bdst, Adst)
"one-minus-dst" (1 - Rdst, 1 - Gdst, 1 - Bdst, 1 - Adst)
"dst-alpha" (Adst, Adst, Adst, Adst)
"one-minus-dst-alpha" (1 - Adst, 1 - Adst, 1 - Adst, 1 - Adst)
"src-alpha-saturated" (Asrc, Asrc, Asrc, Asrc)
"constant" (Rconst, Gconst, Bconst, Aconst)
"one-minus-constant" (1 - Rconst, 1 - Gconst, 1 - Bconst, 1 - Aconst)
enum GPUBlendOperation {
    "add",
    "subtract",
    "reverse-subtract",
    "min",
    "max"
};

GPUBlendOperation defines the algorithm used to combine source and destination blend factors:

GPUBlendOperation RGBA Components
"add" RGBAsrc × RGBAsrcFactor + RGBAdst × RGBAdstFactor
"subtract" RGBAsrc × RGBAsrcFactor - RGBAdst × RGBAdstFactor
"reverse-subtract" RGBAdst × RGBAdstFactor - RGBAsrc × RGBAsrcFactor
"min" min(RGBAsrc, RGBAdst)
"max" max(RGBAsrc, RGBAdst)

10.3.6. Depth/Stencil State

dictionary GPUDepthStencilState {
    required GPUTextureFormat format;

    boolean depthWriteEnabled = false;
    GPUCompareFunction depthCompare = "always";

    GPUStencilFaceState stencilFront = {};
    GPUStencilFaceState stencilBack = {};

    GPUStencilValue stencilReadMask = 0xFFFFFFFF;
    GPUStencilValue stencilWriteMask = 0xFFFFFFFF;

    GPUDepthBias depthBias = 0;
    float depthBiasSlopeScale = 0;
    float depthBiasClamp = 0;
};

GPUDepthStencilState has the following members, which describe how a GPURenderPipeline will affect a render pass’s depthStencilAttachment:

format, of type GPUTextureFormat

The format of depthStencilAttachment this GPURenderPipeline will be compatible with.

depthWriteEnabled, of type boolean, defaulting to false

Indicates if this GPURenderPipeline can modify depthStencilAttachment depth values.

depthCompare, of type GPUCompareFunction, defaulting to "always"

The comparison operation used to test fragment depths against depthStencilAttachment depth values.

stencilFront, of type GPUStencilFaceState, defaulting to {}

Defines how stencil comparisons and operations are performed for front-facing primitives.

stencilBack, of type GPUStencilFaceState, defaulting to {}

Defines how stencil comparisons and operations are performed for back-facing primitives.

stencilReadMask, of type GPUStencilValue, defaulting to 0xFFFFFFFF

Bitmask controlling which depthStencilAttachment stencil value bits are read when performing stencil comparison tests.

stencilWriteMask, of type GPUStencilValue, defaulting to 0xFFFFFFFF

Bitmask controlling which depthStencilAttachment stencil value bits are written to when performing stencil operations.

depthBias, of type GPUDepthBias, defaulting to 0

Constant depth bias added to each fragment. See biased fragment depth for details.

depthBiasSlopeScale, of type float, defaulting to 0

Depth bias that scales with the fragment’s slope. See biased fragment depth for details.

depthBiasClamp, of type float, defaulting to 0

The maximum depth bias of a fragment. See biased fragment depth for details.

The biased fragment depth for a fragment being written to depthStencilAttachment attachment when drawing using GPUDepthStencilState state is calculated by running the following steps:
  1. Let format be attachment.view.format.

  2. Let r be the minimum positive representable value > 0 in the format converted to a 32-bit float.

  3. Let maxDepthSlope be the maximum of the horizontal and vertical slopes of the fragment’s depth value.

  4. If format is a unorm format:

    1. Let bias be (float)state.depthBias * r + state.depthBiasSlopeScale * maxDepthSlope.

  5. Otherwise, if format is a float format:

    1. Let bias be (float)state.depthBias * 2^(exp(max depth in primitive) - r) + state.depthBiasSlopeScale * maxDepthSlope.

  6. If state.depthBiasClamp > 0:

    1. Set bias to min(state.depthBiasClamp, bias).

  7. Otherwise if state.depthBiasClamp < 0:

    1. Set bias to max(state.depthBiasClamp, bias).

  8. If state.depthBias0 or state.depthBiasSlopeScale0:

    1. Set the fragment depth value to fragment depth value + bias

validating GPUDepthStencilState(descriptor)

Arguments:

Return true if, and only if, all of the following conditions are satisfied:

how can this algorithm support depth/stencil formats that are added in extensions?

dictionary GPUStencilFaceState {
    GPUCompareFunction compare = "always";
    GPUStencilOperation failOp = "keep";
    GPUStencilOperation depthFailOp = "keep";
    GPUStencilOperation passOp = "keep";
};

GPUStencilFaceState has the following members, which describe how stencil comparisons and operations are performed:

compare, of type GPUCompareFunction, defaulting to "always"

The GPUCompareFunction used when testing fragments against depthStencilAttachment stencil values.

failOp, of type GPUStencilOperation, defaulting to "keep"

The GPUStencilOperation performed if the fragment stencil comparison test described by compare fails.

depthFailOp, of type GPUStencilOperation, defaulting to "keep"

The GPUStencilOperation performed if the fragment depth comparison described by depthCompare fails.

passOp, of type GPUStencilOperation, defaulting to "keep"

The GPUStencilOperation performed if the fragment stencil comparison test described by compare passes.

enum GPUStencilOperation {
    "keep",
    "zero",
    "replace",
    "invert",
    "increment-clamp",
    "decrement-clamp",
    "increment-wrap",
    "decrement-wrap"
};

GPUStencilOperation defines the following operations:

"keep"

Keep the current stencil value.

"zero"

Set the stencil value to 0.

"replace"

Set the stencil value to [[stencil_reference]].

"invert"

Bitwise-invert the current stencil value.

"increment-clamp"

Increments the current stencil value, clamping to the maximum representable value of the depthStencilAttachment's stencil aspect.

"decrement-clamp"

Decrement the current stencil value, clamping to 0.

"increment-wrap"

Increments the current stencil value, wrapping to zero if the value exceeds the maximum representable value of the depthStencilAttachment's stencil aspect.

"decrement-wrap"

Decrement the current stencil value, wrapping to the maximum representable value of the depthStencilAttachment's stencil aspect if the value goes below 0.

10.3.7. Vertex State

enum GPUIndexFormat {
    "uint16",
    "uint32"
};

The index format determines both the data type of index values in a buffer and, when used with strip primitive topologies ("line-strip" or "triangle-strip") also specifies the primitive restart value. The primitive restart value indicates which index value indicates that a new primitive should be started rather than continuing to construct the triangle strip with the prior indexed vertices.

GPUPrimitiveStates that specify a strip primitive topology must specify a stripIndexFormat if they are used for indexed draws so that the primitive restart value that will be used is known at pipeline creation time. GPUPrimitiveStates that specify a list primitive topology will use the index format passed to setIndexBuffer() when doing indexed rendering.

Index format Byte size Primitive restart value
"uint16" 2 0xFFFF
"uint32" 4 0xFFFFFFFF
10.3.7.1. Vertex Formats

The GPUVertexFormat of a vertex attribute indicates how data from a vertex buffer will be interpreted and exposed to the shader. The name of the format specifies the order of components, bits per component, and vertex data type for the component.

Each vertex data type can map to any WGSL scalar type of the same base type, regardless of the bits per component:

Vertex format prefix Vertex data type Compatible WGSL types
uint unsigned int u32
sint signed int i32
unorm unsigned normalized f16, f32
snorm signed normalized
float floating point

The multi-component formats specify the number of components after "x". Mismatches in the number of components between the vertex format and shader type are allowed, with components being either dropped or filled with default values to compensate.

A vertex attribute with a format of "unorm8x2" and byte values [0x7F, 0xFF] can be accessed in the shader with the following types:
Shader type Shader value
f16 0.5h
f32 0.5f
vec2<f16> vec2(0.5h, 1.0h)
vec2<f32> vec2(0.5f, 1.0f)
vec3<f16> vec2(0.5h, 1.0h, 0.0h)
vec3<f32> vec2(0.5f, 1.0f, 0.0f)
vec4<f16> vec2(0.5h, 1.0h, 0.0h, 1.0h)
vec4<f32> vec2(0.5f, 1.0f, 0.0f, 1.0f)

See § 22.3.2 Vertex Processing for additional information about how vertex formats are exposed in the shader.

enum GPUVertexFormat {
    "uint8x2",
    "uint8x4",
    "sint8x2",
    "sint8x4",
    "unorm8x2",
    "unorm8x4",
    "snorm8x2",
    "snorm8x4",
    "uint16x2",
    "uint16x4",
    "sint16x2",
    "sint16x4",
    "unorm16x2",
    "unorm16x4",
    "snorm16x2",
    "snorm16x4",
    "float16x2",
    "float16x4",
    "float32",
    "float32x2",
    "float32x3",
    "float32x4",
    "uint32",
    "uint32x2",
    "uint32x3",
    "uint32x4",
    "sint32",
    "sint32x2",
    "sint32x3",
    "sint32x4"
};
Vertex format Data type Components Byte size Example WGSL type
"uint8x2" unsigned int 2 2 vec2<u32>
"uint8x4" unsigned int 4 4 vec4<u32>
"sint8x2" signed int 2 2 vec2<i32>
"sint8x4" signed int 4 4 vec4<i32>
"unorm8x2" unsigned normalized 2 2 vec2<f32>
"unorm8x4" unsigned normalized 4 4 vec4<f32>
"snorm8x2" signed normalized 2 2 vec2<f32>
"snorm8x4" signed normalized 4 4 vec4<f32>
"uint16x2" unsigned int 2 4 vec2<u32>
"uint16x4" unsigned int 4 8 vec4<u32>
"sint16x2" signed int 2 4 vec2<i32>
"sint16x4" signed int 4 8 vec4<i32>
"unorm16x2" unsigned normalized 2 4 vec2<f32>
"unorm16x4" unsigned normalized 4 8 vec4<f32>
"snorm16x2" signed normalized 2 4 vec2<f32>
"snorm16x4" signed normalized 4 8 vec4<f32>
"float16x2" float 2 4 vec2<f16>
"float16x4" float 4 8 vec4<f16>
"float32" float 1 4 f32
"float32x2" float 2 8 vec2<f32>
"float32x3" float 3 12 vec3<f32>
"float32x4" float 4 16 vec4<f32>
"uint32" unsigned int 1 4 u32
"uint32x2" unsigned int 2 8 vec2<u32>
"uint32x3" unsigned int 3 12 vec3<u32>
"uint32x4" unsigned int 4 16 vec4<u32>
"sint32" signed int 1 4 i32
"sint32x2" signed int 2 8 vec2<i32>
"sint32x3" signed int 3 12 vec3<i32>
"sint32x4" signed int 4 16 vec4<i32>
enum GPUVertexStepMode {
    "vertex",
    "instance"
};

The step mode configures how an address for vertex buffer data is computed, based on the current vertex or instance index:

"vertex"

The address is advanced by arrayStride for each vertex, and reset between instances.

"instance"

The address is advanced by arrayStride for each instance.

dictionary GPUVertexState : GPUProgrammableStage {
    sequence<GPUVertexBufferLayout?> buffers = [];
};

A vertex buffer is, conceptually, a view into buffer memory as an array of structures. arrayStride is the stride, in bytes, between elements of that array. Each element of a vertex buffer is like a structure with a memory layout defined by its attributes, which describe the members of the structure.

Each GPUVertexAttribute describes its format and its offset, in bytes, within the structure.

Each attribute appears as a separate input in a vertex shader, each bound by a numeric location, which is specified by shaderLocation. Every location must be unique within the GPUVertexState.

dictionary GPUVertexBufferLayout {
    required GPUSize64 arrayStride;
    GPUVertexStepMode stepMode = "vertex";
    required sequence<GPUVertexAttribute> attributes;
};
arrayStride, of type GPUSize64

The stride, in bytes, between elements of this array.

stepMode, of type GPUVertexStepMode, defaulting to "vertex"

Whether each element of this array represents per-vertex data or per-instance data

attributes, of type sequence<GPUVertexAttribute>

An array defining the layout of the vertex attributes within each element.

dictionary GPUVertexAttribute {
    required GPUVertexFormat format;
    required GPUSize64 offset;

    required GPUIndex32 shaderLocation;
};
format, of type GPUVertexFormat

The GPUVertexFormat of the attribute.

offset, of type GPUSize64

The offset, in bytes, from the beginning of the element to the data for the attribute.

shaderLocation, of type GPUIndex32

The numeric location associated with this attribute, which will correspond with a "@location" attribute declared in the vertex.module.

validating GPUVertexBufferLayout(device, descriptor, vertexStage) Arguments:

Return true, if and only if, all of the following conditions are satisfied:

validating GPUVertexState(device, descriptor) Arguments:

Return true, if and only if, all of the following conditions are satisfied:

11. Command Buffers

Command buffers are pre-recorded lists of GPU commands that can be submitted to a GPUQueue for execution. Each GPU command represents a task to be performed on the GPU, such as setting state, drawing, copying resources, etc.

11.1. GPUCommandBuffer

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

GPUCommandBuffer has the following internal slots:

[[command_list]], of type list<GPU command>

A list of GPU commands to be executed on the Queue timeline when this command buffer is submitted.

11.1.1. Creation

dictionary GPUCommandBufferDescriptor : GPUObjectDescriptorBase {
};

12. Command Encoding

12.1. GPUCommandsMixin

GPUCommandsMixin defines state common to all interfaces which encode commands. It has no methods.

interface mixin GPUCommandsMixin {
};

GPUCommandsMixin adds the following internal slots to interfaces which include it:

[[state]], of type encoder state

The current state of the encoder, initially set to "open".

[[commands]], of type list<GPU command>

A list of GPU commands to be executed on the Queue timeline when a GPUCommandBuffer containing these commands is submitted.

The encoder state may be one of the following:

"open"

The encoder is available to encode new commands.

"locked"

The encoder cannot be used, because it is locked by a child encoder: it is a GPUCommandEncoder, and a GPURenderPassEncoder or GPUComputePassEncoder is active. The encoder becomes "open" again when the pass is ended.

Any command issued in this state makes the encoder invalid.

"ended"

The encoder has been ended and new commands can no longer be encoded.

Any command issued in this state will generate a validation error.

To Validate the encoder state of GPUCommandsMixin encoder:

If encoder.[[state]] is:

"open"

Return true.

"locked"

Make encoder invalid, and return false.

"ended"

Generate a validation error, and return false.

12.2. GPUCommandEncoder

[Exposed=(Window, DedicatedWorker), SecureContext]
interface GPUCommandEncoder {
    GPURenderPassEncoder beginRenderPass(GPURenderPassDescriptor descriptor);
    GPUComputePassEncoder beginComputePass(optional GPUComputePassDescriptor descriptor = {});

    undefined copyBufferToBuffer(
        GPUBuffer source,
        GPUSize64 sourceOffset,
        GPUBuffer destination,
        GPUSize64 destinationOffset,
        GPUSize64 size);

    undefined copyBufferToTexture(
        GPUImageCopyBuffer source,
        GPUImageCopyTexture destination,
        GPUExtent3D copySize);

    undefined copyTextureToBuffer(
        GPUImageCopyTexture source,
        GPUImageCopyBuffer destination,
        GPUExtent3D copySize);

    undefined copyTextureToTexture(
        GPUImageCopyTexture source,
        GPUImageCopyTexture destination,
        GPUExtent3D copySize);

    undefined clearBuffer(
        GPUBuffer buffer,
        optional GPUSize64 offset = 0,
        optional GPUSize64 size);

    undefined writeTimestamp(GPUQuerySet querySet, GPUSize32 queryIndex);

    undefined resolveQuerySet(
        GPUQuerySet querySet,
        GPUSize32 firstQuery,
        GPUSize32 queryCount,
        GPUBuffer destination,
        GPUSize64 destinationOffset);

    GPUCommandBuffer finish(optional GPUCommandBufferDescriptor descriptor = {});
};
GPUCommandEncoder includes GPUObjectBase;
GPUCommandEncoder includes GPUCommandsMixin;
GPUCommandEncoder includes GPUDebugCommandsMixin;

12.2.1. Creation

dictionary GPUCommandEncoderDescriptor : GPUObjectDescriptorBase {
};
createCommandEncoder(descriptor)

Creates a GPUCommandEncoder.

Called on: GPUDevice this.

Arguments:

Arguments for the GPUDevice.createCommandEncoder(descriptor) method.
Parameter Type Nullable Optional Description
descriptor GPUCommandEncoderDescriptor Description of the GPUCommandEncoder to create.

Returns: GPUCommandEncoder

  1. Let e be a new GPUCommandEncoder object.

  2. Issue the following steps on the Device timeline of this:

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

    Describe remaining createCommandEncoder() validation and algorithm steps.

  3. Return e.

Creating a GPUCommandEncoder, encoding a command to clear a buffer, finishing the encoder to get a GPUCommandBuffer, then submitting it to the GPUQueue.
const commandEncoder = gpuDevice.createCommandEncoder();
commandEncoder.clearBuffer(buffer);
const commandBuffer = commandEncoder.finish();
gpuDevice.queue.submit([commandBuffer]);

12.3. Pass Encoding

beginRenderPass(descriptor)

Begins encoding a render pass described by descriptor.

Called on: GPUCommandEncoder this.

Arguments:

Arguments for the GPUCommandEncoder.beginRenderPass(descriptor) method.
Parameter Type Nullable Optional Description
descriptor GPURenderPassDescriptor Description of the GPURenderPassEncoder to create.

Returns: GPURenderPassEncoder

  1. Let pass be a new GPURenderPassEncoder object.

  2. Issue the following steps on the Device timeline of this:

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

    2. Set this.[[state]] to "locked".

    3. For each non-null colorAttachment in descriptor.colorAttachments:

      1. The texture subresource seen by colorAttachment.view is considered to be used as attachment for the duration of the render pass.

    4. Let depthStencilAttachment be descriptor.depthStencilAttachment.

    5. If depthStencilAttachment is not null:

      1. Let depthStencilView be depthStencilAttachment.view.

      2. If depthStencilAttachment.depthReadOnly and stencilReadOnly are true:

        1. The texture subresources seen by depthStencilView are considered to be used as attachment-read for the duration of the render pass.

          Describe this in terms of a "set of subresources of" algorithm.

      3. Else, the texture subresource seen by depthStencilView is considered to be used as attachment for the duration of the render pass.

      4. Set pass.[[depthReadOnly]] to depthStencilAttachment.depthReadOnly.

      5. Set pass.[[stencilReadOnly]] to depthStencilAttachment.stencilReadOnly.

    6. Set pass.[[layout]] to derive render targets layout from pass(descriptor).

    7. For each timestampWrite in descriptor.timestampWrites,

      1. If timestampWrite.location is "beginning", append a GPU command to this.[[commands]] that writes the GPU’s timestamp value into the timestampWrite.queryIndexth index in timestampWrite.querySet.

      2. Otherwise, if timestampWrite.location is "end", Append timestampWrite to pass.[[endTimestampWrites]].

    8. Set pass.[[drawCount]] to 0.

    9. Set pass.[[maxDrawCount]] to descriptor.maxDrawCount.

    10. Enqueue attachment loads/clears.

  3. Return pass.

specify the behavior of read-only depth/stencil

beginComputePass(descriptor)

Begins encoding a compute pass described by descriptor.

Called on: GPUCommandEncoder this.

Arguments:

Arguments for the GPUCommandEncoder.beginComputePass(descriptor) method.
Parameter Type Nullable Optional Description
descriptor GPUComputePassDescriptor

Returns: GPUComputePassEncoder

  1. Let pass be a new GPUComputePassEncoder object.

  2. Issue the following steps on the Device timeline of this:

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

    2. Set this.[[state]] to "locked".

    3. For each timestampWrite in descriptor.timestampWrites,

      1. If timestampWrite.location is "beginning", append a GPU command to this.[[commands]] that writes the GPU’s timestamp value into the timestampWrite.queryIndexth index in timestampWrite.querySet.

      2. Otherwise, if timestampWrite.location is "end", Append timestampWrite to pass.[[endTimestampWrites]].

  3. Return pass.

12.4. Copy Commands

these dictionary definitions should be inside the image copies section.

12.4.1. GPUImageDataLayout

dictionary GPUImageDataLayout {
    GPUSize64 offset = 0;
    GPUSize32 bytesPerRow;
    GPUSize32 rowsPerImage;
};

A GPUImageDataLayout is a layout of images within some linear memory. It’s used when copying data between a texture and a buffer, or when scheduling a write into a texture from the GPUQueue.

Define images more precisely. In particular, define them as being comprised of texel blocks.

Operations that copy between byte arrays and textures always work with rows of texel blocks, which we’ll call block rows. It’s not possible to update only a part of a texel block.

Texel blocks are tightly packed within each block row in the linear memory layout of an image copy, with each subsequent texel block immediately following the previous texel block, with no padding. This includes copies to/from specific aspects of depth-or-stencil format textures: stencil values are tightly packed in an array of bytes; depth values are tightly packed in an array of the appropriate type ("depth16unorm" or "depth32float").

Define the exact copy semantics, by reference to common algorithms shared by the copy methods.

offset, of type GPUSize64, defaulting to 0

The offset, in bytes, from the beginning of the image data source (such as a GPUImageCopyBuffer.buffer) to the start of the image data within that source.

bytesPerRow, of type GPUSize32

The stride, in bytes, between the beginning of each block row and the subsequent block row.

Required if there are multiple block rows (i.e. the copy height or depth is more than one block).

rowsPerImage, of type GPUSize32

Number of block rows per single image of the texture. rowsPerImage × bytesPerRow is the stride, in bytes, between the beginning of each image of data and the subsequent image.

Required if there are multiple images (i.e. the copy depth is more than one).

12.4.2. GPUImageCopyBuffer

In an image copy operation, GPUImageCopyBuffer defines a GPUBuffer and, together with the copySize, how image data is laid out in the buffer’s memory (see GPUImageDataLayout).

dictionary GPUImageCopyBuffer : GPUImageDataLayout {
    required GPUBuffer buffer;
};
buffer, of type GPUBuffer

A buffer which either contains image data to be copied or will store the image data being copied, depending on the method it is being passed to.

validating GPUImageCopyBuffer

Arguments:

Returns: boolean

Return true if and only if all of the following conditions are satisfied:

12.4.3. GPUImageCopyTexture

In an image copy operation, a GPUImageCopyTexture defines a GPUTexture and, together with the copySize, the sub-region of the texture (spanning one or more contiguous texture subresources at the same mip-map level).

dictionary GPUImageCopyTexture {
    required GPUTexture texture;
    GPUIntegerCoordinate mipLevel = 0;
    GPUOrigin3D origin = {};
    GPUTextureAspect aspect = "all";
};
texture, of type GPUTexture

Texture to copy to/from.

mipLevel, of type GPUIntegerCoordinate, defaulting to 0

Mip-map level of the texture to copy to/from.

origin, of type GPUOrigin3D, defaulting to {}

Defines the origin of the copy - the minimum corner of the texture sub-region to copy to/from. Together with copySize, defines the full copy sub-region.

aspect, of type GPUTextureAspect, defaulting to "all"

Defines which aspects of the texture to copy to/from.

validating GPUImageCopyTexture

Arguments:

Returns: boolean

Let:

Return true if and only if all of the following conditions apply:

Define the copies with 1d and 3d textures. [Issue #gpuweb/gpuweb#69]

12.4.4. GPUImageCopyTextureTagged

WebGPU textures hold raw numeric data, and are not tagged with semantic metadata describing colors. However, copyExternalImageToTexture() copies from sources that describe colors.

A GPUImageCopyTextureTagged is a GPUImageCopyTexture which is additionally tagged with color space/encoding and alpha-premultiplication metadata, so that semantic color data may be preserved during copies. This metadata affects only the semantics of the copyExternalImageToTexture() operation, not the semantics of the destination texture.

dictionary GPUImageCopyTextureTagged : GPUImageCopyTexture {
    PredefinedColorSpace colorSpace = "srgb";
    boolean premultipliedAlpha = false;
};
colorSpace, of type PredefinedColorSpace, defaulting to "srgb"

Describes the color space and encoding used to encode data into the destination texture.

This may result in values outside of the range [0, 1] being written to the target texture, if its format can represent them. Otherwise, the results are clamped to the target texture format’s range.

Note: If colorSpace matches the source image, conversion may not be necessary. See § 3.8.2 Color Space Conversion Elision.

premultipliedAlpha, of type boolean, defaulting to false

Describes whether the data written into the texture should have its RGB channels premultiplied by the alpha channel, or not.

If this option is set to true and the source is also premultiplied, the source RGB values must be preserved even if they exceed their corresponding alpha values.

Note: If premultipliedAlpha matches the source image, conversion may not be necessary. See § 3.8.2 Color Space Conversion Elision.

Define (and test) the encoding of color values into the various encodings allowed by copyExternalImageToTexture().

12.4.5. GPUImageCopyExternalImage

dictionary GPUImageCopyExternalImage {
    required (ImageBitmap or HTMLCanvasElement or OffscreenCanvas) source;
    GPUOrigin2D origin = {};
    boolean flipY = false;
};

GPUImageCopyExternalImage has the following members:

source, of type (ImageBitmap or HTMLCanvasElement or OffscreenCanvas)

The source of the image copy. The copy source data is captured at the moment that copyExternalImageToTexture() is issued.

origin, of type GPUOrigin2D, defaulting to {}

Defines the origin of the copy - the minimum (top-left) corner of the source sub-region to copy from. Together with copySize, defines the full copy sub-region.

flipY, of type boolean, defaulting to false

Describes whether the source image is vertically flipped, or not.

If this option is set to true, the copy is flipped vertically: the bottom row of the source region is copied into the first row of the destination region, and so on. The origin option is still relative to the top-left corner of the source image, increasing downward.

12.4.6. Buffer Copies

copyBufferToBuffer(source, sourceOffset, destination, destinationOffset, size)

Encode a command into the GPUCommandEncoder that copies data from a sub-region of a GPUBuffer to a sub-region of another GPUBuffer.

Called on: GPUCommandEncoder this.

Arguments:

Arguments for the GPUCommandEncoder.copyBufferToBuffer(source, sourceOffset, destination, destinationOffset, size) method.
Parameter Type Nullable Optional Description
source GPUBuffer The GPUBuffer to copy from.
sourceOffset GPUSize64 Offset in bytes into source to begin copying from.
destination GPUBuffer The GPUBuffer to copy to.
destinationOffset GPUSize64 Offset in bytes into destination to place the copied data.
size GPUSize64 Bytes to copy.

Returns: undefined

Issue the following steps on the Device timeline of this.[[device]]:

  1. Validate the encoder state of this. If it returns false, stop.

  2. If any of the following conditions are unsatisfied, make this invalid and stop.

    • source is valid to use with this.

    • destination is valid to use with this.

    • source.usage contains COPY_SRC.

    • destination.usage contains COPY_DST.

    • size is a multiple of 4.

    • sourceOffset is a multiple of 4.

    • destinationOffset is a multiple of 4.

    • (sourceOffset + size) does not overflow a GPUSize64.

    • (destinationOffset + size) does not overflow a GPUSize64.

    • source.size is greater than or equal to (sourceOffset + size).

    • destination.size is greater than or equal to (destinationOffset + size).

    • source and destination are not the same GPUBuffer.

    figure out how to handle overflows in the spec. [Issue #gpuweb/gpuweb#69]

  3. Describe and enqueue the GPU command.

12.4.7. Buffer Fills

clearBuffer(buffer, offset, size)

Encode a command into the GPUCommandEncoder that fills a sub-region of a GPUBuffer with zeros.

Called on: GPUCommandEncoder this.

Arguments:

Arguments for the GPUCommandEncoder.clearBuffer(buffer, offset, size) method.
Parameter Type Nullable Optional Description
buffer GPUBuffer The GPUBuffer to clear.
offset GPUSize64 Offset in bytes into buffer where the sub-region to clear begins.
size GPUSize64 Size in bytes of the sub-region to clear. Defaults to the size of the buffer minus offset.

Returns: undefined

Issue the following steps on the Device timeline of this.[[device]]:

  1. Validate the encoder state of this. If it returns false, stop.

  2. If size is missing, set size to max(0, |buffer|.{{GPUBuffer/size}} - |offset|).

  3. If any of the following conditions are unsatisfied, make this invalid and stop.

    • buffer is valid to use with this.

    • buffer.usage contains COPY_DST.

    • size is a multiple of 4.

    • offset is a multiple of 4.

    • buffer.size is greater than or equal to (offset + size).

12.4.8. Image Copies

WebGPU provides copyBufferToTexture() for buffer-to-texture copies and copyTextureToBuffer() for texture-to-buffer copies, as well as writeTexture() for ArrayBuffer-to-texture writes.

The following definitions and validation rules are used by these methods, as well as copyTextureToTexture().

Does the term "image copy" include copyTextureToTexture?

imageCopyTexture subresource size and validating texture copy range also applies to copyTextureToTexture().

imageCopyTexture subresource size

Arguments:

Returns: GPUExtent3D

The imageCopyTexture subresource size of imageCopyTexture is calculated as follows:

Its width, height and depthOrArrayLayers are the width, height, and depth, respectively, of the physical miplevel-specific texture extent of imageCopyTexture.texture subresource at mipmap level imageCopyTexture.mipLevel.

define this as an algorithm with (texture, mipmapLevel) parameters and use the call syntax instead of referring to the definition by label.

validating linear texture data(layout, byteSize, format, copyExtent)

Arguments:

GPUImageDataLayout layout

Layout of the linear texture data.

GPUSize64 byteSize

Total size of the linear data, in bytes.

GPUTextureFormat format

Format of the texture.

GPUExtent3D copyExtent

Extent of the texture to copy.

  1. Let blockWidth, blockHeight, and blockSize be the texel block width, height, and size of format.

  2. It is assumed that copyExtent.width is a multiple of blockWidth and copyExtent.height is a multiple of blockHeight. Let:

    • widthInBlocks be copyExtent.width ÷ blockWidth.

    • heightInBlocks be copyExtent.height ÷ blockHeight.

    • bytesInLastRow be blockSize × widthInBlocks.

  3. Fail if the following conditions are not satisfied:

  4. Let requiredBytesInCopy be 0.

  5. If copyExtent.depthOrArrayLayers > 1:

    1. Let bytesPerImage be layout.bytesPerRow × layout.rowsPerImage.

    2. Let bytesBeforeLastImage be bytesPerImage × (copyExtent.depthOrArrayLayers − 1).

    3. Add bytesBeforeLastImage to requiredBytesInCopy.

  6. If copyExtent.depthOrArrayLayers > 0:

    1. If heightInBlocks > 1, add layout.bytesPerRow × (heightInBlocks − 1) to requiredBytesInCopy.

    2. If heightInBlocks > 0, add bytesInLastRow to requiredBytesInCopy.

  7. Fail if the following conditions are not satisfied:

    • layout.offset + requiredBytesInCopybyteSize.

validating texture copy range

Arguments:

GPUImageCopyTexture imageCopyTexture

The texture subresource being copied into and copy origin.

GPUExtent3D copySize

The size of the texture.

  1. Let blockWidth be the texel block width of imageCopyTexture.texture.format.

  2. Let blockHeight be the texel block height of imageCopyTexture.texture.format.

  3. Let subresourceSize be the imageCopyTexture subresource size of imageCopyTexture.

  4. Return whether all the conditions below are satisfied:

copyBufferToTexture(source, destination, copySize)

Encode a command into the GPUCommandEncoder that copies data from a sub-region of a GPUBuffer to a sub-region of one or multiple continuous texture subresources.

Called on: GPUCommandEncoder this.

Arguments:

Arguments for the GPUCommandEncoder.copyBufferToTexture(source, destination, copySize) method.
Parameter Type Nullable Optional Description
source GPUImageCopyBuffer Combined with copySize, defines the region of the source buffer.
destination GPUImageCopyTexture Combined with copySize, defines the region of the destination texture subresource.
copySize GPUExtent3D

Returns: undefined

Issue the following steps on the Device timeline of this.[[device]]:

  1. Validate the encoder state of this. If it returns false, stop.

  2. If any of the following conditions are unsatisfied, make this invalid and stop.

copyTextureToBuffer(source, destination, copySize)

Encode a command into the GPUCommandEncoder that copies data from a sub-region of one or multiple continuous texture subresourcesto a sub-region of a GPUBuffer.

Called on: GPUCommandEncoder this.

Arguments:

Arguments for the GPUCommandEncoder.copyTextureToBuffer(source, destination, copySize) method.
Parameter Type Nullable Optional Description
source GPUImageCopyTexture Combined with copySize, defines the region of the source texture subresources.
destination GPUImageCopyBuffer Combined with copySize, defines the region of the destination buffer.
copySize GPUExtent3D

Returns: undefined

Issue the following steps on the Device timeline of this.[[device]]:

  1. Validate the encoder state of this. If it returns false, stop.

  2. If any of the following conditions are unsatisfied, make this invalid and stop.

copyTextureToTexture(source, destination, copySize)

Encode a command into the GPUCommandEncoder that copies data from a sub-region of one or multiple contiguous texture subresources to another sub-region of one or multiple continuous texture subresources.

Called on: GPUCommandEncoder this.

Arguments:

Arguments for the GPUCommandEncoder.copyTextureToTexture(source, destination, copySize) method.
Parameter Type Nullable Optional Description
source GPUImageCopyTexture Combined with copySize, defines the region of the source texture subresources.
destination GPUImageCopyTexture Combined with copySize, defines the region of the destination texture subresources.
copySize GPUExtent3D

Returns: undefined

Issue the following steps on the Device timeline of this.[[device]]:

  1. Validate the encoder state of this. If it returns false, stop.

  2. If any of the following conditions are unsatisfied, make this invalid and stop.

Two GPUTextureFormats format1 and format2 are copy-compatible if:

Once more formats are allowed in viewFormats, consider making two textures copy-compatible when there’s any overlap in the viewFormats. [Issue #gpuweb/gpuweb#2322]

The set of subresources for texture copy(imageCopyTexture, copySize) is the set containing:

12.5. Queries

writeTimestamp(querySet, queryIndex)

Writes a timestamp value into a querySet when all previous commands have completed executing.

Called on: GPUCommandEncoder this.

Arguments:

Arguments for the GPUCommandEncoder.writeTimestamp(querySet, queryIndex) method.
Parameter Type Nullable Optional Description
querySet GPUQuerySet The query set that will store the timestamp values.
queryIndex GPUSize32 The index of the query in the query set.

Returns: undefined

  1. If this.[[device]].[[features]] does not contain "timestamp-query", throw a TypeError.

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

    1. Validate the encoder state of this. If it returns false, stop.

    2. If any of the following conditions are unsatisfied, make this invalid and stop.

    Describe writeTimestamp() algorithm steps.

resolveQuerySet(querySet, firstQuery, queryCount, destination, destinationOffset)

Resolves query results from a GPUQuerySet out into a range of a GPUBuffer.

Called on: GPUCommandEncoder this.

Arguments:

Arguments for the GPUCommandEncoder.resolveQuerySet(querySet, firstQuery, queryCount, destination, destinationOffset) method.
Parameter Type Nullable Optional Description
querySet GPUQuerySet
firstQuery GPUSize32
queryCount GPUSize32
destination GPUBuffer
destinationOffset GPUSize64

Returns: undefined

Issue the following steps on the Device timeline of this.[[device]]:

  1. Validate the encoder state of this. If it returns false, stop.

  2. If any of the following conditions are unsatisfied, make this invalid and stop.

    • querySet is valid to use with this.

    • destination is valid to use with this.

    • destination.usage contains QUERY_RESOLVE.

    • firstQuery is less than the number of queries in querySet.

    • (firstQuery + queryCount) is less than or equal to the number of queries in querySet.

    • destinationOffset is a multiple of 256.

    • destinationOffset + 8 × queryCountdestination.size.

Describe resolveQuerySet() algorithm steps.

12.6. Finalization

A GPUCommandBuffer containing the commands recorded by the GPUCommandEncoder can be created by calling finish(). Once finish() has been called the command encoder can no longer be used.

finish(descriptor)

Completes recording of the commands sequence and returns a corresponding GPUCommandBuffer.

Called on: GPUCommandEncoder this.

Arguments:

Arguments for the GPUCommandEncoder.finish(descriptor) method.
Parameter Type Nullable Optional Description
descriptor GPUCommandBufferDescriptor

Returns: GPUCommandBuffer

  1. Let commandBuffer be a new GPUCommandBuffer.

  2. Issue the following steps on the Device timeline of this:

    1. Let validationSucceeded be true if all of the following requirements are met, and false otherwise.

    2. Set this.[[state]] to "ended".

    3. If validationSucceeded is false, then:

      1. Generate a validation error.

      2. Return a new invalid GPUCommandBuffer.

    4. Set commandBuffer.[[command_list]] to this.[[commands]].

  3. Return commandBuffer.

13. Programmable Passes

interface mixin GPUBindingCommandsMixin {
    undefined setBindGroup(GPUIndex32 index, GPUBindGroup bindGroup,
                      optional sequence<GPUBufferDynamicOffset> dynamicOffsets = []);

    undefined setBindGroup(GPUIndex32 index, GPUBindGroup bindGroup,
                      Uint32Array dynamicOffsetsData,
                      GPUSize64 dynamicOffsetsDataStart,
                      GPUSize32 dynamicOffsetsDataLength);
};

GPUBindingCommandsMixin assumes the presence of GPUObjectBase and GPUCommandsMixin members on the same object. It must only be included by interfaces which also include those mixins.

GPUBindingCommandsMixin has the following internal slots:

[[bind_groups]], of type ordered map<GPUIndex32, GPUBindGroup>

The current GPUBindGroup for each index, initially empty.

[[dynamic_offsets]], of type ordered map<GPUIndex32, sequence<GPUBufferDynamicOffset>>

The current dynamic offsets for each [[bind_groups]] entry, initially empty.

13.1. Bind Groups

setBindGroup(index, bindGroup, dynamicOffsets)

Sets the current GPUBindGroup for the given index.

Called on: GPUBindingCommandsMixin this.

Arguments:

Arguments for the GPUBindingCommandsMixin.setBindGroup(index, bindGroup, dynamicOffsets) method.
Parameter Type Nullable Optional Description
index GPUIndex32 The index to set the bind group at.
bindGroup GPUBindGroup Bind group to use for subsequent render or compute commands.

Resolve bikeshed conflict when using argumentdef with overloaded functions that prevents us from defining dynamicOffsets.

Returns: undefined

Note: dynamicOffsets[i] is used for the i-th dynamic buffer binding in the bind group, when bindings are ordered by GPUBindGroupLayoutEntry.binding. Said differently dynamicOffsets are in the same order as dynamic buffer binding’s GPUBindGroupLayoutEntry.binding.

Issue the following steps on the Device timeline of this.[[device]]:

  1. Validate the encoder state of this. If it returns false, stop.

  2. If any of the following conditions are unsatisfied, make this invalid and stop.

  3. Set this.[[bind_groups]][index] to be bindGroup.

  4. Set this.[[dynamic_offsets]][index] to be a copy of dynamicOffsets.

setBindGroup(index, bindGroup, dynamicOffsetsData, dynamicOffsetsDataStart, dynamicOffsetsDataLength)

Sets the current GPUBindGroup for the given index, specifying dynamic offsets as a subset of a Uint32Array.

Called on: GPUBindingCommandsMixin this.

Arguments:

Arguments for the GPUBindingCommandsMixin.setBindGroup(index, bindGroup, dynamicOffsetsData, dynamicOffsetsDataStart, dynamicOffsetsDataLength) method.
Parameter Type Nullable Optional Description
index GPUIndex32 The index to set the bind group at.
bindGroup GPUBindGroup Bind group to use for subsequent render or compute commands.
dynamicOffsetsData Uint32Array Array containing buffer offsets in bytes for each entry in bindGroup marked as buffer.hasDynamicOffset.
dynamicOffsetsDataStart GPUSize64 Offset in elements into dynamicOffsetsData where the buffer offset data begins.
dynamicOffsetsDataLength GPUSize32 Number of buffer offsets to read from dynamicOffsetsData.

Returns: undefined

  1. If any of the following requirements are unmet, throw a RangeError and stop.

    • dynamicOffsetsDataStart must be ≥ 0.

    • dynamicOffsetsDataStart + dynamicOffsetsDataLength must be ≤ dynamicOffsetsData.length.

  2. Let dynamicOffsets be a list containing the range, starting at index dynamicOffsetsDataStart, of dynamicOffsetsDataLength elements of a copy of dynamicOffsetsData.

  3. Call this.setBindGroup(index, bindGroup, dynamicOffsets).

To Iterate over each dynamic binding offset in a given GPUBindGroup bindGroup with a given list of steps to be executed for each dynamic offset:
  1. Let dynamicOffsetIndex be 0.

  2. Let layout be bindGroup.[[layout]].

  3. For each GPUBindGroupEntry entry in bindGroup.[[entries]] ordered in increasing values of entry.binding:

    1. Let bindingDescriptor be the GPUBindGroupLayoutEntry at layout.[[entryMap]][entry.binding]:

    2. If bindingDescriptor.buffer is not undefined and bindingDescriptor.buffer.hasDynamicOffset is true:

      1. Let bufferBinding be entry.resource.

      2. Let bufferLayout be bindingDescriptor.buffer.

      3. Call steps with bufferBinding, bufferLayout, and dynamicOffsetIndex.

      4. Let dynamicOffsetIndex be dynamicOffsetIndex + 1

Validate encoder bind groups(encoder, pipeline)

Arguments:

GPUBindingCommandsMixin encoder

Encoder whose bind groups are being validated.

GPUPipelineBase pipeline

Pipeline to validate encoders bind groups are compatible with.

  1. If any of the following conditions are unsatisfied, return false:

    Add validation that, for buffer bindings that weren’t prevalidated with minBindingSize, the binding ranges are large enough for the shader’s minimum binding size requirements.

  2. Encoder bind groups alias a writable resource(encoder, pipeline) must be false.

    Determine what happens when an application violates this. Is it a validation error, one of multiple possible behaviors, or do we just remove this restriction entirely and allow writable bindings to alias with undefined results? [Issue #gpuweb/gpuweb#1842]

Otherwise return true.

Encoder bind groups alias a writable resource(encoder, pipeline) if any writable buffer binding range overlaps with any other binding range of the same buffer, or any writable texture binding overlaps in texture subresources with any other texture binding (which may use the same or a different GPUTextureView object).

Arguments:

GPUBindingCommandsMixin encoder

Encoder whose bind groups are being validated.

GPUPipelineBase pipeline

Pipeline to validate encoders bind groups are compatible with.

  1. For each stage in [VERTEX, FRAGMENT, COMPUTE]:

    1. Let bufferBindings be a list of (GPUBufferBinding, boolean) pairs, where the latter indicates whether the resource was used as writable.

    2. Let textureViews be a list of (GPUTextureView, boolean) pairs, where the latter indicates whether the resource was used as writable.

    3. For each pair of (GPUIndex32 index, GPUBindGroupLayout bindGroupLayout) in pipeline.[[layout]].[[bindGroupLayouts]]:

      1. Let bindGroupEntries be encoder.[[bind_groups]][index].entries.

      2. Let bindGroupLayoutEntries be bindGroupLayout.[[descriptor]].entries.

      3. For each GPUBindGroupEntry bindGroupLayoutEntry in bindGroupLayoutEntries for which bindGroupLayoutEntry.visibility contains stage:

        1. Let bindGroupEntry be the GPUBindGroupEntry in bindGroupEntries for which bindGroupEntry.binding is equal to bindGroupLayoutEntry.binding.

        2. If bindGroupEntry.resource is a GPUBufferBinding:

          1. Let GPUBufferBinding resource be bindGroupEntry.resource.

          2. Let resourceWritable be (bindGroupLayoutEntry.buffer.type == "storage").

          3. For each pair (GPUBufferBinding pastResource, boolean pastResourceWritable) in bufferBindings:

            1. If (resourceWritable or pastResourceWritable) is true, and pastResource and resource are buffer-binding-aliasing, return true.

          4. Append ([resource], resourceWritable) to bufferBindings.

          Otherwise, if bindGroupEntry.resource is a GPUTextureView:

          1. Let GPUTextureView resource be bindGroupEntry.resource.

          2. Let resourceWritable be (bindGroupLayoutEntry.storageTexture.access == "write-only").

          3. If bindGroupLayoutEntry.storageTexture is null, continue.

          4. For each pair (GPUTextureView pastResource, boolean pastResourceWritable) in textureViews,

            1. If (resourceWritable or pastResourceWritable) is true, and pastResource and resource is texture-view-aliasing, return true.

          5. Append ([resource], resourceWritable) to textureViews.

          Otherwise, continue.

  2. Return false.

14. Debug Markers

GPUDebugCommandsMixin provides methods to apply debug labels to groups of commands or insert a single label into the command sequence.

Debug groups can be nested to create a hierarchy of labeled commands, and must be well-balanced.

Like object labels, these labels have no required behavior, but may be shown in error messages and browser developer tools, and may be passed to native API backends.

interface mixin GPUDebugCommandsMixin {
    undefined pushDebugGroup(USVString groupLabel);
    undefined popDebugGroup();
    undefined insertDebugMarker(USVString markerLabel);
};

GPUDebugCommandsMixin assumes the presence of GPUObjectBase and GPUCommandsMixin members on the same object. It must only be included by interfaces which also include those mixins.

GPUDebugCommandsMixin adds the following internal slots to interfaces which include it:

[[debug_group_stack]], of type stack<USVString>

A stack of active debug group labels.

GPUDebugCommandsMixin adds the following methods to interfaces which include it:

pushDebugGroup(groupLabel)

Begins a labeled debug group containing subsequent commands.

Called on: GPUDebugCommandsMixin this.

Arguments:

Arguments for the GPUDebugCommandsMixin.pushDebugGroup(groupLabel) method.
Parameter Type Nullable Optional Description
groupLabel USVString The label for the command group.

Returns: undefined

Issue the following steps on the Device timeline of this.[[device]]:

  1. Validate the encoder state of this. If it returns false, stop.

  2. Push groupLabel onto this.[[debug_group_stack]].

popDebugGroup()

Ends the labeled debug group most recently started by pushDebugGroup().

Called on: GPUDebugCommandsMixin this.

Returns: undefined

Issue the following steps on the Device timeline of this.[[device]]:

  1. Validate the encoder state of this. If it returns false, stop.

  2. If any of the following requirements are unmet, make this invalid, and stop.

  3. Pop an entry off of this.[[debug_group_stack]].

insertDebugMarker(markerLabel)

Marks a point in a stream of commands with a label.

Called on: GPUDebugCommandsMixin this.

Arguments:

Arguments for the GPUDebugCommandsMixin.insertDebugMarker(markerLabel) method.
Parameter Type Nullable Optional Description
markerLabel USVString The label to insert.

Returns: undefined

Issue the following steps on the Device timeline of this.[[device]]:

  1. Validate the encoder state of this. If it returns false, stop.

15. Compute Passes

15.1. GPUComputePassEncoder

[Exposed=(Window, DedicatedWorker), SecureContext]
interface GPUComputePassEncoder {
    undefined setPipeline(GPUComputePipeline pipeline);
    undefined dispatchWorkgroups(GPUSize32 workgroupCountX, optional GPUSize32 workgroupCountY = 1, optional GPUSize32 workgroupCountZ = 1);
    undefined dispatchWorkgroupsIndirect(GPUBuffer indirectBuffer, GPUSize64 indirectOffset);

    undefined end();
};
GPUComputePassEncoder includes GPUObjectBase;
GPUComputePassEncoder includes GPUCommandsMixin;
GPUComputePassEncoder includes GPUDebugCommandsMixin;
GPUComputePassEncoder includes GPUBindingCommandsMixin;

GPUComputePassEncoder has the following internal slots:

[[command_encoder]], of type GPUCommandEncoder, readonly

The GPUCommandEncoder that created this compute pass encoder.

[[pipeline]], of type GPUComputePipeline

The current GPUComputePipeline, initially null.

[[endTimestampWrites]], of type GPUComputePassTimestampWrites

The timestamp attachments which need to be executed when the pass ends.

15.1.1. Creation

enum GPUComputePassTimestampLocation {
    "beginning",
    "end"
};

dictionary GPUComputePassTimestampWrite {
    required GPUQuerySet querySet;
    required GPUSize32 queryIndex;
    required GPUComputePassTimestampLocation location;
};

typedef sequence<GPUComputePassTimestampWrite> GPUComputePassTimestampWrites;

dictionary GPUComputePassDescriptor : GPUObjectDescriptorBase {
    GPUComputePassTimestampWrites timestampWrites = [];
};
timestampWrites, of type GPUComputePassTimestampWrites, defaulting to []

A sequence of GPUComputePassTimestampWrite values define where and when timestamp values will be written for this pass.

Valid Usage

Given a GPUComputePassDescriptor this the following validation rules apply:

  1. No two entries in this.timestampWrites have the same location.

  2. For each timestampWrite in this.timestampWrites:

    1. timestampWrite.querySet.type is "timestamp".

    2. timestampWrite.queryIndex < timestampWrite.querySet.count.

15.1.2. Dispatch

setPipeline(pipeline)

Sets the current GPUComputePipeline.

Called on: GPUComputePassEncoder this.

Arguments:

Arguments for the GPUComputePassEncoder.setPipeline(pipeline) method.
Parameter Type Nullable Optional Description
pipeline GPUComputePipeline The compute pipeline to use for subsequent dispatch commands.

Returns: undefined

Issue the following steps on the Device timeline of this.[[device]]:

  1. Validate the encoder state of this. If it returns false, stop.

  2. If any of the following conditions are unsatisfied, make this invalid and stop.

  3. Set this.[[pipeline]] to be pipeline.

dispatchWorkgroups(workgroupCountX, workgroupCountY, workgroupCountZ)

Dispatch work to be performed with the current GPUComputePipeline. See § 22.2 Computing for the detailed specification.

Called on: GPUComputePassEncoder this.

Arguments:

Arguments for the GPUComputePassEncoder.dispatchWorkgroups(workgroupCountX, workgroupCountY, workgroupCountZ) method.
Parameter Type Nullable Optional Description
workgroupCountX GPUSize32 X dimension of the grid of workgroups to dispatch.
workgroupCountY GPUSize32 Y dimension of the grid of workgroups to dispatch.
workgroupCountZ GPUSize32 Z dimension of the grid of workgroups to dispatch.
Note: The x, y, and z values passed to dispatchWorkgroups() and dispatchWorkgroupsIndirect() are the number of workgroups to dispatch for each dimension, not the number of shader invocations to perform across each dimension. This matches the behavior of modern native GPU APIs, but differs from the behavior of OpenCL.

This means that if a GPUShaderModule defines an entry point with @workgroup_size(4, 4), and work is dispatched to it with the call computePass.dispatchWorkgroups(8, 8); the entry point will be invoked 1024 times total: Dispatching a 4x4 workgroup 8 times along both the X and Y axes. (4*4*8*8=1024)

Returns: undefined

Issue the following steps on the Device timeline of this.[[device]]:

  1. Validate the encoder state of this. If it returns false, stop.

  2. If any of the following conditions are unsatisfied, make this invalid and stop.

  3. Let passState be a snapshot of this’s current state.

  4. Append a GPU command to this.[[commands]] executing the following queue timeline steps:

    1. Dispatch a grid of workgroups with dimensions [workgroupCountX, workgroupCountY, workgroupCountZ] with passState.[[pipeline]] using passState.[[bind_groups]].

dispatchWorkgroupsIndirect(indirectBuffer, indirectOffset)

Dispatch work to be performed with the current GPUComputePipeline using parameters read from a GPUBuffer. See § 22.2 Computing for the detailed specification.

The indirect dispatch parameters encoded in the buffer must be a tightly packed block of three 32-bit unsigned integer values (12 bytes total), given in the same order as the arguments for dispatchWorkgroups(). For example:

let dispatchIndirectParameters = new Uint32Array(3);
dispatchIndirectParameters[0] = workgroupCountX;
dispatchIndirectParameters[1] = workgroupCountY;
dispatchIndirectParameters[2] = workgroupCountZ;
Called on: GPUComputePassEncoder this.

Arguments:

Arguments for the GPUComputePassEncoder.dispatchWorkgroupsIndirect(indirectBuffer, indirectOffset) method.
Parameter Type Nullable Optional Description
indirectBuffer GPUBuffer Buffer containing the indirect dispatch parameters.
indirectOffset GPUSize64 Offset in bytes into indirectBuffer where the dispatch data begins.

Returns: undefined

Issue the following steps on the Device timeline of this.[[device]]:

  1. Validate the encoder state of this. If it returns false, stop.

  2. If any of the following conditions are unsatisfied, make this invalid and stop.

  3. Add indirectBuffer to the usage scope as INDIRECT.

If any of the dispatch parameters (x, y, or z) is greater than this.device.limits.maxComputeWorkgroupsPerDimension, no workgroups will be dispatched.

15.1.3. Finalization

The compute pass encoder can be ended by calling end() once the user has finished recording commands for the pass. Once end() has been called the compute pass encoder can no longer be used.

end()

Completes recording of the compute pass commands sequence.

Called on: GPUComputePassEncoder this.

Returns: undefined

Issue the following steps on the Device timeline of this:

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

  2. Let parentEncoder be this.[[command_encoder]].

  3. Set this.[[state]] to "ended".

  4. Assert: parentEncoder.[[state]] is "locked".

  5. Set parentEncoder.[[state]] to "open".

  6. If any of the following requirements are unmet, make parentEncoder invalid and stop.

  7. Extend parentEncoder.[[commands]] with this.[[commands]].

  8. For each timestampWrite in this.[[endTimestampWrites]]:

    1. Assert: timestampWrite.location is "end".

    2. Append a GPU command to parentEncoder.[[commands]] that writes the GPU’s timestamp value into the timestampWrite.queryIndexth index in timestampWrite.querySet.

16. Render Passes

16.1. GPURenderPassEncoder

[Exposed=(Window, DedicatedWorker), SecureContext]
interface GPURenderPassEncoder {
    undefined setViewport(float x, float y,
                     float width, float height,
                     float minDepth, float maxDepth);

    undefined setScissorRect(GPUIntegerCoordinate x, GPUIntegerCoordinate y,
                        GPUIntegerCoordinate width, GPUIntegerCoordinate height);

    undefined setBlendConstant(GPUColor color);
    undefined setStencilReference(GPUStencilValue reference);

    undefined beginOcclusionQuery(GPUSize32 queryIndex);
    undefined endOcclusionQuery();

    undefined executeBundles(sequence<GPURenderBundle> bundles);
    undefined end();
};
GPURenderPassEncoder includes GPUObjectBase;
GPURenderPassEncoder includes GPUCommandsMixin;
GPURenderPassEncoder includes GPUDebugCommandsMixin;
GPURenderPassEncoder includes GPUBindingCommandsMixin;
GPURenderPassEncoder includes GPURenderCommandsMixin;

GPURenderPassEncoder has the following internal slots:

[[command_encoder]], of type GPUCommandEncoder, readonly

The GPUCommandEncoder that created this render pass encoder.

[[attachment_size]]

Set to the following extents:

  • width, height = the dimensions of the pass’s render attachments

[[occlusion_query_set]], of type GPUQuerySet.

The GPUQuerySet to store occlusion query results for the pass, which is initialized with GPURenderPassDescriptor.occlusionQuerySet at pass creation time.

[[occlusion_query_active]], of type boolean.

Whether the pass’s [[occlusion_query_set]] is being written.

[[viewport]]

Current viewport rectangle and depth range.

[[blend_constant]]

Current blend constant value, initially [0, 0, 0, 0].

[[stencil_reference]]

Current stencil reference value, initially 0.

[[endTimestampWrites]], of type GPURenderPassTimestampWrites

The timestamp attachments which need to be executed when the pass ends.

[[maxDrawCount]] of type GPUSize64.

The maximum number of draws allowed in this pass.

When a GPURenderPassEncoder is created, it has the following default state:

16.1.1. Creation

enum GPURenderPassTimestampLocation {
    "beginning",
    "end"
};

dictionary GPURenderPassTimestampWrite {
    required GPUQuerySet querySet;
    required GPUSize32 queryIndex;
    required GPURenderPassTimestampLocation location;
};

typedef sequence<GPURenderPassTimestampWrite> GPURenderPassTimestampWrites;

dictionary GPURenderPassDescriptor : GPUObjectDescriptorBase {
    required sequence<GPURenderPassColorAttachment?> colorAttachments;
    GPURenderPassDepthStencilAttachment depthStencilAttachment;
    GPUQuerySet occlusionQuerySet;
    GPURenderPassTimestampWrites timestampWrites = [];
    GPUSize64 maxDrawCount = 50000000;
};
colorAttachments, of type sequence<GPURenderPassColorAttachment?>

The set of GPURenderPassColorAttachment values in this sequence defines which color attachments will be output to when executing this render pass.

Due to usage compatibility, no color attachment may alias another attachment or any resource used inside the render pass.

depthStencilAttachment, of type GPURenderPassDepthStencilAttachment

The GPURenderPassDepthStencilAttachment value that defines the depth/stencil attachment that will be output to and tested against when executing this render pass.

Due to usage compatibility, no writable depth/stencil attachment may alias another attachment or any resource used inside the render pass.

occlusionQuerySet, of type GPUQuerySet

The GPUQuerySet value defines where the occlusion query results will be stored for this pass.

timestampWrites, of type GPURenderPassTimestampWrites, defaulting to []

A sequence of GPURenderPassTimestampWrite values defines where and when timestamp values will be written for this pass.

maxDrawCount, of type GPUSize64, defaulting to 50000000

The maximum number of draw calls that will be done in the render pass. Used by some implementations to size work injected before the render pass. Keeping the default value is a good default, unless it is known that more draw calls will be done.

Valid Usage

Given a GPUDevice device and GPURenderPassDescriptor this, the following validation rules apply:

  1. this.colorAttachments.length must be less than or equal to device.[[limits]].maxColorAttachments.

  2. If this.colorAttachments has all values be null (or the sequence is empty):

    1. this.depthStencilAttachment must not be null.

  3. For each non-null colorAttachment in this.colorAttachments:

    1. colorAttachment must meet the GPURenderPassColorAttachment Valid Usage rules.

  4. If this.depthStencilAttachment is not null:

    1. this.depthStencilAttachment must meet the GPURenderPassDepthStencilAttachment Valid Usage rules.

  5. All views in non-null members of this.colorAttachments, and this.depthStencilAttachment.view if present, must have equal sampleCounts.

  6. For each view in non-null members of this.colorAttachments and this.depthStencilAttachment.view, if present, the [[renderExtent]] must match.

  7. If this.occlusionQuerySet is not null:

    1. this.occlusionQuerySet.type must be occlusion.

  8. No two entries in this.timestampWrites have the same location.

  9. For each timestampWrite in this.timestampWrites:

    1. timestampWrite.querySet.type is "timestamp".

    2. timestampWrite.queryIndex < timestampWrite.querySet.count.

    3. timestampWrite.queryIndex is written at most once in the same timestampWrite.querySet in this render pass.

support for no attachments [Issue #gpuweb/gpuweb#503]

For a given GPURenderPassDescriptor value descriptor, the syntax:

make it a define once we reference to this from other places

Note: the Valid Usage guarantees that all of the render extents of the attachments are the same, so we can take any of them, assuming the descriptor is valid.

16.1.1.1. Color Attachments
dictionary GPURenderPassColorAttachment {
    required GPUTextureView view;
    GPUTextureView resolveTarget;

    GPUColor clearValue;
    required GPULoadOp loadOp;
    required GPUStoreOp storeOp;
};
view, of type GPUTextureView

A GPUTextureView describing the texture subresource that will be output to for this color attachment.

resolveTarget, of type GPUTextureView

A GPUTextureView describing the texture subresource that will receive the resolved output for this color attachment if view is multisampled.

clearValue, of type GPUColor

Indicates the value to clear view to prior to executing the render pass. If not provided defaults to {r: 0, g: 0, b: 0, a: 0}. Ignored if loadOp is not "clear".

The members of clearValue are all double values, so they will first be converted to the fully qualified format type of view before being set as the clear value of view.

Let colorAttachmentFormat be view.[[descriptor]].format.

colorAttachmentFormat has up to four components: r, g, b, and a, each component containing one scalar value.

For each componentType of colorAttachmentFormat and corresponding component scalar value value in clearValue:

  1. If componentType is a:

    floating-point type or normalized type

    Convert value to an IDL value of type unrestricted float (f32).

    signed integer type

    Convert value to an IDL value of type long long (i32).

    unsigned integer type

    Convert value to an IDL value of type unsigned long long (u32).

  2. Convert value to componentType using the same conversion rules as the [#Output Merging] step, and return the result.

In other words, the value written will be as if it was written by a WGSL shader that outputs the value represented as WGSL’s f32, i32, or u32, according to its type.

For non-integer types, the exact choice of value is implementation-defined. For normalized types, this results in clamping to the range of the type.

loadOp, of type GPULoadOp

Indicates the load operation to perform on view prior to executing the render pass.

Note: It is recommended to prefer clearing; see "clear" for details.

storeOp, of type GPUStoreOp

The store operation to perform on view after executing the render pass.

GPURenderPassColorAttachment Valid Usage

Given a GPURenderPassColorAttachment this:

  1. Let renderViewDescriptor be this.view.[[descriptor]].

  2. Let resolveViewDescriptor be this.resolveTarget.[[descriptor]].

  3. Let renderTexture be this.view.[[texture]].

  4. Let resolveTexture be this.resolveTarget.[[texture]].

The following validation rules apply:

A GPUTextureView view is a renderable texture view if the following requirements are met:

where descriptor is view.[[descriptor]].

16.1.1.2. Depth/Stencil Attachments
dictionary GPURenderPassDepthStencilAttachment {
    required GPUTextureView view;

    float depthClearValue = 0;
    GPULoadOp depthLoadOp;
    GPUStoreOp depthStoreOp;
    boolean depthReadOnly = false;

    GPUStencilValue stencilClearValue = 0;
    GPULoadOp stencilLoadOp;
    GPUStoreOp stencilStoreOp;
    boolean stencilReadOnly = false;
};
view, of type GPUTextureView

A GPUTextureView describing the texture subresource that will be output to and read from for this depth/stencil attachment.

depthClearValue, of type float, defaulting to 0

Indicates the value to clear view's depth component to prior to executing the render pass. Ignored if depthLoadOp is not "clear". Must be between 0.0 and 1.0, inclusive.

depthLoadOp, of type GPULoadOp

Indicates the load operation to perform on view's depth component prior to executing the render pass.

Note: It is recommended to prefer clearing; see "clear" for details.

depthStoreOp, of type GPUStoreOp

The store operation to perform on view's depth component after executing the render pass.

Note: It is recommended to prefer a clear-value; see "load".

depthReadOnly, of type boolean, defaulting to false

Indicates that the depth component of view is read only.

stencilClearValue, of type GPUStencilValue, defaulting to 0

Indicates the value to clear view's stencil component to prior to executing the render pass. Ignored if stencilLoadOp is not "clear".

The value will be converted to the type of the stencil aspect of view by taking the same number of LSBs as the number of bits in the stencil aspect of one texel block of view.

stencilLoadOp, of type GPULoadOp

Indicates the load operation to perform on view's stencil component prior to executing the render pass.

Note: It is recommended to prefer clearing; see "clear" for details.

stencilStoreOp, of type GPUStoreOp

The store operation to perform on view's stencil component after executing the render pass.

stencilReadOnly, of type boolean, defaulting to false

Indicates that the stencil component of view is read only.

GPURenderPassDepthStencilAttachment Valid Usage

Given a GPURenderPassDepthStencilAttachment this, the following validation rules apply:

16.1.1.3. Load & Store Operations
enum GPULoadOp {
    "load",
    "clear"
};
"load"

Loads the existing value for this attachment into the render pass.

"clear"

Loads a clear value for this attachment into the render pass.

Note: On some GPU hardware (primarily mobile), "clear" is significantly cheaper because it avoids loading data from main memory into tile-local memory. On other GPU hardware, there isn’t a significant difference. As a result, it is recommended to use "clear" rather than "load" in cases where the initial value doesn’t matter (e.g. the render target will be cleared using a skybox).

enum GPUStoreOp {
    "store",
    "discard"
};
"store"

Stores the resulting value of the render pass for this attachment.

"discard"

Discards the resulting value of the render pass for this attachment.

16.1.1.4. Render Pass Layout

GPURenderPassLayout contains the layout of the render targets for the current pass, which determines the compatibility of the pass with render pipelines.

dictionary GPURenderPassLayout: GPUObjectDescriptorBase {
    required sequence<GPUTextureFormat?> colorFormats;
    GPUTextureFormat depthStencilFormat;
    GPUSize32 sampleCount = 1;
};
derive render targets layout from pass

Arguments:

Returns: GPURenderPassLayout

  1. Let layout be a new GPURenderPassLayout object.

  2. For each colorAttachment in descriptor.colorAttachments:

    1. If colorAttachment is not null:

      1. Set layout.sampleCount to colorAttachment.view.[[texture]].sampleCount.

      2. Append colorAttachment.view.[[descriptor]].format to layout.colorFormats.

    2. Otherwise:

      1. Append null to layout.colorFormats.

  3. Let depthStencilAttachment be descriptor.depthStencilAttachment.

  4. If depthStencilAttachment is not null:

    1. Let view be depthStencilAttachment.view.

    2. Set layout.sampleCount to view.[[texture]].sampleCount.

    3. Set layout.depthStencilFormat to view.[[descriptor]].format.

  5. Return layout.

derive render targets layout from pipeline

Arguments:

Returns: GPURenderPassLayout

  1. Let layout be a new GPURenderPassLayout object.

  2. Set layout.sampleCount to descriptor.multisample.count.

  3. If descriptor.depthStencil is not null:

    1. Set layout.depthStencilFormat to descriptor.depthStencil.format.

  4. If descriptor.fragment is not null:

    1. For each colorTarget in descriptor.fragment.targets:

      1. Append colorTarget.format to layout.colorFormats if colorTarget is not null, or append null otherwise.

  5. Return layout.

16.1.2. Finalization

The render pass encoder can be ended by calling end() once the user has finished recording commands for the pass. Once end() has been called the render pass encoder can no longer be used.

end()

Completes recording of the render pass commands sequence.

Called on: GPURenderPassEncoder this.

Returns: undefined

Issue the following steps on the Device timeline of this:

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

  2. Let parentEncoder be this.[[command_encoder]].

  3. Set this.[[state]] to "ended".

  4. Assert: parentEncoder.[[state]] is "locked".

  5. Set parentEncoder.[[state]] to "open".

  6. If any of the following requirements are unmet, make this invalid and stop.

  7. Extend parentEncoder.[[commands]] with this.[[commands]].

  8. For each timestampWrite in this.[[endTimestampWrites]]:

    1. Assert: timestampWrite.location is "end".

    2. Append a GPU command to parentEncoder.[[commands]] that writes the GPU’s timestamp value into the timestampWrite.queryIndexth index in timestampWrite.querySet.

  9. Enqueue the attachment stores/discards.

16.2. GPURenderCommandsMixin

GPURenderCommandsMixin defines rendering commands common to GPURenderPassEncoder and GPURenderBundleEncoder.

interface mixin GPURenderCommandsMixin {
    undefined setPipeline(GPURenderPipeline pipeline);

    undefined setIndexBuffer(GPUBuffer buffer, GPUIndexFormat indexFormat, optional GPUSize64 offset = 0, optional GPUSize64 size);
    undefined setVertexBuffer(GPUIndex32 slot, GPUBuffer buffer, optional GPUSize64 offset = 0, optional GPUSize64 size);

    undefined draw(GPUSize32 vertexCount, optional GPUSize32 instanceCount = 1,
              optional GPUSize32 firstVertex = 0, optional GPUSize32 firstInstance = 0);
    undefined drawIndexed(GPUSize32 indexCount, optional GPUSize32 instanceCount = 1,
                     optional GPUSize32 firstIndex = 0,
                     optional GPUSignedOffset32 baseVertex = 0,
                     optional GPUSize32 firstInstance = 0);

    undefined drawIndirect(GPUBuffer indirectBuffer, GPUSize64 indirectOffset);
    undefined drawIndexedIndirect(GPUBuffer indirectBuffer, GPUSize64 indirectOffset);
};

GPURenderCommandsMixin assumes the presence of GPUObjectBase and GPUCommandsMixin members on the same object. It must only be included by interfaces which also include those mixins.

GPURenderCommandsMixin has the following internal slots:

[[layout]], of type GPURenderPassLayout

The layout of the render pass.

[[depthReadOnly]], of type boolean

If true, indicates that the depth component is not modified.

[[stencilReadOnly]], of type boolean

If true, indicates that the stencil component is not modified.

[[pipeline]], of type GPURenderPipeline

The current GPURenderPipeline, initially null.

[[index_buffer]], of type GPUBuffer

The current buffer to read index data from, initially null.

[[index_format]], of type GPUIndexFormat

The format of the index data in [[index_buffer]].

[[index_buffer_size]], of type GPUSize64

The size in bytes of the section of [[index_buffer]] currently set, initially 0.

[[vertex_buffers]], of type ordered map<slot, GPUBuffer>

The current GPUBuffers to read vertex data from for each slot, initially empty.

[[vertex_buffer_sizes]], of type ordered map<slot, GPUSize64>

The size in bytes of the section of GPUBuffer currently set for each slot, initially empty.

[[drawCount]], of type GPUSize64

The number of draw commands recorded in this encoder.

16.2.1. Drawing

setPipeline(pipeline)

Sets the current GPURenderPipeline.

Called on: GPURenderCommandsMixin this.

Arguments:

Arguments for the GPURenderCommandsMixin.setPipeline(pipeline) method.
Parameter Type Nullable Optional Description
pipeline GPURenderPipeline The render pipeline to use for subsequent drawing commands.

Returns: undefined

Issue the following steps on the Device timeline of this.[[device]]:

  1. Validate the encoder state of this. If it returns false, stop.

  2. Let pipelineTargetsLayout be derive render targets layout from pipeline(pipeline.[[descriptor]]).

  3. If any of the following conditions are unsatisfied, make this invalid and stop.

  4. Set this.[[pipeline]] to be pipeline.

define what "equals" means for GPURenderPassLayout here.

setIndexBuffer(buffer, indexFormat, offset, size)

Sets the current index buffer.

Called on: GPURenderCommandsMixin this.

Arguments:

Arguments for the GPURenderCommandsMixin.setIndexBuffer(buffer, indexFormat, offset, size) method.
Parameter Type Nullable Optional Description
buffer GPUBuffer Buffer containing index data to use for subsequent drawing commands.
indexFormat GPUIndexFormat Format of the index data contained in buffer.
offset GPUSize64 Offset in bytes into buffer where the index data begins. Defaults to 0.
size GPUSize64 Size in bytes of the index data in buffer. Defaults to the size of the buffer minus the offset.

Returns: undefined

Issue the following steps on the Device timeline of this.[[device]]:

  1. Validate the encoder state of this. If it returns false, stop.

  2. If size is missing, set size to max(0, buffer.size - offset).

  3. If any of the following conditions are unsatisfied, make this invalid and stop.

  4. Add buffer to the usage scope as input.

  5. Set this.[[index_buffer]] to be buffer.

  6. Set this.[[index_format]] to be indexFormat.

  7. Set this.[[index_buffer_size]] to be size.

setVertexBuffer(slot, buffer, offset, size)

Sets the current vertex buffer for the given slot.

Called on: GPURenderCommandsMixin this.

Arguments:

Arguments for the GPURenderCommandsMixin.setVertexBuffer(slot, buffer, offset, size) method.
Parameter Type Nullable Optional Description
slot GPUIndex32 The vertex buffer slot to set the vertex buffer for.
buffer GPUBuffer Buffer containing vertex data to use for subsequent drawing commands.
offset GPUSize64 Offset in bytes into buffer where the vertex data begins. Defaults to 0.
size GPUSize64 Size in bytes of the vertex data in buffer. Defaults to the size of the buffer minus the offset.

Returns: undefined

Issue the following steps on the Device timeline of this.[[device]]:

  1. Validate the encoder state of this. If it returns false, stop.

  2. If size is missing, set size to max(0, buffer.size - offset).

  3. If any of the following conditions are unsatisfied, make this invalid and stop.

  4. Add buffer to the usage scope as input.

  5. Set this.[[vertex_buffers]][slot] to be buffer.

  6. Set this.[[vertex_buffer_sizes]][slot] to be size.

draw(vertexCount, instanceCount, firstVertex, firstInstance)

Draws primitives. See § 22.3 Rendering for the detailed specification.

Called on: GPURenderCommandsMixin this.

Arguments:

Arguments for the GPURenderCommandsMixin.draw(vertexCount, instanceCount, firstVertex, firstInstance) method.
Parameter Type Nullable Optional Description
vertexCount GPUSize32 The number of vertices to draw.
instanceCount GPUSize32 The number of instances to draw.
firstVertex GPUSize32 Offset into the vertex buffers, in vertices, to begin drawing from.
firstInstance GPUSize32 First instance to draw.

Returns: undefined

Issue the following steps on the Device timeline of this.[[device]]:

  1. Validate the encoder state of this. If it returns false, stop.

  2. If any of the following conditions are unsatisfied, make this invalid and stop.

  3. Increment this.[[drawCount]] by 1.

drawIndexed(indexCount, instanceCount, firstIndex, baseVertex, firstInstance)

Draws indexed primitives. See § 22.3 Rendering for the detailed specification.

Called on: GPURenderCommandsMixin this.

Arguments:

Arguments for the GPURenderCommandsMixin.drawIndexed(indexCount, instanceCount, firstIndex, baseVertex, firstInstance) method.
Parameter Type Nullable Optional Description
indexCount GPUSize32 The number of indices to draw.
instanceCount GPUSize32 The number of instances to draw.
firstIndex GPUSize32 Offset into the index buffer, in indices, begin drawing from.
baseVertex GPUSignedOffset32 Added to each index value before indexing into the vertex buffers.
firstInstance GPUSize32 First instance to draw.

Returns: undefined

Issue the following steps on the Device timeline of this.[[device]]:

  1. Validate the encoder state of this. If it returns false, stop.

  2. If any of the following conditions are unsatisfied, make this invalid and stop.

  3. Increment this.[[drawCount]] by 1.

Note: a valid program should also never use vertex indices with GPUVertexStepMode."vertex" that are out of bounds. WebGPU implementations have different ways of handling this, and therefore a range of behaviors is allowed. Either the whole draw call is discarded, or the access to those attributes out of bounds is described by WGSL’s invalid memory reference.

drawIndirect(indirectBuffer, indirectOffset)

Draws primitives using parameters read from a GPUBuffer. See § 22.3 Rendering for the detailed specification.

The indirect draw parameters encoded in the buffer must be a tightly packed block of four 32-bit unsigned integer values (16 bytes total), given in the same order as the arguments for draw(). For example:

let drawIndirectParameters = new Uint32Array(4);
drawIndirectParameters[0] = vertexCount;
drawIndirectParameters[1] = instanceCount;
drawIndirectParameters[2] = firstVertex;
drawIndirectParameters[3] = firstInstance;

The value corresponding to firstInstance must be 0, unless the "indirect-first-instance" feature is enabled. If the "indirect-first-instance" feature is not enabled and firstInstance is not zero the drawIndirect() call will be treated as a no-op.

Called on: GPURenderCommandsMixin this.

Arguments:

Arguments for the GPURenderCommandsMixin.drawIndirect(indirectBuffer, indirectOffset) method.
Parameter Type Nullable Optional Description
indirectBuffer GPUBuffer Buffer containing the indirect draw parameters.
indirectOffset GPUSize64 Offset in bytes into indirectBuffer where the drawing data begins.

Returns: undefined

Issue the following steps on the Device timeline of this.[[device]]:

  1. Validate the encoder state of this. If it returns false, stop.

  2. If any of the following conditions are unsatisfied, make this invalid and stop.

  3. Add indirectBuffer to the usage scope as input.

  4. Increment this.[[drawCount]] by 1.

drawIndexedIndirect(indirectBuffer, indirectOffset)

Draws indexed primitives using parameters read from a GPUBuffer. See § 22.3 Rendering for the detailed specification.

The indirect drawIndexed parameters encoded in the buffer must be a tightly packed block of five 32-bit unsigned integer values (20 bytes total), given in the same order as the arguments for drawIndexed(). For example:

let drawIndexedIndirectParameters = new Uint32Array(5);
drawIndexedIndirectParameters[0] = indexCount;
drawIndexedIndirectParameters[1] = instanceCount;
drawIndexedIndirectParameters[2] = firstIndex;
drawIndexedIndirectParameters[3] = baseVertex;
drawIndexedIndirectParameters[4] = firstInstance;

The value corresponding to firstInstance must be 0, unless the "indirect-first-instance" feature is enabled. If the "indirect-first-instance" feature is not enabled and firstInstance is not zero the drawIndexedIndirect() call will be treated as a no-op.

Called on: GPURenderCommandsMixin this.

Arguments:

Arguments for the GPURenderCommandsMixin.drawIndexedIndirect(indirectBuffer, indirectOffset) method.
Parameter Type Nullable Optional Description
indirectBuffer GPUBuffer Buffer containing the indirect drawIndexed parameters.
indirectOffset GPUSize64 Offset in bytes into indirectBuffer where the drawing data begins.

Returns: undefined

Issue the following steps on the Device timeline of this.[[device]]:

  1. Validate the encoder state of this. If it returns false, stop.

  2. If any of the following conditions are unsatisfied, make this invalid and stop.

  3. Add indirectBuffer to the usage scope as input.

  4. Increment this.[[drawCount]] by 1.

To determine if it’s valid to draw with GPURenderCommandsMixin encoder run the following steps:

If any of the following conditions are unsatisfied, return false:

Otherwise return true.

To determine if it’s valid to draw indexed with GPURenderCommandsMixin encoder run the following steps:

If any of the following conditions are unsatisfied, return false:

Otherwise return true.

16.2.2. Rasterization state

The GPURenderPassEncoder has several methods which affect how draw commands are rasterized to attachments used by this encoder.

setViewport(x, y, width, height, minDepth, maxDepth)

Sets the viewport used during the rasterization stage to linearly map from normalized device coordinates to viewport coordinates.

Called on: GPURenderPassEncoder this.

Arguments:

Arguments for the GPURenderPassEncoder.setViewport(x, y, width, height, minDepth, maxDepth) method.
Parameter Type Nullable Optional Description
x float Minimum X value of the viewport in pixels.
y float Minimum Y value of the viewport in pixels.
width float Width of the viewport in pixels.
height float Height of the viewport in pixels.
minDepth float Minimum depth value of the viewport.
maxDepth float Maximum depth value of the viewport.

Returns: undefined

Issue the following steps on the Device timeline of this:

  1. Validate the encoder state of this. If it returns false, stop.

  2. If any of the following conditions are unsatisfied, make this invalid and stop.

    • x is greater than or equal to 0.

    • y is greater than or equal to 0.

    • width is greater than or equal to 0.

    • height is greater than or equal to 0.

    • x + width is less than or equal to this.[[attachment_size]].width.

    • y + height is less than or equal to this.[[attachment_size]].height.

    • minDepth is greater than or equal to 0.0 and less than or equal to 1.0.

    • maxDepth is greater than or equal to 0.0 and less than or equal to 1.0.

    • maxDepth is greater than minDepth.

  3. Set this.[[viewport]] to the extents x, y, width, height, minDepth, and maxDepth.

Allowed for GPUs to use fixed point or rounded viewport coordinates

setScissorRect(x, y, width, height)

Sets the scissor rectangle used during the rasterization stage. After transformation into viewport coordinates any fragments which fall outside the scissor rectangle will be discarded.

Called on: GPURenderPassEncoder this.

Arguments:

Arguments for the GPURenderPassEncoder.setScissorRect(x, y, width, height) method.
Parameter Type Nullable Optional Description
x GPUIntegerCoordinate Minimum X value of the scissor rectangle in pixels.
y GPUIntegerCoordinate Minimum Y value of the scissor rectangle in pixels.
width GPUIntegerCoordinate Width of the scissor rectangle in pixels.
height GPUIntegerCoordinate Height of the scissor rectangle in pixels.

Returns: undefined

Issue the following steps on the Device timeline of this:

  1. Validate the encoder state of this. If it returns false, stop.

  2. If any of the following conditions are unsatisfied, make this invalid and stop.

  3. Set the scissor rectangle to the extents x, y, width, and height.

setBlendConstant(color)

Sets the constant blend color and alpha values used with "constant" and "one-minus-constant" GPUBlendFactors.

Called on: GPURenderPassEncoder this.

Arguments:

Arguments for the GPURenderPassEncoder.setBlendConstant(color) method.
Parameter Type Nullable Optional Description
color GPUColor The color to use when blending.

Issue the following steps on the Device timeline of this:

  1. Validate the encoder state of this. If it returns false, stop.

  2. Set [[blend_constant]] to color.

setStencilReference(reference)

Sets the [[stencil_reference]] value used during stencil tests with the "replace" GPUStencilOperation.

Called on: GPURenderPassEncoder this.

Arguments:

Arguments for the GPURenderPassEncoder.setStencilReference(reference) method.
Parameter Type Nullable Optional Description
reference GPUStencilValue The new stencil reference value.

Issue the following steps on the Device timeline of this:

  1. Validate the encoder state of this. If it returns false, stop.

  2. Set [[stencil_reference]] to reference.

16.2.3. Queries

beginOcclusionQuery(queryIndex)
Called on: GPURenderPassEncoder this.

Arguments:

Arguments for the GPURenderPassEncoder.beginOcclusionQuery(queryIndex) method.
Parameter Type Nullable Optional Description
queryIndex GPUSize32 The index of the query in the query set.

Returns: undefined

Issue the following steps on the Device timeline of this.[[device]]:

  1. Validate the encoder state of this. If it returns false, stop.

  2. If any of the following conditions are unsatisfied, make this invalid and stop.

  3. Set this.[[occlusion_query_active]] to true.

endOcclusionQuery()
Called on: GPURenderPassEncoder this.

Returns: undefined

Issue the following steps on the Device timeline of this.[[device]]:

  1. Validate the encoder state of this. If it returns false, stop.

  2. If any of the following conditions are unsatisfied, make this invalid and stop.

  3. Set this.[[occlusion_query_active]] to false.

16.2.4. Bundles

executeBundles(bundles)

Executes the commands previously recorded into the given GPURenderBundles as part of this render pass.

When a GPURenderBundle is executed, it does not inherit the render pass’s pipeline, bind groups, or vertex and index buffers. After a GPURenderBundle has executed, the render pass’s pipeline, bind group, and vertex/index buffer state is cleared (to the initial, empty values).

Note: The state is cleared, not restored to the previous state. This occurs even if zero GPURenderBundles are executed.

Called on: GPURenderPassEncoder this.

Arguments:

Arguments for the GPURenderPassEncoder.executeBundles(bundles) method.
Parameter Type Nullable Optional Description
bundles sequence<GPURenderBundle> List of render bundles to execute.

Returns: undefined

Issue the following steps on the Device timeline of this:

  1. Validate the encoder state of this. If it returns false, stop.

  2. If any of the following conditions are unsatisfied, make this invalid and stop.

  1. Describe the rest of the steps

17. Bundles

17.1. GPURenderBundle

[Exposed=(Window, DedicatedWorker), SecureContext]
interface GPURenderBundle {
};
GPURenderBundle includes GPUObjectBase;
[[command_list]], of type list<GPU command>

A list of GPU commands to be submitted to the GPURenderPassEncoder when the GPURenderBundle is executed.

[[layout]], of type GPURenderPassLayout

The layout of the render bundle.

[[depthReadOnly]], of type boolean

If true, indicates that the depth component is not modified by executing this render bundle.

[[stencilReadOnly]], of type boolean

If true, indicates that the stencil component is not modified by executing this render bundle.

[[drawCount]], of type GPUSize64

The number of draw commands in this GPURenderBundle.

17.1.1. Creation

dictionary GPURenderBundleDescriptor : GPUObjectDescriptorBase {
};
[Exposed=(Window, DedicatedWorker), SecureContext]
interface GPURenderBundleEncoder {
    GPURenderBundle finish(optional GPURenderBundleDescriptor descriptor = {});
};
GPURenderBundleEncoder includes GPUObjectBase;
GPURenderBundleEncoder includes GPUCommandsMixin;
GPURenderBundleEncoder includes GPUDebugCommandsMixin;
GPURenderBundleEncoder includes GPUBindingCommandsMixin;
GPURenderBundleEncoder includes GPURenderCommandsMixin;
createRenderBundleEncoder(descriptor)

Creates a GPURenderBundleEncoder.

Called on: GPUDevice this.

Arguments:

Arguments for the GPUDevice.createRenderBundleEncoder(descriptor) method.
Parameter Type Nullable Optional Description
descriptor GPURenderBundleEncoderDescriptor Description of the GPURenderBundleEncoder to create.

Returns: GPURenderBundleEncoder

  1. Validate texture format required features of each element of descriptor.colorFormats with this.[[device]].

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

  3. Let e be a new GPURenderBundleEncoder object.

  4. Issue the following steps on the Device timeline of this:

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

    2. Set e.[[layout]] to a copy of descriptor’s included GPURenderPassLayout interface.

    3. Set e.[[depthReadOnly]] to descriptor.depthReadOnly.

    4. Set e.[[stencilReadOnly]] to descriptor.stencilReadOnly.

    5. Set e.[[state]] to "open".

    6. Set e.[[drawCount]] to 0.

    Describe the reset of the steps for createRenderBundleEncoder().

  5. Return e.

17.1.2. Encoding

dictionary GPURenderBundleEncoderDescriptor : GPURenderPassLayout {
    boolean depthReadOnly = false;
    boolean stencilReadOnly = false;
};

17.1.3. Finalization

finish(descriptor)

Completes recording of the render bundle commands sequence.

Called on: GPURenderBundleEncoder this.

Arguments:

Arguments for the GPURenderBundleEncoder.finish(descriptor) method.
Parameter Type Nullable Optional Description
descriptor GPURenderBundleDescriptor

Returns: GPURenderBundle

  1. Let renderBundle be a new GPURenderBundle.

  2. Issue the following steps on the Device timeline of this:

    1. Let validationSucceeded be true if all of the following requirements are met, and false otherwise.

    2. Set this.[[state]] to "ended".

    3. If validationSucceeded is false, then:

      1. Generate a validation error.

      2. Return a new invalid GPURenderBundle.

    4. Set renderBundle.[[command_list]] to this.[[commands]].

    5. Set renderBundle.[[drawCount]] to this.[[drawCount]].

  3. Return renderBundle.

18. Queues

18.1. GPUQueueDescriptor

GPUQueueDescriptor describes a queue request.

dictionary GPUQueueDescriptor : GPUObjectDescriptorBase {
};

18.2. GPUQueue

[Exposed=(Window, DedicatedWorker), SecureContext]
interface GPUQueue {
    undefined submit(sequence<GPUCommandBuffer> commandBuffers);

    Promise<undefined> onSubmittedWorkDone();

    undefined writeBuffer(
        GPUBuffer buffer,
        GPUSize64 bufferOffset,
        [AllowShared] BufferSource data,
        optional GPUSize64 dataOffset = 0,
        optional GPUSize64 size);

    undefined writeTexture(
        GPUImageCopyTexture destination,
        [AllowShared] BufferSource data,
        GPUImageDataLayout dataLayout,
        GPUExtent3D size);

    undefined copyExternalImageToTexture(
        GPUImageCopyExternalImage source,
        GPUImageCopyTextureTagged destination,
        GPUExtent3D copySize);
};
GPUQueue includes GPUObjectBase;

GPUQueue has the following methods:

writeBuffer(buffer, bufferOffset, data, dataOffset, size)

Issues a write operation of the provided data into a GPUBuffer.

Called on: GPUQueue this.

Arguments:

Arguments for the GPUQueue.writeBuffer(buffer, bufferOffset, data, dataOffset, size) method.
Parameter Type Nullable Optional Description
buffer GPUBuffer The buffer to write to.
bufferOffset GPUSize64 Offset in bytes into buffer to begin writing at.
data BufferSource Data to write into buffer.
dataOffset GPUSize64 Offset in into data to begin writing from. Given in elements if data is a TypedArray and bytes otherwise.
size GPUSize64 Size of content to write from data to buffer. Given in elements if data is a TypedArray and bytes otherwise.

Returns: undefined

  1. If data is an ArrayBuffer or DataView, let the element type be "byte". Otherwise, data is a TypedArray; let the element type be the type of the TypedArray.

  2. Let dataSize be the size of data, in elements.

  3. If size is missing, let contentsSize be dataSizedataOffset. Otherwise, let contentsSize be size.

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

    • contentsSize ≥ 0.

    • dataOffset + contentsSizedataSize.

    • contentsSize, converted to bytes, is a multiple of 4 bytes.

  5. Let dataContents be a copy of the bytes held by the buffer source.

  6. Let contents be the contentsSize elements of dataContents starting at an offset of dataOffset elements.

  7. Issue the following steps on the Device timeline of this:

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

    2. Write contents into buffer starting at bufferOffset.

writeTexture(destination, data, dataLayout, size)

Issues a write operation of the provided data into a GPUTexture.

Called on: GPUQueue this.

Arguments:

Arguments for the GPUQueue.writeTexture(destination, data, dataLayout, size) method.
Parameter Type Nullable Optional Description
destination GPUImageCopyTexture The texture subresource and origin to write to.
data BufferSource Data to write into destination.
dataLayout GPUImageDataLayout Layout of the content in data.
size GPUExtent3D Extents of the content to write from data to destination.

Returns: undefined

  1. Let dataBytes be a copy of the bytes held by the buffer source data.

  2. Let dataByteSize be the number of bytes in dataBytes.

  3. Let texture be destination.texture.

  4. Let contents be the contents of the images seen by viewing dataBytes with dataLayout and size.

    Specify more formally.

  5. Issue the following steps on the Device timeline of this:

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

      Note: unlike GPUCommandEncoder.copyBufferToTexture(), there is no alignment requirement on either dataLayout.bytesPerRow or dataLayout.offset.

    2. Write contents into destination.

      Specify more formally.

copyExternalImageToTexture(source, destination, copySize)

Issues a copy operation of the contents of a platform image/canvas into the destination texture.

This operation performs color encoding into the destination encoding according to the parameters of GPUImageCopyTextureTagged.

Copying into a -srgb texture results in the same texture bytes, not the same decoded values, as copying into the corresponding non--srgb format. Thus, after a copy operation, sampling the destination texture has different results depending on whether its format is -srgb, all else unchanged.

If an srgb-linear color space is added, explain here how it interacts.

Called on: GPUQueue this.

Arguments:

Arguments for the GPUQueue.copyExternalImageToTexture(source, destination, copySize) method.
Parameter Type Nullable Optional Description
source GPUImageCopyExternalImage source image and origin to copy to destination.
destination GPUImageCopyTextureTagged The texture subresource and origin to write to, and its encoding metadata.
copySize GPUExtent3D Extents of the content to write from source to destination.

Returns: undefined

  1. Let sourceImage be source.source

  2. Run Check the usability of the image argument(sourceImage). If it throws an exception, stop. If it does not return good, throw an InvalidStateError and stop.

  3. If sourceImage is not origin-clean, throw a SecurityError and stop.

  4. If any of the following requirements are unmet, throw an OperationError and stop.

    • source.origin.x + copySize.width must be ≤ the width of sourceImage.

    • source.origin.y + copySize.height must be ≤ the height of sourceImage.

    • source.origin.z + copySize.depthOrArrayLayers must be ≤ 1.

  5. Issue the following steps on the Device timeline of this:

    1. Let texture be destination.texture.

    2. If any of the following requirements are unmet, generate a validation error and stop.

    3. Do the actual copy.

submit(commandBuffers)

Schedules the execution of the command buffers by the GPU on this queue.

Called on: GPUQueue this.

Arguments:

Arguments for the GPUQueue.submit(commandBuffers) method.
Parameter Type Nullable Optional Description
commandBuffers sequence<GPUCommandBuffer>

Returns: undefined

Issue the following steps on the Device timeline of this:

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

  2. Issue the following steps on the Queue timeline of this:

    1. For each commandBuffer in commandBuffers:

      1. Execute each command in commandBuffer.[[command_list]].

onSubmittedWorkDone()

Returns a Promise that resolves once this queue finishes processing all the work submitted up to this moment.

Called on: GPUQueue this.

Returns: Promise<undefined>

  1. Let promise be a new promise.

  2. Enqueue an operation on the Queue timeline of this that will execute the following:

    1. Resolve promise.

  3. Return promise.

19. Queries

19.1. GPUQuerySet

[Exposed=(Window, DedicatedWorker), SecureContext]
interface GPUQuerySet {
    undefined destroy();

    readonly attribute GPUQueryType type;
    readonly attribute GPUSize32 count;
};
GPUQuerySet includes GPUObjectBase;

GPUQuerySet has the following attributes:

type, of type GPUQueryType, readonly

The type of the queries managed by this GPUQuerySet.

count, of type GPUSize32, readonly

The number of queries managed by this GPUQuerySet.

GPUQuerySet has the following internal slots:

[[state]], of type query set state

The current state of the GPUQuerySet.

Each GPUQuerySet has a current query set state on the Device timeline which is one of the following:

19.1.1. QuerySet Creation

A GPUQuerySetDescriptor specifies the options to use in creating a GPUQuerySet.

dictionary GPUQuerySetDescriptor : GPUObjectDescriptorBase {
    required GPUQueryType type;
    required GPUSize32 count;
};
type, of type GPUQueryType

The type of queries managed by GPUQuerySet.

count, of type GPUSize32

The number of queries managed by GPUQuerySet.

createQuerySet(descriptor)

Creates a GPUQuerySet.

Called on: GPUDevice this.

Arguments:

Arguments for the GPUDevice.createQuerySet(descriptor) method.
Parameter Type Nullable Optional Description
descriptor GPUQuerySetDescriptor Description of the GPUQuerySet to create.

Returns: GPUQuerySet

  1. If descriptor.type is "timestamp", but this.[[device]].[[features]] does not contain "timestamp-query", throw a TypeError.

  2. Let q be a new GPUQuerySet object.

  3. Set q.type to descriptor.type.

  4. Set q.count to descriptor.count.

  5. Issue the following steps on the Device timeline of this:

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

      • this is valid.

      • descriptor.count must be ≤ 8192.

    2. Set q.[[state]] to available.

  6. Return q.

Creating a GPUQuerySet which holds 32 occlusion query results.
const querySet = gpuDevice.createQuerySet({
    type: 'occlusion',
    count: 32
});

19.1.2. QuerySet Destruction

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

destroy()

Destroys the GPUQuerySet.

Called on: GPUQuerySet this.

Returns: undefined

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

19.2. QueryType

enum GPUQueryType {
    "occlusion",
    "timestamp"
};

19.3. Occlusion Query

Occlusion query is only available on render passes, to query the number of fragment samples that pass all the per-fragment tests for a set of drawing commands, including scissor, sample mask, alpha to coverage, stencil, and depth tests. Any non-zero result value for the query indicates that at least one sample passed the tests and reached the output merging stage of the render pipeline, 0 indicates that no samples passed the tests.

When beginning a render pass, GPURenderPassDescriptor.occlusionQuerySet must be set to be able to use occlusion queries during the pass. An occlusion query is begun and ended by calling beginOcclusionQuery() and endOcclusionQuery() in pairs that cannot be nested.

19.4. Timestamp Query

Timestamp query allows application to write timestamp values to a GPUQuerySet by calling writeTimestamp() on GPUCommandEncoder, and then resolve timestamp values in nanoseconds (type of GPUSize64) to a GPUBuffer (using resolveQuerySet()).

Timestamp query requires "timestamp-query" is available on the device.

Note: The timestamp values may be zero if the physical device reset timestamp counter, please ignore it and the following values.

Write normative text about timestamp value resets.

Because timestamp query provides high-resolution GPU timestamp, we need to decide what constraints, if any, are on its availability.

20. Canvas Rendering

20.1. HTMLCanvasElement.getContext()

A GPUCanvasContext object is created via the getContext() method of an HTMLCanvasElement instance by passing the string literal 'webgpu' as its contextType argument.

To create a 'webgpu' context on a canvas (HTMLCanvasElement or OffscreenCanvas) canvas:
  1. Let context be a new GPUCanvasContext.

  2. Set context.canvas to canvas.

  3. Set context.[[drawingBuffer]] to a transparent black image with the same size as canvas.

  4. Return context.

Get a GPUCanvasContext from an offscreen HTMLCanvasElement:
const canvas = document.createElement('canvas');
const context = canvas.getContext('webgpu');

20.2. GPUCanvasContext

[Exposed=(Window, DedicatedWorker), SecureContext]
interface GPUCanvasContext {
    readonly attribute (HTMLCanvasElement or OffscreenCanvas) canvas;

    undefined configure(GPUCanvasConfiguration configuration);
    undefined unconfigure();

    GPUTexture getCurrentTexture();
};

GPUCanvasContext has the following attributes:

canvas, of type (HTMLCanvasElement or OffscreenCanvas), readonly

The canvas this context was created from.

GPUCanvasContext has the following internal slots:

[[configuration]], of type GPUCanvasConfiguration?, initially null

The options this context is currently configured with.

null if the context has not been configured or has been unconfigured.

[[textureDescriptor]], of type GPUTextureDescriptor?, initially null

The currently configured texture descriptor, derived from the [[configuration]] and canvas.

null if the context has not been configured or has been unconfigured.

[[drawingBuffer]], an image, initially a transparent black image with the same size as the canvas

The drawing buffer is the working-copy image data of the canvas. It is exposed as writable by [[currentTexture]] (returned by getCurrentTexture()).

The drawing buffer is used to get a copy of the image contents of a context, which occurs at the end of every frame to present the drawing buffer to the screen, in "update the rendering of the WebGPU canvas". It may be transparent, even if [[configuration]].alphaMode is "opaque". The alphaMode only affects the result of the "get a copy of the image contents of a context" algorithm.

The drawing buffer outlives the [[currentTexture]] and contains the previously-rendered contents even after the canvas has been presented.

Any time the drawing buffer is read, implementations must ensure that all previously submitted work (e.g. queue submissions) have completed writing to it via [[currentTexture]].

[[currentTexture]], of type GPUTexture?, initially null

The GPUTexture to draw into for the current frame. It exposes a writable view onto the underlying [[drawingBuffer]]. getCurrentTexture() populates this slot if null or destroyed, then returns it.

Any changes to the drawing buffer made through the currentTexture get presented at the end of the frame, in "update the rendering of the WebGPU canvas".

Destroying the currentTexture has no effect on the drawing buffer contents; it only terminates write-access to the drawing buffer early. During the same frame, getCurrentTexture() continues returning the same destroyed texture.

Calling configure() or resizing the canvas clears the drawing buffer and sets the current texture to null, in "Replace the drawing buffer".

GPUCanvasContext has the following methods:

configure(configuration)

Configures the context for this canvas. This clears the drawing buffer to transparent black (in Replace the drawing buffer).

Called on: GPUCanvasContext this.

Arguments:

Arguments for the GPUCanvasContext.configure(configuration) method.
Parameter Type Nullable Optional Description
configuration GPUCanvasConfiguration Desired configuration for the context.

Returns: undefined

  1. Let device be configuration.device.

  2. Validate texture format required features of configuration.format with device.[[device]].

  3. Validate texture format required features of each element of configuration.viewFormats with device.[[device]].

  4. Let descriptor be the GPUTextureDescriptor for the canvas and configuration(this.canvas, configuration).

  5. Set this.[[configuration]] to configuration.

  6. Set this.[[textureDescriptor]] to descriptor.

  7. Replace the drawing buffer of this, which resets this.[[drawingBuffer]] with a bitmap with the new format and tags.

  8. Issue the following steps on the Device timeline of device:

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

      Note: This early validation remains valid until the next configure() call, except for validation of the size, which changes when the canvas is resized.

unconfigure()

Removes the context configuration. Destroys any textures produced while configured.

Called on: GPUCanvasContext this.

Returns: undefined

  1. Set this.[[configuration]] to null.

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

  3. Replace the drawing buffer of this.

getCurrentTexture()

Get the GPUTexture that will be composited to the document by the GPUCanvasContext next.

Called on: GPUCanvasContext this.

Returns: GPUTexture

  1. If this.[[configuration]] is null:

    1. Throw an InvalidStateError and stop.

  2. Assert this.[[textureDescriptor]] is not null.

  3. Let device be this.[[configuration]].device.

  4. If this.[[currentTexture]] is null:

    1. Replace the drawing buffer.

    2. Set this.[[currentTexture]] to the result of calling device.createTexture() with this.[[textureDescriptor]], except with the GPUTexture's underlying storage pointing to this.[[drawingBuffer]].

      Note: If the texture can’t be created (e.g. due to validation failure or out-of-memory), this generates and error and returns an invalid GPUTexture. Some validation here is redundant with that done in configure(). Implementations must not skip this redundant validation.

  5. Return this.[[currentTexture]].

Note: The same GPUTexture object will be returned by every call to getCurrentTexture() made within the same frame (i.e. between invocations of "update the rendering of the WebGPU canvas"), even if that GPUTexture is destroyed, failed validation, or failed to allocate, unless the current texture has been removed (in Replace the drawing buffer).

In the "update the rendering or user interface of that Document" sub-step of the "Update the rendering" step of the HTML processing model, each GPUCanvasContext context must update the rendering of the WebGPU canvas by running the following steps:
  1. Update the rendering of context.canvas with a copy of the image contents of context.

  2. If context.[[currentTexture]] is not null:

    1. Call context.[[currentTexture]].destroy() (without destroying context.[[drawingBuffer]]) to terminate write access to the image.

Note: If alphaMode is "opaque", the presented image has its alpha channel cleared. Implementations may skip this step if they are able to composite images in a way that ignores the alpha channel (as if it is 1.0).

When transferToImageBitmap() is called on a canvas with GPUCanvasContext context:
  1. Let imageContents be a copy of the image contents of context.

  2. Replace the drawing buffer.

  3. Return a new ImageBitmap containing the imageContents.

Note: This is equivalent to "moving" the (possibly alpha-cleared) image contents into the ImageBitmap, without a copy.

When WebGPU canvas contents are read using other Web APIs, like drawImage(), texImage2D(), texSubImage2D(), toDataURL(), toBlob(), and so on, they get a copy of the image contents of a context.

Note: If alphaMode is "opaque", this incurs a clear of the alpha channel. If a canvas is only needed for interop (not presentation), avoid "opaque" if not needed.

To get a copy of the image contents of a context:

Arguments:

Returns: image contents

  1. Ensure that all submitted work items (e.g. queue submissions) have completed writing to the image (via context.[[currentTexture]]).

  2. Let snapshot be a copy of context.[[drawingBuffer]].

  3. Let alphaMode be context.[[configuration]].alphaMode.

  4. If alphaMode is "opaque":
    1. Clear the alpha channel of snapshot to 1.0.

    2. Tag snapshot as being opaque.

    Note: If the GPUTexture exposing this [[currentTexture]] (if any) has been destroyed, the alpha channel is unobservable, and implementations may clear the alpha channel in-place.

    Otherwise:

    Tag snapshot with alphaMode.

  5. Return snapshot.

To Replace the drawing buffer of a GPUCanvasContext context:
  1. If context.[[currentTexture]] is not null, call its destroy() method.

  2. Set context.[[currentTexture]] to null.

  3. Let configuration be context.[[configuration]].

  4. Set context.[[drawingBuffer]] to a transparent black image of the same size as context.canvas.

    • If configuration is null, the drawing buffer is tagged with the color space "srgb". In this case, the drawing buffer will remain blank until the context is configured.

    • If not, the drawing buffer has the specified configuration.format and is tagged with the specified configuration.colorSpace.

    Note: configuration.alphaMode is ignored until "get a copy of the image contents of a context".

20.3. GPUCanvasConfiguration

The supported context formats are a set of GPUTextureFormats that must be supported when specified as a GPUCanvasConfiguration.format regardless of the given GPUCanvasConfiguration.device, initially set to: «"bgra8unorm", "rgba8unorm", "rgba16float"».

Note: Canvas configuration cannot use srgb formats like "bgra8unorm-srgb". Instead, use the non-srgb equivalent ("bgra8unorm"), specify the srgb format in the viewFormats, and use createView() to create a view with an srgb format.

enum GPUCanvasAlphaMode {
    "opaque",
    "premultiplied"
};

dictionary GPUCanvasConfiguration {
    required GPUDevice device;
    required GPUTextureFormat format;
    GPUTextureUsageFlags usage = 0x10;  // GPUTextureUsage.RENDER_ATTACHMENT
    sequence<GPUTextureFormat> viewFormats = [];
    PredefinedColorSpace colorSpace = "srgb";
    GPUCanvasAlphaMode alphaMode = "opaque";
};

GPUCanvasConfiguration has the following members:

device, of type GPUDevice

The GPUDevice that textures returned by getCurrentTexture() will be compatible with.

format, of type GPUTextureFormat

The format that textures returned by getCurrentTexture() will have. Must be one of the Supported context formats.

usage, of type GPUTextureUsageFlags, defaulting to 0x10

The usage that textures returned by getCurrentTexture() will have. RENDER_ATTACHMENT is the default, but is not automatically included if the usage is explicitly set. Be sure to include RENDER_ATTACHMENT when setting a custom usage if you wish to use textures returned by getCurrentTexture() as color targets for a render pass.

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

The formats that views created from textures returned by getCurrentTexture() may use.

colorSpace, of type PredefinedColorSpace, defaulting to "srgb"

The color space that values written into textures returned by getCurrentTexture() should be displayed with.

alphaMode, of type GPUCanvasAlphaMode, defaulting to "opaque"

Determines the effect that alpha values will have on the content of textures returned by getCurrentTexture() when read, displayed, or used as an image source.

Configure a GPUCanvasContext to be used with a specific GPUDevice, using the preferred format for this context:
const canvas = document.createElement('canvas');
const context = canvas.getContext('webgpu');

context.configure({
    device: gpuDevice,
    format: navigator.gpu.getPreferredCanvasFormat(),
});
The GPUTextureDescriptor for the canvas and configuration( (HTMLCanvasElement or OffscreenCanvas) canvas, GPUCanvasConfiguration configuration) is a GPUTextureDescriptor with the following members:

and other members set to their defaults.

canvas.width refers to HTMLCanvasElement.width or OffscreenCanvas.width. canvas.height refers to HTMLCanvasElement.height or OffscreenCanvas.height.

20.3.1. Canvas Color Space

During presentation, the chrominance of color values outside of the [0, 1] range is not to be clamped to that range; extended values may be used to display colors outside of the gamut defined by the canvas' color space’s primaries, when permitted by the configured format and the user’s display capabilities. This is in contrast with luminance, which is to be clamped to the maximum standard dynamic range luminance.

Unless high dynamic range is explicitly enabled for the canvas element.

20.3.2. Canvas Context sizing

All canvas configuration is set in configure() except for the resolution of the canvas, which is set by the canvas’s width and height.

Note: Like WebGL and 2d canvas, resizing a WebGPU canvas loses the current contents of the drawing buffer. In WebGPU, it does so by replacing the drawing buffer.

When an HTMLCanvasElement or OffscreenCanvas canvas with a GPUCanvasContext context has its width or height properties modified, update the canvas size:
  1. Replace the drawing buffer of context.

  2. Let configuration be context.[[configuration]]

  3. If configuration is not null:

    1. Set context.[[textureDescriptor]] to the GPUTextureDescriptor for the canvas and configuration(canvas, configuration).

Note: This may result a GPUTextureDescriptor which exceeds the maxTextureDimension2D of the device. In this case, validation will fail inside getCurrentTexture().

Reconfigure a GPUCanvasContext in response to canvas resize, monitored using ResizeObserver to get the exact pixel dimensions of the canvas:
const canvas = document.createElement('canvas');
const context = canvas.getContext('webgpu');

const resizeObserver = new ResizeObserver(entries => {
    for (const entry of entries) {
        if (entry.target != canvas) { continue; }
        canvas.width = entry.devicePixelContentBoxSize[0].inlineSize;
        canvas.height = entry.devicePixelContentBoxSize[0].blockSize;
    }
});
resizeObserver.observe(canvas);

20.4. GPUCanvasAlphaMode

This enum selects how the contents of the canvas will be interpreted when read, when rendered to the screen or used as an image source (in drawImage, toDataURL, etc.)

GPUCanvasAlphaMode Description dst.rgb dst.a
opaque Read RGB as opaque and ignore alpha values. If the content is not already opaque, the alpha channel is cleared to 1.0 when used as an image source or rendered to the screen. dst.rgb = src.rgb dst.a = 1
premultiplied Read RGBA as premultiplied: color values are premultiplied by their alpha value. 100% red 50% opaque is [0.5, 0, 0, 0.5].

When used as an image source, super-luminant values undergo color space conversion.

When displayed to the screen, super-luminant values have undefined compositing results. This is true even if color space conversion would result in non-super-luminant values before compositing, because the intermediate format for compositing is not specified.

dst.rgb = src.rgb + dst.rgb * (1 - src.a) dst.a = src.a + dst.a * (1 - src.a)

21. Errors & Debugging

21.1. Fatal Errors

enum GPUDeviceLostReason {
    "destroyed"
};

[Exposed=(Window, DedicatedWorker), SecureContext]
interface GPUDeviceLostInfo {
    readonly attribute (GPUDeviceLostReason or undefined) reason;
    readonly attribute DOMString message;
};

partial interface GPUDevice {
    readonly attribute Promise<GPUDeviceLostInfo> lost;
};

GPUDevice has the following additional attributes:

lost, of type Promise<GPUDeviceLostInfo>, readonly

A promise which is created with the device, remains pending for the lifetime of the device, then resolves when the device is lost.

This attribute is backed by an immutable internal slot of the same name, initially set to a new promise, and always returns its value.

21.2. Error Scopes

A GPU error scope captures GPUErrors that were generated while the GPU error scope was current. Error scopes are used to isolate errors that occur within a set of WebGPU calls, typically for debugging purposes or to make an operation more fault tolerant.

GPU error scope has the following internal slots:

[[error]], of type GPUError?, initially null

The first GPUError, if any, observed while the GPU error scope was current.

[[filter]], of type GPUErrorFilter

Determines what type of GPUError this GPU error scope observes.

enum GPUErrorFilter {
    "out-of-memory",
    "validation"
};
[Exposed=(Window, DedicatedWorker), SecureContext]
interface GPUError {
    readonly attribute DOMString message;
};

[Exposed=(Window, DedicatedWorker), SecureContext]
interface GPUOutOfMemoryError : GPUError {
    constructor(DOMString message);
};

[Exposed=(Window, DedicatedWorker), SecureContext]
interface GPUValidationError : GPUError {
    constructor(DOMString message);
};

GPUError is the base interface for all errors surfaced from popErrorScope() and the uncapturederror event.

Note: GPUError may gain new subtypes in future versions of this spec. Applications should handle this possibility, using only the error’s message when possible, and specializing using instanceof. Use error.constructor.name when it’s necessary to serialize an error (e.g. into JSON, for a debug report).

GPUError has the following attributes:

message, of type DOMString, readonly

A human-readable message providing information about the error that occurred.

Note: This message is generally intended for application developers to debug their applications and capture information for debug reports, not to be surfaced to end-users.

Note: User agents should not include potentially machine-parsable details in this message, such as free system memory on "out-of-memory" errors, or other details about the conditions under which memory was exhausted.

partial interface GPUDevice {
    undefined pushErrorScope(GPUErrorFilter filter);
    Promise<GPUError?> popErrorScope();
};

GPUDevice has the following internal slots:

[[errorScopeStack]], of type stack<GPU error scope>

A stack of GPU error scopes that have been pushed to the GPUDevice.

The current error scope for a GPUError error and GPUDevice device is determined by issuing the following steps to the Device timeline:
  1. If error is an instance of:

    GPUValidationError

    Let type be "validation".

    GPUOutOfMemoryError

    Let type be "out-of-memory".

  2. Let scope be the last item of device.[[errorScopeStack]].

  3. While scope is not undefined:

    1. If scope.[[filter]] is type, return scope.

    2. Set scope to the previous item of device.[[errorScopeStack]].

  4. Return undefined.

To generate a validation error for GPUDevice device, run the following steps:
  1. Let error be a new GPUValidationError with an appropriate error message.

  2. Issue the following steps to the Device timeline:

    1. Let scope be the current error scope for error and device.

    2. If scope is not undefined:

      1. If scope.[[error]] is null, set scope.[[error]] to error.

      2. Stop.

    3. Otherwise issue the following steps to the Content timeline:

      1. If the user agent chooses, queue a task to fire a GPUUncapturedErrorEvent named "uncapturederror" on device with an error of error.

      Note: If (and only if) there are no uncapturederror handlers are registered, user agents should surface uncaptured errors to developers, for example as warnings in the browser’s developer console.

Note: The user agent may choose to throttle or limit the number of GPUUncapturedErrorEvents that a GPUDevice can raise to prevent an excessive amount of error handling or logging from impacting performance.

pushErrorScope(filter)

Pushes a new GPU error scope onto the [[errorScopeStack]] for this.

Called on: GPUDevice this.

Arguments:

Arguments for the GPUDevice.pushErrorScope(filter) method.
Parameter Type Nullable Optional Description
filter GPUErrorFilter Which class of errors this error scope observes.
  1. Issue the following steps to the Device timeline:

    1. Let scope be a new GPU error scope.

    2. Set scope.[[filter]] to filter.

    3. Push scope onto this.[[errorScopeStack]].

popErrorScope()

Pops a GPU error scope off the [[errorScopeStack]] for this and resolves to a GPUError if one was observed by the error scope.

Called on: GPUDevice this.

Returns: Promise<GPUError?>

  1. Let promise be a new promise.

  2. Issue the following steps to the Device timeline:

    1. If any of the following requirements are unmet, reject promise with an OperationError and stop.

    2. Let scope be the result of popping an item off of this.[[errorScopeStack]].

    3. Resolve promise with scope.[[error]].

  3. Return promise.

Using error scopes to capture validation errors from a GPUDevice operation that may fail:
gpuDevice.pushErrorScope('validation');

let sampler = gpuDevice.createSampler({
    maxAnisotropy: 0, // Invalid, maxAnisotropy must be at least 1.
});

gpuDevice.popErrorScope().then((error) => {
    if (error) {
        // There was an error creating the sampler, so discard it.
        sampler = null;
        console.error(`An error occured while creating sampler: ${error.message}`);
    }
});

21.3. Telemetry

When a GPUError is generated that is not observed by any GPU error scope, the user agent may fire an event named uncapturederror at a GPUDevice using GPUUncapturedErrorEvent.

Note: uncapturederror events are intended to be used for telemetry and reporting unexpected errors. They may not be dispatched for all uncaptured errors (for example, there may be a limit on the number of errors surfaced), and should not be used for handling known error cases that may occur during normal operation of an application. Prefer using pushErrorScope() and popErrorScope() in those cases.

[Exposed=(Window, DedicatedWorker), SecureContext]
interface GPUUncapturedErrorEvent : Event {
    constructor(
        DOMString type,
        GPUUncapturedErrorEventInit gpuUncapturedErrorEventInitDict
    );
    readonly attribute GPUError error;
};

dictionary GPUUncapturedErrorEventInit : EventInit {
    required GPUError error;
};

GPUUncapturedErrorEvent has the following attributes:

error, of type GPUError, readonly

Object representing the error that was uncaptured. This has the same type as errors returned by popErrorScope().

This attribute is backed by an immutable internal slot of the same name, and always returns its value.

This attribute should be [SameObject]. (If GPUError becomes an interface then we can do this without resolving the WebIDL issue.) [Issue #whatwg/webidl#1077]

partial interface GPUDevice {
    [Exposed=(Window, DedicatedWorker)]
    attribute EventHandler onuncapturederror;
};

GPUDevice has the following attributes:

onuncapturederror, of type EventHandler

An event handler IDL attribute for the uncapturederror event type.

Listening for uncaptured errors from a GPUDevice:
gpuDevice.addEventListener('uncapturederror', (event) => {
    // Re-surface the error, because adding an event listener may silence console logs.
    console.error('A WebGPU error was not captured:', event.error);

    myEngineDebugReport.uncapturedErrors.push({
        type: event.error.constructor.name,
        message: event.error.message,
    });
});

22. Detailed Operations

This section describes the details of various GPU operations.

22.1. Transfer

describe the transfers at the high level

22.2. Computing

Computing operations provide direct access to GPU’s programmable hardware. Compute shaders do not have pipeline inputs or outputs, their results are side effects from writing data into storage bindings bound as GPUBufferBindingType."storage" and GPUStorageTextureBindingLayout. These operations are encoded within GPUComputePassEncoder as:

describe the computing algorithm

22.3. Rendering

Rendering is done by a set of GPU operations that are executed within GPURenderPassEncoder, and result in modifications of the texture data, viewed by the render pass attachments. These operations are encoded with:

Note: rendering is the traditional use of GPUs, and is supported by multiple fixed-function blocks in hardware.

A RenderState is an internal object representing the state of the current GPURenderPassEncoder during command encoding. RenderState is a spec namespace for the following definitions:

For a given GPURenderPassEncoder pass, the syntax:

The main rendering algorithm:

render(descriptor, drawCall, state)

Arguments:

  1. Resolve indices. See § 22.3.1 Index Resolution.

    Let vertexList be the result of resolve indices(drawCall, state).

  2. Process vertices. See § 22.3.2 Vertex Processing.

    Execute process vertices(vertexList, drawCall, descriptor.vertex, state).

  3. Assemble primitives. See § 22.3.3 Primitive Assembly.

    Execute assemble primitives(vertexList, drawCall, descriptor.primitive).

  4. Clip primitives. See § 22.3.4 Primitive Clipping.

    Let primitiveList be the result of this stage.

  5. Rasterize. See § 22.3.5 Rasterization.

    Let rasterizationList be the result of rasterize(primitiveList, state).

  6. Process fragments. See § 22.3.6 Fragment Processing.

    Gather a list of fragments, resulting from executing process fragment(rasterPoint, descriptor.fragment, state) for each rasterPoint in rasterizationList.

  7. Process depth/stencil.

    fill out the section, using fragments

  8. Write pixels.

    fill out the section

22.3.1. Index Resolution

At the first stage of rendering, the pipeline builds a list of vertices to process for each instance.

resolve indices(drawCall, state)

Arguments:

Returns: list of integer indices.

  1. Let vertexIndexList be an empty list of indices.

  2. If drawCall is an indexed draw call:

    1. Initialize the vertexIndexList with drawCall.indexCount integers.

    2. For i in range 0 .. drawCall.indexCount (non-inclusive):

      1. Let relativeVertexIndex be fetch index(i + drawCall.firstIndex, state.indexBuffer).

      2. If relativeVertexIndex has the special value "out of bounds", stop and return the empty list.

        Note: Implementations may choose to display a warning when this occurs, especially when it is easy to detect (like in non-indirect indexed draw calls).

      3. Append drawCall.baseVertex + relativeVertexIndex to the vertexIndexList.

  3. Otherwise:

    1. Initialize the vertexIndexList with drawCall.vertexCount integers.

    2. Set each vertexIndexList item i to the value drawCall.firstVertex + i.

  4. Return vertexIndexList.

Note: in case of indirect draw calls, the indexCount, vertexCount, and other properties of drawCall are read from the indirect buffer instead of the draw command itself.

specify indirect commands better.

fetch index(i, buffer, offset, format)

Arguments:

Returns: unsigned integer or "out of bounds"

  1. Let indexSize be defined by the indexBufferState.format:

    "uint16"

    2

    "uint32"

    4

  2. If indexBufferState.offset + |i + 1| × indexSize > indexBufferState.size, return the special value "out of bounds".

  3. Interpret the data in indexBufferState.buffer, starting at offset indexBufferState.offset + i × indexSize, of size indexSize bytes, as an unsigned integer and return it.

22.3.2. Vertex Processing

Vertex processing stage is a programmable stage of the render pipeline that processes the vertex attribute data, and produces clip space positions for § 22.3.4 Primitive Clipping, as well as other data for the § 22.3.6 Fragment Processing.

process vertices(vertexIndexList, drawCall, desc, state)

Arguments:

Each vertex vertexIndex in the vertexIndexList, in each instance of index rawInstanceIndex, is processed independently. The rawInstanceIndex is in range from 0 to drawCall.instanceCount - 1, inclusive. This processing happens in parallel, and any side effects, such as writes into GPUBufferBindingType."storage" bindings, may happen in any order.

  1. Let instanceIndex be rawInstanceIndex + drawCall.firstInstance.

  2. For each non-null vertexBufferLayout in the list of desc.buffers:

    1. Let i be the index of the buffer layout in this list.

    2. Let vertexBuffer, vertexBufferOffset, and vertexBufferBindingSize be the buffer, offset, and size at slot i of state.vertexBuffers.

    3. Let vertexElementIndex be dependent on vertexBufferLayout.stepMode:

      "vertex"

      vertexIndex

      "instance"

      instanceIndex

    4. For each attributeDesc in vertexBufferLayout.attributes:

      1. Let attributeOffset be vertexBufferOffset + vertexElementIndex * vertexBufferLayout.arrayStride + attributeDesc.offset.

      2. Load the attribute data of format attributeDesc.format from vertexBuffer starting at offset attributeOffset. The components are loaded in the order x, y, z, w from buffer memory.

        If this results in an out-of-bounds access, the resulting value is determined according to WGSL’s invalid memory reference behavior.

      3. Optionally (implementation-defined): If attributeOffset + sizeof(attributeDesc.format) > vertexBufferOffset + vertexBufferBindingSize, empty vertexIndexList and stop, cancelling the draw call.

        Note: This allows implementations to detect out-of-bounds values in the index buffer before issuing a draw call, instead of using invalid memory reference behavior.

      4. Convert the data into a shader-visible format, according to channel formats rules.

        An attribute of type "snorm8x2" and byte values of [0x70, 0xD0] will be converted to vec2<f32>(0.88, -0.38) in WGSL.
      5. Adjust the data size to the shader type:

        • if both are scalar, or both are vectors of the same dimensionality, no adjustment is needed.

        • if data is vector but the shader type is scalar, then only the first component is extracted.

        • if both are vectors, and data has a higher dimension, the extra components are dropped.

          An attribute of type "float32x3" and value vec3<f32>(1.0, 2.0, 3.0) will exposed to the shader as vec2<f32>(1.0, 2.0) if a 2-component vector is expected.
        • if the shader type is a vector of higher dimensionality, or the data is a scalar, then the missing components are filled from vec4<*>(0, 0, 0, 1) value.

          An attribute of type "sint32" and value 5 will be exposed to the shader as vec4<i32>(5, 0, 0, 1) if a 4-component vector is expected.
      6. Bind the data to vertex shader input location attributeDesc.shaderLocation.

  3. For each GPUBindGroup group at index in state.bindGroups:

    1. For each resource GPUBindingResource in the bind group:

      1. Let entry be the corresponding GPUBindGroupLayoutEntry for this resource.

      2. If entry.visibility includes VERTEX:

  4. Set the shader builtins:

    • Set the vertex_index builtin, if any, to vertexIndex.

    • Set the instance_index builtin, if any, to instanceIndex.

  5. Invoke the vertex shader entry point described by desc.

    Note: The target platform caches the results of vertex shader invocations. There is no guarantee that any vertexIndex that repeats more than once will result in multiple invocations. Similarly, there is no guarantee that a single vertexIndex will only be processed once.

22.3.3. Primitive Assembly

Primitives are assembled by a fixed-function stage of GPUs.

assemble primitives(vertexIndexList, drawCall, desc)

Arguments:

For each instance, the primitives get assembled from the vertices that have been processed by the shaders, based on the vertexIndexList.

  1. First, if the primitive topology is a strip, (which means that desc.stripIndexFormat is not undefined) and the drawCall is indexed, the vertexIndexList is split into sub-lists using the maximum value of desc.stripIndexFormat as a separator.

    Example: a vertexIndexList with values [1, 2, 65535, 4, 5, 6] of type "uint16" will be split in sub-lists [1, 2] and [4, 5, 6].

  2. For each of the sub-lists vl, primitive generation is done according to the desc.topology:

    "line-list"

    Line primitives are composed from (vl.0, vl.1), then (vl.2, vl.3), then (vl.4 to vl.5), etc. Each subsequent primitive takes 2 vertices.

    "line-strip"

    Line primitives are composed from (vl.0, vl.1), then (vl.1, vl.2), then (vl.2, vl.3), etc. Each subsequent primitive takes 1 vertex.

    "triangle-list"

    Triangle primitives are composed from (vl.0, vl.1, vl.2), then (vl.3, vl.4, vl.5), then (vl.6, vl.7, vl.8), etc. Each subsequent primitive takes 3 vertices.

    "triangle-strip"

    Triangle primitives are composed from (vl.0, vl.1, vl.2), then (vl.2, vl.1, vl.3), then (vl.2, vl.3, vl.4), then (vl.4, vl.3, vl.5), etc. Each subsequent primitive takes 1 vertices.

    should this be defined more formally?

    Any incomplete primitives are dropped.

22.3.4. Primitive Clipping

Vertex shaders have to produce a built-in "position" (of type vec4<f32>), which denotes the clip position of a vertex.

link to WGSL built-ins

Primitives are clipped to the clip volume, which, for any clip position p inside a primitive, is defined by the following inequalities:

If descriptor.primitive.unclippedDepth is true, depth clipping is not applied: the clip volume is not bounded in the z dimension.

A primitive passes through this stage unchanged if every one of its edges lie entirely inside the clip volume. If the edges of a primitives intersect the boundary of the clip volume, the intersecting edges are reconnected by new edges that lie along the boundary of the clip volume. For triangular primitives (descriptor.primitive.topology is "triangle-list" or "triangle-strip"), this reconnection may result in introduction of new vertices into the polygon, internally.

If a primitive intersects an edge of the clip volume’s boundary, the clipped polygon must include a point on this boundary edge.

If the vertex shader outputs other floating-point values (scalars and vectors), qualified with "perspective" interpolation, they also get clipped. The output values associated with a vertex that lies within the clip volume are unaffected by clipping. If a primitive is clipped, however, the output values assigned to vertices produced by clipping are clipped.

Considering an edge between vertices a and b that got clipped, resulting in the vertex c, let’s define t to be the ratio between the edge vertices: c.p = t × a.p + (1 − t) × b.p, where x.p is the output clip position of a vertex x.

For each vertex output value "v" with a corresponding fragment input, a.v and b.v would be the outputs for a and b vertices respectively. The clipped shader output c.v is produced based on the interpolation qualifier:

"flat"

Flat interpolation is unaffected, and is based on provoking vertex, which is the first vertex in the primitive. The output value is the same for the whole primitive, and matches the vertex output of the provoking vertex: c.v = provoking vertex.v

"linear"

The interpolation ratio gets adjusted against the perspective coordinates of the clip positions, so that the result of interpolation is linear in screen space.

provide more specifics here, if possible

"perspective"

The value is linearly interpolated in clip space, producing perspective-correct values:

c.v = t × a.v + (1 − t) × b.v

link to interpolation qualifiers in WGSL

The result of primitive clipping is a new set of primitives, which are contained within the clip volume.

22.3.5. Rasterization

Rasterization is the hardware processing stage that maps the generated primitives to the 2-dimensional rendering area of the framebuffer - the set of render attachments in the current GPURenderPassEncoder. This rendering area is split into an even grid of pixels.

Rasterization determines the set of pixels affected by a primitive. In case of multi-sampling, each pixel is further split into descriptor.multisample.count samples. The locations of samples are the same for each pixel, but not defined in this spec.

do we want to force-enable the "Standard sample locations" in Vulkan?

The framebuffer coordinates start from the top-left corner of the render targets. Each unit corresponds exactly to a pixel. See § 3.3 Coordinate Systems for more information.

Let’s define a FragmentDestination to contain:

position

the 2D pixel position in framebuffer space

sampleIndex

an integer in case § 22.3.10 Sample frequency shading is active, or null otherwise

We’ll also use a notion of NDC - normalized device coordinates. In this coordinate system, the viewport bounds range in X and Y from -1 to 1, and in Z from 0 to 1.

Rasterization produces a list of RasterizationPoints, each containing the following data:

destination

refers to FragmentDestination

coverageMask

refers to multisample coverage mask (see § 22.3.11 Sample Masking)

frontFacing

is true if it’s a point on the front face of a primitive

perspectiveDivisor

refers to interpolated 1.0 ÷ W across the primitive

depth

refers to the depth in NDC

primitiveVertices

refers to the list of vertex outputs forming the primitive

barycentricCoordinates

refers to § 22.3.5.3 Barycentric coordinates

define the depth computation algorithm

rasterize(primitiveList, state)

Arguments:

Returns: list of RasterizationPoint.

Each primitive in primitiveList is processed independently. However, the order of primitives affects later stages, such as depth/stencil operations and pixel writes.

  1. First, the clipped vertices are transformed into NDC - normalized device coordinates. Given the output position p, the NDC coordinates are computed as:

    divisor(p) = 1.0 ÷ p.w

    ndc(p) = vector(p.x ÷ p.w, p.y ÷ p.w, p.z ÷ p.w)

  2. Let vp be state.viewport. Then the NDC coordinates n are converted into framebuffer coordinates, based on the size of the render targets:

framebufferCoords(n) = vector(vp.x + 0.5 × (n.x + 1) × vp.width, vp.y + .5 × (n.y + 1) × vp.height)

specify the depth translation into viewport as well

  1. Let rasterizationPoints be an empty list.

specify that each rasterization point gets assigned an interpolated divisor(p) and framebufferCoords(n), as well as the other attributes.

  1. Proceed with a specific rasterization algorithm, depending on primitive.topology:

    "point-list"

    The point, if not filtered by § 22.3.4 Primitive Clipping, goes into § 22.3.5.1 Point Rasterization.

    "line-list" or "line-strip"

    The line cut by § 22.3.4 Primitive Clipping goes into § 22.3.5.2 Line Rasterization.

    "triangle-list" or "triangle-strip"

    The polygon produced in § 22.3.4 Primitive Clipping goes into § 22.3.5.4 Polygon Rasterization.

    reword the "goes into" part

  2. Remove all the points rp from rasterizationPoints that have rp.destination.position outside of state.scissorRect.

  3. Return rasterizationPoints.

22.3.5.1. Point Rasterization

A single FragmentDestination is selected within the pixel containing the framebuffer coordinates of the point.

The coverage mask depends on multi-sampling mode:

sample-frequency

coverageMask = 1 ≪ sampleIndex

pixel-frequency multi-sampling

coverageMask = 1 ≪ descriptor.multisample.count − 1

no multi-sampling

coverageMask = 1

22.3.5.2. Line Rasterization

fill out this section

22.3.5.3. Barycentric coordinates

Barycentric coordinates is a list of n numbers bi, defined for a point p inside a convex polygon with n vertices vi in framebuffer space. Each bi is in range 0 to 1, inclusive, and represents the proximity to vertex vi. Their sum is always constant:

∑ (bi) = 1

These coordinates uniquely specify any point p within the polygon (or on its boundary) as:

p = ∑ (bi × pi)

For a polygon with 3 vertices - a triangle, barycentric coordinates of any point p can be computed as follows:

Apolygon = A(v1, v2, v3) b1 = A(p, b2, b3) ÷ Apolygon b2 = A(b1, p, b3) ÷ Apolygon b3 = A(b1, b2, p) ÷ Apolygon

Where A(list of points) is the area of the polygon with the given set of vertices.

For polygons with more than 3 vertices, the exact algorithm is implementation-dependent. One of the possible implementations is to triangulate the polygon and compute the barycentrics of a point based on the triangle it falls into.

22.3.5.4. Polygon Rasterization

A polygon is front-facing if it’s oriented towards the projection. Otherwise, the polygon is back-facing.

rasterize polygon()

Arguments:

Returns: list of RasterizationPoint.

  1. Let rasterizationPoints be an empty list.

  2. Let v(i) be the framebuffer coordinates for the clipped vertex number i (starting with 1) in a rasterized polygon of n vertices.

    Note: this section uses the term "polygon" instead of a "triangle", since § 22.3.4 Primitive Clipping stage may have introduced additional vertices. This is non-observable by the application.

  3. Determine if the polygon is front-facing, which depends on the sign of the area occupied by the polygon in framebuffer coordinates:

    area = 0.5 × ((v1.x × vn.y − vn.x × v1.y) + ∑ (vi+1.x × vi.y − vi.x × vi+1.y))

    The sign of area is interpreted based on the primitive.frontFace:

    "ccw"

    area > 0 is considered front-facing, otherwise back-facing

    "cw"

    area < 0 is considered front-facing, otherwise back-facing

  4. Cull based on primitive.cullMode:

    "none"

    All polygons pass this test.

    "front"

    The front-facing polygons are discarded, and do not process in later stages of the render pipeline.

    "back"

    The back-facing polygons are discarded.

  5. Determine a set of fragments inside the polygon in framebuffer space - these are locations scheduled for the per-fragment operations. This operation is known as "point sampling". The logic is based on descriptor.multisample:

    disabled

    Fragments are associated with pixel centers. That is, all the points with coordinates C, where fract(C) = vector2(0.5, 0.5) in the framebuffer space, enclosed into the polygon, are included. If a pixel center is on the edge of the polygon, whether or not it’s included is not defined.

    Note: this becomes a subject of precision for the rasterizer.

    enabled

    Each pixel is associated with descriptor.multisample.count locations, which are implementation-defined. The locations are ordered, and the list is the same for each pixel of the framebuffer. Each location corresponds to one fragment in the multisampled framebuffer.

    The rasterizer builds a mask of locations being hit inside each pixel and provides is as "sample-mask" built-in to the fragment shader.

  6. For each produced fragment of type FragmentDestination:

    1. Let rp be a new RasterizationPoint object

    2. Compute the list b as § 22.3.5.3 Barycentric coordinates of that fragment. Set rp.barycentricCoordinates to b.

    3. Let di be the depth value of vi.

      define how this value is constructed.

    4. Set rp.depth to ∑ (bi × di)

    5. Append rp to rasterizationPoints.

  7. Return rasterizationPoints.

22.3.6. Fragment Processing

The fragment processing stage is a programmable stage of the render pipeline that computes the fragment data (often a color) to be written into render targets.

This stage produces a Fragment for each RasterizationPoint:

process fragment(rp, desc, state)

Arguments:

Returns: Fragment or null.

  1. Let fragment be a new Fragment object.

  2. Set fragment.destination to rp.destination.

  3. Set fragment.coverageMask to rp.coverageMask.

  4. Set fragment.depth to rp.depth.

  5. If desc is not null:

    1. Set the shader input builtins. For each non-composite argument of the entry point, annotated as a builtin, set its value based on the annotation:

      position

      vec4<f32>(rp.destination.position, rp.depth, rp.perspectiveDivisor)

      front_facing

      rp.frontFacing

      sample_index

      rp.destination.sampleIndex

      sample_mask

      rp.coverageMask

    2. For each user-specified pipeline input of the fragment stage:

      1. Let value be the interpolated fragment input, based on rp.barycentricCoordinates, rp.primitiveVertices, and the interpolation qualifier on the input.

        describe the exact equations.

      2. Set the corresponding fragment shader location input to value.

    3. Invoke the fragment shader entry point described by desc.

    4. If the fragment issued discard, return null.

    5. Set fragment.colors to the user-specified pipeline output values from the shader.

    6. Take the shader output builtins:

      1. If frag_depth builtin is produced by the shader as value:

        1. Let vp be state.viewport.

        2. Set fragment.depth to clamp(value, vp.minDepth, vp.maxDepth).

    7. If sample_mask builtin is produced by the shader as value:

      1. Set fragment.coverageMask to fragment.coverageMaskvalue.

    Otherwise we are in § 22.3.8 No Color Output mode, and fragment.colors is empty.

  6. Return fragment.

Processing of fragments happens in parallel, while any side effects, such as writes into GPUBufferBindingType."storage" bindings, may happen in any order.

22.3.7. Output Merging

fill out this section

The depth input to this stage, if any, is clamped to the current [[viewport]] depth range (regardless of whether the fragment shader stage writes the frag_depth builtin).

22.3.8. No Color Output

In no-color-output mode, pipeline does not produce any color attachment outputs.

The pipeline still performs rasterization and produces depth values based on the vertex position output. The depth testing and stencil operations can still be used.

22.3.9. Alpha to Coverage

In alpha-to-coverage mode, an additional alpha-to-coverage mask of MSAA samples is generated based on the alpha component of the fragment shader output value of the fragment.targets[0].

The algorithm of producing the extra mask is platform-dependent and can vary for different pixels. It guarantees that:

22.3.10. Sample frequency shading

fill out the section

22.3.11. Sample Masking

The final sample mask for a pixel is computed as: rasterization mask & mask & shader-output mask.

Only the lower count bits of the mask are considered.

If the least-significant bit at position N of the final sample mask has value of "0", the sample color outputs (corresponding to sample N) to all attachments of the fragment shader are discarded. Also, no depth test or stencil operations are executed on the relevant samples of the depth-stencil attachment.

Note: the color output for sample N is produced by the fragment shader execution with SV_SampleIndex == N for the current pixel. If the fragment shader doesn’t use this semantics, it’s only executed once per pixel.

The rasterization mask is produced by the rasterization stage, based on the shape of the rasterized polygon. The samples included in the shape get the relevant bits 1 in the mask.

The shader-output mask takes the output value of "sample_mask" builtin in the fragment shader. If the builtin is not output from the fragment shader, and alphaToCoverageEnabled is enabled, the shader-output mask becomes the alpha-to-coverage mask. Otherwise, it defaults to 0xFFFFFFFF.

23. Type Definitions

typedef [EnforceRange] unsigned long GPUBufferDynamicOffset;
typedef [EnforceRange] unsigned long GPUStencilValue;
typedef [EnforceRange] unsigned long GPUSampleMask;
typedef [EnforceRange] long GPUDepthBias;

typedef [EnforceRange] unsigned long long GPUSize64;
typedef [EnforceRange] unsigned long GPUIntegerCoordinate;
typedef [EnforceRange] unsigned long GPUIndex32;
typedef [EnforceRange] unsigned long GPUSize32;
typedef [EnforceRange] long GPUSignedOffset32;

typedef unsigned long GPUFlagsConstant;

23.1. Colors & Vectors

dictionary GPUColorDict {
    required double r;
    required double g;
    required double b;
    required double a;
};
typedef (sequence<double> or GPUColorDict) GPUColor;

Note: double is large enough to precisely hold 32-bit signed/unsigned integers and single-precision floats.

dictionary GPUOrigin2DDict {
    GPUIntegerCoordinate x = 0;
    GPUIntegerCoordinate y = 0;
};
typedef (sequence<GPUIntegerCoordinate> or GPUOrigin2DDict) GPUOrigin2D;

An Origin2D is a GPUOrigin2D. Origin2D is a spec namespace for the following definitions:

For a given GPUOrigin2D value origin, depending on its type, the syntax:
dictionary GPUOrigin3DDict {
    GPUIntegerCoordinate x = 0;
    GPUIntegerCoordinate y = 0;
    GPUIntegerCoordinate z = 0;
};
typedef (sequence<GPUIntegerCoordinate> or GPUOrigin3DDict) GPUOrigin3D;

An Origin3D is a GPUOrigin3D. Origin3D is a spec namespace for the following definitions:

For a given GPUOrigin3D value origin, depending on its type, the syntax:
dictionary GPUExtent3DDict {
    required GPUIntegerCoordinate width;
    GPUIntegerCoordinate height = 1;
    GPUIntegerCoordinate depthOrArrayLayers = 1;
};
typedef (sequence<GPUIntegerCoordinate> or GPUExtent3DDict) GPUExtent3D;

An Extent3D is a GPUExtent3D. Extent3D is a spec namespace for the following definitions:

For a given GPUExtent3D value extent, depending on its type, the syntax:

24. Feature Index

24.1. "depth-clip-control"

Define functionality when the "depth-clip-control" feature is enabled.

Feature Dictionary Values

The following dictionary values are supported if and only if the "depth-clip-control" feature is enabled; otherwise, they must be set to their default values:

GPUPrimitiveState

24.2. "depth32float-stencil8"

Allows for explicit creation of textures of format "depth32float-stencil8".

Feature Enums

The following enums are supported if and only if the "depth32float-stencil8" feature is enabled:

GPUTextureFormat

24.3. "texture-compression-bc"

Allows for explicit creation of textures of BC compressed formats.

Feature Enums

The following enums are supported if and only if the "texture-compression-bc" feature is enabled:

GPUTextureFormat

24.4. "texture-compression-etc2"

Allows for explicit creation of textures of ETC2 compressed formats.

Feature Enums

The following enums are supported if and only if the "texture-compression-etc2" feature is enabled:

GPUTextureFormat

24.5. "texture-compression-astc"

Allows for explicit creation of textures of ASTC compressed formats.

Feature Enums

The following enums are supported if and only if the "texture-compression-astc" feature is enabled:

GPUTextureFormat

24.6. "timestamp-query"

Define functionality when the "timestamp-query" feature is enabled.

Feature Enums

The following enums are supported if and only if the "timestamp-query" feature is enabled:

GPUQueryType

24.7. "indirect-first-instance"

Removes the zero value restriction on firstInstance in indirect draw parameters and indirect drawIndexed parameters. firstInstance is allowed to be non-zero if and only if the "indirect-first-instance" feature is enabled.

24.8. "shader-f16"

Using "enable f16;" directive in WGSL code for a shader module is allowed if and only if the "shader-f16" feature is enabled; otherwise using it must result in a compilation error when creating shader module.

24.9. "bgra8unorm-storage"

Allows the STORAGE_BINDING usage on textures with format "bgra8unorm".

25. Appendices

25.1. Texture Format Capabilities

25.1.1. Plain color formats

All plain color formats support COPY_SRC, COPY_DST, and TEXTURE_BINDING usage.

Only formats with GPUTextureSampleType "float" can be blended.

The RENDER_ATTACHMENT and STORAGE_BINDING columns specify support for GPUTextureUsage.RENDER_ATTACHMENT and GPUTextureUsage.STORAGE_BINDING usage respectively.

Format GPUTextureSampleType RENDER_ATTACHMENT multisampling resolve STORAGE_BINDING Texel block size (Bytes)
8-bit per component
r8unorm "float",
"unfilterable-float"
1
r8snorm "float",
"unfilterable-float"
1
r8uint "uint" 1
r8sint "sint" 1
rg8unorm "float",
"unfilterable-float"
2
rg8snorm "float",
"unfilterable-float"
2
rg8uint "uint" 2
rg8sint "sint" 2
rgba8unorm "float",
"unfilterable-float"
4
rgba8unorm-srgb "float",
"unfilterable-float"
4
rgba8snorm "float",
"unfilterable-float"
4
rgba8uint "uint" 4
rgba8sint "sint" 4
bgra8unorm "float",
"unfilterable-float"
If "bgra8unorm-storage" is enabled 4
bgra8unorm-srgb "float",
"unfilterable-float"
4
16-bit per component
r16uint "uint" 2
r16sint "sint" 2
r16float "float",
"unfilterable-float"
2
rg16uint "uint" 4
rg16sint "sint" 4
rg16float "float",
"unfilterable-float"
4
rgba16uint "uint" 8
rgba16sint "sint" 8
rgba16float "float",
"unfilterable-float"
8
32-bit per component
r32uint "uint" 4
r32sint "sint" 4
r32float "unfilterable-float" 4
rg32uint "uint" 8
rg32sint "sint" 8
rg32float "unfilterable-float" 8
rgba32uint "uint" 16
rgba32sint "sint" 16
rgba32float "unfilterable-float" 16
mixed component width
rgb10a2unorm "float",
"unfilterable-float"
4
rg11b10ufloat "float",
"unfilterable-float"
4

25.1.2. Depth-stencil formats

A depth-or-stencil format is any format with depth and/or stencil aspects. A combined depth-stencil format is a depth-or-stencil format that has both depth and stencil aspects.

All depth-or-stencil formats support the COPY_SRC, COPY_DST, TEXTURE_BINDING, and RENDER_ATTACHMENT usages. All of these formats support multisampling. However, certain copy operations also restrict the source and destination formats.

Depth textures cannot be used with "filtering" samplers, but can always be used with "comparison" samplers (which may use filtering).

Format Bytes per texel Aspect Texel block size (Bytes) GPUTextureSampleType Valid image copy source Valid image copy destination Aspect-specific format
stencil8 1 − 4 stencil 1 "uint" stencil8
depth16unorm 2 depth 2 "depth" depth16unorm
depth24plus 4 depth - (See prose) "depth" depth24plus
depth24plus-stencil8 4 − 8 depth - (See prose) "depth" depth24plus
stencil 1 "uint" stencil8
depth32float 4 depth 4 "depth" depth32float
depth32float-stencil8 5 − 8 depth 4 "depth" depth32float
stencil 1 "uint" stencil8
25.1.2.1. Reading and Sampling Depth/Stencil Textures

It is possible to bind a depth-aspect GPUTextureView to either a texture_depth_* binding or a binding with other non-depth 2d/cube texture types. In both cases, the sampleType in the GPUBindGroupLayout must be "depth".

A stencil-aspect GPUTextureView must be bound to a normal texture binding type. The sampleType in the GPUBindGroupLayout must be "uint".

Reading or sampling the depth or stencil aspect of a texture behaves as if the texture contains the values (V, X, X, X), where V is the actual depth or stencil value, and each X is an implementation-defined unspecified value.

For depth-aspect bindings, the unspecified values are not visible through bindings with texture_depth_* types.

If a depth texture is bound to tex with type texture_2d<f32>:

Note: Short of adding a new more constrained stencil sampler type (like depth), it’s infeasible for implementations to efficiently paper over the driver differences for depth/stencil reads. As this was not a portability pain point for WebGL, it’s not expected to be problematic in WebGPU. In practice, expect either (V, V, V, V) or (V, 0, 0, 1) (where V is the depth or stencil value), depending on hardware.

25.1.2.2. Copying Depth/Stencil Textures

The texel values of depth32float formats ("depth32float" and "depth32float-stencil8" have a limited range. As a result, copies into such textures are only valid from other textures of the same format.

The depth aspects of depth24plus formats ("depth24plus" and "depth24plus-stencil8") have opaque representations (implemented as either "depth24unorm" or "depth32float"). As a result, depth-aspect image copies are not allowed with these formats.

It is possible to imitate these disallowed copies:

25.1.3. Packed formats

All packed texture formats support COPY_SRC, COPY_DST, and TEXTURE_BINDING usages. All of these formats have "float" type and can be filtered on sampling. None of these formats support multisampling.

A compressed format is any format with a block size greater than 1 × 1.

The texel block size (in bytes) of a packed format is equal to the Bytes per block column below.

Format Bytes per block GPUTextureSampleType Block Size Feature
rgb9e5ufloat 4 "float",
"unfilterable-float"
1 × 1
bc1-rgba-unorm 8 "float",
"unfilterable-float"
4 × 4 texture-compression-bc
bc1-rgba-unorm-srgb
bc2-rgba-unorm 16
bc2-rgba-unorm-srgb
bc3-rgba-unorm 16
bc3-rgba-unorm-srgb
bc4-r-unorm 8
bc4-r-snorm
bc5-rg-unorm 16
bc5-rg-snorm
bc6h-rgb-ufloat 16
bc6h-rgb-float
bc7-rgba-unorm 16
bc7-rgba-unorm-srgb
etc2-rgb8unorm 8 "float",
"unfilterable-float"
4 × 4 texture-compression-etc2
etc2-rgb8unorm-srgb
etc2-rgb8a1unorm 8
etc2-rgb8a1unorm-srgb
etc2-rgba8unorm 16
etc2-rgba8unorm-srgb
eac-r11unorm 8
eac-r11snorm
eac-rg11unorm 16
eac-rg11snorm
astc-4x4-unorm 16 "float",
"unfilterable-float"
4 × 4 texture-compression-astc
astc-4x4-unorm-srgb
astc-5x4-unorm 16 5 × 4
astc-5x4-unorm-srgb
astc-5x5-unorm 16 5 × 5
astc-5x5-unorm-srgb
astc-6x5-unorm 16 6 × 5
astc-6x5-unorm-srgb
astc-6x6-unorm 16 6 × 6
astc-6x6-unorm-srgb
astc-8x5-unorm 16 8 × 5
astc-8x5-unorm-srgb
astc-8x6-unorm 16 8 × 6
astc-8x6-unorm-srgb
astc-8x8-unorm 16 8 × 8
astc-8x8-unorm-srgb
astc-10x5-unorm 16 10 × 5
astc-10x5-unorm-srgb
astc-10x6-unorm 16 10 × 6
astc-10x6-unorm-srgb
astc-10x8-unorm 16 10 × 8
astc-10x8-unorm-srgb
astc-10x10-unorm 16 10 × 10
astc-10x10-unorm-srgb
astc-12x10-unorm 16 12 × 10
astc-12x10-unorm-srgb
astc-12x12-unorm 16 12 × 12
astc-12x12-unorm-srgb

25.2. Temporary usages of non-exported dfns

x y renderExtent

Eventually all of these should disappear but they are useful to avoid warning while building the specification.

vertex buffer

Conformance

Document conventions

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

Conformant Algorithms

Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and abort these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm.

Conformance requirements phrased as algorithms or specific steps can be implemented in any manner, so long as the end result is equivalent. In particular, the algorithms defined in this specification are intended to be easy to understand and are not intended to be performant. Implementers are encouraged to optimize.

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[DOM]
Anne van Kesteren. DOM Standard. Living Standard. URL: https://dom.spec.whatwg.org/
[ECMASCRIPT]
ECMAScript Language Specification. URL: https://tc39.es/ecma262/multipage/
[HTML]
Anne van Kesteren; et al. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[INFRA]
Anne van Kesteren; Domenic Denicola. Infra Standard. Living Standard. URL: https://infra.spec.whatwg.org/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc2119
[WEBGL-1]
Dean Jackson; Jeff Gilbert. WebGL Specification, Version 1.0. 9 August 2017. URL: https://www.khronos.org/registry/webgl/specs/latest/1.0/
[WEBIDL]
Edgar Chen; Timothy Gu. Web IDL Standard. Living Standard. URL: https://webidl.spec.whatwg.org/
[WGSL]
David Neto; Myles Maxfield. WebGPU Shading Language. 27 June 2022. WD. URL: https://www.w3.org/TR/WGSL/

Informative References

[SourceMap]
John Lenz; Nick Fitzgerald. Source Map Revision 3 Proposal. URL: https://sourcemaps.info/spec.html

IDL Index

interface mixin GPUObjectBase {
    attribute USVString label;
};

dictionary GPUObjectDescriptorBase {
    USVString label;
};

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

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

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

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

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

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

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

[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(optional sequence<DOMString> unmaskHints = []);
};

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

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

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

[Exposed=(Window, DedicatedWorker), SecureContext]
interface GPUBuffer {
    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();

    readonly attribute GPUSize64 size;
    readonly attribute GPUBufferUsageFlags usage;
};
GPUBuffer includes GPUObjectBase;

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

typedef [EnforceRange] unsigned long GPUBufferUsageFlags;
[Exposed=(Window, DedicatedWorker)]
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;
};

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

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

    undefined destroy();

    readonly attribute GPUIntegerCoordinate width;
    readonly attribute GPUIntegerCoordinate height;
    readonly attribute GPUIntegerCoordinate depthOrArrayLayers;
    readonly attribute GPUIntegerCoordinate mipLevelCount;
    readonly attribute GPUSize32 sampleCount;
    readonly attribute GPUTextureDimension dimension;
    readonly attribute GPUTextureFormat format;
    readonly attribute GPUTextureUsageFlags usage;
};
GPUTexture includes GPUObjectBase;

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

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

typedef [EnforceRange] unsigned long GPUTextureUsageFlags;
[Exposed=(Window, DedicatedWorker)]
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;
};

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

dictionary GPUTextureViewDescriptor : GPUObjectDescriptorBase {
    GPUTextureFormat format;
    GPUTextureViewDimension dimension;
    GPUTextureAspect aspect = "all";
    GPUIntegerCoordinate baseMipLevel = 0;
    GPUIntegerCoordinate mipLevelCount;
    GPUIntegerCoordinate baseArrayLayer = 0;
    GPUIntegerCoordinate arrayLayerCount;
};

enum GPUTextureViewDimension {
    "1d",
    "2d",
    "2d-array",
    "cube",
    "cube-array",
    "3d"
};

enum GPUTextureAspect {
    "all",
    "stencil-only",
    "depth-only"
};

enum GPUTextureFormat {
    // 8-bit formats
    "r8unorm",
    "r8snorm",
    "r8uint",
    "r8sint",

    // 16-bit formats
    "r16uint",
    "r16sint",
    "r16float",
    "rg8unorm",
    "rg8snorm",
    "rg8uint",
    "rg8sint",

    // 32-bit formats
    "r32uint",
    "r32sint",
    "r32float",
    "rg16uint",
    "rg16sint",
    "rg16float",
    "rgba8unorm",
    "rgba8unorm-srgb",
    "rgba8snorm",
    "rgba8uint",
    "rgba8sint",
    "bgra8unorm",
    "bgra8unorm-srgb",
    // Packed 32-bit formats
    "rgb9e5ufloat",
    "rgb10a2unorm",
    "rg11b10ufloat",

    // 64-bit formats
    "rg32uint",
    "rg32sint",
    "rg32float",
    "rgba16uint",
    "rgba16sint",
    "rgba16float",

    // 128-bit formats
    "rgba32uint",
    "rgba32sint",
    "rgba32float",

    // Depth/stencil formats
    "stencil8",
    "depth16unorm",
    "depth24plus",
    "depth24plus-stencil8",
    "depth32float",

    // "depth32float-stencil8" feature
    "depth32float-stencil8",

    // BC compressed formats usable if "texture-compression-bc" is both
    // supported by the device/user agent and enabled in requestDevice.
    "bc1-rgba-unorm",
    "bc1-rgba-unorm-srgb",
    "bc2-rgba-unorm",
    "bc2-rgba-unorm-srgb",
    "bc3-rgba-unorm",
    "bc3-rgba-unorm-srgb",
    "bc4-r-unorm",
    "bc4-r-snorm",
    "bc5-rg-unorm",
    "bc5-rg-snorm",
    "bc6h-rgb-ufloat",
    "bc6h-rgb-float",
    "bc7-rgba-unorm",
    "bc7-rgba-unorm-srgb",

    // ETC2 compressed formats usable if "texture-compression-etc2" is both
    // supported by the device/user agent and enabled in requestDevice.
    "etc2-rgb8unorm",
    "etc2-rgb8unorm-srgb",
    "etc2-rgb8a1unorm",
    "etc2-rgb8a1unorm-srgb",
    "etc2-rgba8unorm",
    "etc2-rgba8unorm-srgb",
    "eac-r11unorm",
    "eac-r11snorm",
    "eac-rg11unorm",
    "eac-rg11snorm",

    // ASTC compressed formats usable if "texture-compression-astc" is both
    // supported by the device/user agent and enabled in requestDevice.
    "astc-4x4-unorm",
    "astc-4x4-unorm-srgb",
    "astc-5x4-unorm",
    "astc-5x4-unorm-srgb",
    "astc-5x5-unorm",
    "astc-5x5-unorm-srgb",
    "astc-6x5-unorm",
    "astc-6x5-unorm-srgb",
    "astc-6x6-unorm",
    "astc-6x6-unorm-srgb",
    "astc-8x5-unorm",
    "astc-8x5-unorm-srgb",
    "astc-8x6-unorm",
    "astc-8x6-unorm-srgb",
    "astc-8x8-unorm",
    "astc-8x8-unorm-srgb",
    "astc-10x5-unorm",
    "astc-10x5-unorm-srgb",
    "astc-10x6-unorm",
    "astc-10x6-unorm-srgb",
    "astc-10x8-unorm",
    "astc-10x8-unorm-srgb",
    "astc-10x10-unorm",
    "astc-10x10-unorm-srgb",
    "astc-12x10-unorm",
    "astc-12x10-unorm-srgb",
    "astc-12x12-unorm",
    "astc-12x12-unorm-srgb"
};

[Exposed=(Window, DedicatedWorker), SecureContext]
interface GPUExternalTexture {
    readonly attribute boolean expired;
};
GPUExternalTexture includes GPUObjectBase;

dictionary GPUExternalTextureDescriptor : GPUObjectDescriptorBase {
    required HTMLVideoElement source;
    PredefinedColorSpace colorSpace = "srgb";
};

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

dictionary GPUSamplerDescriptor : GPUObjectDescriptorBase {
    GPUAddressMode addressModeU = "clamp-to-edge";
    GPUAddressMode addressModeV = "clamp-to-edge";
    GPUAddressMode addressModeW = "clamp-to-edge";
    GPUFilterMode magFilter = "nearest";
    GPUFilterMode minFilter = "nearest";
    GPUMipmapFilterMode mipmapFilter = "nearest";
    float lodMinClamp = 0;
    float lodMaxClamp = 32;
    GPUCompareFunction compare;
    [Clamp] unsigned short maxAnisotropy = 1;
};

enum GPUAddressMode {
    "clamp-to-edge",
    "repeat",
    "mirror-repeat"
};

enum GPUFilterMode {
    "nearest",
    "linear"
};

enum GPUMipmapFilterMode {
    "nearest",
    "linear"
};

enum GPUCompareFunction {
    "never",
    "less",
    "equal",
    "less-equal",
    "greater",
    "not-equal",
    "greater-equal",
    "always"
};

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

dictionary GPUBindGroupLayoutDescriptor : GPUObjectDescriptorBase {
    required sequence<GPUBindGroupLayoutEntry> entries;
};

dictionary GPUBindGroupLayoutEntry {
    required GPUIndex32 binding;
    required GPUShaderStageFlags visibility;

    GPUBufferBindingLayout buffer;
    GPUSamplerBindingLayout sampler;
    GPUTextureBindingLayout texture;
    GPUStorageTextureBindingLayout storageTexture;
    GPUExternalTextureBindingLayout externalTexture;
};

typedef [EnforceRange] unsigned long GPUShaderStageFlags;
[Exposed=(Window, DedicatedWorker)]
namespace GPUShaderStage {
    const GPUFlagsConstant VERTEX   = 0x1;
    const GPUFlagsConstant FRAGMENT = 0x2;
    const GPUFlagsConstant COMPUTE  = 0x4;
};

enum GPUBufferBindingType {
    "uniform",
    "storage",
    "read-only-storage"
};

dictionary GPUBufferBindingLayout {
    GPUBufferBindingType type = "uniform";
    boolean hasDynamicOffset = false;
    GPUSize64 minBindingSize = 0;
};

enum GPUSamplerBindingType {
    "filtering",
    "non-filtering",
    "comparison"
};

dictionary GPUSamplerBindingLayout {
    GPUSamplerBindingType type = "filtering";
};

enum GPUTextureSampleType {
    "float",
    "unfilterable-float",
    "depth",
    "sint",
    "uint"
};

dictionary GPUTextureBindingLayout {
    GPUTextureSampleType sampleType = "float";
    GPUTextureViewDimension viewDimension = "2d";
    boolean multisampled = false;
};

enum GPUStorageTextureAccess {
    "write-only"
};

dictionary GPUStorageTextureBindingLayout {
    GPUStorageTextureAccess access = "write-only";
    required GPUTextureFormat format;
    GPUTextureViewDimension viewDimension = "2d";
};

dictionary GPUExternalTextureBindingLayout {
};

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

dictionary GPUBindGroupDescriptor : GPUObjectDescriptorBase {
    required GPUBindGroupLayout layout;
    required sequence<GPUBindGroupEntry> entries;
};

typedef (GPUSampler or GPUTextureView or GPUBufferBinding or GPUExternalTexture) GPUBindingResource;

dictionary GPUBindGroupEntry {
    required GPUIndex32 binding;
    required GPUBindingResource resource;
};

dictionary GPUBufferBinding {
    required GPUBuffer buffer;
    GPUSize64 offset = 0;
    GPUSize64 size;
};

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

dictionary GPUPipelineLayoutDescriptor : GPUObjectDescriptorBase {
    required sequence<GPUBindGroupLayout> bindGroupLayouts;
};

[Exposed=(Window, DedicatedWorker), SecureContext]
interface GPUShaderModule {
    Promise<GPUCompilationInfo> compilationInfo();
};
GPUShaderModule includes GPUObjectBase;

dictionary GPUShaderModuleDescriptor : GPUObjectDescriptorBase {
    required USVString code;
    object sourceMap;
    record<USVString, GPUShaderModuleCompilationHint> hints;
};

dictionary GPUShaderModuleCompilationHint {
    (GPUPipelineLayout or GPUAutoLayoutMode) layout;
};

enum GPUCompilationMessageType {
    "error",
    "warning",
    "info"
};

[Exposed=(Window, DedicatedWorker), Serializable, SecureContext]
interface GPUCompilationMessage {
    readonly attribute DOMString message;
    readonly attribute GPUCompilationMessageType type;
    readonly attribute unsigned long long lineNum;
    readonly attribute unsigned long long linePos;
    readonly attribute unsigned long long offset;
    readonly attribute unsigned long long length;
};

[Exposed=(Window, DedicatedWorker), Serializable, SecureContext]
interface GPUCompilationInfo {
    readonly attribute FrozenArray<GPUCompilationMessage> messages;
};

enum GPUAutoLayoutMode {
    "auto"
};

dictionary GPUPipelineDescriptorBase : GPUObjectDescriptorBase {
    required (GPUPipelineLayout or GPUAutoLayoutMode) layout;
};

interface mixin GPUPipelineBase {
    [NewObject] GPUBindGroupLayout getBindGroupLayout(unsigned long index);
};

dictionary GPUProgrammableStage {
    required GPUShaderModule module;
    required USVString entryPoint;
    record<USVString, GPUPipelineConstantValue> constants;
};

typedef double GPUPipelineConstantValue; // May represent WGSL’s bool, f32, i32, u32, and f16 if enabled.

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

dictionary GPUComputePipelineDescriptor : GPUPipelineDescriptorBase {
    required GPUProgrammableStage compute;
};

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

dictionary GPURenderPipelineDescriptor : GPUPipelineDescriptorBase {
    required GPUVertexState vertex;
    GPUPrimitiveState primitive = {};
    GPUDepthStencilState depthStencil;
    GPUMultisampleState multisample = {};
    GPUFragmentState fragment;
};

dictionary GPUPrimitiveState {
    GPUPrimitiveTopology topology = "triangle-list";
    GPUIndexFormat stripIndexFormat;
    GPUFrontFace frontFace = "ccw";
    GPUCullMode cullMode = "none";

    // Requires "depth-clip-control" feature.
    boolean unclippedDepth = false;
};

enum GPUPrimitiveTopology {
    "point-list",
    "line-list",
    "line-strip",
    "triangle-list",
    "triangle-strip"
};

enum GPUFrontFace {
    "ccw",
    "cw"
};

enum GPUCullMode {
    "none",
    "front",
    "back"
};

dictionary GPUMultisampleState {
    GPUSize32 count = 1;
    GPUSampleMask mask = 0xFFFFFFFF;
    boolean alphaToCoverageEnabled = false;
};

dictionary GPUFragmentState : GPUProgrammableStage {
    required sequence<GPUColorTargetState?> targets;
};

dictionary GPUColorTargetState {
    required GPUTextureFormat format;

    GPUBlendState blend;
    GPUColorWriteFlags writeMask = 0xF;  // GPUColorWrite.ALL
};

dictionary GPUBlendState {
    required GPUBlendComponent color;
    required GPUBlendComponent alpha;
};

typedef [EnforceRange] unsigned long GPUColorWriteFlags;
[Exposed=(Window, DedicatedWorker)]
namespace GPUColorWrite {
    const GPUFlagsConstant RED   = 0x1;
    const GPUFlagsConstant GREEN = 0x2;
    const GPUFlagsConstant BLUE  = 0x4;
    const GPUFlagsConstant ALPHA = 0x8;
    const GPUFlagsConstant ALL   = 0xF;
};

dictionary GPUBlendComponent {
    GPUBlendOperation operation = "add";
    GPUBlendFactor srcFactor = "one";
    GPUBlendFactor dstFactor = "zero";
};

enum GPUBlendFactor {
    "zero",
    "one",
    "src",
    "one-minus-src",
    "src-alpha",
    "one-minus-src-alpha",
    "dst",
    "one-minus-dst",
    "dst-alpha",
    "one-minus-dst-alpha",
    "src-alpha-saturated",
    "constant",
    "one-minus-constant"
};

enum GPUBlendOperation {
    "add",
    "subtract",
    "reverse-subtract",
    "min",
    "max"
};

dictionary GPUDepthStencilState {
    required GPUTextureFormat format;

    boolean depthWriteEnabled = false;
    GPUCompareFunction depthCompare = "always";

    GPUStencilFaceState stencilFront = {};
    GPUStencilFaceState stencilBack = {};

    GPUStencilValue stencilReadMask = 0xFFFFFFFF;
    GPUStencilValue stencilWriteMask = 0xFFFFFFFF;

    GPUDepthBias depthBias = 0;
    float depthBiasSlopeScale = 0;
    float depthBiasClamp = 0;
};

dictionary GPUStencilFaceState {
    GPUCompareFunction compare = "always";
    GPUStencilOperation failOp = "keep";
    GPUStencilOperation depthFailOp = "keep";
    GPUStencilOperation passOp = "keep";
};

enum GPUStencilOperation {
    "keep",
    "zero",
    "replace",
    "invert",
    "increment-clamp",
    "decrement-clamp",
    "increment-wrap",
    "decrement-wrap"
};

enum GPUIndexFormat {
    "uint16",
    "uint32"
};

enum GPUVertexFormat {
    "uint8x2",
    "uint8x4",
    "sint8x2",
    "sint8x4",
    "unorm8x2",
    "unorm8x4",
    "snorm8x2",
    "snorm8x4",
    "uint16x2",
    "uint16x4",
    "sint16x2",
    "sint16x4",
    "unorm16x2",
    "unorm16x4",
    "snorm16x2",
    "snorm16x4",
    "float16x2",
    "float16x4",
    "float32",
    "float32x2",
    "float32x3",
    "float32x4",
    "uint32",
    "uint32x2",
    "uint32x3",
    "uint32x4",
    "sint32",
    "sint32x2",
    "sint32x3",
    "sint32x4"
};

enum GPUVertexStepMode {
    "vertex",
    "instance"
};

dictionary GPUVertexState : GPUProgrammableStage {
    sequence<GPUVertexBufferLayout?> buffers = [];
};

dictionary GPUVertexBufferLayout {
    required GPUSize64 arrayStride;
    GPUVertexStepMode stepMode = "vertex";
    required sequence<GPUVertexAttribute> attributes;
};

dictionary GPUVertexAttribute {
    required GPUVertexFormat format;
    required GPUSize64 offset;

    required GPUIndex32 shaderLocation;
};

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

dictionary GPUCommandBufferDescriptor : GPUObjectDescriptorBase {
};

interface mixin GPUCommandsMixin {
};

[Exposed=(Window, DedicatedWorker), SecureContext]
interface GPUCommandEncoder {
    GPURenderPassEncoder beginRenderPass(GPURenderPassDescriptor descriptor);
    GPUComputePassEncoder beginComputePass(optional GPUComputePassDescriptor descriptor = {});

    undefined copyBufferToBuffer(
        GPUBuffer source,
        GPUSize64 sourceOffset,
        GPUBuffer destination,
        GPUSize64 destinationOffset,
        GPUSize64 size);

    undefined copyBufferToTexture(
        GPUImageCopyBuffer source,
        GPUImageCopyTexture destination,
        GPUExtent3D copySize);

    undefined copyTextureToBuffer(
        GPUImageCopyTexture source,
        GPUImageCopyBuffer destination,
        GPUExtent3D copySize);

    undefined copyTextureToTexture(
        GPUImageCopyTexture source,
        GPUImageCopyTexture destination,
        GPUExtent3D copySize);

    undefined clearBuffer(
        GPUBuffer buffer,
        optional GPUSize64 offset = 0,
        optional GPUSize64 size);

    undefined writeTimestamp(GPUQuerySet querySet, GPUSize32 queryIndex);

    undefined resolveQuerySet(
        GPUQuerySet querySet,
        GPUSize32 firstQuery,
        GPUSize32 queryCount,
        GPUBuffer destination,
        GPUSize64 destinationOffset);

    GPUCommandBuffer finish(optional GPUCommandBufferDescriptor descriptor = {});
};
GPUCommandEncoder includes GPUObjectBase;
GPUCommandEncoder includes GPUCommandsMixin;
GPUCommandEncoder includes GPUDebugCommandsMixin;

dictionary GPUCommandEncoderDescriptor : GPUObjectDescriptorBase {
};

dictionary GPUImageDataLayout {
    GPUSize64 offset = 0;
    GPUSize32 bytesPerRow;
    GPUSize32 rowsPerImage;
};

dictionary GPUImageCopyBuffer : GPUImageDataLayout {
    required GPUBuffer buffer;
};

dictionary GPUImageCopyTexture {
    required GPUTexture texture;
    GPUIntegerCoordinate mipLevel = 0;
    GPUOrigin3D origin = {};
    GPUTextureAspect aspect = "all";
};

dictionary GPUImageCopyTextureTagged : GPUImageCopyTexture {
    PredefinedColorSpace colorSpace = "srgb";
    boolean premultipliedAlpha = false;
};

dictionary GPUImageCopyExternalImage {
    required (ImageBitmap or HTMLCanvasElement or OffscreenCanvas) source;
    GPUOrigin2D origin = {};
    boolean flipY = false;
};

interface mixin GPUBindingCommandsMixin {
    undefined setBindGroup(GPUIndex32 index, GPUBindGroup bindGroup,
                      optional sequence<GPUBufferDynamicOffset> dynamicOffsets = []);

    undefined setBindGroup(GPUIndex32 index, GPUBindGroup bindGroup,
                      Uint32Array dynamicOffsetsData,
                      GPUSize64 dynamicOffsetsDataStart,
                      GPUSize32 dynamicOffsetsDataLength);
};

interface mixin GPUDebugCommandsMixin {
    undefined pushDebugGroup(USVString groupLabel);
    undefined popDebugGroup();
    undefined insertDebugMarker(USVString markerLabel);
};

[Exposed=(Window, DedicatedWorker), SecureContext]
interface GPUComputePassEncoder {
    undefined setPipeline(GPUComputePipeline pipeline);
    undefined dispatchWorkgroups(GPUSize32 workgroupCountX, optional GPUSize32 workgroupCountY = 1, optional GPUSize32 workgroupCountZ = 1);
    undefined dispatchWorkgroupsIndirect(GPUBuffer indirectBuffer, GPUSize64 indirectOffset);

    undefined end();
};
GPUComputePassEncoder includes GPUObjectBase;
GPUComputePassEncoder includes GPUCommandsMixin;
GPUComputePassEncoder includes GPUDebugCommandsMixin;
GPUComputePassEncoder includes GPUBindingCommandsMixin;

enum GPUComputePassTimestampLocation {
    "beginning",
    "end"
};

dictionary GPUComputePassTimestampWrite {
    required GPUQuerySet querySet;
    required GPUSize32 queryIndex;
    required GPUComputePassTimestampLocation location;
};

typedef sequence<GPUComputePassTimestampWrite> GPUComputePassTimestampWrites;

dictionary GPUComputePassDescriptor : GPUObjectDescriptorBase {
    GPUComputePassTimestampWrites timestampWrites = [];
};

[Exposed=(Window, DedicatedWorker), SecureContext]
interface GPURenderPassEncoder {
    undefined setViewport(float x, float y,
                     float width, float height,
                     float minDepth, float maxDepth);

    undefined setScissorRect(GPUIntegerCoordinate x, GPUIntegerCoordinate y,
                        GPUIntegerCoordinate width, GPUIntegerCoordinate height);

    undefined setBlendConstant(GPUColor color);
    undefined setStencilReference(GPUStencilValue reference);

    undefined beginOcclusionQuery(GPUSize32 queryIndex);
    undefined endOcclusionQuery();

    undefined executeBundles(sequence<GPURenderBundle> bundles);
    undefined end();
};
GPURenderPassEncoder includes GPUObjectBase;
GPURenderPassEncoder includes GPUCommandsMixin;
GPURenderPassEncoder includes GPUDebugCommandsMixin;
GPURenderPassEncoder includes GPUBindingCommandsMixin;
GPURenderPassEncoder includes GPURenderCommandsMixin;

enum GPURenderPassTimestampLocation {
    "beginning",
    "end"
};

dictionary GPURenderPassTimestampWrite {
    required GPUQuerySet querySet;
    required GPUSize32 queryIndex;
    required GPURenderPassTimestampLocation location;
};

typedef sequence<GPURenderPassTimestampWrite> GPURenderPassTimestampWrites;

dictionary GPURenderPassDescriptor : GPUObjectDescriptorBase {
    required sequence<GPURenderPassColorAttachment?> colorAttachments;
    GPURenderPassDepthStencilAttachment depthStencilAttachment;
    GPUQuerySet occlusionQuerySet;
    GPURenderPassTimestampWrites timestampWrites = [];
    GPUSize64 maxDrawCount = 50000000;
};

dictionary GPURenderPassColorAttachment {
    required GPUTextureView view;
    GPUTextureView resolveTarget;

    GPUColor clearValue;
    required GPULoadOp loadOp;
    required GPUStoreOp storeOp;
};

dictionary GPURenderPassDepthStencilAttachment {
    required GPUTextureView view;

    float depthClearValue = 0;
    GPULoadOp depthLoadOp;
    GPUStoreOp depthStoreOp;
    boolean depthReadOnly = false;

    GPUStencilValue stencilClearValue = 0;
    GPULoadOp stencilLoadOp;
    GPUStoreOp stencilStoreOp;
    boolean stencilReadOnly = false;
};

enum GPULoadOp {
    "load",
    "clear"
};

enum GPUStoreOp {
    "store",
    "discard"
};

dictionary GPURenderPassLayout: GPUObjectDescriptorBase {
    required sequence<GPUTextureFormat?> colorFormats;
    GPUTextureFormat depthStencilFormat;
    GPUSize32 sampleCount = 1;
};

interface mixin GPURenderCommandsMixin {
    undefined setPipeline(GPURenderPipeline pipeline);

    undefined setIndexBuffer(GPUBuffer buffer, GPUIndexFormat indexFormat, optional GPUSize64 offset = 0, optional GPUSize64 size);
    undefined setVertexBuffer(GPUIndex32 slot, GPUBuffer buffer, optional GPUSize64 offset = 0, optional GPUSize64 size);

    undefined draw(GPUSize32 vertexCount, optional GPUSize32 instanceCount = 1,
              optional GPUSize32 firstVertex = 0, optional GPUSize32 firstInstance = 0);
    undefined drawIndexed(GPUSize32 indexCount, optional GPUSize32 instanceCount = 1,
                     optional GPUSize32 firstIndex = 0,
                     optional GPUSignedOffset32 baseVertex = 0,
                     optional GPUSize32 firstInstance = 0);

    undefined drawIndirect(GPUBuffer indirectBuffer, GPUSize64 indirectOffset);
    undefined drawIndexedIndirect(GPUBuffer indirectBuffer, GPUSize64 indirectOffset);
};

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

dictionary GPURenderBundleDescriptor : GPUObjectDescriptorBase {
};

[Exposed=(Window, DedicatedWorker), SecureContext]
interface GPURenderBundleEncoder {
    GPURenderBundle finish(optional GPURenderBundleDescriptor descriptor = {});
};
GPURenderBundleEncoder includes GPUObjectBase;
GPURenderBundleEncoder includes GPUCommandsMixin;
GPURenderBundleEncoder includes GPUDebugCommandsMixin;
GPURenderBundleEncoder includes GPUBindingCommandsMixin;
GPURenderBundleEncoder includes GPURenderCommandsMixin;

dictionary GPURenderBundleEncoderDescriptor : GPURenderPassLayout {
    boolean depthReadOnly = false;
    boolean stencilReadOnly = false;
};

dictionary GPUQueueDescriptor : GPUObjectDescriptorBase {
};

[Exposed=(Window, DedicatedWorker), SecureContext]
interface GPUQueue {
    undefined submit(sequence<GPUCommandBuffer> commandBuffers);

    Promise<undefined> onSubmittedWorkDone();

    undefined writeBuffer(
        GPUBuffer buffer,
        GPUSize64 bufferOffset,
        [AllowShared] BufferSource data,
        optional GPUSize64 dataOffset = 0,
        optional GPUSize64 size);

    undefined writeTexture(
        GPUImageCopyTexture destination,
        [AllowShared] BufferSource data,
        GPUImageDataLayout dataLayout,
        GPUExtent3D size);

    undefined copyExternalImageToTexture(
        GPUImageCopyExternalImage source,
        GPUImageCopyTextureTagged destination,
        GPUExtent3D copySize);
};
GPUQueue includes GPUObjectBase;

[Exposed=(Window, DedicatedWorker), SecureContext]
interface GPUQuerySet {
    undefined destroy();

    readonly attribute GPUQueryType type;
    readonly attribute GPUSize32 count;
};
GPUQuerySet includes GPUObjectBase;

dictionary GPUQuerySetDescriptor : GPUObjectDescriptorBase {
    required GPUQueryType type;
    required GPUSize32 count;
};

enum GPUQueryType {
    "occlusion",
    "timestamp"
};

[Exposed=(Window, DedicatedWorker), SecureContext]
interface GPUCanvasContext {
    readonly attribute (HTMLCanvasElement or OffscreenCanvas) canvas;

    undefined configure(GPUCanvasConfiguration configuration);
    undefined unconfigure();

    GPUTexture getCurrentTexture();
};

enum GPUCanvasAlphaMode {
    "opaque",
    "premultiplied"
};

dictionary GPUCanvasConfiguration {
    required GPUDevice device;
    required GPUTextureFormat format;
    GPUTextureUsageFlags usage = 0x10;  // GPUTextureUsage.RENDER_ATTACHMENT
    sequence<GPUTextureFormat> viewFormats = [];
    PredefinedColorSpace colorSpace = "srgb";
    GPUCanvasAlphaMode alphaMode = "opaque";
};

enum GPUDeviceLostReason {
    "destroyed"
};

[Exposed=(Window, DedicatedWorker), SecureContext]
interface GPUDeviceLostInfo {
    readonly attribute (GPUDeviceLostReason or undefined) reason;
    readonly attribute DOMString message;
};

partial interface GPUDevice {
    readonly attribute Promise<GPUDeviceLostInfo> lost;
};

enum GPUErrorFilter {
    "out-of-memory",
    "validation"
};

[Exposed=(Window, DedicatedWorker), SecureContext]
interface GPUError {
    readonly attribute DOMString message;
};

[Exposed=(Window, DedicatedWorker), SecureContext]
interface GPUOutOfMemoryError : GPUError {
    constructor(DOMString message);
};

[Exposed=(Window, DedicatedWorker), SecureContext]
interface GPUValidationError : GPUError {
    constructor(DOMString message);
};

partial interface GPUDevice {
    undefined pushErrorScope(GPUErrorFilter filter);
    Promise<GPUError?> popErrorScope();
};

[Exposed=(Window, DedicatedWorker), SecureContext]
interface GPUUncapturedErrorEvent : Event {
    constructor(
        DOMString type,
        GPUUncapturedErrorEventInit gpuUncapturedErrorEventInitDict
    );
    readonly attribute GPUError error;
};

dictionary GPUUncapturedErrorEventInit : EventInit {
    required GPUError error;
};

partial interface GPUDevice {
    [Exposed=(Window, DedicatedWorker)]
    attribute EventHandler onuncapturederror;
};

typedef [EnforceRange] unsigned long GPUBufferDynamicOffset;
typedef [EnforceRange] unsigned long GPUStencilValue;
typedef [EnforceRange] unsigned long GPUSampleMask;
typedef [EnforceRange] long GPUDepthBias;

typedef [EnforceRange] unsigned long long GPUSize64;
typedef [EnforceRange] unsigned long GPUIntegerCoordinate;
typedef [EnforceRange] unsigned long GPUIndex32;
typedef [EnforceRange] unsigned long GPUSize32;
typedef [EnforceRange] long GPUSignedOffset32;

typedef unsigned long GPUFlagsConstant;

dictionary GPUColorDict {
    required double r;
    required double g;
    required double b;
    required double a;
};
typedef (sequence<double> or GPUColorDict) GPUColor;

dictionary GPUOrigin2DDict {
    GPUIntegerCoordinate x = 0;
    GPUIntegerCoordinate y = 0;
};
typedef (sequence<GPUIntegerCoordinate> or GPUOrigin2DDict) GPUOrigin2D;

dictionary GPUOrigin3DDict {
    GPUIntegerCoordinate x = 0;
    GPUIntegerCoordinate y = 0;
    GPUIntegerCoordinate z = 0;
};
typedef (sequence<GPUIntegerCoordinate> or GPUOrigin3DDict) GPUOrigin3D;

dictionary GPUExtent3DDict {
    required GPUIntegerCoordinate width;
    GPUIntegerCoordinate height = 1;
    GPUIntegerCoordinate depthOrArrayLayers = 1;
};
typedef (sequence<GPUIntegerCoordinate> or GPUExtent3DDict) GPUExtent3D;

Issues Index

define the host API distinct from the shader API
Update this section with iframe-control defaulting to "self" being a mitigation against this issue since only the top level origin (that is a bit more trusted since the user navigated to it, or is staying on it).
This section will need to be revised to support multiple queues.
The above should probably talk about GPU commands. But we don’t have a way to reference specific GPU commands (like dispatch) yet.
Define "ownership".
explain how to get from device to its "primary" GPUDevice.
Do we need to have a max per-pixel render target size?
Consider a path for uploading srgb-encoded images into linearly-encoded textures. [Issue #gpuweb/gpuweb#1715]
Super-luminant is a confusing term because it doesn’t really have anything to do with luminance.
Update here if an adaptersadded/adapterschanged event is introduced.
define buffer (internal object)
Specify [[mapping]] in term of DataBlock similarly to AllocateArrayBuffer? [Issue #gpuweb/gpuweb#605]
Add client-side validation that a mapped buffer can only be unmapped and destroyed on the worker on which it was mapped. Likewise getMappedRange() can only be called on that worker. [Issue #gpuweb/gpuweb#605]
Handle error buffers once we have a description of the error monad. [Issue #gpuweb/gpuweb#605]
Do we validate that mode contains only valid flags?
Consider aligning mapAsync offset to 8 to match this.
define texture (internal object)
define mipmap level, array layer, aspect, slice (concepts)
share this definition with the part of the specification that describes sampling.
Define larger compatibility classes. [Issue #gpuweb/gpuweb#168]
Describe this in terms of a "set of subresources of" algorithm.
add something on GPUAdapter(?) that gives an estimate of the bytes per texel of "stencil8", "depth24plus-stencil8", and "depth32float-stencil8". [Issue #gpuweb/gpuweb#1887]
Update this description with canvas.
explain how LOD is calculated and if there are differences here between platforms.
explain what anisotropic sampling is
Describe a "sample footprint" in greater detail.
describe how filtering interacts with comparison sampling.
consider making sampleType truly optional.
consider making format truly optional.
This seems to prevent the use of texture_depth_multisampled_2d. [Issue #gpuweb/gpuweb#1924]
Define how a range is formed by offset/size when size can be undefined.
should this example and the note be moved to some "best practices" document?
Describe remaining createShaderModule() validation and algorithm steps.
Reference WGSL spec when it defines what a line is. [Issue #gpuweb/gpuweb#2435]
Describe compilationInfo() algorithm steps.
Specify this more properly once we have internal objects for GPUBindGroupLayout. Alternatively only spec is as a new internal objects that’s group-equivalent
Define the reflection information concept so that this spec can interface with the WGSL spec and get information what the interface is for a GPUShaderModule for a specific entrypoint.
link to a definition for "minimum buffer binding size" in the "reflection information".
This fills the pipeline layout with empty bindgroups. Revisit once the behavior of empty bindgroups is specified.
Better define using static use, etc.
need description of the render states.
define what "compatible" means for render target formats.
define the area of reach for "statically used" things of GPUProgrammableStage
how can this algorithm support depth/stencil formats that are added in extensions?
Describe remaining createCommandEncoder() validation and algorithm steps.
Describe this in terms of a "set of subresources of" algorithm.
Enqueue attachment loads/clears.
specify the behavior of read-only depth/stencil
these dictionary definitions should be inside the image copies section.
Define images more precisely. In particular, define them as being comprised of texel blocks.
Define the exact copy semantics, by reference to common algorithms shared by the copy methods.
Define the copies with 1d and 3d textures. [Issue #gpuweb/gpuweb#69]
Define (and test) the encoding of color values into the various encodings allowed by copyExternalImageToTexture().
figure out how to handle overflows in the spec. [Issue #gpuweb/gpuweb#69]
Describe and enqueue the GPU command.
Does the term "image copy" include copyTextureToTexture?
define this as an algorithm with (texture, mipmapLevel) parameters and use the call syntax instead of referring to the definition by label.
Once more formats are allowed in viewFormats, consider making two textures copy-compatible when there’s any overlap in the viewFormats. [Issue #gpuweb/gpuweb#2322]
Describe writeTimestamp() algorithm steps.
Describe resolveQuerySet() algorithm steps.
Resolve bikeshed conflict when using argumentdef with overloaded functions that prevents us from defining dynamicOffsets.
Add validation that, for buffer bindings that weren’t prevalidated with minBindingSize, the binding ranges are large enough for the shader’s minimum binding size requirements.
Determine what happens when an application violates this. Is it a validation error, one of multiple possible behaviors, or do we just remove this restriction entirely and allow writable bindings to alias with undefined results? [Issue #gpuweb/gpuweb#1842]
support for no attachments [Issue #gpuweb/gpuweb#503]
make it a define once we reference to this from other places
Enqueue the attachment stores/discards.
define what "equals" means for GPURenderPassLayout here.
Allowed for GPUs to use fixed point or rounded viewport coordinates
Describe the rest of the steps
Describe the reset of the steps for createRenderBundleEncoder().
Specify more formally.
Specify more formally.
If an srgb-linear color space is added, explain here how it interacts.
Do the actual copy.
Write normative text about timestamp value resets.
Because timestamp query provides high-resolution GPU timestamp, we need to decide what constraints, if any, are on its availability.
Unless high dynamic range is explicitly enabled for the canvas element.
This attribute should be [SameObject]. (If GPUError becomes an interface then we can do this without resolving the WebIDL issue.) [Issue #whatwg/webidl#1077]
describe the transfers at the high level
describe the computing algorithm
fill out the section, using fragments
fill out the section
specify indirect commands better.
should this be defined more formally?
link to WGSL built-ins
provide more specifics here, if possible
link to interpolation qualifiers in WGSL
do we want to force-enable the "Standard sample locations" in Vulkan?
define the depth computation algorithm
specify the depth translation into viewport as well
specify that each rasterization point gets assigned an interpolated divisor(p) and framebufferCoords(n), as well as the other attributes.
reword the "goes into" part
fill out this section
define how this value is constructed.
describe the exact equations.
fill out this section
fill out the section
Define functionality when the "depth-clip-control" feature is enabled.
Define functionality when the "timestamp-query" feature is enabled.