WebGPU

Editor’s Draft,

Issue Tracking:
GitHub
Editors:
(Mozilla)
(Apple)
(Google)
Participate:
File an issue (open issues)

Abstract

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

Status of this document

This specification was published by the GPU for the Web Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups.

1. Introduction

This specification rocks.

2. Type Definitions

typedef unsigned long GPUFlags;
typedef unsigned long long GPUBufferSize;

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 32-bit signed/unsigned integers and single-precision floats.

dictionary GPUOrigin2DDict {
    unsigned long x = 0;
    unsigned long y = 0;
};
typedef (sequence<unsigned long> or GPUOrigin2DDict) GPUOrigin2D;
dictionary GPUOrigin3DDict {
    unsigned long x = 0;
    unsigned long y = 0;
    unsigned long z = 0;
};
typedef (sequence<unsigned long> or GPUOrigin3DDict) GPUOrigin3D;
dictionary GPUExtent3DDict {
    required unsigned long width;
    required unsigned long height;
    required unsigned long depth;
};
typedef (sequence<unsigned long> 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.

Their serialization steps, given value, serialized, and forStorage, are:
  1. If forStorage is true, throw a "DataCloneError".

  2. Set serialized.device to the value of value.[[device]].

Their deserialization steps, given serialized and value, are:
  1. Set value.[[device]] to serialized.device.

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.

  1. If the requested configuration is not available (i.e. the requested extensions or limits cannot be supported), requestDevice() rejects with a "NotSupportedError".

  2. Otherwise, a GPUDevice is created with the GPUExtensions and GPULimits specified.

dictionary GPUExtensions {
    boolean anisotropicFiltering = false;
};
dictionary GPULimits {
    unsigned long maxBindGroups = 4;
    unsigned long maxDynamicUniformBuffersPerPipelineLayout = 8;
    unsigned long maxDynamicStorageBuffersPerPipelineLayout = 4;
    unsigned long maxSampledTexturesPerShaderStage = 16;
    unsigned long maxSamplersPerShaderStage = 16;
    unsigned long maxStorageBuffersPerPipelineLayout = 8;
    unsigned long maxStorageTexturesPerShaderStage = 4;
    unsigned long maxUniformBuffersPerShaderStage = 12;
};

4. GPUBuffer

A GPUBuffer represents a block of memory that can be used in GPU operations. Data is stored in linear layout, meaning that each byte of the allocation can be addressed by its offset from the start of the GPUBuffer, subject to alignment restrictions depending on the operation.

GPUBuffer has the following internal slots:

[[size]] of type GPUBufferSize.

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.

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

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

4.1. Creation

A GPUBuffer can be created in the "unmapped" state using the GPUDevice.createBuffer(descriptor) method.

4.1.1. GPUBufferDescriptor

This specifies the options to use in creating a GPUBuffer.

dictionary GPUBufferDescriptor : GPUObjectDescriptorBase {
    required GPUBufferSize size;
    required GPUBufferUsageFlags usage;
};
validating GPUBufferDescriptor(device, descriptor)
  1. If device is lost return false.

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

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

  4. Return true.

4.1.2. GPUDevice.createBuffer(descriptor)

createBuffer(descriptor)
  1. If the result of validating GPUBufferDescriptor(this, descriptor) is false:

    1. Record a validation error in the current scope.

    2. Create an error buffer and return the result.

  2. Let b be a new GPUBuffer object.

  3. Set the [[size]] slot of b to the value of the size attribute of descriptor.

  4. Set the [[usage]] slot of b to the value of the usage attribute of descriptor.

  5. Set the [[state]] internal slot of b to "unmapped".

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

  7. Return b.

4.2. Buffer Usage

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

4.3. Buffer Mapping

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

    void destroy();
};

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;
    unsigned long arrayLayerCount = 1;
    unsigned long mipLevelCount = 1;
    unsigned long sampleCount = 1;
    GPUTextureDimension dimension = "2d";
    required GPUTextureFormat format;
    required GPUTextureUsageFlags usage;
};
enum GPUTextureDimension {
    "1d",
    "2d",
    "3d"
};
typedef GPUFlags GPUTextureUsageFlags;
interface GPUTextureUsage {
    const GPUFlags NONE              = 0x00;
    const GPUFlags COPY_SRC          = 0x01;
    const GPUFlags COPY_DST          = 0x02;
    const GPUFlags SAMPLED           = 0x04;
    const GPUFlags STORAGE           = 0x08;
    const GPUFlags 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";
    unsigned long baseMipLevel = 0;
    unsigned long mipLevelCount = 0;
    unsigned long baseArrayLayer = 0;
    unsigned long arrayLayerCount = 0;
};
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.

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

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

