tek/engine/README.md

tek_engine

this crate provides the Engine trait, which defines an application's lifecycle.

currently, there is one kind of engine implemented, Tui. it uses ratatui to present an interactive user interface in text mode.

at launch, the Tui engine spawns two threads, a render thread and an input thread. (the application may spawn further threads, such as a jack thread.)

all threads communicate using shared ownership, Arc<RwLock> and Arc<Atomic>. the engine and application instances are expected to be wrapped in Arc<RwLock>; internally, those synchronization mechanisms may be used liberally.

rendering

the render thread continually invokes the Content::render method of the application to redraw the display. it does this efficiently by using ratatui's double buffering.

thus, for a type to be a valid application for engine E, it must implement the trait Content<E>, which allows it to display content to the engine's output.

the most important thing about the Content trait is that it composes:

• you can implement Content::content to build Contents out of other Contents
• and/or Content::area for custom positioning and sizing,
• and/or Content::render for custom rendering within the given Content's area.

the manner of output is determined by the Engine::Output type, a mutable pointer to which is passed to the render method, e.g. in the case of the Tui engine: fn render(&self, output: &mut TuiOutput)

you can use TuiOutput::blit and TuiOutput::place to draw at specified coordinates of the display, and/or directly modify the underlying ratatui::Buffer at output.buffer

rendering is intended to work with read-only access to the application state. if you really need to update values during rendering, use interior mutability.

input handling

the input thread polls for keyboard events and passes them onto the application's Handle::handle method.

thus, for a type to be a valid application for engine E, it must implement the trait Handle<E>, which allows it to respond to user input.

this thread has write access to the application state, and is responsible for mutating it in response to user activity.