GPURenderPassEncoder: 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。

验证

调用 setBindGroup() 时必须满足以下条件，否则将生成 GPUValidationError 并且 GPURenderPassEncoder 会失效：

• 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。

示例

设置绑定组

在 WebGPU 示例的 Textured Cube 示例中，setBindGroup() 用于将 uniformBindGroup 绑定到索引位置 0。请查看该示例以获取完整上下文。

// …

const commandEncoder = device.createCommandEncoder();
const passEncoder = commandEncoder.beginRenderPass(renderPassDescriptor);
passEncoder.setPipeline(pipeline);
passEncoder.setBindGroup(0, uniformBindGroup);
passEncoder.setVertexBuffer(0, verticesBuffer);
passEncoder.draw(cubeVertexCount, 1, 0, 0);
passEncoder.end();
device.queue.submit([commandEncoder.finish()]);

// …

取消设置绑定组

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

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

规范

浏览器兼容性

另见

• WebGPU API