sprites now have limited support for Texture and Renderer

Author: oddbookworm

buildconfig/stubs/pygame/sprite.pyi

@@ -12,12 +12,14 @@ from typing import (
     Tuple,
     TypeVar,
     Union,
+    overload,
 )
 from typing_extensions import deprecated # added in 3.13
 
 from pygame.rect import FRect, Rect
 from pygame.surface import Surface
 from pygame.mask import Mask
+from pygame._sdl2.video import Renderer, Texture
 
 from ._common import RectValue, Coordinate
 
@@ -27,9 +29,9 @@ _Group = AbstractGroup[_SpriteSupportsGroup]
 # protocol helps with structural subtyping for typevars in sprite group generics
 class _SupportsSprite(Protocol):
     @property
-    def image(self) -> Optional[Surface]: ...
+    def image(self) -> Optional[Union[Surface, Texture]]: ...
     @image.setter
-    def image(self, value: Optional[Surface]) -> None: ...
+    def image(self, value: Optional[Union[Surface, Texture]]) -> None: ...
     @property
     def rect(self) -> Optional[Union[FRect, Rect]]: ...
     @rect.setter
@@ -61,9 +63,9 @@ class _SupportsDirtySprite(_SupportsSprite, Protocol):
 # concrete sprite implementation class
 class Sprite(_SupportsSprite):
     @property
-    def image(self) -> Optional[Surface]: ...
+    def image(self) -> Optional[Union[Surface, Texture]]: ...
     @image.setter
-    def image(self, value: Optional[Surface]) -> None: ...
+    def image(self, value: Optional[Union[Surface, Texture]]) -> None: ...
     @property
     def rect(self) -> Optional[Union[FRect, Rect]]: ...
     @rect.setter
@@ -105,7 +107,7 @@ class _HasRect(Protocol):
 # image in addition to rect
 class _HasImageAndRect(_HasRect, Protocol):
     @property
-    def image(self) -> Optional[Surface]: ...
+    def image(self) -> Optional[Union[Surface, Texture]]: ...
 
 # mask in addition to rect
 class _HasMaskAndRect(_HasRect, Protocol):
@@ -169,7 +171,10 @@ class AbstractGroup(Generic[_TSprite]):
         self, *sprites: Union[_TSprite, AbstractGroup[_TSprite], Iterable[_TSprite]]
     ) -> bool: ...
     def update(self, *args: Any, **kwargs: Any) -> None: ...
+    @overload
     def draw(self, surface: Surface) -> List[Union[FRect, Rect]]: ...
