Add fill method as an efficient method to clear a displayio Bitmap

[kevinjwalters]

I've been using a 200x201 size Bitmap in CP 5.0.0. At the moment this can only be manipulated by setting individual pixels. This is taking 2.3 seconds on an Adafruit CLUE to assign 0 (the transparent colour from my pallete) to each pixel.

I thought I'd try assigning a full size zero array.array but I ran out of memory. I then tried a row by row approach using slices and got NotImplementedError: Slices not supported.

I could do with a fill() method (implemented in C) a bit like the neopixel library has, that would let me do an efficient clear.

[ladyada]

sure - please implement and submit a PR :)

[caternuson]

I've run into this before too. Would be nice to have.

Just curious - how are you currently doing your fill? It's slightly more efficient to set via straight index vs. (x, y) tuple. But neither of these totaled up to 2.3 secs.

TEST CODE

import time
import displayio

WIDTH = 200
HEIGHT = 201
COLORS = 255

bitmap = displayio.Bitmap(WIDTH, HEIGHT, COLORS)

start = time.monotonic()
for p in range(WIDTH*HEIGHT):
    bitmap[p] = 0
delta1 = time.monotonic() - start

start = time.monotonic()
for x in range(WIDTH):
    for y in range(HEIGHT):
        bitmap[x, y] = 0
delta2 = time.monotonic() - start

print(delta1, delta2)

RESULT

Press any key to enter the REPL. Use CTRL-D to reload.
Adafruit CircuitPython 5.0.0 on 2020-03-02; Adafruit CLUE nRF52840 Express with nRF52840
>>> import fill_test
1.46997 1.64404
>>> 

Still not great, but better than 2.3secs.

[kevinjwalters]

I've got more groups and stuff although I wasn't updating any other stuff. Do you know how displayio should work in that case, does it only send what's changed to the screen? At some point I also had a same size Bitmap underneath it the 200x201. [Added later] My equivalent of COLORS was 8 or 9.

I did some tests away from Bitmap and noted that for elem in a looked faster than for elem_idx in range(len(a)) but I'd already moved onto an undrawing approach in code so didn't bother timing that for Bitmap as I wanted something ideally sub 100ms. [Added later] actually, the for elem in a doesn't allow modification of the original array in Python.

[tannewt]

Displayio does it's best to minimize what areas on the screen are refreshed. In the fill example it will do intermediate refreshes of sub areas as the frame timer decides it should refresh. Bitmap tracks a single dirty rectangle between frames.

You could try turning off auto refresh when running the test for a more accurate measurement. A C implemented fill will still be faster since it can both prevent the intermediate refresh and quickly fill the underlying buffer. Bitmap's values are bitpacked to save memory so a fill operation could compute the packed form and then copy it throughout the buffer.

[Marius-450]

I've got a complete refresh on a few millisecs, but you must trade memory for speed :

>>> start = time.monotonic(); pixels = displayio.Bitmap(240,240,255);palette = displayio.Palette(255); tile_grid = displayio.TileGrid(pixels, pixel_shader=palette);group.pop();group.append(tile_grid);print(time.monotonic()-start, "secs to create and show a bitmap")
<TileGrid>
0.00708008 secs to create and show a bitmap
>>>

A fill() method for the bitmap object would still be amazing, and even more if we can pass it an offset (to fill only a row, or consecutives rows) and/or an iterable with the color values... And it open the door to manage slicing on the bitmap directly.

[kevinjwalters]

I'd tried that on a CLUE bit with a real application I ran out of memory immediately :(

The CLUE's less tight than the 32kB in the SAMD21 stuff like CPX but as soon as you bring in the clue mega-object it chews through a lot its memory:

Adafruit CircuitPython 5.0.0 on 2020-03-02; Adafruit CLUE nRF52840 Express with nRF52840
>>>
>>> import gc
>>> gc.collect() ; print(gc.mem_free())
144736
>>> from adafruit_clue import clue
>>> gc.collect() ; print(gc.mem_free())
92224

[Marius-450]

with less colors it may work too. Replace 255 value by 16, 4 or even 2, it take less memory (again a trade-off)
my comment was more a proof of concept that screen can be filled to an arbitrary (black) color in a few millisecs using CP.

[kevinjwalters]

I had a 200x201x2 (8 pixels per byte), and a 200x201x9 (2 pixels per byte) but anymore blew up even though I was no longer using the 200x201x9 one so it would have been subject to GC. One of my images is a grid so I'm going to try and use TileGrid to reduce memory usage for that if I run into more memory issues - the pattern repeats more-or-less...

