Merge pull request #3372 from pygame-community/ankith26-animation

Add `image.load_animation`

Author: ankith26

buildconfig/stubs/pygame/image.pyi

@@ -15,6 +15,7 @@ _from_bytes_format = Literal["P", "RGB", "RGBX", "RGBA", "ARGB", "BGRA", "ABGR"]
 
 def load(file: FileLike, namehint: str = "") -> Surface: ...
 def load_sized_svg(file: FileLike, size: Point) -> Surface: ...
+def load_animation(file: FileLike, namehint: str = "") -> list[tuple[Surface, int]]: ...
 def save(surface: Surface, file: FileLike, namehint: str = "") -> None: ...
 def get_sdl_image_version(linked: bool = True) -> Optional[tuple[int, int, int]]: ...
 def get_extended() -> bool: ...

docs/reST/ref/image.rst

@@ -135,6 +135,28 @@ following formats.
 
    .. ## pygame.image.load_sized_svg ##
 
+.. function:: load_animation
+
+   | :sl:`load an animation (GIF/WEBP) from a file (or file-like object)`
+   | :sg:`load_animation(file, namehint="") -> list[tuple[Surface, int]]`
+
+   Load an animation (GIF/WEBP) from a file source. You can pass either a
+   filename, a Python file-like object, or a pathlib.Path. If you pass a raw
+   file-like object, you may also want to pass the original filename as the
+   namehint argument so that the file extension can be used to infer the file
+   format.
+
+   This returns a list of tuples (corresponding to every frame of the animation),
+   where each tuple is a (surface, delay) pair for that frame.
+
+   This function requires SDL_image 2.6.0 or above. If pygame was compiled with
+   an older version, ``pygame.error`` will be raised when this function is
+   called.
+
+   .. versionadded:: 2.5.4
+
+   .. ## pygame.image.load_animation ##
+
 .. function:: save
 
    | :sl:`save an image to file (or file-like object)`

examples/data/animated_sample.gif

@@ -2,6 +2,7 @@
 #define DOC_IMAGE "pygame module for image transfer"
 #define DOC_IMAGE_LOAD "load(file) -> Surface\nload(file, namehint="") -> Surface\nload new image from a file (or file-like object)"
 #define DOC_IMAGE_LOADSIZEDSVG "load_sized_svg(file, size) -> Surface\nload an SVG image from a file (or file-like object) with the given size"
+#define DOC_IMAGE_LOADANIMATION "load_animation(file, namehint="") -> list[tuple[Surface, int]]\nload an animation (GIF/WEBP) from a file (or file-like object)"
 #define DOC_IMAGE_SAVE "save(Surface, file) -> None\nsave(Surface, file, namehint="") -> None\nsave an image to file (or file-like object)"
 #define DOC_IMAGE_GETSDLIMAGEVERSION "get_sdl_image_version(linked=True) -> None\nget_sdl_image_version(linked=True) -> (major, minor, patch)\nget version number of the SDL_Image library being used"
 #define DOC_IMAGE_GETEXTENDED "get_extended() -> bool\ntest if extended image formats can be loaded"

src_c/doc/image_doc.h

@@ -49,6 +49,7 @@ static PyObject *extloadobj = NULL;
 static PyObject *extsaveobj = NULL;
 static PyObject *extverobj = NULL;
 static PyObject *ext_load_sized_svg = NULL;
+static PyObject *ext_load_animation = NULL;
 
 static inline void
 pad(char **data, int padding)
@@ -1885,6 +1886,17 @@ image_load_sized_svg(PyObject *self, PyObject *args, PyObject *kwargs)
                  "Support for sized svg image loading was not compiled in.");
 }
 
