WebGPU

1. Introduction

This section is non-normative.

Graphics Processing Units, or GPUs for short, have been essential in enabling rich rendering and computational applications in personal computing. WebGPU is an API that exposes the capabilities of GPU hardware for the Web. The API is designed from the ground up to efficiently map to (post-2014) native GPU APIs. WebGPU is not related to WebGL and does not explicitly target OpenGL ES.

WebGPU sees physical GPU hardware as GPUAdapters. It provides a connection to an adapter via GPUDevice, which manages resources, and the device’s GPUQueues, which execute commands. GPUDevice may have its own memory with high-speed access to the processing units. GPUBuffer and GPUTexture are the physical resources backed by GPU memory. GPUCommandBuffer and GPURenderBundle are containers for user-recorded commands. GPUShaderModule contains shader code. The other resources, such as GPUSampler or GPUBindGroup, configure the way physical resources are used by the GPU.

GPUs execute commands encoded in GPUCommandBuffers by feeding data through a pipeline, which is a mix of fixed-function and programmable stages. Programmable stages execute shaders, which are special programs designed to run on GPU hardware. Most of the state of a pipeline is defined by a GPURenderPipeline or a GPUComputePipeline object. The state not included in these pipeline objects is set during encoding with commands, such as beginRenderPass() or setBlendConstant().

2. Malicious use considerations

This section is non-normative. It describes the risks associated with exposing this API on the Web.

2.1. Security Considerations

The security requirements for WebGPU are the same as ever for the web, and are likewise non-negotiable. The general approach is strictly validating all the commands before they reach GPU, ensuring that a page can only work with its own data.

2.1.1. CPU-based undefined behavior

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

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

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

2.1.2. GPU-based undefined behavior

WebGPU shaders are executed by the compute units inside GPU hardware. In native APIs, some of the shader instructions may result in undefined behavior on the GPU. In order to address that, the shader instruction set and its defined behaviors are strictly defined by WebGPU. When a shader is provided to createShaderModule(), the WebGPU implementation has to validate it before doing any translation (to platform-specific shaders) or transformation passes.

2.1.3. Uninitialized data

Generally, allocating new memory may expose the leftover data of other applications running on the system. In order to address that, WebGPU conceptually initializes all the resources to zero, although in practice an implementation may skip this step if it sees the developer initializing the contents manually. This includes variables and shared workgroup memory inside shaders.

The precise mechanism of clearing the workgroup memory can differ between platforms. If the native API does not provide facilities to clear it, the WebGPU implementation transforms the compute shader to first do a clear across all invocations, synchronize them, and continue executing developer’s code.

2.1.4. Out-of-bounds access in shaders

Shaders can access physical resources either directly (for example, as a "uniform" GPUBufferBinding), or via texture units, which are fixed-function hardware blocks that handle texture coordinate conversions. Validation on the API side can only guarantee that all the inputs to the shader are provided and they have the correct usage and types. The host API side can not guarantee that the data is accessed within bounds if the texture units are not involved.

define the host API distinct from the shader API

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

Alternatively, an implementation may transform the shader code by inserting manual bounds checks. When this path is taken, the out-of-bound checks only apply to array indexing. They aren’t needed for plain field access of shader structures due to the minBindingSize validation on the host side.

If the shader attempts to load data outside of physical resource bounds, the implementation is allowed to:

1. return a value at a different location within the resource bounds

2. return a value vector of "(0, 0, 0, X)" with any "X"

3. partially discard the draw or dispatch call

If the shader attempts to write data outside of physical resource bounds, the implementation is allowed to:

1. write the value to a different location within the resource bounds

2. discard the write operation

3. partially discard the draw or dispatch call

2.1.5. Invalid data

When uploading floating-point data from CPU to GPU, or generating it on the GPU, we may end up with a binary representation that doesn’t correspond to a valid number, such as infinity or NaN (not-a-number). The GPU behavior in this case is subject to the accuracy of the GPU hardware implementation of the IEEE-754 standard. WebGPU guarantees that introducing invalid floating-point numbers would only affect the results of arithmetic computations and will not have other side effects.

2.1.6. Driver bugs

GPU drivers are subject to bugs like any other software. If a bug occurs, an attacker could possibly exploit the incorrect behavior of the driver to get access to unprivileged data. In order to reduce the risk, the WebGPU working group will coordinate with GPU vendors to integrate the WebGPU Conformance Test Suite (CTS) as part of their driver testing process, like it was done for WebGL. WebGPU implementations are expected to have workarounds for some of the discovered bugs, and disable WebGPU on drivers with known bugs that can’t be worked around.

2.1.7. Timing attacks

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

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

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

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

2.1.8. Row hammer attacks

Row hammer is a class of attacks that exploit the leaking of states in DRAM cells. It could be used on GPU. WebGPU does not have any specific mitigations in place, and relies on platform-level solutions, such as reduced memory refresh intervals.

2.1.9. Denial of service