Maybe there's also some hacky techniques with the OnDiskBitmap but I've not experimented with that. https://learn.adafruit.com/circuitpython-display-support-using-displayio/display-a-bitmap#ondiskbitmap-9-4 describes it as:

First, let's use OnDiskBitmap to source the bitmap image directly from flash memory storage. This is like reading the image from disk instead of loading it into memory first (we'll do that next). The trade off here is the reduced use of memory for potentially slower pixel draw times.

[kevinjwalters]

@caternuson I just did a retest with plain Bitmap. My original test was probably slower due to my use of layered Bitmaps, I have a static background one below the main one, elegant but slow.

Here's a basic 201x200 with auto refresh off:

>>> disp.auto_refresh = False
>>> bitmap = displayio.Bitmap(201, 200, 8)

>>> def fillscreen1(bmp, col_idx):
...     for x in range(201):
...         for y in range(200):
...             bmp[x, y] = col_idx

>>> def refresh_screen(disp):
...     while True:
...         ref = False
...         try:
...             ref = disp.refresh(minimum_frames_per_second=0)
...         except:
...             pass
...         if ref:
...             break

>>> t1 = monotonic_ns() ; fillscreen1(bitmap, 0) ; refresh_screen(display) ; t2 = monotonic_ns()  ; print((t2 - t1 ) / 1e9)
1.26893
>>> t1 = monotonic_ns() ; fillscreen1(bitmap, 0) ; refresh_screen(display) ; t2 = monotonic_ns()  ; print((t2 - t1 ) / 1e9)
1.27094
>>> t1 = monotonic_ns() ; fillscreen1(bitmap, 0) ; refresh_screen(display) ; t2 = monotonic_ns()  ; print((t2 - t1 ) / 1e9)
1.26594
>>> t1 = monotonic_ns() ; fillscreen1(bitmap, 1) ; refresh_screen(display) ; t2 = monotonic_ns()  ; print((t2 - t1 ) / 1e9)
1.27092
>>> t1 = monotonic_ns() ; fillscreen1(bitmap, 2) ; refresh_screen(display) ; t2 = monotonic_ns()  ; print((t2 - t1 ) / 1e9)
1.27377

As one might expect there's a boost from not using the (x,y) tuple indexing but it's far more than I would have thought. Perhaps MP/CP has a nify for loop optimisation here?

>>> def fillscreen2(bmp, col_idx):
...     for idx in range(201 * 200):
...         bmp[idx] = col_idx
...
...
...

>>> t1 = monotonic_ns() ; fillscreen2(bitmap, 0) ; refresh_screen(display) ; t2 = monotonic_ns()  ; print((t2 - t1 ) / 1e9)
0.772923
>>> t1 = monotonic_ns() ; fillscreen2(bitmap, 0) ; refresh_screen(display) ; t2 = monotonic_ns()  ; print((t2 - t1 ) / 1e9)
0.784957
>>> t1 = monotonic_ns() ; fillscreen2(bitmap, 0) ; refresh_screen(display) ; t2 = monotonic_ns()  ; print((t2 - t1 ) / 1e9)
0.776937
>>> t1 = monotonic_ns() ; fillscreen2(bitmap, 1) ; refresh_screen(display) ; t2 = monotonic_ns()  ; print((t2 - t1 ) / 1e9)
0.773914
>>> t1 = monotonic_ns() ; fillscreen2(bitmap, 2) ; refresh_screen(display) ; t2 = monotonic_ns()  ; print((t2 - t1 ) / 1e9)
0.769887
>>> t1 = monotonic_ns() ; fillscreen2(bitmap, 3) ; refresh_screen(display) ; t2 = monotonic_ns()  ; print((t2 - t1 ) / 1e9)
0.780918

[caternuson]

How can the display refresh be enabled/disabled from within bitmap?

[kevinjwalters]

@caternuson Can you elaborate on "from within bitmap" ?

I have been doing board.DISPLAY.auto_refresh = False to turn it off. I hadn't worked out a satisfactory way to do a one-off refresh or to inhibit auto for a specific task but you can see an attempt at a manual refresh in refresh_screen(). Setting target_frames_per_second to a high value would probably make it a touch quicker, it has a complex spec. I put in #2696 to get a cleaner way of doing this.

[caternuson]

Sure. Sorry for being vague. I was thinking from within the C code in the firmware. For this fill feature, I've got a loop in Bitmap.c to do the fill. Now want to do the equivalent of board.DISPLAY.auto_refresh = False before the loop. And then re-enable after. As @tannewt mentioned above:

A C implemented fill will still be faster since it can both prevent the intermediate refresh and quickly fill the underlying buffer.

So - how to do the first part? Not seeing how one can access the display instance from there.