WebGPU

1. Introduction

This specification rocks.

2. Type Definitions

typedef long i32;
typedef unsigned long u32;
typedef unsigned long long u64;

2.1. Colors and 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 i32/u32.

dictionary GPUOrigin2DDict {
    u32 x = 0;
    u32 y = 0;
};
typedef (sequence<u32> or GPUOrigin2DDict) GPUOrigin2D;

dictionary GPUOrigin3DDict {
    u32 x = 0;
    u32 y = 0;
    u32 z = 0;
};
typedef (sequence<u32> or GPUOrigin3DDict) GPUOrigin3D;

dictionary GPUExtent3DDict {
    required u32 width;
    required u32 height;
    required u32 depth;
};
typedef (sequence<u32> or GPUExtent3DDict) GPUExtent3D;

2.2. Internal Objects

An internal object is a non-exposed conceptual 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).

2.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 DOMString? label;
};

label, of type DOMString, nullable

[[device]], of type device, readonly

An internal slot holding the device on which the object exists.

2.4. Object Descriptors

dictionary GPUObjectDescriptorBase {
    DOMString? label;
};

3. Initialization

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

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

[Exposed=Window]
interface GPU {
    // May reject with DOMException  // TODO: DOMException("OperationError")?
    Promise<GPUAdapter> requestAdapter(optional GPURequestAdapterOptions options);
};

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

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 reset, or were disconnected and reconnected).

3.1.1. GPUAdapter

A GPUAdapter refers to an adapter, and exposes its capabilities (extensions and limits).

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

    // May reject with DOMException  // TODO: DOMException("OperationError")?
    Promise<GPUDevice> requestDevice(optional GPUDeviceDescriptor descriptor);
};

GPUAdapter has the following attributes:

[[adapter]], of type adapter, readonly

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

name, of type DOMString, readonly

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

extensions, of type GPUExtensions, readonly

A GPUExtensions object which enumerates the extensions supported by the user agent, and whether each extension is supported by the underlying implementation.

• If an extension is not supported by the user agent, it will not be present in the object.

• If an extension is supported by the user agent, but not by the adapter, it will be false.

• If an extension is supported by the user agent and by the adapter, it will be true.

3.1.2. Getting an Adapter

To get a GPUAdapter, use requestAdapter().

dictionary GPURequestAdapterOptions {
    GPUPowerPreference powerPreference;
};

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

powerPreference, of type GPUPowerPreference

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

If unspecified, the user agent decides which class of adapter is most suitable.

Note: This hint may influence which GPU is used in a system with multiple GPUs. For example, a dual-GPU system might have one GPU that consumes less power at the expense of performance.

Note: Depending on the exact hardware configuration, such as 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 (e.g. battery percentage) and powerPreference, the user agent should select the same adapter.

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

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

3.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, all objects created from it become invalid.

A device has the following internal slots:

[[adapter]], of type adapter, readonly

The adapter from which this device was created.

When a device is created, its capabilities are set to those requested by the user in requestDevice() (which must be no greater than the capabilities specified by the adapter). These capabilities are enforced upon the usage of objects on the device, even if the underlying adapter can support higher capabilities.

3.2.1. GPUDevice

A GPUDevice refers to a device and exposes the capabilities with which the device was created. It is the top-level object through which WebGPU interfaces are created.

[Exposed=(Window, Worker), Serializable]
interface GPUDevice : EventTarget {
    readonly attribute GPUExtensions extensions;
    readonly attribute GPULimits limits;
    readonly attribute GPUAdapter adapter;

    GPUBuffer createBuffer(GPUBufferDescriptor descriptor);
    GPUMappedBuffer createBufferMapped(GPUBufferDescriptor descriptor);
    Promise<GPUMappedBuffer> createBufferMappedAsync(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);

    GPUQueue getQueue();
};
GPUDevice includes GPUObjectBase;

GPUDevice also has the following internal slots:

[[device]], of type device, readonly

The device that this GPUDevice refers to.

GPUDevice objects are serializable objects.

3.2.2. Getting a Device

To get a GPUDevice, use requestDevice().