WebGPU applications have access to GPU memory and compute units. A WebGPU implementation may limit the available GPU memory to an application, in order to keep other applications responsive. For GPU processing time, a WebGPU implementation may set up "watchdog" timer that makes sure an application doesn’t cause GPU unresponsiveness for more than a few seconds. These measures are similar to those used in WebGL.

2.1.10. Workload identification

WebGPU provides access to constrained global resources shared between different programs (and web pages) running on the same machine. An application can try to indirectly probe how constrained these global resources are, in order to reason about workloads performed by other open web pages, based on the patterns of usage of these shared resources. These issues are generally analogous to issues with Javascript, such as system memory and CPU execution throughput. WebGPU does not provide any additional mitigations for this.

2.1.11. Memory resources

WebGPU exposes fallible allocations from machine-global memory heaps, such as VRAM. This allows for probing the size of the system’s remaining available memory (for a given heap type) by attempting to allocate and watching for allocation failures.

GPUs internally have one or more (typically only two) heaps of memory shared by all running applications. When a heap is depleted, WebGPU would fail to create a resource. This is observable, which may allow a malicious application to guess what heaps are used by other applications, and how much they allocate from them.

2.1.12. Computation resources

If one site uses WebGPU at the same time as another, it may observe the increase in time it takes to process some work. For example, if a site constantly submits compute workloads and tracks completion of work on the queue, it may observe that something else also started using the GPU.

A GPU has many parts that can be tested independently, such as the arithmetic units, texture sampling units, atomic units, etc. A malicious application may sense when some of these units are stressed, and attempt to guess the workload of another application by analyzing the stress patterns. This is analogous to the realities of CPU execution of Javascript.

2.1.13. Abuse of capabilities

Malicious sites could abuse the capabilities exposed by WebGPU to run computations that don’t benefit the user or their experience and instead only benefit the site. Examples would be hidden crypto-mining, password cracking or rainbow tables computations.

It is not possible to guard against these types of uses of the API because the browser is not able to distinguish between valid workloads and abusive workloads. This is a general problem with all general-purpose computation capabilities on the Web: JavaScript, WebAssembly or WebGL. WebGPU only makes some workloads easier to implement, or slightly more efficient to run than using WebGL.

To mitigate this form of abuse, browsers can throttle operations on background tabs, could warn that a tab is using a lot of resource, and restrict which contexts are allowed to use WebGPU.

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

2.2. Privacy Considerations

The privacy considerations for WebGPU are similar to those of WebGL. GPU APIs are complex and must expose various aspects of a device’s capabilities out of necessity in order to enable developers to take advantage of those capabilities effectively. The general mitigation approach involves normalizing or binning potentially identifying information and enforcing uniform behavior where possble.

2.2.1. Machine-specific limits

WebGPU can expose a lot of detail on the underlying GPU architecture and the device geometry. This includes available physical adapters, many limits on the GPU and CPU resources that could be used (such as the maximum texture size), and any optional hardware-specific capabilities that are available.

User agents are not obligated to expose the real hardware limits, they are in full control of how much the machine specifics are exposed. One strategy to reduce fingerprinting is binning all the target platforms into a few number of bins. In general, the privacy impact of exposing the hardware limits matches the one of WebGL.

The default limits are also deliberately high enough to allow most applications to work without requesting higher limits. All the usage of the API is validated according to the requested limits, so the actual hardware capabilities are not exposed to the users by accident.

2.2.2. Machine-specific artifacts

There are some machine-specific rasterization/precision artifacts and performance differences that can be observed roughly in the same way as in WebGL. This applies to rasterization coverage and patterns, interpolation precision of the varyings between shader stages, compute unit scheduling, and more aspects of execution.

Generally, rasterization and precision fingerprints are identical across most or all of the devices of each vendor. Performance differences are relatively intractable, but also relatively low-signal (as with JS execution performance).

Privacy-critical applications and user agents should utilize software implementations to eliminate such artifacts.

2.2.3. Machine-specific performance

Another factor for differentiating users is measuring the performance of specific operations on the GPU. Even with low precision timing, repeated execution of an operation can show if the user’s machine is fast at specific workloads. This is a fairly common vector (present in both WebGL and Javascript), but it’s also low-signal and relatively intractable to truly normalize.

WebGPU compute pipelines expose access to GPU unobstructed by the fixed-function hardware. This poses an additional risk for unique device fingerprinting. User agents can take steps to dissociate logical GPU invocations with actual compute units to reduce this risk.

2.2.4. User Agent State

This specification doesn’t define any additional user-agent state for an origin. However it is expected that user agents will have compilation caches for the result of expensive compilation like GPUShaderModule, GPURenderPipeline and GPUComputePipeline. These caches are important to improve the loading time of WebGPU applications after the first visit.

For the specification, these caches are indifferentiable from incredibly fast compilation, but for applications it would be easy to measure how long createComputePipelineAsync() takes to resolve. This can leak information across origins (like "did the user access a site with this specific shader") so user agents should follow the best practices in storage partitioning.

