Home - News ( United States | United Kingdom | Italy | Germany ) - Football scores

Showing content from https://gpuweb.github.io/gpuweb/ below:

WebGPU

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

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

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.

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

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

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

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.

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.

NOTE:

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

to

).

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

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

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

Alternatively, an implementation may transform the shader code by inserting manual bounds checks. 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

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.

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.

WebGPU does not expose new states to JavaScript (the content timeline) which are shared between agents in an agent cluster. Content timeline states such as [[mapping]] only change during explicit content timeline tasks, like in plain JavaScript.

Writable storage buffers and other cross-invocation communication may be usable to construct high-precision timers on the queue timeline.

The optional "timestamp-query" feature also provides high precision timing of GPU operations. To mitigate security and privacy concerns, the timing query values are aligned to a lower precision: see current queue timestamp. Note in particular:

• The device timeline typically runs in a process that is shared by multiple origins, so cross-origin isolation (provided by COOP/COEP) does not provide isolation of device/queue-timeline timers.

• Queue timeline work is issued from the device timeline, and may execute on GPU hardware that does not provide the isolation expected of CPU processes (such as Meltdown mitigations).

• GPU hardware is not typically susceptible to Spectre-style attacks, but WebGPU may be implemented in software, and software implementations may run in a shared process, preventing isolation-based mitigations.

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.

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.

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.

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.

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.

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

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

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

User agents can heuristically issue warnings to users about high power use, especially due to potentially malicious usage. If a user agent implements such a warning, it should include WebGPU usage in its heuristics, in addition to JavaScript, WebAssembly, WebGL, and so on.

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

A user agent must not reveal more than 32 distinguishable configurations or buckets.

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.

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.

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.

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.

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.

Past experience with WebGL has demonstrated that developers have a legitimate need to be able to identify the GPU their code is running on in order to create and maintain robust GPU-based content. For example, to identify adapters with known driver bugs in order to work around them or to avoid features that perform more poorly than expected on a given class of hardware.

But exposing adapter identifiers also naturally expands the amount of fingerprinting information available, so there’s a desire to limit the precision with which we identify the adapter.

There are several mitigations that can be applied to strike a balance between enabling robust content and preserving privacy. First is that user agents can reduce the burden on developers by identifying and working around known driver issues, as they have since browsers began making use of GPUs.

When adapter identifiers are exposed by default they should be as broad as possible while still being useful. Possibly identifying, for example, the adapter’s vendor and general architecture without identifying the specific adapter in use. Similarly, in some cases identifiers for an adapter that is considered a reasonable proxy for the actual adapter may be reported.

In cases where full and detailed information about the adapter is useful (for example: when filing bug reports) the user can be asked for consent to reveal additional information about their hardware to the page.

Finally, the user agent will always have the discretion to not report adapter identifiers at all if it considers it appropriate, such as in enhanced privacy modes.

In this specification, the following syntactic shorthands are used:

The . ("dot") syntax, common in programming languages.

The phrasing "Foo.Bar" means "the Bar member of the value (or interface) Foo." If Foo is an ordered map and Bar does not exist in Foo, returns undefined.

The phrasing "Foo.Bar is provided" means "the Bar member exists in the map value Foo"

The ?. ("optional chaining") syntax, adopted from JavaScript.

The phrasing "Foo?.Bar" means "if Foo is null or undefined or Bar does not exist in Foo, 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.

The ?? ("nullish coalescing") syntax, adopted from JavaScript.

The phrasing "x ?? y" means "x, if x is not null or undefined, and y otherwise".

slot-backed attribute

A WebIDL attribute which is backed by an internal slot of the same name. It may or may not be mutable.

A WebGPU object consists of a WebGPU Interface and an internal object.

The WebGPU interface defines the public interface and state of the WebGPU object. It can be used on the content timeline where it was created, where it is a JavaScript-exposed WebIDL interface.

Any interface which includes GPUObjectBase is a WebGPU interface.

The internal object tracks the state of the WebGPU object on the device timeline. All reads/writes to the mutable state of an internal object occur from steps executing on a single well-ordered device timeline.

The following special property types can be defined on WebGPU objects:

immutable property

A read-only slot set during initialization of the object. It can be accessed from any timeline.

Note: Since the slot is immutable, implementations may have a copy on multiple timelines, as needed. Immutable properties are defined in this way to avoid describing multiple copies in this spec.

If named [[with brackets]], it is an internal slot.
If named withoutBrackets, it is a readonly slot-backed attribute of the WebGPU interface.

content timeline property

A property which is only accessible from the content timeline where the object was created.

If named [[with brackets]], it is an internal slot.
If named withoutBrackets, it is a slot-backed attribute of the WebGPU interface.

device timeline property

A property which tracks state of the internal object and is only accessible from the device timeline where the object was created. device timeline properties may be mutable.

Device timeline properties are named [[with brackets]], and are internal slots.

queue timeline property

A property which tracks state of the internal object and is only accessible from the queue timeline where the object was created. queue timeline properties may be mutable.

Queue timeline properties are named [[with brackets]], and are internal slots.

interface mixin GPUObjectBase {
    attribute USVString label;
};

GPUObjectBase has the following immutable properties:

[[device]], of type device, readonly

The device that owns the internal object.

Operations on the contents of this object assert they are running on the device timeline, and that the device is valid.

GPUObjectBase has the following content timeline properties:

label, of type USVString

A developer-provided label which is used in an implementation-defined way. It can be used by the browser, OS, or other tools to help identify the underlying internal object to the developer. Examples include displaying the label in GPUError messages, console warnings, browser developer tools, and platform debugging utilities.

NOTE:

The

label

is a property of the

GPUObjectBase

. Two

GPUObjectBase

"wrapper" objects have completely separate label states, even if they refer to the same underlying object (for example returned by

getBindGroupLayout()

). The

label

property will not change except by being set from JavaScript.

This means one underlying object could be associated with multiple labels. This specification does not define how the label is propagated to the device timeline. How labels are used is completely implementation-defined: error messages could show the most recently set label, all known labels, or no labels at all.

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

GPUObjectBase has the following device timeline properties:

[[valid]], of type boolean, initially true.

If true, indicates that the internal object is valid to use.

NOTE:

Ideally

should not prevent their parent objects, such as the

that owns them, from being garbage collected. This cannot be guaranteed, however, as holding a strong reference to a parent object may be required in some implementations.

As a result, developers should assume that a WebGPU interface may not be garbage collected until all child objects of that interface have also been garbage collected. This may cause some resources to remain allocated longer than anticipated.

Calling the destroy method on a WebGPU interface (such as GPUDevice.destroy() or GPUBuffer.destroy()) should be favored over relying on garbage collection if predictable release of allocated resources is needed.

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, defaulting to ""

The initial value of GPUObjectBase.label.

Object creation operations in WebGPU don’t return promises, but nonetheless are internally asynchronous. Returned objects refer to internal objects which are manipulated on a device timeline. Rather than fail with exceptions or rejections, most errors that occur on a device timeline are communicated through GPUErrors generated on the associated device.

Internal objects are either valid or invalid. An invalid object will never become valid at a later time, but some valid objects may be invalidated.

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. It can also happen if an object is created with or from another invalid object (for example calling createView() on an invalid GPUTexture) (for example the GPUTexture of a createView() call): this case is referred to as contagious invalidity.

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

A given

is

a

if the all of the requirements in the following

steps are met:

Several operations in WebGPU return promises.

• GPU.requestAdapter()

• GPUAdapter.requestDevice()

• GPUDevice.createComputePipelineAsync()

• GPUDevice.createRenderPipelineAsync()

• GPUShaderModule.getCompilationInfo()

• GPUQueue.onSubmittedWorkDone()

• GPUBuffer.mapAsync()

• GPUDevice.lost

• GPUDevice.popErrorScope()

WebGPU does not make any guarantees about the order in which these promises settle (resolve or reject), except for the following:

Applications must not rely on any other promise settlement ordering.

Rendering operations use the following coordinate systems:

• Normalized device coordinates (or NDC) have three dimensions, where:

  • -1.0 ≤ x ≤ 1.0

  • -1.0 ≤ y ≤ 1.0

  • 0.0 ≤ z ≤ 1.0

  • The bottom-left corner is at (-1.0, -1.0, z).

  Normalized device coordinates.

  Note: Whether z = 0 or z = 1 is treated as the near plane is application specific. The above diagram presents z = 0 as the near plane but the observed behavior is determined by a combination of the projection matrices used by shaders, the depthClearValue, and the depthCompare function.

• Clip space coordinates have four dimensions: (x, y, z, w)

  • Clip space coordinates are used for the the clip position of a vertex (i.e. the position output of a vertex shader), and for the clip volume.

  • Normalized device coordinates and clip space coordinates are related as follows: If point p = (p.x, p.y, p.z, p.w) is in the clip volume, then its normalized device coordinates are (p.x ÷ p.w, p.y ÷ p.w, p.z ÷ p.w).

• Framebuffer coordinates address the pixels in the framebuffer

  • They have two dimensions.

  • Each pixel extends 1 unit in x and y dimensions.

  • The top-left corner is at (0.0, 0.0).

  • x increases to the right.

  • y increases down.

  • See § 17 Render Passes and § 23.2.5 Rasterization.

  Framebuffer coordinates.

• Viewport coordinates combine framebuffer coordinates in x and y dimensions, with depth in z.

  • Normally 0.0 ≤ z ≤ 1.0, but this can be modified by setting [[viewport]].minDepth and maxDepth via setViewport()

• Fragment coordinates match viewport coordinates.

• Texture coordinates, sometimes called "UV coordinates" in 2D, are used to sample textures and have a number of components matching the texture dimension.

  • 0 ≤ u ≤ 1.0

  • 0 ≤ v ≤ 1.0

  • 0 ≤ w ≤ 1.0

  • (0.0, 0.0, 0.0) is in the first texel in texture memory address order.

  • (1.0, 1.0, 1.0) is in the last texel texture memory address order.

  2D Texture coordinates.

• Window coordinates, or present coordinates, match framebuffer coordinates, and are used when interacting with an external display or conceptually similar interface.

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

WebGPU’s behavior is described in terms of "timelines". Each operation (defined as algorithms) occurs on a timeline. Timelines clearly define both the order of operations, and which state is available to which operations.

Note: This "timeline" model describes the constraints of the multi-process models of browser engines (typically with a "content process" and "GPU process"), as well as the GPU itself as a separate execution unit in many implementations. Implementing WebGPU does not require timelines to execute in parallel, so does not require multiple processes, or even multiple threads. (It does require concurrency for cases like get a copy of the image contents of a context which synchronously blocks on another timeline to complete.)

Content timeline

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

To issue steps to the content timeline from an operation on GPUDevice device, queue a global task for GPUDevice device with those steps.

Device timeline

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

Queue timeline

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

Timeline-agnostic

Associated with any of the above timelines

Steps may be issued to any timeline if they only operate on immutable properties or arguments passed from the calling steps.

The following show the styling of steps and values associated with each timeline. This styling is non-normative; the specification text always describes the association.

Immutable value example term definition

Can be used on any timeline.

Content-timeline example term definition

Can only be used on the content timeline.

Device-timeline example term definition

Can only be used on the device timeline.

Queue-timeline example term definition

Can only be used on the queue timeline.

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

