Struct SoftwareBackendBuilder 

pub struct SoftwareBackendBuilder { /* private fields */ }

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");

Implementations

impl SoftwareBackendBuilder

pub const fn new() -> Self

Creates a builder with default options.

When the default-font feature is enabled the Unscii 16 font is pre-selected; otherwise you must call font.

pub const fn grid_size(self, cols: u16, rows: u16) -> Self

Sets the grid dimensions in cells.

pub const fn scale(self, scale: u8) -> Self

Pixel-scale factor for the font.

Each 1-bit font pixel becomes a scale×scale block. For the VGA 8×16 font a scale of 2 gives 16×32 pixel cells, more readable on modern displays.

pub fn font(self, fonts: impl Into<FontChain<'static>>) -> Self

Overrides the fonts glyphs are resolved through.

Takes either a single BitmapFont or a whole FontChain, since a lone font is a chain of one. A chain is how a grid draws characters CP437 has no mapping for (quadrants, sextants, braille): the extra coverage comes from a fallback font built with BitmapFont::with_charset, and the glyph is drawn from the bitmap font path, so it takes the cell’s foreground color like any other glyph (unlike a tileset sprite, which carries its own colors).

The cell pixel size is derived from the chain’s glyph size multiplied by scale; every font in a chain must therefore agree on its glyph size, or build fails with SoftwareBackendError::MixedGlyphSizes.

Examples

use retroglyph_software::SoftwareBackendBuilder;
use retroglyph_window::font::{BitmapFont, FontChain, unscii16};

// A fallback font declaring the quadrant glyphs CP437 has no mapping for.
static QUADRANTS: [u8; 3 * 16] = [0; 3 * 16];
const CHARSET: [(char, u8); 3] = [('▘', 0), ('▝', 1), ('▖', 2)];
static FALLBACKS: [BitmapFont; 1] =
    [BitmapFont::with_charset(&QUADRANTS, 8, 16, 3, &CHARSET)];

let backend = SoftwareBackendBuilder::new()
    .font(FontChain::new(unscii16::FONT, &FALLBACKS))
    .build()
    .expect("backend init failed");

pub fn tileset(self, opts: TilesetOptions) -> Self

Registers a tileset for loading when the backend starts.

Multiple tilesets can be registered; they are all loaded when into_renderer is called. Later registrations win on codepoint collision.

Available only when the tilesets feature is enabled.

pub fn build(self) -> Result<SoftwareBackend, SoftwareBackendError>

Validates options and returns the backend configuration.

Call into_renderer on the result to obtain the renderer (hand it to retroglyph_window::winit::run_windowed to open a window).

Errors

Returns SoftwareBackendError::NoFont if no font was set and the default-font feature is not enabled.

Returns SoftwareBackendError::MixedGlyphSizes if the configured chain’s fonts disagree on their glyph size.

Returns SoftwareBackendError::ZeroScale if scale was set to 0.

Returns SoftwareBackendError::ZeroGrid if cols or rows was set to 0.

Trait Implementations

impl Debug for SoftwareBackendBuilder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for SoftwareBackendBuilder

fn default() -> Self

Returns the “default value” for a type.