Play GIF animation on e-paper displays

lib/AnimatedGIF/AnimatedGIF_circuitpy.h

@@ -33,7 +33,6 @@
 #define MAX_CHUNK_SIZE 255
 #define LZW_BUF_SIZE (6 * MAX_CHUNK_SIZE)
 #define LZW_HIGHWATER (4 * MAX_CHUNK_SIZE)
-#define MAX_WIDTH 320
 #define FILE_BUF_SIZE 4096
 
 #define PIXEL_FIRST 0
@@ -140,7 +139,7 @@ typedef struct gif_image_tag
     //unsigned char *pFrameBuffer;
     unsigned int *pFrameBuffer;
     unsigned char *pPixels, *pOldPixels;
-    unsigned char ucLineBuf[MAX_WIDTH]; // current line
+    unsigned char *ucLineBuf; // current line, at least iCanvasWidth bytes. Set by GIF_init().
     unsigned char ucFileBuf[FILE_BUF_SIZE]; // holds temp data and pixel stack
     unsigned short pPalette[384]; // can hold RGB565 or RGB888 - set in begin()
     unsigned short pLocalPalette[384]; // color palettes for GIF images
@@ -166,7 +165,10 @@ int GIF_getComment(GIFIMAGE *pGIF, char *destBuffer);
 int GIF_getInfo(GIFIMAGE *pGIF, GIFINFO *pInfo);
 int GIF_getLastError(GIFIMAGE *pGIF);
 int GIF_getLoopCount(GIFIMAGE *pGIF);
-int GIF_init(GIFIMAGE *pGIF);
+// Reads the header and fills in the canvas size. pLineBuf holds one line of pixels and must be
+// at least iCanvasWidth bytes, or this fails with GIF_TOO_WIDE. Pass NULL and 0 to only measure
+// the canvas, then call again with a buffer before decoding. Returns 1 on success, 0 on failure.
+int GIF_init(GIFIMAGE *pGIF, unsigned char *pLineBuf, int iLineBufSize);
 void GIF_setDrawCallback(GIFIMAGE *pGIF, GIF_DRAW_CALLBACK *pfnDraw);
 void GIF_scaleHalf(uint16_t *pCurrent, uint16_t *pPrev, int iWidth, int bBigEndian);
 

lib/AnimatedGIF/gif.c

@@ -163,8 +163,16 @@ int GIF_getLastError(GIFIMAGE *pGIF)
     return pGIF->iError;
 } /* GIF_getLastError() */
 
-int GIF_init(GIFIMAGE *pGIF) {
-    return GIFInit(pGIF);
+int GIF_init(GIFIMAGE *pGIF, unsigned char *pLineBuf, int iLineBufSize) {
+    pGIF->ucLineBuf = pLineBuf;
+    if (!GIFInit(pGIF)) {
+        return 0;
+    }
+    if (pLineBuf != NULL && pGIF->iCanvasWidth > iLineBufSize) {
+        pGIF->iError = GIF_TOO_WIDE;
+        return 0;
+    }
+    return 1;
 }
 
 //
@@ -253,10 +261,6 @@ static int GIFInit(GIFIMAGE *pGIF)
     if (!GIFParseInfo(pGIF, 1)) // gather info for the first frame
        return 0; // something went wrong; not a GIF file?
     (*pGIF->pfnSeek)(&pGIF->GIFFile, 0); // seek back to start of the file
-    if (pGIF->iCanvasWidth > MAX_WIDTH) { // need to allocate more space
-        pGIF->iError = GIF_TOO_WIDE;
-        return 0;
-    }
   return 1;
 } /* GIFInit() */
 
@@ -445,6 +449,11 @@ static int GIFParseInfo(GIFIMAGE *pPage, int bInfoOnly)
     pPage->iWidth = INTELSHORT(&p[iOffset+4]);
     pPage->iHeight = INTELSHORT(&p[iOffset+6]);
     iOffset += 8;
