pygame.transform.pixelate

buildconfig/stubs/pygame/transform.pyi

@@ -35,6 +35,11 @@ def set_smoothscale_backend(backend: str) -> None: ...
 def chop(surface: Surface, rect: RectValue) -> Surface: ...
 def laplacian(surface: Surface, dest_surface: Optional[Surface] = None) -> Surface: ...
 def invert(surface: Surface, dest_surface: Optional[Surface] = None) -> Surface: ...
+def pixelate(
+    surface: Surface,
+    pixel_size: int,
+    dest_surface: Optional[Surface] = None
+) -> Surface: ...
 def average_surfaces(
     surfaces: Sequence[Surface],
     dest_surface: Optional[Surface] = None,

docs/reST/ref/transform.rst

@@ -336,6 +336,21 @@ Instead, always begin with the original image and scale to the desired size.)
 
    .. ## pygame.transform.grayscale ##
 
+.. function:: pixelate
+
+   | :sl:`pixelate a surface`
+   | :sg:`pixelate(surface, pixel_size, dest_surface=None) -> Surface`
+
+   Returns a pixelated version of the original surface.
+
+   ``pixel_size`` is an integer describing how large you want the pixels in the final pixelated image to be.
+   An optional destination surface can be passed which is faster than creating a new Surface. This destination
+   surface must have the same dimensions (width, height) and smae depth as the source surface.
+
+   .. versionadded:: 2.4.0
+
+   .. ## pygame.transform.pixelate ##
+
 .. function:: threshold
 
    | :sl:`finds which, and how many pixels in a surface are within a threshold of a 'search_color' or a 'search_surf'.`

src_c/doc/transform_doc.h

@@ -18,4 +18,5 @@
 #define DOC_TRANSFORM_AVERAGECOLOR "average_color(surface, rect=None, consider_alpha=False) -> Color\nfinds the average color of a surface"
 #define DOC_TRANSFORM_INVERT "invert(surface, dest_surface=None) -> Surface\ninverts the RGB elements of a surface"
 #define DOC_TRANSFORM_GRAYSCALE "grayscale(surface, dest_surface=None) -> Surface\ngrayscale a surface"
+#define DOC_TRANSFORM_PIXELATE "pixelate(surface, pixel_size, dest_surface=None) -> Surface\npixelate a surface"
 #define DOC_TRANSFORM_THRESHOLD "threshold(dest_surface, surface, search_color, threshold=(0,0,0,0), set_color=(0,0,0,0), set_behavior=1, search_surf=None, inverse_set=False) -> num_threshold_pixels\nfinds which, and how many pixels in a surface are within a threshold of a 'search_color' or a 'search_surf'."

src_c/transform.c

@@ -3353,6 +3353,118 @@ surf_invert(PyObject *self, PyObject *args, PyObject *kwargs)
     return (PyObject *)pgSurface_New(newsurf);
 }
 
+SDL_Surface *
+pixelate(pgSurfaceObject *srcobj, pgSurfaceObject *dstobj, int pixel_size)
+{
+    SDL_Surface *src = pgSurface_AsSurface(srcobj);
+    SDL_Surface *newsurf;
+
+    if (!dstobj) {
+        newsurf = newsurf_fromsurf(src, srcobj->surf->w, srcobj->surf->h);
+        if (!newsurf)
+            return NULL;
+    }
+    else {
+        newsurf = pgSurface_AsSurface(dstobj);
+    }
+
+    if (pixel_size < 1) {
+        return (SDL_Surface *)(RAISE(PyExc_ValueError,
+                                     "pixel_size must be greater than 0."));
+    }
+
+    if (newsurf->w != src->w || newsurf->h != src->h) {
+        return (SDL_Surface *)(RAISE(
+            PyExc_ValueError,
+            "Destination surface must be the same size as source surface."));
+    }
+
+    if (src->format->BytesPerPixel != newsurf->format->BytesPerPixel) {
+        return (SDL_Surface *)(RAISE(
+            PyExc_ValueError,
+            "Source and destination surfaces need the same format."));
+    }
+
+    int x, y;
+    for (y = 0; y < src->h; y += pixel_size) {
+        for (x = 0; x < src->w; x += pixel_size) {
+            unsigned char r, g, b, a;  // current
+            Uint32 ra, ga, ba, aa;     // averages
+            Uint16 size;
+            Uint32 color, average;
+            Uint8 *pix;
+            int width = (pixel_size > (src->w - x)) ? src->w - x : pixel_size;
+            int height = (pixel_size > (src->h - y)) ? src->h - y : pixel_size;
+
+            ra = 0;
+            ga = 0;
+            ba = 0;
+            aa = 0;
+            for (int w = 0; w < width; w++) {
+                for (int h = 0; h < height; h++) {
+                    SURF_GET_AT(color, src, x + w, y + h, (Uint8 *)src->pixels,
+                                src->format, pix);
+                    SDL_GetRGBA(color, src->format, &r, &g, &b, &a);
+                    ra += r;
+                    ga += g;
+                    ba += b;
+                    aa += a;
+                }
+            }
+            size = width * height;
+
+            average = SDL_MapRGBA(newsurf->format, (Uint8)(ra / size),
+                                  (Uint8)(ga / size), (Uint8)(ba / size),
+                                  (Uint8)(aa / size));
+
+            for (int w = 0; w < width; w++) {
+                for (int h = 0; h < height; h++) {
+                    SURF_SET_AT(average, newsurf, x + w, y + h,
+                                (Uint8 *)newsurf->pixels, newsurf->format,
+                                pix);
+                }
+            }
+        }
+    }
+
+    SDL_UnlockSurface(newsurf);
+
+    return newsurf;
+}
+
+/*
+ * anticipated API: pygame.transform.pixelate(surface, pixel_size, dest_surface
+ * = None)
+ */
+static PyObject *
+surf_pixelate(PyObject *self, PyObject *args, PyObject *kwargs)
+{
+    pgSurfaceObject *src;
+    pgSurfaceObject *dst = NULL;
+    int pixel_size;
+    SDL_Surface *new_surf;
+
+    static char *kwds[] = {"surface", "pixel_size", "dest_surface", NULL};
+
+    if (!PyArg_ParseTupleAndKeywords(args, kwargs, "O!i|O!", kwds,
+                                     &pgSurface_Type, &src, &pixel_size,
+                                     &pgSurface_Type, &dst)) {
+        return NULL;
+    }
+
+    new_surf = pixelate(src, dst, pixel_size);
+
+    if (!new_surf) {
+        return NULL;
+    }
+
+    if (dst) {
+        Py_INCREF(dst);
+        return (PyObject *)dst;
+    }
+    return (PyObject *)pgSurface_New(new_surf);
+}
+
 static PyMethodDef _transform_methods[] = {
     {"scale", (PyCFunction)surf_scale, METH_VARARGS | METH_KEYWORDS,
      DOC_TRANSFORM_SCALE},
@@ -3392,6 +3504,8 @@ static PyMethodDef _transform_methods[] = {
      DOC_TRANSFORM_INVERT},
     {"grayscale", (PyCFunction)surf_grayscale, METH_VARARGS | METH_KEYWORDS,
      DOC_TRANSFORM_GRAYSCALE},
+    {"pixelate", (PyCFunction)surf_pixelate, METH_VARARGS | METH_KEYWORDS,
+     DOC_TRANSFORM_PIXELATE},
     {NULL, NULL, 0, NULL}};
 
 MODINIT_DEFINE(transform)