Source code for displaydev.pgdisplay

# SPDX-FileCopyrightText: 2024 Brad Barnett
#
# SPDX-License-Identifier: MIT

"""
displaydev.pgdisplay
"""

import pygame as pg

from displaydev import _DESKTOP_WINDOW_CHROME_H, color_rgb
from displaydev._desktop import DesktopDisplay, FrameRecorderMixin, desktop_work_area
import events
import keys

__all__ = ["PGDisplay", "get_events", "poll_event"]


def _pg_key_name(key):
    try:
        return pg.key.name(key)
    except Exception:
        return str(key)


_pg_displays = []


def _pg_window_cls():
    """Return public ``pygame.Window`` (pygame-ce) with software ``get_surface``/``flip``.

    Does **not** use ``pygame._sdl2.*``. Raises ``ImportError`` when the
    interpreter only has classic pygame (so ``board_config`` can fall back to SDL).
    """
    Window = getattr(pg, "Window", None)
    if Window is None or not hasattr(Window, "get_surface") or not hasattr(Window, "flip"):
        raise ImportError(
            "PGDisplay requires pygame-ce with public pygame.Window "
            "(get_surface/flip); classic pygame / pygame._sdl2 is not supported"
        )
    return Window


# Fail at import time (not only in PGDisplay.__init__) so board_config's
# try/except ImportError selects SDL when pygame-ce is absent.
_pg_window_cls()


def _window_id_of(window):
    if window is None:
        return None
    return getattr(window, "id", window)


def _display_for_window(window):
    wid = _window_id_of(window)
    if wid is None:
        return None
    for display in _pg_displays:
        if getattr(display, "_window_id", None) == wid:
            return display
    return None


def _panel_size(window=None):
    """Logical panel size for normalizing pygame finger coords (0..1 → pixels)."""
    d = _display_for_window(window)
    if d is None and _pg_displays:
        d = _pg_displays[0]
    if d is not None:
        return int(d.width), int(d.height)
    return 320, 240


def _handle_window_close(window):
    display = _display_for_window(window)
    if display is None or display is _pg_displays[0] or len(_pg_displays) <= 1:
        return events.Quit(events.QUIT)
    app = getattr(display, "app", None)
    if app is not None and callable(getattr(app, "remove_display", None)):
        app.remove_display(display)
    else:
        try:
            display.quit()
        except Exception:
            pass
        try:
            _pg_displays.remove(display)
        except ValueError:
            pass
    return None


def _convert(e):  # noqa: PLR0911 — one return per pygame event type
    """Convert a pygame event to an events namedtuple."""
    t = e.type
    if t == pg.QUIT:
        return events.Quit(events.QUIT)
    if t == getattr(pg, "WINDOWCLOSE", -1):
        return _handle_window_close(getattr(e, "window", None))
    win = _window_id_of(getattr(e, "window", None))
    if t == pg.MOUSEMOTION:
        return events.Motion(
            t,
            e.pos,
            e.rel,
            e.buttons,
            bool(getattr(e, "touch", False)),
            win,
        )
    if t in (pg.MOUSEBUTTONDOWN, pg.MOUSEBUTTONUP):
        return events.Button(
            t,
            e.pos,
            e.button,
            bool(getattr(e, "touch", False)),
            win,
        )
    if t in (pg.FINGERDOWN, pg.FINGERUP, pg.FINGERMOTION):
        # Real OS multitouch (touchscreen). Same contract as sdldisplay SDL_FINGER*.
        # Not mouse-chord inject — trackpad OS-pinch still will not appear here.
        w, h = _panel_size(getattr(e, "window", None))
        fx = float(getattr(e, "x", 0.0))
        fy = float(getattr(e, "y", 0.0))
        fid = int(getattr(e, "finger_id", getattr(e, "finger", 0)))
        return events.Finger(t, (int(fx * w), int(fy * h)), fid, win)
    if t == pg.MOUSEWHEEL:
        return events.Wheel(
            t,
            bool(getattr(e, "flipped", False)),
            getattr(e, "x", 0),
            getattr(e, "y", 0),
            getattr(e, "precise_x", getattr(e, "x", 0)),
            getattr(e, "precise_y", getattr(e, "y", 0)),
            bool(getattr(e, "touch", False)),
            win,
        )
    if t in (pg.KEYDOWN, pg.KEYUP):
        # Match browser / SDL backends: drop OS auto-repeat KEYDOWNs.
        if t == pg.KEYDOWN and getattr(e, "repeat", False):
            return None
        return events.Key(t, _pg_key_name(e.key), e.key, e.mod, getattr(e, "scancode", 0), win)
    if t == pg.JOYAXISMOTION:
        return events.JoyAxisMotion(t, e.instance_id, e.axis, e.value / 32767.0)
    if t == pg.JOYBALLMOTION:
        return events.JoyBallMotion(t, e.instance_id, e.ball, e.rel)
    if t == pg.JOYHATMOTION:
        return events.JoyHatMotion(t, e.instance_id, e.hat, e.value)
    if t == pg.JOYBUTTONDOWN:
        return events.JoyButtonDown(t, e.instance_id, e.button)
    if t == pg.JOYBUTTONUP:
        return events.JoyButtonUp(t, e.instance_id, e.button)
    return events.Unknown(t)


