retroglyph_window/

presenter.rs

//! The [`Presenter`] trait: what a renderer crate implements to rasterize a grid and present it
//! to a window surface.
//!
//! `Presenter` is an [`Output`](retroglyph_core::backend::Output) supertrait plus window-surface
//! operations, with no input methods: the event loop owns input, and
//! [`WindowBackend`](crate::WindowBackend) forwards translated events into its own queue instead.
//!
//! | Presenter | `present()` | `init_surface()` |
//! |---|---|---|
//! | `SoftwareRenderer` (retroglyph-software) | Copies pixel buffer to softbuffer surface | Creates `softbuffer::Context` + `Surface` |
//! | `GlRenderer` (retroglyph-gl) | Instanced draw + swaps buffers | Creates a GL context (glutin native / WebGL2 wasm) from the window |
//! | `WgpuRenderer` (retroglyph-wgpu) | Submits a render pass + presents the swap chain | Creates a `wgpu::Surface`, `Device`, and `Queue` |
//!
//! See the crate-level docs (`crate` root, "DPI, scale, and the resize contract" and
//! "Threading model" sections) for the physical-pixel/no-auto-scaling contract on
//! [`cell_size`](Presenter::cell_size), the sub-cell-remainder behavior on
//! [`resize_surface`](Presenter::resize_surface), and the single-threaded execution model
//! every `Presenter` implementation runs under.

use raw_window_handle::{HasDisplayHandle, HasWindowHandle};
use retroglyph_core::backend::Output;
use retroglyph_core::tile::Tile;
use std::fmt;
use std::sync::Arc;

use crate::geometry::CellGeometry;

/// A window/display handle pair, as one trait.
///
/// Presenters receive [`raw-window-handle`](raw_window_handle) types, not a concrete
/// `winit::window::Window`: softbuffer, wgpu, and glutin all accept these handles directly, so
/// any windowing library that produces them can drive the same presenter, and only this crate
/// depends on winit itself.
///
/// `raw-window-handle` has no combined trait, and surface libraries need to *own* the handle
/// (softbuffer stores it for the surface's lifetime), so presenters receive `Arc<dyn
/// WindowHandle>`: rwh implements the handle traits for `Arc<H: ?Sized>`, so the trait object
/// passes straight into `softbuffer::Surface::new` / `wgpu::Instance::create_surface`.
///
/// `Send + Sync` is part of the trait rather than left to each implementation because a trait
/// object erases auto traits its trait doesn't name, and `wgpu::Instance::create_surface` requires
/// them: its safe entry point takes ownership of a `Send + Sync` handle, and the alternative that
/// doesn't is `unsafe`. Declaring them here is what makes `Arc<dyn WindowHandle>` usable with it.
/// Every windowing library that produces `raw-window-handle` types satisfies this already
/// (`winit::window::Window` does on every platform).
///
/// # Examples
///
/// Blanket-implemented for any type implementing both `raw-window-handle` traits; there is
/// nothing to implement directly on `WindowHandle` itself.
///
/// ```
/// use raw_window_handle::{
///     DisplayHandle, HandleError, HasDisplayHandle, HasWindowHandle,
///     WindowHandle as RawWindowHandle,
/// };
/// use retroglyph_window::WindowHandle;
///
/// struct NoWindow;
///
/// impl HasWindowHandle for NoWindow {
///     fn window_handle(&self) -> Result<RawWindowHandle<'_>, HandleError> {
///         Err(HandleError::NotSupported)
///     }
/// }
///
/// impl HasDisplayHandle for NoWindow {
///     fn display_handle(&self) -> Result<DisplayHandle<'_>, HandleError> {
///         Err(HandleError::NotSupported)
///     }
/// }
///
/// fn assert_is_window_handle<T: WindowHandle>(_handle: &T) {}
/// assert_is_window_handle(&NoWindow);
/// ```
pub trait WindowHandle: HasWindowHandle + HasDisplayHandle + Send + Sync {}

impl<T: HasWindowHandle + HasDisplayHandle + Send + Sync + ?Sized> WindowHandle for T {}

