GPUComputePassEncoder: dispatchWorkgroups() 方法

实验性：这是一个实验性技术
在生产环境中使用此功能前，请仔细检查浏览器兼容性表。

安全上下文：此功能仅在安全上下文（HTTPS）中可用，且仅在某些或所有支持的浏览器中可用。

dispatchWorkgroups() 是 GPUComputePassEncoder 接口的一个方法，它分派一个特定的工作组网格来执行当前 GPUComputePipeline（即通过 GPUComputePassEncoder.setPipeline() 设置）正在执行的工作。

语法

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

参数

workgroupCountX: 要分派的工作组网格的 X 维度。
workgroupCountY 可选: 要分派的工作组网格的 Y 维度。如果省略，则 workgroupCountY 默认为 1。
workgroupCountZ 可选: 要分派的工作组网格的 Z 维度。如果省略，则 workgroupCountZ 默认为 1。

注意：传递给dispatchWorkgroups()和GPUComputePassEncoder.dispatchWorkgroupsIndirect()的X、Y和Z维度值表示每个维度要分派的作业组的数量，而不是跨每个维度执行的着色器调用的数量。这与现代原生GPU API的行为一致，但与OpenCL的行为不同。这意味着，如果一个GPUShaderModule定义了一个带有@workgroup_size(4, 4)的入口点，并且通过调用passEncoder.dispatchWorkgroups(8, 8);向其分派工作，则入口点将总共被调用1024次——沿着X和Y轴分别分派8次4 x 4的作业组。4 * 4 * 8 * 8 = 1024。

返回值

无（Undefined）。

验证

调用dispatchWorkgroups()时必须满足以下条件，否则将生成GPUValidationError，并且GPUComputePassEncoder将变为无效

workgroupCountX、workgroupCountY和workgroupCountZ都小于或等于GPUDevice的maxComputeWorkgroupsPerDimension 限制。

示例

在我们基本的计算演示中，几个命令通过GPUCommandEncoder记录。这些命令中的大多数都源于通过beginComputePass()创建的GPUComputePassEncoder。

在代码的开头，我们设置了1000的全局缓冲区大小。另外，请注意着色器中的工作组大小设置为64。

const BUFFER_SIZE = 1000;

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

@compute @workgroup_size(64)

...

`;

在代码的后面，dispatchWorkgroups()的workgroupCountX参数根据全局缓冲区大小和着色器工作组计数进行设置。

// ...

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

// ...

规范

规范
WebGPU # dom-gpucomputepassencoder-dispatchworkgroups

浏览器兼容性

BCD 表格仅在浏览器中加载

另请参阅

The WebGPU API