The system’s GPU driver may also have its own cache of compiled shaders and pipelines. User agents may want to disable these when at all possible, or add per-partition data to shaders in ways that will make the GPU driver consider them different.

2.2.5. Driver bugs

In addition to the concerns outlined in Security Considerations, driver bugs may introduce differences in behavior that can be observed as a method of differentiating users. The mitigations mentioned in Security Considerations apply here as well, including coordinating with GPU vendors and implementing workarounds for known issues in the user agent.

2.2.6. Adapter Identifiers

Describe considerations for exposing adapter info

Note: It is expected that WebGPU will expose some level of information identifying the type of GPU Adapter in use. This is a potential source of fingerprinting information but past experience with WebGL has demonstrated that it is necessary to some degree in order to enable developers to create robust applications and respond effectively to user issues.

3. Fundamentals

3.1. Conventions

3.1.1. Dot Syntax

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

The ?. ("optional chaining") syntax, adopted from JavaScript, is also used. The phrasing "Foo?.Bar" means "if Foo is null or undefined, undefined; otherwise, Foo.Bar".

For example, where buffer is a GPUBuffer, buffer?.[[device]].[[adapter]] means "if buffer is null or undefined, then undefined; otherwise, the [[adapter]] internal slot of the [[device]] internal slot of buffer.

3.1.2. Internal Objects

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

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

3.1.3. WebGPU Interfaces

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

Any interface which includes GPUObjectBase is a WebGPU interface.

interface mixin GPUObjectBase {
    attribute (USVString or undefined) label;
};

GPUObjectBase has the following attributes:

label, of type (USVString or undefined)

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.1.4. Object Descriptors

An object descriptor holds the information needed to create an object, which is typically done via one of the create* methods of GPUDevice.

dictionary GPUObjectDescriptorBase {
    USVString label;
};

GPUObjectDescriptorBase has the following members:

label, of type USVString

The initial value of GPUObjectBase.label.

3.2. Invalid Internal Objects & Contagious Invalidity

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

Objects are invalid from creation if it wasn’t possible to create them. This can happen, for example, if the object descriptor doesn’t describe a valid object, or if there is not enough memory to allocate a resource.

Internal objects of most types cannot become invalid after they are created, but still may become unusable, e.g. if the owning device is lost or destroyed, or the object has a special internal state, like buffer state destroyed.

Internal objects of some types can become invalid after they are created; specifically, devices, adapters, and command/pass/bundle encoders.

3.3. Coordinate Systems

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

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

3.4. Programming Model

3.4.1. Timelines

This section is non-normative.

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

Content timeline

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

Steps executed on the content timeline look like this.

Device timeline

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

Steps executed on the device timeline look like this.

Queue timeline

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

Steps executed on the queue timeline look like this.

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

3.4.2. Memory Model

This section is non-normative.

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

1. User agent implementing the specification.

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

3. Actual CPU and GPU hardware.

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

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

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

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

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

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

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

3.4.3. Multi-Threading

3.4.4. Resource Usages

A physical resource can be used on GPU with an internal usage:

input

Buffer with input data for draw or dispatch calls. Preserves the contents. Allowed by buffer INDEX, buffer VERTEX, or buffer INDIRECT.

constant

Resource bindings that are constant from the shader point of view. Preserves the contents. Allowed by buffer UNIFORM or texture TEXTURE_BINDING.

storage

Writable storage resource binding. Allowed by buffer STORAGE or texture STORAGE_BINDING.

storage-read

Read-only storage resource bindings. Preserves the contents. Allowed by buffer STORAGE.

attachment

Texture used as an output attachment in a render pass. Allowed by texture RENDER_ATTACHMENT.

attachment-read

Texture used as a read-only attachment in a render pass. Preserves the contents. Allowed by texture RENDER_ATTACHMENT.

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

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

Enforcing that the usages are only combined into a compatible usage list allows the API to limit when data races can occur in working with memory. That property makes applications written against WebGPU more likely to run without modification on different platforms.

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

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

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

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

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

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

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

3.4.5. Synchronization

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

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

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

This specification defines the following usage scopes:

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

• In a compute pass, each dispatch command (dispatchWorkgroups() or dispatchWorkgroupsIndirect()) is one usage scope. A subresource is "used" in the usage scope if it is potentially accessible by the command. Within a dispatch, for each bind group slot that is used by the current GPUComputePipeline's [[layout]], every subresource referenced by that bind group is "used" in the usage scope. State-setting compute pass commands, like setBindGroup(index, bindGroup, dynamicOffsets), do not contribute directly to a usage scope; they instead change the state that is checked in dispatch commands.

• One render pass is one usage scope. A subresource is "used" in the usage scope if it’s referenced by any (state-setting or non-state-setting) command. For example, in setBindGroup(index, bindGroup, dynamicOffsets), every subresource in bindGroup is "used" in the render pass’s usage scope.

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

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

3.5. Core Internal Objects

3.5.1. Adapters

