GPUComputePassEncoder: dispatchWorkgroupsIndirect() 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 Methode dispatchWorkgroupsIndirect() der GPUComputePassEncoder-Schnittstelle setzt ein Raster von Workgroups ab, das durch die Parameter eines GPUBuffer definiert wird, um die Arbeit auszuführen, die von der aktuellen GPUComputePipeline (d.h. festgelegt über GPUComputePassEncoder.setPipeline()) ausgeführt wird.

Syntax

js
dispatchWorkgroupsIndirect(indirectBuffer, indirectOffset)

Parameter

indirectBuffer

Ein GPUBuffer, der die X-, Y- und Z-Dimensionen des Rasters von Workgroups enthält, die abgesetzt werden sollen. Der Buffer muss einen kompakten Block von drei 32-Bit-unsigned-Integervariablen enthalten, die die Dimensionen darstellen (insgesamt 12 Bytes), die in derselben Reihenfolge angegeben werden wie die Argumente für GPUComputePassEncoder.dispatchWorkgroups(). Ein Beispiel dazu:

js
const uint32 = new Uint32Array(3);
uint32[0] = 25; // The X value
uint32[1] = 1; // The Y value
uint32[2] = 1; // The Z value

// Write values into a GPUBuffer
device.queue.writeBuffer(buffer, 0, uint32, 0, uint32.length);
indirectOffset

Der Offset in Bytes, ab dem im indirectBuffer die Dimensionsdaten beginnen.

Hinweis: Die X-, Y- und Z-Dimensionswerte, die an GPUComputePassEncoder.dispatchWorkgroups() und dispatchWorkgroupsIndirect() übergeben werden, sind die Anzahl der abzusetzenden Workgroups für jede Dimension, 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 die Arbeit mit dem Aufruf dispatchWorkgroupsIndirect(indirectBuffer); abgesetzt wird, wobei indirectBuffer X- und Y-Dimensionen von 8 und 8 angibt, wird der Einstiegspunkt insgesamt 1024 Mal aufgerufen — Ein 4 x 4 Workgroup wird 8 Mal entlang der X- und Y-Achsen abgesetzt. 4 * 4 * 8 * 8 = 1024.

Rückgabewert

None (Undefined).

Validierung

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

  • Die GPUBuffer.usage von indirectBuffer enthält das GPUBufferUsage.INDIRECT-Flag.
  • indirectOffset + die durch die X-, Y- und Z-Dimensionen spezifizierte Gesamtgröße ist kleiner oder gleich der GPUBuffer.size von indirectBuffer.
  • indirectOffset ist ein Vielfaches von 4.

Beispiele

js
// Set global buffer size
const BUFFER_SIZE = 1000;

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

@compute @workgroup_size(64)

...

`;

// …

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

const uint32 = new Uint32Array(3);
// Note workgroupCountX is set based on the global buffer size and the shader workgroup count.
uint32[0] = Math.ceil(BUFFER_SIZE / 64);
uint32[1] = 1;
uint32[2] = 1;

const workgroupDimensions = device.createBuffer({
  size: 12,
  usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.INDIRECT,
});
device.queue.writeBuffer(workgroupDimensions, 0, uint32, 0, uint32.length);

passEncoder.dispatchWorkgroupsIndirect(workgroupDimensions, 0);

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

Browser-Kompatibilität

Siehe auch