displaydev
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.
- displaydev.byteswap(buf)
Swap a 16-bit pixel buffer in place using numpy or ulab.
- displaydev.capabilities()[source]
Static metadata for the modular displaydev install model (no backend imports).
- displaydev.alloc_buffer(size)[source]
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 normalbytearray(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, preferdisplayio.Bitmap(seeFBDisplay(..., bitmap=...)) so paints go through Cbitmaptoolsinto PSRAM rather than Python loops.
- Parameters:
size (int) – The size of the buffer to create.
- Returns:
(memoryview) – The new buffer.
- displaydev.color565_swapped(r, g=0, b=0)[source]
Convert RGB to 16-bit RGB565 with byte order swapped for some displays.
- class displaydev.FrameClock(period_ms, name=None)[source]
Bases:
objectA display’s frame cadence as a subscription:
subscribe(fn)callsfn()once per frame, on the main thread, frommultimer.period_msis the frame period the backend knows about;countandlast(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/_stopto deliver from that signal instead of a timer.
- class displaydev.DisplayDriver(*, quiet=False)[source]
Bases:
objectBase 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 fromboard_config.displayrather than instantiating this class directly.Periodic presentation when needed is driven by
appdev.App(seeneeds_refresh).share_framebuffer: when True, a GUI may bind the panel scanout buffer(s) fromframebuffersfor direct rendering (e.g. LVGLDISPLAY_RENDER_MODE.DIRECT). Default False — desktop/bus drivers keep their own draw buffers.Frame rate:
measure_fps(orOMNIPYTHON_FPS=1) counts frames and times presents;fpsreads them. Off by default, and nothing is wrapped or timed while it is off.can_rotate: whether settingrotationturns what you draw. When it’s False,rotationonly swapswidthandheight, 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).- property frame_clock
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 amultimertimer atrefresh_period_ms.
- framebuffers()[source]
Return panel buffers for direct GUI paint, or
None.When sharing is supported, returns
(buf1, buf2_or_None, nbytes, stride_bytes).
- property width
The width of the display in pixels.
- property height
The height of the display in pixels.
- property rotation
The rotation of the display.
- property touch_device
The touch device.
- fill(color)[source]
Fill the display with a color.
- Parameters:
color (int) – The color to fill the display with.
- disable_auto_byteswap(value)[source]
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
- Parameters:
value (bool) – Whether to disable byte swapping.
- Returns:
(bool) – Whether byte swapping was disabled successfully.
- property requires_byteswap
Whether the display requires byte swapping.
- blit_transparent(buf, x, y, w, h, key)[source]
Blit a buffer with transparency.
- Parameters:
- Returns:
(tuple) – The x, y, w, h coordinates of the blitted area.
- property vscroll
The vertical scroll position relative to the top fixed area.
- Returns:
(int): The vertical scroll position.
- set_vscroll(tfa=0, bfa=0)[source]
Set the vertical scroll definition and move the vertical scroll to the top.
- property tfa
The top fixed area set by set_vscroll or vscrdef.
- Returns:
(int): The top fixed area.
- property vsa
The vertical scroll area set by set_vscroll or vscrdef.
- Returns:
(int): The vertical scroll area.
- property bfa
The bottom fixed area set by set_vscroll or vscrdef.
- Returns:
(int): The bottom fixed area.
- translate_point(point)[source]
Translate a point from real coordinates to scrolled coordinates.
Useful for touch events.
- Parameters:
point (tuple) – The x and y coordinates to translate.
- Returns:
(tuple) – The translated x and y coordinates.
- scroll_by(value)[source]
Scroll vertically by
valuepixels relative to the current offset.- Parameters:
value – Signed pixel delta applied to
vscroll.
- scroll_to(value)[source]
Set the absolute vertical scroll offset.
- Parameters:
value – New
vscrollposition.
- property tfa_area
Top fixed area for vertical scrolling.
- Returns:
tuple[int, int, int, int]:
(x, y, width, height)of the top fixed band.
- property vsa_area
The vertical scroll area as an Area object.
- Returns:
(tuple): The vertical scroll area.
- property bfa_area
The bottom fixed area as an Area object.
- Returns:
(tuple): The bottom fixed area.
- measure_fps(on=True)[source]
Count frames and time presents (
on=True), or stop (on=False).Switched on, the instance’s
show,flush_rectandblit_rectare wrapped with timers; switched off they are the class’s own methods again. A frame is oneshow(), or oneframe_donefrom a GUI that presents withflush_rect(LVGL on a direct-framebuffer panel).flush_rectandblit_rectcalls (a partial-render panel presents throughblit_rect) are counted asflushesandpixels, not frames; one that calls the other is counted once.OMNIPYTHON_FPS=1switches it on when the driver starts.- Returns:
bool – Whether it is measuring now.
- frame_done()[source]
A GUI that presents with
flush_rectsays a frame’s last area is done.display_drivercalls this on a direct-framebuffer panel when the last area was presented byflush_rectand noshow()followed. Does nothing unlessmeasure_fpsis on.
- fps()[source]
The frame rate and present times, or
Nonewhen not measuring.Returns a dict:
fps(the last whole second),avg_fps(sincemeasure_fpsorfps_reset),frames,seconds,present_ms/present_ms_max(mean and worst time presenting a frame, itsflush_rectcalls included),busy(the share of wall time spent presenting: high means the display is the bottleneck, low means the app is),flushesandpixels.
- fps_print(seconds=5)[source]
Print a one-line summary every
seconds;0stops it.Switches
measure_fpson. 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=Nstarts it when the driver starts.
- vscrdef(tfa, vsa, bfa)[source]
Set the vertical scroll definition. Should be overridden by the subclass and called as super().vscrdef(tfa, vsa, bfa).
- vscsad(vssa=None)[source]
Set or get the vertical scroll start address. Should be overridden by the subclass and called as super().vscsad(y).
- Parameters:
vssa (int) – The vertical scroll start address.
- Returns:
(int) – The vertical scroll start address.
- property power
The power state of the display.
- property brightness
The brightness of the display.
- invert_colors(value)[source]
Invert the colors of the display. Should be overridden by the subclass.
- Parameters:
value (bool) – True to invert the colors, False to restore the colors.
- hard_reset()[source]
Perform a hardware reset of the display. Should be overridden by the subclass.
- soft_reset()[source]
Perform a software reset of the display. Should be overridden by the subclass.
- sleep_mode(value)[source]
Set the sleep mode of the display. Should be overridden by the subclass.
- Parameters:
value (bool) – True to enter sleep mode, False to exit sleep mode.
- deinit()[source]
Run subclass cleanup. Idempotent.
The broker owns the shared refresh timer, so there is no display-owned timer to stop here;
board_configstops the timer on quit viaapp.stop_timer.
- quit(code=0, force=False)[source]
Release display resources (REPL-safe unless
force=True). Called on QUIT.