0
# pyGLFW
1

2
A comprehensive Python ctypes-based wrapper for GLFW3 that provides complete bindings for OpenGL, OpenGL ES, and Vulkan development on desktop platforms. pyGLFW enables creation of windowed graphics applications with hardware-accelerated rendering, supporting Windows, macOS, and Linux (both X11 and Wayland variants).
3

4
## Package Information
5

6
- **Package Name**: glfw
7
- **Language**: Python
8
- **Installation**: `pip install glfw`
9
- **Version**: 2.9.0
10
- **License**: MIT
11

12
## Core Imports
13

14
```python
15
import glfw
16
```
17

18
For C-style API with GLFW prefixes:
19

20
```python
21
import glfw.GLFW as GLFW
22
# Or to import all constants and functions:
23
from glfw.GLFW import *
24
```
25

26
## Basic Usage
27

28
```python
29
import glfw
30

31
# Initialize GLFW
32
if not glfw.init():
33
    raise Exception("GLFW could not be initialized!")
34

35
# Create a window
36
window = glfw.create_window(800, 600, "Hello World", None, None)
37
if not window:
38
    glfw.terminate()
39
    raise Exception("GLFW window could not be created!")
40

41
# Make the OpenGL context current
42
glfw.make_context_current(window)
43

44
# Main loop
45
while not glfw.window_should_close(window):
46
    # Poll for and process events
47
    glfw.poll_events()
48
    
49
    # Render here (OpenGL calls would go here)
50
    
51
    # Swap front and back buffers
52
    glfw.swap_buffers(window)
53

54
# Clean up
55
glfw.destroy_window(window)
56
glfw.terminate()
57
```
58

59
## Architecture
60

61
pyGLFW closely follows the GLFW C API design with Pythonic enhancements:
62

63
- **Library Initialization**: Must call `glfw.init()` before using any GLFW functions
64
- **Window Management**: Create windows with OpenGL/Vulkan contexts for rendering
65
- **Event System**: Callback-based event handling for input, window state changes
66
- **Cross-Platform**: Automatic platform detection and library loading
67
- **Error Handling**: Configurable error reporting (exceptions, warnings, or logging)
68
- **Memory Management**: Automatic cleanup of Python objects and callbacks
69

70
## Configuration
71

72
pyGLFW provides global configuration variables:
73

74
```python { .api }
75
# Error reporting configuration
76
glfw.ERROR_REPORTING = 'warn'  # 'raise', 'warn', 'log', 'ignore', or dict
77

78
# Gamma ramp normalization (0.0-1.0 vs 0-65535)
79
glfw.NORMALIZE_GAMMA_RAMPS = True
80
```
81

82
## Capabilities
83

84
### Library Management
85

86
Core library initialization, termination, and version information functions that must be called before using any other GLFW functionality.
87

88
```python { .api }
89
def init() -> int: ...
90
def terminate() -> None: ...
91
def init_hint(hint: int, value: int) -> None: ...
92
def get_version() -> tuple[int, int, int]: ...
93
def get_version_string() -> bytes: ...
94
def get_error() -> tuple[int, bytes]: ...
95
```
96

97
[Library Management](./library-management.md)
98

99
### Window Management
100

101
Complete window lifecycle management including creation, destruction, properties, and state control for OpenGL and Vulkan applications.
102

103
```python { .api }
104
def create_window(width: int, height: int, title: str, monitor, share) -> ctypes.POINTER: ...
105
def destroy_window(window) -> None: ...
106
def window_should_close(window) -> int: ...
107
def set_window_should_close(window, value: int) -> None: ...
108
def set_window_title(window, title: str) -> None: ...
109
def get_window_pos(window) -> tuple[int, int]: ...
110
def set_window_pos(window, xpos: int, ypos: int) -> None: ...
111
```
112

113
[Window Management](./window-management.md)
114

115
### Input Handling
116

117
Comprehensive input system supporting keyboard, mouse, joystick, and gamepad input with both polling and callback-based event handling.
118

119
```python { .api }
120
def get_key(window, key: int) -> int: ...
121
def get_mouse_button(window, button: int) -> int: ...
122
def get_cursor_pos(window) -> tuple[float, float]: ...
123
def set_cursor_pos(window, xpos: float, ypos: float) -> None: ...
124
def set_key_callback(window, cbfun) -> callable: ...
125
def set_mouse_button_callback(window, cbfun) -> callable: ...
126
```
127

