# `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
  `Content`s out of other `Content`s
* 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.