WebGPU

1. 介绍

This section is non-normative.

图形处理单元，简称GPU，一直以来都是个人计算中实现丰富渲染和计算应用的关键部件。 WebGPU是一个将GPU硬件功能暴露给Web的API。该API从零开始设计，以便有效地映射到（2014年后的）原生GPU API。 WebGPU与WebGL无关，也没有显式地针对OpenGL ES。

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

GPU通过将数据通过管线来执行GPUCommandBuffer中编码的命令，这是固定功能和可编程阶段的混合。可编程阶段执行着色器，这些着色器是专为在GPU硬件上运行而设计的特殊程序。 pipeline的大部分状态由GPURenderPipeline或GPUComputePipeline对象定义。这些管线对象中未包含的状态在编码时通过命令设置，例如beginRenderPass()或setBlendConstant()。

2. 恶意使用注意事项

本节内容为非标准的 本节描述了在 Web 上公开此 API 相关的风险

2.1. 安全

WebGPU的安全性要求与Web的要求相同，同样也是不容妥协的。总体方法是在命令到达GPU之前严格验证所有的命令，确保页面只能处理其自己的数据。

2.1.1. 基于 CPU 的未定义行为

WebGPU实现将用户提出的工作负载转换为针对目标平台的特定API命令。原生API为命令指定有效用法（例如，参见vkCreateDescriptorSetLayout(https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/vkCreateDescriptorSetLayout.html))，通常情况下，如果不遵循有效用法规则，则不能保证任何结果。这被称为“未定义行为”，攻击者可能利用这一行为访问他们无权访问的内存，或迫使驱动程序执行任意代码。

为了禁止不安全的使用，定义了允许的WebGPU行为范围。实现必须验证用户的所有输入，并仅在有效工作负载下达到驱动程序。这份文档详细说明了所有错误条件及处理语义。例如，在copyBufferToBuffer()的“源”和“目标”中同时指定具有相交范围的相同缓冲区，将导致GPUCommandEncoder产生错误，并且不会发生其他操作。

有关错误处理的更多信息，请参阅§ 22 错误 & 调试。

2.1.2. 基于 GPU 的未定义行为

WebGPU 着色器在GPU硬件内部的计算单元中执行。在原生API中，一些着色器指令可能导致GPU上的未定义行为。为了解决这个问题，WebGPU严格定义了着色器指令集及其定义的行为。当着色器提供给createShaderModule()时，WebGPU实现必须在进行任何转换（至特定平台的着色器）或变换过程之前对其进行验证。

2.1.3. 未初始化的数据

通常，分配新内存可能暴露其他在系统上运行的应用程序的残留数据。为解决这一问题，WebGPU在概念上将所有资源初始化为零，尽管在实践中，如果实现发现开发者手动初始化内容，则可以跳过此步骤。这包括着色器内的变量和共享工作组内存。

清除工作组内存的确切机制可能因平台而异。如果原生API没有提供清除它的功能，WebGPU实现将计算着色器转换为首先在所有调用中执行清除操作，然后同步它们，并继续执行开发者的代码。

2.1.4. 着色器中的越界访问

为了防止着色器访问应用程序不拥有的GPU内存，WebGPU实现可能会在驱动程序中启用一种特殊模式（称为“稳健缓冲区访问”），以保证访问仅限于缓冲区边界。

或者，实现可以通过插入手动边界检查来转换着色器代码。当采用这种方法时，越界检查仅适用于数组索引。由于主机端的minBindingSize验证，不需要对着色器结构的简单字段访问进行额外的边界检查。

如果着色器尝试在物理资源边界之外加载数据，实现可以执行以下操作：

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

2. 返回"(0, 0, 0, X)"的值向量，其中X可以是任何值

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

如果着色器尝试在物理资源边界之外写入数据，实现可以执行以下操作：

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

2. 丢弃写入操作

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

2.1.5. 无效数据

在将浮点数数据从CPU上传至GPU，或在GPU上生成这些数据时，我们可能得到一个并不对应于有效数字的二进制表示，例如无穷大或NaN（非数字）。在这种情况下，GPU的行为取决于GPU硬件对IEEE-754标准的实现准确性。WebGPU保证引入无效浮点数只会影响算术计算的结果，不会产生其他副作用。

2.1.6. 驱动程序错误

GPU驱动程序和其他软件一样，可能会受到错误的影响。如果出现错误，攻击者可能会利用驱动程序的错误行为来获取未授权的数据。为了降低风险，WebGPU工作组将与GPU供应商合作，将WebGPU Conformance Test Suite（CTS）集成到他们的驱动程序测试流程中，就像对WebGL所做的那样。

WebGPU实现预计会针对发现的一些错误进行修复，并在无法修复的已知错误的驱动程序上禁用WebGPU。

2.1.7. 定时攻击

WebGPU被设计为通过Web Workers支持多线程使用。因此，它旨在不让用户面临现代高精度定时攻击。一些对象，如GPUBuffer或GPUQueue，具有可以同时访问的共享状态。这可能导致类似于从多个Web Workers访问SharedArrayBuffer的竞态条件，从而使线程调度可观察。

WebGPU通过限制只能对代理内的代理集群进行反序列化（或共享）对象的能力来解决这个问题，并且只有在启用cross-origin isolated策略时才有效。这种限制与防止恶意 SharedArrayBuffer 使用的mitigations相匹配。同样，用户代理也可以序列化共享任何句柄的代理，以完全阻止任何并发。

最后，在WebGPU中共享状态的竞争攻击面将是 SharedArrayBuffer 攻击的一个小子集。

WebGPU还指定了“timestamp-query”功能，该功能可以提供GPU操作的高精度计时。该功能是可选的，WebGPU实现可能仅限于仅将其暴露给受信任的场景。或者，计时查询结果可以由计算着色器处理并与较低精度对齐。

2.1.8. 行锤攻击

