GPUDevice: Methode createBindGroupLayout()

Syntax

createBindGroupLayout(descriptor)

Parameter

descriptor

Ein Objekt, das die folgenden Eigenschaften enthält:

entries

Ein Array von Eintragsobjekten, von denen jedes eine einzelne Shader-Ressourcenbindung beschreibt, die in das GPUBindGroupLayout aufgenommen werden soll. Jeder Eintrag entspricht einem Eintrag, der in einer GPUBindGroup (erstellt durch einen Aufruf von GPUDevice.createBindGroup()) definiert wurde, die dieses GPUBindGroupLayout-Objekt als Vorlage verwendet.

label Optional

Ein String, der eine Bezeichnung angibt, die zur Identifizierung des Objekts verwendet werden kann, zum Beispiel in GPUError-Meldungen oder Konsolenwarnungen.

Eintragsobjekte

Ein Eintragsobjekt beinhaltet die folgenden Eigenschaften:

binding

Eine Zahl, die einen eindeutigen Bezeichner für diesen spezifischen Eintrag darstellt, der dem binding-Wert eines entsprechenden GPUBindGroup-Eintrags entspricht. Darüber hinaus entspricht es dem n-Indexwert des entsprechenden @binding(n)-Attributs im Shader (GPUShaderModule), das in der zugehörigen Pipeline verwendet wird.

visibility

Ein oder mehrere Bitmaskenflags, die die Shader-Stufen definieren, für die ein GPUBindGroup-Eintrag sichtbar ist, der diesem Eintrag entspricht. Mögliche Werte sind:

• GPUShaderStage.COMPUTE: Der Bindungseintrag wird für Compute-Shader zugänglich sein.
• GPUShaderStage.FRAGMENT: Der Bindungseintrag wird für Fragment-Shader zugänglich sein.
• GPUShaderStage.VERTEX: Der Bindungseintrag wird für Vertex-Shader zugänglich sein.

Beachten Sie, dass mehrere Stufen spezifiziert werden können, indem Werte mit bitweise ODER getrennt werden, zum Beispiel: GPUShaderStage.FRAGMENT | GPUShaderStage.VERTEX.

"Ressourcen-Layout-Objekt"

Ein Objekt, das den erforderlichen Bindungsressourcentyp und die Struktur des GPUBindGroup-Eintrags definiert, der diesem Eintrag entspricht. Diese Eigenschaft kann eines von buffer, externalTexture, sampler, storageTexture oder texture sein, deren Objektstrukturen im nächsten Abschnitt beschrieben werden.

Ressourcen-Layout-Objekte

Das Ressourcen-Layout-Objekt kann eines der folgenden sein (siehe auch GPUDevice.createBindGroup() für Details, wie die erforderlichen Ressourcen für jeden Eintrag strukturiert sind):

• buffer: Gibt an, dass der entsprechende GPUBindGroup-Eintrag ein GPUBufferBinding-Objekt ist, das einen GPUBuffer plus offset- und size-Werte enthält. Ein buffer Ressourcen-Layout-Objekt kann die folgenden Eigenschaften enthalten:

  hasDynamicOffset Optional

  Ein Boolean. Wenn auf true gesetzt, zeigt es an, dass diese Bindung einen dynamischen Offset erfordert, beispielsweise wenn er während eines Aufrufs von GPURenderPassEncoder.setBindGroup() festgelegt wird. Wenn ausgelassen, wird hasDynamicOffset standardmäßig auf false gesetzt.

  minBindingSize Optional

  Eine Zahl, die die minimal zulässige Größe, in Bytes, gebundener Buffer angibt. Wenn ausgelassen, wird minBindingSize standardmäßig auf 0 gesetzt. Wenn der Wert 0 ist, wird die minimale Buffergröße während der Pipelinenerstellung ignoriert und stattdessen von ausgegebenen Zeichen-/Verteilkommandos validiert.

  type Optional

  Ein enumerierter Wert, der den erforderlichen Typ für GPUBuffers angibt, die an diese Bindung gebunden sind (siehe GPUDevice.createBuffer() für weitere Informationen zu Buffer-Typen). Mögliche Werte sind:

  • "read-only-storage": Ein Nur-Lese-Buffer, erstellt mit einer usage von GPUBufferUsage.STORAGE.
  • "storage": Ein beschreibbarer Buffer, erstellt mit einer usage von GPUBufferUsage.STORAGE.
  • "uniform": Ein Buffer, erstellt mit einer usage von GPUBufferUsage.UNIFORM.

  Wenn ausgelassen, wird type standardmäßig auf "uniform" gesetzt.

• externalTexture: Gibt an, dass der entsprechende GPUBindGroup-Eintrag ein GPUExternalTexture-Objekt ist. Ein externalTexture Ressourcen-Layout-Objekt ist leer — {}.

• sampler: Gibt an, dass der entsprechende GPUBindGroup-Eintrag ein GPUSampler-Objekt ist. Ein sampler Ressourcen-Layout-Objekt kann die folgenden Eigenschaften enthalten:

  type Optional

  Ein enumerierter Wert, der den erforderlichen Typ für GPUSamplers angibt, die an diese Bindung gebunden sind (siehe GPUDevice.createSampler() für weitere Informationen zu Sampler-Typen). Mögliche Werte sind:

  • "comparison": Ein Vergleichs-Sampler.
  • "filtering": Ein Filter-Sampler.
  • "non-filtering": Ein Nicht-Filter-Sampler.

  Wenn ausgelassen, wird type standardmäßig auf "filtering" gesetzt.