+    @overload
+    def draw(self, renderer: Renderer) -> List[Union[FRect, Rect]]: ...
     def clear(
         self,
         surface: Surface,
@@ -181,7 +186,7 @@ class Group(AbstractGroup[_TSprite]):
     def __init__(
         self, *sprites: Union[_TSprite, AbstractGroup[_TSprite], Iterable[_TSprite]]
     ) -> None: ...
-    
+
 # these are aliased in the code too
 @deprecated("Use `pygame.sprite.Group` instead")
 class RenderPlain(Group): ...
@@ -227,7 +232,7 @@ class LayeredUpdates(AbstractGroup[_TSprite]):
 
 class LayeredDirty(LayeredUpdates[_TDirtySprite]):
     def __init__(self, *sprites: _TDirtySprite, **kwargs: Any) -> None: ...
-    def draw(
+    def draw(                                        # type: ignore[override]
         self, surface: Surface, bgd: Optional[Surface] = None
     ) -> List[Union[FRect, Rect]]: ...
     # clear breaks Liskov substitution principle in code

docs/reST/ref/sprite.rst

@@ -50,6 +50,17 @@ extend those when you add a Sprite or Group class.
 
 Sprites are not thread safe. So lock them yourself if using threads.
 
+.. note:: As of version 2.5.1, you can use ``Sprite`` and ``Group`` with ``Renderer``
+            and ``Texture`` from ``_sdl2.video``, at least partially. Instead of ``Sprite.image``
+            needing to be a ``Surface``, it needs to be a ``Texture`` to do this. This behavior
+            is still very experimental, so please report any weirdness to the developers as an
+            issue on the ``pygame-ce`` github repository. Also note that ``LayeredDirty.draw``
+            does not currently work in this manner. Other group types might work, but have not
+            been thorougly tested.
+
+.. versionchanged:: 2.5.1 ``Sprite`` and ``Group``
+                     have some compatibility with ``_sdl2.video``
+
 .. class:: Sprite
 
    | :sl:`Simple base class for visible game objects.`
@@ -64,24 +75,24 @@ Sprites are not thread safe. So lock them yourself if using threads.
    adding the Sprite to Groups. For example:
 
    .. code-block:: python
-   
+
        class Block(pygame.sprite.Sprite):
-            
-           # Constructor. Pass in the color of the block, 
+
+           # Constructor. Pass in the color of the block,
            # and its x and y position
            def __init__(self, color, width, height):
               # Call the parent class (Sprite) constructor
-              pygame.sprite.Sprite.__init__(self) 
-        
+              pygame.sprite.Sprite.__init__(self)
+
               # Create an image of the block, and fill it with a color.
               # This could also be an image loaded from the disk.
               self.image = pygame.Surface([width, height])
               self.image.fill(color)
-        
+
               # Fetch the rectangle object that has the dimensions of the image
               # Update the position of this object by setting the values of rect.x and rect.y
-              self.rect = self.image.get_rect()   
-      
+              self.rect = self.image.get_rect()
+
    .. method:: update
 
       | :sl:`method to control sprite behavior`
@@ -291,14 +302,25 @@ Sprites are not thread safe. So lock them yourself if using threads.
    .. method:: draw
 
       | :sl:`blit the Sprite images`
-      | :sg:`draw(Surface) -> List[Rect]`
+      | :sg:`draw(Surface) -> List[Union[Rect, FRect]]`
+      | :sg:`draw(Renderer) -> List[Union[Rect, FRect]]`
 
-      Draws the contained Sprites to the Surface argument. This uses the
-      ``Sprite.image`` attribute for the source surface, and ``Sprite.rect``
+      Draws the contained Sprites to the Surface or _sdl2.video.Renderer argument.
+
+      Surface
+      -------
+      This uses the ``Sprite.image`` attribute for the source surface, and ``Sprite.rect``
+      for the position.
+
+      Renderer
+      --------
+      This uses the ``Sprite.image`` attribute for the source Texture, and ``Sprite.rect``
       for the position.
 
       The Group keeps sprites in the order they were added, they will be drawn in this order.
 
+      .. versionchanged:: 2.5.1 Now accepts a renderer for use with ``_sdl2.video``
+
       .. ## Group.draw ##
 
    .. method:: clear
@@ -667,17 +689,17 @@ Sprites are not thread safe. So lock them yourself if using threads.
        collide_circle_ratio, collide_mask
 
    Example:
-   
+
    .. code-block:: python
 
     # See if the Sprite block has collided with anything in the Group block_list
     # The True flag will remove the sprite in block_list
-    blocks_hit_list = pygame.sprite.spritecollide(player, block_list, True)  
-     
+    blocks_hit_list = pygame.sprite.spritecollide(player, block_list, True)
+
     # Check the list of colliding sprites, and add one to the score for each one
     for block in blocks_hit_list:
         score +=1
-       
+
    .. ## pygame.sprite.spritecollide ##
 
 .. function:: collide_rect

src_c/cython/pygame/_sdl2/video.pxd

@@ -90,7 +90,7 @@ cdef extern from "SDL.h" nogil:
         SDL_FPoint position
         SDL_Color color
         SDL_FPoint tex_coord
-    
+
     ctypedef enum SDL_ScaleMode "_pgsdlScaleMode":
         SDL_ScaleModeNearest,
         SDL_ScaleModeLinear,
@@ -151,8 +151,8 @@ cdef extern from "SDL.h" nogil:
     # https://wiki.libsdl.org/SDL_RenderCopyExF
     # https://wiki.libsdl.org/SDL_RenderPresent
     int SDL_GetRenderDrawColor(SDL_Renderer* renderer,
-                               Uint8*        r, 
-                               Uint8*        g, 
+                               Uint8*        r,
+                               Uint8*        g,
                                Uint8*        b,
                                Uint8*        a)
     int SDL_SetRenderDrawColor(SDL_Renderer* renderer,
@@ -227,7 +227,7 @@ cdef extern from "SDL.h" nogil:
                                              SDL_BlendFactor    srcAlphaFactor,
                                              SDL_BlendFactor    dstAlphaFactor,
                                              SDL_BlendOperation alphaOperation)
- 
+
     ctypedef enum SDL_BlendOperation:
         SDL_BLENDOPERATION_ADD = 0x00000001,
         SDL_BLENDOPERATION_SUBTRACT = 0x00000002,
@@ -370,7 +370,7 @@ cdef extern from "SDL.h" nogil:
     # https://wiki.libsdl.org/SDL_RenderGetIntegerScale
     int SDL_RenderSetScale(SDL_Renderer* renderer,
                            float         scaleX,
-                           float         scaleY) 
+                           float         scaleY)
     void SDL_RenderGetScale(SDL_Renderer* renderer,
                             float*        scaleX,
                             float*        scaleY)
@@ -382,7 +382,7 @@ cdef extern from "SDL.h" nogil:
                                   int*          h)
     int SDL_RenderGetIntegerScale(SDL_Renderer* renderer)
 
-    int SDL_VERSION_ATLEAST(int major, int minor, int patch) 
+    int SDL_VERSION_ATLEAST(int major, int minor, int patch)
 
     # https://wiki.libsdl.org/SDL_GetWindowPixelFormat
     # https://wiki.libsdl.org/SDL_IntersectRect
@@ -414,7 +414,7 @@ cdef extern from "pygame.h" nogil:
     ctypedef class pygame.color.Color [object pgColorObject]:
         cdef Uint8 data[4]
         cdef Uint8 len
-    
+
     ctypedef enum pgColorHandleFlags:
         PG_COLOR_HANDLE_SIMPLE
         PG_COLOR_HANDLE_STR
@@ -425,7 +425,11 @@ cdef extern from "pygame.h" nogil:
     ctypedef class pygame.rect.Rect [object pgRectObject]:
         cdef SDL_Rect r
         cdef object weakreflist
-    
+
+    ctypedef class pygame.rect.FRect [object pgFRectObject]:
+        cdef SDL_FRect r
+        cdef object weakreflist
+
     ctypedef class pygame.window.Window [object pgWindowObject]:
         cdef SDL_Window *_win
         cdef SDL_bool _is_borrowed
@@ -464,7 +468,7 @@ cdef class Renderer:
     cdef int _is_borrowed
 
     cpdef object get_viewport(self)
-    cpdef object blit(self, object source, Rect dest=*, Rect area=*, int special_flags=*)
+    cpdef object blit(self, object source, object dest=*, object area=*, int special_flags=*)
 
 cdef class Texture:
     cdef SDL_Texture* _tex