Struct Engine 

pub struct Engine {
    pub renderer: Renderer,
    pub scene_manager: SceneManager,
    pub assets: AssetServer,
    pub input: Input,
    /* private fields */
}

The core engine instance that orchestrates all rendering subsystems.

Engine is a pure engine implementation without window management, making it suitable for integration with various windowing systems and platforms.

Components

• renderer: The rendering subsystem handling GPU operations
• scene_manager: Manages multiple scenes and active scene selection
• assets: Central asset storage for geometries, materials, textures, etc.
• input: Unified input state (keyboard, mouse, touch)

Lifecycle

1. Create with Engine::new or Engine::default
2. Initialize GPU with Engine::init
3. Update each frame with Engine::update
4. Render using Renderer::begin_frame

Fields

renderer: Renderer

scene_manager: SceneManager

assets: AssetServer

input: Input

Implementations

impl Engine

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

Creates a new engine instance with the specified configuration.

This only creates the engine configuration. GPU resources are not allocated until init is called.

Arguments

• init_config - Static GPU initialization parameters
• settings - Runtime rendering settings

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

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

Initializes GPU resources with the given window.

This method must be called before any rendering can occur. It accepts any type that implements the raw window handle traits, making it compatible with various windowing libraries.

Arguments

• window - A window that provides display and window handles
• width - Initial surface width in pixels
• height - Initial surface height in pixels

Errors

Returns an error if GPU initialization fails due to:

• No compatible GPU adapter found
• Device request failed (unsupported features/limits)
• Surface configuration failed

pub async fn init_headless( &mut self, width: u32, height: u32, format: Option<PixelFormat>, ) -> Result<(), Error>

Initializes the GPU context in headless (offscreen) mode.

No window or surface is created. An offscreen render target of the specified dimensions is allocated instead, suitable for server-side rendering, automated testing, and GPU readback.

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.

Errors

Returns an error if GPU initialization fails.

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 byte count per pixel matches the headless texture format. A staging buffer is cached internally to avoid per-frame allocation.

Errors

Returns an error if the renderer is not initialised or not in headless mode.

pub fn submit_to_stream(&self, stream: &mut ReadbackStream) -> Result<(), Error>

Submits the current headless frame to a ReadbackStream (non-blocking).

Returns [ReadbackError::RingFull] if all ring-buffer slots are in-flight. The caller may skip the frame or drain with ReadbackStream::try_recv first.

pub fn submit_to_stream_blocking( &self, stream: &mut ReadbackStream, ) -> Result<(), Error>

Submits the current headless frame to a ReadbackStream, blocking when the ring buffer is full.

Completed frames are stashed internally and can be retrieved via ReadbackStream::try_recv or ReadbackStream::try_recv_into. max_stash_size caps the number of unconsumed stashed frames to prevent unbounded memory growth.

pub fn flush_stream( &self, stream: &mut ReadbackStream, ) -> Result<Vec<ReadbackFrame>, Error>

Flushes a ReadbackStream, blocking until all in-flight frames are returned.

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.

pub fn time(&self) -> f32

Returns the total elapsed time in seconds since the engine started.

pub fn frame_time(&self) -> FrameTime

pub fn frame_count(&self) -> u64

Returns the total number of frames rendered since startup.

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

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

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

Handles window resize events.

This method should be called whenever the window size changes. It updates the renderer’s surface configuration and camera aspect ratios.

Arguments

• width - New width in pixels
• height - New height in pixels

pub fn update(&mut self, dt: f32)

Updates the engine state for the current frame.

This method should be called once per frame before rendering. It:

• Processes completed background asset loads
• Updates the total elapsed time and frame counter
• Runs scene logic and animations
• Resets per-frame input state

Arguments

• dt - Delta time since the last frame in seconds

pub fn maybe_prune(&mut self)

Performs periodic resource cleanup.

This method should be called after each frame to release unused GPU resources and prevent memory leaks. It uses internal heuristics to avoid expensive cleanup operations on every frame.

pub fn render_active_scene(&mut self) -> bool

Renders the active scene using the active camera.

This is a convenience method that combines scene lookup, camera extraction, and frame rendering into a single call. It avoids the split-borrow issues that arise when accessing the renderer and scene manager separately.

Returns true if a frame was successfully rendered, false if rendering was skipped (no active scene, no active camera, etc.).

Trait Implementations

impl Default for Engine

fn default() -> Engine

Returns the “default value” for a type.