Module bundle 

Render Bundles

A render bundle is a prerecorded sequence of commands that can be replayed on a command encoder with a single call. A single bundle can replayed any number of times, on different encoders. Constructing a render bundle lets wgpu validate and analyze its commands up front, so that replaying a bundle can be more efficient than simply re-recording its commands each time.

Not all commands are available in bundles; for example, a render bundle may not contain a [RenderCommand::SetViewport] command.

Most of wgpu’s backend graphics APIs have something like bundles. For example, Vulkan calls them “secondary command buffers”, and Metal calls them “indirect command buffers”. Although we plan to take advantage of these platform features at some point in the future, for now wgpu’s implementation of render bundles does not use them: at the hal level, wgpu render bundles just replay the commands.

Render Bundle Isolation

One important property of render bundles is that the draw calls in a render bundle depend solely on the pipeline and state established within the render bundle itself. A draw call in a bundle will never use a vertex buffer, say, that was set in the RenderPass before executing the bundle. We call this property ‘isolation’, in that a render bundle is somewhat isolated from the passes that use it.

Render passes are also isolated from the effects of bundles. After executing a render bundle, a render pass’s pipeline, bind groups, and vertex and index buffers are are unset, so the bundle cannot affect later draw calls in the pass.

A render pass is isolated from a bundle’s effects on immediate data values. When encoding a render bundle, calls to set_immediates snapshot the immediate data content at encoding time, and the immediate values cannot be changed after finish. Before and after executing each individual bundle, all required immediate slots are cleared/reset, therefore immediate data must be set again.

Render Bundle Lifecycle

To create a render bundle:

1. Create a RenderBundleEncoder by calling Device::create_render_bundle_encoder.

2. Record commands in the RenderBundleEncoder using methods on RenderBundleEncoder.

3. Call RenderBundleEncoder::finish, which analyzes and cleans up the command stream and returns a RenderBundle.

4. Then, any number of times, call RenderPass::execute_bundles to execute the bundle as part of some render pass.

Implementation

The most complex part of render bundles is the “finish” step, mostly implemented in RenderBundleEncoder::finish. This consumes the commands stored in the encoder’s [BasePass], while validating everything, tracking the state, dropping redundant or unnecessary commands, and presenting the results as a new RenderBundle. It doesn’t actually execute any commands.

This step also enforces the ‘isolation’ property mentioned above: every draw call is checked to ensure that the resources it uses on were established since the last time the pipeline was set. This means the bundle can be executed verbatim without any state tracking.

Execution

When the bundle is used in an actual render pass, RenderBundle::execute is called. It goes through the commands and issues them into the native command buffer. Thanks to isolation, it doesn’t track any bind group invalidations or index format changes.

!

Structs

IndexState 🔒

A render bundle’s current index buffer state.

RenderBundle

cbindgen:ignore

RenderBundleEncoder

RenderBundleEncoderDescriptor

Describes a RenderBundleEncoder.

RenderBundleError

Error encountered when finishing recording a render bundle.

RenderBundleState 🔒

State 🔒

The state of a single vertex buffer slot during render bundle encoding.

Enums

CreateRenderBundleError

Error type returned from RenderBundleEncoder::new if the sample count is invalid.

ExecutionError

Error type returned from RenderBundleEncoder::new if the sample count is invalid.

RenderBundleErrorInner

Error encountered when finishing recording a render bundle.

Functions

draw 🔒

draw_indexed 🔒

draw_mesh_tasks 🔒

multi_draw_indirect 🔒

set_bind_group 🔒

set_immediates 🔒

set_index_buffer 🔒

set_pipeline 🔒

set_vertex_buffer 🔒

validate_render_bundle_encoder_descriptor 🔒

Validate a render bundle descriptor.

Type Aliases

RenderBundleDescriptor