The `pygame.draw.aacircle` function cannot draw arcs with a thickness of 2.

[Fantastair]

Environment:

Platform:               Linux-6.12.63+deb13-amd64-x86_64-with-glibc2.41
System:                 Linux
System Version:         #1 SMP PREEMPT_DYNAMIC Debian 6.12.63-1 (2025-12-30)
Processor:                      SSE2: Yes       AVX2: Yes       NEON: No
Architecture:           Bits: 64bit     Linkage: ELF

Python:                 CPython 3.13.5 (main, Jun 25 2025, 18:55:22) [GCC 14.2.0]
GIL Enabled:            True
pygame version:         2.5.6
SDL versions:           Linked: 2.32.10 Compiled: 2.32.10
SDL Mixer versions:     Linked: 2.8.1   Compiled: 2.8.1
SDL Font versions:      Linked: 2.24.0  Compiled: 2.24.0
SDL Image versions:     Linked: 2.8.8   Compiled: 2.8.8
Freetype versions:      Linked: 2.13.3  Compiled: 2.13.3

Display Driver:         Display Not Initialized
Mixer Driver:           Mixer Not Initialized

• Relevant hardware: NVIDIA GeForce RTX 4060 Laptop GPU (Driver Version: 550.163.01), 2560×1600 high-DPI display, 150 % system scaling.

Current behavior:

The pygame.draw.aacircle function accepts a width parameter. When width > 0, it controls the thickness of the arc line. However, I've discovered this function cannot draw arcs with a width of 2. When width = 1, it draws an arc with a width of 1; when width > 1, it draws an arc with a width of width + 1. This means the actual widths that can be drawn are “1, 3, 4, 5, ...”.

Incidentally, I'm using the pygame.Window class to manage the window and have set allow_high_dpi=True for my high-DPI display, though I don't believe this should affect the issue.

[Fantastair]

Here are some additional screenshots.

I initially thought it was a bug in my own program, so I tried to fix it and discovered this relationship between the thickness of the arc and the width.

bw refers to the border width. The horizontal and vertical lines were drawn using pygame.Surface.fill, while the arc lines were drawn using pygame.draw.aacircle.

• width = 1
  The arc and straight line share the same thickness, both measuring 1 pixel, with seamless alignment.
  

• width = 2
  The arc is 1 pixel thicker than the straight line.
  
  Zoom in for a closer look, or you can click on the image to view it—it'll be clearer that way.
  

When width is larger, the arc is always 1 pixel thicker than the straight line.

[Fantastair]

I've written a simple example that should make it clearer.

import pygame
import pygame.freetype

pygame.init()
pygame.freetype.init()

screen = pygame.display.set_mode((800, 400))

WHITE = pygame.Color('white')
BLACK = pygame.Color('black')

font = pygame.freetype.Font(None)

screen.fill(WHITE)

# width = 1
pygame.draw.aacircle(screen, BLACK, (100, 120), 20, width=1, draw_top_left=True)

font.render_to(screen, (60, 50), "width = 1", BLACK, size=24)
screen.fill(BLACK, pygame.Rect(102, 100, 40, 1))
pygame.draw.rect(screen, BLACK, pygame.Rect(90, 90, 20, 20), 1)
pygame.draw.line(screen, BLACK, (90, 110), (20, 200), 1)
pygame.draw.line(screen, BLACK, (110, 110), (180, 200), 1)
font.render_to(screen, (90, 180), "8x", BLACK, size=24)
s = pygame.transform.scale(screen.subsurface(pygame.Rect(90, 90, 20, 20)), (160, 160))
screen.blit(s, (20, 200))

# width = 2
pygame.draw.aacircle(screen, BLACK, (300, 120), 20, width=2, draw_top_left=True)

