euv_engine/engine/

impl.rs

use crate::*;

/// Implements the top-level static engine entry points on the `Engine` namespace.
///
/// Mirrors the role of `euv::App`: every public engine operation begins
/// with an `Engine::xxx` call, and `Engine` itself holds no state.
impl Engine {
    /// Creates a new engine handle bound to the given configuration.
    ///
    /// The handle is uninitialized; call `init_canvas` / `init_webgpu` and
    /// `start` on the returned handle to begin the game loop, or use
    /// `Engine::run` for the one-line equivalent.
    ///
    /// # Arguments
    ///
    /// - `EngineConfig` - The engine configuration.
    ///
    /// # Returns
    ///
    /// - `EngineHandle` - The new uninitialized engine handle.
    pub fn new_handle(config: EngineConfig) -> EngineHandle {
        EngineHandle::new(config, None, None, None)
    }

    /// Runs the engine through its complete lifecycle in a single async call.
    ///
    /// Equivalent to calling `Engine::new_handle(config)` followed by
    /// `init_canvas` / `init_webgpu` (matching the chosen backend) and
    /// `start(handler)`. The returned handle can still be used to stop
    /// the loop later via `handle.stop()`.
    ///
    /// # Arguments
    ///
    /// - `EngineConfig` - The engine configuration.
    /// - `TickHandlerRc` - The tick handler receiving update and render callbacks.
    ///
    /// # Returns
    ///
    /// - `EngineHandle` - A handle to the running engine. If renderer
    ///   initialization failed the handle's renderer field will be `None`
    ///   and `is_running` will be `false`. Initialization errors are not
    ///   logged inside the engine; callers should call `init_webgpu`
    ///   directly if they need access to the typed `WebGpuInitError`.
    pub async fn run(config: EngineConfig, handler: TickHandlerRc) -> EngineHandle {
        let mut handle: EngineHandle = Engine::new_handle(config);
        match handle.get_config().get_render().get_backend() {
            RenderBackendType::Canvas2D => {
                handle.init_canvas();
            }
            RenderBackendType::WebGpu => {
                let _ = handle.init_webgpu().await;
            }
        }
        handle.start(handler);
        handle
    }

    /// Returns the default engine configuration.
    ///
    /// Uses `RenderConfig::default()` (Canvas 2D backend) and the default
    /// scheduler configuration (60 Hz fixed timestep).
    ///
    /// # Returns
    ///
    /// - `EngineConfig` - The default engine configuration.
    pub fn default_config() -> EngineConfig {
        EngineConfig::default()
    }

    /// Creates a Canvas 2D renderer directly from a render configuration.
    ///
    /// Use this when you want a `CanvasRenderer` without going through
    /// the full `EngineHandle` lifecycle (for example, in a custom render
    /// loop that does not use the fixed-timestep scheduler).
    ///
    /// # Arguments
    ///
    /// - `&RenderConfig` - The rendering configuration.
    ///
    /// # Returns
    ///
    /// - `Option<CanvasRenderer>` - The renderer, or `None` if the canvas element was not found.
    pub fn canvas_renderer(config: &RenderConfig) -> Option<CanvasRenderer> {
        CanvasRenderer::from_selector(
            config.get_canvas_selector(),
            config.get_width(),
            config.get_height(),
        )
    }

    /// Creates a WebGPU renderer directly from a render configuration.
    ///
    /// Async because GPU adapter and device acquisition returns JavaScript
    /// Promises that must be awaited. Mirrors `Engine::canvas_renderer` for
    /// callers that want the renderer without the full engine handle.
    ///
    /// Failures are surfaced as `WebGpuInitError` so the caller can decide
    /// how to react (typically by logging via `Console::error` or by
    /// falling back to the Canvas 2D backend).
    ///
    /// # Arguments
    ///
    /// - `&RenderConfig` - The rendering configuration.
    ///
    /// # Returns
    ///
    /// - `Result<WebGpuRenderer, WebGpuInitError>` - The initialized renderer,
    ///   or a typed error describing the specific failure.
    pub async fn webgpu_renderer(config: &RenderConfig) -> Result<WebGpuRenderer, WebGpuInitError> {
        WebGpuRenderer::init(config).await
    }
}

/// Implements lifecycle management for `EngineHandle`.
///
/// All getter methods (`get_config`, `get_canvas_renderer`, `get_webgpu_renderer`)
/// are generated by the `Data` derive on the struct definition; this impl
/// only contributes lifecycle and accessor behavior that is not expressible
/// as a plain getter.
impl EngineHandle {
    /// Initializes the Canvas 2D rendering backend.
    ///
    /// On success, populates `canvas_renderer` and clears `webgpu_renderer`.
    /// On failure, both renderer fields remain `None`.
    ///
    /// # Returns
    ///
    /// - `bool` - `true` if the renderer was created successfully.
    pub fn init_canvas(&mut self) -> bool {
        let render_config: &RenderConfig = &self.get_config().get_render();
        let renderer: Option<CanvasRenderer> = CanvasRenderer::from_selector(
            render_config.get_canvas_selector(),
            render_config.get_width(),
            render_config.get_height(),
        );
        match renderer {
            Some(r) => {
                self.set_canvas_renderer(Some(r));
                self.set_webgpu_renderer(None);
                true
            }
            None => {
                self.set_canvas_renderer(None);
                self.set_webgpu_renderer(None);
                false
            }
        }
    }

    /// Initializes the WebGPU rendering backend.
    ///
    /// On success, populates `webgpu_renderer` and clears `canvas_renderer`.
    /// On failure, both renderer fields remain `None` and the typed error is
    /// returned so the caller can decide how to surface it (typically via
    /// `Console::error`).
    ///
    /// # Returns
    ///
    /// - `Result<WebGpuRenderer, WebGpuInitError>` - The initialized renderer,
    ///   or a typed error describing the specific failure.
    pub async fn init_webgpu(&mut self) -> Result<WebGpuRenderer, WebGpuInitError> {
        let render_config: &RenderConfig = &self.get_config().get_render();
        let renderer: WebGpuRenderer = WebGpuRenderer::init(render_config).await?;
        self.set_webgpu_renderer(Some(renderer.clone()));
        self.set_canvas_renderer(None);
        Ok(renderer)
    }

    /// Starts the game loop with the given tick handler.
    ///
    /// The scheduler configuration from `EngineConfig` controls the fixed
    /// timestep and maximum frame time. The scheduler handle is stored
    /// internally and can be stopped via `stop`.
    ///
    /// # Arguments
    ///
    /// - `TickHandlerRc` - The tick handler receiving update and render callbacks.
    pub fn start(&mut self, handler: TickHandlerRc) {
        let scheduler_config: SchedulerConfig = self.get_config().get_scheduler();
        self.set_scheduler_handle(Some(SchedulerHandle::start(scheduler_config, handler)));
    }

    /// Stops the game loop and cancels any pending animation frame request.
    pub fn stop(&self) {
        if let Some(handle) = self.try_get_scheduler_handle().as_ref() {
            handle.stop();
        }
    }

    /// Returns whether the game loop is currently running.
    ///
    /// # Returns
    ///
    /// - `bool` - `true` if the scheduler is running.
    pub fn is_running(&self) -> bool {
        self.try_get_scheduler_handle()
            .as_ref()
            .is_some_and(|handle: &SchedulerHandle| handle.is_running())
    }
}