0
# Window and Display Management
1

2
Comprehensive window creation, display mode handling, and OpenGL context management. PySDL2 provides both low-level window control through direct SDL2 bindings and high-level window classes through the extensions module.
3

4
## Capabilities
5

6
### Window Creation and Management
7

8
Core window functions for creating, managing, and manipulating windows.
9

10
```python { .api }
11
def SDL_CreateWindow(title: bytes, x: int, y: int, w: int, h: int, flags: int) -> SDL_Window:
12
    """
13
    Create a window with specified parameters.
14
    
15
    Parameters:
16
    - title: window title as bytes
17
    - x, y: initial position (or SDL_WINDOWPOS_CENTERED, SDL_WINDOWPOS_UNDEFINED)
18
    - w, h: window dimensions in pixels
19
    - flags: window flags (SDL_WINDOW_OPENGL, SDL_WINDOW_RESIZABLE, etc.)
20
    
21
    Returns:
22
    SDL_Window object or None on failure
23
    """
24

25
def SDL_DestroyWindow(window: SDL_Window) -> None:
26
    """Destroy a window and free associated resources."""
27

28
def SDL_ShowWindow(window: SDL_Window) -> None:
29
    """Show a window."""
30

31
def SDL_HideWindow(window: SDL_Window) -> None:
32
    """Hide a window."""
33

34
def SDL_SetWindowTitle(window: SDL_Window, title: bytes) -> None:
35
    """Set window title."""
36

37
def SDL_GetWindowTitle(window: SDL_Window) -> bytes:
38
    """Get window title."""
39

40
def SDL_SetWindowSize(window: SDL_Window, w: int, h: int) -> None:
41
    """Set window size."""
42

43
def SDL_GetWindowSize(window: SDL_Window, w: ctypes.POINTER(ctypes.c_int), h: ctypes.POINTER(ctypes.c_int)) -> None:
44
    """Get window size."""
45

46
def SDL_SetWindowPosition(window: SDL_Window, x: int, y: int) -> None:
47
    """Set window position."""
48

49
def SDL_GetWindowPosition(window: SDL_Window, x: ctypes.POINTER(ctypes.c_int), y: ctypes.POINTER(ctypes.c_int)) -> None:
50
    """Get window position."""
51
```
52

53
### Window Flags and States
54

55
Constants for window creation and state management.
56

57
```python { .api }
58
# Window creation flags
59
SDL_WINDOW_FULLSCREEN: int = 0x00000001
60
SDL_WINDOW_OPENGL: int = 0x00000002  
61
SDL_WINDOW_SHOWN: int = 0x00000004
62
SDL_WINDOW_HIDDEN: int = 0x00000008
63
SDL_WINDOW_BORDERLESS: int = 0x00000010
64
SDL_WINDOW_RESIZABLE: int = 0x00000020
65
SDL_WINDOW_MINIMIZED: int = 0x00000040
66
SDL_WINDOW_MAXIMIZED: int = 0x00000080
67
SDL_WINDOW_INPUT_GRABBED: int = 0x00000100
68
SDL_WINDOW_INPUT_FOCUS: int = 0x00000200
69
SDL_WINDOW_MOUSE_FOCUS: int = 0x00000400
70
SDL_WINDOW_FULLSCREEN_DESKTOP: int = 0x00001001
71
SDL_WINDOW_FOREIGN: int = 0x00000800
72
SDL_WINDOW_ALLOW_HIGHDPI: int = 0x00002000
73
SDL_WINDOW_MOUSE_CAPTURE: int = 0x00004000  
74
SDL_WINDOW_ALWAYS_ON_TOP: int = 0x00008000
75
SDL_WINDOW_SKIP_TASKBAR: int = 0x00010000
76
SDL_WINDOW_UTILITY: int = 0x00020000
77
SDL_WINDOW_TOOLTIP: int = 0x00040000
78
SDL_WINDOW_POPUP_MENU: int = 0x00080000
79
SDL_WINDOW_VULKAN: int = 0x10000000
80
SDL_WINDOW_METAL: int = 0x20000000
81

82
# Window positioning constants
83
SDL_WINDOWPOS_UNDEFINED: int = 0x1FFF0000
84
SDL_WINDOWPOS_CENTERED: int = 0x2FFF0000
85
```
86