Row hammer是一类利用DRAM单元中状态泄漏的攻击。它可以在GPU(https://www.vusec.net/projects/glitch/)上使用。WebGPU没有任何特定的缓解措施，而是依赖于平台级解决方案，例如减少内存刷新间隔。

2.1.9. 拒绝服务

WebGPU应用程序可以访问GPU内存和计算单元。WebGPU实现可能会限制应用程序可用的GPU内存，以保持其他应用程序的响应。对于GPU处理时间，WebGPU实现可以设置"看门狗"定时器，确保应用程序不会导致GPU在几秒钟内无响应。这些措施与WebGL中使用的措施类似。

2.1.10. 工作负载识别

WebGPU 提供对在同一机器上运行的不同程序（和网页）之间共享的受限全局资源的访问。应用程序可以尝试间接探测这些全局资源的约束程度，以便根据这些共享资源的使用模式推断其他打开的网页所执行的工作负载。这些问题通常类似于Javascript的问题，例如系统内存和CPU执行吞吐量。WebGPU 没有为此提供任何额外的缓解措施。

2.1.11. 内存资源

WebGPU公开了来自机器全局内存堆（如显存）的可失败分配。这允许通过尝试分配并观察分配失败来探测系统剩余可用内存的大小（对于给定的堆类型）。

内部的GPU通常具有一个或多个（通常只有两个）供所有运行应用程序共享的内存堆。当堆耗尽时，WebGPU将无法创建资源。这是可观察的，这可能允许恶意应用程序猜测其他应用程序使用哪些堆，以及它们从这些堆中分配了多少内存。

虽然这种信息可能被滥用，但要解决这个问题并不容易。WebGPU实现可能会采用一些策略来降低此问题带来的风险，如限制应用程序可用的内存和计算资源，从而保持其他应用程序的响应性。但是，这种策略并不能完全解决问题，因为恶意应用程序仍然可以通过观察资源分配失败来获取有关系统内存堆的信息。

总之，尽管WebGPU暴露了这种潜在的攻击途径，但开发者和用户仍需要保持警惕，并致力于在应用程序安全和系统资源管理方面进行持续改进。

2.1.12. 计算资源

如果一个网站与另一个网站同时使用WebGPU，它可能会注意到处理某些工作所需的时间增加。例如，如果一个网站不断提交计算工作负载并跟踪队列上的工作完成情况，它可能会注意到还有其他内容开始使用GPU。

GPU有许多可以独立测试的部分，如算术单元、纹理采样单元、原子单元等。恶意应用程序可能会感知到其中一些单元所受到的压力，并尝试通过分析压力模式来猜测另一个应用程序的工作负载。这类似于Javascript在CPU执行的现实情况。

要解决此问题并不容易，WebGPU 可能无法提供针对此类信息泄露的特定缓解措施。然而，开发者和用户仍可保持警惕并实施最佳实践，以确保应用程序安全并最大程度地减小潜在风险。这可能包括限制或屏蔽一些具有潜在危险性的GPU功能，或在系统和应用程序之间实施严格的资源隔离。

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相同的方式观察到。这适用于光栅化覆盖和模式、着色器阶段之间变化的插值精度、计算单元调度以及执行的更多方面。

通常情况下，光栅化和精度指纹在每个供应商的大部分或所有设备之间是相同的。性能差异相对难以解决，但也相对信号较低（就像JS执行性能一样）。

对隐私至关重要的应用程序和用户代理应使用软件实现来消除此类伪像。

2.2.3. 机器特定性能

另一个区分用户的因素是测量GPU上特定操作的性能。即使在低精度计时下，通过重复执行某个操作也可以显示出用户的设备在特定工作负载上的运行速度。这是一个相当常见的向量（在WebGL和Javascript中都存在），但信号较低，而且实际上很难进行真正的归一化。

WebGPU计算管线能够在不受固定功能硬件限制的情况下访问GPU。这对于唯一设备指纹识别带来了额外的风险。用户代理可以采取措施将逻辑GPU调用与实际计算单元分离，以降低这种风险。

2.2.4. 用户代理状态

本规范没有为一个源定义任何额外的用户代理状态。然而，预计用户代理将有编译缓存，用于昂贵的编译结果，如 GPUShaderModule，GPURenderPipeline 和 GPUComputePipeline。这些缓存对于在首次访问后提高WebGPU应用程序的加载时间非常重要。

对于规范来说，这些缓存与非常快速的编译无法区分，但对于应用程序来说，很容易测量 createComputePipelineAsync() 所需的解析时间。这可能在源之间泄漏信息（例如 “用户是否访问了具有此特定着色器的站点”），所以用户代理应该遵循存储分区的最佳实践。

系统的GPU驱动程序也可能拥有自己的编译着色器和管线缓存。用户代理可能希望尽可能禁用这些功能，或者以使GPU驱动程序将它们视为不同的方式向着色器中添加每个分区的数据。

2.2.5. 驱动程序错误

除了安全中概述的问题外，驱动程序错误可能引入行为差异，这可以作为一种区分用户的方法来观察。在这里同样适用于安全性考虑中提到的缓解措施，包括与GPU供应商协调以及在用户代理中针对已知问题实施解决方案。通过这些措施，可以最大限度地降低因驱动程序错误导致的安全风险，确保WebGPU应用及相关用户的安全性。

2.2.6. 适配器标识符

根据WebGL的过往经验，开发者确实需要能识别其代码运行在哪个GPU上，以便创建和维护稳健的GPU基础内容。例如，识别具有已知驱动程序错误的适配器以解决它们，或避免在给定类别的硬件上性能低于预期的功能。

但是，公开适配器标识符也自然地扩大了可用的指纹信息量，因此有必要限制识别适配器的精度。

可以应用多种缓解措施来在实现稳健内容和保护隐私之间达到平衡。首先，用户代理可以通过识别和解决已知驱动程序问题来减轻开发者的负担，自从浏览器开始使用GPU以来就一直有这样做。

当默认公开适配器标识符时，它们应尽可能宽泛地有用。例如，可能识别适配器的供应商和一般架构，而不识别正在使用的特定适配器。同样，在某些情况下，可能会报告被认为是实际适配器合理代理的适配器标识符。

在完整且详细的适配器信息有用的情况下（例如：提交错误报告时），可以要求用户同意向页面透露有关其硬件的更多信息。

最后，如果用户代理认为适当（如在增强隐私模式下），它将始终有权自行决定是否报告适配器标识符。

3. 基本概念

3.1. 公约

3.1.1. 语法速记

在本规范中，使用以下语法简写：

. (“dot”) 语法，在编程语言中很常见。

术语 " Foo.Bar "的含义是 “值（或接口）Foo 的 Bar 成员”。 术语 " Foo.Bar 是 提供" 的含义是 " Bar 成员在 map 值 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”。

槽支持的属性

由相同名称的内部槽支持的 WebIDL 属性。它可能是可变的，也可能是不可变的。

3.1.2. WebGPU 接口

WebGPU接口定义了一个WebGPU对象。它可以用于：

在它被创建的内容时间线上，它是一个JavaScript公开的WebIDL接口。 在所有其他时间线上，只能访问不可变属性。

以下特殊属性类型可以在WebGPU接口上定义：

不可变属性

一个在对象初始化期间设置的只读槽。它可以从任何时间线访问。

注：由于槽是不可变的，实现可以在多个时间线上根据需要拥有一个副本。不可变属性 的定义就是这样，以避免在本规范中描述多个副本。

如果名为 [[with brackets]], 它就是一个内部槽。 如果名为 withoutBrackets, 它是一个 只读 槽支持的属性。

内容时间线属性

一个只能从创建对象的内容时间线上访问的属性。

如果名为 [[with brackets]]，它就是一个内部槽。 如果名为 withoutBrackets，它是一个 槽支持的属性。

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

interface mixin GPUObjectBase {
    attribute USVString label;
};

GPUObjectBase具有以下不可变属性：

[[internals]], 类型为 内部对象，只读，可覆盖

内部对象。

对该对象内容的操作需要断言他们正运行在 设备时间线 上，且设备是 有效的。

对于每个子类型化 GPUObjectBase 的接口，它可以使用 内部对象 的子类型进行覆盖。此槽最初设置为该类型的未初始化对象。

[[device]], 类型为 设备，只读。

拥有 内部对象 的 设备。

对此对象内容的操作需要断言它们正在 设备时间线 上运行，且设备是 有效的。

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

label, of type USVString

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

注： label 是 GPUObjectBase 的一个属性。两个 GPUObjectBase “包装器” 对象具有完全独立的标签状态，即使它们引用相同的底层对象（例如通过 getBindGroupLayout() 返回的对象）。label 属性除了从JavaScript设置之外不会改变。

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

该属性定义为 USVString，因为某些用户代理可能会将其提供给底层原生 API 的调试工具。

3.1.3. 内部对象

内部对象 跟踪可能仅在 设备时间线上使用的WebGPU对象的状态，在 设备时间线插槽 中，这些槽可能是可变的。

设备时间线插槽

一个仅从 设备时间线 可访问的内部插槽。

所有对 内部对象 的可变状态的读/写操作都发生在单个严格有序的 设备时间线 上执行的步骤中。这些步骤可能来自多个 代理 上的任何一个 内容时间线 算法。

注：" 代理" 是指JavaScript的 “线程”（即主线程或Web Worker）。

3.1.4. 对象描述符

一个对象描述符包含了创建对象所需的信息，这通常是通过GPUDevice的 create* 方法之一来完成的。

dictionary GPUObjectDescriptorBase {
    USVString label;
};

GPUObjectDescriptorBase has the following members:

label, of type USVString

GPUObjectBase.label的初始值。

3.2. 异步性

3.2.1. 无效的内部对象 & 具有传染性的无效性

在WebGPU中，对象创建操作不返回promise，但实际上是内部异步的。返回的对象引用的是在设备时间线上操作的内部对象。大多数发生在设备时间线上的错误不会通过异常或拒绝失败，而是通过与相关联的设备生成的GPUError进行通信。

内部对象要么有效，要么无效。 一个无效的对象将永远不会在以后变得有效，但一些有效的对象可能会变成无效。

如果无法创建对象，那么对象将从创建时开始就是无效的。例如，这可能是因为对象描述符没有描述一个有效对象，或者没有足够的内存来分配资源。

绝大多数类型的内部对象在创建后不能变无效，但仍可能变得不可用，例如，如果拥有的设备变为丢失或者销毁，或者对象具有特殊的内部状态，如缓冲区状态"销毁"。

某些类型的内部对象在创建后可以变为无效；具体来说，这些类型包括设备、适配器、GPUCommandBuffer和命令/通道/包编码器。

3.2.2. Promise 排序

在WebGPU中，有几个操作会返回promises。

• GPU.requestAdapter()

• GPUAdapter.requestDevice()

• GPUAdapter.requestAdapterInfo()

• GPUDevice.createComputePipelineAsync()

• GPUDevice.createRenderPipelineAsync()

• GPUBuffer.mapAsync()

• GPUShaderModule.getCompilationInfo()

• GPUQueue.onSubmittedWorkDone()

• GPUDevice.lost

• GPUDevice.popErrorScope()

WebGPU不对这些promises的解决顺序（resolve或reject）做任何保证，除了以下情况：

• 如果在 p2 = q.onSubmittedWorkDone() 被调用之前调用了 p1 = b.mapAsync()，并且 b 最后一次是仅在 q 上使用的，那么 p2 在 p1 解析之前不得解析。

应用程序不能依赖于其他任何promise解决顺序。

3.3. 坐标系统

• 在归一化设备坐标（NDC）中，Y轴是向上的：在NDC中，点(-1.0, -1.0)位于NDC的左下角。 此外，NDC中的x和y应在-1.0和1.0（含）之间，而NDC中的z应在0.0和1.0（含）之间。 在NDC范围之外的顶点不会引入任何错误，但它们会被剪裁。

• 在 framebuffer 坐标、视口坐标和片段/像素坐标中，Y轴是向下的： 在这些坐标系中，原点(0, 0)位于左上角。

• 窗口/呈现坐标与 framebuffer坐标相匹配。

• 贴图坐标中原点(0, 0)的UV表示贴图内存中的第一个像素(最低字节)。

注：WebGPU 的坐标系在图形管线中与 DirectX 的坐标系相匹配。

3.4. 编程模型

3.4.1. 时间线

本节为非规范性内容。

一个带有用户代理前端和GPU后端的计算机系统中，各组件在不同的时间线上并行工作：

内容时间线

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

要从操作GPUDevice device 中向内容时间线发出步骤，请使用为GPUDevice排队全局任务 device与这些步骤。

设备时间线

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

队列时间线

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

在本规范中，当结果值取决于除 内容时间线 以外的任何时间轴上的工作时，将使用异步操作。它们在JavaScript中由回调和promises表示。

3.4.2. 内存模型

本节为非规范性内容。

在应用程序初始化例程中获取到 GPUDevice 后，我们可以将 WebGPU平台 描述为包含以下层：

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

2. 具有此设备的低级本地API驱动程序的操作系统。

3. 实际的CPU和GPU硬件。

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

脚本拥有的内存，例如由脚本创建的 ArrayBuffer，通常无法被GPU驱动程序访问。 用户代理可能有不同的进程负责运行内容和与GPU驱动程序通信。在这种情况下，它将使用进程间共享内存来传输数据。 独立GPU有高带宽的自己的内存，而集成GPU通常与系统共享内存。

大多数 物理资源 分配在类型为内存的GPU计算或渲染的效率上。当用户需要向GPU提供新数据时，数据可能首先需要跨越进程边界以到达与GPU驱动程序通信的用户代理部分。然后，可能需要使驱动程序可见，这有时需要将数据复制到驱动程序分配的寄存器内存中。最后，可能需要将其传输到专用GPU内存，可能将内部布局更改为GPU操作最有效的布局。

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

注：此示例描述了最坏情况，而实际上实现可能不需要跨越进程边界，或者可能能够将驱动程序管理的内存直接暴露给用户在 ArrayBuffer 后面，从而避免任何数据副本。

3.4.3. 资源用途

一个物理资源可以在GPU上使用内部用途：

input

用于绘制或调度调用的输入数据缓冲区。保持内容不变。 允许使用缓冲区 INDEX，缓冲区 VERTEX 或 缓冲区 INDIRECT。

constant

从着色器角度来看，资源绑定是不变的。保持内容不变。 允许使用缓冲区 UNIFORM 或纹理 TEXTURE_BINDING。

storage

可写存储资源绑定。 允许使用缓冲区 STORAGE 或纹理 STORAGE_BINDING。

storage-read

只读存储资源绑定。保持内容不变。 允许使用缓冲区 STORAGE。

attachment

在渲染通道中用作输出附件的纹理。 允许使用纹理 RENDER_ATTACHMENT。

attachment-read

在渲染通道中用作只读附件的纹理。 保持内容不变。 允许使用纹理 RENDER_ATTACHMENT。

我们定义子资源可以是整个缓冲区，也可以是一个纹理子资源。

规定用途只能组合成兼容用途列表允许API在处理内存时限制数据竞争发生的时间。具有这种性质的应用程序在针对WebGPU编写时，更有可能在不同平台上无需修改即可运行。

通常，当实现处理一个使用 子资源的操作，以与其当前用途允许的不同方式时，它会调度资源转换到新状态。在某些情况下，例如在打开的 GPURenderPassEncoder 内，由于硬件限制，此类转换是不可能的。我们将这些地方定义为 用途范围。

主要用途规则 是，对于任何一个 子资源，在一个 用途范围 中的 内部用途 列表必须是一个 兼容用途列表。

例如，在同一个 GPURenderPassEncoder 中将同一个缓冲区绑定为 存储 和 输入，会使编码器以及拥有的 GPUCommandEncoder 进入错误状态。这种用途组合不能构成一个 兼容用途列表。

注：在单个 用途范围 内多个可写存储缓冲区/纹理的使用之间的竞争条件是允许的。

提供给 GPURenderPassColorAttachment.view 和 GPURenderPassColorAttachment.resolveTarget 的纹理的 子资源 被视为在此渲染通道的 用途范围 内作为 附件 使用。

3.4.4. 同步

对于 物理资源 的每一个 子资源，其一组 内部使用 标志在 队列时间线 上进行跟踪。

在 队列时间线 上，有一个有序的 用途范围 序列。 在每个范围的持续时间内，任何给定的 子资源 的一组 内部用途 标志是恒定的。 在 用途范围 之间的边界处， 子资源 可能会过渡到新的用途。

本规范定义了以下 用途范围：

• 在通道之外（在 GPUCommandEncoder 中），每个（非状态设置）命令都是一个使用范围（例如 copyBufferToTexture()）。

• 在计算过程中，每个调度命令（dispatchWorkgroups() 或 dispatchWorkgroupsIndirect()) 是一个使用范围。 如果命令可能访问子资源，则该子资源在使用范围内被“使用”。 在调度中，对于当前 GPUComputePipeline 使用的每个绑定组插槽 [[layout]]，每个 subresource 被引用该绑定组在使用范围内被“使用”。 状态设置计算通道命令，如setBindGroup(),不直接对使用范围做出贡献；他们反而改变了在调度命令中检查的状态。

