diff --git a/buildconfig/stubs/pygame/_render.pyi b/buildconfig/stubs/pygame/_render.pyi index 2a76653dec..df3e49c2a2 100644 --- a/buildconfig/stubs/pygame/_render.pyi +++ b/buildconfig/stubs/pygame/_render.pyi @@ -1,3 +1,32 @@ +"""Experimental pygame module porting the SDL render video system + +The SDL render video system supports both software and GPU-accelerated +rendering through the Renderer, Texture and Image objects. + +.. versionadded:: 2.5.4 +""" + +# render.rst contents for the future +""" +.. include:: common.txt + +:mod:`pygame._render` +===================== + +.. warning:: + This module isn't ready for prime time yet, it's still in development. + These docs are primarily meant to help the pygame developers and + super-early adopters who are in communication with the developers. + This API will change. + + Also, this module is a C implementation of most of the features of the + sdl2_video module. It is currently incomplete. + +.. autopgmodule:: pygame._render + :members: + +""" + from typing import Optional, Protocol, Union, final from pygame.color import Color @@ -5,7 +34,6 @@ from pygame.rect import Rect from pygame.surface import Surface from pygame.typing import ColorLike, IntPoint, Point, RectLike, SequenceLike from pygame.window import Window -from typing_extensions import deprecated # added in 3.13 class _DrawableClass(Protocol): # Object that has the draw method that accepts area and dest arguments @@ -15,6 +43,35 @@ class _DrawableClass(Protocol): @final class Renderer: + """Object wrapping a 2D rendering context for a window + + :class:`Renderer` objects provide a cross-platform API for rendering 2D + graphics onto a :class:`Window`, by using either Metal (macOS), OpenGL + (macOS, Windows, Linux) or Direct3D (Windows) rendering drivers, depending + on what is set or is available on a system during their creation. + + They can be used to draw both :class:`Texture` objects and simple points, + lines and rectangles (which are colored based on :attr:`Renderer.draw_color`). + + If configured correctly and supported by an underlying rendering driver, Renderer + objects can have a :class:`Texture` object temporarily set as a target texture + (the Texture object must have been created with target texture usage support), + which allows those textures to be drawn onto. + + To present drawn content onto the window, :meth:`Renderer.present` should be + called. :meth:`Renderer.clear` should be called to clear any drawn content + with the set Renderer draw color. + + When things are drawn onto Renderer objects, an internal batching system is + used by default to batch those "draw calls" together, to have all of them be + processed in one go when :meth:`Renderer.present` is called. This is unlike + :class:`pygame.Surface` objects, on which modifications via blitting occur + immediately, but lends well to the behavior of GPUs, as draw calls can be + expensive on lower-end models. + + .. versionadded:: 2.5.4 + """ + def __init__( self, window: Window, @@ -29,53 +86,224 @@ class Renderer: dest: Optional[RectLike] = None, area: Optional[RectLike] = None, special_flags: int = 0, - ) -> Rect: ... - def clear(self) -> None: ... - def draw_line(self, p1: Point, p2: Point) -> None: ... - def draw_point(self, point: Point) -> None: ... - def draw_quad(self, p1: Point, p2: Point, p3: Point, p4: Point) -> None: ... - def draw_rect(self, rect: RectLike) -> None: ... - def draw_triangle(self, p1: Point, p2: Point, p3: Point) -> None: ... - def fill_quad(self, p1: Point, p2: Point, p3: Point, p4: Point) -> None: ... - def fill_rect(self, rect: RectLike) -> None: ... - def fill_triangle(self, p1: Point, p2: Point, p3: Point) -> None: ... - def get_viewport(self) -> Rect: ... - def present(self) -> None: ... - def set_viewport(self, area: Optional[RectLike]) -> None: ... + ) -> Rect: + """Draw textures using a Surface-like API + + For compatibility purposes. Draws :class:`Texture` objects onto the + Renderer using a method signature similar to :meth:`pygame.Surface.blit`. + + :param source: A :class:`Texture` or :class:`Image` to draw. + :param dest: The drawing destination on the rendering target. + :param area: The portion of the source texture or image to draw from. + :param special_flags: have no effect at this moment. + + .. note:: Textures created by different Renderers cannot shared with each other! + + .. versionadded:: 2.5.4 + """ + + def clear(self) -> None: + """Clear the current rendering target with the drawing color""" + + def draw_line(self, p1: Point, p2: Point) -> None: + """Draw a line + + :param p1: The line start point. + :param p2: The line end point. + + .. versionadded:: 2.5.4 + """ + + def draw_point(self, point: Point) -> None: + """Draw a point + + :param point: The point's coordinates. + + .. versionadded:: 2.5.4 + """ + + def draw_quad(self, p1: Point, p2: Point, p3: Point, p4: Point) -> None: + """Draw a quad outline + + :param p1: The first quad point. + :param p2: The second quad point. + :param p2: The third quad point. + :param p2: The fourth quad point. + + .. versionadded:: 2.5.4 + """ + + def draw_rect(self, rect: RectLike) -> None: + """Draw a rectangle outline + + :param rect: The :class:`pygame.Rect`-like rectangle to draw. + + .. versionadded:: 2.5.4 + """ + + def draw_triangle(self, p1: Point, p2: Point, p3: Point) -> None: + """Draw a triangle outline + + :param p1: The first triangle point. + :param p2: The second triangle point. + :param p2: The third triangle point. + + .. versionadded:: 2.5.4 + """ + + def fill_quad(self, p1: Point, p2: Point, p3: Point, p4: Point) -> None: + """Draw a filled quad + + :param p1: The first quad point. + :param p2: The second quad point. + :param p2: The third quad point. + :param p2: The fourth quad point. + + .. versionadded:: 2.5.4 + """ + + def fill_rect(self, rect: RectLike) -> None: + """Draw a filled rectangle + + :param rect: The :class:`pygame.Rect`-like rectangle to draw. + + .. versionadded:: 2.5.4 + """ + + def fill_triangle(self, p1: Point, p2: Point, p3: Point) -> None: + """Draw a filled triangle + + :param p1: The first triangle point. + :param p2: The second triangle point. + :param p2: The third triangle point. + + .. versionadded:: 2.5.4 + """ + + def get_viewport(self) -> Rect: + """Get the drawing area on the rendering target + + .. versionadded:: 2.5.4 + """ + + def present(self) -> None: + """Update the screen with any rendering performed since the previous call + + Presents the composed backbuffer to the screen. + Updates the screen with any rendering performed since the previous call. + + .. versionadded:: 2.5.4 + """ + + def set_viewport(self, area: Optional[RectLike]) -> None: + """Set the drawing area on the rendering target + + :param area: A :class:`pygame.Rect` or tuple representing the + drawing area on the target, or ``None`` to use the + entire area of the current rendering target. + + .. versionadded:: 2.5.4 + """ + def to_surface( self, surface: Optional[Surface] = None, area: Optional[RectLike] = None - ) -> Surface: ... + ) -> Surface: + """Read pixels from current rendering target and create a Surface (slow operation, use sparingly) + + Read pixel data from the current rendering target and return a + :class:`pygame.Surface` containing it. + + :param Surface surface: A :class:`pygame.Surface` object to read the pixel + data into. It must be large enough to fit the area, otherwise + ``ValueError`` is raised. + If set to ``None``, a new surface will be created. + :param area: The area of the screen to read pixels from. The area is + clipped to fit inside the viewport. + If ``None``, the entire viewport is used. + + .. note:: + This is a very slow operation, due to the overhead of the VRAM to RAM + data transfer and the cost of creating a potentially large + :class:`pygame.Surface`. It should not be used frequently. + + .. versionadded:: 2.5.4 + """ + @property - def draw_blend_mode(self) -> int: ... + def draw_blend_mode(self) -> int: + """Get or set the blend mode used for primitive drawing operations + + .. versionadded:: 2.5.4 + """ @draw_blend_mode.setter def draw_blend_mode(self, value: int) -> None: ... @property - def draw_color(self) -> Color: ... + def draw_color(self) -> Color: + """Get or set the color used for primitive drawing operations + + .. versionadded:: 2.5.4 + """ @draw_color.setter def draw_color(self, value: ColorLike) -> None: ... @property - def logical_size(self) -> tuple[int, int]: ... + def logical_size(self) -> tuple[int, int]: + """Get or set the logical Renderer size (a device independent resolution for rendering)""" @logical_size.setter def logical_size(self, value: IntPoint) -> None: ... @property - def scale(self) -> tuple[float, float]: ... + def scale(self) -> tuple[float, float]: + """Get the drawing scale for the current rendering target + + .. versionadded:: 2.5.4 + """ @scale.setter def scale(self, value: Point) -> None: ... @property - def target(self) -> "Texture": ... + def target(self) -> "Texture": + """Get or set the current rendering target + + Gets or sets the current rendering target. + A value of ``None`` means that no custom rendering target was set and the + Renderer's window will be used as the target. + + .. versionadded:: 2.5.4 + """ @target.setter def target(self, value: "Texture") -> None: ... @classmethod def compose_custom_blend_mode( cls, color_mode: SequenceLike[int], alpha_mode: SequenceLike[int] - ) -> int: ... + ) -> int: + """Compose a custom blend mode + + Compose a custom blend mode. + See https://wiki.libsdl.org/SDL2/SDL_ComposeCustomBlendMode for more information. + + :param color_mode: A tuple ``(srcColorFactor, dstColorFactor, colorOperation)`` + :param alpha_mode: A tuple ``(srcAlphaFactor, dstAlphaFactor, alphaOperation)`` + + :return: A blend mode to be used with :meth:`Renderer.set_draw_blend_mode` and :meth:`Texture.set_blend_mode`. + + .. versionadded:: 2.5.4 + """ + @classmethod - def from_window(cls, window: Window) -> Renderer: ... + def from_window(cls, window: Window) -> Renderer: + """Create a Renderer from an existing window + + .. versionadded:: 2.5.4 + """ @final class Texture: - pass + """Pygame object that represents a texture + + .. versionadded:: 2.5.4 + """ @final class Image: - pass + """Pygame object that represents a portion of a texture + + .. versionadded:: 2.5.4 + """ diff --git a/docs/reST/ext/documenters.py b/docs/reST/ext/documenters.py index 9ecec61f38..df436ae3d6 100644 --- a/docs/reST/ext/documenters.py +++ b/docs/reST/ext/documenters.py @@ -1,6 +1,7 @@ import autoapi import autoapi.documenters from autoapi._objects import PythonClass +from autoapi._mapper import PythonModule import re @@ -142,3 +143,5 @@ def setup(app): {"objtype": f"pg{name}"}, ) ) + + PythonModule._should_skip = lambda *args, **kwargs: False diff --git a/docs/reST/index.rst b/docs/reST/index.rst index 6b3d25679d..4961b2fdd7 100644 --- a/docs/reST/index.rst +++ b/docs/reST/index.rst @@ -57,7 +57,7 @@ them, this is how you can do it: Don't forget to report us any problem with the experimental features on `github`_ so we can easily turn them to stable API in the future ^^. -**Below is currently the list of experimental modules :** +**Below is currently the list of experimental modules:** :doc:`ref/geometry` Pygame module for the Circle, Line, and Polygon objects.