GPUDevice: createBindGroupLayout() 方法

语法

createBindGroupLayout(descriptor)

参数

描述符（descriptor）

包含以下属性的对象：

entries

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

label 可选

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

条目对象

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

binding

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

visibility

一个或多个 按位标志，定义与此条目对应的 GPUBindGroup 条目可访问的着色器阶段。可能的值为：

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

请注意，可以通过使用 按位 OR 分隔值来指定多个阶段，例如：GPUShaderStage.FRAGMENT | GPUShaderStage.VERTEX。

"Resource layout object"

一个对象，用于定义此条目对应的 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"：一个使用 usage 为 GPUBufferUsage.STORAGE 创建的只读缓冲区。
  • "storage"：一个使用 usage 为 GPUBufferUsage.STORAGE 创建的可写缓冲区。
  • "uniform"：一个使用 usage 为 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 可选

  一个枚举值，指定绑定到此绑定的纹理视图是用于读取和/或写入访问。可能的值为：

  • "read-only"：允许 WGSL 代码读取存储纹理。
  • "read-write"：允许 WGSL 代码读取和写入存储纹理。
  • "write-only"：默认值；允许 WGSL 代码写入存储纹理。

  仅当 "readonly_and_readwrite_storage_textures" WGSL 语言扩展存在于 WGSLLanguageFeatures 中时，才能使用 "read-only" 和 "read-write" 值。如果不是这种情况，将生成一个 GPUValidationError。

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

// …

规范

浏览器兼容性

另见

• WebGPU API