• 一个渲染通道是一个使用范围。 如果子资源被任何引用，则它在使用范围内被“使用”（状态设置或非状态设置）命令。 例如，在setBindGroup(),bindGroup 中的每个子资源都在渲染过程的使用范围内“使用”。

问题：上面应该大概讲的是GPU命令。但是我们没有办法参考特定的 GPU 命令（如分派）。

在命令编码期间，子资源的每次使用都记录在命令缓冲区的 usage scopes 之一中。 对于每个 适用范围，实现执行 适用范围验证 通过组成 [=usage scope 中使用的每个 subresource 的所有 internal usage 标志的列表 =]. 如果这些列表中的任何一个不是兼容用法列表，GPUCommandEncoder.finish() 将生成验证错误。

3.5. 核心内部对象

3.5.1. Adapters

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

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

每个 适配器 对象只能用于创建一个 device： 在 requestDevice() 成功后，适配器变为 无效。 此外，适配器 对象可以随时 过期。

注： 这确保应用程序在创建设备时使用最新的系统状态来选择适配器。 它还通过使它们看起来相似来鼓励对更多场景的鲁棒性：首次初始化、由于拔下适配器而重新初始化、由于测试 GPUDevice.destroy() 调用而重新初始化等。

如果 适配器 具有重要的性能警告以换取更广泛的兼容性、更可预测的行为或改进的隐私的某种组合，则它可以被视为 后备适配器。 fallback adapter 不需要在每个系统上都可用。

adapter 具有以下内部插槽：

[[features]]，类型为 ordered set<GPUFeatureName>，只读

features 可用于在此适配器上创建设备。

[[limits]]，类型为 supported limits，只读

可用于在此适配器上创建设备的 best 限制。

每个适配器限制必须与 supported limits 中的默认值相同或 better。

[[fallback]]，布尔类型

如果设置为“true”，则表示该适配器是 fallback adapter。

[[unmaskedIdentifiers]]，类型为 ordered set<DOMString>

用户代理已选择为此适配器报告的 GPUAdapterInfo 字段的名称列表。 最初填充了用户代理在未经用户同意的情况下选择报告的任何 GPUAdapterInfo 字段的名称。

Adapters 通过 GPUAdapter 暴露出来。

3.5.2. 设备

device 是 适配器 的逻辑实例，通过它创建 内部对象。 它可以在多个 代理 之间共享（e.g. dedicated workers）。

设备 是从它创建的所有 内部对象 的独占所有者： 当 设备 变为 无效（是 lost 或 destroyed）时，它和在其上创建的所有对象（直接，例如 createTexture()，或间接地，例如 createView()) 隐式变为 unusable。

device 具有以下内部插槽：

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

创建此设备的 适配器。

[[特性]]，类型为 ordered set<GPUFeatureName>，只读

可在此设备上使用的 特性。 不能使用附加功能，即使底层 适配器 可以支持它们。

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

可在此设备上使用的限制。 不能使用 更好 限制，即使基础 适配器 可以支持它们。

• 将 device.[[adapter]] 设置为 adapter。

• 将 device.[[features]] 设置为 set 中的值 描述符.requiredFeatures。

• 让 device.[[limits]] 成为具有默认值的 supported limits 对象。 对于 descriptor.requiredLimits 中的每个 (key, value) 对，设置 key对应的成员 在 device.[[limits]] 到 value 的 better 值 或 supported limits 中的默认值。

每当用户代理需要撤销对设备的访问权限时，它都会在设备的 device timeline 上调用 lose the device(device, "unknown")，可能会提前 当前在该时间线上排队的其他操作。

如果操作失败并产生副作用，这些副作用会明显改变设备上对象的状态或可能破坏内部实现/驱动程序状态，则设备应该丢失以防止这些更改被观察到。

Devices 通过 GPUDevice 暴露出来。

3.6. 可选功能

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

适配器 的能力必须符合 § 4.2.1 Adapter Capability Guarantees。

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

设备 的功能正是在 requestDevice() 中请求的功能。 无论 适配器 的功能如何，这些功能都会被强制执行。

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

3.6.1. 特性

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

只有在创建设备时请求了该功能（在 requiredFeatures 中）时，才能使用作为功能一部分的功能。 否则，以新方式使用现有 API 表面通常会导致 validation error，而使用 optional API surfaces 会导致以下结果：

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

• 使用具有（正确键入的）非默认值的新字典成员通常会导致 validation error。

• 使用新的 WGSL enable 指令总是导致 createShaderModule() validation error。

请参阅 Feature Index 了解每个功能启用的功能的描述。

3.6.2. 限制

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

每个限制都有一个 默认 值。 每个 适配器 都保证支持默认值或 更好。 如果未在 requiredLimits 中明确指定值，则使用默认值。

一个极限值可能比另一个更好。 更好 限制值总是放宽验证，使更多的程序严格有效。 对于每个 限制类，定义了“更好”。

不同的极限有不同的极限等级：

最大

该限制对传递到 API 中的某些值强制执行最大值。

