Welcome to Python DispmanX←
Hello and welcome! Here's the documentation for Python DispmanX, a pure Python1 library for interacting with the Raspberry Pi's low-level video API. My hope is that you find it useful for creating all sorts of different apps, widgets, and graphical overlays for your Pi. I hope you'll have as much fun using it as I did writing it!
Quickstart←
Follow the steps below to install the DispmanX library and run your first program using this library.
Installation←
Installation
To install the DispmanX library from the Python Package Index (PyPI), type the following at the command line,
Installing From Source Recommended
Until the API stabilizes, it's recommended that you install the latest version from source, described in the "From Source With NumPy" content tab above.
pygame Example←
To get going with your first pygame program, first install the library,
Then try this out,
from random import randint
import pygame
from dispmanx import DispmanX
def random_color_with_alpha():
return tuple(randint(0, 0xFF) for _ in range(3)) + (randint(0x44, 0xFF),)
display = DispmanX(pixel_format="RGBA")
surface = pygame.image.frombuffer(display.buffer, display.size, display.pixel_format)
clock = pygame.time.Clock()
for _ in range(20):
surface.fill(random_color_with_alpha())
display.update()
clock.tick(2)
If you see a DispmanXRuntimeError: No displays found! exception
If you run into the following DispmanXRuntimeError running the code
above,
>>> from dispmanx import DispmanX
>>> display = DispmanX()
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "/home/david/python-dispmanx/dispmanx/dispmanx.py", line 205, in __init__
self._display = self.get_default_display()
File "/home/david/python-dispmanx/dispmanx/dispmanx.py", line 421, in get_default_display
raise DispmanXRuntimeError("No displays found! (Are you using the vc4-kms-v3d driver?)")
dispmanx.exceptions.DispmanXRuntimeError: No displays found! (Are you using the vc4-kms-v3d driver?)
Then you'll need to follow the instructions here to address the issue.
More examples are available on the recipes page.
Use Cases←
You may be asking why this library, when you could just pygame? Here are some potential use cases:
- Transparent iverlays
- You may want to your program to have transparent overlays. pygame and SDL do not support them by default. With this library, you can write code that does just that!2
- Running in a headless environment
- pygame using its underlying SDL library requires either X11 or fbcon drivers on the Pi. While using the X11 driver works great, it requires a full desktop environment on your Pi. Furthermore, the fbcon driver appears to no longer be supported by pygame version 2. This library allows you to use familiar pygame idioms with the Raspberry Pi's native DispmanX layer.
- Using raw NumPy arrays
- You may want to directly interact with NumPy arrays of RGBA (or RGB) pixels with arbitrary imaging tool kits like Pillow or Cairo. Some examples of using raw NumPy arrays are available on the recipes page.
My use case is retro style CRT TV hooked up to a Pi using the Pi-specific video player omxplayer complete with semi-transparent overlays for menus, "channels," and subtitles3.
What's Next?←
- Check out some code recipes that will show you how to use DispmanX with pygame, Pillow, Pycairo, and plain NumPy.
- Head over to the API documentation and read about the DispmanX class, the main entrypoint for this library.
- Read some of the additional information about this library.
-
I say "pure Python" however this library uses Python's included ctypes library to perform "foreign function calls" to
bcm_host.so— a C library included with Raspberry Pi OS to interface with the DispmanX layer directly. ↩ -
Fun fact, transparent overlays is the reason I wrote this package. ↩
-
While omxplayer does technically support subtitles, they don't seem to be working on the Raspberry Pi 4B. And besides, I wanted to render custom subtitles. ↩