+static PyObject *
+image_load_animation(PyObject *self, PyObject *args, PyObject *kwargs)
+{
+    if (ext_load_animation) {
+        return PyObject_Call(ext_load_animation, args, kwargs);
+    }
+
+    return RAISE(PyExc_NotImplementedError,
+                 "Support for animation loading was not compiled in.");
+}
+
 static PyMethodDef _image_methods[] = {
     {"load_basic", (PyCFunction)image_load_basic, METH_O, DOC_IMAGE_LOADBASIC},
     {"load_extended", (PyCFunction)image_load_extended,
@@ -1893,6 +1905,8 @@ static PyMethodDef _image_methods[] = {
      DOC_IMAGE_LOAD},
     {"load_sized_svg", (PyCFunction)image_load_sized_svg,
      METH_VARARGS | METH_KEYWORDS, DOC_IMAGE_LOADSIZEDSVG},
+    {"load_animation", (PyCFunction)image_load_animation,
+     METH_VARARGS | METH_KEYWORDS, DOC_IMAGE_LOADANIMATION},
 
     {"save_extended", (PyCFunction)image_save_extended,
      METH_VARARGS | METH_KEYWORDS, DOC_IMAGE_SAVEEXTENDED},
@@ -1973,6 +1987,11 @@ MODINIT_DEFINE(image)
         if (!ext_load_sized_svg) {
             goto error;
         }
+        ext_load_animation =
+            PyObject_GetAttrString(extmodule, "_load_animation");
+        if (!ext_load_animation) {
+            goto error;
+        }
         Py_DECREF(extmodule);
     }
     else {
@@ -1986,6 +2005,7 @@ MODINIT_DEFINE(image)
     Py_XDECREF(extsaveobj);
     Py_XDECREF(extverobj);
     Py_XDECREF(ext_load_sized_svg);
+    Py_XDECREF(ext_load_animation);
     Py_DECREF(extmodule);
     Py_DECREF(module);
     return NULL;

src_c/image.c

@@ -206,6 +206,84 @@ imageext_load_sized_svg(PyObject *self, PyObject *arg, PyObject *kwargs)
 #endif /* ~SDL_IMAGE_VERSION_ATLEAST(2, 6, 0) */
 }
 
+static PyObject *
+imageext_load_animation(PyObject *self, PyObject *arg, PyObject *kwargs)
+{
+#if SDL_IMAGE_VERSION_ATLEAST(2, 6, 0)
+    PyObject *obj, *ret = NULL;
+    char *name = NULL, *ext = NULL, *type = NULL;
+    IMG_Animation *surfs = NULL;
+    SDL_RWops *rw = NULL;
+    static char *kwds[] = {"file", "namehint", NULL};
+
+    if (!PyArg_ParseTupleAndKeywords(arg, kwargs, "O|s", kwds, &obj, &name)) {
+        return NULL;
+    }
+
+    rw = pgRWops_FromObject(obj, &ext);
+    if (rw == NULL) { /* stop on NULL, error already set */
+        return NULL;
+    }
+
+    if (name) { /* override extension with namehint if given */
+        type = (strlen(name) != 0) ? iext_find_extension(name) : NULL;
+    }
+    else { /* Otherwise type should be whatever ext is, even if ext is NULL */
+        type = ext;
+    }
+
+    Py_BEGIN_ALLOW_THREADS;
+#if SDL_VERSION_ATLEAST(3, 0, 0)
+    surfs = IMG_LoadAnimationTyped_IO(rw, 1, type);
+#else
+    surfs = IMG_LoadAnimationTyped_RW(rw, 1, type);
+#endif
+    Py_END_ALLOW_THREADS;
+
+    if (ext) {
+        free(ext);
+    }
+
+    if (surfs == NULL) {
+        return RAISE(pgExc_SDLError, IMG_GetError());
+    }
+
+    ret = PyList_New(surfs->count);
+    if (!ret) {
+        goto error;
+    }
+
+    for (int i = 0; i < surfs->count; i++) {
+        PyObject *frame = (PyObject *)pgSurface_New(surfs->frames[i]);
+        if (!frame) {
+            /* IMG_FreeAnimation takes care of freeing of member SDL surfaces
+             */
+            goto error;
+        }
+        /* The python surface object now "owns" the sdl surface, so set it
+         * to null in the animation to prevent double free */
+        surfs->frames[i] = NULL;
+
+        PyObject *listentry = Py_BuildValue("(Oi)", frame, surfs->delays[i]);
+        Py_DECREF(frame);
+        if (!listentry) {
+            goto error;
+        }
+        PyList_SET_ITEM(ret, i, listentry);
+    }
+    IMG_FreeAnimation(surfs);
+    return ret;
+error:
+    Py_XDECREF(ret);
+    IMG_FreeAnimation(surfs);
+    return NULL;
+#else  /* ~SDL_IMAGE_VERSION_ATLEAST(2, 6, 0) */
+    return RAISE(
+        pgExc_SDLError,
+        "pygame must be compiled with SDL_image 2.6.0+ to use this function");
+#endif /* ~SDL_IMAGE_VERSION_ATLEAST(2, 6, 0) */
+}
+
 static PyObject *
 image_save_ext(PyObject *self, PyObject *arg, PyObject *kwarg)
 {
@@ -352,6 +430,8 @@ static PyMethodDef _imageext_methods[] = {
      "Note: Should not be used directly."},
     {"_load_sized_svg", (PyCFunction)imageext_load_sized_svg,
      METH_VARARGS | METH_KEYWORDS, "Note: Should not be used directly."},
+    {"_load_animation", (PyCFunction)imageext_load_animation,
+     METH_VARARGS | METH_KEYWORDS, "Note: Should not be used directly."},
     {NULL, NULL, 0, NULL}};
 
 /*DOC*/ static char _imageext_doc[] =

src_c/imageext.c

@@ -1360,6 +1360,37 @@ def test_load_sized_svg_erroring(self):
                     value_error_size,
                 )
 
+    @unittest.skipIf(
+        pygame.image.get_sdl_image_version() < (2, 6, 0),
+        "load_animation requires SDL_image 2.6.0+",
+    )
+    def test_load_animation(self):
+        # test loading from a file
+        SAMPLE_FRAMES = 10
+        SAMPLE_DELAY = 150
+        SAMPLE_SIZE = (312, 312)
+        gif_path = pathlib.Path(example_path("data/animated_sample.gif"))
+        for inp in (
+            (str(gif_path),),  # string path, no namehint
+            (gif_path,),  # pathlib.Path path, no namehint
+            (io.BytesIO(gif_path.read_bytes()),),  # file-like object, no namehint
+            (
+                io.BytesIO(gif_path.read_bytes()),
+                gif_path.name,
+            ),  # file-like object, with namehint
+        ):
+            with self.subTest(f"Test load_animation", inp=inp):
+                s = pygame.image.load_animation(*inp)
+                self.assertIsInstance(s, list)
+                self.assertEqual(len(s), SAMPLE_FRAMES)
+                for val in s:
+                    self.assertIsInstance(val, tuple)
+                    frame, delay = val
+                    self.assertIsInstance(frame, pygame.Surface)
+                    self.assertEqual(frame.size, SAMPLE_SIZE)
+                    self.assertIsInstance(delay, int)
+                    self.assertEqual(delay, SAMPLE_DELAY)
+
     def test_load_pathlib(self):
         """works loading using a Path argument."""
         path = pathlib.Path(example_path("data/asprite.bmp"))