0
# Monitor and Display
1

2
Monitor enumeration, video mode queries, display configuration, and gamma correction for multi-monitor setups and fullscreen applications.
3

4
## Capabilities
5

6
### Monitor Enumeration
7

8
Discover and access connected monitors.
9

10
```python { .api }
11
def get_monitors() -> list:
12
    """
13
    Get a list of currently connected monitors.
14
    
15
    Returns:
16
        list: List of GLFWmonitor handles
17
    """
18

19
def get_primary_monitor():
20
    """
21
    Get the primary monitor.
22
    
23
    Returns:
24
        GLFWmonitor: Primary monitor handle
25
    """
26
```
27

28
### Monitor Properties
29

30
Query monitor position, size, and other properties.
31

32
```python { .api }
33
def get_monitor_pos(monitor) -> tuple[int, int]:
34
    """
35
    Get the position of the monitor's viewport on the virtual screen.
36
    
37
    Parameters:
38
        monitor: Monitor handle
39
        
40
    Returns:
41
        tuple: (x, y) position in screen coordinates
42
    """
43

44
def get_monitor_workarea(monitor) -> tuple[int, int, int, int]:
45
    """
46
    Get the work area of the monitor.
47
    
48
    The work area is the area of the monitor not occluded by 
49
    the operating system task bar or dock.
50
    
51
    Parameters:
52
        monitor: Monitor handle
53
        
54
    Returns:
55
        tuple: (x, y, width, height) of work area
56
    """
57

58
def get_monitor_physical_size(monitor) -> tuple[int, int]:
59
    """
60
    Get the physical size of the monitor in millimeters.
61
    
62
    Parameters:
63
        monitor: Monitor handle
64
        
65
    Returns:
66
        tuple: (width, height) in millimeters
67
    """
68

69
def get_monitor_content_scale(monitor) -> tuple[float, float]:
70
    """
71
    Get the content scale for the specified monitor.
72
    
73
    The content scale is the ratio between the current DPI 
74
    and the platform's default DPI.
75
    
76
    Parameters:
77
        monitor: Monitor handle
78
        
79
    Returns:
80
        tuple: (x_scale, y_scale) content scale factors
81
    """
82

83
def get_monitor_name(monitor) -> bytes:
84
    """
85
    Get the name of the specified monitor.
86
    
87
    Parameters:
88
        monitor: Monitor handle
89
        
90
    Returns:
91
        bytes: Human-readable monitor name
92
    """
93
```
94

95
### Monitor User Data
96

97
Associate custom data with monitors.
98

99
```python { .api }
100
def set_monitor_user_pointer(monitor, pointer) -> None:
101
    """
102
    Set the user pointer of the monitor.
103
    
104
    Parameters:
105
        monitor: Monitor handle
106
        pointer: User data (any Python object)
107
    """
108

109
def get_monitor_user_pointer(monitor):
110
    """
111
    Get the user pointer of the monitor.
112
    
113
    Parameters:
114
        monitor: Monitor handle
115
        
116
    Returns:
117
        User data object previously set
118
    """
119
```
120

121
### Monitor Callbacks
122

123
Handle monitor configuration changes.
124

125
```python { .api }
126
def set_monitor_callback(cbfun) -> callable:
127
    """
128
    Set the monitor configuration callback.
129
    
130
    Parameters:
131
        cbfun: Callback function or None
132
            Signature: callback(monitor, event: int)
133
            
134
    Returns:
135
        callable: Previously set callback function
136
    """
137
```
138

139
#### Monitor Event Constants
140

141
```python { .api }
142
# Monitor events
143
CONNECTED: int = 0x00040001
144
DISCONNECTED: int = 0x00040002
145
```
146

147
### Video Modes
148

149
Query and work with display video modes.
150

151
```python { .api }
152
def get_video_modes(monitor) -> list:
153
    """
154
    Get the available video modes for the specified monitor.
155
    
156
    Parameters:
157
        monitor: Monitor handle
158
        
159
    Returns:
160
        list: List of GLFWvidmode objects
161
    """
162

163
def get_video_mode(monitor):
164
    """
165
    Get the current mode of the specified monitor.
166
    
167
    Parameters:
168
        monitor: Monitor handle
169
        
170
    Returns:
171
        GLFWvidmode: Current video mode
172
    """
173
```
174

175
### Video Mode Type
176

