0
# Drawing and Shapes
1

2
Primitive shape drawing functions for creating graphics. This module provides high-performance drawing operations for basic geometric shapes, lines, and filled areas with support for colors, line widths, and antialiasing.
3

4
## Capabilities
5

6
### Rectangle Drawing
7

8
Draw rectangles and rounded rectangles with various fill and border options.
9

10
```python { .api }
11
def rect(surface: pygame.Surface, color, rect: pygame.Rect, width: int = 0, border_radius: int = 0, border_top_left_radius: int = -1, border_top_right_radius: int = -1, border_bottom_left_radius: int = -1, border_bottom_right_radius: int = -1) -> pygame.Rect:
12
    """
13
    Draw a rectangle on a surface.
14

15
    Args:
16
        surface (pygame.Surface): Surface to draw on
17
        color: Color to use (Color, tuple, or color name)
18
        rect (pygame.Rect): Rectangle area to draw
19
        width (int): Line thickness (0 for filled rectangle)
20
        border_radius (int): Radius for all corners
21
        border_*_radius (int): Radius for specific corners (-1 uses border_radius)
22

23
    Returns:
24
        pygame.Rect: Rectangle area that was drawn
25
    """
26
```
27

28
### Circle and Ellipse Drawing
29

30
Draw circles and ellipses with optional partial drawing and customizable borders.
31

32
```python { .api }
33
def circle(surface: pygame.Surface, color, center: tuple[int, int], radius: int, width: int = 0, draw_top_right: bool = None, draw_top_left: bool = None, draw_bottom_left: bool = None, draw_bottom_right: bool = None) -> pygame.Rect:
34
    """
35
    Draw a circle on a surface.
36

37
    Args:
38
        surface (pygame.Surface): Surface to draw on
39
        color: Color to use
40
        center (tuple[int, int]): (x, y) center position
41
        radius (int): Circle radius in pixels
42
        width (int): Line thickness (0 for filled circle)
43
        draw_*_* (bool): Draw specific quadrants (None draws all)
44

45
    Returns:
46
        pygame.Rect: Bounding rectangle of the drawn circle
47
    """
48

49
def ellipse(surface: pygame.Surface, color, rect: pygame.Rect, width: int = 0) -> pygame.Rect:
50
    """
51
    Draw an ellipse on a surface.
52

53
    Args:
54
        surface (pygame.Surface): Surface to draw on
55
        color: Color to use
56
        rect (pygame.Rect): Bounding rectangle for ellipse
57
        width (int): Line thickness (0 for filled ellipse)
58

59
    Returns:
60
        pygame.Rect: Bounding rectangle that was drawn
61
    """
62
```
63

64
### Arc Drawing
65

66
Draw partial circles and ellipses with precise angle control.
67

68
```python { .api }
69
def arc(surface: pygame.Surface, color, rect: pygame.Rect, start_angle: float, stop_angle: float, width: int = 1) -> pygame.Rect:
70
    """
71
    Draw an arc on a surface.
72

73
    Args:
74
        surface (pygame.Surface): Surface to draw on
75
        color: Color to use
76
        rect (pygame.Rect): Bounding rectangle for arc
77
        start_angle (float): Start angle in radians
78
        stop_angle (float): Stop angle in radians
79
        width (int): Line thickness
80

81
    Returns:
82
        pygame.Rect: Bounding rectangle of the drawn arc
83
    """
84
```
85

86
### Line Drawing
87

88
Draw single lines and connected line sequences with antialiasing options.
89

