WebGPU

1. Introduction

This section is non-normative.

Graphics Processing Units, or GPUs for short, have been essential in enabling rich rendering and computational applications in personal computing. WebGPU is an API that exposes the capabilities of GPU hardware for the Web. The API is designed from the ground up to efficiently map to the Vulkan, Direct3D 12, and Metal 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 setBlendColor().

2. Security considerations

2.1. CPU-based undefined behavior

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

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

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

2.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, the WebGPU implementation has to validate it before doing any translation (to platform-specific shaders) or transformation passes.

2.3. Out-of-bounds access in shaders

Shaders can access physical resources either directly 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 API side can not guarantee that the data is accessed within bounds if the texture units are not involved.

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

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.4. 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.5. 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 support blacklisting particular drivers from using some of the native API backends.

2.6. Timing attacks

WebGPU is designed for multi-threaded use via Web Workers. Some of the objects, like GPUBuffer, 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 and allows the creation of high-precision timers. The theoretical attack vectors are a subset of those of SharedArrayBuffer.

2.7. 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.8. Fingerprinting

WebGPU defines the required limits and capabilities of any GPUAdapter. and encourages applications to target these standard limits. The actual result from requestAdapter() may have better limits, and could be subject to fingerprinting.

3. Terminology & Conventions

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

For example, where buffer is a GPUBuffer, buffer.[[device]].[[adapter]] means "the [[adapter]] internal slot of the [[device]] internal slot of buffer.

3.2. Coordinate Systems

WebGPU’s coordinate systems match DirectX and Metal’s coordinate systems in a graphics pipeline.

• Y-axis is up in normalized device coordinate (NDC): point(-1.0, -1.0) in NDC is located at the bottom-left corner of NDC. In addition, x and y in NDC should be between -1.0 and 1.0 inclusive, while z in NDC should be between 0.0 and 1.0 inclusive. Vertices out of this range in NDC will not introduce any errors, but they will be clipped.

• Y-axis is down in framebuffer coordinate, viewport coordinate and fragment/pixel coordinate: origin(0, 0) is located at the top-left corner in these coordinate systems.

• Window/present coordinate matches framebuffer coordinate.

• UV of origin(0, 0) in texture coordinate represents the first texel (the lowest byte) in texture memory.

3.3. 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.3.1. Invalid Objects

If an object is successfully created, it is valid at that moment. An internal object may be invalid. It may become invalid during its lifetime, but it will never become valid again.

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

As a matter of convention, if a WebGPU interface is referred to as invalid, it means that the internal object it encapsulates is invalid.

Any interface which includes GPUObjectBase is a WebGPU interface.

interface mixin GPUObjectBase {
    attribute USVString? label;
};

GPUObjectBase has the following attributes:

label, of type USVString, nullable

A label which can be used by development tools (such as error/warning messages, browser developer tools, or platform debugging utilities) to identify the underlying internal object to the developer. It has no specified format, and therefore cannot be reliably machine-parsed.

In any given situation, the user agent may or may not choose to use this label.

GPUObjectBase has the following internal slots:

[[device]], of type device, readonly

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

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

4. Programming Model

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.

Device timeline

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

Queue timeline

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

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

4.2. Memory

This section is non-normative.

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

1. User agent implementing the specification.

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

3. Actual CPU and GPU hardware.

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

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

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

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

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

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

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

4.3. Resource usage

Buffers and textures can be used by the GPU in multiple ways, which can be split into two groups:

Read-only usages

Usages like GPUBufferUsage.VERTEX or GPUTextureUsage.SAMPLED don’t change the contents of a resource.

Mutating usages

Usages like GPUBufferUsage.STORAGE do change the contents of a resource.

Consider merging all read-only usages. <https://github.com/gpuweb/gpuweb/issues/296>

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

The main usage rule is that any subresource at any given time can only be in either:

• a combination of read-only usages

• a single mutating usage

Enforcing this rule allows the API to limit when data races can occur when 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: each subresource must not change usage within the usage scope.

For example, binding the same buffer for GPUBufferUsage.STORAGE as well as for GPUBufferUsage.VERTEX within the same GPURenderPassEncoder would put the encoder as well as the owning GPUCommandEncoder into the error state. Since GPUBufferUsage.STORAGE is the only mutating usage for a buffer that is valid inside a render pass, if it’s present, this buffer can’t be used in any other way within this pass.

The subresources of textures included in the views provided to GPURenderPassColorAttachmentDescriptor.attachment and GPURenderPassColorAttachmentDescriptor.resolveTarget are considered to have OUTPUT_ATTACHMENT for the usage scope of this render pass.

The physical size of a GPUTexture subresource is the dimension of the GPUTexture subresource in texels that includes the possible extra paddings to form complete texel blocks in the subresource.

• For pixel-based GPUTextureFormats, the physical size is always equal to the size of the subresource used in the sampling hardwares.

• GPUTextures in block-based compressed GPUTextureFormats always have a mipmap level 0 whose [[textureSize]] is a multiple of the texel block size, but the lower mipmap levels might not be the multiple of the texel block size and can have paddings.

