The dispatchWorkgroups() method of the GPUComputePassEncoder interface dispatches a specific grid of workgroups to perform the work being done by the current GPUComputePipeline (i.e. set via GPUComputePassEncoder.setPipeline()).

workgroupCountX

The X dimension of the grid of workgroups to dispatch.

workgroupCountY Optional

The Y dimension of the grid of workgroups to dispatch. If omitted, workgroupCountY defaults to 1.

workgroupCountZ Optional

The Z dimension of the grid of workgroups to dispatch. If omitted, workgroupCountZ defaults to 1.

None (Undefined).

The following criteria must be met when calling dispatchWorkgroups(), otherwise a GPUValidationError is generated and the GPUComputePassEncoder becomes invalid:

• workgroupCountX, workgroupCountY, and workgroupCountZ are all less than or equal to the GPUDevice's maxComputeWorkgroupsPerDimension limit.

In our basic compute demo, several commands are recorded via a GPUCommandEncoder. Most of these commands originate from the GPUComputePassEncoder created via beginComputePass().

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 shader
const shader = `
@group(0) @binding(0)
var<storage, read_write> output: array<f32>;

@compute @workgroup_size(64)

...

`;

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

// ...

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

// ...

• The WebGPU API