extmod/modframebuf: Add support for blit'ing read-only data.

dpgeorge · dpgeorge · commit b15348415e9d · 2025-06-04T02:40:45.000+10:00
Currently the `FrameBuffer.blit(buf, x, y)` method requires the `buf`
argument to be another `FrameBuffer`, which is quite restrictive because it
doesn't allow blit'ing read-only memory/data.

This commit extends `blit()` to allow the `buf` argument to be a tuple or
list of the form:

    (buffer, width, height, format[, stride])

where `buffer` can be anything with the buffer protocol and may be
read-only, eg `bytes`.

Also, the palette argument to `blit()` may be of the same form.

The form of this tuple/list was chosen to be the same as the signature of
the `FrameBuffer` constructor (that saves quite a bit of code size doing it
that way).

Signed-off-by: Damien George &lt;damien@micropython.org&gt;
diff --git a/docs/library/framebuf.rst b/docs/library/framebuf.rst
@@ -137,6 +137,18 @@ Other methods
     is compared to the value from *palette*, not to the value directly from
     *fbuf*.)
 
+    *fbuf* can be another FrameBuffer instance, or a tuple or list of the form::
+
+        (buffer, width, height, format)
+
+    or::
+
+        (buffer, width, height, format, stride)
+
+    This matches the signature of the FrameBuffer constructor, and the elements
+    of the tuple/list are the same as the arguments to the constructor except that
+    the *buffer* here can be read-only.
+
     The *palette* argument enables blitting between FrameBuffers with differing
     formats. Typical usage is to render a monochrome or grayscale glyph/icon to
     a color display. The *palette* is a FrameBuffer instance whose format is
diff --git a/examples/natmod/framebuf/framebuf.c b/examples/natmod/framebuf/framebuf.c
@@ -4,6 +4,9 @@
 #include "py/dynruntime.h"
 
 #if !defined(__linux__)
+void *memcpy(void *dst, const void *src, size_t n) {
+    return mp_fun_table.memmove_(dst, src, n);
+}
 void *memset(void *s, int c, size_t n) {
     return mp_fun_table.memset_(s, c, n);
 }
diff --git a/extmod/modframebuf.c b/extmod/modframebuf.c
@@ -270,8 +270,7 @@ static void fill_rect(const mp_obj_framebuf_t *fb, int x, int y, int w, int h, u
     formats[fb->format].fill_rect(fb, x, y, xend - x, yend - y, col);
 }
 
