0
# Advanced Drawing
1

2
High-performance primitive drawing operations with antialiasing and advanced features. The pygame.gfxdraw module provides optimized functions for drawing shapes, textures, and geometric primitives with pixel-level precision and enhanced visual quality through antialiasing.
3

4
```python
5
import pygame.gfxdraw
6
```
7

8
## Capabilities
9

10
### Pixel and Line Operations
11

12
Draw individual pixels and optimized horizontal/vertical lines for precise control.
13

14
```python { .api }
15
def pixel(surface: pygame.Surface, x: int, y: int, color) -> None:
16
    """
17
    Draw a single pixel on a surface.
18

19
    Args:
20
        surface (pygame.Surface): Surface to draw on
21
        x (int): X coordinate
22
        y (int): Y coordinate
23
        color: Color to use (Color, tuple, or color name)
24
    """
25

26
def hline(surface: pygame.Surface, x1: int, x2: int, y: int, color) -> None:
27
    """
28
    Draw a horizontal line on a surface.
29

30
    Args:
31
        surface (pygame.Surface): Surface to draw on
32
        x1 (int): Starting X coordinate
33
        x2 (int): Ending X coordinate
34
        y (int): Y coordinate for the line
35
        color: Color to use
36
    """
37

38
def vline(surface: pygame.Surface, x: int, y1: int, y2: int, color) -> None:
39
    """
40
    Draw a vertical line on a surface.
41

42
    Args:
43
        surface (pygame.Surface): Surface to draw on
44
        x (int): X coordinate for the line
45
        y1 (int): Starting Y coordinate
46
        y2 (int): Ending Y coordinate
47
        color: Color to use
48
    """
49
```
50

51
### Rectangle Drawing
52

53
Draw rectangles with outline and filled variants for efficient rendering.
54

55
```python { .api }
56
def rectangle(surface: pygame.Surface, rect: pygame.Rect, color) -> None:
57
    """
58
    Draw a rectangle outline on a surface.
59

60
    Args:
61
        surface (pygame.Surface): Surface to draw on
62
        rect (pygame.Rect): Rectangle area to draw
63
        color: Color to use for the outline
64
    """
65

66
def box(surface: pygame.Surface, rect: pygame.Rect, color) -> None:
67
    """
68
    Draw a filled rectangle on a surface.
69

70
    Args:
71
        surface (pygame.Surface): Surface to draw on
72
        rect (pygame.Rect): Rectangle area to fill
73
        color: Color to use for filling
74
    """
75
```
76

77
### Antialiased Shapes
78

79
Draw smooth, antialiased shapes for high-quality graphics with reduced aliasing artifacts.
80

81
```python { .api }
82
def aacircle(surface: pygame.Surface, x: int, y: int, r: int, color) -> None:
83
    """
84
    Draw an antialiased circle outline on a surface.
85

86
    Args:
87
        surface (pygame.Surface): Surface to draw on
88
        x (int): X coordinate of center
89
        y (int): Y coordinate of center
90
        r (int): Radius in pixels
91
        color: Color to use
92
    """
93

94
def aaellipse(surface: pygame.Surface, x: int, y: int, rx: int, ry: int, color) -> None:
95
    """
96
    Draw an antialiased ellipse outline on a surface.
97

98
    Args:
99
        surface (pygame.Surface): Surface to draw on
100
        x (int): X coordinate of center
101
        y (int): Y coordinate of center
102
        rx (int): Horizontal radius
103
        ry (int): Vertical radius
104
        color: Color to use
105
    """
106

107
def aatrigon(surface: pygame.Surface, x1: int, y1: int, x2: int, y2: int, x3: int, y3: int, color) -> None:
108
    """
109
    Draw an antialiased triangle outline on a surface.
110

111
    Args:
112
        surface (pygame.Surface): Surface to draw on
113
        x1 (int): X coordinate of first vertex
114
        y1 (int): Y coordinate of first vertex
115
        x2 (int): X coordinate of second vertex
116
        y2 (int): Y coordinate of second vertex
117
        x3 (int): X coordinate of third vertex
118
        y3 (int): Y coordinate of third vertex
119
        color: Color to use
120
    """
121

122
def aapolygon(surface: pygame.Surface, points: list[tuple[int, int]], color) -> None:
123
    """
124
    Draw an antialiased polygon outline on a surface.
125

126
    Args:
127
        surface (pygame.Surface): Surface to draw on
128
        points (list[tuple[int, int]]): List of (x, y) vertices
129
        color: Color to use
130
    """
131
```
132

