ThecreateRenderPipeline() method of theGPUDevice interface creates aGPURenderPipeline that can control the vertex and fragment shader stages and be used in aGPURenderPassEncoder orGPURenderBundleEncoder.

Syntax

createRenderPipeline(descriptor)

Parameters

descriptor

An object containing the following properties:

depthStencilOptional

An object (seedepthStencil object structure) describing depth-stencil properties including testing, operations, and bias.

fragmentOptional

An object (seefragment object structure) describing the fragment shader entry point of the pipeline and its output colors. If no fragment shader entry point is defined, the pipeline will not produce any color attachment outputs, but it still performs rasterization and produces depth values based on the vertex position output. Depth testing and stencil operations can still be used.

labelOptional

A string providing a label that can be used to identify the object, for example inGPUError 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:

• AGPUPipelineLayout object, created usingGPUDevice.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.

multisampleOptional

An object (seemultisample object structure) describing how the pipeline interacts with a render pass's multisampled attachments.

primitiveOptional

An object (seeprimitive object structure) describing how a pipeline constructs and rasterizes primitives from its vertex inputs.

vertex

An object (seevertex object structure) describing the vertex shader entry point of the pipeline and its input buffer layouts.

depthStencil object structure

ThedepthStencil object can contain the following properties:

depthBiasOptional

A number representing a constant depth bias that is added to each fragment. If omitted,depthBias defaults to 0.

Note:ThedepthBias,depthBiasClamp, anddepthBiasSlopeScale properties must be set to0 for line and point topologies, i.e., iftopology is set to"line-list","line-strip", or"point-list". If not, aGPUValidationError will be generated and the returnedGPURenderPipeline will be invalid.

depthBiasClampOptional

A number representing the maximum depth bias of a fragment. If omitted,depthBiasClamp defaults to 0.

depthBiasSlopeScaleOptional

A number representing a depth bias that scales with the fragment's slope. If omitted,depthBiasSlopeScale defaults to 0.

depthCompareOptional

An enumerated value specifying the comparison operation used to test fragment depths againstdepthStencilAttachment depth values. Possible values are:

• "never": Comparison tests never pass.
• "less": A provided value passes the comparison test if it is less than the sampled value.
• "equal": A provided value passes the comparison test if it is equal to the sampled value.
• "less-equal": A provided value passes the comparison test if it is less than or equal to the sampled value.
• "greater": A provided value passes the comparison test if it is greater than the sampled value.
• "not-equal": A provided value passes the comparison test if it is not equal to the sampled value.
• "greater-equal": A provided value passes the comparison test if it is greater than or equal to the sampled value.
• "always": Comparison tests always pass.

depthCompare is not required if the specifiedformat does not have a depth component, or if the comparison operation is not used.

depthWriteEnabledOptional

A boolean. A value oftrue specifies that theGPURenderPipeline can modifydepthStencilAttachment depth values after creation. Setting it tofalse means it cannot.

depthWriteEnabled is not required if the specifiedformat does not have a depth component.

format

An enumerated value specifying thedepthStencilAttachment format that theGPURenderPipeline will be compatible with. See the specification'sTexture Formats section for all the availableformat values.

stencilBackOptional

An object that defines how stencil comparisons and operations are performed for back-facing primitives. Its properties can include:

compareOptional

An enumerated value specifying the comparison operation used when testing fragments againstdepthStencilAttachment stencil values. Possible values are the same as for thedepthCompare property; see above. If omitted,compare defaults to"always".

depthFailOpOptional

An enumerated value specifying the stencil operation performed if the fragment depth comparison described bydepthCompare fails. Possible values are:

• "decrement-clamp": Decrement the current render state stencil value, clamping it to 0.
• "decrement-wrap": Decrement the current render state stencil value, wrapping it to the maximum representable value of thedepthStencilAttachment's stencil aspect if the value goes below 0.
• "invert": Bitwise-invert the current render state stencil value.
• "increment-clamp": Increments the current render state stencil value, clamping it to the maximum representable value of thedepthStencilAttachment's stencil aspect.
• "increment-wrap": Increments the current render state stencil value, wrapping it to zero if the value exceeds the maximum representable value of thedepthStencilAttachment's stencil aspect.
• "keep": Keep the current stencil value.
• "replace": Set the stencil value to the current render state stencil value.
• "zero": Set the stencil value to 0.

If omitted,depthFailOp defaults to"keep".

Note:The render state stencil value is initialized to 0 at the start of a render pass.

failOpOptional

An enumerated value specifying the stencil operation performed if the fragment stencil comparison test described bycompare fails. Possible and default values are the same as fordepthFailOp.

passOpOptional

An enumerated value specifying the stencil operation performed if the fragment stencil comparison test described bycompare passes. Possible and default values are the same as fordepthFailOp.

stencilFrontOptional