Document read-only states for depth views. <https://github.com/gpuweb/gpuweb/issues/514>

4.4. Synchronization

For each subresource of a physical resource, its set of usage flags is tracked on the Queue timeline. Usage flags are GPUBufferUsage or GPUTextureUsage flags, according to the type of the subresource.

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

On the Queue timeline, there is an ordered sequence of usage scopes. Each item on the timeline is contained within exactly one scope. For the duration of each scope, the set of 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:

1. an individual command on a GPUCommandEncoder, such as GPUCommandEncoder.copyBufferToTexture.

2. an individual command on a GPUComputePassEncoder, such as GPUProgrammablePassEncoder.setBindGroup.

3. the whole GPURenderPassEncoder.

Note: calling GPUProgrammablePassEncoder.setBindGroup adds the [[usedBuffers]] and [[usedTextures]] to the usage scope regardless of whether the shader or GPUPipelineLayout actually depends on these bindings. Similarly GPURenderEncoderBase.setIndexBuffer add the index buffer to the usage scope (as GPUBufferUsage.INDEX) regardless of whether the indexed draw calls are used afterwards.

The usage scopes are validated at GPUCommandEncoder.finish time. The implementation performs the usage scope validation by composing the set of all usage flags of each subresource used in the usage scope. A GPUValidationError is generated in the current scope with an appropriate error message if that union contains a mutating usage combined with any other usage.

5. Core Internal Objects

5.1. Adapters

An adapter represents an implementation of WebGPU on the system. Each adapter identifies both an instance of a hardware accelerator (e.g. GPU or CPU) and an instance of a browser’s implementation of WebGPU on top of that accelerator.

If an adapter becomes unavailable, it becomes invalid. Once invalid, it never becomes valid again. Any devices on the adapter, and internal objects owned by those devices, also become invalid.

Note: An adapter may be a physical display adapter (GPU), but it could also be a software renderer. A returned adapter could refer to different physical adapters, or to different browser codepaths or system drivers on the same physical adapters. Applications can hold onto multiple adapters at once (via GPUAdapter) (even if some are invalid), and two of these could refer to different instances of the same physical configuration (e.g. if the GPU was reset or disconnected and reconnected).

An adapter has the following internal slots:

[[extensions]], of type sequence<GPUExtensionName>, readonly

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

[[limits]], of type GPULimits, 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 GPULimits.

Adapters are exposed via GPUAdapter.

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

Define "ownership".

A device has the following internal slots:

[[adapter]], of type adapter, readonly

The adapter from which this device was created.

[[extensions]], of type sequence<GPUExtensionName>, readonly

The extensions which can be used on this device. No additional extensions can be used, even if the underlying adapter can support them.

[[limits]], of type GPULimits, readonly

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

Devices are exposed via GPUDevice.

6. Initialization

6.1. Examples

Need a robust example like the one in ErrorHandling.md, which handles all situations. Possibly also include a simple example with no handling.

6.2. navigator.gpu

A GPU object is available via navigator.gpu on the Window:

[Exposed=Window]
partial interface Navigator {
    [SameObject] readonly attribute GPU gpu;
};

... as well as on dedicated workers:

[Exposed=DedicatedWorker]
partial interface WorkerNavigator {
    [SameObject] readonly attribute GPU gpu;
};

6.3. GPU

GPU is the entry point to WebGPU.

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

GPU has the methods defined by the following sections.

6.3.1. requestAdapter(options)

6.3.1.1. Adapter Selection

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

dictionary GPURequestAdapterOptions {
    GPUPowerPreference powerPreference;
};

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.

6.4. GPUAdapter

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

To get a GPUAdapter, use requestAdapter().

interface GPUAdapter {
    readonly attribute DOMString name;
    readonly attribute FrozenArray<GPUExtensionName> extensions;
    //readonly attribute GPULimits limits; Don’t expose higher limits for now.

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

GPUAdapter has:

• These attributes:

  name, of type DOMString, readonly

  A human-readable name identifying the adapter. The contents are implementation-defined.

  extensions, of type FrozenArray<GPUExtensionName>, readonly

  Accessor for this.[[adapter]].[[extensions]].

• These internal slots:

  [[adapter]], of type adapter, readonly

