GPURenderBundleEncoder: setBindGroup() 方法

实验性： 这是一个实验性技术
在生产环境中使用此功能前，请仔细查看浏览器兼容性表。

安全上下文：此功能仅在安全上下文 (HTTPS) 中可用，并且在某些或所有支持的浏览器中可用。

GPURenderBundleEncoder 接口的 setBindGroup() 方法为给定索引设置后续渲染包命令要使用的 GPUBindGroup。

注意：此方法的功能与 GPURenderPassEncoder 上的等效方法 setBindGroup() 完全相同。

语法

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

参数

index

设置绑定组的索引。这与着色器代码 (GPUShaderModule) 中相应 @group(n) 属性的 n 索引值匹配，该着色器代码用于相关管道。

bindGroup

后续渲染包命令要使用的 GPUBindGroup。

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，并且 GPURenderBundleEncoder 将变为无效

index 小于或等于 GPUDevice 的 maxBindGroups 限制。
dynamicOffsets.length 与 bindGroup 中 hasDynamicOffset: true 设置的条目数相同。
对于 bindGroup 中绑定 buffer 的 type 为 "uniform" 的条目（参见 GPUDevice.createBindGroupLayout()），dynamicOffsets 中的每个数字都是 GPUDevice 的 minUniformBufferOffsetAlignment 限制的倍数。
对于 bindGroup 中绑定 buffer 的 type 为 "storage" 或 "read-only-storage" 的条目（参见 GPUDevice.createBindGroupLayout()），dynamicOffsets 中的每个数字都是 GPUDevice 的 minStorageBufferOffsetAlignment 限制的倍数。
对于每个 bindGroup 条目，绑定 buffer 的 offset 加上相应布局条目的 minBindingSize 加上 dynamicOffsets 中指定的相应动态偏移量，小于或等于绑定 buffer 的 size。

示例

function recordRenderPass(passEncoder) {
  if (settings.dynamicOffsets) {
    passEncoder.setPipeline(dynamicPipeline);
  } else {
    passEncoder.setPipeline(pipeline);
  }
  passEncoder.setVertexBuffer(0, vertexBuffer);
  passEncoder.setBindGroup(0, timeBindGroup);
  const dynamicOffsets = [0];
  for (let i = 0; i < numTriangles; ++i) {
    if (settings.dynamicOffsets) {
      dynamicOffsets[0] = i * alignedUniformBytes;
      passEncoder.setBindGroup(1, dynamicBindGroup, dynamicOffsets);
    } else {
      passEncoder.setBindGroup(1, bindGroups[i]);
    }
    passEncoder.draw(3, 1, 0, 0);
  }
}

以上代码片段摘自 WebGPU 示例 Animometer 示例。

规范

规范
WebGPU # programmable-passes-bind-groups

浏览器兼容性

BCD 表格仅在启用了 JavaScript 的浏览器中加载。

另请参阅

WebGPU API