Struct Frame 

pub struct Frame<'w> { /* private fields */ }

Context for a single frame of rendering.

Frame represents a single frame being rendered. It holds the acquired surface texture and collects command buffers from render passes. When dropped, it automatically submits all command buffers and presents the surface.

Key Design Points

• Immutable reference: RenderPasses take &Frame, not &mut Frame
• RefCell for command buffers: Allows multiple passes without mutable borrow
• Atomic stats: Thread-safe pass/draw counting
• RAII cleanup: Drop handles submit and present

Example

let frame = window.begin_frame().expect("Surface available");

// Create first pass
{
    let mut pass = frame.render_pass()
        .clear_color(Color::BLACK)
        .build();
    // Render background
}

// Create second pass (different encoder)
{
    let mut pass = frame.render_pass()
        .load_color()
        .build();
    // Render UI overlay
}

// Auto-submits on drop

Implementations

impl<'w> Frame<'w>

pub fn surface_view(&self) -> &TextureView

Get the surface texture view for this frame.

Panics

Panics if the surface has been consumed. Use try_surface_view() for fallible access.

pub fn try_surface_view(&self) -> Option<&TextureView>

Try to get the surface texture view for this frame.

pub fn depth_view(&self) -> Option<&TextureView>

Get the window’s depth texture view, if the window was created with depth.

This provides access to the window-owned depth buffer for render passes that need depth testing.

pub fn surface_format(&self) -> TextureFormat

Get the surface texture format.

pub fn size(&self) -> (u32, u32)

Get the frame size in physical pixels.

pub fn graphics(&self) -> &GraphicsContext

Get the graphics context.

pub fn device(&self) -> &Device

Get the wgpu device.

pub fn queue(&self) -> &Queue

Get the wgpu queue.

pub fn stats(&self) -> FrameStats

Get frame statistics.

pub fn gpu_profiler(&self) -> Option<&GpuFrameProfiler>

Get the GPU profiler if attached.

pub fn has_gpu_profiler(&self) -> bool

Check if GPU profiling is active.

pub fn create_encoder(&self, label: Option<&str>) -> CommandEncoder

Create a command encoder for custom command recording.

Use this for operations that don’t fit the render pass model, like buffer copies or texture uploads.

pub fn add_command_buffer(&self, buffer: CommandBuffer)

Add a pre-built command buffer to the frame.

Use this when you have custom command recording logic.

pub fn render_pass(&self) -> RenderPassBuilder<'_, 'w>

Start building a render pass.

Returns a builder that can be configured with target, clear operations, and depth settings before building the actual pass.

Examples found in repository

examples/camera_demo.rs (line 108)

    fn render(&mut self, _ctx: &mut AppCtx, window_id: WindowId, events: &mut EventBatch) {
        if window_id != self.window_id {
            return;
        }

        events.dispatch(|event| {
            if let astrelis_winit::event::Event::WindowResized(size) = event {
                self.window.resized(*size);
                astrelis_winit::event::HandleStatus::consumed()
            } else {
                astrelis_winit::event::HandleStatus::ignored()
            }
        });

        let Some(frame) = self.window.begin_frame() else {
            return; // Surface not available
        };
        {
            let _pass = frame
                .render_pass()
                .clear_color(Color::from_rgb_u8(20, 30, 40))
                .label("camera_demo_pass")
                .build();
        }
        // Frame auto-submits on drop
    }

examples/mesh_primitives.rs (line 110)

    fn render(&mut self, _ctx: &mut AppCtx, window_id: WindowId, events: &mut EventBatch) {
        if window_id != self.window_id {
            return;
        }

        events.dispatch(|event| {
            if let astrelis_winit::event::Event::WindowResized(size) = event {
                self.window.resized(*size);
                astrelis_winit::event::HandleStatus::consumed()
            } else {
                astrelis_winit::event::HandleStatus::ignored()
            }
        });

        let Some(frame) = self.window.begin_frame() else {
            return; // Surface not available
        };
        {
            let _pass = frame
                .render_pass()
                .clear_color(Color::from_rgb_u8(20, 30, 40))
                .label("mesh_primitives_pass")
                .build();
        }
        // Frame auto-submits on drop
    }