  An internal slot holding the adapter to which this GPUAdapter refers.

• The methods defined by the following sub-sections.

6.4.1. requestDevice(optional descriptor)

6.4.1.1. GPUDeviceDescriptor

GPUDeviceDescriptor describes a device request.

dictionary GPUDeviceDescriptor : GPUObjectDescriptorBase {
    sequence<GPUExtensionName> extensions = [];
    GPULimits limits = {};
};

extensions, of type sequence<GPUExtensionName>, defaulting to []

The set of GPUExtensionName values in this sequence defines the exact set of extensions that must be enabled on the device.

limits, of type GPULimits, defaulting to {}

Defines the exact limits that must be enabled on the device.

6.4.1.2. GPUExtensionName

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

enum GPUExtensionName {
    "texture-compression-bc",
    "pipeline-statistics-query"
};

"texture-compression-bc"

Write a spec section for this, and link to it.

6.4.1.3. GPULimits

GPULimits describes various limits in the usage of WebGPU on a device.

One limit value may be better than another. For each limit, "better" is defined.

Note: Setting "better" limits may not necessarily be desirable. While they enable strictly more programs to be valid, 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.

dictionary GPULimits {
    GPUSize32 maxBindGroups = 4;
    GPUSize32 maxDynamicUniformBuffersPerPipelineLayout = 8;
    GPUSize32 maxDynamicStorageBuffersPerPipelineLayout = 4;
    GPUSize32 maxSampledTexturesPerShaderStage = 16;
    GPUSize32 maxSamplersPerShaderStage = 16;
    GPUSize32 maxStorageBuffersPerShaderStage = 4;
    GPUSize32 maxStorageTexturesPerShaderStage = 4;
    GPUSize32 maxUniformBuffersPerShaderStage = 12;
    GPUSize32 maxTextureSize = 8192;
    GPUSize32 maxTextureLayers = 256;
};

maxBindGroups, of type GPUSize32, defaulting to 4

The maximum number of GPUBindGroupLayouts allowed in bindGroupLayouts when creating a GPUPipelineLayout.

Higher is better.

maxDynamicUniformBuffersPerPipelineLayout, of type GPUSize32, defaulting to 8

The maximum number of entries for which:

• type is "uniform-buffer", and

• hasDynamicOffset is true,

across all bindGroupLayouts when creating a GPUPipelineLayout.

Higher is better.

maxDynamicStorageBuffersPerPipelineLayout, of type GPUSize32, defaulting to 4

The maximum number of entries for which:

• type is "storage-buffer", and

• hasDynamicOffset is true,

across all bindGroupLayouts when creating a GPUPipelineLayout.

Higher is better.

maxSampledTexturesPerShaderStage, of type GPUSize32, defaulting to 16

For each possible GPUShaderStage stage, the maximum number of entries for which:

• type is "sampled-texture", and

• visibility includes stage,

across all bindGroupLayouts when creating a GPUPipelineLayout.

Higher is better.

maxSamplersPerShaderStage, of type GPUSize32, defaulting to 16

For each possible GPUShaderStage stage, the maximum number of entries for which:

• type is "sampler" or "comparison-sampler", and

• visibility includes stage,

across all bindGroupLayouts when creating a GPUPipelineLayout.

Higher is better.

maxStorageBuffersPerShaderStage, of type GPUSize32, defaulting to 4

For each possible GPUShaderStage stage, the maximum number of entries for which:

• type is "storage-buffer", and

• visibility includes stage,

across all bindGroupLayouts when creating a GPUPipelineLayout.

Higher is better.

maxStorageTexturesPerShaderStage, of type GPUSize32, defaulting to 4

For each possible GPUShaderStage stage, the maximum number of entries for which:

• type is "readonly-storage-texture" or "writeonly-storage-texture", and

• visibility includes stage,

across all bindGroupLayouts when creating a GPUPipelineLayout.

Higher is better.

maxUniformBuffersPerShaderStage, of type GPUSize32, defaulting to 12

For each possible GPUShaderStage stage, the maximum number of entries for which:

• type is uniform-buffer, and

• visibility includes stage,

across all bindGroupLayouts when creating a GPUPipelineLayout.

Higher is better.

maxTextureSize, of type GPUSize32, defaulting to 8192

The maximum size in a single dimension of a texture.

Note: This is only used in the width dimension for 1D textures, and the width & height dimensions for 2D textures. This isn’t used at all for 3D textures.

Higher is better.

maxTextureLayers, of type GPUSize32, defaulting to 256

The maximum number of layers in an array texture.

Note: This is also used for the size limit of 3D textures.

Higher is better.

6.5. 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), Serializable]
interface GPUDevice : EventTarget {
    [SameObject] readonly attribute GPUAdapter adapter;
    readonly attribute FrozenArray<GPUExtensionName> extensions;
    readonly attribute object limits;

    [SameObject] readonly attribute GPUQueue defaultQueue;

    GPUBuffer createBuffer(GPUBufferDescriptor descriptor);
    GPUMappedBuffer createBufferMapped(GPUBufferDescriptor descriptor);
    GPUTexture createTexture(GPUTextureDescriptor descriptor);
    GPUSampler createSampler(optional GPUSamplerDescriptor 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);

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

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

GPUDevice has:

• These attributes:

  adapter, of type GPUAdapter, readonly

  The GPUAdapter from which this device was created.

  extensions, of type FrozenArray<GPUExtensionName>, readonly

  A sequence containing the GPUExtensionNames of the extensions supported by the device (i.e. the ones with which it was created).

  limits, of type object, readonly

  A GPULimits object exposing the limits supported by the device (i.e. the ones with which it was created).

• These internal slots:

  [[device]], of type device, readonly

