0
# Platform Support
1

2
Cross-platform OpenGL support providing automatic platform detection and unified interface for Windows (WGL), Linux/X11 (GLX), macOS (CGL/AGL), and embedded systems (EGL). Includes dynamic library loading, extension detection, and context management across different operating systems.
3

4
## Capabilities
5

6
### Platform Detection and Selection
7

8
Automatic platform detection with manual override capabilities for specialized use cases.
9

10
```python { .api }
11
def GetCurrentPlatform():
12
    """
13
    Get currently active platform implementation.
14
    
15
    Returns:
16
    Platform instance (Win32Platform, GLXPlatform, DarwinPlatform, etc.)
17
    """
18

19
def setPlatform(key: str):
20
    """
21
    Manually set platform implementation.
22
    
23
    Parameters:
24
    - key: Platform identifier ('nt', 'linux', 'darwin', 'glx', 'egl', 'osmesa')
25
    
26
    Note: Must be called before importing GL.* modules as extension
27
    procedure lookup is platform dependent.
28
    
29
    Environment variable PYOPENGL_PLATFORM provides user control.
30
    """
31

32
# Automatic platform detection based on sys.platform
33
PLATFORM_MAPPINGS = {
34
    'nt': 'Win32Platform',        # Windows
35
    'darwin': 'DarwinPlatform',   # macOS
36
    'linux': 'GLXPlatform',       # Linux
37
    'linux2': 'GLXPlatform',      # Linux (older Python)
38
    'posix': 'GLXPlatform',       # Generic POSIX
39
}
40

41
# Manual platform selection
42
MANUAL_PLATFORMS = {
43
    'glx': 'GLXPlatform',         # X11/GLX (Linux, Unix)
44
    'egl': 'EGLPlatform',         # EGL (embedded, Wayland)
45
    'osmesa': 'OSMesaPlatform',   # Off-screen Mesa
46
    'wayland': 'EGLPlatform',     # Wayland compositor
47
    'xwayland': 'EGLPlatform',    # XWayland (X11 over Wayland)
48
}
49
```
50

51
### Windows Platform (WGL)
52

53
Windows-specific OpenGL implementation using WGL (Windows OpenGL) extensions.
54

55
```python { .api }
56
class Win32Platform:
57
    """
58
    Windows platform implementation using WGL extensions.
59
    Handles OpenGL context creation and extension loading on Windows.
60
    """
61
    
62
    def getGLExtensionPointer(self, name: str):
63
        """
64
        Get OpenGL extension function pointer on Windows.
65
        
66
        Parameters:
67
        - name: Extension function name
68
        
69
        Returns:
70
        Function pointer or None if not available
71
        """
72
    
73
    def getCurrentContext(self):
74
        """Get current OpenGL context handle (HGLRC)."""
75
    
76
    def contextIsValid(self, context) -> bool:
77
        """Check if OpenGL context is valid."""
78

79
# Windows-specific constants and functions
80
# Available when platform is Win32Platform
81
from OpenGL.WGL import *
82
```
83

84
### Linux/X11 Platform (GLX)
85

86
Linux and Unix platform support using GLX (GLX) extensions for X Window System integration.
87

88
```python { .api }
89
class GLXPlatform:
90
    """
91
    Linux/Unix platform implementation using GLX extensions.
92
    Handles OpenGL context creation and extension loading on X11 systems.
93
    """
94
    
95
    def getGLExtensionPointer(self, name: str):
96
        """
97
        Get OpenGL extension function pointer on Linux/X11.
98
        
99
        Parameters:
100
        - name: Extension function name
101
        
102
        Returns:
103
        Function pointer or None if not available
104
        """
105
    
106
    def getCurrentContext(self):
107
        """Get current OpenGL context (GLXContext)."""
108
    
109
    def contextIsValid(self, context) -> bool:
110
        """Check if GLX context is valid."""
111

112
# GLX-specific constants and functions
113
# Available when platform is GLXPlatform
114
from OpenGL.GLX import *
115
```
116

