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 versendet ein spezifisches Raster von Arbeitsgruppen, um die Arbeit durchzuführen, die von der aktuellen GPUComputePipeline erledigt wird (d. h. festgelegt über GPUComputePassEncoder.setPipeline()).

Syntax

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

Parameter

workgroupCountX

Die X-Dimension des Rasters von Arbeitsgruppen, die versendet werden sollen.

workgroupCountY Optional

Die Y-Dimension des Rasters von Arbeitsgruppen, die versendet werden sollen. Wenn weggelassen, ist der Standardwert von workgroupCountY 1.

workgroupCountZ Optional

Die Z-Dimension des Rasters von Arbeitsgruppen, die versendet werden sollen. Wenn weggelassen, ist der Standardwert von workgroupCountZ 1.

Hinweis: Die an dispatchWorkgroups() und GPUComputePassEncoder.dispatchWorkgroupsIndirect() übergebenen Dimensionen X, Y und Z sind die Anzahl der zu versendenden Arbeitsgruppen für jede Dimension, nicht die Anzahl der Shader-Aufrufe, die in jeder Dimension auszuführen sind. Dies entspricht dem Verhalten moderner nativer GPU-APIs, unterscheidet sich jedoch vom Verhalten von OpenCL. Das bedeutet, dass wenn ein GPUShaderModule einen Einstiegspunkt mit @workgroup_size(4, 4) definiert und Arbeit damit mit dem Aufruf passEncoder.dispatchWorkgroups(8, 8); versendet wird, der Einstiegspunkt insgesamt 1024 Mal aufgerufen wird — ein 4 x 4-Arbeitsgrupp wird 8 Mal entlang beider Achsen X und Y ausgeführt. 4 * 4 * 8 * 8 = 1024.

Rückgabewert

Keiner (Undefined).

Validierung

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

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

Beispiele

In unserem grundlegenden 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 Puffergröße von 1000 fest. Beachten Sie auch, dass die Arbeitsgruppengröße im Shader auf 64 gesetzt ist.

js
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 workgroupCountX-Parameter von dispatchWorkgroups() basierend auf der globalen Puffergröße und der Shader-Arbeitsgruppenzahl gesetzt.

js
// ...

// 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

Report problems with this compatibility data on GitHub
desktopmobileserver
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
Deno
dispatchWorkgroups
Experimental

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
Partial support
Partial support
In development. Supported in a pre-release version.
In development. Supported in a pre-release version.
No support
No support
Experimental. Expect behavior to change in the future.
See implementation notes.
User must explicitly enable this feature.
Has more compatibility info.

Siehe auch