GPUComputePassEncoder: dispatchWorkgroups() method

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

Secure context: This feature is available only insecure contexts (HTTPS), in some or allsupporting browsers.

Note: This feature is available inWeb Workers.

ThedispatchWorkgroups() method of theGPUComputePassEncoder interface dispatches a specific grid of workgroups to perform the work being done by the currentGPUComputePipeline (i.e., set viaGPUComputePassEncoder.setPipeline()).

Syntax

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

Parameters

workgroupCountX: The X dimension of the grid of workgroups to dispatch.
workgroupCountYOptional: The Y dimension of the grid of workgroups to dispatch. If omitted,workgroupCountY defaults to 1.
workgroupCountZOptional: The Z dimension of the grid of workgroups to dispatch. If omitted,workgroupCountZ defaults to 1.

Note:The X, Y, and Z dimension values passed todispatchWorkgroups() andGPUComputePassEncoder.dispatchWorkgroupsIndirect() are the number of workgroups to dispatch for each dimension, not the number of shader invocations to perform across each dimension. This matches the behavior of modern native GPU APIs, but differs from the behavior of OpenCL. This means that if aGPUShaderModule defines an entry point with@workgroup_size(4, 4), and work is dispatched to it with the callpassEncoder.dispatchWorkgroups(8, 8);, the entry point will be invoked 1024 times total — Dispatching a 4 x 4 workgroup 8 times along both the X and Y axes.4 * 4 * 8 * 8 = 1024.

Return value

None (Undefined).

Validation

The following criteria must be met when callingdispatchWorkgroups(), otherwise aGPUValidationError is generated and theGPUComputePassEncoder becomes invalid:

workgroupCountX,workgroupCountY, andworkgroupCountZ are all less than or equal to theGPUDevice'smaxComputeWorkgroupsPerDimensionlimit.

Examples

In ourbasic compute demo, several commands are recorded via aGPUCommandEncoder. Most of these commands originate from theGPUComputePassEncoder created viabeginComputePass().

At the start of the code, we set a global buffer size of 1000. Also, note that the workgroup size in the shader is set to 64.

const BUFFER_SIZE = 1000;// Compute shaderconst shader = `@group(0) @binding(0)var<storage, read_write> output: array<f32>;@compute @workgroup_size(64)...`;

Later in the code, thedispatchWorkgroups()workgroupCountX parameter is set based on the global buffer size and the shader workgroup count.

// …// Create GPUCommandEncoder to encode commands to issue to the GPUconst commandEncoder = device.createCommandEncoder();// Initiate render passconst passEncoder = commandEncoder.beginComputePass();// Issue commandspassEncoder.setPipeline(computePipeline);passEncoder.setBindGroup(0, bindGroup);passEncoder.dispatchWorkgroups(Math.ceil(BUFFER_SIZE / 64));// End the render passpassEncoder.end();// Copy output buffer to staging buffercommandEncoder.copyBufferToBuffer(  output,  0, // Source offset  stagingBuffer,  0, // Destination offset  BUFFER_SIZE,);// End frame by passing array of command buffers to command queue for executiondevice.queue.submit([commandEncoder.finish()]);// …