diff --git a/buildconfig/stubs/pygame/surface.pyi b/buildconfig/stubs/pygame/surface.pyi index f3c93bdba0..0484b27b1d 100644 --- a/buildconfig/stubs/pygame/surface.pyi +++ b/buildconfig/stubs/pygame/surface.pyi @@ -150,7 +150,7 @@ class Surface: **Parameters** - ``source`` The ``Surface`` object to draw onto this ``Surface``. - If it has transparency, transparent pixels will be ignored when blittting to an 8-bit ``Surface``. + If it has transparency, transparent pixels will be ignored when blitting to an 8-bit ``Surface``. - ``dest`` *(optional)* The ``source`` draw position onto this ``Surface``, defaults to (0, 0). It can be a coordinate pair ``(x, y)`` or a ``Rect`` (using its top-left corner). @@ -271,7 +271,7 @@ class Surface: :param special_flags: the flag(s) representing the blend mode used for each Surface. See :doc:`special_flags_list` for a list of possible values. - :returns: ``None`` + :returns: ``None`` (unlike `blit()` and `blits()`) .. note:: This method only accepts a sequence of (source, dest) pairs and a single special_flags value that's applied to all Surfaces drawn. This allows faster @@ -341,6 +341,9 @@ class Surface: attributes then it should override ``copy()``. Shallow copy and deepcopy are supported, Surface implements __copy__ and __deepcopy__ respectively. + If the Surface is a subsurface, the returned Surface will *not* retain + the parent and will be a regular Surface with its own pixel data. + .. versionadded:: 2.3.1 Added support for deepcopy by implementing __deepcopy__, calls copy() internally. """ @@ -436,23 +439,23 @@ class Surface: onto a destination, the pixels will be drawn slightly transparent. The alpha value is an integer from 0 to 255, 0 is fully transparent and 255 is fully opaque. If ``None`` is passed for the alpha value, then alpha - blending will be disabled, including per-pixel alpha. - - This value is different than the per pixel Surface alpha. For a Surface - with per pixel alpha, blanket alpha is ignored and ``None`` is returned. - - .. versionchangedold:: 2.0 per-Surface alpha can be combined with per-pixel - alpha. + blending will be disabled. This full alpha is compatible with other + kinds of transparency. The optional flags argument can be set to ``pygame.RLEACCEL`` to provide better performance on non accelerated displays. An ``RLEACCEL`` Surface will be slower to modify, but quicker to blit as a source. + + .. versionchangedold:: 2.0 per-Surface alpha can be combined with per-pixel + alpha. """ def get_alpha(self) -> Optional[int]: """Get the current Surface transparency value. - Return the current alpha value for the Surface. + Return the current alpha value for the Surface, which is an integer in the + range 0 (fully transparent) - 255 (fully opaque) set by :meth:`set_alpha()`. + Until an alpha is set this method will return None. """ def lock(self) -> None: @@ -710,8 +713,8 @@ class Surface: def get_abs_parent(self) -> Surface: """Find the top level parent of a subsurface. - Returns the parent Surface of a subsurface. If this is not a subsurface - then this Surface will be returned. + Returns the top level parent Surface of a subsurface. If this is not + a subsurface then this Surface will be returned. """ def get_offset(self) -> tuple[int, int]: @@ -958,15 +961,6 @@ class Surface: """ def get_blendmode(self) -> int: ... - @property - def _pixels_address(self) -> int: - """Pixel buffer address. - - The starting address of the Surface's raw pixel bytes. - - .. versionaddedold:: 1.9.2 - """ - def premul_alpha(self) -> Surface: """Returns a copy of the Surface with the RGB channels pre-multiplied by the alpha channel. @@ -1050,5 +1044,14 @@ class Surface: .. versionadded:: 2.5.0 """ + @property + def _pixels_address(self) -> int: + """Pixel buffer address. + + The starting address of the surface's raw pixel bytes. + + .. versionaddedold:: 1.9.2 + """ + @deprecated("Use `Surface` instead (SurfaceType is an old alias)") class SurfaceType(Surface): ... diff --git a/src_c/doc/surface_doc.h b/src_c/doc/surface_doc.h index eff7fb42a3..131197c273 100644 --- a/src_c/doc/surface_doc.h +++ b/src_c/doc/surface_doc.h @@ -50,9 +50,9 @@ #define DOC_SURFACE_GETBOUNDINGRECT "get_bounding_rect(min_alpha=1) -> Rect\nFind the smallest rect containing data." #define DOC_SURFACE_GETVIEW "get_view(kind='2', /) -> BufferProxy\nReturn a buffer view of the Surface's pixels." #define DOC_SURFACE_GETBUFFER "get_buffer() -> BufferProxy\nAcquires a buffer object for the pixels of the Surface." -#define DOC_SURFACE_PIXELSADDRESS "_pixels_address -> int\nPixel buffer address." #define DOC_SURFACE_PREMULALPHA "premul_alpha() -> Surface\nReturns a copy of the Surface with the RGB channels pre-multiplied by the alpha channel." #define DOC_SURFACE_PREMULALPHAIP "premul_alpha_ip() -> Surface\nMultiplies the RGB channels by the Surface alpha channel." #define DOC_SURFACE_WIDTH "width -> int\nSurface width in pixels (read-only)." #define DOC_SURFACE_HEIGHT "height -> int\nSurface height in pixels (read-only)." #define DOC_SURFACE_SIZE "size -> tuple[int, int]\nSurface size in pixels (read-only)." +#define DOC_SURFACE_PIXELSADDRESS "_pixels_address -> int\nPixel buffer address."