  The device that this GPUDevice refers to.

• The methods listed in its WebIDL definition above, which are defined elsewhere in this document.

GPUDevice objects are serializable objects.

7. Buffers

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

[Serializable]
interface GPUBuffer {
    Promise<void> mapAsync(optional GPUSize64 offset = 0, optional GPUSize64 size = 0);
    ArrayBuffer getMappedRange(optional GPUSize64 offset = 0, optional GPUSize64 size = 0);
    void unmap();

    void destroy();
};
GPUBuffer includes GPUObjectBase;

GPUBuffer has the following internal slots:

[[size]] of type GPUSize64.

The length of the GPUBuffer allocation in bytes.

[[usage]] of type GPUBufferUsageFlags.

The allowed usages for this GPUBuffer.

[[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? <https://github.com/gpuweb/gpuweb/issues/605>

[[mapping_range]] of type sequence<Number> or null.

The range of this GPUBuffer that is mapped.

[[mapped_ranges]] of type sequence<ArrayBuffer> or null.

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

[[usage]] is differently named from [[textureUsage]]. We should make it consistent.

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

• "mapped" where the GPUBuffer is available for CPU operations on its content.

• "mapped at creation" where the GPUBuffer was just created and is available for CPU operations on its content.

• "mapping pending" where the GPUBuffer is being made available for CPU operations on its content.

• "unmapped" where the GPUBuffer is available for GPU operations.

• "destroyed" where the GPUBuffer is no longer available for any operations except destroy.

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

GPUBuffer is Serializable. It is a reference to an internal buffer object, and Serializable means that the reference can be copied between realms (threads/workers), allowing multiple realms to access it concurrently. Since GPUBuffer has internal state (mapped, destroyed), that state is internally-synchronized - these state changes occur atomically across realms.

7.2. Buffer Creation

7.2.1. GPUBufferDescriptor

This specifies the options to use in creating a GPUBuffer.

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

7.3. Buffer Usage

typedef [EnforceRange] unsigned long GPUBufferUsageFlags;
interface GPUBufferUsage {
    const GPUBufferUsageFlags MAP_READ      = 0x0001;
    const GPUBufferUsageFlags MAP_WRITE     = 0x0002;
    const GPUBufferUsageFlags COPY_SRC      = 0x0004;
    const GPUBufferUsageFlags COPY_DST      = 0x0008;
    const GPUBufferUsageFlags INDEX         = 0x0010;
    const GPUBufferUsageFlags VERTEX        = 0x0020;
    const GPUBufferUsageFlags UNIFORM       = 0x0040;
    const GPUBufferUsageFlags STORAGE       = 0x0080;
    const GPUBufferUsageFlags INDIRECT      = 0x0100;
    const GPUBufferUsageFlags QUERY_RESOLVE = 0x0200;
};

7.3.1. createBuffer(descriptor)

7.4. Buffer Destruction

An application that no longer requires a GPUBuffer 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 GPUBuffer once all previously submitted operations using it are complete.

7.4.1. destroy()

7.5. 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. <https://github.com/gpuweb/gpuweb/issues/605>

7.5.1. mapAsync(offset, size)

7.5.2. getMappedRange(start, offset)

7.5.3. unmap()

8. Textures and Texture Views

define texture (internal object)

define mipmap level, array layer, slice (concepts)

8.1. GPUTexture

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

[Serializable]
interface GPUTexture {
    GPUTextureView createView(optional GPUTextureViewDescriptor descriptor = {});

    void destroy();
};
GPUTexture includes GPUObjectBase;

GPUTexture has the following internal slots:

[[textureSize]] of type GPUExtent3D.

The size of the GPUTexture in texels in mipmap level 0.

[[mipLevelCount]] of type GPUIntegerCoordinate.

The total number of the mipmap levels of the GPUTexture.

[[sampleCount]] of type GPUSize32.

The number of samples in each texel of the GPUTexture.

[[dimension]] of type GPUTextureDimension.

The dimension of the GPUTexture.

[[format]] of type GPUTextureFormat.

The format of the GPUTexture.

[[textureUsage]] of type GPUTextureUsageFlags.

The allowed usages for this GPUTexture.

8.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;
};

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

typedef [EnforceRange] unsigned long GPUTextureUsageFlags;
interface GPUTextureUsage {
    const GPUTextureUsageFlags COPY_SRC          = 0x01;
    const GPUTextureUsageFlags COPY_DST          = 0x02;
    const GPUTextureUsageFlags SAMPLED           = 0x04;
    const GPUTextureUsageFlags STORAGE           = 0x08;
    const GPUTextureUsageFlags OUTPUT_ATTACHMENT = 0x10;
};

8.1.2. createTexture(descriptor)

8.2. GPUTextureView

interface GPUTextureView {
};
GPUTextureView includes GPUObjectBase;

8.2.1. Texture View Creation

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

Make this a standalone algorithm used in the createView algorithm.

The references to GPUTextureDescriptor here should actually refer to internal slots of a texture internal object once we have one.

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

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

8.2.2. GPUTexture.createView(descriptor)

8.3. Texture Formats

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

• r, g, b, a = red, green, blue, alpha

• unorm = unsigned normalized

• snorm = signed normalized

• uint = unsigned int

• sint = signed int

• float = floating point

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

• For pixel-based GPUTextureFormats, the texel block width and texel block height are always 1.

• For block-based compressed GPUTextureFormats, the texel block width is the number of texels in each row of one texel block, and the texel block height is the number of texel rows in 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 "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
    "rgb10a2unorm",
    "rg11b10float",

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

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

    // Depth and stencil formats
    "depth32float",
    "depth24plus",
    "depth24plus-stencil8"
};

The following texture formats are considered depth or stencil formats:

• "depth32float"

• "depth24plus"

• "depth24plus-stencil8"

There are no compressed formats defined in unextended WebGPU. Extensions may define some, though.

The depth24plus family of formats (depth24plus and depth24plus-stencil8) must have a depth-component precision of 1 ULP ≤ 1 / (2²⁴).

Note: This is unlike the 24-bit unsigned normalized format family typically found in native APIs, which has a precision of 1 ULP = 1 / (2²⁴ − 1).

enum GPUTextureComponentType {
    "float",
    "sint",
    "uint"
};

9. Samplers

9.1. GPUSampler

interface GPUSampler {
};
GPUSampler includes GPUObjectBase;

GPUSampler has the following internal slots:

[[compareEnable]] of type boolean.

Whether the GPUSampler is used as a comparison sampler.

9.1.1. Creation

dictionary GPUSamplerDescriptor : GPUObjectDescriptorBase {
    GPUAddressMode addressModeU = "clamp-to-edge";
    GPUAddressMode addressModeV = "clamp-to-edge";
    GPUAddressMode addressModeW = "clamp-to-edge";
    GPUFilterMode magFilter = "nearest";
    GPUFilterMode minFilter = "nearest";
    GPUFilterMode mipmapFilter = "nearest";
    float lodMinClamp = 0;
    float lodMaxClamp = 0xffffffff; // TODO: What should this be? Was Number.MAX_VALUE.
    GPUCompareFunction compare;
};

9.1.2. GPUDevice.createSampler(descriptor)

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

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

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

10. Resource Binding

10.1. GPUBindGroupLayout

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

[Serializable]
interface GPUBindGroupLayout {
};
GPUBindGroupLayout includes GPUObjectBase;

10.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;
    required GPUBindingType type;
    GPUTextureViewDimension viewDimension = "2d";
    GPUTextureComponentType textureComponentType = "float";
    GPUTextureFormat storageTextureFormat;
    boolean multisampled = false;
    boolean hasDynamicOffset = false;
};

