GPURenderPassEncoder: setBindGroup() Methode

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

Experimentell: Dies ist eine experimentelle Technologie
Überprüfen Sie die Browser-Kompatibilitätstabelle sorgfältig vor der Verwendung auf produktiven Webseiten.

Sicherer Kontext: Diese Funktion ist nur in sicheren Kontexten (HTTPS) in einigen oder allen unterstützenden Browsern verfügbar.

Hinweis: Diese Funktion ist in Web Workers verfügbar.

Die setBindGroup() Methode der GPURenderPassEncoder-Schnittstelle legt die GPUBindGroup fest, die für nachfolgende Renderbefehle bei einem bestimmten Index verwendet wird.

Syntax

js
setBindGroup(index, bindGroup)
setBindGroup(index, bindGroup, dynamicOffsets)
setBindGroup(index, bindGroup, dynamicOffsets, dynamicOffsetsStart,
             dynamicOffsetsLength)

Parameter

index

Der Index, an dem die Bind-Gruppe gesetzt werden soll. Dies entspricht dem n-Indexwert des entsprechenden @group(n)-Attributs im Shader-Code (GPUShaderModule), der in der zugehörigen Pipeline verwendet wird.

bindGroup

Die GPUBindGroup, die für nachfolgende Renderbefehle verwendet werden soll, oder null, in welchem Fall eine zuvor gesetzte Bind-Gruppe im angegebenen Slot aufgehoben wird.

dynamicOffsets Optional

Ein Wert, der den Offset, in Bytes, für jeden Eintrag in bindGroup angibt, bei dem hasDynamicOffset: true gesetzt ist (d.h. in der Beschreibung des Aufrufs von GPUDevice.createBindGroupLayout(), der das GPUBindGroupLayout-Objekt erstellt hat, auf dem bindGroup basiert). Dieser Wert kann sein:

  • Ein Array von Zahlen, das die verschiedenen Offsets angibt.
  • Ein Uint32Array, das Zahlen enthält, die die Offsets angeben.

Wenn ein Uint32Array-Wert für dynamicOffsets angegeben wird, sind beide der folgenden Parameter ebenfalls erforderlich:

dynamicOffsetsStart

Eine Zahl, die den Offset, in Array-Elementen, in dynamicOffsetsData angibt, wo die dynamischen Offset-Daten beginnen.

dynamicOffsetsLength

Eine Zahl, die die Anzahl der dynamischen Offset-Werte angibt, die aus dynamicOffsetsData gelesen werden sollen.

Rückgabewert

Keiner (Undefined).

Ausnahmen

Bei setBindGroup()-Aufrufen, die einen Uint32Array-Wert für dynamicOffsets verwenden, wird der Aufruf mit einem RangeError DOMException abgebrochen, wenn:

  • dynamicOffsetsStart kleiner als 0 ist.
  • dynamicOffsetsStart + dynamicOffsetsLength größer als dynamicOffsets.length ist.

Validierung

Die folgenden Kriterien müssen bei einem Aufruf von setBindGroup() erfüllt sein, andernfalls wird ein GPUValidationError erzeugt und der GPURenderPassEncoder wird ungültig:

  • index ist kleiner oder gleich dem maxBindGroups Limit von GPUDevice.
  • dynamicOffsets.length ist gleich der Anzahl der Einträge in bindGroup mit hasDynamicOffset: true.
  • Bei bindGroup-Einträgen, bei denen der gebundene buffer-type "uniform" ist (siehe GPUDevice.createBindGroupLayout()), ist jede Zahl in dynamicOffsets ein Vielfaches des minUniformBufferOffsetAlignment Limits von GPUDevice.
  • Bei bindGroup-Einträgen, bei denen der gebundene buffer-type "storage" oder "read-only-storage" (siehe GPUDevice.createBindGroupLayout()) ist, ist jede Zahl in dynamicOffsets ein Vielfaches des minStorageBufferOffsetAlignment Limits von GPUDevice.
  • Für jeden bindGroup-Eintrag ist die Summe aus dem offset des gebundenen buffer, dem minBindingSize des entsprechenden Layout-Eintrags und dem entsprechenden dynamischen Offset in dynamicOffsets kleiner oder gleich der size des gebundenen buffer.

Beispiele

Bind-Gruppe festlegen

Im WebGPU Samples Textured Cube Beispiel wird setBindGroup() verwendet, um die uniformBindGroup an Indexposition 0 zu binden. Sehen Sie sich das Beispiel für den vollständigen Kontext an.

js
// …

const commandEncoder = device.createCommandEncoder();
const passEncoder = commandEncoder.beginRenderPass(renderPassDescriptor);
passEncoder.setPipeline(pipeline);
passEncoder.setBindGroup(0, uniformBindGroup);
passEncoder.setVertexBuffer(0, verticesBuffer);
passEncoder.draw(cubeVertexCount, 1, 0, 0);
passEncoder.end();
device.queue.submit([commandEncoder.finish()]);

// …

Hinweis: Studieren Sie die anderen WebGPU Samples für weitere Beispiele zur Verwendung von setBindGroup().

Bind-Gruppe aufheben

js
// Set bind group in slot 0
passEncoder.setBindGroup(0, uniformBindGroup);

// Later, unset bind group in slot 0
passEncoder.setBindGroup(0, null);

Spezifikationen

Specification
WebGPU
# programmable-passes-bind-groups

Browser-Kompatibilität

Siehe auch