font.render_to(screen, (260, 50), "width = 2", BLACK, size=24)
screen.fill(BLACK, pygame.Rect(302, 100, 40, 2))
pygame.draw.rect(screen, BLACK, pygame.Rect(290, 90, 20, 20), 1)
pygame.draw.line(screen, BLACK, (290, 110), (220, 200), 1)
pygame.draw.line(screen, BLACK, (310, 110), (380, 200), 1)
font.render_to(screen, (290, 180), "8x", BLACK, size=24)
s = pygame.transform.scale(screen.subsurface(pygame.Rect(290, 90, 20, 20)), (160, 160))
screen.blit(s, (220, 200))

# width = 3
pygame.draw.aacircle(screen, BLACK, (500, 120), 20, width=3, draw_top_left=True)

font.render_to(screen, (460, 50), "width = 3", BLACK, size=24)
screen.fill(BLACK, pygame.Rect(502, 100, 40, 3))
pygame.draw.rect(screen, BLACK, pygame.Rect(490, 90, 20, 20), 1)
pygame.draw.line(screen, BLACK, (490, 110), (420, 200), 1)
pygame.draw.line(screen, BLACK, (510, 110), (580, 200), 1)
font.render_to(screen, (490, 180), "8x", BLACK, size=24)
s = pygame.transform.scale(screen.subsurface(pygame.Rect(490, 90, 20, 20)), (160, 160))
screen.blit(s, (420, 200))

# width = 8
pygame.draw.aacircle(screen, BLACK, (700, 120), 20, width=8, draw_top_left=True)

font.render_to(screen, (660, 50), "width = 8", BLACK, size=24)
screen.fill(BLACK, pygame.Rect(702, 100, 40, 8))
pygame.draw.rect(screen, BLACK, pygame.Rect(690, 95, 20, 20), 1)
pygame.draw.line(screen, BLACK, (690, 115), (620, 200), 1)
pygame.draw.line(screen, BLACK, (710, 115), (780, 200), 1)
font.render_to(screen, (690, 180), "8x", BLACK, size=24)
s = pygame.transform.scale(screen.subsurface(pygame.Rect(690, 95, 20, 20)), (160, 160))
screen.blit(s, (620, 200))

pygame.display.flip()

RUNNING = True
while RUNNING:
    for event in pygame.event.get():
        if event.type == pygame.QUIT:
            RUNNING = False

In short, it is impossible to draw an arc with a thickness of 2 using pygame.draw.aacircle.

[ankith26]

Hello, thanks for the bug report and the detailed MRE.

I tested both 2.5.0 (the release that draw.aacircle was introduced) and 2.5.6 (latest) and the issue happens in both cases.

[Fantastair]

I examined the implementation code for pygame.draw.aacircle(), which is adapted from the “Xiaolin Wu Circle Algorithm”. The reason it correctly draws a circle with a width of 1 is that this algorithm was specifically designed to achieve anti-aliased curves with a 1-pixel width for rasterization. However, pygame actually uses many circles with continuous radii stitched together to draw circles of arbitrary width, and this is where the problem lies.

Inside aacircle(), the draw_circle_xiaolinwu() function is called, where the width parameter of aacircle() is passed to the thickness parameter. draw_circle_xiaolinwu() calculates the starting point of the radius to be drawn using radius - thickness, while the endpoint is radius, forming a closed interval.

static void
draw_circle_xiaolinwu(...)
{
    for (int layer_radius = radius - thickness; layer_radius <= radius;
         layer_radius++) {
        ...
    }
}

For example, when I attempt to draw a circle with radius = 5 and width = 2, it actually renders a circle with a radius in the closed interval [5-2, 5](that is, {3, 4, 5}) at a width of 1 pixel. This results in a circle with a width of 3 pixels. And this explains the previous issue: why an extra width pixel is always drawn in the circle.

[Fantastair]

When I call draw_circle_xiaolinwu() inside draw.aacircle(), passing width - 1 to the thickness parameter and recompiling pygame-ce 2.5.7.dev1 (SDL 2.32.4, Python 3.13.5), the function correctly draws the specified width.

However, I'm wondering whether this error should be fixed directly within draw_circle_xiaolinwu(), or at the very least, a comment should be added to clarify this detail.