177
```python { .api }
178
# Video mode data structure
179
GLFWvidmode = namedtuple('GLFWvidmode', ['size', 'bits', 'refresh_rate'])
180
Size = namedtuple('Size', ['width', 'height'])
181
Bits = namedtuple('Bits', ['red', 'green', 'blue'])
182

183
# Access video mode properties:
184
# mode.size.width, mode.size.height
185
# mode.bits.red, mode.bits.green, mode.bits.blue  
186
# mode.refresh_rate
187
```
188

189
### Gamma Correction
190

191
Control monitor gamma correction and color adjustment.
192

193
```python { .api }
194
def set_gamma(monitor, gamma: float) -> None:
195
    """
196
    Generate a gamma ramp and set it for the specified monitor.
197
    
198
    This function generates a 256-element gamma ramp from the specified 
199
    exponent and then sets it as the current gamma ramp.
200
    
201
    Parameters:
202
        monitor: Monitor handle
203
        gamma: Desired exponent (typically 1.0-3.0)
204
    """
205

206
def get_gamma_ramp(monitor):
207
    """
208
    Get the current gamma ramp for the specified monitor.
209
    
210
    Parameters:
211
        monitor: Monitor handle
212
        
213
    Returns:
214
        GLFWgammaramp: Current gamma ramp
215
    """
216

217
def set_gamma_ramp(monitor, ramp) -> None:
218
    """
219
    Set the current gamma ramp for the specified monitor.
220
    
221
    Parameters:
222
        monitor: Monitor handle
223
        ramp: Gamma ramp data (3-tuple of RGB arrays)
224
    """
225
```
226

227
### Gamma Ramp Type
228

229
```python { .api }
230
# Gamma ramp data structure
231
GLFWgammaramp = namedtuple('GLFWgammaramp', ['red', 'green', 'blue'])
232

233
# Each channel (red, green, blue) is a list of values
234
# By default, values are normalized to 0.0-1.0 range
235
# Set glfw.NORMALIZE_GAMMA_RAMPS = False for 0-65535 integer values
236
```
237

238
## Platform-Specific Functions
239

240
Platform-specific functions for accessing native monitor handles and properties.
241

242
### Windows
243

244
```python { .api }
245
def get_win32_adapter(monitor) -> str:
246
    """
247
    Get the adapter device name of the specified monitor.
248
    
249
    Parameters:
250
        monitor: Monitor handle
251
        
252
    Returns:
253
        str: Adapter device name, or None
254
    """
255

256
def get_win32_monitor(monitor) -> str:
257
    """
258
    Get the display device name of the specified monitor.
259
    
260
    Parameters:
261
        monitor: Monitor handle
262
        
263
    Returns:
264
        str: Display device name, or None
265
    """
266
```
267

268
### macOS
269

270
```python { .api }
271
def get_cocoa_monitor(monitor) -> int:
272
    """
273
    Get the CGDirectDisplayID of the specified monitor.
274
    
275
    Parameters:
276
        monitor: Monitor handle
277
        
278
    Returns:
279
        int: CGDirectDisplayID
280
    """
281
```
282

283
### X11
284

285
```python { .api }
286
def get_x11_adapter(monitor) -> int:
287
    """
288
    Get the RRCrtc of the specified monitor.
289
    
290
    Parameters:
291
        monitor: Monitor handle
292
        
293
    Returns:
294
        int: RRCrtc identifier
295
    """
296

297
def get_x11_monitor(monitor) -> int:
298
    """
299
    Get the RROutput of the specified monitor.
300
    
301
    Parameters:
302
        monitor: Monitor handle
303
        
304
    Returns:
305
        int: RROutput identifier
306
    """
307
```
308

309
### Wayland
310

311
```python { .api }
312
def get_wayland_monitor(monitor) -> ctypes.c_void_p:
313
    """
314
    Get the struct wl_output* of the specified monitor.
315
    
316
    Parameters:
317
        monitor: Monitor handle
318
        
319
    Returns:
320
        ctypes.c_void_p: Wayland output handle
321
    """
322
```
323

324
## Usage Examples
325

326
### Monitor Information
327