dictionary GPUDeviceDescriptor : GPUObjectDescriptorBase {
    GPUExtensions extensions;
    GPULimits limits;

    // TODO: are other things configurable like queues?
};

extensions, of type GPUExtensions

The extensions to request of device creation.

limits, of type GPULimits

The limits to request of device creation.

dictionary GPUExtensions {
    boolean anisotropicFiltering = false;
};

dictionary GPULimits {
    u32 maxBindGroups = 4;
};

4. Buffers

4.1. GPUBuffer

interface GPUBuffer : GPUObjectBase {
    Promise<ArrayBuffer> mapReadAsync();
    Promise<ArrayBuffer> mapWriteAsync();
    void unmap();

    void destroy();
};

4.1.1. Creation

dictionary GPUBufferDescriptor : GPUObjectDescriptorBase {
    required u64 size;
    required GPUBufferUsageFlags usage;
};

4.2. Buffer Usage

typedef u32 GPUBufferUsageFlags;
interface GPUBufferUsage {
    const u32 NONE      = 0x0000;
    const u32 MAP_READ  = 0x0001;
    const u32 MAP_WRITE = 0x0002;
    const u32 COPY_SRC  = 0x0004;
    const u32 COPY_DST  = 0x0008;
    const u32 INDEX     = 0x0010;
    const u32 VERTEX    = 0x0020;
    const u32 UNIFORM   = 0x0040;
    const u32 STORAGE   = 0x0080;
    const u32 INDIRECT  = 0x0100;
};

4.3. Buffer Mapping

typedef sequence<any> GPUMappedBuffer;

GPUMappedBuffer is always a sequence of 2 elements, of types GPUBuffer and ArrayBuffer, respectively.

5. Textures

5.1. GPUTexture

interface GPUTexture : GPUObjectBase {
    GPUTextureView createView(optional GPUTextureViewDescriptor descriptor);

    void destroy();
};

5.1.1. Texture Creation

dictionary GPUTextureDescriptor : GPUObjectDescriptorBase {
    required GPUExtent3D size;
    u32 arrayLayerCount = 1;
    u32 mipLevelCount = 1;
    u32 sampleCount = 1;
    GPUTextureDimension dimension = "2d";
    required GPUTextureFormat format;
    required GPUTextureUsageFlags usage;
};

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

typedef u32 GPUTextureUsageFlags;
interface GPUTextureUsage {
    const u32 NONE              = 0x00;
    const u32 COPY_SRC          = 0x01;
    const u32 COPY_DST          = 0x02;
    const u32 SAMPLED           = 0x04;
    const u32 STORAGE           = 0x08;
    const u32 OUTPUT_ATTACHMENT = 0x10;
};

5.2. GPUTextureView

interface GPUTextureView : GPUObjectBase {
};

5.2.1. Texture View Creation

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

• format: If unspecified, defaults to the format of the texture.

• dimension: If unspecified, defaults to the dimension of the texture.

• mipLevelCount: If mipLevelCount == 0, the texture view will cover all the mipmap levels starting from baseMipLevel.

• arrayLayerCount: If arrayLayerCount == 0, the texture view will cover all the array layers starting from baseArrayLayer.

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

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

5.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 gamma compression and decompression are applied during the reading and writing of color values in the pixel. 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.

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 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"
};

6. Samplers

6.1. GPUSampler

interface GPUSampler : GPUObjectBase {
};

6.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 = "never";
};

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"
};

7. Resource Binding

7.1. GPUPipelineLayout

interface GPUPipelineLayout : GPUObjectBase {
};

7.1.1. Creation

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

7.2. GPUBindGroupLayout

interface GPUBindGroupLayout : GPUObjectBase {
};

7.2.1. Creation

dictionary GPUBindGroupLayoutDescriptor : GPUObjectDescriptorBase {
    required sequence<GPUBindGroupLayoutBinding> bindings;
};

dictionary GPUBindGroupLayoutBinding {
    required u32 binding;
    required GPUShaderStageFlags visibility;
    required GPUBindingType type;
    GPUTextureViewDimension textureDimension = "2d";
    GPUTextureComponentType textureComponentType = "float";
    boolean multisampled = false;
    boolean dynamic = false;
};

• textureDimension: For texture bindings only, we need to know the dimensions and multi-sampling properties at the layout creation time.

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

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

