Allow erasing pixels in pygame.Surface.scroll and add repeat function…

…ality (#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 <[email protected]> * 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 <[email protected]> Co-authored-by: Dan Lawrence <[email protected]>
pygame-community · Oct 18, 2024 · 120675a · 120675a
1 parent a5002cf
commit 120675a
Show file tree

Hide file tree

Showing 10 changed files with 302 additions and 132 deletions.
diff --git a/buildconfig/stubs/pygame/__init__.pyi b/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,

diff --git a/buildconfig/stubs/pygame/constants.pyi b/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

diff --git a/buildconfig/stubs/pygame/locals.pyi b/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

diff --git a/buildconfig/stubs/pygame/surface.pyi b/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

diff --git a/docs/reST/ref/surface.rst b/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

diff --git a/src_c/_pygame.h b/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)); \

diff --git a/src_c/constants.c b/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);

diff --git a/src_c/doc/surface_doc.h b/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"