GPUCommandEncoder: beginRenderPass() 方法

descriptor

包含以下属性的对象

colorAttachments

对象数组（请参阅 颜色附件对象结构），用于定义执行此渲染通道时将输出到的颜色附件。

depthStencilAttachment 可选

一个对象（参见 深度/模板附件对象结构），定义了将在执行此渲染传递时输出并进行测试的深度/模板附件。

label 可选

一个字符串，提供一个标签，可用于识别对象，例如在 GPUError 消息或控制台警告中。

maxDrawCount 可选

一个数字，指示渲染传递中将执行的最大绘制调用次数。某些实现使用此值来调整在渲染传递之前注入的工作的大小。除非您知道将执行更多绘制调用，否则应保留默认值 - 50000000。

occlusionQuerySet 可选

将存储此传递的遮挡查询结果的 GPUQuerySet。

timestampWrites 可选

一个对象数组，定义了在此传递中将在何处以及何时写入时间戳查询值。这些对象具有以下属性

• location：一个枚举值，指定何时执行时间戳。可用值为
  • "beginning"：时间戳与计算传递中编码的其他命令一起执行，一旦相应的 GPUCommandBuffer 被提交。
  • "end"：时间戳作为单独的时间戳附件列表的一部分执行，一旦传递结束。
• queryIndex：一个数字，指定时间戳将写入 querySet 中的索引位置。
• querySet：时间戳将写入的 GPUQuerySet。

注意：要使用时间戳查询，必须在 GPUDevice 中启用 timestamp-query 特性。

颜色附件对象可以具有以下属性

clearValue 可选

一个颜色值，用于在执行渲染传递之前清除 view 纹理。如果 loadOp 未设置为 "clear"，则忽略此值。clearValue 使用数组或对象表示四个颜色分量 r、g、b 和 a 作为十进制数。

下面是一个示例数组

js

clearValue: [0.0, 0.5, 1.0, 1.0];

等效的对象如下所示

js

clearValue: {
  r: 0.0,
  g: 0.5,
  b: 1.0,
  a: 1.0
}

如果省略 clearValue，则默认为 {r: 0, g: 0, b: 0, a: 0}。

loadOp

一个枚举值，指示在执行渲染传递之前对 view 执行的加载操作。可能的值为

• "clear"：将此附件的 clearValue 加载到渲染传递中。
• "load"：将此附件的现有值加载到渲染传递中。

注意：建议在初始值无关紧要的情况下始终使用 "clear"，因为它将在某些设备（如移动设备）上提供更好的性能。

storeOp

一个枚举值，指示在执行渲染传递之后对 view 执行的存储操作。可能的值为

• "discard"：丢弃此附件的渲染传递的结果值。
• "store"：存储此附件的渲染传递的结果值。

resolveTarget 可选

一个 GPUTextureView 对象，表示如果 view 是多采样的，则将接收此颜色附件的已解析输出的纹理子资源。

view

一个 GPUTextureView 对象，表示将为此颜色附件输出的纹理子资源。

注意：每个颜色或深度/模板附件必须是唯一的纹理子资源，并且用作附件的纹理子资源不能在渲染传递内部使用。

depthStencilAttachment 对象可以具有以下属性

depthClearValue 可选

一个数字，指示在执行渲染传递之前清除 view 的深度分量的值。如果 depthLoadOp 未设置为 "clear"，则忽略此值。

该值必须介于 0.0 和 1.0（含）之间。

depthLoadOp 可选

一个枚举值，指示在执行渲染传递之前对 view 的深度分量执行的加载操作。可能的值为

• "clear"：将此附件的 clearValue 加载到渲染传递中。
• "load"：将此附件的现有值加载到渲染传递中。

注意：建议在初始值无关紧要的情况下始终使用 "clear"，因为它将在某些设备（如移动设备）上提供更好的性能。

depthReadOnly 可选

一个布尔值。将该值设置为 true 将导致 view 的深度分量为只读。如果省略 depthReadOnly，则默认为 false。

depthStoreOp 可选

一个枚举值，指示在执行渲染传递之后对 view 的深度分量执行的存储操作。可能的值为

• "discard"：丢弃此附件的渲染传递的结果值。
• "store"：存储此附件的渲染传递的结果值。

stencilClearValue 可选

一个数字，指示在执行渲染传递之前清除 view 的模板分量的值。如果 stencilLoadOp 未设置为 "clear"，则忽略此值。

如果省略 stencilClearValue，则默认为 0。

stencilLoadOp 可选

一个枚举值，指示在执行渲染传递之前对 view 的模板分量执行的加载操作。可能的值为

