Allow erasing pixels in pygame.Surface.scroll and add repeat functionality (#2855)

* Implementation, stubs and docs

* Remove spaces added by clang-format

* Fix variable could not be initialized

* Rewrite tests, fix code, add more exceptions

* Fix format 1

* Modify test

* Generate docs

* Allow non erasing pixels

* Fix doc

* Fix bug with erase

* Remove useless memset

* Separate in 2 functions for clarity

* Use SDL function to secure the clip

* Update docs

* build docs

* FLAG SYSTEM (I can revert if you don't like it)

* FLAG_SYSTEM fix stubs

* Update Docs

* Update versionchanged

Co-authored-by: Dan Lawrence <danintheshed@gmail.com>

* FIX THE MISSING PIXEL BUG

* Simplify conditional statement

* fix format

* Split in 2 functions, update versionchanged

* Fix docs and remove redundant C code

---------

Co-authored-by: Damus666 <97639432+Damus666@users.noreply.github.com>
Co-authored-by: Dan Lawrence <danintheshed@gmail.com>

Author: damusss

buildconfig/stubs/pygame/__init__.pyi

@@ -605,6 +605,8 @@ from .constants import (
     SCRAP_PPM as SCRAP_PPM,
     SCRAP_SELECTION as SCRAP_SELECTION,
     SCRAP_TEXT as SCRAP_TEXT,
+    SCROLL_ERASE as SCROLL_ERASE,
+    SCROLL_REPEAT as SCROLL_REPEAT,
     SHOWN as SHOWN,
     SRCALPHA as SRCALPHA,
     SRCCOLORKEY as SRCCOLORKEY,

buildconfig/stubs/pygame/constants.pyi

@@ -528,6 +528,8 @@ SCRAP_PBM: str
 SCRAP_PPM: str
 SCRAP_SELECTION: int
 SCRAP_TEXT: str
+SCROLL_ERASE: int
+SCROLL_REPEAT: int
 SHOWN: int
 SRCALPHA: int
 SRCCOLORKEY: int

buildconfig/stubs/pygame/locals.pyi

@@ -530,6 +530,8 @@ SCRAP_PBM: str
 SCRAP_PPM: str
 SCRAP_SELECTION: int
 SCRAP_TEXT: str
+SCROLL_ERASE: int
+SCROLL_REPEAT: int
 SHOWN: int
 SRCALPHA: int
 SRCCOLORKEY: int

buildconfig/stubs/pygame/surface.pyi

@@ -103,7 +103,9 @@ class Surface:
         rect: Optional[RectLike] = None,
         special_flags: int = 0,
     ) -> Rect: ...
-    def scroll(self, dx: int = 0, dy: int = 0, /) -> None: ...
+    def scroll(
+        self, dx: int = 0, dy: int = 0, scroll_flag: int = 0, /
+    ) -> None: ...
     @overload
     def set_colorkey(self, color: ColorLike, flags: int = 0, /) -> None: ...
     @overload

docs/reST/ref/surface.rst

@@ -316,17 +316,30 @@
 
    .. method:: scroll
 
-      | :sl:`shift the surface image in place`
-      | :sg:`scroll(dx=0, dy=0, /) -> None`
+      | :sl:`shift the Surface pixels in place`
+      | :sg:`scroll(dx=0, dy=0, scroll_flag=0, /) -> None`
 
-      Move the image by dx pixels right and dy pixels down. dx and dy may be
-      negative for left and up scrolls respectively. Areas of the surface that
-      are not overwritten retain their original pixel values. Scrolling is
-      contained by the Surface clip area. It is safe to have dx and dy values
-      that exceed the surface size.
+      Move the Surface by dx pixels right and dy pixels down. dx and dy may be
+      negative for left and up scrolls respectively.
+
+      Scrolling is contained by the Surface clip area. It is safe to have dx
+      and dy values that exceed the surface size.
+
+      The scroll flag can be:
+         * ``0`` (default): the pixels are shifted but previous pixels are
+           not modified.
+
+         * ``pygame.SCROLL_ERASE``: the space created by the shifting pixels
+           is filled with black or transparency.
+
+         * ``pygame.SCROLL_REPEAT``: the pixels that disappear out of the
+           surface or clip bounds are brought back on the opposite side
+           resulting in an infinitely scrolling and repeating surface.
 
       .. versionaddedold:: 1.9
 
+      .. versionchanged:: 2.5.3 Add repeating scroll and allow erasing pixels
+
       .. ## Surface.scroll ##
 
    .. method:: set_colorkey

src_c/_pygame.h

@@ -430,6 +430,12 @@ typedef enum {
     PGS_PREALLOC = 0x01000000
 } PygameSurfaceFlags;
 
+typedef enum {
+    PGS_SCROLL_DEFAULT = 0x00000000,
+    PGS_SCROLL_REPEAT = 0x00000001,
+    PGS_SCROLL_ERASE = 0x00000004
+} PygameScrollSurfaceFlags;
+
 #define RAISE(x, y) (PyErr_SetString((x), (y)), NULL)
 #define RAISERETURN(x, y, r)   \
     PyErr_SetString((x), (y)); \

src_c/constants.c

@@ -116,6 +116,9 @@ MODINIT_DEFINE(constants)
     DEC_CONSTSF(SHOWN);
     DEC_CONSTSF(HIDDEN);
 
+    DEC_CONSTSF(SCROLL_ERASE);
+    DEC_CONSTSF(SCROLL_REPEAT);
+
     DEC_CONSTSF(SCALED);
 
     DEC_CONST(GL_RED_SIZE);

src_c/doc/surface_doc.h

@@ -7,7 +7,7 @@
 #define DOC_SURFACE_CONVERTALPHA "convert_alpha() -> Surface\nchange the pixel format of a surface including per pixel alphas"
 #define DOC_SURFACE_COPY "copy() -> Surface\ncreate a new copy of a Surface"
 #define DOC_SURFACE_FILL "fill(color, rect=None, special_flags=0) -> Rect\nfill Surface with a solid color"
-#define DOC_SURFACE_SCROLL "scroll(dx=0, dy=0, /) -> None\nshift the surface image in place"
+#define DOC_SURFACE_SCROLL "scroll(dx=0, dy=0, scroll_flag=0, /) -> None\nshift the Surface pixels in place"
 #define DOC_SURFACE_SETCOLORKEY "set_colorkey(color, flags=0, /) -> None\nset_colorkey(None) -> None\nset the transparent colorkey"
 #define DOC_SURFACE_GETCOLORKEY "get_colorkey() -> RGBA or None\nget the current transparent colorkey"
 #define DOC_SURFACE_SETALPHA "set_alpha(value, flags=0, /) -> None\nset_alpha(None) -> None\nset the alpha value for the full Surface"