markdown --- sidebar_position: 2 title: Engine API --- # Engine Module API Reference The `engine` module defines the core interfaces for how OSUI applications run, render, and execute commands. It provides abstractions for different rendering backends and includes a default console implementation. ## `Engine` Trait ```rust pub trait Engine { fn run(&self, component: C) -> crate::Result; fn init(&self, component: C) -> Arc; fn render(&self, cx: &Arc); fn render_delay(&self); fn render_view(&self, area: &Area, view: &View) -> DrawContext; fn draw_context(&self, ctx: &DrawContext); fn executor(&self) -> Arc; } ``` The `Engine` trait is the primary interface for running an OSUI application. It abstracts away the specifics of how components are initialized, rendered, and how the application loop is managed. #### Associated Types / Generics: * **`Output`**: A generic type that allows `run` to return different results. By default, it's `()`, but for specialized engines (like `Benchmark`), it can return custom data. #### Methods: * **`fn run(&self, component: C) -> crate::Result`** * The main entry point to start the OSUI application loop. It takes the root component `C`, initializes it, and continuously renders until a stop command is issued. Returns `Ok(())` by default, or a custom `Output` for specialized engines. * **`fn init(&self, component: C) -> Arc`** * Initializes the rendering environment and creates the root `Context` for the application's top-level component. This is typically called by `run`. * **`fn render(&self, cx: &Arc)`** * Performs a full render cycle for the given `Context`. This usually involves clearing the screen, calling `render_view` for the root, and then `draw_context`. * **`fn render_delay(&self)`** * A hook for introducing a delay between render frames. The default implementation calls `crate::sleep(16)` for approximately 60 frames per second. * **`fn render_view(&self, area: &Area, view: &View) -> DrawContext`** * Takes a `View` and the `Area` it should render within, executing the `View`'s closure to produce a `DrawContext` filled with `DrawInstruction`s. * **`fn draw_context(&self, ctx: &DrawContext)`** * Executes the drawing instructions contained within a `DrawContext` to actually draw content to the rendering target (e.g., the terminal). * **`fn executor(&self) -> Arc`** * Returns the `CommandExecutor` instance used by this engine. ## `Command` Trait ```rust pub trait Command { fn as_any(&self) -> &dyn Any; } ``` The `Command` trait is implemented by types that represent actions or instructions that can be executed by the `CommandExecutor`. This trait enables a type-safe way to send commands between components and the engine. * **`fn as_any(&self) -> &dyn Any`**: Allows downcasting the command to its concrete type for pattern matching and execution. ## `CommandExecutor` Trait ```rust pub trait CommandExecutor: Send + Sync { fn execute_command(&self, command: &Arc) -> crate::Result<()>; } ``` The `CommandExecutor` trait defines how commands are processed within the OSUI application. Engines provide their own implementations of this trait to handle system-level operations. * **`fn execute_command(&self, command: &Arc) -> crate::Result<()>`**: Takes an `Arc` wrapped `Command` and executes it. Implementations typically use `command.as_any().downcast_ref()` to identify and process specific commands. ## `console` Module: `Console` Engine and `ConsoleExecutor` The `console` module provides OSUI's default, `crossterm`-based rendering engine. ### `Console` Struct ```rust pub struct Console { threads: Mutex) + Send + Sync>>>, executor: Arc, } ``` The `Console` struct implements the `Engine` trait, specifically designed to render to a terminal using `crossterm`. #### Methods: * **`fn new() -> Self`**: Creates a new `Console` engine. * **`fn thread) + Send + Sync + 'static>(&self, run: F)`**: Registers a closure to be run in a separate thread when the engine initializes. This is useful for background tasks or input polling that needs access to the main `Context`. #### `Engine` Trait Implementation: The `Console` implements all methods of the `Engine` trait, handling terminal setup (raw mode, cursor hiding), screen clearing, `crossterm` cursor movements, and text output. ### `ConsoleExecutor` Struct ```rust pub struct ConsoleExecutor { running: Mutex, } ``` The `ConsoleExecutor` implements the `CommandExecutor` trait for the `Console` engine. It manages the `running` state of the application. #### Methods: * **`fn is_running(self: &Arc) -> bool`**: Checks if the application is currently running. * **`fn stop(&self) -> crate::Result<()>`**: Sets the internal `running` flag to `false`, signaling the `Console` engine to terminate its `run` loop. #### `CommandExecutor` Trait Implementation: The `ConsoleExecutor` currently supports handling the `commands::Stop` command. ## `commands` Module: Built-in Commands The `commands` module defines simple, built-in commands for the engine. ### `Stop` Command ```rust pub struct Stop; impl Command for Stop { fn as_any(&self) -> &dyn std::any::Any; } ``` A basic command used to signal the `Engine` to stop its main loop and exit the application. ## `benchmark` Module: `Benchmark` Engine The `benchmark` module provides a wrapper engine for performance testing. ### `BenchmarkResult` Struct ```rust pub struct BenchmarkResult { pub average: u128, pub min: u128, pub max: u128, pub total_render: u128, pub total: u128, } ``` Holds the statistical results of a benchmark run, including average, minimum, maximum, total render time, and total overall time in microseconds. ### `Benchmark` Struct ```rust pub struct Benchmark(T); ``` A wrapper around any other `Engine` that measures its rendering performance. #### Methods: * **`fn new(engine: T) -> Self`**: Creates a new `Benchmark` wrapper around an existing `Engine` instance. #### `Engine` Trait Implementation: The `Benchmark` engine implements the `Engine` trait, but its `run` method performs multiple render cycles (e.g., 40 times), measures the duration of each, and returns a `BenchmarkResult` instead of `()`. It delegates all other `Engine` methods to the wrapped engine. This comprehensive set of traits and implementations allows OSUI to be flexible regarding its rendering backend and extensible with custom command handling. **Next:** Explore the [Frontend API](./frontend-api.md).