An adapter identifies an implementation of WebGPU on the system: both an instance of compute/rendering functionality on the platform underlying a browser, and an instance of a browser’s implementation of WebGPU on top of that functionality.

Adapters do not uniquely represent underlying implementations: calling requestAdapter() multiple times returns a different adapter object each time.

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

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

An adapter may be considered a fallback adapter if it has significant performance caveats in exchange for some combination of wider compatibility, more predictable behavior, or improved privacy. It is not required that a fallback adapter is available on every system.

An adapter has the following internal slots:

[[features]], of type ordered set<GPUFeatureName>, readonly

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

[[limits]], of type supported limits, readonly

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

Each adapter limit must be the same or better than its default value in supported limits.

[[fallback]], of type boolean

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

Adapters are exposed via GPUAdapter.

3.5.2. Devices

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

A device is the exclusive owner of all internal objects created from it: when the device is lost or destroyed, it and all objects created on it (directly, e.g. createTexture(), or indirectly, e.g. createView()) become implicitly unusable.

Define "ownership".

A device has the following internal slots:

[[adapter]], of type adapter, readonly

The adapter from which this device was created.

[[features]], of type ordered set<GPUFeatureName>, readonly

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

[[limits]], of type supported limits, readonly

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

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

Devices are exposed via GPUDevice.

3.6. Optional Capabilities

WebGPU adapters and devices have capabilities, which describe WebGPU functionality that differs between different implementations, typically due to hardware or system software constraints. A capability is either a feature or a limit.

3.6.1. Features

A feature is a set of optional WebGPU functionality that is not supported on all implementations, typically due to hardware or system software constraints.

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

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

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

See the Feature Index for a description of the functionality each feature enables.

3.6.2. Limits

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

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

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

One limit value may be better than another. A better limit value always relaxes validation, enabling strictly more programs to be valid. For each limit class, "better" is defined.

Different limits have different limit classes:

maximum

The limit enforces a maximum on some value passed into the API.

Higher values are better.

May only be set to values ≥ the default. Lower values are clamped to the default.

alignment

The limit enforces a minimum alignment on some value passed into the API; that is, the value must be a multiple of the limit.

Lower values are better.

May only be set to powers of 2 which are ≤ the default. Values which are not powers of 2 are invalid. Higher powers of 2 are clamped to the default.

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

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

3.6.2.1. GPUSupportedLimits

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

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

3.6.2.2. GPUSupportedFeatures

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

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

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

3.7. Origin Restrictions

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

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

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

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

• HTML § 2.5.4 CORS settings attributes

• HTML § 4.8.3 The img element img

• HTML § 4.8.12 Media elements HTMLMediaElement

3.8. Color Spaces and Encoding

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

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

Each color space is defined over an extended range, if defined by the referenced CSS definitions, to represent color values outside of its space (in both chrominance and luminance).

enum GPUPredefinedColorSpace {
    "srgb",
};

Possibly replace this with PredefinedColorSpace, but note that doing so would mean new WebGPU functionality gets added automatically when items are added to that enum in the upstream spec.

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

"srgb"

The CSS predefined color space srgb.

3.8.1. Color Space Conversions

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

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

Colors are not lossily clamped during conversion: converting from one color space to another will result in values outside the range [0, 1] if the source color values were outside the range of the destination color space’s gamut (e.g. if a Display P3 image is converted to sRGB).

4. Initialization

4.1. navigator.gpu

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

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

4.2. GPU

GPU is the entry point to WebGPU.

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

GPU has the following methods:

requestAdapter(options)

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

Called on: GPU this.

Arguments:

Arguments for the GPU.requestAdapter(options) method.

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

Returns: Promise<GPUAdapter?>

1. Let promise be a new promise.

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

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

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

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

      3. Resolve promise with a new GPUAdapter encapsulating adapter.

   2. Otherwise, promise resolves with null.

3. Return promise.

GPU has the following internal slots:

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

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

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

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

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

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

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

4.2.1. Adapter Selection

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

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

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

GPURequestAdapterOptions has the following members:

powerPreference, of type GPUPowerPreference

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

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

Note: The primary utility of this hint is to influence which GPU is used in a multi-GPU system. For instance, some laptops have a low-power integrated GPU and a high-performance discrete GPU.

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

It must be one of the following values:

undefined (or not present)

Provides no hint to the user agent.

"low-power"

Indicates a request to prioritize power savings over performance.

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

"high-performance"

Indicates a request to prioritize performance over power consumption.

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

forceFallbackAdapter, of type boolean, defaulting to false

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

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

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

4.3. GPUAdapter

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

To get a GPUAdapter, use requestAdapter().

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

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

GPUAdapter has the following attributes:

name, of type DOMString, readonly

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

features, of type GPUSupportedFeatures, readonly

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

limits, of type GPUSupportedLimits, readonly

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

isFallbackAdapter, of type boolean, readonly

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

GPUAdapter has the following internal slots:

[[adapter]], of type adapter, readonly

The adapter to which this GPUAdapter refers.

GPUAdapter has the following methods:

requestDevice(descriptor)

