Source code for displaydev.wasmdisplay

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

"""Direct MicroPython WebAssembly RGB565 display and browser input backend."""

import json

import _wasm_bridge
import events
import keys

from displaydev._desktop import DesktopDisplay
from displaydev._domkeys import enrich_mod, key_to_keycode, mod_mask
from displaydev.fbdisplay import FBDisplay

_POINTER_EVENT_TYPES = (events.Motion, events.Button, events.Finger)


def _buttons_tuple(buttons):
    return (1 if buttons & 1 else 0, 1 if buttons & 4 else 0, 1 if buttons & 2 else 0)


[docs] class WasmDevices: """Translate neutral bridge records into the project-wide ``events`` contract.""" def __init__(self, canvas_id): self._canvas_id = canvas_id self._pressed = set() self._pointer_pos = {} self._finger_pos = {} self._gamepad_axes = {} self._gamepad_buttons = {} def read(self): result = self._read() if result: result = self._touch_motion(result) return result def _touch_motion(self, batch): """Follow each FINGERMOTION with a Motion(touch=True), as SDL does. The bridge turns a finger move into FINGERMOTION alone; code written against the mouse (a drag handler listening for Motion) needs the Motion too. The finger is down while it moves, so the left button is held. """ out = [] for event in batch: out.append(event) kind = getattr(event, "type", None) if kind == events.FINGERDOWN: self._finger_pos[event.finger_id] = event.pos elif kind == events.FINGERUP: self._finger_pos.pop(event.finger_id, None) elif kind == events.FINGERMOTION: old = self._finger_pos.get(event.finger_id, event.pos) self._finger_pos[event.finger_id] = event.pos rel = (event.pos[0] - old[0], event.pos[1] - old[1]) out.append( events.Motion(events.MOUSEMOTION, event.pos, rel, (1, 0, 0), True, event.window) ) return out def _read(self): result = [] batch, raw_count = _wasm_bridge.poll_events(self._canvas_id, _POINTER_EVENT_TYPES) if batch is None: return None if not raw_count: return batch for raw in batch: if isinstance(raw, str): event = self._convert(json.loads(raw)) elif isinstance(raw, list) or raw[0] > 9: event = raw else: event = self._convert_fast(raw) if event is None: continue if isinstance(event, list): result.extend(event) else: result.append(event) return result or None def _convert_fast(self, item): kind = item[0] pos = (item[1], item[2]) if kind <= 5 else (0, 0) if kind in (1, 3): pointer_id = item[7] touch = item[8] != 0 out = [] down = kind == 1 if touch: out.append( events.Finger( events.FINGERDOWN if down else events.FINGERUP, pos, pointer_id, None, ) ) out.append( events.Button( events.MOUSEBUTTONDOWN if down else events.MOUSEBUTTONUP, pos, item[5] + 1, touch, None, ) ) self._pointer_pos[pointer_id] = pos return out if kind == 2: pointer_id = item[7] touch = item[8] != 0 old = self._pointer_pos.get(pointer_id, pos) self._pointer_pos[pointer_id] = pos if touch: return events.Finger(events.FINGERMOTION, pos, pointer_id, None) rel = (item[3] or pos[0] - old[0], item[4] or pos[1] - old[1]) return events.Motion( events.MOUSEMOTION, pos, rel, _buttons_tuple(item[6]), False, None ) if kind == 5: dx, dy = item[3] / 1000, item[4] / 1000 return events.Wheel( events.MOUSEWHEEL, False, -int(dx), -int(dy), -dx, -dy, False, None ) if kind in (6, 7): name, location, flags = item[1], item[3], item[4] code = key_to_keycode(name, location) if kind == 6: self._pressed.add(code) else: self._pressed.discard(code) modifiers = mod_mask(flags & 2, flags & 8, flags & 1, flags & 4) return events.Key( events.KEYDOWN if kind == 6 else events.KEYUP, name, code, enrich_mod(modifiers, self._pressed), item[2], None, ) return None def clear(self): _wasm_bridge.clear_events(self._canvas_id) self._pressed.clear() self._pointer_pos.clear() self._finger_pos.clear() def _convert(self, item): kind = item.get("type") pos = (int(item.get("x", 0)), int(item.get("y", 0))) pointer_id = int(item.get("pointerId", 0)) touch = item.get("pointerType", "mouse") != "mouse" if kind in ("pointerdown", "pointerup"): out = [] if touch: out.append( events.Finger( events.FINGERDOWN if kind == "pointerdown" else events.FINGERUP, pos, pointer_id, None, ) ) out.append( events.Button( events.MOUSEBUTTONDOWN if kind == "pointerdown" else events.MOUSEBUTTONUP, pos, int(item.get("button", 0)) + 1, touch, None, ) ) self._pointer_pos[pointer_id] = pos return out if kind == "pointermove": old = self._pointer_pos.get(pointer_id, pos) self._pointer_pos[pointer_id] = pos if touch: return events.Finger(events.FINGERMOTION, pos, pointer_id, None) rel = ( int(item.get("movementX", pos[0] - old[0])), int(item.get("movementY", pos[1] - old[1])), ) return events.Motion( events.MOUSEMOTION, pos, rel, _buttons_tuple(int(item.get("buttons", 0))), False, None, ) if kind == "wheel": return events.Wheel( events.MOUSEWHEEL, False, -int(item.get("deltaX", 0)), -int(item.get("deltaY", 0)), -float(item.get("deltaX", 0)), -float(item.get("deltaY", 0)), False, None, ) if kind in ("keydown", "keyup"): name = str(item.get("key", "")) code = key_to_keycode(name, int(item.get("location", 0))) if kind == "keydown": self._pressed.add(code) else: self._pressed.discard(code) modifiers = mod_mask( item.get("ctrlKey", False), item.get("shiftKey", False), item.get("altKey", False), item.get("metaKey", False), ) modifiers = enrich_mod(modifiers, self._pressed) return events.Key( events.KEYDOWN if kind == "keydown" else events.KEYUP, name, code, modifiers, item.get("code"), None, ) if kind == "gamepad": return self._gamepad(item) return None def _gamepad(self, item): index = int(item.get("index", 0)) output = [] axes = item.get("axes", ()) old_axes = self._gamepad_axes.get(index, ()) for axis, value in enumerate(axes): normalized = int(max(-1.0, min(1.0, float(value))) * 32767) old = old_axes[axis] if axis < len(old_axes) else 0 if abs(normalized - old) >= 256: output.append( events.JoyAxisMotion(events.JOYAXISMOTION, index, axis, normalized) ) self._gamepad_axes[index] = [ int(max(-1.0, min(1.0, float(v))) * 32767) for v in axes ] buttons = [ bool(button.get("pressed", False)) for button in item.get("buttons", ()) ] old_buttons = self._gamepad_buttons.get(index, ()) for number, pressed in enumerate(buttons): old = old_buttons[number] if number < len(old_buttons) else False if pressed != old: cls = events.JoyButtonDown if pressed else events.JoyButtonUp event_type = events.JOYBUTTONDOWN if pressed else events.JOYBUTTONUP output.append(cls(event_type, index, number)) self._gamepad_buttons[index] = buttons return output
[docs] class WasmDisplay(DesktopDisplay, FBDisplay): """A Python-owned RGB565 framebuffer scanned live by the browser. Apps draw into ``_framebuffer`` through the inherited `FBDisplay` primitives. ``_displayed`` starts out *as* ``_framebuffer`` (the same object) -- the browser's ``requestAnimationFrame`` loop reads straight off WASM linear memory at the registered pointer every frame regardless of whether Python ever calls `show`, so a single shared buffer is already correct and ``show()`` needs to do nothing. A second, real ``_displayed`` buffer is only allocated the first time an app actually engages the classic hardware vertical-scroll registers (``vscrdef``/``vscsad``/``vscroll`` -- emulating a real SPI panel's scan address, the way `PSDisplay` does with ``drawImage``). LVGL apps never touch that API; they scroll entirely at the widget level, so they stay single-buffered and never pay for a full-frame copy on every flush. `_composite` is where that promotion happens, and where the row- shifted copy runs once it has. Attributes: needs_refresh (bool): True — ``appdev.App`` drives periodic ``show()``, so draws that never call ``show()`` explicitly (e.g. a scroll timer) still reach the composited front buffer once double- buffered. """ needs_refresh = True # The browser scans the framebuffer each animation frame; 60 Hz is the # common case and the bridge does not yet report the real rate. refresh_period_ms = 16 quit_chord = (keys.K_AC_BACK, 0) # Unlike a panel's framebuffer, this one is the canvas: a rotation hands # the browser the swapped size, so drawing at it works. can_rotate = True def __init__( self, width=320, height=240, canvas_id="display_canvas", *, quiet=False ): self._canvas_id = canvas_id self._framebuffer = bytearray(int(width) * int(height) * 2) self._displayed = self._framebuffer # single-buffered until real scroll use self._double_buffered = False self._devices = WasmDevices(canvas_id) # Not super(): MicroPython's super() doesn't do full C3-linearized # dispatch across multiple bases — with DesktopDisplay first and no # __init__ override of its own, super().__init__() binds straight to # DisplayDriver.__init__ (self, *, quiet=False) instead of continuing # the MRO to FBDisplay.__init__, dropping the buffer/width/height it # needs. Call it explicitly instead. FBDisplay.__init__(self, self._framebuffer, int(width), int(height), quiet=quiet) self.get_events = self._devices.read
[docs] def init(self): # Straight to DisplayDriver, matching PSDisplay/SDLDisplay/PGDisplay: # a full-height scroll region so vscsad() works before any explicit # set_vscroll/vscrdef, without firing _scroll_changed mid-init. self._reset_vscroll() if not _wasm_bridge.register_framebuffer( self._displayed, self.width, self.height, self._canvas_id ): raise RuntimeError(f"WASM canvas {self._canvas_id!r} was not found") self._composite()
def _scroll_changed(self): """Repaint immediately; this backend has no deferred-render tick.""" self._composite()
[docs] def show(self, _timer=None): self._composite()
def _composite(self): """Copy the back buffer to the front buffer, applying vscroll. No-op while single-buffered and unscrolled (``_displayed`` already *is* ``_framebuffer``, so the browser already sees every draw). The first genuine scroll offset promotes to a real second buffer and re-registers it with the bridge; from then on this always keeps ``_displayed`` in sync, same as before that promotion existed. """ y_start = self.vscsad() if not self._double_buffered: if not y_start: return self._displayed = bytearray(self._framebuffer) self._double_buffered = True if not _wasm_bridge.register_framebuffer( self._displayed, self.width, self.height, self._canvas_id ): raise RuntimeError(f"WASM canvas {self._canvas_id!r} was not found") row_bytes = self.width * 2 src = self._framebuffer dst = self._displayed if not y_start: dst[:] = src return tfa, vsa, bfa = self._tfa, self._vsa, self._bfa if tfa: n = tfa * row_bytes dst[0:n] = src[0:n] top_h = vsa + tfa - y_start a, b = y_start * row_bytes, (y_start + top_h) * row_bytes da, db = tfa * row_bytes, (tfa + top_h) * row_bytes dst[da:db] = src[a:b] btm_h = vsa - top_h if btm_h: a2, b2 = tfa * row_bytes, (tfa + btm_h) * row_bytes dst[db : db + (b2 - a2)] = src[a2:b2] if bfa: n = bfa * row_bytes dst[len(dst) - n :] = src[len(src) - n :] def _deinit(self): self._devices.clear() _wasm_bridge.unregister_framebuffer(self._canvas_id)