Merge pull request #2670 from Matiiss/matiiss-add-mask-to_surface-area-kwarg

ankith26 · web-flow · commit 5ff6bbd791f7 · 2025-06-07T23:37:18.000+05:30
Added `area` kwarg to `mask.to_surface`
diff --git a/buildconfig/stubs/pygame/mask.pyi b/buildconfig/stubs/pygame/mask.pyi
@@ -53,6 +53,7 @@ class Mask:
         setcolor: Optional[ColorLike] = (255, 255, 255, 255),
         unsetcolor: Optional[ColorLike] = (0, 0, 0, 255),
         dest: Union[RectLike, Point] = (0, 0),
+        area: Optional[RectLike] = None,
     ) -> Surface: ...
     if sys.version_info >= (3, 12):
         def __buffer__(self, flags: int, /) -> memoryview[int]: ...
diff --git a/docs/reST/ref/mask.rst b/docs/reST/ref/mask.rst
@@ -570,7 +570,7 @@ to store which parts collide.
 
       | :sl:`Returns a surface with the mask drawn on it`
       | :sg:`to_surface() -> Surface`
-      | :sg:`to_surface(surface=None, setsurface=None, unsetsurface=None, setcolor=(255, 255, 255, 255), unsetcolor=(0, 0, 0, 255), dest=(0, 0)) -> Surface`
+      | :sg:`to_surface(surface=None, setsurface=None, unsetsurface=None, setcolor=(255, 255, 255, 255), unsetcolor=(0, 0, 0, 255), dest=(0, 0), area=None) -> Surface`
 
       Draws this mask on the given surface. Set bits (bits set to 1) and unset
       bits (bits set to 0) can be drawn onto a surface.
@@ -610,6 +610,14 @@ to store which parts collide.
          mask (i.e. position ``(0, 0)`` on the mask always corresponds to
          position ``(0, 0)`` on the ``setsurface`` and ``unsetsurface``)
       :type dest: Rect or tuple(int, int) or list(int, int) or Vector2(int, int)
+      :param area: (optional) rectangular portion of the mask to draw. It can be a
+         rect-like object (a Rect, a tuple or a list with 4 numbers or an object with a
+         rect attribute, etc) or it can be None (the default) in which case it will use the
+         entire mask. If the given rect pertrudes outside the bounds of the mask (as returned
+         by :meth:`get_rect`), it will get clipped to fit those boundaries. If the final rect
+         is smaller than the mask and no destination ``surface`` is given, the returned surface
+         will have the same size as this final rect.
+      :type area: Rect or rect-like object
 
       :returns: the ``surface`` parameter (or a newly created surface if no
          ``surface`` parameter was provided) with this mask drawn on it
diff --git a/src_c/doc/mask_doc.h b/src_c/doc/mask_doc.h
@@ -25,4 +25,4 @@
 #define DOC_MASK_MASK_CONNECTEDCOMPONENT "connected_component() -> Mask\nconnected_component(pos) -> Mask\nReturns a mask containing a connected component"
 #define DOC_MASK_MASK_CONNECTEDCOMPONENTS "connected_components() -> [Mask, ...]\nconnected_components(minimum=0) -> [Mask, ...]\nReturns a list of masks of connected components"
 #define DOC_MASK_MASK_GETBOUNDINGRECTS "get_bounding_rects() -> [Rect, ...]\nReturns a list of bounding rects of connected components"
