GPUComputePassEncoder: dispatchWorkgroups() 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 dispatchWorkgroups() Methode der GPUComputePassEncoder-Schnittstelle sendet ein spezifisches Raster von Workgroups, um die Arbeit des aktuellen GPUComputePipeline (d.h. gesetzt durch GPUComputePassEncoder.setPipeline()) auszuführen.

Syntax

dispatchWorkgroups(workgroupCountX)
dispatchWorkgroups(workgroupCountX, workgroupCountY)
dispatchWorkgroups(workgroupCountX, workgroupCountY, workgroupCountZ)

Parameter

workgroupCountX: Die X-Dimension des Rasters von Workgroups, das gesendet werden soll.
workgroupCountY Optional: Die Y-Dimension des Rasters von Workgroups, das gesendet werden soll. Wenn weggelassen, ist workgroupCountY standardmäßig 1.
workgroupCountZ Optional: Die Z-Dimension des Rasters von Workgroups, das gesendet werden soll. Wenn weggelassen, ist workgroupCountZ standardmäßig 1.

Hinweis: Die an dispatchWorkgroups() und GPUComputePassEncoder.dispatchWorkgroupsIndirect() übergebenen Werte für die X-, Y- und Z-Dimension sind die Anzahl der Workgroups, die für jede Dimension gesendet werden sollen, nicht die Anzahl der Shader-Aufrufe, die über jede Dimension ausgeführt werden sollen. Dies entspricht dem Verhalten moderner nativer GPU-APIs, unterscheidet sich jedoch vom Verhalten von OpenCL. Das bedeutet, wenn ein GPUShaderModule einen Einstiegspunkt mit @workgroup_size(4, 4) definiert, und Arbeit mit dem Aufruf passEncoder.dispatchWorkgroups(8, 8); gesendet wird, wird der Einstiegspunkt insgesamt 1024 Mal aufgerufen — Es wird eine 4 x 4 Arbeitsgruppe 8 Mal entlang der X- und Y-Achse gesendet. 4 * 4 * 8 * 8 = 1024.

Rückgabewert

Keiner (Undefined).

Validierung

Beim Aufruf von dispatchWorkgroups() müssen die folgenden Kriterien erfüllt sein, andernfalls wird ein GPUValidationError generiert und der GPUComputePassEncoder wird ungültig:

workgroupCountX, workgroupCountY und workgroupCountZ sind alle kleiner oder gleich dem maxComputeWorkgroupsPerDimension-Limit des GPUDevice.

Beispiele

In unserem einfachen Compute-Demo werden mehrere Befehle über einen GPUCommandEncoder aufgezeichnet. Die meisten dieser Befehle stammen vom GPUComputePassEncoder, der über beginComputePass() erstellt wurde.

Am Anfang des Codes setzen wir eine globale Pufferggröße von 1000. Beachten Sie auch, dass die Arbeitsgruppengröße im Shader auf 64 eingestellt ist.

const BUFFER_SIZE = 1000;

// Compute shader
const shader = `
@group(0) @binding(0)
var<storage, read_write> output: array<f32>;

@compute @workgroup_size(64)

...

`;

Später im Code wird der dispatchWorkgroups()-Parameter workgroupCountX basierend auf der globalen Pufferggröße und der Arbeitsgruppenzahl des Shaders gesetzt.

// ...

// 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()]);

// ...

Spezifikationen

Specification
WebGPU # dom-gpucomputepassencoder-dispatchworkgroups

Browser-Kompatibilität

Siehe auch

Die WebGPU API