:

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

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

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

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.

A physical resource can be used with an internal usage by a GPU command:

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

Read/write 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 or texture STORAGE_BINDING.

attachment

Texture used as a read/write output attachment or write-only resolve target 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.

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.

EXAMPLE:

These rules allow for

: a single depth/stencil texture can be used as two different read-only usages in a render pass simultaneously:

• attachment-read

  As a depth/stencil attachment with all aspects marked read-only (using depthReadOnly and/or stencilReadOnly as necessary).

• constant

  As a texture binding to a draw call.

EXAMPLE:

The

allows two cases that would not be allowed otherwise:

• A buffer or texture may be bound as storage to two different draw calls in a render pass.

• Disjoint ranges of a single buffer may be bound to two different binding points as storage.

  Overlapping ranges may not be bound to a single dispatch/draw call; this is checked by "Encoder bind groups alias a writable resource".

EXAMPLE:

The

allows a texture subresource to be used as

more than once. This is necessary to allow disjoint slices of 3D textures to be bound as different attachments to a single render pass.

One slice may not be bound twice for two different attachments; this is checked by beginRenderPass().

A usage scope is a map from subresource to list<internal usage>>. Each usage scope covers a range of operations which may execute in a concurrent fashion with each other, and therefore may only use subresources in consistent compatible usage lists within the scope.

Usage scopes are constructed and validated during encoding:

• in dispatchWorkgroups()

• in dispatchWorkgroupsIndirect()

• at GPURenderPassEncoder.end()

• at GPURenderBundleEncoder.finish()

The usage scopes are as follows:

• 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 dispatched invocations, including:

  • All subresources referenced by bind groups in slots used by the current GPUComputePipeline’s [[layout]]

  • Buffers used directly by dispatch calls (such as indirect buffers)

  Note: State-setting compute pass commands, like setBindGroup(), do not contribute their bound resources directly to a usage scope: they only 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 command, including state-setting commands (unlike in compute passes), including:

  • Buffers set by setVertexBuffer()

  • Buffers set by setIndexBuffer()

  • All subresources referenced by bind groups set by setBindGroup()

  • Buffers used directly by draw calls (such as indirect buffers)

Note: Copy commands are standalone operations and don’t use usage scopes for validation. They implement their own validation to prevent self-races.

EXAMPLE:

The following example resource usages

included in

:

• In a render pass, subresources used in any setBindGroup() call, regardless of whether the currently bound pipeline’s shader or layout actually depends on these bindings, or the bind group is shadowed by another 'set' call.

• A buffer used in any setVertexBuffer() call, regardless of whether any draw call depends on this buffer, or whether this buffer is shadowed by another 'set' call.

• A buffer used in any setIndexBuffer() call, regardless of whether any draw call depends on this buffer, or whether this buffer is shadowed by another 'set' call.

• A texture subresource used as a color attachment, resolve attachment, or depth/stencil attachment in GPURenderPassDescriptor by beginRenderPass(), regardless of whether the shader actually depends on these attachments.

• Resources used in bind group entries with visibility 0, or visible only to the compute stage but used in a render pass (or vice versa).

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 are exposed via GPUAdapter.

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

Each adapter object can only be used to create one device: upon a successful requestDevice() call, the adapter’s [[state]] changes to "consumed". Additionally, adapter objects may expire at any time.

Note: This ensures applications use the latest system state for adapter selection when creating a device. It also encourages robustness to more scenarios by making them look similar: first initialization, reinitialization due to an unplugged adapter, reinitialization due to a test GPUDevice.destroy() call, etc.

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.

adapter has the following immutable properties:

[[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, readonly

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

[[xrCompatible]], of type boolean

If set to true indicates that the adapter was requested with compatibility with WebXR sessions.

adapter has the following device timeline properties:

[[state]], initially "valid"

"valid"

The adapter can be used to create a device.

"consumed"

The adapter has already been used to create a device, and cannot be used again.

"expired"

The adapter has expired for some other reason.

A device is the logical instantiation of an adapter, through which internal objects are created.

Devices are exposed via GPUDevice.

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

device has the following immutable properties:

[[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, as computed at creation. 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, as computed at creation. No better limits can be used, even if the underlying adapter can support them.

device has the following content timeline properties:

[[content device]], of type GPUDevice, readonly

The Content timeline GPUDevice interface which this device is associated with.

Any time the user agent needs to revoke access to a device, it calls lose the device(device, "unknown") on the device’s device timeline, potentially ahead of other operations currently queued on that timeline.

If an operation fails with side effects that would observably change the state of objects on the device or potentially corrupt internal implementation/driver state, the device should be lost to prevent these changes from being observable.

Note: For all device losses not initiated by the application (via destroy()), user agents should consider issuing developer-visible warnings unconditionally, even if the lost promise is handled. These scenarios should be rare, and the signal is vital to developers because most of the WebGPU API tries to behave like nothing is wrong to avoid interrupting the runtime flow of the application: no validation errors are raised, most promises resolve normally, etc.

To

on

, handled by

on timeline

:

• If or when the device timeline has been informed of the completion of event, or

• If device is lost already, or when it becomes lost:

Then issue steps on timeline.

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.

A user agent must not reveal more than 32 distinguishable configurations or buckets.

The capabilities of an adapter must conform to § 4.2.1 Adapter Capability Guarantees.

Only supported capabilities may be requested in requestDevice(); requesting unsupported capabilities results in failure.

The capabilities of a device are determined in "a new device" by starting with the adapter’s defaults (no features and the default supported limits) and adding capabilities as requested in requestDevice(). These capabilities are enforced regardless of the capabilities of the adapter.

There is a tracking vector here. For privacy considerations, see § 2.2.1 Machine-specific features and limits.

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

All features are optional, but adapters make some guarantees about their availability (see § 4.2.1 Adapter Capability Guarantees).

A device supports the exact set of features determined at creation (see § 3.6 Optional Capabilities). API calls perform validation according to these features (not the adapter’s features):

• Using existing API surfaces in a new way typically results in a validation error.

• There are several types of optional API surface:

  • Using a new method or enum value always throws a TypeError.

  • Using a new dictionary member with a (correctly-typed) non-default value typically results in a validation error.

  • Using a new WGSL enable directive always results in a createShaderModule() validation error.

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

Note: Enabling features may not necessarily be desirable, as doing so may have a performance impact. Because of this, and to improve portability across devices and implementations, applications should generally only request features that they may actually require.

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

Note: Setting "better" limits may not necessarily be desirable, as doing so may have a performance impact. Because of this, and to improve portability across devices and implementations, applications should generally only request better limits if they may actually require them.

Each limit has a default value.

Adapters are always guaranteed to support the defaults or better (see § 4.2.1 Adapter Capability Guarantees).

A device supports the exact set of limits determined at creation (see § 3.6 Optional Capabilities). API calls perform validation according to these limits (not the adapter’s limits), no better or worse.

For any given limit, some values are better than others. 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).

A supported limits object has a value for every limit defined by WebGPU:

Note: This limit is normative, but arbitrary. With the default binding slot limits, it is impossible to use 1000 bindings in one bind group, but this allows GPUBindGroupLayoutEntry.binding values up to 999. This limit allows implementations to treat binding space as an array, within reasonable memory space, rather than a sparse map structure.

GPUSupportedLimits exposes an adapter or device’s supported limits. See GPUAdapter.limits and GPUDevice.limits.

[Exposed=(Window, Worker), 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 maxBindGroupsPlusVertexBuffers;
    readonly attribute unsigned long maxBindingsPerBindGroup;
    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 long maxBufferSize;
    readonly attribute unsigned long maxVertexAttributes;
    readonly attribute unsigned long maxVertexBufferArrayStride;
    readonly attribute unsigned long maxInterStageShaderVariables;
    readonly attribute unsigned long maxColorAttachments;
    readonly attribute unsigned long maxColorAttachmentBytesPerSample;
    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;
};

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, Worker), SecureContext]
interface GPUSupportedFeatures {
    readonly setlike<DOMString>;
};

NOTE:

The type of the

is

to allow user agents to gracefully handle valid

s which are added in later revisions of the spec but which the user agent has not been updated to recognize yet. If the

type was

the following code would throw an

rather than reporting

:

Check for support of an unrecognized feature:

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

WGSLLanguageFeatures is the setlike interface of navigator.gpu.wgslLanguageFeatures. Its set entries are the string names of the WGSL language extensions supported by the implementation (regardless of the adapter or device).

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

GPUAdapterInfo exposes various identifying information about an adapter.

None of the members in GPUAdapterInfo are guaranteed to be populated with any particular value; if no value is provided, the attribute will return the empty string "". It is at the user agent’s discretion which values to reveal, and it is likely that on some devices none of the values will be populated. As such, applications must be able to handle any possible GPUAdapterInfo values, including the absence of those values.

The GPUAdapterInfo for an adapter is exposed via GPUAdapter.info and GPUDevice.adapterInfo). This info is immutable: for a given adapter, each GPUAdapterInfo attribute will return the same value every time it’s accessed.

Note: Though the GPUAdapterInfo attributes are immutable once accessed, an implementation may delay the decision on what to expose for each attribute until the first time it is accessed.

Note: Other GPUAdapter instances, even if they represent the same physical adapter, may expose different values in GPUAdapterInfo. However, they should expose the same values unless a specific event has increased the amount of identifying information the page is allowed to access. (No such events are defined by this specification.)

There is a tracking vector here. For privacy considerations, see § 2.2.6 Adapter Identifiers.

[Exposed=(Window, Worker), SecureContext]
interface GPUAdapterInfo {
    readonly attribute DOMString vendor;
    readonly attribute DOMString architecture;
    readonly attribute DOMString device;
    readonly attribute DOMString description;
    readonly attribute unsigned long subgroupMinSize;
    readonly attribute unsigned long subgroupMaxSize;
    readonly attribute boolean isFallbackAdapter;
};

GPUAdapterInfo has the following attributes:

vendor, of type DOMString, readonly

The name of the vendor of the adapter, if available. Empty string otherwise.

architecture, of type DOMString, readonly

The name of the family or class of GPUs the adapter belongs to, if available. Empty string otherwise.

device, of type DOMString, readonly

A vendor-specific identifier for the adapter, if available. Empty string otherwise.

Note: This is a value that represents the type of adapter. For example, it may be a PCI device ID. It does not uniquely identify a given piece of hardware like a serial number.

description, of type DOMString, readonly

A human readable string describing the adapter as reported by the driver, if available. Empty string otherwise.

Note: Because no formatting is applied to description attempting to parse this value is not recommended. Applications which change their behavior based on the GPUAdapterInfo, such as applying workarounds for known driver issues, should rely on the other fields when possible.

subgroupMinSize, of type unsigned long, readonly

If the "subgroups" feature is supported, the minimum supported subgroup size for the adapter.

subgroupMaxSize, of type unsigned long, readonly

If the "subgroups" feature is supported, the maximum supported subgroup size for the adapter.

isFallbackAdapter, of type boolean, readonly

Whether the adapter is a fallback adapter.

To create a

for a given

, run the following

steps:

1. Let adapterInfo be a new GPUAdapterInfo.

2. If the vendor is known, set adapterInfo.vendor to the name of adapter’s vendor as a normalized identifier string. To preserve privacy, the user agent may instead set adapterInfo.vendor to the empty string or a reasonable approximation of the vendor as a normalized identifier string.

