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