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
GPUTextureFormatdefinition in the spec. depthReadOnlyOptional-
A boolean. If
true, specifies that executing anyGPURenderBundlecreated by theGPURenderBundleEncoderwill not modify the depth component of thedepthStencilFormatwhen executed. If omitted,depthReadOnlywill default tofalse. depthStencilFormatOptional-
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.
labelOptional-
A string providing a label that can be used to identify the object, for example in
GPUErrormessages or console warnings. sampleCountOptional-
A number representing the expected sample count for render targets.
stencilReadOnlyOptional-
A boolean. If
true, specifies that executing anyGPURenderBundlecreated by theGPURenderBundleEncoderwill not modify the stencil component of thedepthStencilFormatwhen executed. If omitted,stencilReadOnlywill default tofalse.
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:
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():
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.
// …
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()]);
};
// …
Specifications
| Specification |
|---|
| WebGPU # dom-gpudevice-createrenderbundleencoder |
Browser compatibility
| desktop | mobile | server | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
createRenderBundleEncoder
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Legend
Tip: you can click/tap on a cell for more information.
- Full support
- Full support
- Partial support
- Partial support
- No support
- No support
- User must explicitly enable this feature.
- Has more compatibility info.
See also
- The WebGPU API