1. Introduction
This section is non-normative.
Graphics Processing Units, or GPUs for short, have been essential in enabling rich rendering and computational applications in personal computing. WebGPU is an API that exposes the capabilities of GPU hardware for the Web. The API is designed from the ground up to efficiently map to (post-2014) native GPU APIs. WebGPU is not related to WebGL and does not explicitly target OpenGL ES.
WebGPU sees physical GPU hardware as GPUAdapter
s. It provides a connection to an adapter via GPUDevice
, which manages resources, and the device’s GPUQueue
s, 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 GPUCommandBuffer
s by feeding data through a pipeline,
which is a mix of fixed-function and programmable stages. Programmable stages execute shaders, which are special programs designed to run on GPU hardware.
Most of the state of a pipeline is defined by
a GPURenderPipeline
or a GPUComputePipeline
object. The state not included
in these pipeline objects is set during encoding with commands,
such as beginRenderPass()
or setBlendConstant()
.
2. Malicious use considerations
This section is non-normative. It describes the risks associated with exposing this API on the Web.
2.1. Security Considerations
The security requirements for WebGPU are the same as ever for the web, and are likewise non-negotiable. The general approach is strictly validating all the commands before they reach GPU, ensuring that a page can only work with its own data.
2.1.1. CPU-based undefined behavior
A WebGPU implementation translates the workloads issued by the user into API commands specific to the target platform. Native APIs specify the valid usage for the commands (for example, see vkCreateDescriptorSetLayout) and generally don’t guarantee any outcome if the valid usage rules are not followed. This is called "undefined behavior", and it can be exploited by an attacker to access memory they don’t own, or force the driver to execute arbitrary code.
In order to disallow insecure usage, the range of allowed WebGPU behaviors is defined for any input.
An implementation has to validate all the input from the user and only reach the driver
with the valid workloads. This document specifies all the error conditions and handling semantics.
For example, specifying the same buffer with intersecting ranges in both "source" and "destination"
of copyBufferToBuffer()
results in GPUCommandEncoder
generating an error, and no other operation occurring.
See § 21 Errors & Debugging for more information about error handling.
2.1.2. GPU-based undefined behavior
WebGPU shaders are executed by the compute units inside GPU hardware. In native APIs,
some of the shader instructions may result in undefined behavior on the GPU.
In order to address that, the shader instruction set and its defined behaviors are
strictly defined by WebGPU. When a shader is provided to createShaderModule()
,
the WebGPU implementation has to validate it
before doing any translation (to platform-specific shaders) or transformation passes.
2.1.3. Uninitialized data
Generally, allocating new memory may expose the leftover data of other applications running on the system. In order to address that, WebGPU conceptually initializes all the resources to zero, although in practice an implementation may skip this step if it sees the developer initializing the contents manually. This includes variables and shared workgroup memory inside shaders.
The precise mechanism of clearing the workgroup memory can differ between platforms. If the native API does not provide facilities to clear it, the WebGPU implementation transforms the compute shader to first do a clear across all invocations, synchronize them, and continue executing developer’s code.
GPULoadOp
"load"
to "clear"
).
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.
2.1.4. Out-of-bounds access in shaders
Shaders can access physical resources either directly
(for example, as a "uniform"
GPUBufferBinding
), or via texture units,
which are fixed-function hardware blocks that handle texture coordinate conversions.
Validation on the API side can only guarantee that all the inputs to the shader are provided and
they have the correct usage and types.
The host API side can not guarantee that the data is accessed within bounds
if the texture units are not involved.
define the host API distinct from the shader API
In order to prevent the shaders from accessing GPU memory an application doesn’t own, the WebGPU implementation may enable a special mode (called "robust buffer access") in the driver that guarantees that the access is limited to buffer bounds.
Alternatively, an implementation may transform the shader code by inserting manual bounds checks.
When this path is taken, the out-of-bound checks only apply to array indexing. They aren’t needed
for plain field access of shader structures due to the minBindingSize
validation on the host side.
If the shader attempts to load data outside of physical resource bounds, the implementation is allowed to:
-
return a value at a different location within the resource bounds
-
return a value vector of "(0, 0, 0, X)" with any "X"
-
partially discard the draw or dispatch call
If the shader attempts to write data outside of physical resource bounds, the implementation is allowed to:
-
write the value to a different location within the resource bounds
-
discard the write operation
-
partially discard the draw or dispatch call
2.1.5. Invalid data
When uploading floating-point data from CPU to GPU, or generating it on the GPU, we may end up with a binary representation that doesn’t correspond to a valid number, such as infinity or NaN (not-a-number). The GPU behavior in this case is subject to the accuracy of the GPU hardware implementation of the IEEE-754 standard. WebGPU guarantees that introducing invalid floating-point numbers would only affect the results of arithmetic computations and will not have other side effects.
2.1.6. Driver bugs
GPU drivers are subject to bugs like any other software. If a bug occurs, an attacker could possibly exploit the incorrect behavior of the driver to get access to unprivileged data. In order to reduce the risk, the WebGPU working group will coordinate with GPU vendors to integrate the WebGPU Conformance Test Suite (CTS) as part of their driver testing process, like it was done for WebGL. WebGPU implementations are expected to have workarounds for some of the discovered bugs, and disable WebGPU on drivers with known bugs that can’t be worked around.
2.1.7. Timing attacks
WebGPU is designed to later support multi-threaded use via Web Workers. As such, it is designed not to open
the users to modern high-precision timing attacks. Some of the objects,
like GPUBuffer
or GPUQueue
, have shared state which can be simultaneously accessed.
This allows race conditions to occur, similar to those of accessing a SharedArrayBuffer
from multiple Web Workers, which makes the thread scheduling observable.
WebGPU addresses this by limiting the ability to deserialize (or share) objects only to
the agents inside the agent cluster, and only if
the cross-origin isolated policies are in place.
This restriction matches the mitigations against the malicious SharedArrayBuffer
use. Similarly, the user agent may also
serialize the agents sharing any handles to prevent any concurrency entirely.
In the end, the attack surface for races on shared state in WebGPU will be
a small subset of the SharedArrayBuffer
attacks.
WebGPU also specifies the "timestamp-query"
feature, which
provides high precision timing of GPU operations. The feature is optional, and a WebGPU
implementation may limit its exposure only to those scenarios that are trusted. Alternatively,
the timing query results could be processed by a compute shader and aligned to a lower precision.
2.1.8. Row hammer attacks
Row hammer is a class of attacks that exploit the leaking of states in DRAM cells. It could be used on GPU. WebGPU does not have any specific mitigations in place, and relies on platform-level solutions, such as reduced memory refresh intervals.
2.1.9. Denial of service
WebGPU applications have access to GPU memory and compute units. A WebGPU implementation may limit the available GPU memory to an application, in order to keep other applications responsive. For GPU processing time, a WebGPU implementation may set up "watchdog" timer that makes sure an application doesn’t cause GPU unresponsiveness for more than a few seconds. These measures are similar to those used in WebGL.
2.1.10. Workload identification
WebGPU provides access to constrained global resources shared between different programs (and web pages) running on the same machine. An application can try to indirectly probe how constrained these global resources are, in order to reason about workloads performed by other open web pages, based on the patterns of usage of these shared resources. These issues are generally analogous to issues with Javascript, such as system memory and CPU execution throughput. WebGPU does not provide any additional mitigations for this.
2.1.11. Memory resources
WebGPU exposes fallible allocations from machine-global memory heaps, such as VRAM. This allows for probing the size of the system’s remaining available memory (for a given heap type) by attempting to allocate and watching for allocation failures.
GPUs internally have one or more (typically only two) heaps of memory shared by all running applications. When a heap is depleted, WebGPU would fail to create a resource. This is observable, which may allow a malicious application to guess what heaps are used by other applications, and how much they allocate from them.
2.1.12. Computation resources
If one site uses WebGPU at the same time as another, it may observe the increase in time it takes to process some work. For example, if a site constantly submits compute workloads and tracks completion of work on the queue, it may observe that something else also started using the GPU.
A GPU has many parts that can be tested independently, such as the arithmetic units, texture sampling units, atomic units, etc. A malicious application may sense when some of these units are stressed, and attempt to guess the workload of another application by analyzing the stress patterns. This is analogous to the realities of CPU execution of Javascript.
2.1.13. Abuse of capabilities
Malicious sites could abuse the capabilities exposed by WebGPU to run computations that don’t benefit the user or their experience and instead only benefit the site. Examples would be hidden crypto-mining, password cracking or rainbow tables computations.
It is not possible to guard against these types of uses of the API because the browser is not able to distinguish between valid workloads and abusive workloads. This is a general problem with all general-purpose computation capabilities on the Web: JavaScript, WebAssembly or WebGL. WebGPU only makes some workloads easier to implement, or slightly more efficient to run than using WebGL.
To mitigate this form of abuse, browsers can throttle operations on background tabs, could warn that a tab is using a lot of resource, and restrict which contexts are allowed to use WebGPU.
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.
Update this section with iframe-control defaulting to "self" being a mitigation against this issue since only the top level origin (that is a bit more trusted since the user navigated to it, or is staying on it).
2.2. Privacy Considerations
The privacy considerations for WebGPU are similar to those of WebGL. GPU APIs are complex and must expose various aspects of a device’s capabilities out of necessity in order to enable developers to take advantage of those capabilities effectively. The general mitigation approach involves normalizing or binning potentially identifying information and enforcing uniform behavior where possible.
2.2.1. Machine-specific limits
WebGPU can expose a lot of detail on the underlying GPU architecture and the device geometry. This includes available physical adapters, many limits on the GPU and CPU resources that could be used (such as the maximum texture size), and any optional hardware-specific capabilities that are available.
User agents are not obligated to expose the real hardware limits, they are in full control of how much the machine specifics are exposed. One strategy to reduce fingerprinting is binning all the target platforms into a few number of bins. In general, the privacy impact of exposing the hardware limits matches the one of WebGL.
The default limits are also deliberately high enough to allow most applications to work without requesting higher limits. All the usage of the API is validated according to the requested limits, so the actual hardware capabilities are not exposed to the users by accident.
2.2.2. Machine-specific artifacts
There are some machine-specific rasterization/precision artifacts and performance differences that can be observed roughly in the same way as in WebGL. This applies to rasterization coverage and patterns, interpolation precision of the varyings between shader stages, compute unit scheduling, and more aspects of execution.
Generally, rasterization and precision fingerprints are identical across most or all of the devices of each vendor. Performance differences are relatively intractable, but also relatively low-signal (as with JS execution performance).
Privacy-critical applications and user agents should utilize software implementations to eliminate such artifacts.
2.2.3. Machine-specific performance
Another factor for differentiating users is measuring the performance of specific operations on the GPU. Even with low precision timing, repeated execution of an operation can show if the user’s machine is fast at specific workloads. This is a fairly common vector (present in both WebGL and Javascript), but it’s also low-signal and relatively intractable to truly normalize.
WebGPU compute pipelines expose access to GPU unobstructed by the fixed-function hardware. This poses an additional risk for unique device fingerprinting. User agents can take steps to dissociate logical GPU invocations with actual compute units to reduce this risk.
2.2.4. User Agent State
This specification doesn’t define any additional user-agent state for an origin.
However it is expected that user agents will have compilation caches for the result of expensive
compilation like GPUShaderModule
, GPURenderPipeline
and GPUComputePipeline
.
These caches are important to improve the loading time of WebGPU applications after the first
visit.
For the specification, these caches are indifferentiable from incredibly fast compilation, but
for applications it would be easy to measure how long createComputePipelineAsync()
takes to resolve. This can leak information across origins (like "did the user access a site with
this specific shader") so user agents should follow the best practices in storage partitioning.
The system’s GPU driver may also have its own cache of compiled shaders and pipelines. User agents may want to disable these when at all possible, or add per-partition data to shaders in ways that will make the GPU driver consider them different.
2.2.5. Driver bugs
In addition to the concerns outlined in Security Considerations, driver bugs may introduce differences in behavior that can be observed as a method of differentiating users. The mitigations mentioned in Security Considerations apply here as well, including coordinating with GPU vendors and implementing workarounds for known issues in the user agent.
2.2.6. Adapter Identifiers
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.
3. Fundamentals
3.1. Conventions
3.1.1. Syntactic Shorthands
In this specification, the following syntactic shorthands are used:
- The
.
("dot") syntax, common in programming languages. -
The phrasing "
Foo.Bar
" means "theBar
member of the value (or interface)Foo
." - The
?.
("optional chaining") syntax, adopted from JavaScript. -
The phrasing "
Foo?.Bar
" means "ifFoo
isnull
orundefined
,undefined
; otherwise,Foo.Bar
".For example, where
buffer
is aGPUBuffer
,buffer?.[[device]].[[adapter]]
means "ifbuffer
isnull
orundefined
, thenundefined
; otherwise, the[[adapter]]
internal slot of the[[device]]
internal slot ofbuffer
. - The
??
("nullish coalescing") syntax, adopted from JavaScript. -
The phrasing "
x
??y
" means "x
, ifx
is not null/undefined, andy
otherwise".
3.1.2. Internal Objects
An internal object is a conceptual, non-exposed WebGPU object. Internal objects track the state of an API object and hold any underlying implementation. If the state of a particular internal object can change in parallel from multiple agents, those changes are always atomic with respect to all agents.
Note: An "agent" refers to a JavaScript "thread" (i.e. main thread, or Web Worker).
3.1.3. WebGPU Interfaces
A WebGPU interface is an exposed interface which encapsulates an internal object. It provides the interface through which the internal object's state is changed.
Any interface which includes GPUObjectBase
is a WebGPU interface.
interface mixin {
GPUObjectBase attribute USVString label ; };
GPUObjectBase
has the following attributes:
label
, of type USVString-
Initially the empty string.
A developer-provided label which 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 error/warning messages, browser developer tools, and platform debugging utilities. The user agent is free to choose if and how it will use this label.
Note:
label
is defined as aUSVString
because some user agents may supply it to the debug facilities of the underlying native APIs.
GPUObjectBase
has the following internal slots:
[[device]]
, of type device, readonly-
An internal slot holding the device which owns the internal object.
[[device]]
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.
3.1.4. Object Descriptors
An object descriptor holds the information needed to create an object,
which is typically done via one of the create*
methods of GPUDevice
.
dictionary {
GPUObjectDescriptorBase USVString label ; };
GPUObjectDescriptorBase
has the following members:
label
, of type USVString-
The initial value of
GPUObjectBase.label
.
3.2. Invalid Internal Objects & Contagious Invalidity
Object creation operations in WebGPU are internally asynchronous, so they don’t fail with exceptions. Instead, returned objects may refer to internal objects which are either valid or invalid. An invalid object may never become valid at a later time. Some objects may become invalid during their lifetime, while most may only be invalid from creation.
Objects are invalid from creation if it wasn’t possible to create them. This can happen, for example, if the object descriptor doesn’t describe a valid object, or if there is not enough memory to allocate a resource.
Internal objects of most types cannot become invalid after they are created, but still
may become unusable, e.g. if the owning device is lost or destroyed
, or the object has a special internal state,
like buffer state "destroyed".
Internal objects of some types can become invalid after they are created; specifically, devices, adapters, GPUCommandBuffer
s, and command/pass/bundle encoders.
GPUObjectBase
object is valid to use with a targetObject if and only if the following requirements are met:
-
object must be valid.
-
object.
[[device]]
must be valid. -
object.
[[device]]
must equal targetObject.[[device]]
.
3.3. Coordinate Systems
-
Y-axis is up in normalized device coordinate (NDC): point(-1.0, -1.0) in NDC is located at the bottom-left corner of NDC. In addition, x and y in NDC should be between -1.0 and 1.0 inclusive, while z in NDC should be between 0.0 and 1.0 inclusive. Vertices out of this range in NDC will not introduce any errors, but they will be clipped.
-
Y-axis is down in framebuffer coordinate, viewport coordinate and fragment/pixel coordinate: origin(0, 0) is located at the top-left corner in these coordinate systems.
-
Window/present coordinate matches framebuffer coordinate.
-
UV of origin(0, 0) in texture coordinate represents the first texel (the lowest byte) in texture memory.
Note: WebGPU’s coordinate systems match DirectX’s coordinate systems in a graphics pipeline.
3.4. Programming Model
3.4.1. Timelines
This section is non-normative.
A computer system with a user agent at the front-end and GPU at the back-end has components working on different timelines in parallel:
- Content timeline
-
Associated with the execution of the Web script. It includes calling all methods described by this specification.
- Device timeline
-
Associated with the GPU device operations that are issued by the user agent. It includes creation of adapters, devices, and GPU resources and state objects, which are typically synchronous operations from the point of view of the user agent part that controls the GPU, but can live in a separate OS process.
- Queue timeline
-
Associated with the execution of operations on the compute units of the GPU. It includes actual draw, copy, and compute jobs that run on the GPU.
In this specification, asynchronous operations are used when the result value depends on work that happens on any timeline other than the Content timeline. They are represented by callbacks and promises in JavaScript.
GPUComputePassEncoder.dispatchWorkgroups()
:
-
User encodes a
dispatchWorkgroups
command by calling a method of theGPUComputePassEncoder
which happens on the Content timeline. -
User issues
GPUQueue.submit()
that hands over theGPUCommandBuffer
to the user agent, which processes it on the Device timeline by calling the OS driver to do a low-level submission. -
The submit gets dispatched by the GPU invocation scheduler onto the actual compute units for execution, which happens on the Queue timeline.
GPUDevice.createBuffer()
:
-
User fills out a
GPUBufferDescriptor
and creates aGPUBuffer
with it, which happens on the Content timeline. -
User agent creates a low-level buffer on the Device timeline.
GPUBuffer.mapAsync()
:
-
User requests to map a
GPUBuffer
on the Content timeline and gets a promise in return. -
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.
-
After the GPU operating on Queue timeline is done using the buffer, the user agent maps it to memory and resolves the promise.
3.4.2. Memory Model
This section is non-normative.
Once a GPUDevice
has been obtained during an application initialization routine,
we can describe the WebGPU platform as consisting of the following layers:
-
User agent implementing the specification.
-
Operating system with low-level native API drivers for this device.
-
Actual CPU and GPU hardware.
Each layer of the WebGPU platform may have different memory types that the user agent needs to consider when implementing the specification:
-
The script-owned memory, such as an
ArrayBuffer
created by the script, is generally not accessible by a GPU driver. -
A user agent may have different processes responsible for running the content and communication to the GPU driver. In this case, it uses inter-process shared memory to transfer data.
-
Dedicated GPUs have their own memory with high bandwidth, while integrated GPUs typically share memory with the system.
Most physical resources are allocated in the memory of type that is efficient for computation or rendering by the GPU. When the user needs to provide new data to the GPU, the data may first need to cross the process boundary in order to reach the user agent part that communicates with the GPU driver. Then it may need to be made visible to the driver, which sometimes requires a copy into driver-allocated staging memory. Finally, it may need to be transferred to the dedicated GPU memory, potentially changing the internal layout into one that is most efficient for GPUs to operate on.
All of these transitions are done by the WebGPU implementation of the user agent.
Note: This example describes the worst case, while in practice
the implementation may not need to cross the process boundary,
or may be able to expose the driver-managed memory directly to
the user behind an ArrayBuffer
, thus avoiding any data copies.
3.4.3. Resource Usages
A physical resource can be used on GPU with an internal usage:
- input
-
Buffer with input data for draw or dispatch calls. Preserves the contents. Allowed by buffer
INDEX
, bufferVERTEX
, or bufferINDIRECT
. - constant
-
Resource bindings that are constant from the shader point of view. Preserves the contents. Allowed by buffer
UNIFORM
or textureTEXTURE_BINDING
. - storage
-
Writable storage resource binding. Allowed by buffer
STORAGE
or textureSTORAGE_BINDING
. - storage-read
-
Read-only storage resource bindings. Preserves the contents. Allowed by buffer
STORAGE
. - attachment
-
Texture used as an output attachment in a render pass. Allowed by texture
RENDER_ATTACHMENT
. - attachment-read
-
Texture used as a read-only attachment in a render pass. Preserves the contents. Allowed by texture
RENDER_ATTACHMENT
.
Textures may consist of separate mipmap levels and array layers,
which can be used differently at any given time.
Each such texture subresource is uniquely identified by a texture, mipmap level, and
(for 2d
textures only) array layer,
and aspect.
We define subresource to be either a whole buffer, or a texture subresource.
-
Each usage in U is input, constant, storage-read, or attachment-read.
-
Each usage in U is storage.
-
U contains exactly one element: attachment.
Enforcing that the usages are only combined into a compatible usage list allows the API to limit when data races can occur in working with memory. That property makes applications written against WebGPU more likely to run without modification on different platforms.
Generally, when an implementation processes an operation that uses a subresource in a different way than its current usage allows, it schedules a transition of the resource
into the new state. In some cases, like within an open GPURenderPassEncoder
, such a
transition is impossible due to the hardware limitations.
We define these places as usage scopes.
The main usage rule is, for any one subresource, its list of internal usages within one usage scope must be a compatible usage list.
For example, binding the same buffer for storage as well as for input within the same GPURenderPassEncoder
would put the encoder
as well as the owning GPUCommandEncoder
into the error state.
This combination of usages does not make a compatible usage list.
Note: race condition of multiple writable storage buffer/texture usages in a single usage scope is allowed.
The subresources of textures included in the views provided to GPURenderPassColorAttachment.view
and GPURenderPassColorAttachment.resolveTarget
are considered to be used as attachment for the usage scope of this render pass.
The logical miplevel-specific texture extent of a texture is the size of the texture in texels at a specific miplevel. It is calculated by this procedure:
Arguments:
-
GPUTextureDescriptor
descriptor -
GPUSize32
mipLevel
Returns: GPUExtent3DDict
-
Let extent be a new
GPUExtent3DDict
object. -
If descriptor.
dimension
is:"1d"
-
-
Set extent.
width
to max(1, descriptor.size
.width ≫ mipLevel). -
Set extent.
height
to 1. -
Set extent.
depthOrArrayLayers
to descriptor.size
.depthOrArrayLayers.
-
"2d"
-
-
Set extent.
width
to max(1, descriptor.size
.width ≫ mipLevel). -
Set extent.
height
to max(1, descriptor.size
.height ≫ mipLevel). -
Set extent.
depthOrArrayLayers
to descriptor.size
.depthOrArrayLayers.
-
"3d"
-
-
Set extent.
width
to max(1, descriptor.size
.width ≫ mipLevel). -
Set extent.
height
to max(1, descriptor.size
.height ≫ mipLevel). -
Set extent.
depthOrArrayLayers
to max(1, descriptor.size
.depthOrArrayLayers ≫ mipLevel).
-
-
Return extent.
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:
Arguments:
-
GPUTextureDescriptor
descriptor -
GPUSize32
mipLevel
Returns: GPUExtent3DDict
-
Let extent be a new
GPUExtent3DDict
object. -
Let logicalExtent be logical miplevel-specific texture extent(descriptor, mipLevel).
-
If descriptor.
dimension
is:"1d"
-
-
Set extent.
width
to logicalExtent.width rounded up to the nearest multiple of descriptor’s texel block width. -
Set extent.
height
to 1. -
Set extent.
depthOrArrayLayers
to logicalExtent.depthOrArrayLayers.
-
"2d"
-
-
Set extent.
width
to logicalExtent.width rounded up to the nearest multiple of descriptor’s texel block width. -
Set extent.
height
to logicalExtent.height rounded up to the nearest multiple of descriptor’s texel block height. -
Set extent.
depthOrArrayLayers
to logicalExtent.depthOrArrayLayers.
-
"3d"
-
-
Set extent.
width
to logicalExtent.width rounded up to the nearest multiple of descriptor’s texel block width. -
Set extent.
height
to logicalExtent.height rounded up to the nearest multiple of descriptor’s texel block height. -
Set extent.
depthOrArrayLayers
to logicalExtent.depthOrArrayLayers.
-
-
Return extent.
3.4.4. Synchronization
For each subresource of a physical resource, its set of internal usage flags is tracked on the Queue timeline.
This section will need to be revised to support multiple queues.
On the Queue timeline, there is an ordered sequence of usage scopes. For the duration of each scope, the set of internal usage flags of any given subresource is constant. A subresource may transition to new usages at the boundaries between usage scopes.
This specification defines the following usage scopes:
-
Outside of a pass (in
GPUCommandEncoder
), each (non-state-setting) command is one usage scope (e.g.copyBufferToTexture()
). -
In a compute pass, each dispatch command (
dispatchWorkgroups()
ordispatchWorkgroupsIndirect()
) is one usage scope. A subresource is "used" in the usage scope if it is potentially accessible by the command. Within a dispatch, for each bind group slot that is used by the currentGPUComputePipeline
's[[layout]]
, every subresource referenced by that bind group is "used" in the usage scope. State-setting compute pass commands, likesetBindGroup(index, bindGroup, dynamicOffsets)
, do not contribute directly to a usage scope; they instead change the state that is checked in dispatch commands. -
One render pass is one usage scope. A subresource is "used" in the usage scope if it’s referenced by any (state-setting or non-state-setting) command. For example, in
setBindGroup(index, bindGroup, dynamicOffsets)
, every subresource inbindGroup
is "used" in the render pass’s usage scope.
The above should probably talk about GPU commands. But we don’t have a way to reference specific GPU commands (like dispatch) yet.
-
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 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 this buffer is shadowed by another 'set' call. -
A texture subresource used as a color attachment, resolve attachment, or depth/stencil attachment in
GPURenderPassDescriptor
bybeginRenderPass()
, 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).
During command encoding, every usage of a subresource is recorded in one of the usage scopes in the command buffer.
For each usage scope, the implementation performs usage scope validation by composing the list of all internal usage flags of each subresource used in the usage scope.
If any of those lists is not a compatible usage list, GPUCommandEncoder.finish()
will generate a validation error.
3.5. Core Internal Objects
3.5.1. Adapters
An adapter identifies an implementation of WebGPU on the system: both an instance of compute/rendering functionality on the platform underlying a browser, and an instance of a browser’s implementation of WebGPU on top of that functionality.
Adapters do not uniquely represent underlying implementations:
calling requestAdapter()
multiple times returns a different adapter object each time.
An adapter object may become invalid at any time. This happens inside "lose the device" and "mark adapters stale". An invalid adapter is unable to vend new devices.
Note: This mechanism ensures that various adapter-creation scenarios look similar to applications,
so they can easily be robust to more scenarios with less testing: first initialization,
reinitialization due to an unplugged adapter, reinitialization due to a test GPUDevice.destroy()
call, etc. It also ensures applications use
the latest system state to make decisions about which adapter to use.
An adapter may be considered a fallback adapter if it has significant performance caveats in exchange for some combination of wider compatibility, more predictable behavior, or improved privacy. It is not required that a fallback adapter is available on every system.
An adapter has the following internal slots:
[[features]]
, of type ordered set<GPUFeatureName
>, readonly-
The features which can be used to create devices on this adapter.
[[limits]]
, of type supported limits, readonly-
The best limits which can be used to create devices on this adapter.
Each adapter limit must be the same or better than its default value in supported limits.
[[fallback]]
, of type boolean-
If set to
true
indicates that the adapter is a fallback adapter. [[unmaskedIdentifiers]]
, of type ordered set<DOMString
>-
A list of names of
GPUAdapterInfo
fields the user agent has chosen to report for this adapter. Initially populated with the names of anyGPUAdapterInfo
fields the user agent has chosen to report without user consent.
Adapters are exposed via GPUAdapter
.
3.5.2. Devices
A device is the logical instantiation of an adapter, through which internal objects are created. It can be shared across multiple agents (e.g. dedicated workers).
A device is the exclusive owner of all internal objects created from it:
when the device is lost or destroyed
,
it and all objects created on it (directly, e.g. createTexture()
, or indirectly, e.g. createView()
) become
implicitly unusable.
A device has the following internal slots:
[[adapter]]
, of type adapter, readonly-
The adapter from which this device was created.
[[features]]
, of type ordered set<GPUFeatureName
>, readonly-
The features which can be used on this device. No additional features can be used, even if the underlying adapter can support them.
[[limits]]
, of type supported limits, readonly-
The limits which can be used on this device. No better limits can be used, even if the underlying adapter can support them.
GPUDeviceDescriptor
descriptor:
-
Set device.
[[adapter]]
to adapter. -
Set device.
[[features]]
to the set of values in descriptor.requiredFeatures
. -
Let device.
[[limits]]
be a supported limits object with the default values. For each (key, value) pair in descriptor.requiredLimits
, set the member corresponding to key in device.[[limits]]
to the better value of value or the default value in supported limits.
Any time the user agent needs to revoke access to a device, it calls lose the device(device, undefined
).
-
Make device.
[[adapter]]
invalid. -
Make device invalid.
-
explain how to get from device to its "primary"
GPUDevice
. -
Resolve device.
lost
with a newGPUDeviceLostInfo
withreason
set to reason andmessage
set to an implementation-defined value.Note:
message
should not disclose unnecessary user/system information and should never be parsed by applications.
Devices are exposed via GPUDevice
.
3.6. Optional Capabilities
WebGPU adapters and devices have capabilities, which describe WebGPU functionality that differs between different implementations, typically due to hardware or system software constraints. A capability is either a feature or a limit.
3.6.1. Features
A feature is a set of optional WebGPU functionality that is not supported on all implementations, typically due to hardware or system software constraints.
Each GPUAdapter
exposes a set of available features.
Only those features may be requested in requestDevice()
.
Functionality that is part of a feature may only be used if the feature was requested at device creation. Dictionary members added to existing dictionaries by optional features are always optional at the WebIDL level; if the feature is not enabled, such members must not be set to non-default values.
Note: Though enabling a feature won’t add new IDL-required fields, it may not necessarily be backward-compatible with existing code. An optional feature can enable new validation which invalidates previously-valid code.
See the Feature Index for a description of the functionality each feature enables.
3.6.2. Limits
Each limit is a numeric limit on the usage of WebGPU on a device.
A supported limits object has a value for every defined limit.
Each adapter has a set of supported limits, and devices are created
with specific supported limits in place.
The device limits are enforced regardless of the adapter’s limits.
Each limit has a default value.
Every adapter is guaranteed to support the default value or better.
The default is used if a value is not explicitly specified in requiredLimits
.
One limit value may be better than another. A better limit value always relaxes validation, enabling strictly more programs to be valid. For each limit class, "better" is defined.
Different limits have different limit classes:
- maximum
-
The limit enforces a maximum on some value passed into the API.
Higher values are better.
May only be set to values ≥ the default. Lower values are clamped to the default.
- alignment
-
The limit enforces a minimum alignment on some value passed into the API; that is, the value must be a multiple of the limit.
Lower values are better.
May only be set to powers of 2 which are ≤ the default. Values which are not powers of 2 are invalid. Higher powers of 2 are clamped to the default.
Note: Setting "better" limits may not necessarily be desirable, as they may have a performance impact. Because of this, and to improve portability across devices and implementations, applications should generally request the "worst" limits that work for their content (ideally, the default values).
Limit name | Type | Limit class | Default |
---|---|---|---|
maxTextureDimension1D
| GPUSize32
| maximum | 8192 |
The maximum allowed value for the size .width of a texture created with dimension "1d" .
| |||
maxTextureDimension2D
| GPUSize32
| maximum | 8192 |
The maximum allowed value for the size .width and size .height of a texture created with dimension "2d" .
| |||
maxTextureDimension3D
| GPUSize32
| maximum | 2048 |
The maximum allowed value for the size .width, size .height and size .depthOrArrayLayers of a texture created with dimension "3d" .
| |||
maxTextureArrayLayers
| GPUSize32
| maximum | 256 |
The maximum allowed value for the size .depthOrArrayLayers of a texture created with dimension "1d" or "2d" .
| |||
maxBindGroups
| GPUSize32
| maximum | 4 |
The maximum number of GPUBindGroupLayouts allowed in bindGroupLayouts when creating a GPUPipelineLayout .
| |||
maxDynamicUniformBuffersPerPipelineLayout
| GPUSize32
| maximum | 8 |
The maximum number of GPUBindGroupLayoutEntry entries across a GPUPipelineLayout which are uniform buffers with dynamic offsets.
See Exceeds the binding slot limits.
| |||
maxDynamicStorageBuffersPerPipelineLayout
| GPUSize32
| maximum | 4 |
The maximum number of GPUBindGroupLayoutEntry entries across a GPUPipelineLayout which are storage buffers with dynamic offsets.
See Exceeds the binding slot limits.
| |||
maxSampledTexturesPerShaderStage
| GPUSize32
| maximum | 16 |
For each possible GPUShaderStage stage ,
the maximum number of GPUBindGroupLayoutEntry entries across a GPUPipelineLayout which are sampled textures.
See Exceeds the binding slot limits.
| |||
maxSamplersPerShaderStage
| GPUSize32
| maximum | 16 |
For each possible GPUShaderStage stage ,
the maximum number of GPUBindGroupLayoutEntry entries across a GPUPipelineLayout which are samplers.
See Exceeds the binding slot limits.
| |||
maxStorageBuffersPerShaderStage
| GPUSize32
| maximum | 8 |
For each possible GPUShaderStage stage ,
the maximum number of GPUBindGroupLayoutEntry entries across a GPUPipelineLayout which are storage buffers.
See Exceeds the binding slot limits.
| |||
maxStorageTexturesPerShaderStage
| GPUSize32
| maximum | 4 |
For each possible GPUShaderStage stage ,
the maximum number of GPUBindGroupLayoutEntry entries across a GPUPipelineLayout which are storage textures.
See Exceeds the binding slot limits.
| |||
maxUniformBuffersPerShaderStage
| GPUSize32
| maximum | 12 |
For each possible GPUShaderStage stage ,
the maximum number of GPUBindGroupLayoutEntry entries across a GPUPipelineLayout which are uniform buffers.
See Exceeds the binding slot limits.
| |||
maxUniformBufferBindingSize
| GPUSize64
| maximum | 65536 bytes |
The maximum GPUBufferBinding .size for bindings with a GPUBindGroupLayoutEntry entry for which entry.buffer ?.type is "uniform" .
| |||
maxStorageBufferBindingSize
| GPUSize64
| maximum | 134217728 bytes (128 MiB) |
The maximum GPUBufferBinding .size for bindings with a GPUBindGroupLayoutEntry entry for which entry.buffer ?.type is "storage" or "read-only-storage" .
| |||
minUniformBufferOffsetAlignment
| GPUSize32
| alignment | 256 bytes |
The required alignment for GPUBufferBinding .offset and setBindGroup dynamicOffsets arguments for binding with a GPUBindGroupLayoutEntry entry for which entry.buffer ?.type is "uniform" .
Implementations must not support values less than 32 bytes. Note: 32 bytes would be the alignment of | |||
minStorageBufferOffsetAlignment
| GPUSize32
| alignment | 256 bytes |
The required alignment for GPUBufferBinding .offset and setBindGroup dynamicOffsets arguments for binding with a GPUBindGroupLayoutEntry entry for which entry.buffer ?.type is "storage" or "read-only-storage" .
Implementations must not support values less than 32 bytes. Note: 32 bytes would be the alignment of | |||
maxVertexBuffers
| GPUSize32
| maximum | 8 |
The maximum number of buffers when creating a GPURenderPipeline .
| |||
maxVertexAttributes
| GPUSize32
| maximum | 16 |
The maximum number of attributes in total across buffers when creating a GPURenderPipeline .
| |||
maxVertexBufferArrayStride
| GPUSize32
| maximum | 2048 bytes |
The maximum allowed arrayStride when creating a GPURenderPipeline .
| |||
maxInterStageShaderComponents
| GPUSize32
| maximum | 60 |
The maximum allowed number of components of input or output variables for inter-stage communication (like vertex outputs or fragment inputs). | |||
maxInterStageShaderVariables
| GPUSize32
| maximum | 16 |
The maximum allowed number of input or output variables for inter-stage communication (like vertex outputs or fragment inputs). | |||
maxColorAttachments
| GPUSize32
| maximum | 8 |
The maximum allowed number of color attachments in GPURenderPipelineDescriptor .fragment .targets , GPURenderPassDescriptor .colorAttachments ,
and GPURenderPassLayout .colorFormats .
| |||
maxComputeWorkgroupStorageSize
| GPUSize32
| maximum | 16384 bytes |
The maximum number of bytes used for a compute stage GPUShaderModule entry-point.
| |||
maxComputeInvocationsPerWorkgroup
| GPUSize32
| maximum | 256 |
The maximum value of the product of the workgroup_size dimensions for a
compute stage GPUShaderModule entry-point.
| |||
maxComputeWorkgroupSizeX
| GPUSize32
| maximum | 256 |
The maximum value of the workgroup_size X dimension for a
compute stage GPUShaderModule entry-point.
| |||
maxComputeWorkgroupSizeY
| GPUSize32
| maximum | 256 |
The maximum value of the workgroup_size Y dimensions for a
compute stage GPUShaderModule entry-point.
| |||
maxComputeWorkgroupSizeZ
| GPUSize32
| maximum | 64 |
The maximum value of the workgroup_size Z dimensions for a
compute stage GPUShaderModule entry-point.
| |||
maxComputeWorkgroupsPerDimension
| GPUSize32
| maximum | 65535 |
The maximum value for the arguments of dispatchWorkgroups(workgroupCountX, workgroupCountY, workgroupCountZ) .
|
Do we need to have a max per-pixel render target size?
3.6.2.1. GPUSupportedLimits
GPUSupportedLimits
exposes the limits supported by an adapter or device.
See GPUAdapter.limits
and GPUDevice.limits
.
[Exposed =(Window ,DedicatedWorker ),SecureContext ]interface GPUSupportedLimits {readonly attribute unsigned long ;
maxTextureDimension1D readonly attribute unsigned long ;
maxTextureDimension2D readonly attribute unsigned long ;
maxTextureDimension3D readonly attribute unsigned long ;
maxTextureArrayLayers readonly attribute unsigned long ;
maxBindGroups readonly attribute unsigned long ;
maxDynamicUniformBuffersPerPipelineLayout readonly attribute unsigned long ;
maxDynamicStorageBuffersPerPipelineLayout readonly attribute unsigned long ;
maxSampledTexturesPerShaderStage readonly attribute unsigned long ;
maxSamplersPerShaderStage readonly attribute unsigned long ;
maxStorageBuffersPerShaderStage readonly attribute unsigned long ;
maxStorageTexturesPerShaderStage readonly attribute unsigned long ;
maxUniformBuffersPerShaderStage readonly attribute unsigned long long ;
maxUniformBufferBindingSize readonly attribute unsigned long long ;
maxStorageBufferBindingSize readonly attribute unsigned long ;
minUniformBufferOffsetAlignment readonly attribute unsigned long ;
minStorageBufferOffsetAlignment readonly attribute unsigned long ;
maxVertexBuffers readonly attribute unsigned long ;
maxVertexAttributes readonly attribute unsigned long ;
maxVertexBufferArrayStride readonly attribute unsigned long ;
maxInterStageShaderComponents readonly attribute unsigned long ;
maxInterStageShaderVariables readonly attribute unsigned long ;
maxColorAttachments readonly attribute unsigned long ;
maxComputeWorkgroupStorageSize readonly attribute unsigned long ;
maxComputeInvocationsPerWorkgroup readonly attribute unsigned long ;
maxComputeWorkgroupSizeX readonly attribute unsigned long ;
maxComputeWorkgroupSizeY readonly attribute unsigned long ;
maxComputeWorkgroupSizeZ readonly attribute unsigned long ; };
maxComputeWorkgroupsPerDimension
3.6.2.2. GPUSupportedFeatures
GPUSupportedFeatures
is a setlike interface. Its set entries are
the GPUFeatureName
values of the features supported by an adapter or
device. It must only contain strings from the GPUFeatureName
enum.
[Exposed =(Window ,DedicatedWorker ),SecureContext ]interface GPUSupportedFeatures {readonly setlike <DOMString >; };
GPUSupportedFeatures
set entries is DOMString
to allow user
agents to gracefully handle valid GPUFeatureName
s which are added in later revisions of the spec
but which the user agent has not been updated to recognize yet. If the set entries type was GPUFeatureName
the following code would throw an TypeError
rather than reporting false
:
3.6.2.3. GPUAdapterInfo
GPUAdapterInfo
exposes various identifying information about an adapter.
None of the members in GPUAdapterInfo
are guaranteed to be populated. 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.
[Exposed =(Window ,DedicatedWorker ),SecureContext ]interface GPUAdapterInfo {readonly attribute DOMString vendor ;readonly attribute DOMString architecture ;readonly attribute DOMString device ;readonly attribute DOMString description ; };
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 theGPUAdapterInfo
, such as applying workarounds for known driver issues, should rely on the other fields when possible.
-
Let adapterInfo be a new
GPUAdapterInfo
. -
Let unmaskedValues be adapter.
[[unmaskedIdentifiers]]
-
If unmaskedValues contains
"vendor"
and the vendor is known:-
Set adapterInfo.
vendor
to the name of adapter’s vendor as a normalized identifier string.
Otherwise:
-
Set adapterInfo.
vendor
to the empty string or a reasonable approximation of the vendor as a normalized identifier string.
-
-
If unmaskedValues contains
"architecture"
and the architecture is known:-
Set adapterInfo.
architecture
to a normalized identifier string representing the family or class of adapters to which adapter belongs.
Otherwise:
-
Set adapterInfo.
architecture
to the empty string or a reasonable approximation of the architecture as a normalized identifier string.
-
-
If unmaskedValues contains
"device"
and the device is known:-
Set adapterInfo.
device
to a normalized identifier string representing a vendor-specific identifier for adapter.
Otherwise:
-
Set adapterInfo.
device
to to the empty string or a reasonable approximation of a vendor-specific identifier as a normalized identifier string.
-
-
If unmaskedValues contains
"description"
and a description is known:-
Set adapterInfo.
description
to a description of the adapter as reported by the driver.
Otherwise:
-
Set adapterInfo.
description
to the empty string or a reasonable approximation of a description.
-
-
Return adapterInfo.
[a-z0-9]+(-[a-z0-9]+)*
3.7. Origin Restrictions
WebGPU allows accessing image data stored in images, videos, and canvases. Restrictions are imposed on the use of cross-domain media, because shaders can be used to indirectly deduce the contents of textures which have been uploaded to the GPU.
WebGPU disallows uploading an image source if it is not origin-clean.
This also implies that the origin-clean flag for a
canvas rendered using WebGPU will never be set to false
.
For more information on issuing CORS requests for image and video elements, consult:
3.8. Color Spaces and Encoding
WebGPU does not provide color management. All values within WebGPU (such as texture elements) are raw numeric values, not color-managed color values.
WebGPU does interface with color-managed outputs (via GPUCanvasConfiguration
) and inputs
(via copyExternalImageToTexture()
and importExternalTexture()
).
Thus, color conversion must be performed between the WebGPU numeric values and the external color values.
Each such interface point locally defines an encoding (color space, transfer function, and alpha
premultiplication) in which the WebGPU numeric values are to be interpreted.
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).
Consider a path for uploading srgb-encoded images into linearly-encoded textures. [Issue #gpuweb/gpuweb#1715]
A premultiplied RGBA value is super-luminant if 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) sRGB color [2, 0, 0] with alpha of 50%. 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.)
Super-luminant is a confusing term because it doesn’t really have anything to do with luminance.
3.8.1. Color Space Conversions
A color is converted between spaces by translating its representation in one space to a representation in another according to the definitions above.
If the source value has fewer than 4 RGBA channels, the missing green/blue/alpha channels are set to 0, 0, 1
respectively, as needed, before converting for color space/encoding and alpha premultiplication.
After conversion, if the destination needs fewer than 4 channels, the additional channels
are ignored.
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 super-luminant.
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.
3.8.2. Color Space Conversion Elision
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 GPUImageCopyExternalImage
:
-
-
Premultiplication is controlled via
premultiplyAlpha
. -
Color space is controlled via
colorSpaceConversion
.
-
-
2d canvas:
-
Color space is controlled via the
colorSpace
context creation attribute.
-
WebGL canvas:
-
Premultiplication is controlled via the
premultipliedAlpha
option inWebGLContextAttributes
. -
Color space is controlled via the
WebGLRenderingContext
'sdrawingBufferColorSpace
state.
-
Note: Check browser implementation support for these features before relying on them.
4. Initialization
4.1. navigator.gpu
A GPU
object is available in the Window
and DedicatedWorkerGlobalScope
contexts through the Navigator
and WorkerNavigator
interfaces respectively and is exposed via navigator.gpu
:
interface mixin { [
NavigatorGPU SameObject ,SecureContext ]readonly attribute GPU ; };
gpu Navigator includes NavigatorGPU ;WorkerNavigator includes NavigatorGPU ;
4.2. GPU
GPU
is the entry point to WebGPU.
[Exposed =(Window ,DedicatedWorker ),SecureContext ]interface GPU {Promise <GPUAdapter ?>requestAdapter (optional GPURequestAdapterOptions options = {});GPUTextureFormat getPreferredCanvasFormat (); };
GPU
has the following methods:
requestAdapter(options)
-
Requests an adapter from the user agent. The user agent chooses whether to return an adapter, and, if so, chooses according to the provided options.
Called on:GPU
this.Arguments:
Arguments for the GPU.requestAdapter(options) method. Parameter Type Nullable Optional Description options
GPURequestAdapterOptions
✘ ✔ Criteria used to select the adapter. Returns:
Promise
<GPUAdapter
?>Content timeline steps:
-
Let promise be a new promise.
-
Issue the initialization steps on the Device timeline of this.
-
Return promise.
Device timeline initialization steps:-
If the user agent chooses to return an adapter, it should:
-
Create a valid adapter adapter, chosen according to the rules in § 4.2.1 Adapter Selection and the criteria in options.
-
If adapter meets the criteria of a fallback adapter set adapter.
[[fallback]]
totrue
. -
Resolve promise with a new
GPUAdapter
encapsulating adapter.
-
-
Otherwise, promise resolves with
null
.
-
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
toconfigure()
calls on aGPUCanvasContext
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.
Called on:GPU
this.Returns:
GPUTextureFormat
Content timeline steps:
-
Return either
"rgba8unorm"
or"bgra8unorm"
, depending on which format is optimal for displaying WebGPU canvases on this system.
-
GPU
has the following internal slots:
[[previously_returned_adapters]]
, of type ordered set<adapter>-
The set of adapters that have been returned via
requestAdapter()
. It is used, then cleared, in mark adapters stale.
Upon any change in the system’s state that could affect the result of any requestAdapter()
call, the user agent should mark adapters stale. For example:
-
A physical adapter is added/removed (via plug, driver update, TDR, etc.)
-
The system’s power configuration has changed (laptop unplugged, power settings changed, etc.)
Additionally, mark adapters stale may by scheduled at any time.
User agents may choose to do this often even when there has been no system state change (e.g.
several seconds after the last call to requestDevice()
.
This has no effect on well-formed applications, obfuscates real system state changes, and makes
developers more aware that calling requestAdapter()
again is always necessary before
calling requestDevice()
.
-
For each adapter in
navigator.gpu.
[[previously_returned_adapters]]
:-
Make adapter.
[[adapter]]
invalid.
-
-
Empty
navigator.gpu.
[[previously_returned_adapters]]
.
Update here if an adaptersadded
/adapterschanged
event is introduced.
4.2.1. Adapter Selection
GPURequestAdapterOptions
provides hints to the user agent indicating what
configuration is suitable for the application.
dictionary GPURequestAdapterOptions {GPUPowerPreference powerPreference ;boolean forceFallbackAdapter =false ; };
enum {
GPUPowerPreference "low-power" ,"high-performance" };
GPURequestAdapterOptions
has the following members:
powerPreference
, of type GPUPowerPreference-
Optionally provides a hint indicating what class of adapter should be selected from the system’s available adapters.
The value of this hint may influence which adapter is chosen, but it must not influence whether an adapter is returned or not.
Note: The primary utility of this hint is to influence which GPU is used in a multi-GPU system. For instance, some laptops have a low-power integrated GPU and a high-performance discrete GPU.
Note: Depending on the exact hardware configuration, such as battery status and attached displays or removable GPUs, the user agent may select different adapters given the same power preference. Typically, given the same hardware configuration and state and
powerPreference
, the user agent is likely to select the same adapter.It must be one of the following values:
undefined
(or not present)-
Provides no hint to the user agent.
"low-power"
-
Indicates a request to prioritize power savings over performance.
Note: Generally, content should use this if it is unlikely to be constrained by drawing performance; for example, if it renders only one frame per second, draws only relatively simple geometry with simple shaders, or uses a small HTML canvas element. Developers are encouraged to use this value if their content allows, since it may significantly improve battery life on portable devices.
"high-performance"
-
Indicates a request to prioritize performance over power consumption.
Note: By choosing this value, developers should be aware that, for devices created on the resulting adapter, user agents are more likely to force device loss, in order to save power by switching to a lower-power adapter. Developers are encouraged to only specify this value if they believe it is absolutely necessary, since it may significantly decrease battery life on portable devices.
forceFallbackAdapter
, of type boolean, defaulting tofalse
-
When set to
true
indicates that only a fallback adapter may be returned. If the user agent does not support a fallback adapter, will causerequestAdapter()
to resolve tonull
.Note:
requestAdapter()
may still return a fallback adapter ifforceFallbackAdapter
is set tofalse
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 theGPUAdapter
.isFallbackAdapter
attribute prior to requesting aGPUDevice
.
"high-performance"
GPUAdapter
:
const gpuAdapter= await navigator. gpu. requestAdapter({ powerPreference: 'high-performance' });
4.3. GPUAdapter
A GPUAdapter
encapsulates an adapter,
and describes its capabilities (features and limits).
To get a GPUAdapter
, use requestAdapter()
.
[Exposed =(Window ,DedicatedWorker ),SecureContext ]interface GPUAdapter { [SameObject ]readonly attribute GPUSupportedFeatures features ; [SameObject ]readonly attribute GPUSupportedLimits limits ;readonly attribute boolean isFallbackAdapter ;Promise <GPUDevice >requestDevice (optional GPUDeviceDescriptor descriptor = {});Promise <GPUAdapterInfo >requestAdapterInfo (optional sequence <DOMString >unmaskHints = []); };
GPUAdapter
has the following attributes:
features
, of type GPUSupportedFeatures, readonly-
The set of values in
this
.[[adapter]]
.[[features]]
. limits
, of type GPUSupportedLimits, readonly-
The limits in
this
.[[adapter]]
.[[limits]]
. isFallbackAdapter
, of type boolean, readonly-
Returns the value of
[[adapter]]
.[[fallback]]
.
GPUAdapter
has the following internal slots:
[[adapter]]
, of type adapter, readonly-
The adapter to which this
GPUAdapter
refers.
GPUAdapter
has the following methods:
requestDevice(descriptor)
-
Requests a device from the adapter.
Called on:GPUAdapter
this.Arguments:
Arguments for the GPUAdapter.requestDevice(descriptor) method. Parameter Type Nullable Optional Description descriptor
GPUDeviceDescriptor
✘ ✔ Description of the GPUDevice
to request.Content timeline steps:
-
Let promise be a new promise.
-
Let adapter be this.
[[adapter]]
. -
Issue the initialization steps to the Device timeline of this.
-
Return promise.
Device timeline initialization steps:-
If any of the following requirements are unmet, reject promise with a
TypeError
and stop.-
The set of values in descriptor.
requiredFeatures
must be a subset of those in adapter.[[features]]
.
Note: This is the same error that is produced if a feature name isn’t known by the browser at all (in its
GPUFeatureName
definition). This converges the behavior when the browser doesn’t support a feature with the behavior when a particular adapter doesn’t support a feature. -
-
If any of the following requirements are unmet, reject promise with an
OperationError
and stop.-
Each key in descriptor.
requiredLimits
must be the name of a member of supported limits. -
For each limit name key in the keys of supported limits: Let value be descriptor.
requiredLimits
[key].-
value must be no better than the value of that limit in adapter.
[[limits]]
. -
If the limit’s class is alignment, value must be a power of 2.
-
-
-
If adapter is invalid, or the user agent otherwise cannot fulfill the request:
-
Let device be a new device.
-
Lose the device(device,
undefined
).Note: This makes adapter invalid, if it wasn’t already.
Note: User agents should consider issuing developer-visible warnings in most or all cases when this occurs. Applications should perform reinitialization logic starting with
requestAdapter()
. -
Resolve promise with a new
GPUDevice
encapsulating device, and stop.
-
-
Resolve promise with a new
GPUDevice
object encapsulating a new device with the capabilities described by descriptor.
-
requestAdapterInfo()
-
Requests the
GPUAdapterInfo
for thisGPUAdapter
.Note: Adapter info values are returned with a Promise to give user agents an opportunity to perform potentially long-running checks when requesting unmasked values, such as asking for user consent before returning. If no
unmaskHints
are specified, however, no dialogs should be displayed to the user.Called on:GPUAdapter
this.Arguments:
Arguments for the GPUAdapter.requestAdapterInfo() method. Parameter Type Nullable Optional Description unmaskHints
sequence<DOMString>
✘ ✔ A list of GPUAdapterInfo
attribute names for which unmasked values are desired if available.Returns:
Promise
<GPUAdapterInfo
>Content timeline steps:
-
Let promise be a new promise.
-
Let adapter be this.
[[adapter]]
. -
Let hasActivation be
true
if the relevant global object for this has transient activation, andfalse
otherwise. -
Run the following steps in parallel:
-
If unmaskHints.length >
0
:-
If hasActivation is
false
reject promise with aNotAllowedError
and abort these steps. -
Let unmaskedKeys be a list of the fields specified in unmaskHints which the user agent decides to unmask, if any.
Note: The user agent is free to use any method it deems appropriate to decide which fields to unmask.
-
Append unmaskedKeys to adapter.
[[unmaskedIdentifiers]]
.
-
-
Resolve promise with a new adapter info for adapter.
-
-
Return promise.
-
GPUDevice
with default features and limits:
const gpuAdapter= await navigator. gpu. requestAdapter(); const gpuDevice= await gpuAdapter. requestDevice();
4.3.1. GPUDeviceDescriptor
GPUDeviceDescriptor
describes a device request.
dictionary GPUDeviceDescriptor :GPUObjectDescriptorBase {sequence <GPUFeatureName >requiredFeatures = [];record <DOMString ,GPUSize64 >requiredLimits = {};GPUQueueDescriptor defaultQueue = {}; };
GPUDeviceDescriptor
has the following members:
requiredFeatures
, of type sequence<GPUFeatureName>, defaulting to[]
-
Specifies the features that are required by the device request. The request will fail if the adapter cannot provide these features.
Exactly the specified set of features, and no more or less, will be allowed in validation of API calls on the resulting device.
requiredLimits
, of type record<DOMString, GPUSize64>, defaulting to{}
-
Specifies the limits that are required by the device request. The request will fail if the adapter cannot provide these limits.
Each key must be the name of a member of supported limits. Exactly the specified limits, and no better or worse, will be allowed in validation of API calls on the resulting device.
defaultQueue
, of type GPUQueueDescriptor, defaulting to{}
-
The descriptor for the default
GPUQueue
.
GPUDevice
with the "texture-compression-astc"
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});
4.3.1.1. GPUFeatureName
Each GPUFeatureName
identifies a set of functionality which, if available,
allows additional usages of WebGPU that would have otherwise been invalid.
enum GPUFeatureName {"depth-clip-control" ,"depth32float-stencil8" ,"texture-compression-bc" ,"texture-compression-etc2" ,"texture-compression-astc" ,"timestamp-query" ,"indirect-first-instance" ,"shader-f16" ,"bgra8unorm-storage" ,"rg11b10ufloat-renderable" };
4.4. GPUDevice
A GPUDevice
encapsulates a device and exposes
the functionality of that device.
GPUDevice
is the top-level interface through which WebGPU interfaces are created.
To get a GPUDevice
, use requestDevice()
.
[Exposed =(Window ,DedicatedWorker ),SecureContext ]interface GPUDevice :EventTarget { [SameObject ]readonly attribute GPUSupportedFeatures features ; [SameObject ]readonly attribute GPUSupportedLimits limits ; [SameObject ]readonly attribute GPUQueue queue ;undefined destroy ();GPUBuffer createBuffer (GPUBufferDescriptor descriptor );GPUTexture createTexture (GPUTextureDescriptor descriptor );GPUSampler createSampler (optional GPUSamplerDescriptor descriptor = {});GPUExternalTexture importExternalTexture (GPUExternalTextureDescriptor descriptor );GPUBindGroupLayout createBindGroupLayout (GPUBindGroupLayoutDescriptor descriptor );GPUPipelineLayout createPipelineLayout (GPUPipelineLayoutDescriptor descriptor );GPUBindGroup createBindGroup (GPUBindGroupDescriptor descriptor );GPUShaderModule createShaderModule (GPUShaderModuleDescriptor descriptor );GPUComputePipeline createComputePipeline (GPUComputePipelineDescriptor descriptor );GPURenderPipeline createRenderPipeline (GPURenderPipelineDescriptor descriptor );Promise <GPUComputePipeline >createComputePipelineAsync (GPUComputePipelineDescriptor descriptor );Promise <GPURenderPipeline >createRenderPipelineAsync (GPURenderPipelineDescriptor descriptor );GPUCommandEncoder createCommandEncoder (optional GPUCommandEncoderDescriptor descriptor = {});GPURenderBundleEncoder createRenderBundleEncoder (GPURenderBundleEncoderDescriptor descriptor );GPUQuerySet createQuerySet (GPUQuerySetDescriptor descriptor ); };GPUDevice includes GPUObjectBase ;
GPUDevice
has the following attributes:
features
, of type GPUSupportedFeatures, readonly-
A set containing the
GPUFeatureName
values of the features supported by the device (i.e. the ones with which it was created). limits
, of type GPUSupportedLimits, readonly-
Exposes the limits supported by the device (which are exactly the ones with which it was created).
queue
, of type GPUQueue, readonly-
The primary
GPUQueue
for this device.
The [[device]]
for a GPUDevice
is the device that the GPUDevice
refers
to.
GPUDevice
has the methods listed in its WebIDL definition above.
Those not defined here are defined elsewhere in this document.
destroy()
-
Destroys the device, preventing further operations on it. Outstanding asynchronous operations will fail.
Note: It is valid to destroy a device multiple times.
Called on:GPUDevice
this.Content timeline steps:
-
Issue the subsequent steps on the Device timeline of this.
Device timeline steps:-
Once all currently-enqueued operations on any queue on this device are completed, issue the subsequent steps on the current timeline.
-
Lose the device(this.
[[device]]
,"destroyed"
).
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.
GPUDevice
's allowed buffer usages are:
GPUDevice
's allowed texture usages are:
-
Always allowed:
COPY_SRC
,COPY_DST
,TEXTURE_BINDING
,STORAGE_BINDING
,RENDER_ATTACHMENT
4.5. Example
GPUAdapter
and GPUDevice
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();
5. Buffers
5.1. GPUBuffer
define buffer (internal object)
A GPUBuffer
represents a block of memory that can be used in GPU operations.
Data is stored in linear layout, meaning that each byte of the allocation can be
addressed by its offset from the start of the GPUBuffer
, subject to alignment
restrictions depending on the operation. Some GPUBuffers
can be
mapped which makes the block of memory accessible via an ArrayBuffer
called
its mapping.
GPUBuffers
are created via GPUDevice.createBuffer(descriptor)
that returns a new buffer (which may be mappedAtCreation
).
[Exposed =(Window ,DedicatedWorker ),SecureContext ]interface GPUBuffer {Promise <undefined >mapAsync (GPUMapModeFlags mode ,optional GPUSize64 offset = 0,optional GPUSize64 size );ArrayBuffer getMappedRange (optional GPUSize64 offset = 0,optional GPUSize64 size );undefined unmap ();undefined destroy ();readonly attribute GPUSize64 size ;readonly attribute GPUBufferUsageFlags usage ; };GPUBuffer includes GPUObjectBase ;
GPUBuffer
has the following attributes:
size
, of type GPUSize64, readonly-
The length of the
GPUBuffer
allocation in bytes.This attribute is backed by an immutable internal slot of the same name, and always returns its value.
usage
, of type GPUBufferUsageFlags, readonly-
The allowed usages for this
GPUBuffer
.This attribute is backed by an immutable internal slot of the same name, and always returns its value.
GPUBuffer
has the following internal slots:
[[deviceTimelineState]]
, of type buffer device timeline state-
The current buffer device timeline state of the buffer:
[[map_requests]]
, of type ordered map<unique id, map request status>-
The map request status of each outstanding map request:
- "open"
-
The map request is in flight and may still succeed.
- "cancelled"
-
The map request has been cancelled by
unmap()
and will reject when it completes.
Requests are removed from this map when they complete.
[[mapping]]
, of type active buffer mapping ornull
, initiallynull
-
Set iff the buffer is currently mapped for use by
getMappedRange()
. Null otherwise (even if there are outstanding[[map_requests]]
).An active buffer mapping is a structure with the following fields:
- data, of type
ArrayBuffer
-
The mapping for this
GPUBuffer
. TheArrayBuffer
isn’t directly accessible and is instead accessed through views into it, called the mapped ranges, that are stored in views.Note: This is just a memory allocation; this
ArrayBuffer
object is not exposed directly.Specify
[[mapping]]
in term ofDataBlock
similarly to AllocateArrayBuffer? - mode, of type
GPUMapModeFlags
-
The
GPUMapModeFlags
of the map, as specified in the corresponding call tomapAsync()
orcreateBuffer()
. - range, of type tuple [
unsigned long long
,unsigned long long
] -
The range of this
GPUBuffer
that is mapped. - views, of type list<
ArrayBuffer
> -
The
ArrayBuffer
s returned viagetMappedRange()
to the application. They are tracked so they can be detached whenunmap()
is called.
- data, of type
Add diagrams showing the cancellation of a buffer mapping (with unmap arriving at the device timeline either before or after it responds to a mapAsync).
GPUBuffer
is a reference to an internal buffer object.
5.2. Buffer Creation
5.2.1. GPUBufferDescriptor
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 tofalse
-
If
true
creates the buffer in an already mapped state, allowinggetMappedRange()
to be called immediately. It is valid to setmappedAtCreation
totrue
even ifusage
does not containMAP_READ
orMAP_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.
-
If device is lost return
false
. -
If any of the bits of descriptor’s
usage
aren’t present in device’s allowed buffer usages, returnfalse
. -
If both the
MAP_READ
andMAP_WRITE
bits of descriptor’susage
attribute are set, returnfalse
. -
Return
true
.
5.2.2. Buffer Usage
typedef [EnforceRange ]unsigned long ; [
GPUBufferUsageFlags Exposed =(Window ,DedicatedWorker )]namespace {
GPUBufferUsage const GPUFlagsConstant MAP_READ = 0x0001;const GPUFlagsConstant MAP_WRITE = 0x0002;const GPUFlagsConstant COPY_SRC = 0x0004;const GPUFlagsConstant COPY_DST = 0x0008;const GPUFlagsConstant INDEX = 0x0010;const GPUFlagsConstant VERTEX = 0x0020;const GPUFlagsConstant UNIFORM = 0x0040;const GPUFlagsConstant STORAGE = 0x0080;const GPUFlagsConstant INDIRECT = 0x0100;const GPUFlagsConstant QUERY_RESOLVE = 0x0200; };
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()
withGPUMapMode.READ
)May only be combined with
COPY_DST
. MAP_WRITE
-
The buffer can be mapped for writing. (Example: calling
mapAsync()
withGPUMapMode.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 acopyBufferToBuffer()
orcopyBufferToTexture()
call.) COPY_DST
-
The buffer can be used as the destination of a copy or write operation. (Examples: as the
destination
argument of acopyBufferToBuffer()
orcopyTextureToBuffer()
call, or as the target of awriteBuffer()
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 abuffer
.type
of"uniform"
.) STORAGE
-
The buffer can be used as a storage buffer. (Example: as a bind group entry for a
GPUBufferBindingLayout
with abuffer
.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 adrawIndirect()
ordispatchWorkgroupsIndirect()
call.) QUERY_RESOLVE
-
The buffer can be used to capture query results. (Example: as the
destination
argument of aresolveQuerySet()
call.)
createBuffer(descriptor)
-
Creates a
GPUBuffer
.Called on:GPUDevice
this.Arguments:
Arguments for the GPUDevice.createBuffer(descriptor) method. Parameter Type Nullable Optional Description descriptor
GPUBufferDescriptor
✘ ✘ Description of the GPUBuffer
to create.Returns:
GPUBuffer
Content timeline steps:
-
Let b be a new
GPUBuffer
object. -
If descriptor.
mappedAtCreation
istrue
, set b.[[mapping]]
to an active buffer mapping with: -
Issue the initialization steps on the Device timeline of this.
-
Return b.
Device timeline initialization steps:-
If any of the following conditions are unsatisfied generate a validation error, make b invalid, and stop.
-
this is valid.
-
validating GPUBufferDescriptor(this, descriptor) returns true.
-
descriptor.
usage
must not be 0. -
descriptor.
usage
is a subset of this’s allowed buffer usages. -
If descriptor.
mappedAtCreation
istrue
:-
descriptor.
size
is a multiple of 4.
-
-
Note: If buffer creation fails, and descriptor.
mappedAtCreation
isfalse
, any calls tomapAsync()
will reject, so any resources allocated to enable mapping can and may be discarded or recycled.-
If descriptor.
mappedAtCreation
istrue
:-
Set b.
[[deviceTimelineState]]
to "unavailable".
Else:
-
Set b.
[[deviceTimelineState]]
to "available".
-
-
Set each byte of b’s allocation to zero.
-
const buffer= gpuDevice. createBuffer({ size: 128 , usage: GPUBufferUsage. UNIFORM| GPUBufferUsage. COPY_DST});
5.3. Buffer Destruction
An application that no longer requires a GPUBuffer
can choose to lose
access to it before garbage collection by calling destroy()
. Destroying a buffer also
unmaps it, freeing any memory allocated for the mapping.
Note: This allows the user agent to reclaim the GPU memory associated with the GPUBuffer
once all previously submitted operations using it are complete.
destroy()
-
Destroys the
GPUBuffer
.Note: It is valid to destroy a buffer multiple times.
Called on:GPUBuffer
this.Returns:
undefined
Content timeline steps:
-
If this is mapped, call this.
unmap()
. -
Issue the subsequent steps on the Device timeline of this.
[[device]]
.
Device timeline steps:-
Set this.
[[deviceTimelineState]]
to "destroyed".
Note: Since no further operations can be enqueued using this buffer, implementations can free resource allocations, including mapped memory that was just unmapped.
-
5.4. Buffer Mapping
An application can request to map a GPUBuffer
so that they can access its
content via ArrayBuffer
s 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 ,DedicatedWorker )]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 anArrayBuffer
containing the buffer’s current values. Changes to the returnedArrayBuffer
will be discarded afterunmap()
is called. WRITE
-
Only valid with buffers created with the
MAP_WRITE
usage.Once the buffer is mapped, calls to
getMappedRange()
will return anArrayBuffer
containing the buffer’s current values. Changes to the returnedArrayBuffer
will be stored in theGPUBuffer
afterunmap()
is called.Note: Since the
MAP_WRITE
buffer usage may only be combined with theCOPY_SRC
buffer usage, mapping for writing can never return values produced by the GPU, and the returnedArrayBuffer
will only ever contain the default initialized data (zeros) or data written by the webpage during a previous mapping.
mapAsync(mode, offset, size)
-
Maps the given range of the
GPUBuffer
and resolves the returnedPromise
when theGPUBuffer
's content is ready to be accessed withgetMappedRange()
.Called on:GPUBuffer
this.Arguments:
Arguments for the GPUBuffer.mapAsync(mode, offset, size) method. Parameter Type Nullable Optional Description mode
GPUMapModeFlags
✘ ✘ Whether the buffer should be mapped for reading or writing. offset
GPUSize64
✘ ✔ Offset in bytes into the buffer to the start of the range to map. size
GPUSize64
✘ ✔ Size in bytes of the range to map. Content timeline steps:
-
Let contentTimeline be the current Content timeline.
-
Let requestID be a new unique ID identifying this map request.
-
Let p be a new
Promise
. -
Set this.
[[map_requests]]
[requestID] to "open". -
Issue the validation steps on the Device timeline of this.
[[device]]
. -
Return p.
Device timeline validation steps:-
If size is
undefined
:-
Let rangeSize be max(0, this.
size
- offset).
Otherwise:
-
Let rangeSize be size.
-
-
If any of the following conditions are unsatisfied:
-
Figure out exactly how invalid and destroyed buffers are handled.
-
offset is a multiple of 8.
-
rangeSize is a multiple of 4.
-
offset + rangeSize ≤ this.
size
-
this.
[[deviceTimelineState]]
is "available". -
If mode contains
READ
then this.usage
must containMAP_READ
. -
If mode contains
WRITE
then this.usage
must containMAP_WRITE
.
Then:
-
Issue the following steps on contentTimeline:
Content timeline steps:-
Assert this.
[[map_requests]]
[requestID] exists. -
Remove this.
[[map_requests]]
[requestID]. -
Assert p is pending.
-
Reject p with an
OperationError
.
-
-
Return.
-
-
Set this.
[[deviceTimelineState]]
to "unavailable". -
Once all currently-enqueued operations using this (on any queue) are completed, issue the subsequent steps on the current timeline.
Note: Since the buffer is mapped, its contents cannot change between this completion and
unmap()
.
Device timeline steps:-
Let deviceTimelineStateAtCompletion be this.
[[deviceTimelineState]]
.Note: If at this point the buffer has become "available" again due to an
unmap()
call, then the corresponding request status below will also be "cancelled", so mapping will not complete below. -
Let dataForMappedRegion be the contents of this starting at offset offset, for rangeSize bytes.
-
Issue the subsequent steps on contentTimeline.
Content timeline steps:-
Let requestStatus be this.
[[map_requests]]
[requestID]. -
Remove this.
[[map_requests]]
[requestID]. -
Assert p is pending.
-
If requestStatus is "cancelled":
-
Reject p with an
AbortError
. -
Return.
This describes one possible behavior. Need to discuss whether it’s the right one. [Issue #gpuweb/gpuweb#3271]
-
-
Assert deviceTimelineStateAtCompletion is "unavailable".
-
Let m be a new
ArrayBuffer
of size rangeSize. -
Set the content of m to dataForMappedRegion.
-
Set this.
[[mapping]]
to an active buffer mapping with: -
Resolve p.
-
getMappedRange(offset, size)
-
Returns an
ArrayBuffer
with the contents of theGPUBuffer
in the given mapped range.Called on:GPUBuffer
this.Arguments:
Arguments for the GPUBuffer.getMappedRange(offset, size) method. Parameter Type Nullable Optional Description offset
GPUSize64
✘ ✔ Offset in bytes into the buffer to return buffer contents from. size
GPUSize64
✘ ✔ Size in bytes of the ArrayBuffer
to return.Returns:
ArrayBuffer
Content timeline steps:
-
If size is missing:
-
Let rangeSize be max(0, this.
size
- offset).
Otherwise, let rangeSize be size.
-
-
If any of the following conditions are unsatisfied, throw an
OperationError
and stop.-
this.
[[mapping]]
is notnull
. -
offset is a multiple of 8.
-
rangeSize is a multiple of 4.
-
offset ≥ this.
[[mapping]]
.range[0]. -
offset + rangeSize ≤ this.
[[mapping]]
.range[1]. -
[offset, offset + rangeSize) does not overlap another range in this.
[[mapping]]
.views.
Note: It is always valid to get mapped ranges of a
GPUBuffer
that ismappedAtCreation
, even if it is invalid, because the Content timeline might not know it is invalid. -
-
Let m be a new
ArrayBuffer
of size rangeSize, pointing at the content at offset (offset -[[mapping]]
.range[0]) of this.[[mapping]]
. -
Set m.
[[ArrayBufferDetachKey]]
to "WebGPUBufferMapping".Note: This causes a
TypeError
to be thrown if an attempt is made to DetachArrayBuffer, except byunmap()
. -
Append m to this.
[[mapping]]
.views. -
Return m.
Note: User agents should consider issuing a developer-visible warning if
getMappedRange()
succeeds without having checked the status of the map, either by waiting formapAsync()
to succeed, or waiting for a lateronSubmittedWorkDone()
call to succeed. -
unmap()
-
Unmaps the mapped range of the
GPUBuffer
and makes it’s contents available for use by the GPU again.Called on:GPUBuffer
this.Returns:
undefined
Content timeline steps:
-
For each requestID in the keys of this.
[[map_requests]]
:-
Set this.
[[map_requests]]
[requestID] to cancelled.
This describes one possible behavior. Need to discuss whether it’s the right one. [Issue #gpuweb/gpuweb#3271]
-
-
Let updatedBufferContents be
null
. -
If this.
[[mapping]]
is notnull
:-
For each
ArrayBuffer
ab in this.[[mapping]]
.views:-
Perform DetachArrayBuffer(ab, "WebGPUBufferMapping").
-
-
If this.
[[mapping]]
.mode containsWRITE
:-
Set updatedBufferContents to the content of this.
[[mapping]]
.
Note: When a buffer is mapped without the
WRITE
mode, then unmapped, any local modifications done by the application to the mapped rangesArrayBuffer
are discarded and will not affect the content of follow-up mappings. -
-
Set this.
[[mapping]]
tonull
.
-
-
Issue the subsequent steps on the Device timeline of this.
[[device]]
.
Device timeline steps:-
If updatedBufferContents is not
null
:-
Issue the following steps on the Queue timeline of this.
[[device]]
.queue
:Queue timeline steps:-
Update the contents of this with updatedBufferContents.
-
-
-
Set this.
[[deviceTimelineState]]
to "available". -
If any of the following requirements are unmet, generate a validation error and stop.
-
this.
[[deviceTimelineState]]
must be "unavailable".
Note: It is valid to unmap an invalid
GPUBuffer
that ismappedAtCreation
because the Content timeline might not know it is invalid. This allows the temporary[[mapping]]
memory to be freed.This validation isn’t really necessary because it’s not guarding anything. [Issue #gpuweb/gpuweb#3251]
-
-
6. Textures and Texture Views
define texture (internal object)
define mipmap level, array layer, aspect, slice (concepts)
6.1. GPUTexture
GPUTextures
are created via GPUDevice.createTexture(descriptor)
that returns a new texture.
[Exposed =(Window ,DedicatedWorker ),SecureContext ]interface GPUTexture {GPUTextureView createView (optional GPUTextureViewDescriptor descriptor = {});undefined destroy ();readonly attribute GPUIntegerCoordinate width ;readonly attribute GPUIntegerCoordinate height ;readonly attribute GPUIntegerCoordinate depthOrArrayLayers ;readonly attribute GPUIntegerCoordinate mipLevelCount ;readonly attribute GPUSize32 sampleCount ;readonly attribute GPUTextureDimension dimension ;readonly attribute GPUTextureFormat format ;readonly attribute GPUTextureUsageFlags usage ; };GPUTexture includes GPUObjectBase ;
GPUTexture
has the following attributes:
width
, of type GPUIntegerCoordinate, readonly-
The width of this
GPUTexture
. height
, of type GPUIntegerCoordinate, readonly-
The height of this
GPUTexture
. depthOrArrayLayers
, of type GPUIntegerCoordinate, readonly-
The depth or layer count of this
GPUTexture
. mipLevelCount
, of type GPUIntegerCoordinate, readonly-
The number of mip levels of this
GPUTexture
. sampleCount
, of type GPUSize32, 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 GPUTextureUsageFlags, readonly-
The allowed usages for this
GPUTexture
.
GPUTexture
has the following internal slots:
[[size]]
, of typeGPUExtent3D
-
The size of the texture (same as the
width
,height
, anddepthOrArrayLayers
attributes). [[viewFormats]]
, of type sequence<GPUTextureFormat
>-
The set of
GPUTextureFormat
s that can be usedGPUTextureViewDescriptor
.format
when creating views on thisGPUTexture
. [[destroyed]]
, of typeboolean
, initially false-
If the texture is destroyed, it can no longer be used in any operation, and its underlying memory can be freed.
Arguments:
-
GPUExtent3D
baseSize -
GPUSize32
mipLevel
Returns: GPUExtent3DDict
-
Let extent be a new
GPUExtent3DDict
object. -
Set extent.
depthOrArrayLayers
to 1. -
Return extent.
share this definition with the part of the specification that describes sampling.
6.1.1. Texture Creation
dictionary :
GPUTextureDescriptor GPUObjectDescriptorBase {required GPUExtent3D size ;GPUIntegerCoordinate mipLevelCount = 1;GPUSize32 sampleCount = 1;GPUTextureDimension dimension = "2d";required GPUTextureFormat format ;required GPUTextureUsageFlags usage ;sequence <GPUTextureFormat >viewFormats = []; };
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 to1
-
The number of mip levels the texture will contain.
sampleCount
, of type GPUSize32, defaulting to1
-
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 callingcreateView()
on this texture (in addition to the texture’s actualformat
).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
orviewFormats
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.
TwoGPUTextureFormat
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).
Define larger compatibility classes. [Issue #gpuweb/gpuweb#168]
-
enum {
GPUTextureDimension "1d" ,"2d" ,"3d" };
"1d"
-
Specifies a texture that has one dimension, width.
"2d"
-
Specifies a texture that has a width and height, and may have layers. Only
"2d"
textures may have mipmaps, be multisampled, use a compressed or depth/stencil format, and be used as a render attachment. "3d"
-
Specifies a texture that has a width, height, and depth.
typedef [EnforceRange ]unsigned long ; [
GPUTextureUsageFlags Exposed =(Window ,DedicatedWorker )]namespace {
GPUTextureUsage const GPUFlagsConstant COPY_SRC = 0x01;const GPUFlagsConstant COPY_DST = 0x02;const GPUFlagsConstant TEXTURE_BINDING = 0x04;const GPUFlagsConstant STORAGE_BINDING = 0x08;const GPUFlagsConstant RENDER_ATTACHMENT = 0x10; };
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 acopyTextureToTexture()
orcopyTextureToBuffer()
call.) COPY_DST
-
The texture can be used as the destination of a copy or write operation. (Examples: as the
destination
argument of acopyTextureToTexture()
orcopyBufferToTexture()
call, or as the target of awriteTexture()
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
orGPURenderPassDepthStencilAttachment
.view
.)
Arguments:
createTexture(descriptor)
-
Creates a
GPUTexture
.Called on:GPUDevice
this.Arguments:
Arguments for the GPUDevice.createTexture(descriptor) method. Parameter Type Nullable Optional Description descriptor
GPUTextureDescriptor
✘ ✘ Description of the GPUTexture
to create.Returns:
GPUTexture
Content timeline steps:
-
Validate texture format required features of descriptor.
format
with this.[[device]]
. -
Validate texture format required features of each element of descriptor.
viewFormats
with this.[[device]]
. -
Let t be a new
GPUTexture
object. -
Set t.
depthOrArrayLayers
to descriptor.size
.depthOrArrayLayers. -
Set t.
mipLevelCount
to descriptor.mipLevelCount
. -
Set t.
sampleCount
to descriptor.sampleCount
. -
Issue the initialization steps on the Device timeline of this.
-
Return t.
Device timeline initialization steps:-
If any of the following conditions are unsatisfied generate a validation error, make t invalid, and stop.
-
validating GPUTextureDescriptor(this, descriptor) returns
true
.
-
-
Set t.
[[viewFormats]]
to descriptor.viewFormats
.
-
GPUDevice
this, GPUTextureDescriptor
descriptor):
Return true
if all of the following requirements are met, and false
otherwise:
-
descriptor.
usage
must not be 0. -
descriptor.
usage
must contain only bits present in this’s allowed texture usages. -
descriptor.
size
.width, descriptor.size
.height, and descriptor.size
.depthOrArrayLayers must be > zero. -
descriptor.
mipLevelCount
must be > zero. -
descriptor.
sampleCount
must be either 1 or 4. -
If descriptor.
dimension
is:"1d"
-
-
descriptor.
size
.width must be ≤ this.limits
.maxTextureDimension1D
. -
descriptor.
size
.depthOrArrayLayers must be 1. -
descriptor.
sampleCount
must be 1. -
descriptor.
format
must not be a compressed format or depth-or-stencil format.
-
"2d"
-
-
descriptor.
size
.width must be ≤ this.limits
.maxTextureDimension2D
. -
descriptor.
size
.height must be ≤ this.limits
.maxTextureDimension2D
. -
descriptor.
size
.depthOrArrayLayers must be ≤ this.limits
.maxTextureArrayLayers
.
-
"3d"
-
-
descriptor.
size
.width must be ≤ this.limits
.maxTextureDimension3D
. -
descriptor.
size
.height must be ≤ this.limits
.maxTextureDimension3D
. -
descriptor.
size
.depthOrArrayLayers must be ≤ this.limits
.maxTextureDimension3D
. -
descriptor.
sampleCount
must be 1. -
descriptor.
format
must not be a compressed format or depth-or-stencil format.
-
-
descriptor.
size
.width must be multiple of texel block width. -
descriptor.
size
.height must be multiple of texel block height. -
If descriptor.
sampleCount
> 1:-
descriptor.
mipLevelCount
must be 1. -
descriptor.
size
.depthOrArrayLayers must be 1. -
descriptor.
usage
must not include theSTORAGE_BINDING
bit. -
descriptor.
usage
must include theRENDER_ATTACHMENT
bit. -
descriptor.
format
must support multisampling according to § 25.1 Texture Format Capabilities.
-
-
descriptor.
mipLevelCount
must be ≤ maximum mipLevel count(descriptor.dimension
, descriptor.size
). -
If descriptor.
usage
includes theRENDER_ATTACHMENT
bit:-
descriptor.
format
must be a renderable format.
-
-
If descriptor.
usage
includes theSTORAGE_BINDING
bit:-
descriptor.
format
must be listed in § 25.1.1 Plain color formats table withSTORAGE_BINDING
capability.
-
-
For each viewFormat in descriptor.
viewFormats
, descriptor.format
and viewFormat must be texture view format compatible.
const texture= gpuDevice. createTexture({ size: { width: 16 , height: 16 }, format: 'rgba8unorm' , usage: GPUTextureUsage. TEXTURE_BINDING, });
6.1.2. Texture Destruction
An application that no longer requires a GPUTexture
can choose to lose access to it before
garbage collection by calling destroy()
.
Note: This allows the user agent to reclaim the GPU memory associated with the GPUTexture
once
all previously submitted operations using it are complete.
destroy()
-
Destroys the
GPUTexture
.Called on:GPUTexture
this.Returns:
undefined
Content timeline steps:
-
Set this.
[[destroyed]]
to true.
-
6.2. GPUTextureView
[Exposed =(Window ,DedicatedWorker ),SecureContext ]interface GPUTextureView { };GPUTextureView includes GPUObjectBase ;
GPUTextureView
has the following internal slots:
[[texture]]
-
The
GPUTexture
into which this is a view. [[descriptor]]
-
The
GPUTextureViewDescriptor
describing this texture view.All optional fields of
GPUTextureViewDescriptor
are defined. [[renderExtent]]
-
For renderable views, this is the effective
GPUExtent3DDict
for rendering.Note: this extent depends on the
baseMipLevel
.
6.2.1. Texture View Creation
dictionary :
GPUTextureViewDescriptor GPUObjectDescriptorBase {GPUTextureFormat format ;GPUTextureViewDimension dimension ;GPUTextureAspect aspect = "all";GPUIntegerCoordinate baseMipLevel = 0;GPUIntegerCoordinate mipLevelCount ;GPUIntegerCoordinate baseArrayLayer = 0;GPUIntegerCoordinate arrayLayerCount ; };
GPUTextureDescriptor
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 theviewFormats
specified during its creation. dimension
, of type GPUTextureViewDimension-
The dimension to view the texture as.
aspect
, of type GPUTextureAspect, defaulting to"all"
-
Which
aspect(s)
of the texture are accessible to the texture view. baseMipLevel
, of type GPUIntegerCoordinate, defaulting to0
-
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 to0
-
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, corresponding to the [+X, -X, +Y, -Y, +Z, -Z] faces of the cube. Sampling is done seamlessly across the faces of the cubemap.
Corresponding WGSL types:
-
texture_cube
-
texture_depth_cube
-
"cube-array"
-
The texture is viewed as a packed array of
n
cubemaps, each with 6 array layers corresponding to the [+X, -X, +Y, -Y, +Z, -Z] faces of the cube. Sampling is done seamlessly across the faces of the cubemaps.Corresponding WGSL types:
-
texture_cube_array
-
texture_depth_cube_array
-
"3d"
-
The texture is viewed as a 3-dimensional image.
Corresponding WGSL types:
-
texture_3d
-
texture_storage_3d
-
enum {
GPUTextureAspect "all" ,"stencil-only" ,"depth-only" };
"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.
"stencil-only"
-
Only the stencil aspect of a depth-or-stencil format format will be accessible to the texture view.
"depth-only"
-
Only the depth aspect of a depth-or-stencil format format will be accessible to the texture view.
createView(descriptor)
-
Creates a
GPUTextureView
.Note: By defaultcreateView()
will create a view with a dimension that can represent the entire texture. For example, callingcreateView()
without specifying adimension
on a"2d"
texture with more than one layer will create a"2d-array"
GPUTextureView
, even if anarrayLayerCount
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 explicitdimension
to ensure shader compatibility.Called on:GPUTexture
this.Arguments:
Arguments for the GPUTexture.createView(descriptor) method. Parameter Type Nullable Optional Description descriptor
GPUTextureViewDescriptor
✘ ✔ Description of the GPUTextureView
to create.Returns: view, of type
GPUTextureView
.Content timeline steps:
-
Validate texture format required features of descriptor.
format
with this.[[device]]
. -
Let view be a new
GPUTextureView
object. -
Issue the initialization steps on the Device timeline of this.
-
Return view.
Device timeline initialization steps:-
Set descriptor to the result of resolving GPUTextureViewDescriptor defaults for this with descriptor.
-
If any of the following conditions are unsatisfied generate a validation error, make view invalid, and stop.
-
this is valid.
-
If the descriptor.
aspect
is"all"
:-
descriptor.
format
must equal either this.format
or one of the formats in this.[[viewFormats]]
.
Otherwise:
-
descriptor.
format
must equal the result of resolving GPUTextureAspect( this.format
, descriptor.aspect
).
-
-
descriptor.
mipLevelCount
must be > 0. -
descriptor.
baseMipLevel
+ descriptor.mipLevelCount
must be ≤ this.mipLevelCount
. -
descriptor.
arrayLayerCount
must be > 0. -
descriptor.
baseArrayLayer
+ descriptor.arrayLayerCount
must be ≤ the array layer count of this. -
If this.
sampleCount
> 1, descriptor.dimension
must be"2d"
. -
If descriptor.
dimension
is:"1d"
-
-
descriptor.
arrayLayerCount
must be1
.
"2d"
-
-
descriptor.
arrayLayerCount
must be1
.
"2d-array"
"cube"
-
-
descriptor.
arrayLayerCount
must be6
.
"cube-array"
-
-
descriptor.
arrayLayerCount
must be a multiple of6
.
"3d"
-
-
descriptor.
arrayLayerCount
must be1
.
-
-
Let view be a new
GPUTextureView
object. -
Set view.
[[texture]]
to this. -
Set view.
[[descriptor]]
to descriptor. -
If this.
usage
containsRENDER_ATTACHMENT
:-
Let renderExtent be compute render extent(this.
[[size]]
, descriptor.baseMipLevel
). -
Set view.
[[renderExtent]]
to renderExtent.
-
-
GPUTextureView
texture with a GPUTextureViewDescriptor
descriptor run the following steps:
-
Let resolved be a copy of descriptor.
-
If resolved.
format
isundefined
, -
If resolved.
mipLevelCount
isundefined
, set resolved.mipLevelCount
to texture.mipLevelCount
− resolved.baseMipLevel
. -
If resolved.
dimension
isundefined
and texture.dimension
is: -
If resolved.
arrayLayerCount
isundefined
and resolved.dimension
is:"1d"
,"2d"
, or"3d"
-
Set resolved.
arrayLayerCount
to1
. "cube"
-
Set resolved.
arrayLayerCount
to6
. "2d-array"
or"cube-array"
-
Set resolved.
arrayLayerCount
to the array layer count of texture − resolved.baseArrayLayer
.
-
Return resolved.
GPUTexture
texture, run the
following steps:
-
If texture.
dimension
is:"1d"
or"3d"
-
Return
1
. "2d"
-
Return texture.
depthOrArrayLayers
.
-
Let
GPUTextureViewDescriptor
aDescriptor = a.[[descriptor]]
. -
Let
GPUTextureViewDescriptor
bDescriptor = b.[[descriptor]]
. -
Assert: aDescriptor.
mipLevelCount
is notundefined
. -
Assert: bDescriptor.
mipLevelCount
is notundefined
. -
Assert: aDescriptor.
arrayLayerCount
is notundefined
. -
Assert: bDescriptor.
arrayLayerCount
is notundefined
.
Two GPUTextureView
objects a and b are considered texture-view-aliasing if and only if all of the following are true:
-
a.
[[texture]]
== b.[[texture]]
. -
aDescriptor.
aspect
=="all"
, or bDescriptor.aspect
=="all"
, or aDescriptor.aspect
== bDescriptor.aspect
. -
The range formed by aDescriptor.
baseMipLevel
and aDescriptor.mipLevelCount
intersects the range formed by bDescriptor.baseMipLevel
and bDescriptor.mipLevelCount
. -
The range formed by aDescriptor.
baseArrayLayer
and aDescriptor.arrayLayerCount
intersects the range formed by bDescriptor.baseArrayLayer
and bDescriptor.arrayLayerCount
.
Describe this in terms of a "set of subresources of" algorithm.
6.3. Texture Formats
The name of the format specifies the order of components, bits per component, and data type for the component.
-
r
,g
,b
,a
= red, green, blue, alpha -
unorm
= unsigned normalized -
snorm
= signed normalized -
uint
= unsigned int -
sint
= signed int -
float
= floating point
If the format has the -srgb
suffix, then sRGB conversions from gamma to linear
and vice versa are applied during the reading and writing of color values in the
shader. Compressed texture formats are provided by features. Their naming
should follow the convention here, with the texture name as a prefix. e.g. etc2-rgba8unorm
.
The texel block is a single addressable element of the textures in pixel-based GPUTextureFormat
s,
and a single compressed block of the textures in block-based compressed GPUTextureFormat
s.
The texel block width and texel block height specifies the dimension of one texel block.
-
For pixel-based
GPUTextureFormat
s, the texel block width and texel block height are always 1. -
For block-based compressed
GPUTextureFormat
s, the texel block width is the number of texels in each row of one texel block, and the texel block height is the number of texel rows in one texel block. See § 25.1 Texture Format Capabilities for an exhaustive list of values for every texture format.
The texel block size of a GPUTextureFormat
is the number of bytes to store one texel block.
The texel block size of each GPUTextureFormat
is constant except for "stencil8"
, "depth24plus"
, and "depth24plus-stencil8"
.
enum { // 8-bit formats
GPUTextureFormat ,
"r8unorm" ,
"r8snorm" ,
"r8uint" , // 16-bit formats
"r8sint" ,
"r16uint" ,
"r16sint" ,
"r16float" ,
"rg8unorm" ,
"rg8snorm" ,
"rg8uint" , // 32-bit formats
"rg8sint" ,
"r32uint" ,
"r32sint" ,
"r32float" ,
"rg16uint" ,
"rg16sint" ,
"rg16float" ,
"rgba8unorm" ,
"rgba8unorm-srgb" ,
"rgba8snorm" ,
"rgba8uint" ,
"rgba8sint" ,
"bgra8unorm" , // Packed 32-bit formats
"bgra8unorm-srgb" ,
"rgb9e5ufloat" ,
"rgb10a2unorm" , // 64-bit formats
"rg11b10ufloat" ,
"rg32uint" ,
"rg32sint" ,
"rg32float" ,
"rgba16uint" ,
"rgba16sint" , // 128-bit formats
"rgba16float" ,
"rgba32uint" ,
"rgba32sint" , // Depth/stencil formats
"rgba32float" ,
"stencil8" ,
"depth16unorm" ,
"depth24plus" ,
"depth24plus-stencil8" , // "depth32float-stencil8" feature
"depth32float" , // BC compressed formats usable if "texture-compression-bc" is both // supported by the device/user agent and enabled in requestDevice.
"depth32float-stencil8" ,
"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" , // ETC2 compressed formats usable if "texture-compression-etc2" is both // supported by the device/user agent and enabled in requestDevice.
"bc7-rgba-unorm-srgb" ,
"etc2-rgb8unorm" ,
"etc2-rgb8unorm-srgb" ,
"etc2-rgb8a1unorm" ,
"etc2-rgb8a1unorm-srgb" ,
"etc2-rgba8unorm" ,
"etc2-rgba8unorm-srgb" ,
"eac-r11unorm" ,
"eac-r11snorm" ,
"eac-rg11unorm" , // ASTC compressed formats usable if "texture-compression-astc" is both // supported by the device/user agent and enabled in requestDevice.
"eac-rg11snorm" ,
"astc-4x4-unorm" ,
"astc-4x4-unorm-srgb" ,
"astc-5x4-unorm" ,
"astc-5x4-unorm-srgb" ,
"astc-5x5-unorm" ,
"astc-5x5-unorm-srgb" ,
"astc-6x5-unorm" ,
"astc-6x5-unorm-srgb" ,
"astc-6x6-unorm" ,
"astc-6x6-unorm-srgb" ,
"astc-8x5-unorm" ,
"astc-8x5-unorm-srgb" ,
"astc-8x6-unorm" ,
"astc-8x6-unorm-srgb" ,
"astc-8x8-unorm" ,
"astc-8x8-unorm-srgb" ,
"astc-10x5-unorm" ,
"astc-10x5-unorm-srgb" ,
"astc-10x6-unorm" ,
"astc-10x6-unorm-srgb" ,
"astc-10x8-unorm" ,
"astc-10x8-unorm-srgb" ,
"astc-10x10-unorm" ,
"astc-10x10-unorm-srgb" ,
"astc-12x10-unorm" ,
"astc-12x10-unorm-srgb" ,
"astc-12x12-unorm" };
"astc-12x12-unorm-srgb"
The depth component of the "depth24plus"
and "depth24plus-stencil8"
formats may be implemented as either a 24-bit unsigned normalized value (like "depth24unorm")
or a 32-bit IEEE 754 floating point value (like "depth32float"
).
add something on GPUAdapter(?) that gives an estimate of the bytes per texel of "stencil8"
, "depth24plus-stencil8"
, and "depth32float-stencil8"
. [Issue #gpuweb/gpuweb#1887]
The stencil8
format may be implemented as
either a real "stencil8", or "depth24stencil8", where the depth aspect is
hidden and inaccessible.
Note: While the precision of depth32float channels is strictly higher than the precision of depth24unorm channels for all values in the representable range (0.0 to 1.0), note that the set of representable values is not an exact superset: for depth24unorm, 1 ULP has a constant value of 1 / (224 − 1); for depth32float, 1 ULP has a variable value no greater than 1 / (224).
A renderable format is either a color renderable format, or a depth-or-stencil format.
If a format is listed in § 25.1.1 Plain color formats with RENDER_ATTACHMENT
capability, it is a
color renderable format. Any other format is not a color renderable format.
All depth-or-stencil formats are renderable.
Arguments:
-
GPUTextureFormat
format -
GPUTextureAspect
aspect
Returns: GPUTextureFormat
or null
-
If aspect is:
"all"
-
Return format.
"depth-only"
"stencil-only"
-
If format is a depth-stencil-format: Return the aspect-specific format of format according to § 25.1.2 Depth-stencil formats or
null
if the aspect is not present in format.
-
Return
null
.
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 § 25.1 Texture Format Capabilities for information about which GPUTextureFormat
s require features.
GPUTextureFormat
format with logical device device by running the following steps:
-
If format requires a feature and device.
[[features]]
does not contain the feature:-
Throw a
TypeError
.
-
6.4. GPUExternalTexture
A GPUExternalTexture
is a sampleable texture wrapping an external video object.
The contents of a GPUExternalTexture
object are a snapshot and may not change, either from inside WebGPU
(it is only sampleable) or from outside WebGPU (e.g. due to video frame advancement).
Update this description with canvas.
They are bound into bind group layouts using the externalTexture
bind group layout entry member.
External textures use several binding slots: see Exceeds the binding slot limits.
The underlying representation of an external texture is unobservable (except for 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 may not be stable across time, systems, user agents, media sources, or 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 ,DedicatedWorker ),SecureContext ]interface GPUExternalTexture {readonly attribute boolean expired ; };GPUExternalTexture includes GPUObjectBase ;
GPUExternalTexture
has the following internal slots:
[[destroyed]]
, of typeboolean
-
Indicates whether the object has been destroyed (can no longer be used). Initially set to
false
. [[descriptor]]
, of typeGPUExternalTextureDescriptor
-
The descriptor with which the texture was created.
GPUExternalTexture
has the following attributes:
expired
, of type boolean, readonly-
Returns the value of
[[destroyed]]
, which indicates whether the texture has expired or not.
The GPUExternalTexture
interface object (globalThis.GPUExternalTexture
)
has the following internal slots:
[[active_imports]]
, of type list<GPUExternalTexture>-
A list of all imported textures which have not yet been closed. The items in list are checked during each animation frame to determine whether to close them.
6.4.1. Importing External Textures
An external texture is created from an external video object
using importExternalTexture()
.
External textures created from HTMLVideoElement
s are destroyed automatically after the imported
frame is no longer current, instead of manually or upon garbage collection like other resources.
When an external texture expires, its expired
attribute changes to true
.
Applications can use this to determine whether to re-import or not, if their execution is not
already scheduled to match the video’s frame rate.
dictionary :
GPUExternalTextureDescriptor GPUObjectDescriptorBase {required HTMLVideoElement ;
source PredefinedColorSpace = "srgb"; };
colorSpace
importExternalTexture(descriptor)
-
Creates a
GPUExternalTexture
wrapping the provided image source.Called on:GPUDevice
this.Arguments:
Arguments for the GPUDevice.importExternalTexture(descriptor) method. Parameter Type Nullable Optional Description descriptor
GPUExternalTextureDescriptor
✘ ✘ Provides the external image source object (and any creation options). Returns:
GPUExternalTexture
Content timeline steps:
-
Let source be descriptor.
source
. -
Let usability be the result of checking the usability of source (which may throw an exception).
-
If usability is
bad
, throw anInvalidStateError
and stop. -
If source is not origin-clean, throw a
SecurityError
and stop. -
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.
-
Let result be a new
GPUExternalTexture
object wrapping data. -
Add result to
GPUExternalTexture
.[[active_imports]]
. -
Return result.
-
-
For each texture in
GPUExternalTexture
.[[active_imports]]
:-
Let video be texture.
[[descriptor]]
.source
. -
Assert video is an
HTMLVideoElement
. -
If the latest presented frame of video is not the same frame from which texture was imported:
-
Remove texture from
GPUExternalTexture
.[[active_imports]]
. -
Set texture.
[[destroyed]]
totrue
, releasing ownership of the underlying resource.
-
-
Note: An external video texture 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 it is used.
const videoElement= document. createElement( 'video' ); // ... set up videoElement, wait for it to be ready... let externalTexture; function frame() { requestAnimationFrame( frame); // Re-import only if necessary if ( ! externalTexture|| externalTexture. expired) { externalTexture= gpuDevice. importExternalTexture({ source: videoElement}); } // ... render using externalTexture... } requestAnimationFrame( frame);
requestVideoFrameCallback
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);
6.4.2. Sampling External Textures
External textures are represented in WGSL with texture_external
and may be read using textureLoad
and textureSampleLevel
.
The sampler
provided to textureSampleLevel
is used to sample the underlying textures.
The result is in the color space set by colorSpace
.
It is implementation-dependent whether, for any given external texture, the sampler (and filtering)
is applied before or after conversion from underlying values into the specified color space.
Note: If the internal representation is an RGBA plane, sampling behaves as on a regular 2D texture. If there are several underlying planes (e.g. Y+UV), the sampler is used to sample each underlying texture separately, prior to conversion from YUV to the specified color space.
7. Samplers
7.1. GPUSampler
A GPUSampler
encodes transformations and filtering information that can
be used in a shader to interpret texture resource data.
GPUSamplers
are created via GPUDevice.createSampler(optional descriptor)
that returns a new sampler object.
[Exposed =(Window ,DedicatedWorker ),SecureContext ]interface GPUSampler { };GPUSampler includes GPUObjectBase ;
GPUSampler
has the following internal slots:
[[descriptor]]
, of typeGPUSamplerDescriptor
, readonly-
The
GPUSamplerDescriptor
with which theGPUSampler
was created. [[isComparison]]
, of typeboolean
-
Whether the
GPUSampler
is used as a comparison sampler. [[isFiltering]]
, of typeboolean
-
Whether the
GPUSampler
weights multiple samples of a texture.
7.2. Sampler Creation
7.2.1. GPUSamplerDescriptor
A GPUSamplerDescriptor
specifies the options to use to create a GPUSampler
.
dictionary :
GPUSamplerDescriptor GPUObjectDescriptorBase {GPUAddressMode addressModeU = "clamp-to-edge";GPUAddressMode addressModeV = "clamp-to-edge";GPUAddressMode addressModeW = "clamp-to-edge";GPUFilterMode magFilter = "nearest";GPUFilterMode minFilter = "nearest";GPUMipmapFilterMode mipmapFilter = "nearest";float lodMinClamp = 0;float lodMaxClamp = 32;GPUCompareFunction compare ; [Clamp ]unsigned short maxAnisotropy = 1; };
addressModeU
, 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 sample footprint is smaller than or equal to one texel.
minFilter
, of type GPUFilterMode, defaulting to"nearest"
-
Specifies the sampling behavior when the sample footprint is larger than one texel.
mipmapFilter
, of type GPUMipmapFilterMode, defaulting to"nearest"
-
Specifies behavior for sampling between mipmap levels.
lodMinClamp
, of type float, defaulting to0
lodMaxClamp
, of type float, defaulting to32
-
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 to1
-
Specifies the maximum anisotropy value clamp used by the sampler.
Note: Most implementations support
maxAnisotropy
values in range between 1 and 16, inclusive. The used value ofmaxAnisotropy
will be clamped to the maximum value that the platform supports.
explain how LOD is calculated and if there are differences here between platforms.
explain what anisotropic sampling is
GPUAddressMode
describes the behavior of the sampler if the sample footprint extends beyond
the bounds of the sampled texture.
Describe a "sample footprint" in greater detail.
enum {
GPUAddressMode "clamp-to-edge" ,"repeat" ,"mirror-repeat" };
"clamp-to-edge"
-
Texture coordinates are clamped between 0.0 and 1.0, inclusive.
"repeat"
-
Texture coordinates wrap to the other side of the texture.
"mirror-repeat"
-
Texture coordinates wrap to the other side of the texture, but the texture is flipped when the integer part of the coordinate is odd.
GPUFilterMode
and GPUMipmapFilterMode
describe the behavior of the sampler if the sample footprint does not exactly
match one texel.
enum {
GPUFilterMode "nearest" ,"linear" };enum {
GPUMipmapFilterMode ,
"nearest" };
"linear"
"nearest"
-
Return the value of the texel nearest to the texture coordinates.
"linear"
-
Select two texels in each dimension and return a linear interpolation between their values.
GPUCompareFunction
specifies the behavior of a comparison sampler. If a comparison sampler is
used in a shader, an input value is compared to the sampled texture value, and the result of this
comparison test (0.0f for pass, or 1.0f for fail) is used in the filtering operation.
describe how filtering interacts with comparison sampling.
enum {
GPUCompareFunction "never" ,"less" ,"equal" ,"less-equal" ,"greater" ,"not-equal" ,"greater-equal" ,"always" };
"never"
-
Comparison tests never pass.
"less"
-
A provided value passes the comparison test if it is less than the sampled value.
"equal"
-
A provided value passes the comparison test if it is equal to the sampled value.
"less-equal"
-
A provided value passes the comparison test if it is less than or equal to the sampled value.
"greater"
-
A provided value passes the comparison test if it is greater than the sampled value.
"not-equal"
-
A provided value passes the comparison test if it is not equal to the sampled value.
"greater-equal"
-
A provided value passes the comparison test if it is greater than or equal to the sampled value.
"always"
-
Comparison tests always pass.
createSampler(descriptor)
-
Creates a
GPUSampler
.Called on:GPUDevice
this.Arguments:
Arguments for the GPUDevice.createSampler(descriptor) method. Parameter Type Nullable Optional Description descriptor
GPUSamplerDescriptor
✘ ✔ Description of the GPUSampler
to create.Returns:
GPUSampler
Content timeline steps:
-
Let s be a new
GPUSampler
object. -
Issue the initialization steps on the Device timeline of this.
-
Return s.
Device timeline initialization steps:-
If any of the following conditions are unsatisfied generate a validation error, make s invalid, and stop.
-
this is valid.
-
descriptor.
lodMinClamp
≥ 0. -
descriptor.
lodMaxClamp
≥ descriptor.lodMinClamp
. -
descriptor.
maxAnisotropy
≥ 1.Note: Most implementations support
maxAnisotropy
values in range between 1 and 16, inclusive. The providedmaxAnisotropy
value will be clamped to the maximum value that the platform supports. -
If descriptor.
maxAnisotropy
> 1:-
descriptor.
magFilter
, descriptor.minFilter
, and descriptor.mipmapFilter
must be"linear"
.
-
-
-
Set s.
[[descriptor]]
to descriptor. -
Set s.
[[isComparison]]
tofalse
if thecompare
attribute of s.[[descriptor]]
isnull
or undefined. Otherwise, set it totrue
. -
Set s.
[[isFiltering]]
tofalse
if none ofminFilter
,magFilter
, ormipmapFilter
has the value of"linear"
. Otherwise, set it totrue
.
-
GPUSampler
that does trilinear filtering and repeats texture coordinates:
const sampler= gpuDevice. createSampler({ addressModeU: 'repeat' , addressModeV: 'repeat' , magFilter: 'linear' , minFilter: 'linear' , mipmapFilter: 'linear' , });
8. Resource Binding
8.1. GPUBindGroupLayout
A GPUBindGroupLayout
defines the interface between a set of resources bound in a GPUBindGroup
and their accessibility in shader stages.
[Exposed =(Window ,DedicatedWorker ),SecureContext ]interface GPUBindGroupLayout { };GPUBindGroupLayout includes GPUObjectBase ;
GPUBindGroupLayout
has the following internal slots:
[[descriptor]]
8.1.1. Creation
A GPUBindGroupLayout
is created via GPUDevice.createBindGroupLayout()
.
dictionary :
GPUBindGroupLayoutDescriptor GPUObjectDescriptorBase {required sequence <GPUBindGroupLayoutEntry >; };
entries
A GPUBindGroupLayoutEntry
describes a single shader resource binding to be included in a GPUBindGroupLayout
.
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 aGPUBindGroupEntry.binding
and a @binding attribute in theGPUShaderModule
. visibility
, of type GPUShaderStageFlags-
A bitset of the members of
GPUShaderStage
. Each set bit indicates that aGPUBindGroupLayoutEntry
's resource will be accessible from the associated shader stage. buffer
, of type GPUBufferBindingLayout-
When not
undefined
, indicates the binding resource type for thisGPUBindGroupLayoutEntry
isGPUBufferBinding
. sampler
, of type GPUSamplerBindingLayout-
When not
undefined
, indicates the binding resource type for thisGPUBindGroupLayoutEntry
isGPUSampler
. texture
, of type GPUTextureBindingLayout-
When not
undefined
, indicates the binding resource type for thisGPUBindGroupLayoutEntry
isGPUTextureView
. storageTexture
, of type GPUStorageTextureBindingLayout-
When not
undefined
, indicates the binding resource type for thisGPUBindGroupLayoutEntry
isGPUTextureView
. externalTexture
, of type GPUExternalTextureBindingLayout-
When not
undefined
, indicates the binding resource type for thisGPUBindGroupLayoutEntry
isGPUExternalTexture
.
typedef [EnforceRange ]unsigned long ; [
GPUShaderStageFlags Exposed =(Window ,DedicatedWorker )]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:
Binding member | Resource type | Binding type | Binding usage |
---|---|---|---|
buffer
| GPUBufferBinding
| "uniform"
| constant |
"storage"
| storage | ||
"read-only-storage"
| storage-read | ||
sampler
| GPUSampler
| "filtering"
| constant |
"non-filtering"
| |||
"comparison"
| |||
texture
| GPUTextureView
| "float"
| constant |
"unfilterable-float"
| |||
"depth"
| |||
"sint"
| |||
"uint"
| |||
storageTexture
| GPUTextureView
| "write-only"
| storage |
externalTexture
| GPUExternalTexture
| constant |
GPUBindGroupLayoutEntry
values entries exceeds the binding slot limits of supported limits limits if the number of slots used toward a limit exceeds the supported value in limits.
Each entry may use multiple slots toward multiple limits.
-
For each entry in entries, if:
- entry.
buffer
?.type
is"uniform"
and entry.buffer
?.hasDynamicOffset
istrue
-
Consider 1
maxDynamicUniformBuffersPerPipelineLayout
slot to be used. - entry.
buffer
?.type
is"storage"
and entry.buffer
?.hasDynamicOffset
istrue
-
Consider 1
maxDynamicStorageBuffersPerPipelineLayout
slot to be used.
- entry.
-
For each shader stage stage in «
VERTEX
,FRAGMENT
,COMPUTE
»:-
For each entry in entries for which entry.
visibility
contains stage, if:- entry.
buffer
?.type
is"uniform"
-
Consider 1
maxUniformBuffersPerShaderStage
slot to be used. - entry.
buffer
?.type
is"storage"
or"read-only-storage"
-
Consider 1
maxStorageBuffersPerShaderStage
slot to be used. - entry.
sampler
is notundefined
-
Consider 1
maxSamplersPerShaderStage
slot to be used. - entry.
texture
is notundefined
-
Consider 1
maxSampledTexturesPerShaderStage
slot to be used. - entry.
storageTexture
is notundefined
-
Consider 1
maxStorageTexturesPerShaderStage
slot to be used. - entry.
externalTexture
is notundefined
-
Consider 4
maxSampledTexturesPerShaderStage
slot, 1maxSamplersPerShaderStage
slot, and 1maxUniformBuffersPerShaderStage
slot to be used.
- entry.
-
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 tofalse
-
Indicates whether this binding requires a dynamic offset.
minBindingSize
, of type GPUSize64, defaulting to0
-
Indicates the minimum buffer binding size.
Bindings are always validated against this size in
createBindGroup()
.If this is not
0
, pipeline creation additionally validates that this value is large enough for the bindings declared in the shader.If this is
0
, draw/dispatch commands additionally validate that each binding in theGPUBindGroup
is large enough for the bindings declared in the shader.Note: Similar execution-time validation is theoretically possible for other binding-related fields specified for early validation, like
sampleType
andformat
, 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 forminBindingSize
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 ; };
consider making sampleType
truly optional.
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 tofalse
-
Indicates whether or not texture views bound to this binding must be multisampled.
enum {
GPUStorageTextureAccess };
"write-only" dictionary {
GPUStorageTextureBindingLayout GPUStorageTextureAccess access = "write-only";required GPUTextureFormat format ;GPUTextureViewDimension viewDimension = "2d"; };
consider making format
truly optional.
GPUStorageTextureBindingLayout
dictionaries have the following members:
access
, of type GPUStorageTextureAccess, defaulting to"write-only"
-
Indicates whether texture views bound to this binding will be bound for read-only or write-only access.
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 internal slots:
[[entryMap]]
, of type ordered map<GPUSize32
,GPUBindGroupLayoutEntry
>-
The map of binding indices pointing to the
GPUBindGroupLayoutEntry
s, which thisGPUBindGroupLayout
describes. [[dynamicOffsetCount]]
, of typeGPUSize32
-
The number of buffer bindings with dynamic offsets in this
GPUBindGroupLayout
. [[exclusivePipeline]]
, of typeGPUPipelineBase
?, initiallynull
-
The pipeline that created this
GPUBindGroupLayout
, if it was created as part of a default pipeline layout. If notnull
,GPUBindGroup
s created with thisGPUBindGroupLayout
can only be used with the specifiedGPUPipelineBase
.
createBindGroupLayout(descriptor)
-
Creates a
GPUBindGroupLayout
.Called on:GPUDevice
this.Arguments:
Arguments for the GPUDevice.createBindGroupLayout(descriptor) method. Parameter Type Nullable Optional Description descriptor
GPUBindGroupLayoutDescriptor
✘ ✘ Description of the GPUBindGroupLayout
to create.Returns:
GPUBindGroupLayout
Content timeline steps:
-
For each
GPUBindGroupLayoutEntry
entry in descriptor.entries
:-
If entry.
storageTexture
is notundefined
:-
Validate texture format required features for entry.
storageTexture
.format
with this.[[device]]
.
-
-
-
Let layout be a new
GPUBindGroupLayout
object. -
Issue the initialization steps on the Device timeline of this.
-
Return layout.
Device timeline initialization steps:-
If any of the following conditions are unsatisfied generate a validation error, make layout invalid, and stop.
-
this is valid.
-
The
binding
of each entry in descriptor is unique. -
The
binding
of each entry in descriptor must be < 65536. -
descriptor.
entries
must not exceed the binding slot limits of this.[[device]]
.[[limits]]
. -
For each
GPUBindGroupLayoutEntry
entry in descriptor.entries
:-
Let bufferLayout be entry.
buffer
-
Let samplerLayout be entry.
sampler
-
Let textureLayout be entry.
texture
-
Let storageTextureLayout be entry.
storageTexture
-
Exactly one of bufferLayout, samplerLayout, textureLayout, or storageTextureLayout are not
undefined
. -
If entry.
visibility
includesVERTEX
:-
entry.
storageTexture
?.access
must not be"write-only"
.
-
If the textureLayout is not
undefined
and textureLayout.multisampled
istrue
:-
textureLayout.
viewDimension
is"2d"
. -
textureLayout.
sampleType
is not"float"
.
-
-
If storageTextureLayout is not
undefined
:-
storageTextureLayout.
viewDimension
is not"cube"
or"cube-array"
. -
storageTextureLayout.
format
must be a format which can support storage usage.
-
-
-
-
Set layout.
[[descriptor]]
to descriptor. -
Set layout.
[[dynamicOffsetCount]]
to the number of entries in descriptor wherebuffer
is notundefined
andbuffer
.hasDynamicOffset
istrue
. -
For each
GPUBindGroupLayoutEntry
entry in descriptor.entries
:-
Insert entry into layout.
[[entryMap]]
with the key of entry.binding
.
-
-
8.1.2. Compatibility
GPUBindGroupLayout
objects a and b are considered group-equivalent if and only if all of the following conditions are satisfied:
-
for any binding number binding, one of the following conditions is satisfied:
-
it’s missing from both a.
[[entryMap]]
and b.[[entryMap]]
. -
a.
[[entryMap]]
[binding] == b.[[entryMap]]
[binding]
-
If bind groups layouts are group-equivalent they can be interchangeably used in all contents.
8.2. GPUBindGroup
A GPUBindGroup
defines a set of resources to be bound together in a group
and how the resources are used in shader stages.
[Exposed =(Window ,DedicatedWorker ),SecureContext ]interface GPUBindGroup { };GPUBindGroup includes GPUObjectBase ;
A GPUBindGroup
object has the following internal slots:
[[layout]]
, of typeGPUBindGroupLayout
, readonly-
The
GPUBindGroupLayout
associated with thisGPUBindGroup
. [[entries]]
, of type sequence<GPUBindGroupEntry
>, readonly-
The set of
GPUBindGroupEntry
s thisGPUBindGroup
describes. [[usedResources]]
, of type ordered map<subresource, list<internal usage>>, readonly-
The set of buffer and texture subresources used by this bind group, associated with lists of the internal usage flags.
8.2.1. Bind Group Creation
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 aGPUBindGroupLayoutEntry.binding
and a @binding attribute in theGPUShaderModule
. resource
, of type GPUBindingResource-
The resource to bind, which may be a
GPUSampler
,GPUTextureView
,GPUExternalTexture
, orGPUBufferBinding
.
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 to0
-
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
undefined
, specifies the range starting atoffset
and ending at the end ofbuffer
.
createBindGroup(descriptor)
-
Creates a
GPUBindGroup
.Called on:GPUDevice
this.Arguments:
Arguments for the GPUDevice.createBindGroup(descriptor) method. Parameter Type Nullable Optional Description descriptor
GPUBindGroupDescriptor
✘ ✘ Description of the GPUBindGroup
to create.Returns:
GPUBindGroup
Content timeline steps:
-
Let bindGroup be a new
GPUBindGroup
object. -
Issue the initialization steps on the Device timeline of this.
-
Return bindGroup.
Device timeline initialization steps:-
Let limits be this.
[[device]]
.[[limits]]
. -
If any of the following conditions are unsatisfied generate a validation error, make bindGroup invalid, and stop.
-
descriptor.
layout
is valid to use with this. -
The number of
entries
of descriptor.layout
is exactly equal to the number of descriptor.entries
.
For each
GPUBindGroupEntry
bindingDescriptor in descriptor.entries
:-
Let resource be bindingDescriptor.
resource
. -
There is exactly one
GPUBindGroupLayoutEntry
layoutBinding in descriptor.layout
.entries
such that layoutBinding.binding
equals to bindingDescriptor.binding
. -
If the defined binding member for layoutBinding is
sampler
-
-
resource is a
GPUSampler
. -
resource is valid to use with this.
-
If layoutBinding.
sampler
.type
is:"filtering"
-
resource.
[[isComparison]]
isfalse
. "non-filtering"
-
resource.
[[isFiltering]]
isfalse
. resource.[[isComparison]]
isfalse
. "comparison"
-
resource.
[[isComparison]]
istrue
.
-
texture
-
-
resource is a
GPUTextureView
. -
resource is valid to use with this.
-
Let texture be resource.
[[texture]]
. -
layoutBinding.
texture
.viewDimension
is equal to resource’sdimension
. -
layoutBinding.
texture
.sampleType
is compatible with resource’sformat
. -
texture’s
usage
includesTEXTURE_BINDING
. -
If layoutBinding.
texture
.multisampled
istrue
, texture’ssampleCount
>1
, Otherwise texture’ssampleCount
is1
.
-
storageTexture
-
-
resource is a
GPUTextureView
. -
resource is valid to use with this.
-
Let texture be resource.
[[texture]]
. -
layoutBinding.
storageTexture
.viewDimension
is equal to resource’sdimension
. -
layoutBinding.
storageTexture
.format
is equal to resource.[[descriptor]]
.format
. -
texture’s
usage
includesSTORAGE_BINDING
. -
resource.
[[descriptor]]
.mipLevelCount
must be 1.
-
buffer
-
-
resource is a
GPUBufferBinding
. -
resource.
buffer
is valid to use with this. -
The bound part designated by resource.
offset
and resource.size
resides inside the buffer and has non-zero size. -
effective buffer binding size(resource), ≥ layoutBinding.
buffer
.minBindingSize
. -
If layoutBinding.
buffer
.type
is"uniform"
-
-
effective buffer binding size(resource) ≤ limits.
maxUniformBufferBindingSize
. -
resource.
offset
is a multiple of limits.minUniformBufferOffsetAlignment
.
"storage"
or"read-only-storage"
-
-
effective buffer binding size(resource) ≤ limits.
maxStorageBufferBindingSize
. -
resource.
offset
is a multiple of limits.minStorageBufferOffsetAlignment
.
-
externalTexture
-
-
resource is a
GPUExternalTexture
. -
resource is valid to use with this.
-
-
-
Let bindGroup.
[[layout]]
= descriptor.layout
. -
Let bindGroup.
[[entries]]
= descriptor.entries
. -
Let bindGroup.
[[usedResources]]
= {}. -
For each
GPUBindGroupEntry
bindingDescriptor in descriptor.entries
:-
Let internalUsage be the binding usage for layoutBinding.
-
Each subresource seen by resource is added to
[[usedResources]]
as internalUsage.
-
-
GPUBufferBinding
objects a and b are considered buffer-binding-aliasing if and only if all of the following are true:
Define how a range is formed by offset/size when size can be undefined.
8.3. GPUPipelineLayout
A GPUPipelineLayout
defines the mapping between resources of all GPUBindGroup
objects set up during command encoding in setBindGroup
, and the shaders of the pipeline set by GPURenderCommandsMixin.setPipeline
or GPUComputePassEncoder.setPipeline
.
The full binding address of a resource can be defined as a trio of:
-
shader stage mask, to which the resource is visible
-
bind group index
-
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 ,DedicatedWorker ),SecureContext ]interface GPUPipelineLayout { };GPUPipelineLayout includes GPUObjectBase ;
GPUPipelineLayout
has the following internal slots:
[[bindGroupLayouts]]
, of type list<GPUBindGroupLayout
>-
The
GPUBindGroupLayout
objects provided at creation inGPUPipelineLayoutDescriptor.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.
GPUComputePipeline
object X was created with GPUPipelineLayout.bindGroupLayouts
A, B, C. GPUComputePipeline
object Y was created with GPUPipelineLayout.bindGroupLayouts
A, D, C. Supposing the command encoding sequence has two dispatches:
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.
should this example and the note be moved to some "best practices" document?
Note: the expected usage of the GPUPipelineLayout
is placing the most common and the least frequently changing bind groups at the "bottom" of the layout, meaning lower bind group slot numbers, like 0 or 1. The more frequently a bind group needs to change between draw calls, the higher its index should be. This general guideline allows the user agent to minimize state changes between draw calls, and consequently lower the CPU overhead.
8.3.1. Creation
A GPUPipelineLayout
is created via GPUDevice.createPipelineLayout()
.
dictionary :
GPUPipelineLayoutDescriptor GPUObjectDescriptorBase {required sequence <GPUBindGroupLayout >bindGroupLayouts ; };
GPUPipelineLayoutDescriptor
dictionaries define all the GPUBindGroupLayout
s used by a
pipeline, and have the following members:
bindGroupLayouts
, of type sequence<GPUBindGroupLayout>-
A list of
GPUBindGroupLayout
s the pipline will use. Each element corresponds to a @group attribute in theGPUShaderModule
, with theN
th element corresponding with@group(N)
.
createPipelineLayout(descriptor)
-
Creates a
GPUPipelineLayout
.Called on:GPUDevice
this.Arguments:
Arguments for the GPUDevice.createPipelineLayout(descriptor) method. Parameter Type Nullable Optional Description descriptor
GPUPipelineLayoutDescriptor
✘ ✘ Description of the GPUPipelineLayout
to create.Returns:
GPUPipelineLayout
Content timeline steps:
-
Let pl be a new
GPUPipelineLayout
object. -
Issue the initialization steps on the Device timeline of this.
-
Return pl.
Device timeline initialization steps:-
Let limits be this.
[[device]]
.[[limits]]
. -
Let allEntries be the result of concatenating bgl.
[[descriptor]]
.entries
for all bgl in descriptor.bindGroupLayouts
. -
If any of the following conditions are unsatisfied generate a validation error, make pl invalid, and stop.
-
Every
GPUBindGroupLayout
in descriptor.bindGroupLayouts
must be valid to use with this and have a[[exclusivePipeline]]
ofnull
. -
The size of descriptor.
bindGroupLayouts
must be ≤ limits.maxBindGroups
. -
allEntries must not exceed the binding slot limits of limits.
-
-
Set the pl.
[[bindGroupLayouts]]
to descriptor.bindGroupLayouts
.
-
Note: two GPUPipelineLayout
objects are considered equivalent for any usage
if their internal [[bindGroupLayouts]]
sequences contain GPUBindGroupLayout
objects that are group-equivalent.
8.4. Example
GPUBindGroupLayout
that describes a binding with a uniform buffer, a texture, and a sampler.
Then create a GPUBindGroup
and a GPUPipelineLayout
using the GPUBindGroupLayout
.
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] });
9. Shader Modules
9.1. GPUShaderModule
[Exposed =(Window ,DedicatedWorker ),SecureContext ]interface GPUShaderModule {Promise <GPUCompilationInfo >compilationInfo (); };GPUShaderModule includes GPUObjectBase ;
GPUShaderModule
is a reference to an internal shader module object.
9.1.1. Shader Module Creation
dictionary :
GPUShaderModuleDescriptor GPUObjectDescriptorBase {required USVString code ;object sourceMap ;record <USVString ,GPUShaderModuleCompilationHint >hints ; };
code
, of type USVString-
The WGSL source code for the shader module.
sourceMap
, of type object-
If defined MAY be interpreted as a source-map-v3 format.
Source maps are optional, but serve as a standardized way to support dev-tool integration such as source-language debugging [SourceMap]. WGSL names (identifiers) in source maps follow the rules defined in WGSL identifier comparison.
hints
, of type record<USVString, GPUShaderModuleCompilationHint>-
If defined maps an entry point name from the shader to a
GPUShaderModuleCompilationHint
. No validation is performed with any of theseGPUShaderModuleCompilationHint
. Implementations should use any information present in theGPUShaderModuleCompilationHint
to perform as much compilation as is possible withincreateShaderModule()
. Entry point names follow the rules defined in WGSL identifier comparison.Note: Supplying information in
hints
does not have any observable effect, other than performance. 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 increateShaderModule()
rather than multiple times in the multiple calls tocreateComputePipeline()
/createRenderPipeline()
.
createShaderModule(descriptor)
-
Creates a
GPUShaderModule
.Called on:GPUDevice
this.Arguments:
Arguments for the GPUDevice.createShaderModule(descriptor) method. Parameter Type Nullable Optional Description descriptor
GPUShaderModuleDescriptor
✘ ✘ Description of the GPUShaderModule
to create.Returns:
GPUShaderModule
Content timeline steps:
-
Let sm be a new
GPUShaderModule
object. -
Issue the initialization steps on the Device timeline of this.
-
Return sm.
Device timeline initialization steps:-
If any of the following conditions are unsatisfied generate a validation error, make sm invalid, and stop.
-
this is valid.
-
Describe remaining
createShaderModule()
validation and algorithm steps.Note: User agents should not include error messages or shader text in themessage
text of validation errors arising here: these details are accessible viacompilationInfo()
. 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 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 aGPUCompilationInfo
object to the console. -
GPUShaderModule
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[input.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, });
9.1.1.1. Shader Module Compilation Hints
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 GPUPipelineLayout or GPUAutoLayoutMode )layout ; };
layout
, of type(GPUPipelineLayout or GPUAutoLayoutMode)
-
A
GPUPipelineLayout
that theGPUShaderModule
may be used with in a futurecreateComputePipeline()
orcreateRenderPipeline()
call. If set to"auto"
the layout will be the default pipeline layout for the entry point associated with this hint will be used.
createShaderModule()
and createComputePipeline()
/ createRenderPipeline()
.
If an author is unable to provide hint information at the time of calling createShaderModule()
, they should usually not delay calling createShaderModule()
; but should instead just omit the unknown information from hints
or GPUShaderModuleCompilationHint
. Omitting this information
may cause compilation to be deferred to createComputePipeline()
/ createRenderPipeline()
.
If an author is not confident that the hint information passed to createShaderModule()
will match the information later passed to createComputePipeline()
/ createRenderPipeline()
with that same module, they should avoid passing that
information to createShaderModule()
, as passing mismatched information to createShaderModule()
may cause unnecessary compilations to occur.
9.1.2. Shader Module Compilation Information
enum {
GPUCompilationMessageType ,
"error" ,
"warning" }; [
"info" Exposed =(Window ,DedicatedWorker ),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 ,DedicatedWorker ),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-
A human-readable string containing the message generated during the shader compilation.
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
themessage
corresponds to. Value is one-based, such that a lineNum of1
indicates the first line of the shadercode
.If the
message
corresponds to a substring this points to the line on which the substring begins. Must be0
if themessage
does not correspond to any specific point in the shadercode
.Reference WGSL spec when it defines what a line is. [Issue #gpuweb/gpuweb#2435]
linePos
, of type unsigned long long, readonly-
The offset, in UTF-16 code units, from the beginning of line
lineNum
of the shadercode
to the point or beginning of the substring that themessage
corresponds to. Value is one-based, such that alinePos
of1
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 be0
if themessage
does not correspond to any specific point in the shadercode
. 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 thatmessage
corresponds to. Must reference the same position aslineNum
andlinePos
. Must be0
if themessage
does not correspond to any specific point in the shadercode
. 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 thenlength
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.
compilationInfo()
-
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
.Called on:GPUShaderModule
thisReturns:
Promise
<GPUCompilationInfo
>Describe
compilationInfo()
algorithm steps.
10. Pipelines
A pipeline, be it GPUComputePipeline
or GPURenderPipeline
,
represents the complete function done by a combination of the GPU hardware, the driver,
and the user agent, that process the input data in the shape of bindings and vertex buffers,
and produces some output, like the colors in the output render targets.
Structurally, the pipeline consists of a sequence of programmable stages (shaders) and fixed-function states, such as the blending modes.
Note: Internally, depending on the target platform, the driver may convert some of the fixed-function states into shader code, and link it together with the shaders provided by the user. This linking is one of the reason the object is created as a whole.
This combination state is created as a single object
(by GPUDevice.createComputePipeline()
or GPUDevice.createRenderPipeline()
),
and switched as one
(by GPUComputePassEncoder.setPipeline
or GPURenderCommandsMixin.setPipeline
correspondingly).
10.1. Base pipelines
enum {
GPUAutoLayoutMode };
"auto" dictionary :
GPUPipelineDescriptorBase GPUObjectDescriptorBase {required (GPUPipelineLayout or GPUAutoLayoutMode ); };
layout interface mixin { [
GPUPipelineBase NewObject ]GPUBindGroupLayout getBindGroupLayout (unsigned long index ); };
GPUPipelineBase
has the following internal slots:
[[layout]]
, of typeGPUPipelineLayout
-
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 theGPUPipelineBase
'sGPUBindGroupLayout
atindex
.Called on:GPUPipelineBase
thisArguments:
Arguments for the GPUPipelineBase.getBindGroupLayout(index) method. Parameter Type Nullable Optional Description index
unsigned long
✘ ✘ Index into the pipeline layout’s [[bindGroupLayouts]]
sequence.Returns:
GPUBindGroupLayout
-
If index ≥ this.
[[device]]
.[[limits]]
.maxBindGroups
:-
Throw a
RangeError
.
-
-
If this is not valid:
-
Return a new error
GPUBindGroupLayout
.
-
-
If index ≥ the size of this.
[[layout]]
.[[bindGroupLayouts]]
:-
Return a new error
GPUBindGroupLayout
.
-
-
Return a new
GPUBindGroupLayout
object that references the same internal object as this.[[layout]]
.[[bindGroupLayouts]]
[index].
Specify this more properly once we have internal objects for
GPUBindGroupLayout
. Alternatively only spec is as a new internal objects that’s group-equivalentNote: Only returning new
GPUBindGroupLayout
objects ensures no synchronization is necessary between the Content timeline and the Device timeline. -
10.1.1. Default pipeline layout
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.
To create a default pipeline layout for GPUPipelineBase
pipeline,
run the following steps:
-
Let groupDescs be a sequence of device.
[[limits]]
.maxBindGroups
newGPUBindGroupLayoutDescriptor
objects. -
For each groupDesc in groupDescs:
-
Set groupDesc.
entries
to an empty sequence.
-
-
For each
GPUProgrammableStage
stageDesc in the descriptor used to create pipeline:-
Let stageInfo be the "reflection information" for stageDesc.
Define the reflection information concept so that this spec can interface with the WGSL spec and get information what the interface is for a
GPUShaderModule
for a specific entrypoint. -
Let shaderStage be the
GPUShaderStageFlags
for stageDesc.entryPoint
in stageDesc.module
. -
For each resource resource in stageInfo’s resource interface:
-
Let group be resource’s "group" decoration.
-
Let binding be resource’s "binding" decoration.
-
Let entry be a new
GPUBindGroupLayoutEntry
. -
Set entry.
binding
to binding. -
Set entry.
visibility
to shaderStage. -
If resource is for a sampler binding:
-
Let samplerLayout be a new
GPUSamplerBindingLayout
. -
Set entry.
sampler
to samplerLayout.
-
-
If resource is for a comparison sampler binding:
-
Let samplerLayout be a new
GPUSamplerBindingLayout
. -
Set samplerLayout.
type
to"comparison"
. -
Set entry.
sampler
to samplerLayout.
-
-
If resource is for a buffer binding:
-
Let bufferLayout be a new
GPUBufferBindingLayout
. -
Set bufferLayout.
minBindingSize
to resource’s minimum buffer binding size.link to a definition for "minimum buffer binding size" in the "reflection information".
-
If resource is for a read-only storage buffer:
-
Set bufferLayout.
type
to"read-only-storage"
.
-
-
If resource is for a storage buffer:
-
Set entry.
buffer
to bufferLayout.
-
-
If resource is for a sampled texture binding:
-
Let textureLayout be a new
GPUTextureBindingLayout
. -
If resource is a depth texture binding:
-
Set textureLayout.
sampleType
to"depth"
Else if the sampled type of resource is:
f32
and resource is statically used with a textureSample* builtin in the shader-
Set textureLayout.
sampleType
to"float"
f32
otherwise-
Set textureLayout.
sampleType
to"unfilterable-float"
i32
-
Set textureLayout.
sampleType
to"sint"
u32
-
Set textureLayout.
sampleType
to"uint"
-
-
Set textureLayout.
viewDimension
to resource’s dimension. -
If resource is for a multisampled texture:
-
Set textureLayout.
multisampled
totrue
.
-
-
Set entry.
texture
to textureLayout.
-
-
If resource is for a storage texture binding:
-
Let storageTextureLayout be a new
GPUStorageTextureBindingLayout
. -
Set storageTextureLayout.
format
to resource’s format. -
Set storageTextureLayout.
viewDimension
to resource’s dimension. -
If resource is for a write-only storage texture:
-
Set storageTextureLayout.
access
to"write-only"
.
-
-
Set entry.
storageTexture
to storageTextureLayout.
-
-
If groupDescs[group] has an entry previousEntry with
binding
equal to binding:-
If entry has different
visibility
than previousEntry:-
Add the bits set in entry.
visibility
into previousEntry.visibility
-
-
If resource is for a buffer binding and entry has greater
buffer
.minBindingSize
than previousEntry:-
Set previousEntry.
buffer
.minBindingSize
to entry.buffer
.minBindingSize
.
-
-
If resource is a sampled texture binding and entry has different
texture
.sampleType
than previousEntry and both entry and previousEntry havetexture
.sampleType
of either"float"
or"unfilterable-float"
:-
Set previousEntry.
texture
.sampleType
to"float"
.
-
-
If any other property is unequal between entry and previousEntry:
-
Return
null
(which will cause the creation of the pipeline to fail).
-
-
-
Else
-
Append entry to groupDescs[group].
-
-
-
-
Let groupLayouts be a new sequence.
-
For each groupDesc in groupDescs:
-
Let bindGroupLayout be the result of calling device.
createBindGroupLayout()
(groupDesc). -
Set bindGroupLayout.
[[exclusivePipeline]]
to pipeline. -
Append bindGroupLayout to groupLayouts.
-
-
Let desc be a new
GPUPipelineLayoutDescriptor
. -
Set desc.
bindGroupLayouts
to groupLayouts. -
Return device.
createPipelineLayout()
(desc).
This fills the pipeline layout with empty bindgroups. Revisit once the behavior of empty bindgroups is specified.
10.1.2. GPUProgrammableStage
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 ;required 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. constants
, of type record<USVString, GPUPipelineConstantValue>-
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 numeric ID of the constant, if one is specified, and otherwise the constant’s identifier name). WGSL names (identifiers) in source maps follow the rules defined in WGSL identifier comparison.
The key of each key-value pair must equal the identifier string of one such constant. When the pipeline is executed, that constant will have the specified value.
Values are specified as
GPUPipelineConstantValue
, which is adouble
which is converted to the WGSL data type of the corresponding pipeline-overridable constant (bool
,i32
,u32
, orf32
) via an IDL value (boolean
,long
,unsigned long
, orfloat
). If the"shader-f16"
feature is enabled, a pipeline-overridable constant may be of WGSL data typef16
. The specifiedGPUPipelineConstantValue
for a pipeline-overridable constant off16
is converted tofloat
via an IDL value, then converted to WGSL typef16
via WGSL f32 to f16 conversion defined in WGSL specification.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" } }
Arguments:
-
GPUShaderStage
stage -
GPUProgrammableStage
descriptor -
GPUPipelineLayout
layout
Return true
if all of the following conditions are met:
-
descriptor.
module
must be a validGPUShaderModule
. -
descriptor.
module
must contain an entry point, for shader stage stage, named descriptor.entryPoint
. -
For each binding that is statically used by the shader entry point:
-
validating shader binding(binding, layout) must return
true
.
-
-
For each texture sampling shader call that is statically used by the entry point:
-
Let texture be the
GPUBindGroupLayoutEntry
corresponding to the sampled texture in the call. -
Let sampler be the
GPUBindGroupLayoutEntry
corresponding to the used sampler in the call. -
If sampler.
type
is"filtering"
, then texture.sampleType
must be"float"
.
-
-
For each key in the keys of descriptor.
constants
:-
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.
-
-
For each pipeline-overridable constant identifier string key which is statically accessed by the shader entry point:
-
If the pipeline-overridable constant identified by key does not have a default value, descriptor.
constants
must contain key.
-
A return value of false
corresponds to a pipeline-creation error.
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 aGPUBindGroupLayoutEntry
entry whose entry.binding
== bindIndex. -
If the defined binding member for entry is:
buffer
-
"uniform"
-
variable is declared with address space
uniform
. "storage"
-
variable is declared with address space
storage
and access moderead_write
. "read-only-storage"
-
variable is declared with address space
storage
and access moderead
.
If entry.
buffer
.minBindingSize
is not0
, then it must be at least the minimum binding size for the associated buffer variable in the shader. If the variable has store type T, the minimum binding size is SizeOf(T). In this calculation, if T is a runtime-sized array or contains a runtime-sized array, that array is assumed to have one element. Enforcing this lower bound ensures reads and writes via the buffer variable only access memory locations within the bound region of the buffer. sampler
-
"filtering"
or"non-filtering"
-
variable has type
sampler
. "comparison"
-
variable has type
sampler_comparison
.
texture
-
If, and only if, entry.
texture
.multisampled
istrue
, variable has typetexture_multisampled_2d<T>
ortexture_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
isf32
. "sint"
-
The sampled type
T
isi32
. "uint"
-
The sampled type
T
isu32
.
-
"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
isf32
. -
If entry.
texture
.viewDimension
is:"1d"
-
variable has type
texture_1d<T>
. "2d"
-
variable has type
texture_2d<T>
ortexture_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
iswrite
.
The texel format
T
equals entry.storageTexture
.format
.
A resource binding is considered to be statically used by a shader entry point if and only if it’s reachable by the control flow graph of the shader module, starting at the entry point.
10.2. GPUComputePipeline
A GPUComputePipeline
is a kind of pipeline that controls the compute shader stage,
and can be used in GPUComputePassEncoder
.
Compute inputs and outputs are all contained in the bindings,
according to the given GPUPipelineLayout
.
The outputs correspond to buffer
bindings with a type of "storage"
and storageTexture
bindings with a type of "write-only"
.
Stages of a compute pipeline:
-
Compute shader
[Exposed =(Window ,DedicatedWorker ),SecureContext ]interface GPUComputePipeline { };GPUComputePipeline includes GPUObjectBase ;GPUComputePipeline includes GPUPipelineBase ;
10.2.1. Creation
A GPURenderPipelineDescriptor
describes a compute pipeline. See § 22.2 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
.Called on:GPUDevice
this.Arguments:
Arguments for the GPUDevice.createComputePipeline(descriptor) method. Parameter Type Nullable Optional Description descriptor
GPUComputePipelineDescriptor
✘ ✘ Description of the GPUComputePipeline
to create.Returns:
GPUComputePipeline
Content timeline steps:
-
Let pipeline be a new
GPUComputePipeline
object. -
Issue the initialization steps on the Device timeline of this.
-
Return pipeline.
Device timeline initialization steps:-
Let layout be a new default pipeline layout for pipeline if descriptor.
layout
is"auto"
, and descriptor.layout
otherwise. -
If any of the following conditions are unsatisfied generate a validation error, make pipeline invalid, and stop.
-
layout is valid to use with this.
-
validating GPUProgrammableStage(
COMPUTE
, descriptor.compute
, layout) succeeds. -
descriptor.
compute
uses ≤ device.limits.maxComputeWorkgroupStorageSize
bytes of workgroup storage. -
descriptor.
compute
uses ≤ device.limits.maxComputeInvocationsPerWorkgroup
per workgroup. -
descriptor.
compute
'sworkgroup_size
attribute has each component ≤ the corresponding component in [device.limits.maxComputeWorkgroupSizeX
, device.limits.maxComputeWorkgroupSizeY
, device.limits.maxComputeWorkgroupSizeZ
].
-
-
Set pipeline.
[[layout]]
to layout.
-
createComputePipelineAsync(descriptor)
-
Creates a
GPUComputePipeline
. The returnedPromise
resolves when the created pipeline is ready to be used without additional delay.If pipeline creation fails, the returned
Promise
rejects with anOperationError
.Note: Use of this method is preferred whenever possible, as it prevents blocking the queue timeline work on pipeline compilation.
Called on:GPUDevice
this.Arguments:
Arguments for the GPUDevice.createComputePipelineAsync(descriptor) method. Parameter Type Nullable Optional Description descriptor
GPUComputePipelineDescriptor
✘ ✘ Description of the GPUComputePipeline
to create.Returns:
Promise
<GPUComputePipeline
>Content timeline steps:
-
Let promise be a new promise.
-
Issue the initialization steps on the Device timeline of this.
-
Return promise.
Device timeline initialization steps:-
Let pipeline be a new
GPUComputePipeline
created as if this.createComputePipeline()
was called with descriptor; -
When pipeline is ready to be used or has been made invalid, resolve promise with pipeline.
-
GPUComputePipeline
:
const computePipeline= gpuDevice. createComputePipeline({ layout: pipelineLayout, compute: { module: computeShaderModule, entryPoint: 'computeMain' , } });
10.3. GPURenderPipeline
A GPURenderPipeline
is a kind of pipeline that controls the vertex
and fragment shader stages, and can be used in GPURenderPassEncoder
as well as GPURenderBundleEncoder
.
Render pipeline inputs are:
-
bindings, according to the given
GPUPipelineLayout
-
vertex and index buffers, described by
GPUVertexState
-
the color attachments, described by
GPUColorTargetState
-
optionally, the depth-stencil attachment, described by
GPUDepthStencilState
Render pipeline outputs are:
-
storageTexture
bindings with aaccess
of"write-only"
-
the color attachments, described by
GPUColorTargetState
-
optionally, depth-stencil attachment, described by
GPUDepthStencilState
A render pipeline is comprised of the following render stages:
-
Vertex fetch, controlled by
GPUVertexState.buffers
-
Vertex shader, controlled by
GPUVertexState
-
Primitive assembly, controlled by
GPUPrimitiveState
-
Rasterization, controlled by
GPUPrimitiveState
,GPUDepthStencilState
, andGPUMultisampleState
-
Fragment shader, controlled by
GPUFragmentState
-
Stencil test and operation, controlled by
GPUDepthStencilState
-
Depth test and write, controlled by
GPUDepthStencilState
-
Output merging, controlled by
GPUFragmentState.targets
[Exposed =(Window ,DedicatedWorker ),SecureContext ]interface GPURenderPipeline { };GPURenderPipeline includes GPUObjectBase ;GPURenderPipeline includes GPUPipelineBase ;
GPURenderPipeline
has the following internal slots:
[[descriptor]]
, of typeGPURenderPipelineDescriptor
-
The
GPURenderPipelineDescriptor
describing this pipeline.All optional fields of
GPURenderPipelineDescriptor
are defined. [[writesDepth]]
, of type boolean-
True if the pipeline writes to the depth component of the depth/stencil attachment
[[writesStencil]]
, of type boolean-
True if the pipeline writes to the stencil component of the depth/stencil attachment
10.3.1. Creation
A GPURenderPipelineDescriptor
describes a render pipeline by configuring each
of the render stages. See § 22.3 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
undefined
, the § 22.3.8 No Color Output mode is enabled.
createRenderPipeline(descriptor)
-
Creates a
GPURenderPipeline
.Called on:GPUDevice
this.Arguments:
Arguments for the GPUDevice.createRenderPipeline(descriptor) method. Parameter Type Nullable Optional Description descriptor
GPURenderPipelineDescriptor
✘ ✘ Description of the GPURenderPipeline
to create.Returns:
GPURenderPipeline
Content timeline steps:
-
If descriptor.
fragment
is notundefined
:-
For each non-
null
colorState layout descriptor in the list descriptor.fragment
.targets
:-
Validate texture format required features of colorState.
format
with this.[[device]]
.
-
-
-
If descriptor.
depthStencil
is notnull
:-
Validate texture format required features of descriptor.
depthStencil
.format
with this.[[device]]
.
-
-
Let pipeline be a new
GPURenderPipeline
object. -
Issue the initialization steps on the Device timeline of this.
-
Return pipeline.
Device timeline initialization steps:-
Let layout be a new default pipeline layout for pipeline if descriptor.
layout
is"auto"
, and descriptor.layout
otherwise. -
If any of the following conditions are unsatisfied: generate a validation error, make pipeline invalid, and stop.
-
layout is valid to use with this.
-
validating GPURenderPipelineDescriptor(descriptor, layout, this) succeeds.
-
-
Set pipeline.
[[descriptor]]
to descriptor. -
Set pipeline.
[[writesDepth]]
to false. -
Set pipeline.
[[writesStencil]]
to false. -
Let depthStencil be descriptor.
depthStencil
. -
If depthStencil is not null:
-
Set pipeline.
[[writesDepth]]
to depthStencil.depthWriteEnabled
. -
If depthStencil.
stencilWriteMask
is not 0:-
Let stencilFront be depthStencil.
stencilFront
. -
Let stencilBack be depthStencil.
stencilBack
. -
If cullMode is not
"front"
, and any of stencilFront.passOp
, stencilFront.depthFailOp
, or stencilFront.failOp
is not"keep"
:-
Set pipeline.
[[writesStencil]]
to true.
-
-
If cullMode is not
"back"
, and any of stencilBack.passOp
, stencilBack.depthFailOp
, or stencilBack.failOp
is not"keep"
:-
Set pipeline.
[[writesStencil]]
to true.
-
-
-
-
Set pipeline.
[[layout]]
to layout.
-
createRenderPipelineAsync(descriptor)
-
Creates a
GPURenderPipeline
. The returnedPromise
resolves when the created pipeline is ready to be used without additional delay.If pipeline creation fails, the returned
Promise
rejects with anOperationError
.Note: Use of this method is preferred whenever possible, as it prevents blocking the queue timeline work on pipeline compilation.
Called on:GPUDevice
this.Arguments:
Arguments for the GPUDevice.createRenderPipelineAsync(descriptor) method. Parameter Type Nullable Optional Description descriptor
GPURenderPipelineDescriptor
✘ ✘ Description of the GPURenderPipeline
to create.Returns:
Promise
<GPURenderPipeline
>Content timeline steps:
-
Let promise be a new promise.
-
Issue the initialization steps on the Device timeline of this.
-
Return promise.
Device timeline initialization steps:-
Let pipeline be a new
GPURenderPipeline
created as if this.createRenderPipeline()
was called with descriptor; -
When pipeline is ready to be used or has been made invalid, resolve promise with pipeline.
-
Arguments:
-
GPURenderPipelineDescriptor
descriptor -
GPUPipelineLayout
layout -
GPUDevice
device
Return true
if all of the following conditions are satisfied:
-
validating GPUProgrammableStage(
VERTEX
, descriptor.vertex
, layout) succeeds. -
validating GPUVertexState(device, descriptor.
vertex
, descriptor.vertex
) succeeds. -
If descriptor.
fragment
is notnull
:-
validating GPUProgrammableStage(
FRAGMENT
, descriptor.fragment
, layout) succeeds. -
validating GPUFragmentState(device, descriptor.
fragment
) succeeds. -
If the "sample_mask" builtin is a pipeline output of descriptor.
fragment
:-
descriptor.
multisample
.alphaToCoverageEnabled
isfalse
.
-
-
-
validating GPUPrimitiveState(descriptor.
primitive
, device.[[features]]
) succeeds. -
If descriptor.
depthStencil
is notnull
:-
validating GPUDepthStencilState(descriptor.
depthStencil
) succeeds.
-
-
validating GPUMultisampleState(descriptor.
multisample
) succeeds. -
For each user-defined input of descriptor.
fragment
there must be a user-defined output of descriptor.vertex
that location, type, and interpolation of the input. -
validating inter-stage interfaces(device, descriptor) returns
true
.
Arguments:
-
GPUDevice
device -
GPURenderPipelineDescriptor
descriptor
Returns: boolean
-
Let maxVertexShaderOutputComponents be device.limits.
maxInterStageShaderComponents
.-
If descriptor.
primitive
.topology
is"point-list"
:-
Decrement maxVertexShaderOutputComponents by 1.
-
-
-
Let maxFragmentShaderInputComponents be device.limits.
maxInterStageShaderComponents
.-
If the
front_facing
builtin is an input of descriptor.fragment
:-
Decrement maxFragmentShaderInputComponents by 1.
-
-
If the
sample_index
builtin is an input of descriptor.fragment
:-
Decrement maxFragmentShaderInputComponents by 1.
-
-
If the
sample_mask
builtin is an input of descriptor.fragment
:-
Decrement maxFragmentShaderInputComponents by 1.
-
-
-
Return
true
if and only if all of the following conditions are satisfied:-
The location of each user-defined output of descriptor.
vertex
is less than (device.limits.maxInterStageShaderVariables
). -
The location of each user-defined input of descriptor.
fragment
is less than (device.limits.maxInterStageShaderVariables
). -
There are no more than maxVertexShaderOutputComponents scalar components across all user-defined outputs for descriptor.
vertex
. (For example, af32
output uses 1 component, and avec3<f32>
output uses 3 components.) -
There are no more than maxFragmentShaderInputComponents scalar components across all user-defined inputs for descriptor.
fragment
.
-
define what "compatible" means for render target formats.
GPURenderPipeline
:
const renderPipeline= gpuDevice. createRenderPipeline({ layout: pipelineLayout, vertex: { module: shaderModule, entryPoint: 'vertexMain' }, fragment: { module: shaderModule, entryPoint: 'fragmentMain' , targets: [{ format: 'bgra8unorm' , }], } });
10.3.2. Primitive State
dictionary {
GPUPrimitiveState GPUPrimitiveTopology topology = "triangle-list";GPUIndexFormat stripIndexFormat ;GPUFrontFace frontFace = "ccw";GPUCullMode cullMode = "none"; // Requires "depth-clip-control" feature.boolean unclippedDepth =false ; };
GPUPrimitiveState
has the following members, which describe how a GPURenderPipeline
constructs and rasterizes primitives from its vertex inputs:
topology
, of type GPUPrimitiveTopology, defaulting to"triangle-list"
-
The type of primitive to be constructed from the vertex inputs.
stripIndexFormat
, of type GPUIndexFormat-
For strip topologies (
"line-strip"
or"triangle-strip"
), defines the format of indices that may be used with thisGPURenderPipeline
. This determines the strip’s primitive restart value. See § 22.3.3 Primitive Assembly for additional details.Required only if the pipeline is used with indexed draw calls. Not allowed with non-strip topologies.
frontFace
, of type GPUFrontFace, defaulting to"ccw"
-
Defines which polygons are considered front-facing.
cullMode
, of type GPUCullMode, defaulting to"none"
-
Defines which polygon orientation will be culled, if any.
unclippedDepth
, of type boolean, defaulting tofalse
-
If true, indicates that depth clipping is disabled. See § 24.1 "depth-clip-control" for additional details.
Requires the
"depth-clip-control"
feature to be enabled.
-
GPUPrimitiveState
descriptor -
list<
GPUFeatureName
> features
Return true
if all of the following conditions are satisfied:
-
If descriptor.
topology
is not"line-strip"
or"triangle-strip"
:-
descriptor.
stripIndexFormat
isundefined
-
-
If descriptor.
unclippedDepth
istrue
:-
features must contain
"depth-clip-control"
.
-
enum {
GPUPrimitiveTopology "point-list" ,"line-list" ,"line-strip" ,"triangle-list" ,"triangle-strip" };
GPUPrimitiveTopology
defines the primitive type draw calls made with a GPURenderPipeline
will use. See § 22.3.5 Rasterization for additional details:
"point-list"
-
Each vertex defines a point primitive.
"line-list"
-
Each consecutive pair of two vertices defines a line primitive.
"line-strip"
-
Each vertex after the first defines a line primitive between it and the previous vertex.
"triangle-list"
-
Each consecutive triplet of three vertices defines a triangle primitive.
"triangle-strip"
-
Each vertex after the first two defines a triangle primitive between it and the previous two vertices.
enum {
GPUFrontFace "ccw" ,"cw" };
GPUFrontFace
defines which polygons are considered front-facing by a GPURenderPipeline
.
See § 22.3.5.4 Polygon Rasterization for additional details:
"ccw"
-
Polygons with vertices whose framebuffer coordinates are given in counter-clockwise order are considered front-facing.
"cw"
-
Polygons with vertices whose framebuffer coordinates are given in clockwise order are considered front-facing.
enum {
GPUCullMode "none" ,"front" ,"back" };
GPUPrimitiveTopology
defines which polygons will be culled by draw calls made with a GPURenderPipeline
. See § 22.3.5.4 Polygon Rasterization for additional details:
"none"
-
No polygons are discarded.
"front"
-
Front-facing polygons are discarded.
"back"
-
Back-facing polygons are discarded.
Note: GPUFrontFace
and GPUCullMode
have no effect on "point-list"
, "line-list"
, or "line-strip"
topologies.
10.3.3. Multisample State
dictionary {
GPUMultisampleState GPUSize32 count = 1;GPUSampleMask mask = 0xFFFFFFFF;boolean alphaToCoverageEnabled =false ; };
GPUMultisampleState
has the following members, which describe how a GPURenderPipeline
interacts with a render pass’s multisampled attachments.
count
, of type GPUSize32, defaulting to1
-
Number of samples per pixel. This
GPURenderPipeline
will be compatible only with attachment textures (colorAttachments
anddepthStencilAttachment
) with matchingsampleCount
s. mask
, of type GPUSampleMask, defaulting to0xFFFFFFFF
-
Mask determining which samples are written to.
alphaToCoverageEnabled
, of type boolean, defaulting tofalse
-
When
true
indicates that a fragment’s alpha channel should be used to generate a sample coverage mask.
-
GPUMultisampleState
descriptor
Return true
if all of the following conditions are satisfied:
-
If descriptor.
alphaToCoverageEnabled
istrue
:-
descriptor.
count
> 1.
-
10.3.4. Fragment State
dictionary :
GPUFragmentState GPUProgrammableStage {required sequence <GPUColorTargetState ?>; };
targets
GPUDevice
device, GPUFragmentState
descriptor)
Return true
if all of the following requirements are met:
-
descriptor.
targets
.length must be ≤ device.[[limits]]
.maxColorAttachments
. -
For each non-
null
colorState layout descriptor in the list descriptor.targets
:-
colorState.
format
must be listed in § 25.1.1 Plain color formats withRENDER_ATTACHMENT
capability. -
If colorState.
blend
is notundefined
:-
The colorState.
format
must be filterable according to the § 25.1.1 Plain color formats table. -
colorState.
blend
.color
must be a valid GPUBlendComponent. -
colorState.
blend
.alpha
must be a valid GPUBlendComponent.
-
-
colorState.
writeMask
must be < 16. -
If descriptor.
entryPoint
has a pipeline output value with location attribute equal to the index of the colorState in the descriptor.targets
list:-
The pipeline output type must be compatible with colorState.
format
.
Otherwise:
-
colorState.
writeMask
must be 0.
-
-
Note: The fragment shader may output more values than what the pipeline uses. If that is the case the values are ignored.
define the area of reach for "statically used" things of GPUProgrammableStage
10.3.5. Color Target State
dictionary {
GPUColorTargetState required GPUTextureFormat ;
format GPUBlendState ;
blend GPUColorWriteFlags = 0xF; // GPUColorWrite.ALL };
writeMask
dictionary {
GPUBlendState required GPUBlendComponent ;
color required GPUBlendComponent ; };
alpha
typedef [EnforceRange ]unsigned long ; [
GPUColorWriteFlags Exposed =(Window ,DedicatedWorker )]namespace {
GPUColorWrite const GPUFlagsConstant = 0x1;
RED const GPUFlagsConstant = 0x2;
GREEN const GPUFlagsConstant = 0x4;
BLUE const GPUFlagsConstant = 0x8;
ALPHA const GPUFlagsConstant = 0xF; };
ALL
10.3.5.1. Blend State
dictionary {
GPUBlendComponent GPUBlendOperation operation = "add";GPUBlendFactor srcFactor = "one";GPUBlendFactor dstFactor = "zero"; };
GPUBlendComponent
has the following members, which describe how the color or alpha components
of a fragment are blended:
operation
, of type GPUBlendOperation, defaulting to"add"
-
Defines the
GPUBlendOperation
used to calculate the values written to the target attachment components. srcFactor
, of type GPUBlendFactor, defaulting to"one"
-
Defines the
GPUBlendFactor
operation to be performed on values from the fragment shader. dstFactor
, of type GPUBlendFactor, defaulting to"zero"
-
Defines the
GPUBlendFactor
operation to be performed on values from the target attachment.
The following tables use this notation to describe color components for a given fragment location:
RGBAsrc
| Color output by the fragment shader for the color attachment. |
RGBAdst
| Color currently in the color attachment. |
RGBAconst
| The current [[blend_constant]] .
|
RGBAsrcFactor
| The source blend factor components, as defined by srcFactor .
|
RGBAdstFactor
| The destination blend factor components, as defined by dstFactor .
|
enum {
GPUBlendFactor "zero" ,"one" ,"src" ,"one-minus-src" ,"src-alpha" ,"one-minus-src-alpha" ,"dst" ,"one-minus-dst" ,"dst-alpha" ,"one-minus-dst-alpha" ,"src-alpha-saturated" ,"constant" ,"one-minus-constant" };
GPUBlendFactor
defines how either a source or destination blend factors is calculated:
GPUBlendFactor | Blend factor RGBA components |
---|---|
"zero"
| (0, 0, 0, 0)
|
"one"
| (1, 1, 1, 1)
|
"src"
| (Rsrc, Gsrc, Bsrc, Asrc)
|
"one-minus-src"
| (1 - Rsrc, 1 - Gsrc, 1 - Bsrc, 1 - Asrc)
|
"src-alpha"
| (Asrc, Asrc, Asrc, Asrc)
|
"one-minus-src-alpha"
| (1 - Asrc, 1 - Asrc, 1 - Asrc, 1 - Asrc)
|
"dst"
| (Rdst, Gdst, Bdst, Adst)
|
"one-minus-dst"
| (1 - Rdst, 1 - Gdst, 1 - Bdst, 1 - Adst)
|
"dst-alpha"
| (Adst, Adst, Adst, Adst)
|
"one-minus-dst-alpha"
| (1 - Adst, 1 - Adst, 1 - Adst, 1 - Adst)
|
"src-alpha-saturated"
| (Asrc, Asrc, Asrc, Asrc)
|
"constant"
| (Rconst, Gconst, Bconst, Aconst)
|
"one-minus-constant"
| (1 - Rconst, 1 - Gconst, 1 - Bconst, 1 - Aconst)
|
enum {
GPUBlendOperation "add" ,"subtract" ,"reverse-subtract" ,"min" ,"max" };
GPUBlendOperation
defines the algorithm used to combine source and destination blend factors:
GPUBlendOperation | RGBA Components |
---|---|
"add"
| RGBAsrc × RGBAsrcFactor + RGBAdst × RGBAdstFactor
|
"subtract"
| RGBAsrc × RGBAsrcFactor - RGBAdst × RGBAdstFactor
|
"reverse-subtract"
| RGBAdst × RGBAdstFactor - RGBAsrc × RGBAsrcFactor
|
"min"
| min(RGBAsrc, RGBAdst)
|
"max"
| max(RGBAsrc, RGBAdst)
|
10.3.6. Depth/Stencil State
dictionary {
GPUDepthStencilState required GPUTextureFormat format ;boolean depthWriteEnabled =false ;GPUCompareFunction depthCompare = "always";GPUStencilFaceState stencilFront = {};GPUStencilFaceState stencilBack = {};GPUStencilValue stencilReadMask = 0xFFFFFFFF;GPUStencilValue stencilWriteMask = 0xFFFFFFFF;GPUDepthBias depthBias = 0;float depthBiasSlopeScale = 0;float depthBiasClamp = 0; };
GPUDepthStencilState
has the following members, which describe how a GPURenderPipeline
will affect a render pass’s depthStencilAttachment
:
format
, of type GPUTextureFormat-
The
format
ofdepthStencilAttachment
thisGPURenderPipeline
will be compatible with. depthWriteEnabled
, of type boolean, defaulting tofalse
-
Indicates if this
GPURenderPipeline
can modifydepthStencilAttachment
depth values. depthCompare
, of type GPUCompareFunction, defaulting to"always"
-
The comparison operation used to test fragment depths against
depthStencilAttachment
depth values. stencilFront
, of type GPUStencilFaceState, defaulting to{}
-
Defines how stencil comparisons and operations are performed for front-facing primitives.
stencilBack
, of type GPUStencilFaceState, defaulting to{}
-
Defines how stencil comparisons and operations are performed for back-facing primitives.
stencilReadMask
, of type GPUStencilValue, defaulting to0xFFFFFFFF
-
Bitmask controlling which
depthStencilAttachment
stencil value bits are read when performing stencil comparison tests. stencilWriteMask
, of type GPUStencilValue, defaulting to0xFFFFFFFF
-
Bitmask controlling which
depthStencilAttachment
stencil value bits are written to when performing stencil operations. depthBias
, of type GPUDepthBias, defaulting to0
-
Constant depth bias added to each fragment. See biased fragment depth for details.
depthBiasSlopeScale
, of type float, defaulting to0
-
Depth bias that scales with the fragment’s slope. See biased fragment depth for details.
depthBiasClamp
, of type float, defaulting to0
-
The maximum depth bias of a fragment. See biased fragment depth for details.
depthStencilAttachment
attachment when drawing using GPUDepthStencilState
state is calculated by running the following steps:
-
Let r be the minimum positive representable value >
0
in the format converted to a 32-bit float. -
Let maxDepthSlope be the maximum of the horizontal and vertical slopes of the fragment’s depth value.
-
If format is a unorm format:
-
Let bias be
(float)state.
.depthBias
* r + state.depthBiasSlopeScale
* maxDepthSlope
-
-
Otherwise, if format is a float format:
-
Let bias be
(float)state.
.depthBias
* 2^(exp(max depth in primitive) - r) + state.depthBiasSlopeScale
* maxDepthSlope
-
-
If state.
depthBiasClamp
>0
:-
Set bias to
min(state.
.depthBiasClamp
, bias)
-
-
Otherwise if state.
depthBiasClamp
<0
:-
Set bias to
max(state.
.depthBiasClamp
, bias)
-
-
If state.
depthBias
≠0
or state.depthBiasSlopeScale
≠0
:-
Set the fragment depth value to
fragment depth value + bias
-
Arguments:
-
GPUDepthStencilState
descriptor
Return true
if, and only if, all of the following conditions are satisfied:
-
descriptor.
format
is a depth-or-stencil format. -
If descriptor.
depthWriteEnabled
istrue
or descriptor.depthCompare
is not"always"
:-
descriptor.
format
must have a depth component.
-
-
If descriptor.
stencilFront
or descriptor.stencilBack
are not the default values:-
descriptor.
format
must have a stencil component.
-
how can this algorithm support depth/stencil formats that are added in extensions?
dictionary {
GPUStencilFaceState GPUCompareFunction compare = "always";GPUStencilOperation failOp = "keep";GPUStencilOperation depthFailOp = "keep";GPUStencilOperation passOp = "keep"; };
GPUStencilFaceState
has the following members, which describe how stencil comparisons and
operations are performed:
compare
, of type GPUCompareFunction, defaulting to"always"
-
The
GPUCompareFunction
used when testing fragments againstdepthStencilAttachment
stencil values. failOp
, of type GPUStencilOperation, defaulting to"keep"
-
The
GPUStencilOperation
performed if the fragment stencil comparison test described bycompare
fails. depthFailOp
, of type GPUStencilOperation, defaulting to"keep"
-
The
GPUStencilOperation
performed if the fragment depth comparison described bydepthCompare
fails. passOp
, of type GPUStencilOperation, defaulting to"keep"
-
The
GPUStencilOperation
performed if the fragment stencil comparison test described bycompare
passes.
enum {
GPUStencilOperation "keep" ,"zero" ,"replace" ,"invert" ,"increment-clamp" ,"decrement-clamp" ,"increment-wrap" ,"decrement-wrap" };
GPUStencilOperation
defines the following operations:
"keep"
-
Keep the current stencil value.
"zero"
-
Set the stencil value to
0
. "replace"
-
Set the stencil value to
[[stencil_reference]]
. "invert"
-
Bitwise-invert the current stencil value.
"increment-clamp"
-
Increments the current stencil value, clamping to the maximum representable value of the
depthStencilAttachment
's stencil aspect. "decrement-clamp"
-
Decrement the current stencil value, clamping to
0
. "increment-wrap"
-
Increments the current stencil value, wrapping to zero if the value exceeds the maximum representable value of the
depthStencilAttachment
's stencil aspect. "decrement-wrap"
-
Decrement the current stencil value, wrapping to the maximum representable value of the
depthStencilAttachment
's stencil aspect if the value goes below0
.
10.3.7. Vertex State
enum {
GPUIndexFormat "uint16" ,"uint32" };
The index format determines both the data type of index values in a buffer and, when used with
strip primitive topologies ("line-strip"
or "triangle-strip"
) also specifies the primitive restart value. The primitive restart value indicates which index value indicates that a new primitive
should be started rather than continuing to construct the triangle strip with the prior indexed
vertices.
GPUPrimitiveState
s that specify a strip primitive topology must specify a stripIndexFormat
if they are used for indexed draws
so that the primitive restart value that will be used is known at pipeline
creation time. GPUPrimitiveState
s that specify a list primitive
topology will use the index format passed to setIndexBuffer()
when doing indexed rendering.
Index format | Byte size | Primitive restart value |
---|---|---|
"uint16"
| 2 | 0xFFFF |
"uint32"
| 4 | 0xFFFFFFFF |
10.3.7.1. Vertex Formats
The GPUVertexFormat
of a vertex attribute indicates how data from a vertex buffer will
be interpreted and exposed to the shader. The name of the format specifies the order of components,
bits per component, and vertex data type for the component.
Each vertex data type can map to any WGSL scalar type of the same base type, regardless of the bits per component:
Vertex format prefix | Vertex data type | Compatible WGSL types |
---|---|---|
uint
| unsigned int | u32
|
sint
| signed int | i32
|
unorm
| unsigned normalized | f16 , f32
|
snorm
| signed normalized | |
float
| floating point |
The multi-component formats specify the number of components after "x". Mismatches in the number of components between the vertex format and shader type are allowed, with components being either dropped or filled with default values to compensate.
"unorm8x2"
and byte values [0x7F, 0xFF]
can be accessed in the shader with the following types:
Shader type | Shader value |
---|---|
f16
| 0.5h
|
f32
| 0.5f
|
vec2<f16>
| vec2(0.5h, 1.0h)
|
vec2<f32>
| vec2(0.5f, 1.0f)
|
vec3<f16>
| vec2(0.5h, 1.0h, 0.0h)
|
vec3<f32>
| vec2(0.5f, 1.0f, 0.0f)
|
vec4<f16>
| vec2(0.5h, 1.0h, 0.0h, 1.0h)
|
vec4<f32>
| vec2(0.5f, 1.0f, 0.0f, 1.0f)
|
See § 22.3.2 Vertex Processing for additional information about how vertex formats are exposed in the shader.
enum {
GPUVertexFormat "uint8x2" ,"uint8x4" ,"sint8x2" ,"sint8x4" ,"unorm8x2" ,"unorm8x4" ,"snorm8x2" ,"snorm8x4" ,"uint16x2" ,"uint16x4" ,"sint16x2" ,"sint16x4" ,"unorm16x2" ,"unorm16x4" ,"snorm16x2" ,"snorm16x4" ,"float16x2" ,"float16x4" ,"float32" ,"float32x2" ,"float32x3" ,"float32x4" ,"uint32" ,"uint32x2" ,"uint32x3" ,"uint32x4" ,"sint32" ,"sint32x2" ,"sint32x3" ,"sint32x4" };
Vertex format | Data type | Components | Byte size | Example WGSL type |
---|---|---|---|---|
"uint8x2"
| unsigned int | 2 | 2 | vec2<u32>
|
"uint8x4"
| unsigned int | 4 | 4 | vec4<u32>
|
"sint8x2"
| signed int | 2 | 2 | vec2<i32>
|
"sint8x4"
| signed int | 4 | 4 | vec4<i32>
|
"unorm8x2"
| unsigned normalized | 2 | 2 | vec2<f32>
|
"unorm8x4"
| unsigned normalized | 4 | 4 | vec4<f32>
|
"snorm8x2"
| signed normalized | 2 | 2 | vec2<f32>
|
"snorm8x4"
| signed normalized | 4 | 4 | vec4<f32>
|
"uint16x2"
| unsigned int | 2 | 4 | vec2<u32>
|
"uint16x4"
| unsigned int | 4 | 8 | vec4<u32>
|
"sint16x2"
| signed int | 2 | 4 | vec2<i32>
|
"sint16x4"
| signed int | 4 | 8 | vec4<i32>
|
"unorm16x2"
| unsigned normalized | 2 | 4 | vec2<f32>
|
"unorm16x4"
| unsigned normalized | 4 | 8 | vec4<f32>
|
"snorm16x2"
| signed normalized | 2 | 4 | vec2<f32>
|
"snorm16x4"
| signed normalized | 4 | 8 | vec4<f32>
|
"float16x2"
| float | 2 | 4 | vec2<f16>
|
"float16x4"
| float | 4 | 8 | vec4<f16>
|
"float32"
| float | 1 | 4 | f32
|
"float32x2"
| float | 2 | 8 | vec2<f32>
|
"float32x3"
| float | 3 | 12 | vec3<f32>
|
"float32x4"
| float | 4 | 16 | vec4<f32>
|
"uint32"
| unsigned int | 1 | 4 | u32
|
"uint32x2"
| unsigned int | 2 | 8 | vec2<u32>
|
"uint32x3"
| unsigned int | 3 | 12 | vec3<u32>
|
"uint32x4"
| unsigned int | 4 | 16 | vec4<u32>
|
"sint32"
| signed int | 1 | 4 | i32
|
"sint32x2"
| signed int | 2 | 8 | vec2<i32>
|
"sint32x3"
| signed int | 3 | 12 | vec3<i32>
|
"sint32x4"
| signed int | 4 | 16 | vec4<i32>
|
enum {
GPUVertexStepMode "vertex" ,"instance" };
The step mode configures how an address for vertex buffer data is computed, based on the current vertex or instance index:
"vertex"
-
The address is advanced by
arrayStride
for each vertex, and reset between instances. "instance"
-
The address is advanced by
arrayStride
for each instance.
dictionary :
GPUVertexState GPUProgrammableStage {sequence <GPUVertexBufferLayout ?>= []; };
buffers
A vertex buffer is, conceptually, a view into buffer memory as an array of structures. arrayStride
is the stride, in bytes, between elements of that array.
Each element of a vertex buffer is like a structure with a memory layout defined by its attributes
, which describe the members of the structure.
Each GPUVertexAttribute
describes its format
and its offset
, in bytes, within the structure.
Each attribute appears as a separate input in a vertex shader, each bound by a numeric location,
which is specified by shaderLocation
.
Every location must be unique within the GPUVertexState
.
dictionary {
GPUVertexBufferLayout required GPUSize64 arrayStride ;GPUVertexStepMode stepMode = "vertex";required sequence <GPUVertexAttribute >attributes ; };
arrayStride
, of type GPUSize64-
The stride, in bytes, between elements of this array.
stepMode
, of type GPUVertexStepMode, defaulting to"vertex"
-
Whether each element of this array represents per-vertex data or per-instance data
attributes
, of type sequence<GPUVertexAttribute>-
An array defining the layout of the vertex attributes within each element.
dictionary {
GPUVertexAttribute required GPUVertexFormat format ;required GPUSize64 offset ;required GPUIndex32 shaderLocation ; };
format
, of type GPUVertexFormat-
The
GPUVertexFormat
of the attribute. offset
, of type GPUSize64-
The offset, in bytes, from the beginning of the element to the data for the attribute.
shaderLocation
, of type GPUIndex32-
The numeric location associated with this attribute, which will correspond with a "@location" attribute declared in the
vertex
.module
.
Arguments:
-
GPUDevice
device -
GPUVertexBufferLayout
descriptor -
GPUProgrammableStage
vertexStage
Return true
, if and only if, all of the following conditions are satisfied:
-
descriptor.
arrayStride
≤ device.[[device]]
.[[limits]]
.maxVertexBufferArrayStride
. -
descriptor.
arrayStride
is a multiple of 4. -
For each attribute attrib in the list descriptor.
attributes
:-
If descriptor.
arrayStride
is zero:-
attrib.
offset
+ sizeof(attrib.format
) ≤ device.[[device]]
.[[limits]]
.maxVertexBufferArrayStride
.
Otherwise:
-
attrib.
offset
+ sizeof(attrib.format
) ≤ descriptor.arrayStride
.
-
-
attrib.
offset
is a multiple of the minimum of 4 and sizeof(attrib.format
). -
attrib.
shaderLocation
is < device.[[device]]
.[[limits]]
.maxVertexAttributes
.
-
-
For every vertex attribute in the shader reflection of vertexStage.
module
that is a pipeline input of vertexStage.entryPoint
, there is a corresponding attrib element of descriptor.attributes
for which all of the following are true:-
The shader format is compatible with attrib.
format
's vertex data type:- "unorm", "snorm", or "float"
-
shader format must be
f32
orvecN<f32>
. - "uint"
-
shader format must be
u32
orvecN<u32>
. - "sint"
-
shader format must be
i32
orvecN<i32>
.
-
The shader location is attrib.
shaderLocation
.
-
Arguments:
-
GPUDevice
device -
GPUVertexState
descriptor
Return true
, if and only if, all of the following conditions are satisfied:
-
descriptor.
buffers
.length is ≤ device.[[device]]
.[[limits]]
.maxVertexBuffers
. -
Each vertexBuffer layout descriptor in the list descriptor.
buffers
passes validating GPUVertexBufferLayout(device, vertexBuffer, descriptor) -
The sum of vertexBuffer.
attributes
.length, over every vertexBuffer in descriptor.buffers
, is ≤ device.[[device]]
.[[limits]]
.maxVertexAttributes
. -
Each attrib in the union of all
GPUVertexAttribute
across descriptor.buffers
has a distinct attrib.shaderLocation
value.
11. Command Buffers
Command buffers are pre-recorded lists of GPU commands that can be submitted to a GPUQueue
for execution. Each GPU command represents a task to be performed on the GPU, such as
setting state, drawing, copying resources, etc.
A GPUCommandBuffer
can only be submitted once, at which point it becomes invalid.
To reuse rendering commands across multiple submissions, use GPURenderBundle
.
11.1. GPUCommandBuffer
[Exposed =(Window ,DedicatedWorker ),SecureContext ]interface GPUCommandBuffer { };GPUCommandBuffer includes GPUObjectBase ;
GPUCommandBuffer
has the following internal slots:
[[command_list]]
, of type list<GPU command>-
A list of GPU commands to be executed on the Queue timeline when this command buffer is submitted.
11.1.1. Creation
dictionary :
GPUCommandBufferDescriptor GPUObjectDescriptorBase { };
12. Command Encoding
12.1. GPUCommandsMixin
GPUCommandsMixin
defines state common to all interfaces which encode commands.
It has no methods.
interface mixin GPUCommandsMixin { };
GPUCommandsMixin
adds the following internal slots to interfaces which include it:
[[state]]
, of type encoder state-
The current state of the encoder, initially set to "open".
[[commands]]
, of type list<GPU command>-
A list of GPU commands to be executed on the Queue timeline when a
GPUCommandBuffer
containing these commands is submitted.
The encoder state may be one of the following:
- "open"
-
The encoder is available to encode new commands.
- "locked"
-
The encoder cannot be used, because it is locked by a child encoder: it is a
GPUCommandEncoder
, and aGPURenderPassEncoder
orGPUComputePassEncoder
is active. The encoder becomes "open" again when the pass is ended.Any command issued in this state makes the encoder invalid.
- "ended"
-
The encoder has been ended and new commands can no longer be encoded.
Any command issued in this state will generate a validation error.
GPUCommandsMixin
encoder:
If encoder.[[state]]
is:
- "open"
-
Return
true
. - "locked"
-
Make encoder invalid, and return
false
. - "ended"
-
Generate a validation error, and return
false
.
12.2. GPUCommandEncoder
[Exposed =(Window ,DedicatedWorker ),SecureContext ]interface GPUCommandEncoder {GPURenderPassEncoder beginRenderPass (GPURenderPassDescriptor descriptor );GPUComputePassEncoder beginComputePass (optional GPUComputePassDescriptor descriptor = {});undefined copyBufferToBuffer (GPUBuffer source ,GPUSize64 sourceOffset ,GPUBuffer destination ,GPUSize64 destinationOffset ,GPUSize64 size );undefined copyBufferToTexture (GPUImageCopyBuffer source ,GPUImageCopyTexture destination ,GPUExtent3D copySize );undefined copyTextureToBuffer (GPUImageCopyTexture source ,GPUImageCopyBuffer destination ,GPUExtent3D copySize );undefined copyTextureToTexture (GPUImageCopyTexture