更高的值是 更好。

只能设置为值 ≥ 默认。 较低的值被限制在 默认。

对齐方式

该限制对传递给 API 的某些值强制执行最小对齐； 那是， 该值必须是限制的倍数。

较低的值是 更好。

只能设置为 2 的幂，即 ≤ 默认。 不是 2 的幂的值无效。 2 的更高次幂被限制在 默认。

注： 设置“更好”的限制可能不一定是可取的，因为它们可能会对性能产生影响。 因此，为了提高跨设备和实现的可移植性，应用程序通常应该请求适用于其内容的“最差”限制（理想情况下，默认值）。

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

3.6.2.1. GPUSupportedLimits

GPUSupportedLimits 公开适配器或设备支持的 limits。 请参见 GPUAdapter.limits 和 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 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 maxInterStageShaderComponents;
    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 界面。 它的 set entries 是适配器或设备支持的 features 的 GPUFeatureName 值。 它必须只包含来自 GPUFeatureName 枚举的字符串。

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

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

3.6.2.3. WGSLLanguageFeatures

WGSLLanguageFeatures 是一个 setlike 接口。 它的 set entries 是 WGSL language extensions 支持所有适配器的字符串名称。

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

3.6.2.4. GPUAdapterInfo

GPUAdapterInfo 公开有关适配器的各种标识信息。

GPUAdapterInfo 中的任何成员都不能保证被填充。用户代理可以自行决定显示哪些值，并且在某些设备上很可能不会填充任何值。因此，应用程序必须能够处理任何可能的 GPUAdapterInfo 值，包括这些值的缺失。

有关隐私方面的考虑，请参阅 § 2.2.6 适配器标识符。

[Exposed=(Window, DedicatedWorker), SecureContext]
interface GPUAdapterInfo {
    readonly attribute DOMString vendor;
    readonly attribute DOMString architecture;
    readonly attribute DOMString device;
    readonly attribute DOMString description;
};

GPUAdapterInfo 具有以下属性：

vendor, of type DOMString, readonly

适配器 供应商的名称，如果可用的话。否则为空字符串。

architecture, of type DOMString, readonly

适配器 所属的 GPU 系列或类别的名称（如果可用）。否则为空字符串。

device, of type DOMString, readonly

适配器 的供应商特定标识符（如果可用）。否则为空字符串。

注：这是一个表示适配器类型的值。 例如，它可能是 PCI 设备 ID。 它不像序列号那样唯一地标识给定的硬件。

description, of type DOMString, readonly

描述驱动程序报告的 适配器 的人类可读字符串（如果可用）。 否则为空字符串。

注：因为没有格式应用于 description ，所以不建议尝试解析此值。 根据 GPUAdapterInfo 更改其行为的应用程序，例如对已知驱动程序问题应用解决方法，应尽可能依赖其他字段。

3.7. 扩展文档

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

WebGPU 实现不得暴露扩展功能； 这样做是违反规范的。 在将新功能集成到 WebGPU 规范（本文档）和/或 WGSL 规范中之前，它不会成为 WebGPU 标准的一部分。

3.8. 源限制

WebGPU 允许访问存储在图像、视频和画布中的图像数据。 跨域媒体的使用受到限制，因为着色器可用于间接推断已上传到 GPU 的纹理内容。

WebGPU 不允许上传is not origin-clean 的图像源。

这也意味着使用 WebGPU 渲染的画布的 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. 任务源

3.9.1. WebGPU 任务源

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

3.9.2. 自动过期任务源

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

• GPUTexture 由 getCurrentTexture() 返回

• 从 HTMLVideoElement 创建的 GPUExternalTexture

来自自动过期任务源的任务应该被高优先级处理； 特别是，一旦排队，它们应该在用户定义的（JavaScript）任务之前运行。

3.10. 颜色空间和编码

WebGPU 不提供颜色管理。 WebGPU 中的所有值（例如纹理元素）都是原始数值，而不是颜色管理颜色值。

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

WebGPU 允许 PredefinedColorSpace 枚举中的所有颜色空间。 请注意，每个颜色空间都定义在扩展范围内，如引用的 CSS 定义所定义，以表示其空间之外的颜色值（色度和亮度）。

问题（gpuweb/gpuweb#1715）： 考虑将 srgb 编码图像上传到线性编码纹理的路径。

色域外预乘 RGBA 值 是任何 R/G/B 通道值超过 alpha 通道值的值。 例如，预乘 sRGB RGBA 值 [1.0, 0, 0, 0.5] 表示具有 50% alpha 的（未预乘）颜色 [2, 0, 0]，在 CSS 中写为 rgb(srgb 2 0 0 / 50%) . 就像 sRGB 色域之外的任何颜色值一样，这是扩展颜色空间中定义明确的点（除非 alpha 为 0，在这种情况下没有颜色）。 但是，当这些值输出到可见画布时，结果是不确定的（参见 GPUCanvasAlphaMode "premultiplied"）。

3.10.1. Color Space Conversions

根据上面的定义，通过将颜色在一个空间中的表示转换为另一个空间中的表示，颜色在空间之间进行转换。

如果源值的 RGBA 通道少于 4 个，则在转换颜色空间/编码和 alpha 预乘之前，将缺少的绿色/蓝色/alpha 通道分别设置为“0、0、1”。 转换后，如果目标需要少于 4 个通道，则忽略额外的通道。

注： 灰度图像通常在其颜色空间中表示 RGB 值“(V, V, V)”或 RGBA 值“(V, V, V, A)”。

颜色在转换期间不会被有损限制：如果源颜色值在目标颜色空间的色域范围之外，则从一个颜色空间转换到另一个颜色空间将导致值超出 [0, 1] 范围。 例如，对于 sRGB 目标，如果源是 rgba16float，在更宽的色彩空间（如 Display-P3）中，或者预乘并包含 [=色域外预乘 RGBA 值|色域外值 = ].

类似地，如果源值具有高位深度（例如 PNG，每个组件 16 位）或扩展范围（例如，具有“float16”存储的画布），这些颜色将通过颜色空间转换保留，中间计算至少具有精度 的来源。

3.10.2. 色彩空间转换省略

如果颜色空间/编码转换的源和目标相同，则不需要转换。 一般来说，如果转换的任何给定步骤是恒等函数（无操作），实现应该将其省略，以提高性能。

为了获得最佳性能，应用程序应该设置它们的颜色空间和编码选项，以便在整个过程中最大限度地减少必要的转换次数。 对于 GPUImageCopyExternalImage 的各种图像源：

• ImageBitmap:

  • 预乘通过 premultiplyAlpha 控制。

  • 色彩空间通过 colorSpaceConversion 控制。

• 二维画布：

  • Always premultiplied。

  • 颜色空间通过 colorSpace 上下文创建属性控制。

• WebGL 画布：

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

  • 通过 WebGLRenderingContext 的 drawingBufferColorSpace 状态控制颜色空间。

注：在依赖这些功能之前，检查浏览器实现是否支持这些功能。

3.11. 从 JavaScript 到 WGSL 的数字转换

WebGPU API 的几个部分（pipeline-overridable constants 和 render pass clear values）从 WebIDL（double 或 float）获取数值并将它们转换为 WGSL 值（bool、i32、u32、f32、f16）。

4. 初始化

4.1. navigator.gpu

GPU 对象分别通过 Navigator 和 WorkerNavigator 接口在 Window 和 DedicatedWorkerGlobalScope 上下文中可用，并通过 navigator.gpu 暴露出来：

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

4.2. GPU

GPU 是 WebGPU 的入口。

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

GPU 具有以下方法和属性：

requestAdapter(options)

从用户代理请求 适配器。 用户代理选择是否返回适配器，如果是，则根据提供的选项进行选择。

Called on: GPU this.

Arguments:

Arguments for the GPU.requestAdapter(options) method.

Parameter	Type	Nullable	Optional	Description
options	GPURequestAdapterOptions	✘	✔	选择适配器的标准。

Returns: Promise<GPUAdapter?>

Content timeline steps:

1.让 contentTimeline 成为当前 内容时间线。 1.让 promise 成为 a new promise。 1.在 this 的 设备时间线 上发出initialization steps。

1. 返回promise。

Device timeline initialization steps:

1. 让 adapter 为 null.

2. 如果用户代理选择返回一个适配器，它应该：

   1. 设置 adapter 为一个 有效 适配器，根据 § 4.2.2 适配器选择 中的规则和 options 中的标准选择，遵守 § 4.2.1 Adapter Capability Guarantees。

      适配器的 支持的限制 必须符合 § 3.6.2 限制 中定义的要求。

   2. 如果适配器 满足 fallback adapter 的标准，设置 adapter.[[fallback]] 为 true。

3. 在 内容时间线 上发布后续步骤.

Content timeline steps:

1. 如果 adapter 不为 null:

   1. 使用一个新的 GPUAdapter 去封装 adapter解析 promise。

2. 否则, 解析 promise 为 null.

getPreferredCanvasFormat()

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

返回值可以作为 format 传递给 configure() 调用 GPUCanvasContext 以确保关联的画布能够有效地显示其内容。

注：未显示在屏幕上的画布可能会或可能不会从使用此格式中受益。

Called on: GPU this.

Returns: GPUTextureFormat

内容时间线 步骤:

1. 返回 "rgba8unorm" 或 "bgra8unorm"，具体取决于哪种格式最适合在此系统上显示 WebGPU 画布。

