WebGPU

1. 引言

本节为非规范性内容。

图形处理单元（GPU）在个人计算领域中已成为实现丰富渲染和计算应用的关键。WebGPU 是一个为 Web 暴露 GPU 硬件能力的 API。该 API 从零开始设计，能够高效映射到（2014年之后的）原生 GPU API。WebGPU 与 WebGL 无关，也不直接针对 OpenGL ES。

WebGPU 将物理 GPU 硬件视为 GPUAdapter。它通过 GPUDevice 提供与适配器的连接，设备负责管理资源，并通过设备的 GPUQueue 执行命令。GPUDevice 可能拥有自己的高速存储器以供处理单元访问。GPUBuffer 和 GPUTexture 是由 GPU 内存支持的物理资源。GPUCommandBuffer 和 GPURenderBundle 是用户录制命令的容器。GPUShaderModule 包含 着色器代码。其他资源如 GPUSampler 或 GPUBindGroup 用于配置 GPU 如何使用物理资源。

GPU 通过 GPUCommandBuffer 编码的命令，通过 管线 执行，该管线是固定功能与可编程阶段的混合体。可编程阶段运行着色器，即专为 GPU 硬件设计的特殊程序。管线的大部分状态由 GPURenderPipeline 或 GPUComputePipeline 对象定义。未包含在这些 管线对象中的状态，则在命令编码阶段通过如 beginRenderPass() 或 setBlendConstant() 之类命令设置。

2. 恶意使用考量

本节为非规范性内容。 介绍了在 Web 上暴露此 API 所带来的风险。

2.1. 安全考量

WebGPU 的安全要求与 Web 一贯的要求相同，也是不可协商的。总体原则是：在所有命令到达 GPU 之前进行严格校验，确保页面只能操作自身数据。

2.1.1. 基于 CPU 的未定义行为

WebGPU 实现会将用户发起的工作量转换为目标平台特定的 API 命令。原生 API 规定了命令的有效用法（例如见 vkCreateDescriptorSetLayout），并且通常不保证不遵守有效用法规则时的任何结果。这被称为“未定义行为”，攻击者可以利用它访问非授权内存，或迫使驱动执行任意代码。

为禁止不安全用法，WebGPU 针对任意输入都定义了允许的行为范围。实现必须校验所有用户输入，只允许有效工作负载到达驱动。本规范规定了所有错误条件及其处理语义。例如，在 copyBufferToBuffer() 的 "source" 和 "destination" 同时指定同一缓冲区，且区间相交时，GPUCommandEncoder 会生成错误，且不会执行其它操作。

更多错误处理信息参见 § 22 错误与调试。

2.1.2. 基于 GPU 的未定义行为

WebGPU 着色器 由 GPU 内部的计算单元执行。在原生 API 中，某些着色器指令可能在 GPU 上导致未定义行为。为应对这一点，WebGPU 严格定义了着色器指令集及其行为。当为 createShaderModule() 提供着色器时，WebGPU 实现必须在进行任何平台特定着色器转换或变换之前进行校验。

2.1.3. 未初始化数据

一般来说，分配新内存可能暴露系统上其它应用残留的数据。为避免此问题，WebGPU 在概念上会将所有资源初始化为零，尽管若实现检测到开发者已手动初始化内容时可跳过此步骤。这包括着色器内变量和共享工作组内存。

清除工作组内存的具体机制依平台而异。若原生 API 未提供清除机制，WebGPU 实现会先在所有调用中清空，再同步，然后继续执行开发者代码。

2.1.4. 着色器中的越界访问

着色器可以直接访问物理资源（如 "uniform" GPUBufferBinding），也可以通过纹理单元（为纹理坐标转换而设的固定功能硬件块）间接访问。WebGPU API 的校验只能保证所有着色器输入已提供且类型正确。如果未通过纹理单元访问，WebGPU API 无法保证数据访问不会越界。

为防止着色器访问非本应用 GPU 内存，WebGPU 实现可在驱动中启用“健壮缓冲区访问”模式，确保访问不会超出缓冲区界限。

或者，实现可在着色器代码中插入手动越界检查。此时，越界检查仅适用于数组索引，对结构体字段访问则无需手动检查，因为主机侧 minBindingSize 校验已覆盖。

若着色器尝试读取物理资源边界外的数据，实现可以：

1. 返回资源边界内其他位置的值

2. 返回值向量 "(0, 0, 0, X)"，其中 X 可为任意值

3. 部分丢弃绘制或调度调用

若着色器尝试写入物理资源边界外，实现可以：

1. 写入资源边界内其他位置

2. 丢弃写入操作

3. 部分丢弃绘制或调度调用

2.1.5. 无效数据

从 CPU 向 GPU 上传 浮点数数据或在 GPU 上生成浮点数时，可能会出现不对应于有效数值的二进制表示（如无穷大或 NaN）。此时 GPU 行为取决于硬件对 IEEE-754 标准的实现精度。WebGPU 保证引入无效浮点数只会影响算术运算结果，不会有其他副作用。

2.1.6. 驱动漏洞

GPU 驱动程序和其他软件一样可能存在漏洞。攻击者可能利用驱动的错误行为访问非授权数据。为降低风险，WebGPU 工作组将与 GPU 厂商协作，将 WebGPU 一致性测试套件（CTS）集成到驱动测试流程中，类似 WebGL 的做法。WebGPU 实现应对已发现的部分漏洞有兼容性处理，并对无法绕过的已知漏洞驱动禁用 WebGPU。

2.1.7. 时序攻击

2.1.7.1. 内容时间线时序

WebGPU 不会向 JavaScript 暴露在 内容时间线上由 agent 在 agent cluster 中共享的新状态。内容时间线状态如 [[mapping]] 仅在显式 内容时间线任务（如普通 JavaScript）中变化。

2.1.7.2. 设备/队列时间线时序

可写存储缓冲区和其他跨调用通信机制可能用于在队列时间线上构造高精度定时器。

可选的 "timestamp-query" 特性也为 GPU 操作提供高精度计时。为缓解安全和隐私风险，定时查询的值被对齐到较低精度：参见 current queue timestamp。特别注意：

• 设备时间线通常在多个源共享的进程中运行，因此跨源隔离（如 COOP/COEP）无法隔离设备/队列时间线定时器。

• 队列时间线工作由设备时间线发起，可能在不能像 CPU 进程（如 Meltdown 缓解）那样隔离的 GPU 硬件上执行。

• GPU 硬件通常不易受到 Spectre 类攻击，但 WebGPU 可能在软件中实现，软件实现可能运行在共享进程中，无法依赖隔离缓解。

2.1.8. Row hammer 攻击

Row hammer 是一类利用 DRAM 单元状态泄漏的攻击，可被用于 GPU。WebGPU 没有专门的防护措施，依赖于平台级解决方案，例如缩短内存刷新间隔。

2.1.9. 拒绝服务

WebGPU 应用可访问 GPU 内存和计算单元。WebGPU 实现可以限制应用可用的 GPU 内存，以保证其他应用的响应性。对于 GPU 处理时间，WebGPU 实现可以设置“看门狗”定时器，确保应用不会导致 GPU 无响应超过数秒。这些措施类似于 WebGL 所采用的策略。

2.1.10. 工作负载识别

WebGPU 提供对全局受限资源的访问，这些资源由同一台机器上不同程序（和网页）共享。应用可通过间接探测全局资源受限程度，进而推测其他网页正在进行的工作负载。这些问题与 Javascript 中的系统内存和 CPU 执行吞吐量类似。WebGPU 没有对此提供额外的缓解措施。

2.1.11. 内存资源

WebGPU 允许从机器全局内存堆（如 VRAM）进行可失败的分配。这使得应用可以通过尝试分配并观察分配失败情况，探测系统剩余可用内存（针对特定堆类型）。

GPU 内部一般有一个或多个（通常只有两个）所有运行应用共享的内存堆。当某个堆耗尽时，WebGPU 创建资源会失败。这是可观察到的，可能使恶意应用推测出其他应用使用了哪些堆，以及它们分配了多少。

2.1.12. 计算资源

如果一个站点与另一个站点同时使用 WebGPU，它可能会观察到处理某些工作的耗时增加。例如，持续向队列提交计算工作并跟踪完成时间，可能会发现其他任务也开始使用 GPU。

GPU 有多个可独立测试的部分，如算术单元、纹理采样单元、原子单元等。恶意应用可以检测某些单元的负载，并试图分析压力模式来猜测其他应用的工作负载。这与 Javascript 的 CPU 执行现实类似。

2.1.13. 能力滥用

恶意站点可能滥用 WebGPU 所暴露的能力，运行对用户或其体验无益、仅对站点有利的计算。例如隐蔽挖矿、密码破解或彩虹表计算。

无法针对这类 API 使用方式加以防范，因为浏览器无法区分有效负载和滥用负载。这是 Web 上所有通用计算能力（如 JavaScript、WebAssembly 或 WebGL）面临的普遍问题。WebGPU 只是让某些负载的实现更容易，或比 WebGL 更高效。

为缓解此类滥用，浏览器可对后台标签页的操作进行限速，可警告标签页资源占用过高，并可限制哪些上下文允许使用 WebGPU。

用户代理可基于启发式方法向用户发出高功耗警告，尤其在检测到潜在恶意使用时。如果实现此类警告，应将 WebGPU 使用纳入与 JavaScript、WebAssembly、WebGL 等相同的启发式中。

2.2. 隐私考量

WebGPU 的隐私考量与 WebGL 类似。GPU API 十分复杂，必须出于必要暴露设备能力的各个方面，以便开发者能够有效利用这些能力。一般的缓解方法是对潜在可识别信息进行归一化或分桶，并在可能的情况下强制行为一致。

用户代理不得暴露超过 32 种可区分配置或分桶。

2.2.1. 机器特有功能与限制

WebGPU 可以揭示底层 GPU 架构和设备结构的许多细节，包括可用的物理适配器、GPU 和 CPU 资源的多项限制（如最大纹理尺寸），以及可用的任何可选硬件专属能力。

用户代理没有义务暴露真实硬件限制，可以完全控制机器细节的暴露程度。减少指纹识别的一种策略是将所有目标平台归为少数几个分桶。总体来说，暴露硬件限制的隐私影响与 WebGL 相同。

默认限制值也被故意设置得足够高，以便大多数应用无需请求更高限制即可运行。所有 API 的使用都按请求限制进行校验，因此不会因意外而向用户暴露实际硬件能力。

2.2.2. 机器特有产物

和 WebGL 一样，可以观察到一些机器特有的光栅化/精度差异和性能差异。这涉及光栅化覆盖及模式、着色器阶段间 varyings 的插值精度、计算单元调度，以及更多执行相关特性。

通常，同一厂商的大多数或全部设备的光栅化和精度指纹是相同的。性能差异难以完全规避，但信号强度较低（如 JS 执行性能）。

对隐私要求高的应用和用户代理应采用软件实现以消除这类产物。

2.2.3. 机器特有性能

通过测量 GPU 上特定操作的性能也是区分用户的一个因素。即便计时精度较低，重复执行某一操作也能体现用户机器在特定负载下的快慢。这是常见的识别向量（WebGL 和 Javascript 皆有），但信号较低且难以完全规避。

