Faster fblits() for multiple blits of the same Surface

buildconfig/stubs/pygame/surface.pyi

@@ -80,8 +80,14 @@ class Surface:
     ) -> Union[List[Rect], None]: ...
     def fblits(
         self,
-        blit_sequence: Iterable[Tuple[Surface, Union[Coordinate, RectValue]]],
-        special_flags: int = 0, /
+        blit_sequence: Iterable[
+            Union[
+                Tuple[Surface, Union[Coordinate, RectValue]],
+                Tuple[Surface, Sequence[Union[Coordinate, RectValue]]],
+            ]
+        ],
+        special_flags: int = 0,
+        /,
     ) -> None: ...
     @overload
     def convert(self, surface: Surface, /) -> Surface: ...

docs/reST/ref/surface.rst

@@ -197,7 +197,8 @@
    .. method:: fblits
 
       | :sl:`draw many surfaces onto the calling surface at their corresponding location and the same special_flags`
-      | :sg:`fblits(blit_sequence=((source, dest), ...), special_flags=0, /) -> None`
+      | :sg:`fblits(blit_sequence=((source, dest), ...), special_flags=0/) -> None`
+      | :sg:`fblits(blit_sequence=((source, [dest1, dest2, ...]), ...), special_flags=0/) -> None`
 
       This method takes a sequence of tuples (source, dest) as input, where source is a Surface
       object and dest is its destination position on this Surface. It draws each source Surface

src_c/alphablit.c

@@ -61,6 +61,11 @@ blit_blend_premultiplied(SDL_BlitInfo *info);
 static int
 SoftBlitPyGame(SDL_Surface *src, SDL_Rect *srcrect, SDL_Surface *dst,
                SDL_Rect *dstrect, int blend_flags);
+
+int
+SoftMultiBlitPyGame(SDL_Surface *src, SDL_Surface *dst, int blend_flags,
+                    BlitSequence *destinations);
+
 extern int
 SDL_RLESurface(SDL_Surface *surface);
 extern void
@@ -580,6 +585,80 @@ SoftBlitPyGame(SDL_Surface *src, SDL_Rect *srcrect, SDL_Surface *dst,
     return (okay ? 0 : -1);
 }
 
+void
+pg_multi_blitcopy(SDL_Surface *restrict src, SDL_Surface *restrict dst,
+                  BlitSequence *restrict destinations)
+{
+    Py_ssize_t i;
+    const int src_skip = src->pitch / 4;
+    const int dst_skip = dst->pitch / 4;
+
+    Uint32 *const src_start = (Uint32 *)src->pixels;
+
+    for (i = 0; i < destinations->size; i++) {
+        BlitDestination *item = &destinations->sequence[i];
+        Uint32 *dstp32 = item->pixels;
+        int h = item->rows;
+        const int copy_w = item->width * 4;
+        Uint32 *srcp32 = src_start + item->src_offset;
+
+        while (h--) {
+            memcpy(dstp32, srcp32, copy_w);
+            srcp32 += src_skip;
+            dstp32 += dst_skip;
+        }
+    }
+}
+
+int
+SoftMultiBlitPyGame(SDL_Surface *src, SDL_Surface *dst, int blend_flags,
+                    BlitSequence *destinations)
+{
+    int okay = 1;
+    int src_locked = 0, dst_locked = 0;
+
+    if (SDL_MUSTLOCK(dst)) {
+        if (SDL_LockSurface(dst) < 0)
+            okay = 0;
+        else
+            dst_locked = 1;
+    }
+    if (SDL_MUSTLOCK(src)) {
+        if (SDL_LockSurface(src) < 0)
+            okay = 0;
+        else
+            src_locked = 1;
+    }
+
+    if (okay) {
+        SDL_BlendMode src_blend;
+        switch (blend_flags) {
+            case 0:
+                /* unhandled cases */
+                if (SDL_GetSurfaceBlendMode(src, &src_blend) != 0 ||
+                    (src_blend == SDL_BLENDMODE_NONE && src->format->Amask) ||
+                    SDL_HasColorKey(src)) {
+                    okay = 0;
+                    break;
+                }
+
+                /* blitcopy */
+                pg_multi_blitcopy(src, dst, destinations);
+                break;
+            default:
+                okay = 0;
+                break;
+        }
+    }
+
+    if (dst_locked)
+        SDL_UnlockSurface(dst);
+    if (src_locked)
+        SDL_UnlockSurface(src);
+
+    return okay ? 0 : -1;
+}
+
 /* --------------------------------------------------------- */
 
 static void

src_c/doc/surface_doc.h

@@ -2,7 +2,7 @@
 #define DOC_SURFACE "Surface((width, height), flags=0, depth=0, masks=None) -> Surface\nSurface((width, height), flags=0, Surface) -> Surface\npygame object for representing images"
 #define DOC_SURFACE_BLIT "blit(source, dest, area=None, special_flags=0) -> Rect\ndraw another surface onto this one"
 #define DOC_SURFACE_BLITS "blits(blit_sequence=((source, dest), ...), doreturn=True) -> [Rect, ...] or None\nblits(((source, dest, area), ...)) -> [Rect, ...]\nblits(((source, dest, area, special_flags), ...)) -> [Rect, ...]\ndraw many images onto another"
-#define DOC_SURFACE_FBLITS "fblits(blit_sequence=((source, dest), ...), special_flags=0, /) -> None\ndraw many surfaces onto the calling surface at their corresponding location and the same special_flags"
+#define DOC_SURFACE_FBLITS "fblits(blit_sequence=((source, dest), ...), special_flags=0/) -> None\nfblits(blit_sequence=((source, [dest1, dest2, ...]), ...), special_flags=0/) -> None\ndraw many surfaces onto the calling surface at their corresponding location and the same special_flags"
 #define DOC_SURFACE_CONVERT "convert(surface, /) -> Surface\nconvert(depth, flags=0, /) -> Surface\nconvert(masks, flags=0, /) -> Surface\nconvert() -> Surface\nchange the pixel format of an image"
 #define DOC_SURFACE_CONVERTALPHA "convert_alpha() -> Surface\nchange the pixel format of an image including per pixel alphas"
 #define DOC_SURFACE_COPY "copy() -> Surface\ncreate a new copy of a Surface"