[Feature Request] Support Software Frame Buffering and Manual Display Swap in Pi 5 RGB Matrix Library

[kklasmeier]

Background:

I'm developing an animation engine for a 64×64 RGB LED matrix using the Adafruit RGB Matrix Bonnet. On Raspberry Pi 4 and earlier, I rely heavily on the Henner Zeller rpi-rgb-led-matrix library, which provides precise, tear-free frame updates using SwapOnVSync() and true double-buffering.

On the Raspberry Pi 5, this library is no longer compatible due to GPIO architecture changes involving the RP1 I/O controller.

I've been evaluating the new Adafruit_Blinka_Raspberry_Pi5_Piomatter + RGB Matrix display stack, and while I understand the hardware limitations, I believe there’s a valuable opportunity to improve developer control through software-level buffering and swap control.

Current Limitation:

The current Pi 5 RGB Matrix library appears to:

Draw directly to the physical matrix display

Immediately push updates without buffering

Offer no way to draw a full frame offscreen before committing it

This results in:

Visual tearing, especially at medium to high frame rates

Lack of timing control — frame updates happen immediately

Inability to build animations with frame-to-frame consistency

No replacement for batching workflows

What Can Be Improved (Even With RP1 Limitations):

We understand that true hardware vsync or GPIO DMA swaps are not currently feasible due to:

The lack of low-level access to RP1's DMA system

GPIO abstraction on Pi 5 not supporting waveform-level control

However, the following features can be implemented entirely in software:

Proposed Features:

Offscreen Drawing Surface

Provide a retained Image, bytearray, or framebuf object where users can draw without affecting the live display.

All drawing operations would go to this buffer.

Manual Frame Commit

Add a show() or display() method to copy the offscreen buffer to the physical matrix.

This gives the user full control over when a frame is pushed.

Optional Frame Clear / Preservation

Allow clearing the offscreen buffer automatically after show(), or preserving it for incremental builds behavior.

Minimal Animation API

Reintroduce a familiar batching pattern, even if it’s simulated in Python.

This improves code portability from Pi 4 systems.

Throttle / Delay Option (Optional)

Optionally allow frame-rate limiting or timed updates to reduce tearing on fast redraws.

Sample Workflow:

# Initialize
canvas = RGBMatrix(width=64, height=64)

# Frame rendering
canvas.draw_pixel(0, 0, color)
canvas.draw_rect(...)
canvas.show()  # <-- manually push to LED matrix

This model gives developers timing control, removes flicker during draw builds, and enables frame-accurate behavior even without DMA or vsync.

Use Case Examples

Sprite-based animation engines

Games or LED visualizations with dynamic objects

Physics or particle simulations with precise layering

Matrix scripting engines (e.g., scripting languages for LED art)

Summary

This request is not for full SwapOnVSync() hardware DMA support (which we understand is not possible on the Pi 5 today), but for a software feature set that restores essential animation and batching workflows by:

Decoupling draw operations from display updates

Giving developers control over when to show frames

Allowing preservation of frame state between updates

These additions would be extremely valuable to intermediate and advanced users working with real-time animation, while still preserving the simplicity of the current Piomatter stack for beginners.

Thanks again for your hard work bringing RGB Matrix support to the Pi 5.
Happy to help test or prototype any of the above.