87
### Display Management
88

89
Functions for working with displays and display modes.
90

91
```python { .api }
92
def SDL_GetNumVideoDisplays() -> int:
93
    """Get the number of available video displays."""
94

95
def SDL_GetDisplayBounds(displayIndex: int, rect: SDL_Rect) -> int:
96
    """Get display bounds."""
97

98
def SDL_GetCurrentDisplayMode(displayIndex: int, mode: SDL_DisplayMode) -> int:
99
    """Get current display mode."""
100

101
def SDL_GetDesktopDisplayMode(displayIndex: int, mode: SDL_DisplayMode) -> int:
102
    """Get desktop display mode."""
103

104
def SDL_GetNumDisplayModes(displayIndex: int) -> int:
105
    """Get number of display modes for a display."""
106

107
def SDL_GetDisplayMode(displayIndex: int, modeIndex: int, mode: SDL_DisplayMode) -> int:
108
    """Get specific display mode."""
109

110
def SDL_SetWindowDisplayMode(window: SDL_Window, mode: SDL_DisplayMode) -> int:
111
    """Set window display mode for fullscreen."""
112

113
def SDL_GetWindowDisplayMode(window: SDL_Window, mode: SDL_DisplayMode) -> int:
114
    """Get window display mode."""
115
```
116

117
### High-Level Window Class
118

119
The extension module provides a Pythonic Window class for simplified window management.
120

121
```python { .api }
122
class Window:
123
    """High-level window management class."""
124
    
125
    def __init__(self, title: str, size: tuple[int, int] = (800, 600), position: tuple[int, int] = None, flags: int = 0):
126
        """
127
        Create a new window.
128
        
129
        Parameters:
130
        - title: window title string
131
        - size: (width, height) tuple in pixels
132
        - position: (x, y) position tuple or None for default
133
        - flags: SDL window flags
134
        """
135
    
136
    def show(self) -> None:
137
        """Show the window."""
138
    
139
    def hide(self) -> None:
140
        """Hide the window."""
141
    
142
    def maximize(self) -> None:
143
        """Maximize the window."""
144
    
145
    def minimize(self) -> None:
146
        """Minimize the window."""
147
    
148
    def restore(self) -> None:
149
        """Restore the window from minimized/maximized state."""
150
    
151
    def refresh(self) -> None:
152
        """Refresh the window contents."""
153
    
154
    @property
155
    def size(self) -> tuple[int, int]:
156
        """Get window size as (width, height) tuple."""
157
    
158
    @size.setter  
159
    def size(self, value: tuple[int, int]) -> None:
160
        """Set window size from (width, height) tuple."""
161
    
162
    @property
163
    def position(self) -> tuple[int, int]:
164
        """Get window position as (x, y) tuple."""
165
    
166
    @position.setter
167
    def position(self, value: tuple[int, int]) -> None:
168
        """Set window position from (x, y) tuple."""
169
    
170
    @property
171
    def title(self) -> str:
172
        """Get window title."""
173
    
174
    @title.setter
175
    def title(self, value: str) -> None:
176
        """Set window title."""
177
```
178

179
### OpenGL Context Management
180

181
Functions for creating and managing OpenGL contexts.
182

