Struct WindowBackend 

pub struct WindowBackend<P: Presenter> { /* private fields */ }

A Backend built from a Presenter plus an input event queue.

Input and Output are independent facets of Backend, which does not fit a window as one type: some event loop owns input, while a per-renderer surface owns output. WindowBackend reunites the two (implementing Output by delegating to P, Input via its own event queue, and the no-op default Cursor), so Terminal gets the full Backend it needs, while renderer crates implement only Presenter. See the crate-level Architecture section for the data-flow diagram.

Because WindowBackend owns input, a Presenter should not implement Input or Cursor itself for windowed use: those impls would be dead (the event loop pushes to this queue, not the presenter’s) and would silently miss the Mouse(Moved) coalescing that push_event applies. A presenter that also wants a direct headless Terminal<Self> input path (as retroglyph-software does for pixel tests) may still implement Input for that path, accepting that a bare queue does not coalesce; a presenter with no such path (as retroglyph-gl) implements only Presenter.

With the winit feature enabled, winit::run_windowed and winit::run_app own the event loop, call push_event as winit events are translated, and call Presenter::present once per frame; callers never touch WindowBackend directly. With winit disabled, retroglyph-window exports no event loop at all: a caller driving its own loop (SDL2, tao, a custom driver) constructs WindowBackend::new(presenter) itself, calls push_event for each translated input event, and calls Terminal::present (which drives Presenter::flush) plus presenter_mut().present() once per frame.

Examples

use retroglyph_core::backend::{Backend, DrawCell, Input, Output};
use retroglyph_core::event::Event;
use retroglyph_core::grid::{Pos, Size};
use retroglyph_core::terminal::Terminal;
use retroglyph_core::tile::Tile;
use retroglyph_window::{Presenter, WindowBackend, WindowHandle};
use std::sync::Arc;
use std::time::Duration;

struct NullPresenter;

impl Output for NullPresenter {
    type Error = core::convert::Infallible;

    fn draw<'a, I>(&mut self, _content: I) -> Result<(), Self::Error>
    where
        I: Iterator<Item = DrawCell<'a>>,
    {
        Ok(())
    }

    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(())
    }

    fn resize(&mut self, _size: Size) {}
}

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)
    }
}

// A caller driving its own loop (SDL2, tao, a hand-rolled driver) builds
// `WindowBackend` directly, no `winit` feature required.
let backend = WindowBackend::new(NullPresenter);
let mut term = Terminal::new(backend);

// The loop pushes each translated input event onto the queue...
term.backend_mut().push_event(Event::FocusGained);

// ...and the app drains it through the normal `Terminal` polling API,
// which never blocks for `WindowBackend`.
while term.poll(Duration::ZERO).is_some() {}

// Once per frame: `Terminal::present` diffs the grid and drives
// `Presenter::flush`, then the caller drives `Presenter::present` itself
// to push pixels to the window.
term.present().unwrap();
term.backend_mut().presenter_mut().present().unwrap();

poll_event never blocks: frame timing is owned by the event loop, not by input waits.

Implementations

impl<P: Presenter> WindowBackend<P>

pub const fn new(presenter: P) -> Self

Wrap a presenter, creating an empty event queue.

pub const fn presenter(&self) -> &P

The wrapped presenter.

pub const fn presenter_mut(&mut self) -> &mut P

The wrapped presenter, mutably.

pub fn into_presenter(self) -> P

Unwrap into the presenter, discarding queued events.

Trait Implementations

impl<P: Presenter> Cursor for WindowBackend<P>

fn set_cursor_visible(&mut self, _visible: bool)

Show or hide the cursor.

fn set_cursor_position(&mut self, _position: Pos<u16>)

Move the cursor to a position.

fn set_cursor_style(&mut self, _style: CursorStyle)

Set the cursor’s shape (and blink behavior).

impl<P: Debug + Presenter> Debug for WindowBackend<P>

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

Formats the value using the given formatter.

impl<P: Presenter> Input for WindowBackend<P>

fn poll_event(&mut self, _timeout: Duration) -> Option<Event>

Poll for an input event, waiting up to timeout.

fn push_event(&mut self, event: Event)

Push an event into the backend’s event buffer.

impl<P: Presenter> Output for WindowBackend<P>

type Error = <P as Output>::Error

Error type returned by fallible operations.

fn draw<'a, I>(&mut self, content: I) -> Result<(), Self::Error>

where I: Iterator<Item = DrawCell<'a>>,

Draw changed cells to the output surface, layer 0 only.

fn draw_layers<'a, I>(&mut self, content: I) -> Result<(), Self::Error>

where I: Iterator<Item = DrawCell<'a>>,

Draw changed cells across all layers.

fn flush(&mut self) -> Result<(), Self::Error>

Flush buffered output to the display.

fn size(&self) -> Size

Return current display dimensions.

fn clear(&mut self) -> Result<(), Self::Error>

Clear the entire display.

fn resize(&mut self, size: Size)

Notify the backend of a resize to size, updating what size reports.

fn needs_full_frame(&self) -> bool

Returns true if the backend needs the entire frame (all cells on all layers) on every call to draw_layers, rather than just the changed cells.

fn composites_layers(&self) -> bool

Whether this backend composites layers itself (per pixel or quad), receiving the raw layered stream from draw_layers.