• binding: A unique identifier for a resource binding within a GPUBindGroupLayoutEntry, a corresponding GPUBindGroupEntry, and shader stages.

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

typedef [EnforceRange] unsigned long GPUShaderStageFlags;
interface GPUShaderStage {
    const GPUShaderStageFlags VERTEX   = 0x1;
    const GPUShaderStageFlags FRAGMENT = 0x2;
    const GPUShaderStageFlags COMPUTE  = 0x4;
};

• type: A member of GPUBindingType that indicates the intended usage of a resource binding in its visible GPUShaderStages.

enum GPUBindingType {
    "uniform-buffer",
    "storage-buffer",
    "readonly-storage-buffer",
    "sampler",
    "comparison-sampler",
    "sampled-texture",
    "readonly-storage-texture",
    "writeonly-storage-texture"
    // TODO: other binding types
};

• viewDimension, multisampled: Describes the dimensionality of texture view bindings, and indicates if they are multisampled.

  Note: This allows Metal-based implementations to back the respective bind groups with MTLArgumentBuffer objects that are more efficient to bind at run-time.

• hasDynamicOffset: For uniform-buffer, storage-buffer, and readonly-storage-buffer bindings, indicates that the binding has a dynamic offset. One offset must be passed to setBindGroup for each dynamic binding in increasing order of binding number.

A GPUBindGroupLayout object has the following internal slots:

[[entryMap]] of type map .

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

10.1.2. GPUDevice.createBindGroupLayout(GPUBindGroupLayoutDescriptor)

10.1.3. Compatibility

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

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

interface GPUBindGroup {
};
GPUBindGroup includes GPUObjectBase;

10.2.1. Bind Group Creation

A GPUBindGroup is created via GPUDevice.createBindGroup().

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

A GPUBindGroupEntry describes a single resource to be bound in a GPUBindGroup.

typedef (GPUSampler or GPUTextureView or GPUBufferBinding) GPUBindingResource;

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

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

• size: If undefined, specifies the range starting at offset and ending at the end of the buffer.

A GPUBindGroup object has the following internal slots:

[[layout]] of type GPUBindGroupLayout.

The GPUBindGroupLayout associated with this GPUBindGroup.

[[entries]] of type sequence<GPUBindGroupEntry>.

The set of GPUBindGroupEntrys this GPUBindGroup describes.

[[usedBuffers]] of type maplike<GPUBuffer, GPUBufferUsage>.

The set of buffers used by this bind group and the corresponding usage flags.