wgslLanguageFeatures, of type WGSLLanguageFeatures, readonly

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

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

• 添加/移除物理适配器（通过插入/拔出、驱动程序更新、挂起恢复等）

• 系统的电源配置已更改（笔记本电脑已拔出、电源设置已更改等）

注： 用户代理可能会经常选择 expire 适配器，即使没有系统状态更改（例如，创建适配器后的几秒或几分钟）。 这有助于混淆真实的系统状态变化，并让开发人员更加意识到在调用 requestDevice() 之前再次调用 requestAdapter() 总是必要的。 如果应用程序确实遇到这种情况，标准的设备丢失恢复处理应该允许它恢复。

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

4.2.1. Adapter Capability Guarantees

requestAdapter() 返回的任何 GPUAdapter 必须提供以下保证：

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

  • 支持 "texture-compression-bc"。

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

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

• 所有 alignment-class 限制必须是 2 的幂。

• maxBindingsPerBindGroup 必须是 ≥ （每个着色器阶段的最大绑定 × 每个管线的最大着色器阶段），其中：

  • 每个着色器阶段的最大绑定数 是 （maxSampledTexturesPerShaderStage + maxSamplersPerShaderStage + maxStorageBuffersPerShaderStage + maxStorageTexturesPerShaderStage + maxUniformBuffersPerShaderStage）。

  • max shader stages per pipeline 是 2，因为 GPURenderPipeline 支持顶点和片段着色器。

  注：maxBindingsPerBindGroup 不反映基本限制； 实现应该提高它以符合这个要求，而不是降低 其他限制。

• maxBindGroups 必须是 ≤ maxBindGroupsPlusVertexBuffers。

• maxVertexBuffers 必须是 ≤ maxBindGroupsPlusVertexBuffers。

• minUniformBufferOffsetAlignment 和 minStorageBufferOffsetAlignment 必须都是 ≥ 32 字节。

  注：32 字节将是 vec4<f64> 的对齐方式。 参见 WebGPU Shading Language § 13.4.1 Alignment and Size。

• maxUniformBufferBindingSize 必须 ≤ maxBufferSize。

• maxStorageBufferBindingSize 必须 ≤ maxBufferSize。

• maxStorageBufferBindingSize 必须是 4 字节的倍数。

• maxVertexBufferArrayStride 必须是 4 字节的倍数。

• maxComputeWorkgroupSizeX 必须 ≤ maxComputeInvocationsPerWorkgroup。

• maxComputeWorkgroupSizeY 必须 ≤ maxComputeInvocationsPerWorkgroup。

• maxComputeWorkgroupSizeZ 必须 ≤ maxComputeInvocationsPerWorkgroup。

• maxComputeInvocationsPerWorkgroup 必须 ≤ maxComputeWorkgroupSizeX × maxComputeWorkgroupSizeY × maxComputeWorkgroupSizeZ。

4.2.2. 适配器选择

GPURequestAdapterOptions 向用户代理提供提示，指示哪种配置适合该应用程序。

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

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

GPURequestAdapterOptions 拥有以下成员:

powerPreference, of type GPUPowerPreference

可选地提供提示，指示应从系统的可用适配器中选择 适配器 的类别。

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

注： 此提示的主要用途是影响在多 GPU 系统中使用哪个 GPU。 例如，一些笔记本电脑具有低功耗集成 GPU 和高性能独立 GPU。 此提示还可能会影响所选 GPU 的电源配置，以匹配请求的电源首选项。

注： 根据具体的硬件配置，例如电池状态和连接的显示器或可拆卸的 GPU，用户代理可以选择不同的 适配器 给定相同的电源偏好。 通常，给定相同的硬件配置和状态以及“powerPreference”，用户代理很可能会选择相同的适配器。

它必须是以下值之一：

undefined (or not present)

没有对于用户代理的提示。

"low-power"

指将节能优先于性能的请求。

注： 通常，如果内容不太可能受到绘图性能的限制，则应该使用它； 例如，如果它每秒只渲染一帧，只使用简单的着色器绘制相对简单的几何图形，或者使用一个小的 HTML canvas 元素。 如果内容允许，鼓励开发人员使用此值，因为它可以显着延长便携式设备的电池寿命。

"high-performance"

指将性能优先于功耗的请求。

注： 通过选择这个值，开发人员应该意识到，对于在生成的适配器上创建的 设备，用户代理更有可能强制设备丢失，以便通过切换到低功率适配器来节省功率。 鼓励开发人员仅在他们认为绝对必要时才指定此值，因为它可能会显着缩短便携式设备的电池寿命。

forceFallbackAdapter, of type boolean, defaulting to false

当设置为 true 时，表示可能只返回 备用适配器。 如果用户代理不支持 备用适配器，将导致 requestAdapter() 解析为“null”。

注： 如果 forceFallbackAdapter 设置为“false”并且没有其他合适的 适配器 可用或用户代理选择，返回一个 备用适配器。 希望阻止其应用程序在 备用适配器 上运行的开发人员应在请求 GPUDevice 之前检查 GPUAdapter.isFallbackAdapter 属性。

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

4.3. GPUAdapter

GPUAdapter 封装了一个 adapter，并描述了它的功能（特性 和 限制）。

要获得 GPUAdapter，请使用 requestAdapter()。

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

    Promise<GPUDevice> requestDevice(optional GPUDeviceDescriptor descriptor = {});
    Promise<GPUAdapterInfo> requestAdapterInfo(optional sequence<DOMString> unmaskHints = []);
};

GPUAdapter 拥有以下属性:

features, of type GPUSupportedFeatures, readonly

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

limits, of type GPUSupportedLimits, readonly

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

isFallbackAdapter, of type boolean, readonly

返回[[adapter]].[[fallback]]的值。

GPUAdapter has the following internal slots:

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

GPUAdapter 指向的 [= 适配器 =]。

GPUAdapter 拥有以下方法：

requestDevice(descriptor)

从 适配器 请求 设备。

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

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>

Content timeline steps:

1. 使 contentTimeline 为当前 内容时间线.

2. 使 promise 为 a new promise.

3. 使 adapter 为 this.[[adapter]].

4. 在 this 的 Device timeline 发起 initialization steps.

5. 返回 promise.

Device timeline initialization steps:

1. 如果以下任何条件没有满足：

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

   然后在 contentTimeline 上执行以下步骤并返回：

   内容时间线 步骤:

   1. 以一个 TypeError 拒绝 promise。

   注：这与浏览器根本不知道功能名称（在其 GPUFeatureName 定义中）时产生的错误相同。 这将浏览器不支持某项功能时的行为与特定适配器不支持某项功能时的行为融合在一起。

2. 如果未满足以下任何要求：

   • descriptor 中的每个键。requiredLimits 必须是 supported limits 成员的名称。

   • 对于每个限制名称 key 在 supported limits 的键中： 让value 是 descriptor.requiredLimits[key]。

     • value 必须不 更好 adapter 中的限制值。[[limits]]。

     • 如果限制的 class 是 alignment, value 必须是 2 的幂。

   然后在 contentTimeline 上执行以下步骤并返回：

   Content timeline 步骤：

   1. 以一个 OperationError 拒绝 promise

   1.如果adapter 无效，否则用户代理无法满足请求：

   1.让device 成为一个新的 shebei1。

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

      注： 这使得 adapter invalid，如果还没有的话。

      注： 当这种情况发生时，用户代理应该考虑在大多数或所有情况下发出开发人员可见的警告。 应用程序应从 requestAdapter() 开始执行重新初始化逻辑。

   否则：

   1.让device 成为具有 descriptor 描述的功能的新设备。 1.制作adapter.[[adapter]] 无效。

3. 在 contentTimeline 上发布后续步骤。

内容时间线 步骤：

1. 使用新的 GPUDevice 对象 device 解析 promise 。

   注： 如果设备已经丢失，因为适配器无法满足请求，device.lost 已经在 promise 解析之前被解析。

requestAdapterInfo()

请求此 GPUAdapter 的 GPUAdapterInfo。

注：适配器信息值与 Promise 一起返回，使用户代理有机会在请求未屏蔽的值时执行可能长时间运行的检查，例如在返回前征求用户同意。 但是，如果未指定 unmaskHints，则不应向用户显示任何对话框。

Called on: GPUAdapter this.

Arguments:

Arguments for the GPUAdapter.requestAdapterInfo() method.

Parameter	Type	Nullable	Optional	Description
unmaskHints	sequence<DOMString>	✘	✔	GPUAdapterInfo 属性名称列表，如果可用，需要未屏蔽值。

Returns: Promise<GPUAdapterInfo>

内容时间线 步骤：

1. 使 promise 为 a new promise.

2. 使 adapter 为 this.[[adapter]].

3. 如果 this 的 relevant global object 具有 transient activation，使 hasActivation 为 true, 否则为 false。

4. 在 in parallel 上运行以下步骤：

   1. 如果 unmaskHints.length > 0:

      1. 如果 hasActivation 为 false 以一个 NotAllowedError 拒绝 promise 并停止此步骤。

      2. 让 unmaskedKeys 是 unmaskHints 中指定的用户代理决定取消屏蔽的字段的 list，如果有的话。

         注：用户代理可以自由使用它认为合适的任何方法来决定要取消屏蔽哪些字段。

      3. Append unmaskedKeys 为 adapter.[[unmaskedIdentifiers]]。

   2. 以一个 new adapter info 对 adapter 解析 promise。