An object that defines how stencil comparisons and operations are performed for front-facing primitives. Its properties are the same as forstencilBack.

stencilReadMaskOptional

A bitmask controlling whichdepthStencilAttachment stencil value bits are read when performing stencil comparison tests. If omitted,stencilReadMask defaults to0xFFFFFFFF.

stencilWriteMaskOptional

A bitmask controlling whichdepthStencilAttachment stencil value bits are written to when performing stencil operations. If omitted,stencilWriteMask defaults to0xFFFFFFFF.

fragment object structure

Thefragment object contains an array of objects, each of which can contain the following properties:

constantsOptional

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

Depending on which constant you want to override, theid 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,  },});

entryPointOptional

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

You can omit theentryPoint property if your shader code contains a single function with the@fragment attribute set — the browser will use this as the default entry point. IfentryPoint is omitted and the browser cannot determine a default entry point, aGPUValidationError is generated and the resultingGPURenderPipeline will be invalid.

module

AGPUShaderModule object containing theWGSL code that this programmable stage will execute.

targets

an array of objects representing color states that represent configuration details for the colors output by the fragment shader stage. These objects can include the following properties:

blendOptional

An object that describes a blend mode to be applied to the output color.blend has two properties:

alpha

Describes the alpha channel value.

color

Describes the color value.

alpha andcolor both take an object as a value that can include the following properties:

dstFactorOptional

An enumerated value that defines the blend factor operation to be performed on values from the target attachment. Possible values are:

• "constant"
• "dst"
• "dst-alpha"
• "one"
• "one-minus-dst"
• "one-minus-src"
• "one-minus-src1"
• "one-minus-src-alpha"
• "one-minus-src1-alpha"
• "one-minus-dst-alpha"
• "one-minus-constant"
• "src"
• "src1"
• "src-alpha"
• "src1-alpha"
• "src-alpha-saturated"
• "zero"

If omitted,dstFactor defaults to"zero".

Note:Thedual-source-blendingfeature needs to be enabled for thesrc1,one-minus-src1,src1-alpha, andone-minus-src1-alpha blend factor operations to be used successfully. If not, aGPUValidationError is generated.

operationOptional

An enumerated value that defines the algorithm used to combine source and destination blend factors, to calculate the final values written to the target attachment components. Possible values are:

• "add"
• "max"
• "min"
• "reverse-subtract"
• "subtract"

If omitted,operation defaults to"add".

srcFactorOptional

An enumerated value that defines the blend factor operation to be performed on values from the fragment shader. Possible values are the same as fordstFactor. If omitted,srcFactor defaults to"one".

Note:For a detailed explanation of the algorithms defined by eachdstFactor/srcFactor andoperation enumerated value, see theBlend State section of the specification.

format

An enumerated value specifying the required format for output colors. See the specification'sTexture Formats section for all the availableformat values.

Note:For ther32float,rg32float, andrgba32float formats to be used withblending, thefloat32-blendablefeature must be available in the device.

writeMaskOptional

One or morebitwise flags defining the write mask to apply to the color target state. Possible flag values are:

• GPUColorWrite.RED
• GPUColorWrite.GREEN
• GPUColorWrite.BLUE
• GPUColorWrite.ALPHA
• GPUColorWrite.ALL

If omitted,writeMask defaults toGPUColorWrite.ALL.

Note that multiple flags can be specified by separating values withbitwise OR, for example:GPUColorWrite.RED | GPUColorWrite.ALPHA.

multisample object structure

Themultisample object can contain the following properties:

alphaToCoverageEnabledOptional

A boolean. A value oftrue indicates that a fragment's alpha channel should be used to generate a sample coverage mask. If omitted,alphaToCoverageEnabled defaults tofalse.

countOptional

A number that defines the number of samples per pixel. The pipeline will be compatible only with attachment textures (colorAttachments anddepthStencilAttachments) with matchingsampleCounts (seeGPUTexture).

If omitted,count defaults to 1.

maskOptional

A bitmask that determines which samples are written to. If omitted,mask defaults to0xFFFFFFFF.

primitive object structure

Theprimitive object can contain the following properties:

cullModeOptional

An enumerated value that defines which polygon orientation will be culled, if any. Possible values are:

• "back": Back-facing polygons are culled.
• "front": Front-facing polygons are culled.
• "none": No polygons are culled.

If omitted,cullMode defaults to"none".

frontFaceOptional

An enumerated value that defines which polygons are considered front-facing. Possible values are:

• "ccw": Polygons with vertices whose framebuffer coordinates are given in counter-clockwise order.
• "cw": Polygons with vertices whose framebuffer coordinates are given in clockwise order.

If omitted,frontFace defaults to"ccw".

Note:ThefrontFace andcullMode values have no effect on the"point-list","line-list", or"line-strip" topologies.

stripIndexFormatOptional