133
### Filled Shapes
134

135
Draw solid filled shapes for efficient area rendering and backgrounds.
136

137
```python { .api }
138
def filled_circle(surface: pygame.Surface, x: int, y: int, r: int, color) -> None:
139
    """
140
    Draw a filled circle on a surface.
141

142
    Args:
143
        surface (pygame.Surface): Surface to draw on
144
        x (int): X coordinate of center
145
        y (int): Y coordinate of center
146
        r (int): Radius in pixels
147
        color: Color to use for filling
148
    """
149

150
def filled_ellipse(surface: pygame.Surface, x: int, y: int, rx: int, ry: int, color) -> None:
151
    """
152
    Draw a filled ellipse on a surface.
153

154
    Args:
155
        surface (pygame.Surface): Surface to draw on
156
        x (int): X coordinate of center
157
        y (int): Y coordinate of center
158
        rx (int): Horizontal radius
159
        ry (int): Vertical radius
160
        color: Color to use for filling
161
    """
162

163
def filled_trigon(surface: pygame.Surface, x1: int, y1: int, x2: int, y2: int, x3: int, y3: int, color) -> None:
164
    """
165
    Draw a filled triangle on a surface.
166

167
    Args:
168
        surface (pygame.Surface): Surface to draw on
169
        x1 (int): X coordinate of first vertex
170
        y1 (int): Y coordinate of first vertex
171
        x2 (int): X coordinate of second vertex
172
        y2 (int): Y coordinate of second vertex
173
        x3 (int): X coordinate of third vertex
174
        y3 (int): Y coordinate of third vertex
175
        color: Color to use for filling
176
    """
177

178
def filled_polygon(surface: pygame.Surface, points: list[tuple[int, int]], color) -> None:
179
    """
180
    Draw a filled polygon on a surface.
181

182
    Args:
183
        surface (pygame.Surface): Surface to draw on
184
        points (list[tuple[int, int]]): List of (x, y) vertices
185
        color: Color to use for filling
186
    """
187
```
188

189
### Advanced Shapes
190

191
Draw specialized shapes including arcs, textured polygons, and smooth curves.
192

193
```python { .api }
194
def pie(surface: pygame.Surface, x: int, y: int, r: int, start: int, end: int, color) -> None:
195
    """
196
    Draw a filled pie slice (sector) on a surface.
197

198
    Args:
199
        surface (pygame.Surface): Surface to draw on
200
        x (int): X coordinate of center
201
        y (int): Y coordinate of center
202
        r (int): Radius in pixels
203
        start (int): Start angle in degrees
204
        end (int): End angle in degrees
205
        color: Color to use for filling
206
    """
207

208
def trigon(surface: pygame.Surface, x1: int, y1: int, x2: int, y2: int, x3: int, y3: int, color) -> None:
209
    """
210
    Draw a triangle outline on a surface.
211

212
    Args:
213
        surface (pygame.Surface): Surface to draw on
214
        x1 (int): X coordinate of first vertex
215
        y1 (int): Y coordinate of first vertex
216
        x2 (int): X coordinate of second vertex
217
        y2 (int): Y coordinate of second vertex
218
        x3 (int): X coordinate of third vertex
219
        y3 (int): Y coordinate of third vertex
220
        color: Color to use
221
    """
222

223
def textured_polygon(surface: pygame.Surface, points: list[tuple[int, int]], texture: pygame.Surface, tx: int, ty: int) -> None:
224
    """
225
    Draw a polygon filled with a texture pattern.
226

227
    Args:
228
        surface (pygame.Surface): Surface to draw on
229
        points (list[tuple[int, int]]): List of (x, y) vertices
230
        texture (pygame.Surface): Texture surface to use for filling
231
        tx (int): Texture X offset
232
        ty (int): Texture Y offset
233
    """
234

235
def bezier(surface: pygame.Surface, points: list[tuple[int, int]], steps: int, color) -> None:
236
    """
237
    Draw a smooth Bezier curve through control points.
238

239
    Args:
240
        surface (pygame.Surface): Surface to draw on
241
        points (list[tuple[int, int]]): Control points for the curve
242
        steps (int): Number of interpolation steps (higher = smoother)
243
        color: Color to use for the curve
244
    """
245
```
246

