retroglyph_window/
presenter_builder.rs

1//! [`PresenterBuilder`](crate::presenter_builder::PresenterBuilder), the shape shared by the
2//! software/GL/wgpu backend builders.
3
4use crate::font::FontChain;
5use crate::presenter::Presenter;
6#[cfg(feature = "tilesets")]
7use crate::tileset::TilesetOptions;
8
9/// The builder shape `retroglyph-software`, `retroglyph-gl`, and `retroglyph-wgpu` all implement.
10///
11/// `SoftwareBackendBuilder`, `GlBackendBuilder`, and `WgpuBackendBuilder` are otherwise unrelated
12/// types: each crate defines its own builder because each backend owns its own renderer and error
13/// type, but the configuration surface (grid size, scale, fonts, tilesets) is identical across all
14/// three. This trait names that shared surface so a caller (a demo gallery, a test harness) can be
15/// generic over "a windowed backend's builder" instead of writing one near-identical function per
16/// backend crate (retroglyph#1192).
17///
18/// A backend crate implements this by forwarding to its existing inherent methods; see
19/// `SoftwareBackendBuilder`, `GlBackendBuilder`, and `WgpuBackendBuilder` for the impls.
20pub trait PresenterBuilder: Sized {
21    /// The renderer this builder produces.
22    type Presenter: Presenter + 'static;
23    /// The error [`build_presenter`](Self::build_presenter) can fail with.
24    type Error: core::error::Error;
25
26    /// Creates a builder with the backend's default configuration.
27    fn new() -> Self;
28
29    /// Sets the grid dimensions in cells.
30    #[must_use]
31    fn grid_size(self, cols: u16, rows: u16) -> Self;
32
33    /// Sets the integer pixel scale (each glyph pixel becomes `scale`x`scale` physical pixels).
34    #[must_use]
35    fn scale(self, scale: u16) -> Self;
36
37    /// Sets the fonts glyphs are resolved through.
38    #[must_use]
39    fn font(self, fonts: impl Into<FontChain<'static>>) -> Self;
40
41    /// Registers a PNG sprite tileset. Available only with the `tilesets` feature.
42    #[cfg(feature = "tilesets")]
43    #[must_use]
44    fn tileset(self, opts: TilesetOptions) -> Self;
45
46    /// Builds the configured [`Presenter`](Self::Presenter).
47    ///
48    /// # Errors
49    ///
50    /// Returns [`Self::Error`] if the configuration is invalid (see the backend crate's own error
51    /// type for the exact conditions: missing font, mismatched glyph sizes, zero scale/grid, an
52    /// oversized surface, or a tileset that failed to load).
53    fn build_presenter(self) -> Result<Self::Presenter, Self::Error>;
54}
retroglyph_window/presenter_builder.rs

retroglyph_window/
presenter_builder.rs