typedef u32 GPUShaderStageFlags;
interface GPUShaderStage {
    const u32 NONE     = 0x0;
    const u32 VERTEX   = 0x1;
    const u32 FRAGMENT = 0x2;
    const u32 COMPUTE  = 0x4;
};

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

7.3. GPUBindGroup

interface GPUBindGroup : GPUObjectBase {
};

7.3.1. Bind Group Creation

dictionary GPUBindGroupDescriptor : GPUObjectDescriptorBase {
    required GPUBindGroupLayout layout;
    required sequence<GPUBindGroupBinding> bindings;
};

typedef (GPUSampler or GPUTextureView or GPUBufferBinding) GPUBindingResource;

dictionary GPUBindGroupBinding {
    required u32 binding;
    required GPUBindingResource resource;
};

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

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

8. Shader Modules

8.1. GPUShaderModule

interface GPUShaderModule : GPUObjectBase {
};

8.1.1. Shader Module Creation

typedef (Uint32Array or DOMString) GPUShaderCode;

dictionary GPUShaderModuleDescriptor : GPUObjectDescriptorBase {
    required GPUShaderCode code;
};

Note: While the choice of shader language is undecided, GPUShaderModuleDescriptor will temporarily accept both text and binary input.

9. Pipelines

dictionary GPUPipelineDescriptorBase : GPUObjectDescriptorBase {
    required GPUPipelineLayout layout;
};

dictionary GPUProgrammableStageDescriptor {
    required GPUShaderModule module;
    required DOMString entryPoint;
    // TODO: other stuff like specialization constants?
};

9.1. GPUComputePipeline

interface GPUComputePipeline : GPUObjectBase {
};

9.1.1. Creation

dictionary GPUComputePipelineDescriptor : GPUPipelineDescriptorBase {
    required GPUProgrammableStageDescriptor computeStage;
};

9.2. GPURenderPipeline

interface GPURenderPipeline : GPUObjectBase {
};

9.2.1. Creation

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

    required GPUPrimitiveTopology primitiveTopology;
    GPURasterizationStateDescriptor rasterizationState;
    required sequence<GPUColorStateDescriptor> colorStates;
    GPUDepthStencilStateDescriptor depthStencilState;
    required GPUVertexInputDescriptor vertexInput;

    u32 sampleCount = 1;
    u32 sampleMask = 0xFFFFFFFF;
    boolean alphaToCoverageEnabled = false;
    // TODO: other properties
};

• sampleCount: Number of MSAA samples.

9.2.2. Primitive Topology

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

9.2.3. Rasterization State

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

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

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

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

9.2.4. Color State

dictionary GPUColorStateDescriptor {
    required GPUTextureFormat format;

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

typedef u32 GPUColorWriteFlags;
interface GPUColorWrite {
    const u32 NONE  = 0x0;
    const u32 RED   = 0x1;
    const u32 GREEN = 0x2;
    const u32 BLUE  = 0x4;
    const u32 ALPHA = 0x8;
    const u32 ALL   = 0xF;
};

9.2.4.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"
};

9.2.5. Depth/Stencil State

dictionary GPUDepthStencilStateDescriptor {
    required GPUTextureFormat format;

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

    required GPUStencilStateFaceDescriptor stencilFront;
    required GPUStencilStateFaceDescriptor stencilBack;

    u32 stencilReadMask = 0xFFFFFFFF;
    u32 stencilWriteMask = 0xFFFFFFFF;
};

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

9.2.6. Vertex Input

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

9.2.6.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 GPUVertexAttributeDescriptor {
    u64 offset = 0;
    required GPUVertexFormat format;
    required u32 shaderLocation;
};

dictionary GPUVertexBufferDescriptor {
    required u64 stride;
    GPUInputStepMode stepMode = "vertex";
    required sequence<GPUVertexAttributeDescriptor> attributeSet;
};

dictionary GPUVertexInputDescriptor {
    GPUIndexFormat indexFormat = "uint32";
    required sequence<GPUVertexBufferDescriptor?> vertexBuffers;
};

10. Command Buffers

10.1. GPUCommandBuffer