5. 返回 promise.

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

4.3.1. GPUDeviceDescriptor

GPUDeviceDescriptor describes a device request.

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

GPUDeviceDescriptor has the following members:

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

指定设备请求所需的 特性。 如果适配器不能提供这些功能，请求将失败。

在生成的设备上验证 API 调用时，将允许完全指定的一组功能，不多也不少。

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

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

每个键必须是 支持的限制 成员的名称。 在生成的设备上验证 API 调用时，将允许完全指定的限制，并且不允许 更好 或更糟。

defaultQueue, of type GPUQueueDescriptor, defaulting to {}

默认 GPUQueue 的描述符。

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

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

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

4.3.1.1. GPUFeatureName

每个 GPUFeatureName 标识一组功能，如果可用，则允许 WebGPU 的其他使用，否则这些功能将无效。

enum GPUFeatureName {
    "depth-clip-control",
    "depth32float-stencil8",
    "texture-compression-bc",
    "texture-compression-etc2",
    "texture-compression-astc",
    "timestamp-query",
    "indirect-first-instance",
    "shader-f16",
    "rg11b10ufloat-renderable",
    "bgra8unorm-storage",
    "float32-filterable"
};

4.4. GPUDevice

GPUDevice 封装了 device 并公开了该设备的功能。

GPUDevice 是创建 WebGPU interfaces 的顶级接口。

要获取 GPUDevice，请使用 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

包含设备支持的功能（即创建它的功能）的 GPUFeatureName 值的集合。

limits, of type GPUSupportedLimits, readonly

公开设备支持的限制（这正是创建它时所用的限制）。

queue, of type GPUQueue, readonly

此设备的主要 GPUQueue。

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

GPUDevice 具有上面的 WebIDL 定义中列出的方法。 此处未定义的那些在本文档的其他地方定义。

destroy()

销毁 设备，防止对其进行进一步操作。 未完成的异步操作将失败。

注：多次销毁设备有效。

Called on: GPUDevice this.

内容时间线 步骤：

1. unmap() 所有此设备中的 GPUBuffer。

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

设备时间线 步骤：

1. 一旦所有当前在此设备上的任何队列上排队的操作完成后，在当前时间线上发出后续步骤。

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

注：由于没有进一步的操作可以在此设备上排队，实现可以立即中止未完成的异步操作并释放资源分配，包括刚刚取消映射的映射内存。

4.5. 示例

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

GPUBuffer 表示可用于 GPU 操作的内存块。 数据以线性布局存储，这意味着分配的每个字节都可以通过它从 GPUBuffer 开始的偏移量来寻址，取决于操作的对齐限制。 一些 GPUBuffers 可以被映射，这使得内存块可以通过称为其映射的 ArrayBuffer 访问。

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

[Exposed=(Window, DedicatedWorker), SecureContext]
interface GPUBuffer {
    readonly attribute GPUSize64 size;
    readonly attribute GPUBufferUsageFlags 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, of type GPUSize64, readonly

GPUBuffer 分配的字节长度。

usage, of type GPUBufferUsageFlags, readonly

此 GPUBuffer 的允许用途。

[[internals]], 类型为 buffer internals, 只读, override

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

mapState, of type GPUBufferMapState, readonly

缓冲区的当前 GPUBufferMapState：

"unmapped"

缓冲区未映射供“this”使用。getMappedRange()。

"pending"

已请求缓冲区的映射，但尚未完成。 它可能会在 mapAsync() 中验证成功或失败。

"mapped"

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

The getter steps are:

Content timeline 步骤：

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

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

3. 返回"unmapped"。

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

当前未决的 mapAsync() 调用返回的 Promise。

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

[[mapping]], 类型为 active buffer mapping 或 null, 初始为 null

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

active buffer mapping 是一个包含以下字段的结构：

data, of type Data Block

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

mode, of type GPUMapModeFlags

地图的 GPUMapModeFlags，在对 mapAsync() 或 createBuffer() 的相应调用中指定。

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

此 GPUBuffer 映射的范围。

views, of type list<ArrayBuffer>

ArrayBuffer 通过 getMappedRange() 返回给应用程序。 它们被跟踪，因此可以在调用 unmap() 时分离它们。

使用模式 mode 和范围 range 来 初始化一个活动缓冲区映射 ：

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

2. 让 data 为 ? CreateByteDataBlock(size)。

   注： 这可能会导致抛出 RangeError。 为了一致性和可预测性：

   • 对于 new ArrayBuffer() 在给定时刻成功的任何大小，此分配应该在那一刻成功。

   • 对于 new ArrayBuffer() 确定性 抛出 RangeError 的任何大小，此分配也应该。

3. 返回一个 active buffer mapping 且:

   • data 设置为 data.

   • mode 设置为 mode.

   • range 设置为 range.

   • views 设置为 [].

GPUBuffer 的 internal object 是 buffer internals，它使用以下 device timeline slots 扩展 internal object：

state

缓冲区的当前内部状态：

"available"

缓冲区可用于队列操作（除非它是 无效的）。

"unavailable"

由于被映射，缓冲区可能无法用于队列操作。

"destroyed"

由于被 destroy()ed，缓冲区可能无法用于任何操作。

5.1.1. GPUBufferDescriptor

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

GPUBufferDescriptor 拥有以下成员：

size, of type GPUSize64

缓冲大小，以字节为单位。

usage, of type GPUBufferUsageFlags

缓冲的可用用途。

mappedAtCreation, of type boolean, defaulting to false

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

保证即使缓冲区创建最终失败，在取消映射之前，它仍然会显示为可以写入/读取映射范围。

5.1.2. 缓冲区使用

typedef [EnforceRange] unsigned long GPUBufferUsageFlags;
[Exposed=(Window, DedicatedWorker), 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

可以映射缓冲区以供读取。（示例：使用 GPUMapMode.READ 调用 mapAsync()）

只能与 COPY_DST 结合使用。

MAP_WRITE

可以映射缓冲区以进行写入。（示例：使用 GPUMapMode.WRITE 调用 mapAsync()）

只能与 COPY_SRC 结合使用。

COPY_SRC

缓冲区可以用作复制操作的源。（示例：作为 copyBufferToBuffer() 或 copyBufferToTexture() 调用的 source 参数。）

COPY_DST

缓冲区可用作复制或写入操作的目标。（示例：作为 copyBufferToBuffer() 或 copyTextureToBuffer() 调用的“目标”参数，或作为 writeBuffer() 调用的目标。）

INDEX

该缓冲区可用作索引缓冲区。（示例：传递给 setIndexBuffer()。）

VERTEX

该缓冲区可用作顶点缓冲区。（示例：传递给 setVertexBuffer()。）

UNIFORM

该缓冲区可以用作统一缓冲区。（示例：作为 GPUBufferBindingLayout 的绑定组条目，其 buffer.type 为 "uniform"。）

STORAGE

缓冲区可以用作存储缓冲区。（示例：作为具有 buffer 的 GPUBufferBindingLayout 的绑定组条目。type 为 "storage" 或 "read- 仅存储“。）

INDIRECT

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

QUERY_RESOLVE

缓冲区可用于捕获查询结果。（示例：作为 resolveQuerySet() 调用的“目标”参数。）

5.1.3. 缓冲区创建

createBuffer(descriptor)

创建一个 GPUBuffer.

Called on: GPUDevice this.

Arguments:

Arguments for the GPUDevice.createBuffer(descriptor) method.

Parameter	Type	Nullable	Optional	Description
descriptor	GPUBufferDescriptor	✘	✘	要创建的 GPUBuffer 的描述。

Returns: GPUBuffer

Content timeline steps:

1. 使 [b, bi] 为 ! create a new WebGPU object(this, GPUBuffer, descriptor).

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

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

4. 如果 descriptor.mappedAtCreation 为 true:

   1. 设置 b.[[mapping]] 为 ? initialize an active buffer mapping，模式为 WRITE 范围为 [0, descriptor.size].

5. 在 this 的 设备时间线上发起initialization steps

6. 返回 b。

Device timeline initialization steps:

1. 如果以下任何条件没有满足， generate a validation error, 使 bi 无效, 并停止。

   • device 必须 有效。

   • descriptor.usage 必须不为 0.

   • descriptor.usage 必须为 device’s allowed buffer usages 的一个子集。

   • 如果 descriptor.usage 包含 MAP_READ:

     • descriptor.usage 不得包含除 COPY_DST 之外的其他标志。

   • 如果 descriptor.usage 包含 MAP_WRITE:

     • descriptor.usage 不得包含除 COPY_SRC 之外的其他标志。

   • 如果 descriptor.size 必须 ≤ device.[[device]].[[limits]].maxBufferSize.

   • 如果 descriptor.mappedAtCreation 为 true:

     • descriptor.size 必须为 4 的倍数。

注：如果缓冲区创建失败，并且 descriptor.mappedAtCreation 为“false”，则对 mapAsync() 的任何调用都将被拒绝，因此分配用于启用映射的任何资源都可以而且可能是丢弃或回收。

1. 如果 descriptor.mappedAtCreation 为“真”：

   1. 将 bi.state 设置为“unavailable”。

   另外：

   1. 将 bi.state 设置为“available”。

2. 为 bi 创建设备分配 每个字节都为零。

   如果分配失败且没有副作用，生成内存不足错误，生成 bi 无效，然后返回。

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

5.1.4. 缓冲区销毁

不再需要 GPUBuffer 的应用程序可以通过调用 destroy() 选择在垃圾收集之前失去对它的访问。 销毁缓冲区也会取消映射，释放为映射分配的所有内存。

注：这允许用户代理在所有先前使用它提交的操作完成后回收与 GPUBuffer 关联的 GPU 内存。

destroy()

销毁 GPUBuffer.

注：多次销毁缓冲区是有效的。

Called on: GPUBuffer this.

Returns: undefined

内容时间线 步骤：

1. 调用 this.unmap().

2. 在 this.[[device]] 的 Device timeline 上发布后续步骤。

Device timeline steps:

1. 将 this.[[internals]].state 设置为“destroyed”。

注：由于没有进一步的操作可以使用此缓冲区排队，因此实现可以释放资源分配，包括刚刚取消映射的映射内存。

5.2. 缓冲区映射

应用程序可以请求映射 GPUBuffer，以便它们可以通过代表 GPUBuffer 分配部分的 ArrayBuffer 访问其内容。异步请求映射 GPUBuffer mapAsync() 以便用户代理可以确保 GPU 在应用程序可以访问其内容之前完成使用 GPUBuffer。 映射的 GPUBuffer 不能被 GPU 使用，必须使用 unmap() 取消映射，然后才能将使用它的工作提交到 队列时间线。

一旦 GPUBuffer 被映射，应用程序可以使用 getMappedRange() 同步请求访问其内容范围。 返回的 ArrayBuffer 只能通过 unmap() detached（直接，或通过 GPUBuffer.destroy() 或 GPUDevice.destroy())，并且不能是transferred。 TypeError 被试图这样做的任何其他操作抛出。

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

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

READ

仅对使用 MAP_READ 用法创建的缓冲区有效。

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

WRITE

仅对使用 MAP_WRITE 用法创建的缓冲区有效。

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

注：由于 MAP_WRITE 缓冲区使用只能与 COPY_SRC 缓冲区使用相结合，写入映射永远不会返回 GPU 生成的值，返回的 ArrayBuffer 将 仅包含默认初始化数据（零）或网页在先前映射期间写入的数据。

mapAsync(mode, offset, size)

映射 GPUBuffer 的给定范围，并在 GPUBuffer 的内容准备好使用 getMappedRange() 访问时解析返回的 Promise。

返回的 Promise 的决议仅表示缓冲区已被映射。 它不保证 content timeline 可见的任何其他操作的完成，尤其不暗示从 onSubmittedWorkDone() 或 其他 {{GPUBuffer 上的 mapAsync()}} 已解决。

从 onSubmittedWorkDone() 返回的 Promise 的决议确实意味着在 GPUBuffer 上完成该调用之前进行的 mapAsync() 用于该队列的最后专门调用。

Called on: GPUBuffer this.

Arguments:

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

Parameter	Type	Nullable	Optional	Description
mode	GPUMapModeFlags	✘	✘	缓冲区是否应该映射为读取或写入。
offset	GPUSize64	✘	✔	以字节为单位的偏移量到缓冲区到要映射的范围的开始。
size	GPUSize64	✘	✔	要映射的范围的大小（以字节为单位）。

Returns: Promise<undefined>

内容时间线 步骤：

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

2. 如果 this.[[pending_map]] 不是 null：