-#define DOC_MASK_MASK_TOSURFACE "to_surface() -> Surface\nto_surface(surface=None, setsurface=None, unsetsurface=None, setcolor=(255, 255, 255, 255), unsetcolor=(0, 0, 0, 255), dest=(0, 0)) -> Surface\nReturns a surface with the mask drawn on it"
+#define DOC_MASK_MASK_TOSURFACE "to_surface() -> Surface\nto_surface(surface=None, setsurface=None, unsetsurface=None, setcolor=(255, 255, 255, 255), unsetcolor=(0, 0, 0, 255), dest=(0, 0), area=None) -> Surface\nReturns a surface with the mask drawn on it"
diff --git a/src_c/mask.c b/src_c/mask.c
@@ -1985,7 +1985,8 @@ extract_color(SDL_Surface *surf, PyObject *color_obj, Uint8 rgba_color[],
  */
 static void
 draw_to_surface(SDL_Surface *surf, bitmask_t *bitmask, int x_dest, int y_dest,
-                int draw_setbits, int draw_unsetbits, SDL_Surface *setsurf,
+                int x_area_offset, int y_area_offset, int draw_setbits,
+                int draw_unsetbits, SDL_Surface *setsurf,
                 SDL_Surface *unsetsurf, Uint32 *setcolor, Uint32 *unsetcolor)
 {
     Uint8 *pixel = NULL;
@@ -2050,10 +2051,12 @@ draw_to_surface(SDL_Surface *surf, bitmask_t *bitmask, int x_dest, int y_dest,
 
         for (y = y_start, ym = ym_start; y < y_end; ++y, ++ym) {
             pixel = (Uint8 *)surf->pixels + y * surf->pitch + x_start * bpp;
-            setpixel = (Uint8 *)setsurf->pixels + ym * setsurf->pitch +
-                       xm_start * bpp;
-            unsetpixel = (Uint8 *)unsetsurf->pixels + ym * unsetsurf->pitch +
-                         xm_start * bpp;
+            setpixel = (Uint8 *)setsurf->pixels +
+                       (y_area_offset + ym) * setsurf->pitch +
+                       (x_area_offset + xm_start) * bpp;
+            unsetpixel = (Uint8 *)unsetsurf->pixels +
+                         (y_area_offset + ym) * unsetsurf->pitch +
+                         (x_area_offset + xm_start) * bpp;
 
             for (x = x_start, xm = xm_start; x < x_end;
                  ++x, ++xm, pixel += bpp, setpixel += bpp, unsetpixel += bpp) {
@@ -2084,13 +2087,15 @@ draw_to_surface(SDL_Surface *surf, bitmask_t *bitmask, int x_dest, int y_dest,
                 draw_unsetbits && NULL != unsetsurf && unsetsurf->h > ym;
 
             if (use_setsurf) {
-                setpixel = (Uint8 *)setsurf->pixels + ym * setsurf->pitch +
-                           xm_start * bpp;
+                setpixel = (Uint8 *)setsurf->pixels +
+                           (y_area_offset + ym) * setsurf->pitch +
+                           (x_area_offset + xm_start) * bpp;
             }
 
             if (use_unsetsurf) {
                 unsetpixel = (Uint8 *)unsetsurf->pixels +
-                             ym * unsetsurf->pitch + xm_start * bpp;
+                             (y_area_offset + ym) * unsetsurf->pitch +
+                             (x_area_offset + xm_start) * bpp;
             }
 
             for (x = x_start, xm = xm_start; x < x_end;
@@ -2158,31 +2163,93 @@ mask_to_surface(PyObject *self, PyObject *args, PyObject *kwargs)
 {
     PyObject *surfobj = Py_None, *setcolorobj = NULL, *unsetcolorobj = NULL;
     PyObject *setsurfobj = Py_None, *unsetsurfobj = Py_None;
-    PyObject *destobj = NULL;
+    PyObject *destobj = NULL, *areaobj = NULL;
+    SDL_Rect *area_rect, temp_rect;
     SDL_Surface *surf = NULL, *setsurf = NULL, *unsetsurf = NULL;
-    bitmask_t *bitmask = pgMask_AsBitmap(self);
+    bitmask_t *bitmask = pgMask_AsBitmap(self), *area_bitmask;
     Uint32 *setcolor_ptr = NULL, *unsetcolor_ptr = NULL;
     Uint32 setcolor, unsetcolor;
     int draw_setbits = 0, draw_unsetbits = 0;
     int created_surfobj = 0; /* Set to 1 if this func creates the surfobj. */
     int x_dest = 0, y_dest = 0; /* Default destination coordinates. */
     Uint8 dflt_setcolor[] = {255, 255, 255, 255}; /* Default set color. */
     Uint8 dflt_unsetcolor[] = {0, 0, 0, 255};     /* Default unset color. */
+    int create_area_bitmask = 0;
 
     static char *keywords[] = {"surface",  "setsurface", "unsetsurface",
                                "setcolor", "unsetcolor", "dest",
-                               NULL};
+                               "area",     NULL};
 
-    if (!PyArg_ParseTupleAndKeywords(args, kwargs, "|OOOOOO", keywords,
-                                     &surfobj, &setsurfobj, &unsetsurfobj,
-                                     &setcolorobj, &unsetcolorobj, &destobj)) {
+    if (!PyArg_ParseTupleAndKeywords(
+            args, kwargs, "|OOOOOOO", keywords, &surfobj, &setsurfobj,
+            &unsetsurfobj, &setcolorobj, &unsetcolorobj, &destobj, &areaobj)) {
         return NULL; /* Exception already set. */
     }
 
+    if (NULL != destobj) {
+        int tempx = 0, tempy = 0;
+
+        /* Destination coordinates can be extracted from:
+         * - lists/tuples with 2 items
+         * - Rect (or Rect like) objects (uses x, y values) */
+        if (pg_TwoIntsFromObj(destobj, &tempx, &tempy)) {
+            x_dest = tempx;
+            y_dest = tempy;
+        }
+        else {
+            SDL_Rect temp_rect;
+            SDL_Rect *dest_rect = pgRect_FromObject(destobj, &temp_rect);
+
+            if (NULL != dest_rect) {
+                x_dest = dest_rect->x;
+                y_dest = dest_rect->y;
+            }
+            else {
+                PyErr_SetString(PyExc_TypeError, "invalid dest argument");
+                goto to_surface_error;
+            }
+        }
+    }
+
+    if (areaobj && areaobj != Py_None) {
+        if (!(area_rect = pgRect_FromObject(areaobj, &temp_rect))) {
+            PyErr_SetString(PyExc_TypeError, "invalid rectstyle argument");
+            goto to_surface_error;
+        }
+
+        memcpy(&temp_rect, area_rect, sizeof(temp_rect));
+        area_rect = &temp_rect;
+
+        pgRect_Normalize(area_rect);
+
+        if (area_rect->x < 0) {
+            // x_dest -= area_rect->x;
+            area_rect->w += area_rect->x;
+            area_rect->x = 0;
+        }
+        if (area_rect->y < 0) {
+            // y_dest -= area_rect->y;
+            area_rect->h += area_rect->y;
+            area_rect->y = 0;
+        }
+
+        // clamp rect width and height to not stick out of the mask
+        area_rect->w = MAX(MIN(area_rect->w, bitmask->w - area_rect->x), 0);
+        area_rect->h = MAX(MIN(area_rect->h, bitmask->h - area_rect->y), 0);
+
+        create_area_bitmask = 1;
+    }
+    else {
+        temp_rect.x = temp_rect.y = 0;
+        temp_rect.w = bitmask->w;
+        temp_rect.h = bitmask->h;
+        area_rect = &temp_rect;
+    }
+
     if (Py_None == surfobj) {
-        surfobj =
-            PyObject_CallFunction((PyObject *)&pgSurface_Type, "(ii)ii",
-                                  bitmask->w, bitmask->h, PGS_SRCALPHA, 32);
+        surfobj = PyObject_CallFunction((PyObject *)&pgSurface_Type, "(ii)ii",
+                                        area_rect->w, area_rect->h,
+                                        PGS_SRCALPHA, 32);
 
         if (NULL == surfobj) {
             if (!PyErr_Occurred()) {
@@ -2266,31 +2333,6 @@ mask_to_surface(PyObject *self, PyObject *args, PyObject *kwargs)
         draw_unsetbits = 1;
     }
 
-    if (NULL != destobj) {
-        int tempx = 0, tempy = 0;
-
-        /* Destination coordinates can be extracted from:
-         * - lists/tuples with 2 items
-         * - Rect (or Rect like) objects (uses x, y values) */
-        if (pg_TwoIntsFromObj(destobj, &tempx, &tempy)) {
-            x_dest = tempx;
-            y_dest = tempy;
-        }
-        else {
-            SDL_Rect temp_rect;
-            SDL_Rect *dest_rect = pgRect_FromObject(destobj, &temp_rect);
-
-            if (NULL != dest_rect) {
-                x_dest = dest_rect->x;
-                y_dest = dest_rect->y;
-            }
-            else {
-                PyErr_SetString(PyExc_TypeError, "invalid dest argument");
-                goto to_surface_error;
-            }
-        }
-    }
-
     if (!pgSurface_Lock((pgSurfaceObject *)surfobj)) {
         PyErr_SetString(PyExc_RuntimeError, "cannot lock surface");
         goto to_surface_error;
@@ -2311,14 +2353,32 @@ mask_to_surface(PyObject *self, PyObject *args, PyObject *kwargs)
         goto to_surface_error;
     }
 
+    if (create_area_bitmask) {
+        area_bitmask = bitmask_create(area_rect->w, area_rect->h);
+        if (NULL == area_bitmask) {
+            PyErr_Format(PyExc_MemoryError,
+                         "failed to allocate memory for a mask");
+            return NULL;
+        }
+
+        bitmask_draw(area_bitmask, bitmask, -area_rect->x, -area_rect->y);
+    }
+    else {
+        area_bitmask = bitmask;
+    }
+
     Py_BEGIN_ALLOW_THREADS; /* Release the GIL. */
 
-    draw_to_surface(surf, bitmask, x_dest, y_dest, draw_setbits,
-                    draw_unsetbits, setsurf, unsetsurf, setcolor_ptr,
-                    unsetcolor_ptr);
+    draw_to_surface(surf, area_bitmask, x_dest, y_dest, area_rect->x,
+                    area_rect->y, draw_setbits, draw_unsetbits, setsurf,
+                    unsetsurf, setcolor_ptr, unsetcolor_ptr);
 
     Py_END_ALLOW_THREADS; /* Obtain the GIL. */
 
+    if (create_area_bitmask) {
+        bitmask_free(area_bitmask);
+    }
+
     if (NULL != unsetsurf &&
         !pgSurface_Unlock((pgSurfaceObject *)unsetsurfobj)) {
         PyErr_SetString(PyExc_RuntimeError, "cannot unlock unsetsurface");
diff --git a/test/mask_test.py b/test/mask_test.py