def _process_pg_event(e):
    if e.type == pg.NOEVENT:
        return None
    if e.type == getattr(pg, "WINDOWCLOSE", -1) or e.type in events.filter:
        return _convert(e)
    return None


[docs] def poll_event(): """Non-blocking poll; return one events event or ``None`` (not for QUEUE ``read``).""" return _process_pg_event(pg.event.poll())
[docs] def get_events(): """Drain the pygame queue; return a list of events or ``None``.""" raw = pg.event.get() if not raw: return None eventlist = [] for e in raw: evt = _process_pg_event(e) if evt is not None: eventlist.append(evt) return eventlist if eventlist else None
# Opened joystick handles, kept referenced so PyGame keeps delivering their # events. PyGame's joystick events (JOYAXISMOTION, JOYBUTTONDOWN, ...) already # share events's numeric types and attribute names, so they flow through # share events's numeric types once joysticks are opened. _joysticks = [] def _init_joysticks() -> None: """ Initialize the joystick subsystem and open all connected joysticks. Joysticks must be opened for PyGame to deliver their events. Devices connected after startup are not hot-plugged (connect controllers before launching). Failures are ignored so a missing joystick subsystem never breaks the display. """ try: pg.joystick.init() for i in range(pg.joystick.get_count()): js = pg.joystick.Joystick(i) js.init() _joysticks.append(js) except Exception: pass
[docs] class PGDisplay(FrameRecorderMixin, DesktopDisplay): """Emulate an LCD window with pygame-ce (``pygame.Window``). Requires pygame-ce with public ``Window.get_surface`` / ``Window.flip`` (no ``pygame._sdl2``). Provides scrolling and rotation similar to a panel driver; scale is reduced when the window would not fit the desktop work area. Args: width (int, optional): Panel width in pixels. Defaults to 320. height (int, optional): Panel height in pixels. Defaults to 240. rotation (int, optional): Rotation in degrees. Defaults to 0. color_depth (int, optional): Bits per pixel. Defaults to 16. title (str, optional): Window title. Defaults to ``"displaydev"``. scale (float, optional): Window scale factor. Defaults to 1.0. window_flags (int, optional): pygame display flags. Defaults to ``pg.SHOWN``. quiet (bool): Suppress init chatter when True. Attributes: color_depth (int): Bits per pixel. touch_scale (float): Scale used to map host pointer coords into panel space. needs_refresh (bool): True — ``appdev.App`` drives periodic ``show()``. """ needs_refresh = True quit_chord = (keys.K_q, keys.KMOD_CTRL) def __init__( self, width=320, height=240, rotation=0, color_depth=16, title="displaydev", scale=1.0, window_flags=pg.SHOWN, *, quiet=False, ): self._width = width self._height = height self._rotation = rotation self.color_depth = color_depth self._title = title self._window_flags = window_flags self._scale = scale self.touch_scale = scale self._buffer = None self._pg_window = None self._window_id = None self._window = None # Window.get_surface() display surface self.app = None self._render_dirty = False self._show_pending = False self._requires_byteswap = False self._frame_recorder = None self._bytes_per_pixel = color_depth // 8 # Fail early if this interpreter lacks pygame-ce Window (e.g. system python3). _pg_window_cls() if self._scale != 1 and not hasattr(pg.transform, "scale_by"): if not quiet: print( f"PGDisplay: Scaling is set to {self._scale}, but pygame {pg.ver} does not support it." ) self._scale = 1 pg.init() ux, uy, desktop_w, desktop_h = desktop_work_area() if desktop_w <= 0 or desktop_h <= 0: try: info = pg.display.Info() desktop_w, desktop_h = info.current_w, info.current_h ux, uy = 0, 0 except Exception: desktop_w, desktop_h = 0, 0 self._work_area = (ux, uy, desktop_w, desktop_h) self._scale = self._fit_scale(desktop_w, desktop_h, quiet) self.touch_scale = self._scale _init_joysticks() self._buffer = pg.Surface(size=(self._width, self._height), depth=self.color_depth) self._buffer.fill((0, 0, 0)) super().__init__(quiet=quiet) # DisplayDriver.__init__ used to reset touch_scale to 1.0; keep window scale # so HostEventsDevice maps pygame coords into panel space. self.touch_scale = self._scale # System-wide pygame queue drain (same callable on every PGDisplay). self.get_events = get_events if self not in _pg_displays: _pg_displays.append(self) ############### Required API Methods ################ def _lock_window_size(self) -> None: """Keep the OS window fixed to the scaled panel size (not user-resizable).""" win = self._pg_window if win is not None: try: win.resizable = False except Exception: pass def _place_window(self, win_w, win_h) -> None: """Center the window in the usable work area (taskbar / chrome aware).""" win = self._pg_window if win is None: return ux, uy, uw, uh = getattr(self, "_work_area", (0, 0, 0, 0)) if uw <= 0 or uh <= 0: return x = ux + max(0, (uw - win_w) // 2) y = uy + _DESKTOP_WINDOW_CHROME_H + max(0, (uh - _DESKTOP_WINDOW_CHROME_H - win_h) // 2) try: win.position = (x, y) except Exception: pass
[docs] def init(self) -> None: """ Initializes the display instance. Called by __init__ and rotation setter. """ win_w = int(self.width * self._scale) win_h = int(self.height * self._scale) Window = _pg_window_cls() if self._pg_window is None: self._pg_window = Window(title=self._title, size=(win_w, win_h)) self._window_id = int(self._pg_window.id) else: try: self._pg_window.size = (win_w, win_h) self._pg_window.title = self._title except Exception: pass self._window = self._pg_window.get_surface() self._lock_window_size() self._place_window(win_w, win_h) # Full-height scroll region, no repaint during init. self._reset_vscroll()
[docs] def blit_rect(self, buffer: memoryview, x: int, y: int, w: int, h: int): """ Blit a buffer into the logical framebuffer. Compositing is deferred until ``show()``. """ for i in range(h): for j in range(w): pixel_index = (i * w + j) * self._bytes_per_pixel color = color_rgb(buffer[pixel_index : pixel_index + self._bytes_per_pixel]) self._buffer.set_at((x + j, y + i), color) self._render_dirty = True return (x, y, w, h)
[docs] def fill_rect(self, x: int, y: int, w: int, h: int, c: int): """ Fill a rectangle in the logical framebuffer. Compositing is deferred until ``show()``. """ fillRect = pg.Rect(x, y, w, h) self._buffer.fill(color_rgb(c), fillRect) self._render_dirty = True return (x, y, w, h)
[docs] def pixel(self, x: int, y: int, c: int): """ Set a pixel on the display. Args: x (int): The x-coordinate of the pixel. y (int): The y-coordinate of the pixel. c (int): The color of the pixel. Returns: (tuple): A tuple containing the x, y, w & h values. """ return self.blit_rect(bytearray(c.to_bytes(2, "little")), x, y, 1, 1)
############### API Method Overrides ################ def _rotation_helper(self, value): """ Helper function for the rotation setter. """ if (angle := (value % 360) - (self._rotation % 360)) != 0: tempBuffer = pg.transform.rotate(self._buffer, -angle) self._buffer = tempBuffer ############### Class Specific Methods ############## def _video_active(self) -> bool: """True while pygame is initialized and this window is live.""" if getattr(self, "_deinitialized", False): return False if self._pg_window is None or self._window is None: return False try: return bool(pg.get_init()) except pg.error: return False
[docs] def capture_rgb(self): """Return the visible window as ``(RGB24 bytes, width, height)``.""" if not self._video_active(): raise RuntimeError("pygame display is not active") self.show() width, height = self._window.get_size() return self._window_rgb(), width, height
def _window_rgb(self): """Export the composed visible window as packed RGB24 bytes.""" if hasattr(pg.image, "tobytes"): return pg.image.tobytes(self._window, "RGB") return pg.image.tostring(self._window, "RGB")
[docs] def render(self, renderRect=None) -> None: """ Composite the logical framebuffer to the window. Called from ``show()`` when draws are pending. """ if not self._video_active(): return s = self._scale buffer = pg.transform.scale_by(self._buffer, s) if s != 1 else self._buffer if not (y_start := self.vscsad()): if renderRect is not None: x, y, w, h = renderRect renderRect = pg.Rect(x * s, y * s, w * s, h * s) dest = renderRect else: dest = (0, 0) self._window.blit(buffer, dest, renderRect) else: # Ignore renderRect and render the entire buffer to the window in four steps y_start *= s tfa = self._tfa * s vsa = self._vsa * s bfa = self._bfa * s width = self.width * s if tfa > 0: tfaRect = pg.Rect(0, 0, width, tfa) self._window.blit(buffer, tfaRect, tfaRect) vsaTopHeight = vsa + tfa - y_start vsaTopSrcRect = pg.Rect(0, y_start, width, vsaTopHeight) vsaTopDestRect = pg.Rect(0, tfa, width, vsaTopHeight) self._window.blit(buffer, vsaTopDestRect, vsaTopSrcRect) vsaBtmHeight = vsa - vsaTopHeight vsaBtmSrcRect = pg.Rect(0, tfa, width, vsaBtmHeight) vsaBtmDestRect = pg.Rect(0, tfa + vsaTopHeight, width, vsaBtmHeight) self._window.blit(buffer, vsaBtmDestRect, vsaBtmSrcRect) if bfa > 0: bfaRect = pg.Rect(0, tfa + vsa, width, bfa) self._window.blit(buffer, bfaRect, bfaRect)
[docs] def show(self, _timer=None) -> None: """ Show the display. """ if not self._video_active(): return if self._render_dirty: self.render() self._render_dirty = False if self._frame_recorder is not None: self._record_frame(self._window_rgb()) try: self._pg_window.flip() except pg.error: if getattr(self, "_deinitialized", False): return raise
[docs] def quit(self, code: int = 0, force: bool = False) -> None: """Release pygame resources (REPL-safe unless ``force=True``).""" self.deinit() if not force: return try: import os os._exit(code) except Exception: pass raise SystemExit(code)
def _deinit(self) -> None: """Release this window; quit pygame only when no PGDisplay remains.""" self.close_frame_recorder() try: _pg_displays.remove(self) except ValueError: pass window = self._pg_window self._pg_window = None self._window = None self._window_id = None self.app = None if window is not None: try: window.destroy() except Exception: pass if _pg_displays: return global _joysticks try: pg.joystick.quit() except Exception: pass _joysticks = [] try: pg.quit() except Exception: pass self._window = None self._buffer = None