GPUComputePassEncoder: setBindGroup() 方法

語法

setBindGroup(index, bindGroup)
setBindGroup(index, bindGroup, dynamicOffsets)
setBindGroup(index, bindGroup, dynamicOffsets, dynamicOffsetsStart,
             dynamicOffsetsLength)

引數

index

要設定繫結組的索引。這對應於著色器程式碼（GPUShaderModule）中相關管線使用的 @group(n) 屬性的 n 索引值。

bindGroup

用於後續計算命令的 GPUBindGroup，或者 null，在這種情況下，給定槽位中任何先前設定的繫結組都會被取消設定。

dynamicOffsets 可選

一個值，用於指定 bindGroup 中 hasDynamicOffset: true 設定的每個條目的偏移量（以位元組為單位）（即，在建立 bindGroup 所基於的 GPUBindGroupLayout 物件的 GPUDevice.createBindGroupLayout() 呼叫中）。此值可以是

• 一個數字陣列，指定不同的偏移量。
• 一個包含指定偏移量的數字的 Uint32Array。

如果為 dynamicOffsets 指定了 Uint32Array 值，則以下兩個引數也是必需的

dynamicOffsetsStart

一個數字，指定從 dynamicOffsetsData 中開始讀取動態偏移量資料的陣列元素的偏移量。

dynamicOffsetsLength

一個數字，指定要從 dynamicOffsetsData 中讀取的動態偏移量值的數量。

返回值

無 (Undefined)。

異常

對於使用 Uint32Array 值作為 dynamicOffsets 的 setBindGroup() 呼叫，如果以下條件成立，將丟擲 RangeError DOMException：

• dynamicOffsetsStart 小於 0。
• dynamicOffsetsStart + dynamicOffsetsLength 大於 dynamicOffsets.length。

驗證

呼叫 dispatchWorkgroups() 時必須滿足以下條件，否則會生成 GPUValidationError 並且 GPUComputePassEncoder 會失效。

• index 小於或等於 GPUDevice 的 maxBindGroups 限制。
• dynamicOffsets.length 等於 bindGroup 中 hasDynamicOffset: true 設定的條目數。
• 對於繫結 buffer 的 type 為 "uniform" 的 bindGroup 條目（參見 GPUDevice.createBindGroupLayout()），dynamicOffsets 中的每個數字都是 GPUDevice 的 minUniformBufferOffsetAlignment 限制 的倍數。
• 對於繫結 buffer 的 type 為 "storage" 或 "read-only-storage" 的 bindGroup 條目（參見 GPUDevice.createBindGroupLayout()），dynamicOffsets 中的每個數字都是 GPUDevice 的 minStorageBufferOffsetAlignment 限制 的倍數。
• 對於每個 bindGroup 條目，繫結的 buffer 的 offset，加上對應的佈局條目的 minBindingSize，再加上 dynamicOffsets 中指定的相應動態偏移量，都小於或等於繫結的 buffer 的 size。

示例

設定繫結組

在我們 基礎計算演示 中，透過 GPUCommandEncoder 記錄了多個命令。其中大多數命令源自透過 beginComputePass() 建立的 GPUComputePassEncoder。此處使用的 setBindGroup() 呼叫是最簡單的形式，僅指定了索引和繫結組。

const BUFFER_SIZE = 1000;

// …

// Create GPUCommandEncoder to encode commands to issue to the GPU
const commandEncoder = device.createCommandEncoder();

// Initiate render pass
const passEncoder = commandEncoder.beginComputePass();

// Issue commands
passEncoder.setPipeline(computePipeline);
passEncoder.setBindGroup(0, bindGroup);
passEncoder.dispatchWorkgroups(Math.ceil(BUFFER_SIZE / 64));

// End the render pass
passEncoder.end();

// Copy output buffer to staging buffer
commandEncoder.copyBufferToBuffer(
  output,
  0, // Source offset
  stagingBuffer,
  0, // Destination offset
  BUFFER_SIZE,
);

// End frame by passing array of command buffers to command queue for execution
device.queue.submit([commandEncoder.finish()]);

// …

取消設定繫結組

// Set bind group in slot 0
passEncoder.setBindGroup(0, bindGroup);

// Later, unset bind group in slot 0
passEncoder.setBindGroup(0, null);

規範

瀏覽器相容性

另見

• WebGPU API