Skip to content

Clean Surface docs 3: minor clarifications, typos and movements #3605

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Clean Surface docs 3: minor clarifications, typos and movements #3605

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
99dbbb3
Minor improvements
damusss Oct 8, 2025
4afd45d
Fix mistakes
damusss Oct 9, 2025
eade6d5
Merge branch 'main' into clean-surface-docs-3
damusss Oct 11, 2025
4185490
Convert to present tense, clarify regular blitting
damusss Oct 11, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
185 changes: 98 additions & 87 deletions buildconfig/stubs/pygame/surface.pyi
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -143,22 +143,22 @@ 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).
If a ``Rect`` is passed, its size will not affect the blit.
- ``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)*
Expand All @@ -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**
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.
"""
Expand Down Expand Up @@ -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.
Expand All @@ -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:
Expand Down Expand Up @@ -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]:
Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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).
Expand All @@ -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): ...
14 changes: 7 additions & 7 deletions src_c/doc/surface_doc.h
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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."
Expand All @@ -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."
Expand Down Expand Up @@ -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."
Loading