[[usedTextures]] of type maplike<GPUTexture subresource, GPUTextureUsage>.

The set of texure subresources used by this bind group. Each subresource is stored with the union of usage flags that apply to it.

10.2.2. GPUDevice.createBindGroup(GPUBindGroupDescriptor)

10.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 GPURenderEncoderBase.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.

[Serializable]
interface GPUPipelineLayout {
};
GPUPipelineLayout includes GPUObjectBase;

GPUPipelineLayout has the following internal slots:

[[bindGroupLayouts]] of type sequence<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.

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.

10.3.1. Creation

A GPUPipelineLayout is created via GPUDevice.createPipelineLayout().

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

10.3.2. GPUDevice.createPipelineLayout(descriptor)

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

11. Shader Modules

11.1. GPUShaderModule

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

[Serializable]
interface GPUCompilationMessage {
    readonly attribute DOMString message;
    readonly attribute GPUCompilationMessageType type;
    readonly attribute unsigned long long lineNum;
    readonly attribute unsigned long long linePos;
};

[Serializable]
interface GPUCompilationInfo {
    readonly attribute sequence<GPUCompilationMessage> messages;
};

[Serializable]
interface GPUShaderModule {
    Promise<GPUCompilationInfo> compilationInfo();
};
GPUShaderModule includes GPUObjectBase;

GPUShaderModule is Serializable. It is a reference to an internal shader module object, and Serializable means that the reference can be copied between realms (threads/workers), allowing multiple realms to access it concurrently. Since GPUShaderModule is immutable, there are no race conditions.

11.1.1. Shader Module Creation

dictionary GPUShaderModuleDescriptor : GPUObjectDescriptorBase {
    required USVString code;
    object sourceMap;
};

sourceMap, if defined, MAY be interpreted as a source-map-v3 format. (https://sourcemaps.info/spec.html) Source maps are optional, but serve as a standardized way to support dev-tool integration such as source-language debugging.

12. 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 GPURenderEncoderBase.setPipeline correspondingly).

12.1. Base pipelines

dictionary GPUPipelineDescriptorBase : GPUObjectDescriptorBase {
    GPUPipelineLayout layout;
};

