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 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.

Parameters:

size (int) – The size of the buffer to create.

Returns:

(memoryview) – The new buffer.

displaydev.color565(r, g=None, b=None)[source]

Convert RGB values to a 16-bit color value.

Parameters:
  • 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

displaydev.color565_swapped(r, g=0, b=0)[source]

Convert RGB to 16-bit RGB565 with byte order swapped for some displays.

Parameters:
  • 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.

displaydev.color332(r, g, b)[source]

Convert RGB to 8-bit RGB332 color.

Parameters:
  • r (int) – Red (0-255).

  • g (int) – Green (0-255).

  • b (int) – Blue (0-255).

Returns:

int – RGB332 color byte.

displaydev.color_rgb(color)[source]

Expand a display color to an (r, g, b) tuple.

Parameters:

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).

class displaydev.FrameClock(period_ms, name=None)[source]

Bases: object

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.

class displaydev.DisplayDriver(*, quiet=False)[source]

Bases: object

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).

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 a multimer timer at refresh_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.

scroll(dx, dy)[source]

Scroll the display.

Parameters:
  • dx (int) – The number of pixels to scroll horizontally.

  • dy (int) – The number of pixels to scroll vertically.

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:
  • 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.

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.

Parameters:
  • tfa (int) – The top fixed area.

  • bfa (int) – The bottom fixed area.

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 value pixels 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 vscroll position.

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_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.

frame_done()[source]

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.

fps()[source]

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.

fps_reset()[source]

Start a fresh measurement (does nothing when not measuring).

fps_print(seconds=5)[source]

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.

vscrdef(tfa, vsa, bfa)[source]

Set the vertical scroll definition. Should be overridden by the subclass and called as super().vscrdef(tfa, vsa, bfa).

Parameters:
  • tfa (int) – The top fixed area.

  • vsa (int) – The vertical scroll area.

  • bfa (int) – The bottom fixed area.

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.

reset()[source]

Perform a reset of the display. Should be overridden by the subclass.

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_config stops the timer on quit via app.stop_timer.

quit(code=0, force=False)[source]

Release display resources (REPL-safe unless force=True). Called on QUIT.

force_quit(code=0)[source]

Release resources then exit the process (alias for quit(code, force=True)).

show(*args, **kwargs)[source]

Show the display. Base class method does nothing. May be overridden by subclasses.