Smoothscale: deprecate old backends, update docs

docs/reST/ref/examples.rst

@@ -287,8 +287,8 @@ pygame much earlier.
    Thumbnail generation with scaling is an example of what you can do with
    pygame.
 
-   ``NOTE``: the pygame scale function uses MMX/SSE if available, and can be
-   run in multiple threads.
+   ``NOTE``: the pygame scale function uses SIMD acceleration if available, 
+   and can be run in multiple threads.
 
    If ``headless_no_windows_needed.py`` is run as a program it takes the
    following command line arguments:

docs/reST/ref/transform.rst

@@ -127,19 +127,20 @@ Instead, always begin with the original image and scale to the desired size.)
 
    Uses one of two different algorithms for scaling each dimension of the input
    surface as required. For shrinkage, the output pixels are area averages of
-   the colors they cover. For expansion, a bilinear filter is used. For the
-   x86-64 and i686 architectures, optimized ``MMX`` routines are included and
-   will run much faster than other machine types. The size is a 2 number
-   sequence for (width, height). This function only works for 24-bit or 32-bit
-   surfaces. An exception will be thrown if the input surface bit depth is less
-   than 24.
+   the colors they cover. The size is a 2 number sequence for (width, height). 
+   This function only works for 24-bit or 32-bit surfaces. A ``ValueError`` will
+   be thrown if the input surface bit depth is less than 24.
 
    An optional destination surface can be passed which is faster than creating a new
    Surface. This destination surface must be the same as the size (width, height) passed
    in, and the same depth and format as the source Surface.
 
    .. versionaddedold:: 1.8
 
+   .. versionchanged:: 2.4.0 now uses SSE2/NEON SIMD for acceleration on x86
+      and ARM machines, a performance improvement over previous MMX/SSE only 
+      supported on x86.
+
    .. ## pygame.transform.smoothscale ##
 
 .. function:: smoothscale_by
@@ -165,31 +166,34 @@ Instead, always begin with the original image and scale to the desired size.)
 
 .. function:: get_smoothscale_backend
 
-   | :sl:`return smoothscale filter version in use: 'GENERIC', 'MMX', or 'SSE'`
+   | :sl:`return smoothscale filter version in use: 'GENERIC', 'MMX', 'SSE', 'SSE2', or 'NEON'`
    | :sg:`get_smoothscale_backend() -> string`
 
-   Shows whether or not smoothscale is using ``MMX`` or ``SSE`` acceleration.
-   If no acceleration is available then "GENERIC" is returned. For a x86
-   processor the level of acceleration to use is determined at runtime.
+   Shows whether or not smoothscale is using SIMD accleration.
+   If no acceleration is available then "GENERIC" is returned. The level of
+   acceleration possible is automatically determined at runtime.
 
    This function is provided for pygame testing and debugging.
 
+   .. versionchanged:: 2.4.0 Added SSE2 and NEON backends, MMX and SSE are deprecated.
+
    .. ## pygame.transform.get_smoothscale_backend ##
 
 .. function:: set_smoothscale_backend
 
-   | :sl:`set smoothscale filter version to one of: 'GENERIC', 'MMX', or 'SSE'`
+   | :sl:`set smoothscale filter version to one of: 'GENERIC', 'MMX', 'SSE', 'SSE2', or 'NEON'`
    | :sg:`set_smoothscale_backend(backend) -> None`
 
    Sets smoothscale acceleration. Takes a string argument. A value of 'GENERIC'
-   turns off acceleration. 'MMX' uses ``MMX`` instructions only. 'SSE' allows
-   ``SSE`` extensions as well. A value error is raised if type is not
+   turns off acceleration. A value error is raised if type is not
    recognized or not supported by the current processor.
 
    This function is provided for pygame testing and debugging. If smoothscale
    causes an invalid instruction error then it is a pygame/SDL bug that should
    be reported. Use this function as a temporary fix only.
 
+   .. versionchanged:: 2.4.0 Added SSE2 and NEON backends, MMX and SSE are deprecated.
+
    .. ## pygame.transform.set_smoothscale_backend ##
 
 .. function:: chop