[Serializable]
interface GPUBindGroupLayout : GPUObjectBase {
};

7.1.1. Creation

A GPUBindGroupLayout is created via GPUDevice.createBindGroupLayout().

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

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

dictionary GPUBindGroupLayoutBinding {
    required unsigned long binding;
    required GPUShaderStageFlags visibility;
    required GPUBindingType type;
    GPUTextureViewDimension textureDimension = "2d";
    GPUTextureComponentType textureComponentType = "float";
    boolean multisampled = false;
    boolean hasDynamicOffset = false;
};
typedef GPUFlags GPUShaderStageFlags;
interface GPUShaderStage {
    const GPUFlags NONE     = 0x0;
    const GPUFlags VERTEX   = 0x1;
    const GPUFlags FRAGMENT = 0x2;
    const GPUFlags COMPUTE  = 0x4;
};
enum GPUBindingType {
    "uniform-buffer",
    "storage-buffer",
    "readonly-storage-buffer",
    "sampler",
    "sampled-texture",
    "storage-texture"
    // TODO: other binding types
};

A GPUBindGroupLayout object has the following internal slots:

[[bindings]] of type sequence<GPUBindGroupLayoutBinding>.

The set of GPUBindGroupLayoutBindings this GPUBindGroupLayout describes.

7.1.2. GPUDevice.createBindGroupLayout(GPUBindGroupLayoutDescriptor)

The createBindGroupLayout(descriptor) method is used to create GPUBindGroupLayouts.

  1. Ensure device validation is not violated.

  2. Let layout be a new valid GPUBindGroupLayout object.

  3. For each GPUBindGroupLayoutBinding bindingDescriptor in descriptor.bindings:

    1. Ensure bindingDescriptor.binding does not violate binding validation.

    2. If bindingDescriptor.type is uniform-buffer:

      1. Ensure uniform buffer validation is not violated.

      2. If bindingDescriptor.hasDynamicOffset is true, ensure dynamic uniform buffer validation is not violated.

    3. If bindingDescriptor.type is storage-buffer or readonly-storage-buffer:

      1. Ensure storage buffer validation is not violated.

      2. If bindingDescriptor.hasDynamicOffset is true, ensure dynamic storage buffer validation is not violated.

    4. If bindingDescriptor.type is sampled-texture , ensure sampled texture validation is not violated.

    5. If bindingDescriptor.type is storage-texture , ensure storage texture validation is not violated.

    6. If bindingDescriptor.type is sampler , ensure sampler validation is not violated.

    7. Insert bindingDescriptor into layout.[[bindings]].

  4. Return layout.

Validation Conditions

If any of the following conditions are violated:
  1. Generate a GPUValidationError in the current scope with appropriate error message.

  2. Create a new invalid GPUBindGroupLayout and return the result.

device validation: The GPUDevice must not be lost.

binding validation: Each bindingDescriptor.binding in descriptor must be unique.

uniform buffer validation: There must be GPULimits.maxUniformBuffersPerShaderStage or fewer bindingDescriptors of type uniform-buffer visible on each shader stage in descriptor.

dynamic uniform buffer validation: There must be GPULimits.maxDynamicUniformBuffersPerPipelineLayout or fewer bindingDescriptors of type uniform-buffer with hasDynamicOffset set to true in descriptor that are visible to any shader stage.

storage buffer validation: There must be GPULimits.maxStorageBuffersPerPipelineLayout or fewer bindingDescriptors of type storage-buffer in descriptor that are visible to any shader stage.

dynamic storage buffer validation: There must be GPULimits.maxDynamicStorageBuffersPerPipelineLayout or fewer bindingDescriptors of type storage-buffer with hasDynamicOffset set to true in descriptor that are visible to any shader stage.

sampled texture validation: There must be GPULimits.maxSampledTexturesPerShaderStage or fewer bindingDescriptors of type sampled-texture visible on each shader stage in descriptor.

storage texture validation: There must be GPULimits.maxStorageTexturesPerShaderStage or fewer bindingDescriptors of type storage-texture visible on each shader stage in descriptor.

