0
# Library Management
1
2
Core library initialization, termination, version queries, and error handling functions. These functions must be called in the correct order for proper GLFW operation.
3
4
## Capabilities
5
6
### Library Initialization
7
8
Initialize the GLFW library before using any other GLFW functions. Must be called successfully before any other GLFW operations.
9
10
```python { .api }
11
def init() -> int:
12
"""
13
Initialize the GLFW library.
14
15
Returns:
16
int: 1 (TRUE) if successful, 0 (FALSE) if failed
17
"""
18
19
def terminate() -> None:
20
"""
21
Terminate the GLFW library and free all resources.
22
23
This function destroys all remaining windows and cursors,
24
restores modified gamma ramps, and frees other resources.
25
"""
26
```
27
28
### Initialization Hints
29
30
Configure GLFW initialization behavior before calling `init()`.
31
32
```python { .api }
33
def init_hint(hint: int, value: int) -> None:
34
"""
35
Set initialization hints for GLFW library behavior.
36
37
Parameters:
38
hint: Initialization hint identifier
39
value: Hint value
40
"""
41
```
42
43
#### Initialization Hint Constants
44
45
```python { .api }
46
# Platform selection hints
47
PLATFORM: int = 0x00050003
48
ANY_PLATFORM: int = 0x00060000
49
PLATFORM_WIN32: int = 0x00060001
50
PLATFORM_COCOA: int = 0x00060002
51
PLATFORM_WAYLAND: int = 0x00060003
52
PLATFORM_X11: int = 0x00060004
53
PLATFORM_NULL: int = 0x00060005
54
55
# macOS-specific hints
56
COCOA_CHDIR_RESOURCES: int = 0x00051001
57
COCOA_MENUBAR: int = 0x00051002
58
59
# X11-specific hints
60
X11_XCB_VULKAN_SURFACE: int = 0x00052001
61
62
# Wayland-specific hints
63
WAYLAND_LIBDECOR: int = 0x00053001
64
65
# Joystick behavior hints
66
JOYSTICK_HAT_BUTTONS: int = 0x00050001
67
68
# ANGLE platform hints
69
ANGLE_PLATFORM_TYPE: int = 0x00050002
70
```
71
72
### Version Information
73
74
Query GLFW version and build information.
75
76
```python { .api }
77
def get_version() -> tuple[int, int, int]:
78
"""
79
Get the GLFW library version.
80
81
Returns:
82
tuple: (major, minor, revision) version numbers
83
"""
84
85
def get_version_string() -> bytes:
86
"""
87
Get version string with compile-time configuration info.
88
89
Returns:
90
bytes: Version string describing build configuration
91
"""
92
```
93
94
### Error Handling
95
96
Retrieve and manage GLFW errors.
97
98
```python { .api }
99
def get_error() -> tuple[int, bytes]:
100
"""
101
Get and clear the last error for the calling thread.
102
103
Returns:
104
tuple: (error_code, description) - error code and description
105
"""
106
107
def set_error_callback(cbfun) -> callable:
108
"""
109
Set the error callback function.
110
111
Parameters:
112
cbfun: Error callback function or None to remove callback
113
Signature: callback(error_code: int, description: str)
114
115
Returns:
116
callable: Previously set callback function or None
117
"""
118
```
119
120
#### Error Codes
121
122
```python { .api }
123
# Error code constants
124
NO_ERROR: int = 0
125
NOT_INITIALIZED: int = 0x00010001
126
NO_CURRENT_CONTEXT: int = 0x00010002
127
INVALID_ENUM: int = 0x00010003
128
INVALID_VALUE: int = 0x00010004
129
OUT_OF_MEMORY: int = 0x00010005
130
API_UNAVAILABLE: int = 0x00010006
131
VERSION_UNAVAILABLE: int = 0x00010007
132
PLATFORM_ERROR: int = 0x00010008
133
FORMAT_UNAVAILABLE: int = 0x00010009
134
NO_WINDOW_CONTEXT: int = 0x0001000A
135
CURSOR_UNAVAILABLE: int = 0x0001000B
136
FEATURE_UNAVAILABLE: int = 0x0001000C
137
FEATURE_UNIMPLEMENTED: int = 0x0001000D
138
PLATFORM_UNAVAILABLE: int = 0x0001000E
139
```
140
141
### Platform Information
142
143
Query platform support and current platform.
144
145
```python { .api }
146
def get_platform() -> int:
147
"""
148
Get the currently selected platform.
149
150
Returns:
151
int: Platform constant (PLATFORM_WIN32, PLATFORM_COCOA, etc.)
152
"""
153
154
def platform_supported(platform: int) -> int:
155
"""
156
Check if the library includes support for the specified platform.
157
158
Parameters:
159
platform: Platform constant to check
160
161
Returns:
162
int: 1 if supported, 0 if not supported
163
"""
164
```
165
166
### Memory Management
167
168
Configure custom memory allocation (advanced usage).
169
170
```python { .api }
171
def init_allocator(allocate, reallocate, deallocate) -> None:
172
"""
173
Set custom memory allocator functions.
174
175
Parameters:
176
allocate: Custom allocation function or None
177
reallocate: Custom reallocation function or None
178
deallocate: Custom deallocation function or None
179
"""
180
```
181
182
## Usage Examples
183
184
### Basic Initialization
185
186
```python
187
import glfw
188
189
# Initialize GLFW
190
if not glfw.init():
191
raise Exception("Failed to initialize GLFW")
192
193
try:
194
# Use GLFW functions here
195
pass
196
finally:
197
# Always terminate GLFW
198
glfw.terminate()
199
```
200
201
### Error Handling with Callback
202
203
```python
204
import glfw
205
206
def error_callback(error_code, description):
207
print(f"GLFW Error {error_code}: {description.decode('utf-8')}")
208
209
# Set error callback before initialization
210
glfw.set_error_callback(error_callback)
211
212
if not glfw.init():
213
raise Exception("Failed to initialize GLFW")
214
215
# ... rest of application
216
217
glfw.terminate()
218
```
219
220
### Platform-Specific Initialization
221
222
```python
223
import glfw
224
225
# Force X11 on Linux (instead of Wayland)
226
glfw.init_hint(glfw.PLATFORM, glfw.PLATFORM_X11)
227
228
if not glfw.init():
229
raise Exception("Failed to initialize GLFW")
230
231
glfw.terminate()
232
```