Source code for displaydev.auto

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

"""Optional host backend selection. Backends never import this module.

Selects ``PSDisplay`` / ``JNDisplay`` / ``WinDisplay``→``PGDisplay``→
``SDLDisplay`` (or Android ``AndroidSDLDisplay``) from the host so
board configs stay MCU-shaped wiring only. Explicit boards import a backend
directly; this factory is convenience only.

Returns the display driver directly. Desktop drivers expose ``get_events`` for
``appdev.App(host_read=...)``.

The host backends are rows of the `backends` registry, so a backend of your
own can join them. See "Write your own backend" in docs/guides/displays.md.
"""

import sys

import backends

__all__ = ["AutoDisplay", "host_kind"]


[docs] def host_kind(): """Return ``"wasm"``, ``"android"``, ``"pyscript"``, ``"jupyter"``, or ``"desktop"``.""" try: import _wasm_bridge # noqa: F401 return "wasm" except ImportError: pass if sys.platform == "android": return "android" try: import pyscript # noqa: F401 return "pyscript" except Exception: pass try: get_ipython() # noqa: F821 return "jupyter" except Exception: return "desktop"
# The backends in the box, in the order they are tried. Each probe says whether # this host can run it; each factory builds it (and may raise Decline, which # moves on to the next one, the way a failed import always did). def _on(kind): return lambda: host_kind() == kind def _on_windows(): return host_kind() == "desktop" and sys.platform == "win32" def _on_desktop(): return host_kind() == "desktop" _BUILTIN = ( ("wasm", "displaydev.auto:_make_wasm", _on("wasm")), ("pyscript", "displaydev.auto:_make_pyscript", _on("pyscript")), ("jupyter", "displaydev.auto:_make_jupyter", _on("jupyter")), ("android", "displaydev.auto:_make_android", _on("android")), ("win", "displaydev.auto:_make_win", _on_windows), ("pygame", "displaydev.auto:_make_pygame", _on_desktop), ("sdl", "displaydev.auto:_make_sdl", _on_desktop), ) for _name, _spec, _probe in _BUILTIN: backends.register("display", _name, _spec, probe=_probe, _builtin=True) def _make_wasm(width, height, rotation, scale, title, canvas_id, quiet, maximized): from displaydev.wasmdisplay import WasmDisplay return WasmDisplay(width, height, canvas_id, quiet=quiet) def _make_pyscript(width, height, rotation, scale, title, canvas_id, quiet, maximized): from displaydev.psdisplay import PSDisplay return PSDisplay(canvas_id, width, height, quiet=quiet) def _make_jupyter(width, height, rotation, scale, title, canvas_id, quiet, maximized): from displaydev.jndisplay import JNDisplay return JNDisplay(width, height, quiet=quiet) def _make_android(width, height, rotation, scale, title, canvas_id, quiet, maximized): import usdl2 from displaydev.androidsdl import AndroidSDLDisplay # Do not use SDL_WINDOW_FULLSCREEN_DESKTOP: it toggles immersive mode after # the Activity SurfaceView/GL buffers are created, and Android then rejects # presents (BLASTBufferQueue size mismatch → black screen after splash). # buildozer.spec keeps fullscreen=0; SHOWN + HIGHDPI matches that surface. # AndroidSDLDisplay locks Activity orientation from logical aspect. return AndroidSDLDisplay( width=width, height=height, rotation=rotation, title=title, scale=scale, quiet=quiet, window_flags=(usdl2.SDL_WINDOW_SHOWN | usdl2.SDL_WINDOW_ALLOW_HIGHDPI), ) def _make_win(width, height, rotation, scale, title, canvas_id, quiet, maximized): try: from displaydev.windisplay import WinDisplay return WinDisplay( width=width, height=height, rotation=rotation, title=title, scale=scale, quiet=quiet, maximized=maximized, ) except Exception: pass # pygame / SDL fallback: SDL2 WASAPI glitches with pygame small-chunk # playback; DirectSound does not. Must land before PGDisplay.pg.init(). from boarddev import env_get, env_set if env_get("SDL_AUDIODRIVER") is None: env_set("SDL_AUDIODRIVER", "directsound") raise backends.Decline("WinDisplay") def _make_pygame(width, height, rotation, scale, title, canvas_id, quiet, maximized): try: from displaydev.pgdisplay import PGDisplay except Exception: raise backends.Decline("PGDisplay") return PGDisplay( width=width, height=height, rotation=rotation, title=title, scale=scale, quiet=quiet, ) def _no_desktop(): """True on Linux with no Wayland or X11 session, where SDL draws through KMS.""" if not sys.platform.startswith("linux"): return False from boarddev import env_get return not (env_get("WAYLAND_DISPLAY") or env_get("DISPLAY")) def _make_sdl(width, height, rotation, scale, title, canvas_id, quiet, maximized): from displaydev.sdldisplay import SDLDisplay kwargs = {} if _no_desktop(): import usdl2 # With no desktop, a plain window makes SDL's KMS driver switch the # screen to whatever mode fits it (a 720p TV went to 1152x864). # Fullscreen-desktop keeps the screen's own mode and scales the panel # to fill it, so the scale that sizes a desktop window doesn't apply. kwargs["window_flags"] = usdl2.SDL_WINDOW_FULLSCREEN_DESKTOP | usdl2.SDL_WINDOW_ALLOW_HIGHDPI scale = 1.0 return SDLDisplay( width=width, height=height, rotation=rotation, title=title, scale=scale, quiet=quiet, **kwargs ) def _skipped_note(skipped): if not skipped: return "" return "; the required %s backend %s skipped because its probe said no" % ( ", ".join(skipped), "was" if len(skipped) == 1 else "were", )
[docs] def AutoDisplay( width=320, height=240, rotation=0, scale=1.0, title="displaydev", canvas_id=None, *, quiet=False, maximized=False, **kwargs ): """Construct a host-appropriate display driver. Args: width, height, rotation, scale, title: Forwarded to PG/SDL constructors (PS/JN ignore rotation/scale/title as their APIs dictate). canvas_id: PyScript canvas DOM id for the primary ``PSDisplay``. quiet: Suppress driver init chatter when True. maximized: Open maximised, the panel exactly the window's client area at scale 1 (width, height and scale are then ignored). WinDisplay only, for now; the other backends open at width x height. **kwargs: Passed on to the backend that wins, so a registered backend can take its own options (``tv=...``). A backend that isn't built in also gets ``rotation`` as a keyword when it isn't 0. ``scale``, ``title``, ``quiet`` and ``maximized`` are window hints for the built-in backends and never reach one that isn't. Raises: TypeError: A backend was given a keyword it doesn't take, such as a ``rotation`` it has no parameter for. The message names the backend. The search order is the ``OMNIPYTHON_DISPLAY`` environment variable, then the backends a board config asked for with ``require``, then the ones in the box. See `backends`. Returns: A ``PSDisplay``, ``JNDisplay``, ``WinDisplay``, ``PGDisplay``, or ``SDLDisplay`` with ``get_events`` set for board_config wiring; or whatever registered backend was asked for. """ from boarddev import env_get if canvas_id is None: canvas_id = env_get("OMNIPYTHON_CANVAS_ID", "display_canvas") override = env_get("OMNIPYTHON_DISPLAY") seen = [] for name, spec, builtin in backends.candidates("display", override): seen.append(name) try: factory = backends.load(spec) if builtin: if kwargs: skipped = [n for n in backends._required.get("display", ()) if n not in seen] raise TypeError( "AutoDisplay() got %s, which the %s backend doesn't take%s" % ( ", ".join(sorted(kwargs)), name, _skipped_note(skipped) if not override else "", ) ) return factory(width, height, rotation, scale, title, canvas_id, quiet, maximized) # a backend from outside the box gets the size, what you added, and # a rotation if you asked for one; the other options are window # hints for the built-in backends options = dict(kwargs) if rotation: options["rotation"] = rotation try: return factory(width=width, height=height, **options) except TypeError as exc: raise TypeError("display backend %r: %s" % (name, exc)) except backends.Decline: if override: raise ImportError( "display backend %r (OMNIPYTHON_DISPLAY) can't run here" % name ) raise ImportError( "no usable display backend; the ones registered are: %s" % ", ".join(backends.names("display")) )