GPUComputePassEncoder: 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, bevor Sie diese produktiv verwenden.

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

Hinweis: Dieses Feature ist verfügbar in Web Workers.

Die setBindGroup() Methode der GPUComputePassEncoder-Schnittstelle legt die für nachfolgende Berechnungsbefehle zu verwendende GPUBindGroup für einen gegebenen Index fest.

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 wird. Dies entspricht dem n Indexwert des entsprechenden @group(n) Attributs im Shader-Code (GPUShaderModule), das in der zugehörigen Pipeline verwendet wird.

bindGroup

Die GPUBindGroup, die für nachfolgende Berechnungsbefehle verwendet wird, oder null, in welchem Fall eine zuvor gesetzte Bind-Gruppe im gegebenen 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. im Deskriptor des GPUDevice.createBindGroupLayout()-Aufrufs, der das GPUBindGroupLayout-Objekt erstellt hat, auf dem die bindGroup basiert). Dieser Wert kann sein:

  • Ein Array von Zahlen, das die verschiedenen Offsets angibt.
  • Ein Uint32Array mit Zahlen, die die Offsets angeben.

Wenn ein Uint32Array-Wert für dynamicOffsets angegeben ist, 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 in dynamicOffsetsData gelesen werden sollen.

Rückgabewert

Keiner (Undefined).

Ausnahmen

Für setBindGroup()-Aufrufe, 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 beim Aufruf von dispatchWorkgroups() erfüllt sein, ansonsten wird ein GPUValidationError erzeugt und der GPUComputePassEncoder wird ungültig:

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

Beispiele

Bind-Gruppe setzen

In unserem grundlegenden Berechnungs-Demo werden mehrere Befehle über einen GPUCommandEncoder aufgezeichnet. Die meisten dieser Befehle stammen vom GPUComputePassEncoder, der über beginComputePass() erstellt wird. Der hier verwendete setBindGroup()-Aufruf ist die einfachste Form, bei der nur Index und Bind-Gruppe angegeben werden.

js
const BUFFER_SIZE = 1000;

// ...

// Create GPUCommandEncoder to encode commands to issue to the GPU
const commandEncoder = device.createCommandEncoder();

// Initiate render pass
const passEncoder = commandEncoder.beginComputePass();

// Issue commands
passEncoder.setPipeline(computePipeline);
passEncoder.setBindGroup(0, bindGroup);
passEncoder.dispatchWorkgroups(Math.ceil(BUFFER_SIZE / 64));

// End the render pass
passEncoder.end();

// Copy output buffer to staging buffer
commandEncoder.copyBufferToBuffer(
  output,
  0, // Source offset
  stagingBuffer,
  0, // Destination offset
  BUFFER_SIZE,
);

// End frame by passing array of command buffers to command queue for execution
device.queue.submit([commandEncoder.finish()]);

// ...

Bind-Gruppe aufheben

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

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

Spezifikationen

Specification
WebGPU
# programmable-passes-bind-groups

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch