0
# Display and Graphics
1

2
Comprehensive display management including window creation, surface operations, and drawing primitives. Handles everything from basic window setup to advanced graphics rendering and transformations.
3

4
## Capabilities
5

6
### Display Initialization
7

8
Core display functions for creating and managing the game window and screen surface.
9

10
```python { .api }
11
def init() -> None:
12
    """Initialize the display module."""
13

14
def quit() -> None:
15
    """Uninitialize the display module."""
16

17
def get_init() -> bool:
18
    """
19
    Check if display module is initialized.
20
    
21
    Returns:
22
        bool: True if display module is initialized
23
    """
24

25
def set_mode(size: tuple[int, int], flags: int = 0, depth: int = 0, display: int = 0, vsync: int = 0) -> Surface:
26
    """
27
    Initialize a window or screen for display.
28
    
29
    Parameters:
30
        size: (width, height) in pixels
31
        flags: Display flags (FULLSCREEN, RESIZABLE, etc.)
32
        depth: Color depth in bits per pixel (0 for best match)
33
        display: Display index for multi-monitor setups
34
        vsync: Vertical sync (0=off, 1=on, -1=adaptive)
35
    
36
    Returns:
37
        Surface: The display surface
38
    """
39

40
def get_surface() -> Surface | None:
41
    """
42
    Get reference to currently set display surface.
43
    
44
    Returns:
45
        Surface: Current display surface or None if not set
46
    """
47
```
48

49
### Display Updates
50

51
Functions for updating the display with rendered content.
52

53
```python { .api }
54
def flip() -> None:
55
    """
56
    Update the full display Surface to the screen.
57
    Should be called once per frame after all drawing is complete.
58
    """
59

60
def update(rectangle_list: list[Rect] | None = None) -> None:
61
    """
62
    Update all or portion of the display.
63
    
64
    Parameters:
65
        rectangle_list: List of rectangles to update, or None for full screen
66
    """
67
```
68

69
### Display Information and Configuration
70

71
Functions to query and configure display properties.
72

73
```python { .api }
74
def get_driver() -> str:
75
    """
76
    Get name of pygame display backend.
77
    
78
    Returns:
79
        str: Name of the display driver
80
    """
81

82
def Info() -> object:
83
    """
84
    Create video display information object.
85
    
86
    Returns:
87
        object: Display info with attributes like hw, wm, bitsize, fmt, etc.
88
    """
89

90
def list_modes(depth: int = 0, flags: int = 0, display: int = 0) -> list[tuple[int, int]]:
91
    """
92
    Get available display modes.
93
    
94
    Parameters:
95
        depth: Color depth to check
96
        flags: Display flags to require
97
        display: Display index
98
    
99
    Returns:
100
        list[tuple[int, int]]: List of (width, height) tuples, or [-1] if all modes supported
101
    """
102

103
def mode_ok(size: tuple[int, int], flags: int = 0, depth: int = 0, display: int = 0) -> int:
104
    """
105
    Check if display mode is available.
106
    
107
    Parameters:
108
        size: (width, height) to check
109
        flags: Display flags
110
        depth: Color depth
111
        display: Display index
112
    
113
    Returns:
114
        int: Best matching color depth, or 0 if mode not supported
115
    """
116
```
117

118
### Window Management
119

120
Functions for controlling window appearance and behavior.
121

122
```python { .api }
123
def set_caption(title: str, icontitle: str | None = None) -> None:
124
    """
125
    Set display window caption/title.
126
    
127
    Parameters:
128
        title: Window title
129
        icontitle: Minimized window title (defaults to title)
130
    """
131

132
def get_caption() -> tuple[str, str]:
133
    """
134
    Get display window caption.
135
    
136
    Returns:
137
        tuple[str, str]: (title, icontitle)
138
    """
139

140
def set_icon(surface: Surface) -> None:
141
    """
142
    Set display window icon.
143
    
144
    Parameters:
145
        surface: Icon surface (should be 32x32 pixels)
146
    """
147

148
def iconify() -> bool:
149
    """
150
    Iconify/minimize the display window.
151
    
152
    Returns:
153
        bool: True if successful
154
    """
155

156
def toggle_fullscreen() -> int:
157
    """
158
    Toggle between fullscreen and windowed mode.
159
    
160
    Returns:
161
        int: 1 if successful, 0 if failed
162
    """
163

164
def get_active() -> bool:
165
    """
166
    Check if display surface is active on screen.
167
    
168
    Returns:
169
        bool: True if display is active
170
    """
171
```
172