examples/render_graph_demo.rs (line 108)

    fn render(&mut self, _ctx: &mut AppCtx, window_id: WindowId, events: &mut EventBatch) {
        if window_id != self.window_id {
            return;
        }

        events.dispatch(|event| {
            if let astrelis_winit::event::Event::WindowResized(size) = event {
                self.window.resized(*size);
                astrelis_winit::event::HandleStatus::consumed()
            } else {
                astrelis_winit::event::HandleStatus::ignored()
            }
        });

        let Some(frame) = self.window.begin_frame() else {
            return; // Surface not available
        };
        {
            let _pass = frame
                .render_pass()
                .clear_color(Color::from_rgb_u8(20, 30, 40))
                .label("render_graph_demo_pass")
                .build();
        }
        // Frame auto-submits on drop
    }

examples/window_manager_demo.rs (line 108)

    fn render(&mut self, _ctx: &mut AppCtx, window_id: WindowId, events: &mut EventBatch) {
        // Get the color for this window
        let Some(&color) = self.window_colors.get(&window_id) else {
            return;
        };

        // WindowManager automatically handles:
        // 1. Window lookup (no manual HashMap.get_mut)
        // 2. Resize events (automatic)
        // 3. Event dispatching
        self.window_manager
            .render_window(window_id, events, |window, _events| {
                // No need to manually handle resize events!
                // WindowManager already did that for us

                // Just render!
                let Some(frame) = window.begin_frame() else {
                    return; // Surface not available
                };

                {
                    let _pass = frame
                        .render_pass()
                        .clear_color(color)
                        .label("window_manager_pass")
                        .build();
                    // Additional rendering would go here
                }
                // Frame auto-submits on drop
            });
    }

examples/material_system.rs (line 131)

    fn render(&mut self, _ctx: &mut AppCtx, window_id: WindowId, events: &mut EventBatch) {
        if window_id != self.window_id {
            return;
        }

        // Handle resize
        events.dispatch(|event| {
            if let astrelis_winit::event::Event::WindowResized(size) = event {
                self.window.resized(*size);
                astrelis_winit::event::HandleStatus::consumed()
            } else {
                astrelis_winit::event::HandleStatus::ignored()
            }
        });

        // In a real application, materials would be bound during rendering:
        // material.bind(&mut render_pass);
        // draw_mesh(&mesh);

        // Begin frame
        let Some(frame) = self.window.begin_frame() else {
            return; // Surface not available
        };

        {
            let _pass = frame
                .render_pass()
                .clear_color(Color::from_rgb_u8(20, 30, 40))
                .label("material_system_pass")
                .build();
            // Materials would be applied here in actual rendering
            // This is a conceptual demonstration
        }
        // Frame auto-submits on drop
    }

examples/sprite_sheet.rs (line 456)

    fn render(
        &mut self,
        _ctx: &mut astrelis_winit::app::AppCtx,
        window_id: WindowId,
        events: &mut astrelis_winit::event::EventBatch,
    ) {
        let Some(window) = self.windows.get_mut(&window_id) else {
            return;
        };

        // Handle resize
        events.dispatch(|event| {
            if let astrelis_winit::event::Event::WindowResized(size) = event {
                window.resized(*size);
                astrelis_winit::event::HandleStatus::consumed()
            } else {
                astrelis_winit::event::HandleStatus::ignored()
            }
        });

        let Some(frame) = window.begin_frame() else {
            return; // Surface not available
        };
        {
            let mut pass = frame
                .render_pass()
                .clear_color(Color::rgb(0.1, 0.1, 0.15))
                .label("sprite_sheet_pass")
                .build();
            pass.set_pipeline(&self.pipeline);
            pass.set_bind_group(0, &self.bind_group, &[]);
            pass.set_vertex_buffer(0, self.vertex_buffer.slice(..));
            pass.draw(0..6, 0..1);
        }
        // Frame auto-submits on drop
    }

Additional examples can be found in:

• examples/image_blitting.rs
• examples/textured_window.rs
• examples/multi_window.rs
• examples/profiling_demo.rs
• examples/renderer_api.rs
• examples/batched_renderer.rs
• examples/performance_benchmark.rs

pub fn compute_pass(&self) -> ComputePassBuilder<'_, 'w>

Start building a compute pass.

pub fn submit(self)

Submit all collected command buffers and present the surface.

This is called automatically on drop, but can be called explicitly for more control over timing.

Trait Implementations

impl Drop for Frame<'_>

fn drop(&mut self)

Executes the destructor for this type.