GPUDevice: createBindGroup() 方法

语法

createBindGroup(descriptor)

参数

描述符（descriptor）

包含以下属性的对象：

entries

一个描述要暴露给着色器的资源的条目对象数组。数组中的每个对象都对应于 layout 中引用的 GPUBindGroupLayout 所描述的相应条目。每个条目对象具有以下属性：

binding

一个数字，表示此资源绑定的唯一标识符，它匹配 GPUBindGroupLayout 中相应条目的 binding 值。此外，它还匹配相关管道中使用的着色器（GPUShaderModule）中 @binding(n) 属性的 n 索引值。

resource

要绑定的资源。可以是以下之一：

• GPUBufferBinding：封装了一个 GPUBuffer；有关定义，请参阅 GPUBufferBinding 对象。
• GPUBuffer：如果使用了默认的 offset 和 size 值，则可以直接使用，而不是封装在 GPUBufferBinding 中。
• GPUExternalTexture
• GPUTextureView：可以代替 GPUExternalTexture 使用，前提是它们兼容（即，为 2D 格式且具有单个子资源，例如 dimension: "2d"）。
• GPUTexture：可以代替 GPUTextureView 使用，前提是想要一个默认视图。在此上下文中，GPUTexture 等同于使用不带参数的 GPUTexture.createView() 调用创建的 GPUTextureView 对象。
• GPUSampler

label 可选

一个字符串，提供可用于识别对象的标签，例如在 GPUError 消息或控制台警告中。

layout

entries（此绑定组的条目）将符合的 GPUBindGroupLayout。

GPUBufferBinding 对象

GPUBufferBinding 对象可以包含以下属性：

buffer

要绑定的 GPUBuffer 对象。

offset 可选

从 buffer 开始到缓冲区绑定在着色器中暴露的范围开始处的字节偏移量。如果省略，offset 默认为 0。

size 可选

缓冲区绑定的字节大小。如果省略，size 将是从 offset 开始到 buffer 结束的范围。如果同时省略 offset 和 size，则整个缓冲区都会暴露给着色器。

返回值

一个 GPUBindGroup 对象实例。

验证

调用 createBindGroup() 时必须满足以下条件，否则会生成 GPUValidationError，并返回一个无效的 GPUBindGroup 对象：

• layout GPUBindGroupLayout 中的条目数量等于 entries 中条目对象的数量。
• 对于 layout GPUBindGroupLayout 中的每个条目，entries 中相应的条目对象都绑定了正确的资源类型。例如，一个 buffer 资源布局对象在相应的绑定中指定了一个 GPUBufferBinding 对象。
• 如果资源布局对象是 buffer
  • 相应的绑定 GPUBuffer
    • 其绑定部分（由 offset 和 size 指定）完全包含在其内，并且大小非零。
    • 大小大于 buffer 资源布局的 minBindingSize。
  • 如果资源布局对象的 type 是 "uniform"
    • 绑定的 GPUBuffer 的 usage 包含 GPUBufferUsage.UNIFORM。
    • 绑定的缓冲区段的有效大小小于或等于 GPUDevice 的 maxUniformBufferBindingSize 限制。
    • 指定的 GPUBufferBinding offset 是 GPUDevice 的 minUniformBufferOffsetAlignment 限制 的倍数。
  • 如果资源布局对象的 type 是 "storage" 或 "read-only-storage"
    • 绑定的 GPUBuffer 的 usage 包含 GPUBufferUsage.STORAGE。
    • 绑定的缓冲区段的有效大小小于或等于 GPUDevice 的 maxStorageBufferBindingSize 限制。
    • 绑定的缓冲区段的有效大小是 4 的倍数。
    • 指定的 GPUBufferBinding offset 是 GPUDevice 的 minStorageBufferOffsetAlignment 限制 的倍数。
• 如果资源布局对象是 storageTexture，则相应的绑定 GPUTextureView
  • 其 dimension 等于资源布局对象的 viewDimension（有关纹理视图设置的更多详细信息，请参阅 GPUTexture.createView()）。
  • 其 format 等于资源布局对象的 sampleType。
  • 其 mipLevelCount 等于 1。
  • 是具有包含 GPUTextureUsage.STORAGE_BINDING 的 usage 的 GPUTexture 的视图。
• 如果资源布局对象是 texture，则相应的绑定 GPUTextureView
  • 其 dimension 等于资源布局对象的 viewDimension（有关纹理视图设置的更多详细信息，请参阅 GPUTexture.createView()）。
  • 其 format 与资源布局对象的 sampleType 兼容。
  • 是具有包含 GPUTextureUsage.TEXTURE_BINDING 的 usage 的 GPUTexture 的视图。
  • 是具有大于 1 的 sampleCount 的 GPUTexture 的视图（如果资源布局对象的 multisampled 属性为 true），或者等于 1（如果为 false）。

示例

基本示例

我们的 基本计算演示 展示了如何创建绑定组布局，然后将其用作创建绑定组的模板的示例。

// …

const bindGroupLayout = device.createBindGroupLayout({
  entries: [
    {
      binding: 0,
      visibility: GPUShaderStage.COMPUTE,
      buffer: {
        type: "storage",
      },
    },
  ],
});

const bindGroup = device.createBindGroup({
  layout: bindGroupLayout,
  entries: [
    {
      binding: 0,
      resource: {
        buffer: output,
      },
    },
  ],
});

// …

规范

浏览器兼容性

另见

• WebGPU API