117
### macOS Platform (CGL/AGL)
118

119
macOS platform support using Core OpenGL (CGL) and Apple OpenGL (AGL) frameworks.
120

121
```python { .api }
122
class DarwinPlatform:
123
    """
124
    macOS platform implementation using CGL/AGL frameworks.
125
    Handles OpenGL context creation and extension loading on macOS.
126
    """
127
    
128
    def getGLExtensionPointer(self, name: str):
129
        """
130
        Get OpenGL extension function pointer on macOS.
131
        
132
        Parameters:
133
        - name: Extension function name
134
        
135
        Returns:
136
        Function pointer or None if not available
137
        """
138
    
139
    def getCurrentContext(self):
140
        """Get current OpenGL context (CGLContextObj)."""
141
    
142
    def contextIsValid(self, context) -> bool:
143
        """Check if CGL context is valid."""
144

145
# macOS-specific constants and functions
146
# Available when platform is DarwinPlatform
147
from OpenGL.AGL import *  # Legacy Apple OpenGL
148
```
149

150
### EGL Platform (Embedded/Wayland)
151

152
EGL (Embedded-System Graphics Library) support for embedded systems and Wayland compositors.
153

154
```python { .api }
155
class EGLPlatform:
156
    """
157
    EGL platform implementation for embedded systems and Wayland.
158
    Provides OpenGL ES and desktop OpenGL context creation via EGL.
159
    """
160
    
161
    def getGLExtensionPointer(self, name: str):
162
        """
163
        Get OpenGL extension function pointer via EGL.
164
        
165
        Parameters:
166
        - name: Extension function name
167
        
168
        Returns:
169
        Function pointer or None if not available
170
        """
171
    
172
    def getCurrentContext(self):
173
        """Get current EGL context."""
174
    
175
    def contextIsValid(self, context) -> bool:
176
        """Check if EGL context is valid."""
177

178
# EGL-specific constants and functions
179
# Available when platform supports EGL
180
from OpenGL.EGL import *
181
```
182

183
### Off-Screen Rendering (OSMesa)
184

185
Mesa off-screen rendering support for headless OpenGL rendering without window system.
186

187
```python { .api }
188
class OSMesaPlatform:
189
    """
190
    OSMesa platform implementation for off-screen rendering.
191
    Enables OpenGL rendering without window system or display.
192
    """
193
    
194
    def getGLExtensionPointer(self, name: str):
195
        """
196
        Get OpenGL extension function pointer via OSMesa.
197
        
198
        Parameters:
199
        - name: Extension function name
200
        
201
        Returns:
202
        Function pointer or None if not available
203
        """
204
    
205
    def getCurrentContext(self):
206
        """Get current OSMesa context."""
207
    
208
    def contextIsValid(self, context) -> bool:
209
        """Check if OSMesa context is valid."""
210

211
# OSMesa-specific functions
212
# Available when platform is OSMesaPlatform  
213
from OpenGL.osmesa import *
214
```
215

216
### Dynamic Library Loading
217

218
Cross-platform dynamic library loading with automatic library discovery.
219

220
```python { .api }
221
class CtypesLoader:
222
    """
223
    Cross-platform dynamic library loader using ctypes.
224
    Handles loading OpenGL libraries with platform-specific paths.
225
    """
226
    
227
    def loadLibrary(self, name: str):
228
        """
229
        Load dynamic library by name.
230
        
231
        Parameters:
232
        - name: Library name (platform-specific)
233
        
234
        Returns:
235
        Loaded library handle
236
        """
237
    
238
    def getFunction(self, library, name: str):
239
        """
240
        Get function from loaded library.
241
        
242
        Parameters:
243
        - library: Library handle from loadLibrary()
244
        - name: Function name
245
        
246
        Returns:
247
        Function pointer or None if not found
248
        """
249

250
# Platform-specific library names
251
LIBRARY_NAMES = {
252
    'nt': ['opengl32.dll', 'glu32.dll', 'glut32.dll'],
253
    'darwin': ['OpenGL.framework/OpenGL', 'GLUT.framework/GLUT'],
254
    'linux': ['libGL.so.1', 'libGLU.so.1', 'libglut.so.3'],
255
    'posix': ['libGL.so', 'libGLU.so', 'libglut.so']
256
}
257
```
258

