Crate retroglyph_core 

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), diffing each frame drawn through Surface against the previous one so only changed cells reach the Backend. B is the only thing that changes between a headless test and a real window or terminal: Headless here, Crossterm (retroglyph-crossterm) for a real TTY, SoftwareRenderer/GlRenderer/WgpuRenderer for a window or browser tab. See https://main.retroglyph.dev/book/explanation/architecture.html for the full data-flow diagram and how those backends compare.

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.