173
### Multi-Monitor Support
174

175
Functions for working with multiple displays.
176

177
```python { .api }
178
def get_num_displays() -> int:
179
    """
180
    Get number of available displays.
181
    
182
    Returns:
183
        int: Number of displays
184
    """
185

186
def get_window_size() -> tuple[int, int]:
187
    """
188
    Get actual window size (may differ from surface size).
189
    
190
    Returns:
191
        tuple[int, int]: (width, height) of window
192
    """
193

194
def get_window_position() -> tuple[int, int]:
195
    """
196
    Get window position on desktop.
197
    
198
    Returns:
199
        tuple[int, int]: (x, y) position
200
    """
201

202
def set_window_position(position: tuple[int, int]) -> None:
203
    """
204
    Set window position on desktop.
205
    
206
    Parameters:
207
        position: (x, y) position to set
208
    """
209
```
210

211
### Drawing Primitives
212

213
Basic shape drawing functions for immediate rendering to surfaces.
214

215
```python { .api }
216
def rect(surface: Surface, color: Color, rect: Rect, width: int = 0, border_radius: int = 0) -> Rect:
217
    """
218
    Draw rectangle on surface.
219
    
220
    Parameters:
221
        surface: Surface to draw on
222
        color: Color to draw with
223
        rect: Rectangle to draw
224
        width: Line width (0 for filled)
225
        border_radius: Corner radius for rounded rectangles
226
    
227
    Returns:
228
        Rect: The drawn rectangle
229
    """
230

231
def circle(surface: Surface, color: Color, center: tuple[int, int], radius: int, width: int = 0) -> Rect:
232
    """
233
    Draw circle on surface.
234
    
235
    Parameters:
236
        surface: Surface to draw on
237
        color: Color to draw with  
238
        center: (x, y) center point
239
        radius: Circle radius
240
        width: Line width (0 for filled)
241
    
242
    Returns:
243
        Rect: Bounding rectangle of drawn circle
244
    """
245

246
def line(surface: Surface, color: Color, start_pos: tuple[int, int], end_pos: tuple[int, int], width: int = 1) -> Rect:
247
    """
248
    Draw line on surface.
249
    
250
    Parameters:
251
        surface: Surface to draw on
252
        color: Color to draw with
253
        start_pos: (x, y) starting point
254
        end_pos: (x, y) ending point  
255
        width: Line width
256
    
257
    Returns:
258
        Rect: Bounding rectangle of drawn line
259
    """
260

261
def polygon(surface: Surface, color: Color, points: list[tuple[int, int]], width: int = 0) -> Rect:
262
    """
263
    Draw polygon on surface.
264
    
265
    Parameters:
266
        surface: Surface to draw on
267
        color: Color to draw with
268
        points: List of (x, y) vertices
269
        width: Line width (0 for filled)
270
    
271
    Returns:
272
        Rect: Bounding rectangle of drawn polygon
273
    """
274
```
275

276
### Surface Operations
277

278
The Surface class provides the fundamental 2D image object used throughout pygame.
279

