# SPDX-FileCopyrightText: 2026 Brad Barnett
#
# SPDX-License-Identifier: MIT
"""
displaydev.workerdisplay
A display for Python running in a Web Worker: it draws on an
``OffscreenCanvas`` the page transferred to the worker, and takes its input
from events the page relays.
Running the app in a worker leaves the page's main thread free, so a long
redraw never holds up anything the page has to do on time (Web MIDI, audio
hand-offs, input). The page side is a few lines of JavaScript:
.. code-block:: javascript
const off = canvas.transferControlToOffscreen();
worker.postMessage({type: "canvas", canvas: off}, [off]);
// then, for every pointer, wheel and key event on the canvas:
worker.postMessage({type: "input", event: {
type: e.type, // pointerdown, pointerup, pointercancel,
// pointermove, wheel, keydown, keyup
x: e.offsetX, y: e.offsetY, // CSS pixels inside the canvas
movementX: e.movementX, movementY: e.movementY,
button: e.button, buttons: e.buttons,
pointerType: e.pointerType, pointerId: e.pointerId,
deltaX: e.deltaX, deltaY: e.deltaY,
key: e.key, location: e.location, repeat: e.repeat,
ctrlKey: e.ctrlKey, shiftKey: e.shiftKey, altKey: e.altKey, metaKey: e.metaKey,
}});
// and whenever the canvas's CSS size changes:
worker.postMessage({type: "resize", width: rect.width, height: rect.height});
In the worker, hand each ``input`` event to `feed` and each
``resize`` to `WorkerDisplay.set_css_size`. The events come out of
``display_drv.get_events`` exactly as `PSDisplay` produces them, so
``appdev`` and LVGL's ``display_driver`` work unchanged. The page should
call ``preventDefault()`` itself on ``wheel``, ``contextmenu`` and the keys
that scroll a page; a worker can't.
Gamepads aren't available in a worker.
"""
from displaydev._webcanvas import CanvasDisplay
from displaydev._webinput import WebInput
import keys
_current = None
[docs]
class WorkerDevices(WebInput):
"""Input for a `WorkerDisplay`, fed by events the page relays."""
_HANDLERS = {
"pointerdown": "_on_pointer_down",
"pointerup": "_on_pointer_up",
"pointercancel": "_on_pointer_up",
"pointermove": "_on_pointer_move",
"wheel": "_on_wheel",
"keydown": "_on_keydown",
"keyup": "_on_keyup",
}
[docs]
def feed(self, event):
"""Queue one relayed browser event (a JS object or a ``dict``)."""
if isinstance(event, dict):
event = _Event(event)
name = self._HANDLERS.get(str(event.type))
if name:
getattr(self, name)(event)
def _local_xy(self, e):
return float(e.x), float(e.y)
def _poll_gamepads(self):
pass
class _Event:
"""Attribute access over a plain ``dict`` (tests, or a converted JS object)."""
def __init__(self, d):
self.__dict__.update(d)
def __getattr__(self, name):
raise AttributeError(name)
[docs]
class WorkerDisplay(CanvasDisplay):
"""Emulate a display on an ``OffscreenCanvas``, from a Web Worker.
Args:
canvas: The ``OffscreenCanvas`` the page transferred to this worker.
width (int, optional): Panel width; defaults to the canvas width.
height (int, optional): Panel height; defaults to the canvas height.
quiet (bool): Suppress init chatter when True.
"""
needs_refresh = True
quit_chord = (keys.K_AC_BACK, 0)
def __init__(self, canvas, width=None, height=None, *, quiet=False):
global _current
self._css_size = None
super().__init__(canvas, width, height, quiet=quiet)
self._devices = WorkerDevices(self)
self.get_events = self._devices.read
self.feed = self._devices.feed
_current = self
def _new_buffer(self, width, height):
from js import OffscreenCanvas
return OffscreenCanvas.new(width, height)
[docs]
def set_css_size(self, width, height):
"""Tell the display how big the page shows the canvas, in CSS pixels."""
self._css_size = (float(width), float(height))
def _pointer_scale(self):
"""Framebuffer pixels per CSS pixel (1.0 until the page says otherwise)."""
if not self._css_size:
return 1.0, 1.0
cw, ch = self._css_size
if cw <= 0 or ch <= 0:
return 1.0, 1.0
return float(self.width) / cw, float(self.height) / ch
@property
def touch_scale(self):
"""CSS pixels per framebuffer pixel, the same contract as ``PSDisplay``."""
sx, _sy = self._pointer_scale()
return 1.0 / sx if sx else 1.0
@touch_scale.setter
def touch_scale(self, value):
# DisplayDriver.__init__ assigns a default; the page's layout decides.
pass
[docs]
def map_pointer(self, local_x, local_y):
"""Map canvas-local CSS pixels to framebuffer ``(x, y)``."""
sx, sy = self._pointer_scale()
return (int(float(local_x) * sx), int(float(local_y) * sy))
[docs]
def map_pointer_rel(self, dx, dy):
"""Map a pointer delta in CSS pixels to framebuffer pixels."""
sx, sy = self._pointer_scale()
return (int(float(dx) * sx), int(float(dy) * sy))
[docs]
def feed(event):
"""Hand a relayed ``input`` event to the most recent `WorkerDisplay`."""
if _current is not None:
_current.feed(event)
[docs]
def resize(width, height):
"""Hand a relayed ``resize`` to the most recent `WorkerDisplay`."""
if _current is not None:
_current.set_css_size(width, height)