From 0a267c2df8086180e655146300e51b7445456972 Mon Sep 17 00:00:00 2001 From: damusss Date: Tue, 13 May 2025 16:50:56 +0200 Subject: [PATCH 1/5] Document pygame._render --- buildconfig/stubs/pygame/_render.pyi | 255 ++++++++++++++++++++++++--- docs/reST/ext/boilerplate.py | 1 + docs/reST/ext/documenters.py | 3 + docs/reST/index.rst | 5 +- docs/reST/ref/_render.rst | 16 ++ src_c/doc/_render_doc.h | 23 +++ src_c/render.c | 46 ++--- 7 files changed, 301 insertions(+), 48 deletions(-) create mode 100644 docs/reST/ref/_render.rst create mode 100644 src_c/doc/_render_doc.h diff --git a/buildconfig/stubs/pygame/_render.pyi b/buildconfig/stubs/pygame/_render.pyi index 2a76653dec..91b7484d6b 100644 --- a/buildconfig/stubs/pygame/_render.pyi +++ b/buildconfig/stubs/pygame/_render.pyi @@ -1,3 +1,11 @@ +"""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 +""" + from typing import Optional, Protocol, Union, final from pygame.color import Color @@ -5,7 +13,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 +22,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 +65,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/boilerplate.py b/docs/reST/ext/boilerplate.py index d4aeae34c9..9c8d3a0f21 100644 --- a/docs/reST/ext/boilerplate.py +++ b/docs/reST/ext/boilerplate.py @@ -350,6 +350,7 @@ def lowercase_name(d): "pixelcopy", "sndarray", "surfarray", + "_render" ] existing_order = ["pygame." + x for x in existing_order] 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..dc4bc51185 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. @@ -68,6 +68,9 @@ turn them to stable API in the future ^^. :doc:`ref/sdl2_video` Pygame module for porting new SDL video systems. +:doc:`ref/_render` + Experimental pygame module porting the SDL render video system (A C implementation of the sdl2_video module, currently incomplete!) + .. _github: https://github.com/pygame-community/pygame-ce Documents diff --git a/docs/reST/ref/_render.rst b/docs/reST/ref/_render.rst new file mode 100644 index 0000000000..a0d32db2bd --- /dev/null +++ b/docs/reST/ref/_render.rst @@ -0,0 +1,16 @@ +.. 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: diff --git a/src_c/doc/_render_doc.h b/src_c/doc/_render_doc.h new file mode 100644 index 0000000000..4afd792721 --- /dev/null +++ b/src_c/doc/_render_doc.h @@ -0,0 +1,23 @@ +/* Auto generated file: with make_docs.py . Docs go in docs/reST/ref/ . */ +#define DOC_RENDER_RENDERER "Renderer(window, index=-1, accelerated=-1, vsync=False, target_texture=False) -> Renderer\nObject wrapping a 2D rendering context for a window" +#define DOC_RENDER_RENDERER_BLIT "blit(source, dest=None, area=None, special_flags=0) -> Rect\nDraw textures using a Surface-like API" +#define DOC_RENDER_RENDERER_CLEAR "clear() -> None\nClear the current rendering target with the drawing color" +#define DOC_RENDER_RENDERER_DRAWLINE "draw_line(p1, p2) -> None\nDraw a line" +#define DOC_RENDER_RENDERER_DRAWPOINT "draw_point(point) -> None\nDraw a point" +#define DOC_RENDER_RENDERER_DRAWQUAD "draw_quad(p1, p2, p3, p4) -> None\nDraw a quad outline" +#define DOC_RENDER_RENDERER_DRAWRECT "draw_rect(rect) -> None\nDraw a rectangle outline" +#define DOC_RENDER_RENDERER_DRAWTRIANGLE "draw_triangle(p1, p2, p3) -> None\nDraw a triangle outline" +#define DOC_RENDER_RENDERER_FILLQUAD "fill_quad(p1, p2, p3, p4) -> None\nDraw a filled quad" +#define DOC_RENDER_RENDERER_FILLRECT "fill_rect(rect) -> None\nDraw a filled rectangle" +#define DOC_RENDER_RENDERER_FILLTRIANGLE "fill_triangle(p1, p2, p3) -> None\nDraw a filled triangle" +#define DOC_RENDER_RENDERER_GETVIEWPORT "get_viewport() -> Rect\nGet the drawing area on the rendering target" +#define DOC_RENDER_RENDERER_PRESENT "present() -> None\nUpdate the screen with any rendering performed since the previous call" +#define DOC_RENDER_RENDERER_SETVIEWPORT "set_viewport(area) -> None\nSet the drawing area on the rendering target" +#define DOC_RENDER_RENDERER_TOSURFACE "to_surface(surface=None, area=None) -> Surface\nRead pixels from current rendering target and create a Surface (slow operation, use sparingly)" +#define DOC_RENDER_RENDERER_DRAWBLENDMODE "draw_blend_mode -> int\nGet or set the blend mode used for primitive drawing operations" +#define DOC_RENDER_RENDERER_DRAWCOLOR "draw_color -> Color\nGet or set the color used for primitive drawing operations" +#define DOC_RENDER_RENDERER_LOGICALSIZE "logical_size -> tuple[int, int]\nGet or set the logical Renderer size (a device independent resolution for rendering)" +#define DOC_RENDER_RENDERER_SCALE "scale -> tuple[float, float]\nGet the drawing scale for the current rendering target" +#define DOC_RENDER_RENDERER_TARGET "target -> Texture\nGet or set the current rendering target" +#define DOC_RENDER_RENDERER_COMPOSECUSTOMBLENDMODE "compose_custom_blend_mode(color_mode, alpha_mode) -> int\nCompose a custom blend mode" +#define DOC_RENDER_RENDERER_FROMWINDOW "from_window(window) -> Renderer\nCreate a Renderer from an existing window" diff --git a/src_c/render.c b/src_c/render.c index 7dbdf29ccc..2999b0153a 100644 --- a/src_c/render.c +++ b/src_c/render.c @@ -5,6 +5,7 @@ #include "pgcompat.h" #include "doc/sdl2_video_doc.h" +#include "doc/_render_doc.h" static PyTypeObject pgRenderer_Type; @@ -559,55 +560,54 @@ image_renderer_draw(pgImageObject *self, PyObject *area, PyObject *dest) /* Module definition */ static PyMethodDef renderer_methods[] = { {"draw_point", (PyCFunction)renderer_draw_point, - METH_VARARGS | METH_KEYWORDS, DOC_SDL2_VIDEO_RENDERER_DRAWPOINT}, + METH_VARARGS | METH_KEYWORDS, DOC_RENDER_RENDERER_DRAWPOINT}, {"draw_line", (PyCFunction)renderer_draw_line, - METH_VARARGS | METH_KEYWORDS, DOC_SDL2_VIDEO_RENDERER_DRAWLINE}, + METH_VARARGS | METH_KEYWORDS, DOC_RENDER_RENDERER_DRAWLINE}, {"draw_rect", (PyCFunction)renderer_draw_rect, - METH_VARARGS | METH_KEYWORDS, DOC_SDL2_VIDEO_RENDERER_DRAWRECT}, + METH_VARARGS | METH_KEYWORDS, DOC_RENDER_RENDERER_DRAWRECT}, {"draw_triangle", (PyCFunction)renderer_draw_triangle, - METH_VARARGS | METH_KEYWORDS, DOC_SDL2_VIDEO_RENDERER_DRAWTRIANGLE}, + METH_VARARGS | METH_KEYWORDS, DOC_RENDER_RENDERER_DRAWTRIANGLE}, {"draw_quad", (PyCFunction)renderer_draw_quad, - METH_VARARGS | METH_KEYWORDS, DOC_SDL2_VIDEO_RENDERER_DRAWQUAD}, + METH_VARARGS | METH_KEYWORDS, DOC_RENDER_RENDERER_DRAWQUAD}, {"fill_rect", (PyCFunction)renderer_fill_rect, - METH_VARARGS | METH_KEYWORDS, DOC_SDL2_VIDEO_RENDERER_FILLRECT}, + METH_VARARGS | METH_KEYWORDS, DOC_RENDER_RENDERER_FILLRECT}, {"fill_triangle", (PyCFunction)renderer_fill_triangle, - METH_VARARGS | METH_KEYWORDS, DOC_SDL2_VIDEO_RENDERER_FILLTRIANGLE}, + METH_VARARGS | METH_KEYWORDS, DOC_RENDER_RENDERER_FILLTRIANGLE}, {"fill_quad", (PyCFunction)renderer_fill_quad, - METH_VARARGS | METH_KEYWORDS, DOC_SDL2_VIDEO_RENDERER_FILLQUAD}, + METH_VARARGS | METH_KEYWORDS, DOC_RENDER_RENDERER_FILLQUAD}, {"present", (PyCFunction)renderer_present, METH_NOARGS, - DOC_SDL2_VIDEO_RENDERER_PRESENT}, + DOC_RENDER_RENDERER_PRESENT}, {"clear", (PyCFunction)renderer_clear, METH_NOARGS, - DOC_SDL2_VIDEO_RENDERER_CLEAR}, + DOC_RENDER_RENDERER_CLEAR}, {"set_viewport", (PyCFunction)renderer_set_viewport, - METH_VARARGS | METH_KEYWORDS, DOC_SDL2_VIDEO_RENDERER_SETVIEWPORT}, + METH_VARARGS | METH_KEYWORDS, DOC_RENDER_RENDERER_SETVIEWPORT}, {"get_viewport", (PyCFunction)renderer_get_viewport, METH_NOARGS, - DOC_SDL2_VIDEO_RENDERER_GETVIEWPORT}, + DOC_RENDER_RENDERER_GETVIEWPORT}, {"compose_custom_blend_mode", (PyCFunction)renderer_compose_custom_blend_mode, METH_VARARGS | METH_KEYWORDS | METH_CLASS, - DOC_SDL2_VIDEO_RENDERER_COMPOSECUSTOMBLENDMODE}, + DOC_RENDER_RENDERER_COMPOSECUSTOMBLENDMODE}, {"from_window", (PyCFunction)renderer_from_window, METH_CLASS | METH_VARARGS | METH_KEYWORDS, - DOC_SDL2_VIDEO_GETGRABBEDWINDOW}, + DOC_RENDER_RENDERER_FROMWINDOW}, {"to_surface", (PyCFunction)renderer_to_surface, - METH_VARARGS | METH_KEYWORDS, DOC_SDL2_VIDEO_RENDERER_TOSURFACE}, + METH_VARARGS | METH_KEYWORDS, DOC_RENDER_RENDERER_TOSURFACE}, {"blit", (PyCFunction)renderer_blit, METH_VARARGS | METH_KEYWORDS, - DOC_SDL2_VIDEO_RENDERER_SETVIEWPORT}, + DOC_RENDER_RENDERER_SETVIEWPORT}, {NULL, NULL, 0, NULL}}; static PyGetSetDef renderer_getset[] = { {"draw_color", (getter)renderer_get_draw_color, - (setter)renderer_set_draw_color, DOC_SDL2_VIDEO_RENDERER_DRAWCOLOR, NULL}, + (setter)renderer_set_draw_color, DOC_RENDER_RENDERER_DRAWCOLOR, NULL}, {"draw_blend_mode", (getter)renderer_get_draw_blend_mode, - (setter)renderer_set_draw_blend_mode, DOC_SDL2_VIDEO_RENDERER_DRAWCOLOR, + (setter)renderer_set_draw_blend_mode, DOC_RENDER_RENDERER_DRAWCOLOR, NULL}, {"logical_size", (getter)renderer_get_logical_size, - (setter)renderer_set_logical_size, DOC_SDL2_VIDEO_RENDERER_LOGICALSIZE, - NULL}, + (setter)renderer_set_logical_size, DOC_RENDER_RENDERER_LOGICALSIZE, NULL}, {"scale", (getter)renderer_get_scale, (setter)renderer_set_scale, - DOC_SDL2_VIDEO_RENDERER_SCALE, NULL}, + DOC_RENDER_RENDERER_SCALE, NULL}, {"target", (getter)renderer_get_target, (setter)renderer_set_target, - DOC_SDL2_VIDEO_RENDERER_TARGET, NULL}, + DOC_RENDER_RENDERER_TARGET, NULL}, {NULL, 0, NULL, NULL, NULL}}; static PyMethodDef texture_methods[] = {{NULL, NULL, 0, NULL}}; @@ -622,7 +622,7 @@ static PyTypeObject pgRenderer_Type = { PyVarObject_HEAD_INIT(NULL, 0).tp_name = "pygame._render.Renderer", .tp_basicsize = sizeof(pgRendererObject), .tp_dealloc = (destructor)renderer_dealloc, - .tp_doc = DOC_SDL2_VIDEO_RENDERER, + .tp_doc = DOC_RENDER_RENDERER, .tp_methods = renderer_methods, .tp_init = (initproc)renderer_init, .tp_new = PyType_GenericNew, From 1e1436be9b767f06e89052f63a8a9287bf4d7d46 Mon Sep 17 00:00:00 2001 From: damusss Date: Sat, 17 May 2025 10:52:39 +0200 Subject: [PATCH 2/5] Remove from module list, keep private --- buildconfig/stubs/pygame/_render.pyi | 21 +++++++++++++++++++++ docs/reST/index.rst | 3 --- docs/reST/ref/_render.rst | 16 ---------------- 3 files changed, 21 insertions(+), 19 deletions(-) delete mode 100644 docs/reST/ref/_render.rst diff --git a/buildconfig/stubs/pygame/_render.pyi b/buildconfig/stubs/pygame/_render.pyi index 91b7484d6b..df3e49c2a2 100644 --- a/buildconfig/stubs/pygame/_render.pyi +++ b/buildconfig/stubs/pygame/_render.pyi @@ -6,6 +6,27 @@ 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 diff --git a/docs/reST/index.rst b/docs/reST/index.rst index dc4bc51185..4961b2fdd7 100644 --- a/docs/reST/index.rst +++ b/docs/reST/index.rst @@ -68,9 +68,6 @@ turn them to stable API in the future ^^. :doc:`ref/sdl2_video` Pygame module for porting new SDL video systems. -:doc:`ref/_render` - Experimental pygame module porting the SDL render video system (A C implementation of the sdl2_video module, currently incomplete!) - .. _github: https://github.com/pygame-community/pygame-ce Documents diff --git a/docs/reST/ref/_render.rst b/docs/reST/ref/_render.rst deleted file mode 100644 index a0d32db2bd..0000000000 --- a/docs/reST/ref/_render.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. 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 461d0109a71f8c51e2e54376a3039824367b75cf Mon Sep 17 00:00:00 2001 From: Damiano <97639432+damusss@users.noreply.github.com> Date: Sat, 17 May 2025 10:53:47 +0200 Subject: [PATCH 3/5] Discard changes to src_c/render.c --- src_c/render.c | 46 +++++++++++++++++++++++----------------------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/src_c/render.c b/src_c/render.c index 2999b0153a..7dbdf29ccc 100644 --- a/src_c/render.c +++ b/src_c/render.c @@ -5,7 +5,6 @@ #include "pgcompat.h" #include "doc/sdl2_video_doc.h" -#include "doc/_render_doc.h" static PyTypeObject pgRenderer_Type; @@ -560,54 +559,55 @@ image_renderer_draw(pgImageObject *self, PyObject *area, PyObject *dest) /* Module definition */ static PyMethodDef renderer_methods[] = { {"draw_point", (PyCFunction)renderer_draw_point, - METH_VARARGS | METH_KEYWORDS, DOC_RENDER_RENDERER_DRAWPOINT}, + METH_VARARGS | METH_KEYWORDS, DOC_SDL2_VIDEO_RENDERER_DRAWPOINT}, {"draw_line", (PyCFunction)renderer_draw_line, - METH_VARARGS | METH_KEYWORDS, DOC_RENDER_RENDERER_DRAWLINE}, + METH_VARARGS | METH_KEYWORDS, DOC_SDL2_VIDEO_RENDERER_DRAWLINE}, {"draw_rect", (PyCFunction)renderer_draw_rect, - METH_VARARGS | METH_KEYWORDS, DOC_RENDER_RENDERER_DRAWRECT}, + METH_VARARGS | METH_KEYWORDS, DOC_SDL2_VIDEO_RENDERER_DRAWRECT}, {"draw_triangle", (PyCFunction)renderer_draw_triangle, - METH_VARARGS | METH_KEYWORDS, DOC_RENDER_RENDERER_DRAWTRIANGLE}, + METH_VARARGS | METH_KEYWORDS, DOC_SDL2_VIDEO_RENDERER_DRAWTRIANGLE}, {"draw_quad", (PyCFunction)renderer_draw_quad, - METH_VARARGS | METH_KEYWORDS, DOC_RENDER_RENDERER_DRAWQUAD}, + METH_VARARGS | METH_KEYWORDS, DOC_SDL2_VIDEO_RENDERER_DRAWQUAD}, {"fill_rect", (PyCFunction)renderer_fill_rect, - METH_VARARGS | METH_KEYWORDS, DOC_RENDER_RENDERER_FILLRECT}, + METH_VARARGS | METH_KEYWORDS, DOC_SDL2_VIDEO_RENDERER_FILLRECT}, {"fill_triangle", (PyCFunction)renderer_fill_triangle, - METH_VARARGS | METH_KEYWORDS, DOC_RENDER_RENDERER_FILLTRIANGLE}, + METH_VARARGS | METH_KEYWORDS, DOC_SDL2_VIDEO_RENDERER_FILLTRIANGLE}, {"fill_quad", (PyCFunction)renderer_fill_quad, - METH_VARARGS | METH_KEYWORDS, DOC_RENDER_RENDERER_FILLQUAD}, + METH_VARARGS | METH_KEYWORDS, DOC_SDL2_VIDEO_RENDERER_FILLQUAD}, {"present", (PyCFunction)renderer_present, METH_NOARGS, - DOC_RENDER_RENDERER_PRESENT}, + DOC_SDL2_VIDEO_RENDERER_PRESENT}, {"clear", (PyCFunction)renderer_clear, METH_NOARGS, - DOC_RENDER_RENDERER_CLEAR}, + DOC_SDL2_VIDEO_RENDERER_CLEAR}, {"set_viewport", (PyCFunction)renderer_set_viewport, - METH_VARARGS | METH_KEYWORDS, DOC_RENDER_RENDERER_SETVIEWPORT}, + METH_VARARGS | METH_KEYWORDS, DOC_SDL2_VIDEO_RENDERER_SETVIEWPORT}, {"get_viewport", (PyCFunction)renderer_get_viewport, METH_NOARGS, - DOC_RENDER_RENDERER_GETVIEWPORT}, + DOC_SDL2_VIDEO_RENDERER_GETVIEWPORT}, {"compose_custom_blend_mode", (PyCFunction)renderer_compose_custom_blend_mode, METH_VARARGS | METH_KEYWORDS | METH_CLASS, - DOC_RENDER_RENDERER_COMPOSECUSTOMBLENDMODE}, + DOC_SDL2_VIDEO_RENDERER_COMPOSECUSTOMBLENDMODE}, {"from_window", (PyCFunction)renderer_from_window, METH_CLASS | METH_VARARGS | METH_KEYWORDS, - DOC_RENDER_RENDERER_FROMWINDOW}, + DOC_SDL2_VIDEO_GETGRABBEDWINDOW}, {"to_surface", (PyCFunction)renderer_to_surface, - METH_VARARGS | METH_KEYWORDS, DOC_RENDER_RENDERER_TOSURFACE}, + METH_VARARGS | METH_KEYWORDS, DOC_SDL2_VIDEO_RENDERER_TOSURFACE}, {"blit", (PyCFunction)renderer_blit, METH_VARARGS | METH_KEYWORDS, - DOC_RENDER_RENDERER_SETVIEWPORT}, + DOC_SDL2_VIDEO_RENDERER_SETVIEWPORT}, {NULL, NULL, 0, NULL}}; static PyGetSetDef renderer_getset[] = { {"draw_color", (getter)renderer_get_draw_color, - (setter)renderer_set_draw_color, DOC_RENDER_RENDERER_DRAWCOLOR, NULL}, + (setter)renderer_set_draw_color, DOC_SDL2_VIDEO_RENDERER_DRAWCOLOR, NULL}, {"draw_blend_mode", (getter)renderer_get_draw_blend_mode, - (setter)renderer_set_draw_blend_mode, DOC_RENDER_RENDERER_DRAWCOLOR, + (setter)renderer_set_draw_blend_mode, DOC_SDL2_VIDEO_RENDERER_DRAWCOLOR, NULL}, {"logical_size", (getter)renderer_get_logical_size, - (setter)renderer_set_logical_size, DOC_RENDER_RENDERER_LOGICALSIZE, NULL}, + (setter)renderer_set_logical_size, DOC_SDL2_VIDEO_RENDERER_LOGICALSIZE, + NULL}, {"scale", (getter)renderer_get_scale, (setter)renderer_set_scale, - DOC_RENDER_RENDERER_SCALE, NULL}, + DOC_SDL2_VIDEO_RENDERER_SCALE, NULL}, {"target", (getter)renderer_get_target, (setter)renderer_set_target, - DOC_RENDER_RENDERER_TARGET, NULL}, + DOC_SDL2_VIDEO_RENDERER_TARGET, NULL}, {NULL, 0, NULL, NULL, NULL}}; static PyMethodDef texture_methods[] = {{NULL, NULL, 0, NULL}}; @@ -622,7 +622,7 @@ static PyTypeObject pgRenderer_Type = { PyVarObject_HEAD_INIT(NULL, 0).tp_name = "pygame._render.Renderer", .tp_basicsize = sizeof(pgRendererObject), .tp_dealloc = (destructor)renderer_dealloc, - .tp_doc = DOC_RENDER_RENDERER, + .tp_doc = DOC_SDL2_VIDEO_RENDERER, .tp_methods = renderer_methods, .tp_init = (initproc)renderer_init, .tp_new = PyType_GenericNew, From 180170b108e7f814748fe201989dcb3147ebd6c9 Mon Sep 17 00:00:00 2001 From: Damiano <97639432+damusss@users.noreply.github.com> Date: Sat, 17 May 2025 10:54:17 +0200 Subject: [PATCH 4/5] Discard changes to docs/reST/ext/boilerplate.py --- docs/reST/ext/boilerplate.py | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/reST/ext/boilerplate.py b/docs/reST/ext/boilerplate.py index 9c8d3a0f21..d4aeae34c9 100644 --- a/docs/reST/ext/boilerplate.py +++ b/docs/reST/ext/boilerplate.py @@ -350,7 +350,6 @@ def lowercase_name(d): "pixelcopy", "sndarray", "surfarray", - "_render" ] existing_order = ["pygame." + x for x in existing_order] From d1f5a4b44bf837de29d3db132e132ecedea53ae0 Mon Sep 17 00:00:00 2001 From: Damiano <97639432+damusss@users.noreply.github.com> Date: Sat, 17 May 2025 10:54:51 +0200 Subject: [PATCH 5/5] Delete src_c/doc/_render_doc.h --- src_c/doc/_render_doc.h | 23 ----------------------- 1 file changed, 23 deletions(-) delete mode 100644 src_c/doc/_render_doc.h diff --git a/src_c/doc/_render_doc.h b/src_c/doc/_render_doc.h deleted file mode 100644 index 4afd792721..0000000000 --- a/src_c/doc/_render_doc.h +++ /dev/null @@ -1,23 +0,0 @@ -/* Auto generated file: with make_docs.py . Docs go in docs/reST/ref/ . */ -#define DOC_RENDER_RENDERER "Renderer(window, index=-1, accelerated=-1, vsync=False, target_texture=False) -> Renderer\nObject wrapping a 2D rendering context for a window" -#define DOC_RENDER_RENDERER_BLIT "blit(source, dest=None, area=None, special_flags=0) -> Rect\nDraw textures using a Surface-like API" -#define DOC_RENDER_RENDERER_CLEAR "clear() -> None\nClear the current rendering target with the drawing color" -#define DOC_RENDER_RENDERER_DRAWLINE "draw_line(p1, p2) -> None\nDraw a line" -#define DOC_RENDER_RENDERER_DRAWPOINT "draw_point(point) -> None\nDraw a point" -#define DOC_RENDER_RENDERER_DRAWQUAD "draw_quad(p1, p2, p3, p4) -> None\nDraw a quad outline" -#define DOC_RENDER_RENDERER_DRAWRECT "draw_rect(rect) -> None\nDraw a rectangle outline" -#define DOC_RENDER_RENDERER_DRAWTRIANGLE "draw_triangle(p1, p2, p3) -> None\nDraw a triangle outline" -#define DOC_RENDER_RENDERER_FILLQUAD "fill_quad(p1, p2, p3, p4) -> None\nDraw a filled quad" -#define DOC_RENDER_RENDERER_FILLRECT "fill_rect(rect) -> None\nDraw a filled rectangle" -#define DOC_RENDER_RENDERER_FILLTRIANGLE "fill_triangle(p1, p2, p3) -> None\nDraw a filled triangle" -#define DOC_RENDER_RENDERER_GETVIEWPORT "get_viewport() -> Rect\nGet the drawing area on the rendering target" -#define DOC_RENDER_RENDERER_PRESENT "present() -> None\nUpdate the screen with any rendering performed since the previous call" -#define DOC_RENDER_RENDERER_SETVIEWPORT "set_viewport(area) -> None\nSet the drawing area on the rendering target" -#define DOC_RENDER_RENDERER_TOSURFACE "to_surface(surface=None, area=None) -> Surface\nRead pixels from current rendering target and create a Surface (slow operation, use sparingly)" -#define DOC_RENDER_RENDERER_DRAWBLENDMODE "draw_blend_mode -> int\nGet or set the blend mode used for primitive drawing operations" -#define DOC_RENDER_RENDERER_DRAWCOLOR "draw_color -> Color\nGet or set the color used for primitive drawing operations" -#define DOC_RENDER_RENDERER_LOGICALSIZE "logical_size -> tuple[int, int]\nGet or set the logical Renderer size (a device independent resolution for rendering)" -#define DOC_RENDER_RENDERER_SCALE "scale -> tuple[float, float]\nGet the drawing scale for the current rendering target" -#define DOC_RENDER_RENDERER_TARGET "target -> Texture\nGet or set the current rendering target" -#define DOC_RENDER_RENDERER_COMPOSECUSTOMBLENDMODE "compose_custom_blend_mode(color_mode, alpha_mode) -> int\nCompose a custom blend mode" -#define DOC_RENDER_RENDERER_FROMWINDOW "from_window(window) -> Renderer\nCreate a Renderer from an existing window"