3. If |the architecture is known, set adapterInfo.architecture to a normalized identifier string representing the family or class of adapters to which adapter belongs. To preserve privacy, the user agent may instead set adapterInfo.architecture to the empty string or a reasonable approximation of the architecture as a normalized identifier string.

4. If the device is known, set adapterInfo.device to a normalized identifier string representing a vendor-specific identifier for adapter. To preserve privacy, the user agent may instead set adapterInfo.device to to the empty string or a reasonable approximation of a vendor-specific identifier as a normalized identifier string.

5. If a description is known, set adapterInfo.description to a description of the adapter as reported by the driver. To preserve privacy, the user agent may instead set adapterInfo.description to the empty string or a reasonable approximation of a description.

6. If "subgroups" is supported, set subgroupMinSize to the smallest supported subgroup size. Otherwise, set this value to 4.

   Note: To preserve privacy, the user agent may choose to not support some features or provide values for the property which do not distinguish different devices, but are still usable (e.g. use the default value of 4 for all devices).

7. If "subgroups" is supported, set subgroupMaxSize to the largest supported subgroup size. Otherwise, set this value to 128.

   Note: To preserve privacy, the user agent may choose to not support some features or provide values for the property which do not distinguish different devices, but are still usable (e.g. use the default value of 128 for all devices).

8. Set adapterInfo.isFallbackAdapter to adapter.[[fallback]].

9. Return adapterInfo.

A

is one that follows the following pattern:

[a-z0-9]+(-[a-z0-9]+)*

a-z 0-9 -

Examples of valid normalized identifier strings include:

• gpu

• 3d

• 0x3b2f

• next-gen

• series-x20-ultra

"Extension Documents" are additional documents which describe new functionality which is non-normative and not part of the WebGPU/WGSL specifications. They describe functionality that builds upon these specifications, often including one or more new API feature flags and/or WGSL enable directives, or interactions with other draft web specifications.

WebGPU implementations must not expose extension functionality; doing so is a spec violation. New functionality does not become part of the WebGPU standard until it is integrated into the WebGPU specification (this document) and/or WGSL specification.

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.11 Media elements HTMLMediaElement

WebGPU defines a new task source called the WebGPU task source. It is used for the uncapturederror event and GPUDevice.lost.

WebGPU defines a new task source called the automatic expiry task source. It is used for the automatic, timed expiry (destruction) of certain objects:

• GPUTextures returned by getCurrentTexture()

• GPUExternalTextures created from HTMLVideoElements

Tasks from the automatic expiry task source should be processed with high priority; in particular, once queued, they should run before user-defined (JavaScript) tasks.

NOTE:

This behavior is more predictable, and the strictness helps developers write more portable applications by eagerly detecting incorrect assumptions about implicit lifetimes that may be hard to detect. Developers are still strongly encouraged to test in multiple implementations.

Implementation note: It is valid to implement a high-priority expiry "task" by instead inserting additional steps at a fixed point inside the event loop processing model rather than running an actual task.

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

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

WebGPU allows all of the color spaces in the PredefinedColorSpace enum. Note, each color space is defined over an extended range, as defined by the referenced CSS definitions, to represent color values outside of its space (in both chrominance and luminance).

An out-of-gamut premultiplied RGBA value is one where any of the R/G/B channel values exceeds the alpha channel value. For example, the premultiplied sRGB RGBA value [1.0, 0, 0, 0.5] represents the (unpremultiplied) color [2, 0, 0] with 50% alpha, written rgb(srgb 2 0 0 / 50%) in CSS. Just like any color value outside the sRGB color gamut, this is a well defined point in the extended color space (except when alpha is 0, in which case there is no color). However, when such values are output to a visible canvas, the result is undefined (see GPUCanvasAlphaMode "premultiplied").

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

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

Note: Grayscale images generally represent RGB values (V, V, V), or RGBA values (V, V, V, A) in their color space.

Colors are not lossily clamped during conversion: converting from one color space to another will result in values outside the range [0, 1] if the source color values were outside the range of the destination color space’s gamut. For an sRGB destination, for example, this can occur if the source is rgba16float, in a wider color space like Display-P3, or is premultiplied and contains out-of-gamut values.

Similarly, if the source value has a high bit depth (e.g. PNG with 16 bits per component) or extended range (e.g. canvas with float16 storage), these colors are preserved through color space conversion, with intermediate computations having at least the precision of the source.

If the source and destination of a color space/encoding conversion are the same, then conversion is not necessary. In general, if any given step of the conversion is an identity function (no-op), implementations should elide it, for performance.

For optimal performance, applications should set their color space and encoding options so that the number of necessary conversions is minimized throughout the process. For various image sources of GPUCopyExternalImageSourceInfo:

• ImageBitmap:

  • Premultiplication is controlled via premultiplyAlpha.

  • Color space is controlled via colorSpaceConversion.

• 2d canvas:

  • Always premultiplied.

  • Color space is controlled via the colorSpace context creation attribute.

• WebGL canvas:

  • Premultiplication is controlled via the premultipliedAlpha option in WebGLContextAttributes.

  • Color space is controlled via the WebGLRenderingContextBase’s drawingBufferColorSpace state.

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

Several parts of the WebGPU API (pipeline-overridable constants and render pass clear values) take numeric values from WebIDL (double or float) and convert them to WGSL values (bool, i32, u32, f32, f16).

To convert an IDL value

of type

or

, possibly throwing a

, run the following

steps:

Note: This TypeError is generated in the device timeline and never surfaced to JavaScript.

1. Assert idlValue is a finite value, since it is not unrestricted double or unrestricted float.

2. Let v be the ECMAScript Number resulting from ! converting idlValue to an ECMAScript value.

3. If T is bool

   Return the WGSL bool value corresponding to the result of ! converting v to an IDL value of type boolean.

   Note: This algorithm is called after the conversion from an ECMAScript value to an IDL double or float value. If the original ECMAScript value was a non-numeric, non-boolean value like [] or {}, then the WGSL bool result may be different than if the ECMAScript value had been converted to IDL boolean directly.

   If T is i32

   Return the WGSL i32 value corresponding to the result of ? converting v to an IDL value of type [EnforceRange] long.

   If T is u32

   Return the WGSL u32 value corresponding to the result of ? converting v to an IDL value of type [EnforceRange] unsigned long.

   If T is f32

   Return the WGSL f32 value corresponding to the result of ? converting v to an IDL value of type float.

   If T is f16

   1. Let wgslF32 be the WGSL f32 value corresponding to the result of ? converting v to an IDL value of type float.

   2. Return f16(wgslF32), the result of ! converting the WGSL f32 value to f16 as defined in WGSL floating point conversion.

   Note: As long as the value is in-range of f32, no error is thrown, even if the value is out-of-range of f16.

To convert a

, possibly throwing a

, run the following

steps:

Note: This TypeError is generated in the device timeline and never surfaced to JavaScript.

1. If the components of format (assert they all have the same type) are:

   floating-point types or normalized types

   Let T be f32.

   signed integer types

   Let T be i32.

   unsigned integer types

   Let T be u32.

2. Let wgslColor be a WGSL value of type vec4<T>, where the 4 components are the RGBA channels of color, each ? converted to WGSL type T.

3. Convert wgslColor to format using the same conversion rules as the § 23.2.7 Output Merging step, and return the result.

   Note: For non-integer types, the exact choice of value is implementation-defined. For normalized types, the value is clamped to the range of the type.

Note: In other words, the value written will be as if it was written by a WGSL shader that outputs the value represented as a vec4 of f32, i32, or u32.

A GPU object is available in the Window and WorkerGlobalScope 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;

NavigatorGPU has the following attributes:

gpu, of type GPU, readonly

A global singleton providing top-level entry points like requestAdapter().

GPU is the entry point to WebGPU.

[Exposed=(Window, Worker), SecureContext]
interface GPU {
    Promise<GPUAdapter?> requestAdapter(optional GPURequestAdapterOptions options = {});
    GPUTextureFormat getPreferredCanvasFormat();
    [SameObject] readonly attribute WGSLLanguageFeatures wgslLanguageFeatures;
};

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.

getPreferredCanvasFormat()

Returns an optimal GPUTextureFormat for displaying 8-bit depth, standard dynamic range content on this system. Must only return "rgba8unorm" or "bgra8unorm".

The returned value can be passed as the format to configure() calls on a GPUCanvasContext to ensure the associated canvas is able to display its contents efficiently.

Note: Canvases which are not displayed to the screen may or may not benefit from using this format.

GPU has the following attributes:

wgslLanguageFeatures, of type WGSLLanguageFeatures, readonly

The names of supported WGSL language extensions. Supported language extensions are automatically enabled.

Adapters may expire at any time. Upon any change in the system’s state that could affect the result of any requestAdapter() call, the user agent should expire all previously-returned adapters. For example:

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

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

Note: User agents may choose to expire adapters often, even when there has been no system state change (e.g. seconds or minutes after the adapter was created). This can help obfuscate real system state changes, and make developers more aware that calling requestAdapter() again is always necessary before calling requestDevice(). If an application does encounter this situation, standard device-loss recovery handling should allow it to recover.

Requesting a

with no hints:

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

Any GPUAdapter returned by requestAdapter() must provide the following guarantees:

• At least one of the following must be true:

  • "texture-compression-bc" is supported.

  • Both "texture-compression-etc2" and "texture-compression-astc" are supported.

• If "texture-compression-bc-sliced-3d" is supported, then "texture-compression-bc" must be supported.

• If "texture-compression-astc-sliced-3d" is supported, then "texture-compression-astc" must be supported.

• All supported limits must be either the default value or better.

• All alignment-class limits must be powers of 2.

• maxBindingsPerBindGroup must be must be ≥ (max bindings per shader stage × max shader stages per pipeline), where:

  • max bindings per shader stage is (maxSampledTexturesPerShaderStage + maxSamplersPerShaderStage + maxStorageBuffersPerShaderStage + maxStorageTexturesPerShaderStage + maxUniformBuffersPerShaderStage).

  • max shader stages per pipeline is 2, because a GPURenderPipeline supports both a vertex and fragment shader.

  Note: maxBindingsPerBindGroup does not reflect a fundamental limit; implementations should raise it to conform to this requirement, rather than lowering the other limits.

• maxBindGroups must be ≤ maxBindGroupsPlusVertexBuffers.

• maxVertexBuffers must be ≤ maxBindGroupsPlusVertexBuffers.

• minUniformBufferOffsetAlignment and minStorageBufferOffsetAlignment must both be ≥ 32 bytes.

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

• maxUniformBufferBindingSize must be ≤ maxBufferSize.

• maxStorageBufferBindingSize must be ≤ maxBufferSize.

• maxStorageBufferBindingSize must be a multiple of 4 bytes.

• maxVertexBufferArrayStride must be a multiple of 4 bytes.

• maxComputeWorkgroupSizeX must be ≤ maxComputeInvocationsPerWorkgroup.

• maxComputeWorkgroupSizeY must be ≤ maxComputeInvocationsPerWorkgroup.

• maxComputeWorkgroupSizeZ must be ≤ maxComputeInvocationsPerWorkgroup.

