0
# Graphics and Display
1

2
Display window management, screen surface creation, and display configuration. This module controls the pygame window, handles fullscreen mode, manages the display surface, and provides information about the display system.
3

4
## Capabilities
5

6
### Display Creation and Management
7

8
Create and configure the main display window with various options for size, color depth, and special modes.
9

10
```python { .api }
11
def set_mode(size: tuple[int, int], flags: int = 0, depth: int = 0, display: int = 0, vsync: int = 0) -> pygame.Surface:
12
    """
13
    Initialize a window or screen for display.
14

15
    Args:
16
        size (tuple[int, int]): (width, height) of the display
17
        flags (int): Additional display options (FULLSCREEN, DOUBLEBUF, etc.)
18
        depth (int): Color depth in bits per pixel (0 for best)
19
        display (int): Which display to use (0 for primary)
20
        vsync (int): Enable vertical sync (1 for on, 0 for off)
21

22
    Returns:
23
        pygame.Surface: Display surface for drawing
24
    """
25

26
def get_surface() -> pygame.Surface:
27
    """
28
    Get a reference to the currently set display surface.
29

30
    Returns:
31
        pygame.Surface: Current display surface or None if not set
32
    """
33

34
def quit() -> None:
35
    """Close the display window and clean up display resources."""
36

37
def init() -> None:
38
    """Initialize the display module."""
39

40
def get_init() -> bool:
41
    """
42
    Check if the display module is initialized.
43

44
    Returns:
45
        bool: True if display module is initialized
46
    """
47
```
48

49
### Display Updates
50

51
Control when and how the display is updated to show changes.
52

53
```python { .api }
54
def flip() -> None:
55
    """
56
    Update the full display Surface to the screen.
57
    Should be used with DOUBLEBUF flag for best performance.
58
    """
59

60
def update(rectangle = None) -> None:
61
    """
62
    Update portions of the display surface.
63

64
    Args:
65
        rectangle (pygame.Rect or list, optional):
66
            Area(s) to update. If None, updates entire display.
67
            Can be single Rect or sequence of Rects.
68
    """
69
```
70

71
### Display Information
72

73
Get information about available display modes and current display properties.
74

75
```python { .api }
76
def Info() -> pygame.display.VideoInfo:
77
    """
78
    Get information about the display.
79

80
    Returns:
81
        pygame.display.VideoInfo: Object with display information attributes
82
    """
83

84
def get_driver() -> str:
85
    """
86
    Get the name of the pygame display backend.
87

88
    Returns:
89
        str: Name of display driver (e.g., 'windib', 'x11')
90
    """
91

92
def list_modes(depth: int = 0, flags: int = 0, display: int = 0) -> list:
93
    """
94
    Get list of available fullscreen modes.
95

96
    Args:
97
        depth (int): Color depth to check (0 for current depth)
98
        flags (int): Display flags to check
99
        display (int): Display index to check
100

101
    Returns:
102
        list: List of (width, height) tuples or [-1] if any size supported
103
    """
104

105
def mode_ok(size: tuple[int, int], flags: int = 0, depth: int = 0, display: int = 0) -> int:
106
    """
107
    Check if a display mode is available.
108

109
    Args:
110
        size (tuple[int, int]): (width, height) to check
111
        flags (int): Display flags
112
        depth (int): Color depth
113
        display (int): Display index
114

115
    Returns:
116
        int: Suggested pixel depth or 0 if not supported
117
    """
118

119
def get_desktop_sizes() -> list[tuple[int, int]]:
120
    """
121
    Get desktop sizes for all displays.
122

123
    Returns:
124
        list[tuple[int, int]]: List of (width, height) for each display
125
    """
126

127
def get_num_displays() -> int:
128
    """
129
    Get the number of available displays.
130

131
    Returns:
132
        int: Number of displays
133
    """
134
```
135

136
### Window Properties
137

138
Control window appearance, behavior, and state.
139

140
```python { .api }
141
def set_caption(title: str, icontitle: str = None) -> None:
142
    """
143
    Set the current window caption and icon title.
144

145
    Args:
146
        title (str): Window title text
147
        icontitle (str, optional): Icon title (defaults to title)
148
    """
149

150
def get_caption() -> tuple[str, str]:
151
    """
152
    Get the current window caption and icon title.
153

154
    Returns:
155
        tuple[str, str]: (title, icontitle)
156
    """
157

158
def set_icon(surface: pygame.Surface) -> None:
159
    """
160
    Change the system image for the display window.
161

162
    Args:
163
        surface (pygame.Surface): Icon surface (32x32 recommended)
164
    """
165

166
def iconify() -> bool:
167
    """
168
    Iconify (minimize) the display surface.
169

170
    Returns:
171
        bool: True if successful
172
    """
173

174
def toggle_fullscreen() -> int:
175
    """
176
    Switch between fullscreen and windowed displays.
177

178
    Returns:
179
        int: 1 if successful, 0 if failed
180
    """
181

182
def get_active() -> bool:
183
    """
184
    Check if the display is active (has input focus).
185

186
    Returns:
187
        bool: True if display is active
188
    """
189

190
def get_window_size() -> tuple[int, int]:
191
    """
192
    Get the size of the window.
193

194
    Returns:
195
        tuple[int, int]: (width, height) of window
196
    """
197

198
def is_fullscreen() -> bool:
199
    """
200
    Check if the display is in fullscreen mode.
201

202
    Returns:
203
        bool: True if display is fullscreen, False otherwise
204
    """
205
```
206