-static mp_obj_t framebuf_make_new(const mp_obj_type_t *type, size_t n_args, size_t n_kw, const mp_obj_t *args_in) {
-    mp_arg_check_num(n_args, n_kw, 4, 5, false);
+static mp_obj_t framebuf_make_new_helper(size_t n_args, const mp_obj_t *args_in, unsigned int buf_flags, mp_obj_framebuf_t *o) {
 
     mp_int_t width = mp_obj_get_int(args_in[1]);
     mp_int_t height = mp_obj_get_int(args_in[2]);
@@ -318,13 +317,15 @@ static mp_obj_t framebuf_make_new(const mp_obj_type_t *type, size_t n_args, size
     }
 
     mp_buffer_info_t bufinfo;
-    mp_get_buffer_raise(args_in[0], &bufinfo, MP_BUFFER_WRITE);
+    mp_get_buffer_raise(args_in[0], &bufinfo, buf_flags);
 
     if ((strides_required * stride + (height_required - strides_required) * width_required) * bpp / 8 > bufinfo.len) {
         mp_raise_ValueError(NULL);
     }
 
-    mp_obj_framebuf_t *o = mp_obj_malloc(mp_obj_framebuf_t, type);
+    if (o == NULL) {
+        o = mp_obj_malloc(mp_obj_framebuf_t, (const mp_obj_type_t *)&mp_type_framebuf);
+    }
     o->buf_obj = args_in[0];
     o->buf = bufinfo.buf;
     o->width = width;
@@ -335,6 +336,11 @@ static mp_obj_t framebuf_make_new(const mp_obj_type_t *type, size_t n_args, size
     return MP_OBJ_FROM_PTR(o);
 }
 
+static mp_obj_t framebuf_make_new(const mp_obj_type_t *type, size_t n_args, size_t n_kw, const mp_obj_t *args_in) {
+    mp_arg_check_num(n_args, n_kw, 4, 5, false);
+    return framebuf_make_new_helper(n_args, args_in, MP_BUFFER_WRITE, NULL);
+}
+
 static void framebuf_args(const mp_obj_t *args_in, mp_int_t *args_out, int n) {
     for (int i = 0; i < n; ++i) {
         args_out[i] = mp_obj_get_int(args_in[i + 1]);
@@ -707,30 +713,45 @@ static MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(framebuf_poly_obj, 5, 6, framebuf_pol
 
 #endif // MICROPY_PY_ARRAY
 
+static void get_readonly_framebuffer(mp_obj_t arg, mp_obj_framebuf_t *rofb) {
+    mp_obj_t fb = mp_obj_cast_to_native_base(arg, MP_OBJ_FROM_PTR(&mp_type_framebuf));
+    if (fb != MP_OBJ_NULL) {
+        *rofb = *(mp_obj_framebuf_t *)MP_OBJ_TO_PTR(fb);
+    } else {
+        // A tuple/list of the form: (buffer, width, height, format[, stride]).
+        size_t len;
+        mp_obj_t *items;
+        mp_obj_get_array(arg, &len, &items);
+        if (len < 4 || len > 5) {
+            mp_raise_ValueError(NULL);
+        }
+        framebuf_make_new_helper(len, items, MP_BUFFER_READ, rofb);
+    }
+}
+
 static mp_obj_t framebuf_blit(size_t n_args, const mp_obj_t *args_in) {
     mp_obj_framebuf_t *self = MP_OBJ_TO_PTR(args_in[0]);
-    mp_obj_t source_in = mp_obj_cast_to_native_base(args_in[1], MP_OBJ_FROM_PTR(&mp_type_framebuf));
-    if (source_in == MP_OBJ_NULL) {
-        mp_raise_TypeError(NULL);
-    }
-    mp_obj_framebuf_t *source = MP_OBJ_TO_PTR(source_in);
+
+    mp_obj_framebuf_t source;
+    get_readonly_framebuffer(args_in[1], &source);
 
     mp_int_t x = mp_obj_get_int(args_in[2]);
     mp_int_t y = mp_obj_get_int(args_in[3]);
     mp_int_t key = -1;
     if (n_args > 4) {
         key = mp_obj_get_int(args_in[4]);
     }
-    mp_obj_framebuf_t *palette = NULL;
+    mp_obj_framebuf_t palette;
+    palette.buf = NULL;
     if (n_args > 5 && args_in[5] != mp_const_none) {
-        palette = MP_OBJ_TO_PTR(mp_obj_cast_to_native_base(args_in[5], MP_OBJ_FROM_PTR(&mp_type_framebuf)));
+        get_readonly_framebuffer(args_in[5], &palette);
     }
 
     if (
         (x >= self->width) ||
         (y >= self->height) ||
-        (-x >= source->width) ||
-        (-y >= source->height)
+        (-x >= source.width) ||
+        (-y >= source.height)
         ) {
         // Out of bounds, no-op.
         return mp_const_none;
@@ -741,15 +762,15 @@ static mp_obj_t framebuf_blit(size_t n_args, const mp_obj_t *args_in) {
     int y0 = MAX(0, y);
     int x1 = MAX(0, -x);
     int y1 = MAX(0, -y);
-    int x0end = MIN(self->width, x + source->width);
-    int y0end = MIN(self->height, y + source->height);
+    int x0end = MIN(self->width, x + source.width);
+    int y0end = MIN(self->height, y + source.height);
 
     for (; y0 < y0end; ++y0) {
         int cx1 = x1;
         for (int cx0 = x0; cx0 < x0end; ++cx0) {
-            uint32_t col = getpixel(source, cx1, y1);
-            if (palette) {
-                col = getpixel(palette, col, 0);
+            uint32_t col = getpixel(&source, cx1, y1);
+            if (palette.buf) {
+                col = getpixel(&palette, col, 0);
             }
             if (col != (uint32_t)key) {
                 setpixel(self, cx0, y0, col);
diff --git a/tests/extmod/framebuf_blit.py b/tests/extmod/framebuf_blit.py
@@ -0,0 +1,68 @@
+# Test FrameBuffer.blit method.
+
+try:
+    import framebuf
+except ImportError:
+    print("SKIP")
+    raise SystemExit
+
+
+def printbuf():
+    print("--8<--")
+    for y in range(h):
+        for x in range(w):
+            print("%02x" % buf[(x + y * w)], end="")
+        print()
+    print("-->8--")
+
+
+w = 5
+h = 4
+buf = bytearray(w * h)
+fbuf = framebuf.FrameBuffer(buf, w, h, framebuf.GS8)
+
+fbuf2 = framebuf.FrameBuffer(bytearray(4), 2, 2, framebuf.GS8)
+fbuf2.fill(0xFF)
+
+# Blit another FrameBuffer, at various locations.
+for x, y in ((-1, -1), (0, 0), (1, 1), (4, 3)):
+    fbuf.fill(0)
+    fbuf.blit(fbuf2, x, y)
+    printbuf()
+
+# Blit a bytes object.
+fbuf.fill(0)
+image = (b"\x10\x11\x12\x13", 2, 2, framebuf.GS8)
+fbuf.blit(image, 1, 1)
+printbuf()
+
+# Blit a bytes object that has a stride.
+fbuf.fill(0)
+image = (b"\x20\x21\xff\x22\x23\xff", 2, 2, framebuf.GS8, 3)
+fbuf.blit(image, 1, 1)
+printbuf()
+
+# Blit a bytes object with a bytes palette.
+fbuf.fill(0)
+image = (b"\x00\x01\x01\x00", 2, 2, framebuf.GS8)
+palette = (b"\xa1\xa2", 2, 1, framebuf.GS8)
+fbuf.blit(image, 1, 1, -1, palette)
+printbuf()
+
+# Not enough elements in the tuple.
+try:
+    fbuf.blit((0, 0, 0), 0, 0)
+except ValueError:
+    print("ValueError")
+
+# Too many elements in the tuple.
+try:
+    fbuf.blit((0, 0, 0, 0, 0, 0), 0, 0)
+except ValueError:
+    print("ValueError")
+
+# Bytes too small.
+try:
+    fbuf.blit((b"", 1, 1, framebuf.GS8), 0, 0)
+except ValueError:
+    print("ValueError")
diff --git a/tests/extmod/framebuf_blit.py.exp b/tests/extmod/framebuf_blit.py.exp
@@ -0,0 +1,45 @@
+--8<--
+ff00000000
+0000000000
+0000000000
+0000000000
+-->8--
+--8<--
+ffff000000
+ffff000000
+0000000000
+0000000000
+-->8--
+--8<--
+0000000000
+00ffff0000
+00ffff0000
+0000000000
+-->8--
+--8<--
+0000000000
+0000000000
+0000000000
+00000000ff
+-->8--
+--8<--
+0000000000
+0010110000
+0012130000
+0000000000
+-->8--
+--8<--
+0000000000
+0020210000
+0022230000
+0000000000
+-->8--
+--8<--
+0000000000
+00a1a20000
+00a2a10000
+0000000000
+-->8--
+ValueError
+ValueError
+ValueError

Original file line number	Diff line number	Diff line change
`@@ -4,6 +4,9 @@`
`4`	`4`	`#include "py/dynruntime.h"`
`5`	`5`
`6`	`6`	`#if !defined(__linux__)`
	`7`	`+void memcpy(void dst, const void *src, size_t n) {`
	`8`	`+ return mp_fun_table.memmove_(dst, src, n);`
	`9`	`+}`
`7`	`10`	`void memset(void s, int c, size_t n) {`
`8`	`11`	`return mp_fun_table.memset_(s, c, n);`
`9`	`12`	`}`