328
```python
329
import glfw
330

331
glfw.init()
332

333
# Get all monitors
334
monitors = glfw.get_monitors()
335
primary = glfw.get_primary_monitor()
336

337
print(f"Found {len(monitors)} monitor(s)")
338
print(f"Primary monitor: {glfw.get_monitor_name(primary).decode('utf-8')}")
339

340
for i, monitor in enumerate(monitors):
341
    name = glfw.get_monitor_name(monitor).decode('utf-8')
342
    x, y = glfw.get_monitor_pos(monitor)
343
    width, height = glfw.get_monitor_physical_size(monitor)
344
    xscale, yscale = glfw.get_monitor_content_scale(monitor)
345
    
346
    print(f"Monitor {i}: {name}")
347
    print(f"  Position: {x}, {y}")
348
    print(f"  Physical size: {width}x{height}mm")
349
    print(f"  Content scale: {xscale}x{yscale}")
350
    
351
    # Get current video mode
352
    mode = glfw.get_video_mode(monitor)
353
    print(f"  Current mode: {mode.size.width}x{mode.size.height} @ {mode.refresh_rate}Hz")
354
    print(f"  Color bits: R{mode.bits.red} G{mode.bits.green} B{mode.bits.blue}")
355

356
glfw.terminate()
357
```
358

359
### Video Mode Selection
360

361
```python
362
import glfw
363

364
glfw.init()
365
monitor = glfw.get_primary_monitor()
366

367
# Get all available video modes
368
modes = glfw.get_video_modes(monitor)
369
print(f"Available video modes for {glfw.get_monitor_name(monitor).decode('utf-8')}:")
370

371
for mode in modes:
372
    print(f"  {mode.size.width}x{mode.size.height} @ {mode.refresh_rate}Hz "
373
          f"(R{mode.bits.red}G{mode.bits.green}B{mode.bits.blue})")
374

375
# Find highest resolution mode
376
highest_res = max(modes, key=lambda m: m.size.width * m.size.height)
377
print(f"Highest resolution: {highest_res.size.width}x{highest_res.size.height}")
378

379
# Create fullscreen window with specific mode
380
window = glfw.create_window(highest_res.size.width, highest_res.size.height, 
381
                           "Fullscreen", monitor, None)
382

383
glfw.terminate()
384
```
385

386
### Monitor Events
387

388
```python
389
import glfw
390

391
def monitor_callback(monitor, event):
392
    name = glfw.get_monitor_name(monitor).decode('utf-8') if monitor else "Unknown"
393
    if event == glfw.CONNECTED:
394
        print(f"Monitor connected: {name}")
395
    elif event == glfw.DISCONNECTED:
396
        print(f"Monitor disconnected: {name}")
397

398
glfw.init()
399

400
# Set monitor callback
401
glfw.set_monitor_callback(monitor_callback)
402

403
# Main loop to handle events (monitors can be hot-plugged)
404
# In a real application, this would be your main event loop
405
import time
406
for i in range(100):  # Run for a while to catch monitor events
407
    glfw.poll_events()
408
    time.sleep(0.1)
409

410
glfw.terminate()
411
```
412

413
### Gamma Correction
414

415
```python
416
import glfw
417

418
glfw.init()
419
monitor = glfw.get_primary_monitor()
420

421
# Save original gamma ramp
422
original_ramp = glfw.get_gamma_ramp(monitor)
423

424
try:
425
    # Set gamma correction
426
    glfw.set_gamma(monitor, 1.5)  # Brighten display
427
    
428
    # Or set custom gamma ramp
429
    size = len(original_ramp.red)
430
    red = [i / (size - 1) for i in range(size)]    # Linear ramp
431
    green = [i / (size - 1) for i in range(size)]  # Linear ramp  
432
    blue = [i / (size - 1) for i in range(size)]   # Linear ramp
433
    
434
    custom_ramp = (red, green, blue)
435
    glfw.set_gamma_ramp(monitor, custom_ramp)
436
    
437
    # Do work with modified gamma...
438
    
439
finally:
440
    # Restore original gamma ramp
441
    glfw.set_gamma_ramp(monitor, original_ramp)
442

443
glfw.terminate()
444
```
445

446
### Multi-Monitor Setup
447

448
```python
449
import glfw
450

451
glfw.init()
452

453
monitors = glfw.get_monitors()
454
if len(monitors) >= 2:
455
    # Create windows on different monitors
456
    for i, monitor in enumerate(monitors[:2]):
457
        mode = glfw.get_video_mode(monitor)
458
        x, y = glfw.get_monitor_pos(monitor)
459
        
460
        # Create window positioned on this monitor
461
        window = glfw.create_window(800, 600, f"Window on Monitor {i+1}", None, None)
462
        glfw.set_window_pos(window, x + 100, y + 100)
463
        
464
        print(f"Created window on {glfw.get_monitor_name(monitor).decode('utf-8')}")
465

466
glfw.terminate()
467
```