GPUDevice: createBindGroupLayout() 方法

descriptor

包含以下属性的对象

entries

一个 条目对象 数组，每个条目对象描述一个要包含在 GPUBindGroupLayout 中的单个着色器资源绑定。每个条目都对应于在 GPUBindGroup（通过 GPUDevice.createBindGroup() 调用创建）中定义的条目，该 GPUBindGroup 使用此 GPUBindGroupLayout 对象作为模板。

label 可选

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

一个条目对象包含以下属性

binding

一个数字，代表此特定条目的唯一标识符，与对应 GPUBindGroup 条目的 binding 值匹配。此外，它还与着色器中对应 @binding(n) 属性的 n 索引值匹配（GPUShaderModule）用于相关管道。

visibility

一个或多个 位标志，定义了对应于此条目的 GPUBindGroup 条目可见的着色器阶段。可能的取值是

• GPUShaderStage.COMPUTE: 绑定组条目将可供计算着色器访问。
• GPUShaderStage.FRAGMENT: 绑定组条目将可供片段着色器访问。
• GPUShaderStage.VERTEX: 绑定组条目将可供顶点着色器访问。

请注意，可以通过管道符号分隔多个值来指定多个阶段，例如

js

visibility: GPUShaderStage.FRAGMENT | GPUShaderStage.VERTEX;

"资源布局对象"

一个对象，定义了对应于此条目的 GPUBindGroup 条目所需的绑定资源类型和结构。此属性可以是 buffer、externalTexture、sampler、storageTexture 或 texture 中的一种，这些对象的结构将在下一节中描述。

资源布局对象可以是以下之一（有关每个条目所需资源的结构的详细信息，请参阅 GPUDevice.createBindGroup()）

• buffer: 指示对应 GPUBindGroup 条目将是一个 GPUBufferBinding 对象，它包含一个 GPUBuffer 以及 offset 和 size 值。一个 buffer 资源布局对象可以包含以下属性

  hasDynamicOffset 可选

  一个布尔值。如果设置为 true，则表示此绑定需要动态偏移量，例如在 GPURenderPassEncoder.setBindGroup() 调用期间设置。如果省略，hasDynamicOffset 默认为 false。

  minBindingSize 可选

  一个数字，表示绑定缓冲区的最小允许大小（以字节为单位）。如果省略，minBindingSize 默认为 0。如果值为 0，则在管道创建期间会忽略最小缓冲区大小，而是由发出的绘制/调度命令进行验证。

  type 可选

  一个枚举值，指定绑定到此绑定的 GPUBuffer 的所需类型（有关缓冲区类型的更多信息，请参阅 GPUDevice.createBuffer()）。可能的取值是

  • "read-only-storage": 一个使用 GPUBufferUsage.STORAGE 创建的只读缓冲区。
  • "storage": 一个使用 GPUBufferUsage.STORAGE 创建的可写缓冲区。
  • "uniform": 一个使用 GPUBufferUsage.UNIFORM 创建的缓冲区。

  如果省略，type 默认为 "uniform"。

• externalTexture: 指示对应 GPUBindGroup 条目将是一个 GPUExternalTexture 对象。一个 externalTexture 资源布局对象为空 - {}。
• sampler: 指示对应 GPUBindGroup 条目将是一个 GPUSampler 对象。一个 sampler 资源布局对象可以包含以下属性

  type 可选

  一个枚举值，指定绑定到此绑定的 GPUSampler 的所需类型（有关采样器类型的更多信息，请参阅 GPUDevice.createSampler()）。可能的取值是

  • "comparison": 一个比较采样器。
  • "filtering": 一个过滤采样器。
  • "non-filtering": 一个非过滤采样器。

  如果省略，type 默认为 "filtering"。

• storageTexture: 指示对应 GPUBindGroup 条目将是一个 GPUTextureView 对象。一个 storageTexture 资源布局对象可以包含以下属性

  access 可选

  一个枚举值，指定绑定到此绑定的纹理视图是绑定用于读和/或写访问。当前可能的取值是 "write-only" 和 undefined，将来打算添加更多访问模式。如果省略，默认值为 "write-only"。

  format

  一个枚举值，指定绑定到此绑定的纹理视图所需的格式。有关所有可用的 format 值，请参阅规范的 纹理格式 部分。

  viewDimension 可选

  一个枚举值，指定绑定到此绑定的纹理视图所需的维度。可能的取值是

  • "1d": 纹理被视为一维图像。
  • "2d": 纹理被视为单个二维图像。
  • "2d-array": 纹理被视为二维图像数组。
  • "cube": 纹理被视为立方体贴图。该视图有 6 个数组层，对应于立方体的 [+X, -X, +Y, -Y, +Z, -Z] 面。采样是在立方体贴图的各个面之间无缝完成的。
  • "cube-array": 纹理被视为 n 个立方体贴图的打包数组，每个数组都有 6 个数组层，对应于立方体的 [+X, -X, +Y, -Y, +Z, -Z] 面。采样是在立方体贴图的各个面之间无缝完成的。
  • "3d": 纹理被视为三维图像。

  如果省略，viewDimension 默认为 "2d"。

• texture: 指示对应 GPUBindGroup 条目将是一个 GPUTextureView 对象。一个 texture 资源布局对象可以包含以下属性

  multisampled 可选

  一个布尔值。值为 true 表示绑定到此绑定的纹理视图必须是多重采样的。如果省略，multisampled 默认为 false。

  sampleType 可选

  一个枚举值，指定绑定到此绑定的纹理视图所需的采样类型（有关纹理视图类型的更多信息，请参阅 GPUDevice.createTexture()）。可能的取值是

  • "depth"
  • "float"
  • "sint"
  • "uint"
  • "unfilterable-float"

  如果省略，sampleType 默认为 "float"。

  viewDimension 可选

  一个枚举值，指定绑定到此绑定的纹理视图所需的维度。可能的取值和默认值与 storageTexture 资源布局对象相同 - 请参阅上文。

一个 GPUBindGroupLayout 对象实例。

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

• 每个条目的 binding 值都是唯一的。
• 每个条目的 binding 值都小于 GPUDevice 的 maxBindingsPerBindGroup 限制。
• 条目的数量不能超过 绑定插槽限制。
• 每个条目只定义 1 个资源布局对象。
• 如果一个条目的 visibility 包含 GPUShaderStage.VERTEX
  • 如果其资源布局对象是 buffer，则其 type 不是 "storage"。
  • 其资源布局对象不是 storageTexture。
• 如果一个条目的资源布局对象是 texture，并且其 multisampled 值为 true
  • 其 viewDimension 为 "2d"。
  • 其 sampleType 不是 "float"。
• 如果一个条目的资源布局对象是 storageTexture
  • 其 viewDimension 不是 "cube" 或 "cube-array"。
  • 其 format 是支持存储使用的格式。

我们的 基本计算演示 展示了创建绑定组布局并将其用作模板来创建绑定组的示例。

// ...

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,
      },
    },
  ],
});

// ...

• The WebGPU API