GPUDevice: createBindGroupLayout() Methode

Syntax

createBindGroupLayout(descriptor)

Parameter

descriptor

Ein Objekt, das die folgenden Eigenschaften enthält:

entries

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

label Optional

Ein String, der ein Label angibt, das verwendet werden kann, um das Objekt beispielsweise in GPUError Meldungen oder Konsolenwarnungen zu identifizieren.

Eintragsobjekte

Ein Eintragsobjekt enthält die folgenden Eigenschaften:

binding

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

visibility

Ein oder mehrere bitweise Flags, die die Shader-Stufen definieren, für die ein GPUBindGroup Eintrag, der diesem Eintrag entspricht, sichtbar sein wird. 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 angegeben werden können, indem Werte mit bitwise OR getrennt werden, zum Beispiel: GPUShaderStage.FRAGMENT | GPUShaderStage.VERTEX.

"Resource layout object"

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

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 sein wird, das ein GPUBuffer sowie 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 für diese Bindung ein dynamischer Offset erforderlich ist, beispielsweise wie während eines Aufrufs von GPURenderPassEncoder.setBindGroup() festgelegt. Wenn nicht angegeben, ist hasDynamicOffset standardmäßig false.

  minBindingSize Optional

  Eine Zahl, die die minimal zulässige Größe, in Bytes, der gebundenen Puffer angibt. Wenn nicht angegeben, ist minBindingSize standardmäßig 0. Wenn der Wert 0 ist, wird die Mindestpuffergröße während der Pipelinenerstellung ignoriert und stattdessen durch erteilte Zeichnen/Ausführen-Befehle 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 Pufferarten). Mögliche Werte sind:

  • "read-only-storage": Ein nur lesbarer Puffer, der mit einer usage von GPUBufferUsage.STORAGE erstellt wurde.
  • "storage": Ein beschreibbarer Puffer, der mit einer usage von GPUBufferUsage.STORAGE erstellt wurde.
  • "uniform": Ein Puffer, der mit einer usage von GPUBufferUsage.UNIFORM erstellt wurde.

  Wenn nicht angegeben, ist type standardmäßig "uniform".

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

• sampler: Gibt an, dass der entsprechende GPUBindGroup Eintrag ein GPUSampler Objekt sein wird. 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 Samplertypen). Mögliche Werte sind:

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

  Wenn nicht angegeben, ist type standardmäßig "filtering".

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

  access Optional

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

  • "read-only": Ermöglicht es WGSL-Code, Speichertexturen zu lesen.
  • "read-write": Ermöglicht es WGSL-Code, Speichertexturen zu lesen und zu schreiben.
  • "write-only": Der Standardwert; ermöglicht es 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. Andernfalls wird ein GPUValidationError generiert.

  format

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

  viewDimension Optional

  Ein enumerierter Wert, der die erforderliche Dimension für die an diese Bindung gebundenen Texturansichten angibt. 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 zweidimensionaler Bilder betrachtet.
  • "cube": Die Textur wird als Würfelkarte betrachtet. Die Ansicht hat 6 Array-Layer, die den [+X, -X, +Y, -Y, +Z, -Z] Flächen des Würfels entsprechen. Abtastung 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-Layern, die den [+X, -X, +Y, -Y, +Z, -Z] Flächen des Würfels entsprechen. Abtastung erfolgt nahtlos über die Flächen der Würfelkarten.
  • "3d": Die Textur wird als dreidimensionales Bild betrachtet.

  Wenn nicht angegeben, ist viewDimension standardmäßig "2d".

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

  multisampled Optional

  Ein boolean. Ein Wert von true gibt an, dass Texturansichten, die an diese Bindung gebunden sind, multi-gesampelt sein müssen. Wenn nicht angegeben, ist multisampled standardmäßig false.

  sampleType Optional

  Ein enumerierter Wert, der den erforderlichen Sample-Typ für die an diese Bindung gebundenen Texturansichten angibt (siehe GPUDevice.createTexture() für mehr Informationen zu Texturansichtstypen). Mögliche Werte sind:

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

  Wenn nicht angegeben, ist sampleType standardmäßig "float".

  viewDimension Optional

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

Rückgabewert

Ein GPUBindGroupLayout Objektinstanz.

Validierung

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

• Der binding-Wert jedes Eintrags ist eindeutig.
• Der binding-Wert jedes Eintrags ist kleiner als der GPUDevice maxBindingsPerBindGroup Grenzwert.
• Die Anzahl der Einträge überschreitet nicht die Bindingslot-Limits.
• Nur ein Ressourcen-Layout-Objekt ist pro Eintrag definiert.
• Wenn die visibility eines Eintrags GPUShaderStage.VERTEX umfasst:
  • Ist sein Ressourcen-Layout-Objekt ein buffer, 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:
  • Ist seine viewDimension "2d".
  • Sein sampleType ist nicht "float".
• Wenn das Ressourcen-Layout-Objekt eines Eintrags ein storageTexture ist:
  • Ist seine viewDimension weder "cube" noch "cube-array".
  • Sein format ist ein Format, das die Benutzung als Speicher 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