259
### Extension Management
260

261
Platform-aware extension detection and function loading with fallback mechanisms.
262

263
```python { .api }
264
def hasExtension(extension_name: str) -> bool:
265
    """
266
    Check if OpenGL extension is available on current platform.
267
    
268
    Parameters:
269
    - extension_name: Extension name (e.g., "GL_ARB_vertex_buffer_object")
270
    
271
    Returns:
272
    True if extension is supported on current platform
273
    """
274

275
def getExtensionFunction(name: str):
276
    """
277
    Get platform-specific extension function pointer.
278
    
279
    Parameters:
280
    - name: Extension function name
281
    
282
    Returns:
283
    Function pointer or None if not available
284
    """
285

286
class ExtensionQuerier:
287
    """
288
    Platform-aware extension detection and management.
289
    Handles differences in extension reporting across platforms.
290
    """
291
    
292
    def __init__(self, platform):
293
        """
294
        Parameters:
295
        - platform: Platform implementation instance
296
        """
297
    
298
    def hasExtension(self, name: str) -> bool:
299
        """Check if extension is available."""
300
    
301
    def getExtensions(self) -> list:
302
        """Get list of all available extensions."""
303
```
304

305
### Context Information
306

307
Platform-specific context information and capabilities query.
308

309
```python { .api }
310
def getContextInfo() -> dict:
311
    """
312
    Get comprehensive OpenGL context information.
313
    
314
    Returns:
315
    Dictionary containing:
316
    - 'vendor': OpenGL vendor string
317
    - 'renderer': OpenGL renderer string  
318
    - 'version': OpenGL version string
319
    - 'extensions': List of available extensions
320
    - 'platform': Current platform name
321
    - 'context': Platform-specific context info
322
    """
323

324
def getRendererInfo() -> dict:
325
    """
326
    Get detailed renderer capabilities.
327
    
328
    Returns:
329
    Dictionary with platform-specific renderer information
330
    """
331

332
def getPlatformInfo() -> dict:
333
    """
334
    Get platform-specific information.
335
    
336
    Returns:
337
    Dictionary containing platform details and capabilities
338
    """
339
```
340

341
## Usage Examples
342

343
### Platform Selection
344
```python
345
import OpenGL
346
import os
347

348
# Set platform before importing GL modules
349
if os.environ.get('USE_EGL'):
350
    OpenGL.setPlatform('egl')
351
elif os.environ.get('WAYLAND_DISPLAY'):
352
    OpenGL.setPlatform('wayland')
353
else:
354
    # Use automatic detection
355
    pass
356

357
# Now import GL modules
358
from OpenGL.GL import *
359
```
360

361
### Cross-Platform Context Info
362
```python
363
from OpenGL.platform import getContextInfo, GetCurrentPlatform
364

365
# Get platform information
366
platform = GetCurrentPlatform()
367
print(f"Platform: {platform.__class__.__name__}")
368

369
# Get context information (requires active OpenGL context)
370
try:
371
    info = getContextInfo()
372
    print(f"Vendor: {info['vendor']}")
373
    print(f"Renderer: {info['renderer']}")
374
    print(f"Version: {info['version']}")
375
    print(f"Extensions: {len(info['extensions'])} available")
376
except:
377
    print("No OpenGL context available")
378
```
379

380
### Extension Detection
381
```python
382
from OpenGL.platform import hasExtension, getExtensionFunction
383

384
# Check for specific extensions
385
extensions_to_check = [
386
    'GL_ARB_vertex_buffer_object',
387
    'GL_ARB_shader_objects',
388
    'GL_EXT_framebuffer_object'
389
]
390

391
for ext in extensions_to_check:
392
    if hasExtension(ext):
393
        print(f"✓ {ext} is available")
394
    else:
395
        print(f"✗ {ext} is not available")
396

397
# Get extension function
398
vbo_gen_func = getExtensionFunction('glGenBuffersARB')
399
if vbo_gen_func:
400
    print("VBO functions available")
401
```
402