• maxComputeInvocationsPerWorkgroup must be ≤ maxComputeWorkgroupSizeX × maxComputeWorkgroupSizeY × maxComputeWorkgroupSizeZ.

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

dictionary GPURequestAdapterOptions {
    DOMString featureLevel = "core";
    GPUPowerPreference powerPreference;
    boolean forceFallbackAdapter = false;
    boolean xrCompatible = false;
};

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

GPURequestAdapterOptions has the following members:

featureLevel, of type DOMString, defaulting to "core"

"Feature level" for the adapter request.

The allowed feature level string values are:

"core"

No effect.

"compatibility"

No effect.

Note: This value is reserved for future use as a way to opt into additional validation restrictions. Applications should not use this value at this time.

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. This hint may also affect the power configuration of the selected GPU to match the requested power preference.

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 info.isFallbackAdapter attribute prior to requesting a GPUDevice.

xrCompatible, of type boolean, defaulting to false

When set to true indicates that the best adapter for rendering to a WebXR session must be returned. If the user agent or system does not support WebXR sessions then adapter selection may ignore this value.

Note: If xrCompatible is not set to true when the adapter is requested, GPUDevices created from the adapter cannot be used to render for WebXR sessions.

Requesting a

:

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

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

To get a GPUAdapter, use requestAdapter().

[Exposed=(Window, Worker), SecureContext]
interface GPUAdapter {
    [SameObject] readonly attribute GPUSupportedFeatures features;
    [SameObject] readonly attribute GPUSupportedLimits limits;
    [SameObject] readonly attribute GPUAdapterInfo info;

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

GPUAdapter has the following immutable properties

features, of type GPUSupportedFeatures, readonly

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

limits, of type GPUSupportedLimits, readonly

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

info, of type GPUAdapterInfo, readonly

Information about the physical adapter underlying this GPUAdapter.

For a given GPUAdapter, the GPUAdapterInfo values exposed are constant over time.

The same object is returned each time. To create that object for the first time:

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

This is a one-time action: if a device is returned successfully, the adapter becomes "consumed".

Device timeline initialization steps

:

1. If any of the following requirements are unmet:

   Then issue the following steps on contentTimeline and return:

   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. All of the requirements in the following steps must be met.

   1. adapter.[[state]] must not be "consumed".

   2. For each [key, value] in descriptor.requiredLimits for which value is not undefined:

      1. key must be the name of a member of supported limits.

      2. value must be no better than adapter.[[limits]][key].

      3. If key’s class is alignment, value must be a power of 2 less than 2³².

      Note: User agents should consider issuing developer-visible warnings when key is not recognized, even when value is undefined.

   If any are unmet, issue the following steps on contentTimeline and return:

3. If adapter.[[state]] is "expired" or the user agent otherwise cannot fulfill the request:

   1. Let device be a new device.

   2. Lose the device(device, "unknown").

   3. Assert adapter.[[state]] is "expired".

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

   Otherwise:

   1. Let device be a new device with the capabilities described by descriptor.

   2. Expire adapter.

4. Issue the subsequent steps on contentTimeline.

Requesting a

with default features and limits:

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

GPUDeviceDescriptor describes a device request.

dictionary GPUDeviceDescriptor
         : GPUObjectDescriptorBase {
    sequence<GPUFeatureName> requiredFeatures = [];
    record<DOMString, (GPUSize64 or undefined)> 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 or undefined)>, 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 with a non-undefined value must be the name of a member of supported limits.

API calls on the resulting device perform validation according to the exact limits of the device (not the adapter; see § 3.6.2 Limits).

defaultQueue, of type GPUQueueDescriptor, defaulting to {}

The descriptor for the default GPUQueue.

Requesting a

with the

feature if supported:

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

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

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

Requesting a

with a higher

limit:

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

if (gpuAdapter.limits.maxColorAttachmentBytesPerSample < 64) {
    // When the desired limit isn’t supported, take action to either fall back to a code
    // path that does not require the higher limit or notify the user that their device
    // does not meet minimum requirements.
}

// Request higher limit of max color attachments bytes per sample.
const gpuDevice = await gpuAdapter.requestDevice({
    requiredLimits: { maxColorAttachmentBytesPerSample: 64 },
});

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

enum GPUFeatureName {
    "core-features-and-limits",
    "depth-clip-control",
    "depth32float-stencil8",
    "texture-compression-bc",
    "texture-compression-bc-sliced-3d",
    "texture-compression-etc2",
    "texture-compression-astc",
    "texture-compression-astc-sliced-3d",
    "timestamp-query",
    "indirect-first-instance",
    "shader-f16",
    "rg11b10ufloat-renderable",
    "bgra8unorm-storage",
    "float32-filterable",
    "float32-blendable",
    "clip-distances",
    "dual-source-blending",
    "subgroups",
};

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, Worker), SecureContext]
interface GPUDevice : EventTarget {
    [SameObject] readonly attribute GPUSupportedFeatures features;
    [SameObject] readonly attribute GPUSupportedLimits limits;
    [SameObject] readonly attribute GPUAdapterInfo adapterInfo;

    [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 immutable properties:

features, of type GPUSupportedFeatures, readonly

A set containing the GPUFeatureName values of the features supported by the device ([[device]].[[features]]).

limits, of type GPUSupportedLimits, readonly

The limits supported by the device ([[device]].[[limits]]).

queue, of type GPUQueue, readonly

The primary GPUQueue for this device.

adapterInfo, of type GPUAdapterInfo, readonly

Information about the physical adapter which created the device that this GPUDevice refers to.

For a given GPUDevice, the GPUAdapterInfo values exposed are constant over time.

The same object is returned each time. To create that object for the first time:

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

GPUDevice has the following methods:

destroy()

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

Note: It is valid to destroy a device multiple times.

Note: Since no further operations can be enqueued on this device, implementations can abort outstanding asynchronous operations immediately and free resource allocations, including mapped memory that was just unmapped.

A more robust example of requesting a

and

with error handling:

let gpuDevice = null;

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

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

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

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

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

        gpuDevice = null;

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

    onWebGPUInitialized();

    return true;
}

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

initializeWebGPU();

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 createBuffer(). Buffers may be mappedAtCreation.

[Exposed=(Window, Worker), SecureContext]
interface GPUBuffer {
    readonly attribute GPUSize64Out size;
    readonly attribute GPUFlagsConstant usage;

    readonly attribute GPUBufferMapState mapState;

    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;

enum GPUBufferMapState {
    "unmapped",
    "pending",
    "mapped",
};

GPUBuffer has the following immutable properties:

size, of type GPUSize64Out, readonly

The length of the GPUBuffer allocation in bytes.

usage, of type GPUFlagsConstant, readonly

The allowed usages for this GPUBuffer.

GPUBuffer has the following content timeline properties:

mapState, of type GPUBufferMapState, readonly

The current GPUBufferMapState of the buffer:

"unmapped"

The buffer is not mapped for use by this.getMappedRange().

"pending"

A mapping of the buffer has been requested, but is pending. It may succeed, or fail validation in mapAsync().

"mapped"

The buffer is mapped and this.getMappedRange() may be used.

The getter steps are:

[[pending_map]], of type Promise<void> or null, initially null

The Promise returned by the currently-pending mapAsync() call.

There is never more than one pending map, because mapAsync() will refuse immediately if a request is already in flight.

[[mapping]], of type active buffer mapping or null, initially null

Set if and only if the buffer is currently mapped for use by getMappedRange(). Null otherwise (even if there is a [[pending_map]]).

An active buffer mapping is a structure with the following fields:

data, of type Data Block

The mapping for this GPUBuffer. This data is accessed through ArrayBuffers which are views onto this data, returned by getMappedRange() and stored in views.

mode, of type GPUMapModeFlags

The GPUMapModeFlags of the map, as specified in the corresponding call to mapAsync() or createBuffer().

range, of type tuple [unsigned long long, unsigned long long]

The range of this GPUBuffer that is mapped.

views, of type list<ArrayBuffer>

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

To

initialize an active buffer mapping

with mode

mode

and range

range

, run the following

content timeline

steps:

1. Let size be range[1] - range[0].

2. Let data be ? CreateByteDataBlock(size).

   NOTE:

   This may result in a

   RangeError

   being thrown. For consistency and predictability:

   • For any size at which new ArrayBuffer() would succeed at a given moment, this allocation should succeed at that moment.

   • For any size at which new ArrayBuffer() deterministically throws a RangeError, this allocation should as well.

3. Return an active buffer mapping with:

   • data set to data.

   • mode set to mode.

   • range set to range.

   • views set to [].

GPUBuffer has the following device timeline properties:

[[internal state]]

The current internal state of the buffer:

"available"

The buffer may be used in queue operations (unless it is invalid).

"unavailable"

The buffer may not be used in queue operations due to being mapped.

"destroyed"

The buffer may not be used in any operations due to being destroy()ed.

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

GPUBufferDescriptor has the following members:

size, of type GPUSize64

The size of the buffer in bytes.

usage, of type GPUBufferUsageFlags

The allowed usages for the buffer.

mappedAtCreation, of type boolean, defaulting to false

If true creates the buffer in an already mapped state, allowing getMappedRange() to be called immediately. It is valid to set mappedAtCreation to true even if usage does not contain MAP_READ or MAP_WRITE. This can be used to set the buffer’s initial data.

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

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

The GPUBufferUsage flags determine how a GPUBuffer may be used after its creation:

MAP_READ

The buffer can be mapped for reading. (Example: calling mapAsync() with GPUMapMode.READ)

May only be combined with COPY_DST.

MAP_WRITE

The buffer can be mapped for writing. (Example: calling mapAsync() with GPUMapMode.WRITE)

May only be combined with COPY_SRC.

COPY_SRC

The buffer can be used as the source of a copy operation. (Examples: as the source argument of a copyBufferToBuffer() or copyBufferToTexture() call.)

COPY_DST

The buffer can be used as the destination of a copy or write operation. (Examples: as the destination argument of a copyBufferToBuffer() or copyTextureToBuffer() call, or as the target of a writeBuffer() call.)

INDEX

The buffer can be used as an index buffer. (Example: passed to setIndexBuffer().)

VERTEX

The buffer can be used as a vertex buffer. (Example: passed to setVertexBuffer().)

UNIFORM

The buffer can be used as a uniform buffer. (Example: as a bind group entry for a GPUBufferBindingLayout with a buffer.type of "uniform".)

STORAGE

The buffer can be used as a storage buffer. (Example: as a bind group entry for a GPUBufferBindingLayout with a buffer.type of "storage" or "read-only-storage".)

INDIRECT

The buffer can be used as to store indirect command arguments. (Examples: as the indirectBuffer argument of a drawIndirect() or dispatchWorkgroupsIndirect() call.)

QUERY_RESOLVE

The buffer can be used to capture query results. (Example: as the destination argument of a resolveQuerySet() call.)

createBuffer(descriptor)

Creates a GPUBuffer.

Creating a 128 byte uniform buffer that can be written into:

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

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.

GPUBuffer has the following methods:

destroy()

Destroys the GPUBuffer.

Note: It is valid to destroy a buffer multiple times.

Note: Since no further operations can be enqueued using this buffer, implementations can free resource allocations, including mapped memory that was just unmapped.

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

Once the GPUBuffer is mapped, the application can synchronously ask for access to ranges of its content with getMappedRange(). The returned ArrayBuffer can only be detached by unmap() (directly, or via GPUBuffer.destroy() or GPUDevice.destroy()), and cannot be transferred. A TypeError is thrown by any other operation that attempts to do so.

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

The GPUMapMode flags determine how a GPUBuffer is mapped when calling mapAsync():

READ

Only valid with buffers created with the MAP_READ usage.

Once the buffer is mapped, calls to getMappedRange() will return an ArrayBuffer containing the buffer’s current values. Changes to the returned ArrayBuffer will be discarded after unmap() is called.

WRITE

Only valid with buffers created with the MAP_WRITE usage.

Once the buffer is mapped, calls to getMappedRange() will return an ArrayBuffer containing the buffer’s current values. Changes to the returned ArrayBuffer will be stored in the GPUBuffer after unmap() is called.

Note: Since the MAP_WRITE buffer usage may only be combined with the COPY_SRC buffer usage, mapping for writing can never return values produced by the GPU, and the returned ArrayBuffer will only ever contain the default initialized data (zeros) or data written by the webpage during a previous mapping.

GPUBuffer has the following methods:

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

The resolution of the returned Promise only indicates that the buffer has been mapped. It does not guarantee the completion of any other operations visible to the content timeline, and in particular does not imply that any other Promise returned from onSubmittedWorkDone() or mapAsync() on other GPUBuffers have resolved.

The resolution of the Promise returned from onSubmittedWorkDone() does imply the completion of mapAsync() calls made prior to that call, on GPUBuffers last used exclusively on that queue.

Device timeline validation steps

:

1. If size is undefined:

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