sampler validation: There must be GPULimits.maxSamplersPerShaderStage or fewer bindingDescriptors of type sampler visible on each shader stage in descriptor.

7.2. GPUBindGroup

interface GPUBindGroup : GPUObjectBase {
};

7.2.1. Bind Group Creation

dictionary GPUBindGroupDescriptor : GPUObjectDescriptorBase {
    required GPUBindGroupLayout layout;
    required sequence<GPUBindGroupBinding> bindings;
};
typedef (GPUSampler or GPUTextureView or GPUBufferBinding) GPUBindingResource;

dictionary GPUBindGroupBinding {
    required unsigned long binding;
    required GPUBindingResource resource;
};
dictionary GPUBufferBinding {
    required GPUBuffer buffer;
    GPUBufferSize offset = 0;
    GPUBufferSize size;
};

7.3. GPUPipelineLayout

interface GPUPipelineLayout : GPUObjectBase {
};

7.3.1. Creation

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

8. Shader Modules

8.1. GPUShaderModule

[Serializable]
interface GPUShaderModule : 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 immutable, there are no race conditions.

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

[Serializable]
interface GPUComputePipeline : GPUObjectBase {
};

9.1.1. Creation

dictionary GPUComputePipelineDescriptor : GPUPipelineDescriptorBase {
    required GPUProgrammableStageDescriptor computeStage;
};

9.2. GPURenderPipeline

[Serializable]
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;
    GPUVertexInputDescriptor vertexInput = {};

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

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

    long 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 GPUFlags GPUColorWriteFlags;
interface GPUColorWrite {
    const GPUFlags NONE  = 0x0;
    const GPUFlags RED   = 0x1;
    const GPUFlags GREEN = 0x2;
    const GPUFlags BLUE  = 0x4;
    const GPUFlags ALPHA = 0x8;
    const GPUFlags 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;

    unsigned long stencilReadMask = 0xFFFFFFFF;
    unsigned long 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.

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 {
    GPUBufferSize offset = 0;
    required GPUVertexFormat format;
    required unsigned long shaderLocation;
};
dictionary GPUVertexBufferDescriptor {
    required GPUBufferSize stride;
    GPUInputStepMode stepMode = "vertex";
    required sequence<GPUVertexAttributeDescriptor> attributeSet;
};
dictionary GPUVertexInputDescriptor {
    GPUIndexFormat indexFormat = "uint32";
    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,
        GPUBufferSize sourceOffset,
        GPUBuffer destination,
        GPUBufferSize destinationOffset,
        GPUBufferSize 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);
};

11.1.1. Creation

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

11.2. Copy Commands

dictionary GPUBufferCopyView {
    required GPUBuffer buffer;
    GPUBufferSize offset = 0;
    required unsigned long rowPitch;
    required unsigned long imageHeight;
};
dictionary GPUTextureCopyView {
    required GPUTexture texture;
    unsigned long mipLevel = 0;
    unsigned long arrayLayer = 0;
    GPUOrigin3D origin;
};
dictionary GPUImageBitmapCopyView {
    required ImageBitmap imageBitmap;
    GPUOrigin2D origin;
};

11.3. Programmable Passes

interface GPUProgrammablePassEncoder : GPUObjectBase {
    void setBindGroup(unsigned long index, GPUBindGroup bindGroup,
                      optional sequence<GPUBufferSize> dynamicOffsets);

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

Debug groups in a GPUCommandEncoder or GPUProgrammablePassEncoder must be well nested.

12. Compute Passes

12.1. GPUComputePassEncoder

interface GPUComputePassEncoder : GPUProgrammablePassEncoder {
    void setPipeline(GPUComputePipeline pipeline);
    void dispatch(unsigned long x, optional unsigned long y = 1, optional unsigned long z = 1);
    void dispatchIndirect(GPUBuffer indirectBuffer, GPUBufferSize 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 GPUBufferSize offset = 0);
    void setVertexBuffers(unsigned long startSlot,
                          sequence<GPUBuffer> buffers, sequence<GPUBufferSize> offsets);

    void draw(unsigned long vertexCount, unsigned long instanceCount,
              unsigned long firstVertex, unsigned long firstInstance);
    void drawIndexed(unsigned long indexCount, unsigned long instanceCount,
                     unsigned long firstIndex, long baseVertex, unsigned long firstInstance);

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

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

    void setScissorRect(unsigned long x, unsigned long y, unsigned long width, unsigned long height);

