ThebeginRenderPass() method of theGPUCommandEncoder interface starts encoding a render pass, returning aGPURenderPassEncoder that can be used to control rendering.

Syntax

beginRenderPass(descriptor)

Parameters

descriptor

An object containing the following properties:

colorAttachments

An array of objects (seeColor attachment object structure) defining the color attachments that will be output to when executing this render pass.

depthStencilAttachmentOptional

An object (seeDepth/stencil attachment object structure) defining the depth/stencil attachment that will be output to and tested against when executing this render pass.

labelOptional

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

maxDrawCountOptional

A number indicating the maximum number of draw calls that will be done in the render pass. This is used by some implementations to size work injected before the render pass. You should keep the default value — 50000000 — unless you know that more draw calls will be done.

occlusionQuerySetOptional

TheGPUQuerySet that will store the occlusion query results for this pass.

timestampWritesOptional

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

querySet

AGPUQuerySet of type"timestamp" that the timestamp query results will be written to.

beginningOfPassWriteIndex

A number specifying the query index inquerySet where the timestamp at the beginning of the render pass will be written. This is optional - if not defined, no timestamp will be written for the beginning of the pass.

endOfPassWriteIndex

A number specifying the query index inquerySet where the timestamp at the end of the render pass will be written. This is optional - if not defined, no timestamp will be written for the end of the pass.

Note:Thetimestamp-queryfeature needs to be enabled to use timestamp queries. Timestamp query values are written in nanoseconds, but how the value is determined is implementation-defined.

Color attachment object structure

Color attachment objects can have the following properties:

clearValueOptional

A color value to clear theview texture to, prior to executing the render pass. This value is ignored ifloadOp is not set to"clear".clearValue takes an array or object representing the four color componentsr,g,b, anda as decimals.

For example, you can pass an array like[0.0, 0.5, 1.0, 1.0], or its equivalent object{ r: 0.0, g: 0.5, b: 1.0, a: 1.0 }.

IfclearValue is omitted, it defaults to{ r: 0, g: 0, b: 0, a: 0 }.

depthSliceOptional

A number representing the index of the 3D depth slice that will be output to for this color attachment, in the case of a 3DGPUTextureViewview. When specified, this allows WebGPU to render directly to slices of 3D textures within render passes.

loadOp

An enumerated value indicating the load operation to perform onview prior to executing the render pass. Possible values are:

• "clear": Loads theclearValue for this attachment into the render pass.
• "load": Loads the existing value for this attachment into the render pass.

Note:It is recommended to always use"clear" in cases where the initial value doesn't matter, as it will give better performance on some devices such as mobiles.

storeOp

An enumerated value indicating the store operation to perform onview after executing the render pass. Possible values are:

• "discard": Discards the resulting value of the render pass for this attachment.
• "store": Stores the resulting value of the render pass for this attachment.

resolveTargetOptional

An object representing the texture subresource that will receive the resolved output for this color attachment ifview is multisampled. This can be one of the following:

• GPUTextureView
• GPUTexture: Can be used in place of aGPUTextureView, provided a default view is desired. When used in this context,GPUTexture is equivalent to aGPUTextureView object created using aGPUTexture.createView() call with no argument specified.

view

An object representing the texture subresource that will be output to for this color attachment. This can be one of the following:

• GPUTextureView
• GPUTexture: Can be used in place of aGPUTextureView, provided a default view is desired. When used in this context,GPUTexture is equivalent to aGPUTextureView object created using aGPUTexture.createView() call with no argument specified.

Note:Each color or depth/stencil attachment must be a unique texture subresource, and texture subresources used as attachments cannot be used inside the render pass.

Depth/stencil attachment object structure

ThedepthStencilAttachment object can have the following properties:

depthClearValueOptional

A number indicating the value to clearview's depth component prior to executing the render pass. This is ignored ifdepthLoadOp is not set to"clear".

The value must be between 0.0 and 1.0, inclusive.

depthLoadOpOptional

An enumerated value indicating the load operation to perform onview's depth component prior to executing the render pass. Possible values are:

• "clear": Loads theclearValue for this attachment into the render pass.
• "load": Loads the existing value for this attachment into the render pass.

Note:It is recommended to always use"clear" in cases where the initial value doesn't matter, as it will give better performance on some devices such as mobiles.

depthReadOnlyOptional

A boolean. Setting the value totrue causes the depth component ofview to be read-only. IfdepthReadOnly is omitted, it defaults tofalse.

depthStoreOpOptional

An enumerated value indicating the store operation to perform onview's depth component after executing the render pass. Possible values are:

• "discard": Discards the resulting value of the render pass for this attachment.
• "store": Stores the resulting value of the render pass for this attachment.

stencilClearValueOptional

A number indicating the value to clearview's stencil component to prior to executing the render pass. This is ignored ifstencilLoadOp is not set to"clear".

IfstencilClearValue is omitted, it defaults to 0.

stencilLoadOpOptional

An enumerated value indicating the load operation to perform onview's stencil component prior to executing the render pass. Possible values are:

• "clear": Loads theclearValue for this attachment into the render pass.
• "load": Loads the existing value for this attachment into the render pass.

Note:It is recommended to always use"clear" in cases where the initial value doesn't matter, as it will give better performance on some devices such as mobiles.

stencilReadOnlyOptional

A boolean. Setting the value totrue causes the stencil component ofview to be read-only. IfstencilReadOnly is omitted, it defaults tofalse.

stencilStoreOpOptional

An enumerated value indicating the store operation to perform onview's stencil component after executing the render pass. Possible values are:

• "discard": Discards the resulting value of the render pass for this attachment.
• "store": Stores the resulting value of the render pass for this attachment.

view

An object representing the texture subresource that will be output to and read from for this depth/stencil attachment. This can be one of the following:

• GPUTextureView
• GPUTexture: Can be used in place of aGPUTextureView, provided a default view is desired. When used in this context,GPUTexture is equivalent to aGPUTextureView object created using aGPUTexture.createView() call with no argument specified.

Return value

AGPURenderPassEncoder object instance.

Validation

The following criteria must be met when callingbeginRenderPass(), otherwise aGPUValidationError is generated and an invalidGPURenderPassEncoder is returned.

General:

• colorAttachments.length is less than or equal to theGPUDevice'smaxColorAttachmentslimit.
• IfcolorAttachments contains onlynull values,depthStencilAttachment is provided.
• Allviews incolorAttachments anddepthStencilAttachment have equalGPUTexture.sampleCount values and render extents (GPUTexture.height,GPUTexture.width, andGPUTexture.depthOrArrayLayers).
• IfocclusionQuerySet is set, the referencedGPUQuerySet has atype of"occlusion".

For color attachment objects

• Theview is renderable, and theview's format (i.e., specified in the descriptor of the originatingGPUTexture.createView() call) is a color renderable format.
• IfresolveTarget is provided:
  • Theview's originatingGPUTexture'ssampleCount is greater than 1.
  • TheresolveTarget's originatingGPUTexture'ssampleCount is 1.
  • resolveTarget is renderable.
  • The sizes of the subresources thatview andresolveTarget provide a view of match.
  • view's andresolveTarget's formats match.
• Color attachments bytes per sample is less than or equal to theGPUDevice'smaxColorAttachmentBytesPerSamplelimit.

For depth/stencil attachment objects:

• Theview is renderable, and its format is adepth-or-stencil format.
• IfdepthLoadOp is set to"clear", a validdepthClearValue is provided.
• Ifview's format is a combined depth-or-stencil format,depthReadOnly matchesstencilReadOnly.
• Ifview's format has a depth aspect, anddepthReadOnly isfalse,depthLoadOp anddepthStoreOp are provided.
• Ifview's format has a depth aspect, anddepthReadOnly istrue,depthLoadOp anddepthStoreOp are not provided.
• Ifview's format has a stencil aspect, andstencilReadOnly isfalse,stencilLoadOp andstencilStoreOp are provided.
• Ifview's format has a stencil aspect, andstencilReadOnly istrue,stencilLoadOp andstencilStoreOp are not provided.

For timestamp queries:

• Thetimestamp-queryfeature is enabled in theGPUDevice.

Examples

In ourbasic render demo, a number of commands are recorded via aGPUCommandEncoder. These commands originate from theGPURenderPassEncoder created viabeginRenderPass() :

// …// Create GPUCommandEncoderconst commandEncoder = device.createCommandEncoder();// Create GPURenderPassDescriptor to tell WebGPU which texture to draw into, then initiate render passconst renderPassDescriptor = {  colorAttachments: [    {      clearValue: clearColor,      loadOp: "clear",      storeOp: "store",      view: context.getCurrentTexture().createView(),    },  ],};const passEncoder = commandEncoder.beginRenderPass(renderPassDescriptor);// Draw a trianglepassEncoder.setPipeline(renderPipeline);passEncoder.setVertexBuffer(0, vertexBuffer);passEncoder.draw(3);// End the render passpassEncoder.end();device.queue.submit([commandEncoder.finish()]);// …

Specifications

Browser compatibility

See also

• TheWebGPU API