+    // The line buffer is sized to the canvas, so a frame must fit inside it.
+    if (pPage->iX + pPage->iWidth > pPage->iCanvasWidth) {
+        pPage->iError = GIF_DECODE_ERROR;
+        return 0;
+    }
 
     /* Image descriptor
      7 6 5 4 3 2 1 0    M=0 - use global color map, ignore pixel

ports/raspberrypi/boards/adafruit_feather_rp2040_thinkink/mpconfigboard.mk

@@ -7,3 +7,5 @@ CHIP_VARIANT = RP2040
 CHIP_FAMILY = rp2
 
 EXTERNAL_FLASH_DEVICES = "GD25Q64C,W25Q64JVxQ"
+
+CIRCUITPY_VIDEOCORE = 1

py/circuitpy_mpconfig.mk

@@ -868,9 +868,8 @@ CFLAGS += -DCIRCUITPY_ULAB=$(CIRCUITPY_ULAB)
 # element-wise array arithmetic roughly 1.5x slower.
 CIRCUITPY_ULAB_OPTIMIZE_SIZE ?= 0
 
-# Video pipeline: playing video sources into framebuffers. Requires a port
-# with a video source such as mipicsi and a framebuffer output such as
-# mipidsi.
+# Video pipeline: playing video sources into framebuffers or plain buffers.
+# A source can be a port's camera, such as mipicsi, or a GIF file with videogif.
 CIRCUITPY_VIDEOCORE ?= 0
 CFLAGS += -DCIRCUITPY_VIDEOCORE=$(CIRCUITPY_VIDEOCORE)
 

shared-bindings/gifio/OnDiskGif.c

@@ -97,9 +97,8 @@
 //|
 //|         If the image is too large it will be cropped at the bottom and right when displayed.
 //|
-//|         **Limitations**: The image width is limited to 320 pixels at present. `ValueError`
-//|         will be raised if the image is too wide. The height
-//|         is not limited but images that are too large will cause a memory exception.
+//|         **Limitations**: The width and height are not limited, but images that are too
+//|         large will cause a memory exception.
 //|         """
 //|         ...
 //|

shared-bindings/videocore/VideoBuffer.c

@@ -32,9 +32,18 @@
 //|     Assigning a Group that contains a framebuffer target as a rotated
 //|     display's ``root_group`` raises `ValueError`.
 //|
-//|     When the target is a plain buffer, frames are written compactly (row
-//|     stride equals ``width * bits_per_pixel / 8``) and can be read from
-//|     Python at any time, for example to process or save camera pixels.
+//|     When the target is a plain buffer, frames are written with no gap
+//|     between rows, so each row takes ``(width * bits_per_pixel + 7) // 8``
+//|     bytes. Python code can read the buffer at any time, for example to
+//|     process or save camera pixels. 1-bit pixels are packed together, and
+//|     each row is padded out to a whole byte.
+//|     A Group shows a plain buffer target only when its pixels are 16 bits
+//|     and the display uses 16-bit color, or its pixels are 1 bit and the
+//|     display is monochrome with the leftmost pixel in the top bit of each
+//|     byte, such as `epaperdisplay.EPaperDisplay`. A 1 bit means white.
+//|     On a tricolor display with separate black and color RAM, a 1 bit video
+//|     only draws black and white, and a highlight colored layer below it shows
+//|     through. Other tricolor displays don't draw it.
 //|
 //|     See the `videocore` module overview for complete examples.
 //|     """
@@ -44,41 +53,54 @@
 //|         framebuffer: Union[
 //|             circuitpython_typing.FrameBuffer, circuitpython_typing.WriteableBuffer
 //|         ],
+//|         *,
+//|         bits_per_pixel: int = 16,
 //|     ) -> None:
 //|         """Create a VideoBuffer that plays video into the given framebuffer
 //|
 //|         :param framebuffer: The framebuffer to copy video frames into, or a
 //|             writable buffer such as a ``bytearray`` or ``memoryview``.
+//|         :param int bits_per_pixel: The pixel format of a writable buffer: 16
+//|             for color (RGB565), or 1 for black and white. A framebuffer uses
+//|             its own color depth instead.
 //|         """
 //|
 static mp_obj_t videocore_videobuffer_make_new(const mp_obj_type_t *type, size_t n_args, size_t n_kw, const mp_obj_t *all_args) {
-    enum { ARG_framebuffer, NUM_ARGS };
+    enum { ARG_framebuffer, ARG_bits_per_pixel, NUM_ARGS };
     static const mp_arg_t allowed_args[] = {
         { MP_QSTR_framebuffer, MP_ARG_REQUIRED | MP_ARG_OBJ },
+        { MP_QSTR_bits_per_pixel, MP_ARG_INT | MP_ARG_KW_ONLY, {.u_int = 16} },
     };
 
     mp_arg_val_t args[MP_ARRAY_SIZE(allowed_args)];
     MP_STATIC_ASSERT(MP_ARRAY_SIZE(allowed_args) == NUM_ARGS);
     mp_arg_parse_all_kw_array(n_args, n_kw, all_args, MP_ARRAY_SIZE(allowed_args), allowed_args, args);
 
+    const mp_int_t bits_per_pixel = args[ARG_bits_per_pixel].u_int;
+    if (bits_per_pixel != 1 && bits_per_pixel != 16) {
+        mp_arg_error_invalid(MP_QSTR_bits_per_pixel);
+    }
+
     videocore_videobuffer_obj_t *self = mp_obj_malloc_with_finaliser(videocore_videobuffer_obj_t, &videocore_videobuffer_type);
-    common_hal_videocore_videobuffer_construct(self, args[ARG_framebuffer].u_obj);
+    common_hal_videocore_videobuffer_construct(self, args[ARG_framebuffer].u_obj, bits_per_pixel);
     return MP_OBJ_FROM_PTR(self);
 }
 
 //|     def play(self, source: circuitpython_typing.VideoSource) -> None:
 //|         """Begin streaming the given video source into the target.
 //|
 //|         The source streams continuously, writing each new frame where the
-//|         VideoBuffer tells it to, replacing the previous one. The source's
-//|         frame format must be byte aligned. The source's size and format are
-//|         then fixed for the duration of the ``play()``; sources that change
-//|         them require ``stop()`` and a new ``play()``.
+//|         VideoBuffer tells it to, replacing the previous one. The source can
+//|         use 1 bit per pixel, or a whole number of bytes per pixel.
+//|         The source's size and format are then fixed for the duration of the
+//|         ``play()``; sources that change them require ``stop()`` and a new
+//|         ``play()``.
 //|
 //|         When the target is a framebuffer, its bits per pixel must match the
-//|         framebuffer color depth and the whole frame must fit within the
-//|         framebuffer at the current ``x``/``y`` position. An exception may be
-//|         raised if the video can't be played directly into the framebuffer.
+//|         source and be a whole number of bytes, and the whole frame must fit
+//|         within the framebuffer at the current ``x``/``y`` position. An
+//|         exception may be raised if the video can't be played directly into
+//|         the framebuffer.
 //|
 //|         When the target is a plain buffer, it must be large enough for a
 //|         whole frame.

shared-bindings/videogif/GifDecoder.c

@@ -81,9 +81,14 @@
 //|         :param str filename: The name of a GIF file, such as ``"/animation.gif"``.
 //|             The GifDecoder closes the file when it is deinitialized.
 //|
-//|         Frames are RGB565, in the byte order of the display or framebuffer
-//|         that shows them. Raises `ValueError` if the file is not a GIF or if
-//|         the GIF is wider than 320 pixels.
+//|         The `videocore.VideoBuffer` playing the GIF sets the pixel format.
+//|         16-bit frames are RGB565, in the byte order of the display or
+//|         framebuffer that shows them. 1-bit frames pack eight pixels into
+//|         each byte, with the leftmost pixel in the most significant bit. A
+//|         pixel is white (1) when its brightness is at least 128 out of 255,
+//|         so a GIF that uses only black and white converts exactly.
+//|
+//|         Raises `ValueError` if the file is not a GIF.
 //|         """
 //|         ...
 //|
@@ -206,7 +211,11 @@ static mp_int_t videogif_gifdecoder_videosource_get_height(mp_obj_t self_in) {
 }
 
 static mp_int_t videogif_gifdecoder_get_bits_per_pixel(mp_obj_t self_in) {
-    return 16;
+    return common_hal_videogif_gifdecoder_get_bits_per_pixel(native_gifdecoder(self_in));
+}
+
+static bool videogif_gifdecoder_set_bits_per_pixel(mp_obj_t self_in, mp_int_t bits_per_pixel) {
+    return common_hal_videogif_gifdecoder_set_bits_per_pixel(native_gifdecoder(self_in), bits_per_pixel);
 }
 
 static const videosource_p_t videogif_gifdecoder_videosource_protocol = {
@@ -219,6 +228,7 @@ static const videosource_p_t videogif_gifdecoder_videosource_protocol = {
     .get_width = videogif_gifdecoder_videosource_get_width,
     .get_height = videogif_gifdecoder_videosource_get_height,
     .get_bits_per_pixel = videogif_gifdecoder_get_bits_per_pixel,
+    .set_bits_per_pixel = videogif_gifdecoder_set_bits_per_pixel,
 };
 
 MP_DEFINE_CONST_OBJ_TYPE(

shared-bindings/videogif/GifDecoder.h

@@ -11,15 +11,20 @@
 extern const mp_obj_type_t videogif_gifdecoder_type;
 
 // Open the GIF in file, which the constructor opened from its filename. Frames
-// are RGB565.
-// Raises when the file isn't a GIF or is wider than AnimatedGIF supports.
+// are 16-bit until set_bits_per_pixel asks for 1. Raises when the file isn't a
+// GIF or is wider than AnimatedGIF supports.
 void common_hal_videogif_gifdecoder_construct(videogif_gifdecoder_obj_t *self, mp_obj_t file);
 // Stop playing, free the decoder and close the file. Safe to call more than
 // once.
 void common_hal_videogif_gifdecoder_deinit(videogif_gifdecoder_obj_t *self);
 bool common_hal_videogif_gifdecoder_deinited(videogif_gifdecoder_obj_t *self);
 mp_int_t common_hal_videogif_gifdecoder_get_width(videogif_gifdecoder_obj_t *self);
 mp_int_t common_hal_videogif_gifdecoder_get_height(videogif_gifdecoder_obj_t *self);
+mp_int_t common_hal_videogif_gifdecoder_get_bits_per_pixel(videogif_gifdecoder_obj_t *self);
+// Decode frames to 1 or 16 bits per pixel from the next play. Returns false
+// while playing or for another value. Never raises.
+bool common_hal_videogif_gifdecoder_set_bits_per_pixel(videogif_gifdecoder_obj_t *self,
+    mp_int_t bits_per_pixel);
 
 // Videosource protocol steps, driven by videocore.VideoBuffer. Frames are
 // decoded by the supervisor background tick, never in an interrupt. play

shared-module/gifio/OnDiskGif.c

@@ -162,16 +162,15 @@ void common_hal_gifio_ondiskgif_construct(gifio_ondiskgif_t *self, mp_obj_t file
     }
     self->gif.GIFFile.iSize = (int32_t)size;
 
-    int result = GIF_init(&self->gif);
-    if (result != 1) {
-        switch (self->gif.iError) {
-            case GIF_TOO_WIDE:
-                mp_raise_ValueError_varg(MP_ERROR_TEXT("%q must be <= %d"), MP_QSTR_width, MAX_WIDTH);
-                break;
-            default:
-                mp_arg_error_invalid(MP_QSTR_file);
-                break;
-        }
+    // Measure the canvas first, then hand the decoder a line buffer of that width.
+    if (GIF_init(&self->gif, NULL, 0) != 1) {
+        mp_arg_error_invalid(MP_QSTR_file);
+    }
+    // One line of 8-bit pixels. It holds no pointers, so the GC doesn't scan it.
+    int width = self->gif.iCanvasWidth;
+    unsigned char *line_buf = m_malloc_without_collect(width);
+    if (GIF_init(&self->gif, line_buf, width) != 1) {
+        mp_arg_error_invalid(MP_QSTR_file);
     }
 
     int bpp = 16;
@@ -201,6 +200,8 @@ void common_hal_gifio_ondiskgif_deinit(gifio_ondiskgif_t *self) {
         return;
     }
     self->file = NULL;
+    m_del(uint8_t, self->gif.ucLineBuf, self->gif.iCanvasWidth);
+    self->gif.ucLineBuf = NULL;
     common_hal_displayio_bitmap_deinit(self->bitmap);
     self->bitmap = NULL;
     self->palette = NULL;