interface GPUCommandBuffer : GPUObjectBase {
};

10.1.1. Creation

dictionary GPUCommandBufferDescriptor : GPUObjectDescriptorBase {
};

11. Command Encoding

11.1. GPUCommandEncoder

interface GPUCommandEncoder : GPUObjectBase {
    GPURenderPassEncoder beginRenderPass(GPURenderPassDescriptor descriptor);
    GPUComputePassEncoder beginComputePass(optional GPUComputePassDescriptor descriptor);

    void copyBufferToBuffer(
        GPUBuffer source,
        u64 sourceOffset,
        GPUBuffer destination,
        u64 destinationOffset,
        u64 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 copyImageBitmapToTexture(
        GPUImageBitmapCopyView source,
        GPUTextureCopyView destination,
        GPUExtent3D copySize);

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

    GPUCommandBuffer finish(optional GPUCommandBufferDescriptor descriptor);
};

• copyImageBitmapToTexture():

  • For now, copySize.z must be 1.

11.1.1. Creation

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

11.2. Copy Commands

dictionary GPUBufferCopyView {
    required GPUBuffer buffer;
    u64 offset = 0;
    required u32 rowPitch;
    required u32 imageHeight;
};

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

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

dictionary GPUImageBitmapCopyView {
    required ImageBitmap imageBitmap;
    GPUOrigin2D origin;
};

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

11.3. Programmable Passes

interface GPUProgrammablePassEncoder : GPUObjectBase {
    void setBindGroup(u32 index, GPUBindGroup bindGroup,
                      optional sequence<u64> dynamicOffsets);

    void pushDebugGroup(DOMString groupLabel);
    void popDebugGroup();
    void insertDebugMarker(DOMString markerLabel);
};

12. Compute Passes

12.1. GPUComputePassEncoder

interface GPUComputePassEncoder : GPUProgrammablePassEncoder {
    void setPipeline(GPUComputePipeline pipeline);
    void dispatch(u32 x, optional u32 y = 1, optional u32 z = 1);
    void dispatchIndirect(GPUBuffer indirectBuffer, u64 indirectOffset);

    void endPass();
};

12.1.1. Creation

dictionary GPUComputePassDescriptor : GPUObjectDescriptorBase {
};

13. Render Passes

13.1. GPURenderPassEncoder

interface GPURenderEncoderBase : GPUProgrammablePassEncoder {
    void setPipeline(GPURenderPipeline pipeline);

    void setIndexBuffer(GPUBuffer buffer, optional u64 offset = 0);
    void setVertexBuffers(u32 startSlot,
                          sequence<GPUBuffer> buffers, sequence<u64> offsets);

    void draw(u32 vertexCount, u32 instanceCount,
              u32 firstVertex, u32 firstInstance);
    void drawIndexed(u32 indexCount, u32 instanceCount,
                     u32 firstIndex, i32 baseVertex, u32 firstInstance);

    void drawIndirect(GPUBuffer indirectBuffer, u64 indirectOffset);
    void drawIndexedIndirect(GPUBuffer indirectBuffer, u64 indirectOffset);
};

interface GPURenderPassEncoder : GPURenderEncoderBase {
    void setViewport(float x, float y,
                     float width, float height,
                     float minDepth, float maxDepth);

    void setScissorRect(u32 x, u32 y, u32 width, u32 height);

    void setBlendColor(GPUColor color);
    void setStencilReference(u32 reference);

    void executeBundles(sequence<GPURenderBundle> bundles);
    void endPass();
};

• In indirect draw calls, the base instance field (inside the indirect buffer data) must be set to zero.

• setScissorRect():

  • An error is generated if width or height is not greater than 0.

When a GPURenderPassEncoder is created, it has the following default state:

• Viewport:

  • x, y = 0.0, 0.0

  • width, height = the dimensions of the pass’s render targets

  • minDepth, maxDepth = 0.0, 1.0

• Scissor rectangle:

  • x, y = 0, 0

