Shim and deprecate pygame.gfxdraw using pygame.draw

buildconfig/Setup.Android.SDL2.in

@@ -29,7 +29,7 @@ _sdl2.controller_old src_c/_sdl2/controller_old.c $(SDL) $(DEBUG) -Isrc_c
 
 GFX = src_c/SDL_gfx/SDL_gfxPrimitives.c
 #GFX = src_c/SDL_gfx/SDL_gfxBlitFunc.c src_c/SDL_gfx/SDL_gfxPrimitives.c
-gfxdraw src_c/gfxdraw.c $(SDL) $(GFX) $(DEBUG)
+_gfxdraw src_c/_gfxdraw.c $(SDL) $(GFX) $(DEBUG)
 
 #optional freetype module (do not break in multiple lines
 #or the configuration script will choke!)

buildconfig/Setup.Emscripten.SDL2.in

@@ -48,7 +48,7 @@ display src_c/void.c
 draw src_c/void.c
 event src_c/void.c
 font src_c/void.c
-gfxdraw  src_c/void.c
+_gfxdraw  src_c/void.c
 joystick src_c/void.c
 key src_c/void.c
 newbuffer  src_c/void.c

buildconfig/Setup.SDL2.in

@@ -39,7 +39,7 @@ _sdl2.controller_old src_c/_sdl2/controller_old.c $(SDL) $(DEBUG) -Isrc_c
 
 GFX = src_c/SDL_gfx/SDL_gfxPrimitives.c
 #GFX = src_c/SDL_gfx/SDL_gfxBlitFunc.c src_c/SDL_gfx/SDL_gfxPrimitives.c
-gfxdraw src_c/gfxdraw.c $(SDL) $(GFX) $(DEBUG)
+_gfxdraw src_c/_gfxdraw.c $(SDL) $(GFX) $(DEBUG)
 
 #optional freetype module (do not break in multiple lines
 #or the configuration script will choke!)

buildconfig/stubs/pygame/gfxdraw.pyi

@@ -1,47 +1,63 @@
 from pygame.surface import Surface
+from typing_extensions import deprecated # added in 3.13
 
 from ._common import ColorValue, Coordinate, RectValue, Sequence
 
+@deprecated("since GFX_DEPRECATED_VERSION. Use `pygame.Surface.set_at` instead")
 def pixel(surface: Surface, x: int, y: int, color: ColorValue, /) -> None: ...
+@deprecated("since GFX_DEPRECATED_VERSION. Use `pygame.draw.line` instead")
 def hline(surface: Surface, x1: int, x2: int, y: int, color: ColorValue, /) -> None: ...
+@deprecated("since GFX_DEPRECATED_VERSION. Use `pygame.draw.line` instead")
 def vline(surface: Surface, x: int, y1: int, y2: int, color: ColorValue, /) -> None: ...
+@deprecated("since GFX_DEPRECATED_VERSION. Use `pygame.draw.line` instead")
 def line(
     surface: Surface, x1: int, y1: int, x2: int, y2: int, color: ColorValue, /
 ) -> None: ...
+@deprecated("since GFX_DEPRECATED_VERSION. Use `pygame.draw.rect` instead")
 def rectangle(surface: Surface, rect: RectValue, color: ColorValue, /) -> None: ...
+@deprecated("since GFX_DEPRECATED_VERSION. Use `pygame.draw.rect` instead")
 def box(surface: Surface, rect: RectValue, color: ColorValue, /) -> None: ...
+@deprecated("since GFX_DEPRECATED_VERSION. Use `pygame.draw.circle` instead")
 def circle(surface: Surface, x: int, y: int, r: int, color: ColorValue, /) -> None: ...
+@deprecated("since GFX_DEPRECATED_VERSION. Use `pygame.draw.aacircle` instead")
 def aacircle(surface: Surface, x: int, y: int, r: int, color: ColorValue, /) -> None: ...
+@deprecated("since GFX_DEPRECATED_VERSION. Use `pygame.draw.circle` instead")
 def filled_circle(
     surface: Surface, x: int, y: int, r: int, color: ColorValue, /
 ) -> None: ...
+@deprecated("since GFX_DEPRECATED_VERSION. Use `pygame.draw.ellipse` instead")
 def ellipse(
     surface: Surface, x: int, y: int, rx: int, ry: int, color: ColorValue, /
 ) -> None: ...