• "clear"：将此附件的 clearValue 加载到渲染传递中。
• "load"：将此附件的现有值加载到渲染传递中。

注意：建议在初始值无关紧要的情况下始终使用 "clear"，因为它将在某些设备（如移动设备）上提供更好的性能。

stencilReadOnly 可选

一个布尔值。将该值设置为 true 将导致 view 的模板分量为只读。如果省略 stencilReadOnly，则默认为 false。

stencilStoreOp 可选

一个枚举值，指示在执行渲染传递之后对 view 的模板分量执行的存储操作。可能的值为

• "discard"：丢弃此附件的渲染传递的结果值。
• "store"：存储此附件的渲染传递的结果值。

view

一个 GPUTextureView 对象，表示将输出到并从此深度/模板附件读取的纹理子资源。

一个 GPURenderPassEncoder 对象实例。

调用 beginRenderPass() 时必须满足以下条件，否则将生成 GPUValidationError 并返回一个无效的 GPURenderPassEncoder。

常规

• colorAttachments.length 小于或等于 GPUDevice 的 maxColorAttachments 限制。
• 如果 colorAttachments 只包含 null 值，则提供 depthStencilAttachment。
• colorAttachments 和 depthStencilAttachment 中的所有 view 具有相等的 GPUTexture.sampleCount 值和渲染范围（GPUTexture.height、GPUTexture.width 和 GPUTexture.depthOrArrayLayers）。
• 如果设置了 occlusionQuerySet，则引用的 GPUQuerySet 的 type 为 "occlusion"。

对于颜色附件对象

• view 是可渲染的，并且 view 的格式（即在源 GPUTexture.createView() 调用的描述符中指定）是可渲染的颜色格式。
• 如果提供了 resolveTarget
  • view 的源 GPUTexture 的 sampleCount 大于 1。
  • resolveTarget 的源 GPUTexture 的 sampleCount 为 1。
  • resolveTarget 是可渲染的。
  • view 和 resolveTarget 提供视图的子资源的大小匹配。
  • view 和 resolveTarget 的格式匹配。
• 颜色附件每个样本的字节数 小于或等于 GPUDevice 的 maxColorAttachmentBytesPerSample 限制。

对于深度/模板附件对象

• view 是可渲染的，并且其格式是 深度或模板 格式。
• 如果 depthLoadOp 设置为 "clear"，则提供有效的 depthClearValue。
• 如果 view 的格式是组合的深度或模板格式，则 depthReadOnly 与 stencilReadOnly 匹配。
• 如果 view 的格式具有深度方面，并且 depthReadOnly 为 false，则提供 depthLoadOp 和 depthStoreOp。
• 如果 view 的格式具有深度方面，并且 depthReadOnly 为 true，则不提供 depthLoadOp 和 depthStoreOp。
• 如果 view 的格式具有模板方面，并且 stencilReadOnly 为 false，则提供 stencilLoadOp 和 stencilStoreOp。
• 如果 view 的格式具有模板方面，并且 stencilReadOnly 为 true，则不提供 stencilLoadOp 和 stencilStoreOp。

对于时间戳查询

• 在 GPUDevice 中启用了 timestamp-query 特性。
• 没有两个 timestampWrites 对象具有相同的 location。实际上，这意味着您每个渲染传递只能运行两个时间戳查询。
• 对于每个时间戳查询，querySet GPUQuerySet.type 为 "timestamp"，并且 queryIndex 值小于 GPUQuerySet.count。
• 没有两个 timestampWrites 对象具有相同的 queryIndex 和 querySet 对。

在我们 基本的渲染演示 中，一些命令通过 GPUCommandEncoder 记录。这些命令源自通过 beginRenderPass() 创建的 GPURenderPassEncoder

// ...

// Create GPUCommandEncoder
const commandEncoder = device.createCommandEncoder();

// Create GPURenderPassDescriptor to tell WebGPU which texture to draw into, then initiate render pass

const renderPassDescriptor = {
  colorAttachments: [
    {
      clearValue: clearColor,
      loadOp: "clear",
      storeOp: "store",
      view: context.getCurrentTexture().createView(),
    },
  ],
};

const passEncoder = commandEncoder.beginRenderPass(renderPassDescriptor);

// Draw a triangle

passEncoder.setPipeline(renderPipeline);
passEncoder.setVertexBuffer(0, vertexBuffer);
passEncoder.draw(3);

// End the render pass

passEncoder.end();

device.queue.submit([commandEncoder.finish()]);

// ...

• The WebGPU API