GPUCommandEncoder: beginComputePass() method

Experimental: This is an experimental technology
Check the Browser compatibility table carefully before using this in production.

The beginComputePass() method of the GPUCommandEncoder interface starts encoding a compute pass, returning a GPUComputePassEncoder that can be used to control computation.

Syntax

js

beginComputePass()
beginComputePass(descriptor)

Parameters

descriptor Optional

An object containing the following properties:

label Optional

A string providing a label that can be used to identify the object, for example in GPUError messages or console warnings.

timestampWrites Optional

An array of objects defining where and when timestamp query values will be written for this pass. These objects have the following properties:

  • location: An enumerated value specifying when the timestamp will be executed. Available values are:
    • "beginning": The timestamp is executed along with the other encoded commands in the compute pass once the corresponding GPUCommandBuffer is submitted.
    • "end": The timestamp is executed as part of a separate list of timestamp attachments once the pass ends.
  • queryIndex: A number specifying the index position in the querySet that the timestamp will be written to.
  • querySet: The GPUQuerySet that the timestamp will be written to.

Note: To use timestamp queries, the timestamp-query feature must be enabled in the GPUDevice.

Return value

A GPUComputePassEncoder object instance.

Validation

The following criteria must be met when calling beginComputePass(), otherwise a GPUValidationError is generated and an invalid GPUComputePassEncoder is returned:

  • The timestamp-query feature is enabled in the GPUDevice.
  • No two timestampWrites objects have the same location. In effect, this means that you can only run two timestamp queries per render pass.
  • For each timestamp query, the querySet GPUQuerySet.type is "timestamp", and the queryIndex value is less than the GPUQuerySet.count.

Examples

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

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

// ...

Specifications

Specification
WebGPU
# dom-gpucommandencoder-begincomputepass

Browser compatibility

BCD tables only load in the browser

See also