Add pygame.transform.bloom function

buildconfig/stubs/pygame/transform.pyi

@@ -1,4 +1,4 @@
-from typing import Optional, Union
+from typing import Optional, Union, Literal
 
 from pygame.color import Color
 from pygame.surface import Surface
@@ -65,3 +65,11 @@ def gaussian_blur(
     repeat_edge_pixels: bool = True,
     dest_surface: Optional[Surface] = None
 ) -> Surface: ...
+def bloom(
+    surface: Surface,
+    intensity: float = 1.0,
+    luminance_threshold: float = 0.5,
+    blur_radius: int = 5,
+    blur_type: Literal["gaussian", "box"] = "box",
+    dest_surface: Optional[Surface] = None 
+) -> Surface: ...

docs/reST/ref/transform.rst

@@ -279,6 +279,27 @@ Instead, always begin with the original image and scale to the desired size.)
 
    .. ## pygame.transform.gaussian_blur ##
 
+.. function:: bloom
+
+   | :sl:`apply the bloom effect to a surface`
+   | :sg:`bloom(surface, intensity=1, luminance_threshold=0.5, blur_radius=5, blur_type='box', dest_surface=None) -> Surface`
+
+   Returns a surface where the bright pixels are blurred and added to the original
+   surface resulting in a bloom effect.
+
+   This function does not work for indexed surfaces and for surfaces with less than
+   24 bits. An exception will be thrown if the input is an indexed surface or if it
+   has less than 24 bits.
+
+   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
+   depth and format as the source Surface.
+
+   Using box blur will be faster than gaussian blur. A higher blur radius will be
+   smoother but will be slower.
+
+   .. versionadded:: 2.5.0
+
 .. function:: average_surfaces
 
    | :sl:`find the average surface from many surfaces.`

src_c/doc/transform_doc.h

@@ -14,6 +14,7 @@
 #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"
 #define DOC_TRANSFORM_GAUSSIANBLUR "gaussian_blur(surface, radius, repeat_edge_pixels=True, dest_surface=None) -> Surface\nblur a surface using gaussian blur"
+#define DOC_TRANSFORM_BLOOM "bloom(surface, intensity=1, luminance_threshold=0.5, blur_radius=5, blur_type='box', dest_surface=None) -> Surface\napply the bloom effect to a surface"
 #define DOC_TRANSFORM_AVERAGESURFACES "average_surfaces(surfaces, dest_surface=None, palette_colors=1) -> Surface\nfind the average surface from many surfaces."
 #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"