GPUDevice: createBindGroupLayout() Methode

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 in einer GPUBindGroup (erstellt über einen Aufruf von GPUDevice.createBindGroup()), das dieses GPUBindGroupLayout-Objekt als Vorlage verwendet.

label Optional

Eine Zeichenfolge, die ein Label bereitstellt, das verwendet werden kann, um das Objekt zu identifizieren, beispielsweise in GPUError-Nachrichten oder Konsolenwarnungen.

Ein Eintragsobjekt enthält die folgenden Eigenschaften:

binding

Eine Zahl, die eine eindeutige Kennung für diesen speziellen Eintrag darstellt, die mit dem binding Wert eines entsprechenden GPUBindGroup-Eintrags übereinstimmt. 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

Einer oder mehrere bitweise Flags, die die Shader-Stufen definieren, denen ein GPUBindGroup-Eintrag, der diesem Eintrag entspricht, sichtbar sein wird. Mögliche Werte sind:

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

Beachten Sie, dass mehrere Stufen durch Trennen der Werte mit bitweise OR angegeben werden können, zum Beispiel: GPUShaderStage.FRAGMENT | GPUShaderStage.VERTEX.

"Ressourcenlayout-Objekt"

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

Das Ressourcenlayout-Objekt kann eines der folgenden sein (siehe auch GPUDevice.createBindGroup() für Details zur Strukturierung der erforderlichen Ressourcen für jeden Eintrag):

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

  hasDynamicOffset Optional

  Ein boolescher Wert. Wenn auf true gesetzt, zeigt es an, dass diese Bindung einen dynamischen Offset erfordert, zum Beispiel, wie während eines Aufrufs von GPURenderPassEncoder.setBindGroup() gesetzt. Wenn weggelassen, wird hasDynamicOffset auf false gesetzt.

  minBindingSize Optional

  Eine Zahl, die die minimal erlaubte Größe, in Bytes, der gebundenen Puffer angibt. Wenn weggelassen, wird minBindingSize auf 0 gesetzt. Wenn der Wert 0 ist, wird die minimale Puffergröße während der Pipeline-Erstellung ignoriert und stattdessen durch ausgegebene Zeichnungs-/Verteilungsbefehle 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 einem usage von GPUBufferUsage.STORAGE erstellt wurde.
  • "storage": Ein beschreibbarer Puffer, der mit einem usage von GPUBufferUsage.STORAGE erstellt wurde.
  • "uniform": Ein Puffer, der mit einem usage von GPUBufferUsage.UNIFORM erstellt wurde.

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

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

• sampler: Gibt an, dass der entsprechende GPUBindGroup-Eintrag ein GPUSampler-Objekt sein wird. Ein sampler-Ressourcenlayout-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 Vergleichssampler.
  • "filtering": Ein Filterungssampler.
  • "non-filtering": Ein Nicht-Filterungssampler.

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

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

  access Optional

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

  • "read-only": Ermöglicht WGSL-Code das Lesen von Speichertexturen.
  • "read-write": Ermöglicht WGSL-Code das Lesen und Schreiben in Speichertexturen.
  • "write-only": Der Standardwert; Ermöglicht WGSL-Code das Schreiben in Speichertexturen.

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

  format

  Ein enumerierter Wert, der das erforderliche Format der an diese Bindung gebundenen Texturansichten angibt. Siehe den Abschnitt Texture Formats der Spezifikation für alle verfügbaren format-Werte.

  viewDimension Optional

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

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

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

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

  multisampled Optional

  Ein boolescher Wert. Ein Wert von true gibt an, dass an diese Bindung gebundene Texturansichten multi-sampled sein müssen. Wenn weggelassen, wird multisampled auf false standardmäßig gesetzt.

  sampleType Optional

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

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

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

  viewDimension Optional

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

Eine GPUBindGroupLayout-Objektinstanz.

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

• Der binding-Wert jedes Eintrags ist eindeutig.
• Der binding-Wert jedes Eintrags ist kleiner als das maxBindingsPerBindGroup Limit des GPUDevice.
• Die Anzahl der Einträge überschreitet nicht die Binding-Slot-Limits.
• Für jeden Eintrag ist nur 1 Ressourcenlayout-Objekt definiert.
• Wenn die visibility eines Eintrags GPUShaderStage.VERTEX einschließt:
  • Wenn sein Ressourcenlayout-Objekt ein buffer ist, ist sein type nicht "storage".
  • Sein Ressourcenlayout-Objekt ist kein storageTexture.
• Wenn ein Eintragsressourcenlayout-Objekt eine texture ist und sein multisampled-Wert true ist:
  • Seine viewDimension ist "2d".
  • Sein sampleType ist nicht "float".
• Wenn ein Eintragsressourcenlayout-Objekt ein storageTexture ist:
  • Seine viewDimension ist weder "cube" noch "cube-array".
  • Sein format ist ein Format, das die Speicherverwendung unterstützt.

Unser einfaches Berechnungs-Demo zeigt ein Beispiel für das Erstellen eines Bind-Group-Layouts und die Verwendung dieses als Vorlage beim Erstellen einer Bind-Group.

// …

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

// …

• Die WebGPU API