Introduction

Info

Blinka makes her debut on the big screen! With this library you can use CircuitPython displayio code on PC and Raspberry Pi to output to a PyGame window instead of a hardware display connected to I2C or SPI. This makes it easy to to use displayio elements on HDMI and other large format screens.

Warning: you must check display.check_quit() in the main loop and break if it's true in order to correctly handle the close button!

Auto Refresh

Auto refresh works differently for this library than for native CircuitPython implementations due to technical limitations of Pygame.

Pygame does not support updating the UI and refreshing the display from a background thread but this is how CircuitPython implements it. To work around this limitation, the library tells the main thread to refresh the display on the next occasion. This happens whenever you call display.check_quit().

To keep your UI responsive, make sure to

• call display.check_quit() on a regular basis
• do lengthy processing (e.g. fetching data from the net) in a separate thread. This thread should only update data, but not any UI elements (e.g. labels).

If you disable auto-refresh, the display will still refresh on certain externally triggered events from the window-manager of your OS. This includes events like maximizing a window, moving it, uncovering it and so on. Failing to react to these events might make the window-manager angry and you will be asked what to do with the unresponsive window.

Dependencies

This driver depends on:

• PyGame
• Adafruit Blinka Displayio
• numpy

Please ensure all dependencies are available they can be installed with pip3

Optional Dependencies

This driver can optionally make use of these displayio module libraries:

• Adafruit Display Text
• Adafruit ImageLoad
• Adafruit Progress Bar
• Adafruit Display Button

They can be installed with pip3.

Installing from PyPI

On supported GNU/Linux systems like the Raspberry Pi, you can install the driver locally from PyPI. To install for current user:

pip3 install blinka-displayio-pygamedisplay

To install system-wide (this may be required in some cases):

sudo pip3 install blinka-displayio-pygamedisplay

To install in a virtual environment in your current project:

mkdir project-name && cd project-name
python3 -m venv .env
source .env/bin/activate
pip3 install blinka-displayio-pygamedisplay

Usage Example

import displayio
from blinka_displayio_pygamedisplay import PyGameDisplay

display = PyGameDisplay(width=320, height=240)
splash = displayio.Group()
display.show(splash)

color_bitmap = displayio.Bitmap(display.width, display.height, 1)
color_palette = displayio.Palette(1)
color_palette[0] = 0x00FF00  # Bright Green

bg_sprite = displayio.TileGrid(color_bitmap, pixel_shader=color_palette, x=0, y=0)
splash.append(bg_sprite)

while True:
    if display.check_quit():
        break

Initialization Parameters

• width (required) - The width of the window. A value of zero maximizes the window
• height (required) - The height of the window. A value of zero maximizes the window
• icon (optional) - An icon for the PyGame window
• caption (optional) - A caption for the PyGame window
• native_frames_per_second (optional) - High values result in high CPU load
• hw_accel (optional) - Whether to use hardware acceleration. Default is True
• flags (optional) - Pygame display flags, e.g. pygame.FULLSCREEN or pygame.NOFRAME

If you encounter GL or EGL Pygame errors, try setting hw_accel to False to disable hardware acceleration. Performance may be reduced.

Contributing

Contributions are welcome! Please read our Code of Conduct before contributing to help this project stay welcoming.

Documentation

For information on building library documentation, please check out this guide.