Struct Renderer 

pub struct Renderer { /* private fields */ }

The main renderer responsible for GPU rendering operations.

The renderer manages the complete rendering pipeline including:

• GPU context (device, queue, surface)
• Resource management (buffers, textures, bind groups)
• Pipeline caching (shader compilation, PSO creation)
• Frame rendering (scene extraction, command submission)

Lifecycle

1. Create with Renderer::new (no GPU resources allocated)
2. Initialize GPU with Renderer::init
3. Render frames with Renderer::begin_frame
4. Clean up with Renderer::maybe_prune

Implementations

impl Renderer

pub fn new( init_config: RendererInitConfig, settings: RendererSettings, ) -> Renderer

Phase 1: Create configuration (no GPU resources yet).

This only stores the render settings. GPU resources are allocated when init is called.

Arguments

• init_config - Static GPU/device configuration (consumed at init time)
• settings - Runtime rendering settings (can be changed later via update_settings)

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

Returns the current surface size in pixels as (width, height).

pub async fn init<W>( &mut self, window: W, width: u32, height: u32, ) -> Result<(), Error>

where W: HasWindowHandle + HasDisplayHandle + Send + Sync + 'static,

Phase 2: Initialize GPU context with window handle.

This method:

1. Creates the wgpu instance and adapter
2. Requests a device with required features/limits
3. Configures the surface for presentation
4. Initializes resource manager and pipeline cache

pub fn resize(&mut self, width: u32, height: u32)

pub fn begin_frame<'a>( &'a mut self, scene: &'a mut Scene, camera: &'a RenderCamera, assets: &'a AssetServer, frame_time: FrameTime, ) -> Option<FrameComposer<'a>>

Begins building a new frame for rendering.

Returns a FrameComposer that provides a chainable API for configuring the render pipeline via custom pass hooks.

Usage

// Method 1: Use default built-in passes
if let Some(composer) = renderer.begin_frame(scene, camera, assets, time) {
    composer.render();
}

// Method 2: With custom hooks (e.g., UI overlay)
if let Some(composer) = renderer.begin_frame(scene, camera, assets, time) {
    composer
        .add_custom_pass(HookStage::AfterPostProcess, |graph, bb| {
            ui_pass.target_tex = bb.surface_out;
            graph.add_pass(&mut ui_pass);
        })
        .render();
}

Returns

Returns Some(FrameComposer) if frame preparation succeeds, or None if rendering should be skipped (e.g., window size is 0).

pub fn maybe_prune(&mut self)

Performs periodic resource cleanup.

Should be called after each frame to release unused GPU resources. Uses internal heuristics to avoid expensive cleanup every frame.

pub fn render_path(&self) -> &RenderPath

Returns the current RenderPath.

pub fn settings(&self) -> &RendererSettings

Returns a reference to the current runtime renderer settings.

pub fn init_config(&self) -> &RendererInitConfig

Returns a reference to the init-time configuration.

pub fn update_settings(&mut self, new_settings: RendererSettings)

Applies new runtime settings, performing an internal diff to update only the parts that actually changed.

This is the single entry point for all runtime configuration changes. Callers (UI panels, scripting layers, etc.) should maintain their own RendererSettings instance, mutate it, and pass it here.

pub fn set_render_path(&mut self, path: RenderPath)

Switches the active render path at runtime.

Convenience wrapper around update_settings for changing only the render path.

pub fn device(&self) -> Option<&Device>

Returns a reference to the wgpu Device.

Useful for external plugins to initialize GPU resources.

pub fn queue(&self) -> Option<&Queue>

Returns a reference to the wgpu Queue.

Useful for external plugins to submit commands.

pub fn surface_format(&self) -> Option<TextureFormat>

Returns the surface texture format.

Useful for external plugins to configure render pipelines.

pub fn wgpu_ctx(&self) -> Option<&WgpuContext>

Returns a reference to the WgpuContext.

For external plugins that need access to low-level GPU resources. Only available after renderer initialization.

pub fn dump_graph_mermaid(&self) -> Option<String>