280
```python { .api }
281
class Surface:
282
    def __init__(self, size: tuple[int, int], flags: int = 0, depth: int = 0, masks: tuple[int, int, int, int] | None = None):
283
        """
284
        Create new Surface object.
285
        
286
        Parameters:
287
            size: (width, height) in pixels
288
            flags: Surface creation flags
289
            depth: Color depth in bits per pixel
290
            masks: RGBA bit masks for pixel format
291
        """
292
    
293
    def blit(self, source: Surface, dest: tuple[int, int] | Rect, area: Rect | None = None, special_flags: int = 0) -> Rect:
294
        """
295
        Copy pixels from another surface.
296
        
297
        Parameters:
298
            source: Source surface to copy from
299
            dest: Destination position or rectangle
300
            area: Source area to copy (None for entire source)
301
            special_flags: Blend mode flags
302
        
303
        Returns:
304
            Rect: Area that was modified
305
        """
306
    
307
    def fill(self, color: Color, rect: Rect | None = None, special_flags: int = 0) -> Rect:
308
        """
309
        Fill surface with solid color.
310
        
311
        Parameters:
312
            color: Color to fill with
313
            rect: Area to fill (None for entire surface)
314
            special_flags: Blend mode flags
315
        
316
        Returns:
317
            Rect: Area that was filled
318
        """
319
    
320
    def convert(self, surface: Surface | None = None) -> Surface:
321
        """
322
        Convert surface to match display format for faster blitting.
323
        
324
        Parameters:
325
            surface: Surface to match format with (None for display)
326
        
327
        Returns:
328
            Surface: New converted surface
329
        """
330
    
331
    def convert_alpha(self, surface: Surface | None = None) -> Surface:
332
        """
333
        Convert surface with per-pixel alpha for faster alpha blitting.
334
        
335
        Parameters:
336
            surface: Surface to match format with (None for display)
337
        
338
        Returns:
339
            Surface: New converted surface with alpha
340
        """
341
    
342
    def copy(self) -> Surface:
343
        """
344
        Create copy of surface.
345
        
346
        Returns:
347
            Surface: New surface copy
348
        """
349
    
350
    def get_size() -> tuple[int, int]:
351
        """
352
        Get surface dimensions.
353
        
354
        Returns:
355
            tuple[int, int]: (width, height)
356
        """
357
    
358
    def get_width() -> int:
359
        """Get surface width."""
360
    
361
    def get_height() -> int:
362
        """Get surface height."""
363
    
364
    def get_rect(**kwargs) -> Rect:
365
        """
366
        Get rectangle representing surface area.
367
        
368
        Parameters:
369
            **kwargs: Rectangle positioning (center, topleft, etc.)
370
        
371
        Returns:
372
            Rect: Rectangle with surface dimensions
373
        """
374
    
375
    def set_alpha(self, value: int | None, flags: int = 0) -> None:
376
        """
377
        Set surface transparency.
378
        
379
        Parameters:
380
            value: Alpha value 0-255 (None to disable)
381
            flags: Alpha flags
382
        """
383
    
384
    def get_alpha() -> int | None:
385
        """
386
        Get surface alpha value.
387
        
388
        Returns:
389
            int | None: Alpha value or None if not set
390
        """
391
    
392
    def set_colorkey(self, color: Color | None, flags: int = 0) -> None:
393
        """
394
        Set transparent color key.
395
        
396
        Parameters:
397
            color: Color to make transparent (None to disable)
398
            flags: Colorkey flags  
399
        """
400
    
401
    def get_colorkey() -> Color | None:
402
        """
403
        Get transparent color key.
404
        
405
        Returns:
406
            Color | None: Colorkey color or None if not set
407
        """
408
```
409

410
### Transform Operations
411

412
Functions for scaling, rotating, and transforming surfaces.
413

414
```python { .api }
415
def scale(surface: Surface, size: tuple[int, int], dest_surface: Surface | None = None) -> Surface:
416
    """
417
    Resize surface to new dimensions.
418
    
419
    Parameters:
420
        surface: Source surface
421
        size: New (width, height)
422
        dest_surface: Optional destination surface
423
    
424
    Returns:
425
        Surface: Scaled surface
426
    """
427

428
def rotate(surface: Surface, angle: float) -> Surface:
429
    """
430
    Rotate surface by angle in degrees.
431
    
432
    Parameters:
433
        surface: Source surface
434
        angle: Rotation angle in degrees (positive is counterclockwise)
435
    
436
    Returns:
437
        Surface: Rotated surface
438
    """
439

440
def flip(surface: Surface, xbool: bool, ybool: bool) -> Surface:
441
    """
442
    Flip surface horizontally and/or vertically.
443
    
444
    Parameters:
445
        surface: Source surface
446
        xbool: Flip horizontally
447
        ybool: Flip vertically
448
    
449
    Returns:
450
        Surface: Flipped surface
451
    """
452
```
453

454
## Constants
455

456
Display and surface flags:
457

458
```python { .api }
459
# Display flags
460
FULLSCREEN: int      # Create fullscreen display
461
DOUBLEBUF: int       # Double buffered display
462
HWSURFACE: int       # Hardware accelerated surface
463
OPENGL: int          # OpenGL display
464
RESIZABLE: int       # Resizable display
465
NOFRAME: int         # Display without border/controls
466
SCALED: int          # Scale display to desktop size
467

468
# Surface flags  
469
SRCALPHA: int        # Per-pixel alpha
470
SRCCOLORKEY: int     # Use colorkey transparency
471
RLEACCEL: int        # RLE acceleration
472

473
# Blend modes
474
BLENDMODE_NONE: int    # No blending
475
BLENDMODE_BLEND: int   # Alpha blending  
476
BLENDMODE_ADD: int     # Additive blending
477
BLENDMODE_SUB: int     # Subtractive blending
478
BLENDMODE_MULT: int    # Multiplicative blending
479
```