Requests a device from the adapter.

Called on: GPUAdapter this.

Arguments:

Arguments for the GPUAdapter.requestDevice(descriptor) method.

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

Returns: Promise<GPUDevice>

1. Let promise be a new promise.

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

3. Issue the following steps to the Device timeline:

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

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

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

   2. If any of the following requirements are unmet, reject promise with an OperationError and stop.

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

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

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

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

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

      1. Let device be a new device.

      2. Lose the device(device, undefined).

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

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

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

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

4. Return promise.

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

4.3.1. GPUDeviceDescriptor

GPUDeviceDescriptor describes a device request.

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

GPUDeviceDescriptor has the following members:

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

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

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

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

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

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

defaultQueue, of type GPUQueueDescriptor, defaulting to {}

The descriptor for the default GPUQueue.

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

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

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

4.3.1.1. GPUFeatureName

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

enum GPUFeatureName {
    "depth-clip-control",
    "depth24unorm-stencil8",
    "depth32float-stencil8",
    "texture-compression-bc",
    "texture-compression-etc2",
    "texture-compression-astc",
    "timestamp-query",
    "indirect-first-instance",
};

4.4. GPUDevice

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

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

To get a GPUDevice, use requestDevice().

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

    [SameObject] readonly attribute GPUQueue queue;

    undefined destroy();

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

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

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

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

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

GPUDevice has the following attributes:

features, of type GPUSupportedFeatures, readonly

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

limits, of type GPUSupportedLimits, readonly

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

queue, of type GPUQueue, readonly

The primary GPUQueue for this device.

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

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

destroy()

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

Called on: GPUDevice this.

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

Note: Since no further operations can occur on this device, implementations can free resource allocations and abort outstanding asynchronous operations immediately.

GPUDevice objects are serializable objects.

Finish defining multithreading API and add [Serializable] back to the interface. [Issue #gpuweb/gpuweb#354]

GPUDevice doesn’t really need the cross-origin policy restriction. It should be usable from multiple agents regardless. Once we describe the serialization of buffers, textures, and queues - the COOP+COEP logic should be moved in there.

4.5. Example

let gpuDevice = null;

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

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

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

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

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

        gpuDevice = null;

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

    onWebGPUInitialized();

    return true;
}

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

initializeWebGPU();

5. Buffers

5.1. GPUBuffer

define buffer (internal object)

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

GPUBuffers are created via GPUDevice.createBuffer(descriptor) that returns a new buffer in the mapped or unmapped state.

[Exposed=(Window, DedicatedWorker), SecureContext]
interface GPUBuffer {
    Promise<undefined> mapAsync(GPUMapModeFlags mode, optional GPUSize64 offset = 0, optional GPUSize64 size);
    ArrayBuffer getMappedRange(optional GPUSize64 offset = 0, optional GPUSize64 size);
    undefined unmap();