/// A surface-lifecycle error that can optionally signal whether it's worth retrying.
///
/// [`Presenter::SurfaceError`] is a per-implementation associated type: softbuffer's error enum
/// has no `Lost`/`Outdated`/`Timeout` discrimination the way `wgpu::SurfaceError` does, so today's
/// only backend (`SoftwareRenderer`) has no structured way to say "this specific failure is
/// fatal, don't bother retrying." [`is_recoverable`](Self::is_recoverable) is that hook: a
/// presenter with real error categories can override it to return `false` for a truly fatal
/// failure, while every presenter that doesn't need the distinction (including every backend that
/// exists in this crate today) can implement this trait with an empty body and inherit the
/// default `true`.
///
/// Not blanket-implemented for every `Debug + Display` type: that would make it
/// impossible for any concrete error type to override [`is_recoverable`](Self::is_recoverable) at
/// all (a specific `impl` would conflict with the blanket one), defeating the point of the trait.
/// Instead, each `SurfaceError` type needs one explicit (and usually empty) `impl
/// RecoverableError for ...` block: see `retroglyph_software`'s `SurfaceError` for the minimal
/// case that just inherits the default.
///
/// # Examples
///
/// ```
/// use core::fmt;
/// use retroglyph_window::RecoverableError;
///
/// #[derive(Debug)]
/// enum MySurfaceError {
///     Init,
///     Lost,
/// }
///
/// impl fmt::Display for MySurfaceError {
///     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
///         match self {
///             Self::Init => write!(f, "surface init failed"),
///             Self::Lost => write!(f, "surface lost"),
///         }
///     }
/// }
///
/// impl RecoverableError for MySurfaceError {
///     fn is_recoverable(&self) -> bool {
///         // Init failures are fatal; a lost surface may come back.
///         matches!(self, Self::Lost)
///     }
/// }
///
/// assert!(!MySurfaceError::Init.is_recoverable());
/// assert!(MySurfaceError::Lost.is_recoverable());
/// ```
pub trait RecoverableError: core::fmt::Debug + core::fmt::Display {
    /// Whether this error represents a transient failure worth retrying, as opposed to a fatal
    /// one.
    ///
    /// Defaults to `true`: absent any structured error categorization, every failure is treated
    /// as potentially transient, matching the generic consecutive-failure recovery heuristic
    /// `winit::run::present_failure_action` already applies. Override to return `false` only for
    /// an error variant known to be unrecoverable regardless of retries (e.g. a `wgpu::SurfaceError
    /// ::Lost` variant that persists until the surface is fully rebuilt from a different code
    /// path than a simple retry).
    #[must_use]
    fn is_recoverable(&self) -> bool {
        true
    }
}

// `Infallible` is uninhabited: no value of it can ever exist, so `is_recoverable` can never
// actually be called on one, but a presenter that can't fail (e.g. a test mock) still needs
// `type SurfaceError = core::convert::Infallible` to satisfy the `RecoverableError` bound, so
// this impl exists purely for that convenience.
impl RecoverableError for core::convert::Infallible {}

/// A ready-made, string-backed [`SurfaceError`](Presenter::SurfaceError) for presenters whose
/// underlying surface library reports failures as opaque strings rather than a structured error
/// enum.
///
/// Several presenter backends (e.g. `retroglyph-gl`'s native/wasm split, or a future softbuffer
/// backend) need only two buckets ("surface/context creation failed" (fatal) and "presenting a
/// frame failed" (potentially recoverable)) and would otherwise each hand-roll the same `enum {
/// Init(String), Present(String) }` plus [`RecoverableError`] impl. This type is that common
/// shape, provided once here so backends can reuse it directly instead of duplicating it.
#[derive(Debug)]
#[non_exhaustive]
pub enum GenericSurfaceError {
    /// Creating the surface or its underlying context failed. Treated as fatal (not
    /// recoverable): a presenter cannot proceed without a surface, and retrying the same
    /// creation path is very unlikely to succeed.
    Init(String),
    /// Presenting a frame failed. Treated as potentially recoverable so the event loop's
    /// consecutive-failure heuristic can retry before giving up.
    Present(String),
}

impl fmt::Display for GenericSurfaceError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Init(msg) => write!(f, "surface init: {msg}"),
            Self::Present(msg) => write!(f, "surface present: {msg}"),
        }
    }
}