128
[Input Handling](./input-handling.md)
129

130
### Monitor and Display
131

132
Monitor enumeration, video mode queries, and display configuration for multi-monitor setups and fullscreen applications.
133

134
```python { .api }
135
def get_monitors() -> list: ...
136
def get_primary_monitor() -> ctypes.POINTER: ...
137
def get_monitor_name(monitor) -> bytes: ...
138
def get_video_modes(monitor) -> list: ...
139
def get_video_mode(monitor) -> object: ...
140
def set_gamma(monitor, gamma: float) -> None: ...
141
```
142

143
[Monitor and Display](./monitor-display.md)
144

145
### OpenGL Context
146

147
OpenGL context creation, management, and OpenGL function loading for hardware-accelerated graphics rendering.
148

149
```python { .api }
150
def make_context_current(window) -> None: ...
151
def get_current_context() -> ctypes.POINTER: ...
152
def swap_buffers(window) -> None: ...
153
def swap_interval(interval: int) -> None: ...
154
def extension_supported(extension: str) -> int: ...
155
def get_proc_address(procname: str) -> ctypes.c_void_p: ...
156
```
157

158
[OpenGL Context](./opengl-context.md)
159

160
### Vulkan Support
161

162
Vulkan surface creation and instance management for modern low-level graphics programming.
163

164
```python { .api }
165
def vulkan_supported() -> bool: ...
166
def get_required_instance_extensions() -> list[str]: ...
167
def create_window_surface(instance, window, allocator, surface) -> int: ...
168
def get_physical_device_presentation_support(instance, device, queuefamily: int) -> int: ...
169
def get_instance_proc_address(instance, procname: str) -> ctypes.c_void_p: ...
170
```
171

172
[Vulkan Support](./vulkan-support.md)
173

174
## Types
175

176
### Core Types
177

178
```python { .api }
179
class GLFWError(UserWarning):
180
    """Exception class for GLFW errors."""
181
    def __init__(self, message: str, error_code: int = None): ...
182
    error_code: int
183
```
184

185
### Window and Monitor Handles
186

187
```python { .api }
188
# Opaque handle types (ctypes.POINTER objects)
189
GLFWwindow = ctypes.POINTER  # Window handle
190
GLFWmonitor = ctypes.POINTER  # Monitor handle  
191
GLFWcursor = ctypes.POINTER  # Cursor handle
192
```
193

194
### Data Structures
195

196
```python { .api }
197
# Video mode information
198
GLFWvidmode = namedtuple('GLFWvidmode', ['size', 'bits', 'refresh_rate'])
199
Size = namedtuple('Size', ['width', 'height'])
200
Bits = namedtuple('Bits', ['red', 'green', 'blue'])
201

202
# Gamma ramp data
203
GLFWgammaramp = namedtuple('GLFWgammaramp', ['red', 'green', 'blue'])
204

205
# Image data (for icons and cursors)
206
GLFWimage = namedtuple('GLFWimage', ['width', 'height', 'pixels'])
207

208
# Gamepad state
209
GLFWgamepadstate = namedtuple('GLFWgamepadstate', ['buttons', 'axes'])
210
```
211

212
## Constants
213

214
pyGLFW provides 480+ constants for keys, mouse buttons, window hints, and more:
215

216
```python { .api }
217
# Version constants
218
VERSION_MAJOR: int = 3
219
VERSION_MINOR: int = 4
220
VERSION_REVISION: int = 0
221

222
# Boolean values
223
TRUE: int = 1
224
FALSE: int = 0
225

226
# Key actions
227
RELEASE: int = 0
228
PRESS: int = 1
229
REPEAT: int = 2
230

231
# Example key constants (100+ available)
232
KEY_SPACE: int = 32
233
KEY_A: int = 65
234
KEY_ESCAPE: int = 256
235
KEY_ENTER: int = 257
236

237
# Mouse button constants
238
MOUSE_BUTTON_LEFT: int = 0
239
MOUSE_BUTTON_RIGHT: int = 1
240
MOUSE_BUTTON_MIDDLE: int = 2
241

242
# Window hints and attributes
243
FOCUSED: int = 0x00020001
244
RESIZABLE: int = 0x00020003
245
VISIBLE: int = 0x00020004
246
```
247

248
*Note: See individual capability documentation for complete constant listings by category.*