WebGPU 计算管线让开发者可绕过固定功能硬件直接访问 GPU，这带来了独特设备指纹识别的额外风险。用户代理可通过将逻辑 GPU 调用与实际计算单元解耦来降低此风险。

2.2.4. 用户代理状态

本规范未为源定义任何额外用户代理状态。但预期用户代理会对 GPUShaderModule、 GPURenderPipeline、 GPUComputePipeline 等高开销编译结果进行缓存。这些缓存有助于提升 WebGPU 应用首次访问后的加载速度。

对规范而言，这些缓存与极快编译无异，但应用可以轻易测量 createComputePipelineAsync() 的耗时。这可能导致跨源信息泄露（如“用户是否访问过包含特定着色器的站点”），因此用户代理应遵循 存储分区最佳实践。

系统的 GPU 驱动也可能有自己的着色器和管线编译缓存。用户代理可在可能的情况下禁用该缓存，或为着色器添加分区数据，使驱动将其视为不同对象。

2.2.5. 驱动漏洞

除安全考量中提到的问题外，驱动漏洞还可能导致行为差异，成为区分用户的手段。此处可采用安全考量中提及的缓解措施，如与 GPU 厂商协作，在用户代理中实现已知问题的兼容处理。

2.2.6. 适配器标识符

WebGL 实践表明，开发者有合理需求识别其代码运行的 GPU，以便创建和维护健壮的 GPU 内容。例如识别有已知驱动漏洞的适配器，以便规避或避免在某些硬件上使用表现不佳的特性。

但暴露适配器标识符自然会增加指纹识别信息量，因此有必要限制适配器识别的精度。

可以采取多项缓解措施以平衡内容健壮性与隐私保护。首先，用户代理可通过主动识别和规避已知驱动问题，减少开发者负担，就像浏览器开始用 GPU 以来所做的一样。

默认暴露适配器标识符时应尽量宽泛，只要有用即可。例如，可仅标识适配器厂商及架构而非具体型号。有时也可报告实际适配器的合理代理的标识符。

在需要完整详细适配器信息（如提交 bug 报告）时，可请用户同意向页面披露更多硬件信息。

最后，若用户代理认为合适（如增强隐私模式下），可完全不报告适配器标识符。

3. 基础

3.1. 约定

3.1.1. 语法速记

本规范中使用了如下语法速记：

.（点）语法，常见于编程语言。

短语“Foo.Bar”表示“值（或接口）Foo 的 Bar 成员”。如果 Foo 是 有序映射（ordered map）且 Bar 在 Foo 中未存在，则返回 undefined。

短语“Foo.Bar 被提供”表示“Bar 成员存在于 映射值 Foo 中”。

?.（可选链）语法，借鉴自 JavaScript。

短语“Foo?.Bar”表示：“如果 Foo 为 null 或 undefined 或 Bar 在 Foo 中未存在，则为 undefined；否则为 Foo.Bar”。

例如，若 buffer 是一个 GPUBuffer，则 buffer?.\[[device]].\[[adapter]] 表示：“如果 buffer 为 null 或 undefined，则为 undefined；否则为 buffer 的 \[[device]] 内部槽的 \[[adapter]] 内部槽。”

??（空值合并）语法，借鉴自 JavaScript。

短语“x ?? y”表示：“如果 x 不为 null 或 undefined，则为 x，否则为 y。”

槽支持属性（slot-backed attribute）

由同名内部槽支持的 WebIDL 属性。其可变性视规范而定。

3.1.2. WebGPU 对象

WebGPU 对象由WebGPU 接口和内部对象组成。

WebGPU 接口定义了WebGPU 对象的公共接口和状态。它可在其创建的内容时间线上使用，此时它是 JavaScript 暴露的 WebIDL 接口。

任何包含 GPUObjectBase 的接口都是 WebGPU 接口。

内部对象跟踪WebGPU 对象在设备时间线上的状态。所有对内部对象可变状态的读写都发生在单一有序的设备时间线步骤中。

在WebGPU 对象上可定义以下特殊属性类型：

不可变属性（immutable property）

在对象初始化时设定的只读槽，可从任意时间线访问。

注：由于该槽不可变，实现可在多个时间线中保有副本，按需分配。不可变属性这样定义是为避免在规范中描述多个副本。

若命名为 [[带括号]]，则是内部槽。
若命名为 不带括号，则是 WebGPU 接口的 readonly 槽支持属性。

内容时间线属性（content timeline property）

仅可从对象创建的内容时间线访问的属性。

若命名为 [[带括号]]，则是内部槽。
若命名为 不带括号，则是 WebGPU 接口的槽支持属性。

设备时间线属性（device timeline property）

跟踪内部对象状态，仅可从对象创建的设备时间线访问。设备时间线属性可为可变的。

设备时间线属性命名为 [[带括号]]，为内部槽。

队列时间线属性（queue timeline property）

跟踪内部对象状态，仅可从对象创建的队列时间线访问。队列时间线属性可为可变的。

队列时间线属性命名为 [[带括号]]，为内部槽。

interface mixin GPUObjectBase {
    attribute USVString label;
};

GPUObjectBase 具有如下不可变属性：

[[device]]，类型为device，只读

拥有该内部对象的设备。

对此对象内容的操作断言其运行在设备时间线上，并且设备是有效的。

GPUObjectBase 具有如下内容时间线属性：

label，类型为 USVString

开发者提供的标签，由实现自定义使用。可由浏览器、操作系统或其他工具用于帮助开发者识别底层内部对象。示例包括在 GPUError 消息、控制台警告、浏览器开发者工具和平台调试工具中显示标签。

注：

实现应当利用标签提升错误消息的可读性，用于标识 WebGPU 对象。

但这不必是标识对象的唯一方式：实现还应结合其他可用信息，尤其是在没有标签时。例如：

• 打印 GPUTexture 视图时，显示其父对象的标签。

• 打印 GPURenderPassEncoder 或 GPUComputePassEncoder 时，显示其父 GPUCommandEncoder 的标签。

• 打印 GPUCommandBuffer 时，显示其源 GPUCommandEncoder 的标签。

• 打印 GPURenderBundle 时，显示其源 GPURenderBundleEncoder 的标签。

注：

label 是 GPUObjectBase 的属性。两个 GPUObjectBase “包装器”对象即使引用同一底层对象，其 label 状态也是完全独立的（如由 getBindGroupLayout() 返回时）。除非通过 JavaScript 设置，否则 label 属性不会变更。

这意味着一个底层对象可关联多个标签。本规范未定义标签如何传递到 设备时间线。标签的使用完全由实现自定义：错误消息可显示最近设置的标签、所有已知标签，或完全不显示标签。

属性类型为 USVString，因为某些用户代理可能将其传递给底层原生 API 的调试工具。

GPUObjectBase 具有如下设备时间线属性：

[[valid]]，类型为boolean，初始值为 true

若为 true，表示该内部对象可用。

3.1.3. 对象描述符

对象描述符用于保存创建对象所需的信息，通常通过 GPUDevice 的 create* 方法之一进行对象创建。

dictionary GPUObjectDescriptorBase {
    USVString label = "";
};

GPUObjectDescriptorBase 具有如下成员：

label，类型为 USVString，默认值为 ""

GPUObjectBase.label 的初始值。

3.2. 异步性

3.2.1. 无效的内部对象与传染性无效

WebGPU 中的对象创建操作不会返回 Promise，但其本质上是异步的。返回的对象引用的是在设备时间线上被操作的内部对象。多数在设备时间线上发生的错误不会通过异常或拒绝抛出，而是通过关联设备上生成的 GPUError 进行传递。

内部对象可以是有效或无效。无效对象不会在之后变为有效，但部分有效对象可以被使无效（invalidated）。

如果对象无法被创建，则其从创建开始即为无效。例如，对象描述符未能描述出有效对象，或者没有足够内存分配资源时会发生此情况。如果从另一个无效对象创建对象（例如对无效的 GPUTexture 调用 createView()），也会如此。这类情况称为传染性无效。

大多数类型的内部对象在创建后不会变为无效，但仍可能变得不可用，例如其所属设备丢失或destroyed，或对象处于特殊内部状态（如缓冲区状态“destroyed”）。

部分类型的内部对象在创建后可以变为无效；具体包括设备、适配器、GPUCommandBuffer，以及命令/通道/捆绑编码器。

3.2.2. Promise 顺序

WebGPU 中有若干操作会返回 promise。

• GPU.requestAdapter()

• GPUAdapter.requestDevice()

• GPUDevice.createComputePipelineAsync()

• GPUDevice.createRenderPipelineAsync()

• GPUShaderModule.getCompilationInfo()

• GPUQueue.onSubmittedWorkDone()

• GPUBuffer.mapAsync()

• GPUDevice.lost

• GPUDevice.popErrorScope()

WebGPU 不保证这些 promise 的 settle（resolve 或 reject）顺序，除非有如下例外：

• 对于某个 GPUQueue q，如果 p1 = q.onSubmittedWorkDone() 先于 p2 = q.onSubmittedWorkDone() 被调用，则 p1 必须早于 p2 settle。
• 对于某个 GPUQueue q 和同一 GPUDevice 上的 GPUBuffer b，如果 p1 = b.mapAsync() 先于 p2 = q.onSubmittedWorkDone() 被调用，则 p1 必须早于 p2 settle。

应用不得依赖于其它 promise 的 settle 顺序。

3.3. 坐标系统

渲染操作使用如下坐标系统：

• 归一化设备坐标（NDC）有三维：

  • -1.0 ≤ x ≤ 1.0

  • -1.0 ≤ y ≤ 1.0

  • 0.0 ≤ z ≤ 1.0

  • 左下角为 (-1.0, -1.0, z)。

  

  注： z = 0 还是 z = 1 作为近平面由应用决定。上图以 z = 0 为近平面，但实际行为由着色器使用的投影矩阵、depthClearValue 和 depthCompare 函数共同决定。

• 裁剪空间坐标有四维：(x, y, z, w)

  • 裁剪空间坐标用于顶点的裁剪位置（即顶点着色器的position输出），以及裁剪体积。

  • 归一化设备坐标和裁剪空间坐标的关系如下：若点 p = (p.x, p.y, p.z, p.w) 在裁剪体积内，则其归一化设备坐标为 (p.x ÷ p.w, p.y ÷ p.w, p.z ÷ p.w)。

• 帧缓冲坐标用于寻址帧缓冲内的像素。

  • 为二维坐标。

  • 每个像素在 x、y 方向上长度为 1。

  • 左上角为 (0.0, 0.0)。

  • x 向右递增。

  • y 向下递增。

  • 参见 § 17 渲染通道 和 § 23.2.5 光栅化。

  

• 视口坐标结合了 x、y 方向的帧缓冲坐标与 z 方向的深度。

  • 通常 0.0 ≤ z ≤ 1.0，但可通过 [[viewport]].minDepth 和 maxDepth，以及 setViewport() 修改。

• 片元坐标与视口坐标一致。

• 纹理坐标，在 2D 中有时称为“UV 坐标”，用于采样纹理，其分量数量与 texture dimension 匹配。

  • 0 ≤ u ≤ 1.0

  • 0 ≤ v ≤ 1.0

  • 0 ≤ w ≤ 1.0

  • (0.0, 0.0, 0.0) 位于纹理存储顺序的首个 texel。

  • (1.0, 1.0, 1.0) 位于纹理存储顺序的最后一个 texel。

  

