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 async fn init_headless( &mut self, width: u32, height: u32, format: Option<PixelFormat>, ) -> Result<(), Error>

Phase 2 (headless): Initialize GPU context without a window.

Creates an offscreen render target of the specified dimensions. No window surface is created, making this suitable for server-side rendering, automated testing, and GPU readback workflows.

Arguments

• width — Render target width in pixels.
• height — Render target height in pixels.
• format — Desired pixel format. Pass None for the default Rgba8Unorm (sRGB). Use Some(Rgba16Float) for HDR readback.

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/render-target texture format.

In windowed mode this is the swap-chain format; in headless mode it is the offscreen texture format. Returns None before initialisation.

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>

pub fn register_shader_template(&mut self, name: &str, source: &str)

Registers a custom WGSL shader template with the given name.

The source string is pre-processed by the minijinja template engine at compile time, so {$ include "chunks/camera_uniforms.wgsl" $} and similar directives are fully supported.

Usage

renderer.register_shader_template(
    "custom_unlit",
    include_str!("shaders/custom_unlit.wgsl"),
);

After registration, any material declared with #[myth_material(shader = "custom_unlit")] will use this template.

Panics

Panics if the renderer has not been initialized via init.

pub fn is_headless(&self) -> bool

Returns true if the renderer is in headless (offscreen) mode.

pub fn readback_pixels(&mut self) -> Result<Vec<u8>, Error>

Reads back the current headless render target as raw pixel data.

The returned Vec<u8> contains tightly-packed pixel data whose per-pixel byte count matches the headless texture format (e.g. 4 bytes for RGBA8, 8 bytes for RGBA16Float). Row ordering is top-to-bottom.

A staging buffer is cached internally and re-used across calls as long as the required size has not changed, eliminating per-frame allocation.

This method submits a GPU copy command and blocks the calling thread until the transfer completes.

Errors

Returns an error if:

• The renderer has not been initialised
• No headless render target exists (windowed mode)
• The GPU buffer mapping fails

pub fn create_readback_stream( &self, buffer_count: usize, max_stash_size: usize, ) -> Result<ReadbackStream, Error>

Creates a [ReadbackStream] backed by the headless render target.

The stream pre-allocates buffer_count staging buffers that rotate in a ring, enabling fully non-blocking GPU→CPU readback suitable for video recording and AI training-data pipelines.

Errors

Returns an error if the renderer is not initialised or not in headless mode, or if the texture format does not support readback.

pub fn poll_device(&self)

Drives pending GPU callbacks without blocking.

Call this once per frame in a readback-stream loop so that map_async callbacks fire and frames become available via [ReadbackStream::try_recv].

pub fn headless_texture(&self) -> Option<&Texture>

Returns a reference to the headless render target texture, if present.