183
```python { .api }
184
def SDL_GL_CreateContext(window: SDL_Window) -> SDL_GLContext:
185
    """Create an OpenGL context for use with window."""
186

187
def SDL_GL_DeleteContext(context: SDL_GLContext) -> None:
188
    """Delete an OpenGL context."""
189

190
def SDL_GL_MakeCurrent(window: SDL_Window, context: SDL_GLContext) -> int:
191
    """Set up an OpenGL context for rendering into an OpenGL window."""
192

193
def SDL_GL_SwapWindow(window: SDL_Window) -> None:
194
    """Update a window with OpenGL rendering."""
195

196
def SDL_GL_SetAttribute(attr: int, value: int) -> int:
197
    """Set an OpenGL window attribute before window creation."""
198

199
def SDL_GL_GetAttribute(attr: int, value: ctypes.POINTER(ctypes.c_int)) -> int:
200
    """Get an OpenGL window attribute."""
201

202
def SDL_GL_SetSwapInterval(interval: int) -> int:
203
    """Set the swap interval for the current OpenGL context."""
204

205
def SDL_GL_GetSwapInterval() -> int:
206
    """Get the swap interval for the current OpenGL context."""
207
```
208

209
## Types
210

211
```python { .api }
212
class SDL_Window:
213
    """Opaque structure representing a window."""
214

215
class SDL_GLContext:
216
    """Opaque structure representing an OpenGL context."""
217

218
class SDL_DisplayMode:
219
    """Display mode structure."""
220
    format: int         # pixel format
221
    w: int             # width in pixels
222
    h: int             # height in pixels
223
    refresh_rate: int  # refresh rate in Hz
224
    driverdata: ctypes.c_void_p  # driver-specific data
225

226
class SDL_Rect:
227
    """Rectangle structure."""
228
    x: int  # x coordinate
229
    y: int  # y coordinate  
230
    w: int  # width
231
    h: int  # height
232
```
233

234
## Usage Examples
235

236
### Basic Window Creation
237

238
```python
239
import sdl2
240
import sdl2.ext
241

242
# Initialize SDL2
243
sdl2.ext.init()
244

245
# Create window using extension class
246
window = sdl2.ext.Window("My Application", size=(1024, 768))
247
window.show()
248

249
# Main loop
250
running = True
251
while running:
252
    events = sdl2.ext.get_events()
253
    for event in events:
254
        if event.type == sdl2.SDL_QUIT:
255
            running = False
256

257
# Cleanup
258
sdl2.ext.quit()
259
```
260

261
### Low-Level Window Control
262

263
```python
264
import sdl2
265

266
# Initialize SDL2 video subsystem
267
sdl2.SDL_Init(sdl2.SDL_INIT_VIDEO)
268

269
# Create window with specific flags
270
window = sdl2.SDL_CreateWindow(
271
    b"Low-level Window",
272
    sdl2.SDL_WINDOWPOS_CENTERED, sdl2.SDL_WINDOWPOS_CENTERED,
273
    800, 600,
274
    sdl2.SDL_WINDOW_SHOWN | sdl2.SDL_WINDOW_RESIZABLE
275
)
276

277
# Show window
278
sdl2.SDL_ShowWindow(window)
279

280
# Event loop
281
event = sdl2.SDL_Event()
282
running = True
283
while running:
284
    while sdl2.SDL_PollEvent(event):
285
        if event.type == sdl2.SDL_QUIT:
286
            running = False
287

288
# Cleanup
289
sdl2.SDL_DestroyWindow(window)
290
sdl2.SDL_Quit()
291
```
292

293
### Fullscreen and Display Modes
294

295
```python
296
import sdl2
297

298
# Get display information
299
num_displays = sdl2.SDL_GetNumVideoDisplays()
300
print(f"Number of displays: {num_displays}")
301

302
# Get desktop display mode
303
display_mode = sdl2.SDL_DisplayMode()
304
sdl2.SDL_GetDesktopDisplayMode(0, display_mode)
305
print(f"Desktop mode: {display_mode.w}x{display_mode.h}@{display_mode.refresh_rate}Hz")
306

307
# Create fullscreen window
308
window = sdl2.SDL_CreateWindow(
309
    b"Fullscreen Window",
310
    sdl2.SDL_WINDOWPOS_UNDEFINED, sdl2.SDL_WINDOWPOS_UNDEFINED,
311
    0, 0,  # Size ignored for fullscreen desktop
312
    sdl2.SDL_WINDOW_FULLSCREEN_DESKTOP
313
)
314
```