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.*