GPUDevice: createComputePipeline() method

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

Secure context: This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.

The createComputePipeline() method of the GPUDevice interface creates a GPUComputePipeline that can control the compute shader stage and be used in a GPUComputePassEncoder.

Syntax

js
createComputePipeline(descriptor)

Parameters

descriptor

An object containing the following properties:

compute

An object describing the compute shader entry point of the pipeline. This object can contain the following properties:

constants Optional

A sequence of record types, with the structure (id, value), representing override values for WGSL constants that can be overridden in the pipeline. These behave like ordered maps. In each case, the id is a key used to identify or select the record, and the constant is an enumerated value representing a WGSL.

Depending on which constant you want to override, the id may take the form of the numeric ID of the constant, if one is specified, or otherwise the constant's identifier name.

A code snippet providing override values for several overridable constants might look like this:

js
{
  // ...
  constants: {
    0: false,
    1200: 3.0,
    1300: 2.0,
    width: 20,
    depth: -1,
    height: 15,
  }
}
entryPoint

The name of the function in the module that this stage will use to perform its work. The corresponding shader function must have the @compute attribute to be identified as this entry point. See Entry Point Declaration for more information.

module

A GPUShaderModule object containing the WGSL code that this programmable stage will execute.

label Optional

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

layout

Defines the layout (structure, purpose, and type) of all the GPU resources (buffers, textures, etc.) used during the execution of the pipeline. Possible values are:

  • A GPUPipelineLayout object, created using GPUDevice.createPipelineLayout(), which allows the GPU to figure out how to run the pipeline most efficiently ahead of time.
  • A string of "auto", which causes the pipeline to generate an implicit bind group layout based on any bindings defined in the shader code. If "auto" is used, the generated bind group layouts may only be used with the current pipeline.

Return value

A GPUComputePipeline object instance.

Validation

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

  • The workgroup storage size used by the module referenced inside the compute property is less than or equal to the GPUDevice's maxComputeWorkgroupStorageSize limit.
  • The module uses a number of compute invocations per workgroup less than or equal to the GPUDevice's maxComputeInvocationsPerWorkgroup limit.
  • The module's workgroup size is less than or equal to the GPUDevice's corresponding maxComputeWorkgroupSizeX, maxComputeWorkgroupSizeY, or maxComputeWorkgroupSizeZ limit.

Examples

Note: The WebGPU samples feature many more examples.

Basic example

Our basic compute demo shows a process of:

js
// ...

const bindGroupLayout = device.createBindGroupLayout({
  entries: [
    {
      binding: 0,
      visibility: GPUShaderStage.COMPUTE,
      buffer: {
        type: "storage",
      },
    },
  ],
});

const computePipeline = device.createComputePipeline({
  layout: device.createPipelineLayout({
    bindGroupLayouts: [bindGroupLayout],
  }),
  compute: {
    module: shaderModule,
    entryPoint: "main",
  },
});

// ...

Specifications

Specification
WebGPU
# dom-gpudevice-createcomputepipeline

Browser compatibility

BCD tables only load in the browser

See also