Display backend internals
This document explains how gallery display drivers relate to each other: the shared 565 API contract, the two-stage draw/present model used by desktop and browser simulators, color conversion strategies, and why each backend chose its implementation pattern.
For a shorter “which driver do I pick?” guide, see Displays. For chip wiring and board configs, see Board configs and Display drivers.
The DisplayDriver API contract
Application and example code assume a 16-bit RGB565 surface:
display_drv.color_depth == 16(bits per pixel)Color literals like
0xFFFF,0xF800, and helpers likecolor565(r, g, b)Scratch buffers:
FrameBuffer(..., RGB565)andBPP = display_drv.color_depth // 8(2 bytes per pixel)blit_rectsource buffers sizedw * h * 2blit_transparentkey colors as 2-byte 565 values
Every concrete backend must implement the drawing and lifecycle methods
below. Application code, pygraphics, and examples assume they exist — not only
show() and quit():
Method |
Role |
|---|---|
|
Copy a 565 buffer region into the driver’s logical framebuffer |
|
Fill a rectangle with a 565 color |
|
Set one pixel (often implemented via a 1×1 |
|
Present the logical framebuffer (immediate on MCU buses; batched on SDL/pygame until |
|
Release native resources; |
Optional but common: deinit() (called from quit()), scroll helpers (vscroll,
set_vscroll), blit_transparent, and needs_refresh for app-driven
presentation on hosted backends.
BusDisplay, FBDisplay, and most TFT paths are 565 end-to-end — the API matches the hardware framebuffer.
Other backends store pixels in a deeper native format (RGB888 strip buffer,
PIL RGB, canvas RGBA, SDL texture at 24/32 bpp). They still expose the 565
API and convert at draw time via color_rgb (or backend-specific blit paths).
Color encoding trap
565 and 888 use different integer layouts:
Meaning |
RGB565 int |
RGB888 int |
|---|---|---|
White |
|
|
Red |
|
|
RGB888 unpack (used by PixelFramebuffer and pygraphics.RGB888) treats the int
as 0xRRGGBB. Passing 0xFFFF (565 white) through that path yields cyan
(R=0, G=255, B=255), not white.
The shared expand helper is color_rgb() in displaydev/__init__.py: 565
int or 2-byte little-endian slice → (r, g, b) with 5/6/5 bit expansion. Tests
live in tests/test_color.py.
Two-stage architecture: logical GRAM + present
Five simulators — SDLDisplay, PGDisplay, WinDisplay, PSDisplay, JNDisplay — mimic an ILI9341-style panel:
App draw API Present path
───────────── ──────────────
fill_rect / blit_rect → self._buffer (logical GRAM)
render() (scroll bands, scale, …)
show() (flip / widget / canvas)
self._buffer— offscreen memory at logicalwidth × height(PG calls this “the LCD’s internal memory”).Draw methods — write only into that buffer.
render()— composes the buffer to the visible surface, including vertical scroll (top fixed / scroll area / bottom fixed).show()— pushes frames to the OS window, browser canvas, or Jupyter widget.
Scroll emulation requires this split: you cannot draw directly on the window
and still implement vscroll / set_vscroll correctly. See
pydevices_demo for the redraw-at-vscroll=0
rule.
PixelDisplay is different: there is no ILI9341 scroll model. Drawing updates
an RGB888 grid buffer; show() diff-flushes to the LED strip.
Rotation
Backend |
Buffer rotation |
|---|---|
SDLDisplay |
|
PGDisplay |
|
PSDisplay |
|
JNDisplay |
Same as PS — property only, no pixel rotation |
PixelDisplay |
|
FBDisplay |
|
A driver says whether rotation turns what you draw in can_rotate. It’s
False on FBDisplay and PixelDisplay, where a rotation swaps width
and height over a buffer that keeps the panel’s layout, so drawing at the
swapped size runs out of range. A program that wants landscape checks it
before rotating, and keeps the panel’s own orientation when it’s False.
LVGL turns its frames itself on those boards, through the display’s
lvgl_rotation.
Full rotation matters for SDL/PG desktop LCD simulation. Browser and notebook backends document that rotation reshapes the surface but does not rotate pointer coordinates — see Displays — Browser / notebook.
Scaling
Backend |
Mechanism |
|---|---|
PGDisplay |
Constructor |
SDLDisplay |
Window size |
PSDisplay |
CSS layout vs canvas pixel size; |
JNDisplay |
1:1 ( |
PixelDisplay |
N/A (tiny physical grid) |
Why each backend exists (interpreter)
Backend |
Typical interpreter |
Why it exists |
|---|---|---|
SDLDisplay |
CPython, MicroPython Unix, CircuitPython Unix |
Native SDL2 / |
WinDisplay |
Windows CPython |
Native HWND via |
PGDisplay |
CPython desktop |
Easier install on Windows; avoids some SDL glitches on Chromebooks; fallback after |
PSDisplay |
PyScript |
HTML Canvas 2D; no SDL/pygame in the browser |
JNDisplay |
Jupyter |
|
PixelDisplay |
MCU / CP |
NeoPixel / DotStar grids via |
CircuitPython Unix SDLDisplay forces software rendering when accelerated
GL cannot attach rotated render targets (see comment in sdldisplay.py).
MicroPython SDL show() may defer present on MemoryError when the heap is
locked during scroll rendering.
Color conversion toolbox
Backends use several patterns to map 565 API input to native storage:
Pattern |
Where |
Description |
|---|---|---|
Bitwise expand |
|
Per-color 565 → |
One JavaScript call |
PSDisplay, WorkerDisplay |
The whole RGB565 buffer goes to JavaScript once and is expanded to RGBA there for |
Python pixel loop |
PGDisplay blit, JNDisplay blit |
Per pixel: read 2 bytes → |
Zero-copy passthrough |
SDLDisplay at 16 bpp |
|
Raw 565 pack |
BusDisplay, FBDisplay |
|
Not yet centralized in displaydev, but useful for future shared helpers:
frombuffer+ blit (Pygame) —pg.image.frombuffer(buf, (w,h), "RGB565")thendest.blit(src, (x,y))for 16-in / 16-stored without a Python loopRow expand — convert one row of 565 to RGB/RGBA, bulk-write
Component mini-LUTs — small 5/6/5-bit tables (~128 bytes) instead of 256 KB
Per-backend blit strategy (today)
Backend |
Native sink |
Blit path |
Rationale |
|---|---|---|---|
SDLDisplay (16) |
RGB565 texture |
Zero-copy upload |
Throughput on large blits; matches app buffers |
SDLDisplay fill |
Same texture |
|
Draw API expects 8-bit RGB |
PGDisplay |
Pygame surface (default 16) |
Per-pixel |
Simple; partial |
PSDisplay, WorkerDisplay |
Canvas RGBA |
One JS call → |
Browser API requires RGBA bytes; the bridge is the cost, so cross it once |
JNDisplay |
PIL RGB |
Loop → |
Present is PNG-bound; blit speed secondary |
PixelDisplay |
RGB888 strip buf |
565 in → |
Tiny grids; standard DisplayDriver API |
SDL vs Pygame “fast path”
SDL at color_depth=16 is true 16-in / 16-stored for blits: the app’s
565 buffer is uploaded directly into a RGB565 render-target texture.
Pygame can match that intent (not the same mechanism) by keeping a 16-bit
surface and using frombuffer + blit once per blit_rect call instead of
set_at per pixel. The current PG implementation still expands each pixel to
RGB for set_at, which quantizes back to 565 on a 16-bit surface — correct but
slow at 320×480.
LUT size and MCUs
PSDisplay and WorkerDisplay keep no lookup table: the RGB565 buffer is expanded to RGBA in JavaScript, so no 256 KB table (65536 × 4 bytes) has to sit in Python memory.
For PixelDisplay (8×4, 12×6, …), a color_rgb loop over tens or hundreds
of pixels is negligible. A full 565→888 LUT (~192 KB for 3-byte entries) would
cost more RAM than the grid itself.
PixelDisplay specifics
Addressable LED boards wire:
_pixel_framebuf = PixelFramebuffer(...) # internal; RGB888 grid + strip map
display_drv = PixelDisplay(_pixel_framebuf)
Use display_drv for all app drawing. _pixel_framebuf is prefixed to
discourage bypassing the DisplayDriver API (see
Board configs — Pixel configs).
PixelDisplay exposes the usual 565 DisplayDriver API (color_depth=16).
The inner PixelFramebuffer stays RGB888 for the strip; fill_rect,
pixel, and blit_rect expand via color_rgb before writing the inner buffer.
MicroPython uses displaydev.pixeldisplay.PixelFramebuffer; CircuitPython uses
Adafruit adafruit_pixel_framebuf behind the same PixelDisplay wrapper.
Hardware drivers (brief)
These follow the 565 API without a separate “present” stage in the same sense:
Class |
Storage |
Notes |
|---|---|---|
BusDisplay |
Panel GRAM via SPI/I80 |
Optional byteswap; true 565 |
FBDisplay |
CircuitPython framebuf |
RAM mirror + |
Consolidation direction
Goals for displaydev maintenance:
One API — all
DisplayDriverinstances reportcolor_depth=16and accept 565 colors and blit buffers.Shared conversion helpers in
displaydev/__init__.py—color_rgb(exists), plus swappable loop vs LUT blit writers for benchmarking, where a LUT is worth its RAM.Keep backend-specific fast paths where they matter:
SDL: zero-copy 565 blit
PS: one JavaScript call expands to RGBA
PG: consider
frombuffer+blitfor 565 surfacesPixelDisplay: loop expand (tiny grids)
Internal buffer format may remain 565 (SDL), RGB (JN), RGBA (PS), or RGB888 (strip) as long as the public contract stays 565.