• 窗口坐标，或称显示坐标，与帧缓冲坐标一致，用于与外部显示或类似接口交互时。

注：WebGPU 的坐标系统与 DirectX 图形管线中的坐标系统一致。

3.4. 编程模型

3.4.1. 时间线

WebGPU 的行为以“时间线”为单位进行描述。每个操作（以算法定义）都发生在某个时间线上。时间线明确了操作的顺序，以及哪些状态可被哪些操作访问。

注： 这种“时间线”模型反映了浏览器引擎多进程模型（如“内容进程”和“GPU 进程”）的约束，也体现了许多实现中 GPU 作为独立执行单元的现实。实现 WebGPU 并不要求时间线并行执行，因此不要求多进程，甚至不要求多线程。（但如 获取上下文图像内容副本 这类需同步阻塞其它时间线完成的情况，仍需支持并发。）

内容时间线

与 Web 脚本的执行相关。包括本规范描述的所有方法调用。

要从 GPUDevice device 的操作向内容时间线派发步骤，可通过 为 GPUDevice 排队全局任务。

设备时间线

与用户代理发起的 GPU 设备操作相关。包括适配器、设备、GPU 资源与状态对象的创建，这些操作从用户代理控制 GPU 的部分看通常是同步的，但可在独立的操作系统进程中运行。

队列时间线

与 GPU 计算单元上操作的执行相关。包括实际在 GPU 上运行的绘制、拷贝和计算任务。

时间线无关

可以与上述任意时间线关联。

如仅操作不可变属性或调用步骤传入的参数，则可派发到任意时间线。

本规范中，当返回值依赖于非内容时间线上发生的工作时，采用异步操作。API 以 promise 或事件的形式表现异步操作。

3.4.2. 内存模型

本节为非规范性内容。

一旦应用初始化过程中获取到 GPUDevice，我们可以将 WebGPU 平台描述为包含以下各层：

1. 实现本规范的用户代理。

2. 为该设备提供底层原生 API 驱动的操作系统。

3. 实际的 CPU 和 GPU 硬件。

WebGPU 平台的每一层可能有不同类型的内存，用户代理在实现规范时需要加以考虑：

• 脚本拥有的内存，如脚本创建的 ArrayBuffer，通常无法被 GPU 驱动直接访问。

• 用户代理可能有不同进程分别负责内容运行和与 GPU 驱动的通信。在这种情况下，会使用进程间共享内存来传递数据。

• 独立显卡有自己的高带宽内存，而集成显卡通常与系统共享内存。

大多数物理资源分配在适合 GPU 计算或渲染的内存类型中。当用户需要向 GPU 提供新数据时，数据可能首先需要跨越进程边界，抵达与 GPU 驱动通信的用户代理部分。随后可能需要使数据对驱动可见，有时这需要拷贝到驱动分配的中转（staging）内存。最后，数据还可能需要传输到独立 GPU 内存中，并在内部转换为最适合 GPU 运算的布局。

所有这些转换都由用户代理的 WebGPU 实现负责完成。

注：上述示例描述了最坏情况，实际实现中可能无需跨越进程边界，或者能直接向用户暴露由驱动管理的内存（例如通过 ArrayBuffer），从而避免数据拷贝。

3.4.3. 资源用法

物理资源可以被GPU 命令以内部用法使用：

输入（input）

为 draw 或 dispatch 调用提供输入数据的缓冲区。会保留内容。由缓冲区 INDEX、VERTEX 或 INDIRECT 允许。

常量（constant）

从着色器视角为常量的资源绑定。会保留内容。由缓冲区 UNIFORM 或纹理 TEXTURE_BINDING 允许。

存储（storage）

读/写存储资源绑定。由缓冲区 STORAGE 或纹理 STORAGE_BINDING 允许。

存储只读（storage-read）

只读存储资源绑定。会保留内容。由缓冲区 STORAGE 或纹理 STORAGE_BINDING 允许。

附件（attachment）

在渲染通道中作为读/写输出附件或仅写解决目标的纹理。由纹理 RENDER_ATTACHMENT 允许。

附件只读（attachment-read）

在渲染通道中作为只读附件的纹理。会保留内容。由纹理 RENDER_ATTACHMENT 允许。

子资源（subresource）指整个缓冲区或纹理子资源。

强制要求用法仅可组合为兼容用法列表，使得 API 能够限制内存操作中的数据竞争出现时机。该属性使基于 WebGPU 的应用更容易无修改地在不同平台上运行。

3.4.4. 同步机制

用法范围（usage scope）是一个从有序映射，其键为子资源，值为 列表<内部用法>。每个用法范围覆盖一组可能并发执行的操作，因此在该范围内对子资源的使用只能是兼容用法列表。

用法范围在编码期间被构建和校验：

• 在 dispatchWorkgroups() 中

• 在 dispatchWorkgroupsIndirect() 中

• 在 GPURenderPassEncoder.end() 时

• 在 GPURenderBundleEncoder.finish() 时

用法范围如下：

• 在计算通道中，每个 dispatch 命令（dispatchWorkgroups() 或 dispatchWorkgroupsIndirect()）即为一个用法范围。

  若某子资源在当前 dispatch 调用中可能被访问，则视为在该用法范围内被使用，包括：

  • 当前 GPUComputePipeline 的 [[layout]] 所用绑定组（bind group）槽引用的全部子资源

  • dispatch 调用直接使用的缓冲区（如间接缓冲区）

  注： 诸如 setBindGroup() 等状态设定命令本身不会直接将绑定资源计入用法范围，它们只改变 dispatch 命令检查的状态。

• 一次渲染通道（render pass）即为一个用法范围。

  若某子资源在任何命令中被引用（包括状态设定命令，与计算通道不同），则视为在该用法范围内被使用，包括：

  • 通过 setVertexBuffer() 设置的缓冲区

  • 通过 setIndexBuffer() 设置的缓冲区

  • 通过 setBindGroup() 设置的绑定组引用的所有子资源

  • draw 调用直接使用的缓冲区（如间接缓冲区）

注：拷贝命令为独立操作，不使用用法范围进行校验，其自身实现了防止自竞争的校验。

3.5. 核心内部对象

3.5.1. 适配器（Adapters）

适配器（adapter）标识系统上的 WebGPU 实现：既包括底层平台上的计算/渲染功能实例，也包括浏览器在该功能之上实现 WebGPU 的实例。

适配器通过 GPUAdapter 暴露。

适配器并不唯一代表底层实现：多次调用 requestAdapter() 每次都会返回不同的适配器对象。

每个 适配器对象只能用于创建一个 设备（device）：一旦成功调用 requestDevice()，该适配器的 [[state]] 变为 "consumed"。此外，适配器对象可能在任何时刻过期（expire）。

注： 这样保证应用在创建设备时能使用最新的系统状态来选择适配器。也让多种场景（如首次初始化、因适配器移除重初始化、因 GPUDevice.destroy() 测试重初始化等）行为保持一致，提高健壮性。

若适配器以显著性能换取更广兼容性、更可预测行为或更好的隐私，则可视为回退适配器（fallback adapter）。不是每个系统都必须提供回退适配器。

适配器具有如下不可变属性：

[[features]]，类型为 有序集合<GPUFeatureName>，只读

可用于在此适配器上创建设备的特性。

[[limits]]，类型为支持的限制，只读

可用于在此适配器上创建设备的最佳限制。每个限制值必须与支持的限制中该项的默认值相同或更好（better）。

[[fallback]]，类型为 boolean，只读

为 true 时，表示该适配器是回退适配器。

[[xrCompatible]]，类型为 boolean

为 true 时，表示该适配器请求了与 WebXR 会话 兼容。

适配器具有如下设备时间线属性：

[[state]]，初始值为 "valid"

"valid"

适配器可用于创建设备。

"consumed"

适配器已被用于创建设备，不能再次使用。

"expired"

适配器因其他原因已过期。

3.5.2. 设备（Devices）

设备（device）是适配器的逻辑实例，通过它可以创建内部对象。

设备通过 GPUDevice 暴露。

一个设备独占其上创建的所有内部对象：当该设备变为无效（丢失或 销毁时），它本身和所有直接（如 createTexture()）或间接（如 createView()）创建的对象都会隐式变为不可用。

设备具有如下不可变属性：

[[adapter]]，类型为 适配器，只读

创建该设备的适配器。

[[features]]，类型为 有序集合<GPUFeatureName>，只读

可在该设备上使用的特性，在创建时确定。即使底层适配器支持更多特性，也不能使用额外特性。

[[limits]]，类型为支持的限制，只读

可在该设备上使用的限制，在创建时确定。即使底层适配器支持更高限制，也不能使用更高值（better）。

设备具有如下内容时间线属性：

[[content device]]，类型为 GPUDevice，只读

该设备关联的内容时间线 GPUDevice 接口实例。

每当用户代理需要撤销设备访问权限时，会在该设备的设备时间线上调用 丢失设备(device, "unknown")，该操作可能优先于当前队列中的其他操作。

如果某操作失败且副作用可能导致设备上的对象状态可见变化或内部实现/驱动状态损坏，应当丢失该设备以防止这些变化被观察到。

注： 非应用主动发起的设备丢失（通过 destroy()）时，用户代理应无条件向开发者发出警告，即使 lost promise 已被处理。此类场景应极其罕见，并且该信号对开发者至关重要，因为大多数 WebGPU API 会尽量表现为“一切正常”以避免中断运行时流程：不会抛出校验错误，大多数 promise 正常 resolve 等。

3.6. 可选功能

WebGPU 适配器和设备具备功能，这些功能描述了WebGPU在不同实现之间的差异， 通常是由于硬件或系统软件的限制。 一项功能可以是特性或限制。

用户代理不得透露超过32个可区分的配置或分组。

适配器的功能必须符合§ 4.2.1 适配器功能保证。

仅支持的功能可以在requestDevice()中请求； 请求不支持的功能会导致失败。

设备的功能在"一个新的设备"中确定， 通过从适配器的默认值（无特性和默认的支持的限制）开始， 并根据在requestDevice()中请求的功能添加功能。 这些功能无论适配器的功能如何均会被强制执行。

有关隐私方面的考虑，请参阅§ 2.2.1 机器特定的功能和限制。

3.6.1. 特性

特性是一组可选的 WebGPU 功能，并非所有实现都支持这些功能，通常是由于硬件或系统软件的限制所致。

所有特性都是可选的，但适配器会对其可用性做出一定保证 （参见§ 4.2.1 适配器功能保证）。

设备仅支持在创建时确定的那组特性（参见§ 3.6 可选功能）。 API 调用将根据这些特性（而非适配器的特性）进行校验：

• 以新方式使用已有的 API 接口通常会导致校验错误。

• 有几种类型的可选 API 接口：

  • 使用新方法或枚举值时总是抛出 TypeError 异常。

  • 使用带有（正确类型）非默认值的新字典成员通常会导致校验错误。

  • 使用新的 WGSL enable 指令时，总是会在 createShaderModule() 的过程中产生校验错误。

每个特性所启用的功能描述可参见特性索引。