90
```python { .api }
91
def line(surface: pygame.Surface, color, start_pos: tuple[int, int], end_pos: tuple[int, int], width: int = 1) -> pygame.Rect:
92
    """
93
    Draw a straight line on a surface.
94

95
    Args:
96
        surface (pygame.Surface): Surface to draw on
97
        color: Color to use
98
        start_pos (tuple[int, int]): (x, y) starting position
99
        end_pos (tuple[int, int]): (x, y) ending position
100
        width (int): Line thickness
101

102
    Returns:
103
        pygame.Rect: Bounding rectangle of the drawn line
104
    """
105

106
def lines(surface: pygame.Surface, color, closed: bool, points: list[tuple[int, int]], width: int = 1) -> pygame.Rect:
107
    """
108
    Draw connected lines on a surface.
109

110
    Args:
111
        surface (pygame.Surface): Surface to draw on
112
        color: Color to use
113
        closed (bool): If True, connect last point to first
114
        points (list[tuple[int, int]]): List of (x, y) points
115
        width (int): Line thickness
116

117
    Returns:
118
        pygame.Rect: Bounding rectangle of all drawn lines
119
    """
120

121
def aaline(surface: pygame.Surface, color, start_pos: tuple[int, int], end_pos: tuple[int, int], blend: int = 1) -> pygame.Rect:
122
    """
123
    Draw an antialiased line on a surface.
124

125
    Args:
126
        surface (pygame.Surface): Surface to draw on
127
        color: Color to use
128
        start_pos (tuple[int, int]): (x, y) starting position
129
        end_pos (tuple[int, int]): (x, y) ending position
130
        blend (int): Blending mode (1 for antialiased, 0 for solid)
131

132
    Returns:
133
        pygame.Rect: Bounding rectangle of the drawn line
134
    """
135

136
def aalines(surface: pygame.Surface, color, closed: bool, points: list[tuple[int, int]], blend: int = 1) -> pygame.Rect:
137
    """
138
    Draw connected antialiased lines on a surface.
139

140
    Args:
141
        surface (pygame.Surface): Surface to draw on
142
        color: Color to use
143
        closed (bool): If True, connect last point to first
144
        points (list[tuple[int, int]]): List of (x, y) points
145
        blend (int): Blending mode (1 for antialiased, 0 for solid)
146

147
    Returns:
148
        pygame.Rect: Bounding rectangle of all drawn lines
149
    """
150
```
151

152
### Polygon Drawing
153

154
Draw complex shapes defined by multiple points.
155

156
```python { .api }
157
def polygon(surface: pygame.Surface, color, points: list[tuple[int, int]], width: int = 0) -> pygame.Rect:
158
    """
159
    Draw a polygon on a surface.
160

161
    Args:
162
        surface (pygame.Surface): Surface to draw on
163
        color: Color to use
164
        points (list[tuple[int, int]]): List of (x, y) vertices (minimum 3)
165
        width (int): Line thickness (0 for filled polygon)
166

167
    Returns:
168
        pygame.Rect: Bounding rectangle of the drawn polygon
169
    """
170
```
171

172
## Color Specification
173

174
All drawing functions accept colors in multiple formats:
175

176
```python { .api }
177
# Color formats accepted by all drawing functions:
178
color_name: str           # "red", "blue", "white", etc.
179
rgb_tuple: tuple[int, int, int]        # (255, 0, 0) for red
180
rgba_tuple: tuple[int, int, int, int]  # (255, 0, 0, 128) for semi-transparent red
181
pygame_color: pygame.Color             # Color object
182
hex_integer: int                       # 0xFF0000 for red
183
```
184

185
## Usage Examples
186

187
### Basic Shape Drawing
188

189
```python
190
import pygame
191

192
pygame.init()
193
screen = pygame.display.set_mode((800, 600))
194

195
# Fill background
196
screen.fill((255, 255, 255))  # White background
197

198
# Draw filled rectangle
199
pygame.draw.rect(screen, (255, 0, 0), (100, 100, 200, 150))
200

201
# Draw rectangle outline
202
pygame.draw.rect(screen, (0, 255, 0), (350, 100, 200, 150), 3)
203

204
# Draw rounded rectangle
205
pygame.draw.rect(screen, (0, 0, 255), (100, 300, 200, 100), border_radius=20)
206

207
# Draw circle
208
pygame.draw.circle(screen, (255, 255, 0), (400, 400), 50)
209

210
# Draw circle outline
211
pygame.draw.circle(screen, (255, 0, 255), (600, 400), 50, 5)
212

213
pygame.display.flip()
214
```
215