src_c/doc/transform_doc.h

@@ -8,8 +8,8 @@
 #define DOC_TRANSFORM_SCALE2X "scale2x(surface, dest_surface=None) -> Surface\nspecialized image doubler"
 #define DOC_TRANSFORM_SMOOTHSCALE "smoothscale(surface, size, dest_surface=None) -> Surface\nscale a surface to an arbitrary size smoothly"
 #define DOC_TRANSFORM_SMOOTHSCALEBY "smoothscale_by(surface, factor, dest_surface=None) -> Surface\nresize to new resolution, using scalar(s)"
-#define DOC_TRANSFORM_GETSMOOTHSCALEBACKEND "get_smoothscale_backend() -> string\nreturn smoothscale filter version in use: 'GENERIC', 'MMX', or 'SSE'"
-#define DOC_TRANSFORM_SETSMOOTHSCALEBACKEND "set_smoothscale_backend(backend) -> None\nset smoothscale filter version to one of: 'GENERIC', 'MMX', or 'SSE'"
+#define DOC_TRANSFORM_GETSMOOTHSCALEBACKEND "get_smoothscale_backend() -> string\nreturn smoothscale filter version in use: 'GENERIC', 'MMX', 'SSE', 'SSE2', or 'NEON'"
+#define DOC_TRANSFORM_SETSMOOTHSCALEBACKEND "set_smoothscale_backend(backend) -> None\nset smoothscale filter version to one of: 'GENERIC', 'MMX', 'SSE', 'SSE2', or 'NEON'"
 #define DOC_TRANSFORM_CHOP "chop(surface, rect) -> Surface\ngets a copy of an image with an interior area removed"
 #define DOC_TRANSFORM_LAPLACIAN "laplacian(surface, dest_surface=None) -> Surface\nfind edges in a surface"
 #define DOC_TRANSFORM_BOXBLUR "box_blur(surface, radius, repeat_edge_pixels=True, dest_surface=None) -> Surface\nblur a surface using box blur"

src_c/transform.c

@@ -1590,6 +1590,12 @@ surf_set_smoothscale_backend(PyObject *self, PyObject *args, PyObject *kwargs)
             return RAISE(PyExc_ValueError,
                          "MMX not supported on this machine");
         }
+        if (PyErr_WarnEx(
+                PyExc_DeprecationWarning,
+                "MMX backend is deprecated in favor of new SSE2 backend",
+                1) == -1) {
+            return NULL;
+        }
         st->filter_type = "MMX";
         st->filter_shrink_X = filter_shrink_X_MMX;
         st->filter_shrink_Y = filter_shrink_Y_MMX;
@@ -1601,6 +1607,12 @@ surf_set_smoothscale_backend(PyObject *self, PyObject *args, PyObject *kwargs)
             return RAISE(PyExc_ValueError,
                          "SSE not supported on this machine");
         }
+        if (PyErr_WarnEx(
+                PyExc_DeprecationWarning,
+                "SSE backend is deprecated in favor of new SSE2 backend",
+                1) == -1) {
+            return NULL;
+        }
         st->filter_type = "SSE";
         st->filter_shrink_X = filter_shrink_X_SSE;
         st->filter_shrink_Y = filter_shrink_Y_SSE;

test/transform_test.py

@@ -1238,6 +1238,14 @@ def change():
         filter_type = pygame.transform.get_smoothscale_backend()
         self.assertEqual(filter_type, original_type)
 
+        try:
+            with self.assertWarns(DeprecationWarning):
+                pygame.transform.set_smoothscale_backend("MMX")
+            with self.assertWarns(DeprecationWarning):
+                pygame.transform.set_smoothscale_backend("SSE")
+        except ValueError:
+            pass  # Backends not supported on this CPU, also valid
+
     def test_chop(self):
         original_surface = pygame.Surface((20, 20))
         pygame.draw.rect(original_surface, (255, 0, 0), (0, 0, 10, 10))