注意： 启用特性未必是理想选择，可能会影响性能。 因此，为了提升不同设备和实现间的可移植性，应用程序通常只应请求实际需要的特性。

3.6.2. 限制

每个限制都是对设备上 WebGPU 使用的数值限制。

注意： 设置“更好”的限制未必是理想选择，因为这样可能会对性能产生影响。 因此，为了提升不同设备和实现之间的可移植性，应用程序通常只有在确实需要时才请求比默认值更好的限制。

每个限制都有一个默认值。

适配器始终保证支持默认值或更好的 （参见§ 4.2.1 适配器功能保证）。

设备仅支持在创建时确定的那组限制（参见§ 3.6 可选功能）。 API 调用根据这些限制进行校验（而非适配器的限制）， 不允许“更好”或更差。

对于任何给定的限制，一些值是更好的。 更好的限制值始终放宽校验，从而使更多程序变得有效。 对于每个限制类别，“更好”的定义如下。

不同的限制具有不同的限制类别：

最大值

限制在传递给 API 的某些值上强制设置一个最大值。

更高的值是更好的。

仅能设置为 ≥ 默认值 的值。 较低的值会被限制为默认值。

对齐

限制在传递给 API 的某些值上强制设置一个最小对齐；即该值必须是限制的倍数。

较低的值是更好的。

仅能设置为 ≤ 默认值 的2的幂次。 非2的幂次值是无效的。 更高的2的幂次值会被限制为默认值。

支持的限制 对象具有 WebGPU 定义的每个限制的值：

3.6.2.1. GPUSupportedLimits

GPUSupportedLimits 用于暴露适配器或设备的支持的限制。 参见 GPUAdapter.limits 和 GPUDevice.limits。

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

3.6.2.2. GPUSupportedFeatures

GPUSupportedFeatures 是一个 类似集合（setlike） 接口。它的 集合条目 是适配器或设备支持的 GPUFeatureName 值。 它只能包含 GPUFeatureName 枚举中的字符串。

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

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

3.6.2.3. WGSLLanguageFeatures

WGSLLanguageFeatures 是 navigator.gpu.wgslLanguageFeatures 的 类似集合（setlike） 接口。 它的 集合条目 是该实现支持的 WGSL 语言扩展 的字符串名称（不论适配器或设备）。

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

3.6.2.4. GPUAdapterInfo

GPUAdapterInfo 用于暴露关于适配器的各种标识信息。

GPUAdapterInfo 的成员不保证有任何特定值；如果没有提供值，该属性将返回空字符串 ""。是否揭示这些值由用户代理自行决定，并且某些设备上可能所有值都为空。因此，应用必须能够处理任何可能的 GPUAdapterInfo 值，包括这些值缺失的情况。

适配器的 GPUAdapterInfo 可通过 GPUAdapter.info 和 GPUDevice.adapterInfo 获取。 这些信息是不可变的：对于某个适配器，每次访问同一个 GPUAdapterInfo 属性都会返回相同的值。

注意: 虽然 GPUAdapterInfo 属性一旦访问就不可变， 但实现可以在首次访问前延后决定每个属性的内容。

注意: 即便其他 GPUAdapter 实例代表同一物理适配器， 它们在 GPUAdapterInfo 中揭示的值也可能不同。 但除非有特殊事件提升了页面可访问的标识信息（本规范未定义此类事件），否则它们应当揭示相同的值。

关于隐私考虑，请参见 § 2.2.6 适配器标识符。

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

GPUAdapterInfo 拥有如下属性：

vendor， 类型为 DOMString，只读

适配器的厂商名称（如有）。否则为空字符串。

architecture， 类型为 DOMString，只读

适配器所属 GPU 家族或类别的名称（如有）。否则为空字符串。

device， 类型为 DOMString，只读

适配器的厂商自定义标识符（如有）。否则为空字符串。

注意: 这是代表适配器类型的值。例如，可能是 PCI 设备ID。它不会像序列号一样唯一标识某块硬件。

description， 类型为 DOMString，只读

驱动报告的关于适配器的人类可读字符串描述（如有）。否则为空字符串。

注意: description 没有采用任何格式化，不建议尝试解析此值。根据 GPUAdapterInfo 改变行为的应用（如为已知驱动问题应用修正），应尽量依赖其他字段。

subgroupMinSize， 类型为 unsigned long，只读

如果支持 "subgroups" 特性，则为适配器支持的最小 子组大小。

subgroupMaxSize， 类型为 unsigned long，只读

如果支持 "subgroups" 特性，则为适配器支持的最大 子组大小。

isFallbackAdapter， 类型为 boolean，只读

适配器是否为回退适配器。

3.7. 扩展文档

“扩展文档”是描述新功能的附加文档，这些功能是非规范性的，不属于 WebGPU/WGSL 规范的一部分。 它们描述了在这些规范基础上构建的功能，通常包含一个或多个新的 API 特性标志和/或 WGSL enable 指令，或与其他草案 Web 规范的交互。

WebGPU 实现不得暴露扩展功能；这样做属于规范违规。 新功能只有在被集成到 WebGPU 规范（本文档）和/或 WGSL 规范后，才成为 WebGPU 标准的一部分。

3.8. 源限制（Origin Restrictions）

WebGPU 允许访问存储在图片、视频和画布中的图像数据。 出于安全原因，对跨域媒体的使用施加了限制，因为着色器可以被用来间接推测已上传到 GPU 的纹理内容。

WebGPU 不允许上传 不是 origin-clean 的图片源。

这也意味着，使用 WebGPU 渲染的 canvas 的 origin-clean 标志永远不会被置为 false。

关于为图片和视频元素发起 CORS 请求的更多信息，请参考：

• HTML § 2.5.4 CORS settings attributes

• HTML § 4.8.3 The img element img

• HTML § 4.8.11 Media elements HTMLMediaElement

3.9. 任务源（Task Sources）

3.9.1. WebGPU 任务源

WebGPU 定义了一个新的 任务源，称为 WebGPU 任务源。 它用于 uncapturederror 事件和 GPUDevice.lost。

3.9.2. 自动过期任务源

WebGPU 定义了一个新的 任务源，称为 自动过期任务源。 它用于自动、定时地销毁某些对象：

• 由 getCurrentTexture() 返回的 GPUTexture

• 由 HTMLVideoElement 创建的 GPUExternalTexture

来自 自动过期任务源 的任务应当以高优先级处理；尤其是排入队列后，应当在用户自定义（JavaScript）任务之前执行。

3.10. 色彩空间与编码

WebGPU 不提供色彩管理。WebGPU 内的所有值（如纹理元素）都是原始数值，不是经过色彩管理的色值。

WebGPU 确实与色彩管理的输出（通过 GPUCanvasConfiguration）和输入（通过 copyExternalImageToTexture() 及 importExternalTexture()）对接。因此，必须在 WebGPU 数值和外部色值之间进行色彩转换。每个接口点都会本地定义一种编码（色彩空间、传递函数和 alpha 预乘），用于解释 WebGPU 的数值。

WebGPU 允许 PredefinedColorSpace 枚举中的所有色彩空间。注意，每个色彩空间都定义了扩展范围（详见 CSS 相关定义），可以表示其空间外的颜色值（包括色度和明度）。

超出色域的预乘 RGBA 值指 R/G/B 其中任意一个通道的值大于 alpha 通道的值。例如，预乘 sRGB RGBA 值 [1.0, 0, 0, 0.5] 表示原始（未预乘）颜色 [2, 0, 0] 且 alpha 为 50%，在 CSS 中可写作 rgb(srgb 2 0 0 / 50%)。和所有 sRGB 色域外的颜色一样，这在扩展色彩空间中是有定义的点（alpha 为 0 时除外，此时没有颜色）。但若此类值输出到可见画布，结果未定义（见 GPUCanvasAlphaMode "premultiplied"）。

3.10.1. 色彩空间转换

颜色在空间间转换时，需根据上述定义将其在一个空间中的表示转换为另一个空间中的表示。

如果源值少于4个 RGBA 通道，则缺失的绿/蓝/alpha 通道分别设为0, 0, 1，然后再做色彩空间/编码和 alpha 预乘转换。转换后，如果目标需要的通道数少于4，则忽略多余通道。

注意: 灰度图像通常在其色彩空间下表现为 RGB 值 (V, V, V) 或 RGBA 值 (V, V, V, A)。

颜色在转换时不会被有损截断：若源色值本就在目标色彩空间的色域外，转换后会产生超出[0, 1]范围的值。例如，sRGB 目标下，如果源为 rgba16float，色彩空间更广（如 Display-P3），或为预乘且包含超出色域的预乘值，都可能出现上述情况。

同样，如果源值有高位深（如 16 位/分量 PNG）或扩展范围（如 float16 存储的 canvas），这些颜色会在转换过程中保留，且中间计算的精度不少于源。

3.10.2. 色彩空间转换省略

若源与目标的色彩空间/编码一致，则无需转换。通常，若某一步是恒等函数（无操作），实现应当出于性能考虑省略该步骤。

为获得最佳性能，应用应当设置色彩空间和编码选项，以最小化整个流程中所需的转换次数。 对于各种 GPUCopyExternalImageSourceInfo 图像源：

• ImageBitmap：

  • 预乘由 premultiplyAlpha 控制。

  • 色彩空间由 colorSpaceConversion 控制。

• 2d 画布：

  • 始终为预乘。

  • 色彩空间由 colorSpace 创建上下文时的属性控制。

• WebGL 画布：

  • 预乘由 WebGLContextAttributes 中的 premultipliedAlpha 选项控制。

  • 色彩空间由 WebGLRenderingContextBase 的 drawingBufferColorSpace 状态控制。

注意: 在依赖这些特性前，请检查浏览器的实现支持。

3.11. JavaScript 到 WGSL 的数值转换

WebGPU API 的多个部分（可覆盖管线 constants 和渲染通道清除值）会接收来自 WebIDL（double 或 float）的数值，并将其转换为 WGSL 值（bool、i32、u32、f32、f16）。

4. 初始化

4.1. navigator.gpu

在 Window 和 WorkerGlobalScope 上下文中，GPU 对象通过 Navigator 和 WorkerNavigator 接口暴露，访问方式为 navigator.gpu：

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

NavigatorGPU 具有以下属性：

gpu，类型为 GPU，只读

一个全局单例，提供诸如 requestAdapter() 的顶级入口点。

4.2. GPU

GPU 是 WebGPU 的入口点。

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

GPU 具有以下方法：

requestAdapter(options)

从用户代理请求一个 adapter。用户代理选择是否返回适配器，并根据提供的选项进行选择。

调用对象： GPU this.

参数：

参数表：GPU.requestAdapter(options) 方法。

参数	类型	可空	可选	描述
options	GPURequestAdapterOptions	✘	✔	用于选择适配器的条件。

返回： Promise<GPUAdapter?>

内容时序步骤：

1. 令 contentTimeline 为当前 内容时序。

2. 令 promise 为 一个新的 promise。

3. 在 this 的 设备时序上执行 初始化步骤。

4. 返回 promise。

设备时序 初始化步骤：

