Generic framebuffer implementation in Rust for use with embedded-graphics library

Last update: Nov 29, 2022

Related tags

Overview

Fraramebuffer implementation for Rust's Embedded-graphics

Framebuffer approach helps to deal with display flickering when you update multiple parts of the display in separate operations. Intead, with this approach, you're going to write to a in-memory display and push it all at once into your hardware display when the whole picture is drawn.

This technique is useful when you're updating large portions of screen or just simply don't want to deal with partial display updates.
The approach has been tested on TTGO (esp32) with ST7789
Explore the docs »

Rust Crate · Report Bug · Request Feature

Table of Contents

About The Project
- Built With
Getting Started
- Prerequisites
- Installation
Roadmap
License
Contact
Acknowledgments

About The Project

This library is a Rust implementation of framebuffer approach that is often used when driving hardware displays. The goal is to perform bulk-write of all the screen pixels at once, avoiding multiple individual updates that could lead to screen flickering.

This library has been designed to work with Rust's embedded-graphics library.

(back to top)

Built With

(back to top)

Getting Started

Make sure you have your rust environment configurated

Installation

Add library to your Cargo.toml

...
[dependencies]
embedded-graphics-framebuf = "0.1.0"

Use the library in you code

use embedded_graphics_framebuf::FrameBuf;
...

let mut display = st7789::ST7789::new(
    di,
    rst.into_output()?,
    // SP7789V is designed to drive 240x320 screens, even though the TTGO physical screen is smaller
    320,
    240,
);

static mut FBUFF: FrameBuf<Rgb565, 240_usize, 135_usize> = FrameBuf([[Rgb565::BLACK; 240]; 135]);
let fbuff = unsafe { &mut FBUFF };

fbuff.clear_black();
Text::new(
    &"Good luck!",
    Point::new(10, 13),
    MonoTextStyle::new(&FONT_10X20, Rgb565::WHITE.into()),
)
.draw(fbuff).unwrap();

// write to the actual display :-)
let u16_iter = fbuff
    .into_iter()
    .map(|px| px.into_storage());

// those are the offsets for my physical ST7789 display
display.set_pixels(40, 53, 240 - 1 + 40, 53 + 135, u16_iter);

Your flickering problems should be solved at this point :)

(back to top)

Roadmap

add tests
add rustdocs
CI integration with GithHub Actions
better error generation & handling

See the open issues for a full list of proposed features (and known issues).

(back to top)

License

Distributed under the MIT License. See LICENSE for more information.

(back to top)

Contact

Bernard Kobos - @bkobos - [email protected]

Project Link: https://github.com/bernii/embedded-graphics-framebuf

(back to top)

Acknowledgments

proven examlpes from adamgreid (imlplementation)
st7789 driver by almindor
super helpful embedded-graphics matrix chat

(back to top)

Comments

Framebuffer as a contiguous buffer?

The current implementation is not really friendly to DMA engines, in general, it prefers a continuous block of memory (unless you have one of those fancy 2D DMA engines). I also believe in general (not been benchmarked so, in reality, it may not be true) that a single buffer is better for performance reasons, I think you'll get double bounds checks using an array of an array, as opposed to a single buffer.

Thoughts on changing the underlying storage? Or providing a storage trait to customise the backing storage?

opened by MabezDev 5
Version 0.2.0

In case you agree to the changes in #3, #6, #8, #9, and #10, I merged them all in my fork so you don't have to do that work again. These are breaking changes, so a version update is advised. This also adds a basic CI, based on what @pyaillet had in his repository.

opened by jounathaen 3
Separated Framebuffer and underlying data storage

This enables linear memory can be used, e.g., for DMA access. Closes #4. Maybe not the best long-term solution, but a nicer one requires a new compiler feature.

opened by jounathaen 1
Reworked iterators

An iterator over pixels is often more helpful, as all displays which implement embedded_graphics can handle them better. To iterate over the raw color data, a helper function raw_data is added.

This makes #5 obsolete.

opened by jounathaen 1
Renamed FrameBufIntoIterator to FrameBufIterator

I was highly confused what an "IntoIterator" is, until I gasped that this is simply the iterator type for the framebuffer. I think FrameBufIterator is a better name.

opened by jounathaen 1
There is no boundary check when writing to the framebuf

Hi! Thank you for making embedded-graphics-framebuf.

I face a panic when using this library when writing outside of the defined dimensions.

Would you be interested in a PR adding this checks ? I'm planning to add it for my own use anyway.

opened by pyaillet 0
add ci

Hi !

Thanks for this project, I was able to use it here.

This PR adds a minimal CI workflows.

If you're interested I can create other PR with actions similar to the ones in this project

opened by pyaillet 0
Support for drawing Sprites with transparent pixels - filtering specific color

Hello. I want to open a discussion on how to add support for drawing sprites with transparent pixels.

Right now, Embedded Graphics and FrameBuf do not allow filtering out specific color (or alpha) when drawing an image. This results in always transferring all pixels. What would it take to implement an option to filter colors?

E.g., in the days of old DOS games, pink color (RGB = 255,0,255) was not transferred during blit operation, resulting in a "transparent" background of the sprite.

I made an experimental implementation, basically just copying FrameBuf code and fixing it to a specific type, Rgb565, because generic C does not have the option to check for color. And I've added one condition to match the color value, which is ignored. The implementation works. I'm curious whether it would be possible to do it generically without enforcing the Rgb565 type.

https://github.com/georgik/esp32-spooky-maze-game/pull/18/files#diff-bbfc2130868c076ad19c8df25d7e8cc8ba13539606e23ad0d0e02a2120e47c51R68

Another option would be to use the alpha channel, but that seems to be a slightly more complex operation.

I would appreciate your input @bernii @pyaillet

opened by georgik 1

Releases(v0.2.0)

v0.2.0(Sep 2, 2022)
Complete overhaul:

no-std compatible

Separated framebuffer and underlying data storage

DMA compatibility

Other minor changes

Includes major API changes!
Source code(tar.gz)
Source code(zip)