Display Backends

PyHMI uses a pluggable backend architecture. The same UI description (PyHML) runs across all platforms. The backend determines how pixels reach the display and how input is captured.

Framebuffer Backend

The framebuffer backend renders directly to the Linux framebuffer device. No X11, Wayland, or graphical desktop environment is required.

Setup

from pyhmi import Application

app = Application(
    backend="fb",
    device="/dev/fb0",
    color_format="rgb565",  # or "rgb888", "grayscale"
)
app.load_scene("main.pyhml")
app.run()

Configuration

Requirements

• Linux kernel with framebuffer support (CONFIG_FB)
• Write access to /dev/fb0 (run as root or add user to video group)
• Python 3.7+

Performance

Target: 30 FPS on Raspberry Pi 3. Double buffering reduces tearing. Partial updates supported for efficiency.

SPI / LCD Backend

The SPI backend renders to LCD displays connected via SPI bus. Designed for CircuitPython 9+ on microcontrollers.

Supported Displays

Setup

import displayio
import board
from pyhmi import Application

displayio.release_displays()
display = displayio.Display(
    board.SCK, board.MOSI,
    data_command=board.D9,
    reset=board.D10,
)

app = Application(
    backend="spi",
    display=display,
    color_format="rgb565",
)
app.load_scene("main.pyhml")
app.run()

Requirements

• CircuitPython 9.0+
• Compatible SPI LCD display
• displayio protocol support
• <500 KB RAM available

Performance

Target: 15 FPS on Raspberry Pi Pico W with 240x240 display. Partial updates reduce SPI bandwidth. Use rgb565 for best performance.

SDL2 Emulation Backend

The SDL2 backend renders to a window using the SDL2 library. This is the primary development and testing backend, running on macOS, Linux, and Windows.

Setup

from pyhmi import Application

app = Application(
    backend="sdl2",
    width=320,
    height=240,
    title="PyHMI Demo",
    scale=2,  # Window scale factor
)
app.load_scene("main.pyhml")
app.run()

Configuration

Installation

# Install with SDL2 backend
pip install pyhmi[sdl2]

# Or install SDL2 system library first:
# macOS:  brew install sdl2
# Linux:  sudo apt install libsdl2-2.0-0
# Windows: included in wheel

Input

The SDL2 backend captures keyboard and mouse input natively. Touch input is simulated via mouse events. Use scale to enlarge the window for comfortable interaction.

Performance

Target: 60 FPS on desktop. The SDL2 backend is the fastest backend, suitable for performance testing and animation verification.

Input Backends

Input handling is also pluggable. Each display backend pairs with an appropriate input backend:

Backend Selection Guide