    void setBlendColor(GPUColor color);
    void setStencilReference(unsigned long reference);

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

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

When a GPURenderBundle is executed, it does not inherit the pass’s pipeline, bind groups, or vertex or index buffers. After a GPURenderBundle has executed, the pass’s pipeline, bind groups, and vertex and index buffers are cleared. If zero GPURenderBundles are executed, the command buffer state is unchanged.

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;
    GPUStoreOp storeOp = "store";
};
13.1.1.2. Depth/Stencil Attachments
dictionary GPURenderPassDepthStencilAttachmentDescriptor {
    required GPUTextureView attachment;

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

    required (GPULoadOp or unsigned long) 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;
    unsigned long sampleCount = 1;
};

15. Queues

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

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

15.1. GPUFence

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

15.1.1. Creation

dictionary GPUFenceDescriptor : GPUObjectDescriptorBase {
    unsigned long long initialValue = 0;
};

16. Canvas Rendering and Swap Chain

interface GPUCanvasContext {
    GPUSwapChain configureSwapChain(GPUSwapChainDescriptor descriptor);

    Promise<GPUTextureFormat> getSwapChainPreferredFormat(GPUDevice device);
};
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();
};

popErrorScope() throws OperationError if there are no error scopes on the stack.

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

18. Temporary usages of non-exported dfns #

Eventually all of these should disappear but they are useful to avoid warning while building the specification.

mapped destroyed

Conformance

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[DOM]
Anne van Kesteren. DOM Standard. Living Standard. URL: https://dom.spec.whatwg.org/
[ECMASCRIPT]
ECMAScript Language Specification. URL: https://tc39.github.io/ecma262/
[HTML]
Anne van Kesteren; et al. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[WebIDL]
Boris Zbarsky. Web IDL. 15 December 2016. ED. URL: https://heycam.github.io/webidl/

IDL Index

typedef unsigned long GPUFlags;
typedef unsigned long long GPUBufferSize;

dictionary GPUColorDict {
    required double r;
    required double g;
    required double b;
    required double a;
};
typedef (sequence<double> or GPUColorDict) GPUColor;

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

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

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

interface mixin GPUObjectBase {
    attribute DOMString? label;
};

dictionary GPUObjectDescriptorBase {
    DOMString? label;
};

[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);
};

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

dictionary GPURequestAdapterOptions {
    GPUPowerPreference powerPreference;
};

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

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

dictionary GPUDeviceDescriptor : GPUObjectDescriptorBase {
    GPUExtensions extensions;
    GPULimits limits;

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

dictionary GPUExtensions {
    boolean anisotropicFiltering = false;
};

dictionary GPULimits {
    unsigned long maxBindGroups = 4;
    unsigned long maxDynamicUniformBuffersPerPipelineLayout = 8;
    unsigned long maxDynamicStorageBuffersPerPipelineLayout = 4;
    unsigned long maxSampledTexturesPerShaderStage = 16;
    unsigned long maxSamplersPerShaderStage = 16;
    unsigned long maxStorageBuffersPerPipelineLayout = 8;
    unsigned long maxStorageTexturesPerShaderStage = 4;
    unsigned long maxUniformBuffersPerShaderStage = 12;
};

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

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

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

    void destroy();
};

typedef sequence<any> GPUMappedBuffer;

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

    void destroy();
};

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

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

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

interface GPUTextureView : GPUObjectBase {
};

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

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

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

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

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

    // 32-bit formats
    "r32uint",
    "r32sint",
    "r32float",
    "rg16uint",
    "rg16sint",
    "rg16float",
    "rgba8unorm",
    "rgba8unorm-srgb",
    "rgba8snorm",
    "rgba8uint",
    "rgba8sint",
    "bgra8unorm",
    "bgra8unorm-srgb",
    // Packed 32-bit formats
    "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"
};

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

interface GPUSampler : GPUObjectBase {
};

dictionary GPUSamplerDescriptor : GPUObjectDescriptorBase {
    GPUAddressMode addressModeU = "clamp-to-edge";
    GPUAddressMode addressModeV = "clamp-to-edge";
    GPUAddressMode addressModeW = "clamp-to-edge";
    GPUFilterMode magFilter = "nearest";
    GPUFilterMode minFilter = "nearest";
    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"
};

[Serializable]
interface GPUBindGroupLayout : GPUObjectBase {
};

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

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

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

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