    undefined destroy();
};
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? [Issue #gpuweb/gpuweb#605]

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

The range of this GPUBuffer that is mapped.

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

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

[[map_mode]] of type GPUMapModeFlags.

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

[[usage]] is differently named from [[descriptor]].usage. 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 a reference to an internal buffer object.

Finish defining multithreading API and add [Serializable] back to the interface. [Issue #gpuweb/gpuweb#354]

5.2. Buffer Creation

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

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

5.2.2. Buffer Usage

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

createBuffer(descriptor)

Creates a GPUBuffer.

Called on: GPUDevice this.

Arguments:

Arguments for the GPUDevice.createBuffer(descriptor) method.

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

Returns: GPUBuffer

1. If any of the following conditions are unsatisfied, return an error buffer and stop.

   • this is a valid GPUDevice.

   • validating GPUBufferDescriptor(this, descriptor) returns true.

   • descriptor.usage must not be 0.

   • descriptor.usage is a subset of this.[[allowed buffer usages]].

   • If descriptor.usage contains MAP_READ:

     • descriptor.usage contains no other flags except COPY_DST.

   • If descriptor.usage contains MAP_WRITE:

     • descriptor.usage contains no other flags except COPY_SRC.

   • If descriptor.mappedAtCreation is true:

     • descriptor.size is a multiple of 4.

   Explain what are a GPUDevice's [[allowed buffer usages]]. [Issue #gpuweb/gpuweb#605]

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

1. Let b be a new GPUBuffer object.

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

3. Set b.[[usage]] to descriptor.usage.

4. If descriptor.mappedAtCreation is true:

   1. Set b.[[mapping]] to a new ArrayBuffer of size b.[[size]].

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

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

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

   Else:

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

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

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

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

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

6. Return b.

Note: it is valid to set mappedAtCreation to true without MAP_READ or MAP_WRITE in usage. This can be used to set the buffer’s initial data.

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

5.3. Buffer Destruction

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

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

destroy()

Destroys the GPUBuffer.

Called on: GPUBuffer this.

Returns: undefined

1. If the this.[[state]] is not either of unmapped or destroyed

   1. Run the steps to unmap this.

2. Set this.[[state]] to destroyed.

5.4. Buffer Mapping

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

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

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

mapAsync(mode, offset, size)

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

Called on: GPUBuffer this.

Arguments:

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

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

Returns: Promise<undefined>

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

1. If size is missing:

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

   Otherwise, let rangeSize be size.

2. If any of the following conditions are unsatisfied:

   • this is a valid GPUBuffer. TODO: check destroyed state?

   • offset is a multiple of 8.

   • rangeSize is a multiple of 4.

   • offset + rangeSize is less or equal to this.[[size]]

   • this.[[state]] is unmapped

   • mode contains exactly one of READ or WRITE.

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

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

   Do we validate that mode contains only valid flags?

   Then:

   1. Record a validation error on the current scope.

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

3. Let p be a new Promise.

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

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

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

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

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

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

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

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

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

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

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

   2. Resolve p.

8. Return p.

getMappedRange(offset, size)

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

Called on: GPUBuffer this.

Arguments:

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

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

Returns: ArrayBuffer

1. If size is missing:

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

   Otherwise, let rangeSize be size.

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

   • this.[[state]] is mapped or mapped at creation.

   • offset is a multiple of 8.

   • rangeSize is a multiple of 4.

   • offset is greater than or equal to this.[[mapping_range]][0].

   • offset + rangeSize is less than or equal to this.[[mapping_range]][1].

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

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

   Consider aligning mapAsync offset to 8 to match this.

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

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

5. Return m.

unmap()

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

Called on: GPUBuffer this.

Returns: undefined

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

   • this.[[state]] must be mapped at creation, mapping pending, or mapped.

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

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

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

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

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

   1. If one of the two following conditions holds:

      • this.[[state]] is mapped at creation

      • this.[[state]] is mapped and this.[[map_mode]] contains WRITE

      Then:

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

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

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

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

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

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

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

6. Textures and Texture Views

define texture (internal object)

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

6.1. GPUTexture

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

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

    undefined destroy();
};
GPUTexture includes GPUObjectBase;

GPUTexture has the following internal slots:

[[descriptor]], of type GPUTextureDescriptor

The GPUTextureDescriptor describing this texture.

All optional fields of GPUTextureDescriptor are defined.

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

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

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

6.1.1. Texture Creation

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

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

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

Note: Adding formats to this list may have a sizable performance impact, depending on the user’s system. It is best to avoid adding formats unnecessarily.

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

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

• format equals viewFormat, or

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

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

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

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

createTexture(descriptor)

Creates a GPUTexture.

Called on: GPUDevice this.

Arguments:

Arguments for the GPUDevice.createTexture(descriptor) method.

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

Returns: GPUTexture

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

   1. If descriptor.format is a GPUTextureFormat that requires a feature (see § 25.1 Texture Format Capabilities), but this.[[device]].[[features]] does not contain the feature, throw a TypeError.

   2. If any of the following requirements are unmet:

      • this must be a valid GPUDevice.

      • descriptor.usage must not be 0.

      • descriptor.size.width, descriptor.size.height, and descriptor.size.depthOrArrayLayers must be greater than zero.

      • descriptor.mipLevelCount must be greater than zero.

      • descriptor.sampleCount must be either 1 or 4.

      • If descriptor.dimension is:

        "1d"

        • descriptor.size.width must be less than or equal to this.limits.maxTextureDimension1D.

        • descriptor.size.height must be 1.

        • descriptor.size.depthOrArrayLayers must be 1.

        • descriptor.sampleCount must be 1.

        • descriptor.format must not be a compressed format or depth-or-stencil format.

        "2d"

        • descriptor.size.width must be less than or equal to this.limits.maxTextureDimension2D.

        • descriptor.size.height must be less than or equal to this.limits.maxTextureDimension2D.

        • descriptor.size.depthOrArrayLayers must be less than or equal to this.limits.maxTextureArrayLayers.

        "3d"

        • descriptor.size.width must be less than or equal to this.limits.maxTextureDimension3D.

        • descriptor.size.height must be less than or equal to this.limits.maxTextureDimension3D.

        • descriptor.size.depthOrArrayLayers must be less than or equal to this.limits.maxTextureDimension3D.

        • descriptor.sampleCount must be 1.

        • descriptor.format must not be a compressed format or depth-or-stencil format.

      • descriptor.size.width must be multiple of texel block width.

      • descriptor.size.height must be multiple of texel block height.

      • If descriptor.sampleCount > 1:

        • descriptor.mipLevelCount must be 1.

        • descriptor.size.depthOrArrayLayers must be 1.

        • descriptor.usage must not include the STORAGE_BINDING bit.

        • descriptor.format must be a renderable format and support multisampling according to § 25.1 Texture Format Capabilities.

      • descriptor.mipLevelCount must be less than or equal to maximum mipLevel count(descriptor.dimension, descriptor.size).

      • descriptor.usage must be a combination of GPUTextureUsage values.

      • If descriptor.usage includes the RENDER_ATTACHMENT bit:

        • descriptor.format must be a renderable format.

        • descriptor.dimension must be "2d".

      • If descriptor.usage includes the STORAGE_BINDING bit:

        • descriptor.format must be listed in § 25.1.1 Plain color formats table with STORAGE_BINDING capability.

      • For each viewFormat in descriptor.viewFormats, descriptor.format and viewFormat must be texture view format compatible.

      Then:

      1. Generate a validation error.

      2. Return a new invalid GPUTexture.

   3. Let t be a new GPUTexture object.

   4. Set t.[[descriptor]] to descriptor.

   5. Return t.

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

6.1.2. Texture Destruction

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

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

destroy()

Destroys the GPUTexture.

Called on: GPUTexture this.

Returns: undefined

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

6.2. GPUTextureView

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

GPUTextureView has the following internal slots:

[[texture]]

The GPUTexture into which this is a view.

[[descriptor]]

The GPUTextureViewDescriptor describing this texture view.

All optional fields of GPUTextureViewDescriptor are defined.

[[renderExtent]]

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

Note: this extent depends on the baseMipLevel.

6.2.1. Texture View Creation

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

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

"1d"

The texture is viewed as a 1-dimensional image.

Corresponding WGSL types:

• texture_1d

• texture_storage_1d

"2d"

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

Corresponding WGSL types:

• texture_2d

• texture_storage_2d

• texture_multisampled_2d

• texture_depth_2d

• texture_depth_multisampled_2d

"2d-array"

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

Corresponding WGSL types:

• texture_2d_array

• texture_storage_2d_array

• texture_depth_2d_array

"cube"

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

Corresponding WGSL types:

• texture_cube

• texture_depth_cube

"cube-array"

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

Corresponding WGSL types:

• texture_cube_array

• texture_depth_cube_array

"3d"

The texture is viewed as a 3-dimensional image.

Corresponding WGSL types:

• texture_3d

• texture_storage_3d

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

createView(descriptor)

Creates a GPUTextureView.

Called on: GPUTexture this.

Arguments:

Arguments for the GPUTexture.createView(descriptor) method.

Parameter	Type	Nullable	Optional	Description
descriptor	GPUTextureViewDescriptor	✘	✔	Description of the GPUTextureView to create.

Returns: view, of type GPUTextureView.

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

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

   1. If any of the following requirements are unmet:

      • this is valid

      • descriptor.aspect must be present in this.[[descriptor]].format.

      • If the descriptor.aspect is "all":

        • descriptor.format must be equal to either this.[[descriptor]].format or one of the formats in this.[[descriptor]].viewFormats.

        Otherwise:

        • descriptor.format must be equal to the result of resolving GPUTextureAspect( this.[[descriptor]].format, descriptor.aspect).

      • descriptor.mipLevelCount must be > 0.

      • descriptor.baseMipLevel + descriptor.mipLevelCount must be ≤ this.[[descriptor]].mipLevelCount.

      • descriptor.arrayLayerCount must be > 0.

      • descriptor.baseArrayLayer + descriptor.arrayLayerCount must be ≤ the array layer count of this.

      • If this.[[descriptor]].sampleCount is > 1, descriptor.dimension must be "2d".

      • If descriptor.dimension is:

        "1d"

        this.[[descriptor]].dimension must be "1d".

        descriptor.arrayLayerCount must be 1.

        "2d"

        this.[[descriptor]].dimension must be "2d".

        descriptor.arrayLayerCount must be 1.

        "2d-array"

        this.[[descriptor]].dimension must be "2d".

        "cube"

        this.[[descriptor]].dimension must be "2d".

        descriptor.arrayLayerCount must be 6.

        this.[[descriptor]].size.width must be this.[[descriptor]].size.height.

        "cube-array"

        this.[[descriptor]].dimension must be "2d".

        descriptor.arrayLayerCount must be a multiple of 6.

        this.[[descriptor]].size.width must be this.[[descriptor]].size.height.

        "3d"

        this.[[descriptor]].dimension must be "3d".

        descriptor.arrayLayerCount must be 1.

      Then:

      1. Generate a validation error.

      2. Return a new invalid GPUTextureView.

   2. Let view be a new GPUTextureView object.

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

   4. Set view.[[descriptor]] to descriptor.

   5. If this.[[descriptor]].usage contains RENDER_ATTACHMENT:

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

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

   6. Return view.

6.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 features. Their naming should follow the convention here, with the texture name as a prefix. e.g. etc2-rgba8unorm.

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

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

• 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. See § 25.1 Texture Format Capabilities for an exhaustive list of values for every texture format.

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

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

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

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

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

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

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

    // "depth24unorm-stencil8" feature
    "depth24unorm-stencil8",

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

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

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

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

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

add something on GPUAdapter(?) that gives an estimate of the bytes per texel of "stencil8", "depth24plus-stencil8", and "depth32float-stencil8".

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

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

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

6.4. GPUExternalTexture

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

Update this description with canvas.

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

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

GPUExternalTexture has the following internal slots:

[[destroyed]], of type boolean

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

[[descriptor]], of type GPUExternalTextureDescriptor

The descriptor with which the texture was created.

GPUExternalTexture has the following attributes:

expired, of type boolean, readonly

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

The GPUExternalTexture interface object has the following "static" internal slots:

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

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

6.4.1. Importing External Textures

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

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

dictionary GPUExternalTextureDescriptor : GPUObjectDescriptorBase {
    required HTMLVideoElement source;
    GPUPredefinedColorSpace colorSpace = "srgb";
};

importExternalTexture(descriptor)

Creates a GPUExternalTexture wrapping the provided image source.

Called on: GPUDevice this.

Arguments:

Arguments for the GPUDevice.importExternalTexture(descriptor) method.

Parameter	Type	Nullable	Optional	Description
descriptor	GPUExternalTextureDescriptor	✘	✘	Provides the external image source object (and any creation options).

Returns: GPUExternalTexture

1. Let source be descriptor.source.

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

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

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

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

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

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

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

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

8. Return result.

const videoElement = document.createElement('video');
// ... set up videoElement, wait for it to be ready...

let externalTexture;

function frame() {
    requestAnimationFrame(frame);

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

    // ... render using externalTexture...
}
requestAnimationFrame(frame);

const videoElement = document.createElement('video');
// ... set up videoElement...

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

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

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

6.4.2. Sampling External Textures

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

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

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

7. Samplers

7.1. GPUSampler

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

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

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

GPUSampler has the following internal slots:

[[descriptor]], of type GPUSamplerDescriptor, readonly

The GPUSamplerDescriptor with which the GPUSampler was created.

[[isComparison]] of type boolean.

Whether the GPUSampler is used as a comparison sampler.

[[isFiltering]] of type boolean.

Whether the GPUSampler weights multiple samples of a texture.

7.2. Sampler Creation

7.2.1. GPUSamplerDescriptor

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

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

• addressModeU, addressModeV, and addressModeW specify the address modes for the texture width, height, and depth coordinates, respectively.

• magFilter specifies the sampling behavior when the sample footprint is smaller than or equal to one texel.

• minFilter specifies the sampling behavior when the sample footprint is larger than one texel.

• mipmapFilter specifies behavior for sampling between two mipmap levels.

• lodMinClamp and lodMaxClamp specify the minimum and maximum levels of detail, respectively, used internally when sampling a texture.

• If compare is provided, the sampler will be a comparison sampler with the specified GPUCompareFunction.

• maxAnisotropy specifies the maximum anisotropy value clamp used by the sampler.

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

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

explain what anisotropic sampling is

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

Describe a "sample footprint" in greater detail.

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

"clamp-to-edge"

Texture coordinates are clamped between 0.0 and 1.0, inclusive.

"repeat"

Texture coordinates wrap to the other side of the texture.

"mirror-repeat"

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

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

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

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

"nearest"

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

"linear"

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

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

describe how filtering interacts with comparison sampling.

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

"never"

Comparison tests never pass.

"less"

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

"equal"

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

"less-equal"

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

"greater"

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

"not-equal"

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

"greater-equal"

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

"always"

Comparison tests always pass.

createSampler(descriptor)

Creates a GPUSampler.

Called on: GPUDevice this.

Arguments:

Arguments for the GPUDevice.createSampler(descriptor) method.

Parameter	Type	Nullable	Optional	Description
descriptor	GPUSamplerDescriptor	✘	✔	Description of the GPUSampler to create.

Returns: GPUSampler

1. Let s be a new GPUSampler object.

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

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

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

5. Return s.

Valid Usage

• If descriptor is not null or undefined:

  • If validating GPUSamplerDescriptor(this, descriptor) returns false:

    1. Generate a validation error.

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

const sampler = gpuDevice.createSampler({
    addressModeU: 'repeat',
    addressModeV: 'repeat',
    magFilter: 'linear',
    minFilter: 'linear',
    mipmapFilter: 'linear',
});

8. Resource Binding

8.1. GPUBindGroupLayout

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

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

GPUBindGroupLayout has the following internal slots:

[[descriptor]]

8.1.1. Creation

A GPUBindGroupLayout is created via GPUDevice.createBindGroupLayout().

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

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

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

dictionary GPUBindGroupLayoutEntry {
    required GPUIndex32 binding;
    required GPUShaderStageFlags visibility;

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

GPUBindGroupLayoutEntry dictionaries have the following members:

binding, of type GPUIndex32

A unique identifier for a resource binding within a GPUBindGroupLayoutEntry, a corresponding GPUBindGroupEntry, and the GPUShaderModules.

visibility, of type GPUShaderStageFlags

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

buffer, of type GPUBufferBindingLayout

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

sampler, of type GPUSamplerBindingLayout

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

texture, of type GPUTextureBindingLayout

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

storageTexture, of type GPUStorageTextureBindingLayout

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

externalTexture, of type GPUExternalTextureBindingLayout

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

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