# SPDX-FileCopyrightText: 2024 Brad Barnett
#
# SPDX-License-Identifier: MIT
"""
displaydev.fbdisplay
"""
from displaydev import DisplayDriver
def _as_u16_pixels(buf):
"""View RGB565 byte data as uint16 pixels (little-endian) for bitmaptools."""
mv = memoryview(buf)
try:
return mv.cast("H")
except (AttributeError, TypeError, ValueError):
import array
return array.array("H", mv)
[docs]
class FBDisplay(DisplayDriver):
"""
A class to interface with CircuitPython FrameBuffer objects.
Args:
buffer (FrameBuffer): The CircuitPython FrameBuffer object
(e.g. ``dotclockframebuffer.DotClockFramebuffer``, already in PSRAM).
width (int, optional): The width of the display. Defaults to None.
height (int, optional): The height of the display. Defaults to None.
reverse_bytes_in_word (bool, optional): Whether to reverse the bytes in a word. Defaults to False.
bitmap: Optional ``displayio.Bitmap`` paint surface (typically allocated in
SPIRAM/PSRAM). When set with ``bitmaptools``, blit/fill use C
``arrayblit`` / ``fill_region`` — the Adafruit Qualia RGB666 path —
instead of Python loops into the raw framebuffer.
display: Optional ``framebufferio.FramebufferDisplay`` that owns ``bitmap``
as its root group. ``show()`` calls ``display.refresh()`` so dirty
regions are composited in C into the DotClock PSRAM framebuffer.
Attributes:
color_depth (int): The color depth of the display
``share_framebuffer`` and ``needs_refresh`` are properties, below.
``can_rotate`` is False: the framebuffer is laid out at the panel's own
size, so `rotation` swaps `width` and `height` but every blit and fill
still lands in the panel's orientation. LVGL turns its frames itself
(``lvgl_rotation`` on the board's display), and other programs keep the
panel's orientation.
"""
can_rotate = False
@property
def share_framebuffer(self):
"""Whether a GUI may paint the scanout buffer directly.
Not when a ``framebufferio.FramebufferDisplay`` was given: it composites
its own root group into that buffer at the panel rate (and keeps PSRAM's
cache in step for the scanout), so direct paint would race it and could
reach the panel late. The GUI paints through `blit_rect` instead,
into ``bitmap`` when there is one.
"""
return self._display is None
@property
def needs_refresh(self):
"""Whether ``appdev.App`` must drive periodic ``show()``.
This cannot be a class attribute, because one class covers two runtimes
that need opposite answers:
* CircuitPython's ``framebufferio.FramebufferDisplay(fb,
auto_refresh=True)`` composites at the panel rate on its own, and
presenting it again tears against the free-running DPI scanout (see
the Qualia board config).
* MicroPython's ``dotclockframebuffer.DotClockFramebuffer`` uses double
panel buffers with ``auto_refresh=False``: nothing reaches the panel
until ``refresh()`` promotes the back buffer.
`DisplayDriver` defaults this to ``False``, which is right for the first
and wrong for the second — so without LVGL, every MicroPython program had
to call ``show()`` itself, and forgetting looked exactly like dead
hardware. The driver already knows which case it is: this is the same
test `show` makes before presenting, asked once rather than left to
the caller.
"""
disp = self._display
if disp is not None:
return not getattr(disp, "auto_refresh", False)
return not getattr(self._raw_buffer, "auto_refresh", False)
def __init__(
self,
buffer,
width=None,
height=None,
reverse_bytes_in_word=False,
*,
bitmap=None,
display=None,
quiet=False,
):
self._raw_buffer = buffer
mv = memoryview(buffer)
self._width = width if width else buffer.width
self._height = height if height else buffer.height
self._requires_byteswap = reverse_bytes_in_word
self._rotation = 0
self.color_depth = 16
self._bitmap = bitmap
self._display = display
self._bitmaptools = None
if bitmap is not None:
try:
import bitmaptools as _bt
self._bitmaptools = _bt
except ImportError:
self._bitmap = None
# Native framebuffers may expose RGB565 as bytes ('B') or uint16 ('H').
# DotClockFramebuffer on CircuitPython is uint16-indexed (len == pixels);
# painting through that view is a Python per-pixel loop (~12s for 720x720).
# Prefer a byte view so blit/fill can use bulk memoryview assigns when no
# displayio.Bitmap is provided.
pix = self._width * self._height
self._buffer_u16 = len(mv) == pix
self._buffer = mv
self._pixel_bytes = mv
if self._buffer_u16:
try:
self._pixel_bytes = mv.cast("B")
except (AttributeError, TypeError, ValueError):
# No cast: fall back to slow uint16 element stores in blit/fill.
self._pixel_bytes = None
super().__init__(quiet=quiet)
[docs]
def framebuffers(self):
"""Panel scanout buffer(s) for direct GUI rendering.
Returns ``(buf1, buf2_or_None, nbytes, stride_bytes)``.
Prefers native dual FBs from ``dotclockframebuffer.DotClockFramebuffer.framebuffers``
when present; otherwise a single ``memoryview`` of the raw buffer
(e.g. mipidsi).
"""
raw = self._raw_buffer
bpp = max(1, int(self.color_depth) // 8)
stride = getattr(raw, "row_stride", None)
stride = int(self._width) * bpp if stride is None else int(stride)
fbs = getattr(raw, "framebuffers", None)
if callable(fbs):
try:
fbs = fbs()
except Exception:
fbs = None
if fbs is not None:
try:
n = len(fbs)
except TypeError:
n = 0
if n >= 2:
b0, b1 = fbs[0], fbs[1]
return b0, b1, len(memoryview(b0)), stride
if n == 1:
b0 = fbs[0]
return b0, None, len(memoryview(b0)), stride
# The length is in bytes: a uint16 view (DotClockFramebuffer on
# CircuitPython) has half as many elements.
if self._buffer_u16 and self._pixel_bytes is not None:
return self._pixel_bytes, None, len(self._pixel_bytes), stride
mv = memoryview(raw)
return mv, None, len(mv) * (2 if self._buffer_u16 else 1), stride
############### Required API Methods ################
[docs]
def init(self) -> None:
"""
Initializes the display instance. Called by __init__ and rotation setter.
"""
[docs]
def fill_rect(self, x, y, w, h, c):
"""
Fills a rectangle with the given color.
Args:
x (int): The x-coordinate of the top-left corner of the rectangle.
y (int): The y-coordinate of the top-left corner of the rectangle.
w (int): The width of the rectangle.
h (int): The height of the rectangle.
c (int): The color to fill the rectangle with.
Returns:
(tuple): A tuple containing the x, y, w, h values
"""
color = c & 0xFFFF
bt = self._bitmaptools
if bt is not None and self._bitmap is not None:
# C fill into PSRAM Bitmap (Adafruit Qualia path).
if self._auto_byteswap:
color = ((color & 0xFF) << 8) | (color >> 8)
bt.fill_region(self._bitmap, x, y, x + w, y + h, color)
return (x, y, w, h)
# Native FB fill (dotclockframebuffer.DotClockFramebuffer on ESP32-S3): Python band assigns into
# PSRAM are hundreds of ms for 720x720; C fill is a few ms.
native_fill = getattr(self._raw_buffer, "fill_rect", None)
if native_fill is not None:
if self._auto_byteswap:
color = ((color & 0xFF) << 8) | (color >> 8)
native_fill(x, y, w, h, color)
return (x, y, w, h)
# Native FB blit: the ESP32-P4's mipidsi Display exposes ``blit`` but no
# ``fill_rect``, so without this a fill falls through to per-row
# memoryview assigns into SPIRAM. Measured on the P4 Touch-LCD-4B, a
# 100x100 fill took 1.387 s that way and 950 us through ``blit`` — the
# same ratio blit_rect already documents for LVGL partials. Bands keep
# the temporary bounded: a full 720x720 frame would be ~1 MB.
native_blit = getattr(self._raw_buffer, "blit", None)
if native_blit is not None and w > 0 and h > 0:
if self._auto_byteswap:
cbytes = color.to_bytes(2, "big")
else:
cbytes = color.to_bytes(2, "little")
band_rows = max(1, min(h, 8192 // w))
band = cbytes * (w * band_rows)
y0, left = y, h
while left:
rows = band_rows if left >= band_rows else left
if rows != band_rows:
band = cbytes * (w * rows)
native_blit(band, x, y0, w, rows)
y0 += rows
left -= rows
return (x, y, w, h)
dest = self._pixel_bytes
if dest is None:
# uint16 buffer without byte cast — last-resort element stores.
if self._auto_byteswap:
color = ((color & 0xFF) << 8) | (color >> 8)
buf = self._buffer
for _y in range(y, y + h):
begin = _y * self.width + x
end = begin + w
for i in range(begin, end):
buf[i] = color
return (x, y, w, h)
BPP = self.color_depth // 8
if self._auto_byteswap:
color_bytes = color.to_bytes(2, "big")
else:
color_bytes = color.to_bytes(2, "little")
# Full-width: contiguous band assigns. A single ``color_bytes * (w*h)`` for
# 720x720 is ~1MB and can OOM on CircuitPython; chunked bands stay small
# while avoiding per-row slice assigns (~60ms/row into DotClockFramebuffer).
if x == 0 and w == self.width:
band_rows = min(h, 48)
block = color_bytes * (w * band_rows)
y0 = y
left = h
while left:
rows = band_rows if left >= band_rows else left
if rows != band_rows:
block = color_bytes * (w * rows)
begin = y0 * self.width * BPP
dest[begin : begin + len(block)] = block
y0 += rows
left -= rows
return (x, y, w, h)
rowbytes = color_bytes * w
for _y in range(y, y + h):
begin = (_y * self.width + x) * BPP
end = begin + w * BPP
dest[begin:end] = rowbytes
return (x, y, w, h)
[docs]
def blit_rect(self, buf, x, y, w, h):
"""
Blits a buffer to the display at the given coordinates.
Args:
buf (memoryview): The buffer to blit.
x (int): The x-coordinate of the buffer.
y (int): The y-coordinate of the buffer.
w (int): The width of the buffer.
h (int): The height of the buffer.
Returns:
(tuple): A tuple containing the x, y, w, h values.
"""
if self._auto_byteswap:
self.byteswap(buf)
BPP = self.color_depth // 8
if x < 0 or y < 0 or x + w > self.width or y + h > self.height:
raise ValueError("The provided x, y, w, h values are out of range")
if len(buf) != w * h * BPP:
raise ValueError("The source buffer is not the correct size")
bt = self._bitmaptools
if bt is not None and self._bitmap is not None:
# C arrayblit into PSRAM Bitmap — same idea as Adafruit's Qualia demos
# (paint Bitmap; FramebufferDisplay composites into DotClock PSRAM).
bt.arrayblit(self._bitmap, _as_u16_pixels(buf), x, y, x + w, y + h)
return (x, y, w, h)
dest = self._pixel_bytes
if dest is None:
# Source is byte-packed RGB565; dest buffer is uint16 elements.
src = memoryview(buf)
for row in range(h):
for col in range(w):
i = (row * w + col) * 2
color = src[i] | (src[i + 1] << 8)
self._buffer[(y + row) * self.width + x + col] = color
return (x, y, w, h)
# Native FB blit (mipidsi on ESP32-P4): Python memoryview row slices into
# SPIRAM are ~25ms/row; C memcpy is sub-millisecond for LVGL partials.
native_blit = getattr(self._raw_buffer, "blit", None)
if native_blit is not None:
native_blit(buf, x, y, w, h)
return (x, y, w, h)
# Contiguous copy for full-width strips (and full frames). Per-row
# memoryview slice assigns into some native FBs (e.g. mipidsi on
# ESP32-P4 720x720) are ~28ms/row — a height/10 LVGL partial was ~2s.
if x == 0 and w == self.width:
begin = y * self.width * BPP
dest[begin : begin + h * self.width * BPP] = buf
return (x, y, w, h)
for row in range(h):
source_begin = row * w * BPP
source_end = source_begin + w * BPP
dest_begin = ((y + row) * self.width + x) * BPP
dest_end = dest_begin + w * BPP
dest[dest_begin:dest_end] = buf[source_begin:source_end]
return (x, y, w, h)
[docs]
def pixel(self, x, y, c):
"""
Sets the color of the pixel at the given coordinates.
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 values.
"""
return self.fill_rect(x, y, 1, 1, c)
############### Optional API Methods ################
[docs]
def show(self, _timer=None) -> None:
"""
Refreshes the display.
Present the frame. Drivers with ``auto_refresh=True`` (CP Qualia
``FramebufferDisplay``) already composite into the scanned buffer —
skip here. MicroPython ``dotclockframebuffer.DotClockFramebuffer`` uses double panel FBs
with ``auto_refresh=False``, so ``show()`` must call ``refresh()`` to
promote the back buffer (LVGL wires this as ``refresh_cb``).
"""
disp = self._display
if disp is not None:
if getattr(disp, "auto_refresh", False):
return
try:
disp.refresh()
return
except TypeError:
try:
disp.refresh(None, None)
return
except Exception:
pass
raw = self._raw_buffer
if getattr(raw, "auto_refresh", False):
return
raw.refresh()
[docs]
def show_nowait(self):
"""Start presenting the frame and return without waiting for it.
On a double-buffered native framebuffer that can split its present
(MicroPython ``DotClockFramebuffer`` with ``present()``/``wait()``),
this promotes the back buffer and returns at once; call
`wait_shown` before painting the framebuffers again. Elsewhere
it is `show`.
Returns:
bool: ``True`` when a present is pending and `wait_shown`
must follow, ``False`` when the frame is already out.
"""
raw = self._raw_buffer
present = getattr(raw, "present", None)
if (
self._display is None
and present is not None
and getattr(raw, "wait", None) is not None
and not getattr(raw, "auto_refresh", False)
):
present()
frame_done = getattr(self, "frame_done", None)
if frame_done is not None:
frame_done() # one frame for measure_fps, as show() would be
return True
self.show()
return False
[docs]
def wait_shown(self):
"""Return once the frame `show_nowait` started is on screen.
Does nothing when no present is pending.
"""
wait = getattr(self._raw_buffer, "wait", None)
if wait is not None:
wait()
[docs]
def flush_rect(self, x, y, w, h):
"""Make a directly-painted native framebuffer region visible.
Returns ``True`` when the native framebuffer can cache-sync the dirty
rows without a full-frame refresh/present, otherwise ``False``.
"""
refresh_rect = getattr(self._raw_buffer, "refresh_rect", None)
if refresh_rect is None:
return False
refresh_rect(x, y, w, h)
return True