+@deprecated("since GFX_DEPRECATED_VERSION. Use `pygame.draw.aaellipse` instead") # not implemented yet
 def aaellipse(
     surface: Surface, x: int, y: int, rx: int, ry: int, color: ColorValue, /
 ) -> None: ...
+@deprecated("since GFX_DEPRECATED_VERSION. Use `pygame.draw.ellipse` instead")
 def filled_ellipse(
     surface: Surface, x: int, y: int, rx: int, ry: int, color: ColorValue, /
 ) -> None: ...
+@deprecated("since GFX_DEPRECATED_VERSION. Use `pygame.draw.arc` instead")
 def arc(
     surface: Surface,
     x: int,
     y: int,
     r: int,
     start_angle: int,
-    atp_angle: int,
+    stop_angle: int,
     color: ColorValue, /
 ) -> None: ...
+@deprecated("since GFX_DEPRECATED_VERSION. Use `pygame.draw.arc` and `pygame.draw.line` instead")
 def pie(
     surface: Surface,
     x: int,
     y: int,
     r: int,
     start_angle: int,
-    atp_angle: int,
+    stop_angle: int,
     color: ColorValue, /
 ) -> None: ...
+@deprecated("since GFX_DEPRECATED_VERSION. Use `pygame.draw.polygon` instead")
 def trigon(
     surface: Surface,
     x1: int,
@@ -52,6 +68,7 @@ def trigon(
     y3: int,
     color: ColorValue, /
 ) -> None: ...
+@deprecated("since GFX_DEPRECATED_VERSION. Use `pygame.draw.aalines` instead") # should replace with aapolygon
 def aatrigon(
     surface: Surface,
     x1: int,
@@ -62,6 +79,7 @@ def aatrigon(
     y3: int,
     color: ColorValue, /
 ) -> None: ...
+@deprecated("since GFX_DEPRECATED_VERSION. Use `pygame.draw.polygon` instead")
 def filled_trigon(
     surface: Surface,
     x1: int,
@@ -72,18 +90,23 @@ def filled_trigon(
     y3: int,
     color: ColorValue, /
 ) -> None: ...
+@deprecated("since GFX_DEPRECATED_VERSION. Use `pygame.draw.polygon` instead")
 def polygon(
     surface: Surface, points: Sequence[Coordinate], color: ColorValue, /
 ) -> None: ...
+@deprecated("since GFX_DEPRECATED_VERSION. Use `pygame.draw.aalines` instead") # should replace with aapolygon
 def aapolygon(
     surface: Surface, points: Sequence[Coordinate], color: ColorValue, /
 ) -> None: ...
+@deprecated("since GFX_DEPRECATED_VERSION. Use `pygame.draw.polygon` instead")
 def filled_polygon(
     surface: Surface, points: Sequence[Coordinate], color: ColorValue, /
 ) -> None: ...
+@deprecated("since GFX_DEPRECATED_VERSION.")
 def textured_polygon(
     surface: Surface, points: Sequence[Coordinate], texture: Surface, tx: int, ty: int, /
 ) -> None: ...
+@deprecated("since GFX_DEPRECATED_VERSION. Use `pygame.draw.bezier` instead") # not implemented yet
 def bezier(
     surface: Surface, points: Sequence[Coordinate], steps: int, color: ColorValue, /
 ) -> None: ...

docs/reST/ref/gfxdraw.rst

@@ -8,8 +8,8 @@
 
 | :sl:`pygame module for drawing shapes`
 
-**EXPERIMENTAL!**: This API may change or disappear in later pygame releases. If
-you use this, your code may break with the next pygame release.
+**DEPRECATED!**: The gfxdraw module is now deprecated in favor of the draw module
+and all its functions are also deprecated.
 
 The pygame package does not import gfxdraw automatically when loaded, so it
 must imported explicitly to be used.
@@ -26,6 +26,7 @@ following formats:
    - a :mod:`pygame.Color` object
    - an ``(RGB)`` triplet (tuple/list)
    - an ``(RGBA)`` quadruplet (tuple/list)
+   - a ``"color"`` string
 
 The functions :meth:`rectangle` and :meth:`box` will accept any ``(x, y, w, h)``
 sequence for their ``rect`` argument, though :mod:`pygame.Rect` instances are
@@ -43,17 +44,6 @@ For example:
    pygame.gfxdraw.filled_circle(surf, x, y, 30, col)
 
 
-.. note::
-   For threading, each of the functions releases the GIL during the C part of
-   the call.
-
-.. note::
-   See the :mod:`pygame.draw` module for alternative draw methods.
-   The ``pygame.gfxdraw`` module differs from the :mod:`pygame.draw` module in
-   the API it uses and the different draw functions available.
-   ``pygame.gfxdraw`` wraps the primitives from the library called SDL_gfx,
-   rather than using modified versions.
-
 .. versionaddedold:: 1.9.0
 
 
@@ -74,6 +64,8 @@ For example:
    :returns: ``None``
    :rtype: NoneType
 
+   .. deprecated:: GFX_DEPRECATED_VERSION Use :mod:`pygame.Surface.set_at` instead.
+
    .. ## pygame.gfxdraw.pixel ##
 
 .. function:: hline
@@ -95,6 +87,8 @@ For example:
    :returns: ``None``
    :rtype: NoneType
 
+   .. deprecated:: GFX_DEPRECATED_VERSION Use :mod:`pygame.draw.line` instead.
+
    .. ## pygame.gfxdraw.hline ##
 
 .. function:: vline
@@ -116,6 +110,8 @@ For example:
    :returns: ``None``
    :rtype: NoneType
 
+   .. deprecated:: GFX_DEPRECATED_VERSION Use :mod:`pygame.draw.line` instead.
+
    .. ## pygame.gfxdraw.vline ##
 
 .. function:: line
@@ -138,6 +134,8 @@ For example:
    :returns: ``None``
    :rtype: NoneType
 
+   .. deprecated:: GFX_DEPRECATED_VERSION Use :mod:`pygame.draw.line` instead.
+
    .. ## pygame.gfxdraw.line ##
 
 .. function:: rectangle
@@ -162,6 +160,8 @@ For example:
       always lie one pixel outside of its actual border. Therefore, these
       values will not be included as part of the drawing.
 
+   .. deprecated:: GFX_DEPRECATED_VERSION Use :mod:`pygame.draw.rect` instead.
+
    .. ## pygame.gfxdraw.rectangle ##
 
 .. function:: box
@@ -192,6 +192,8 @@ For example:
       accelerated on some platforms with both software and hardware display
       modes.
 
+   .. deprecated:: GFX_DEPRECATED_VERSION Use :mod:`pygame.draw.rect` instead.
+
    .. ## pygame.gfxdraw.box ##
 
 .. function:: circle
@@ -213,6 +215,8 @@ For example:
    :returns: ``None``
    :rtype: NoneType
 
+   .. deprecated:: GFX_DEPRECATED_VERSION Use :mod:`pygame.draw.circle` instead.
+
    .. ## pygame.gfxdraw.circle ##
 
 .. function:: aacircle
@@ -233,6 +237,8 @@ For example:
    :returns: ``None``
    :rtype: NoneType
 
+   .. deprecated:: GFX_DEPRECATED_VERSION Use :mod:`pygame.draw.aacircle` instead.
+
    .. ## pygame.gfxdraw.aacircle ##
 
 .. function:: filled_circle
@@ -254,6 +260,8 @@ For example:
    :returns: ``None``
    :rtype: NoneType
 
+   .. deprecated:: GFX_DEPRECATED_VERSION Use :mod:`pygame.draw.circle` instead.
+
    .. ## pygame.gfxdraw.filled_circle ##
 
 .. function:: ellipse
@@ -276,6 +284,8 @@ For example:
    :returns: ``None``
    :rtype: NoneType
 
+   .. deprecated:: GFX_DEPRECATED_VERSION Use :mod:`pygame.draw.ellipse` instead.
+
    .. ## pygame.gfxdraw.ellipse ##
 
 .. function:: aaellipse
@@ -297,6 +307,8 @@ For example:
    :returns: ``None``
    :rtype: NoneType
 
+   .. deprecated:: GFX_DEPRECATED_VERSION Use :mod:`pygame.draw.aaellipse` instead.
+
    .. ## pygame.gfxdraw.aaellipse ##
 
 .. function:: filled_ellipse
@@ -319,6 +331,8 @@ For example:
    :returns: ``None``
    :rtype: NoneType
 
+   .. deprecated:: GFX_DEPRECATED_VERSION Use :mod:`pygame.draw.ellipse` instead.
+
    .. ## pygame.gfxdraw.filled_ellipse ##
 
 .. function:: arc
@@ -347,6 +361,8 @@ For example:
    :returns: ``None``
    :rtype: NoneType
 
+   .. deprecated:: GFX_DEPRECATED_VERSION Use :mod:`pygame.draw.arc` instead.
+
    .. note::
       This function uses *degrees* while the :func:`pygame.draw.arc` function
       uses *radians*.
@@ -380,6 +396,8 @@ For example:
    :returns: ``None``
    :rtype: NoneType
 
+   .. deprecated:: GFX_DEPRECATED_VERSION Use :mod:`pygame.draw.arc` and `pygame.draw.line` instead.
+
    .. ## pygame.gfxdraw.pie ##
 
 .. function:: trigon
@@ -407,6 +425,8 @@ For example:
    :returns: ``None``
    :rtype: NoneType
 
+   .. deprecated:: GFX_DEPRECATED_VERSION Use :mod:`pygame.draw.polygon` instead.
+
    .. ## pygame.gfxdraw.trigon ##
 
 .. function:: aatrigon
@@ -433,6 +453,8 @@ For example:
    :returns: ``None``
    :rtype: NoneType
 
+   .. deprecated:: GFX_DEPRECATED_VERSION Use :mod:`pygame.draw.aalines` instead.
+
    .. ## pygame.gfxdraw.aatrigon ##
 
 .. function:: filled_trigon
@@ -460,6 +482,8 @@ For example:
    :returns: ``None``
    :rtype: NoneType
 
+   .. deprecated:: GFX_DEPRECATED_VERSION Use :mod:`pygame.draw.polygon` instead.
+
    .. ## pygame.gfxdraw.filled_trigon ##
 
 .. function:: polygon
@@ -493,6 +517,8 @@ For example:
    :raises IndexError: if ``len(coordinate) < 2`` (each coordinate must have
       at least 2 items)
 
+   .. deprecated:: GFX_DEPRECATED_VERSION Use :mod:`pygame.draw.polygon` instead.
+
    .. ## pygame.gfxdraw.polygon ##
 
 .. function:: aapolygon
@@ -525,6 +551,8 @@ For example:
    :raises IndexError: if ``len(coordinate) < 2`` (each coordinate must have
       at least 2 items)
 
+   .. deprecated:: GFX_DEPRECATED_VERSION Use :mod:`pygame.draw.aalines` instead.
+
    .. ## pygame.gfxdraw.aapolygon ##
 
 .. function:: filled_polygon
@@ -558,6 +586,8 @@ For example:
    :raises IndexError: if ``len(coordinate) < 2`` (each coordinate must have
       at least 2 items)
 
+   .. deprecated:: GFX_DEPRECATED_VERSION Use :mod:`pygame.draw.polygon` instead.
+
    .. ## pygame.gfxdraw.filled_polygon ##
 
 .. function:: textured_polygon
@@ -595,6 +625,8 @@ For example:
    :raises IndexError: if ``len(coordinate) < 2`` (each coordinate must have
       at least 2 items)
 
+   .. deprecated:: GFX_DEPRECATED_VERSION
+
    .. ## pygame.gfxdraw.textured_polygon ##
 
 .. function:: bezier
@@ -626,6 +658,8 @@ For example:
    .. note:: This function supports up to around 150-200 points before the algorithm
              breaks down.
 
+   .. deprecated:: GFX_DEPRECATED_VERSION Use :mod:`pygame.draw.bezier` instead.
+
    .. ## pygame.gfxdraw.bezier ##
 
 .. ## pygame.gfxdraw ##

docs/reST/themes/classic/elements.html

@@ -39,8 +39,8 @@ <h5>pygame-ce documentation</h5>
 
 #}
 {%- set basic = ['Color', 'display', 'draw', 'event', 'font', 'image', 'key', 'locals', 'mixer', 'mouse', 'music', 'pygame', 'Rect', 'Surface', 'time'] %}
-{%- set advanced = ['BufferProxy', 'freetype', 'gfxdraw', 'midi', 'PixelArray', 'pixelcopy', 'sndarray', 'surfarray', 'cursors', 'joystick', 'mask', 'math', 'sprite', 'transform'] %}
-{%- set hidden = ['sdl2_video', 'sdl2_controller', 'geometry', 'Window'] %}
+{%- set advanced = ['BufferProxy', 'freetype', 'midi', 'PixelArray', 'pixelcopy', 'sndarray', 'surfarray', 'cursors', 'joystick', 'mask', 'math', 'sprite', 'transform'] %}
+{%- set hidden = ['sdl2_video', 'sdl2_controller', 'geometry', 'Window', 'gfxdraw'] %}
 {%-   if pyg_sections %}
 	  <p class="bottom"><b>Most useful stuff</b>:
 {%      set sep = joiner(" | \n") %}