Trait DrawablePipeline

pub trait DrawablePipeline<T: DrawCommand> {
    // Required method
    fn draw(
        &mut self,
        gpu: &Device,
        gpu_queue: &Queue,
        config: &SurfaceConfiguration,
        render_pass: &mut RenderPass<'_>,
        command: &T,
        size: PxSize,
        start_pos: PxPosition,
        scene_texture_view: &TextureView,
    );

    // Provided methods
    fn begin_frame(
        &mut self,
        gpu: &Device,
        gpu_queue: &Queue,
        config: &SurfaceConfiguration,
    ) { ... }
    fn begin_pass(
        &mut self,
        gpu: &Device,
        gpu_queue: &Queue,
        config: &SurfaceConfiguration,
        render_pass: &mut RenderPass<'_>,
    ) { ... }
    fn end_pass(
        &mut self,
        gpu: &Device,
        gpu_queue: &Queue,
        config: &SurfaceConfiguration,
        render_pass: &mut RenderPass<'_>,
    ) { ... }
    fn end_frame(
        &mut self,
        gpu: &Device,
        gpu_queue: &Queue,
        config: &SurfaceConfiguration,
    ) { ... }
}

Core trait for implementing custom graphics rendering pipelines.

This trait defines the interface for rendering pipelines that process specific types of draw commands. Each pipeline is responsible for setting up GPU resources, managing render state, and executing the actual drawing operations.

Type Parameters

• T - The specific DrawCommand type this pipeline can handle

Lifecycle Methods

The pipeline system provides five lifecycle hooks, executed in the following order:

1. begin_frame(): Called once at the start of a new frame, before any render passes.
2. begin_pass(): Called at the start of each render pass that involves this pipeline.
3. draw(): Called for each command of type T within a render pass.
4. end_pass(): Called at the end of each render pass that involved this pipeline.
5. end_frame(): Called once at the end of the frame, after all render passes are complete.

Typically, begin_pass, draw, and end_pass are used for the core rendering logic within a pass, while begin_frame and end_frame are used for setup and teardown that spans the entire frame.

Implementation Notes

• Only the draw() method is required; others have default empty implementations.
• Pipelines should be stateless between frames when possible
• Resource management should prefer reuse over recreation
• Consider batching multiple commands for better performance

Example

See the module-level documentation for a complete implementation example.

Required Methods

fn draw( &mut self, gpu: &Device, gpu_queue: &Queue, config: &SurfaceConfiguration, render_pass: &mut RenderPass<'_>, command: &T, size: PxSize, start_pos: PxPosition, scene_texture_view: &TextureView, )

Renders a single draw command.

This is the core method where the actual rendering happens. It’s called once for each draw command of type T that needs to be rendered.

Parameters

• gpu - The WGPU device for creating resources
• gpu_queue - The WGPU queue for submitting commands and updating buffers
• config - Current surface configuration containing format and size information
• render_pass - The active render pass to record draw commands into
• command - The specific draw command to render
• size - The size of the rendering area in pixels
• start_pos - The top-left position where rendering should begin
• scene_texture_view - View of the current scene texture for background sampling

Implementation Guidelines

• Update any per-command uniforms or push constants
• Set the appropriate render pipeline
• Bind necessary resources (textures, buffers, bind groups)
• Issue draw calls (typically draw(), draw_indexed(), or draw_indirect())
• Avoid expensive operations like buffer creation; prefer reusing resources

Scene Texture Usage

The scene_texture_view provides access to the current rendered scene, enabling effects that sample from the background. This is commonly used for:

• Blur and post-processing effects
• Glass and transparency effects
• Distortion and refraction

Example

fn draw(&mut self, gpu: &wgpu::Device, gpu_queue: &wgpu::Queue,
        config: &wgpu::SurfaceConfiguration, render_pass: &mut wgpu::RenderPass<'_>,
        command: &MyCommand, size: PxSize, start_pos: PxPosition,
        scene_texture_view: &wgpu::TextureView) {
    // Update uniforms with command-specific data
    let uniforms = MyUniforms {
        color: command.color,
        position: [start_pos.x as f32, start_pos.y as f32],
        size: [size.width as f32, size.height as f32],
    };
    gpu_queue.write_buffer(&self.uniform_buffer, 0, bytemuck::cast_slice(&[uniforms]));
     
    // Set pipeline and resources
    render_pass.set_pipeline(&self.render_pipeline);
    render_pass.set_bind_group(0, &self.bind_group, &[]);
     
    // Draw a quad (two triangles)
    render_pass.draw(0..6, 0..1);
}

Provided Methods

fn begin_frame( &mut self, gpu: &Device, gpu_queue: &Queue, config: &SurfaceConfiguration, )

Called once at the beginning of the frame, before any render passes.

This method is the first hook in the pipeline’s frame lifecycle. It’s invoked after a new CommandEncoder has been created but before any rendering occurs. It’s ideal for per-frame setup that is not tied to a specific wgpu::RenderPass.

Since this method is called outside a render pass, it cannot be used for drawing commands. However, it can be used for operations like:

• Updating frame-global uniform buffers (e.g., with time or resolution data) using [wgpu::Queue::write_buffer].
• Preparing or resizing buffers that will be used throughout the frame.
• Performing CPU-side calculations needed for the frame.

Parameters

• gpu - The WGPU device, for resource creation.
• gpu_queue - The WGPU queue, for submitting buffer writes.
• config - The current surface configuration.

Default Implementation

The default implementation does nothing.

fn begin_pass( &mut self, gpu: &Device, gpu_queue: &Queue, config: &SurfaceConfiguration, render_pass: &mut RenderPass<'_>, )

Called once at the beginning of the render pass.

Use this method to perform one-time setup operations that apply to all draw commands of this type in the current frame. This is ideal for:

• Setting up shared uniform buffers
• Binding global resources
• Configuring render state that persists across multiple draw calls

Parameters

• gpu - The WGPU device for creating resources
• gpu_queue - The WGPU queue for submitting commands
• config - Current surface configuration
• render_pass - The active render pass

Default Implementation

The default implementation does nothing, which is suitable for most pipelines.

fn end_pass( &mut self, gpu: &Device, gpu_queue: &Queue, config: &SurfaceConfiguration, render_pass: &mut RenderPass<'_>, )

Called once at the end of the render pass.

Use this method to perform cleanup operations or finalize rendering for all draw commands of this type in the current frame. This is useful for:

• Cleaning up temporary resources
• Finalizing multi-pass rendering operations
• Submitting batched draw calls

Parameters

• gpu - The WGPU device for creating resources
• gpu_queue - The WGPU queue for submitting commands
• config - Current surface configuration
• render_pass - The active render pass

Default Implementation

The default implementation does nothing, which is suitable for most pipelines.

fn end_frame( &mut self, gpu: &Device, gpu_queue: &Queue, config: &SurfaceConfiguration, )

Called once at the end of the frame, after all render passes are complete.

This method is the final hook in the pipeline’s frame lifecycle. It’s invoked after all begin_pass, draw, and end_pass calls for the frame have completed, but before the frame’s command buffer is submitted to the GPU.

It’s suitable for frame-level cleanup or finalization tasks, such as:

• Reading data back from the GPU (though this can be slow and should be used sparingly).
• Cleaning up temporary resources created in begin_frame.
• Preparing data for the next frame.

Parameters

• gpu - The WGPU device.
• gpu_queue - The WGPU queue.
• config - The current surface configuration.

Default Implementation

The default implementation does nothing.

Implementors