GPUDevice: createBindGroupLayout() Methode

descriptor

Ein Objekt, das die folgenden Eigenschaften enthält:

entries

Ein Array von Entry-Objekten, von denen jedes eine einzelne Shader-Ressourcenbindung beschreibt, die in das GPUBindGroupLayout aufgenommen werden soll. Jedes Entry entspricht einem im GPUBindGroup definierten Eintrag (erstellt über einen GPUDevice.createBindGroup() Aufruf), das dieses GPUBindGroupLayout Objekt als Vorlage verwendet.

label Optional

Ein String, der ein Label bereitstellt, das zum Beispiel in GPUError Nachrichten oder Konsolenwarnungen zur Identifizierung des Objekts verwendet werden kann.

Ein Entry-Objekt umfasst die folgenden Eigenschaften:

binding

Eine Nummer, die einen eindeutigen Bezeichner für diesen speziellen Eintrag darstellt, der dem binding Wert eines entsprechenden GPUBindGroup Eintrags entspricht. Außerdem entspricht es dem n Indexwert des entsprechenden @binding(n) Attributs im Shader (GPUShaderModule), der in der zugehörigen Pipeline verwendet wird.

visibility

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

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

Beachten Sie, dass mehrere Stufen angegeben werden können, indem Werte mit bitweisem OR bitwise OR getrennt werden, zum Beispiel: GPUShaderStage.FRAGMENT | GPUShaderStage.VERTEX.

"Ressourcen-Layout-Objekt"

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

Das Ressourcen-Layout-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 Ressourcen-Layout-Objekt kann die folgenden Eigenschaften enthalten:

  hasDynamicOffset Optional

  Ein Boolescher Wert. Wenn auf true gesetzt, wird angezeigt, dass diese Bindung einen dynamischen Offset erfordert, zum Beispiel, wie es während eines GPURenderPassEncoder.setBindGroup() Aufrufs festgelegt wird. Wenn weggelassen, ist hasDynamicOffset standardmäßig false.

  minBindingSize Optional

  Eine Nummer, die die minimal erlaubte Größe in Bytes der gebundenen Puffer angibt. Wenn weggelassen, ist minBindingSize standardmäßig 0. Wenn der Wert 0 ist, wird die minimale Puffergröße während der Pipelineerstellung ignoriert und stattdessen durch ausgegebene Zeichen-/Dispatch-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 schreibgeschützter 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, 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 Sampler-Typen). Mögliche Werte sind:

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

  Wenn weggelassen, 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 WGSL-Code, Speicher-Texturen zu lesen.
  • "read-write": Ermöglicht WGSL-Code, Speicher-Texturen zu lesen und zu schreiben.
  • "write-only": Der Standardwert; ermöglicht WGSL-Code, Speicher-Texturen zu schreiben.

  Die Werte "read-only" und "read-write" 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 von Texturansichten angibt, die an diese Bindung gebunden sind. Siehe den Abschnitt Texture Formats in der Spezifikation für alle verfügbaren format Werte.

  viewDimension Optional

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

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

  Wenn weggelassen, 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 boolescher Wert. Ein Wert von true zeigt an, dass Texturansichten, die an diese Bindung gebunden sind, multisampled sein müssen. Wenn weggelassen, ist multisampled standardmäßig false.

  sampleType Optional

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

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

  Wenn weggelassen, ist sampleType standardmäßig "float".

  viewDimension Optional

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

Ein GPUBindGroupLayout Objektinstanz.

Die folgenden Kriterien müssen beim Aufruf von createBindGroupLayout() erfüllt sein, andernfalls 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 die GPUDevice's maxBindingsPerBindGroup Grenze.
• Die Anzahl der Einträge überschreitet nicht die Binding-Slot-Grenzen.
• Es ist nur ein Ressourcen-Layout-Objekt pro Eintrag definiert.
• Wenn die visibility eines Eintrags GPUShaderStage.VERTEX enthält:
  • Wenn sein 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 die Speicher-Nutzung unterstützt.

Unser einfaches Berechnungs-Demo zeigt ein Beispiel für die Erstellung eines Bindgruppen-Layouts und dessen Verwendung als Vorlage beim Erstellen einer Bindgruppe.

// …

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