From 99dbbb3457a18aedebf87bb7df282b3eb4216f02 Mon Sep 17 00:00:00 2001 From: damusss Date: Wed, 8 Oct 2025 10:37:46 +0200 Subject: [PATCH 1/3] Minor improvements --- buildconfig/stubs/pygame/surface.pyi | 185 ++++++++++++++------------- src_c/doc/surface_doc.h | 14 +- 2 files changed, 105 insertions(+), 94 deletions(-) diff --git a/buildconfig/stubs/pygame/surface.pyi b/buildconfig/stubs/pygame/surface.pyi index bf5b52e831..a20bca5e44 100644 --- a/buildconfig/stubs/pygame/surface.pyi +++ b/buildconfig/stubs/pygame/surface.pyi @@ -143,14 +143,14 @@ class Surface: area: Optional[RectLike] = None, special_flags: int = 0, ) -> Rect: - """Draw another surface onto this one. + """Draw another Surface onto this one. Draws another Surface onto this 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). @@ -158,7 +158,7 @@ class Surface: - ``area`` *(optional)* The rectangular portion of the ``source`` to draw. It can be a ``Rect`` object representing that section. If ``None`` or not provided, - the entire source surface will be drawn. + the entire source Surface will be drawn. If the ``Rect`` has negative position, the final blit position will be ``dest`` - ``Rect.topleft``. - ``special_flags`` *(optional)* @@ -176,11 +176,11 @@ class Surface: **Example Use** .. code-block:: python - # create a surface of size 50x50 and fill it with red color + # create a Surface of size 50x50 and fill it with red color red_surf = pygame.Surface((50, 50)) red_surf.fill("red") - # draw the surface on another surface at position (0, 0) + # draw the Surface on another Surface at position (0, 0) another_surface.blit(red_surf, (0, 0)) **Notes** @@ -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 regular blitting) .. 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 was 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,7 +439,8 @@ 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. + blending will be disabled. This full alpha is compatible with other + kinds of transparency. 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. @@ -447,80 +451,19 @@ class Surface: 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. - """ - - def lock(self) -> None: - """Lock the Surface memory for pixel access. - - Lock the pixel data of a Surface for access. On accelerated Surfaces, the - pixel data may be stored in volatile video memory or nonlinear compressed - forms. When a Surface is locked the pixel memory becomes available to - access by regular software. Code that reads or writes pixel values will - need the Surface to be locked. - - Surfaces should not remain locked for more than necessary. A locked - Surface can often not be displayed or managed by pygame. - - Not all Surfaces require locking. The :meth:`mustlock()` method can - determine if it is actually required. There is no performance penalty for - locking and unlocking a Surface that does not need it. - - All pygame functions will automatically lock and unlock the Surface data - as needed. If a section of code is going to make calls that will - repeatedly lock and unlock the Surface many times, it can be helpful to - wrap the block inside a lock and unlock pair. - - It is safe to nest locking and unlocking calls. The surface will only be - unlocked after the final lock is released. - """ - - def unlock(self) -> None: - """Unlock the Surface memory from pixel access. - - Unlock the Surface pixel data after it has been locked. The unlocked - Surface can once again be drawn and managed by pygame. See the - :meth:`lock()` documentation for more details. - - All pygame functions will automatically lock and unlock the Surface data - as needed. If a section of code is going to make calls that will - repeatedly lock and unlock the Surface many times, it can be helpful to - wrap the block inside a lock and unlock pair. - - It is safe to nest locking and unlocking calls. The surface will only be - unlocked after the final lock is released. - """ - - def mustlock(self) -> bool: - """Test if the Surface requires locking. - - Returns ``True`` if the Surface is required to be locked to access pixel - data. Usually pure software Surfaces do not require locking. This method - is rarely needed, since it is safe and quickest to just lock all Surfaces - as needed. - - All pygame functions will automatically lock and unlock the Surface data - as needed. If a section of code is going to make calls that will - repeatedly lock and unlock the Surface many times, it can be helpful to - wrap the block inside a lock and unlock pair. - """ - - def get_locked(self) -> bool: - """Test if the Surface is current locked. - - Returns ``True`` when the Surface is locked. It doesn't matter how many - times the Surface is locked. - """ - - def get_locks(self) -> tuple[Any, ...]: - """Gets the locks for the Surface. - - Returns the currently existing locks for the Surface. + Return the current alpha value for the Surface. If the blendmode of the + Surface is not ``pygame.BLENDMODE_NONE``, this method will always return + a valid value in the range 0 (fully transparent) - 255 (fully opaque). + Otherwise, this method will return None until an alpha is set with + :meth:`set_alpha()` (the set alpha value will be returned). """ def get_at(self, x_y: Point, /) -> Color: @@ -710,8 +653,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 +901,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. @@ -1024,6 +958,74 @@ class Surface: .. versionadded:: 2.5.1 """ + def lock(self) -> None: + """Lock the Surface memory for pixel access. + + Lock the pixel data of a Surface for access. On accelerated Surfaces, the + pixel data may be stored in volatile video memory or nonlinear compressed + forms. When a Surface is locked the pixel memory becomes available to + access by regular software. Code that reads or writes pixel values will + need the Surface to be locked. + + Surfaces should not remain locked for more than necessary. A locked + Surface can often not be displayed or managed by pygame. + + Not all Surfaces require locking. The :meth:`mustlock()` method can + determine if it is actually required. There is no performance penalty for + locking and unlocking a Surface that does not need it. + + All pygame functions will automatically lock and unlock the Surface data + as needed. If a section of code is going to make calls that will + repeatedly lock and unlock the Surface many times, it can be helpful to + wrap the block inside a lock and unlock pair. + + It is safe to nest locking and unlocking calls. The surface will only be + unlocked after the final lock is released. + """ + + def unlock(self) -> None: + """Unlock the Surface memory from pixel access. + + Unlock the Surface pixel data after it has been locked. The unlocked + Surface can once again be drawn and managed by pygame. See the + :meth:`lock()` documentation for more details. + + All pygame functions will automatically lock and unlock the Surface data + as needed. If a section of code is going to make calls that will + repeatedly lock and unlock the Surface many times, it can be helpful to + wrap the block inside a lock and unlock pair. + + It is safe to nest locking and unlocking calls. The surface will only be + unlocked after the final lock is released. + """ + + def mustlock(self) -> bool: + """Test if the Surface requires locking. + + Returns ``True`` if the Surface is required to be locked to access pixel + data. Usually pure software Surfaces do not require locking. This method + is rarely needed, since it is safe and quickest to just lock all Surfaces + as needed. + + All pygame functions will automatically lock and unlock the Surface data + as needed. If a section of code is going to make calls that will + repeatedly lock and unlock the Surface many times, it can be helpful to + wrap the block inside a lock and unlock pair. + """ + + def get_locked(self) -> bool: + """Test if the Surface is current locked. + + Returns ``True`` when the Surface is locked. It doesn't matter how many + times the Surface is locked. + """ + + def get_locks(self) -> tuple[Any, ...]: + """Gets the locks for the Surface. + + Returns the currently existing locks for the Surface. + """ + @property def width(self) -> int: """Surface width in pixels (read-only). @@ -1050,5 +1052,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 a0f7f8da5a..30f6bfef12 100644 --- a/src_c/doc/surface_doc.h +++ b/src_c/doc/surface_doc.h @@ -1,6 +1,6 @@ /* Auto generated file: with make_docs.py . Docs go in docs/reST/ref/ . */ #define DOC_SURFACE "Surface(size, flags=0, depth=0, masks=None) -> Surface\nSurface(size, flags=0, surface=...) -> Surface\nPygame object for representing images." -#define DOC_SURFACE_BLIT "blit(source, dest=(0, 0), area=None, special_flags=0) -> Rect\nDraw another surface onto this one." +#define DOC_SURFACE_BLIT "blit(source, dest=(0, 0), area=None, special_flags=0) -> Rect\nDraw another Surface onto this one." #define DOC_SURFACE_BLITS "blits(blit_sequence, doreturn=1) -> Union[list[Rect], None]\nDraw many surfaces onto this surface at their corresponding location." #define DOC_SURFACE_FBLITS "fblits(blit_sequence, special_flags=0, /) -> None\nDraw many surfaces onto this surface at their corresponding location and with the same special_flags." #define DOC_SURFACE_CONVERT "convert(surface, /) -> Surface\nconvert(depth, flags=0, /) -> Surface\nconvert(masks, flags=0, /) -> Surface\nconvert() -> Surface\nChange the pixel format of a surface." @@ -12,11 +12,6 @@ #define DOC_SURFACE_GETCOLORKEY "get_colorkey() -> Optional[tuple[int, int, int, int]]\nGet the current transparent colorkey." #define DOC_SURFACE_SETALPHA "set_alpha(value, flags=0, /) -> None\nset_alpha(value, /) -> None\nSet the alpha value for the full Surface." #define DOC_SURFACE_GETALPHA "get_alpha() -> Optional[int]\nGet the current Surface transparency value." -#define DOC_SURFACE_LOCK "lock() -> None\nLock the Surface memory for pixel access." -#define DOC_SURFACE_UNLOCK "unlock() -> None\nUnlock the Surface memory from pixel access." -#define DOC_SURFACE_MUSTLOCK "mustlock() -> bool\nTest if the Surface requires locking." -#define DOC_SURFACE_GETLOCKED "get_locked() -> bool\nTest if the Surface is current locked." -#define DOC_SURFACE_GETLOCKS "get_locks() -> tuple[Any, ...]\nGets the locks for the Surface." #define DOC_SURFACE_GETAT "get_at(x_y, /) -> Color\nGet the color value at a single pixel." #define DOC_SURFACE_SETAT "set_at(x_y, color, /) -> None\nSet the color value for a single pixel." #define DOC_SURFACE_GETATMAPPED "get_at_mapped(x_y, /) -> int\nGet the mapped color value at a single pixel." @@ -50,9 +45,14 @@ #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_LOCK "lock() -> None\nLock the Surface memory for pixel access." +#define DOC_SURFACE_UNLOCK "unlock() -> None\nUnlock the Surface memory from pixel access." +#define DOC_SURFACE_MUSTLOCK "mustlock() -> bool\nTest if the Surface requires locking." +#define DOC_SURFACE_GETLOCKED "get_locked() -> bool\nTest if the Surface is current locked." +#define DOC_SURFACE_GETLOCKS "get_locks() -> tuple[Any, ...]\nGets the locks for the Surface." #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." From 4afd45d6e20d6d8b97d99c2c4084ba644ff5250c Mon Sep 17 00:00:00 2001 From: damusss Date: Thu, 9 Oct 2025 22:06:42 +0200 Subject: [PATCH 2/3] Fix mistakes --- buildconfig/stubs/pygame/surface.pyi | 150 +++++++++++++-------------- src_c/doc/surface_doc.h | 10 +- 2 files changed, 76 insertions(+), 84 deletions(-) diff --git a/buildconfig/stubs/pygame/surface.pyi b/buildconfig/stubs/pygame/surface.pyi index a20bca5e44..9a21ad8bed 100644 --- a/buildconfig/stubs/pygame/surface.pyi +++ b/buildconfig/stubs/pygame/surface.pyi @@ -442,12 +442,6 @@ class Surface: blending will be disabled. This full alpha is compatible with other kinds of transparency. - 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. - 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. @@ -459,11 +453,77 @@ class Surface: def get_alpha(self) -> Optional[int]: """Get the current Surface transparency value. - Return the current alpha value for the Surface. If the blendmode of the - Surface is not ``pygame.BLENDMODE_NONE``, this method will always return - a valid value in the range 0 (fully transparent) - 255 (fully opaque). - Otherwise, this method will return None until an alpha is set with - :meth:`set_alpha()` (the set alpha value will be returned). + 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: + """Lock the Surface memory for pixel access. + + Lock the pixel data of a Surface for access. On accelerated Surfaces, the + pixel data may be stored in volatile video memory or nonlinear compressed + forms. When a Surface is locked the pixel memory becomes available to + access by regular software. Code that reads or writes pixel values will + need the Surface to be locked. + + Surfaces should not remain locked for more than necessary. A locked + Surface can often not be displayed or managed by pygame. + + Not all Surfaces require locking. The :meth:`mustlock()` method can + determine if it is actually required. There is no performance penalty for + locking and unlocking a Surface that does not need it. + + All pygame functions will automatically lock and unlock the Surface data + as needed. If a section of code is going to make calls that will + repeatedly lock and unlock the Surface many times, it can be helpful to + wrap the block inside a lock and unlock pair. + + It is safe to nest locking and unlocking calls. The surface will only be + unlocked after the final lock is released. + """ + + def unlock(self) -> None: + """Unlock the Surface memory from pixel access. + + Unlock the Surface pixel data after it has been locked. The unlocked + Surface can once again be drawn and managed by pygame. See the + :meth:`lock()` documentation for more details. + + All pygame functions will automatically lock and unlock the Surface data + as needed. If a section of code is going to make calls that will + repeatedly lock and unlock the Surface many times, it can be helpful to + wrap the block inside a lock and unlock pair. + + It is safe to nest locking and unlocking calls. The surface will only be + unlocked after the final lock is released. + """ + + def mustlock(self) -> bool: + """Test if the Surface requires locking. + + Returns ``True`` if the Surface is required to be locked to access pixel + data. Usually pure software Surfaces do not require locking. This method + is rarely needed, since it is safe and quickest to just lock all Surfaces + as needed. + + All pygame functions will automatically lock and unlock the Surface data + as needed. If a section of code is going to make calls that will + repeatedly lock and unlock the Surface many times, it can be helpful to + wrap the block inside a lock and unlock pair. + """ + + def get_locked(self) -> bool: + """Test if the Surface is current locked. + + Returns ``True`` when the Surface is locked. It doesn't matter how many + times the Surface is locked. + """ + + def get_locks(self) -> tuple[Any, ...]: + """Gets the locks for the Surface. + + Returns the currently existing locks for the Surface. """ def get_at(self, x_y: Point, /) -> Color: @@ -958,74 +1018,6 @@ class Surface: .. versionadded:: 2.5.1 """ - def lock(self) -> None: - """Lock the Surface memory for pixel access. - - Lock the pixel data of a Surface for access. On accelerated Surfaces, the - pixel data may be stored in volatile video memory or nonlinear compressed - forms. When a Surface is locked the pixel memory becomes available to - access by regular software. Code that reads or writes pixel values will - need the Surface to be locked. - - Surfaces should not remain locked for more than necessary. A locked - Surface can often not be displayed or managed by pygame. - - Not all Surfaces require locking. The :meth:`mustlock()` method can - determine if it is actually required. There is no performance penalty for - locking and unlocking a Surface that does not need it. - - All pygame functions will automatically lock and unlock the Surface data - as needed. If a section of code is going to make calls that will - repeatedly lock and unlock the Surface many times, it can be helpful to - wrap the block inside a lock and unlock pair. - - It is safe to nest locking and unlocking calls. The surface will only be - unlocked after the final lock is released. - """ - - def unlock(self) -> None: - """Unlock the Surface memory from pixel access. - - Unlock the Surface pixel data after it has been locked. The unlocked - Surface can once again be drawn and managed by pygame. See the - :meth:`lock()` documentation for more details. - - All pygame functions will automatically lock and unlock the Surface data - as needed. If a section of code is going to make calls that will - repeatedly lock and unlock the Surface many times, it can be helpful to - wrap the block inside a lock and unlock pair. - - It is safe to nest locking and unlocking calls. The surface will only be - unlocked after the final lock is released. - """ - - def mustlock(self) -> bool: - """Test if the Surface requires locking. - - Returns ``True`` if the Surface is required to be locked to access pixel - data. Usually pure software Surfaces do not require locking. This method - is rarely needed, since it is safe and quickest to just lock all Surfaces - as needed. - - All pygame functions will automatically lock and unlock the Surface data - as needed. If a section of code is going to make calls that will - repeatedly lock and unlock the Surface many times, it can be helpful to - wrap the block inside a lock and unlock pair. - """ - - def get_locked(self) -> bool: - """Test if the Surface is current locked. - - Returns ``True`` when the Surface is locked. It doesn't matter how many - times the Surface is locked. - """ - - def get_locks(self) -> tuple[Any, ...]: - """Gets the locks for the Surface. - - Returns the currently existing locks for the Surface. - """ - @property def width(self) -> int: """Surface width in pixels (read-only). diff --git a/src_c/doc/surface_doc.h b/src_c/doc/surface_doc.h index 30f6bfef12..8098dd90cb 100644 --- a/src_c/doc/surface_doc.h +++ b/src_c/doc/surface_doc.h @@ -12,6 +12,11 @@ #define DOC_SURFACE_GETCOLORKEY "get_colorkey() -> Optional[tuple[int, int, int, int]]\nGet the current transparent colorkey." #define DOC_SURFACE_SETALPHA "set_alpha(value, flags=0, /) -> None\nset_alpha(value, /) -> None\nSet the alpha value for the full Surface." #define DOC_SURFACE_GETALPHA "get_alpha() -> Optional[int]\nGet the current Surface transparency value." +#define DOC_SURFACE_LOCK "lock() -> None\nLock the Surface memory for pixel access." +#define DOC_SURFACE_UNLOCK "unlock() -> None\nUnlock the Surface memory from pixel access." +#define DOC_SURFACE_MUSTLOCK "mustlock() -> bool\nTest if the Surface requires locking." +#define DOC_SURFACE_GETLOCKED "get_locked() -> bool\nTest if the Surface is current locked." +#define DOC_SURFACE_GETLOCKS "get_locks() -> tuple[Any, ...]\nGets the locks for the Surface." #define DOC_SURFACE_GETAT "get_at(x_y, /) -> Color\nGet the color value at a single pixel." #define DOC_SURFACE_SETAT "set_at(x_y, color, /) -> None\nSet the color value for a single pixel." #define DOC_SURFACE_GETATMAPPED "get_at_mapped(x_y, /) -> int\nGet the mapped color value at a single pixel." @@ -47,11 +52,6 @@ #define DOC_SURFACE_GETBUFFER "get_buffer() -> BufferProxy\nAcquires a buffer object for the pixels of the Surface." #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_LOCK "lock() -> None\nLock the Surface memory for pixel access." -#define DOC_SURFACE_UNLOCK "unlock() -> None\nUnlock the Surface memory from pixel access." -#define DOC_SURFACE_MUSTLOCK "mustlock() -> bool\nTest if the Surface requires locking." -#define DOC_SURFACE_GETLOCKED "get_locked() -> bool\nTest if the Surface is current locked." -#define DOC_SURFACE_GETLOCKS "get_locks() -> tuple[Any, ...]\nGets the locks for the Surface." #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)." From 41854907a25aae393b60a92d0d1c7cef64249950 Mon Sep 17 00:00:00 2001 From: damusss Date: Sat, 11 Oct 2025 10:52:05 +0200 Subject: [PATCH 3/3] Convert to present tense, clarify regular blitting --- buildconfig/stubs/pygame/surface.pyi | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/buildconfig/stubs/pygame/surface.pyi b/buildconfig/stubs/pygame/surface.pyi index 6d42e47502..0484b27b1d 100644 --- a/buildconfig/stubs/pygame/surface.pyi +++ b/buildconfig/stubs/pygame/surface.pyi @@ -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`` (unlike regular blitting) + :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,7 +341,7 @@ class Surface: attributes then it should override ``copy()``. Shallow copy and deepcopy are supported, Surface implements __copy__ and __deepcopy__ respectively. - If the Surface was a subsurface, the returned Surface will *not* retain + 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