GPUComputePassEncoder: Methode setBindGroup()

Syntax

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

Parameter

index

Der Index, an dem die Bind-Gruppe festgelegt 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 Compute-Befehle verwendet werden soll, oder null, in diesem Fall wird eine zuvor eingestellte Bind-Gruppe in dem angegebenen Slot entfernt.

dynamicOffsets Optional

Ein Wert, der den Offset in Bytes für jeden Eintrag in bindGroup angibt, bei dem hasDynamicOffset: true festgelegt ist (d.h. im Deskriptor des Aufrufs GPUDevice.createBindGroupLayout(), 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, das Zahlen enthält, 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, bei dem die dynamische 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

Für setBindGroup()-Aufrufe, die einen Uint32Array-Wert für dynamicOffsets verwenden, wird der Aufruf mit einem RangeError DOMException ausgelöst, wenn:

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

Validierung

Die folgenden Kriterien müssen erfüllt sein, wenn dispatchWorkgroups() aufgerufen wird, andernfalls wird ein GPUValidationError generiert und der GPUComputePassEncoder wird ungültig:

• index ist kleiner oder gleich dem maxBindGroups-Limit des GPUDevice.
• dynamicOffsets.length entspricht der Anzahl der Einträge in bindGroup mit hasDynamicOffset: true.
• Für bindGroup-Einträge, bei denen der gebundene buffer-Typ "uniform" ist (siehe GPUDevice.createBindGroupLayout()), muss jede Zahl in dynamicOffsets ein Vielfaches des minUniformBufferOffsetAlignment-Limits des GPUDevice sein.
• Für bindGroup-Einträge, bei denen der gebundene buffer-Typ "storage" oder "read-only-storage" ist (siehe GPUDevice.createBindGroupLayout()), muss jede Zahl in dynamicOffsets ein Vielfaches des minStorageBufferOffsetAlignment-Limits des GPUDevice sein.
• Für jeden bindGroup-Eintrag darf der offset des gebundenen buffer, plus der minBindingSize des entsprechenden Layout-Eintrags, plus der entsprechende dynamische Offset, der in dynamicOffsets angegeben ist, nicht größer als die size des gebundenen buffer sein.

Beispiele

Bind-Gruppe festlegen

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

const BUFFER_SIZE = 1000;

// …

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

// Initiate compute 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 entfernen

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

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

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Die WebGPU API