GPUCommandEncoder: beginRenderPass() method

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 beginRenderPass() method of the GPUCommandEncoder interface starts encoding a render pass, returning a GPURenderPassEncoder that can be used to control rendering.

Syntax

js
beginRenderPass(descriptor)

Parameters

descriptor

An object containing the following properties:

colorAttachments

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

depthStencilAttachment Optional

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

label Optional

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

maxDrawCount Optional

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.

occlusionQuerySet Optional

The GPUQuerySet that will store the occlusion query results for this pass.

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:

querySet

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

beginningOfPassWriteIndex

A number specifying the query index in querySet 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 in querySet 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: The timestamp-query feature 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:

clearValue Optional

A color value to clear the view texture to, prior to executing the render pass. This value is ignored if loadOp is not set to "clear". clearValue takes an array or object representing the four color components r, g, b, and a 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 }.

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

depthSlice Optional

A number representing the index of the 3D depth slice that will be output to for this color attachment, in the case of a 3D GPUTextureView view. 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 on view prior to executing the render pass. Possible values are:

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 on view after executing the render pass. Possible values are:

resolveTarget Optional

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

view

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

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

The depthStencilAttachment object can have the following properties:

depthClearValue Optional

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

The value must be between 0.0 and 1.0, inclusive.

depthLoadOp Optional

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

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.

depthReadOnly Optional

A boolean. Setting the value to true causes the depth component of view to be read-only. If depthReadOnly is omitted, it defaults to false.

depthStoreOp Optional

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

stencilClearValue Optional

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

If stencilClearValue is omitted, it defaults to 0.

stencilLoadOp Optional

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

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.

stencilReadOnly Optional

A boolean. Setting the value to true causes the stencil component of view to be read-only. If stencilReadOnly is omitted, it defaults to false.

stencilStoreOp Optional

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

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:

Return value

A GPURenderPassEncoder object instance.

Validation

The following criteria must be met when calling beginRenderPass(), otherwise a GPUValidationError is generated and an invalid GPURenderPassEncoder is returned.

General:

For color attachment objects

For depth/stencil attachment objects:

For timestamp queries:

Examples

In our basic render demo, a number of commands are recorded via a GPUCommandEncoder. These commands originate from the GPURenderPassEncoder created via beginRenderPass() :

js
// …

// Create GPUCommandEncoder
const commandEncoder = device.createCommandEncoder();

// Create GPURenderPassDescriptor to tell WebGPU which texture to draw into, then initiate render pass

const renderPassDescriptor = {
  colorAttachments: [
    {
      clearValue: clearColor,
      loadOp: "clear",
      storeOp: "store",
      view: context.getCurrentTexture().createView(),
    },
  ],
};

const passEncoder = commandEncoder.beginRenderPass(renderPassDescriptor);

// Draw a triangle

passEncoder.setPipeline(renderPipeline);
passEncoder.setVertexBuffer(0, vertexBuffer);
passEncoder.draw(3);

// End the render pass

passEncoder.end();

device.queue.submit([commandEncoder.finish()]);

// …

Specifications

See also