Crate retroglyph_core

Expand description

retroglyph-core: the no_std-compatible foundation of retroglyph.

Grid, tile, style, color, text, terminal, and event types, plus the Output/Input/Cursor backend facets (bundled together as Backend) and the dependency-free Headless test backend, and the App/Flow/Frame game loop contract. Platform backends (retroglyph-crossterm, retroglyph-software) and drawing helpers (retroglyph-ui) are separate crates that depend on this one.

§Features

Default features: egc, std.

§`dev`

⚪ Optional.

Forces BuildMode::Dev on in a build that would otherwise resolve to Release.

Can be used so an optimized build still reports development diagnostics (see the dev module).

§`egc`

🟢 Enabled by default.

Enables grapheme-cluster-aware text handling (via unicode-segmentation) for EGC-correct cell diffing and layout.

§`libm`

⚪ Optional.

Uses libm’s software float implementation (roundf/fmaf/sinf/cosf/powf) for the separable BlendMode channel math, via this crate’s own math shim – the no_std side of that split. See std below for the alternative that prefers the platform’s own float intrinsics when available; a build needs exactly one of the two.

§`serde`

⚪ Optional.

Adds Serialize/Deserialize impls for Color, Style, Size, Offset, and (via ixy) Pos/Rect, so a config file can round-trip a saved camera position, window geometry, sub-cell pixel offset, or theme color.

Color serializes through its Display/FromStr round trip (e.g. "bright-red", "#ff8000") rather than a derived structural form, so hand-edited TOML/JSON stays legible.

§`std`

🟢 Enabled by default.

Enables gem/std and alpha-blend/std, and uses std’s float intrinsics (via this crate’s math shim) instead of libm’s software implementation for the separable BlendMode channel math.

Disabling this feature (--no-default-features) builds this crate no_std, and then needs libm above as the float backend instead: see the crate-level compile_error! in src/lib.rs.

§`testing`

⚪ Optional.

Enables testing’s TestHarness, which drives an App against Headless for tests, with synthetic input queuing and frame-settling helpers.

Test-only surface, no_std + alloc compatible, off by default so it never ships in a release build by accident.

§Architecture

Terminal<B> owns a double-buffered Grid and the Backend lifecycle (resize, present, events). Drawing itself goes entirely through Surface, handed out by Terminal::draw/Terminal::surface: a game calls term.draw(|s| { s.put(...); ... }) once per frame, and present diffs the current frame against the previous one, sending only changed cells to the Backend. B is the only thing that changes between a headless test and a real window or terminal:

              ┌───────────────────────────┐
              │      App::update(...)      │  game logic, once, generic over B
              └──────────────┬─────────────┘
                             │ term.draw(|s| ...): writes through Surface
                             ▼
              ┌───────────────────────────┐
              │       Terminal<B>          │  double-buffered Grid, cell diff
              └──────────────┬─────────────┘
                             │ draw / draw_layers / poll_event
                             ▼
              ┌───────────────────────────┐
              │  B: Output + Input + Cursor │  the only piece that swaps out
              └──────────────┬─────────────┘
                             │
       ┌─────────────────────┼─────────────────────┐
       ▼                     ▼                      ▼
 Headless (here)      Crossterm                SoftwareRenderer
 in-memory grid,      (retroglyph-crossterm)   (retroglyph-software)
 synthetic events     real TTY, ANSI output    winit window, pixels

Headless stores presented content in memory and lets tests inject synthetic Events with Headless::push_event; nothing here talks to a real terminal or window. Swapping Headless for Crossterm or SoftwareRenderer changes only the B type parameter – App implementations, Terminal calls, and game logic are unchanged. run_blocking drives Terminal<Headless> and Terminal<Crossterm> identically; the software backend’s windowed loop drives Terminal<SoftwareRenderer> through the same App contract, inverted because winit owns the event loop instead of handing control back to a driver function.

See examples/headless.rs (cargo run -p retroglyph-core --example headless) for the smallest possible use of Headless, depending on nothing but this crate.

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.
dev: Which diagnostics a build compiles in. Build-mode vocabulary: which diagnostics a build compiles in.
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.
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.
testingtesting: Headless test harness driving an App with synthetic input. Headless test harness driving an App with synthetic input.
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.

Macros§

dev_only: Runs body only in a build that compiles in development diagnostics.
spans: Build a Line from a list of (Style, text) pairs.