1. 以下步骤的所有要求必须满足。

   1. options.featureLevel必须为一个特性级别字符串。

   如果满足要求且用户代理选择返回一个适配器：

   1. 设置 adapter 为根据 § 4.2.2 适配器选择 中的规则和 options 的条件选择的 adapter，并遵循 § 4.2.1 适配器能力保证。根据定义初始化适配器的属性：

      1. 根据适配器的支持能力设置 adapter.[[limits]] 和 adapter.[[features]]。adapter.[[features]] 必须包含 "core-features-and-limits"。

      2. 如果 adapter 满足回退适配器的条件，则将 adapter.[[fallback]] 设置为 true。否则，设置为 false。

      3. 将 adapter.[[xrCompatible]] 设置为 options.xrCompatible。

   否则：

   1. 令 adapter 为 null。

2. 在 contentTimeline 上执行后续步骤。

内容时序步骤：

1. 如果 adapter 不为 null：

   1. 解析（Resolve） promise，返回一个封装了 adapter 的新 GPUAdapter。

2. 否则，解析（Resolve） promise，返回 null。

getPreferredCanvasFormat()

返回在本系统上显示 8 位深度、标准动态范围内容的最佳 GPUTextureFormat。只能返回 "rgba8unorm" 或 "bgra8unorm"。

返回值可作为 format 传递给 configure() 方法，以确保相关 GPUCanvasContext 能高效显示其内容。

注意: 未显示到屏幕上的 canvas 使用此格式可能无益，也可能有益。

调用对象： GPU this。

返回： GPUTextureFormat

内容时序 步骤：

1. 根据本系统 WebGPU canvas 显示的最佳格式，返回 "rgba8unorm" 或 "bgra8unorm"。

GPU 有以下属性：

wgslLanguageFeatures ， 类型为 WGSLLanguageFeatures，只读

支持的 WGSL 语言扩展的名称。 支持的语言扩展会自动启用。

适配器 可能 随时被 过期。 当系统状态发生任何可能影响任何 requestAdapter() 调用结果的变化时，用户代理 应当 使所有 先前返回的 适配器 过期。例如：

• 物理适配器被添加/移除（通过插拔、驱动更新、死机恢复等）

• 系统电源配置发生变化（如笔记本电脑断电、电源设置更改等）

注意： 用户代理可能会选择经常 过期 适配器，即使系统状态没有发生变化（例如在适配器创建后几秒或几分钟）。 这有助于混淆真实的系统状态变化，并让开发者更加意识到，在调用 requestAdapter() 之前，总是需要重新请求适配器再调用 requestDevice()。 如果应用遇到这种情况，标准的设备丢失恢复处理应当能够使其恢复。

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

4.2.1. 适配器能力保证

任何由 GPUAdapter 通过 requestAdapter() 返回的对象都必须提供以下保证：

• 以下至少一项必须为真：

  • 支持 "texture-compression-bc"。

  • 同时支持 "texture-compression-etc2" 和 "texture-compression-astc"。

• 如果支持 "texture-compression-bc-sliced-3d"，则必须支持 "texture-compression-bc"。

• 如果支持 "texture-compression-astc-sliced-3d"，则必须支持 "texture-compression-astc"。

• 所有支持的限制值必须为默认值或更高。

• 所有alignment-class 类型的限制值必须为2的幂。

• maxBindingsPerBindGroup 必须大于等于 (每个着色器阶段的最大绑定数 × 每个管线的最大着色器阶段数)，其中：

  • 每个着色器阶段的最大绑定数为 (maxSampledTexturesPerShaderStage + maxSamplersPerShaderStage + maxStorageBuffersPerShaderStage + maxStorageTexturesPerShaderStage + maxUniformBuffersPerShaderStage).

  • 每个管线的最大着色器阶段数为 2，因为 GPURenderPipeline 同时支持顶点和片元着色器。

  注意： maxBindingsPerBindGroup 并不反映一个基本限制； 实现应通过提高该值来满足这一要求，而不是降低其他限制。

• maxBindGroups 必须小于等于 maxBindGroupsPlusVertexBuffers。

• maxVertexBuffers 必须小于等于 maxBindGroupsPlusVertexBuffers。

• minUniformBufferOffsetAlignment 和 minStorageBufferOffsetAlignment 都必须大于等于 32 字节。

  注意： 32 字节是 vec4<f64> 的对齐值。参见 WebGPU 着色语言 § 14.4.1 对齐与大小。

• maxUniformBufferBindingSize 必须小于等于 maxBufferSize。

• maxStorageBufferBindingSize 必须小于等于 maxBufferSize。

• maxStorageBufferBindingSize 必须为4字节的整数倍。

• maxVertexBufferArrayStride 必须为4字节的整数倍。

• maxComputeWorkgroupSizeX 必须小于等于 maxComputeInvocationsPerWorkgroup。

• maxComputeWorkgroupSizeY 必须小于等于 maxComputeInvocationsPerWorkgroup。

• maxComputeWorkgroupSizeZ 必须小于等于 maxComputeInvocationsPerWorkgroup。

• maxComputeInvocationsPerWorkgroup 必须小于等于 maxComputeWorkgroupSizeX × maxComputeWorkgroupSizeY × maxComputeWorkgroupSizeZ。

4.2.2. 适配器选择

GPURequestAdapterOptions 为用户代理提供指示，表明哪些配置适合应用程序。

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

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

GPURequestAdapterOptions 拥有如下成员：

featureLevel， 类型为 DOMString，默认值为 "core"

适配器请求的“功能级别”。

允许的 功能级别字符串值为：

"core"

无影响。

"compatibility"

无影响。

注意： 该值为将来引入额外验证限制时保留。 目前应用不应使用此值。

powerPreference， 类型为 GPUPowerPreference

可选，为用户代理提供一个提示，指示应从系统可用适配器中选择哪种类别的 适配器。

该提示的值可能影响选择哪个适配器，但不得影响是否返回适配器。

注意： 该提示的主要用途是在多GPU系统上影响所用的GPU。 例如，某些笔记本电脑有低功耗集成GPU和高性能独立GPU。该提示也可能影响所选GPU的电源配置，以匹配请求的电源偏好。

注意： 根据具体硬件配置（如电池状态、外接显示器或可卸载GPU），即使设置了相同的电源偏好，用户代理可能依然选择不同的 适配器。 通常，在相同硬件配置和状态下，且 powerPreference 一致，用户代理通常会选择同一个适配器。

必须为以下值之一：

undefined（或未设置）

不给用户代理提供任何提示。

"low-power"

表示请求优先考虑节能而非性能。

注意： 如果内容渲染需求较低（如每秒只渲染一帧，仅绘制相对简单的几何体和着色器，或只用小型HTML canvas元素），一般应使用该选项。 如果内容允许，鼓励开发者使用此值，因为这可能大幅提升便携设备的电池寿命。

"high-performance"

表示请求优先考虑性能而非能耗。

注意： 选择此值时，开发者应注意，对于在所选适配器上创建的 设备，用户代理更可能强制设备丢失，以便切换到低功耗适配器节能。 只有在确有必要时，开发者才应指定此值，因为它可能会大幅降低便携设备的电池寿命。

forceFallbackAdapter， 类型为 boolean，默认值为 false

若设为 true，表示只能返回 回退适配器。如果用户代理不支持 回退适配器，则 requestAdapter() 会返回 null。

注意： 即使 forceFallbackAdapter 设为 false，requestAdapter() 仍可能返回 回退适配器（当没有其他合适的 适配器可用，或用户代理选择返回回退适配器时）。 希望避免应用在 回退适配器上运行的开发者应在请求 GPUDevice 前检查 info.isFallbackAdapter 属性。

xrCompatible， 类型为 boolean，默认值为 false

若设为 true，表示必须返回用于 WebXR会话渲染的最佳 适配器。如果用户代理或系统不支持 WebXR会话，则适配器选择可忽略此值。

注意： 如果在请求适配器时 xrCompatible 未设为 true，则从该适配器创建的 GPUDevice 无法用于 WebXR会话 渲染。

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

4.3. GPUAdapter

GPUAdapter 封装了一个 适配器， 并描述其能力（特性 和 限制）。

要获取一个 GPUAdapter， 请使用 requestAdapter()。

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

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

GPUAdapter 拥有以下不可变属性

features， 类型为 GPUSupportedFeatures，只读

在 this.[[adapter]].[[features]] 中的值集合。

limits， 类型为 GPUSupportedLimits，只读

在 this.[[adapter]].[[limits]] 中的限制。

info， 类型为 GPUAdapterInfo，只读

关于该 GPUAdapter 所对应物理适配器的信息。

对于同一个 GPUAdapter， 暴露的 GPUAdapterInfo 值在时间上是恒定的。

每次返回的都是同一个对象。首次创建该对象的方法如下：

调用对象: GPUAdapter this.

返回: GPUAdapterInfo

内容时间线 步骤：

1. 为 this.[[adapter]] 返回一个新的适配器信息。

[[adapter]]，类型为 adapter，只读

该 GPUAdapter 所引用的 适配器。

GPUAdapter 拥有以下方法：

requestDevice(descriptor)

从该 适配器 请求一个 设备。

这是一次性操作：如果成功返回了设备，则适配器变为 "consumed"。

调用对象: GPUAdapter this.

参数:

方法 GPUAdapter.requestDevice(descriptor) 的参数。

参数	类型	可为 null	可选	描述
descriptor	GPUDeviceDescriptor	✘	✔	请求的 GPUDevice 的描述信息。

返回: Promise<GPUDevice>

内容时间线 步骤：

1. 令 contentTimeline 为当前 内容时间线。

2. 令 promise 为新的 promise。

3. 令 adapter 为 this.[[adapter]]。

4. 对 this 的 设备时间线 执行 初始化步骤。

5. 返回 promise。

设备时间线 初始化步骤：

1. 如果下列任何要求未满足：

   • descriptor.requiredFeatures 中的值集合 必须是 adapter.[[features]] 的子集。

   则在 contentTimeline 上执行下列步骤并返回：

   内容时间线 步骤：

   1. 拒绝 promise，并给出 TypeError。

   注意： 这与浏览器完全不识别某特性的情况下抛出的错误相同（在其 GPUFeatureName 定义里）。 这使得浏览器不支持某特性和某适配器不支持某特性时的行为一致。

2. 以下步骤中的所有要求 必须 被满足。

   1. adapter.[[state]] 不得为 "consumed"。

   2. 对于 descriptor.requiredLimits 中每个 key、value 对（且 value 不为 undefined）：

      1. key 必须 是 支持的限制的成员名。

      2. value 不得比 adapter.[[limits]][key] 更高。

      3. 若 key 的 类别为 对齐， value 必须 是小于 2³² 的 2 的幂。

      注意： 即使 value 为 undefined，当 key 未被识别时，用户代理应考虑给出开发者可见的警告。

   若有未满足项，则在 contentTimeline 上执行下列步骤并返回：

   内容时间线 步骤：

   1. 拒绝 promise，并给出 OperationError。

3. 如果 adapter.[[state]] 为 "expired" 或用户代理无法完成该请求：

   1. 令 device 为新的 设备。

   2. 丢失该设备(device, "unknown")。

   3. 断言 adapter.[[state]] 为 "expired"。

      注意： 当发生这种情况时，用户代理应考虑在大多数或所有情况下向开发者发出警告。应用应从 requestAdapter() 开始重新初始化逻辑。

   否则：

   1. 令 device 为带有 descriptor 描述能力的新设备。

   2. 使 adapter 过期。

