Merge pull request #2800 from mzivic7/draw.aacircle

draw.aacircle()

Author: oddbookworm

buildconfig/stubs/pygame/draw.pyi

@@ -1,5 +1,6 @@
 from pygame.rect import Rect
 from pygame.surface import Surface
+from typing import overload
 
 from ._common import ColorValue, Coordinate, RectValue, Sequence
 
@@ -31,6 +32,26 @@ def circle(
     draw_bottom_left: bool = False,
     draw_bottom_right: bool = False,
 ) -> Rect: ...
+@overload
+def aacircle(
+    surface: Surface,
+    color: ColorValue,
+    center: Coordinate,
+    radius: float,
+    width: int = 0,
+) -> Rect: ...
+@overload
+def aacircle(
+    surface: Surface,
+    color: ColorValue,
+    center: Coordinate,
+    radius: float,
+    width: int = 0,
+    draw_top_right: bool = False,
+    draw_top_left: bool = False,
+    draw_bottom_left: bool = False,
+    draw_bottom_right: bool = False,
+) -> Rect: ...
 def ellipse(
     surface: Surface, color: ColorValue, rect: RectValue, width: int = 0
 ) -> Rect: ...

docs/reST/ref/code_examples/draw_module_example.png

@@ -77,6 +77,15 @@
 
     # Draw a circle
     pygame.draw.circle(screen, "blue", [60, 250], 40)
+    
+    # Draw an antialiased circle with 3 pixels wide line
+    pygame.draw.aacircle(screen, "green", [340, 250], 40, 3)
+    
+    # Draw an antialiased top right circle quadrant with 4 pixels wide line
+    pygame.draw.aacircle(screen, "red", [340, 250], 20, 4, draw_top_right=True)
+    
+    # Draw an antialiased bottom left filled circle quadrant
+    pygame.draw.aacircle(screen, "blue", [340, 250], 20, draw_bottom_left=True)
 
     # Draw only one circle quadrant
     pygame.draw.circle(screen, "blue", [250, 250], 40, 0, draw_top_right=True)

docs/reST/ref/code_examples/draw_module_example.py

@@ -206,6 +206,62 @@ object around the draw calls (see :func:`pygame.Surface.lock` and
 
    .. ## pygame.draw.circle ##
 
+.. function:: aacircle
+
+   | :sl:`draw an antialiased circle`
+   | :sg:`aacircle(surface, color, center, radius) -> Rect`
+   | :sg:`aacircle(surface, color, center, radius, width=0, draw_top_right=None, draw_top_left=None, draw_bottom_left=None, draw_bottom_right=None) -> Rect`
+
+   Draws an antialiased circle on the given surface.
+   Uses Xaolin Wu Circle Algorithm.
+   adapted from: https://cgg.mff.cuni.cz/~pepca/ref/WU.pdf
+
+   :param Surface surface: surface to draw on
+   :param color: color to draw with, the alpha value is optional if using a
+      tuple ``(RGB[A])``
+   :type color: Color or string (for :doc:`color_list`) or int or tuple(int, int, int, [int])
+   :param center: center point of the circle as a sequence of 2 ints/floats,
+      e.g. ``(x, y)``
+   :type center: tuple(int or float, int or float) or
+      list(int or float, int or float) or Vector2(int or float, int or float)
+   :param radius: radius of the circle, measured from the ``center`` parameter,
+      nothing will be drawn if the ``radius`` is less than 1
+   :type radius: int or float
+   :param int width: (optional) used for line thickness or to indicate that
+      the circle is to be filled
+
+         | if ``width == 0``, (default) fill the circle
+         | if ``width > 0``, used for line thickness
+         | if ``width < 0``, nothing will be drawn
+         |
+
+         .. note::
+            When using ``width`` values ``> 1``, the edge lines will only grow
+            inward.
+   :param bool draw_top_right: (optional) if this is set to True then the top right corner
+      of the circle will be drawn
+   :param bool draw_top_left: (optional) if this is set to True then the top left corner
+      of the circle will be drawn
+   :param bool draw_bottom_left: (optional) if this is set to True then the bottom left corner
+      of the circle will be drawn
+   :param bool draw_bottom_right: (optional) if this is set to True then the bottom right corner
+      of the circle will be drawn
+
+         | if any of the draw_circle_part is True then it will draw all circle parts that have the True
+         | value, otherwise it will draw the entire circle.
+
+   :returns: a rect bounding the changed pixels, if nothing is drawn the
+      bounding rect's position will be the ``center`` parameter value (float
+      values will be truncated) and its width and height will be 0
+   :rtype: Rect
+
+   :raises TypeError: if ``center`` is not a sequence of two numbers
+   :raises TypeError: if ``radius`` is not a number
+
+   .. versionadded:: 2.5.0
+
+   .. ## pygame.draw.aacircle ##
+
 .. function:: ellipse
 
    | :sl:`draw an ellipse`

docs/reST/ref/draw.rst

@@ -3,6 +3,7 @@
 #define DOC_DRAW_RECT "rect(surface, color, rect) -> Rect\nrect(surface, color, rect, width=0, border_radius=0, border_top_left_radius=-1, border_top_right_radius=-1, border_bottom_left_radius=-1, border_bottom_right_radius=-1) -> Rect\ndraw a rectangle"
 #define DOC_DRAW_POLYGON "polygon(surface, color, points) -> Rect\npolygon(surface, color, points, width=0) -> Rect\ndraw a polygon"
 #define DOC_DRAW_CIRCLE "circle(surface, color, center, radius) -> Rect\ncircle(surface, color, center, radius, width=0, draw_top_right=None, draw_top_left=None, draw_bottom_left=None, draw_bottom_right=None) -> Rect\ndraw a circle"
+#define DOC_DRAW_AACIRCLE "aacircle(surface, color, center, radius) -> Rect\naacircle(surface, color, center, radius, width=0, draw_top_right=None, draw_top_left=None, draw_bottom_left=None, draw_bottom_right=None) -> Rect\ndraw an antialiased circle"
 #define DOC_DRAW_ELLIPSE "ellipse(surface, color, rect) -> Rect\nellipse(surface, color, rect, width=0) -> Rect\ndraw an ellipse"
 #define DOC_DRAW_ARC "arc(surface, color, rect, start_angle, stop_angle) -> Rect\narc(surface, color, rect, start_angle, stop_angle, width=1) -> Rect\ndraw an elliptical arc"
 #define DOC_DRAW_LINE "line(surface, color, start_pos, end_pos) -> Rect\nline(surface, color, start_pos, end_pos, width=1) -> Rect\ndraw a straight line"