Add skew functionality to pygame.transform

buildconfig/stubs/pygame/transform.pyi

@@ -16,6 +16,13 @@ def scale_by(
     dest_surface: Optional[Surface] = None,
 ) -> Surface: ...
 def rotate(surface: Surface, angle: float) -> Surface: ...
+def skew(
+    surface: Surface,
+    points: SequenceLike[Point],
+    bg_color: Optional[ColorLike] = None,
+    adjust_size: bool = True,
+    dest_surface: Optional[Surface] = None,
+) -> Surface: ...
 def rotozoom(surface: Surface, angle: float, scale: float) -> Surface: ...
 def scale2x(surface: Surface, dest_surface: Optional[Surface] = None) -> Surface: ...
 def grayscale(surface: Surface, dest_surface: Optional[Surface] = None) -> Surface: ...
@@ -62,13 +69,13 @@ def box_blur(
     surface: Surface,
     radius: int,
     repeat_edge_pixels: bool = True,
-    dest_surface: Optional[Surface] = None
+    dest_surface: Optional[Surface] = None,
 ) -> Surface: ...
 def gaussian_blur(
     surface: Surface,
     radius: int,
     repeat_edge_pixels: bool = True,
-    dest_surface: Optional[Surface] = None
+    dest_surface: Optional[Surface] = None,
 ) -> Surface: ...
 def hsl(
     surface: Surface,

docs/reST/ref/transform.rst

@@ -101,6 +101,31 @@ Instead, always begin with the original image and scale to the desired size.)
 
    .. ## pygame.transform.rotozoom ##
 
+.. function:: skew
+
+   | :sl:`skew an image to specified points`
+   | :sg:`skew(surface, points, bg_color=None, adjust_size=True, dest_surface=None)`
+
+   This maps an image to a new surface warping the image so that its corners
+   match the provided points in a clockwise order: top left, top right, bottom
+   right, bottom left. Provided points represent the pixel coordinates of the
+   new corners of the image, they must be unique and can be positive or negative
+   provided they fit in the new surface.
+
+   When no 'dest_surface' is provided, the 'adjust_size' option will set the
+   size of the resulting surface to be the smallest surface the points are
+   capable of fitting in, if false it will use the original size of the
+   provided surface.
+
+   If 'bg_color' is not provided then it will select a color to use based on
+   the surface. If the image has pixel alphas, the padded area will be
+   transparent. Otherwise pygame will pick a color that matches the Surface
+   colorkey or the top left pixel value.
+
+   .. versionadded:: 2.5.2
+
+   .. ## pygame.transform.skew ##
+
 .. function:: scale2x
 
    | :sl:`specialized image doubler`

src_c/doc/transform_doc.h

@@ -5,6 +5,7 @@
 #define DOC_TRANSFORM_SCALEBY "scale_by(surface, factor, dest_surface=None) -> Surface\nresize to new resolution, using scalar(s)"
 #define DOC_TRANSFORM_ROTATE "rotate(surface, angle) -> Surface\nrotate an image"
 #define DOC_TRANSFORM_ROTOZOOM "rotozoom(surface, angle, scale) -> Surface\nfiltered scale and rotation"
+#define DOC_TRANSFORM_SKEW "skew(surface, points, bg_color=None, adjust_size=True, dest_surface=None)\nskew an image to specified points"
 #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)"