4. 在 contentTimeline 上执行后续步骤。

内容时间线 步骤：

1. 令 gpuDevice 为新的 GPUDevice 实例。

2. 设置 gpuDevice.[[device]] 为 device。

3. 设置 device.[[content device]] 为 gpuDevice。

4. 设置 gpuDevice.label 为 descriptor.label。

5. 解决 promise，返回 gpuDevice。

   注意： 如果由于适配器无法完成请求而设备已丢失，则 device.lost 在 promise 解决前已经解决。

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

4.3.1. GPUDeviceDescriptor

GPUDeviceDescriptor 描述一个设备请求。

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

GPUDeviceDescriptor 拥有以下成员：

requiredFeatures， 类型为 sequence<GPUFeatureName>，默认值为 []

指定设备请求所需的特性。 如果适配器无法提供这些特性，请求会失败。

API调用的校验只允许恰好指定的特性，不多也不少。

requiredLimits， 类型为 record<DOMString, (GPUSize64 or undefined)>，默认值为 {}

指定设备请求所需的限制。 如果适配器无法提供这些限制，请求会失败。

每个非 undefined 值的 key 必须是支持的限制的成员名。

在最终设备上的 API 调用会根据该设备的实际限制（不是适配器的限制；见 § 3.6.2 限制）进行校验。

defaultQueue， 类型为 GPUQueueDescriptor，默认值为 {}

默认 GPUQueue 的描述符。

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

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

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

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

if (gpuAdapter.limits.maxColorAttachmentBytesPerSample < 64) {
    // 当所需限制不被支持时，采取措施，要么降级代码路径，要么提示用户其设备不满足最低要求。
}

// 请求更高的每样本最大颜色附件字节数限制。
const gpuDevice = await gpuAdapter.requestDevice({
    requiredLimits: { maxColorAttachmentBytesPerSample: 64 },
});

4.3.1.1. GPUFeatureName

每个 GPUFeatureName 都标识一组功能，如果可用，可使 WebGPU 支持本来无效的额外用法。

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

4.4. GPUDevice

GPUDevice 封装了一个设备并暴露该设备的功能。

GPUDevice 是创建WebGPU 接口的顶层接口。

要获取一个 GPUDevice，请使用 requestDevice()。

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

    [SameObject] readonly attribute GPUQueue queue;

    undefined destroy();

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

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

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

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

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

GPUDevice 拥有以下 不可变属性：

features， 类型为 GPUSupportedFeatures，只读

包含设备支持的 GPUFeatureName 的集合（[[device]].[[features]]）。

limits， 类型为 GPUSupportedLimits，只读

该设备支持的限制（[[device]].[[limits]]）。

queue， 类型为 GPUQueue，只读

此设备的主 GPUQueue。

adapterInfo， 类型为 GPUAdapterInfo，只读

创建此 设备的物理适配器的信息，该 GPUDevice 所指向的适配器。

对于同一个 GPUDevice，暴露的 GPUAdapterInfo 值在时间上是恒定的。

每次返回的都是同一个对象。首次创建该对象的方法如下：

调用对象: GPUDevice this。

返回: GPUAdapterInfo

内容时间线 步骤：

1. 为 this.[[device]].[[adapter]] 返回一个新的适配器信息。

[[device]] 是 GPUDevice 所引用的 设备。

GPUDevice 拥有以下方法：

destroy()

销毁该 设备，阻止进一步的操作。所有未完成的异步操作将失败。

注意： 多次销毁同一个设备是合法的。

调用对象: GPUDevice this。

内容时间线 步骤：

1. 对该设备的所有 GPUBuffer 调用 unmap()。

2. 在 this 的 设备时间线 上执行后续步骤。

1. 丢失该设备(this.[[device]], "destroyed")。

注意： 由于无法在该设备上排队新的操作，实现可以立即中止所有未完成的异步操作并释放资源，包括刚刚解除映射的内存。

4.5. 示例

let gpuDevice = null;

async function initializeWebGPU() {
    // 检查用户代理是否支持 WebGPU。
    if (!('gpu' in navigator)) {
        console.error("用户代理不支持 WebGPU。");
        return false;
    }

    // 请求适配器。
    const gpuAdapter = await navigator.gpu.requestAdapter();

    // 如果找不到合适的适配器，requestAdapter 可能会 resolve 为 null。
    if (!gpuAdapter) {
        console.error('未找到 WebGPU 适配器。');
        return false;
    }

    // 请求设备。
    // 注意：如果给可选字典传递了无效参数，promise 会 reject。为避免 promise 被拒绝，
    // 总是应在调用 requestDevice() 前检查特性和限制是否被适配器支持。
    gpuDevice = await gpuAdapter.requestDevice();

    // requestDevice 永远不会返回 null，但如果出于某种原因无法满足有效的设备请求，
    // 它可能会返回一个已经丢失的设备。
    // 此外，设备在创建后可能随时丢失（如：浏览器资源管理、驱动更新），
    // 因此应始终优雅地处理设备丢失。
    gpuDevice.lost.then((info) => {
        console.error(`WebGPU 设备已丢失: ${info.message}`);

        gpuDevice = null;

        // 多数设备丢失的原因是临时性的，因此应用应在丢失后尝试获取新设备，
        // 除非丢失原因是应用主动销毁了设备。注意，所有用旧设备创建的 WebGPU 资源（缓冲区、纹理等）
        // 都需要用新设备重新创建。
        if (info.reason != 'destroyed') {
            initializeWebGPU();
        }
    });

    onWebGPUInitialized();

    return true;
}

function onWebGPUInitialized() {
    // 在这里创建 WebGPU 资源……
}

initializeWebGPU();

5. 缓冲区

5.1. GPUBuffer

GPUBuffer 表示一块可用于 GPU 操作的内存块。 数据以线性布局存储，这意味着分配的每个字节都可以通过其相对于 GPUBuffer 起始位置的偏移来寻址， 但具体操作可能有对齐限制。某些 GPUBuffers 可以被映射，使这块内存可以通过一个称为映射的 ArrayBuffer 访问。

GPUBuffer 通过 createBuffer() 创建。 缓冲区可以 mappedAtCreation。

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

    readonly attribute GPUBufferMapState mapState;

    Promise<undefined> mapAsync(GPUMapModeFlags mode, optional GPUSize64 offset = 0, optional GPUSize64 size);
    ArrayBuffer getMappedRange(optional GPUSize64 offset = 0, optional GPUSize64 size);
    undefined unmap();

    undefined destroy();
};
GPUBuffer includes GPUObjectBase;

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

GPUBuffer 拥有以下 不可变属性：

size， 类型为 GPUSize64Out，只读

GPUBuffer 分配的字节长度。

usage， 类型为 GPUFlagsConstant，只读

此 GPUBuffer 的允许用法。

GPUBuffer 拥有以下 内容时间线属性：

mapState， 类型为 GPUBufferMapState，只读

缓冲区的当前 GPUBufferMapState：

"unmapped"

缓冲区未被 this.getMappedRange() 映射使用。

"pending"

缓冲区已请求映射，但尚未完成。映射可能成功，也可能在 mapAsync() 校验时失败。

"mapped"

缓冲区已映射，可以通过 this.getMappedRange() 使用。

getter 步骤如下：

内容时间线 步骤：

1. 如果 this.[[mapping]] 不为 null，返回 "mapped"。

2. 如果 this.[[pending_map]] 不为 null，返回 "pending"。

3. 返回 "unmapped"。

[[pending_map]]，类型为 Promise<void> 或 null，初始为 null

当前挂起的 mapAsync() 调用返回的 Promise。

永远不会有多个挂起的映射，因为如果已有请求在进行中，mapAsync() 会立即拒绝。

[[mapping]]，类型为 活动缓冲区映射 或 null，初始为 null

仅当缓冲区当前被 getMappedRange() 映射使用时才设置。否则为 null（即使有 [[pending_map]]）。

活动缓冲区映射 是具有以下字段的结构：

data，类型为 数据块

本 GPUBuffer 的映射数据。应用通过 ArrayBuffer 视图访问，由 getMappedRange() 返回并存储在 views 中。

mode，类型为 GPUMapModeFlags

映射的 GPUMapModeFlags，由相应 mapAsync() 或 createBuffer() 调用指定。

range，类型为元组 [unsigned long long, unsigned long long]

该 GPUBuffer 被映射的范围。

views，类型为 list<ArrayBuffer>

通过 getMappedRange() 返回给应用的 ArrayBuffer。这些视图会在 unmap() 被调用时被追踪并分离。

要用 mode mode 和 range range 初始化活动缓冲区映射，执行以下 内容时间线 步骤：

1. 令 size 为 range[1] - range[0]。

2. 令 data 为 ? CreateByteDataBlock(size)。

   注意：

   这可能抛出 RangeError。 为了保证一致和可预测性：

   • 对于 new ArrayBuffer() 在某一时刻能成功的任意 size，此分配 也应 同时成功。

   • 对于 new ArrayBuffer() 确定性 抛出 RangeError 的任意 size，此分配 也应 抛出。

3. 返回具有如下内容的 活动缓冲区映射：

   • data 设为 data。

   • mode 设为 mode。

   • range 设为 range。

   • views 设为 []。

GPUBuffer 拥有以下 设备时间线属性：

[[internal state]]

缓冲区的当前内部状态：

"available"

缓冲区可用于队列操作（除非已失效）。

"unavailable"

缓冲区因已映射而不可用于队列操作。

"destroyed"

缓冲区因被 destroy() 而无法用于任何操作。

5.1.1. GPUBufferDescriptor

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

GPUBufferDescriptor 拥有以下成员：

size， 类型为 GPUSize64

缓冲区的字节大小。

usage， 类型为 GPUBufferUsageFlags

缓冲区允许的用法。

mappedAtCreation， 类型为 boolean，默认值为 false

如果为 true，则缓冲区会以已映射状态创建，允许立即调用 getMappedRange()。 即使 usage 不包含 MAP_READ 或 MAP_WRITE，也可以设置 mappedAtCreation 为 true。 这可用于设置缓冲区的初始数据。

即使最终缓冲区创建失败，也保证看起来映射范围可读写直到其被解除映射。

5.1.2. 缓冲区用法

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

GPUBufferUsage 标志决定了 GPUBuffer 创建后可以如何使用：

MAP_READ

缓冲区可被映射用于读取。（例如：调用 mapAsync() 并传入 GPUMapMode.READ）

只能与 COPY_DST 组合使用。

MAP_WRITE

缓冲区可被映射用于写入。（例如：调用 mapAsync() 并传入 GPUMapMode.WRITE）

只能与 COPY_SRC 组合使用。

COPY_SRC

缓冲区可作为拷贝操作的源。（例如：作为 copyBufferToBuffer() 或 copyBufferToTexture() 调用的 source 参数）

COPY_DST

缓冲区可作为拷贝或写入操作的目标。（例如：作为 copyBufferToBuffer() 或 copyTextureToBuffer() 调用的 destination 参数，或作为 writeBuffer() 的目标。）

INDEX

缓冲区可作为索引缓冲区使用。（例如：传递给 setIndexBuffer()。）

