querySet: 一个类型为 "timestamp" 的 GPUQuerySet，时间戳查询结果将写入其中。
beginningOfPassWriteIndex: 一个数字，指定 querySet 中写入渲染通道开始时的时间戳的查询索引。这是可选的 — 如果未定义，则不会写入通道开始时的时间戳。
endOfPassWriteIndex: 一个数字，指定 querySet 中写入渲染通道结束时的时间戳的查询索引。这是可选的 — 如果未定义，则不会写入通道结束时的时间戳。

注意：需要启用 timestamp-query 功能才能使用时间戳查询。时间戳查询值以纳秒为单位写入，但值的确定方式是实现定义的。

颜色附件对象结构

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

clearValue 可选

在执行渲染通道之前，用于清除 view 纹理的颜色值。如果 loadOp 未设置为 "clear"，则此值将被忽略。clearValue 接受一个数组或对象，表示四个颜色分量 r、g、b 和 a 的小数。

例如，您可以传入一个数组，如 [0.0, 0.5, 1.0, 1.0]，或其等效对象 { r: 0.0, g: 0.5, b: 1.0, a: 1.0 }。

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

depthSlice 可选

一个数字，表示此颜色附件将输出到的 3D 深度切片的索引，适用于 3D GPUTextureView view。指定此项后，WebGPU 可以在渲染通道内直接渲染到 3D 纹理的切片。

loadOp

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

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

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

storeOp

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

"discard"：丢弃此附件的渲染通道的最终值。
"store"：存储此附件的渲染通道的最终值。

resolveTarget 可选

一个对象，表示如果 view 是多重采样的，将接收此颜色附件解析输出的纹理子资源。这可以是以下之一

GPUTextureView
GPUTexture：可以代替 GPUTextureView 使用，前提是需要默认视图。在此上下文中，GPUTexture 等同于使用不带参数的 GPUTexture.createView() 调用创建的 GPUTextureView 对象。

view

一个对象，表示此颜色附件将输出到的纹理子资源。这可以是以下之一

GPUTextureView
GPUTexture：可以代替 GPUTextureView 使用，前提是需要默认视图。在此上下文中，GPUTexture 等同于使用不带参数的 GPUTexture.createView() 调用创建的 GPUTextureView 对象。

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

深度/模板附件对象结构

depthStencilAttachment 对象可以具有以下属性

depthClearValue 可选

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

该值必须在 0.0 到 1.0 之间（包括 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
GPUTexture：可以代替 GPUTextureView 使用，前提是需要默认视图。在此上下文中，GPUTexture 等同于使用不带参数的 GPUTexture.createView() 调用创建的 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 功能。

示例

在我们的基本渲染演示中，通过 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()]);

// …

规范

规范
WebGPU # dom-gpucommandencoder-beginrenderpass

浏览器兼容性

另见

WebGPU API

帮助改进 MDN

了解如何贡献

此页面最后由 MDN 贡献者在 2025 年 10 月 20 日修改。

在 GitHub 上查看此页面 • 报告此内容的问题