GPUDevice: createRenderBundleEncoder() method

Limited availability

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

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 createRenderBundleEncoder() method of the GPUDevice interface creates a GPURenderBundleEncoder that can be used to pre-record bundles of commands. These can be reused in GPURenderPassEncoders via the executeBundles() method, as many times as required.

Syntax

createRenderBundleEncoder(descriptor)

Parameters

descriptor

An object containing the following properties:

colorFormats

An array of enumerated values specifying the expected color formats for render targets. For possible values, see the GPUTextureFormat definition in the spec.

depthReadOnly Optional

A boolean. If true, specifies that executing any GPURenderBundle created by the GPURenderBundleEncoder will not modify the depth component of the depthStencilFormat when executed. If omitted, depthReadOnly will default to false.

depthStencilFormat Optional

An enumerated value that specifies the expected depth-or-stencil format for render targets. For possible values, see the Depth-stencil formats section of the spec.

label Optional

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

sampleCount Optional

A number representing the expected sample count for render targets.

stencilReadOnly Optional

A boolean. If true, specifies that executing any GPURenderBundle created by the GPURenderBundleEncoder will not modify the stencil component of the depthStencilFormat when executed. If omitted, stencilReadOnly will default to false.

Return value

A GPURenderBundleEncoder object instance.

Examples

In the WebGPU Samples Animometer example, numerous similar operations are done on many different objects simultaneously. A bundle of commands is encoded using the following function:

js
function recordRenderPass(
  passEncoder: GPURenderBundleEncoder | GPURenderPassEncoder
) {
  if (settings.dynamicOffsets) {
    passEncoder.setPipeline(dynamicPipeline);
  } else {
    passEncoder.setPipeline(pipeline);
  }
  passEncoder.setVertexBuffer(0, vertexBuffer);
  passEncoder.setBindGroup(0, timeBindGroup);
  const dynamicOffsets = [0];
  for (let i = 0; i < numTriangles; ++i) {
    if (settings.dynamicOffsets) {
      dynamicOffsets[0] = i * alignedUniformBytes;
      passEncoder.setBindGroup(1, dynamicBindGroup, dynamicOffsets);
    } else {
      passEncoder.setBindGroup(1, bindGroups[i]);
    }
    passEncoder.draw(3, 1, 0, 0);
  }
}

Later on, a GPURenderBundleEncoder is created using createRenderBundleEncoder(), the function is invoked, and the command bundle is recorded into a GPURenderBundle using GPURenderBundleEncoder.finish():

js
const renderBundleEncoder = device.createRenderBundleEncoder({
  colorFormats: [presentationFormat],
});
recordRenderPass(renderBundleEncoder);
const renderBundle = renderBundleEncoder.finish();

GPURenderPassEncoder.executeBundles() is then used to reuse the work across multiple render passes to improve performance. Study the example code listing for the full context.

js
// …

return function doDraw(timestamp) {
  if (startTime === undefined) {
    startTime = timestamp;
  }
  uniformTime[0] = (timestamp - startTime) / 1000;
  device.queue.writeBuffer(uniformBuffer, timeOffset, uniformTime.buffer);

  renderPassDescriptor.colorAttachments[0].view = context
    .getCurrentTexture()
    .createView();

  const commandEncoder = device.createCommandEncoder();
  const passEncoder = commandEncoder.beginRenderPass(renderPassDescriptor);

  if (settings.renderBundles) {
    passEncoder.executeBundles([renderBundle]);
  } else {
    recordRenderPass(passEncoder);
  }

  passEncoder.end();
  device.queue.submit([commandEncoder.finish()]);
};

// …