216
### Line Drawing
217

218
```python
219
import pygame
220

221
pygame.init()
222
screen = pygame.display.set_mode((800, 600))
223
screen.fill((0, 0, 0))
224

225
# Draw single line
226
pygame.draw.line(screen, (255, 255, 255), (0, 0), (800, 600), 2)
227

228
# Draw connected lines (triangle)
229
points = [(400, 100), (300, 300), (500, 300)]
230
pygame.draw.lines(screen, (0, 255, 0), True, points, 3)
231

232
# Draw antialiased lines for smoother appearance
233
start = (100, 500)
234
end = (700, 100)
235
pygame.draw.aaline(screen, (255, 0, 0), start, end)
236

237
pygame.display.flip()
238
```
239

240
### Complex Shapes
241

242
```python
243
import pygame
244
import math
245

246
pygame.init()
247
screen = pygame.display.set_mode((800, 600))
248
screen.fill((0, 0, 0))
249

250
# Draw star polygon
251
center = (400, 300)
252
outer_radius = 100
253
inner_radius = 50
254
num_points = 5
255

256
star_points = []
257
for i in range(num_points * 2):
258
    angle = i * math.pi / num_points
259
    if i % 2 == 0:
260
        radius = outer_radius
261
    else:
262
        radius = inner_radius
263
    x = center[0] + radius * math.cos(angle)
264
    y = center[1] + radius * math.sin(angle)
265
    star_points.append((x, y))
266

267
pygame.draw.polygon(screen, (255, 255, 0), star_points)
268

269
# Draw partial circle (pac-man)
270
mouth_rect = pygame.Rect(100, 100, 100, 100)
271
pygame.draw.arc(screen, (255, 255, 0), mouth_rect, 0.5, 5.8, 3)
272

273
pygame.display.flip()
274
```
275

276
### Animation with Drawing
277

278
```python
279
import pygame
280
import math
281

282
pygame.init()
283
screen = pygame.display.set_mode((800, 600))
284
clock = pygame.time.Clock()
285

286
angle = 0
287
running = True
288

289
while running:
290
    for event in pygame.event.get():
291
        if event.type == pygame.QUIT:
292
            running = False
293

294
    # Clear screen
295
    screen.fill((0, 0, 0))
296

297
    # Draw rotating line
298
    center = (400, 300)
299
    length = 100
300
    end_x = center[0] + length * math.cos(angle)
301
    end_y = center[1] + length * math.sin(angle)
302

303
    pygame.draw.line(screen, (255, 255, 255), center, (end_x, end_y), 3)
304
    pygame.draw.circle(screen, (255, 0, 0), center, 5)
305

306
    angle += 0.05
307

308
    pygame.display.flip()
309
    clock.tick(60)
310

311
pygame.quit()
312
```
313

314
### Drawing Performance Tips
315

316
```python
317
import pygame
318

319
pygame.init()
320
screen = pygame.display.set_mode((800, 600))
321

322
# Use filled shapes when possible - they're faster than outlines
323
pygame.draw.rect(screen, (255, 0, 0), (10, 10, 100, 50))  # Faster
324
pygame.draw.rect(screen, (255, 0, 0), (10, 10, 100, 50), 1)  # Slower
325

326
# Batch multiple draw operations
327
dirty_rects = []
328
dirty_rects.append(pygame.draw.circle(screen, (0, 255, 0), (100, 100), 20))
329
dirty_rects.append(pygame.draw.circle(screen, (0, 0, 255), (200, 100), 20))
330

331
# Update only the drawn areas
332
pygame.display.update(dirty_rects)
333
```