displaydev.fbdisplay

displaydev.fbdisplay

class displaydev.fbdisplay.FBDisplay(buffer, width=None, height=None, reverse_bytes_in_word=False, *, bitmap=None, display=None, quiet=False)[source]

Bases: DisplayDriver

A class to interface with CircuitPython FrameBuffer objects.

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

color_depth

The color depth of the display

Type:

int

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.

property share_framebuffer

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.

property needs_refresh

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.

framebuffers()[source]

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

init()[source]

Initializes the display instance. Called by __init__ and rotation setter.

fill_rect(x, y, w, h, c)[source]

Fills a rectangle with the given color.

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

blit_rect(buf, x, y, w, h)[source]

Blits a buffer to the display at the given coordinates.

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

pixel(x, y, c)[source]

Sets the color of the pixel at the given coordinates.

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

show(_timer=None)[source]

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

show_nowait()[source]

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.

wait_shown()[source]

Return once the frame show_nowait started is on screen.

Does nothing when no present is pending.

flush_rect(x, y, w, h)[source]

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.