interface GPUBindGroup : GPUObjectBase {
};

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

typedef (GPUSampler or GPUTextureView or GPUBufferBinding) GPUBindingResource;

dictionary GPUBindGroupBinding {
    required unsigned long binding;
    required GPUBindingResource resource;
};

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

interface GPUPipelineLayout : GPUObjectBase {
};

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

[Serializable]
interface GPUShaderModule : GPUObjectBase {
};

typedef (Uint32Array or DOMString) GPUShaderCode;

dictionary GPUShaderModuleDescriptor : GPUObjectDescriptorBase {
    required GPUShaderCode code;
};

dictionary GPUPipelineDescriptorBase : GPUObjectDescriptorBase {
    required GPUPipelineLayout layout;
};

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

[Serializable]
interface GPUComputePipeline : GPUObjectBase {
};

dictionary GPUComputePipelineDescriptor : GPUPipelineDescriptorBase {
    required GPUProgrammableStageDescriptor computeStage;
};

[Serializable]
interface GPURenderPipeline : GPUObjectBase {
};

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

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

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

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

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

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

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

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

dictionary GPUColorStateDescriptor {
    required GPUTextureFormat format;

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

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

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

dictionary GPUDepthStencilStateDescriptor {
    required GPUTextureFormat format;

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

    required GPUStencilStateFaceDescriptor stencilFront;
    required GPUStencilStateFaceDescriptor stencilBack;

    unsigned long stencilReadMask = 0xFFFFFFFF;
    unsigned long stencilWriteMask = 0xFFFFFFFF;
};

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

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

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 {
    GPUBufferSize offset = 0;
    required GPUVertexFormat format;
    required unsigned long shaderLocation;
};

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

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

interface GPUCommandBuffer : GPUObjectBase {
};

dictionary GPUCommandBufferDescriptor : GPUObjectDescriptorBase {
};

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

    void copyBufferToBuffer(
        GPUBuffer source,
        GPUBufferSize sourceOffset,
        GPUBuffer destination,
        GPUBufferSize destinationOffset,
        GPUBufferSize 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);
};

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

dictionary GPUBufferCopyView {
    required GPUBuffer buffer;
    GPUBufferSize offset = 0;
    required unsigned long rowPitch;
    required unsigned long imageHeight;
};

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

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

interface GPUProgrammablePassEncoder : GPUObjectBase {
    void setBindGroup(unsigned long index, GPUBindGroup bindGroup,
                      optional sequence<GPUBufferSize> dynamicOffsets);

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

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

    void endPass();
};

dictionary GPUComputePassDescriptor : GPUObjectDescriptorBase {
};

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

    void setIndexBuffer(GPUBuffer buffer, optional GPUBufferSize offset = 0);
    void setVertexBuffers(unsigned long startSlot,
                          sequence<GPUBuffer> buffers, sequence<GPUBufferSize> offsets);

    void draw(unsigned long vertexCount, unsigned long instanceCount,
              unsigned long firstVertex, unsigned long firstInstance);
    void drawIndexed(unsigned long indexCount, unsigned long instanceCount,
                     unsigned long firstIndex, long baseVertex, unsigned long firstInstance);

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

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

    void setScissorRect(unsigned long x, unsigned long y, unsigned long width, unsigned long height);

    void setBlendColor(GPUColor color);
    void setStencilReference(unsigned long reference);

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

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

dictionary GPURenderPassColorAttachmentDescriptor {
    required GPUTextureView attachment;
    GPUTextureView resolveTarget;

    required (GPULoadOp or GPUColor) loadValue;
    GPUStoreOp storeOp = "store";
};

dictionary GPURenderPassDepthStencilAttachmentDescriptor {
    required GPUTextureView attachment;

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

    required (GPULoadOp or unsigned long) stencilLoadValue;
    required GPUStoreOp stencilStoreOp;
};

enum GPULoadOp {
    "load"
};

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

interface GPURenderBundle : GPUObjectBase {
};

dictionary GPURenderBundleDescriptor : GPUObjectDescriptorBase {
};

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

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

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

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

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

dictionary GPUFenceDescriptor : GPUObjectDescriptorBase {
    unsigned long long initialValue = 0;
};

interface GPUCanvasContext {
    GPUSwapChain configureSwapChain(GPUSwapChainDescriptor descriptor);

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

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

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

interface GPUDeviceLostInfo {
    readonly attribute DOMString message;
};

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

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

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