GPUDevice: createRenderPipelineAsync() method

Limited availability

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

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.

Note: This feature is available in Web Workers.

The createRenderPipelineAsync() method of the GPUDevice interface returns a Promise that fulfills with a GPURenderPipeline, which can control the vertex and fragment shader stages and be used in a GPURenderPassEncoder or GPURenderBundleEncoder, once the pipeline can be used without any stalling.

Note: It is generally preferable to use this method over GPUDevice.createRenderPipeline() whenever possible, as it prevents blocking of GPU operation execution on pipeline compilation.

Syntax

js
createRenderPipelineAsync(descriptor)

Parameters

descriptor

See the descriptor definition for the GPUDevice.createRenderPipeline() method.

Return value

A Promise that fulfills with a GPURenderPipeline object instance when the created pipeline is ready to be used without additional delay.

Validation

If pipeline creation fails and the resulting pipeline becomes invalid as a result, the returned promise rejects with a GPUPipelineError:

  • If this is due to an internal error, the GPUPipelineError will have a reason of "internal".
  • If this is due to a validation error, the GPUPipelineError will have a reason of "validation".

A validation error can occur if any of the following are false:

  • For depthStencil objects:
    • format is a depth-or-stencil format.
    • The depthBias, depthBiasClamp, and depthBiasSlopeScale properties are set to 0 for line and point topologies, i.e., if topology is set to "line-list", "line-strip", or "point-list".
    • If depthWriteEnabled is true or depthCompare is not "always", format has a depth component.
    • If stencilFront or stencilBack's properties are not at their default values, format has a stencil component.
  • For fragment objects:
    • targets.length is less than or equal to the GPUDevice's maxColorAttachments limit.
    • For each target, writeMask's numeric equivalent is less than 16.
    • If any of the used blend factor operations use the source alpha channel (for example "src-alpha-saturated"), the output has an alpha channel (that is, it must be a vec4).
    • If the entryPoint property is omitted, the shader code contains a single fragment shader entry point function for the browser to use as the default entry point.
  • For primitive objects:
    • If the unclippedDepth property is used, the depth-clip-control feature is enabled.
  • For vertex objects:
    • If the entryPoint property is omitted, the shader code contains a single vertex shader entry point function for the browser to use as the default entry point.

Examples

Note: The WebGPU samples feature many more examples.

Basic example

The following example shows a basic example of the construction of a valid render pipeline descriptor object, which is then used to create a GPURenderPipeline via a createRenderPipelineAsync() call.

js
async function init() {
  // ...

  const vertexBuffers = [
    {
      attributes: [
        {
          shaderLocation: 0, // position
          offset: 0,
          format: "float32x4",
        },
        {
          shaderLocation: 1, // color
          offset: 16,
          format: "float32x4",
        },
      ],
      arrayStride: 32,
      stepMode: "vertex",
    },
  ];

  const pipelineDescriptor = {
    vertex: {
      module: shaderModule,
      entryPoint: "vertex_main",
      buffers: vertexBuffers,
    },
    fragment: {
      module: shaderModule,
      entryPoint: "fragment_main",
      targets: [
        {
          format: navigator.gpu.getPreferredCanvasFormat(),
        },
      ],
    },
    primitive: {
      topology: "triangle-list",
    },
    layout: "auto",
  };

  const renderPipeline =
    await device.createRenderPipelineAsync(pipelineDescriptor);

  // ...
}

Specifications

Specification
WebGPU
# dom-gpudevice-createrenderpipelineasync

Browser compatibility

Report problems with this compatibility data on GitHub
desktopmobileserver
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
Deno
createRenderPipelineAsync
Experimental
Dual-source blending: src1, one-minus-src1, src1-alpha, and one-minus-src1-alpha blend factors.
Experimental
depthCompare and depthWriteEnabled properties are optional when not needed (for example, formats without depth).
Experimental
entryPoint properties are optional for determined default fragment and vertex shader entry points.
Experimental
rgb10a2uint texture format
Experimental
Validates that depthBias, depthBiasSlopeScale, and depthBiasClamp must be 0 for line and point topologies.
Experimental
unorm10-10-10-2 vertex format
Experimental

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
Partial support
Partial support
In development. Supported in a pre-release version.
In development. Supported in a pre-release version.
No support
No support
Experimental. Expect behavior to change in the future.
See implementation notes.
User must explicitly enable this feature.
Has more compatibility info.

See also