VERTEX

缓冲区可作为顶点缓冲区使用。（例如：传递给 setVertexBuffer()。）

UNIFORM

缓冲区可用作 uniform 缓冲区。（例如：用于 GPUBufferBindingLayout 的绑定组条目，且 buffer.type 为 "uniform"。）

STORAGE

缓冲区可用作 storage 缓冲区。（例如：用于 GPUBufferBindingLayout 的绑定组条目，且 buffer.type 为 "storage" 或 "read-only-storage"。）

INDIRECT

缓冲区可用于存储间接命令参数。（例如：作为 indirectBuffer 参数传递给 drawIndirect() 或 dispatchWorkgroupsIndirect() 调用。）

QUERY_RESOLVE

缓冲区可用于捕获查询结果。（例如：作为 destination 参数传递给 resolveQuerySet()。）

5.1.3. 缓冲区创建

createBuffer(descriptor)

创建一个 GPUBuffer。

调用对象: GPUDevice this。

参数:

GPUDevice.createBuffer(descriptor) 方法的参数。

参数	类型	可为 null	可选	描述
descriptor	GPUBufferDescriptor	✘	✘	要创建的 GPUBuffer 描述信息。

返回: GPUBuffer

内容时间线 步骤：

1. 令 b 为 ! 创建新的 WebGPU 对象(this, GPUBuffer, descriptor)。

2. 设置 b.size 为 descriptor.size。

3. 设置 b.usage 为 descriptor.usage。

4. 如果 descriptor.mappedAtCreation 为 true：

   1. 如果 descriptor.size 不是 4 的倍数，抛出 RangeError。

   2. 设置 b.[[mapping]] 为 ? 初始化活动缓冲区映射，mode 为 WRITE，range 为 [0, descriptor.size]。

5. 在 this 的 设备时间线 上执行 初始化步骤。

6. 返回 b。

设备时间线 初始化步骤：

1. 如有以下任一要求未被满足， 生成校验错误，使 b 失效并返回。

   • this 不能 已失效。

   • descriptor.usage 不能为 0。

   • descriptor.usage 必须是该 this 允许缓冲区用法 的子集。

   • 如果 descriptor.usage 包含 MAP_READ：

     • descriptor.usage 不能包含除 COPY_DST 以外的标志。

   • 如果 descriptor.usage 包含 MAP_WRITE：

     • descriptor.usage 不能包含除 COPY_SRC 以外的标志。

   • 如果 descriptor.size 必须小于等于 this.[[device]].[[limits]].maxBufferSize。

注意： 如果缓冲区创建失败，且 descriptor.mappedAtCreation 为 false， 任何对 mapAsync() 的调用都会被拒绝，因此为支持映射而分配的任何资源都可以被回收。

1. 如果 descriptor.mappedAtCreation 为 true：

   1. 设置 b.[[internal state]] 为 "unavailable"。

   否则：

   1. 设置 b.[[internal state]] 为 "available"。

2. 为 b 创建设备分配，并将每个字节置零。

   如果分配失败且无副作用，生成内存不足错误，使 b 失效并返回。

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

5.1.4. 缓冲区销毁

应用如果不再需要某个 GPUBuffer，可以在垃圾回收前调用 destroy() 主动放弃访问它。 销毁缓冲区还会解除映射，释放为映射分配的内存。

注意： 这样允许用户代理在所有先前提交的与该 GPUBuffer 相关的操作完成后及时回收其 GPU 内存。

GPUBuffer 拥有以下方法：

destroy()

销毁该 GPUBuffer。

注意： 多次销毁同一个缓冲区是合法的。

调用对象: GPUBuffer this。

返回值: undefined

内容时间线 步骤：

1. 调用 this.unmap()。

2. 在 this.[[device]] 的 设备时间线 上执行后续步骤。

设备时间线 步骤：

1. 设置 this.[[internal state]] 为 "destroyed"。

注意： 由于无法继续用该缓冲区排队新操作，实现可以立即释放资源分配，包括刚刚解除映射的内存。

5.2. 缓冲区映射

应用可以请求映射 GPUBuffer，从而通过代表该 GPUBuffer 分配部分的 ArrayBuffer 访问其内容。 映射 GPUBuffer 的请求是通过 mapAsync() 异步进行的，以便用户代理能确保 GPU 在应用访问内容前已完成对该 GPUBuffer 的使用。 被映射的 GPUBuffer 不能被 GPU 使用，必须通过 unmap() 解除映射后才能再次用于 队列时间线的工作提交。

一旦 GPUBuffer 被映射，应用可通过 getMappedRange() 同步访问其内容范围。 返回的 ArrayBuffer 只能被 unmap()（直接或通过 GPUBuffer.destroy() 或 GPUDevice.destroy())分离，不能被转移。 任何其它操作试图这样做都会抛出 TypeError。

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

GPUMapMode 标志决定了调用 mapAsync() 时 GPUBuffer 被如何映射：

READ

只对创建时带有 MAP_READ 用法的缓冲区有效。

映射后，调用 getMappedRange() 将返回包含缓冲区当前值的 ArrayBuffer。对返回的 ArrayBuffer 的更改在 unmap() 后会被丢弃。

WRITE

只对创建时带有 MAP_WRITE 用法的缓冲区有效。

映射后，调用 getMappedRange() 将返回包含缓冲区当前值的 ArrayBuffer。对返回的 ArrayBuffer 的更改会在 unmap() 后写入缓冲区。

注意： 由于 MAP_WRITE 用法只能与 COPY_SRC 组合，写映射永远不会返回 GPU 产生的数据，返回的 ArrayBuffer 只包含初始化为零的数据或网页之前映射写入的数据。

GPUBuffer 拥有以下方法：

mapAsync(mode, offset, size)

映射 GPUBuffer 的指定范围，并在缓冲区内容可以通过 getMappedRange() 访问时 resolve 返回的 Promise。

返回的 Promise 仅表示缓冲区已被映射，不保证其它 内容时间线可见操作完成，特别是不保证其它 Promise（如 onSubmittedWorkDone() 或其它 mapAsync()）已 resolve。

而 Promise 由 onSubmittedWorkDone() 返回则保证在该队列上之前的所有 mapAsync() 已完成。

调用对象: GPUBuffer this。

参数:

GPUBuffer.mapAsync(mode, offset, size) 方法的参数。

参数	类型	可为 null	可选	描述
mode	GPUMapModeFlags	✘	✘	缓冲区应以读或写方式映射。
offset	GPUSize64	✘	✔	要映射的范围起始字节偏移。
size	GPUSize64	✘	✔	要映射的范围字节大小。

返回值: Promise<undefined>

内容时间线步骤：

1. 令 contentTimeline 为当前 内容时间线。

2. 若 this.mapState 不为 "unmapped"：

   1. 在 this.[[device]] 的 设备时间线 上执行 early-reject steps。

   2. 返回 被拒绝的 promise，错误为 OperationError。

3. 令 p 为新的 Promise。

4. 设置 this.[[pending_map]] = p。

5. 在 this.[[device]] 的 设备时间线 上执行 validation steps。

6. 返回 p。

设备时间线 early-reject steps：

1. 生成校验错误。

2. 返回。

设备时间线 validation steps：

1. 如果 size 为 undefined：

   1. 令 rangeSize = max(0, this.size - offset)。

   否则：

   1. 令 rangeSize = size。

2. 如果下述任一条件不满足：

   • this 必须是 有效的。

   1. 设置 deviceLost 为 true。

   2. 在 contentTimeline 上执行 map failure steps。

   3. 返回。

3. 如果下述任一条件不满足：

   • this.[[internal state]] 为 "available"。

   • offset 为 8 的倍数。

   • rangeSize 为 4 的倍数。

   • offset + rangeSize ≤ this.size。

   • mode 仅包含 GPUMapMode 中定义的比特。

   • mode 必须等于 READ 或 WRITE，且只能有一个。

   • 如果 mode 包含 READ，则 this.usage 必须包含 MAP_READ。

   • 如果 mode 包含 WRITE，则 this.usage 必须包含 MAP_WRITE。

   否则：

   1. 设置 deviceLost 为 false。

   2. 在 contentTimeline 上执行 map failure steps。

   3. 生成校验错误。

   4. 返回。

4. 将 this.[[internal state]] 设为 "unavailable"。

   注意： 缓冲区被映射后，在解除映射前其内容不会改变。

5. 当下述任一事件发生（以先发生者为准），或已发生时：

   • 设备时间线 获悉某个未指定的 队列时间线点已完成：

     • 在所有当前排队并使用 this 的操作完成后

     • 且不晚于所有当前排队操作（不论是否使用 this）完成时

   • this.[[device]] 丢失。

   然后在 this.[[device]] 的 设备时间线 上执行后续步骤。

设备时间线 步骤：

1. 若 this.[[device]] 已失效，则 deviceLost 设为 true，否则为 false。

   注意： 设备可能在前后步骤之间丢失。

2. 如果 deviceLost：

   1. 在 contentTimeline 上执行 map failure steps。

   否则：

   1. 令 internalStateAtCompletion = this.[[internal state]]。

      注意： 只有当此时缓冲区因 unmap() 变为 "available" 时，[[pending_map]] ≠ p，后续 mapping 步骤不会成功。

   2. 令 dataForMappedRegion 为 this 从 offset 开始，长度为 rangeSize 字节的内容。

   3. 在 contentTimeline 上执行 map success steps。

内容时间线 map success steps：

1. 若 this.[[pending_map]] ≠ p：

   注意： 映射已被 unmap() 取消。

   1. 断言 p 已被拒绝。

   2. 返回。

2. 断言 p 仍为 pending。

3. 断言 internalStateAtCompletion 为 "unavailable"。

4. 令 mapping = 初始化活动缓冲区映射，mode 为 mode，range 为 [offset, offset + rangeSize]。

   若分配失败：

   1. 设 this.[[pending_map]] = null，并 拒绝 p，错误为 RangeError。

   2. 返回。

5. 将 mapping.data 设为 dataForMappedRegion。

6. 设 this.[[mapping]] = mapping。

7. 设 this.[[pending_map]] = null，并 resolve p。

内容时间线 map failure steps：

1. 如果 this.[[pending_map]] ≠ p：

   注意： 映射已被 unmap() 取消。

   1. 断言 p 已被拒绝。

   2. 返回。

2. 断言 p 仍为 pending。

3. 设 this.[[pending_map]] = null。

4. 如果 deviceLost：

   1. 拒绝 p 并抛出 AbortError。

      注意： 这和用 unmap() 取消 map 时抛出的错误类型一致。

   否则：

   1. 拒绝 p 并抛出 OperationError。

getMappedRange(offset, size)

返回包含指定范围 GPUBuffer 内容的 ArrayBuffer。

调用对象: GPUBuffer this。

参数:

GPUBuffer.getMappedRange(offset, size) 方法的参数。

参数	类型	可为 null	可选	描述
offset	GPUSize64	✘	✔	要返回内容的起始字节偏移。
size	GPUSize64	✘	✔	要返回的 ArrayBuffer 字节长度。

返回值: ArrayBuffer

内容时间线 步骤：

1. 如果 size 未指定：

   1. 令 rangeSize = max(0, this.size - offset)。

   否则，rangeSize = size。

