GPUCommandEncoder: beginRenderPass() 方法

語法

beginRenderPass(descriptor)

引數

描述符（descriptor）

包含以下屬性的物件：

colorAttachments

一個物件陣列（參見顏色附件物件結構），定義了執行此渲染通道時將輸出到的顏色附件。

depthStencilAttachment 可選

一個物件（參見深度/模板附件物件結構），定義了執行此渲染通道時將輸出到和進行測試的深度/模板附件。

label 可選

一個字串，提供可用於識別物件的標籤，例如在 GPUError 訊息或控制檯警告中。

maxDrawCount 可選

一個數字，表示將在渲染通道中執行的最大繪製呼叫次數。某些實現會使用此值來確定在渲染通道之前注入的工作量。除非您知道將執行更多繪製呼叫，否則應保留預設值 — 50000000。

occlusionQuerySet 可選

將儲存此通道的遮擋查詢結果的 GPUQuerySet。

timestampWrites 可選

一個物件陣列，定義此通道的時間戳查詢值寫入的位置和時間。這些物件具有以下屬性

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 API