207
### Display Configuration
208

209
Advanced display configuration including gamma, palette, and screensaver settings.
210

211
```python { .api }
212
def set_gamma(red: float, green: float = None, blue: float = None) -> bool:
213
    """
214
    Change hardware gamma correction.
215

216
    Args:
217
        red (float): Red gamma value (1.0 = no change)
218
        green (float, optional): Green gamma (defaults to red)
219
        blue (float, optional): Blue gamma (defaults to red)
220

221
    Returns:
222
        bool: True if successful
223
    """
224

225
def set_gamma_ramp(red: list, green: list, blue: list) -> bool:
226
    """
227
    Set custom gamma correction with ramp arrays.
228

229
    Args:
230
        red (list): 256 red intensity values (0-65535)
231
        green (list): 256 green intensity values
232
        blue (list): 256 blue intensity values
233

234
    Returns:
235
        bool: True if successful
236
    """
237

238
def set_palette(palette = None) -> None:
239
    """
240
    Set the display color palette for 8-bit displays.
241

242
    Args:
243
        palette (list, optional): List of (r,g,b) tuples for palette colors
244
    """
245

246
def get_allow_screensaver() -> bool:
247
    """
248
    Check if screensaver is allowed.
249

250
    Returns:
251
        bool: True if screensaver is enabled
252
    """
253

254
def set_allow_screensaver(bool) -> None:
255
    """
256
    Control whether screensaver can activate.
257

258
    Args:
259
        bool (bool): True to allow screensaver, False to disable
260
    """
261
```
262

263
### OpenGL Integration
264

265
Support for OpenGL rendering within pygame displays.
266

267
```python { .api }
268
def gl_get_attribute(flag: int) -> int:
269
    """
270
    Get an OpenGL flag value.
271

272
    Args:
273
        flag (int): OpenGL attribute constant
274

275
    Returns:
276
        int: Current value of the attribute
277
    """
278

279
def gl_set_attribute(flag: int, value: int) -> None:
280
    """
281
    Set an OpenGL flag value.
282

283
    Args:
284
        flag (int): OpenGL attribute constant
285
        value (int): Value to set
286
    """
287
```
288

289
### Window Manager Information
290

291
Get platform-specific window manager information.
292

293
```python { .api }
294
def get_wm_info() -> dict:
295
    """
296
    Get window manager information.
297

298
    Returns:
299
        dict: Platform-specific window manager data
300
    """
301
```
302

303
## Display Flag Constants
304

305
```python { .api }
306
# Display mode flags
307
FULLSCREEN: int       # Create fullscreen display
308
DOUBLEBUF: int        # Create double-buffered display
309
HWSURFACE: int        # Create hardware accelerated surface
310
OPENGL: int           # Create OpenGL compatible display
311
RESIZABLE: int        # Create resizable window
312
NOFRAME: int          # Create window without border
313
SCALED: int           # Create scaled display
314
SHOWN: int            # Window is visible
315
HIDDEN: int           # Window is hidden
316
```
317

318
## Usage Examples
319

320
### Basic Display Setup
321

322
```python
323
import pygame
324

325
pygame.init()
326

327
# Create a 800x600 window
328
screen = pygame.display.set_mode((800, 600))
329
pygame.display.set_caption("My Game")
330

331
# Game loop
332
clock = pygame.time.Clock()
333
running = True
334

335
while running:
336
    for event in pygame.event.get():
337
        if event.type == pygame.QUIT:
338
            running = False
339

340
    # Clear screen
341
    screen.fill((0, 0, 0))
342

343
    # Update display
344
    pygame.display.flip()
345
    clock.tick(60)
346

347
pygame.quit()
348
```
349

350
### Fullscreen Mode
351

352
```python
353
import pygame
354

355
pygame.init()
356

357
# Create fullscreen display
358
screen = pygame.display.set_mode((0, 0), pygame.FULLSCREEN)
359

360
# Or toggle fullscreen later
361
pygame.display.toggle_fullscreen()
362
```
363

364
### Display Information
365

366
```python
367
import pygame
368

369
pygame.init()
370

371
# Get display info
372
info = pygame.display.Info()
373
print(f"Display size: {info.current_w}x{info.current_h}")
374
print(f"Bits per pixel: {info.bitsize}")
375

376
# List available modes
377
modes = pygame.display.list_modes()
378
print(f"Available modes: {modes}")
379

380
# Check if specific mode is supported
381
if pygame.display.mode_ok((1920, 1080)):
382
    print("1920x1080 is supported")
383
```
384

385
### Optimized Updates
386

387
```python
388
import pygame
389

390
pygame.init()
391
screen = pygame.display.set_mode((800, 600))
392

393
# Update only changed areas for better performance
394
dirty_rects = []
395

396
# Draw something that changes
397
rect = pygame.draw.circle(screen, (255, 0, 0), (400, 300), 50)
398
dirty_rects.append(rect)
399

400
# Update only the changed areas
401
pygame.display.update(dirty_rects)
402
```