Crate retroglyph

Expand description

retroglyph: a 2D pseudographic terminal library, one dependency and one use.

Add this crate and you get the double-buffered Terminal/App game loop, styled cells, text and layout helpers, and input events – app, color, event, frames, grid, layout, surface, terminal, text, tile, symbols – plus a prelude with the handful of names a program can’t avoid, and one feature-gated module per backend (crossterm, software, gl, wgpu, terminal_wasm, ui). Writing a new backend instead of a game? Depend on retroglyph-core directly for its lower-level backend, dev, and math modules.

§Quick start

cargo add retroglyph

use retroglyph::crossterm::Crossterm;
use retroglyph::prelude::*;

struct Game;

impl App<Crossterm> for Game {
    fn update(&mut self, term: &mut Terminal<Crossterm>, _frame: &Frame) -> Flow {
        term.surface().put((5, 5), '@', Style::new().fg(Color::GREEN));

        if let Some(Event::Key(k)) = term.poll(std::time::Duration::from_secs(1)) {
            if k.code == KeyCode::Char('q') {
                return Flow::Exit;
            }
        }
        Flow::Continue
    }
}

fn main() -> std::io::Result<()> {
    retroglyph::app::run(Crossterm::new()?, Game)
}

Want a native window or a browser tab instead of a real terminal? Enable the software, gl, or wgpu feature instead of (or alongside) crossterm: same Terminal/App contract, a different Backend type. See each backend module’s own docs (and WindowConfig/run_app) for the windowed quick start.

§Features

Default features: crossterm, ui.

§`crossterm`

🟢 Enabled by default.

Re-exports retroglyph-crossterm as crossterm: a real-terminal Backend via crossterm.

§`default-font`

⚪ Optional.

Forwards each enabled backend’s own default-font feature (an embedded Unscii 16 bitmap font), so a caller doesn’t need to know which backend crate actually owns it.

§`gl`

⚪ Optional.

Re-exports retroglyph-gl as gl: a GPU Backend via glow (OpenGL 3.3 native, WebGL2 wasm). Also pulls in the curated windowed re-exports (WindowConfig, PresenterBuilder, Windowed, WindowedLaunchError, run_app, run_app_on).

§`serde`

⚪ Optional.

Adds Serialize/Deserialize impls to the curated types that support them (Color, Style, geometry, …, plus ui::theme::Theme/Density when ui is also enabled). Forwards to retroglyph-core’s and retroglyph-ui’s own serde features; neither backend crate has one.

§`software`

⚪ Optional.

Re-exports retroglyph-software as software: a CPU pixel Backend via softbuffer. Also pulls in the curated windowed re-exports (WindowConfig, PresenterBuilder, Windowed, WindowedLaunchError, run_app, run_app_on).

§`terminal-wasm`

⚪ Optional.

Re-exports retroglyph-terminal-wasm as terminal_wasm: a browser Backend driven by pushed/pulled ANSI I/O (e.g. xterm.js). Its #[wasm_bindgen] FFI module only compiles for target_arch = "wasm32", but the crate (and this re-export) build portably otherwise.

§`testing`

⚪ Optional.

Enables TestHarness and its error, the published headless App driver for testing your own App. Forwards to retroglyph-core’s own testing feature.

§`tilesets`

⚪ Optional.

Forwards each enabled backend’s own tilesets feature (PNG sprite/tileset loading), so a caller doesn’t need to know which backend crate actually owns it. Mirrors default-font above; see retroglyph_window::tileset for the TilesetOptions/ Codepage config types that feature adds – reach for retroglyph-window directly for those, same as any other finer-grained windowed control this facade doesn’t curate.

§`tracing`

⚪ Optional.

Forwards to retroglyph-crossterm’s tracing feature: instruments draw/flush/poll_event with tracing spans for profiling render/input time.

§`ui`

🟢 Enabled by default.

Re-exports retroglyph-ui as ui: the immediate-mode widget/layout toolkit.

§`wgpu`

⚪ Optional.

Re-exports retroglyph-wgpu as wgpu: a GPU Backend via wgpu (Vulkan, Metal, D3D12, WebGPU). Also pulls in the curated windowed re-exports (WindowConfig, PresenterBuilder, Windowed, WindowedLaunchError, run_app, run_app_on).

Re-exports§

pub use retroglyph_crossterm as crossterm;crossterm
pub use retroglyph_gl as gl;gl
pub use retroglyph_software as software;software
pub use retroglyph_terminal_wasm as terminal_wasm;terminal-wasm
pub use retroglyph_ui as ui;ui
pub use retroglyph_wgpu as wgpu;wgpu

Modules§

app: The App-driven game loop. The App-driven game loop.
backend: Pluggable rendering backends. Pluggable rendering backends.
color: Color and style types for character cells: Color (this module) and Style, a {fg, bg} pair of two Colors with no other relation to anything else in this crate.
event: Input event system.
frames: FrameClock/FrameStats accumulators for the App/Frame game loop. FrameClock and FrameStats, the two accumulators behind the App/Frame game loop.
grid: The layered tile grid: Grid, plus the Size, Pos, and Rect coordinate types used throughout the crate.
layout: Text layout: measurement, word wrapping, and bounded alignment.
prelude: The names a program cannot avoid, glob-importable in one line. The names a retroglyph program cannot avoid, glob-importable in one line (use retroglyph::prelude::*;): the App contract, the trait a backend’s own builder implements to be launched, the two style primitives, the input event/key types, and the geometry aliases every Surface/Backend call takes or returns, plus HasSize so .width()/.height() resolve on Size without a separate ixy import.
surface: The one grid-drawing primitive: an area-clipped, single-layer view over a Grid. Surface: an area-clipped, single-layer view over a Grid.
symbols: Border, gridline, and partial-block char data shared by widgets and backends. char data for drawing borders, gridlines, and partial-block glyphs, plus the pixel-to-glyph matching logic that picks one of those glyphs for a raw pixel block.
terminal: Terminal: construction, sizing, resizing, cursor control, and raw grid/backend access.
text: Styled text primitives: Span and Line.
tile: The atomic drawable unit (glyph, style, sub-cell offsets). Fundamental unit of the grid: a single drawable tile.

Structs§

TestHarnesstesting: Drives an App against a Headless backend: queues synthetic input, steps frames, and reads back the rendered view.
WindowConfiggl or software or wgpu: Window configuration for run_windowed / run_app.
Windowedgl or software or wgpu: Pairs a windowed backend’s PresenterBuilder with the window title Launch needs to open one.

Enums§

RunErrortesting: Error returned by TestHarness::settle when the queue held more staged frames than the step budget.
WindowedLaunchErrorgl or software or wgpu: The error Windowed’s Launch impl can fail with.

Traits§

Launch: The trait a backend’s own builder implements to be driven end to end by launch: the user names the backend (CrosstermOptions, Windowed<B>, …) and gets back that backend’s own unwrapped error, rather than a facade-wide one. See this trait’s own docs for why there is no unified error here (retroglyph::LaunchError, tracked by #430, is only needed if the facade grows an entry point that can return either backend’s error). A backend’s own entry point for driving an App, named at the call site rather than selected by which Cargo features happen to be enabled.
PresenterBuildergl or software or wgpu: The builder shape retroglyph-software, retroglyph-gl, and retroglyph-wgpu all implement.

Functions§

run_appgl or software or wgpu: Drive an App from the windowed event loop.
run_app_ongl or software or wgpu: Same as run_app, but takes an already-built Terminal instead of a bare presenter.
run_defaultsoftware: Picks a backend from this crate’s enabled Cargo features and drives app on it, using that backend’s own default configuration.