   Otherwise:

   1. Let rangeSize be size.

2. If any of the following conditions are unsatisfied:

   1. Set deviceLost to true.

   2. Issue the map failure steps on contentTimeline.

   3. Return.

3. If any of the following conditions are unsatisfied:

   Then:

   1. Set deviceLost to false.

   2. Issue the map failure steps on contentTimeline.

   3. Generate a validation error.

   4. Return.

4. Set this.[[internal state]] to "unavailable".

   Note: Since the buffer is mapped, its contents cannot change between this step and unmap().

5. When either of the following events occur (whichever comes first), or if either has already occurred:

   • The device timeline becomes informed of the completion of an unspecified queue timeline point:

     • after the completion of currently-enqueued operations that use this

     • and no later than the completion of all currently-enqueued operations (regardless of whether they use this).

   • this.[[device]] becomes lost.

   Then issue the subsequent steps on the device timeline of this.[[device]].

Device timeline

steps:

1. Set deviceLost to true if this.[[device]] is lost, and false otherwise.

   Note: The device could have been lost between the previous block of steps and this one.

2. If deviceLost:

   1. Issue the map failure steps on contentTimeline.

   Otherwise:

   1. Let internalStateAtCompletion be this.[[internal state]].

      Note: If, and only if, at this point the buffer has become "available" again due to an unmap() call, then [[pending_map]] != p below, so mapping will not succeed in the steps below.

   2. Let dataForMappedRegion be the contents of this starting at offset offset, for rangeSize bytes.

   3. Issue the map success steps on the contentTimeline.

getMappedRange(offset, size)

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

unmap()

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

A texture is made up of 1d, 2d, or 3d arrays of data which can contain multiple values per-element to represent things like colors. Textures can be read and written in many ways, depending on the GPUTextureUsage they are created with. For example, textures can be sampled, read, and written from render and compute pipeline shaders, and they can be written by render pass outputs. Internally, textures are often stored in GPU memory with a layout optimized for multidimensional access rather than linear access.

One texture consists of one or more texture subresources, each uniquely identified by a mipmap level and, for 2d textures only, array layer and aspect.

A texture subresource is a subresource: each can be used in different internal usages within a single usage scope.

Each subresource in a mipmap level is approximately half the size, in each spatial dimension, of the corresponding resource in the lesser level (see logical miplevel-specific texture extent). The subresource in level 0 has the dimensions of the texture itself. Smaller levels are typically used to store lower resolution versions of the same image. GPUSampler and WGSL provide facilities for selecting and interpolating between levels of detail, explicitly or automatically.

A "2d" texture may be an array of array layers. Each subresource in a layer is the same size as the corresponding resources in other layers. For non-2d textures, all subresources have an array layer index of 0.

Each subresource has an aspect. Color textures have just one aspect: color. Depth-or-stencil format textures may have multiple aspects: a depth aspect, a stencil aspect, or both, and may be used in special ways, such as in depthStencilAttachment and in "depth" bindings.

A "3d" texture may have multiple slices, each being the two-dimensional image at a particular z value in the texture. Slices are not separate subresources.

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

    undefined destroy();

    readonly attribute GPUIntegerCoordinateOut width;
    readonly attribute GPUIntegerCoordinateOut height;
    readonly attribute GPUIntegerCoordinateOut depthOrArrayLayers;
    readonly attribute GPUIntegerCoordinateOut mipLevelCount;
    readonly attribute GPUSize32Out sampleCount;
    readonly attribute GPUTextureDimension dimension;
    readonly attribute GPUTextureFormat format;
    readonly attribute GPUFlagsConstant usage;
};
GPUTexture includes GPUObjectBase;

GPUTexture has the following immutable properties:

width, of type GPUIntegerCoordinateOut, readonly

The width of this GPUTexture.

height, of type GPUIntegerCoordinateOut, readonly

The height of this GPUTexture.

depthOrArrayLayers, of type GPUIntegerCoordinateOut, readonly

The depth or layer count of this GPUTexture.

mipLevelCount, of type GPUIntegerCoordinateOut, readonly

The number of mip levels of this GPUTexture.

sampleCount, of type GPUSize32Out, readonly

The number of sample count of this GPUTexture.

dimension, of type GPUTextureDimension, readonly

The dimension of the set of texel for each of this GPUTexture’s subresources.

format, of type GPUTextureFormat, readonly

The format of this GPUTexture.

usage, of type GPUFlagsConstant, readonly

The allowed usages for this GPUTexture.

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

The set of GPUTextureFormats that can be used as the GPUTextureViewDescriptor.format when creating views on this GPUTexture.

GPUTexture has the following device timeline properties:

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

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:

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

GPUTextureDescriptor has the following members:

size, of type GPUExtent3D

The width, height, and depth or layer count of the texture.

mipLevelCount, of type GPUIntegerCoordinate, defaulting to 1

The number of mip levels the texture will contain.

sampleCount, of type GPUSize32, defaulting to 1

The sample count of the texture. A sampleCount > 1 indicates a multisampled texture.

dimension, of type GPUTextureDimension, defaulting to "2d"

Whether the texture is one-dimensional, an array of two-dimensional layers, or three-dimensional.

format, of type GPUTextureFormat

The format of the texture.

usage, of type GPUTextureUsageFlags

The allowed usages for the texture.

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

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

NOTE:

Adding a format to this list may have a significant performance impact, so it is best to avoid adding formats unnecessarily.

The actual performance impact is highly dependent on the target system; developers must test various systems to find out the impact on their particular application. For example, on some systems any texture with a format or viewFormats entry including "rgba8unorm-srgb" will perform less optimally than a "rgba8unorm" texture which does not. Similar caveats exist for other formats and pairs of formats on other systems.

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

Two

GPUTextureFormat

s

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

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

"1d"

Specifies a texture that has one dimension, width. "1d" textures cannot have mipmaps, be multisampled, use compressed or depth/stencil formats, or be used as a render target.

"2d"

Specifies a texture that has a width and height, and may have layers.

"3d"

Specifies a texture that has a width, height, and depth. "3d" textures cannot be multisampled, and their format must support 3d textures (all plain color formats and some packed/compressed formats).

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

The GPUTextureUsage flags determine how a GPUTexture may be used after its creation:

COPY_SRC

The texture can be used as the source of a copy operation. (Examples: as the source argument of a copyTextureToTexture() or copyTextureToBuffer() call.)

COPY_DST

The texture can be used as the destination of a copy or write operation. (Examples: as the destination argument of a copyTextureToTexture() or copyBufferToTexture() call, or as the target of a writeTexture() call.)

TEXTURE_BINDING

The texture can be bound for use as a sampled texture in a shader (Example: as a bind group entry for a GPUTextureBindingLayout.)

STORAGE_BINDING

The texture can be bound for use as a storage texture in a shader (Example: as a bind group entry for a GPUStorageTextureBindingLayout.)

RENDER_ATTACHMENT

The texture can be used as a color or depth/stencil attachment in a render pass. (Example: as a GPURenderPassColorAttachment.view or GPURenderPassDepthStencilAttachment.view.)

createTexture(descriptor)

Creates a GPUTexture.

Creating a 16x16, RGBA, 2D texture with one array layer and one mip level:

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

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.

GPUTexture has the following methods:

destroy()

Destroys the GPUTexture.

A GPUTextureView is a view onto some subset of the texture subresources defined by a particular GPUTexture.

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

GPUTextureView has the following immutable properties:

[[texture]], readonly

The GPUTexture into which this is a view.

[[descriptor]], readonly

The GPUTextureViewDescriptor describing this texture view.

All optional fields of GPUTextureViewDescriptor are defined.

[[renderExtent]], readonly

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

Note: this extent depends on the baseMipLevel.

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

GPUTextureViewDescriptor has the following members:

format, of type GPUTextureFormat

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

dimension, of type GPUTextureViewDimension

The dimension to view the texture as.

usage, of type GPUTextureUsageFlags, defaulting to 0

The allowed usage(s) for the texture view. Must be a subset of the usage flags of the texture. If 0, defaults to the full set of usage flags of the texture.

Note: If the view’s format doesn’t support all of the texture’s usages, the default will fail, and the view’s usage must be specified explicitly.

aspect, of type GPUTextureAspect, defaulting to "all"

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

baseMipLevel, of type GPUIntegerCoordinate, defaulting to 0

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

mipLevelCount, of type GPUIntegerCoordinate

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

baseArrayLayer, of type GPUIntegerCoordinate, defaulting to 0

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

arrayLayerCount, of type GPUIntegerCoordinate

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

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

"1d"

The texture is viewed as a 1-dimensional image.

Corresponding WGSL types:

• texture_1d

• texture_storage_1d

"2d"

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

Corresponding WGSL types:

• texture_2d

• texture_storage_2d

• texture_multisampled_2d

• texture_depth_2d

• texture_depth_multisampled_2d

"2d-array"

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

Corresponding WGSL types:

• texture_2d_array

• texture_storage_2d_array

• texture_depth_2d_array

"cube"

The texture is viewed as a cubemap.

The view has 6 array layers, each corresponding to a face of the cube in the order [+X, -X, +Y, -Y, +Z, -Z] and the following orientations:

Cubemap faces. The +U/+V axes indicate the individual faces' texture coordinates, and thus the texel copy memory layout of each face.

Note: When viewed from the inside, this results in a left-handed coordinate system where +X is right, +Y is up, and +Z is forward.

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 behaving like one "cube" view, for 6n array layers in total.

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

Each GPUTextureAspect value corresponds to a set of aspects. The set of aspects are defined for each value below.

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

"all"

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

The set of aspects is [color, depth, stencil].

"stencil-only"

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

The set of aspects is [stencil].

"depth-only"

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

The set of aspects is [depth].

createView(descriptor)

Creates a GPUTextureView.

NOTE:

By default

createView()

will create a view with a dimension that can represent the entire texture. For example, calling

createView()

without specifying a

dimension

on a

"2d"

texture with more than one layer will create a

"2d-array" GPUTextureView

, even if an

arrayLayerCount

of 1 is specified.

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

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

The of an aspect of a GPUTextureFormat is the number of bytes one texel block occupies during a texel copy, if applicable.

Note: The texel block memory cost of a GPUTextureFormat is the number of bytes needed to store one texel block. It is not fully defined for all formats. This value is informative and non-normative.

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",
    "rgb10a2uint",
    "rgb10a2unorm",
    "rg11b10ufloat",

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

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

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

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

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

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

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

The depth component of the "depth24plus" and "depth24plus-stencil8" formats may be implemented as either a 24-bit depth value or a "depth32float" value.

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

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 24-bit depth, 1 ULP has a constant value of 1 / (2²⁴ − 1).

• For depth32float, 1 ULP has a variable value no greater than 1 / (2²⁴).

A format is renderable if it is either a color renderable format, or a depth-or-stencil format. If a format is listed in § 26.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.

A renderable format is also blendable if it can be used with render pipeline blending. See § 26.1 Texture Format Capabilities.

A format is filterable if it supports the GPUTextureSampleType "float" (not just "unfilterable-float"); that is, it can be used with "filtering" GPUSamplers. See § 26.1 Texture Format Capabilities.

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

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

A GPUExternalTexture is a sampleable 2D texture wrapping an external video frame. It is an immutable snapshot; its contents may not change over time, either from inside WebGPU (it is only sampleable) or from outside WebGPU (e.g. due to video frame advancement).

GPUExternalTextures can be bound into bind groups via the externalTexture bind group layout entry member. Note that member uses several binding slots, as defined there.

NOTE:

be implemented without creating a copy of the imported source, but this depends

factors. Ownership of the underlying representation may either be exclusive or shared with other owners (such as a video decoder), but this is not visible to the application.

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

• Up to three 2D planes of data (e.g. RGBA, Y+UV, Y+U+V).

• Metadata for converting coordinates before reading from those planes (crop and rotation).

• Metadata for converting values into the specified output color space (matrices, gammas, 3D LUT).

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

• three sampled texture bindings (for up to 3 planes),

• one sampled texture binding for a 3D LUT,

• one sampler binding to sample the 3D LUT, and

• one uniform buffer binding for metadata.

[Exposed=(Window, Worker), SecureContext]
interface GPUExternalTexture {
};
GPUExternalTexture includes GPUObjectBase;

GPUExternalTexture has the following immutable properties:

[[descriptor]], of type GPUExternalTextureDescriptor, readonly

The descriptor with which the texture was created.

GPUExternalTexture has the following immutable properties:

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

Indicates whether the object has expired (can no longer be used).

Note: Unlike [[destroyed]] slots, which are similar, this can change from true back to false.

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

An external texture created from an HTMLVideoElement expires (is destroyed) automatically in a task after it is imported, instead of manually or upon garbage collection like other resources. When an external texture expires, its [[expired]] slot changes to true.

An external texture created from a VideoFrame expires (is destroyed) when, and only when, the source VideoFrame is closed, either explicitly by close(), or by other means.

Note: As noted in decode(), authors should call close() on output VideoFrames to avoid decoder stalls. If an imported VideoFrame is dropped without being closed, the imported GPUExternalTexture object will keep it alive until it is also dropped. The VideoFrame cannot be garbage collected until both objects are dropped. Garbage collection is unpredictable, so this may still stall the video decoder.

Once the GPUExternalTexture expires, importExternalTexture() must be called again. However, the user agent may un-expire and return the same GPUExternalTexture again, instead of creating a new one. This will commonly happen unless the execution of the application is scheduled to match the video’s frame rate (e.g. using requestVideoFrameCallback()). If the same object is returned again, it will compare equal, and GPUBindGroups, GPURenderBundles, etc. referencing the previous object can still be used.

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

GPUExternalTextureDescriptor dictionaries have the following members:

source, of type (HTMLVideoElement or VideoFrame)

The video source to import the external texture from. Source size is determined as described by the external source dimensions table.

colorSpace, of type PredefinedColorSpace, defaulting to "srgb"

The color space the image contents of source will be converted into when reading.

importExternalTexture(descriptor)

Creates a GPUExternalTexture wrapping the provided image source.

Called on: GPUDevice this

.

Arguments:

Returns: GPUExternalTexture

Content timeline steps:

1. Let source be descriptor.source.

2. If the current image contents of source are the same as the most recent importExternalTexture() call with the same descriptor (ignoring label), and the user agent chooses to reuse it:

   1. Let previousResult be the GPUExternalTexture returned previously.

   2. Set previousResult.[[expired]] to false, renewing ownership of the underlying resource.

   3. Let result be previousResult.

   Note: This allows the application to detect duplicate imports and avoid re-creating dependent objects (such as GPUBindGroups). Implementations still need to be able to handle a single frame being wrapped by multiple GPUExternalTexture, since import metadata like colorSpace can change even for the same frame.

   Otherwise:

   1. If source is not origin-clean, throw a SecurityError and return.

   2. Let usability be ? check the usability of the image argument(source).

   3. If usability is not good:

      1. Generate a validation error.

      2. Return an invalidated GPUExternalTexture.

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

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

3. If source is an HTMLVideoElement, queue an automatic expiry task with device this and the following steps:

   1. Set result.[[expired]] to true, releasing ownership of the underlying resource.

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

4. If source is a VideoFrame, then when source is closed, run the following steps:

5. Set result.label to descriptor.label.

6. Return result.

Rendering using an video element external texture at the page animation frame rate:

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

function frame() {
    requestAnimationFrame(frame);

    // Always re-import the video on every animation frame, because the
    // import is likely to have expired.
    // The browser may cache and reuse a past frame, and if it does it
    // may return the same GPUExternalTexture object again.
    // In this case, old bind groups are still valid.
    const externalTexture = gpuDevice.importExternalTexture({
        source: videoElement
    });

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

Rendering using an video element external texture at the video’s frame rate, if

is available:

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

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

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

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

The externalTexture binding point allows binding GPUExternalTexture objects (from dynamic image sources like videos). It also supports GPUTextureView.

Note: When a GPUTextureView is bound to an externalTexture binding, it is like a GPUExternalTexture with a single RGBA plane and no crop, rotation, or color conversion.

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

The sampler provided to textureSampleBaseClampToEdge is used to sample the underlying textures.

When the binding resource type is a GPUExternalTexture, 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.

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

GPUSamplers are created via createSampler().

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

GPUSampler has the following immutable properties:

[[descriptor]], of type GPUSamplerDescriptor, readonly

The GPUSamplerDescriptor with which the GPUSampler was created.

[[isComparison]], of type boolean, readonly

Whether the GPUSampler is used as a comparison sampler.

[[isFiltering]], of type boolean, readonly

Whether the GPUSampler weights multiple samples of a texture.

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

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

addressModeU, of type GPUAddressMode, defaulting to "clamp-to-edge"

addressModeV, of type GPUAddressMode, defaulting to "clamp-to-edge"

addressModeW, of type GPUAddressMode, defaulting to "clamp-to-edge"

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

magFilter, of type GPUFilterMode, defaulting to "nearest"

Specifies the sampling behavior when the sampled area is smaller than or equal to one texel.

minFilter, of type GPUFilterMode, defaulting to "nearest"

Specifies the sampling behavior when the sampled area is larger than one texel.

mipmapFilter, of type GPUMipmapFilterMode, defaulting to "nearest"

Specifies behavior for sampling between mipmap levels.

lodMinClamp, of type float, defaulting to 0

lodMaxClamp, of type float, defaulting to 32

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

compare, of type GPUCompareFunction

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

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

maxAnisotropy, of type unsigned short, defaulting to 1

Specifies the maximum anisotropy value clamp used by the sampler. Anisotropic filtering is enabled when maxAnisotropy is > 1 and the implementation supports it.

Anisotropic filtering improves the image quality of textures sampled at oblique viewing angles. Higher maxAnisotropy values indicate the maximum ratio of anisotropy supported when filtering.

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.

The precise filtering behavior is implementation-dependent.

Level of detail (LOD) describes which mip level(s) are selected when sampling a texture. It may be specified explicitly through shader methods like textureSampleLevel or implicitly determined from the texture coordinate derivatives.

Note: See Scale Factor Operation, LOD Operation and Image Level Selection in the Vulkan 1.3 spec for an example of how implicit LODs may be calculated.

GPUAddressMode describes the behavior of the sampler if the sampled texels extend beyond the bounds of the sampled texture.

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 sampled area does not cover exactly one texel.

Note: See Texel Filtering in the Vulkan 1.3 spec for an example of how samplers may determine which texels are sampled from for the various filtering modes.

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, the depth_ref is compared to the fetched texel value, and the result of this comparison test is generated (1.0f for pass, or 0.0f for fail).

After comparison, if texture filtering is enabled, the filtering step occurs, so that comparison results are mixed together resulting in values in the range [0, 1]. Filtering should behave as usual, however it may be computed with lower precision or not mix results at all.

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.

Creating a

that does trilinear filtering and repeats texture coordinates:

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

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

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

GPUBindGroupLayout has the following immutable properties:

[[descriptor]], of type GPUBindGroupLayoutDescriptor, readonly

A GPUBindGroupLayout is created via GPUDevice.createBindGroupLayout().

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

GPUBindGroupLayoutDescriptor dictionaries have the following members:

entries, of type sequence<GPUBindGroupLayoutEntry>

A list of entries describing the shader resource bindings for a bind group.

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

dictionary GPUBindGroupLayoutEntry {
    required GPUIndex32 binding;
    required GPUShaderStageFlags visibility;

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

GPUBindGroupLayoutEntry dictionaries have the following members:

binding, of type GPUIndex32

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

visibility, of type GPUShaderStageFlags

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

buffer, of type GPUBufferBindingLayout

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

sampler, of type GPUSamplerBindingLayout

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

texture, of type GPUTextureBindingLayout

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

storageTexture, of type GPUStorageTextureBindingLayout

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

externalTexture, of type GPUExternalTextureBindingLayout

When provided, indicates the binding resource type for this GPUBindGroupLayoutEntry is either GPUExternalTexture or GPUTextureView.

External textures use several binding slots: see Exceeds the binding slot limits.

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

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

VERTEX

The bind group entry will be accessible to vertex shaders.

FRAGMENT

The bind group entry will be accessible to fragment shaders.

COMPUTE

The bind group entry will be accessible to compute shaders.

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

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

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

GPUBufferBindingLayout dictionaries have the following members:

type, of type GPUBufferBindingType, defaulting to "uniform"

Indicates the type required for buffers bound to this bindings.

hasDynamicOffset, of type boolean, defaulting to false

Indicates whether this binding requires a dynamic offset.

minBindingSize, of type GPUSize64, defaulting to 0

Indicates the minimum size of a buffer binding used with this bind point.

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

If this is not 0, pipeline creation additionally validates that this value ≥ the minimum buffer binding size of the variable.

If this is 0, it is ignored by pipeline creation, and instead draw/dispatch commands validate that each binding in the GPUBindGroup satisfies the minimum buffer binding size of the variable.

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

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

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

GPUSamplerBindingLayout dictionaries have the following members:

type, of type GPUSamplerBindingType, defaulting to "filtering"

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

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

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

GPUTextureBindingLayout dictionaries have the following members:

sampleType, of type GPUTextureSampleType, defaulting to "float"

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

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

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

multisampled, of type boolean, defaulting to false

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

enum GPUStorageTextureAccess {
    "write-only",
    "read-only",
    "read-write",
};

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

GPUStorageTextureBindingLayout dictionaries have the following members:

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

The access mode for this binding, indicating readability and writability.

format, of type GPUTextureFormat

The required format of texture views bound to this binding.

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

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

dictionary GPUExternalTextureBindingLayout {
};

A GPUBindGroupLayout object has the following device timeline properties:

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

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

[[dynamicOffsetCount]], of type GPUSize32, readonly

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

[[exclusivePipeline]], of type GPUPipelineBase?, readonly

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

createBindGroupLayout(descriptor)

Creates a GPUBindGroupLayout.

Two

objects

and

are considered

if and only if all of the following conditions are satisfied:

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

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

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

GPUBindGroup has the following device timeline properties:

[[layout]], of type GPUBindGroupLayout, readonly

The GPUBindGroupLayout associated with this GPUBindGroup.

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

The set of GPUBindGroupEntrys this GPUBindGroup describes.

[[usedResources]], of type usage scope, readonly

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

A GPUBindGroup is created via GPUDevice.createBindGroup().

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

GPUBindGroupDescriptor dictionaries have the following members:

layout, of type GPUBindGroupLayout

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

entries, of type sequence<GPUBindGroupEntry>

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

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

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

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

binding, of type GPUIndex32

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

resource, of type GPUBindingResource

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

GPUBindGroupEntry has the following device timeline properties:

[[prevalidatedSize]], of type boolean

Whether or not this binding entry had its buffer size validated at time of creation.

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

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

buffer, of type GPUBuffer

The GPUBuffer to bind.

offset, of type GPUSize64, defaulting to 0

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

size, of type GPUSize64

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

createBindGroup(descriptor)

Creates a GPUBindGroup.

Two

objects

and

are considered

if and only if all of the following are true:

• a.buffer == b.buffer

• The range formed by a.offset and a.size intersects the range formed by b.offset and b.size, where if a size is unspecified, the range goes to the end of the buffer.

Note: When doing this calculation, any dynamic offsets have already been applied to the ranges.

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

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

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

2. bind group index

3. binding number

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

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

GPUPipelineLayout has the following device timeline properties:

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

The GPUBindGroupLayout objects provided at creation in GPUPipelineLayoutDescriptor.bindGroupLayouts.

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

object X was created with

A, B, C.

object Y was created with

A, D, C. Supposing the command encoding sequence has two dispatches:

1. setBindGroup(0, ...)

2. setBindGroup(1, ...)

3. setBindGroup(2, ...)

4. setPipeline(X)

5. dispatchWorkgroups()

6. setBindGroup(1, ...)

7. setPipeline(Y)

8. dispatchWorkgroups()

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

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

A GPUPipelineLayout is created via GPUDevice.createPipelineLayout().

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

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

bindGroupLayouts, of type sequence<GPUBindGroupLayout?>

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

createPipelineLayout(descriptor)

Creates a GPUPipelineLayout.

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

Create a

that describes a binding with a uniform buffer, a texture, and a sampler. Then create a

and a

using the

.

const bindGroupLayout = gpuDevice.createBindGroupLayout({
    entries: [{
        binding: 0,
        visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT,
        buffer: {}
    }, {
        binding: 1,
        visibility: GPUShaderStage.FRAGMENT,
        texture: {}
    }, {
        binding: 2,
        visibility: GPUShaderStage.FRAGMENT,
        sampler: {}
    }]
});

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

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

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

GPUShaderModule is a reference to an internal shader module object.

dictionary GPUShaderModuleDescriptor
         : GPUObjectDescriptorBase {
    required USVString code;
    sequence<GPUShaderModuleCompilationHint> compilationHints = [];
};

code, of type USVString

The WGSL source code for the shader module.

compilationHints, of type sequence<GPUShaderModuleCompilationHint>, defaulting to []

A list of GPUShaderModuleCompilationHints.

Any hint provided by an application should contain information about one entry point of a pipeline that will eventually be created from the entry point.

Implementations should use any information present in the GPUShaderModuleCompilationHint to perform as much compilation as is possible within createShaderModule().

Aside from type-checking, these hints are not validated in any way.

NOTE:

Supplying information in

compilationHints

does not have any observable effect, other than performance. It may be detrimental to performance to provide hints for pipelines that never end up being created.

Because a single shader module can hold multiple entry points, and multiple pipelines can be created from a single shader module, it can be more performant for an implementation to do as much compilation as possible once in createShaderModule() rather than multiple times in the multiple calls to createComputePipeline() or createRenderPipeline().

Hints are only applied to the entry points they explicitly name. Unlike GPUProgrammableStage.entryPoint, there is no default, even if only one entry point is present in the module.

Note: Hints are not validated in an observable way, but user agents may surface identifiable errors (like unknown entry point names or incompatible pipeline layouts) to developers, for example in the browser developer console.

createShaderModule(descriptor)

Creates a GPUShaderModule.

Device timeline initialization steps

:

1. Let error be any error that results from shader module creation with the WGSL source descriptor.code, or null if no errors occured.

2. If any of the following requirements are unmet, generate a validation error, invalidate sm, and return.

   Note: Uncategorized errors cannot arise from shader module creation. Implementations which detect such errors during shader module creation must behave as if the shader module is valid, and defer surfacing the error until pipeline creation.

NOTE:

User agents

should not

include detailed compiler error messages or shader text in the

message

text of validation errors arising here: these details are accessible via

getCompilationInfo()

. User agents

should

surface human-readable, formatted error details

to developers

for easier debugging (for example as a warning in the browser developer console, expandable to show full shader source).

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

Create a

from WGSL code:

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

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

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

const shaderModule = gpuDevice.createShaderModule({
    code: shaderSource,
});

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

dictionary GPUShaderModuleCompilationHint {
    required USVString entryPoint;
    (GPUPipelineLayout or GPUAutoLayoutMode) layout;
};

layout, of type (GPUPipelineLayout or GPUAutoLayoutMode)

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

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

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

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

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

GPUCompilationMessage has the following attributes:

message, of type DOMString, readonly

The human-readable, localizable text for this compilation message.

Note: The message should follow the best practices for language and direction information. This includes making use of any future standards which may emerge regarding the reporting of string language and direction metadata.

Editorial note: At the time of this writing, no language/direction recommendation is available that provides compatibility and consistency with legacy APIs, but when there is, adopt it formally.

type, of type GPUCompilationMessageType, readonly

The severity level of the message.

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

lineNum, of type unsigned long long, readonly

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

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

linePos, of type unsigned long long, readonly

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

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

offset, of type unsigned long long, readonly

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

length, of type unsigned long long, readonly

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

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

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

getCompilationInfo()

Returns any messages generated during the GPUShaderModule’s compilation.

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

Content timeline

steps:

1. Let info be a new GPUCompilationInfo.

2. Let messages be a list of any errors, warnings, or informational messages generated during shader module creation for this, or the empty list [] if the device was lost.

3. For each message in messages:

   1. Let m be a new GPUCompilationMessage.

   2. Set m.message to be the text of message.

   3. If message is a shader-creation error:

      Set m.type to "error"

      If message is a warning:

      Set m.type to "warning"

      Otherwise:

      Set m.type to "info"

   4. If message is associated with a specific substring or position within the shader code:

      1. Set m.lineNum to the one-based number of the first line that the message refers to.

      2. Set m.linePos to the one-based number of the first UTF-16 code units on m.lineNum that the message refers to, or 1 if the message refers to the entire line.

      3. Set m.offset to the number of UTF-16 code units from the beginning of the shader to beginning of the substring or position that message refers to.

      4. Set m.length the length of the substring in UTF-16 code units that message refers to, or 0 if message refers to a position

      Otherwise:

      1. Set m.lineNum to 0.

      2. Set m.linePos to 0.

      3. Set m.offset to 0.

      4. Set m.length to 0.

   5. Append m to info.messages.

4. Resolve promise with info.

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

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

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

This combination state is created as a single object (a GPUComputePipeline or GPURenderPipeline) and switched using one command (GPUComputePassEncoder.setPipeline() or GPURenderCommandsMixin.setPipeline() respectively).

There are two ways to create pipelines:

immediate pipeline creation

createComputePipeline() and createRenderPipeline() return a pipeline object which can be used immediately in a pass encoder.

When this fails, the pipeline object will be invalid and the call will generate either a validation error or an internal error.

Note: A handle object is returned immediately, but actual pipeline creation is not synchronous. If pipeline creation takes a long time, this can incur a stall in the device timeline at some point between the creation call and execution of the submit() in which it is first used. The point is unspecified, but most likely to be one of: at creation, at the first usage of the pipeline in setPipeline(), at the corresponding finish() of that GPUCommandEncoder or GPURenderBundleEncoder, or at submit() of that GPUCommandBuffer.

async pipeline creation

createComputePipelineAsync() and createRenderPipelineAsync() return a Promise which resolves to a pipeline object when creation of the pipeline has completed.

When this fails, the Promise rejects with a GPUPipelineError.

GPUPipelineError describes a pipeline creation failure.

[Exposed=(Window, Worker), SecureContext, Serializable]
interface GPUPipelineError : DOMException {
    constructor(optional DOMString message = "", GPUPipelineErrorInit options);
    readonly attribute GPUPipelineErrorReason reason;
};

dictionary GPUPipelineErrorInit {
    required GPUPipelineErrorReason reason;
};

enum GPUPipelineErrorReason {
    "validation",
    "internal",
};

GPUPipelineError constructor:

constructor()

GPUPipelineError has the following attributes:

reason, of type GPUPipelineErrorReason, readonly

A read-only slot-backed attribute exposing the type of error encountered in pipeline creation as a GPUPipelineErrorReason:

• "validation": A validation error.

• "internal": An internal error.

GPUPipelineError objects are serializable objects.

enum GPUAutoLayoutMode {
    "auto",
};

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

layout, of type (GPUPipelineLayout or GPUAutoLayoutMode)

The GPUPipelineLayout for this pipeline, or "auto" to generate the pipeline layout automatically.

Note: If "auto" is used the pipeline cannot share GPUBindGroups with any other pipelines.

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

GPUPipelineBase has the following device timeline properties:

[[layout]], of type GPUPipelineLayout

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

GPUPipelineBase has the following methods:

getBindGroupLayout(index)

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

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

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

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

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

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

GPUProgrammableStage has the following members:

module, of type GPUShaderModule

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

entryPoint, of type USVString

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

NOTE: Since the entryPoint dictionary member is not required, methods which consume a GPUProgrammableStage must use the "get the entry point" algorithm to determine which entry point it refers to.

constants, of type record<USVString, GPUPipelineConstantValue>, defaulting to {}

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

Each such pipeline-overridable constant is uniquely identified by a single pipeline-overridable constant identifier string, representing the pipeline constant ID of the constant if its declaration specifies one, and otherwise the constant’s identifier name.

The key of each key-value pair must equal the identifier string of one such constant, with the comparison performed according to the rules for WGSL identifier comparison. When the pipeline is executed, that constant will have the specified value.

Values are specified as GPUPipelineConstantValue, which is a double. They are converted to WGSL type of the pipeline-overridable constant (bool/i32/u32/f32/f16). If conversion fails, a validation error is generated.

Pipeline-overridable constants defined in WGSL:

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

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

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

Corresponding JavaScript code, overriding all constants:

{
    // ...
    constants: {
        0: false,   // "has_point_light"
        1200: 3.0,  // "specular_param"
        1300: 2.0,  // "gain"
        width: 20,  // "width"
        depth: -1,  // "depth"
        height: 15, // "height"
    }
}

To

(

,

), run the following

steps:

1. If descriptor.entryPoint is provided:

   1. If descriptor.module contains an entry point whose name equals descriptor.entryPoint, and whose shader stage equals stage, return that entry point.

      Otherwise, return null.

   Otherwise:

   1. If there is exactly one entry point in descriptor.module whose shader stage equals stage, return that entry point.

      Otherwise, return null.

(

,

,

,

)

Arguments:

• GPUShaderStage stage

• GPUProgrammableStage descriptor

• GPUPipelineLayout layout

• GPUDevice device

All of the requirements in the following steps must be met. If any are unmet, return false; otherwise, return true.

1. descriptor.module must be valid to use with device.

2. Let entryPoint be get the entry point(stage, descriptor).

3. entryPoint must not be null.

4. For each binding that is statically used by entryPoint:

   • validating shader binding(binding, layout) must return true.

5. For each texture builtin function call in any of the functions in the shader stage rooted at entryPoint, if it uses a textureBinding of sampled texture or depth texture type together with a samplerBinding of sampler type (excluding sampler_comparison):

   1. Let texture be the GPUBindGroupLayoutEntry corresponding to textureBinding.

   2. Let sampler be the GPUBindGroupLayoutEntry corresponding to samplerBinding.

   3. If sampler.type is "filtering", then texture.sampleType must be "float".

   Note: "comparison" samplers can also only be used with "depth" textures, because they are the only texture type that can be bound to WGSL texture_depth_* bindings.

6. For each key → value in descriptor.constants:

   1. key must equal the pipeline-overridable constant identifier string of some pipeline-overridable constant defined in the shader module descriptor.module by the rules defined in WGSL identifier comparison. The pipeline-overridable constant is not required to be statically used by entryPoint. Let the type of that constant be T.

   2. Converting the IDL value value to WGSL type T must not throw a TypeError.

7. For each pipeline-overridable constant identifier string key which is statically used by entryPoint:

   • If the pipeline-overridable constant identified by key does not have a default value, descriptor.constants must contain key.

8. Pipeline-creation program errors must not result from the rules of the [WGSL] specification.

(

,

)

Arguments:

• shader binding declaration variable, a module-scope variable declaration reflected from a shader module

• GPUPipelineLayout layout

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

Return true if all of the following conditions are satisfied:

• layout.[[bindGroupLayouts]][bindGroup] contains a GPUBindGroupLayoutEntry entry whose entry.binding == bindIndex.

• If the defined binding member for entry is:

  buffer

  If entry.buffer.type is:

  "uniform"

  variable is declared with address space uniform.

  "storage"

  variable is declared with address space storage and access mode read_write.

  "read-only-storage"

  variable is declared with address space storage and access mode read.

  If entry.buffer.minBindingSize is not 0, then it must be at least the minimum buffer binding size for the associated buffer binding variable in the shader.

  sampler

  If entry.sampler.type is:

  "filtering" or "non-filtering"

  variable has type sampler.

  "comparison"

  variable has type sampler_comparison.

  texture

  If, and only if, entry.texture.multisampled is true, variable has type texture_multisampled_2d<T> or texture_depth_multisampled_2d<T>.

  If entry.texture.sampleType is:

  "float", "unfilterable-float", "sint" or "uint"

  variable has one of the types:

  • texture_1d<T>

  • texture_2d<T>

  • texture_2d_array<T>

  • texture_cube<T>

  • texture_cube_array<T>

  • texture_3d<T>

  • texture_multisampled_2d<T>

  If entry.texture.sampleType is:

  "float" or "unfilterable-float"

  The sampled type T is f32.

  "sint"

  The sampled type T is i32.

  "uint"

  The sampled type T is u32.

  "depth"

  variable has one of the types:

  • texture_2d<T>

  • texture_2d_array<T>

  • texture_cube<T>

  • texture_cube_array<T>

  • texture_multisampled_2d<T>

  • texture_depth_2d

  • texture_depth_2d_array

  • texture_depth_cube

  • texture_depth_cube_array

  • texture_depth_multisampled_2d

  where the sampled type T is f32.

  If entry.texture.viewDimension is:

  "1d"

  variable has type texture_1d<T>.

  "2d"

  variable has type texture_2d<T> or texture_multisampled_2d<T>.

  "2d-array"

  variable has type texture_2d_array<T>.

  "cube"

  variable has type texture_cube<T>.

  "cube-array"

  variable has type texture_cube_array<T>.

  "3d"

  variable has type texture_3d<T>.

  storageTexture

  If entry.storageTexture.viewDimension is:

  "1d"

  variable has type texture_storage_1d<T, A>.

  "2d"

  variable has type texture_storage_2d<T, A>.

  "2d-array"

  variable has type texture_storage_2d_array<T, A>.

  "3d"

  variable has type texture_storage_3d<T, A>.

  If entry.storageTexture.access is:

  "write-only"

  The access mode A is write.

  "read-only"

  The access mode A is read.

  "read-write"

  The access mode A is read_write or write.

  The texel format T equals entry.storageTexture.format.

The

for a buffer binding variable

is computed as follows:

1. Let T be the store type of var.

2. If T is a runtime-sized array, or contains a runtime-sized array, replace that array<E> with array<E, 1>.

   Note: This ensures there’s always enough memory for one element, which allows array indices to be clamped to the length of the array resulting in an in-memory access.

3. Return SizeOf(T).

Note: Enforcing this lower bound ensures reads and writes via the buffer variable only access memory locations within the bound region of the buffer.

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

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

Stages of a compute pipeline:

1. Compute shader

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

A GPUComputePipelineDescriptor describes a compute pipeline. See § 23.1 Computing for additional details.

dictionary GPUComputePipelineDescriptor
         : GPUPipelineDescriptorBase {
    required GPUProgrammableStage compute;
};

GPUComputePipelineDescriptor has the following members:

compute, of type GPUProgrammableStage

Describes the compute shader entry point of the pipeline.

createComputePipeline(descriptor)

Creates a GPUComputePipeline using immediate pipeline creation.

createComputePipelineAsync(descriptor)

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

If pipeline creation fails, the returned Promise rejects with an GPUPipelineError. (A GPUError is not dispatched to the device.)

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

Creating a simple

:

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

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

Render pipeline inputs are:

• bindings, according to the given GPUPipelineLayout

• vertex and index buffers, described by GPUVertexState

• the color attachments, described by GPUColorTargetState

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

Render pipeline outputs are:

• buffer bindings with a type of "storage"

• storageTexture bindings with a access of "write-only" or "read-write"

• the color attachments, described by GPUColorTargetState

• optionally, depth-stencil attachment, described by GPUDepthStencilState

A render pipeline is comprised of the following render stages:

1. Vertex fetch, controlled by GPUVertexState.buffers

2. Vertex shader, controlled by GPUVertexState

3. Primitive assembly, controlled by GPUPrimitiveState

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

5. Fragment shader, controlled by GPUFragmentState

6. Stencil test and operation, controlled by GPUDepthStencilState

7. Depth test and write, controlled by GPUDepthStencilState

8. Output merging, controlled by GPUFragmentState.targets

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

GPURenderPipeline has the following device timeline properties:

[[descriptor]], of type GPURenderPipelineDescriptor, readonly

The GPURenderPipelineDescriptor describing this pipeline.

All optional fields of GPURenderPipelineDescriptor are defined.

[[writesDepth]], of type boolean, readonly

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

[[writesStencil]], of type boolean, readonly

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

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

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

GPURenderPipelineDescriptor has the following members:

vertex, of type GPUVertexState

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

primitive, of type GPUPrimitiveState, defaulting to {}

Describes the primitive-related properties of the pipeline.

depthStencil, of type GPUDepthStencilState

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

multisample, of type GPUMultisampleState, defaulting to {}

Describes the multi-sampling properties of the pipeline.

fragment, of type GPUFragmentState

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

createRenderPipeline(descriptor)

Creates a GPURenderPipeline using immediate pipeline creation.

Device timeline initialization steps

:

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

2. All of the requirements in the following steps must be met. If any are unmet, generate a validation error, invalidate pipeline, and return.

3. If any pipeline-creation uncategorized errors result from the implementation of pipeline creation, generate an internal error, invalidate pipeline and return.

   Note: Even if the implementation detected uncategorized errors in shader module creation, the error is surfaced here.

4. Set pipeline.[[descriptor]] to descriptor.

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

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

7. Let depthStencil be descriptor.depthStencil.

8. If depthStencil is not null:

   1. If depthStencil.depthWriteEnabled is provided:

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

   2. If depthStencil.stencilWriteMask is not 0:

      1. Let stencilFront be depthStencil.stencilFront.

      2. Let stencilBack be depthStencil.stencilBack.

      3. Let cullMode be descriptor.primitive.cullMode.

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

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

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

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

9. Set pipeline.[[layout]] to layout.

createRenderPipelineAsync(descriptor)

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

If pipeline creation fails, the returned Promise rejects with an GPUPipelineError. (A GPUError is not dispatched to the device.)

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

(descriptor, layout, device)

Arguments:

• GPURenderPipelineDescriptor descriptor

• GPUPipelineLayout layout

• GPUDevice device

Device timeline steps:

1. Return true if all of the following conditions are satisfied:

   • validating GPUVertexState(device, descriptor.vertex, layout) succeeds.

   • If descriptor.fragment is provided:

     • validating GPUFragmentState(device, descriptor.fragment, layout) succeeds.

     • If the sample_mask builtin is a shader stage output of descriptor.fragment:

       • descriptor.multisample.alphaToCoverageEnabled is false.

     • If the frag_depth builtin is a shader stage output of descriptor.fragment:

       • descriptor.depthStencil must be provided, and descriptor.depthStencil.format must have a depth aspect.

   • validating GPUPrimitiveState(descriptor.primitive, device) succeeds.

   • If descriptor.depthStencil is provided:

     • validating GPUDepthStencilState(descriptor.depthStencil, descriptor.primitive.topology) succeeds.

   • validating GPUMultisampleState(descriptor.multisample) succeeds.

   • If descriptor.multisample.alphaToCoverageEnabled is true:

     1. descriptor.fragment must be provided.

     2. descriptor.fragment.targets[0] must exist and be non-null.

     3. descriptor.fragment.targets[0].format must be a GPUTextureFormat which is blendable and has an alpha channel.

   • There must exist at least one attachment, either:

     • A non-null value in descriptor.fragment.targets, or

     • A descriptor.depthStencil.

   • validating inter-stage interfaces(device, descriptor) returns true.