# retroglyph-software - Complete API Documentation > Software (winit + softbuffer) pixel rendering backend for retroglyph **Version:** 0.0.0 **Authors:** Matan Lurey **License:** MIT **Repository:** https://github.com/crates-lurey-io/retroglyph **Keywords:** roguelike, terminal, grid, gamedev Generated: 2026-08-05 20:21:10 UTC Created by: [cargo-llms-txt](https://github.com/masinc/cargo-llms-txt) ## Table of Contents ### src/lib.rs - pub mod config - pub use retroglyph_window::{sprite_cache, tileset} - pub use surface::SurfaceError - pub use config::{SoftwareBackend, SoftwareBackendBuilder, SoftwareBackendError} - pub use retroglyph_window::font::{BitmapFont, FontChain} - pub struct SoftwareRenderer - impl SoftwareRenderer - impl SoftwareBackend - impl Output for SoftwareRenderer - impl Input for SoftwareRenderer - impl Cursor for SoftwareRenderer - impl retroglyph_window::Presenter for SoftwareRenderer - impl tests::SoftwareObserver - impl Output for tests::SoftwareObserver - impl tests::SoftwareObserver - impl Cursor for tests::SoftwareObserver - impl retroglyph_core::testing::conformance::Observable for tests::SoftwareObserver ### src/config.rs - pub enum SoftwareBackendError - impl fmt::Display for SoftwareBackendError - impl std::error::Error for SoftwareBackendError - pub struct SoftwareBackend - impl SoftwareBackend - pub struct SoftwareBackendBuilder - impl SoftwareBackendBuilder - impl Default for SoftwareBackendBuilder ### src/surface_wasm.rs - pub enum SurfaceError - impl core::fmt::Display for SurfaceError - impl retroglyph_window::RecoverableError for SurfaceError - impl std::error::Error for SurfaceError - impl WindowSurface ### src/surface_native.rs - pub enum SurfaceError - impl core::fmt::Display for SurfaceError - impl retroglyph_window::RecoverableError for SurfaceError - impl std::error::Error for SurfaceError - impl WindowSurface --- ## README.md ### retroglyph-software Software (winit + softbuffer) pixel rendering backend for retroglyph Part of the [retroglyph](https://github.com/crates-lurey-io/retroglyph) workspace. --- ## src/lib.rs ### retroglyph_window::{sprite_cache, tileset} ```rust pub use retroglyph_window::{sprite_cache, tileset}; ``` ### surface::SurfaceError ```rust pub use surface::SurfaceError; ``` ### config::{SoftwareBackend, SoftwareBackendBuilder, SoftwareBackendError} ```rust pub use config::{SoftwareBackend, SoftwareBackendBuilder, SoftwareBackendError}; ``` ### retroglyph_window::font::{BitmapFont, FontChain} ```rust pub use retroglyph_window::font::{BitmapFont, FontChain}; ``` ### SoftwareRenderer ```rust pub struct SoftwareRenderer { } ``` A running software renderer, produced by [`SoftwareBackend::into_renderer`]. Unlike [`SoftwareBackend`] (which is just configuration), this type always has an active rendering context: its pixel buffer is always available, and the `ctx` field is never `None`, so [`Output`] methods never panic for missing initialization. Call [`pixels`](Self::pixels) to inspect the rendered output, or use [`Output::draw`] and [`Output::draw_layers`] to render into it. If the `tilesets` feature is enabled, the sprite tileset is loaded once, at [`into_renderer`](SoftwareBackend::into_renderer) time, into an internal [`SpriteCache`]. That cache has no reload/hot-swap support (see its docs); to pick up a changed tileset, rebuild the renderer via a fresh [`SoftwareBackend`] configuration rather than mutating this one. ### impl SoftwareRenderer ```rust impl SoftwareRenderer { pub fn pixels(&self) -> &[u32]; pub fn push_event(&mut self, event: Event); pub fn init_surface(&mut self, window: Arc) -> Result<(), SurfaceError>; pub fn resize_surface(&mut self, width: u32, height: u32); pub fn present(&mut self) -> Result<(), SurfaceError>; } ``` ### impl SoftwareBackend ```rust impl SoftwareBackend { pub fn into_renderer(self) -> Result; } ``` ### impl Output for SoftwareRenderer ```rust impl Output for SoftwareRenderer { } ``` ### impl Input for SoftwareRenderer ```rust impl Input for SoftwareRenderer { } ``` ### impl Cursor for SoftwareRenderer ```rust impl Cursor for SoftwareRenderer { } ``` ### impl retroglyph_window::Presenter for SoftwareRenderer ```rust impl retroglyph_window::Presenter for SoftwareRenderer { } ``` ### impl SoftwareObserver ```rust impl SoftwareObserver { } ``` ### impl Output for SoftwareObserver ```rust impl Output for SoftwareObserver { } ``` ### impl SoftwareObserver ```rust impl SoftwareObserver { } ``` ### impl Cursor for SoftwareObserver ```rust impl Cursor for SoftwareObserver { } ``` ### impl retroglyph_core::testing::conformance::Observable for SoftwareObserver ```rust impl retroglyph_core::testing::conformance::Observable for SoftwareObserver { } ``` ## src/config.rs ### SoftwareBackendError ```rust #[derive(Debug)] pub enum SoftwareBackendError { NoFont, MixedGlyphSizes, ZeroScale, ZeroGrid, #[cfg(feature = "tilesets")] Tileset(retroglyph_window::tileset::TilesetError), } ``` Errors that can occur when configuring the software backend. Windowing errors (window creation, event loop) are not represented here: this crate builds renderers, and the loop (`retroglyph-window` or another windowing integration) reports its own errors. ### impl fmt::Display for SoftwareBackendError ```rust impl fmt::Display for SoftwareBackendError { } ``` ### impl std::error::Error for SoftwareBackendError ```rust impl std::error::Error for SoftwareBackendError { } ``` ### SoftwareBackend ```rust #[derive(Debug, Clone, PartialEq, Eq)] pub struct SoftwareBackend { pub cols: u16, pub rows: u16, pub scale: u8, pub tilesets: Vec, } ``` Configuration and entry point for the software rendering backend. Construct this via [`SoftwareBackendBuilder`], then call [`into_renderer`](SoftwareBackend::into_renderer) to obtain a [`SoftwareRenderer`](crate::SoftwareRenderer) (which implements [`Backend`](retroglyph_core::backend::Backend) for in-memory use, and `retroglyph_window::Presenter` for windowed use). #### Examples Windowed mode (requires `default-font` feature; the loop comes from `retroglyph-window`): ```no_run use retroglyph_software::SoftwareBackendBuilder; use retroglyph_window::winit::{WindowConfig, run_windowed}; use retroglyph_core::event::{Event, KeyCode}; use retroglyph_core::color::Style; use std::time::Duration; let renderer = SoftwareBackendBuilder::new() .grid_size(80, 25) .scale(2) .build() .expect("backend init failed") .into_renderer() .expect("renderer init failed"); let config = WindowConfig::fit(&renderer, "My Game", None, true); run_windowed(config, renderer, move |term| { term.draw(|s| s.print((0, 0), "Hello from rg!", Style::default())).ok(); if let Some(event) = term.poll(Duration::from_millis(16)) { match event { Event::Key(k) if k.code == KeyCode::Escape => std::process::exit(0), Event::Close => std::process::exit(0), _ => {} } } }).expect("event loop failed"); ``` Headless mode (useful for testing): ``` use retroglyph_software::{SoftwareBackendBuilder, SoftwareRenderer}; use retroglyph_core::color::Style; use retroglyph_core::grid::Pos; use retroglyph_core::backend::{DrawCell, Output}; use retroglyph_core::color::Color; let opts = SoftwareBackendBuilder::new() .grid_size(1, 1) .scale(1) .build() .unwrap(); let mut renderer: SoftwareRenderer = opts.into_renderer().unwrap(); // Draw a red cell on layer 0. use retroglyph_core::tile::Tile; let tile = Tile::new(' ', Style::new().bg(Color::Rgb { r: 255, g: 0, b: 0 })); renderer .draw_layers([DrawCell::on_layer(0, Pos::new(0, 0), &tile)].into_iter()) .unwrap(); let pixels = renderer.pixels(); assert!(pixels.iter().all(|&p| p == 0x00FF_0000)); ``` See the `demo` example for a complete runnable program. ### impl SoftwareBackend ```rust impl SoftwareBackend { pub fn fonts(&self) -> Option<&FontChain<'static>>; } ``` ### SoftwareBackendBuilder ```rust #[derive(Debug)] pub struct SoftwareBackendBuilder { } ``` Builder for [`SoftwareBackend`]. #### Examples ``` use retroglyph_software::SoftwareBackendBuilder; // With the `default-font` feature the embedded Unscii 16 font is // used automatically. To supply your own 8×16 bitmap font: // // use retroglyph_window::font::BitmapFont; // let my_font = BitmapFont::new(include_bytes!("my_font.bin"), 8, 16, 256); // SoftwareBackendBuilder::new().font(my_font)... let backend = SoftwareBackendBuilder::new() .grid_size(80, 25) .build() .expect("backend init failed"); ``` ### impl SoftwareBackendBuilder ```rust impl SoftwareBackendBuilder { pub fn new() -> Self; pub fn grid_size(self, cols: u16, rows: u16) -> Self; pub fn scale(self, scale: u8) -> Self; pub fn font(self, fonts: impl Trait) -> Self; pub fn tileset(self, opts: TilesetOptions) -> Self; pub fn build(self) -> Result; } ``` ### impl Default for SoftwareBackendBuilder ```rust impl Default for SoftwareBackendBuilder { } ``` ## src/surface_wasm.rs ### SurfaceError ```rust #[derive(Debug)] pub enum SurfaceError { Canvas(String), } ``` Error locating or using the backing `` element. ### impl core::fmt::Display for SurfaceError ```rust impl core::fmt::Display for SurfaceError { } ``` ### impl retroglyph_window::RecoverableError for SurfaceError ```rust impl retroglyph_window::RecoverableError for SurfaceError { } ``` ### impl std::error::Error for SurfaceError ```rust impl std::error::Error for SurfaceError { } ``` ### impl WindowSurface ```rust impl WindowSurface { } ``` ## src/surface_native.rs ### SurfaceError ```rust #[derive(Debug)] pub enum SurfaceError { Context(softbuffer::SoftBufferError), Surface(softbuffer::SoftBufferError), } ``` Errors creating or presenting the native window surface. ### impl core::fmt::Display for SurfaceError ```rust impl core::fmt::Display for SurfaceError { } ``` ### impl retroglyph_window::RecoverableError for SurfaceError ```rust impl retroglyph_window::RecoverableError for SurfaceError { } ``` ### impl std::error::Error for SurfaceError ```rust impl std::error::Error for SurfaceError { } ``` ### impl WindowSurface ```rust impl WindowSurface { } ```