impl std::error::Error for GenericSurfaceError {}

impl RecoverableError for GenericSurfaceError {
    fn is_recoverable(&self) -> bool {
        // Init failures are fatal (nothing to retry into); present failures may be transient.
        matches!(self, Self::Present(_))
    }
}

/// A renderer that rasterizes grid content and presents it to a window surface.
///
/// A supertrait of [`Output`], adding the surface lifecycle (`init_surface`, `resize_surface`,
/// `present`, `cell_size`) that the event loop drives. Every `Presenter` implementation is an
/// `Output` implementation for free: [`WindowBackend`](crate::WindowBackend) delegates its own
/// `Output` impl straight through to `P: Presenter`, with no duplicated method bodies.
///
/// # Sub-cell offsets and spill
///
/// A [`Tile`]'s `dx`/`dy` shift its glyph within, and past, its cell.
/// This is a cross-backend rendering contract: the CPU rasterizer (`retroglyph-software`) and the
/// GPU ones (`retroglyph-gl`, `retroglyph-wgpu`) must produce the same pixels, so it is specified
/// here once instead of in mirrored per-backend comments that reference each other (and drift when
/// only one is touched). A `Presenter` that honors sub-cell offsets must obey all four points:
///
/// - `dx`/`dy` are in **unscaled font pixels** (a presenter multiplies by its own integer scale);
///   negative `dx` shifts the glyph left, negative `dy` up.
/// - The cell's **background fill is always the full, unshifted cell** rectangle. An offset moves
///   only the glyph, never the background.
/// - An offset glyph **may spill past its cell edge into neighboring cells**, and that spill is
///   **uniform in all four directions**: a glyph pushed right/down onto a later neighbor spills
///   the same way as one pushed left/up onto an earlier neighbor.
/// - The mechanism that guarantees that uniformity is a **two-pass draw**: lay down *every* cell's
///   background first, then draw *every* cell's (offset) glyph over the result. Interleaving the
///   two per cell would let a later cell's background overwrite an earlier neighbor's spilled
///   glyph, breaking spill in the right/down directions only.
///
/// See <https://main.retroglyph.dev/book/explanation/coordinates.html> for why the offset
/// *application* itself is not shared code across backends.
///
/// # Examples
///
/// ```
/// use retroglyph_core::backend::{DrawCell, Output};
/// use retroglyph_core::grid::Size;
/// use retroglyph_window::{Presenter, WindowHandle};
/// use std::sync::Arc;
///
/// struct NullPresenter;
///
/// impl Output for NullPresenter {
///     type Error = core::convert::Infallible;
///
///     fn draw_layers<'a, I>(&mut self, _content: I) -> Result<(), Self::Error>
///     where
///         I: Iterator<Item = DrawCell<'a>>,
///     {
///         Ok(())
///     }
///
///     fn flush(&mut self) -> Result<(), Self::Error> {
///         Ok(())
///     }
///
///     fn size(&self) -> Size {
///         Size::new(4, 2)
///     }
///
///     fn clear(&mut self) -> Result<(), Self::Error> {
///         Ok(())
///     }
/// }
///
/// impl Presenter for NullPresenter {
///     type SurfaceError = core::convert::Infallible;
///
///     fn init_surface(&mut self, _window: Arc<dyn WindowHandle>) -> Result<(), Self::SurfaceError> {
///         Ok(())
///     }
///
///     fn resize_surface(&mut self, _width: u32, _height: u32) {}
///
///     fn present(&mut self) -> Result<(), Self::SurfaceError> {
///         Ok(())
///     }
///
///     fn cell_size(&self) -> (u32, u32) {
///         (8, 16)
///     }
/// }
/// ```
pub trait Presenter: Output {
    /// Surface lifecycle error (context creation, buffer acquisition, present).
    type SurfaceError: RecoverableError;