   1. 返回 a promise rejected with OperationError。

3. 让p 成为新的Promise。

4. 将 this.[[pending_map]] 设置为 p。

5. 发布验证步骤 在 this 的 Device timeline 上。[[device]]。

6. 返回 p。

设备时间线 validation steps:

1. 如果 size 为 undefined:

   1. 使 rangeSize 为 max(0, this.size - offset).

   否则：

   1. 使 rangeSize 为 size.

2. 如果以下任何条件未满足：

   • this 是一个 有效 GPUBuffer。

   • this.[[internals]].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.

   Then:

   1. 在 contentTimeline 上发起 map failure steps

   2. Generate a validation error.

   3. 返回。

3. 设置 this.[[internals]].state 为 "unavailable".

   注：由于缓冲区已映射，因此其内容不能在此完成和 unmap() 之间更改。

4. 如果 this.[[device]] 丢失，或者当它 becomes lost 时：

   1. 在内容时间线上运行地图失败步骤。

   否则，在未指定的点：

   • 在完成当前使用this的排队操作后，

   • 并且不晚于 device timeline 收到 all currently-enqueued operations 完成通知后的下一个 device timeline 操作（无论它们是否 使用 这个),

   运行以下步骤：

   1. 让 internalStateAtCompletion 是 this.[[internals]].state。

      注：当且仅当此时缓冲区由于 unmap() 调用再次变为“available”，则 [[pending_map ]] != p 下面，所以映射将不会在下面的步骤中成功。

   2. 让 dataForMappedRegion 是this的内容 从偏移量 offset 开始，对于 rangeSize 字节。

   3. 在 contentTimeline 上运行map success steps。

内容时间线 map success steps:

1. 如果 this.[[pending_map]] != p:

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

   1. 断言 p 被拒绝。

   2. 返回。

2. 断言 p 被挂起。

3. 断言 internalStateAtCompletion 为 "unavailable".

4. 使 mapping 为 initialize an active buffer mapping，模式为 mode 且范围为 [offset, offset + rangeSize].

   如果分配失败：

   1. 设置 this.[[pending_map]] 为 null, 且以一个 RangeError reject p。

   2. 返回。

5. 设置 mapping.data 的内容为 dataForMappedRegion.

6. 设置 this.[[mapping]] 为 mapping.

7. 设置 this.[[pending_map]] 为 null,且 resolve p.

Content timeline map failure steps:

1. 如果 this.[[pending_map]] != p:

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

   1. 断言 p 已被拒绝。

   2. 返回。

2. 断言 p 仍被挂起。

3. 设置 this.[[pending_map]] 为 null,并且以一个 OperationError 拒绝 p

getMappedRange(offset, size)

返回一个 ArrayBuffer，其中包含给定映射范围内 GPUBuffer 的内容。

Called on: GPUBuffer this.

Arguments:

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

Parameter	Type	Nullable	Optional	Description
offset	GPUSize64	✘	✔	缓冲区中以字节为单位的偏移量，以从中返回缓冲区内容。
size	GPUSize64	✘	✔	要返回的 ArrayBuffer 的字节大小。

Returns: ArrayBuffer

内容时间线 步骤：

1.如果size 缺失：

1. 让 rangeSize 为最大值（0，this.size - offset）。

否则，让 rangeSize 为 size。

1. 如果不满足以下任何条件，则抛出 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，即使它是 无效的，因为 内容时间线 可能不知道它是无效的。

2. 使 data 为 this.[[mapping]].data.

3. 使 view 为 ! create an ArrayBuffer，大小为 rangeSize, 但是它的指针在偏移处（offset - [[mapping]].range[0]）可变地引用了 data 的内容。

   注：这里可能不会抛出 RangeError，因为 data 已经在 mapAsync() 或 createBuffer() 期间分配。

4. 设置 view.[[ArrayBufferDetachKey]] 为 "WebGPUBufferMapping".

   注：如果尝试 DetachArrayBuffer，这会导致抛出 TypeError，unmap() 除外。

5. Append view 至 this.[[mapping]].views.

6. 返回 view.

注：如果 getMappedRange() 在没有检查地图状态的情况下成功，用户代理应考虑发出开发人员可见的警告，方法是等待 mapAsync() 成功，查询 "mapped" 的 mapState，或等待稍后的 onSubmittedWorkDone() 调用成功。

unmap()

取消 GPUBuffer 的映射范围并使其内容再次可供 GPU 使用。

Called on: GPUBuffer this.

Returns: undefined

内容时间线 步骤：

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

   1. 以一个 AbortError 拒绝 this.[[pending_map]]

   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]] 的 Device timeline 上运行后续步骤。

设备时间线 步骤：

1. 如果this.[[device]]是无效的，返回。

2. 如果 bufferUpdate 不为 null：

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

      队列时间线 步骤：

      1.更新this的内容 在偏移 bufferUpdate.offset 与数据 bufferUpdate.data 处。

3. 将 this.[[internals]].state 设置为 "available"。

6. 纹理与纹理视图

6.1. GPUTexture

问题：删除此定义：texture

一张纹理由一个或多个纹理子资源组成，每个纹理子资源由 mipmap level 唯一标识，并且仅对于 2d 纹理，array layer 和 [ =方面=]。

一个 texture subresource 是一个 subresource：每个都可以在一个 usage scope 中用于不同的 internal usages。

mipmap level 中的每个子资源在每个空间维度上大约是较低级别中相应资源大小的一半（参见 logical miplevel-specific texture extent）。 级别 0 中的子资源具有纹理本身的尺寸。 这些通常用于表示纹理的细节级别。 GPUSampler 和 WGSL 提供了在细节层次之间选择和插值的工具，明确地或自动地。

"2d" 纹理可以是array layer的数组。 层中的每个子资源与其他层中的相应资源大小相同。 对于非二维纹理，所有子资源的数组层索引均为 0。

每个子资源都有一个方面。 颜色纹理只有一个方面：color。 深度或模板格式 纹理可能有多个方面： depth 方面，stencil 方面，或两者兼而有之，并且可以以特殊方式使用，例如 {{GPURenderPassDescriptor/depthStencilAttachment} } 和 "depth" 绑定。