interface mixin GPUPipelineBase {
    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.

12.1.1. getBindGroupLayout(index)

12.1.2. Default pipeline layout

A GPUPipelineBase object that was created without a layout has a default layout created and used instead.

12.1.3. GPUProgrammableStageDescriptor

dictionary GPUProgrammableStageDescriptor {
    required GPUShaderModule module;
    required USVString entryPoint;
};

A GPUProgrammableStageDescriptor describes the entry point in the user-provided GPUShaderModule that controls one of the programmable stages of a pipeline.

is there a match/switch statement in bikeshed?

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.

12.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 "storage-buffer" and "writeonly-storage-texture" binding types.

Stages of a compute pipeline:

1. Compute shader

[Serializable]
interface GPUComputePipeline {
};
GPUComputePipeline includes GPUObjectBase;
GPUComputePipeline includes GPUPipelineBase;

12.2.1. Creation

dictionary GPUComputePipelineDescriptor : GPUPipelineDescriptorBase {
    required GPUProgrammableStageDescriptor computeStage;
};

12.2.2. GPUDevice.createComputePipeline(GPUComputePipelineDescriptor)

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

• bindings, according to the given GPUPipelineLayout

• vertex and index buffers, described by GPUVertexStateDescriptor

• the color attachments, described by GPUColorStateDescriptor

• optionally, the depth-stencil attachment, described by GPUDepthStencilStateDescriptor

Render pipeline outputs are:

• bindings of types "storage-buffer" and "writeonly-storage-texture"

• the color attachments, described by GPUColorStateDescriptor

• optionally, depth-stencil attachment, described by GPUDepthStencilStateDescriptor

Stages of a render pipeline:

1. Vertex fetch, controlled by GPUVertexStateDescriptor

2. Vertex shader

3. Primitive assembly, controlled by GPUPrimitiveTopology

4. Rasterization, controlled by GPURasterizationStateDescriptor

5. Fragment shader

6. Stencil test and operation, controlled by GPUDepthStencilStateDescriptor

7. Depth test and write, controlled by GPUDepthStencilStateDescriptor

8. Output merging, controlled by GPUColorStateDescriptor

we need a deeper description of these stages

[Serializable]
interface GPURenderPipeline {
};
GPURenderPipeline includes GPUObjectBase;
GPURenderPipeline includes GPUPipelineBase;

12.3.1. Creation

dictionary GPURenderPipelineDescriptor : GPUPipelineDescriptorBase {
    required GPUProgrammableStageDescriptor vertexStage;
    GPUProgrammableStageDescriptor fragmentStage;

    required GPUPrimitiveTopology primitiveTopology;
    GPURasterizationStateDescriptor rasterizationState = {};
    required sequence<GPUColorStateDescriptor> colorStates;
    GPUDepthStencilStateDescriptor depthStencilState;
    GPUVertexStateDescriptor vertexState = {};

    GPUSize32 sampleCount = 1;
    GPUSampleMask sampleMask = 0xFFFFFFFF;
    boolean alphaToCoverageEnabled = false;
};

• vertexStage describes the vertex shader entry point of the pipeline

• fragmentStage describes the fragment shader entry point of the pipeline. If it’s "null", the § 12.3.2 No Color Output mode is enabled.

• primitiveTopology configures the primitive assembly stage of the pipeline.

• rasterizationState configures the rasterization stage of the pipeline.

• colorStates describes the color attachments that are written by the pipeline.

• depthStencilState describes the optional depth-stencil attachment that is written by the pipeline.

• vertexState configures the vertex fetch stage of the pipeline.

• sampleCount is the number of MSAA samples that each attachment has to have.

• sampleMask is a binary mask of MSAA samples, according to [#sample-masking]].

• alphaToCoverageEnabled enables the § 12.3.3 Alpha to Coverage mode.

12.3.2. No Color Output

In no-color-output mode, pipeline does not produce any color attachment outputs, and the colorStates is expected to be empty.

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.

12.3.3. 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 colorStates[0].

The algorithm of producing the extra mask is platform-dependent. It guarantees that:

• if alpha is 0.0 or less, the result is 0x0

• if alpha is 1.0 or greater, the result is 0xFFFFFFFF

• if alpha is greater than some other alpha1, then the produced sample mask has at least as many bits set to 1 as the mask for alpha1

12.3.4. Sample Masking

The final sample mask for a pixel is computed as: rasterization mask & sampleMask & shader-output mask.

Only the lower sampleCount 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 incuded in the shape get the relevant bits 1 in the mask.

The shader-output mask takes the output value of SV_Coverage semantics in the fragment shader. If the semantics is not statically used by the shader, and alphaToCoverageEnabled is enabled, the shader-output mask becomes the alpha-to-coverage mask. Otherwise, it defaults to 0xFFFFFFFF.

link to the semantics of SV_SampleIndex and SV_Coverage in WGSL spec.

12.3.5. GPUDevice.createRenderPipeline(GPURenderPipelineDescriptor)

need a proper limit for the maximum number of color targets.

need a more detailed validation of the render states.

need description of the render states.

12.3.6. Primitive Topology

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

12.3.7. Rasterization State

dictionary GPURasterizationStateDescriptor {
    GPUFrontFace frontFace = "ccw";
    GPUCullMode cullMode = "none";

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

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

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

12.3.8. Color State

dictionary GPUColorStateDescriptor {
    required GPUTextureFormat format;

    GPUBlendDescriptor alphaBlend = {};
    GPUBlendDescriptor colorBlend = {};
    GPUColorWriteFlags writeMask = 0xF;  // GPUColorWrite.ALL
};

typedef [EnforceRange] unsigned long GPUColorWriteFlags;
interface GPUColorWrite {
    const GPUColorWriteFlags RED   = 0x1;
    const GPUColorWriteFlags GREEN = 0x2;
    const GPUColorWriteFlags BLUE  = 0x4;
    const GPUColorWriteFlags ALPHA = 0x8;
    const GPUColorWriteFlags ALL   = 0xF;
};

12.3.8.1. Blend State

dictionary GPUBlendDescriptor {
    GPUBlendFactor srcFactor = "one";
    GPUBlendFactor dstFactor = "zero";
    GPUBlendOperation operation = "add";
};

enum GPUBlendFactor {
    "zero",
    "one",
    "src-color",
    "one-minus-src-color",
    "src-alpha",
    "one-minus-src-alpha",
    "dst-color",
    "one-minus-dst-color",
    "dst-alpha",
    "one-minus-dst-alpha",
    "src-alpha-saturated",
    "blend-color",
    "one-minus-blend-color"
};

enum GPUBlendOperation {
    "add",
    "subtract",
    "reverse-subtract",
    "min",
    "max"
};

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

12.3.9. Depth/Stencil State

dictionary GPUDepthStencilStateDescriptor {
    required GPUTextureFormat format;

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

    GPUStencilStateFaceDescriptor stencilFront = {};
    GPUStencilStateFaceDescriptor stencilBack = {};

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

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

12.3.10. Vertex State

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

12.3.10.1. Vertex Formats

The name of the format specifies the data type of the component, the number of values, and whether the data is normalized.

• uchar = unsigned 8-bit value

• char = signed 8-bit value

• ushort = unsigned 16-bit value

• short = signed 16-bit value

• half = half-precision 16-bit floating point value

• float = 32-bit floating point value

• uint = unsigned 32-bit integer value

• int = signed 32-bit integer value

If no number of values is given in the name, a single value is provided. If the format has the -bgra suffix, it means the values are arranged as blue, green, red and alpha values.

enum GPUVertexFormat {
    "uchar2",
    "uchar4",
    "char2",
    "char4",
    "uchar2norm",
    "uchar4norm",
    "char2norm",
    "char4norm",
    "ushort2",
    "ushort4",
    "short2",
    "short4",
    "ushort2norm",
    "ushort4norm",
    "short2norm",
    "short4norm",
    "half2",
    "half4",
    "float",
    "float2",
    "float3",
    "float4",
    "uint",
    "uint2",
    "uint3",
    "uint4",
    "int",
    "int2",
    "int3",
    "int4"
};

enum GPUInputStepMode {
    "vertex",
    "instance"
};

dictionary GPUVertexStateDescriptor {
    GPUIndexFormat indexFormat = "uint32";
    sequence<GPUVertexBufferLayoutDescriptor?> vertexBuffers = [];
};

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 GPUVertexAttributeDescriptor 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 GPUVertexStateDescriptor.

dictionary GPUVertexBufferLayoutDescriptor {
    required GPUSize64 arrayStride;
    GPUInputStepMode stepMode = "vertex";
    required sequence<GPUVertexAttributeDescriptor> attributes;
};

dictionary GPUVertexAttributeDescriptor {
    required GPUVertexFormat format;
    required GPUSize64 offset;

    required GPUIndex32 shaderLocation;
};

add a limit to the number of vertex attributes

add a limit to the number of vertex buffers

13. Command Buffers

13.1. GPUCommandBuffer

interface GPUCommandBuffer {
};
GPUCommandBuffer includes GPUObjectBase;

13.1.1. Creation

dictionary GPUCommandBufferDescriptor : GPUObjectDescriptorBase {
};

14. Command Encoding

14.1. GPUCommandEncoder

interface GPUCommandEncoder {
    GPURenderPassEncoder beginRenderPass(GPURenderPassDescriptor descriptor);
    GPUComputePassEncoder beginComputePass(optional GPUComputePassDescriptor descriptor = {});

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

    void copyBufferToTexture(
        GPUBufferCopyView source,
        GPUTextureCopyView destination,
        GPUExtent3D copySize);

    void copyTextureToBuffer(
        GPUTextureCopyView source,
        GPUBufferCopyView destination,
        GPUExtent3D copySize);

    void copyTextureToTexture(
        GPUTextureCopyView source,
        GPUTextureCopyView destination,
        GPUExtent3D copySize);

    void pushDebugGroup(USVString groupLabel);
    void popDebugGroup();
    void insertDebugMarker(USVString markerLabel);

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

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

GPUCommandEncoder has the following internal slots:

[[state]] of type encoder state.

The current state of the GPUCommandEncoder, initially set to open.

[[debug_group_stack]] of type sequence<USVString>.

A stack of active debug group labels.

Each GPUCommandEncoder has a current encoder state on the Content timeline which may be one of the following:

"open"

Indicates the GPUCommandEncoder is available to begin new operations. The [[state]] is open any time the GPUCommandEncoder is valid and has no active GPURenderPassEncoder or GPUComputePassEncoder.

"encoding a render pass"

Indicates the GPUCommandEncoder has an active GPURenderPassEncoder. The [[state]] becomes encoding a render pass once beginRenderPass() is called sucessfully until endPass() is called on the returned GPURenderPassEncoder, at which point the [[state]] (if the encoder is still valid) reverts to open.

"encoding a compute pass"

Indicates the GPUCommandEncoder has an active GPUComputePassEncoder. The [[state]] becomes encoding a compute pass once beginComputePass() is called sucessfully until endPass() is called on the returned GPUComputePassEncoder, at which point the [[state]] (if the encoder is still valid) reverts to open.

"closed"

Indicates the GPUCommandEncoder is no longer available for any operations. The [[state]] becomes closed once finish() is called or the GPUCommandEncoder otherwise becomes invalid.

14.1.1. Creation

dictionary GPUCommandEncoderDescriptor : GPUObjectDescriptorBase {
    // TODO: reusability flag?
};

14.2. Copy Commands

14.2.1. GPUTextureDataLayout

dictionary GPUTextureDataLayout {
    GPUSize64 offset = 0;
    required GPUSize32 bytesPerRow;
    GPUSize32 rowsPerImage = 0;
};

A GPUTextureDataLayout 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.

• For 2d textures, data is copied between one or multiple contiguous images and array layers.

• For 3d textures, data is copied between one or multiple contiguous images and depth slices.

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.

bytesPerRow, of type GPUSize32

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

rowsPerImage, of type GPUSize32, defaulting to 0

rowsPerImage ÷ texel block height × bytesPerRow is the stride, in bytes, between the beginning of each image of data and the subsequent image.

14.2.2. GPUBufferCopyView

dictionary GPUBufferCopyView : GPUTextureDataLayout {
    required GPUBuffer buffer;
};

A GPUBufferCopyView contains the actual texture data placed in a buffer according to GPUTextureDataLayout.

14.2.3. GPUTextureCopyView

dictionary GPUTextureCopyView {
    required GPUTexture texture;
    GPUIntegerCoordinate mipLevel = 0;
    GPUOrigin3D origin = {};
};

A GPUTextureCopyView is a view of a sub-region of one or multiple contiguous texture subresources with the initial offset GPUOrigin3D in texels, used when copying data from or to a GPUTexture.

• origin: If unspecified, defaults to [0, 0, 0].