    /// Initialize the window surface.
    ///
    /// Called once from the loop's `resumed` handler. The presenter creates its platform surface
    /// (softbuffer surface, wgpu device+surface, GL context) from the raw window/display handles.
    ///
    /// # Errors
    ///
    /// Returns [`Self::SurfaceError`] if surface or context creation from `window` fails (an
    /// unsupported display/window system connection, a missing graphics API, or, on wasm32,
    /// a canvas element that can't be located). Unlike a failed [`present`](Self::present),
    /// the `winit` driver treats this as fatal rather than retryable: it logs the error and
    /// exits the event loop immediately, since there is no surface to draw into and no later
    /// hook that calls `init_surface` again.
    fn init_surface(&mut self, window: Arc<dyn WindowHandle>) -> Result<(), Self::SurfaceError>;

    /// Resize the window surface to a new physical pixel size.
    ///
    /// Called on every window resize event with `width`/`height` already resolved by the
    /// caller: for the `winit` driver (see `winit::run::WindowApp::resize_to`), that means
    /// `cols * cell_w` x `rows * cell_h`, where `cols`/`rows` are the window's physical size
    /// divided down to whole cells. Any sub-cell remainder is truncated, not centered or
    /// cleared: when the window's physical size isn't an exact multiple of the cell size,
    /// `width`/`height` here are the largest whole-cell-multiple that fits, which can be
    /// smaller than the window's actual physical size. The OS window itself is never resized
    /// to compensate, so a non-exact-multiple resize leaves a thin strip at the window's
    /// trailing edge outside the surface: retroglyph does not paint or clear that strip;
    /// whatever the OS/windowing backend leaves there remains visible until a subsequent
    /// resize covers it.
    fn resize_surface(&mut self, width: u32, height: u32);

    /// Notify the presenter that the window's scale factor (DPI) changed.
    ///
    /// Called when the window moves to a display with a different pixel density, or the
    /// system DPI setting changes. The event loop follows this with
    /// [`resize_surface`](Self::resize_surface) for the window's new physical size, so
    /// this hook only needs to handle DPI-dependent state that isn't a plain buffer
    /// resize (e.g. regenerating a font atlas rasterized for a particular scale).
    ///
    /// Defaults to a no-op: presenters whose rasterization doesn't depend on DPI (like
    /// `SoftwareRenderer`'s integer `scale` config, set once at construction) need no
    /// action here.
    fn scale_factor_changed(&mut self, _scale_factor: f64) {}

    /// Present the rasterized frame to the window surface.
    ///
    /// Called after each app tick. A lost frame is not fatal; the caller logs the error and
    /// continues.
    ///
    /// # Errors
    ///
    /// Returns [`Self::SurfaceError`] if the surface buffer can't be acquired or presented (e.g.
    /// context lost on wasm, page flip pending on DRI/KMS).
    fn present(&mut self) -> Result<(), Self::SurfaceError>;

    /// Cell size in physical pixels `(width, height)`.
    ///
    /// Physical pixels, not logical/DPI-scaled pixels, and never auto-scaled by this crate for
    /// display DPI: see the crate-level "DPI, scale, and the resize contract" docs. A presenter
    /// whose cells should grow on a `HiDPI` display must change what this returns itself (from
    /// [`resize`](Output::resize) or [`scale_factor_changed`](Self::scale_factor_changed)); absent
    /// that, it stays constant for the presenter's lifetime.
    ///
    /// `(u32, u32)` rather than [`Size`](retroglyph_core::grid::Size) because grid coordinates
    /// are `u16` but pixel arithmetic uses `u32` (winit `PhysicalSize`).
    #[must_use]
    fn cell_size(&self) -> (u32, u32);

    /// This presenter's cell geometry, as a [`CellGeometry`] rather than the raw
    /// `(width, height)` pair [`cell_size`](Self::cell_size) returns.
    ///
    /// Lets callers (e.g. `winit::run`'s cursor/mouse handlers) use
    /// [`CellGeometry::pixel_to_cell`] directly instead of pairing a raw `cell_size()` with the
    /// [`translate_pixel_to_cell`](crate::winit::translate::translate_pixel_to_cell) free
    /// function. The default implementation derives a geometry from [`cell_size`](Self::cell_size)
    /// at `scale` 1, clamping each dimension to `u8::MAX`: exact for presenters whose cell size
    /// fits in a `u8` (true of every glyph/tile size in practice), lossy only past that, which
    /// only affects [`pixel_to_cell`](CellGeometry::pixel_to_cell) precision for callers that
    /// don't override this method (test doubles, not `retroglyph-software`/`retroglyph-gl`, both
    /// of which override it to return their real internal geometry).
    #[must_use]
    fn geometry(&self) -> CellGeometry {
        let (cell_w, cell_h) = self.cell_size();
        #[allow(clippy::cast_possible_truncation)]
        CellGeometry::new(cell_w.min(255) as u8, cell_h.min(255) as u8, 1)
    }
}

