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
shader
s
are
executed
by
the
compute
units
inside
GPU
hardware.
In
native
APIs,
some
of
the
shader
instructions
may
result
in
undefined
behavior
on
the
GPU.
In
order
to
address
that,
the
shader
instruction
set
and
its
defined
behaviors
are
strictly
defined
by
WebGPU.
When
a
shader
is
provided
to
createShaderModule()
,
the
WebGPU
implementation
has
to
validate
it
before
doing
any
translation
(to
platform-specific
shaders)
or
transformation
passes.
2.1.3. Uninitialized data
Generally, allocating new memory may expose the leftover data of other applications running on the system. In order to address that, WebGPU conceptually initializes all the resources to zero, although in practice an implementation may skip this step if it sees the developer initializing the contents manually. This includes variables and shared workgroup memory inside shaders.
The precise mechanism of clearing the workgroup memory can differ between platforms. If the native API does not provide facilities to clear it, the WebGPU implementation transforms the compute shader to first do a clear across all invocations, synchronize them, and continue executing developer’s code.
2.1.4. Out-of-bounds access in shaders
Shader
s
can
access
physical
resource
s
either
directly
(for
example,
as
a
"uniform"
GPUBufferBinding
),
or
via
texture
unit
s,
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
unit
s
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.
Update this section with iframe-control defaulting to "self" being a mitigation against this issue since only the top level origin (that is a bit more trusted since the user navigated to it, or is staying on it).
2.2. Privacy Considerations
The privacy considerations for WebGPU are similar to those of WebGL. GPU APIs are complex and must expose various aspects of a device’s capabilities out of necessity in order to enable developers to take advantage of those capabilities effectively. The general mitigation approach involves normalizing or binning potentially identifying information and enforcing uniform behavior where possble.
2.2.1. Machine-specific limits
WebGPU can expose a lot of detail on the underlying GPU architecture and the device geometry. This includes available physical adapters, many limits on the GPU and CPU resources that could be used (such as the maximum texture size), and any optional hardware-specific capabilities that are available.
User agents are not obligated to expose the real hardware limits, they are in full control of how much the machine specifics are exposed. One strategy to reduce fingerprinting is binning all the target platforms into a few number of bins. In general, the privacy impact of exposing the hardware limits matches the one of WebGL.
The default limits are also deliberately high enough to allow most applications to work without requesting higher limits. All the usage of the API is validated according to the requested limits, so the actual hardware capabilities are not exposed to the users by accident.
2.2.2. Machine-specific artifacts
There are some machine-specific rasterization/precision artifacts and performance differences that can be observed roughly in the same way as in WebGL. This applies to rasterization coverage and patterns, interpolation precision of the varyings between shader stages, compute unit scheduling, and more aspects of execution.
Generally, rasterization and precision fingerprints are identical across most or all of the devices of each vendor. Performance differences are relatively intractable, but also relatively low-signal (as with JS execution performance).
Privacy-critical applications and user agents should utilize software implementations to eliminate such artifacts.
2.2.3. Machine-specific performance
Another factor for differentiating users is measuring the performance of specific operations on the GPU. Even with low precision timing, repeated execution of an operation can show if the user’s machine is fast at specific workloads. This is a fairly common vector (present in both WebGL and Javascript), but it’s also low-signal and relatively intractable to truly normalize.
WebGPU compute pipelines expose access to GPU unobstructed by the fixed-function hardware. This poses an additional risk for unique device fingerprinting. User agents can take steps to dissociate logical GPU invocations with actual compute units to reduce this risk.
2.2.4. User Agent State
This
specification
doesn’t
define
any
additional
user-agent
state
for
an
origin.
However
it
is
expected
that
user
agents
will
have
compilation
caches
for
the
result
of
expensive
compilation
like
GPUShaderModule
,
GPURenderPipeline
and
GPUComputePipeline
.
These
caches
are
important
to
improve
the
loading
time
of
WebGPU
applications
after
the
first
visit.
For
the
specification,
these
caches
are
indifferentiable
from
incredibly
fast
compilation,
but
for
applications
it
would
be
easy
to
measure
how
long
createComputePipelineAsync()
takes
to
resolve.
This
can
leak
information
across
origins
(like
"did
the
user
access
a
site
with
this
specific
shader")
so
user
agents
should
follow
the
best
practices
in
storage
partitioning
.
The system’s GPU driver may also have its own cache of compiled shaders and pipelines. User agents may want to disable these when at all possible, or add per-partition data to shaders in ways that will make the GPU driver consider them different.
2.2.5. Driver bugs
In addition to the concerns outlined in Security Considerations , driver bugs may introduce differences in behavior that can be observed as a method of differentiating users. The mitigations mentioned in Security Considerations apply here as well, including coordinating with GPU vendors and implementing workarounds for known issues in the user agent.
2.2.6. Adapter Identifiers
Describe considerations for exposing adapter info
Note: It is expected that WebGPU will expose some level of information identifying the type of GPU Adapter in use. This is a potential source of fingerprinting information but past experience with WebGL has demonstrated that it is necessary to some degree in order to enable developers to create robust applications and respond effectively to user issues.
3. Fundamentals
3.1. Conventions
3.1.1. Dot Syntax
In
this
specification,
the
.
("dot")
syntax,
common
in
programming
languages,
is
used.
The
phrasing
"
Foo.Bar
"
means
"the
Bar
member
of
the
value
(or
interface)
Foo
."
The
?.
("optional
chaining")
syntax,
adopted
from
JavaScript,
is
also
used.
The
phrasing
"
Foo?.Bar
"
means
"if
Foo
is
null
or
undefined
,
undefined
;
otherwise,
Foo.Bar
".
For
example,
where
buffer
is
a
GPUBuffer
,
buffer?.[[device]].[[adapter]]
means
"if
buffer
is
null
or
undefined
,
then
undefined
;
otherwise,
the
[[adapter]]
internal
slot
of
the
[[device]]
internal
slot
of
buffer
.
3.1.2. Internal Objects
An internal object is a conceptual, non-exposed WebGPU object. Internal objects track the state of an API object and hold any underlying implementation. If the state of a particular internal object can change in parallel from multiple agents , those changes are always atomic with respect to all agents .
Note: An " agent " refers to a JavaScript "thread" (i.e. main thread, or Web Worker).
3.1.3. WebGPU Interfaces
A WebGPU interface is an exposed interface which encapsulates an internal object . It provides the interface through which the internal object 's state is changed.
Any
interface
which
includes
GPUObjectBase
is
a
WebGPU
interface
.
interface mixin {
GPUObjectBase attribute USVString 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 .
3.1.4. Object Descriptors
An
object
descriptor
holds
the
information
needed
to
create
an
object,
which
is
typically
done
via
one
of
the
create*
methods
of
GPUDevice
.
dictionary {
GPUObjectDescriptorBase USVString label ; };
GPUObjectDescriptorBase
has
the
following
members:
-
label
, of type USVString -
The initial value of
GPUObjectBase.label
.
3.2. Invalid Internal Objects & Contagious Invalidity
Object creation operations in WebGPU are internally asynchronous, so they don’t fail with exceptions. Instead, returned objects may refer to internal objects which are either valid or invalid . An invalid object may never become valid at a later time. Some objects may become invalid during their lifetime, while most may only be invalid from creation.
Objects are invalid from creation if it wasn’t possible to create them. This can happen, for example, if the object descriptor doesn’t describe a valid object, or if there is not enough memory to allocate a resource.
Internal
objects
of
most
types
cannot
become
invalid
after
they
are
created,
but
still
may
become
unusable,
e.g.
if
the
owning
device
is
lost
or
destroyed
,
or
the
object
has
a
special
internal
state,
like
buffer
state
destroyed
.
Internal objects of some types can become invalid after they are created; specifically, devices , adapters , and command/pass/bundle encoders.
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.
Steps executed on the content timeline look like this. - Device timeline
-
Associated with the GPU device operations that are issued by the user agent. It includes creation of adapters, devices, and GPU resources and state objects, which are typically synchronous operations from the point of view of the user agent part that controls the GPU, but can live in a separate OS process.
Steps executed on the device timeline look like this. - Queue timeline
-
Associated with the execution of operations on the compute units of the GPU. It includes actual draw, copy, and compute jobs that run on the GPU.
Steps executed on the queue timeline look like this.
In this specification, asynchronous operations are used when the result value depends on work that happens on any timeline other than the Content timeline . They are represented by callbacks and promises in JavaScript.
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 scope s.
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()
generates
a
GPUValidationError
in
the
current
error
scope.
3.5. Core Internal Objects
3.5.1. Adapters
An adapter identifies an implementation of WebGPU on the system: both an instance of compute/rendering functionality on the platform underlying a browser, and an instance of a browser’s implementation of WebGPU on top of that functionality.
Adapters
do
not
uniquely
represent
underlying
implementations:
calling
requestAdapter()
multiple
times
returns
a
different
adapter
object
each
time.
An adapter object may become invalid at any time. This happens inside " lose the device " and " mark adapters stale ". An invalid adapter is unable to vend new devices .
Note:
This
mechanism
ensures
that
various
adapter-creation
scenarios
look
similar
to
applications,
so
they
can
easily
be
robust
to
more
scenarios
with
less
testing:
first
initialization,
reinitialization
due
to
an
unplugged
adapter,
reinitialization
due
to
a
test
GPUDevice.destroy()
call,
etc.
It
also
ensures
applications
use
the
latest
system
state
to
make
decisions
about
which
adapter
to
use.
An adapter may be considered a fallback adapter if it has significant performance caveats in exchange for some combination of wider compatibility, more predictable behavior, or improved privacy. It is not required that a fallback adapter is available on every system.
An adapter has the following internal slots:
-
[[features]]
, of type ordered set <GPUFeatureName
>, readonly -
The features which can be used to create devices on this adapter.
-
[[limits]]
, of type supported limits , readonly -
The best limits which can be used to create devices on this adapter.
Each adapter limit must be the same or better than its default value in supported limits .
-
[[fallback]]
, of type boolean -
If set to
true
indicates that the adapter is a fallback adapter .
Adapters
are
exposed
via
GPUAdapter
.
3.5.2. Devices
A device is the logical instantiation of an adapter , through which internal objects are created. It can be shared across multiple agents (e.g. dedicated workers).
A
device
is
the
exclusive
owner
of
all
internal
objects
created
from
it:
when
the
device
is
lost
or
destroyed
,
it
and
all
objects
created
on
it
(directly,
e.g.
createTexture()
,
or
indirectly,
e.g.
createView()
)
become
implicitly
unusable
.
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 an feature may only be used if the feature was requested at device creation. Dictionary members added to existing dictionaries by optional features are always optional at the WebIDL level; if the feature is not enabled, such members must not be set to non-default values.
Note: Though enabling a feature won’t add new IDL-required fields, it may not necessarily be backward-compatible with existing code. An optional feature can enable new validation which invalidates previously-valid code.
See the Feature Index for a description of the functionality each feature enables.
3.6.2. Limits
Each limit is a numeric limit on the usage of WebGPU on a device.
A
supported
limits
object
has
a
value
for
every
defined
limit.
Each
adapter
has
a
set
of
supported
limits
,
and
devices
are
created
with
specific
supported
limits
in
place.
The
device
limits
are
enforced
regardless
of
the
adapter’s
limits.
Each
limit
has
a
default
value.
Every
adapter
is
guaranteed
to
support
the
default
value
or
better
.
The
default
is
used
if
a
value
is
not
explicitly
specified
in
requiredLimits
.
One limit value may be better than another. A better limit value always relaxes validation, enabling strictly more programs to be valid. For each limit class , "better" is defined.
Different limits have different limit classes :
- maximum
-
The limit enforces a maximum on some value passed into the API.
Higher values are better .
May only be set to values ≥ the default . Lower values are clamped to the default .
- alignment
-
The limit enforces a minimum alignment on some value passed into the API; that is, the value must be a multiple of the limit.
Lower values are better .
May only be set to powers of 2 which are ≤ the default . Values which are not powers of 2 are invalid. Higher powers of 2 are clamped to the default .
Note: Setting "better" limits may not necessarily be desirable, as they may have a performance impact. Because of this, and to improve portability across devices and implementations, applications should generally request the "worst" limits that work for their content (ideally, the default values).
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 |
The
maximum
GPUBufferBinding
.
size
for
bindings
with
a
GPUBindGroupLayoutEntry
entry
for
which
entry
.
buffer
?.
type
is
"uniform"
.
| |||
maxStorageBufferBindingSize
|
GPUSize64
| maximum | 134217728 (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 |
The
required
alignment
for
GPUBufferBinding
.
offset
and
setBindGroup
dynamicOffsets
arguments
for
binding
with
a
GPUBindGroupLayoutEntry
entry
for
which
entry
.
buffer
?.
type
is
"uniform"
.
| |||
minStorageBufferOffsetAlignment
|
GPUSize32
| alignment | 256 |
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"
.
| |||
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 |
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). | |||
maxColorAttachments
|
GPUSize32
| maximum | 8 |
The
maximum
allowed
number
of
color
attachments
in
GPURenderPipelineDescriptor
.
fragment
.
targets
,
GPURenderPassDescriptor
.
colorAttachments
,
and
GPURenderPassLayout
.
colorFormats
.
| |||
maxComputeWorkgroupStorageSize
|
GPUSize32
| maximum | 16352 |
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 ;
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.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.
Each color space is defined over an extended range, if defined by the referenced CSS definitions, to represent color values outside of its space (in both chrominance and luminance).
enum {
GPUPredefinedColorSpace "srgb" , };
Possibly
replace
this
with
PredefinedColorSpace
,
but
note
that
doing
so
would
mean
new
WebGPU
functionality
gets
added
automatically
when
items
are
added
to
that
enum
in
the
upstream
spec.
Consider a path for uploading srgb-encoded images into linearly-encoded textures. [Issue #gpuweb/gpuweb#1715]
-
"srgb"
-
The CSS predefined color space srgb .
3.8.1. Color Space Conversions
A color is converted between spaces by translating its representation in one space to a representation in another according to the definitions above.
If
the
source
value
has
fewer
than
4
channels,
the
remaining
green/blue/alpha
channels
are
set
to
0,
0,
1
respectively,
as
needed,
before
converting
for
color
space/encoding
and
alpha
premultiplication.
After
conversion,
if
the
destination
needs
fewer
than
4
channels,
the
additional
channels
are
ignored.
Colors are not lossily clamped during conversion: converting from one color space to another will result in values outside the range [0, 1] if the source color values were outside the range of the destination color space’s gamut (e.g. if a Display P3 image is converted to sRGB).
4. Initialization
4.1. navigator.gpu
A
GPU
object
is
available
in
the
Window
and
DedicatedWorkerGlobalScope
contexts
through
the
Navigator
and
WorkerNavigator
interfaces
respectively
and
is
exposed
via
navigator.gpu
:
interface mixin { [
NavigatorGPU SameObject ,SecureContext ]readonly attribute GPU ; };
gpu Navigator includes NavigatorGPU ;WorkerNavigator includes NavigatorGPU ;
4.2. GPU
GPU
is
the
entry
point
to
WebGPU.
[Exposed =(Window ,DedicatedWorker ),SecureContext ]interface GPU {Promise <GPUAdapter ?>requestAdapter (optional GPURequestAdapterOptions options = {}); };
GPU
has
the
following
methods:
-
requestAdapter(options)
-
Requests an adapter from the user agent. The user agent chooses whether to return an adapter, and, if so, chooses according to the provided options.
Called on:GPU
this .Arguments:
Arguments for the GPU.requestAdapter(options) method. Parameter Type Nullable Optional Description options
GPURequestAdapterOptions ✘ ✔ Criteria used to select the adapter. Returns:
Promise
<GPUAdapter
?>-
Let promise be a new promise .
-
Issue the following steps on the Device timeline of this :
-
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
.
-
-
Return promise .
-
GPU
has
the
following
internal
slots:
-
[[previously_returned_adapters]]
, of type ordered set < adapter > -
The set of adapters that have been returned via
requestAdapter()
. It is used, then cleared, in mark adapters stale .
Upon
any
change
in
the
system’s
state
that
could
affect
the
result
of
any
requestAdapter()
call,
the
user
agent
should
mark
adapters
stale
.
For
example:
-
A physical adapter is added/removed (via plug, driver update, TDR, etc.)
-
The system’s power configuration has changed (laptop unplugged, power settings changed, etc.)
Additionally,
mark
adapters
stale
may
by
scheduled
at
any
time.
User
agents
may
choose
to
do
this
often
even
when
there
has
been
no
system
state
change
(e.g.
several
seconds
after
the
last
call
to
requestDevice()
.
This
has
no
effect
on
well-formed
applications,
obfuscates
real
system
state
changes,
and
makes
developers
more
aware
that
calling
requestAdapter()
again
is
always
necessary
before
calling
requestDevice()
.
-
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 {readonly attribute DOMString name ; [SameObject ]readonly attribute GPUSupportedFeatures features ; [SameObject ]readonly attribute GPUSupportedLimits limits ;readonly attribute boolean isFallbackAdapter ;Promise <GPUDevice >requestDevice (optional GPUDeviceDescriptor descriptor = {}); };
GPUAdapter
has
the
following
attributes:
-
name
, of type DOMString , readonly -
A human-readable name identifying the adapter. The contents are implementation-defined.
-
features
, of type GPUSupportedFeatures , readonly -
The set of values in
this
.[[adapter]]
.[[features]]
. -
limits
, of type GPUSupportedLimits , readonly -
The limits in
this
.[[adapter]]
.[[limits]]
. -
isFallbackAdapter
, of type boolean , readonly -
Returns the value of
[[adapter]]
.[[fallback]]
.
GPUAdapter
has
the
following
internal
slots:
-
[[adapter]]
, of type adapter , readonly -
The adapter to which this
GPUAdapter
refers.
GPUAdapter
has
the
following
methods:
-
requestDevice(descriptor)
-
Requests a device from the adapter .
Called on:GPUAdapter
this .Arguments:
Arguments for the GPUAdapter.requestDevice(descriptor) method. Parameter Type Nullable Optional Description descriptor
GPUDeviceDescriptor ✘ ✔ Description of the GPUDevice
to request.Returns:
Promise
<GPUDevice
>-
Let promise be a new promise .
-
Let adapter be this .
[[adapter]]
. -
Issue the following steps to the Device timeline :
-
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 .
-
-
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" ,"depth24unorm-stencil8" ,"depth32float-stencil8" ,"texture-compression-bc" ,"texture-compression-etc2" ,"texture-compression-astc" ,"timestamp-query" ,"indirect-first-instance" ,"shader-f16" , };
4.4.
GPUDevice
A
GPUDevice
encapsulates
a
device
and
exposes
the
functionality
of
that
device.
GPUDevice
is
the
top-level
interface
through
which
WebGPU
interfaces
are
created.
To
get
a
GPUDevice
,
use
requestDevice()
.
[Exposed =(Window ,DedicatedWorker ),SecureContext ]interface GPUDevice :EventTarget { [SameObject ]readonly attribute GPUSupportedFeatures features ; [SameObject ]readonly attribute GPUSupportedLimits limits ; [SameObject ]readonly attribute GPUQueue queue ;undefined destroy ();GPUBuffer createBuffer (GPUBufferDescriptor descriptor );GPUTexture createTexture (GPUTextureDescriptor descriptor );GPUSampler createSampler (optional GPUSamplerDescriptor descriptor = {});GPUExternalTexture importExternalTexture (GPUExternalTextureDescriptor descriptor );GPUBindGroupLayout createBindGroupLayout (GPUBindGroupLayoutDescriptor descriptor );GPUPipelineLayout createPipelineLayout (GPUPipelineLayoutDescriptor descriptor );GPUBindGroup createBindGroup (GPUBindGroupDescriptor descriptor );GPUShaderModule createShaderModule (GPUShaderModuleDescriptor descriptor );GPUComputePipeline createComputePipeline (GPUComputePipelineDescriptor descriptor );GPURenderPipeline createRenderPipeline (GPURenderPipelineDescriptor descriptor );Promise <GPUComputePipeline >createComputePipelineAsync (GPUComputePipelineDescriptor descriptor );Promise <GPURenderPipeline >createRenderPipelineAsync (GPURenderPipelineDescriptor descriptor );GPUCommandEncoder createCommandEncoder (optional GPUCommandEncoderDescriptor descriptor = {});GPURenderBundleEncoder createRenderBundleEncoder (GPURenderBundleEncoderDescriptor descriptor );GPUQuerySet createQuerySet (GPUQuerySetDescriptor descriptor ); };GPUDevice includes GPUObjectBase ;
GPUDevice
has
the
following
attributes:
-
features
, of type GPUSupportedFeatures , readonly -
A set containing the
GPUFeatureName
values of the features supported by the device (i.e. the ones with which it was created). -
limits
, of type GPUSupportedLimits , readonly -
Exposes the limits supported by the device (which are exactly the ones with which it was created).
-
queue
, of type GPUQueue , readonly -
The primary
GPUQueue
for this device.
The
[[device]]
for
a
GPUDevice
is
the
device
that
the
GPUDevice
refers
to.
GPUDevice
has
the
methods
listed
in
its
WebIDL
definition
above.
Those
not
defined
here
are
defined
elsewhere
in
this
document.
-
destroy()
-
Destroys the device , preventing further operations on it. Outstanding asynchronous operations will fail.
Called on:GPUDevice
this .-
Lose the device ( this .
[[device]]
,"destroyed"
).
Note: Since no further operations can occur on this device, implementations can free resource allocations and abort outstanding asynchronous operations immediately.
-
GPUDevice
'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
in
the
mapped
or
unmapped
state.
[Exposed =(Window ,DedicatedWorker ),SecureContext ]interface GPUBuffer {Promise <undefined >mapAsync (GPUMapModeFlags mode ,optional GPUSize64 offset = 0,optional GPUSize64 size );ArrayBuffer getMappedRange (optional GPUSize64 offset = 0,optional GPUSize64 size );undefined unmap ();undefined destroy (); };GPUBuffer includes GPUObjectBase ;
GPUBuffer
has
the
following
internal
slots:
-
[[size]]
of typeGPUSize64
. -
The length of the
GPUBuffer
allocation in bytes. -
[[usage]]
of typeGPUBufferUsageFlags
. -
The allowed usages for this
GPUBuffer
. -
[[state]]
of type buffer state . -
The current state of the
GPUBuffer
. -
[[mapping]]
of typeArrayBuffer
orPromise
ornull
. -
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[[mapped_ranges]]
Specify
[[mapping]]
in term ofDataBlock
similarly toAllocateArrayBuffer
? [Issue #gpuweb/gpuweb#605] -
[[mapping_range]]
of type list <unsigned long long
> ornull
. -
The range of this
GPUBuffer
that is mapped. -
[[mapped_ranges]]
of type list <ArrayBuffer
> ornull
. -
The
ArrayBuffer
s returned viagetMappedRange
to the application. They are tracked so they can be detached whenunmap
is called. -
[[map_mode]]
of typeGPUMapModeFlags
. -
The
GPUMapModeFlags
of the last call tomapAsync()
(if any).
[[usage]]
is
differently
named
from
[[descriptor]]
.
usage
.
We
should
make
it
consistent.
Each
GPUBuffer
has
a
current
buffer
state
on
the
Content
timeline
which
is
one
of
the
following:
-
" mapped " where the
GPUBuffer
is available for CPU operations on its content. -
" mapped at creation " where the
GPUBuffer
was just created and is available for CPU operations on its content. -
" mapping pending " where the
GPUBuffer
is being made available for CPU operations on its content. -
" unmapped " where the
GPUBuffer
is available for GPU operations. -
" destroyed " where the
GPUBuffer
is no longer available for any operations exceptdestroy
.
Note:
[[size]]
and
[[usage]]
are
immutable
once
the
GPUBuffer
has
been
created.
GPUBuffer
has
a
state
machine
with
the
following
states.
(
[[mapping]]
,
[[mapping_range]]
,
and
[[mapped_ranges]]
are
null
when
not
specified.)
-
mapped or mapped at creation with an
ArrayBuffer
typed[[mapping]]
, a sequence of two numbers in[[mapping_range]]
and a sequence ofArrayBuffer
in[[mapped_ranges]]
-
mapping pending with a
Promise
typed[[mapping]]
.
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 ; };
This
specifies
GPUBufferDescriptor
has
the
options
to
use
following
members:
size
, of type GPUSize64The size of the buffer in
creating abytes.-
GPUBufferusage
, 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
guaranteestotrue
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 creation,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 )]{ = 0x0001; = 0x0002; = 0x0004; = 0x0008; = 0x0010; = 0x0020; = 0x0040; = 0x0080; = 0x0100; = 0x0200;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
-
If any of the following conditions are unsatisfied, return an error buffer and stop.
-
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.-
Let b be a new
GPUBuffer
object. -
If descriptor .
mappedAtCreation
istrue
:-
Set b .
[[mapping]]
to a newArrayBuffer
of size b .[[size]]
. -
Set b .
[[mapping_range]]
to[0, descriptor.size]
. -
Set b .
[[mapped_ranges]]
to[]
. -
Set b .
[[state]]
to mapped at creation .
Else:
-
Set b .
[[mapping]]
tonull
. -
Set b .
[[mapping_range]]
tonull
. -
Set b .
[[mapped_ranges]]
tonull
.
-
-
Set each byte of b ’s allocation to zero.
-
Return b .
Note: it is valid to set mappedAtCreation to true without MAP_READ or MAP_WRITE in usage . This can be used to set the buffer’s initial data. -
const buffer= gpuDevice. createBuffer({ size: 128 , usage: GPUBufferUsage. UNIFORM| GPUBufferUsage. COPY_DST});
5.3. Buffer Destruction
An
application
that
no
longer
requires
a
GPUBuffer
can
choose
to
lose
access
to
it
before
garbage
collection
by
calling
destroy()
.
Destroying
a
buffer
also
unmaps
it,
freeing
any
memory
allocated
for
the
mapping.
Note:
This
allows
the
user
agent
to
reclaim
the
GPU
memory
associated
with
the
GPUBuffer
once
all
previously
submitted
operations
using
it
are
complete.
-
destroy()
-
Destroys the
GPUBuffer
.
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.
Once
the
GPUBuffer
is
mapped
the
application
can
synchronously
ask
for
access
to
ranges
of
its
content
with
getMappedRange
.
A
mapped
GPUBuffer
cannot
be
used
by
the
GPU
and
must
be
unmapped
using
unmap
before
work
using
it
can
be
submitted
to
the
Queue
timeline
.
Add
client-side
validation
that
a
mapped
buffer
can
only
be
unmapped
and
destroyed
on
the
worker
on
which
it
was
mapped.
Likewise
getMappedRange
can
only
be
called
on
that
worker.
[Issue
#gpuweb/gpuweb#605]
typedef [EnforceRange ]unsigned long ; [
GPUMapModeFlags Exposed =(Window ,DedicatedWorker )]namespace {
GPUMapMode const GPUFlagsConstant = 0x0001;
READ const GPUFlagsConstant = 0x0002; };
WRITE
-
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. Returns:
Promise
<undefined
>Handle error buffers once we have a description of the error monad. [Issue #gpuweb/gpuweb#605]
-
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:
Then:
-
Record a validation error on the current scope.
-
Return a promise rejected with an
OperationError
on the Device timeline .
-
-
Let p be a new
Promise
. -
Set this .
[[mapping]]
to p . -
Set this .
[[state]]
to mapping pending . -
Set this .
[[map_mode]]
to mode . -
Enqueue an operation on the default queue’s Queue timeline that will execute the following:
-
If this .
[[state]]
is mapping pending :-
Let m be a new
ArrayBuffer
of size rangeSize . -
Set the content of m to the content of this ’s allocation starting at offset offset and for rangeSize bytes.
-
Set this .
[[mapping]]
to m . -
Set this .
[[mapping_range]]
to[ offset , offset + rangeSize ]
. -
Set this .
[[mapped_ranges]]
to[]
.
-
-
Resolve p .
-
-
Return p .
-
-
getMappedRange(offset, size)
-
Returns a
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
-
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 .
[[state]]
is mapped or mapped at creation . -
offset is a multiple of 8.
-
rangeSize is a multiple of 4.
-
offset is greater than or equal to this .
[[mapping_range]]
[0]. -
offset + rangeSize is less than or equal to this .
[[mapping_range]]
[1]. -
[ offset , offset + rangeSize ) does not overlap another range in this .
[[mapped_ranges]]
.
Note: It is always valid to get mapped ranges of a
GPUBuffer
that is mapped at creation , even if it is invalid , because the Content timeline might not know it is invalid. -
-
Let m be a new
ArrayBuffer
of size rangeSize pointing at the content of this .[[mapping]]
at offset offset - this .[[mapping_range]]
[0]. -
Append m to this .
[[mapped_ranges]]
. -
Return m .
-
-
unmap()
-
Unmaps the mapped range of the
GPUBuffer
and makes it’s contents available for use by the GPU again.Called on:GPUBuffer
this .Returns:
undefined
-
If any of the following requirements are unmet, generate a validation error and stop.
-
this .
[[state]]
must be mapped at creation , mapping pending , or mapped .
Note: It is valid to unmap an invalid
GPUBuffer
that is mapped at creation because the Content timeline might not know it is an errorGPUBuffer
. This allows the temporary[[mapping]]
memory to be freed. -
-
If this .
[[state]]
is mapping pending :-
Reject
[[mapping]]
with anAbortError
. -
Set this .
[[mapping]]
tonull
.
-
-
If this .
[[state]]
is mapped or mapped at creation :-
If one of the two following conditions holds:
-
this .
[[state]]
is mapped at creation -
this .
[[state]]
is mapped and this .[[map_mode]]
containsWRITE
Then:
-
Enqueue an operation on the default queue’s Queue timeline that updates the this .
[[mapping_range]]
of this ’s allocation to the content of this .[[mapping]]
.
-
-
Detach each
ArrayBuffer
in this .[[mapped_ranges]]
from its content. -
Set this .
[[mapping]]
tonull
. -
Set this .
[[mapping_range]]
tonull
. -
Set this .
[[mapped_ranges]]
tonull
.
-
Note: When a
MAP_READ
buffer (not currently mapped at creation) is unmapped, any local modifications done by the application to the mapped rangesArrayBuffer
are discarded and will not affect the content of follow-up mappings. -
6. Textures and Texture Views
define texture (internal object)
define mipmap level , array layer , aspect , slice (concepts)
6.1.
GPUTexture
GPUTextures
are
created
via
GPUDevice.createTexture(descriptor)
that
returns
a
new
texture.
[Exposed =(Window ,DedicatedWorker ),SecureContext ]interface GPUTexture {GPUTextureView createView (optional GPUTextureViewDescriptor descriptor = {});undefined destroy (); };GPUTexture includes GPUObjectBase ;
GPUTexture
has
the
following
internal
slots:
-
[[descriptor]]
, of typeGPUTextureDescriptor
-
The
GPUTextureDescriptor
describing this texture.All optional fields of
GPUTextureDescriptor
are defined. -
[[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 .
height
to max(1, baseSize . height ≫ mipLevel ). -
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 {; = 1; = 1; = "2d"; ; ;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 GPUTextureFormatThe format of the texture.
usage
, of type GPUTextureUsageFlagsThe 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 formats to this list may have a sizable performance impact, depending on the user’s system. It is best to avoid adding formats unnecessarily.
Formats in this list must be texture view format compatible with the texture format.
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 = 0x01; = 0x02; = 0x04; = 0x08; = 0x10;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
.)
-
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
-
Issue the following steps on the Device timeline of this :
-
If descriptor .
format
is aGPUTextureFormat
that requires a feature (see § 25.1 Texture Format Capabilities ), but this .[[device]]
.[[features]]
does not contain the feature, throw aTypeError
. -
If validating GPUTextureDescriptor ( this , descriptor ) returns false:
-
Return a new invalid
GPUTexture
.
-
Let t be a new
GPUTexture
object. -
Set t .
[[descriptor]]
to descriptor . -
Return t .
-
-
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 greater than zero. -
descriptor .
mipLevelCount
must be greater than zero. -
descriptor .
sampleCount
must be either 1 or 4. -
If descriptor .
dimension
is:-
"1d"
-
-
descriptor .
size
. width must be less than or equal to this .limits
.maxTextureDimension1D
. -
descriptor .
size
. depthOrArrayLayers must be 1. -
descriptor .
sampleCount
must be 1. -
descriptor .
format
must not be a compressed format or depth-or-stencil format .
-
-
"2d"
-
-
descriptor .
size
. width must be less than or equal to this .limits
.maxTextureDimension2D
. -
descriptor .
size
. height must be less than or equal to this .limits
.maxTextureDimension2D
. -
descriptor .
size
. depthOrArrayLayers must be less than or equal to this .limits
.maxTextureArrayLayers
.
-
-
"3d"
-
-
descriptor .
size
. width must be less than or equal to this .limits
.maxTextureDimension3D
. -
descriptor .
size
. height must be less than or equal to this .limits
.maxTextureDimension3D
. -
descriptor .
size
. depthOrArrayLayers must be less than or equal to this .limits
.maxTextureDimension3D
. -
descriptor .
sampleCount
must be 1. -
descriptor .
format
must not be a compressed format or depth-or-stencil format .
-
-
-
descriptor .
size
. width must be multiple of texel block width . -
descriptor .
size
. height must be multiple of texel block height . -
If descriptor .
sampleCount
> 1:-
descriptor .
mipLevelCount
must be 1. -
descriptor .
size
. depthOrArrayLayers must be 1. -
descriptor .
usage
must not include 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 less than or equal to maximum mipLevel count ( descriptor .dimension
, descriptor .size
). -
descriptor .
usage
must be a combination ofGPUTextureUsage
values. -
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
.
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 = "all";
aspect = 0; ; = 0; ;GPUIntegerCoordinate = 0;
baseMipLevel GPUIntegerCoordinate ;
mipLevelCount GPUIntegerCoordinate = 0;
baseArrayLayer GPUIntegerCoordinate ; };
arrayLayerCount
enum {
GPUTextureViewDimension "1d" ,"2d" ,"2d-array" ,"cube" ,"cube-array" ,"3d" , };
-
"1d"
-
The texture is viewed as a 1-dimensional image.
Corresponding WGSL types:
-
texture_1d
-
texture_storage_1d
-
-
"2d"
-
The texture is viewed as a single 2-dimensional image.
Corresponding WGSL types:
-
texture_2d
-
texture_storage_2d
-
texture_multisampled_2d
-
texture_depth_2d
-
texture_depth_multisampled_2d
-
-
"2d-array"
-
The texture view is viewed as an array of 2-dimensional images.
Corresponding WGSL types:
-
texture_2d_array
-
texture_storage_2d_array
-
texture_depth_2d_array
-
-
"cube"
-
The texture is viewed as a cubemap. The view has 6 array layers, corresponding to the [+X, -X, +Y, -Y, +Z, -Z] faces of the cube. Sampling is done seamlessly across the faces of the cubemap.
Corresponding WGSL types:
-
texture_cube
-
texture_depth_cube
-
-
"cube-array"
-
The texture is viewed as a packed array of
n
cubemaps, each with 6 array layers corresponding to the [+X, -X, +Y, -Y, +Z, -Z] faces of the cube. Sampling is done seamlessly across the faces of the cubemaps.Corresponding WGSL types:
-
texture_cube_array
-
texture_depth_cube_array
-
-
"3d"
-
The texture is viewed as a 3-dimensional image.
Corresponding WGSL types:
-
texture_3d
-
texture_storage_3d
-
enum {
GPUTextureAspect ,
"all" ,
"stencil-only" , };
"depth-only"
-
createView(descriptor)
-
Creates a
GPUTextureView
.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 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
.-
Set descriptor to the result of resolving GPUTextureViewDescriptor defaults for this with descriptor .
-
Issue the following steps on the Device timeline of this :
-
If any of the following requirements are unmet:
-
this is valid
-
descriptor .
aspect
must be present in this .[[descriptor]]
.format
. -
If the descriptor .
aspect
is"all"
:-
descriptor .
format
must be equal to either this .[[descriptor]]
.format
or one of the formats in this .[[descriptor]]
.viewFormats
.
Otherwise:
-
descriptor .
format
must be equal to the result of resolving GPUTextureAspect ( this .[[descriptor]]
.format
, descriptor .aspect
).
-
-
descriptor .
mipLevelCount
must be > 0. -
descriptor .
baseMipLevel
+ descriptor .mipLevelCount
must be ≤ this .[[descriptor]]
.mipLevelCount
. -
descriptor .
arrayLayerCount
must be > 0. -
descriptor .
baseArrayLayer
+ descriptor .arrayLayerCount
must be ≤ the array layer count of this . -
If this .
[[descriptor]]
.sampleCount
is > 1, descriptor .dimension
must be"2d"
. -
If descriptor .
dimension
is:-
"1d"
-
this .
[[descriptor]]
.dimension
must be"1d"
.descriptor .
arrayLayerCount
must be1
. -
"2d"
-
this .
[[descriptor]]
.dimension
must be"2d"
.descriptor .
arrayLayerCount
must be1
. -
"2d-array"
-
this .
[[descriptor]]
.dimension
must be"2d"
. -
"cube"
-
this .
[[descriptor]]
.dimension
must be"2d"
.descriptor .
arrayLayerCount
must be6
.this .
[[descriptor]]
.size
. width must be this .[[descriptor]]
.size
. height . -
"cube-array"
-
this .
[[descriptor]]
.dimension
must be"2d"
.descriptor .
arrayLayerCount
must be a multiple of6
.this .
[[descriptor]]
.size
. width must be this .[[descriptor]]
.size
. height . -
"3d"
-
this .
[[descriptor]]
.dimension
must be"3d"
.descriptor .
arrayLayerCount
must be1
.
-
Then:
-
Return a new invalid
GPUTextureView
.
-
-
Let view be a new
GPUTextureView
object. -
Set view .
[[texture]]
to this . -
Set view .
[[descriptor]]
to descriptor . -
If this .
[[descriptor]]
.usage
containsRENDER_ATTACHMENT
:-
Let renderExtent be compute render extent ( this .
[[descriptor]]
.size
, descriptor .baseMipLevel
). -
Set view .
[[renderExtent]]
to renderExtent .
-
-
Return view .
-
-
GPUTextureView
texture
with
a
GPUTextureViewDescriptor
descriptor
run
the
following
steps:
-
Let resolved be a copy of descriptor .
-
If resolved .
format
isundefined
,-
Let format be the result of resolving GPUTextureAspect (
[[descriptor]]
.format
, descriptor .aspect
). -
If format is
null
:-
Set resolved .
format
to texture .[[descriptor]]
.format
.
Otherwise:
-
Set resolved .
format
to format .
-
-
-
If resolved .
mipLevelCount
isundefined
, set resolved .mipLevelCount
to texture .[[descriptor]]
.mipLevelCount
− resolved .baseMipLevel
. -
If resolved .
dimension
isundefined
and texture .[[descriptor]]
.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 .
[[descriptor]]
.dimension
is:-
"1d"
or"3d"
-
Return
1
. -
"2d"
-
Return texture .
[[descriptor]]
.size
. 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" , // "depth24unorm-stencil8" feature
"depth32float" , // "depth32float-stencil8" feature
"depth24unorm-stencil8" , // 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"
in
"depth24unorm-stencil8"
)
or
a
32-bit
IEEE
754
floating
point
value
(like
"depth32float"
).
add
something
on
GPUAdapter(?)
that
gives
an
estimate
of
the
bytes
per
texel
of
"stencil8"
,
"depth24plus-stencil8"
,
and
"depth32float-stencil8"
.
The
stencil8
format
may
be
implemented
as
either
a
real
"stencil8",
or
"depth24stencil8",
where
the
depth
aspect
is
hidden
and
inaccessible.
Note: While the precision of depth32float channels is strictly higher than the precision of depth24unorm channels for all values in the representable range (0.0 to 1.0), note that the set of representable values is not an exact superset: for depth24unorm, 1 ULP has a constant value of 1 / (2 24 − 1); for depth32float, 1 ULP has a variable value no greater than 1 / (2 24 ).
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
.
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
has
the
following
"static"
internal
slots:
-
[[active_imports]]
, of type list <GPUExternalTexture> -
A list of all imported textures which have not yet been closed. The items in list are checked during each animation frame to determine whether to close them.
6.4.1. Importing External Textures
An
external
texture
is
created
from
an
external
video
object
using
importExternalTexture()
.
External
textures
created
from
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 GPUPredefinedColorSpace = "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
-
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:
The
steps
above
occur
before
requestVideoFrameCallback
callbacks,
if
any.
If
requestVideoFrameCallback
is
implemented,
stale
GPUExternalTexture
s
could
equivalently
be
said
to
be
destroyed
in
a
"priority"
requestVideoFrameCallback
callback
that
occurs
just
before
user-specified
callbacks.
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 = "clamp-to-edge";
addressModeU GPUAddressMode = "clamp-to-edge";
addressModeV GPUAddressMode = "clamp-to-edge";
addressModeW GPUFilterMode = "nearest";
magFilter GPUFilterMode = "nearest";
minFilter GPUMipmapFilterMode = "nearest";
mipmapFilter float = 0;
lodMinClamp float = 32;
lodMaxClamp GPUCompareFunction ; [
compare Clamp ]unsigned short = 1; };
maxAnisotropy
-
addressModeU
,addressModeV
, andaddressModeW
specify the address modes for the texture width, height, and depth coordinates, respectively. -
magFilter
specifies the sampling behavior when the sample footprint is smaller than or equal to one texel. -
minFilter
specifies the sampling behavior when the sample footprint is larger than one texel. -
mipmapFilter
specifies behavior for sampling between two mipmap levels. -
lodMinClamp
andlodMaxClamp
specify the minimum and maximum levels of detail, respectively, used internally when sampling a texture. -
If
compare
is provided, the sampler will be a comparison sampler with the specifiedGPUCompareFunction
. Comparison samplers may use filtering, but the sampling results will be implementation-dependent and may differ from the normal filtering rules. -
maxAnisotropy
specifies the maximum anisotropy value clamp used by the sampler.Note: Most implementations support
maxAnisotropy
values in range between 1 and 16, inclusive. The used value 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.
Arguments:
-
GPUDevice
device -
GPUSamplerDescriptor
descriptor
Returns:
boolean
Return
true
if
and
only
if
all
of
the
following
conditions
are
satisfied:
-
device is valid.
-
descriptor .
lodMinClamp
is greater than or equal to 0. -
descriptor .
lodMaxClamp
is greater than or equal to descriptor .lodMinClamp
. -
descriptor .
maxAnisotropy
is greater than or equal to 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. -
When descriptor .
maxAnisotropy
is greater than 1, descriptor .magFilter
, descriptor .minFilter
, and descriptor .mipmapFilter
must be equal to"linear"
.
-
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
-
Let s be a new
GPUSampler
object. -
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
. -
Return s .
Valid Usage-
If descriptor is not
null
or undefined:-
If validating GPUSamplerDescriptor (this, descriptor ) returns
false
:-
Create a new invalid
GPUSampler
and return the result.
-
-
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
.
typedef [EnforceRange ]unsigned long ; [
GPUShaderStageFlags Exposed =(Window ,DedicatedWorker )]namespace {
GPUShaderStage const GPUFlagsConstant = 0x1;
VERTEX const GPUFlagsConstant = 0x2;
FRAGMENT const GPUFlagsConstant = 0x4; };
COMPUTE dictionary {
GPUBindGroupLayoutEntry required GPUIndex32 binding ;required GPUShaderStageFlags visibility ;;GPUBufferBindingLayout buffer ;GPUSamplerBindingLayout sampler ;; ;GPUTextureBindingLayout texture ;GPUStorageTextureBindingLayout storageTexture ;GPUExternalTextureBindingLayout externalTexture ; };
GPUBindGroupLayoutEntry
dictionaries
have
the
following
members:
-
binding
, of type GPUIndex32 -
A unique identifier for a resource binding within a
GPUBindGroupLayoutEntry
, a correspondingGPUBindGroupEntry
, and theGPUShaderModule
s. -
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
.
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 = "uniform"; ; = 0;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
-
Let layout be a new valid
GPUBindGroupLayout
object. -
Set layout .
[[descriptor]]
to descriptor . -
Issue the following steps on the Device timeline of this :
-
If any of the following conditions are unsatisfied:
-
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"
or"depth"
.
-
-
If storageTextureLayout is not
undefined
:-
storageTextureLayout .
viewDimension
is not"cube"
or"cube-array"
. -
storageTextureLayout .
format
must be a format which can support storage usage.
-
-
Then:
-
Make layout invalid and return layout .
-
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
.
-
-
-
Return layout .
-
8.1.2. Compatibility
GPUBindGroupLayout
objects
a
and
b
are
considered
group-equivalent
if
and
only
if
all
of
the
following
conditions
are
satisfied:
-
a .
[[exclusivePipeline]]
== b .[[exclusivePipeline]]
. -
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 ;
8.2.1. Bind Group Creation
A
GPUBindGroup
is
created
via
GPUDevice.createBindGroup()
.
dictionary :
GPUBindGroupDescriptor GPUObjectDescriptorBase {required GPUBindGroupLayout ;
layout required sequence <GPUBindGroupEntry >; };
entries
A
GPUBindGroupEntry
describes
a
single
resource
to
be
bound
in
a
GPUBindGroup
.
typedef (GPUSampler or GPUTextureView or GPUBufferBinding or GPUExternalTexture );
GPUBindingResource dictionary {
GPUBindGroupEntry required GPUIndex32 ;
binding required GPUBindingResource ; };
resource
dictionary {
GPUBufferBinding required GPUBuffer ;
buffer = 0; ;GPUSize64 = 0;
offset GPUSize64 ; };
size
A
GPUBindGroup
object
has
the
following
internal
slots:
-
[[layout]]
of typeGPUBindGroupLayout
. -
The
GPUBindGroupLayout
associated with thisGPUBindGroup
. -
[[entries]]
of type sequence<GPUBindGroupEntry
>. -
The set of
GPUBindGroupEntry
s thisGPUBindGroup
describes. -
[[usedResources]]
of type ordered map < subresource , list < internal usage >>. -
The set of buffer and texture subresource s used by this bind group, associated with lists of the internal usage flags.
-
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
-
Let bindGroup be a new valid
GPUBindGroup
object. -
Let limits be this .
[[device]]
.[[limits]]
. -
Issue the following steps on the Device timeline of this :
-
If any of the following conditions are unsatisfied:
-
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 ), is greater than or equal to layoutBinding .
buffer
.minBindingSize
. -
If layoutBinding .
buffer
.type
is-
"uniform"
-
resource .
buffer
.usage
includesUNIFORM
.effective buffer binding size ( resource ) ≤ limits .
maxUniformBufferBindingSize
.resource .
offset
is a multiple of limits .minUniformBufferOffsetAlignment
. -
"storage"
or"read-only-storage"
-
resource .
buffer
.usage
includesSTORAGE
.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 .
-
-
Then:
-
Make bindGroup invalid and return bindGroup .
-
-
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 .
-
-
-
Return bindGroup .
-
GPUBufferBinding
objects
a
and
b
are
considered
buffer-binding-aliasing
if
and
only
if
all
of
the
following
are
true:
-
The range formed by a .
offset
and a .size
intersects the range formed by b .offset
and b .size
.
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
-
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
-
If any of the following requirements are unmet:
Let limits be this .[[device]]
.[[limits]]
.Let allEntries be the result of concatenating bgl .
[[descriptor]]
.entries
for all bgl in descriptor .bindGroupLayouts
.-
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 .
Then:
-
Create a new invalid
GPUPipelineLayout
and return the result.
-
-
Let pl be a new
GPUPipelineLayout
object. -
Set the pl .
[[bindGroupLayouts]]
to descriptor .bindGroupLayouts
. -
Return pl .
-
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 {
GPUShaderModuleCompilationHint required (GPUPipelineLayout or GPUAutoLayoutMode ); };
layout dictionary :
GPUShaderModuleDescriptor GPUObjectDescriptorBase {required USVString ;
code object ;
sourceMap record <USVString ,GPUShaderModuleCompilationHint >; };
hints
sourceMap
,
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
,
if
defined,
maps
an
entry
point
name
from
the
shader
to
a
GPUShaderModuleCompilationHint
.
No
validation
is
performed
with
any
of
these
GPUShaderModuleCompilationHint
.
Implementations
should
use
any
information
present
in
the
GPUShaderModuleCompilationHint
to
perform
as
much
compilation
as
is
possible
within
createShaderModule()
.
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
in
createShaderModule()
rather
than
multiple
times
in
the
multiple
calls
to
createComputePipeline()
/
createRenderPipeline()
.
Note:
If
possible,
authors
should
be
supplying
the
same
information
to
createShaderModule()
and
createComputePipeline()
/
createRenderPipeline()
.
Note:
If
an
author
is
unable
to
provide
this
hints
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()
.
Note:
If
an
author
is
not
confident
that
the
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.
-
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
Describe
createShaderModule()
algorithm steps.
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)); @stage(vertex) fn vertexMain(@builtin(vertex_index) vertexIndex : u32) -> @builtin(position) vec4<f32> { return vec4(pos[input.vertexIndex], 1.0, 1.0); } @stage(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.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
this.Returns:
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 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
this .Arguments:
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.
-
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
comparison_sampler
.
-
-
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 type
texture_1d<T>
,texture_2d<T>
,texture_2d_array<T>
,texture_cube<T>
,texture_cube_array<T>
,texture_3d<T>
, ortexture_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 type
texture_depth_2d
,texture_depth_2d_array
,texture_depth_cube
,texture_depth_cube_array
, ortexture_depth_multisampled_2d
.
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
dictionary :
GPUComputePipelineDescriptor GPUPipelineDescriptorBase {required GPUProgrammableStage ; };
compute
-
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
-
Let pipeline be a new valid
GPUComputePipeline
object. -
Issue the following steps on the Device timeline of this :
-
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:
-
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
].
Then:
-
Make pipeline invalid .
-
-
Set pipeline .
[[layout]]
to layout .
-
-
Return pipeline .
-
-
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
>-
Let promise be a new promise .
-
Issue the following steps on the Device timeline of this :
-
Let pipeline be a new
GPUComputePipeline
created as if this .createComputePipeline()
was called with descriptor ; -
When pipeline is ready to be used, resolve promise with pipeline .
-
-
Return promise .
-
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
dictionary :
GPURenderPipelineDescriptor GPUPipelineDescriptorBase {required GPUVertexState ;
vertex GPUPrimitiveState = {};
primitive GPUDepthStencilState ;
depthStencil GPUMultisampleState = {};
multisample GPUFragmentState ; };
fragment
A
GPURenderPipelineDescriptor
describes
the
state
of
a
render
pipeline
by
configuring
each
of
the
render
stages
.
See
§ 22.3
Rendering
for
the
details.
-
vertex
describes the vertex shader entry point of the pipeline and its input buffer layouts. -
primitive
describes the primitive-related properties of the pipeline . -
depthStencil
describes the optional depth-stencil properties, including the testing, operations, and bias. -
multisample
describes the multi-sampling properties of the pipeline . -
fragment
describes the fragment shader entry point of the pipeline and its output colors. If it’snull
, 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
-
Let pipeline be a new valid
GPURenderPipeline
object. -
Issue the following steps on the Device timeline of this :
-
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:
-
layout is valid to use with this .
-
validating GPURenderPipelineDescriptor ( descriptor , layout , this ) succeeds.
Then:
-
Make pipeline invalid .
-
-
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 .
-
-
Return pipeline .
-
-
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
>-
Let promise be a new promise .
-
Issue the following steps on the Device timeline of this :
-
Let pipeline be a new
GPURenderPipeline
created as if this .createRenderPipeline()
was called with descriptor ; -
When pipeline is ready to be used, resolve promise with pipeline .
-
-
Return promise .
-
-
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 output of descriptor .
vertex
there must be a user-defined input of descriptor .fragment
that matches the location , type, and interpolation of the output. -
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. -
There is less than device .limits.
maxInterStageShaderComponents
components of user-defined outputs for descriptor .vertex
. -
There is less than device .limits.
maxInterStageShaderComponents
components of user-defined inputs for descriptor .fragment
.
should
we
validate
that
cullMode
is
none
for
points
and
lines?
define what "compatible" means for render target formats.
need a proper limit for the maximum number of color targets.
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
enum {
GPUPrimitiveTopology ,
"point-list" ,
"line-list" ,
"line-strip" ,
"triangle-list" , };
"triangle-strip"
dictionary {
GPUPrimitiveState GPUPrimitiveTopology = "triangle-list";
topology GPUIndexFormat ;
stripIndexFormat GPUFrontFace = "ccw";
frontFace GPUCullMode = "none"; // Requires "depth-clip-control" feature.
cullMode ;boolean =
unclippedDepth false ; };
-
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 {
GPUFrontFace ,
"ccw" , };
"cw"
enum {
GPUCullMode ,
"none" ,
"front" , };
"back"
10.3.3. Multisample State
dictionary {
GPUMultisampleState = 1;GPUSize32 = 1;
count GPUSampleMask = 0xFFFFFFFF;
mask ;boolean =
alphaToCoverageEnabled false ; };
-
GPUMultisampleState
descriptor
Return
true
if
all
of
the
following
conditions
are
satisfied:
-
If descriptor .
alphaToCoverageEnabled
istrue
:-
descriptor .
count
is greater than 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 = "add";
operation GPUBlendFactor = "one";
srcFactor GPUBlendFactor = "zero"; };
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"
enum {
GPUBlendOperation ,
"add" ,
"subtract" ,
"reverse-subtract" ,
"min" , };
"max"
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; };
dictionary {
GPUStencilFaceState GPUCompareFunction compare = "always";GPUStencilOperation failOp = "keep";GPUStencilOperation depthFailOp = "keep";GPUStencilOperation passOp = "keep"; };
enum {
GPUStencilOperation "keep" ,"zero" ,"replace" ,"invert" ,"increment-clamp" ,"decrement-clamp" ,"increment-wrap" ,"decrement-wrap" , };
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
-
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.
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
.
-
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 default values:-
descriptor .
format
must have a stencil component.
-
how can this algorithm support depth/stencil formats that are added in extensions?
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 name of the format specifies the order of components, bits per component, and vertex data type for the component.
-
unorm
= unsigned normalized -
snorm
= signed normalized -
uint
= unsigned int -
sint
= signed int -
float
= floating point
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"
The
multi-component
formats
specify
the
number
of
components
after
"x".
As
such,
"sint32x3"
denotes
a
3-component
vector
of
i32
values
in
the
shader.
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 = "vertex";
stepMode required sequence <GPUVertexAttribute >; };
attributes
dictionary {
GPUVertexAttribute required GPUVertexFormat ;
format ;required GPUSize64 ;
offset required GPUIndex32 ; };
shaderLocation
-
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 less than 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
.
-
-
GPUDevice
device -
GPUVertexState
descriptor
Return
true
,
if
and
only
if,
all
of
the
following
conditions
are
satisfied:
-
descriptor .
buffers
.length is less than or equal to 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 less than or equal to 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.
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 generates a
GPUValidationError
.
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 source ,GPUImageCopyTexture destination ,);GPUExtent3D copySize );undefined clearBuffer (GPUBuffer buffer ,= 0, );optional GPUSize64 offset = 0,optional GPUSize64 size ););undefined writeTimestamp (GPUQuerySet querySet ,GPUSize32 queryIndex );(undefined resolveQuerySet (GPUQuerySet querySet ,, ,GPUSize32 firstQuery ,GPUSize32 queryCount ,GPUBuffer destination ,);GPUSize64 destinationOffset );GPUCommandBuffer finish (optional GPUCommandBufferDescriptor descriptor = {}); };GPUCommandEncoder includes GPUObjectBase ;GPUCommandEncoder includes GPUCommandsMixin ;GPUCommandEncoder includes GPUDebugCommandsMixin ;
12.2.1. Creation
dictionary :
GPUCommandEncoderDescriptor GPUObjectDescriptorBase { };
-
createCommandEncoder(descriptor)
-
Creates a
GPUCommandEncoder
.Called on:GPUDevice
this.Arguments:
Arguments for the GPUDevice.createCommandEncoder(descriptor) method. Parameter Type Nullable Optional Description descriptor
GPUCommandEncoderDescriptor ✘ ✔ Description of the GPUCommandEncoder
to create.Returns:
GPUCommandEncoder
Describe
createCommandEncoder()
algorithm steps.
GPUCommandEncoder
,
encoding
a
command
to
clear
a
buffer,
finishing
the
encoder
to
get
a
GPUCommandBuffer
,
then
submitting
it
to
the
GPUQueue
.
const commandEncoder= gpuDevice. createCommandEncoder(); commandEncoder. clearBuffer( buffer); const commandBuffer= commandEncoder. finish(); gpuDevice. queue. submit([ commandBuffer]);
12.3. Pass Encoding
-
beginRenderPass(descriptor)
-
Begins encoding a render pass described by descriptor .
Called on:GPUCommandEncoder
this .Arguments:
Arguments for the GPUCommandEncoder.beginRenderPass(descriptor) method. Parameter Type Nullable Optional Description descriptor
GPURenderPassDescriptor ✘ ✘ Description of the GPURenderPassEncoder
to create.Returns:
GPURenderPassEncoder
Issue the following steps on the Device timeline of this :
-
Let pass be a new
GPURenderPassEncoder
object. -
If any of the following conditions are unsatisfied, generate a validation error and stop.
-
descriptor meets the Valid Usage rules.
-
descriptor .
timestampWrites
is empty, or this .[[device]]
.[[features]]
contain s"timestamp-query"
. -
For each timestampWrite in descriptor .
timestampWrites
,-
timestampWrite .
querySet
is valid to use with this .
-
-
For each non-
null
colorAttachment in descriptor .colorAttachments
:-
The texture subresource seen by colorAttachment .
view
is considered to be used as attachment for the duration of the render pass.
-
-
Let depthStencilAttachment be descriptor .
depthStencilAttachment
. -
If depthStencilAttachment is not
null
:-
Let depthStencilView be depthStencilAttachment .
view
. -
If depthStencilAttachment .
depthReadOnly
andstencilReadOnly
aretrue
:-
The texture subresources seen by depthStencilView are considered to be used as attachment-read for the duration of the render pass.
Describe this in terms of a "set of subresources of" algorithm.
-
-
Else, the texture subresource seen by depthStencilView is considered to be used as attachment for the duration of the render pass.
-
Set pass .
[[depthReadOnly]]
to depthStencilAttachment .depthReadOnly
. -
Set pass .
[[stencilReadOnly]]
to depthStencilAttachment .stencilReadOnly
.
-
-
Set pass .
[[layout]]
to derive render targets layout from pass ( descriptor ). -
For each timestampWrite in descriptor .
timestampWrites
,-
If timestampWrite .
location
is"beginning"
, append a GPU command to this .[[commands]]
that writes the GPU’s timestamp value into the timestampWrite .queryIndex
th index in timestampWrite .querySet
. -
Otherwise, if timestampWrite .
location
is"end"
, Append timestampWrite to pass .[[endTimestampWrites]]
.
-
-
Return pass .
-
-
beginComputePass(descriptor)
-
Begins encoding a compute pass described by descriptor .
Called on:GPUCommandEncoder
this .Arguments:
Arguments for the GPUCommandEncoder.beginComputePass(descriptor) method. Parameter Type Nullable Optional Description descriptor
GPUComputePassDescriptor ✘ ✔ Returns:
GPUComputePassEncoder
Issue the following steps on the Device timeline of this :
-
If any of the following conditions are unsatisfied, generate a validation error and stop.
-
descriptor .
timestampWrites
is empty, or this .[[device]]
.[[features]]
contain s"timestamp-query"
. -
For each timestampWrite in descriptor .
timestampWrites
,-
timestampWrite .
querySet
is valid to use with this .
-
-
Let pass be a new
GPUComputePassEncoder
object. -
For each timestampWrite in descriptor .
timestampWrites
,-
If timestampWrite .
location
is"beginning"
, append a GPU command to this .[[commands]]
that writes the GPU’s timestamp value into the timestampWrite .queryIndex
th index in timestampWrite .querySet
. -
Otherwise, if timestampWrite .
location
is"end"
, Append timestampWrite to pass .[[endTimestampWrites]]
.
-
-
Return pass .
-
12.4. Copy Commands
these dictionary definitions should be inside the image copies section.
12.4.1.
GPUImageDataLayout
dictionary GPUImageDataLayout {= 0; ; ;GPUSize64 = 0;
offset GPUSize32 bytesPerRow ;GPUSize32 rowsPerImage ; };
A
GPUImageDataLayout
is
a
layout
of
images
within
some
linear
memory.
It’s
used
when
copying
data
between
a
texture
and
a
buffer
,
or
when
scheduling
a
write
into
a
texture
from
the
GPUQueue
.
-
For
2d
textures, data is copied between one or multiple contiguous images and array layers . -
For
3d
textures, data is copied between one or multiple contiguous images and depth slices .
Define images more precisely. In particular, define them as being comprised of texel blocks .
Operations that copy between byte arrays and textures always work with rows of texel blocks , which we’ll call block row s. It’s not possible to update only a part of a texel block .
Texel blocks are tightly packed within each block row in the linear memory layout of an image copy, with each subsequent texel block immediately following the previous texel block, with no padding. This includes copies to/from specific aspects of depth-or-stencil format textures: stencil values are tightly packed in an array of bytes; depth values are tightly packed in an array of the appropriate type ("depth16unorm" or "depth32float").
Define the exact copy semantics, by reference to common algorithms shared by the copy methods.
-
bytesPerRow
, of type GPUSize32 -
The stride, in bytes, between the beginning of each block row and the subsequent block row .
Required if there are multiple block rows (i.e. the copy height or depth is more than one block).
-
rowsPerImage
, of type GPUSize32 -
Number of block rows per single image of the texture .
rowsPerImage
×bytesPerRow
is the stride, in bytes, between the beginning of each image of data and the subsequent image .Required if there are multiple images (i.e. the copy depth is more than one).
12.4.2.
GPUImageCopyBuffer
In
an
image
copy
operation,
GPUImageCopyBuffer
defines
a
GPUBuffer
and,
together
with
the
copySize
,
how
image
data
is
laid
out
in
the
buffer’s
memory
(see
GPUImageDataLayout
).
dictionary GPUImageCopyBuffer :GPUImageDataLayout {required GPUBuffer ; };
buffer
Arguments:
-
GPUImageCopyBuffer
imageCopyBuffer
Returns:
boolean
Return
true
if
and
only
if
all
of
the
following
conditions
are
satisfied:
-
imageCopyBuffer .
bytesPerRow
must be a multiple of 256.
12.4.3.
GPUImageCopyTexture
In
an
image
copy
operation,
a
GPUImageCopyTexture
defines
a
GPUTexture
and,
together
with
the
copySize
,
the
sub-region
of
the
texture
(spanning
one
or
more
contiguous
texture
subresources
at
the
same
mip-map
level).
dictionary GPUImageCopyTexture {; = 0;required GPUTexture texture ;GPUIntegerCoordinate mipLevel = 0;GPUOrigin3D origin = {};GPUTextureAspect aspect = "all"; };
-
texture
, of type GPUTexture -
Texture to copy to/from.
-
mipLevel
, of type GPUIntegerCoordinate , defaulting to0
-
Mip-map level of the
texture
to copy to/from. -
origin
, of type GPUOrigin3D , defaulting to{}
-
Defines the origin of the copy - the minimum corner of the texture sub-region to copy to/from. Together with
copySize
, defines the full copy sub-region. -
aspect
, of type GPUTextureAspect , defaulting to"all"
-
Defines which aspects of the
texture
to copy to/from.
Arguments:
-
GPUImageCopyTexture
imageCopyTexture -
GPUExtent3D
copySize
Returns:
boolean
Let:
-
blockWidth be the texel block width of imageCopyTexture .
texture
.[[descriptor]]
.format
. -
blockHeight be the texel block height of imageCopyTexture .
texture
.[[descriptor]]
.format
.
Return
true
if
and
only
if
all
of
the
following
conditions
apply:
-
imageCopyTexture .
texture
must be a validGPUTexture
. -
imageCopyTexture .
mipLevel
must be less than the[[descriptor]]
.mipLevelCount
of imageCopyTexture .texture
. -
imageCopyTexture .
origin
. x must be a multiple of blockWidth . -
imageCopyTexture .
origin
. y must be a multiple of blockHeight . -
The imageCopyTexture subresource size of imageCopyTexture is equal to copySize if either of the following conditions is true:
-
imageCopyTexture .
texture
.[[descriptor]]
.format
is a depth-stencil format. -
imageCopyTexture .
texture
.[[descriptor]]
.sampleCount
is greater than 1.
-
Define
the
copies
with
1d
and
3d
textures.
[Issue
#gpuweb/gpuweb#69]
12.4.4.
GPUImageCopyTextureTagged
WebGPU
textures
hold
raw
numeric
data,
and
are
not
tagged
with
semantic
metadata
describing
colors.
However,
copyExternalImageToTexture()
copies
from
sources
that
describe
colors.
A
GPUImageCopyTextureTagged
is
a
GPUImageCopyTexture
which
is
additionally
tagged
with
color
space/encoding
and
alpha-premultiplication
metadata,
so
that
semantic
color
data
may
be
preserved
during
copies.
This
metadata
affects
only
the
semantics
of
the
copyExternalImageToTexture()
operation,
not
the
semantics
of
the
destination
texture.
dictionary GPUImageCopyTextureTagged :GPUImageCopyTexture {GPUPredefinedColorSpace colorSpace = "srgb";;boolean premultipliedAlpha =false ; };
-
colorSpace
, of type GPUPredefinedColorSpace , defaulting to"srgb"
-
Describes the color space and encoding used to encode data into the destination texture.
This may result in values outside of the range [0, 1] being written to the target texture, if its format can represent them. Otherwise, the results are clamped to the target texture format’s range.
Note: If
colorSpace
matches the source image, no conversion occurs.ImageBitmap
color space tagging and conversion can be controlled viaImageBitmapOptions
. -
premultipliedAlpha
, of type boolean , defaulting tofalse
-
Describes whether the data written into the texture should be have its RGB channels premultiplied by the alpha channel, or not.
If this option is set to
true
and thesource
is also premultiplied, the source RGB values must be preserved even if they exceed their corresponding alpha values.Note: If
premultipliedAlpha
matches the source image, no conversion occurs. 2d canvases are always premultiplied , while WebGL canvases can be controlled via WebGLContextAttributes .ImageBitmap
premultiplication can be controlled viaImageBitmapOptions
.
Define
(and
test)
the
encoding
of
color
values
into
the
various
encodings
allowed
by
copyExternalImageToTexture()
.
12.4.5.
GPUImageCopyExternalImage
dictionary GPUImageCopyExternalImage {required (ImageBitmap or HTMLCanvasElement or OffscreenCanvas )source ;GPUOrigin2D origin = {};;boolean flipY =false ; };
GPUImageCopyExternalImage
has
the
following
members:
-
source
, of type(ImageBitmap or HTMLCanvasElement or OffscreenCanvas)
-
The source of the image copy . The copy source data is captured at the moment that
copyExternalImageToTexture()
is issued. -
origin
, of type GPUOrigin2D , defaulting to{}
-
Defines the origin of the copy - the minimum (top-left) corner of the source sub-region to copy from. Together with
copySize
, defines the full copy sub-region. -
flipY
, of type boolean , defaulting tofalse
-
Describes whether the source image is vertically flipped, or not.
If this option is set to
true
, the copy is flipped vertically: the bottom row of the source region is copied into the first row of the destination region, and so on. Theorigin
option is still relative to the top-left corner of the source image, increasing downward.
12.4.6. Buffer Copies
-
copyBufferToBuffer(source, sourceOffset, destination, destinationOffset, size)
-
Encode a command into the
GPUCommandEncoder
that copies data from a sub-region of aGPUBuffer
to a sub-region of anotherGPUBuffer
.Called on:GPUCommandEncoder
this .Arguments:
Arguments for the GPUCommandEncoder.copyBufferToBuffer(source, sourceOffset, destination, destinationOffset, size) method. Parameter Type Nullable Optional Description source
GPUBuffer ✘ ✘ The GPUBuffer
to copy from.sourceOffset
GPUSize64 ✘ ✘ Offset in bytes into source to begin copying from. destination
GPUBuffer ✘ ✘ The GPUBuffer
to copy to.destinationOffset
GPUSize64 ✘ ✘ Offset in bytes into destination to place the copied data. size
GPUSize64 ✘ ✘ Bytes to copy. Returns:
undefined
Issue the following steps on the Device timeline of this .
[[device]]
:-
Validate the encoder state of this . If it returns false, stop.
-
If any of the following conditions are unsatisfied, make this invalid and stop.
-
source is valid to use with this .
-
destination is valid to use with this .
-
size is a multiple of 4.
-
sourceOffset is a multiple of 4.
-
destinationOffset is a multiple of 4.
-
( sourceOffset + size ) does not overflow a
GPUSize64
. -
( destinationOffset + size ) does not overflow a
GPUSize64
. -
source .
[[size]]
is greater than or equal to ( sourceOffset + size ). -
destination .
[[size]]
is greater than or equal to ( destinationOffset + size ). -
source and destination are not the same
GPUBuffer
.
figure out how to handle overflows in the spec. [Issue #gpuweb/gpuweb#69]
-
-
12.4.7. Buffer Fills
-
clearBuffer(buffer, offset, size)
-
Encode a command into the
GPUCommandEncoder
that fills a sub-region of aGPUBuffer
with zeros.Called on:GPUCommandEncoder
this .Arguments:
Arguments for the GPUCommandEncoder.clearBuffer(buffer, offset, size) method. Parameter Type Nullable Optional Description buffer
GPUBuffer ✘ ✘ The GPUBuffer
to clear.offset
GPUSize64 ✘ ✔ Offset in bytes into buffer where the sub-region to clear begins. size
GPUSize64 ✘ ✔ Size in bytes of the sub-region to clear. Defaults to the size of the buffer minus offset . Returns:
undefined
Issue the following steps on the Device timeline of this .
[[device]]
:-
Validate the encoder state of this . If it returns false, stop.
-
If size is missing, set size to
max(0, |buffer|.{{GPUBuffer/[[size]]}} - |offset|)
. -
If any of the following conditions are unsatisfied, make this invalid and stop.
-
buffer is valid to use with this .
-
size is a multiple of 4.
-
offset is a multiple of 4.
-
buffer .
[[size]]
is greater than or equal to ( offset + size ).
-
-
12.4.8. Image Copies
WebGPU
provides
copyBufferToTexture()
for
buffer-to-texture
copies
and
copyTextureToBuffer()
for
texture-to-buffer
copies,
as
well
as
writeTexture()
for
ArrayBuffer-to-texture
writes.
The
following
definitions
and
validation
rules
are
used
by
these
methods,
as
well
as
copyTextureToTexture()
.
Does the term "image copy" include copyTextureToTexture?
imageCopyTexture
subresource
size
and
validating
texture
copy
range
also
applies
to
copyTextureToTexture()
.
imageCopyTexture subresource size
Arguments:
-
GPUImageCopyTexture
imageCopyTexture
Returns:
GPUExtent3D
The imageCopyTexture subresource size of imageCopyTexture is calculated as follows:
Its
width
,
height
and
depthOrArrayLayers
are
the
width,
height,
and
depth,
respectively,
of
the
physical
miplevel-specific
texture
extent
of
imageCopyTexture
.
texture
subresource
at
mipmap
level
imageCopyTexture
.
mipLevel
.
define this as an algorithm with (texture, mipmapLevel) parameters and use the call syntax instead of referring to the definition by label.
Arguments:
-
GPUImageDataLayout
layout -
Layout of the linear texture data.
-
GPUSize64
byteSize -
Total size of the linear data, in bytes.
-
GPUTextureFormat
format -
Format of the texture.
-
GPUExtent3D
copyExtent -
Extent of the texture to copy.
-
Let blockWidth , blockHeight , and blockSize be the texel block width , height , and size of format .
-
It is assumed that copyExtent . width is a multiple of blockWidth and copyExtent . height is a multiple of blockHeight . Let:
-
Fail if the following conditions are not satisfied:
-
If heightInBlocks > 1, layout .
bytesPerRow
must be specified. -
If copyExtent . depthOrArrayLayers > 1, layout .
bytesPerRow
and layout .rowsPerImage
must be specified. -
If specified, layout .
bytesPerRow
must be greater than or equal to bytesInLastRow . -
If specified, layout .
rowsPerImage
must be greater than or equal to heightInBlocks .
-
-
Let requiredBytesInCopy be 0.
-
If copyExtent . depthOrArrayLayers > 1:
-
Let bytesPerImage be layout .
bytesPerRow
× layout .rowsPerImage
. -
Let bytesBeforeLastImage be bytesPerImage × ( copyExtent . depthOrArrayLayers − 1).
-
Add bytesBeforeLastImage to requiredBytesInCopy .
-
-
If copyExtent . depthOrArrayLayers > 0:
-
If heightInBlocks > 1, add layout .
bytesPerRow
× ( heightInBlocks − 1) to requiredBytesInCopy . -
If heightInBlocks > 0, add bytesInLastRow to requiredBytesInCopy .
-
-
Fail if the following conditions are not satisfied:
-
layout .
offset
+ requiredBytesInCopy ≤ byteSize .
-
Arguments:
-
GPUImageCopyTexture
imageCopyTexture -
The texture subresource being copied into and copy origin.
-
GPUExtent3D
copySize -
The size of the texture.
-
Let blockWidth be the texel block width of imageCopyTexture .
texture
.[[descriptor]]
.format
. -
Let blockHeight be the texel block height of imageCopyTexture .
texture
.[[descriptor]]
.format
. -
Let subresourceSize be the imageCopyTexture subresource size of imageCopyTexture .
-
Return whether all the conditions below are satisfied:
-
( imageCopyTexture .
origin
. x + copySize . width ) ≤ subresourceSize . width -
( imageCopyTexture .
origin
. y + copySize . height ) ≤ subresourceSize . height -
( imageCopyTexture .
origin
. z + copySize . depthOrArrayLayers ) ≤ subresourceSize . depthOrArrayLayers -
copySize . width must be a multiple of blockWidth .
-
copySize . height must be a multiple of blockHeight .
-
copyBufferToTexture(source, destination, copySize)
-
Encode a command into the
GPUCommandEncoder
that copies data from a sub-region of aGPUBuffer
to a sub-region of one or multiple continuous texture subresources .Called on:GPUCommandEncoder
this .Arguments:
Arguments for the GPUCommandEncoder.copyBufferToTexture(source, destination, copySize) method. Parameter Type Nullable Optional Description source
GPUImageCopyBuffer ✘ ✘ Combined with copySize , defines the region of the source buffer. destination
GPUImageCopyTexture ✘ ✘ Combined with copySize , defines the region of the destination texture subresource . copySize
GPUExtent3D ✘ ✘ Returns:
undefined
Issue the following steps on the Device timeline of this .
[[device]]
:-
Validate the encoder state of this . If it returns false, stop.
-
If any of the following conditions are unsatisfied, make this invalid and stop.
-
Let dstTextureDesc be destination .
texture
.[[descriptor]]
. -
validating GPUImageCopyBuffer ( source ) returns
true
. -
validating GPUImageCopyTexture ( destination , copySize ) returns
true
. -
dstTextureDesc .
sampleCount
is 1. -
Let aspectSpecificFormat = dstTextureDesc .
format
. -
If dstTextureDesc .
format
is a depth-or-stencil format :-
destination .
aspect
must refer to a single aspect of dstTextureDesc .format
. -
That aspect must be a valid image copy destination according to § 25.1.2 Depth-stencil formats .
-
Set aspectSpecificFormat to the aspect-specific format according to § 25.1.2 Depth-stencil formats .
-
-
validating texture copy range ( destination , copySize ) return
true
. -
If dstTextureDesc .
format
is not a depth-or-stencil format :-
source .
offset
is a multiple of the texel block size of dstTextureDesc .format
.
-
-
If dstTextureDesc .
format
is a depth-or-stencil format :-
source .
offset
is a multiple of 4.
-
-
validating linear texture data ( source , source .
buffer
.[[size]]
, aspectSpecificFormat , copySize ) succeeds.
-
-
-
copyTextureToBuffer(source, destination, copySize)
-
Encode a command into the
GPUCommandEncoder
that copies data from a sub-region of one or multiple continuous texture subresources to a sub-region of aGPUBuffer
.Called on:GPUCommandEncoder
this .Arguments:
Arguments for the GPUCommandEncoder.copyTextureToBuffer(source, destination, copySize) method. Parameter Type Nullable Optional Description source
GPUImageCopyTexture ✘ ✘ Combined with copySize , defines the region of the source texture subresources . destination
GPUImageCopyBuffer ✘ ✘ Combined with copySize , defines the region of the destination buffer. copySize
GPUExtent3D ✘ ✘ Returns:
undefined
Issue the following steps on the Device timeline of this .
[[device]]
:-
Validate the encoder state of this . If it returns false, stop.
-
If any of the following conditions are unsatisfied, make this invalid and stop.
-
Let srcTextureDesc be source .
texture
.[[descriptor]]
. -
validating GPUImageCopyTexture ( source , copySize ) returns
true
. -
srcTextureDesc .
sampleCount
is 1. -
Let aspectSpecificFormat = srcTextureDesc .
format
. -
If srcTextureDesc .
format
is a depth-or-stencil format format:-
source .
aspect
must refer to a single aspect of srcTextureDesc .format
. -
That aspect must be a valid image copy source according to § 25.1.2 Depth-stencil formats .
-
Set aspectSpecificFormat to the aspect-specific format according to § 25.1.2 Depth-stencil formats .
-
-
validating GPUImageCopyBuffer ( destination ) returns
true
. -
validating texture copy range ( source , copySize ) returns
true
. -
If srcTextureDesc .
format
is not a depth-or-stencil format :-
destination .
offset
is a multiple of the texel block size of srcTextureDesc .format
.
-
-
If srcTextureDesc .
format
is a depth-or-stencil format :-
destination .
offset
is a multiple of 4.
-
-
validating linear texture data ( destination , destination .
buffer
.[[size]]
, aspectSpecificFormat , copySize ) succeeds.
-
-
-
copyTextureToTexture(source, destination, copySize)
-
Encode a command into the
GPUCommandEncoder
that copies data from a sub-region of one or multiple contiguous texture subresources to another sub-region of one or multiple continuous texture subresources .Called on:GPUCommandEncoder
this .Arguments:
Arguments for the GPUCommandEncoder.copyTextureToTexture(source, destination, copySize) method. Parameter Type Nullable Optional Description source
GPUImageCopyTexture ✘ ✘ Combined with copySize , defines the region of the source texture subresources . destination
GPUImageCopyTexture ✘ ✘ Combined with copySize , defines the region of the destination texture subresources . copySize
GPUExtent3D ✘ ✘ Returns:
undefined
Issue the following steps on the Device timeline of this .
[[device]]
:-
Validate the encoder state of this . If it returns false, stop.
-
If any of the following conditions are unsatisfied, make this invalid and stop.
-
Let srcTextureDesc be source .
texture
.[[descriptor]]
. -
Let dstTextureDesc be destination .
texture
.[[descriptor]]
. -
validating GPUImageCopyTexture ( source , copySize ) returns
true
. -
validating GPUImageCopyTexture ( destination , copySize ) returns
true
. -
srcTextureDesc .
sampleCount
is equal to dstTextureDesc .sampleCount
. -
srcTextureDesc .
format
and dstTextureDesc .format
must be copy-compatible . -
If srcTextureDesc .
format
is a depth-stencil format: -
validating texture copy range ( source , copySize ) returns
true
. -
validating texture copy range ( destination , copySize ) returns
true
. -
The set of subresources for texture copy ( source , copySize ) and the set of subresources for texture copy ( destination , copySize ) are disjoint.
-
-
GPUTextureFormat
s
format1
and
format2
are
copy-compatible
if:
-
format1 equals format2 , or
-
format1 and format2 differ only in whether they are
srgb
formats (have the-srgb
suffix).
Once
more
formats
are
allowed
in
viewFormats
,
consider
making
two
textures
copy-compatible
when
there’s
any
overlap
in
the
viewFormats.
[Issue
#gpuweb/gpuweb#2322]
-
If imageCopyTexture .
texture
.[[descriptor]]
.dimension
is"2d"
:-
For each arrayLayer of the copySize . depthOrArrayLayers array layers starting at imageCopyTexture .
origin
. z :-
The subresource of imageCopyTexture .
texture
at mipmap level imageCopyTexture .mipLevel
and array layer arrayLayer .
-
-
-
Otherwise:
-
The subresource of imageCopyTexture .
texture
at mipmap level imageCopyTexture .mipLevel
.
-
12.5. Queries
-
writeTimestamp(querySet, queryIndex)
-
Writes a timestamp value into a querySet when all previous commands have completed executing.
Called on:GPUCommandEncoder
this .Arguments:
Arguments for the GPUCommandEncoder.writeTimestamp(querySet, queryIndex) method. Parameter Type Nullable Optional Description querySet
GPUQuerySet ✘ ✘ The query set that will store the timestamp values. queryIndex
GPUSize32 ✘ ✘ The index of the query in the query set. Returns:
undefined
-
If this .
[[device]]
.[[features]]
does not contain"timestamp-query"
, throw aTypeError
. -
Issue the following steps on the Device timeline of this .
[[device]]
:-
Validate the encoder state of this . If it returns false, stop.
-
If any of the following conditions are unsatisfied, make this invalid and stop.
-
querySet is valid to use with this .
-
querySet .
[[descriptor]]
.type
is"timestamp"
. -
queryIndex < querySet .
[[descriptor]]
.count
.
-
Describe
writeTimestamp()
algorithm steps. -
-
-
resolveQuerySet(querySet, firstQuery, queryCount, destination, destinationOffset)
-
Resolves query results from a
GPUQuerySet
out into a range of aGPUBuffer
.Called on:GPUCommandEncoder
this.Arguments:
Arguments for the GPUCommandEncoder.resolveQuerySet(querySet, firstQuery, queryCount, destination, destinationOffset) method. Parameter Type Nullable Optional Description querySet
GPUQuerySet ✘ ✘ firstQuery
GPUSize32 ✘ ✘ queryCount
GPUSize32 ✘ ✘ destination
GPUBuffer ✘ ✘ destinationOffset
GPUSize64 ✘ ✘ Returns:
undefined
Issue the following steps on the Device timeline of this .
[[device]]
:-
Validate the encoder state of this . If it returns false, stop.
-
If any of the following conditions are unsatisfied, make this invalid and stop.
-
querySet is valid to use with this .
-
destination is valid to use with this .
-
destination .
[[usage]]
containsQUERY_RESOLVE
. -
firstQuery is less than the number of queries in querySet .
-
( firstQuery + queryCount ) is less than or equal to the number of queries in querySet .
-
destinationOffset is a multiple of 256.
-
destinationOffset + 8 × queryCount ≤ destination .
[[size]]
.
-
Describe
resolveQuerySet()
algorithm steps. -
12.6. Finalization
A
GPUCommandBuffer
containing
the
commands
recorded
by
the
GPUCommandEncoder
can
be
created
by
calling
finish()
.
Once
finish()
has
been
called
the
command
encoder
can
no
longer
be
used.
-
finish(descriptor)
-
Completes recording of the commands sequence and returns a corresponding
GPUCommandBuffer
.Called on:GPUCommandEncoder
this .Arguments:
Arguments for the GPUCommandEncoder.finish(descriptor) method. Parameter Type Nullable Optional Description descriptor
GPUCommandBufferDescriptor ✘ ✔ Returns:
GPUCommandBuffer
-
Let commandBuffer be a new
GPUCommandBuffer
. -
Issue the following steps on the Device timeline of this :
-
Let validationSucceeded be
true
if all of the following requirements are met, andfalse
otherwise.-
this must be valid .
-
this .
[[debug_group_stack]]
must be empty . -
Every usage scope contained in this must satisfy the usage scope validation .
-
-
If validationSucceeded is
false
, then:-
Return a new invalid
GPUCommandBuffer
.
-
Set commandBuffer .
[[command_list]]
to this .[[commands]]
.
-
-
Return commandBuffer .
-
13. Programmable Passes
interface mixin {
GPUBindingCommandsMixin undefined setBindGroup (GPUIndex32 index ,GPUBindGroup bindGroup ,optional sequence <GPUBufferDynamicOffset >= []);
dynamicOffsets undefined setBindGroup (GPUIndex32 index ,GPUBindGroup bindGroup ,Uint32Array dynamicOffsetsData ,, );GPUSize64 dynamicOffsetsDataStart ,GPUSize32 dynamicOffsetsDataLength ); };
GPUBindingCommandsMixin
assumes
the
presence
of
GPUObjectBase
and
GPUCommandsMixin
members
on
the
same
object.
It
must
only
be
included
by
interfaces
which
also
include
those
mixins.
GPUBindingCommandsMixin
has
the
following
internal
slots:
-
[[bind_groups]]
, of type ordered map <GPUIndex32
,GPUBindGroup
> -
The current
GPUBindGroup
for each index, initially empty. -
[[dynamic_offsets]]
, of type ordered map <GPUIndex32
, sequence<GPUBufferDynamicOffset
>> -
The current dynamic offsets for each
[[bind_groups]]
entry, initially empty.
13.1. Bind Groups
-
setBindGroup(index, bindGroup, dynamicOffsets)
-
Sets the current
GPUBindGroup
for the given index.Called on:GPUBindingCommandsMixin
this.Arguments:
Arguments for the GPUBindingCommandsMixin.setBindGroup(index, bindGroup, dynamicOffsets) method. Parameter Type Nullable Optional Description index
GPUIndex32 ✘ ✘ The index to set the bind group at. bindGroup
GPUBindGroup ✘ ✘ Bind group to use for subsequent render or compute commands. Resolve bikeshed conflict when using
argumentdef
with overloaded functions that prevents us from defining dynamicOffsets .Returns:
undefined
Note: dynamicOffsets [ i ] is used for the i -th dynamic buffer binding in the bind group, when bindings are ordered by
GPUBindGroupLayoutEntry
.binding
. Said differently dynamicOffsets are in the same order as dynamic buffer binding’sGPUBindGroupLayoutEntry
.binding
.Issue the following steps on the Device timeline of this .
[[device]]
:-
Validate the encoder state of this . If it returns false, stop.
-
If any of the following conditions are unsatisfied, make this invalid and stop.
-
bindGroup is valid to use with this .
-
index < this .
[[device]]
.[[limits]]
.maxBindGroups
. -
dynamicOffsets .length is bindGroup .
[[layout]]
.[[dynamicOffsetCount]]
. -
Iterate over each dynamic binding offset in bindGroup and run the following steps for each bufferBinding , bufferLayout , and dynamicOffsetIndex :
-
Let bufferDynamicOffset be dynamicOffsets [ dynamicOffsetIndex ].
-
bufferBinding .
offset
+ bufferDynamicOffset + bufferLayout .minBindingSize
≤ bufferBinding .buffer
.[[size]]
. -
if bufferLayout .
type
is"uniform"
:-
dynamicOffset is a multiple of
minUniformBufferOffsetAlignment
.
-
-
if bufferLayout .
type
is"storage"
or"read-only-storage"
:-
dynamicOffset is a multiple of
minStorageBufferOffsetAlignment
.
-
-
-
-
Set this .
[[bind_groups]]
[ index ] to be bindGroup . -
Set this .
[[dynamic_offsets]]
[ index ] to be a copy of dynamicOffsets .
-
-
setBindGroup(index, bindGroup, dynamicOffsetsData, dynamicOffsetsDataStart, dynamicOffsetsDataLength)
-
Sets the current
GPUBindGroup
for the given index, specifying dynamic offsets as a subset of aUint32Array
.Called on:GPUBindingCommandsMixin
this .Arguments:
Arguments for the GPUBindingCommandsMixin.setBindGroup(index, bindGroup, dynamicOffsetsData, dynamicOffsetsDataStart, dynamicOffsetsDataLength) method. Parameter Type Nullable Optional Description index
GPUIndex32 ✘ ✘ The index to set the bind group at. bindGroup
GPUBindGroup ✘ ✘ Bind group to use for subsequent render or compute commands. dynamicOffsetsData
Uint32Array ✘ ✘ Array containing buffer offsets in bytes for each entry in bindGroup marked as buffer
.hasDynamicOffset
.dynamicOffsetsDataStart
GPUSize64 ✘ ✘ Offset in elements into dynamicOffsetsData where the buffer offset data begins. dynamicOffsetsDataLength
GPUSize32 ✘ ✘ Number of buffer offsets to read from dynamicOffsetsData . Returns:
undefined
-
If any of the following requirements are unmet, throw a
RangeError
and stop.-
dynamicOffsetsDataStart must be ≥ 0.
-
dynamicOffsetsDataStart + dynamicOffsetsDataLength must be ≤ dynamicOffsetsData .
length
.
-
-
Let dynamicOffsets be a list containing the range, starting at index dynamicOffsetsDataStart , of dynamicOffsetsDataLength elements of a copy of dynamicOffsetsData .
-
Call this .
setBindGroup
( index , bindGroup , dynamicOffsets ).
-
GPUBindGroup
bindGroup
with
a
given
list
of
steps
to
be
executed
for
each
dynamic
offset:
-
Let dynamicOffsetIndex be
0
. -
Let layout be bindGroup .
[[layout]]
. -
For each
GPUBindGroupEntry
entry in bindGroup .[[entries]]
ordered in increasing values of entry .binding
:-
Let bindingDescriptor be the
GPUBindGroupLayoutEntry
at layout .[[entryMap]]
[ entry .binding
]: -
If bindingDescriptor .
buffer
is notundefined
and bindingDescriptor .buffer
.hasDynamicOffset
istrue
:
-
Arguments:
-
GPUBindingCommandsMixin
encoder -
Encoder whose bind groups are being validated.
-
GPUPipelineBase
pipeline -
Pipeline to validate encoder s bind groups are compatible with.
-
If any of the following conditions are unsatisfied, return
false
:-
pipeline must not be
null
. -
All bind groups used by the pipeline must be set and compatible with the pipeline layout: For each pair of (
GPUIndex32
index ,GPUBindGroupLayout
bindGroupLayout ) in pipeline .[[layout]]
.[[bindGroupLayouts]]
:-
Let bindGroup be encoder .
[[bind_groups]]
[ index ]. -
bindGroup must not be
null
. -
bindGroup .
[[layout]]
must be group-equivalent with bindGroupLayout .
-
Add validation that, for buffer bindings that weren’t prevalidated with
minBindingSize
, the binding ranges are large enough for the shader’s minimum binding size requirements. -
-
Encoder bind groups alias a writable resource ( encoder , pipeline ) must be
false
.Determine what happens when an application violates this. Is it a validation error, one of multiple possible behaviors, or do we just remove this restriction entirely and allow writable bindings to alias with undefined results? [Issue #gpuweb/gpuweb#1842]
Otherwise
return
true
.
GPUTextureView
object).
Arguments:
-
GPUBindingCommandsMixin
encoder -
Encoder whose bind groups are being validated.
-
GPUPipelineBase
pipeline -
Pipeline to validate encoder s bind groups are compatible with.
-
For each stage in [
VERTEX
,FRAGMENT
,COMPUTE
]:-
Let bufferBindings be a list of (
GPUBufferBinding
,boolean
) pairs, where the latter indicates whether the resource was used as writable. -
Let textureViews be a list of (
GPUTextureView
,boolean
) pairs, where the latter indicates whether the resource was used as writable. -
For each pair of (
GPUIndex32
index ,GPUBindGroupLayout
bindGroupLayout ) in pipeline .[[layout]]
.[[bindGroupLayouts]]
:-
Let bindGroupEntries be encoder .
[[bind_groups]]
[ index ].entries
. -
Let bindGroupLayoutEntries be bindGroupLayout .
[[descriptor]]
.entries
. -
For each
GPUBindGroupEntry
bindGroupLayoutEntry in bindGroupLayoutEntries for which bindGroupLayoutEntry .visibility
contains stage :-
Let bindGroupEntry be the
GPUBindGroupEntry
in bindGroupEntries for which bindGroupEntry .binding
is equal to bindGroupLayoutEntry .binding
. -
If bindGroupEntry .
resource
is aGPUBufferBinding
:-
Let
GPUBufferBinding
resource be bindGroupEntry .resource
. -
Let resourceWritable be ( bindGroupLayoutEntry .
buffer
.type
=="storage"
). -
For each pair (
GPUBufferBinding
pastResource ,boolean
pastResourceWritable ) in bufferBindings :-
If ( resourceWritable or pastResourceWritable ) is true, and pastResource and resource are buffer-binding-aliasing , return
true
.
-
-
Append ([ resource ], resourceWritable ) to bufferBindings .
Otherwise, if bindGroupEntry .
resource
is aGPUTextureView
:-
Let
GPUTextureView
resource be bindGroupEntry .resource
. -
Let resourceWritable be ( bindGroupLayoutEntry .
storageTexture
.access
=="write-only"
). -
If bindGroupLayoutEntry .
storageTexture
isnull
, continue. -
For each pair (
GPUTextureView
pastResource ,boolean
pastResourceWritable ) in textureViews ,-
If ( resourceWritable or pastResourceWritable ) is true, and pastResource and resource is texture-view-aliasing , return
true
.
-
-
Append ([ resource ], resourceWritable ) to textureViews .
Otherwise, continue.
-
-
-
-
-
Return
false
.
14. Debug Markers
GPUDebugCommandsMixin
provides
methods
to
apply
debug
labels
to
groups
of
commands
or
insert
a
single
label
into
the
command
sequence.
Debug groups can be nested to create a hierarchy of labeled commands, and must be well-balanced.
Like
object
labels
,
these
labels
have
no
required
behavior,
but
may
be
shown
in
error
messages
and
browser
developer
tools,
and
may
be
passed
to
native
API
backends.
interface mixin GPUDebugCommandsMixin {undefined pushDebugGroup (USVString groupLabel );undefined popDebugGroup ();undefined insertDebugMarker (USVString markerLabel ); };
GPUDebugCommandsMixin
assumes
the
presence
of
GPUObjectBase
and
GPUCommandsMixin
members
on
the
same
object.
It
must
only
be
included
by
interfaces
which
also
include
those
mixins.
GPUDebugCommandsMixin
adds
the
following
internal
slots
to
interfaces
which
include
it:
-
[[debug_group_stack]]
of type stack <USVString
>. -
A stack of active debug group labels.
GPUDebugCommandsMixin
adds
the
following
methods
to
interfaces
which
include
it:
-
pushDebugGroup(groupLabel)
-
Begins a labeled debug group containing subsequent commands.
Called on:GPUDebugCommandsMixin
this .Arguments:
Arguments for the GPUDebugCommandsMixin.pushDebugGroup(groupLabel) method. Parameter Type Nullable Optional Description groupLabel
USVString ✘ ✘ The label for the command group. Returns:
undefined
Issue the following steps on the Device timeline of this .
[[device]]
:-
Validate the encoder state of this . If it returns false, stop.
-
Push groupLabel onto this .
[[debug_group_stack]]
.
-
-
popDebugGroup()
-
Ends the labeled debug group most recently started by
pushDebugGroup()
.Called on:GPUDebugCommandsMixin
this .Returns:
undefined
Issue the following steps on the Device timeline of this .
[[device]]
:-
Validate the encoder state of this . If it returns false, stop.
-
If any of the following requirements are unmet, make this invalid , and stop.
-
this .
[[debug_group_stack]]
must not be empty .
-
-
Pop an entry off of this .
[[debug_group_stack]]
.
-
-
insertDebugMarker(markerLabel)
-
Marks a point in a stream of commands with a label.
Called on:GPUDebugCommandsMixin
this.Arguments:
Arguments for the GPUDebugCommandsMixin.insertDebugMarker(markerLabel) method. Parameter Type Nullable Optional Description markerLabel
USVString ✘ ✘ The label to insert. Returns:
undefined
Issue the following steps on the Device timeline of this .
[[device]]
:-
Validate the encoder state of this . If it returns false, stop.
-
15. Compute Passes
15.1.
GPUComputePassEncoder
[Exposed =(Window ,DedicatedWorker ),SecureContext ]interface GPUComputePassEncoder {undefined setPipeline (GPUComputePipeline pipeline );= 1); );undefined dispatchWorkgroups (GPUSize32 workgroupCountX ,optional GPUSize32 workgroupCountY = 1,optional GPUSize32 workgroupCountZ = 1);undefined dispatchWorkgroupsIndirect (GPUBuffer indirectBuffer ,GPUSize64 indirectOffset );undefined end (); };GPUComputePassEncoder includes GPUObjectBase ;GPUComputePassEncoder includes GPUCommandsMixin ;GPUComputePassEncoder includes GPUDebugCommandsMixin ;GPUComputePassEncoder includes GPUBindingCommandsMixin ;
GPUComputePassEncoder
has
the
following
internal
slots:
-
[[command_encoder]]
of typeGPUCommandEncoder
, readonly -
The
GPUCommandEncoder
that created this compute pass encoder. -
[[pipeline]]
, of typeGPUComputePipeline
-
The current
GPUComputePipeline
, initiallynull
. -
[[endTimestampWrites]]
, of typeGPUComputePassTimestampWrites
-
The timestamp attachments which need to be executed when the pass ends.
15.1.1. Creation
enum {
GPUComputePassTimestampLocation ,
"beginning" , };
"end" dictionary {
GPUComputePassTimestampWrite required GPUQuerySet ;
querySet ;required GPUSize32 ;
queryIndex required GPUComputePassTimestampLocation ; };
location typedef sequence <GPUComputePassTimestampWrite >;
GPUComputePassTimestampWrites dictionary :
GPUComputePassDescriptor GPUObjectDescriptorBase {GPUComputePassTimestampWrites timestampWrites = []; };
-
timestampWrites
, of type GPUComputePassTimestampWrites , defaulting to[]
-
A sequence of
GPUComputePassTimestampWrite
values define where and when timestamp values will be written for this pass.
Given
a
GPUComputePassDescriptor
this
the
following
validation
rules
apply:
-
For each timestampWrite in this .
timestampWrites
:-
timestampWrite .
querySet
.[[descriptor]]
.type
is"timestamp"
. -
timestampWrite .
queryIndex
< timestampWrite .querySet
.[[descriptor]]
.count
.
-
15.1.2. Dispatch
-
setPipeline(pipeline)
-
Sets the current
GPUComputePipeline
.Called on:GPUComputePassEncoder
this.Arguments:
Arguments for the GPUComputePassEncoder.setPipeline(pipeline) method. Parameter Type Nullable Optional Description pipeline
GPUComputePipeline ✘ ✘ The compute pipeline to use for subsequent dispatch commands. Returns:
undefined
Issue the following steps on the Device timeline of this .
[[device]]
:-
Validate the encoder state of this . If it returns false, stop.
-
If any of the following conditions are unsatisfied, make this invalid and stop.
-
pipeline is valid to use with this .
-
-
Set this .
[[pipeline]]
to be pipeline .
-
-
dispatchWorkgroups(workgroupCountX, workgroupCountY, workgroupCountZ)
-
Dispatch work to be performed with the current
GPUComputePipeline
. See § 22.2 Computing for the detailed specification.Called on:GPUComputePassEncoder
this.Arguments:
Arguments for the GPUComputePassEncoder.dispatchWorkgroups(workgroupCountX, workgroupCountY, workgroupCountZ) method. Parameter Type Nullable Optional Description workgroupCountX
GPUSize32 ✘ ✘ X dimension of the grid of workgroups to dispatch. workgroupCountY
GPUSize32 ✘ ✔ Y dimension of the grid of workgroups to dispatch. workgroupCountZ
GPUSize32 ✘ ✔ Z dimension of the grid of workgroups to dispatch. Note: Thex
,y
, andz
values passed todispatchWorkgroups()
anddispatchWorkgroupsIndirect()
are the number of workgroups to dispatch for each dimension, not the number of shader invocations to perform across each dimension. This matches the behavior of modern native GPU APIs, but differs from the behavior of OpenCL.This means that if a
GPUShaderModule
defines an entry point with@workgroup_size(4, 4)
, and work is dispatched to it with the callcomputePass.dispatchWorkgroups(8, 8);
the entry point will be invoked 1024 times total: Dispatching a 4x4 workgroup 8 times along both the X and Y axes. (4*4*8*8=1024
)Returns:
undefined
Issue the following steps on the Device timeline of this .
[[device]]
:-
Validate the encoder state of this . If it returns false, stop.
-
If any of the following conditions are unsatisfied, make this invalid and stop.
-
Validate encoder bind groups ( this , this .
[[pipeline]]
) istrue
. -
all of workgroupCountX , workgroupCountY and workgroupCountZ are less than or equal to this .device.limits.
maxComputeWorkgroupsPerDimension
.
-
-
Let passState be a snapshot of this ’s current state.
-
Append a GPU command to this .
[[commands]]
executing the following queue timeline steps:-
Dispatch a grid of workgroups with dimensions [ workgroupCountX , workgroupCountY , workgroupCountZ ] with passState .
[[pipeline]]
using passState .[[bind_groups]]
.
-
-
-
dispatchWorkgroupsIndirect(indirectBuffer, indirectOffset)
-
Dispatch work to be performed with the current
GPUComputePipeline
using parameters read from aGPUBuffer
. See § 22.2 Computing for the detailed specification.The indirect dispatch parameters encoded in the buffer must be a tightly packed block of three 32-bit unsigned integer values (12 bytes total) , given in the same order as the arguments for
dispatchWorkgroups()
. For example:let dispatchIndirectParameters= new Uint32Array( 3 ); dispatchIndirectParameters[ 0 ] = workgroupCountX; dispatchIndirectParameters[ 1 ] = workgroupCountY; dispatchIndirectParameters[ 2 ] = workgroupCountZ; Called on:GPUComputePassEncoder
this.Arguments:
Arguments for the GPUComputePassEncoder.dispatchWorkgroupsIndirect(indirectBuffer, indirectOffset) method. Parameter Type Nullable Optional Description indirectBuffer
GPUBuffer ✘ ✘ Buffer containing the indirect dispatch parameters . indirectOffset
GPUSize64 ✘ ✘ Offset in bytes into indirectBuffer where the dispatch data begins. Returns:
undefined
Issue the following steps on the Device timeline of this .
[[device]]
:-
Validate the encoder state of this . If it returns false, stop.
-
If any of the following conditions are unsatisfied, make this invalid and stop.
-
Validate encoder bind groups ( this , this .
[[pipeline]]
) istrue
. -
indirectBuffer is valid to use with this .
-
indirectOffset + sizeof( indirect dispatch parameters ) ≤ indirectBuffer .
[[size]]
. -
indirectOffset is a multiple of 4.
-
-
Add indirectBuffer to the usage scope as
INDIRECT
.
If any of the dispatch parameters (x, y, or z) is greater than this .device.limits.
maxComputeWorkgroupsPerDimension
, no workgroups will be dispatched. -
15.1.3. Finalization
The
compute
pass
encoder
can
be
ended
by
calling
end()
once
the
user
has
finished
recording
commands
for
the
pass.
Once
end()
has
been
called
the
compute
pass
encoder
can
no
longer
be
used.
-
end()
-
Completes recording of the compute pass commands sequence.
Called on:GPUComputePassEncoder
this .Returns:
undefined
Issue the following steps on the Device timeline of this :
-
If any of the following requirements are unmet, generate a validation error and stop.
-
Let parentEncoder be this .
[[command_encoder]]
. -
If any of the following requirements are unmet, make parentEncoder invalid and stop.
-
this must be valid .
-
this .
[[debug_group_stack]]
must be empty .
-
-
Extend parentEncoder .
[[commands]]
with this .[[commands]]
. -
For each timestampWrite in this .
[[endTimestampWrites]]
:-
Append a GPU command to parentEncoder .
[[commands]]
that writes the GPU’s timestamp value into the timestampWrite .queryIndex
th index in timestampWrite .querySet
.
-
16. Render Passes
16.1.
GPURenderPassEncoder
[Exposed =(Window ,DedicatedWorker ),SecureContext ]interface GPURenderPassEncoder {undefined setViewport (float x ,float y ,float width ,float height ,float minDepth ,float maxDepth );, );undefined setScissorRect (GPUIntegerCoordinate x ,GPUIntegerCoordinate y ,GPUIntegerCoordinate width ,GPUIntegerCoordinate height );undefined setBlendConstant (GPUColor color );undefined setStencilReference (GPUStencilValue reference ););undefined beginOcclusionQuery (GPUSize32 queryIndex );undefined endOcclusionQuery ();undefined executeBundles (sequence <GPURenderBundle >bundles );undefined end (); };GPURenderPassEncoder includes GPUObjectBase ;GPURenderPassEncoder includes GPUCommandsMixin ;GPURenderPassEncoder includes GPUDebugCommandsMixin ;GPURenderPassEncoder includes GPUBindingCommandsMixin ;GPURenderPassEncoder includes GPURenderCommandsMixin ;
GPURenderPassEncoder
has
the
following
internal
slots:
-
[[command_encoder]]
of typeGPUCommandEncoder
, readonly -
The
GPUCommandEncoder
that created this render pass encoder. -
[[attachment_size]]
-
Set to the following extents:
-
width, height
= the dimensions of the pass’s render attachments
-
-
[[occlusion_query_set]]
, of typeGPUQuerySet
. -
The
GPUQuerySet
to store occlusion query results for the pass, which is initialized withGPURenderPassDescriptor
.occlusionQuerySet
at pass creation time. -
[[occlusion_query_active]]
, of typeboolean
. -
Whether the pass’s
[[occlusion_query_set]]
is being written. -
[[viewport]]
-
Current viewport rectangle and depth range.
-
[[stencil_reference]]
-
Current stencil reference value, initially
0
. -
[[endTimestampWrites]]
, of typeGPURenderPassTimestampWrites
-
The timestamp attachments which need to be executed when the pass ends.
When
a
GPURenderPassEncoder
is
created,
it
has
the
following
default
state:
-
-
x, y
=0.0, 0.0
-
width, height
= the dimensions of the pass’s render targets -
minDepth, maxDepth
=0.0, 1.0
-
-
Scissor rectangle:
-
x, y
=0, 0
-
width, height
= the dimensions of the pass’s render targets
-
16.1.1. Creation
enum {
GPURenderPassTimestampLocation ,
"beginning" , };
"end" dictionary {
GPURenderPassTimestampWrite required GPUQuerySet ;
querySet ;required GPUSize32 ;
queryIndex required GPURenderPassTimestampLocation ; };
location typedef sequence <GPURenderPassTimestampWrite >;
GPURenderPassTimestampWrites dictionary :
GPURenderPassDescriptor GPUObjectDescriptorBase {; ;required sequence <GPURenderPassColorAttachment ?>colorAttachments ;GPURenderPassDepthStencilAttachment depthStencilAttachment ;GPUQuerySet occlusionQuerySet ;GPURenderPassTimestampWrites timestampWrites = []; };
-
colorAttachments
, of typesequence<GPURenderPassColorAttachment?>
-
The set of
GPURenderPassColorAttachment
values in this sequence defines which color attachments will be output to when executing this render pass.Due to usage compatibility , no color attachment may alias another attachment or any resource used inside the render pass.
-
depthStencilAttachment
, of type GPURenderPassDepthStencilAttachment -
The
GPURenderPassDepthStencilAttachment
value that defines the depth/stencil attachment that will be output to and tested against when executing this render pass.Due to usage compatibility , no writable depth/stencil attachment may alias another attachment or any resource used inside the render pass.
-
occlusionQuerySet
, of type GPUQuerySet -
The
GPUQuerySet
value defines where the occlusion query results will be stored for this pass. -
timestampWrites
, of type GPURenderPassTimestampWrites , defaulting to[]
-
A sequence of
GPURenderPassTimestampWrite
values defines where and when timestamp values will be written for this pass.
Given
a
GPUDevice
device
and
GPURenderPassDescriptor
this
,
the
following
validation
rules
apply:
-
this .
colorAttachments
.length must be less than or equal to device .[[limits]]
.maxColorAttachments
. -
If this .
colorAttachments
has all values benull
(or the sequence is empty):-
this .
depthStencilAttachment
must not benull
.
-
-
For each non-
null
colorAttachment in this .colorAttachments
:-
colorAttachment must meet the GPURenderPassColorAttachment Valid Usage rules.
-
-
If this .
depthStencilAttachment
is notnull
:-
this .
depthStencilAttachment
must meet the GPURenderPassDepthStencilAttachment Valid Usage rules.
-
-
All
view
s in non-null
members of this .colorAttachments
, and this .depthStencilAttachment
.view
if present, must have equal[[descriptor]]
.sampleCount
s. -
For each
view
in non-null
members of this .colorAttachments
and this .depthStencilAttachment
.view
, if present, the[[renderExtent]]
must match. -
If this .
occlusionQuerySet
is notnull
:-
this .
occlusionQuerySet
.[[descriptor]]
.type
must beocclusion
.
-
-
For each timestampWrite in this .
timestampWrites
:-
timestampWrite .
querySet
.[[descriptor]]
.type
is"timestamp"
. -
timestampWrite .
queryIndex
< timestampWrite .querySet
.[[descriptor]]
.count
. -
timestampWrite .
queryIndex
is written at most once in the same timestampWrite .querySet
in this render pass.
-
support for no attachments [Issue #gpuweb/gpuweb#503]
GPURenderPassDescriptor
value
descriptor
,
the
syntax:
-
descriptor . renderExtent refers to
[[renderExtent]]
of any[[descriptor]]
in either descriptor .depthStencilAttachment
.view
, or any of theview
in descriptor .colorAttachments
.
make it a define once we reference to this from other places
Note: the Valid Usage guarantees that all of the render extents of the attachments are the same, so we can take any of them, assuming the descriptor is valid.
16.1.1.1. Color Attachments
dictionary {
GPURenderPassColorAttachment ;required GPUTextureView view ;GPUTextureView resolveTarget ;GPUColor clearValue ;required GPULoadOp loadOp ;required GPUStoreOp storeOp ; };
-
view
, of type GPUTextureView -
A
GPUTextureView
describing the texture subresource that will be output to for this color attachment. -
resolveTarget
, of type GPUTextureView -
A
GPUTextureView
describing the texture subresource that will receive the resolved output for this color attachment ifview
is multisampled. -
clearValue
, of type GPUColor -
Indicates the value to clear
view
to prior to executing the render pass. If not provided defaults to{r: 0, g: 0, b: 0, a: 0}
. Ignored ifloadOp
is not"clear"
. -
loadOp
, of type GPULoadOp -
Indicates the load operation to perform on
view
prior to executing the render pass.Note: It is recommended to prefer clearing; see
"clear"
for details. -
storeOp
, of type GPUStoreOp -
The store operation to perform on
view
after executing the render pass.
Given
a
GPURenderPassColorAttachment
this
:
-
Let renderViewDescriptor be this .
view
.[[descriptor]]
. -
Let resolveViewDescriptor be this .
resolveTarget
.[[descriptor]]
. -
Let renderTextureDescriptor be this .
view
.[[texture]]
.[[descriptor]]
. -
Let resolveTextureDescriptor be this .
resolveTarget
.[[texture]]
.[[descriptor]]
.
The following validation rules apply:
-
renderViewDescriptor .
format
must be a color renderable format . -
this .
view
must be a renderable texture view . -
If this .
resolveTarget
is notnull
:-
renderTextureDescriptor .
sampleCount
must be greater than 1. -
resolveTextureDescriptor .
sampleCount
must be 1. -
this .
resolveTarget
must be a renderable texture view . -
The sizes of the subresource s seen by this .
resolveTarget
and this .view
must match. -
resolveViewDescriptor .
format
must equal renderViewDescriptor .format
. -
resolveViewDescriptor .
format
must support resolve according to § 25.1.1 Plain color formats .
-
GPUTextureView
view
is
a
renderable
texture
view
if
the
following
requirements
are
met:
-
view .
[[texture]]
.[[descriptor]]
.usage
must containRENDER_ATTACHMENT
. -
descriptor .
mipLevelCount
must be 1. -
descriptor .
arrayLayerCount
must be 1. -
descriptor .
aspect
must refer to all aspects of view .[[texture]]
.
where
descriptor
is
view
.
[[descriptor]]
.
16.1.1.2. Depth/Stencil Attachments
dictionary {
GPURenderPassDepthStencilAttachment ;required GPUTextureView view ;float depthClearValue = 0;GPULoadOp depthLoadOp ;GPUStoreOp depthStoreOp ;;boolean depthReadOnly =false ;GPUStencilValue stencilClearValue = 0;GPULoadOp stencilLoadOp ;GPUStoreOp stencilStoreOp ;;boolean stencilReadOnly =false ; };
-
view
, of type GPUTextureView -
A
GPUTextureView
describing the texture subresource that will be output to and read from for this depth/stencil attachment. -
depthClearValue
, of type float , defaulting to0
-
Indicates the value to clear
view
's depth component to prior to executing the render pass. Ignored ifdepthLoadOp
is not"clear"
. Must be between 0.0 and 1.0, inclusive. -
depthLoadOp
, of type GPULoadOp -
Indicates the load operation to perform on
view
's depth component prior to executing the render pass.Note: It is recommended to prefer clearing; see
"clear"
for details. -
depthStoreOp
, of type GPUStoreOp -
The store operation to perform on
view
's depth component after executing the render pass.Note: It is recommended to prefer a clear-value; see
"load"
. -
depthReadOnly
, of type boolean , defaulting tofalse
-
Indicates that the depth component of
view
is read only. -
stencilClearValue
, of type GPUStencilValue , defaulting to0
-
Indicates the value to clear
view
's stencil component to prior to executing the render pass. Ignored ifstencilLoadOp
is not"clear"
. -
stencilLoadOp
, of type GPULoadOp -
Indicates the load operation to perform on
view
's stencil component prior to executing the render pass.Note: It is recommended to prefer clearing; see
"clear"
for details. -
stencilStoreOp
, of type GPUStoreOp -
The store operation to perform on
view
's stencil component after executing the render pass. -
stencilReadOnly
, of type boolean , defaulting tofalse
-
Indicates that the stencil component of
view
is read only.
Given
a
GPURenderPassDepthStencilAttachment
this
,
the
following
validation
rules
apply:
-
this .
view
must have a depth-or-stencil format . -
this .
view
must be a renderable texture view . -
If this .
depthLoadOp
is"clear"
, this .depthClearValue
must be between 0.0 and 1.0, inclusive. -
Let format be this .
view
.[[descriptor]]
.format
. -
If format is a combined depth-stencil format :
-
this .
depthReadOnly
must be equal to this .stencilReadOnly
-
-
If format has a depth aspect and this .
depthReadOnly
is nottrue
:-
this .
depthLoadOp
must be provided . -
this .
depthStoreOp
must be provided .
-
-
Otherwise:
-
this .
depthLoadOp
must not be provided . -
this .
depthStoreOp
must not be provided .
-
-
If format has a stencil aspect and this .
stencilReadOnly
is nottrue
:-
this .
depthLoadOp
must be provided . -
this .
depthStoreOp
must be provided .
-
-
Otherwise:
-
this .
stencilLoadOp
must not be provided . -
this .
stencilStoreOp
must not be provided .
-
16.1.1.3. Load & Store Operations
enum {
GPULoadOp "load" ,"clear" , };
-
"load"
-
Loads the existing value for this attachment into the render pass.
-
"clear"
-
Loads a clear value for this attachment into the render pass.
Note: On some GPU hardware (primarily mobile),
"clear"
is significantly cheaper because it avoids loading data from main memory into tile-local memory. On other GPU hardware, there isn’t a significant difference. As a result, it is recommended to use"clear"
rather than"load"
in cases where the initial value doesn’t matter (e.g. the render target will be cleared using a skybox).
enum {
GPUStoreOp "store" ,"discard" , };
-
"store"
-
Stores the resulting value of the render pass for this attachment.
-
"discard"
-
Discards the resulting value of the render pass for this attachment.
16.1.1.4. Render Pass Layout
GPURenderPassLayout
contains
the
layout
of
the
render
targets
for
the
current
pass,
which
determines
the
compatibility
of
the
pass
with
render
pipelines.
dictionary :
GPURenderPassLayout GPUObjectDescriptorBase {; ; = 1;required sequence <GPUTextureFormat ?>;
colorFormats GPUTextureFormat ;
depthStencilFormat GPUSize32 = 1; };
sampleCount
Arguments:
-
GPURenderPassDescriptor
descriptor
Returns:
GPURenderPassLayout
-
Let layout be a new
GPURenderPassLayout
object. -
For each colorAttachment in descriptor .
colorAttachments
:-
If colorAttachment is not
null
:-
Set layout .
sampleCount
to colorAttachment .view
.[[texture]]
.[[descriptor]]
.sampleCount
. -
Append colorAttachment .
view
.[[descriptor]]
.format
to layout .colorFormats
.
-
-
Otherwise:
-
Append
null
to layout .colorFormats
.
-
-
-
Let depthStencilAttachment be descriptor .
depthStencilAttachment
. -
If depthStencilAttachment is not
null
:-
Let view be depthStencilAttachment .
view
. -
Set layout .
sampleCount
to view .[[texture]]
.[[descriptor]]
.sampleCount
. -
Set layout .
depthStencilFormat
to view .[[descriptor]]
.format
.
-
-
Return layout .
Arguments:
-
GPURenderPipelineDescriptor
descriptor
Returns:
GPURenderPassLayout
-
Let layout be a new
GPURenderPassLayout
object. -
Set layout .
sampleCount
to descriptor .multisample
.count
. -
If descriptor .
depthStencil
is notnull
:-
Set layout .
depthStencilFormat
to descriptor .depthStencil
/format
.
-
-
If descriptor .
fragment
is notnull
:-
For each colorTarget in descriptor .
fragment
.targets
:-
Append colorTarget .
format
to layout .colorFormats
if colorTarget is notnull
, or appendnull
otherwise.
-
-
-
Return layout .
16.1.2. Finalization
The
render
pass
encoder
can
be
ended
by
calling
end()
once
the
user
has
finished
recording
commands
for
the
pass.
Once
end()
has
been
called
the
render
pass
encoder
can
no
longer
be
used.
-
end()
-
Completes recording of the render pass commands sequence.
Called on:GPURenderPassEncoder
this .Returns:
undefined
Issue the following steps on the Device timeline of this :
-
If any of the following requirements are unmet, generate a validation error and stop.
-
Let parentEncoder be this .
[[command_encoder]]
. -
If any of the following requirements are unmet, make this invalid and stop.
-
this must be valid .
-
this .
[[debug_group_stack]]
must be empty . -
this .
[[occlusion_query_active]]
must befalse
.
-
-
Extend parentEncoder .
[[commands]]
with this .[[commands]]
. -
For each timestampWrite in this .
[[endTimestampWrites]]
:-
Append a GPU command to parentEncoder .
[[commands]]
that writes the GPU’s timestamp value into the timestampWrite .queryIndex
th index in timestampWrite .querySet
.
-
16.2.
GPURenderCommandsMixin
GPURenderCommandsMixin
defines
rendering
commands
common
to
GPURenderPassEncoder
and
GPURenderBundleEncoder
.
interface mixin GPURenderCommandsMixin {undefined setPipeline (GPURenderPipeline pipeline );); );undefined setIndexBuffer (GPUBuffer buffer ,GPUIndexFormat indexFormat ,optional GPUSize64 offset = 0,optional GPUSize64 size );undefined setVertexBuffer (GPUIndex32 slot ,GPUBuffer buffer ,optional GPUSize64 offset = 0,optional GPUSize64 size );= 1, = 0); = 1, = 0,undefined draw (GPUSize32 vertexCount ,optional GPUSize32 instanceCount = 1,optional GPUSize32 firstVertex = 0,optional GPUSize32 firstInstance = 0);undefined drawIndexed (GPUSize32 indexCount ,optional GPUSize32 instanceCount = 1,optional GPUSize32 firstIndex = 0,optional GPUSignedOffset32 baseVertex = 0,= 0);optional GPUSize32 firstInstance = 0);); );undefined drawIndirect (GPUBuffer indirectBuffer ,GPUSize64 indirectOffset );undefined drawIndexedIndirect (GPUBuffer indirectBuffer ,GPUSize64 indirectOffset ); };
GPURenderCommandsMixin
assumes
the
presence
of
GPUObjectBase
and
GPUCommandsMixin
members
on
the
same
object.
It
must
only
be
included
by
interfaces
which
also
include
those
mixins.
GPURenderCommandsMixin
has
the
following
internal
slots:
-
[[layout]]
, of typeGPURenderPassLayout
-
The layout of the render pass.
-
[[depthReadOnly]]
, of type boolean -
If
true
, indicates that the depth component is not modified. -
[[stencilReadOnly]]
, of type boolean -
If
true
, indicates that the stencil component is not modified. -
[[pipeline]]
, of typeGPURenderPipeline
-
The current
GPURenderPipeline
, initiallynull
. -
[[index_buffer]]
, of typeGPUBuffer
-
The current buffer to read index data from, initially
null
. -
[[index_format]]
, of typeGPUIndexFormat
-
The format of the index data in
[[index_buffer]]
. -
[[index_buffer_size]]
, of typeGPUSize64
-
The size in bytes of the section of
[[index_buffer]]
currently set, initially0
. -
[[vertex_buffers]]
, of type ordered map <slot,GPUBuffer
> -
The current
GPUBuffer
s to read vertex data from for each slot, initially empty. -
[[vertex_buffer_sizes]]
, of type ordered map <slot,GPUSize64
> -
The size in bytes of the section of
GPUBuffer
currently set for each slot, initially empty.
16.2.1. Drawing
-
setPipeline(pipeline)
-
Sets the current
GPURenderPipeline
.Called on:GPURenderCommandsMixin
this.Arguments:
Arguments for the GPURenderCommandsMixin.setPipeline(pipeline) method. Parameter Type Nullable Optional Description pipeline
GPURenderPipeline ✘ ✘ The render pipeline to use for subsequent drawing commands. Returns:
undefined
Issue the following steps on the Device timeline of this .
[[device]]
:-
Validate the encoder state of this . If it returns false, stop.
-
Let pipelineTargetsLayout be derive render targets layout from pipeline ( pipeline .
[[descriptor]]
). -
If any of the following conditions are unsatisfied, make this invalid and stop.
-
pipeline is valid to use with this .
-
this .
[[layout]]
equals pipelineTargetsLayout . -
If pipeline .
[[writesDepth]]
: this .[[depthReadOnly]]
must befalse
. -
If pipeline .
[[writesStencil]]
: this .[[stencilReadOnly]]
must befalse
.
-
-
Set this .
[[pipeline]]
to be pipeline .
define what "equals" means for
GPURenderPassLayout
here. -
-
setIndexBuffer(buffer, indexFormat, offset, size)
-
Sets the current index buffer.
Called on:GPURenderCommandsMixin
this.Arguments:
Arguments for the GPURenderCommandsMixin.setIndexBuffer(buffer, indexFormat, offset, size) method. Parameter Type Nullable Optional Description buffer
GPUBuffer ✘ ✘ Buffer containing index data to use for subsequent drawing commands. indexFormat
GPUIndexFormat ✘ ✘ Format of the index data contained in buffer . offset
GPUSize64 ✘ ✔ Offset in bytes into buffer where the index data begins. Defaults to 0
.size
GPUSize64 ✘ ✔ Size in bytes of the index data in buffer . Defaults to the size of the buffer minus the offset. Returns:
undefined
Issue the following steps on the Device timeline of this .
[[device]]
:-
Validate the encoder state of this . If it returns false, stop.
-
If size is missing, set size to max(0, buffer .
[[size]]
- offset ). -
If any of the following conditions are unsatisfied, make this invalid and stop.
-
buffer is valid to use with this .
-
offset is a multiple of indexFormat ’s byte size.
-
offset + size ≤ buffer .
[[size]]
.
-
-
Add buffer to the usage scope as input .
-
Set this .
[[index_buffer]]
to be buffer . -
Set this .
[[index_format]]
to be indexFormat . -
Set this .
[[index_buffer_size]]
to be size .
-
-
setVertexBuffer(slot, buffer, offset, size)
-
Sets the current vertex buffer for the given slot.
Called on:GPURenderCommandsMixin
this.Arguments:
Arguments for the GPURenderCommandsMixin.setVertexBuffer(slot, buffer, offset, size) method. Parameter Type Nullable Optional Description slot
GPUIndex32 ✘ ✘ The vertex buffer slot to set the vertex buffer for. buffer
GPUBuffer ✘ ✘ Buffer containing vertex data to use for subsequent drawing commands. offset
GPUSize64 ✘ ✔ Offset in bytes into buffer where the vertex data begins. Defaults to 0
.size
GPUSize64 ✘ ✔ Size in bytes of the vertex data in buffer . Defaults to the size of the buffer minus the offset. Returns:
undefined
Issue the following steps on the Device timeline of this .
[[device]]
:-
Validate the encoder state of this . If it returns false, stop.
-
If size is missing, set size to max(0, buffer .
[[size]]
- offset ). -
If any of the following conditions are unsatisfied, make this invalid and stop.
-
buffer is valid to use with this .
-
slot < this .
[[device]]
.[[limits]]
.maxVertexBuffers
. -
offset is a multiple of 4.
-
offset + size ≤ buffer .
[[size]]
.
-
-
Add buffer to the usage scope as input .
-
Set this .
[[vertex_buffers]]
[ slot ] to be buffer . -
Set this .
[[vertex_buffer_sizes]]
[ slot ] to be size .
-
-
draw(vertexCount, instanceCount, firstVertex, firstInstance)
-
Draws primitives. See § 22.3 Rendering for the detailed specification.
Called on:GPURenderCommandsMixin
this.Arguments:
Arguments for the GPURenderCommandsMixin.draw(vertexCount, instanceCount, firstVertex, firstInstance) method. Parameter Type Nullable Optional Description vertexCount
GPUSize32 ✘ ✘ The number of vertices to draw. instanceCount
GPUSize32 ✘ ✔ The number of instances to draw. firstVertex
GPUSize32 ✘ ✔ Offset into the vertex buffers, in vertices, to begin drawing from. firstInstance
GPUSize32 ✘ ✔ First instance to draw. Returns:
undefined
Issue the following steps on the Device timeline of this .
[[device]]
:-
Validate the encoder state of this . If it returns false, stop.
-
If any of the following conditions are unsatisfied, make this invalid and stop.
-
It is valid to draw with this .
-
Let buffers be this .
[[pipeline]]
.[[descriptor]]
.vertex
.buffers
. -
For each
GPUIndex32
slot from0
to buffers .length (non-inclusive):-
Let bufferSize be this .
[[vertex_buffer_sizes]]
[ slot ]. -
Let stride be buffers [ slot ].
arrayStride
. -
Let lastStride be max( attribute .
offset
+ sizeof( attribute .format
)) for each attribute in buffers [ slot ].attributes
. -
Let strideCount be computed based on buffers [ slot ].
stepMode
:-
"vertex"
-
firstVertex + vertexCount
-
"instance"
-
firstInstance + instanceCount
-
-
If strideCount ≠
0
-
Ensure ( strideCount −
1
) × stride + lastStride ≤ bufferSize .
-
-
-
-
-
drawIndexed(indexCount, instanceCount, firstIndex, baseVertex, firstInstance)
-
Draws indexed primitives. See § 22.3 Rendering for the detailed specification.
Called on:GPURenderCommandsMixin
this.Arguments:
Arguments for the GPURenderCommandsMixin.drawIndexed(indexCount, instanceCount, firstIndex, baseVertex, firstInstance) method. Parameter Type Nullable Optional Description indexCount
GPUSize32 ✘ ✘ The number of indices to draw. instanceCount
GPUSize32 ✘ ✔ The number of instances to draw. firstIndex
GPUSize32 ✘ ✔ Offset into the index buffer, in indices, begin drawing from. baseVertex
GPUSignedOffset32 ✘ ✔ Added to each index value before indexing into the vertex buffers. firstInstance
GPUSize32 ✘ ✔ First instance to draw. Returns:
undefined
Issue the following steps on the Device timeline of this .
[[device]]
:-
Validate the encoder state of this . If it returns false, stop.
-
If any of the following conditions are unsatisfied, make this invalid and stop.
-
It is valid to draw indexed with this .
-
firstIndex + indexCount ≤ this .
[[index_buffer_size]]
÷ this .[[index_format]]
's byte size; -
Let buffers be this .
[[pipeline]]
.[[descriptor]]
.vertex
.buffers
. -
For each
GPUIndex32
slot from0
to buffers .length (non-inclusive):-
Let bufferSize be this .
[[vertex_buffer_sizes]]
[ slot ]. -
Let stride be buffers [ slot ].
arrayStride
. -
Let lastStride be max( attribute .
offset
+ sizeof( attribute .format
)) for each attribute in buffers [ slot ].attributes
. -
Let strideCount be firstInstance + instanceCount .
-
If buffers [ slot ].
stepMode
is"instance"
and strideCount ≠0
:-
Ensure ( strideCount −
1
) × stride + lastStride ≤ bufferSize .
-
-
-
Note: a valid program should also never use vertex indices with
GPUVertexStepMode."vertex"
that are out of bounds. WebGPU implementations have different ways of handling this, and therefore a range of behaviors is allowed. Either the whole draw call is discarded, or the access to those attributes out of bounds is described by WGSL’s invalid memory reference . -
-
drawIndirect(indirectBuffer, indirectOffset)
-
Draws primitives using parameters read from a
GPUBuffer
. See § 22.3 Rendering for the detailed specification.The indirect draw parameters encoded in the buffer must be a tightly packed block of four 32-bit unsigned integer values (16 bytes total) , given in the same order as the arguments for
draw()
. For example:let drawIndirectParameters= new Uint32Array( 4 ); drawIndirectParameters[ 0 ] = vertexCount; drawIndirectParameters[ 1 ] = instanceCount; drawIndirectParameters[ 2 ] = firstVertex; drawIndirectParameters[ 3 ] = firstInstance; The value corresponding to
firstInstance
must be 0, unless the"indirect-first-instance"
feature is enabled. If the"indirect-first-instance"
feature is not enabled andfirstInstance
is not zero thedrawIndirect()
call will be treated as a no-op.Called on:GPURenderCommandsMixin
this.Arguments:
Arguments for the GPURenderCommandsMixin.drawIndirect(indirectBuffer, indirectOffset) method. Parameter Type Nullable Optional Description indirectBuffer
GPUBuffer ✘ ✘ Buffer containing the indirect draw parameters . indirectOffset
GPUSize64 ✘ ✘ Offset in bytes into indirectBuffer where the drawing data begins. Returns:
undefined
Issue the following steps on the Device timeline of this .
[[device]]
:-
Validate the encoder state of this . If it returns false, stop.
-
If any of the following conditions are unsatisfied, make this invalid and stop.
-
It is valid to draw with this .
-
indirectBuffer is valid to use with this .
-
indirectOffset + sizeof( indirect draw parameters ) ≤ indirectBuffer .
[[size]]
. -
indirectOffset is a multiple of 4.
-
-
Add indirectBuffer to the usage scope as input .
-
-
drawIndexedIndirect(indirectBuffer, indirectOffset)
-
Draws indexed primitives using parameters read from a
GPUBuffer
. See § 22.3 Rendering for the detailed specification.The indirect drawIndexed parameters encoded in the buffer must be a tightly packed block of five 32-bit unsigned integer values (20 bytes total) , given in the same order as the arguments for
drawIndexed()
. For example:let drawIndexedIndirectParameters= new Uint32Array( 5 ); drawIndexedIndirectParameters[ 0 ] = indexCount; drawIndexedIndirectParameters[ 1 ] = instanceCount; drawIndexedIndirectParameters[ 2 ] = firstIndex; drawIndexedIndirectParameters[ 3 ] = baseVertex; drawIndexedIndirectParameters[ 4 ] = firstInstance; The value corresponding to
firstInstance
must be 0, unless the"indirect-first-instance"
feature is enabled. If the"indirect-first-instance"
feature is not enabled andfirstInstance
is not zero thedrawIndexedIndirect()
call will be treated as a no-op.Called on:GPURenderCommandsMixin
this.Arguments:
Arguments for the GPURenderCommandsMixin.drawIndexedIndirect(indirectBuffer, indirectOffset) method. Parameter Type Nullable Optional Description indirectBuffer
GPUBuffer ✘ ✘ Buffer containing the indirect drawIndexed parameters . indirectOffset
GPUSize64 ✘ ✘ Offset in bytes into indirectBuffer where the drawing data begins. Returns:
undefined
Issue the following steps on the Device timeline of this .
[[device]]
:-
Validate the encoder state of this . If it returns false, stop.
-
If any of the following conditions are unsatisfied, make this invalid and stop.
-
It is valid to draw indexed with this .
-
indirectBuffer is valid to use with this .
-
indirectOffset + sizeof( indirect drawIndexed parameters ) ≤ indirectBuffer .
[[size]]
. -
indirectOffset is a multiple of 4.
-
-
Add indirectBuffer to the usage scope as input .
-
GPURenderCommandsMixin
encoder
run
the
following
steps:
If
any
of
the
following
conditions
are
unsatisfied,
return
false
:
-
Validate encoder bind groups ( encoder , encoder .
[[pipeline]]
) must betrue
. -
Let pipelineDescriptor be encoder .
[[pipeline]]
.[[descriptor]]
. -
For each
GPUIndex32
slot0
to pipelineDescriptor .vertex
.buffers
.length:-
encoder .
[[vertex_buffers]]
[ slot ] must not benull
.
-
Otherwise
return
true
.
GPURenderCommandsMixin
encoder
run
the
following
steps:
If
any
of
the
following
conditions
are
unsatisfied,
return
false
:
-
It must be valid to draw with encoder .
-
encoder .
[[index_buffer]]
must not benull
. -
Let topology be encoder .
[[pipeline]]
.[[descriptor]]
.primitive
.topology
. -
If topology is
"line-strip"
or"triangle-strip"
:-
encoder .
[[index_format]]
must equal encoder .[[pipeline]]
.[[descriptor]]
.primitive
.stripIndexFormat
.
-
Otherwise
return
true
.
16.2.2. Rasterization state
The
GPURenderPassEncoder
has
several
methods
which
affect
how
draw
commands
are
rasterized
to
attachments
used
by
this
encoder.
-
setViewport(x, y, width, height, minDepth, maxDepth)
-
Sets the viewport used during the rasterization stage to linearly map from normalized device coordinates to viewport coordinates.
Called on:GPURenderPassEncoder
this .Arguments:
Arguments for the GPURenderPassEncoder.setViewport(x, y, width, height, minDepth, maxDepth) method. Parameter Type Nullable Optional Description x
float ✘ ✘ Minimum X value of the viewport in pixels. y
float ✘ ✘ Minimum Y value of the viewport in pixels. width
float ✘ ✘ Width of the viewport in pixels. height
float ✘ ✘ Height of the viewport in pixels. minDepth
float ✘ ✘ Minimum depth value of the viewport. maxDepth
float ✘ ✘ Maximum depth value of the viewport. Returns:
undefined
Issue the following steps on the Device timeline of this :
-
Validate the encoder state of this . If it returns false, stop.
-
If any of the following conditions are unsatisfied, make this invalid and stop.
-
x is greater than or equal to
0
. -
y is greater than or equal to
0
. -
width is greater than or equal to
0
. -
height is greater than or equal to
0
. -
x + width is less than or equal to this .
[[attachment_size]]
.width. -
y + height is less than or equal to this .
[[attachment_size]]
.height. -
minDepth is greater than or equal to
0.0
and less than or equal to1.0
. -
maxDepth is greater than or equal to
0.0
and less than or equal to1.0
. -
maxDepth is greater than minDepth .
-
-
Set this .
[[viewport]]
to the extents x , y , width , height , minDepth , and maxDepth .
Allowed for GPUs to use fixed point or rounded viewport coordinates
-
-
setScissorRect(x, y, width, height)
-
Sets the scissor rectangle used during the rasterization stage. After transformation into viewport coordinates any fragments which fall outside the scissor rectangle will be discarded.
Called on:GPURenderPassEncoder
this .Arguments:
Arguments for the GPURenderPassEncoder.setScissorRect(x, y, width, height) method. Parameter Type Nullable Optional Description x
GPUIntegerCoordinate ✘ ✘ Minimum X value of the scissor rectangle in pixels. y
GPUIntegerCoordinate ✘ ✘ Minimum Y value of the scissor rectangle in pixels. width
GPUIntegerCoordinate ✘ ✘ Width of the scissor rectangle in pixels. height
GPUIntegerCoordinate ✘ ✘ Height of the scissor rectangle in pixels. Returns:
undefined
Issue the following steps on the Device timeline of this :
-
Validate the encoder state of this . If it returns false, stop.
-
If any of the following conditions are unsatisfied, make this invalid and stop.
-
x + width is less than or equal to this .
[[attachment_size]]
.width. -
y + height is less than or equal to this .
[[attachment_size]]
.height.
-
-
Set the scissor rectangle to the extents x , y , width , and height .
-
-
setBlendConstant(color)
-
Sets the constant blend color and alpha values used with
"constant"
and"one-minus-constant"
GPUBlendFactor
s.Called on:GPURenderPassEncoder
this.Arguments:
Arguments for the GPURenderPassEncoder.setBlendConstant(color) method. Parameter Type Nullable Optional Description color
GPUColor ✘ ✘ The color to use when blending. -
setStencilReference(reference)
-
Sets the
[[stencil_reference]]
value used during stencil tests with the"replace"
GPUStencilOperation
.Called on:GPURenderPassEncoder
this.Arguments:
Arguments for the GPURenderPassEncoder.setStencilReference(reference) method. Parameter Type Nullable Optional Description reference
GPUStencilValue ✘ ✘ The new stencil reference value. Issue the following steps on the Device timeline of this :
-
Validate the encoder state of this . If it returns false, stop.
-
Set
[[stencil_reference]]
to reference .
-
16.2.3. Queries
-
beginOcclusionQuery(queryIndex)
-
Called on:
GPURenderPassEncoder
this .Arguments:
Arguments for the GPURenderPassEncoder.beginOcclusionQuery(queryIndex) method. Parameter Type Nullable Optional Description queryIndex
GPUSize32 ✘ ✘ The index of the query in the query set. Returns:
undefined
Issue the following steps on the Device timeline of this .
[[device]]
:-
Validate the encoder state of this . If it returns false, stop.
-
If any of the following conditions are unsatisfied, make this invalid and stop.
-
this .
[[occlusion_query_set]]
is notnull
. -
queryIndex < this .
[[occlusion_query_set]]
.[[descriptor]]
.count
. -
The query at same queryIndex must not have been previously written to in this pass.
-
this .
[[occlusion_query_active]]
isfalse
.
-
-
Set this .
[[occlusion_query_active]]
totrue
.
-
-
endOcclusionQuery()
-
Called on:
GPURenderPassEncoder
this.Returns:
undefined
Issue the following steps on the Device timeline of this .
[[device]]
:-
Validate the encoder state of this . If it returns false, stop.
-
If any of the following conditions are unsatisfied, make this invalid and stop.
-
this .
[[occlusion_query_active]]
istrue
.
-
-
Set this .
[[occlusion_query_active]]
tofalse
.
-
16.2.4. Bundles
-
executeBundles(bundles)
-
Executes the commands previously recorded into the given
GPURenderBundle
s as part of this render pass.When a
GPURenderBundle
is executed, it does not inherit the render pass’s pipeline, bind groups, or vertex and index buffers. After aGPURenderBundle
has executed, the render pass’s pipeline, bind group, and vertex/index buffer state is cleared (to the initial, empty values).Note: The state is cleared, not restored to the previous state. This occurs even if zero
GPURenderBundles
are executed.Called on:GPURenderPassEncoder
this.Arguments:
Arguments for the GPURenderPassEncoder.executeBundles(bundles) method. Parameter Type Nullable Optional Description bundles
sequence<GPURenderBundle> ✘ ✘ List of render bundles to execute. Returns:
undefined
Issue the following steps on the Device timeline of this :
-
Validate the encoder state of this . If it returns false, stop.
-
If any of the following conditions are unsatisfied, make this invalid and stop.
-
For each bundle in bundles :
-
bundle must be valid to use with this .
-
this .
[[layout]]
must equal bundle .[[layout]]
. -
If this .
[[depthReadOnly]]
is true, bundle .[[depthReadOnly]]
must be true. -
If this .
[[stencilReadOnly]]
is true, bundle .[[stencilReadOnly]]
must be true.
-
-
-
17. Bundles
17.1.
GPURenderBundle
[Exposed =(Window ,DedicatedWorker ),SecureContext ]interface GPURenderBundle { };GPURenderBundle includes GPUObjectBase ;
-
[[command_list]]
of type list < GPU command >. -
A list of GPU commands to be submitted to the
GPURenderPassEncoder
when theGPURenderBundle
is executed. -
[[layout]]
, of typeGPURenderPassLayout
-
The layout of the render bundle.
-
[[depthReadOnly]]
, of type boolean -
If
true
, indicates that the depth component is not modified by executing this render bundle. -
[[stencilReadOnly]]
, of type boolean -
If
true
, indicates that the stencil component is not modified by executing this render bundle.
17.1.1. Creation
dictionary :
GPURenderBundleDescriptor GPUObjectDescriptorBase { };
[Exposed =(Window ,DedicatedWorker ),SecureContext ]interface {
GPURenderBundleEncoder GPURenderBundle finish (optional GPURenderBundleDescriptor descriptor = {}); };GPURenderBundleEncoder includes GPUObjectBase ;GPURenderBundleEncoder includes GPUCommandsMixin ;GPURenderBundleEncoder includes GPUDebugCommandsMixin ;GPURenderBundleEncoder includes GPUBindingCommandsMixin ;GPURenderBundleEncoder includes GPURenderCommandsMixin ;
-
createRenderBundleEncoder(descriptor)
-
Creates a
GPURenderBundleEncoder
.Called on:GPUDevice
this .Arguments:
Arguments for the GPUDevice.createRenderBundleEncoder(descriptor) method. Parameter Type Nullable Optional Description descriptor
GPURenderBundleEncoderDescriptor ✘ ✘ Description of the GPURenderBundleEncoder
to create.Returns:
GPURenderBundleEncoder
Issue the following steps on the Device timeline of this :
-
If any of the following conditions are unsatisfied, generate a validation error and stop.
-
descriptor .
colorFormats
.length must be less than or equal to this .[[limits]]
.maxColorAttachments
. -
If descriptor .
colorFormats
only containsnull
members:-
descriptor .
depthStencilFormat
must not benull
.
-
-
For each colorFormat in descriptor .
colorFormats
:-
colorFormat is
null
, or it must be a color renderable format .
-
-
Let depthStencilFormat be descriptor .
depthStencilFormat
. -
If depthStencilFormat is not
null
:-
depthStencilFormat must be a depth-or-stencil format .
-
If depthStencilFormat is a combined depth-stencil format :
-
descriptor .
depthReadOnly
must be equal to descriptor .stencilReadOnly
-
-
-
-
Let e be a new
GPURenderBundleEncoder
object. -
Set e .
[[layout]]
to descriptor .GPURenderPassLayout
. -
Set e .
[[depthReadOnly]]
to descriptor .depthReadOnly
. -
Set e .
[[stencilReadOnly]]
to descriptor .stencilReadOnly
. -
Return e .
Describe the reset of the steps for
createRenderBundleEncoder()
. -
17.1.2. Encoding
dictionary :
GPURenderBundleEncoderDescriptor GPURenderPassLayout {; ;boolean =
depthReadOnly false ;boolean =
stencilReadOnly false ; };
17.1.3. Finalization
-
finish(descriptor)
-
Completes recording of the render bundle commands sequence.
Called on:GPURenderBundleEncoder
this.Arguments:
Arguments for the GPURenderBundleEncoder.finish(descriptor) method. Parameter Type Nullable Optional Description descriptor
GPURenderBundleDescriptor ✘ ✔ Returns:
GPURenderBundle
-
Let renderBundle be a new
GPURenderBundle
. -
Issue the following steps on the Device timeline of this :
-
Let validationFailed be
true
if all of the following requirements are met, andfalse
otherwise.-
this must be valid .
-
this .
[[debug_group_stack]]
must be empty . -
Every usage scope contained in this must satisfy the usage scope validation .
-
-
If validationFailed , then:
-
Return a new invalid
GPURenderBundle
.
-
Set renderBundle .
[[command_list]]
to this .[[commands]]
.
-
-
Return renderBundle .
-
18. Queues
18.1.
GPUQueueDescriptor
GPUQueueDescriptor
describes
a
queue
request.
dictionary GPUQueueDescriptor :GPUObjectDescriptorBase { };
18.2.
GPUQueue
[Exposed =(Window ,DedicatedWorker ),SecureContext ]interface GPUQueue {undefined submit (sequence <GPUCommandBuffer >commandBuffers );Promise <undefined >onSubmittedWorkDone ();(undefined writeBuffer (GPUBuffer buffer ,,GPUSize64 bufferOffset , [AllowShared ]BufferSource data ,= 0, );optional GPUSize64 dataOffset = 0,optional GPUSize64 size );(undefined writeTexture (GPUImageCopyTexture destination , [AllowShared ]BufferSource data ,GPUImageDataLayout dataLayout ,);GPUExtent3D size );undefined copyExternalImageToTexture (GPUImageCopyExternalImage source ,GPUImageCopyTextureTagged destination ,);GPUExtent3D copySize ); };GPUQueue includes GPUObjectBase ;
GPUQueue
has
the
following
methods:
-
writeBuffer(buffer, bufferOffset, data, dataOffset, size)
-
Issues a write operation of the provided data into a
GPUBuffer
.Called on:GPUQueue
this .Arguments:
Arguments for the GPUQueue.writeBuffer(buffer, bufferOffset, data, dataOffset, size) method. Parameter Type Nullable Optional Description buffer
GPUBuffer ✘ ✘ The buffer to write to. bufferOffset
GPUSize64 ✘ ✘ Offset in bytes into buffer to begin writing at. data
BufferSource ✘ ✘ Data to write into buffer . dataOffset
GPUSize64 ✘ ✔ Offset in into data to begin writing from. Given in elements if data is a TypedArray
and bytes otherwise.size
GPUSize64 ✘ ✔ Size of content to write from data to buffer . Given in elements if data is a TypedArray
and bytes otherwise.Returns:
undefined
-
If data is an
ArrayBuffer
orDataView
, let the element type be "byte". Otherwise, data is a TypedArray; let the element type be the type of the TypedArray. -
Let dataSize be the size of data , in elements.
-
If size is missing, let contentsSize be dataSize − dataOffset . Otherwise, let contentsSize be size .
-
If any of the following conditions are unsatisfied, throw
OperationError
and stop.-
contentsSize ≥ 0.
-
dataOffset + contentsSize ≤ dataSize .
-
contentsSize , converted to bytes, is a multiple of 4 bytes.
-
-
Let dataContents be a copy of the bytes held by the buffer source .
-
Let contents be the contentsSize elements of dataContents starting at an offset of dataOffset elements.
-
Issue the following steps on the Queue timeline of this :
-
If any of the following conditions are unsatisfied, generate a validation error and stop.
-
Write contents into buffer starting at bufferOffset .
-
-
-
writeTexture(destination, data, dataLayout, size)
-
Issues a write operation of the provided data into a
GPUTexture
.Called on:GPUQueue
this .Arguments:
Arguments for the GPUQueue.writeTexture(destination, data, dataLayout, size) method. Parameter Type Nullable Optional Description destination
GPUImageCopyTexture ✘ ✘ The texture subresource and origin to write to. data
BufferSource ✘ ✘ Data to write into destination . dataLayout
GPUImageDataLayout ✘ ✘ Layout of the content in data . size
GPUExtent3D ✘ ✘ Extents of the content to write from data to destination . Returns:
undefined
-
Let dataBytes be a copy of the bytes held by the buffer source data .
-
Let dataByteSize be the number of bytes in dataBytes .
-
Let textureDesc be destination .
texture
.[[descriptor]]
. -
Let contents be the contents of the images seen by viewing dataBytes with dataLayout and size .
-
Issue the following steps on the Queue timeline of this :
-
If any of the following conditions are unsatisfied, generate a validation error and stop.
-
validating GPUImageCopyTexture ( destination , size ) returns
true
. -
textureDesc .
sampleCount
is 1. -
validating texture copy range ( destination , size ) return
true
. -
destination .
aspect
must refer to a single aspect of textureDesc .format
. -
That aspect must be a valid image copy destination according to § 25.1.2 Depth-stencil formats .
-
Let aspectSpecificFormat = textureDesc .
format
. -
If textureDesc .
format
is a depth-or-stencil format :-
Set aspectSpecificFormat to the aspect-specific format of textureDesc .
format
according to § 25.1.2 Depth-stencil formats .
-
-
validating linear texture data ( dataLayout , dataByteSize , aspectSpecificFormat , size ) succeeds.
Note: unlike
GPUCommandEncoder
.copyBufferToTexture()
, there is no alignment requirement on either dataLayout .bytesPerRow
or dataLayout .offset
. -
-
Write contents into destination .
-
-
-
copyExternalImageToTexture(source, destination, copySize)
-
Issues a copy operation of the contents of a platform image/canvas into the destination texture.
This operation performs color encoding into the destination encoding according to the parameters of
GPUImageCopyTextureTagged
.Copying into a
-srgb
texture results in the same texture bytes, not the same decoded values, as copying into the corresponding non--srgb
format. Thus, after a copy operation, sampling the destination texture has different results depending on whether its format is-srgb
, all else unchanged.If an srgb-linear color space is added, explain here how it interacts.
Called on:GPUQueue
this .Arguments:
Arguments for the GPUQueue.copyExternalImageToTexture(source, destination, copySize) method. Parameter Type Nullable Optional Description source
GPUImageCopyExternalImage ✘ ✘ source image and origin to copy to destination . destination
GPUImageCopyTextureTagged ✘ ✘ The texture subresource and origin to write to, and its encoding metadata. copySize
GPUExtent3D ✘ ✘ Extents of the content to write from source to destination . Returns:
undefined
-
Let sourceImage be source .
source
-
Run Check the usability of the image argument ( sourceImage ). If it throws an exception, stop. If it does not return
good
, throw anInvalidStateError
and stop. -
If sourceImage is not origin-clean , throw a
SecurityError
and stop. -
If any of the following requirements are unmet, throw an
OperationError
and stop. -
Issue the following steps on the Device timeline of this :
-
Let textureDesc be destination .
texture
.[[descriptor]]
. -
If any of the following requirements are unmet, generate a validation error and stop.
-
destination .
texture
must be valid to use with this . -
validating GPUImageCopyTexture (destination, copySize) must return
true
. -
validating texture copy range (destination, copySize) must return
true
. -
textureDesc .
usage
must include bothRENDER_ATTACHMENT
andCOPY_DST
. -
textureDesc .
sampleCount
must be 1. -
textureDesc .
format
must be one of the following formats (which all supportRENDER_ATTACHMENT
usage):
-
-
-
-
submit(commandBuffers)
-
Schedules the execution of the command buffers by the GPU on this queue.
Called on:GPUQueue
this.Arguments:
Arguments for the GPUQueue.submit(commandBuffers) method. Parameter Type Nullable Optional Description commandBuffers
sequence<GPUCommandBuffer> ✘ ✘ Returns:
undefined
Issue the following steps on the Device timeline of this :
-
If any of the following conditions are unsatisfied, generate a validation error and stop.
-
Every
GPUCommandBuffer
in commandBuffers is valid to use with this . -
Every
GPUBuffer
referenced in any element of commandBuffers is in the"unmapped"
buffer state . -
Every
GPUQuerySet
referenced in a command in any element of commandBuffers is in the available state. For occlusion queries,occlusionQuerySet
inbeginRenderPass()
does not constitute a reference, whilebeginOcclusionQuery()
does.
-
-
Issue the following steps on the Queue timeline of this :
-
For each commandBuffer in commandBuffers :
-
Execute each command in commandBuffer .
[[command_list]]
.
-
-
-
-
onSubmittedWorkDone()
-
Returns a
Promise
that resolves once this queue finishes processing all the work submitted up to this moment.Called on:GPUQueue
this.Arguments:
Arguments for the GPUQueue.onSubmittedWorkDone() method. Parameter Type Nullable Optional Description Returns:
Promise
<undefined
>Describe
onSubmittedWorkDone()
algorithm steps.
19. Queries
19.1.
GPUQuerySet
[Exposed =(Window ,DedicatedWorker ),SecureContext ]interface GPUQuerySet {undefined destroy (); };GPUQuerySet includes GPUObjectBase ;
GPUQuerySet
has
the
following
internal
slots:
-
[[descriptor]]
, of typeGPUQuerySetDescriptor
-
The
GPUQuerySetDescriptor
describing this query set.All optional fields of
GPUTextureViewDescriptor
are defined. -
[[state]]
of type query set state . -
The current state of the
GPUQuerySet
.
Each
GPUQuerySet
has
a
current
query
set
state
on
the
Device
timeline
which
is
one
of
the
following:
-
" available " where the
GPUQuerySet
is available for GPU operations on its content. -
" destroyed " where the
GPUQuerySet
is no longer available for any operations exceptdestroy
.
19.1.1. QuerySet Creation
A
GPUQuerySetDescriptor
specifies
the
options
to
use
in
creating
a
GPUQuerySet
.
dictionary :
GPUQuerySetDescriptor GPUObjectDescriptorBase {required GPUQueryType type ;;required GPUSize32 count ; };
-
type
, of type GPUQueryType -
The type of queries managed by
GPUQuerySet
. -
count
, of type GPUSize32 -
The number of queries managed by
GPUQuerySet
.
-
createQuerySet(descriptor)
-
Creates a
GPUQuerySet
.Called on:GPUDevice
this.Arguments:
Arguments for the GPUDevice.createQuerySet(descriptor) method. Parameter Type Nullable Optional Description descriptor
GPUQuerySetDescriptor ✘ ✘ Description of the GPUQuerySet
to create.Returns:
GPUQuerySet
-
If descriptor .
type
is"timestamp"
, but this .[[device]]
.[[features]]
does not contain"timestamp-query"
, throw aTypeError
. -
If any of the following requirements are unmet, return an error query set and stop.
-
Let q be a new
GPUQuerySet
object. -
Set q .
[[descriptor]]
to descriptor . -
Return q .
-
GPUQuerySet
which
holds
32
occlusion
query
results.
const querySet= gpuDevice. createQuerySet({ type: 'occlusion' , count: 32 });
19.1.2. QuerySet Destruction
An
application
that
no
longer
requires
a
GPUQuerySet
can
choose
to
lose
access
to
it
before
garbage
collection
by
calling
destroy()
.
-
destroy()
-
Destroys the
GPUQuerySet
.
19.2. QueryType
enum {
GPUQueryType ,
"occlusion" , };
"timestamp"
19.3. Occlusion Query
Occlusion query is only available on render passes, to query the number of fragment samples that pass all the per-fragment tests for a set of drawing commands, including scissor, sample mask, alpha to coverage, stencil, and depth tests. Any non-zero result value for the query indicates that at least one sample passed the tests and reached the output merging stage of the render pipeline, 0 indicates that no samples passed the tests.
When
beginning
a
render
pass,
GPURenderPassDescriptor
.
occlusionQuerySet
must
be
set
to
be
able
to
use
occlusion
queries
during
the
pass.
An
occlusion
query
is
begun
and
ended
by
calling
beginOcclusionQuery()
and
endOcclusionQuery()
in
pairs
that
cannot
be
nested.
19.4. Timestamp Query
Timestamp
query
allows
application
to
write
timestamp
values
to
a
GPUQuerySet
by
calling
writeTimestamp()
on
GPUCommandEncoder
,
and
then
resolve
timestamp
values
in
nanoseconds
(type
of
GPUSize64
)
to
a
GPUBuffer
(using
resolveQuerySet()
).
Timestamp
query
requires
"timestamp-query"
is
available
on
the
device.
Note: The timestamp values may be zero if the physical device reset timestamp counter, please ignore it and the following values.
Write normative text about timestamp value resets.
Because timestamp query provides high-resolution GPU timestamp, we need to decide what constraints, if any, are on its availability.
20. Canvas Rendering
20.1.
HTMLCanvasElement.getContext()
A
GPUCanvasContext
object
can
be
obtained
via
the
getContext()
method
of
an
HTMLCanvasElement
instance
by
passing
the
string
literal
'webgpu'
as
its
contextType
argument.
GPUCanvasContext
from
an
offscreen
HTMLCanvasElement
:
const canvas= document. createElement( 'canvas' ); const context= canvas. getContext( 'webgpu' );
20.2. GPUCanvasContext
[Exposed =(Window ,DedicatedWorker ),SecureContext ]interface {
GPUCanvasContext readonly attribute (HTMLCanvasElement or OffscreenCanvas )canvas ;undefined configure (GPUCanvasConfiguration configuration );undefined unconfigure ();); ();GPUTextureFormat getPreferredFormat (GPUAdapter adapter );GPUTexture getCurrentTexture (); };
GPUCanvasContext
has
the
following
attributes:
-
canvas
, of type(HTMLCanvasElement or OffscreenCanvas)
, readonly -
The canvas this context was created from.
GPUCanvasContext
has
the
following
internal
slots:
-
[[validConfiguration]]
of type boolean, initiallyfalse
. -
Indicates if the context currently has a valid configuration.
-
[[configuration]]
of typeGPUCanvasConfiguration
, initiallynull
. -
The options this context is configured with.
null
if the context has not been configured or the configuration has been removed. -
[[size]]
of typeGPUExtent3D
-
The size of
GPUTexture
s returned from this context. depthOrArrayLayers is always1
. -
[[currentTexture]]
of typeGPUTexture
?, initiallynull
-
The current texture that will be returned by the context when calling
getCurrentTexture()
, and the next one to be composited to the document.When non-
null
, this texture’s size always matches the current[[configuration]]
's size. Callingconfigure()
invalidates it.
GPUCanvasContext
has
the
following
methods:
-
configure(configuration)
-
Configures the context for this canvas. Destroys any textures produced with a previous configuration.
Called on:GPUCanvasContext
this .Arguments:
Arguments for the GPUCanvasContext.configure(configuration) method. Parameter Type Nullable Optional Description configuration
GPUCanvasConfiguration ✘ ✘ Desired configuration for the context. Returns: undefined
-
Invalidate the current texture of this .
-
Set this .
[[validConfiguration]]
tofalse
. -
Set this .
[[configuration]]
to configuration . -
Let device be configuration .
device
. -
Let canvas be this .
canvas
. -
If configuration .
size
isundefined
set this .[[size]]
to [ canvas .width, canvas .height, 1], otherwise set this .[[size]]
to configuration .size
. -
Issue the following steps on the Device timeline of device :
-
If any of the following conditions are unsatisfied:
-
Supported context formats contains configuration .
format
. -
this .
[[size]]
. width ≤ device .limits
.maxTextureDimension2D
. -
this .
[[size]]
. height ≤ device .limits
.maxTextureDimension2D
. -
this .
[[size]]
. depthOrArrayLayers is 1;
Then:
-
Return.
-
-
Set this .
[[validConfiguration]]
totrue
.
-
-
unconfigure()
-
Removes the context configuration. Destroys any textures produced while configured.
Called on:GPUCanvasContext
this .Returns: undefined
-
Invalidate the current texture of this .
-
Set this .
[[validConfiguration]]
tofalse
. -
Set this .
[[configuration]]
tonull
.
-
-
getPreferredFormat(adapter)
-
Returns an optimal
GPUTextureFormat
to use with this context and devices created from the given adapter.Called on:GPUCanvasContext
this.Arguments:
Arguments for the GPUCanvasContext.getPreferredFormat(adapter) method. Parameter Type Nullable Optional Description adapter
GPUAdapter ✘ ✘ Adapter the format should be queried for. Returns:
GPUTextureFormat
-
Return an optimal
GPUTextureFormat
to use when callingconfigure()
with the given adapter . Must be one of the supported context formats .
-
-
getCurrentTexture()
-
Get the
GPUTexture
that will be composited to the document by theGPUCanvasContext
next.Called on:GPUCanvasContext
this .Returns:
GPUTexture
-
If this .
[[configuration]]
isnull
:-
Throw an
OperationError
and stop.
-
-
If this .
[[currentTexture]]
isnull
or this .[[currentTexture]]
.[[destroyed]]
is true:-
Set this .
[[currentTexture]]
to the result of allocating a new context texture for this .
-
-
Return this .
[[currentTexture]]
.
Note: Developers can expect that the same
GPUTexture
object will be returned by every call togetCurrentTexture()
made within the same frame (i.e. between invocations of Update the rendering ) unless the current texture has been invalidated . -
Document
"
step
of
the
"
Update
the
rendering
"
HTML
processing
model,
each
GPUCanvasContext
context
must
present
the
context
content
to
the
canvas
by
running
the
following
steps:
-
If context .
[[currentTexture]]
is notnull
and context .[[currentTexture]]
.[[destroyed]]
isfalse
:-
Let imageContents be a copy of the image contents of context .
-
Update context .
canvas
with imageContents . -
Call context .
[[currentTexture]]
.destroy()
.
-
-
Set context .
[[currentTexture]]
tonull
.
transferToImageBitmap()
is
called
on
a
canvas
with
GPUCanvasContext
context
:
-
Let imageContents be a copy of the image contents of context .
-
If context .
[[currentTexture]]
is notnull
:-
Call context .
[[currentTexture]]
.destroy()
.
-
-
Set context .
[[currentTexture]]
tonull
. -
Return a new
ImageBitmap
containing the imageContents .
drawImage()
,
texImage2D()
,
texSubImage2D()
,
toDataURL()
,
toBlob()
,
and
so
on,
they
get
a
copy
of
the
image
contents
of
a
context
:
Arguments:
-
context : the
GPUCanvasContext
Returns: image contents
-
Let texture be context .
[[currentTexture]]
. -
If any of the following requirements is unmet, return a transparent black image of size context .
[[size]]
and stop.-
texture must not be
null
. -
texture .
[[destroyed]]
must be false. -
If context .
canvas
is anOffscreenCanvas
, it must not be linked to a placeholder canvas element .
-
-
Ensure that all submitted work items (e.g. queue submissions) have completed writing to texture .
-
Return the contents of texture , tagged as having alpha premultiplied, and with the color space context .
[[configuration]]
.colorSpace
.Does compositingAlphaMode=opaque make this return opaque contents? [Issue #gpuweb/gpuweb#1847]
GPUCanvasContext
context
run
the
following
steps:
-
Let device be context .
[[configuration]]
.device
. -
If context .
[[validConfiguration]]
isfalse
:-
Return a new invalid
GPUTexture
.
-
Let textureDescriptor be a new
GPUTextureDescriptor
. -
Set textureDescriptor .
format
to context .[[configuration]]
.format
. -
Set textureDescriptor .
usage
to context .[[configuration]]
.usage
. -
Let texture be a new
GPUTexture
created as if device .createTexture()
were called with textureDescriptor .Note: This results in an invalid
GPUTexture
and generates an error if the texture can’t be created (e.g. due to out-of-memory).Note: If a previously presented texture from context matches the required criteria, its GPU memory may be re-used. This optimization is unobservable.
-
Ensure texture is cleared to
(0, 0, 0, 0)
. -
Return texture .
GPUCanvasContext
context
:
-
If context .
[[currentTexture]]
is notnull
, call itsdestroy()
method. -
Set context .
[[currentTexture]]
tonull
.
20.3. GPUCanvasConfiguration
The
supported
context
formats
are
a
set
of
GPUTextureFormat
s
that
must
be
supported
when
specified
as
a
GPUCanvasConfiguration
.
format
regardless
of
the
given
GPUCanvasConfiguration
.
device
,
initially
set
to:
«
"bgra8unorm"
,
"rgba8unorm"
,
"rgba16float"
».
Note:
Canvas
configuration
cannot
use
srgb
formats
like
"bgra8unorm-srgb"
.
Instead,
use
the
non-
srgb
equivalent
(
"bgra8unorm"
),
specify
the
srgb
format
in
the
viewFormats
,
and
use
createView()
to
create
a
view
with
an
srgb
format.
enum {
GPUCanvasCompositingAlphaMode ,
"opaque" , };
"premultiplied" dictionary {
GPUCanvasConfiguration required GPUDevice ;
device ; = 0x10; // GPUTextureUsage.RENDER_ATTACHMENT = [];required GPUTextureFormat ;
format GPUTextureUsageFlags = 0x10; // GPUTextureUsage.RENDER_ATTACHMENT
usage sequence <GPUTextureFormat >= [];
viewFormats GPUPredefinedColorSpace = "srgb";
colorSpace GPUCanvasCompositingAlphaMode = "opaque";
compositingAlphaMode ;GPUExtent3D ; };
size
GPUCanvasContext
to
be
used
with
a
specific
GPUDevice
,
using
the
preferred
format
for
this
context:
const canvas= document. createElement( 'canvas' ); const context= canvas. getContext( 'webgpu' ); context. configure({ device: gpuDevice, format: context. getPreferredFormat( gpuAdapter), });
20.3.1. Canvas Color Space
During
presentation,
the
chrominance
of
color
values
outside
of
the
[0,
1]
range
is
not
to
be
clamped
to
that
range;
extended
values
may
be
used
to
display
colors
outside
of
the
gamut
defined
by
the
canvas'
color
space’s
primaries,
when
permitted
by
the
configured
format
and
the
user’s
display
capabilities.
This
is
in
contrast
with
luminance,
which
is
to
be
clamped
to
the
maximum
standard
dynamic
range
luminance.
Unless high dynamic range is explicitly enabled for the canvas element.
20.3.2. Canvas Context sizing
A
GPUCanvasContext
's
[[size]]
is
set
by
the
GPUCanvasConfiguration
passed
to
configure()
,
and
remains
the
same
until
configure()
is
called
again
with
a
new
size.
If
a
size
is
not
specified
then
the
width
and
height
attributes
of
the
GPUCanvasContext
.
canvas
at
the
time
configure()
is
called
will
be
used.
If
GPUCanvasContext
.
[[size]]
does
not
match
the
dimensions
of
the
canvas
the
textures
produced
by
the
GPUCanvasContext
will
be
scaled
to
fit
the
canvas
element.
'webgl'
or
'2d'
contexts,
width
and
height
attributes
of
canvases
with
a
'webgpu'
context
only
affect:
-
Default layout size, if not overridden by CSS.
-
Default
GPUCanvasConfiguration
.size
when callingconfigure()
, if not overridden.
If
it
is
desired
to
match
the
dimensions
of
the
canvas
after
it
is
resized,
the
GPUCanvasContext
must
be
reconfigured
by
calling
configure()
again
with
the
new
dimensions.
GPUCanvasContext
in
response
to
canvas
resize,
monitored
using
ResizeObserver
to
get
the
exact
pixel
dimensions
of
the
canvas:
const canvas= document. createElement( 'canvas' ); const context= canvas. getContext( 'webgpu' ); const resizeObserver= new ResizeObserver( entries=> { for ( const entryof entries) { if ( entry. target!= canvas) { continue ; } context. configure({ device: gpuDevice, format: context. getPreferredFormat( gpuAdapter), size: { // This reports the size of the canvas element in pixels width: entry. devicePixelContentBoxSize[ 0 ]. inlineSize, height: entry. devicePixelContentBoxSize[ 0 ]. blockSize, } }); } }); resizeObserver. observe( canvas);
20.4.
GPUCanvasCompositingAlphaMode
This enum selects how the contents of the canvas' context will paint onto the page.
GPUCanvasCompositingAlphaMode | Description | dst.rgb | dst.a |
---|---|---|---|
opaque
| Paint RGB as opaque and ignore alpha values. If the content is not already opaque, implementations may need to clear alpha to opaque during presentation. |
dst.rgb
=
src.rgb
|
dst.a
=
1
|
premultiplied
| Composite assuming color values are premultiplied by their alpha value. 100% red 50% opaque is [0.5, 0, 0, 0.5]. Color values must be less than or equal to their alpha value. [1.0, 0, 0, 0.5] is "super-luminant" and cannot reliably be displayed. |
dst.rgb
=
src.rgb
+
dst.rgb
*
(1
-
src.a)
|
dst.a
=
src.a
+
dst.a
*
(1
-
src.a)
|
21. Errors & Debugging
21.1. Fatal Errors
enum {
GPUDeviceLostReason , }; [
"destroyed" Exposed =(Window ,DedicatedWorker ),SecureContext ]interface {
GPUDeviceLostInfo readonly attribute (GPUDeviceLostReason or undefined );
reason readonly attribute DOMString ; };
message partial interface GPUDevice {readonly attribute Promise <GPUDeviceLostInfo >lost ; };
GPUDevice
has
the
following
additional
attributes:
-
lost
, of type Promise< GPUDeviceLostInfo >, readonly -
A promise which is created with the device, remains pending for the lifetime of the device, then resolves when the device is lost.
This attribute is backed by an immutable internal slot of the same name, initially set to a new promise , and always returns its value.
21.2. Error Scopes
A
GPU
error
scope
captures
GPUError
s
that
were
generated
while
the
GPU
error
scope
was
current.
Error
scopes
are
used
to
isolate
errors
that
occur
within
a
set
of
WebGPU
calls,
typically
for
debugging
purposes
or
to
make
an
operation
more
fault
tolerant.
GPU error scope has the following internal slots:
-
[[error]]
of typeGPUError
?, initiallynull
. -
The first
GPUError
, if any, observed while the GPU error scope was current. -
[[filter]]
of typeGPUErrorFilter
. -
Determines what type of
GPUError
this GPU error scope observes.
enum {
GPUErrorFilter ,
"out-of-memory" , };
"validation"
[Exposed =(Window ,DedicatedWorker ),SecureContext ]interface {
GPUOutOfMemoryError (); }; [
constructor Exposed =(Window ,DedicatedWorker ),SecureContext ]interface {
GPUValidationError (
constructor DOMString );
message readonly attribute DOMString ; };
message typedef (GPUOutOfMemoryError or GPUValidationError );
GPUError
partial interface GPUDevice {undefined pushErrorScope (GPUErrorFilter filter );Promise <GPUError ?>popErrorScope (); };
GPUDevice
has
the
following
internal
slots:
-
[[errorScopeStack]]
of type stack < GPU error scope >. -
A stack of GPU error scopes that have been pushed to the
GPUDevice
.
GPUError
error
and
GPUDevice
device
is
determined
by
issuing
the
following
steps
to
the
Device
timeline
:
-
If error is an instance of:
-
GPUValidationError
-
Let type be "validation".
-
GPUOutOfMemoryError
-
Let type be "out-of-memory".
-
-
Let scope be the last item of device .
[[errorScopeStack]]
. -
While scope is not
undefined
:-
If scope .
[[filter]]
is type , return scope . -
Set scope to the previous item of device .
[[errorScopeStack]]
.
-
-
Return
undefined
.
GPUDevice
device
,
run
the
following
steps:
-
Let error be a new
GPUValidationError
with an appropriate error message. -
Issue the following steps to the Device timeline :
-
Let scope be the current error scope for error and device .
-
If scope is not
undefined
: -
Otherwise issue the following steps to the Content timeline :
-
If the user agent chooses, queue a task to fire a
GPUUncapturedErrorEvent
named "uncapturederror
" on device with anerror
of error .
-
-
Note:
The
user
agent
may
choose
to
throttle
or
limit
the
number
of
GPUUncapturedErrorEvent
s
that
a
GPUDevice
can
raise
to
prevent
an
excessive
amount
of
error
handling
or
logging
from
impacting
performance.
-
pushErrorScope(filter)
-
Pushes a new GPU error scope onto the
[[errorScopeStack]]
for this .Called on:GPUDevice
this .Arguments:
Arguments for the GPUDevice.pushErrorScope(filter) method. Parameter Type Nullable Optional Description filter
GPUErrorFilter ✘ ✘ Which class of errors this error scope observes. -
Issue the following steps to the Device timeline :
-
Let scope be a new GPU error scope .
-
Set scope .
[[filter]]
to filter . -
Push scope onto this .
[[errorScopeStack]]
.
-
-
-
popErrorScope()
-
Pops a GPU error scope off the
[[errorScopeStack]]
for this and resolves to aGPUError
if one was observed by the error scope.Called on:GPUDevice
this .Returns:
Promise
<GPUError
?>-
Let promise be a new promise .
-
Issue the following steps to the Device timeline :
-
If any of the following requirements are unmet, reject promise with an
OperationError
and stop.-
this must not be lost .
-
this .
[[errorScopeStack]]
. size > 0.
-
-
Let scope be the result of popping an item off of this .
[[errorScopeStack]]
.
-
-
Return promise .
-
GPUDevice
operation
that
may
fail:
gpuDevice. pushErrorScope( 'validation' ); let sampler= gpuDevice. createSampler({ maxAnisotropy: 0 , // Invalid, maxAnisotropy must be at least 1. }); gpuDevice. popErrorScope(). then(( error) => { if ( error) { // There was an error creating the sampler, so discard it. sampler= null ; console. error( `An error occured while creating sampler: ${ error. message} ` ); } });
21.3. Telemetry
User
agents
may
dispatch
an
uncapturederror
event
on
a
GPUDevice
when
a
GPUError
is
generated
that
is
not
observed
by
any
GPU
error
scope
.
The
event
must
be
of
type
GPUUncapturedErrorEvent
.
Note:
uncapturederror
events
are
intended
to
be
used
for
telemetry
and
reporting
unexpected
errors.
They
may
not
be
dispatched
for
all
uncaptured
errors
(for
example,
there
may
be
a
limit
on
the
number
of
errors
surfaced),
and
should
not
be
used
for
handling
known
error
cases
that
may
occur
during
normal
operation
of
an
application.
Prefer
using
pushErrorScope()
and
popErrorScope()
in
those
cases.
[Exposed =(Window ,DedicatedWorker ),SecureContext ]interface :
GPUUncapturedErrorEvent Event {(
constructor DOMString ,
type GPUUncapturedErrorEventInit );
gpuUncapturedErrorEventInitDict readonly attribute GPUError error ; };dictionary :
GPUUncapturedErrorEventInit EventInit {required GPUError ; };
error
GPUUncapturedErrorEvent
has
the
following
attributes:
-
error
, of type GPUError , readonly -
Object representing the error that was uncaptured. This has the same type as errors returned by
popErrorScope()
.This attribute is backed by an immutable internal slot of the same name, and always returns its value.
This attribute should be
[SameObject]
. (If GPUError becomes an interface then we can do this without resolving the WebIDL issue.) [Issue #whatwg/webidl#1077]
partial interface GPUDevice { [Exposed =(Window ,DedicatedWorker )]attribute EventHandler onuncapturederror ; };
GPUDevice
has
the
following
attributes:
-
onuncapturederror
, of type EventHandler -
An event handler IDL attribute for the
uncapturederror
event type.
GPUDevice
:
gpuDevice. addEventListener( 'uncapturederror' , ( event) => { if ( event. errorinstanceof GPUValidationError) { console. error( `An uncaught WebGPU validation error was raised: ${ event. error. message} ` ); } });
22. Detailed Operations
This section describes the details of various GPU operations.
22.1. Transfer
describe the transfers at the high level
22.2. Computing
Computing
operations
provide
direct
access
to
GPU’s
programmable
hardware.
Compute
shaders
do
not
have
pipeline
inputs
or
outputs,
their
results
are
side
effects
from
writing
data
into
storage
bindings
bound
as
GPUBufferBindingType."storage"
and
GPUStorageTextureBindingLayout
.
These
operations
are
encoded
within
GPUComputePassEncoder
as:
describe the computing algorithm
22.3. Rendering
Rendering
is
done
by
a
set
of
GPU
operations
that
are
executed
within
GPURenderPassEncoder
,
and
result
in
modifications
of
the
texture
data,
viewed
by
the
render
pass
attachments.
These
operations
are
encoded
with:
Note: rendering is the traditional use of GPUs, and is supported by multiple fixed-function blocks in hardware.
A
RenderState
is
an
internal
object
representing
the
state
of
the
current
GPURenderPassEncoder
during
command
encoding.
RenderState
is
a
spec
namespace
for
the
following
definitions:
GPURenderPassEncoder
pass
,
the
syntax:
-
pass . indexBuffer refers to the index buffer bound via
setIndexBuffer()
, if any. -
pass . vertexBuffers refers to list <vertex buffer> bound by
setVertexBuffer()
. -
pass . bindGroups refers to list <
GPUBindGroup
> bound bysetBindGroup(index, bindGroup, dynamicOffsets)
. -
pass . viewport refers to an object containing
setViewport()
arguments. At the start of a render pass, the state is equivalent to a call of setViewport(0, 0, pass .[[attachment_size]]
.width, pass .[[attachment_size]]
.height, 0.0, 1.0). -
pass . scissorRect refers to an object containing
setScissorRect()
arguments. At the start of a render pass, the state is equivalent to a call of setScissorRect(0, 0, pass .[[attachment_size]]
.width, pass .[[attachment_size]]
.height).
The main rendering algorithm:
Arguments:
-
descriptor : Description of the current
GPURenderPipeline
. -
drawCall : The draw call parameters.
-
state : RenderState of the
GPURenderCommandsMixin
where the draw call is issued.
-
Resolve indices . See § 22.3.1 Index Resolution .
Let vertexList be the result of resolve indices ( drawCall , state ).
-
Process vertices . See § 22.3.2 Vertex Processing .
Execute process vertices ( vertexList , drawCall , descriptor .
vertex
, state ). -
Assemble primitives . See § 22.3.3 Primitive Assembly .
Execute assemble primitives ( vertexList , drawCall , descriptor .
primitive
). -
Clip primitives . See § 22.3.4 Primitive Clipping .
Let primitiveList be the result of this stage.
-
Rasterize . See § 22.3.5 Rasterization .
Let rasterizationList be the result of rasterize ( primitiveList , state ).
-
Process fragments . See § 22.3.6 Fragment Processing .
Gather a list of fragments , resulting from executing process fragment ( rasterPoint , descriptor .
fragment
, state ) for each rasterPoint in rasterizationList . -
Process depth/stencil .
-
Write pixels .
22.3.1. Index Resolution
At the first stage of rendering, the pipeline builds a list of vertices to process for each instance.
Arguments:
-
drawCall : The draw call parameters.
-
state : The active RenderState .
Returns: list of integer indices.
-
Let vertexIndexList be an empty list of indices.
-
If drawCall is an indexed draw call:
-
Initialize the vertexIndexList with drawCall .indexCount integers.
-
For i in range 0 .. drawCall .indexCount (non-inclusive):
-
Let relativeVertexIndex be fetch index ( i + drawCall .
firstIndex
, state . indexBuffer ). -
If relativeVertexIndex has the special value
"out of bounds"
, stop and return the empty list.Note: Implementations may choose to display a warning when this occurs, especially when it is easy to detect (like in non-indirect indexed draw calls).
-
Append drawCall .
baseVertex
+ relativeVertexIndex to the vertexIndexList .
-
-
-
Otherwise:
-
Initialize the vertexIndexList with drawCall .vertexCount integers.
-
Set each vertexIndexList item i to the value drawCall .firstVertex + i .
-
-
Return vertexIndexList .
Note:
in
case
of
indirect
draw
calls,
the
indexCount
,
vertexCount
,
and
other
properties
of
drawCall
are
read
from
the
indirect
buffer
instead
of
the
draw
command
itself.
Arguments:
-
i : Index of a vertex index to fetch.
-
indexBufferState : A value of indexBuffer (buffer, format, offset, and size).
Returns:
unsigned
integer
or
"out
of
bounds"
-
Let indexSize be defined by the indexBufferState .
format
: -
If indexBufferState .
offset
+ |i + 1| × indexSize > indexBufferState .size
, return the special value"out of bounds"
. -
Interpret the data in indexBufferState .
buffer
, starting at offset indexBufferState .offset
+ i × indexSize , of size indexSize bytes, as an unsigned integer and return it.
22.3.2. Vertex Processing
Vertex processing stage is a programmable stage of the render pipeline that processes the vertex attribute data, and produces clip space positions for § 22.3.4 Primitive Clipping , as well as other data for the § 22.3.6 Fragment Processing .
Arguments:
-
vertexIndexList : List of vertex indices to process (mutable, passed by reference).
-
drawCall : The draw call parameters.
-
desc : The descriptor of type
GPUVertexState
. -
state : The active RenderState .
Each
vertex
vertexIndex
in
the
vertexIndexList
,
in
each
instance
of
index
rawInstanceIndex
,
is
processed
independently.
The
rawInstanceIndex
is
in
range
from
0
to
drawCall
.instanceCount
-
1,
inclusive.
This
processing
happens
in
parallel,
and
any
side
effects,
such
as
writes
into
GPUBufferBindingType."storage"
bindings,
may
happen
in
any
order.
-
Let instanceIndex be rawInstanceIndex + drawCall .firstInstance.
-
For each non-
null
vertexBufferLayout in the list of desc .buffers
:-
Let i be the index of the buffer layout in this list.
-
Let vertexBuffer , vertexBufferOffset , and vertexBufferBindingSize be the buffer, offset, and size at slot i of state . vertexBuffers .
-
Let vertexElementIndex be dependent on vertexBufferLayout .
stepMode
:-
"vertex"
-
vertexIndex
-
"instance"
-
instanceIndex
-
-
For each attributeDesc in vertexBufferLayout .
attributes
:-
Let attributeOffset be vertexBufferOffset + vertexElementIndex * vertexBufferLayout .
arrayStride
+ attributeDesc .offset
. -
Load the attribute data of format attributeDesc .
format
from vertexBuffer starting at offset attributeOffset . The components are loaded in the orderx
,y
,z
,w
from buffer memory.If this results in an out-of-bounds access, the resulting value is determined according to WGSL’s invalid memory reference behavior.
-
Optionally (implementation-defined): If attributeOffset + sizeof( attributeDesc .
format
) > vertexBufferOffset + vertexBufferBindingSize , empty vertexIndexList and stop, cancelling the draw call.Note: This allows implementations to detect out-of-bounds values in the index buffer before issuing a draw call, instead of using invalid memory reference behavior.
-
Convert the data into a shader-visible format, according to channel formats rules.
An attribute of type"snorm8x2"
and byte values of[0x70, 0xD0]
will be converted tovec2<f32>(0.88, -0.38)
in WGSL. -
Adjust the data size to the shader type:
-
if both are scalar, or both are vectors of the same dimensionality, no adjustment is needed.
-
if data is vector but the shader type is scalar, then only the first component is extracted.
-
if both are vectors, and data has a higher dimension, the extra components are dropped.
An attribute of type"float32x3"
and valuevec3<f32>(1.0, 2.0, 3.0)
will exposed to the shader asvec2<f32>(1.0, 2.0)
if a 2-component vector is expected. -
if the shader type is a vector of higher dimensionality, or the data is a scalar, then the missing components are filled from
vec4<*>(0, 0, 0, 1)
value.An attribute of type"sint32"
and value5
will be exposed to the shader asvec4<i32>(5, 0, 0, 1)
if a 4-component vector is expected.
-
-
Bind the data to vertex shader input location attributeDesc .
shaderLocation
.
-
-
-
For each
GPUBindGroup
group at index in state . bindGroups :-
For each resource
GPUBindingResource
in the bind group:-
Let entry be the corresponding
GPUBindGroupLayoutEntry
for this resource. -
If entry .
GPUBindGroupLayoutEntry
.visibility includesVERTEX
:-
Bind the resource to the shader under group index and binding
GPUBindGroupLayoutEntry.binding
.
-
-
-
-
Set the shader builtins :
-
Set the
vertex_index
builtin, if any, to vertexIndex . -
Set the
instance_index
builtin, if any, to instanceIndex .
-
-
Invoke the vertex shader entry point described by desc .
Note: The target platform caches the results of vertex shader invocations. There is no guarantee that any vertexIndex that repeats more than once will result in multiple invocations. Similarly, there is no guarantee that a single vertexIndex will only be processed once.
22.3.3. Primitive Assembly
Primitives are assembled by a fixed-function stage of GPUs.
Arguments:
-
vertexIndexList : List of vertex indices to process.
-
drawCall : The draw call parameters.
-
desc : The descriptor of type
GPUPrimitiveState
.
For each instance, the primitives get assembled from the vertices that have been processed by the shaders, based on the vertexIndexList .
-
First, if the primitive topology is a strip, (which means that desc .
stripIndexFormat
is not undefined) and the drawCall is indexed, the vertexIndexList is split into sub-lists using the maximum value of desc .stripIndexFormat
as a separator.Example: a vertexIndexList with values
[1, 2, 65535, 4, 5, 6]
of type"uint16"
will be split in sub-lists[1, 2]
and[4, 5, 6]
. -
For each of the sub-lists vl , primitive generation is done according to the desc .
topology
:-
"line-list"
-
Line primitives are composed from ( vl .0, vl .1), then ( vl .2, vl .3), then ( vl .4 to vl .5), etc. Each subsequent primitive takes 2 vertices.
-
"line-strip"
-
Line primitives are composed from ( vl .0, vl .1), then ( vl .1, vl .2), then ( vl .2, vl .3), etc. Each subsequent primitive takes 1 vertex.
-
"triangle-list"
-
Triangle primitives are composed from ( vl .0, vl .1, vl .2), then ( vl .3, vl .4, vl .5), then ( vl .6, vl .7, vl .8), etc. Each subsequent primitive takes 3 vertices.
-
"triangle-strip"
-
Triangle primitives are composed from ( vl .0, vl .1, vl .2), then ( vl .2, vl .1, vl .3), then ( vl .2, vl .3, vl .4), then ( vl .4, vl .3, vl .5), etc. Each subsequent primitive takes 1 vertices.
should this be defined more formally?
Any incomplete primitives are dropped.
-
22.3.4. Primitive Clipping
Vertex
shaders
have
to
produce
a
built-in
"position"
(of
type
vec4<f32>
),
which
denotes
the
clip
position
of
a
vertex.
Primitives are clipped to the clip volume , which, for any clip position p inside a primitive, is defined by the following inequalities:
-
− p .w ≤ p .x ≤ p .w
-
− p .w ≤ p .y ≤ p .w
-
0 ≤ p .z ≤ p .w ( depth clipping )
If
descriptor
.
primitive
.
unclippedDepth
is
true
,
depth
clipping
is
not
applied:
the
clip
volume
is
not
bounded
in
the
z
dimension.
A
primitive
passes
through
this
stage
unchanged
if
every
one
of
its
edges
lie
entirely
inside
the
clip
volume
.
If
the
edges
of
a
primitives
intersect
the
boundary
of
the
clip
volume
,
the
intersecting
edges
are
reconnected
by
new
edges
that
lie
along
the
boundary
of
the
clip
volume
.
For
triangular
primitives
(
descriptor
.
primitive
.
topology
is
"triangle-list"
or
"triangle-strip"
),
this
reconnection
may
result
in
introduction
of
new
vertices
into
the
polygon,
internally.
If a primitive intersects an edge of the clip volume ’s boundary, the clipped polygon must include a point on this boundary edge.
If the vertex shader outputs other floating-point values (scalars and vectors), qualified with "perspective" interpolation, they also get clipped. The output values associated with a vertex that lies within the clip volume are unaffected by clipping. If a primitive is clipped, however, the output values assigned to vertices produced by clipping are clipped.
Considering an edge between vertices a and b that got clipped, resulting in the vertex c , let’s define t to be the ratio between the edge vertices: c .p = t × a .p + (1 − t ) × b .p, where x .p is the output clip position of a vertex x .
For each vertex output value "v" with a corresponding fragment input, a .v and b .v would be the outputs for a and b vertices respectively. The clipped shader output c .v is produced based on the interpolation qualifier:
- "flat"
-
Flat interpolation is unaffected, and is based on provoking vertex , which is the first vertex in the primitive. The output value is the same for the whole primitive, and matches the vertex output of the provoking vertex : c .v = provoking vertex .v
- "linear"
-
The interpolation ratio gets adjusted against the perspective coordinates of the clip position s, so that the result of interpolation is linear in screen space.
- "perspective"
-
The value is linearly interpolated in clip space, producing perspective-correct values:
c .v = t × a .v + (1 − t ) × b .v
link to interpolation qualifiers in WGSL
The result of primitive clipping is a new set of primitives, which are contained within the clip volume .
22.3.5. Rasterization
Rasterization
is
the
hardware
processing
stage
that
maps
the
generated
primitives
to
the
2-dimensional
rendering
area
of
the
framebuffer
-
the
set
of
render
attachments
in
the
current
GPURenderPassEncoder
.
This
rendering
area
is
split
into
an
even
grid
of
pixels.
Rasterization
determines
the
set
of
pixels
affected
by
a
primitive.
In
case
of
multi-sampling,
each
pixel
is
further
split
into
descriptor
.
multisample
.
count
samples.
The
locations
of
samples
are
the
same
for
each
pixel,
but
not
defined
in
this
spec.
do we want to force-enable the "Standard sample locations" in Vulkan?
The framebuffer coordinates start from the top-left corner of the render targets. Each unit corresponds exactly to a pixel. See § 3.3 Coordinate Systems for more information.
Let’s define a FragmentDestination to contain:
- position
-
the 2D pixel position in framebuffer space
- sampleIndex
-
an integer in case § 22.3.10 Sample frequency shading is active, or
null
otherwise
We’ll also use a notion of NDC - normalized device coordinates. In this coordinate system, the viewport bounds range in X and Y from -1 to 1, and in Z from 0 to 1.
Rasterization produces a list of RasterizationPoint s, each containing the following data:
- destination
-
refers to FragmentDestination
- coverageMask
-
refers to multisample coverage mask (see § 22.3.11 Sample Masking )
- frontFacing
-
is true if it’s a point on the front face of a primitive
- perspectiveDivisor
-
refers to interpolated 1.0 ÷ W across the primitive
- depth
-
refers to the depth in NDC
- primitiveVertices
-
refers to the list of vertex outputs forming the primitive
- barycentricCoordinates
-
refers to § 22.3.5.3 Barycentric coordinates
define the depth computation algorithm
Arguments:
-
primitiveList : List of primitives to rasterize.
-
state : The active RenderState .
Returns: list of RasterizationPoint .
Each primitive in primitiveList is processed independently. However, the order of primitives affects later stages, such as depth/stencil operations and pixel writes.
-
First, the clipped vertices are transformed into NDC - normalized device coordinates. Given the output position p , the NDC coordinates are computed as:
divisor( p ) = 1.0 ÷ p .w
ndc( p ) = vector( p .x ÷ p .w, p .y ÷ p .w, p .z ÷ p .w)
-
Let vp be state . viewport . Then the NDC coordinates n are converted into framebuffer coordinates, based on the size of the render targets:
framebufferCoords(
n
)
=
vector(
vp
.
x
+
0.5
×
(
n
.x
+
1)
×
vp
.
width
,
vp
.
y
+
.5
×
(
n
.y
+
1)
×
vp
.
height
)
specify the depth translation into viewport as well
-
Let rasterizationPoints be an empty list.
specify
that
each
rasterization
point
gets
assigned
an
interpolated
divisor(p)
and
framebufferCoords(n)
,
as
well
as
the
other
attributes.
-
Proceed with a specific rasterization algorithm, depending on
primitive
.topology
:-
"point-list"
-
The point, if not filtered by § 22.3.4 Primitive Clipping , goes into § 22.3.5.1 Point Rasterization .
-
"line-list"
or"line-strip"
-
The line cut by § 22.3.4 Primitive Clipping goes into § 22.3.5.2 Line Rasterization .
-
"triangle-list"
or"triangle-strip"
-
The polygon produced in § 22.3.4 Primitive Clipping goes into § 22.3.5.4 Polygon Rasterization .
-
-
Remove all the points rp from rasterizationPoints that have rp . destination . position outside of state . scissorRect .
-
Return rasterizationPoints .
22.3.5.1. Point Rasterization
A single FragmentDestination is selected within the pixel containing the framebuffer coordinates of the point.
The coverage mask depends on multi-sampling mode:
- sample-frequency
-
coverageMask = 1 ≪
sampleIndex
- pixel-frequency multi-sampling
-
coverageMask = 1 ≪ descriptor .
multisample
.count
− 1 - no multi-sampling
-
coverageMask = 1
22.3.5.2. Line Rasterization
22.3.5.3. Barycentric coordinates
Barycentric coordinates is a list of n numbers b i , defined for a point p inside a convex polygon with n vertices v i in framebuffer space. Each b i is in range 0 to 1, inclusive, and represents the proximity to vertex v i . Their sum is always constant:
∑ ( b i ) = 1
These coordinates uniquely specify any point p within the polygon (or on its boundary) as:
p = ∑ ( b i × p i )
For a polygon with 3 vertices - a triangle, barycentric coordinates of any point p can be computed as follows:
A polygon = A( v 1 , v 2 , v 3 ) b 1 = A( p , b 2 , b 3 ) ÷ A polygon b 2 = A( b 1 , p , b 3 ) ÷ A polygon b 3 = A( b 1 , b 2 , p ) ÷ A polygon
Where A(list of points) is the area of the polygon with the given set of vertices.
For polygons with more than 3 vertices, the exact algorithm is implementation-dependent. One of the possible implementations is to triangulate the polygon and compute the barycentrics of a point based on the triangle it falls into.
22.3.5.4. Polygon Rasterization
A polygon is front-facing if it’s oriented towards the projection. Otherwise, the polygon is back-facing .
Arguments:
Returns: list of RasterizationPoint .
-
Let rasterizationPoints be an empty list.
-
Let v ( i ) be the framebuffer coordinates for the clipped vertex number i (starting with 1) in a rasterized polygon of n vertices.
Note: this section uses the term "polygon" instead of a "triangle", since § 22.3.4 Primitive Clipping stage may have introduced additional vertices. This is non-observable by the application.
-
Determine if the polygon is front-facing, which depends on the sign of the area occupied by the polygon in framebuffer coordinates:
area = 0.5 × (( v 1 .x × v n .y − v n .x × v 1 .y) + ∑ ( v i +1 .x × v i .y − v i .x × v i +1 .y))
The sign of area is interpreted based on the
primitive
.frontFace
:-
"ccw"
-
area > 0 is considered front-facing , otherwise back-facing
-
"cw"
-
area < 0 is considered front-facing , otherwise back-facing
-
-
Cull based on
primitive
.cullMode
:-
"none"
-
All polygons pass this test.
-
"front"
-
The front-facing polygons are discarded, and do not process in later stages of the render pipeline.
-
"back"
-
The back-facing polygons are discarded.
-
-
Determine a set of fragments inside the polygon in framebuffer space - these are locations scheduled for the per-fragment operations. This operation is known as "point sampling". The logic is based on descriptor .
multisample
:- disabled
-
Fragment s are associated with pixel centers. That is, all the points with coordinates C , where fract( C ) = vector2(0.5, 0.5) in the framebuffer space, enclosed into the polygon, are included. If a pixel center is on the edge of the polygon, whether or not it’s included is not defined.
Note: this becomes a subject of precision for the rasterizer.
- enabled
-
Each pixel is associated with descriptor .
multisample
.count
locations, which are implementation-defined. The locations are ordered, and the list is the same for each pixel of the framebuffer . Each location corresponds to one fragment in the multisampled framebuffer .The rasterizer builds a mask of locations being hit inside each pixel and provides is as "sample-mask" built-in to the fragment shader.
-
For each produced fragment of type FragmentDestination :
-
Let rp be a new RasterizationPoint object
-
Compute the list b as § 22.3.5.3 Barycentric coordinates of that fragment. Set rp . barycentricCoordinates to b .
-
Let d i be the depth value of v i .
-
Set rp . depth to ∑ ( b i × d i )
-
Append rp to rasterizationPoints .
-
-
Return rasterizationPoints .
22.3.6. Fragment Processing
The fragment processing stage is a programmable stage of the render pipeline that computes the fragment data (often a color) to be written into render targets.
This stage produces a Fragment for each RasterizationPoint :
-
destination refers to FragmentDestination .
-
coverageMask refers to multisample coverage mask (see § 22.3.11 Sample Masking ).
-
depth refers to the depth in NDC coordinates.
-
colors refers to the list of color values, one for each target in
colorAttachments
.
Arguments:
-
rp : The RasterizationPoint , produced by § 22.3.5 Rasterization .
-
desc : The descriptor of type
GPUFragmentState
. -
state : The active RenderState .
Returns:
Fragment
or
null
.
-
Let fragment be a new Fragment object.
-
Set fragment . destination to rp . destination .
-
Set fragment . coverageMask to rp . coverageMask .
-
If desc is not
null
:-
Set the shader input builtins . For each non-composite argument of the entry point, annotated as a builtin , set its value based on the annotation:
-
position
-
vec4<f32>
( rp . destination . position , rp . depth , rp . perspectiveDivisor ) -
front_facing
-
rp . frontFacing
-
sample_index
-
rp . destination . sampleIndex
-
sample_mask
-
rp . coverageMask
-
-
For each user-specified pipeline input of the fragment stage:
-
Let value be the interpolated fragment input, based on rp . barycentricCoordinates , rp . primitiveVertices , and the interpolation qualifier on the input.
-
Set the corresponding fragment shader location input to value .
-
-
Invoke the fragment shader entry point described by desc .
-
If the fragment issued
discard
, returnnull
. -
Set fragment . colors to the user-specified pipeline output values from the shader.
-
Take the shader output builtins :
-
If
sample_mask
builtin is produced by the shader as value :-
Set fragment . coverageMask to fragment . coverageMask ∧ value .
-
Otherwise we are in § 22.3.8 No Color Output mode, and fragment . colors is empty.
-
-
Return fragment .
Processing
of
fragments
happens
in
parallel,
while
any
side
effects,
such
as
writes
into
GPUBufferBindingType."storage"
bindings,
may
happen
in
any
order.
22.3.7. Output Merging
The
depth
input
to
this
stage,
if
any,
is
clamped
to
the
current
[[viewport]]
depth
range
(regardless
of
whether
the
fragment
shader
stage
writes
the
frag_depth
builtin).
22.3.8. No Color Output
In no-color-output mode, pipeline does not produce any color attachment outputs.
The pipeline still performs rasterization and produces depth values based on the vertex position output. The depth testing and stencil operations can still be used.
22.3.9. Alpha to Coverage
In
alpha-to-coverage
mode,
an
additional
alpha-to-coverage
mask
of
MSAA
samples
is
generated
based
on
the
alpha
component
of
the
fragment
shader
output
value
of
the
fragment
.
targets
[0].
The algorithm of producing the extra mask is platform-dependent and can vary for different pixels. It guarantees that:
-
if alpha is 0.0 or less, the result is 0x0
-
if alpha is 1.0 or greater, the result is 0xFFFFFFFF
-
if alpha is greater than some other alpha1 , then the produced sample mask has at least as many bits set to 1 as the mask for alpha1
22.3.10. Sample frequency shading
22.3.11. Sample Masking
The
final
sample
mask
for
a
pixel
is
computed
as:
rasterization
mask
&
mask
&
shader-output
mask
.
Only
the
lower
count
bits
of
the
mask
are
considered.
If the least-significant bit at position N of the final sample mask has value of "0", the sample color outputs (corresponding to sample N ) to all attachments of the fragment shader are discarded. Also, no depth test or stencil operations are executed on the relevant samples of the depth-stencil attachment.
Note: the color output for sample N is produced by the fragment shader execution with SV_SampleIndex == N for the current pixel. If the fragment shader doesn’t use this semantics, it’s only executed once per pixel.
The rasterization mask is produced by the rasterization stage, based on the shape of the rasterized polygon. The samples included in the shape get the relevant bits 1 in the mask.
The
shader-output
mask
takes
the
output
value
of
"sample_mask"
builtin
in
the
fragment
shader.
If
the
builtin
is
not
output
from
the
fragment
shader,
and
alphaToCoverageEnabled
is
enabled,
the
shader-output
mask
becomes
the
alpha-to-coverage
mask
.
Otherwise,
it
defaults
to
0xFFFFFFFF.
23. Type Definitions
typedef [EnforceRange ]unsigned long ;
GPUBufferDynamicOffset typedef [EnforceRange ]unsigned long ;
GPUStencilValue typedef [EnforceRange ]unsigned long ;
GPUSampleMask typedef [EnforceRange ]long ;
GPUDepthBias typedef [EnforceRange ]unsigned long long ;
GPUSize64 typedef [EnforceRange ]unsigned long ;
GPUIntegerCoordinate typedef [EnforceRange ]unsigned long ;
GPUIndex32 typedef [EnforceRange ]unsigned long ;
GPUSize32 typedef [EnforceRange ]long ;
GPUSignedOffset32 typedef unsigned long ;
GPUFlagsConstant
23.1. Colors & Vectors
dictionary {
GPUColorDict required double ;
r required double ;
g required double ;
b required double ; };
a typedef (sequence <double >or GPUColorDict );
GPUColor
Note:
double
is
large
enough
to
precisely
hold
32-bit
signed/unsigned
integers
and
single-precision
floats.
dictionary {
GPUOrigin2DDict = 0; = 0;GPUIntegerCoordinate = 0;
x GPUIntegerCoordinate = 0; };
y ;typedef (sequence <GPUIntegerCoordinate >or GPUOrigin2DDict );
GPUOrigin2D
An
Origin2D
is
a
GPUOrigin2D
.
Origin2D
is
a
spec
namespace
for
the
following
definitions:
GPUOrigin2D
value
origin
,
depending
on
its
type,
the
syntax:
-
origin . x refers to either
GPUOrigin2DDict
.x
or the first item of the sequence or 0 if it isn’t present. -
origin . y refers to either
GPUOrigin2DDict
.y
or the second item of the sequence or 0 if it isn’t present.
dictionary {
GPUOrigin3DDict = 0; = 0; = 0;GPUIntegerCoordinate = 0;
x GPUIntegerCoordinate = 0;
y GPUIntegerCoordinate = 0; };
z ;typedef (sequence <GPUIntegerCoordinate >or GPUOrigin3DDict );
GPUOrigin3D
An
Origin3D
is
a
GPUOrigin3D
.
Origin3D
is
a
spec
namespace
for
the
following
definitions:
GPUOrigin3D
value
origin
,
depending
on
its
type,
the
syntax:
-
origin . x refers to either
GPUOrigin3DDict
.x
or the first item of the sequence or 0 if it isn’t present. -
origin . y refers to either
GPUOrigin3DDict
.y
or the second item of the sequence or 0 if it isn’t present. -
origin . z refers to either
GPUOrigin3DDict
.z
or the third item of the sequence or 0 if it isn’t present.
dictionary {
GPUExtent3DDict ; = 1; = 1;required GPUIntegerCoordinate ;
width GPUIntegerCoordinate = 1;
height GPUIntegerCoordinate = 1; };
depthOrArrayLayers ;typedef (sequence <GPUIntegerCoordinate >or GPUExtent3DDict );
GPUExtent3D
An
Extent3D
is
a
GPUExtent3D
.
Extent3D
is
a
spec
namespace
for
the
following
definitions:
GPUExtent3D
value
extent
,
depending
on
its
type,
the
syntax:
-
extent . width refers to either
GPUExtent3DDict
.width
or the first item of the sequence (1 if not present). -
extent . height refers to either
GPUExtent3DDict
.height
or the second item of the sequence (1 if not present). -
extent . depthOrArrayLayers refers to either
GPUExtent3DDict
.depthOrArrayLayers
or the third item of the sequence (1 if not present).
24. Feature Index
24.1.
"depth-clip-control"
Define
functionality
when
the
"depth-clip-control"
feature
is
enabled.
Feature Dictionary Values
The
following
dictionary
values
are
supported
if
and
only
if
the
"depth-clip-control"
feature
is
enabled;
otherwise,
they
must
be
set
to
their
default
values:
-
GPUPrimitiveState
24.2.
"depth24unorm-stencil8"
Allows
for
explicit
creation
of
textures
of
format
"depth24unorm-stencil8"
.
Feature Enums
The
following
enums
are
supported
if
and
only
if
the
"depth24unorm-stencil8"
feature
is
enabled:
-
GPUTextureFormat
24.3.
"depth32float-stencil8"
Allows
for
explicit
creation
of
textures
of
format
"depth32float-stencil8"
.
Feature Enums
The
following
enums
are
supported
if
and
only
if
the
"depth32float-stencil8"
feature
is
enabled:
-
GPUTextureFormat
24.4.
"texture-compression-bc"
Allows for explicit creation of textures of BC compressed formats.
Feature Enums
The
following
enums
are
supported
if
and
only
if
the
"texture-compression-bc"
feature
is
enabled:
-
GPUTextureFormat
24.5.
"texture-compression-etc2"
Allows for explicit creation of textures of ETC2 compressed formats.
Feature Enums
The
following
enums
are
supported
if
and
only
if
the
"texture-compression-etc2"
feature
is
enabled:
-
GPUTextureFormat
24.6.
"texture-compression-astc"
Allows for explicit creation of textures of ASTC compressed formats.
Feature Enums
The
following
enums
are
supported
if
and
only
if
the
"texture-compression-astc"
feature
is
enabled:
-
GPUTextureFormat
-
24.7.
"timestamp-query"
Define
functionality
when
the
"timestamp-query"
feature
is
enabled.
Feature Enums
The
following
enums
are
supported
if
and
only
if
the
"timestamp-query"
feature
is
enabled:
-
GPUQueryType
24.8.
"indirect-first-instance"
Removes
the
zero
value
restriction
on
firstInstance
in
indirect
draw
parameters
and
indirect
drawIndexed
parameters
.
firstInstance
is
allowed
to
be
non-zero
if
and
only
if
the
"indirect-first-instance"
feature
is
enabled.
24.9.
"shader-f16"
Using
"
enable
f16;
"
directive
in
WGSL
code
for
a
shader
module
is
allowed
if
and
only
if
the
"shader-f16"
feature
is
enabled;
otherwise
using
it
must
result
in
a
compilation
error
when
creating
shader
module.
25. Appendices
25.1. Texture Format Capabilities
25.1.1. Plain color formats
All
plain
color
formats
support
COPY_SRC
,
COPY_DST
,
and
TEXTURE_BINDING
usage.
Only
formats
with
GPUTextureSampleType
"float"
can
be
blended.
The
RENDER_ATTACHMENT
and
STORAGE_BINDING
columns
specify
support
for
GPUTextureUsage.RENDER_ATTACHMENT
and
GPUTextureUsage.STORAGE_BINDING
usage
respectively.
25.1.2. Depth-stencil formats
A depth-or-stencil format is any format with depth and/or stencil aspects. A combined depth-stencil format is a depth-or-stencil format that has both depth and stencil aspects.
All
depth-or-stencil
formats
support
the
COPY_SRC
,
COPY_DST
,
TEXTURE_BINDING
,
and
RENDER_ATTACHMENT
usages.
All
of
these
formats
support
multisampling.
However,
certain
copy
operations
also
restrict
the
source
and
destination
formats.
Depth
textures
cannot
be
used
with
"filtering"
samplers,
but
can
always
be
used
with
"comparison"
samplers
(which
may
use
filtering).
Format | Bytes per texel | Aspect | Texel block size (Bytes) |
GPUTextureSampleType
| Valid image copy source | Valid image copy destination | Aspect-specific format |
---|---|---|---|---|---|---|---|
stencil8
| 1 − 4 | stencil | 1 |
"uint"
| ✓ |
stencil8
| |
depth16unorm
| 2 | depth | 2 |
"depth"
| ✓ |
depth16unorm
| |
depth24plus
| 4 | depth | - ( See prose ) |
"depth"
| ✗ |
depth24plus
| |
depth24plus-stencil8
| 4 − 8 | depth | - ( See prose ) |
"depth"
| ✗ |
depth24plus
| |
stencil | 1 |
"uint"
| ✓ |
stencil8
| |||
depth32float
| 4 | depth | 4 |
"depth"
| ✓ | ✗ |
depth32float
|
depth24unorm-stencil8
| 4 | depth | 3 |
"depth"
| ✗ |
depth24plus
| |
stencil | 1 |
"uint"
| ✓ |
stencil8
| |||
depth32float-stencil8
| 5 − 8 | depth | 4 |
"depth"
| ✓ | ✗ |
depth32float
|
stencil | 1 |
"uint"
| ✓ |
stencil8
|
25.1.2.1. Reading and Sampling Depth/Stencil Textures
When
reading
or
sampling
a
depth
component
via
a
texture_depth_*
-typed
binding,
the
value
is
returned
as
an
f32
value.
Depending
on
the
resolution
of
this
issue,
allow
reading/sampling
via
texture_2d
etc.
in
the
table
above
and
specify
the
behavior.
(
vec4<f32>(D,
X,
X,
X)
?)
Update
the
note
below
which
would
become
slightly
outdated.
[Issue
#gpuweb/gpuweb#2094]
Reading
or
sampling
a
stencil
component
must
be
done
via
a
normal
texture
binding
(
texture_2d
,
texture_2d_array
,
texture_cube
,
or
texture_cube_array
).
When
doing
so,
the
value
is
returned
as
vec4<u32>(S,
X,
X,
X)
,
where
S
is
the
stencil
value
and
each
X
is
an
implementation-defined
unspecified
value.
Authors
must
not
rely
on
these
.y
,
.z
,
and
.w
components,
as
their
behavior
is
non-portable.
Note:
Short
of
adding
a
new
more
constrained
stencil
sampler
type
(like
depth),
it’s
infeasible
for
implementations
to
efficiently
paper
over
the
driver
differences
for
stencil
reads.
As
this
was
not
a
portability
pain
point
for
WebGL,
it’s
not
expected
to
be
problematic
in
WebGPU.
In
practice,
expect
either
vec4<u32>(S,
S,
S,
S)
or
vec4<u32>(S,
0,
0,
1)
,
depending
on
hardware.
25.1.2.2. Copying Depth/Stencil Textures
The
texel
values
of
depth32float
formats
(
"depth32float"
and
"depth32float-stencil8"
have
a
limited
range.
As
a
result,
copies
into
such
textures
are
only
valid
from
other
textures
of
the
same
format.
The
depth
aspects
of
depth24plus
formats
(
"depth24plus"
and
"depth24plus-stencil8"
)
have
opaque
representations
(implemented
as
either
"depth24unorm"
or
"depth32float").
The
depth
aspect
of
"depth24unorm-stencil8"
doesn’t
have
an
aligned
tightly-packed
representation
(because
its
size
is
3
bytes).
As
a
result,
depth-aspect
image
copies
are
not
allowed
with
these
formats.
-
All of these formats can be written in a render pass using a fragment shader that outputs depth values via the
frag_depth
output. -
Textures with "depth24plus"/"depth24unorm" formats can be read as shader textures, and written to a texture (as a render pass attachment) or buffer (via a storage buffer binding in a compute shader).
25.1.3. Packed formats
All
packed
texture
formats
support
COPY_SRC
,
COPY_DST
,
and
TEXTURE_BINDING
usages.
All
of
these
formats
have
"float"
type
and
can
be
filtered
on
sampling.
None
of
these
formats
support
multisampling.
A compressed format is any format with a block size greater than 1 × 1.
The texel block size (in bytes) of a packed format is equal to the Bytes per block column below.
25.2. Temporary usages of non-exported dfns
Eventually all of these should disappear but they are useful to avoid warning while building the specification.