• storageTexture: Gibt an, dass der entsprechende GPUBindGroup-Eintrag ein GPUTextureView-Objekt ist. Ein storageTexture Ressourcen-Layout-Objekt kann die folgenden Eigenschaften enthalten:

  access Optional

  Ein enumerierter Wert, der angibt, ob die an diese Bindung gebundenen Texturansichten für Lese- und/oder Schreibzugriff gebunden werden. Mögliche Werte sind:

  • "read-only": Ermöglicht WGSL-Code, Speichertexturen zu lesen.
  • "read-write": Ermöglicht WGSL-Code, Speichertexturen zu lesen und zu schreiben.
  • "write-only": Der Standardwert; ermöglicht WGSL-Code, in Speichertexturen zu schreiben.

  Die "read-only" und "read-write" Werte können nur verwendet werden, wenn die "readonly_and_readwrite_storage_textures" WGSL-Spracherweiterung in WGSLLanguageFeatures vorhanden ist. Wenn dies nicht der Fall ist, wird ein GPUValidationError erzeugt.

  format

  Ein enumerierter Wert, der das erforderliche Format der an diese Bindung gebundenen Texturansichten spezifiziert. Siehe die Spezifikation im Abschnitt Texturformate für alle verfügbaren format-Werte. Siehe auch Tier 1 und Tier 2 Texturformate.

  Hinweis: Die Verwendung des bgra8unorm-Formats für Nur-Lese-Speichertexturen ist veraltet. Die Spezifikation verbietet dies explizit, da dieses Format für Schreibzugriff gedacht ist und nicht portabel ist. Jegliche Browserunterstützung für diese Kombination wird als Bug angesehen.

  viewDimension Optional

  Ein enumerierter Wert, der die erforderliche Dimension für an diese Bindung gebundene Texturansichten spezifiziert. Mögliche Werte sind:

  • "1d": Die Textur wird als eindimensionales Bild betrachtet.
  • "2d": Die Textur wird als einzelnes zweidimensionales Bild betrachtet.
  • "2d-array": Die Textur wird als Array von zweidimensionalen Bildern betrachtet.
  • "cube": Die Textur wird als Würfelkarte betrachtet. Die Ansicht hat 6 Array-Ebenen, die den [+X, -X, +Y, -Y, +Z, -Z]-Flächen des Würfels entsprechen. Das Abtasten erfolgt nahtlos über die Flächen der Würfelkarte.
  • "cube-array": Die Textur wird als gepacktes Array von n Würfelkarten betrachtet, jede mit 6 Array-Ebenen, die den [+X, -X, +Y, -Y, +Z, -Z]-Flächen des Würfels entsprechen. Das Abtasten erfolgt nahtlos über die Flächen der Würfelkarten.
  • "3d": Die Textur wird als dreidimensionales Bild betrachtet.

  Wenn ausgelassen, wird viewDimension standardmäßig auf "2d" gesetzt.

• texture: Gibt an, dass der entsprechende GPUBindGroup-Eintrag ein GPUTextureView-Objekt ist. Ein texture Ressourcen-Layout-Objekt kann die folgenden Eigenschaften enthalten:

  multisampled Optional

  Ein Boolean. Ein Wert von true gibt an, dass die an diese Bindung gebundenen Texturansichten multi-abgetastet sein müssen. Wenn ausgelassen, wird multisampled standardmäßig auf false gesetzt.

  sampleType Optional

  Ein enumerierter Wert, der den erforderlichen Abtasttyp für an diese Bindung gebundene Texturansichten spezifiziert (siehe GPUDevice.createTexture() für weitere Informationen über Texturansichtstypen). Mögliche Werte sind:

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

  Wenn ausgelassen, wird sampleType standardmäßig auf "float" gesetzt.

  viewDimension Optional

  Ein enumerierter Wert, der die erforderliche Dimension für an diese Bindung gebundene Texturansichten spezifiziert. Mögliche und Standardwerte sind die gleichen wie für storageTexture Ressourcen-Layout-Objekte — siehe oben.

Rückgabewert

Eine Instanz des GPUBindGroupLayout-Objekts.

Validierung

Die folgenden Kriterien müssen erfüllt sein, wenn createBindGroupLayout() aufgerufen wird, andernfalls wird ein GPUValidationError erzeugt, und ein ungültiges GPUBindGroupLayout-Objekt wird zurückgegeben:

• Jeder Eintrag hat einen eindeutigen binding-Wert.
• Jeder Eintrag hat einen binding-Wert, der kleiner als das maxBindingsPerBindGroup Limit des GPUDevice ist.
• Die Anzahl der Einträge überschreitet nicht die Bindungsslotbeschränkungen.
• Nur ein Ressourcen-Layout-Objekt ist pro Eintrag definiert.
• Wenn die visibility eines Eintrags GPUShaderStage.VERTEX enthält:
  • Wenn das Ressourcen-Layout-Objekt ein buffer ist, ist sein type nicht "storage".
  • Sein Ressourcen-Layout-Objekt ist kein storageTexture.
• Wenn das Ressourcen-Layout-Objekt eines Eintrags ein texture ist und sein multisampled-Wert true ist:
  • Seine viewDimension ist "2d".
  • Sein sampleType ist nicht "float".
• Wenn das Ressourcen-Layout-Objekt eines Eintrags ein storageTexture ist:
  • Seine viewDimension ist nicht "cube" oder "cube-array".
  • Sein format ist ein Format, das Speicherverwendung unterstützt.

Beispiele

Einfaches Beispiel

Unser einfaches Compute-Demo zeigt ein Beispiel für die Erstellung eines Bindungsgruppenlayouts und dessen Verwendung als Vorlage bei der Erstellung einer Bindungsgruppe.

// …

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

// …

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Die WebGPU API