"3d" 纹理可能有多个 切片，每个都是纹理中特定 z 值处的二维图像。 切片不是单独的子资源。

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

    undefined destroy();

    readonly attribute GPUIntegerCoordinate width;
    readonly attribute GPUIntegerCoordinate height;
    readonly attribute GPUIntegerCoordinate depthOrArrayLayers;
    readonly attribute GPUIntegerCoordinate mipLevelCount;
    readonly attribute GPUSize32 sampleCount;
    readonly attribute GPUTextureDimension dimension;
    readonly attribute GPUTextureFormat format;
    readonly attribute GPUTextureUsageFlags usage;
};
GPUTexture includes GPUObjectBase;

GPUTexture 具有以下属性

width, of type GPUIntegerCoordinate, readonly

此 GPUTexture 的宽度。

height, of type GPUIntegerCoordinate, readonly

此 GPUTexture 的高度。

depthOrArrayLayers, of type GPUIntegerCoordinate, readonly

此 GPUTexture 的深度或层数。

mipLevelCount, of type GPUIntegerCoordinate, readonly

此 GPUTexture 的 mip 级别数。

sampleCount, of type GPUSize32, readonly

GPUTexture 的采样数。

dimension, of type GPUTextureDimension, readonly

此 GPUTexture 的每个子资源的纹素集的维度。

format, of type GPUTextureFormat, readonly

此 GPUTexture 的格式。

usage, of type GPUTextureUsageFlags, readonly

此 GPUTexture 的允许用法。

GPUTexture 有以下内部插槽：

[[size]], 类型为 GPUExtent3D

纹理的大小（与 width、height 和 depthOrArrayLayers 属性相同）。

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

在这个 GPUTexture 上创建视图时可以使用 GPUTextureViewDescriptor.format 的一组 GPUTextureFormat。

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

如果纹理被销毁，它就不能再用于任何操作，并且它的底层内存可以被释放。

texture 的 logical miplevel-specific texture extent 是 texture 在特定 miplevel 的纹素大小。 它是通过以下过程计算的：

特定miplevel物理纹理尺寸是指在特定mip级别的纹理大小（以像素为单位），包括可能的额外填充以形成纹理中的完整 [ =像素块= ]。 它通过以下步骤计算得出：

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, of type GPUExtent3D

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

mipLevelCount, of type GPUIntegerCoordinate, defaulting to 1

纹理将包含的 mip 级别数。

sampleCount, of type GPUSize32, defaulting to 1

纹理的样本数量。sampleCount > 1 表示多重采样纹理。

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

纹理是一维的、二维层的数组还是三维的。

format, of type GPUTextureFormat

纹理的格式。

usage, of type GPUTextureUsageFlags

纹理的允许用途。

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

指定在调用 createView() 时允许的 format 值（除实际的 format 之外）。

注： 向该列表添加格式可能会对性能产生显著影响，因此最好避免不必要地添加格式。

实际性能影响高度依赖于目标系统；开发者必须测试各种系统，以了解其对特定应用的影响。 例如，在某些系统上，任何具有 format 或 viewFormats 条目（包括 "rgba8unorm-srgb"）的纹理性能都会比一个没有该项的 "rgba8unorm" 纹理低一些。 在其他系统上，针对其他格式和格式组合也存在类似的注意事项。

此列表中的格式必须与纹理格式纹理视图格式兼容。

如果两个GPUTextureFormats format 和 viewFormat 是纹理视图格式兼容的：

• format 等于 viewFormat, 或

• format 和 viewFormat 区别仅在于它们是否为 srgb 格式（具有 -srgb 后缀）。

问题(gpuweb/gpuweb#168): 定义更大的兼容类。

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

"1d"

指定具有一维宽度的纹理。

"2d"

指定具有宽度和高度并且可能具有层的纹理。 只有 "2d" 纹理可以有 mipmaps、多重采样、使用压缩或深度/模板格式，并用作渲染附件。

"3d"

指定具有宽度、高度和深度的纹理。

6.1.2. 纹理使用

typedef [EnforceRange] unsigned long GPUTextureUsageFlags;
[Exposed=(Window, DedicatedWorker), 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

纹理可以用作复制操作的来源。 （示例：作为 copyTextureToTexture() 或 copyTextureToBuffer() 调用的 source 参数。）

COPY_DST

纹理可用作复制或写入操作的目标。 （示例：作为 copyTextureToTexture() 或 copyBufferToTexture() 调用的“目标”参数，或作为 writeTexture() 调用的目标。）

TEXTURE_BINDING

纹理可以绑定用作着色器中的采样纹理（示例：作为绑定组 GPUTextureBindingLayout 的条目。）

STORAGE_BINDING

纹理可以绑定用作着色器中的存储纹理（示例：作为 GPUStorageTextureBindingLayout 的绑定组条目。）

RENDER_ATTACHMENT

纹理可以用作渲染过程中的颜色或深度/模板附件。 （示例：作为 GPURenderPassColorAttachment.view 或 GPURenderPassDepthStencilAttachment.view。）

6.1.3. 纹理创建

createTexture(descriptor)

创建一个 GPUTexture.

Called on: GPUDevice this.

Arguments:

Arguments for the GPUDevice.createTexture(descriptor) method.

Parameter	Type	Nullable	Optional	Description
descriptor	GPUTextureDescriptor	✘	✘	要创建的 GPUTexture 的描述。

Returns: GPUTexture

内容时间线 步骤：

1. ? validate GPUExtent3D shape(descriptor.size).

2. ? 使用 this.[[device]] 验证descriptor.format 所需的纹理格式特性。

3. 验证descriptor.viewFormats中每个元素所需的 ? 纹理格式所需特性 与 this.[[device]]。

4. 使 t 为一个新的 GPUTexture 对象。

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 的 设备时间线 上发起 initialization steps。

14. 返回 t。

设备时间线 initialization steps:

1. 如果以下任何条件不满足，产生验证错误，使得 t 为 无效，并停止。

   • 验证 GPUTextureDescriptor (this, descriptor) 返回 true.

2. 设置 t.[[size]] 为 descriptor.size.

3. 设置 t.[[viewFormats]] 为 descriptor.viewFormats.

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

6.1.4. 纹理销毁

一个不再需要GPUTexture的应用可以在垃圾收集之前选择通过调用destroy()来丢失对其的访问。

注：这允许用户代理在使用它完成所有先前提交的操作后回收与GPUTexture关联的GPU内存。

destroy()

销毁 GPUTexture.

Called on: GPUTexture this.

Returns: undefined

内容时间线 步骤：

1. 设置 this.[[destroyed]] 为 true.

6.2. GPUTextureView

一个 GPUTextureView 是对某个 GPUTexture 定义的一部分 纹理子资源 的视图。

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

GPUTextureView 局有以下内部插槽：

[[texture]]

该视图所对应的GPUTexture。

[[descriptor]]

GPUTextureViewDescriptor 描述这个纹理视图。

GPUTextureViewDescriptor 的所有可选字段均已定义。

[[renderExtent]]

对于可渲染视图，这是用于渲染的有效 GPUExtent3DDict。

注：这个范围取决于 baseMipLevel。

6.2.1. 纹理视图创建

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

GPUTextureViewDescriptor 具有以下成员：

format, of type GPUTextureFormat

纹理视图的格式。必须是纹理的 format 或在其创建过程中指定的 viewFormats 之一。

dimension, of type GPUTextureViewDimension

纹理视图的维度。

aspect, of type GPUTextureAspect, defaulting to "all"

纹理视图可以访问纹理的哪些 aspect(s)。

baseMipLevel, of type GPUIntegerCoordinate, defaulting to 0

纹理视图可访问的第一个（最详细的）mipmap 级别。

mipLevelCount, of type GPUIntegerCoordinate

纹理视图可以访问多少个 mipmap 级别，以 baseMipLevel 开头。

baseArrayLayer, of type GPUIntegerCoordinate, defaulting to 0

纹理视图可访问的第一个数组层的索引。

arrayLayerCount, of type GPUIntegerCoordinate

纹理视图可以访问多少个数组层，以 baseArrayLayer 开头。

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

"1d"

纹理被视为一维图像。

对应的WGSL类型：

• texture_1d

• texture_storage_1d

"2d"

纹理被视为单个二维图像。

对应的WGSL类型：

• texture_2d

• texture_storage_2d

• texture_multisampled_2d

• texture_depth_2d

• texture_depth_multisampled_2d

"2d-array"

纹理视图被视为二维图像的数组。

对应的WGSL类型：

• texture_2d_array

• texture_storage_2d_array

• texture_depth_2d_array

"cube"

纹理被视为立方体贴图。 该视图有 6 个数组层，对应于立方体的 [+X, -X, +Y, -Y, +Z, -Z] 面。 采样是在立方体贴图的各个面上无缝完成的。

对应的WGSL类型：

• texture_cube

• texture_depth_cube

"cube-array"

纹理被视为 n 个立方体贴图的打包数组， 每个都有 6 个数组层，对应于立方体的 [+X, -X, +Y, -Y, +Z, -Z] 面。 采样是在立方体贴图的各个面上无缝完成的。

对应的WGSL类型：

• texture_cube_array

• texture_depth_cube_array

"3d"

纹理被视为 3 维图像。

对应的WGSL类型：

• texture_3d

• texture_storage_3d