  • width, height = the dimensions of the pass’s render targets

13.1.1. Creation

dictionary GPURenderPassDescriptor : GPUObjectDescriptorBase {
    required sequence<GPURenderPassColorAttachmentDescriptor> colorAttachments;
    GPURenderPassDepthStencilAttachmentDescriptor depthStencilAttachment;
};

13.1.1.1. Color Attachments

dictionary GPURenderPassColorAttachmentDescriptor {
    required GPUTextureView attachment;
    GPUTextureView resolveTarget;

    required (GPULoadOp or GPUColor) loadValue;
    required GPUStoreOp storeOp;
};

13.1.1.2. Depth/Stencil Attachments

dictionary GPURenderPassDepthStencilAttachmentDescriptor {
    required GPUTextureView attachment;

    required (GPULoadOp or float) depthLoadValue;
    required GPUStoreOp depthStoreOp;

    required (GPULoadOp or u32) stencilLoadValue;
    required GPUStoreOp stencilStoreOp;
};

13.1.2. Load & Store Operations

enum GPULoadOp {
    "load"
};

enum GPUStoreOp {
    "store",
    "clear"
};

14. Bundles

14.1. GPURenderBundle

interface GPURenderBundle : GPUObjectBase {
};

14.1.1. Creation

dictionary GPURenderBundleDescriptor : GPUObjectDescriptorBase {
};

interface GPURenderBundleEncoder : GPURenderEncoderBase {
    GPURenderBundle finish(optional GPURenderBundleDescriptor descriptor);
};

14.1.2. Encoding

dictionary GPURenderBundleEncoderDescriptor : GPUObjectDescriptorBase {
    required sequence<GPUTextureFormat> colorFormats;
    GPUTextureFormat depthStencilFormat;
    u32 sampleCount = 1;
};

15. Queues

interface GPUQueue : GPUObjectBase {
    void submit(sequence<GPUCommandBuffer> buffers);

    GPUFence createFence(optional GPUFenceDescriptor descriptor);
    void signal(GPUFence fence, u64 signalValue);
};

15.1. GPUFence

interface GPUFence : GPUObjectBase {
    u64 getCompletedValue();
    Promise<void> onCompletion(u64 completionValue);
};

15.1.1. Creation

dictionary GPUFenceDescriptor : GPUObjectDescriptorBase {
    u64 initialValue = 0;
};

16. Canvas Rendering and Swap Chain

interface GPUCanvasContext {
    GPUSwapChain configureSwapChain(GPUSwapChainDescriptor descriptor);

    Promise<GPUTextureFormat> getSwapChainPreferredFormat(GPUDevice device);
};

• configureSwapChain(): Configures the swap chain for this canvas, and returns a new GPUSwapChain object representing it. Destroys any swapchain previously returned by configureSwapChain, including all of the textures it has produced.

dictionary GPUSwapChainDescriptor : GPUObjectDescriptorBase {
    required GPUDevice device;
    required GPUTextureFormat format;
    GPUTextureUsageFlags usage = 0x10;  // GPUTextureUsage.OUTPUT_ATTACHMENT
};

interface GPUSwapChain : GPUObjectBase {
    GPUTexture getCurrentTexture();
};

17. Errors & Debugging

17.1. Fatal Errors

interface GPUDeviceLostInfo {
    readonly attribute DOMString message;
};

partial interface GPUDevice {
    readonly attribute Promise<GPUDeviceLostInfo> lost;
};

17.2. Error Scopes

enum GPUErrorFilter {
    "none",
    "out-of-memory",
    "validation"
};

[
    Constructor()
]
interface GPUOutOfMemoryError {};

[
    Constructor(DOMString message)
]
interface GPUValidationError {
    readonly attribute DOMString message;
};

typedef (GPUOutOfMemoryError or GPUValidationError) GPUError;

partial interface GPUDevice {
    void pushErrorScope(GPUErrorFilter filter);
    Promise<GPUError?> popErrorScope();
};

17.3. Telemetry

[
    Constructor(DOMString type, GPUUncapturedErrorEventInit gpuUncapturedErrorEventInitDict),
    Exposed=Window
]
interface GPUUncapturedErrorEvent : Event {
    readonly attribute GPUError error;
};

dictionary GPUUncapturedErrorEventInit : EventInit {
    required GPUError error;
};

partial interface GPUDevice {
    [Exposed=Window]
    attribute EventHandler onuncapturederror;
};