Code Recipes

Below are a few code recipes for pygame, Pillow, Pycairo, and plain NumPy to get you started. If you're unsure how to install this library, check out the installation section.

pygame Example

First install pygame,

pip install pygame

Then run this program,

pygame_test.py

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)

Pillow Example

NumPy Required

For this example to work correctly, ensure you've installed NumPy. The easiest way to do that with pip is: pip install dispmanx[numpy]

First install Pillow,

pip install Pillow

Then run this program,

pillow_test.py

import time
from random import randint
import numpy
from PIL import Image, ImageDraw
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", buffer_type="numpy")
image = Image.new(mode=display.pixel_format, size=display.size)
draw = ImageDraw.Draw(image)

for _ in range(20):
    draw.rectangle(((0, 0), (image.size)), fill=random_color_with_alpha())
    numpy.copyto(display.buffer, image)
    display.update()
    time.sleep(0.5)

A Note About Performance

This example includes copying an RGBA array of pixels from a Pillow rendering, rather than editing an array in-place like the other examples. This is inherently slow, so you're not going to get as high frame rates as in the pygame example.

If you know a way to do in-place modification of numpy arrays with Pillow, let me know by filing a GitHub issue!

Pycairo Example

First install Pycairo,

pip install pycairo

Then run this program,

pycairo_test.py

from random import uniform
import time
from cairo import ImageSurface, FORMAT_RGB24, Context
from dispmanx import DispmanX

def random_color():
    return tuple(uniform(0, 1) for _ in range(3))

display = DispmanX(pixel_format="RGBX")
width, height = display.size
surface = ImageSurface.create_for_data(display.buffer, FORMAT_RGB24, width, height)
context = Context(surface)

for _ in range(20):
    context.set_source_rgba(*random_color())
    context.rectangle(0, 0, display.width - 1, display.height - 1)
    context.fill()
    display.update()
    time.sleep(0.5)

NumPy Example

All you need is NumPy for this one. First, install it,

pip install numpy

Then run this program to create a fake static effect,

numpy_static.py

import time
import numpy
from dispmanx import DispmanX

import numpy

display = DispmanX(pixel_format="RGB565", buffer_type="numpy")
high = numpy.iinfo(display.buffer.dtype).max + 1  # white pixel
rng = numpy.random.default_rng()

while True:
    static = rng.integers(low=0, high=high, size=display.buffer.shape, dtype=display.buffer.dtype)
    numpy.copyto(display.buffer, static)  # Simulates TV static
    display.update()
    time.sleep(0.0135)

What's Next?

Now that you're an expert, check out the API documentation.