247
## Usage Examples
248

249
### Antialiased Graphics
250

251
```python
252
import pygame
253
import pygame.gfxdraw
254

255
pygame.init()
256
screen = pygame.display.set_mode((800, 600))
257
screen.fill((0, 0, 0))
258

259
# Compare regular vs antialiased circles
260
pygame.draw.circle(screen, (255, 0, 0), (200, 150), 50, 2)  # Regular circle
261
pygame.gfxdraw.aacircle(screen, 600, 150, 50, (255, 0, 0))  # Antialiased circle
262

263
# Antialiased ellipse with smooth edges
264
pygame.gfxdraw.aaellipse(screen, 400, 300, 100, 50, (0, 255, 0))
265
pygame.gfxdraw.filled_ellipse(screen, 400, 300, 98, 48, (0, 100, 0))
266

267
# Smooth triangle
268
triangle_points = [(300, 450), (400, 350), (500, 450)]
269
pygame.gfxdraw.aatrigon(screen, *triangle_points[0], *triangle_points[1], *triangle_points[2], (0, 0, 255))
270

271
pygame.display.flip()
272
```
273

274
### Precise Pixel Operations
275

276
```python
277
import pygame
278
import pygame.gfxdraw
279
import random
280

281
pygame.init()
282
screen = pygame.display.set_mode((800, 600))
283
screen.fill((0, 0, 0))
284

285
# Draw starfield with individual pixels
286
for _ in range(1000):
287
    x = random.randint(0, 799)
288
    y = random.randint(0, 599)
289
    brightness = random.randint(100, 255)
290
    pygame.gfxdraw.pixel(screen, x, y, (brightness, brightness, brightness))
291

292
# Draw grid with horizontal and vertical lines
293
grid_color = (40, 40, 40)
294
for x in range(0, 800, 50):
295
    pygame.gfxdraw.vline(screen, x, 0, 599, grid_color)
296
for y in range(0, 600, 50):
297
    pygame.gfxdraw.hline(screen, 0, 799, y, grid_color)
298

299
# Highlight with brighter lines
300
pygame.gfxdraw.hline(screen, 0, 799, 300, (100, 100, 0))
301
pygame.gfxdraw.vline(screen, 400, 0, 599, (100, 100, 0))
302

303
pygame.display.flip()
304
```
305

306
### Complex Shapes and Curves
307

308
```python
309
import pygame
310
import pygame.gfxdraw
311
import math
312

313
pygame.init()
314
screen = pygame.display.set_mode((800, 600))
315
screen.fill((50, 50, 50))
316

317
# Draw pie chart segments
318
center = (200, 200)
319
radius = 80
320
segments = [30, 45, 60, 90, 120, 135]  # Angles
321
colors = [(255, 0, 0), (0, 255, 0), (0, 0, 255), (255, 255, 0), (255, 0, 255), (0, 255, 255)]
322

323
start_angle = 0
324
for i, segment in enumerate(segments):
325
    end_angle = start_angle + segment
326
    pygame.gfxdraw.pie(screen, center[0], center[1], radius, start_angle, end_angle, colors[i])
327
    start_angle = end_angle
328

329
# Draw smooth Bezier curve
330
control_points = [(500, 100), (600, 200), (700, 150), (750, 300)]
331
pygame.gfxdraw.bezier(screen, control_points, 100, (255, 255, 255))
332

333
# Mark control points
334
for point in control_points:
335
    pygame.gfxdraw.filled_circle(screen, point[0], point[1], 5, (255, 255, 0))
336

337
# Draw complex polygon with texture
338
polygon_points = [(100, 400), (200, 350), (250, 450), (150, 500), (50, 450)]
339
texture = pygame.Surface((20, 20))
340
pygame.draw.checkerboard(texture, (100, 100, 100), (150, 150, 150), 10)
341
pygame.gfxdraw.textured_polygon(screen, polygon_points, texture, 0, 0)
342

343
pygame.display.flip()
344
```
345