/// The glyph a `Presenter` should paint art (a bitmap-font glyph or a tileset sprite) for, or
/// `None` when this cell draws none.
///
/// Both pixel backends (`retroglyph-software`, `retroglyph-gl`) ask this same question at
/// several points in their draw path (sprite-vs-font dispatch, font fallback, whether a cell
/// counts as "occupied" for compositing), and used to each answer it independently, which let
/// them drift (retroglyph#762). This is the one place that decides it:
///
/// - A [`TileFlags::SPAN_COVERED`](retroglyph_core::tile::TileFlags::SPAN_COVERED) cell (see
///   [`Tile::span_offset`]) draws no art of its own: the span's anchor already drew one piece of
///   artwork across the whole footprint, and this cell's glyph is only that artwork's text
///   fallback for backends that can't draw it.
/// - An [`is_empty`](Tile::is_empty) tile draws no art: nothing has been written to it, so it is
///   transparent when compositing layers. This is the canonical blank rule, matching
///   [`Grid::flatten_into`](retroglyph_core::grid::Grid::flatten_into) and the cell backends;
///   comparing the glyph itself against `' '` is both slower (it can't be decided without the
///   glyph) and wrong for a font whose space glyph isn't blank.
///
/// Neither check depends on whether a sprite exists for the glyph: that dispatch (sprite vs.
/// bitmap font) is a separate, backend-specific decision made *after* this one, once a caller
/// knows a cell draws art at all.
#[must_use]
pub const fn cell_art_glyph(tile: &Tile) -> Option<char> {
    if tile.span_offset().is_some() || tile.is_empty() {
        None
    } else {
        Some(tile.glyph())
    }
}

#[cfg(test)]
mod cell_art_glyph_tests {
    use super::cell_art_glyph;
    use retroglyph_core::color::Style;
    use retroglyph_core::grid::Grid;
    use retroglyph_core::tile::Tile;

    #[test]
    fn none_for_an_empty_tile() {
        assert_eq!(cell_art_glyph(&Tile::default()), None);
    }

    #[test]
    fn some_for_an_occupied_tile() {
        let tile = Tile::new('@', Style::new());
        assert_eq!(cell_art_glyph(&tile), Some('@'));
    }

    #[test]
    fn none_for_a_span_covered_tile() {
        let mut grid = Grid::new(2, 1);
        grid.write_span(0, 0, 0, &["AB"], Style::new()).unwrap();
        let covered = *grid.tile(0, (1, 0)).unwrap();
        assert!(covered.span_offset().is_some());
        assert_eq!(cell_art_glyph(&covered), None);
    }

    #[test]
    fn some_for_a_non_blank_space_glyph() {
        // A space glyph is not inherently blank: an explicit `Tile::new(' ', ...)` is occupied
        // (not `is_empty()`), and a font may draw something for it (`BitmapFont::new` allows a
        // non-blank space). The blank rule is `is_empty()`, not `glyph == ' '`.
        let tile = Tile::new(' ', Style::new());
        assert_eq!(cell_art_glyph(&tile), Some(' '));
    }
}

#[cfg(test)]
mod generic_surface_error_tests {
    use super::{GenericSurfaceError, RecoverableError};

    #[test]
    fn init_is_not_recoverable() {
        let err = GenericSurfaceError::Init("boom".to_string());
        assert!(!err.is_recoverable());
    }

    #[test]
    fn present_is_recoverable() {
        let err = GenericSurfaceError::Present("boom".to_string());
        assert!(err.is_recoverable());
    }

    #[test]
    fn display_includes_message() {
        let init = GenericSurfaceError::Init("init failed".to_string());
        assert!(init.to_string().contains("init failed"));

        let present = GenericSurfaceError::Present("present failed".to_string());
        assert!(present.to_string().contains("present failed"));
    }
}