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