2. 如以下任一条件不满足，则抛出 OperationError 并返回：

   • this.[[mapping]] 不为 null。

   • offset 为 8 的倍数。

   • rangeSize 为 4 的倍数。

   • offset ≥ this.[[mapping]].range[0]。

   • offset + rangeSize ≤ this.[[mapping]].range[1]。

   • [offset, offset + rangeSize) 不与 this.[[mapping]].views 中的其它范围重叠。

   注意： 对 GPUBuffer，即使其为 mappedAtCreation 且 无效，只要 内容时间线 未知其无效，依然可以获取映射范围。

3. 令 data = this.[[mapping]].data。

4. 令 view = 创建 ArrayBuffer，大小为 rangeSize，指针可变地引用 data 从 (offset - [[mapping]].range[0]) 开始的内容。

   注意： 这里不会抛出 RangeError，因为 data 已在 mapAsync() 或 createBuffer() 时分配。

5. 设置 view.[[ArrayBufferDetachKey]] 为 "WebGPUBufferMapping"。

   注意： 这样如果尝试用除 unmap() 外的方法分离该 ArrayBuffer，会抛出 TypeError。

6. 追加 view 到 this.[[mapping]].views。

7. 返回 view。

注意： 若 getMappedRange() 调用未先检查映射状态（如等待 mapAsync() resolve、查询 mapState 为 "mapped" 或等待 onSubmittedWorkDone()），用户代理应考虑发出开发警告。

unmap()

解除 GPUBuffer 的映射范围，使其内容重新可被 GPU 使用。

调用对象: GPUBuffer this。

返回值: undefined

内容时间线 步骤：

1. 如果 this.[[pending_map]] 不为 null：

   1. 拒绝 this.[[pending_map]]，错误为 AbortError。

   2. 设 this.[[pending_map]] = null。

2. 如果 this.[[mapping]] 为 null：

   1. 返回。

3. 对于 this.[[mapping]].views 中的每个 ArrayBuffer ab：

   1. 执行 DetachArrayBuffer(ab, "WebGPUBufferMapping")。

4. 令 bufferUpdate = null。

5. 如果 this.[[mapping]].mode 包含 WRITE：

   1. 设 bufferUpdate = { data: this.[[mapping]].data, offset: this.[[mapping]].range[0] }。

   注意： 如果缓冲区不是以 WRITE 模式映射，解除映射时应用对映射范围 ArrayBuffer 的本地修改会被丢弃，不会影响后续映射内容。

6. 设 this.[[mapping]] = null。

7. 在 this.[[device]] 的 设备时间线 上执行后续步骤。

设备时间线 步骤：

1. 如下条件任一不满足则返回：

   • this 可与 this.[[device]] 安全配合使用。

2. 断言 this.[[internal state]] 为 "unavailable"。

3. 如果 bufferUpdate 不为 null：

   1. 在 this.[[device]].queue 的 队列时间线 上执行：

      队列时间线 步骤：

      1. 用 bufferUpdate.data 更新 this 从 bufferUpdate.offset 开始的内容。

4. 将 this.[[internal state]] 设为 "available"。

6. 纹理与纹理视图

6.1. GPUTexture

纹理（texture） 由 1d、 2d 或 3d 的数据数组组成，每个元素可包含多个值用于表示如颜色等信息。纹理的读写方式取决于创建时使用的 GPUTextureUsage。 例如，纹理可被采样、读写于渲染与计算管线着色器，也可由渲染通道输出写入。纹理在 GPU 内部通常以多维访问优化的布局存储，而非线性存储。

一个 纹理 由一个或多个 纹理子资源（texture subresource） 组成，每个子资源由 mipmap 级别 唯一标识， 对于 2d 纹理，还包括 数组层 和 aspect（分量）。

纹理子资源 是一种 子资源：每个子资源可在单一 用法范围 内有不同 内部用途。

每个 mipmap 级别 的子资源 在每个空间维度上的尺寸大约是上一级资源的一半 （见 mipmap 级别特定逻辑纹理范围）。 0 级子资源的尺寸等于纹理本身的尺寸，更小的级别通常用于存储同一图像的低分辨率版本。 GPUSampler 与 WGSL 提供了选择与插值 细节级别 的能力，可显式或自动进行。

"2d" 纹理可以是 数组层（array layer） 的集合。 每一层的子资源尺寸都相同。非 2d 纹理的所有子资源的数组层索引都为 0。

每个子资源有一个 aspect（分量）。 彩色纹理只有一个分量：color。 深度或模板格式 的纹理可能有多个分量： depth 分量， stencil 分量，或两者皆有， 可被特殊用法所使用，如 depthStencilAttachment 和 "depth" 绑定。

"3d" 纹理可以有多个 切片（slice），每个切片是该纹理在特定 z 值下的二维图像。 切片不是独立的子资源。

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

    undefined destroy();

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

GPUTexture 拥有如下不可变属性：

width，类型为 GPUIntegerCoordinateOut，只读

该 GPUTexture 的宽度。

height，类型为 GPUIntegerCoordinateOut，只读

该 GPUTexture 的高度。

depthOrArrayLayers，类型为 GPUIntegerCoordinateOut，只读

该 GPUTexture 的深度或层数。

mipLevelCount，类型为 GPUIntegerCoordinateOut，只读

该 GPUTexture 的 mip 级别数量。

sampleCount，类型为 GPUSize32Out，只读

该 GPUTexture 的采样数。

dimension，类型为 GPUTextureDimension，只读

每个子资源的 texel 集的维度。

format，类型为 GPUTextureFormat，只读

该 GPUTexture 的格式。

usage，类型为 GPUFlagsConstant，只读

该 GPUTexture 允许的用途。

[[viewFormats]]，类型为 sequence<GPUTextureFormat>

为此 GPUTexture 创建视图时可用作 GPUTextureViewDescriptor.format 的 GPUTextureFormat 集合。

GPUTexture 拥有如下设备时间线属性：

[[destroyed]]，类型为 boolean， 初始值为 false

如果纹理被销毁，它将无法再被用于任何操作，其底层内存可以被释放。

逻辑 mip 级别特定纹理范围（logical miplevel-specific texture extent） 指的是某个 纹理 在特定 mipLevel 下的 texel 尺寸。 其计算过程如下：

物理 mip 级别特定纹理范围（physical miplevel-specific texture extent） 指的是某个 纹理 在特定 mipLevel 下的 texel 尺寸，并包含为形成完整texel block而可能补齐的额外填充。其计算过程如下：

6.1.1. GPUTextureDescriptor

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

GPUTextureDescriptor 拥有如下成员：

size， 类型为 GPUExtent3D

纹理的宽度、高度和深度或层数。

mipLevelCount，类型为 GPUIntegerCoordinate，默认值为1

该纹理包含的 mip 级别数量。

sampleCount，类型为 GPUSize32，默认值为1

纹理的采样数。当 sampleCount > 1 时，表示为多重采样纹理。

dimension，类型为 GPUTextureDimension，默认值为"2d"

指定纹理是一维、二维数组层，还是三维纹理。

format，类型为 GPUTextureFormat

纹理的格式。

usage，类型为 GPUTextureUsageFlags

纹理允许的用途。

viewFormats，类型为 sequence<GPUTextureFormat>，默认值为[]

指定在该纹理上调用 createView() 时，允许作为 format 的格式（除了纹理实际的 format 外）。

注意：

添加格式到该列表可能会带来显著的性能影响，因此应避免不必要地添加格式。

实际的性能影响高度依赖于目标系统；开发者需在多种系统上测试应用以了解具体影响。例如，在某些系统上，format 或 viewFormats 包含 "rgba8unorm-srgb" 时， 性能可能不如仅包含 "rgba8unorm" 的纹理。其他格式和格式组合在不同系统上也有类似注意事项。

该列表的格式必须与纹理格式 兼容。

两个 GPUTextureFormat， format 和 viewFormat，当且仅当满足以下条件时，纹理视图格式兼容（texture view format compatible）：

• format 等于 viewFormat，或

• format 与 viewFormat 唯一区别在于是否为 srgb 格式（后缀为 -srgb）。

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

"1d"

指定仅有宽度的一维纹理。"1d" 纹理不能有 mipmap，不能多重采样，不能使用压缩或深度/模板格式，也不能作为渲染目标。

"2d"

指定具有宽度和高度，并可具有层的二维纹理。

"3d"

指定具有宽度、高度和深度的三维纹理。"3d" 纹理不能多重采样，且其格式必须支持 3d 纹理（所有纯色格式和部分打包/压缩格式）。

6.1.2. 纹理用法

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

GPUTextureUsage 标志决定 GPUTexture 创建后可如何使用：

COPY_SRC

该纹理可作为拷贝操作的源。（例如：作为 source 参数传递给 copyTextureToTexture() 或 copyTextureToBuffer() 调用。）

COPY_DST

该纹理可作为拷贝或写入操作的目标。（例如：作为 destination 参数传递给 copyTextureToTexture() 或 copyBufferToTexture() 调用，或作为 writeTexture() 的目标。)

TEXTURE_BINDING

该纹理可在着色器中作为采样纹理绑定（例如：作为 GPUTextureBindingLayout 的绑定组项）。

STORAGE_BINDING

该纹理可在着色器中作为存储纹理绑定（例如：作为 GPUStorageTextureBindingLayout 的绑定组项）。

RENDER_ATTACHMENT

该纹理可作为渲染通道中的颜色或深度/模板附件使用。（例如：作为 GPURenderPassColorAttachment.view 或 GPURenderPassDepthStencilAttachment.view。）

6.1.3. 纹理创建

createTexture(descriptor)

创建一个 GPUTexture。

调用对象: GPUDevice this.

参数：

参数列表: GPUDevice.createTexture(descriptor)

参数	类型	可为 null	可选	描述
descriptor	GPUTextureDescriptor	✘	✘	描述要创建的 GPUTexture。

返回值： GPUTexture

内容时间线步骤：

1. ? 校验 GPUExtent3D 形状(descriptor.size)。

2. ? 校验纹理格式所需特性 (descriptor.format, this.[[device]])。

3. ? 校验纹理格式所需特性 (对 descriptor.viewFormats 的每一项, this.[[device]])。

4. 令 t = ! 创建新的 WebGPU 对象(this, GPUTexture, descriptor)。

5. 设 t.width = descriptor.size.width。

6. 设 t.height = descriptor.size.height。

7. 设 t.depthOrArrayLayers = descriptor.size.depthOrArrayLayers。

8. 设 t.mipLevelCount = descriptor.mipLevelCount。

9. 设 t.sampleCount = descriptor.sampleCount。

10. 设 t.dimension = descriptor.dimension。

11. 设 t.format = descriptor.format。

12. 设 t.usage = descriptor.usage。

13. 在 this 的 设备时间线上执行初始化步骤。

14. 返回 t。

设备时间线 初始化步骤：

1. 如以下任一条件不满足，产生校验错误，置为无效并返回。

   • validating GPUTextureDescriptor(this, descriptor) 返回 true。

2. 设 t.[[viewFormats]] = descriptor.viewFormats。

3. 为 t 创建设备分配，使每个块具有与全零比特表示的块等价的 texel 表示。

   如分配失败且无副作用，产生内存不足错误，置为无效并返回。