GPUCommandEncoder: beginRenderPass() method

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:

• location: An enumerated value specifying when the timestamp will be executed. Available values are:
  • "beginning": The timestamp is executed along with the other encoded commands in the compute pass once the corresponding GPUCommandBuffer is submitted.
  • "end": The timestamp is executed as part of a separate list of timestamp attachments once the pass ends.
• queryIndex: A number specifying the index position in the querySet that the timestamp will be written to.
• querySet: The GPUQuerySet that the timestamp will be written to.

Note: To use timestamp queries, the timestamp-query feature must be enabled in the GPUDevice.

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.

What follows is a sample array:

js

clearValue: [0.0, 0.5, 1.0, 1.0];

The object equivalent would look like this:

js

clearValue: {
  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}.

loadOp

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

• "clear": Loads the clearValue 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 on view 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.

resolveTarget Optional

A GPUTextureView object representing the texture subresource that will receive the resolved output for this color attachment if view is multisampled.

view

A GPUTextureView object representing the texture subresource that will be output to for this color attachment.

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.

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:

• "clear": Loads the clearValue 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.

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:

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

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:

• "clear": Loads the clearValue 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.

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:

• "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

A GPUTextureView object representing the texture subresource that will be output to and read from for this depth/stencil attachment.

A GPURenderPassEncoder object instance.

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

General:

• colorAttachments.length is less than or equal to the GPUDevice's maxColorAttachments limit.
• If colorAttachments contains only null values, depthStencilAttachment is provided.
• All views in colorAttachments and depthStencilAttachment have equal GPUTexture.sampleCount values and render extents (GPUTexture.height, GPUTexture.width, and GPUTexture.depthOrArrayLayers).
• If occlusionQuerySet is set, the referenced GPUQuerySet has a type of "occlusion".

For color attachment objects

• The view is renderable, and the view's format (i.e. specified in the descriptor of the originating GPUTexture.createView() call) is a color renderable format.
• If resolveTarget is provided:
  • The view's originating GPUTexture's sampleCount is greater than 1.
  • The resolveTarget's originating GPUTexture's sampleCount is 1.
  • resolveTarget is renderable.
  • The sizes of the subresources that view and resolveTarget provide a view of match.
  • view's and resolveTarget's formats match.
• Color attachments bytes per sample is less than or equal to the GPUDevice's maxColorAttachmentBytesPerSample limit.

For depth/stencil attachment objects:

• The view is renderable, and its format is a depth-or-stencil format.
• If depthLoadOp is set to "clear", a valid depthClearValue is provided.
• If view's format is a combined depth-or-stencil format, depthReadOnly matches stencilReadOnly.
• If view's format has a depth aspect, and depthReadOnly is false, depthLoadOp and depthStoreOp are provided.
• If view's format has a depth aspect, and depthReadOnly is true, depthLoadOp and depthStoreOp are not provided.
• If view's format has a stencil aspect, and stencilReadOnly is false, stencilLoadOp and stencilStoreOp are provided.
• If view's format has a stencil aspect, and stencilReadOnly is true, stencilLoadOp and stencilStoreOp are not provided.

For timestamp queries:

• The timestamp-query feature is enabled in the GPUDevice.
• No two timestampWrites objects have the same location. In effect, this means that you can only run two timestamp queries per render pass.
• For each timestamp query, the querySet GPUQuerySet.type is "timestamp", and the queryIndex value is less than the GPUQuerySet.count.
• No two timestampWrites objects have the same queryIndex and querySet pair.

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

// ...

// 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()]);

// ...

• The WebGPU API