403
### Off-Screen Rendering Setup
404
```python
405
import OpenGL
406
# Force OSMesa for headless rendering
407
OpenGL.setPlatform('osmesa')
408

409
from OpenGL.GL import *
410
from OpenGL.osmesa import *
411

412
# Create off-screen context
413
width, height = 800, 600
414
context = OSMesaCreateContext(OSMESA_RGBA, None)
415
buffer = (ctypes.c_ubyte * (width * height * 4))()
416

417
if OSMesaMakeCurrent(context, buffer, GL_UNSIGNED_BYTE, width, height):
418
    # Now have working OpenGL context for rendering
419
    glViewport(0, 0, width, height)
420
    glClearColor(0.2, 0.3, 0.4, 1.0)
421
    glClear(GL_COLOR_BUFFER_BIT)
422
    
423
    # Render scene...
424
    
425
    # Clean up
426
    OSMesaDestroyContext(context)
427
```
428

429
### Platform-Specific Features
430
```python
431
from OpenGL.platform import GetCurrentPlatform
432
import sys
433

434
platform = GetCurrentPlatform()
435

436
if sys.platform == 'win32':
437
    # Windows-specific features
438
    from OpenGL.WGL import *
439
    print("Using WGL extensions")
440
    
441
elif sys.platform == 'darwin':
442
    # macOS-specific features
443
    from OpenGL.AGL import *
444
    print("Using CGL/AGL frameworks")
445
    
446
else:
447
    # Linux/Unix-specific features
448
    from OpenGL.GLX import *
449
    print("Using GLX extensions")
450
```
451

452
### Environment Variable Configuration
453
```python
454
import os
455

456
# User can control platform selection
457
platform_override = os.environ.get('PYOPENGL_PLATFORM')
458
if platform_override:
459
    print(f"Using platform override: {platform_override}")
460

461
# Other environment variables
462
if os.environ.get('PYOPENGL_USE_ACCELERATE') == '0':
463
    print("Acceleration disabled by environment")
464

465
if os.environ.get('PYOPENGL_ERROR_CHECKING') == '0':
466
    print("Error checking disabled by environment")
467
```
468

469
## Platform-Specific Constants
470

471
### Library Names by Platform
472
```python { .api }
473
# Windows
474
OPENGL32_DLL: str = "opengl32.dll"
475
GLU32_DLL: str = "glu32.dll"
476
GLUT32_DLL: str = "glut32.dll"
477

478
# macOS
479
OPENGL_FRAMEWORK: str = "OpenGL.framework/OpenGL"
480
GLUT_FRAMEWORK: str = "GLUT.framework/GLUT"
481

482
# Linux/Unix
483
LIBGL_SO: str = "libGL.so.1"
484
LIBGLU_SO: str = "libGLU.so.1"
485
LIBGLUT_SO: str = "libglut.so.3"
486
```
487

488
### Platform Identifiers
489
```python { .api }
490
PLATFORM_NT: str = "nt"           # Windows
491
PLATFORM_DARWIN: str = "darwin"   # macOS
492
PLATFORM_LINUX: str = "linux"     # Linux
493
PLATFORM_GLX: str = "glx"         # X11/GLX
494
PLATFORM_EGL: str = "egl"         # EGL
495
PLATFORM_OSMESA: str = "osmesa"   # Off-screen Mesa
496
PLATFORM_WAYLAND: str = "wayland" # Wayland
497
```
498

499
### Extension Categories
500
```python { .api }
501
WGL_EXTENSIONS: list  # Windows WGL extensions
502
GLX_EXTENSIONS: list  # Linux GLX extensions
503
CGL_EXTENSIONS: list  # macOS CGL extensions
504
EGL_EXTENSIONS: list  # EGL extensions
505
```