An enumerated value that determines the index buffer format and primitive restart value in the case of pipelines with strip topologies ("line-strip" or"triangle-strip"). The primitive restart value specifies which index value indicates that a new primitive should be started rather than continuing to construct the strip with the prior indexed vertices. Possible values are:

• "uint16": Indicates a byte size of 2 and a primitive restart value of0xFFFF.
• "uint32": Indicates a byte size of 4 and a primitive restart value of0xFFFFFFFF.

GPU primitive states that specify a strip primitive topology must specify a strip index format if they are used for indexed draws (for example, viaGPURenderPassEncoder.drawIndexed()) so that the primitive restart value that will be used is known at pipeline creation time. Pipelines with list primitive topologies ("line-list","point-list", or"triangle-list") should not specify astripIndexFormat value. They will instead use the index format passed to, for example,GPURenderPassEncoder.setIndexBuffer() when doing indexed rendering.

topologyOptional

An enumerated value that defines the type of primitive to be constructed from the specifiedvertex inputs. Possible values are:

• "line-list": Each consecutive pair of two vertices defines a line primitive.
• "line-strip": Each vertex after the first defines a line primitive between it and the previous vertex.
• "point-list": Each vertex defines a point primitive.
• "triangle-list": Each consecutive triplet of three vertices defines a triangle primitive.
• "triangle-strip": Each vertex after the first two defines a triangle primitive between it and the previous two vertices.

If omitted,topology defaults to"triangle-list".

unclippedDepthOptional

A boolean. A value oftrue indicates that depth clipping is disabled. If omitted,unclippedDepth defaults tofalse. Note that to control depth clipping, thedepth-clip-controlfeature must be enabled in theGPUDevice.

Note:Thedepth-clip-controlfeature needs to be enabled for theunclippedDepth property to be used successfully. If not, aGPUValidationError is generated.

vertex object structure

Thevertex object can contain the following properties:

constantsOptional

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

Depending on which constant you want to override, theid 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,  },});

entryPointOptional

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

You can omit theentryPoint property if your shader code contains a single function with the@vertex attribute set — the browser will use this as the default entry point. IfentryPoint is omitted and the browser cannot determine a default entry point, aGPUValidationError is generated and the resultingGPURenderPipeline will be invalid.

module

AGPUShaderModule object containing theWGSL code that this programmable stage will execute.

buffersOptional

An array of objects, each representing the expected layout of a vertex buffer used in the pipeline. Each object can contain the following properties:

arrayStride

A number representing the stride, in bytes, between the different structures (e.g., vertices) inside the buffer.

attributes

An array of objects defining the layout of the vertex attributes within each structure. Each object has the following properties:

format

An enumerated value that specifies the format of the vertex. For all the available values, see theGPUVertexFormat definition in the specification.

offset

A number specifying the offset, in bytes, from the beginning of the structure to the data for the attribute.

shaderLocation

The numeric location associated with this attribute, which will correspond with a@location attribute declared in the WGSL code of the associatedGPUShaderModule referenced in thevertex object'smodule property.

stepModeOptional

An enumerated value that defines whether the separate structures inside the buffer represent vertices or instances. Possible values are:

• "instance": Each structure is an instance — the address is advanced byarrayStride for each instance.
• "vertex": Each structure is a vertex — the address is advanced byarrayStride for each vertex, and reset between instances.

If omitted,stepMode defaults to"vertex".

Return value

AGPURenderPipeline object instance.

Validation

The following criteria must be met when callingcreateRenderPipeline(), otherwise aGPUValidationError is generated and an invalidGPURenderPipeline object is returned:

• FordepthStencil objects:
  • format is adepth-or-stencil format.
  • ThedepthBias,depthBiasClamp, anddepthBiasSlopeScale properties are set to0 for line and point topologies, i.e., iftopology is set to"line-list","line-strip", or"point-list".
  • IfdepthWriteEnabled istrue ordepthCompare is not"always",format has a depth component.
  • IfstencilFront orstencilBack's properties are not at their default values,format has a stencil component.
• Forfragment objects:
  • targets.length is less than or equal to theGPUDevice'smaxColorAttachmentslimit.
  • For eachtarget,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 avec4).
  • If thesrc1,one-minus-src1,src1-alpha, orone-minus-src1-alpha blend factor operations are used, thedual-source-blendingfeature is enabled.
  • If theentryPoint property is omitted, the shader code contains a single fragment shader entry point function for the browser to use as the default entry point.
• Forprimitive objects:
  • If theunclippedDepth property is used, thedepth-clip-controlfeature is enabled.
• Forvertex objects:
  • If theentryPoint 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

Basic example

Ourbasic render demo provides an example of the construction of a valid render pipeline descriptor object, which is then used to create aGPURenderPipeline via acreateRenderPipeline() call.

// …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 = device.createRenderPipeline(pipelineDescriptor);// …

Specifications

Browser compatibility

See also

• TheWebGPU API