# SPDX-FileCopyrightText: 2024 Brad Barnett
#
# SPDX-License-Identifier: MIT
"""Portable display driver core for MicroPython, CircuitPython, and CPython.
Each backend is a separate submodule; import only what your target needs::
from displaydev import DisplayDriver, color565, capabilities
from displaydev.busdisplay import BusDisplay
Optional host selection lives in `displaydev.auto` and is never imported
from here. Backends never import that module.
"""
import gc
import sys
try:
import micropython as _mp
except ImportError: # bare CPython
_mp = None
def _mp_native(f):
"""Apply ``@micropython.native`` when the port provides it."""
deco = getattr(_mp, "native", None) if _mp is not None else None
return deco(f) if deco is not None else f
def _install_byteswap():
"""Select a fast array implementation when available, else portable Python."""
try:
try:
import numpy as np
except ImportError:
from ulab import numpy as np
def byteswap(buf):
"""Swap a 16-bit pixel buffer in place using numpy or ulab."""
npbuf = np.frombuffer(buf, dtype=np.uint16)
npbuf.byteswap(inplace=True)
return byteswap, "array"
except Exception:
pass
@_mp_native
def byteswap(buf):
"""Swap 16-bit pixel bytes in place (portable fallback)."""
n = len(buf)
if n & 1:
raise ValueError("buffer size must be a multiple of 2")
for i in range(0, n, 2):
b0 = buf[i]
buf[i] = buf[i + 1]
buf[i + 1] = b0
return byteswap, "native" if getattr(_mp, "native", None) else "pure_python"
byteswap, _BYTESWAP_BACKEND = _install_byteswap()
__all__ = [
"DisplayDriver",
"alloc_buffer",
"byteswap",
"capabilities",
"color332",
"color565",
"color565_swapped",
"color_rgb",
]
_DEFAULT_AUTO_REFRESH_PERIOD = 33
_DESKTOP_SCALE_MARGIN = 48
# OS window frame outside the client area (title bar / borders). Usable display
# bounds exclude the taskbar/dock but not chrome; reserve these when fitting.
_DESKTOP_WINDOW_CHROME_W = 16
_DESKTOP_WINDOW_CHROME_H = 48
[docs]
def capabilities():
"""Static metadata for the modular displaydev install model (no backend imports)."""
return {
"dialect": sys.implementation.name,
"byteswap": _BYTESWAP_BACKEND,
"modules": {
"busdisplay": {"appdev": False, "auto_refresh": False},
"fbdisplay": {"appdev": False, "auto_refresh": False},
"pixeldisplay": {"appdev": False, "auto_refresh": False},
"sdldisplay": {
"appdev": True,
"auto_refresh": True,
"default_period_ms": _DEFAULT_AUTO_REFRESH_PERIOD,
"async_default": False,
"touch_scale": "1.0 (logical renderer size)",
"scroll_emulation": True,
},
"pgdisplay": {
"appdev": True,
"auto_refresh": True,
"default_period_ms": _DEFAULT_AUTO_REFRESH_PERIOD,
"async_default": False,
"touch_scale": "window scale",
"scroll_emulation": True,
},
"windisplay": {
"appdev": True,
"auto_refresh": True,
"default_period_ms": _DEFAULT_AUTO_REFRESH_PERIOD,
"async_default": False,
"touch_scale": "1.0 (wndproc maps to panel coords)",
"scroll_emulation": True,
},
"psdisplay": {
"appdev": True,
"auto_refresh": True,
"default_period_ms": _DEFAULT_AUTO_REFRESH_PERIOD,
"async_default": True,
"touch_scale": "canvas layout scale",
"scroll_emulation": True,
},
"workerdisplay": {
"appdev": True,
"auto_refresh": True,
"default_period_ms": _DEFAULT_AUTO_REFRESH_PERIOD,
"async_default": True,
"touch_scale": "canvas layout scale (the page relays it)",
"scroll_emulation": True,
},
"jndisplay": {
"appdev": True,
"auto_refresh": True,
"default_period_ms": _DEFAULT_AUTO_REFRESH_PERIOD,
"async_default": True,
"touch_scale": "1.0",
"scroll_emulation": True,
},
"auto": {
"appdev": True,
"auto_refresh": True,
"host_select": True,
},
},
}
[docs]
def alloc_buffer(size):
"""
Create a new buffer of the specified size.
Prefers SPIRAM/PSRAM when the port exposes it:
* **MicroPython ESP32** — ``esp32.idf_heap_caps_malloc``-style helpers when
present; otherwise a normal ``bytearray`` (large objects may still land
in PSRAM depending on IDF heap config).
* **CircuitPython** — GC ``bytearray``; on ESP32-S3 boards with PSRAM,
large allocations are typically served from SPIRAM. For display surfaces,
prefer ``displayio.Bitmap`` (see ``FBDisplay(..., bitmap=...)``) so paints
go through C ``bitmaptools`` into PSRAM rather than Python loops.
Args:
size (int): The size of the buffer to create.
Returns:
(memoryview): The new buffer.
"""
size = int(size)
# MicroPython / forks that expose heap_caps to Python.
for mod_name, fn_name, caps in (
("esp32", "idf_heap_caps_malloc", None),
("esp32", "heap_caps_malloc", 0x400), # MALLOC_CAP_SPIRAM on IDF
):
try:
mod = __import__(mod_name)
fn = getattr(mod, fn_name, None)
if fn is None:
continue
ptr = fn(size) if caps is None else fn(size, caps)
if ptr:
import uctypes
return memoryview(uctypes.bytearray_at(ptr, size))
except Exception:
pass
return memoryview(bytearray(size))
[docs]
def color565(r, g=None, b=None):
"""
Convert RGB values to a 16-bit color value.
Args:
r (int, tuple or list): The red value or a tuple or list of RGB values.
g (int): The green value.
b (int): The blue value.
Returns:
(int): The 16-bit color value
"""
if isinstance(r, (tuple, list)):
r, g, b = r[:3]
return ((r & 0xF8) << 8) | ((g & 0xFC) << 3) | (b >> 3)
[docs]
def color565_swapped(r, g=0, b=0):
"""
Convert RGB to 16-bit RGB565 with byte order swapped for some displays.
Args:
r (int | tuple | list): Red value, or an (r, g, b) sequence.
g (int): Green value when r is an int.
b (int): Blue value when r is an int.
Returns:
int: Byte-swapped RGB565 color.
"""
if isinstance(r, (tuple, list)):
r, g, b = r[:3]
color = color565(r, g, b)
return (color & 0xFF) << 8 | (color & 0xFF00) >> 8
[docs]
def color332(r, g, b):
"""
Convert RGB to 8-bit RGB332 color.
Args:
r (int): Red (0-255).
g (int): Green (0-255).
b (int): Blue (0-255).
Returns:
int: RGB332 color byte.
"""
return (r & 0xE0) | ((g >> 3) & 0x1C) | (b >> 6)
[docs]
def color_rgb(color):
"""
Expand a display color to an (r, g, b) tuple.
Args:
color (int | tuple | list | bytearray): 16-bit RGB565 int or 2-3 byte sequence.
Returns:
tuple[int, int, int]: Red, green, blue (0-255 each).
"""
if isinstance(color, int):
# convert 16-bit int color to 2 bytes
color = (color & 0xFF, color >> 8)
if len(color) == 2:
r = color[1] & 0xF8 | (color[1] >> 5) & 0x7 # 5 bit to 8 bit red
g = color[1] << 5 & 0xE0 | (color[0] >> 3) & 0x1F # 6 bit to 8 bit green
b = color[0] << 3 & 0xF8 | (color[0] >> 2) & 0x7 # 5 bit to 8 bit blue
else:
r, g, b = color
return (r, g, b)
@_mp_native
def _blit_transparent_rgb565(blit_rect, buf, x, y, w, h, key):
"""Scan RGB565 runs and blit non-key spans (``@micropython.native`` when available)."""
key16 = key & 0xFFFF
k0 = key16 & 0xFF
k1 = (key16 >> 8) & 0xFF
stride = w * 2
for j in range(h):
rowstart = j * stride
colstart = 0
while colstart < stride:
i = rowstart + colstart
if buf[i] != k0 or buf[i + 1] != k1:
colend = colstart + 2
while colend < stride:
ei = rowstart + colend
if buf[ei] == k0 and buf[ei + 1] == k1:
break
colend += 2
blit_rect(
buf[rowstart + colstart : rowstart + colend],
x + (colstart >> 1),
y + j,
(colend - colstart) >> 1,
1,
)
colstart = colend
else:
colstart += 2
@_mp_native
def _blit_transparent_generic(blit_rect, buf, x, y, w, h, bpp, key):
"""Scan packed runs for non-RGB565 depths."""
key_bytes = key.to_bytes(bpp, "little")
stride = w * bpp
for j in range(h):
rowstart = j * stride
colstart = 0
while colstart < stride:
startoffset = rowstart + colstart
if buf[startoffset : startoffset + bpp] != key_bytes:
colend = colstart
while colend < stride:
endoffset = rowstart + colend
if buf[endoffset : endoffset + bpp] == key_bytes:
break
colend += bpp
blit_rect(
buf[rowstart + colstart : rowstart + colend],
x + colstart // bpp,
y + j,
(colend - colstart) // bpp,
1,
)
colstart = colend
else:
colstart += bpp
[docs]
class FrameClock:
"""A display's frame cadence as a subscription: ``subscribe(fn)`` calls
``fn()`` once per frame, on the main thread, from ``multimer``.
``period_ms`` is the frame period the backend knows about; ``count`` and
``last`` (``ticks_ms``) say what has been delivered; ``stop()`` releases
the underlying timer. A backend with a host frame signal (vsync, the
browser's animation frame) subclasses this and overrides ``_start`` /
``_stop`` to deliver from that signal instead of a timer.
"""
def __init__(self, period_ms, name=None):
self._period_ms = max(1, int(period_ms))
self.name = name or "frame"
self.count = 0
self.last = None
self._subs = []
self._timer = None
@property
def period_ms(self):
return self._period_ms
@period_ms.setter
def period_ms(self, value):
value = max(1, int(value))
if value == self._period_ms:
return
self._period_ms = value
if self._timer is not None:
self._stop()
self._start()
@property
def running(self):
return self._timer is not None
def subscribe(self, fn):
if not callable(fn):
raise ValueError("fn must be callable")
if fn not in self._subs:
self._subs.append(fn)
if self._timer is None:
self._start()
return fn
def unsubscribe(self, fn):
try:
self._subs.remove(fn)
except ValueError:
pass
if not self._subs:
self.stop()
def stop(self):
self._stop()
def _start(self):
import multimer
self._timer = multimer.every(self._period_ms, self._tick, name=self.name)
def _stop(self):
t = self._timer
self._timer = None
if t is not None:
t.deinit()
def _tick(self, _timer=None):
self.count += 1
try:
from multimer import ticks_ms
self.last = ticks_ms()
except ImportError:
pass
for fn in tuple(self._subs):
fn()
_fps_clock_cache = None
def _fps_clock():
"""``(now, diff)`` for timing presents: ``diff(later, earlier)`` is in µs.
``time.ticks_us`` on MicroPython, ``perf_counter_ns`` on CPython,
``monotonic_ns`` on CircuitPython, and ``supervisor.ticks_ms`` (ms steps)
on a CircuitPython build without long ints. Chosen on first use, so a
driver that never measures never pays for it.
"""
global _fps_clock_cache
if _fps_clock_cache is None:
import time
ticks_us = getattr(time, "ticks_us", None)
ns = getattr(time, "perf_counter_ns", None) or getattr(time, "monotonic_ns", None)
if ticks_us is not None:
_fps_clock_cache = (ticks_us, time.ticks_diff)
elif ns is not None:
def now():
return ns() // 1000
def diff(a, b):
return a - b
_fps_clock_cache = (now, diff)
else:
from supervisor import ticks_ms
def diff_ms(a, b):
return (((a - b) + 0x10000000) & 0x1FFFFFFF) - 0x10000000
def diff(a, b):
return diff_ms(a, b) * 1000
_fps_clock_cache = (ticks_ms, diff)
return _fps_clock_cache
class _FpsMeter:
"""Frame and present-time counters for one display (see ``measure_fps``).
Counts go into a window that is folded into the totals once a second, so
the per-frame arithmetic stays on small ints (no heap on a board) and the
last whole second's rate falls out of the fold. Wall time is added up
between events rather than read against a start time, so a 32-bit
board's wrapping ``ticks_us`` is fine as long as something happens every
few minutes (a frame, ``fps()``, the ``fps_print`` line).
"""
def __init__(self, now, diff):
self.now = now
self.diff = diff
self.in_flush = False # inside a wrapped flush_rect/blit_rect
self.reset()
def reset(self):
self.mark = self.now()
self.win_us = 0
self.win_frames = 0
self.win_present = 0
self.win_flushes = 0
self.win_pixels = 0
self.frame_us = 0
self.frame_max = 0
self.last_fps = None
self.seconds = 0.0
self.frames = 0
self.present_us = 0.0
self.flushes = 0
self.pixels = 0
def _advance(self, t):
self.win_us += self.diff(t, self.mark)
self.mark = t
if self.win_us >= 1000000:
self._fold()
def _fold(self):
w = self.win_us
if w > 0:
self.last_fps = self.win_frames * 1000000 / w
self.seconds += w / 1000000
self.frames += self.win_frames
self.present_us += self.win_present
self.flushes += self.win_flushes
self.pixels += self.win_pixels
self.win_us = 0
self.win_frames = 0
self.win_present = 0
self.win_flushes = 0
self.win_pixels = 0
def frame(self, t, dt):
"""A present ended at ``t`` after ``dt`` µs; it finished a frame."""
f = self.frame_us + dt
self.frame_us = 0
if f > self.frame_max:
self.frame_max = f
self.win_present += dt
self.win_frames += 1
self._advance(t)
def flush(self, t, dt, pixels):
"""A ``flush_rect`` or ``blit_rect`` ended at ``t`` after ``dt`` µs: part of a frame."""
self.frame_us += dt
self.win_present += dt
self.win_flushes += 1
self.win_pixels += pixels
self._advance(t)
def snapshot(self):
self._advance(self.now())
seconds = self.seconds + self.win_us / 1000000
frames = self.frames + self.win_frames
present = self.present_us + self.win_present
if self.last_fps is not None:
fps = self.last_fps
elif self.win_us > 0:
fps = self.win_frames * 1000000 / self.win_us
else:
fps = 0.0
return {
"fps": round(fps, 1),
"avg_fps": round(frames / seconds, 1) if seconds > 0 else 0.0,
"frames": frames,
"seconds": round(seconds, 1),
"present_ms": round(present / frames / 1000, 2) if frames else 0.0,
"present_ms_max": round(self.frame_max / 1000, 2),
"busy": round(present / (seconds * 1000000), 3) if seconds > 0 else 0.0,
"flushes": self.flushes + self.win_flushes,
"pixels": self.pixels + self.win_pixels,
}
def _fps_line(s):
line = "fps %.1f avg %.1f frames %d present %.1f ms (max %.1f) busy %d%%" % (
s["fps"],
s["avg_fps"],
s["frames"],
s["present_ms"],
s["present_ms_max"],
round(s["busy"] * 100),
)
if s["flushes"]:
line += " flushes %d" % s["flushes"]
return line
def _console_off_screen():
"""Take CircuitPython's console off the board's built-in screen.
CircuitPython shows its console on ``board.DISPLAY`` and redraws it on
every ``print``; on an 800x480 panel each line stops the program for
hundreds of milliseconds. A board without ``board.DISPLAY``, one whose
display was released, and one that already shows a group of its own are
left alone.
"""
try:
import board
import displayio
display = board.DISPLAY
if display.root_group is displayio.CIRCUITPYTHON_TERMINAL:
display.root_group = None
except Exception: # noqa: BLE001 - no board.DISPLAY, or it was released
pass
[docs]
class DisplayDriver:
"""
Base class for all display backends (BusDisplay, SDLDisplay, PGDisplay, FBDisplay, etc.).
Subclasses implement drawing (``blit_rect``, ``fill_rect``, ``pixel``),
presentation (``show()``), and teardown (``quit()`` / ``deinit()``). Most
applications use a concrete driver from ``board_config.display`` rather than
instantiating this class directly.
Periodic presentation when needed is driven by ``appdev.App`` (see
``needs_refresh``).
``share_framebuffer``: when True, a GUI may bind the panel scanout
buffer(s) from `framebuffers` for direct rendering (e.g. LVGL
``DISPLAY_RENDER_MODE.DIRECT``). Default False — desktop/bus drivers keep
their own draw buffers.
Frame rate: `measure_fps` (or ``OMNIPYTHON_FPS=1``) counts frames and
times presents; `fps` reads them. Off by default, and nothing is
wrapped or timed while it is off.
``can_rotate``: whether setting `rotation` turns what you draw. When it's
False, `rotation` only swaps `width` and `height`, and drawing still lands
in the panel's own layout, so a program that wants another orientation
keeps the display's own one instead (or rotates its frames itself).
"""
needs_refresh = False
# The panel or window turns with ``rotation``; drivers over a fixed
# framebuffer say otherwise.
can_rotate = True
# The frame-rate meter while measuring (measure_fps); None means off.
_fps = None
_fps_timer = None
# The display's own frame period: what ``appdev.App`` presents at and what a
# GUI's refresh timer is set to. A backend that can measure its host's
# refresh (vsync, requestAnimationFrame) sets it; 33 ms otherwise.
# ``OMNIPYTHON_REFRESH_MS`` overrides it per instance when the driver starts.
refresh_period_ms = 33
share_framebuffer = False
# HostEventsDevice reads this ``(key, mod)`` tuple; None disables keyboard quit.
quit_chord = None
@property
def frame_clock(self):
"""This display's `FrameClock`: "call me once per frame".
Created on first use. Backends with a real frame signal override
``_make_frame_clock``; the default is a ``multimer`` timer at
`refresh_period_ms`.
"""
fc = getattr(self, "_frame_clock", None)
if fc is None:
fc = self._make_frame_clock()
self._frame_clock = fc
return fc
def _make_frame_clock(self):
return FrameClock(self.refresh_period_ms, name="frame:%s" % (self.__class__.__name__,))
[docs]
def framebuffers(self):
"""Return panel buffers for direct GUI paint, or ``None``.
When sharing is supported, returns
``(buf1, buf2_or_None, nbytes, stride_bytes)``.
"""
return None
def __init__(self, *, quiet=False):
"""Initialize shared display state and call subclass `init`.
Args:
quiet: When True, suppress init / rotation chatter.
"""
self._quiet = quiet
if sys.implementation.name == "circuitpython":
_console_off_screen()
if not self._quiet:
print(f"Initializing {self.__class__.__name__}...")
gc.collect()
self.byteswap = byteswap
# Subclasses (e.g. PGDisplay) may set touch_scale before super().__init__
# to match window scaling; do not clobber a preconfigured value.
if getattr(self, "touch_scale", None) is None:
self.touch_scale = 1.0
self._vssa = False # False means no vertical scroll
self._auto_byteswap = self.requires_byteswap
self._touch_device = None
self.init()
gc.collect()
self._deinitialized = False
self._apply_refresh_override()
if not self._quiet:
print(f"{self.__class__.__name__}: initialized.")
if self.requires_byteswap:
print(
f"{self.__class__.__name__}: requires_byteswap = True"
f" (byteswap={_BYTESWAP_BACKEND})"
)
if _BYTESWAP_BACKEND == "pure_python":
print(
f"{self.__class__.__name__}: warning: slow byteswap fallback; "
"install utils/byteswap (GitHub MIP) for viper/numpy swap"
)
# The environment helpers are boarddev's, imported where they are read
# so displaydev never re-exports them.
from boarddev import env_bool, env_float
every = env_float("OMNIPYTHON_FPS_PRINT", 0)
if every > 0:
self.fps_print(every)
elif env_bool("OMNIPYTHON_FPS"):
self.measure_fps(True)
def _apply_refresh_override(self):
"""``OMNIPYTHON_REFRESH_MS=N`` replaces this display's frame period.
Read once, when the driver starts, after the backend's own ``init()``
has had its say, so it wins over a backend's default (33 ms, or the
browser's 16). ``appdev.App``'s refresh timer, the frame clock and
``display_driver``'s LVGL refresh timer all read
`refresh_period_ms`, so LVGL and non-LVGL apps both follow it.
Unset, empty, zero or not a number leaves the backend's period alone.
"""
from boarddev import env_int
period = env_int("OMNIPYTHON_REFRESH_MS", 0)
if period <= 0:
return
self.refresh_period_ms = period
fc = getattr(self, "_frame_clock", None)
if fc is not None:
fc.period_ms = period
def __del__(self):
self.deinit()
############### Universal API Methods, not usually overridden ################
@property
def width(self) -> int:
"""The width of the display in pixels."""
if ((self._rotation // 90) & 0x1) == 0x1: # if rotation index is odd
return self._height
return self._width
@property
def height(self) -> int:
"""The height of the display in pixels."""
if ((self._rotation // 90) & 0x1) == 0x1: # if rotation index is odd
return self._width
return self._height
@property
def rotation(self) -> int:
"""
The rotation of the display.
"""
return self._rotation
@rotation.setter
def rotation(self, value) -> None:
"""
Sets the rotation of the display.
Args:
value (int): The rotation of the display in degrees.
"""
if value % 90 != 0:
value = value * 90
if value == self._rotation:
return
if not self._quiet:
print(f"{self.__class__.__name__}.rotation(): Setting rotation to {value}")
self._rotation_helper(value)
if not self._quiet:
print("done setting rotation")
self._rotation = value
if self._touch_device is not None:
self._touch_device.rotation = value
self.init()
@property
def touch_device(self) -> object:
"""
The touch device.
"""
return self._touch_device
@touch_device.setter
def touch_device(self, value) -> None:
"""
Sets the touch device.
Args:
value (object): The touch device.
"""
if hasattr(value, "rotation") or value is None:
self._touch_device = value
else:
raise ValueError("touch_device must have a rotation attribute")
self._touch_device.rotation = self.rotation
[docs]
def fill(self, color):
"""
Fill the display with a color.
Args:
color (int): The color to fill the display with.
"""
return self.fill_rect(0, 0, self.width, self.height, color)
[docs]
def disable_auto_byteswap(self, value: bool) -> bool:
"""
Disable byte swapping in the display driver.
If self.requires_byteswap and the guest application is capable of byte swapping color data
check to see if byte swapping can be disabled. If so, disable it.
Usage::
# If byte swapping is required and the display driver is capable of having byte swapping disabled,
# disable it and set a flag so we can swap the color bytes as they are created.
if display_drv.requires_byteswap:
needs_swap = display_drv.disable_auto_byteswap(True)
else:
needs_swap = False
Args:
value (bool): Whether to disable byte swapping.
Returns:
(bool): Whether byte swapping was disabled successfully.
"""
if self._requires_byteswap:
self._auto_byteswap = not value
else:
self._auto_byteswap = False
if not self._quiet:
print(f"{self.__class__.__name__}: auto byte swapping = {self._auto_byteswap}")
return not self._auto_byteswap
@property
def requires_byteswap(self) -> bool:
"""
Whether the display requires byte swapping.
"""
return self._requires_byteswap
[docs]
def blit_transparent(self, buf: memoryview, x: int, y: int, w: int, h: int, key: int):
"""
Blit a buffer with transparency.
Args:
buf (memoryview): The buffer to blit.
x (int): The x coordinate to blit to.
y (int): The y coordinate to blit to.
w (int): The width to blit.
h (int): The height to blit.
key (int): The color key to use for transparency.
Returns:
(tuple): The x, y, w, h coordinates of the blitted area.
"""
bpp = self.color_depth // 8
if bpp == 2:
_blit_transparent_rgb565(self.blit_rect, buf, x, y, w, h, key)
else:
_blit_transparent_generic(self.blit_rect, buf, x, y, w, h, bpp, key)
return (x, y, w, h)
@property
def vscroll(self) -> int:
"""
The vertical scroll position relative to the top fixed area.
Returns:
(int): The vertical scroll position.
"""
return self.vscsad() - self._tfa
@vscroll.setter
def vscroll(self, y) -> None:
"""
Set the vertical scroll position relative to the top fixed area.
Args:
y (int): The vertical scroll position.
"""
self.vscsad((y % self._vsa) + self._tfa)
@property
def tfa(self) -> int:
"""
The top fixed area set by set_vscroll or vscrdef.
Returns:
(int): The top fixed area.
"""
return self._tfa
@property
def vsa(self) -> int:
"""
The vertical scroll area set by set_vscroll or vscrdef.
Returns:
(int): The vertical scroll area.
"""
return self._vsa
@property
def bfa(self) -> int:
"""
The bottom fixed area set by set_vscroll or vscrdef.
Returns:
(int): The bottom fixed area.
"""
return self._bfa
[docs]
def translate_point(self, point) -> tuple:
"""
Translate a point from real coordinates to scrolled coordinates.
Useful for touch events.
Args:
point (tuple): The x and y coordinates to translate.
Returns:
(tuple): The translated x and y coordinates.
"""
x, y = point
if self.vscsad() and self.tfa < y < self.height - self.bfa:
y = y + self.vscsad() - self.tfa
if y >= (self.vsa + self.tfa):
y %= self.vsa
return x, y
@property
def tfa_area(self):
"""
Top fixed area for vertical scrolling.
Returns:
tuple[int, int, int, int]: ``(x, y, width, height)`` of the top fixed band.
"""
return (0, 0, self.width, self.tfa)
@property
def vsa_area(self):
"""
The vertical scroll area as an Area object.
Returns:
(tuple): The vertical scroll area.
"""
return (0, self.tfa, self.width, self.vsa)
@property
def bfa_area(self):
"""
The bottom fixed area as an Area object.
Returns:
(tuple): The bottom fixed area.
"""
return (0, self.tfa + self.vsa, self.width, self.bfa)
############### Frame rate ################
[docs]
def measure_fps(self, on=True):
"""Count frames and time presents (``on=True``), or stop (``on=False``).
Switched on, the instance's ``show``, ``flush_rect`` and ``blit_rect``
are wrapped with timers; switched off they are the class's own
methods again. A frame is one ``show()``, or one `frame_done`
from a GUI that presents with ``flush_rect`` (LVGL on a
direct-framebuffer panel). ``flush_rect`` and ``blit_rect`` calls
(a partial-render panel presents through ``blit_rect``) are counted
as ``flushes`` and ``pixels``, not frames; one that calls the other
is counted once. ``OMNIPYTHON_FPS=1`` switches it on when the driver starts.
Returns:
bool: Whether it is measuring now.
"""
if on:
if self._fps is None:
now, diff = _fps_clock()
self._fps = _FpsMeter(now, diff)
self._fps_wrapped = []
self._fps_wrap("show")
self._fps_wrap("flush_rect")
self._fps_wrap("blit_rect")
elif self._fps is not None:
self.fps_print(0)
for name, wrapper, prev in self._fps_wrapped:
if getattr(self, name, None) is not wrapper:
continue # someone wrapped ours since: leave theirs alone
if prev is None:
delattr(self, name)
else:
setattr(self, name, prev)
self._fps_wrapped = []
self._fps = None
return self._fps is not None
def _fps_wrap(self, name):
orig = getattr(self, name, None)
if orig is None:
return
try:
own = name in self.__dict__
except AttributeError:
own = False
meter = self._fps
now = meter.now
diff = meter.diff
if name == "flush_rect":
def wrapper(x, y, w, h, *args, **kwargs):
if meter.in_flush:
return orig(x, y, w, h, *args, **kwargs)
meter.in_flush = True
t = now()
try:
return orig(x, y, w, h, *args, **kwargs)
finally:
meter.in_flush = False
t1 = now()
meter.flush(t1, diff(t1, t), w * h)
elif name == "blit_rect":
def wrapper(buf, x, y, w, h, *args, **kwargs):
if meter.in_flush:
return orig(buf, x, y, w, h, *args, **kwargs)
meter.in_flush = True
t = now()
try:
return orig(buf, x, y, w, h, *args, **kwargs)
finally:
meter.in_flush = False
t1 = now()
meter.flush(t1, diff(t1, t), w * h)
else:
def wrapper(*args, **kwargs):
t = now()
try:
return orig(*args, **kwargs)
finally:
t1 = now()
meter.frame(t1, diff(t1, t))
self._fps_wrapped.append((name, wrapper, orig if own else None))
setattr(self, name, wrapper)
[docs]
def frame_done(self):
"""A GUI that presents with ``flush_rect`` says a frame's last area is done.
``display_driver`` calls this on a direct-framebuffer panel when the
last area was presented by ``flush_rect`` and no ``show()`` followed.
Does nothing unless `measure_fps` is on.
"""
meter = self._fps
if meter is not None:
meter.frame(meter.now(), 0)
[docs]
def fps(self):
"""The frame rate and present times, or ``None`` when not measuring.
Returns a dict: ``fps`` (the last whole second), ``avg_fps`` (since
`measure_fps` or `fps_reset`), ``frames``, ``seconds``,
``present_ms`` / ``present_ms_max`` (mean and worst time presenting a
frame, its ``flush_rect`` calls included), ``busy`` (the share of
wall time spent presenting: high means the display is the
bottleneck, low means the app is), ``flushes`` and ``pixels``.
"""
meter = self._fps
return None if meter is None else meter.snapshot()
[docs]
def fps_reset(self):
"""Start a fresh measurement (does nothing when not measuring)."""
if self._fps is not None:
self._fps.reset()
[docs]
def fps_print(self, seconds=5):
"""Print a one-line summary every ``seconds``; ``0`` stops it.
Switches `measure_fps` on. The line is short, for agents
tailing a log::
fps 29.8 avg 29.5 frames 1180 present 4.2 ms (max 12.0) busy 13%
``OMNIPYTHON_FPS_PRINT=N`` starts it when the driver starts.
"""
timer = self._fps_timer
self._fps_timer = None
if timer is not None:
timer.deinit()
if not seconds or seconds <= 0:
return
self.measure_fps(True)
import multimer
def _print(_timer=None):
meter = self._fps
if meter is not None:
print(_fps_line(meter.snapshot()))
self._fps_timer = multimer.every(
max(1, int(seconds * 1000)), _print, name="fps:%s" % (self.__class__.__name__,)
)
############### Common API Methods, sometimes overridden ################
[docs]
def vscrdef(self, tfa: int, vsa: int, bfa: int) -> None:
"""
Set the vertical scroll definition. Should be overridden by the
subclass and called as super().vscrdef(tfa, vsa, bfa).
Args:
tfa (int): The top fixed area.
vsa (int): The vertical scroll area.
bfa (int): The bottom fixed area.
"""
if tfa + vsa + bfa != self.height:
raise ValueError("Sum of top, scroll and bottom areas must equal screen height")
self._tfa = tfa
self._vsa = vsa
self._bfa = bfa
[docs]
def vscsad(self, vssa: int | None = None) -> int:
"""
Set or get the vertical scroll start address. Should be overridden by the
subclass and called as super().vscsad(y).
Args:
vssa (int): The vertical scroll start address.
Returns:
(int): The vertical scroll start address.
"""
if vssa is not None:
while vssa < 0:
vssa += self._height
if vssa >= self._height:
vssa %= self._height
self._vssa = vssa
return vssa
def _rotation_helper(self, value):
"""
Helper function to set the rotation of the display.
Args:
value (int): The rotation of the display in degrees.
"""
# override this method in subclasses to handle rotation
############### Empty API Methods, must be overridden if applicable ################
@property
def power(self) -> bool:
"""The power state of the display."""
return -1
@power.setter
def power(self, value: bool) -> None:
"""
Set the power state of the display. Should be overridden by the subclass.
Args:
value (bool): True to power on, False to power off.
"""
return
@property
def brightness(self) -> float:
"""The brightness of the display."""
return -1
@brightness.setter
def brightness(self, value: float) -> None:
"""
Set the brightness of the display. Should be overridden by the subclass.
Args:
value (int, float): The brightness value from 0 to 1.
"""
return
[docs]
def invert_colors(self, value: bool) -> None:
"""
Invert the colors of the display. Should be overridden by the subclass.
Args:
value (bool): True to invert the colors, False to restore the colors.
"""
return
[docs]
def reset(self) -> None:
"""
Perform a reset of the display. Should be overridden by the subclass.
"""
return
[docs]
def hard_reset(self) -> None:
"""
Perform a hardware reset of the display. Should be overridden by the subclass.
"""
return
[docs]
def soft_reset(self) -> None:
"""
Perform a software reset of the display. Should be overridden by the subclass.
"""
return
[docs]
def sleep_mode(self, value: bool) -> None:
"""
Set the sleep mode of the display. Should be overridden by the subclass.
Args:
value (bool): True to enter sleep mode, False to exit sleep mode.
"""
return
[docs]
def deinit(self) -> None:
"""
Run subclass cleanup. Idempotent.
The broker owns the shared refresh timer, so there is no display-owned
timer to stop here; ``board_config`` stops the timer on quit via
``app.stop_timer``.
"""
if getattr(self, "_deinitialized", False):
return
self._deinitialized = True
if self._fps_timer is not None:
self.fps_print(0) # the counts stay readable after quit
self._deinit()
def _deinit(self) -> None:
"""Subclass resource cleanup hook, called after the timer is stopped."""
return
[docs]
def quit(self, code: int = 0, force: bool = False) -> None:
"""Release display resources (REPL-safe unless ``force=True``). Called on QUIT."""
self.deinit()
if force:
raise SystemExit(code)
[docs]
def force_quit(self, code: int = 0) -> None:
"""Release resources then exit the process (alias for ``quit(code, force=True)``)."""
self.quit(code, force=True)
[docs]
def show(self, *args, **kwargs) -> None:
"""
Show the display. Base class method does nothing. May be overridden by subclasses.
"""
return