346
### Performance Optimization with GFXDraw
347

348
```python
349
import pygame
350
import pygame.gfxdraw
351
import time
352

353
pygame.init()
354
screen = pygame.display.set_mode((800, 600))
355
clock = pygame.time.Clock()
356

357
# Efficient batch drawing operations
358
def draw_optimized_scene():
359
    screen.fill((0, 0, 0))
360

361
    # Use box() for filled rectangles - faster than pygame.draw.rect
362
    for x in range(0, 800, 40):
363
        for y in range(0, 600, 40):
364
            if (x + y) % 80 == 0:
365
                rect = pygame.Rect(x, y, 35, 35)
366
                pygame.gfxdraw.box(screen, rect, (20, 20, 50))
367

368
    # Efficient circle drawing
369
    for i in range(20):
370
        x = 50 + i * 35
371
        y = 300
372
        pygame.gfxdraw.filled_circle(screen, x, y, 15, (100 + i * 5, 0, 255 - i * 10))
373
        pygame.gfxdraw.aacircle(screen, x, y, 15, (255, 255, 255))
374

375
    # Fast line operations
376
    for i in range(0, 800, 10):
377
        pygame.gfxdraw.vline(screen, i, 500, 580, (0, i // 3, 100))
378

379
running = True
380
frame_count = 0
381
start_time = time.time()
382

383
while running:
384
    for event in pygame.event.get():
385
        if event.type == pygame.QUIT:
386
            running = False
387

388
    draw_optimized_scene()
389

390
    frame_count += 1
391
    if frame_count % 60 == 0:
392
        elapsed = time.time() - start_time
393
        fps = frame_count / elapsed
394
        print(f"FPS: {fps:.1f}")
395

396
    pygame.display.flip()
397
    clock.tick(60)
398

399
pygame.quit()
400
```
401

402
## Performance Notes
403

404
### Optimization Guidelines
405

406
```python
407
# Use gfxdraw for high-performance scenarios
408
import pygame.gfxdraw
409

410
# Faster filled shapes
411
pygame.gfxdraw.box(surface, rect, color)           # Faster than pygame.draw.rect(surface, color, rect)
412
pygame.gfxdraw.filled_circle(surface, x, y, r, color)  # Faster than pygame.draw.circle(surface, color, (x, y), r)
413

414
# Antialiasing when quality matters
415
pygame.gfxdraw.aacircle(surface, x, y, r, color)   # Smooth edges, slightly slower
416
pygame.gfxdraw.aapolygon(surface, points, color)   # Professional quality graphics
417

418
# Pixel-level control for effects
419
pygame.gfxdraw.pixel(surface, x, y, color)         # Direct pixel access
420
pygame.gfxdraw.hline(surface, x1, x2, y, color)    # Optimized horizontal lines
421
pygame.gfxdraw.vline(surface, x, y1, y2, color)    # Optimized vertical lines
422
```
423

424
### Memory and Speed Considerations
425

426
- `pygame.gfxdraw` functions are generally faster than equivalent `pygame.draw` functions
427
- Antialiased functions (`aa*`) provide better visual quality at slight performance cost
428
- Use `box()` instead of `rectangle()` for filled shapes when possible
429
- Pixel operations are efficient for effects but avoid for large areas
430
- Bezier curves and textured polygons are computationally expensive
431
- Batch similar operations together for better cache performance