From c507028366d842022a79691e22bbc770dd815e99 Mon Sep 17 00:00:00 2001 From: Charlie Hayden <46412508+Starbuck5@users.noreply.github.com> Date: Mon, 26 Aug 2024 05:49:33 -0700 Subject: [PATCH] Fix average_color docs and stubs to match implementation (#3076) * Fix average_color docs and stubs to match implementation * Use RGBATuple for average_color and don't use it when it's not an RGBA tuple. --- buildconfig/stubs/pygame/display.pyi | 7 +++---- buildconfig/stubs/pygame/surface.pyi | 6 +++--- buildconfig/stubs/pygame/transform.pyi | 5 ++--- docs/reST/ref/transform.rst | 7 ++++--- src_c/doc/transform_doc.h | 2 +- 5 files changed, 13 insertions(+), 14 deletions(-) diff --git a/buildconfig/stubs/pygame/display.pyi b/buildconfig/stubs/pygame/display.pyi index eb9f29a5c1..0acf086e99 100644 --- a/buildconfig/stubs/pygame/display.pyi +++ b/buildconfig/stubs/pygame/display.pyi @@ -11,7 +11,6 @@ from pygame.typing import ( Coordinate, IntCoordinate, RectLike, - RGBATuple, SequenceLike, ) @@ -21,9 +20,9 @@ class _VidInfo: video_mem: int bitsize: int bytesize: int - masks: RGBATuple - shifts: RGBATuple - losses: RGBATuple + masks: Tuple[int, int, int, int] + shifts: Tuple[int, int, int, int] + losses: Tuple[int, int, int, int] blit_hw: int blit_hw_CC: int blit_hw_A: int diff --git a/buildconfig/stubs/pygame/surface.pyi b/buildconfig/stubs/pygame/surface.pyi index 03bb9360db..df6c2819ad 100644 --- a/buildconfig/stubs/pygame/surface.pyi +++ b/buildconfig/stubs/pygame/surface.pyi @@ -152,13 +152,13 @@ class Surface: def get_bytesize(self) -> int: ... def get_flags(self) -> int: ... def get_pitch(self) -> int: ... - def get_masks(self) -> RGBATuple: ... + def get_masks(self) -> Tuple[int, int, int, int]: ... @deprecated("since 2.0.0. Immutable in SDL2") def set_masks(self, color: ColorLike, /) -> None: ... - def get_shifts(self) -> RGBATuple: ... + def get_shifts(self) -> Tuple[int, int, int, int]: ... @deprecated("since 2.0.0. Immutable in SDL2") def set_shifts(self, color: ColorLike, /) -> None: ... - def get_losses(self) -> RGBATuple: ... + def get_losses(self) -> Tuple[int, int, int, int]: ... def get_bounding_rect(self, min_alpha: int = 1) -> Rect: ... def get_view(self, kind: _ViewKind = "2", /) -> BufferProxy: ... def get_buffer(self) -> BufferProxy: ... diff --git a/buildconfig/stubs/pygame/transform.pyi b/buildconfig/stubs/pygame/transform.pyi index 64a6fabf16..76c58c6dac 100644 --- a/buildconfig/stubs/pygame/transform.pyi +++ b/buildconfig/stubs/pygame/transform.pyi @@ -1,9 +1,8 @@ from typing import Optional, Union, Literal -from pygame.color import Color from pygame.surface import Surface -from pygame.typing import ColorLike, Coordinate, RectLike, SequenceLike +from pygame.typing import ColorLike, Coordinate, RectLike, SequenceLike, RGBATuple def flip(surface: Surface, flip_x: bool, flip_y: bool) -> Surface: ... def scale( @@ -42,7 +41,7 @@ def average_surfaces( ) -> Surface: ... def average_color( surface: Surface, rect: Optional[RectLike] = None, consider_alpha: bool = False -) -> Color: ... +) -> RGBATuple: ... def threshold( dest_surface: Optional[Surface], surface: Surface, diff --git a/docs/reST/ref/transform.rst b/docs/reST/ref/transform.rst index 9c6f0111d0..926a304e42 100644 --- a/docs/reST/ref/transform.rst +++ b/docs/reST/ref/transform.rst @@ -306,11 +306,12 @@ Instead, always begin with the original image and scale to the desired size.) .. function:: average_color | :sl:`finds the average color of a surface` - | :sg:`average_color(surface, rect=None, consider_alpha=False) -> Color` + | :sg:`average_color(surface, rect=None, consider_alpha=False) -> tuple` Finds the average color of a Surface or a region of a surface specified by a - Rect, and returns it as a Color. If consider_alpha is set to True, then alpha is - taken into account (removing the black artifacts). + Rect, and returns it as a tuple of integers red, green, blue, and alpha. + If consider_alpha is set to True, then alpha is taken into account + (removing the black artifacts). .. versionaddedold:: 2.1.2 ``consider_alpha`` argument diff --git a/src_c/doc/transform_doc.h b/src_c/doc/transform_doc.h index 7707ef7c8d..cf51b9a57b 100644 --- a/src_c/doc/transform_doc.h +++ b/src_c/doc/transform_doc.h @@ -15,7 +15,7 @@ #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_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_AVERAGECOLOR "average_color(surface, rect=None, consider_alpha=False) -> tuple\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_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'."