1 | /************************************************************************* |
2 | * GLFW 3.4 - www.glfw.org |
3 | * A library for OpenGL, window and input |
4 | *------------------------------------------------------------------------ |
5 | * Copyright (c) 2002-2006 Marcus Geelnard |
6 | * Copyright (c) 2006-2019 Camilla Löwy <elmindreda@glfw.org> |
7 | * |
8 | * This software is provided 'as-is', without any express or implied |
9 | * warranty. In no event will the authors be held liable for any damages |
10 | * arising from the use of this software. |
11 | * |
12 | * Permission is granted to anyone to use this software for any purpose, |
13 | * including commercial applications, and to alter it and redistribute it |
14 | * freely, subject to the following restrictions: |
15 | * |
16 | * 1. The origin of this software must not be misrepresented; you must not |
17 | * claim that you wrote the original software. If you use this software |
18 | * in a product, an acknowledgment in the product documentation would |
19 | * be appreciated but is not required. |
20 | * |
21 | * 2. Altered source versions must be plainly marked as such, and must not |
22 | * be misrepresented as being the original software. |
23 | * |
24 | * 3. This notice may not be removed or altered from any source |
25 | * distribution. |
26 | * |
27 | *************************************************************************/ |
28 | |
29 | #ifndef _glfw3_h_ |
30 | #define _glfw3_h_ |
31 | |
32 | #ifdef __cplusplus |
33 | extern "C" { |
34 | #endif |
35 | |
36 | |
37 | /************************************************************************* |
38 | * Doxygen documentation |
39 | *************************************************************************/ |
40 | |
41 | /*! @file glfw3.h |
42 | * @brief The header of the GLFW 3 API. |
43 | * |
44 | * This is the header file of the GLFW 3 API. It defines all its types and |
45 | * declares all its functions. |
46 | * |
47 | * For more information about how to use this file, see @ref build_include. |
48 | */ |
49 | /*! @defgroup context Context reference |
50 | * @brief Functions and types related to OpenGL and OpenGL ES contexts. |
51 | * |
52 | * This is the reference documentation for OpenGL and OpenGL ES context related |
53 | * functions. For more task-oriented information, see the @ref context_guide. |
54 | */ |
55 | /*! @defgroup vulkan Vulkan reference |
56 | * @brief Functions and types related to Vulkan. |
57 | * |
58 | * This is the reference documentation for Vulkan related functions and types. |
59 | * For more task-oriented information, see the @ref vulkan_guide. |
60 | */ |
61 | /*! @defgroup init Initialization, version and error reference |
62 | * @brief Functions and types related to initialization and error handling. |
63 | * |
64 | * This is the reference documentation for initialization and termination of |
65 | * the library, version management and error handling. For more task-oriented |
66 | * information, see the @ref intro_guide. |
67 | */ |
68 | /*! @defgroup input Input reference |
69 | * @brief Functions and types related to input handling. |
70 | * |
71 | * This is the reference documentation for input related functions and types. |
72 | * For more task-oriented information, see the @ref input_guide. |
73 | */ |
74 | /*! @defgroup monitor Monitor reference |
75 | * @brief Functions and types related to monitors. |
76 | * |
77 | * This is the reference documentation for monitor related functions and types. |
78 | * For more task-oriented information, see the @ref monitor_guide. |
79 | */ |
80 | /*! @defgroup window Window reference |
81 | * @brief Functions and types related to windows. |
82 | * |
83 | * This is the reference documentation for window related functions and types, |
84 | * including creation, deletion and event polling. For more task-oriented |
85 | * information, see the @ref window_guide. |
86 | */ |
87 | |
88 | |
89 | /************************************************************************* |
90 | * Compiler- and platform-specific preprocessor work |
91 | *************************************************************************/ |
92 | |
93 | /* If we are we on Windows, we want a single define for it. |
94 | */ |
95 | #if !defined(_WIN32) && (defined(__WIN32__) || defined(WIN32) || defined(__MINGW32__)) |
96 | #define _WIN32 |
97 | #endif /* _WIN32 */ |
98 | |
99 | /* Include because most Windows GLU headers need wchar_t and |
100 | * the macOS OpenGL header blocks the definition of ptrdiff_t by glext.h. |
101 | * Include it unconditionally to avoid surprising side-effects. |
102 | */ |
103 | #include <stddef.h> |
104 | |
105 | /* Include because it is needed by Vulkan and related functions. |
106 | * Include it unconditionally to avoid surprising side-effects. |
107 | */ |
108 | #include <stdint.h> |
109 | |
110 | #if defined(GLFW_INCLUDE_VULKAN) |
111 | #include <vulkan/vulkan.h> |
112 | #endif /* Vulkan header */ |
113 | |
114 | /* The Vulkan header may have indirectly included windows.h (because of |
115 | * VK_USE_PLATFORM_WIN32_KHR) so we offer our replacement symbols after it. |
116 | */ |
117 | |
118 | /* It is customary to use APIENTRY for OpenGL function pointer declarations on |
119 | * all platforms. Additionally, the Windows OpenGL header needs APIENTRY. |
120 | */ |
121 | #if !defined(APIENTRY) |
122 | #if defined(_WIN32) |
123 | #define APIENTRY __stdcall |
124 | #else |
125 | #define APIENTRY |
126 | #endif |
127 | #define GLFW_APIENTRY_DEFINED |
128 | #endif /* APIENTRY */ |
129 | |
130 | /* Some Windows OpenGL headers need this. |
131 | */ |
132 | #if !defined(WINGDIAPI) && defined(_WIN32) |
133 | #define WINGDIAPI __declspec(dllimport) |
134 | #define GLFW_WINGDIAPI_DEFINED |
135 | #endif /* WINGDIAPI */ |
136 | |
137 | /* Some Windows GLU headers need this. |
138 | */ |
139 | #if !defined(CALLBACK) && defined(_WIN32) |
140 | #define CALLBACK __stdcall |
141 | #define GLFW_CALLBACK_DEFINED |
142 | #endif /* CALLBACK */ |
143 | |
144 | /* Include the chosen OpenGL or OpenGL ES headers. |
145 | */ |
146 | #if defined(GLFW_INCLUDE_ES1) |
147 | |
148 | #include <GLES/gl.h> |
149 | #if defined(GLFW_INCLUDE_GLEXT) |
150 | #include <GLES/glext.h> |
151 | #endif |
152 | |
153 | #elif defined(GLFW_INCLUDE_ES2) |
154 | |
155 | #include <GLES2/gl2.h> |
156 | #if defined(GLFW_INCLUDE_GLEXT) |
157 | #include <GLES2/gl2ext.h> |
158 | #endif |
159 | |
160 | #elif defined(GLFW_INCLUDE_ES3) |
161 | |
162 | #include <GLES3/gl3.h> |
163 | #if defined(GLFW_INCLUDE_GLEXT) |
164 | #include <GLES2/gl2ext.h> |
165 | #endif |
166 | |
167 | #elif defined(GLFW_INCLUDE_ES31) |
168 | |
169 | #include <GLES3/gl31.h> |
170 | #if defined(GLFW_INCLUDE_GLEXT) |
171 | #include <GLES2/gl2ext.h> |
172 | #endif |
173 | |
174 | #elif defined(GLFW_INCLUDE_ES32) |
175 | |
176 | #include <GLES3/gl32.h> |
177 | #if defined(GLFW_INCLUDE_GLEXT) |
178 | #include <GLES2/gl2ext.h> |
179 | #endif |
180 | |
181 | #elif defined(GLFW_INCLUDE_GLCOREARB) |
182 | |
183 | #if defined(__APPLE__) |
184 | |
185 | #include <OpenGL/gl3.h> |
186 | #if defined(GLFW_INCLUDE_GLEXT) |
187 | #include <OpenGL/gl3ext.h> |
188 | #endif /*GLFW_INCLUDE_GLEXT*/ |
189 | |
190 | #else /*__APPLE__*/ |
191 | |
192 | #include <GL/glcorearb.h> |
193 | |
194 | #endif /*__APPLE__*/ |
195 | |
196 | #elif !defined(GLFW_INCLUDE_NONE) |
197 | |
198 | #if defined(__APPLE__) |
199 | |
200 | #if !defined(GLFW_INCLUDE_GLEXT) |
201 | #define GL_GLEXT_LEGACY |
202 | #endif |
203 | #include <OpenGL/gl.h> |
204 | #if defined(GLFW_INCLUDE_GLU) |
205 | #include <OpenGL/glu.h> |
206 | #endif |
207 | |
208 | #else /*__APPLE__*/ |
209 | |
210 | #include <GL/gl.h> |
211 | #if defined(GLFW_INCLUDE_GLEXT) |
212 | #include <GL/glext.h> |
213 | #endif |
214 | #if defined(GLFW_INCLUDE_GLU) |
215 | #include <GL/glu.h> |
216 | #endif |
217 | |
218 | #endif /*__APPLE__*/ |
219 | |
220 | #endif /* OpenGL and OpenGL ES headers */ |
221 | |
222 | #if defined(GLFW_DLL) && defined(_GLFW_BUILD_DLL) |
223 | /* GLFW_DLL must be defined by applications that are linking against the DLL |
224 | * version of the GLFW library. _GLFW_BUILD_DLL is defined by the GLFW |
225 | * configuration header when compiling the DLL version of the library. |
226 | */ |
227 | #error "You must not have both GLFW_DLL and _GLFW_BUILD_DLL defined" |
228 | #endif |
229 | |
230 | /* GLFWAPI is used to declare public API functions for export |
231 | * from the DLL / shared library / dynamic library. |
232 | */ |
233 | #if defined(_WIN32) && defined(_GLFW_BUILD_DLL) |
234 | /* We are building GLFW as a Win32 DLL */ |
235 | #define GLFWAPI __declspec(dllexport) |
236 | #elif defined(_WIN32) && defined(GLFW_DLL) |
237 | /* We are calling GLFW as a Win32 DLL */ |
238 | #define GLFWAPI __declspec(dllimport) |
239 | #elif defined(__GNUC__) && defined(_GLFW_BUILD_DLL) |
240 | /* We are building GLFW as a shared / dynamic library */ |
241 | #define GLFWAPI __attribute__((visibility("default"))) |
242 | #else |
243 | /* We are building or calling GLFW as a static library */ |
244 | #define GLFWAPI |
245 | #endif |
246 | |
247 | |
248 | /************************************************************************* |
249 | * GLFW API tokens |
250 | *************************************************************************/ |
251 | |
252 | /*! @name GLFW version macros |
253 | * @{ */ |
254 | /*! @brief The major version number of the GLFW library. |
255 | * |
256 | * This is incremented when the API is changed in non-compatible ways. |
257 | * @ingroup init |
258 | */ |
259 | #define GLFW_VERSION_MAJOR 3 |
260 | /*! @brief The minor version number of the GLFW library. |
261 | * |
262 | * This is incremented when features are added to the API but it remains |
263 | * backward-compatible. |
264 | * @ingroup init |
265 | */ |
266 | #define GLFW_VERSION_MINOR 4 |
267 | /*! @brief The revision number of the GLFW library. |
268 | * |
269 | * This is incremented when a bug fix release is made that does not contain any |
270 | * API changes. |
271 | * @ingroup init |
272 | */ |
273 | #define GLFW_VERSION_REVISION 0 |
274 | /*! @} */ |
275 | |
276 | /*! @brief One. |
277 | * |
278 | * This is only semantic sugar for the number 1. You can instead use `1` or |
279 | * `true` or `_True` or `GL_TRUE` or `VK_TRUE` or anything else that is equal |
280 | * to one. |
281 | * |
282 | * @ingroup init |
283 | */ |
284 | #define GLFW_TRUE 1 |
285 | /*! @brief Zero. |
286 | * |
287 | * This is only semantic sugar for the number 0. You can instead use `0` or |
288 | * `false` or `_False` or `GL_FALSE` or `VK_FALSE` or anything else that is |
289 | * equal to zero. |
290 | * |
291 | * @ingroup init |
292 | */ |
293 | #define GLFW_FALSE 0 |
294 | |
295 | /*! @name Key and button actions |
296 | * @{ */ |
297 | /*! @brief The key or mouse button was released. |
298 | * |
299 | * The key or mouse button was released. |
300 | * |
301 | * @ingroup input |
302 | */ |
303 | #define GLFW_RELEASE 0 |
304 | /*! @brief The key or mouse button was pressed. |
305 | * |
306 | * The key or mouse button was pressed. |
307 | * |
308 | * @ingroup input |
309 | */ |
310 | #define GLFW_PRESS 1 |
311 | /*! @brief The key was held down until it repeated. |
312 | * |
313 | * The key was held down until it repeated. |
314 | * |
315 | * @ingroup input |
316 | */ |
317 | #define GLFW_REPEAT 2 |
318 | /*! @} */ |
319 | |
320 | /*! @defgroup hat_state Joystick hat states |
321 | * @brief Joystick hat states. |
322 | * |
323 | * See [joystick hat input](@ref joystick_hat) for how these are used. |
324 | * |
325 | * @ingroup input |
326 | * @{ */ |
327 | #define GLFW_HAT_CENTERED 0 |
328 | #define GLFW_HAT_UP 1 |
329 | #define GLFW_HAT_RIGHT 2 |
330 | #define GLFW_HAT_DOWN 4 |
331 | #define GLFW_HAT_LEFT 8 |
332 | #define GLFW_HAT_RIGHT_UP (GLFW_HAT_RIGHT | GLFW_HAT_UP) |
333 | #define GLFW_HAT_RIGHT_DOWN (GLFW_HAT_RIGHT | GLFW_HAT_DOWN) |
334 | #define GLFW_HAT_LEFT_UP (GLFW_HAT_LEFT | GLFW_HAT_UP) |
335 | #define GLFW_HAT_LEFT_DOWN (GLFW_HAT_LEFT | GLFW_HAT_DOWN) |
336 | /*! @} */ |
337 | |
338 | /*! @defgroup keys Keyboard keys |
339 | * @brief Keyboard key IDs. |
340 | * |
341 | * See [key input](@ref input_key) for how these are used. |
342 | * |
343 | * These key codes are inspired by the _USB HID Usage Tables v1.12_ (p. 53-60), |
344 | * but re-arranged to map to 7-bit ASCII for printable keys (function keys are |
345 | * put in the 256+ range). |
346 | * |
347 | * The naming of the key codes follow these rules: |
348 | * - The US keyboard layout is used |
349 | * - Names of printable alpha-numeric characters are used (e.g. "A", "R", |
350 | * "3", etc.) |
351 | * - For non-alphanumeric characters, Unicode:ish names are used (e.g. |
352 | * "COMMA", "LEFT_SQUARE_BRACKET", etc.). Note that some names do not |
353 | * correspond to the Unicode standard (usually for brevity) |
354 | * - Keys that lack a clear US mapping are named "WORLD_x" |
355 | * - For non-printable keys, custom names are used (e.g. "F4", |
356 | * "BACKSPACE", etc.) |
357 | * |
358 | * @ingroup input |
359 | * @{ |
360 | */ |
361 | |
362 | /* The unknown key */ |
363 | #define GLFW_KEY_UNKNOWN -1 |
364 | |
365 | /* Printable keys */ |
366 | #define GLFW_KEY_SPACE 32 |
367 | #define GLFW_KEY_APOSTROPHE 39 /* ' */ |
368 | #define GLFW_KEY_COMMA 44 /* , */ |
369 | #define GLFW_KEY_MINUS 45 /* - */ |
370 | #define GLFW_KEY_PERIOD 46 /* . */ |
371 | #define GLFW_KEY_SLASH 47 /* / */ |
372 | #define GLFW_KEY_0 48 |
373 | #define GLFW_KEY_1 49 |
374 | #define GLFW_KEY_2 50 |
375 | #define GLFW_KEY_3 51 |
376 | #define GLFW_KEY_4 52 |
377 | #define GLFW_KEY_5 53 |
378 | #define GLFW_KEY_6 54 |
379 | #define GLFW_KEY_7 55 |
380 | #define GLFW_KEY_8 56 |
381 | #define GLFW_KEY_9 57 |
382 | #define GLFW_KEY_SEMICOLON 59 /* ; */ |
383 | #define GLFW_KEY_EQUAL 61 /* = */ |
384 | #define GLFW_KEY_A 65 |
385 | #define GLFW_KEY_B 66 |
386 | #define GLFW_KEY_C 67 |
387 | #define GLFW_KEY_D 68 |
388 | #define GLFW_KEY_E 69 |
389 | #define GLFW_KEY_F 70 |
390 | #define GLFW_KEY_G 71 |
391 | #define GLFW_KEY_H 72 |
392 | #define GLFW_KEY_I 73 |
393 | #define GLFW_KEY_J 74 |
394 | #define GLFW_KEY_K 75 |
395 | #define GLFW_KEY_L 76 |
396 | #define GLFW_KEY_M 77 |
397 | #define GLFW_KEY_N 78 |
398 | #define GLFW_KEY_O 79 |
399 | #define GLFW_KEY_P 80 |
400 | #define GLFW_KEY_Q 81 |
401 | #define GLFW_KEY_R 82 |
402 | #define GLFW_KEY_S 83 |
403 | #define GLFW_KEY_T 84 |
404 | #define GLFW_KEY_U 85 |
405 | #define GLFW_KEY_V 86 |
406 | #define GLFW_KEY_W 87 |
407 | #define GLFW_KEY_X 88 |
408 | #define GLFW_KEY_Y 89 |
409 | #define GLFW_KEY_Z 90 |
410 | #define GLFW_KEY_LEFT_BRACKET 91 /* [ */ |
411 | #define GLFW_KEY_BACKSLASH 92 /* \ */ |
412 | #define GLFW_KEY_RIGHT_BRACKET 93 /* ] */ |
413 | #define GLFW_KEY_GRAVE_ACCENT 96 /* ` */ |
414 | #define GLFW_KEY_WORLD_1 161 /* non-US #1 */ |
415 | #define GLFW_KEY_WORLD_2 162 /* non-US #2 */ |
416 | |
417 | /* Function keys */ |
418 | #define GLFW_KEY_ESCAPE 256 |
419 | #define GLFW_KEY_ENTER 257 |
420 | #define GLFW_KEY_TAB 258 |
421 | #define GLFW_KEY_BACKSPACE 259 |
422 | #define GLFW_KEY_INSERT 260 |
423 | #define GLFW_KEY_DELETE 261 |
424 | #define GLFW_KEY_RIGHT 262 |
425 | #define GLFW_KEY_LEFT 263 |
426 | #define GLFW_KEY_DOWN 264 |
427 | #define GLFW_KEY_UP 265 |
428 | #define GLFW_KEY_PAGE_UP 266 |
429 | #define GLFW_KEY_PAGE_DOWN 267 |
430 | #define GLFW_KEY_HOME 268 |
431 | #define GLFW_KEY_END 269 |
432 | #define GLFW_KEY_CAPS_LOCK 280 |
433 | #define GLFW_KEY_SCROLL_LOCK 281 |
434 | #define GLFW_KEY_NUM_LOCK 282 |
435 | #define GLFW_KEY_PRINT_SCREEN 283 |
436 | #define GLFW_KEY_PAUSE 284 |
437 | #define GLFW_KEY_F1 290 |
438 | #define GLFW_KEY_F2 291 |
439 | #define GLFW_KEY_F3 292 |
440 | #define GLFW_KEY_F4 293 |
441 | #define GLFW_KEY_F5 294 |
442 | #define GLFW_KEY_F6 295 |
443 | #define GLFW_KEY_F7 296 |
444 | #define GLFW_KEY_F8 297 |
445 | #define GLFW_KEY_F9 298 |
446 | #define GLFW_KEY_F10 299 |
447 | #define GLFW_KEY_F11 300 |
448 | #define GLFW_KEY_F12 301 |
449 | #define GLFW_KEY_F13 302 |
450 | #define GLFW_KEY_F14 303 |
451 | #define GLFW_KEY_F15 304 |
452 | #define GLFW_KEY_F16 305 |
453 | #define GLFW_KEY_F17 306 |
454 | #define GLFW_KEY_F18 307 |
455 | #define GLFW_KEY_F19 308 |
456 | #define GLFW_KEY_F20 309 |
457 | #define GLFW_KEY_F21 310 |
458 | #define GLFW_KEY_F22 311 |
459 | #define GLFW_KEY_F23 312 |
460 | #define GLFW_KEY_F24 313 |
461 | #define GLFW_KEY_F25 314 |
462 | #define GLFW_KEY_KP_0 320 |
463 | #define GLFW_KEY_KP_1 321 |
464 | #define GLFW_KEY_KP_2 322 |
465 | #define GLFW_KEY_KP_3 323 |
466 | #define GLFW_KEY_KP_4 324 |
467 | #define GLFW_KEY_KP_5 325 |
468 | #define GLFW_KEY_KP_6 326 |
469 | #define GLFW_KEY_KP_7 327 |
470 | #define GLFW_KEY_KP_8 328 |
471 | #define GLFW_KEY_KP_9 329 |
472 | #define GLFW_KEY_KP_DECIMAL 330 |
473 | #define GLFW_KEY_KP_DIVIDE 331 |
474 | #define GLFW_KEY_KP_MULTIPLY 332 |
475 | #define GLFW_KEY_KP_SUBTRACT 333 |
476 | #define GLFW_KEY_KP_ADD 334 |
477 | #define GLFW_KEY_KP_ENTER 335 |
478 | #define GLFW_KEY_KP_EQUAL 336 |
479 | #define GLFW_KEY_LEFT_SHIFT 340 |
480 | #define GLFW_KEY_LEFT_CONTROL 341 |
481 | #define GLFW_KEY_LEFT_ALT 342 |
482 | #define GLFW_KEY_LEFT_SUPER 343 |
483 | #define GLFW_KEY_RIGHT_SHIFT 344 |
484 | #define GLFW_KEY_RIGHT_CONTROL 345 |
485 | #define GLFW_KEY_RIGHT_ALT 346 |
486 | #define GLFW_KEY_RIGHT_SUPER 347 |
487 | #define 348 |
488 | |
489 | #define GLFW_KEY_LAST GLFW_KEY_MENU |
490 | |
491 | /*! @} */ |
492 | |
493 | /*! @defgroup mods Modifier key flags |
494 | * @brief Modifier key flags. |
495 | * |
496 | * See [key input](@ref input_key) for how these are used. |
497 | * |
498 | * @ingroup input |
499 | * @{ */ |
500 | |
501 | /*! @brief If this bit is set one or more Shift keys were held down. |
502 | * |
503 | * If this bit is set one or more Shift keys were held down. |
504 | */ |
505 | #define GLFW_MOD_SHIFT 0x0001 |
506 | /*! @brief If this bit is set one or more Control keys were held down. |
507 | * |
508 | * If this bit is set one or more Control keys were held down. |
509 | */ |
510 | #define GLFW_MOD_CONTROL 0x0002 |
511 | /*! @brief If this bit is set one or more Alt keys were held down. |
512 | * |
513 | * If this bit is set one or more Alt keys were held down. |
514 | */ |
515 | #define GLFW_MOD_ALT 0x0004 |
516 | /*! @brief If this bit is set one or more Super keys were held down. |
517 | * |
518 | * If this bit is set one or more Super keys were held down. |
519 | */ |
520 | #define GLFW_MOD_SUPER 0x0008 |
521 | /*! @brief If this bit is set the Caps Lock key is enabled. |
522 | * |
523 | * If this bit is set the Caps Lock key is enabled and the @ref |
524 | * GLFW_LOCK_KEY_MODS input mode is set. |
525 | */ |
526 | #define GLFW_MOD_CAPS_LOCK 0x0010 |
527 | /*! @brief If this bit is set the Num Lock key is enabled. |
528 | * |
529 | * If this bit is set the Num Lock key is enabled and the @ref |
530 | * GLFW_LOCK_KEY_MODS input mode is set. |
531 | */ |
532 | #define GLFW_MOD_NUM_LOCK 0x0020 |
533 | |
534 | /*! @} */ |
535 | |
536 | /*! @defgroup buttons Mouse buttons |
537 | * @brief Mouse button IDs. |
538 | * |
539 | * See [mouse button input](@ref input_mouse_button) for how these are used. |
540 | * |
541 | * @ingroup input |
542 | * @{ */ |
543 | #define GLFW_MOUSE_BUTTON_1 0 |
544 | #define GLFW_MOUSE_BUTTON_2 1 |
545 | #define GLFW_MOUSE_BUTTON_3 2 |
546 | #define GLFW_MOUSE_BUTTON_4 3 |
547 | #define GLFW_MOUSE_BUTTON_5 4 |
548 | #define GLFW_MOUSE_BUTTON_6 5 |
549 | #define GLFW_MOUSE_BUTTON_7 6 |
550 | #define GLFW_MOUSE_BUTTON_8 7 |
551 | #define GLFW_MOUSE_BUTTON_LAST GLFW_MOUSE_BUTTON_8 |
552 | #define GLFW_MOUSE_BUTTON_LEFT GLFW_MOUSE_BUTTON_1 |
553 | #define GLFW_MOUSE_BUTTON_RIGHT GLFW_MOUSE_BUTTON_2 |
554 | #define GLFW_MOUSE_BUTTON_MIDDLE GLFW_MOUSE_BUTTON_3 |
555 | /*! @} */ |
556 | |
557 | /*! @defgroup joysticks Joysticks |
558 | * @brief Joystick IDs. |
559 | * |
560 | * See [joystick input](@ref joystick) for how these are used. |
561 | * |
562 | * @ingroup input |
563 | * @{ */ |
564 | #define GLFW_JOYSTICK_1 0 |
565 | #define GLFW_JOYSTICK_2 1 |
566 | #define GLFW_JOYSTICK_3 2 |
567 | #define GLFW_JOYSTICK_4 3 |
568 | #define GLFW_JOYSTICK_5 4 |
569 | #define GLFW_JOYSTICK_6 5 |
570 | #define GLFW_JOYSTICK_7 6 |
571 | #define GLFW_JOYSTICK_8 7 |
572 | #define GLFW_JOYSTICK_9 8 |
573 | #define GLFW_JOYSTICK_10 9 |
574 | #define GLFW_JOYSTICK_11 10 |
575 | #define GLFW_JOYSTICK_12 11 |
576 | #define GLFW_JOYSTICK_13 12 |
577 | #define GLFW_JOYSTICK_14 13 |
578 | #define GLFW_JOYSTICK_15 14 |
579 | #define GLFW_JOYSTICK_16 15 |
580 | #define GLFW_JOYSTICK_LAST GLFW_JOYSTICK_16 |
581 | /*! @} */ |
582 | |
583 | /*! @defgroup gamepad_buttons Gamepad buttons |
584 | * @brief Gamepad buttons. |
585 | * |
586 | * See @ref gamepad for how these are used. |
587 | * |
588 | * @ingroup input |
589 | * @{ */ |
590 | #define GLFW_GAMEPAD_BUTTON_A 0 |
591 | #define GLFW_GAMEPAD_BUTTON_B 1 |
592 | #define GLFW_GAMEPAD_BUTTON_X 2 |
593 | #define GLFW_GAMEPAD_BUTTON_Y 3 |
594 | #define GLFW_GAMEPAD_BUTTON_LEFT_BUMPER 4 |
595 | #define GLFW_GAMEPAD_BUTTON_RIGHT_BUMPER 5 |
596 | #define GLFW_GAMEPAD_BUTTON_BACK 6 |
597 | #define GLFW_GAMEPAD_BUTTON_START 7 |
598 | #define GLFW_GAMEPAD_BUTTON_GUIDE 8 |
599 | #define GLFW_GAMEPAD_BUTTON_LEFT_THUMB 9 |
600 | #define GLFW_GAMEPAD_BUTTON_RIGHT_THUMB 10 |
601 | #define GLFW_GAMEPAD_BUTTON_DPAD_UP 11 |
602 | #define GLFW_GAMEPAD_BUTTON_DPAD_RIGHT 12 |
603 | #define GLFW_GAMEPAD_BUTTON_DPAD_DOWN 13 |
604 | #define GLFW_GAMEPAD_BUTTON_DPAD_LEFT 14 |
605 | #define GLFW_GAMEPAD_BUTTON_LAST GLFW_GAMEPAD_BUTTON_DPAD_LEFT |
606 | |
607 | #define GLFW_GAMEPAD_BUTTON_CROSS GLFW_GAMEPAD_BUTTON_A |
608 | #define GLFW_GAMEPAD_BUTTON_CIRCLE GLFW_GAMEPAD_BUTTON_B |
609 | #define GLFW_GAMEPAD_BUTTON_SQUARE GLFW_GAMEPAD_BUTTON_X |
610 | #define GLFW_GAMEPAD_BUTTON_TRIANGLE GLFW_GAMEPAD_BUTTON_Y |
611 | /*! @} */ |
612 | |
613 | /*! @defgroup gamepad_axes Gamepad axes |
614 | * @brief Gamepad axes. |
615 | * |
616 | * See @ref gamepad for how these are used. |
617 | * |
618 | * @ingroup input |
619 | * @{ */ |
620 | #define GLFW_GAMEPAD_AXIS_LEFT_X 0 |
621 | #define GLFW_GAMEPAD_AXIS_LEFT_Y 1 |
622 | #define GLFW_GAMEPAD_AXIS_RIGHT_X 2 |
623 | #define GLFW_GAMEPAD_AXIS_RIGHT_Y 3 |
624 | #define GLFW_GAMEPAD_AXIS_LEFT_TRIGGER 4 |
625 | #define GLFW_GAMEPAD_AXIS_RIGHT_TRIGGER 5 |
626 | #define GLFW_GAMEPAD_AXIS_LAST GLFW_GAMEPAD_AXIS_RIGHT_TRIGGER |
627 | /*! @} */ |
628 | |
629 | /*! @defgroup errors Error codes |
630 | * @brief Error codes. |
631 | * |
632 | * See [error handling](@ref error_handling) for how these are used. |
633 | * |
634 | * @ingroup init |
635 | * @{ */ |
636 | /*! @brief No error has occurred. |
637 | * |
638 | * No error has occurred. |
639 | * |
640 | * @analysis Yay. |
641 | */ |
642 | #define GLFW_NO_ERROR 0 |
643 | /*! @brief GLFW has not been initialized. |
644 | * |
645 | * This occurs if a GLFW function was called that must not be called unless the |
646 | * library is [initialized](@ref intro_init). |
647 | * |
648 | * @analysis Application programmer error. Initialize GLFW before calling any |
649 | * function that requires initialization. |
650 | */ |
651 | #define GLFW_NOT_INITIALIZED 0x00010001 |
652 | /*! @brief No context is current for this thread. |
653 | * |
654 | * This occurs if a GLFW function was called that needs and operates on the |
655 | * current OpenGL or OpenGL ES context but no context is current on the calling |
656 | * thread. One such function is @ref glfwSwapInterval. |
657 | * |
658 | * @analysis Application programmer error. Ensure a context is current before |
659 | * calling functions that require a current context. |
660 | */ |
661 | #define GLFW_NO_CURRENT_CONTEXT 0x00010002 |
662 | /*! @brief One of the arguments to the function was an invalid enum value. |
663 | * |
664 | * One of the arguments to the function was an invalid enum value, for example |
665 | * requesting @ref GLFW_RED_BITS with @ref glfwGetWindowAttrib. |
666 | * |
667 | * @analysis Application programmer error. Fix the offending call. |
668 | */ |
669 | #define GLFW_INVALID_ENUM 0x00010003 |
670 | /*! @brief One of the arguments to the function was an invalid value. |
671 | * |
672 | * One of the arguments to the function was an invalid value, for example |
673 | * requesting a non-existent OpenGL or OpenGL ES version like 2.7. |
674 | * |
675 | * Requesting a valid but unavailable OpenGL or OpenGL ES version will instead |
676 | * result in a @ref GLFW_VERSION_UNAVAILABLE error. |
677 | * |
678 | * @analysis Application programmer error. Fix the offending call. |
679 | */ |
680 | #define GLFW_INVALID_VALUE 0x00010004 |
681 | /*! @brief A memory allocation failed. |
682 | * |
683 | * A memory allocation failed. |
684 | * |
685 | * @analysis A bug in GLFW or the underlying operating system. Report the bug |
686 | * to our [issue tracker](https://github.com/glfw/glfw/issues). |
687 | */ |
688 | #define GLFW_OUT_OF_MEMORY 0x00010005 |
689 | /*! @brief GLFW could not find support for the requested API on the system. |
690 | * |
691 | * GLFW could not find support for the requested API on the system. |
692 | * |
693 | * @analysis The installed graphics driver does not support the requested |
694 | * API, or does not support it via the chosen context creation backend. |
695 | * Below are a few examples. |
696 | * |
697 | * @par |
698 | * Some pre-installed Windows graphics drivers do not support OpenGL. AMD only |
699 | * supports OpenGL ES via EGL, while Nvidia and Intel only support it via |
700 | * a WGL or GLX extension. macOS does not provide OpenGL ES at all. The Mesa |
701 | * EGL, OpenGL and OpenGL ES libraries do not interface with the Nvidia binary |
702 | * driver. Older graphics drivers do not support Vulkan. |
703 | */ |
704 | #define GLFW_API_UNAVAILABLE 0x00010006 |
705 | /*! @brief The requested OpenGL or OpenGL ES version is not available. |
706 | * |
707 | * The requested OpenGL or OpenGL ES version (including any requested context |
708 | * or framebuffer hints) is not available on this machine. |
709 | * |
710 | * @analysis The machine does not support your requirements. If your |
711 | * application is sufficiently flexible, downgrade your requirements and try |
712 | * again. Otherwise, inform the user that their machine does not match your |
713 | * requirements. |
714 | * |
715 | * @par |
716 | * Future invalid OpenGL and OpenGL ES versions, for example OpenGL 4.8 if 5.0 |
717 | * comes out before the 4.x series gets that far, also fail with this error and |
718 | * not @ref GLFW_INVALID_VALUE, because GLFW cannot know what future versions |
719 | * will exist. |
720 | */ |
721 | #define GLFW_VERSION_UNAVAILABLE 0x00010007 |
722 | /*! @brief A platform-specific error occurred that does not match any of the |
723 | * more specific categories. |
724 | * |
725 | * A platform-specific error occurred that does not match any of the more |
726 | * specific categories. |
727 | * |
728 | * @analysis A bug or configuration error in GLFW, the underlying operating |
729 | * system or its drivers, or a lack of required resources. Report the issue to |
730 | * our [issue tracker](https://github.com/glfw/glfw/issues). |
731 | */ |
732 | #define GLFW_PLATFORM_ERROR 0x00010008 |
733 | /*! @brief The requested format is not supported or available. |
734 | * |
735 | * If emitted during window creation, the requested pixel format is not |
736 | * supported. |
737 | * |
738 | * If emitted when querying the clipboard, the contents of the clipboard could |
739 | * not be converted to the requested format. |
740 | * |
741 | * @analysis If emitted during window creation, one or more |
742 | * [hard constraints](@ref window_hints_hard) did not match any of the |
743 | * available pixel formats. If your application is sufficiently flexible, |
744 | * downgrade your requirements and try again. Otherwise, inform the user that |
745 | * their machine does not match your requirements. |
746 | * |
747 | * @par |
748 | * If emitted when querying the clipboard, ignore the error or report it to |
749 | * the user, as appropriate. |
750 | */ |
751 | #define GLFW_FORMAT_UNAVAILABLE 0x00010009 |
752 | /*! @brief The specified window does not have an OpenGL or OpenGL ES context. |
753 | * |
754 | * A window that does not have an OpenGL or OpenGL ES context was passed to |
755 | * a function that requires it to have one. |
756 | * |
757 | * @analysis Application programmer error. Fix the offending call. |
758 | */ |
759 | #define GLFW_NO_WINDOW_CONTEXT 0x0001000A |
760 | /*! @brief The specified cursor shape is not available. |
761 | * |
762 | * The specified standard cursor shape is not available, either because the |
763 | * current system cursor theme does not provide it or because it is not |
764 | * available on the platform. |
765 | * |
766 | * @analysis Platform or system settings limitation. Pick another |
767 | * [standard cursor shape](@ref shapes) or create a |
768 | * [custom cursor](@ref cursor_custom). |
769 | */ |
770 | #define GLFW_CURSOR_UNAVAILABLE 0x0001000B |
771 | /*! @} */ |
772 | |
773 | /*! @addtogroup window |
774 | * @{ */ |
775 | /*! @brief Input focus window hint and attribute |
776 | * |
777 | * Input focus [window hint](@ref GLFW_FOCUSED_hint) or |
778 | * [window attribute](@ref GLFW_FOCUSED_attrib). |
779 | */ |
780 | #define GLFW_FOCUSED 0x00020001 |
781 | /*! @brief Window iconification window attribute |
782 | * |
783 | * Window iconification [window attribute](@ref GLFW_ICONIFIED_attrib). |
784 | */ |
785 | #define GLFW_ICONIFIED 0x00020002 |
786 | /*! @brief Window resize-ability window hint and attribute |
787 | * |
788 | * Window resize-ability [window hint](@ref GLFW_RESIZABLE_hint) and |
789 | * [window attribute](@ref GLFW_RESIZABLE_attrib). |
790 | */ |
791 | #define GLFW_RESIZABLE 0x00020003 |
792 | /*! @brief Window visibility window hint and attribute |
793 | * |
794 | * Window visibility [window hint](@ref GLFW_VISIBLE_hint) and |
795 | * [window attribute](@ref GLFW_VISIBLE_attrib). |
796 | */ |
797 | #define GLFW_VISIBLE 0x00020004 |
798 | /*! @brief Window decoration window hint and attribute |
799 | * |
800 | * Window decoration [window hint](@ref GLFW_DECORATED_hint) and |
801 | * [window attribute](@ref GLFW_DECORATED_attrib). |
802 | */ |
803 | #define GLFW_DECORATED 0x00020005 |
804 | /*! @brief Window auto-iconification window hint and attribute |
805 | * |
806 | * Window auto-iconification [window hint](@ref GLFW_AUTO_ICONIFY_hint) and |
807 | * [window attribute](@ref GLFW_AUTO_ICONIFY_attrib). |
808 | */ |
809 | #define GLFW_AUTO_ICONIFY 0x00020006 |
810 | /*! @brief Window decoration window hint and attribute |
811 | * |
812 | * Window decoration [window hint](@ref GLFW_FLOATING_hint) and |
813 | * [window attribute](@ref GLFW_FLOATING_attrib). |
814 | */ |
815 | #define GLFW_FLOATING 0x00020007 |
816 | /*! @brief Window maximization window hint and attribute |
817 | * |
818 | * Window maximization [window hint](@ref GLFW_MAXIMIZED_hint) and |
819 | * [window attribute](@ref GLFW_MAXIMIZED_attrib). |
820 | */ |
821 | #define GLFW_MAXIMIZED 0x00020008 |
822 | /*! @brief Cursor centering window hint |
823 | * |
824 | * Cursor centering [window hint](@ref GLFW_CENTER_CURSOR_hint). |
825 | */ |
826 | #define GLFW_CENTER_CURSOR 0x00020009 |
827 | /*! @brief Window framebuffer transparency hint and attribute |
828 | * |
829 | * Window framebuffer transparency |
830 | * [window hint](@ref GLFW_TRANSPARENT_FRAMEBUFFER_hint) and |
831 | * [window attribute](@ref GLFW_TRANSPARENT_FRAMEBUFFER_attrib). |
832 | */ |
833 | #define GLFW_TRANSPARENT_FRAMEBUFFER 0x0002000A |
834 | /*! @brief Mouse cursor hover window attribute. |
835 | * |
836 | * Mouse cursor hover [window attribute](@ref GLFW_HOVERED_attrib). |
837 | */ |
838 | #define GLFW_HOVERED 0x0002000B |
839 | /*! @brief Input focus on calling show window hint and attribute |
840 | * |
841 | * Input focus [window hint](@ref GLFW_FOCUS_ON_SHOW_hint) or |
842 | * [window attribute](@ref GLFW_FOCUS_ON_SHOW_attrib). |
843 | */ |
844 | #define GLFW_FOCUS_ON_SHOW 0x0002000C |
845 | |
846 | /*! @brief Framebuffer bit depth hint. |
847 | * |
848 | * Framebuffer bit depth [hint](@ref GLFW_RED_BITS). |
849 | */ |
850 | #define GLFW_RED_BITS 0x00021001 |
851 | /*! @brief Framebuffer bit depth hint. |
852 | * |
853 | * Framebuffer bit depth [hint](@ref GLFW_GREEN_BITS). |
854 | */ |
855 | #define GLFW_GREEN_BITS 0x00021002 |
856 | /*! @brief Framebuffer bit depth hint. |
857 | * |
858 | * Framebuffer bit depth [hint](@ref GLFW_BLUE_BITS). |
859 | */ |
860 | #define GLFW_BLUE_BITS 0x00021003 |
861 | /*! @brief Framebuffer bit depth hint. |
862 | * |
863 | * Framebuffer bit depth [hint](@ref GLFW_ALPHA_BITS). |
864 | */ |
865 | #define GLFW_ALPHA_BITS 0x00021004 |
866 | /*! @brief Framebuffer bit depth hint. |
867 | * |
868 | * Framebuffer bit depth [hint](@ref GLFW_DEPTH_BITS). |
869 | */ |
870 | #define GLFW_DEPTH_BITS 0x00021005 |
871 | /*! @brief Framebuffer bit depth hint. |
872 | * |
873 | * Framebuffer bit depth [hint](@ref GLFW_STENCIL_BITS). |
874 | */ |
875 | #define GLFW_STENCIL_BITS 0x00021006 |
876 | /*! @brief Framebuffer bit depth hint. |
877 | * |
878 | * Framebuffer bit depth [hint](@ref GLFW_ACCUM_RED_BITS). |
879 | */ |
880 | #define GLFW_ACCUM_RED_BITS 0x00021007 |
881 | /*! @brief Framebuffer bit depth hint. |
882 | * |
883 | * Framebuffer bit depth [hint](@ref GLFW_ACCUM_GREEN_BITS). |
884 | */ |
885 | #define GLFW_ACCUM_GREEN_BITS 0x00021008 |
886 | /*! @brief Framebuffer bit depth hint. |
887 | * |
888 | * Framebuffer bit depth [hint](@ref GLFW_ACCUM_BLUE_BITS). |
889 | */ |
890 | #define GLFW_ACCUM_BLUE_BITS 0x00021009 |
891 | /*! @brief Framebuffer bit depth hint. |
892 | * |
893 | * Framebuffer bit depth [hint](@ref GLFW_ACCUM_ALPHA_BITS). |
894 | */ |
895 | #define GLFW_ACCUM_ALPHA_BITS 0x0002100A |
896 | /*! @brief Framebuffer auxiliary buffer hint. |
897 | * |
898 | * Framebuffer auxiliary buffer [hint](@ref GLFW_AUX_BUFFERS). |
899 | */ |
900 | #define GLFW_AUX_BUFFERS 0x0002100B |
901 | /*! @brief OpenGL stereoscopic rendering hint. |
902 | * |
903 | * OpenGL stereoscopic rendering [hint](@ref GLFW_STEREO). |
904 | */ |
905 | #define GLFW_STEREO 0x0002100C |
906 | /*! @brief Framebuffer MSAA samples hint. |
907 | * |
908 | * Framebuffer MSAA samples [hint](@ref GLFW_SAMPLES). |
909 | */ |
910 | #define GLFW_SAMPLES 0x0002100D |
911 | /*! @brief Framebuffer sRGB hint. |
912 | * |
913 | * Framebuffer sRGB [hint](@ref GLFW_SRGB_CAPABLE). |
914 | */ |
915 | #define GLFW_SRGB_CAPABLE 0x0002100E |
916 | /*! @brief Monitor refresh rate hint. |
917 | * |
918 | * Monitor refresh rate [hint](@ref GLFW_REFRESH_RATE). |
919 | */ |
920 | #define GLFW_REFRESH_RATE 0x0002100F |
921 | /*! @brief Framebuffer double buffering hint. |
922 | * |
923 | * Framebuffer double buffering [hint](@ref GLFW_DOUBLEBUFFER). |
924 | */ |
925 | #define GLFW_DOUBLEBUFFER 0x00021010 |
926 | |
927 | /*! @brief Context client API hint and attribute. |
928 | * |
929 | * Context client API [hint](@ref GLFW_CLIENT_API_hint) and |
930 | * [attribute](@ref GLFW_CLIENT_API_attrib). |
931 | */ |
932 | #define GLFW_CLIENT_API 0x00022001 |
933 | /*! @brief Context client API major version hint and attribute. |
934 | * |
935 | * Context client API major version [hint](@ref GLFW_CONTEXT_VERSION_MAJOR_hint) |
936 | * and [attribute](@ref GLFW_CONTEXT_VERSION_MAJOR_attrib). |
937 | */ |
938 | #define GLFW_CONTEXT_VERSION_MAJOR 0x00022002 |
939 | /*! @brief Context client API minor version hint and attribute. |
940 | * |
941 | * Context client API minor version [hint](@ref GLFW_CONTEXT_VERSION_MINOR_hint) |
942 | * and [attribute](@ref GLFW_CONTEXT_VERSION_MINOR_attrib). |
943 | */ |
944 | #define GLFW_CONTEXT_VERSION_MINOR 0x00022003 |
945 | /*! @brief Context client API revision number hint and attribute. |
946 | * |
947 | * Context client API revision number |
948 | * [attribute](@ref GLFW_CONTEXT_REVISION_attrib). |
949 | */ |
950 | #define GLFW_CONTEXT_REVISION 0x00022004 |
951 | /*! @brief Context robustness hint and attribute. |
952 | * |
953 | * Context client API revision number [hint](@ref GLFW_CONTEXT_ROBUSTNESS_hint) |
954 | * and [attribute](@ref GLFW_CONTEXT_ROBUSTNESS_attrib). |
955 | */ |
956 | #define GLFW_CONTEXT_ROBUSTNESS 0x00022005 |
957 | /*! @brief OpenGL forward-compatibility hint and attribute. |
958 | * |
959 | * OpenGL forward-compatibility [hint](@ref GLFW_OPENGL_FORWARD_COMPAT_hint) |
960 | * and [attribute](@ref GLFW_OPENGL_FORWARD_COMPAT_attrib). |
961 | */ |
962 | #define GLFW_OPENGL_FORWARD_COMPAT 0x00022006 |
963 | /*! @brief OpenGL debug context hint and attribute. |
964 | * |
965 | * OpenGL debug context [hint](@ref GLFW_OPENGL_DEBUG_CONTEXT_hint) and |
966 | * [attribute](@ref GLFW_OPENGL_DEBUG_CONTEXT_attrib). |
967 | */ |
968 | #define GLFW_OPENGL_DEBUG_CONTEXT 0x00022007 |
969 | /*! @brief OpenGL profile hint and attribute. |
970 | * |
971 | * OpenGL profile [hint](@ref GLFW_OPENGL_PROFILE_hint) and |
972 | * [attribute](@ref GLFW_OPENGL_PROFILE_attrib). |
973 | */ |
974 | #define GLFW_OPENGL_PROFILE 0x00022008 |
975 | /*! @brief Context flush-on-release hint and attribute. |
976 | * |
977 | * Context flush-on-release [hint](@ref GLFW_CONTEXT_RELEASE_BEHAVIOR_hint) and |
978 | * [attribute](@ref GLFW_CONTEXT_RELEASE_BEHAVIOR_attrib). |
979 | */ |
980 | #define GLFW_CONTEXT_RELEASE_BEHAVIOR 0x00022009 |
981 | /*! @brief Context error suppression hint and attribute. |
982 | * |
983 | * Context error suppression [hint](@ref GLFW_CONTEXT_NO_ERROR_hint) and |
984 | * [attribute](@ref GLFW_CONTEXT_NO_ERROR_attrib). |
985 | */ |
986 | #define GLFW_CONTEXT_NO_ERROR 0x0002200A |
987 | /*! @brief Context creation API hint and attribute. |
988 | * |
989 | * Context creation API [hint](@ref GLFW_CONTEXT_CREATION_API_hint) and |
990 | * [attribute](@ref GLFW_CONTEXT_CREATION_API_attrib). |
991 | */ |
992 | #define GLFW_CONTEXT_CREATION_API 0x0002200B |
993 | /*! @brief Window content area scaling window |
994 | * [window hint](@ref GLFW_SCALE_TO_MONITOR). |
995 | */ |
996 | #define GLFW_SCALE_TO_MONITOR 0x0002200C |
997 | /*! @brief macOS specific |
998 | * [window hint](@ref GLFW_COCOA_RETINA_FRAMEBUFFER_hint). |
999 | */ |
1000 | #define GLFW_COCOA_RETINA_FRAMEBUFFER 0x00023001 |
1001 | /*! @brief macOS specific |
1002 | * [window hint](@ref GLFW_COCOA_FRAME_NAME_hint). |
1003 | */ |
1004 | #define GLFW_COCOA_FRAME_NAME 0x00023002 |
1005 | /*! @brief macOS specific |
1006 | * [window hint](@ref GLFW_COCOA_GRAPHICS_SWITCHING_hint). |
1007 | */ |
1008 | #define GLFW_COCOA_GRAPHICS_SWITCHING 0x00023003 |
1009 | /*! @brief X11 specific |
1010 | * [window hint](@ref GLFW_X11_CLASS_NAME_hint). |
1011 | */ |
1012 | #define GLFW_X11_CLASS_NAME 0x00024001 |
1013 | /*! @brief X11 specific |
1014 | * [window hint](@ref GLFW_X11_CLASS_NAME_hint). |
1015 | */ |
1016 | #define GLFW_X11_INSTANCE_NAME 0x00024002 |
1017 | #define 0x00025001 |
1018 | /*! @} */ |
1019 | |
1020 | #define GLFW_NO_API 0 |
1021 | #define GLFW_OPENGL_API 0x00030001 |
1022 | #define GLFW_OPENGL_ES_API 0x00030002 |
1023 | |
1024 | #define GLFW_NO_ROBUSTNESS 0 |
1025 | #define GLFW_NO_RESET_NOTIFICATION 0x00031001 |
1026 | #define GLFW_LOSE_CONTEXT_ON_RESET 0x00031002 |
1027 | |
1028 | #define GLFW_OPENGL_ANY_PROFILE 0 |
1029 | #define GLFW_OPENGL_CORE_PROFILE 0x00032001 |
1030 | #define GLFW_OPENGL_COMPAT_PROFILE 0x00032002 |
1031 | |
1032 | #define GLFW_CURSOR 0x00033001 |
1033 | #define GLFW_STICKY_KEYS 0x00033002 |
1034 | #define GLFW_STICKY_MOUSE_BUTTONS 0x00033003 |
1035 | #define GLFW_LOCK_KEY_MODS 0x00033004 |
1036 | #define GLFW_RAW_MOUSE_MOTION 0x00033005 |
1037 | |
1038 | #define GLFW_CURSOR_NORMAL 0x00034001 |
1039 | #define GLFW_CURSOR_HIDDEN 0x00034002 |
1040 | #define GLFW_CURSOR_DISABLED 0x00034003 |
1041 | |
1042 | #define GLFW_ANY_RELEASE_BEHAVIOR 0 |
1043 | #define GLFW_RELEASE_BEHAVIOR_FLUSH 0x00035001 |
1044 | #define GLFW_RELEASE_BEHAVIOR_NONE 0x00035002 |
1045 | |
1046 | #define GLFW_NATIVE_CONTEXT_API 0x00036001 |
1047 | #define GLFW_EGL_CONTEXT_API 0x00036002 |
1048 | #define GLFW_OSMESA_CONTEXT_API 0x00036003 |
1049 | |
1050 | /*! @defgroup shapes Standard cursor shapes |
1051 | * @brief Standard system cursor shapes. |
1052 | * |
1053 | * These are the [standard cursor shapes](@ref cursor_standard) that can be |
1054 | * requested from the window system. |
1055 | * |
1056 | * @ingroup input |
1057 | * @{ */ |
1058 | |
1059 | /*! @brief The regular arrow cursor shape. |
1060 | * |
1061 | * The regular arrow cursor shape. |
1062 | */ |
1063 | #define GLFW_ARROW_CURSOR 0x00036001 |
1064 | /*! @brief The text input I-beam cursor shape. |
1065 | * |
1066 | * The text input I-beam cursor shape. |
1067 | */ |
1068 | #define GLFW_IBEAM_CURSOR 0x00036002 |
1069 | /*! @brief The crosshair cursor shape. |
1070 | * |
1071 | * The crosshair cursor shape. |
1072 | */ |
1073 | #define GLFW_CROSSHAIR_CURSOR 0x00036003 |
1074 | /*! @brief The pointing hand cursor shape. |
1075 | * |
1076 | * The pointing hand cursor shape. |
1077 | */ |
1078 | #define GLFW_POINTING_HAND_CURSOR 0x00036004 |
1079 | /*! @brief The horizontal resize/move arrow shape. |
1080 | * |
1081 | * The horizontal resize/move arrow shape. This is usually a horizontal |
1082 | * double-headed arrow. |
1083 | */ |
1084 | #define GLFW_RESIZE_EW_CURSOR 0x00036005 |
1085 | /*! @brief The vertical resize/move arrow shape. |
1086 | * |
1087 | * The vertical resize/move shape. This is usually a vertical double-headed |
1088 | * arrow. |
1089 | */ |
1090 | #define GLFW_RESIZE_NS_CURSOR 0x00036006 |
1091 | /*! @brief The top-left to bottom-right diagonal resize/move arrow shape. |
1092 | * |
1093 | * The top-left to bottom-right diagonal resize/move shape. This is usually |
1094 | * a diagonal double-headed arrow. |
1095 | * |
1096 | * @note @macos This shape is provided by a private system API and may fail |
1097 | * with @ref GLFW_CURSOR_UNAVAILABLE in the future. |
1098 | * |
1099 | * @note @x11 This shape is provided by a newer standard not supported by all |
1100 | * cursor themes. |
1101 | * |
1102 | * @note @wayland This shape is provided by a newer standard not supported by |
1103 | * all cursor themes. |
1104 | */ |
1105 | #define GLFW_RESIZE_NWSE_CURSOR 0x00036007 |
1106 | /*! @brief The top-right to bottom-left diagonal resize/move arrow shape. |
1107 | * |
1108 | * The top-right to bottom-left diagonal resize/move shape. This is usually |
1109 | * a diagonal double-headed arrow. |
1110 | * |
1111 | * @note @macos This shape is provided by a private system API and may fail |
1112 | * with @ref GLFW_CURSOR_UNAVAILABLE in the future. |
1113 | * |
1114 | * @note @x11 This shape is provided by a newer standard not supported by all |
1115 | * cursor themes. |
1116 | * |
1117 | * @note @wayland This shape is provided by a newer standard not supported by |
1118 | * all cursor themes. |
1119 | */ |
1120 | #define GLFW_RESIZE_NESW_CURSOR 0x00036008 |
1121 | /*! @brief The omni-directional resize/move cursor shape. |
1122 | * |
1123 | * The omni-directional resize cursor/move shape. This is usually either |
1124 | * a combined horizontal and vertical double-headed arrow or a grabbing hand. |
1125 | */ |
1126 | #define GLFW_RESIZE_ALL_CURSOR 0x00036009 |
1127 | /*! @brief The operation-not-allowed shape. |
1128 | * |
1129 | * The operation-not-allowed shape. This is usually a circle with a diagonal |
1130 | * line through it. |
1131 | * |
1132 | * @note @x11 This shape is provided by a newer standard not supported by all |
1133 | * cursor themes. |
1134 | * |
1135 | * @note @wayland This shape is provided by a newer standard not supported by |
1136 | * all cursor themes. |
1137 | */ |
1138 | #define GLFW_NOT_ALLOWED_CURSOR 0x0003600A |
1139 | /*! @brief Legacy name for compatibility. |
1140 | * |
1141 | * This is an alias for compatibility with earlier versions. |
1142 | */ |
1143 | #define GLFW_HRESIZE_CURSOR GLFW_RESIZE_EW_CURSOR |
1144 | /*! @brief Legacy name for compatibility. |
1145 | * |
1146 | * This is an alias for compatibility with earlier versions. |
1147 | */ |
1148 | #define GLFW_VRESIZE_CURSOR GLFW_RESIZE_NS_CURSOR |
1149 | /*! @brief Legacy name for compatibility. |
1150 | * |
1151 | * This is an alias for compatibility with earlier versions. |
1152 | */ |
1153 | #define GLFW_HAND_CURSOR GLFW_POINTING_HAND_CURSOR |
1154 | /*! @} */ |
1155 | |
1156 | #define GLFW_CONNECTED 0x00040001 |
1157 | #define GLFW_DISCONNECTED 0x00040002 |
1158 | |
1159 | /*! @addtogroup init |
1160 | * @{ */ |
1161 | /*! @brief Joystick hat buttons init hint. |
1162 | * |
1163 | * Joystick hat buttons [init hint](@ref GLFW_JOYSTICK_HAT_BUTTONS). |
1164 | */ |
1165 | #define GLFW_JOYSTICK_HAT_BUTTONS 0x00050001 |
1166 | /*! @brief macOS specific init hint. |
1167 | * |
1168 | * macOS specific [init hint](@ref GLFW_COCOA_CHDIR_RESOURCES_hint). |
1169 | */ |
1170 | #define GLFW_COCOA_CHDIR_RESOURCES 0x00051001 |
1171 | /*! @brief macOS specific init hint. |
1172 | * |
1173 | * macOS specific [init hint](@ref GLFW_COCOA_MENUBAR_hint). |
1174 | */ |
1175 | #define 0x00051002 |
1176 | /*! @} */ |
1177 | |
1178 | #define GLFW_DONT_CARE -1 |
1179 | |
1180 | |
1181 | /************************************************************************* |
1182 | * GLFW API types |
1183 | *************************************************************************/ |
1184 | |
1185 | /*! @brief Client API function pointer type. |
1186 | * |
1187 | * Generic function pointer used for returning client API function pointers |
1188 | * without forcing a cast from a regular pointer. |
1189 | * |
1190 | * @sa @ref context_glext |
1191 | * @sa @ref glfwGetProcAddress |
1192 | * |
1193 | * @since Added in version 3.0. |
1194 | * |
1195 | * @ingroup context |
1196 | */ |
1197 | typedef void (*GLFWglproc)(void); |
1198 | |
1199 | /*! @brief Vulkan API function pointer type. |
1200 | * |
1201 | * Generic function pointer used for returning Vulkan API function pointers |
1202 | * without forcing a cast from a regular pointer. |
1203 | * |
1204 | * @sa @ref vulkan_proc |
1205 | * @sa @ref glfwGetInstanceProcAddress |
1206 | * |
1207 | * @since Added in version 3.2. |
1208 | * |
1209 | * @ingroup vulkan |
1210 | */ |
1211 | typedef void (*GLFWvkproc)(void); |
1212 | |
1213 | /*! @brief Opaque monitor object. |
1214 | * |
1215 | * Opaque monitor object. |
1216 | * |
1217 | * @see @ref monitor_object |
1218 | * |
1219 | * @since Added in version 3.0. |
1220 | * |
1221 | * @ingroup monitor |
1222 | */ |
1223 | typedef struct GLFWmonitor GLFWmonitor; |
1224 | |
1225 | /*! @brief Opaque window object. |
1226 | * |
1227 | * Opaque window object. |
1228 | * |
1229 | * @see @ref window_object |
1230 | * |
1231 | * @since Added in version 3.0. |
1232 | * |
1233 | * @ingroup window |
1234 | */ |
1235 | typedef struct GLFWwindow GLFWwindow; |
1236 | |
1237 | /*! @brief Opaque cursor object. |
1238 | * |
1239 | * Opaque cursor object. |
1240 | * |
1241 | * @see @ref cursor_object |
1242 | * |
1243 | * @since Added in version 3.1. |
1244 | * |
1245 | * @ingroup input |
1246 | */ |
1247 | typedef struct GLFWcursor GLFWcursor; |
1248 | |
1249 | /*! @brief The function pointer type for error callbacks. |
1250 | * |
1251 | * This is the function pointer type for error callbacks. An error callback |
1252 | * function has the following signature: |
1253 | * @code |
1254 | * void callback_name(int error_code, const char* description) |
1255 | * @endcode |
1256 | * |
1257 | * @param[in] error_code An [error code](@ref errors). Future releases may add |
1258 | * more error codes. |
1259 | * @param[in] description A UTF-8 encoded string describing the error. |
1260 | * |
1261 | * @pointer_lifetime The error description string is valid until the callback |
1262 | * function returns. |
1263 | * |
1264 | * @sa @ref error_handling |
1265 | * @sa @ref glfwSetErrorCallback |
1266 | * |
1267 | * @since Added in version 3.0. |
1268 | * |
1269 | * @ingroup init |
1270 | */ |
1271 | typedef void (* GLFWerrorfun)(int,const char*); |
1272 | |
1273 | /*! @brief The function pointer type for window position callbacks. |
1274 | * |
1275 | * This is the function pointer type for window position callbacks. A window |
1276 | * position callback function has the following signature: |
1277 | * @code |
1278 | * void callback_name(GLFWwindow* window, int xpos, int ypos) |
1279 | * @endcode |
1280 | * |
1281 | * @param[in] window The window that was moved. |
1282 | * @param[in] xpos The new x-coordinate, in screen coordinates, of the |
1283 | * upper-left corner of the content area of the window. |
1284 | * @param[in] ypos The new y-coordinate, in screen coordinates, of the |
1285 | * upper-left corner of the content area of the window. |
1286 | * |
1287 | * @sa @ref window_pos |
1288 | * @sa @ref glfwSetWindowPosCallback |
1289 | * |
1290 | * @since Added in version 3.0. |
1291 | * |
1292 | * @ingroup window |
1293 | */ |
1294 | typedef void (* GLFWwindowposfun)(GLFWwindow*,int,int); |
1295 | |
1296 | /*! @brief The function pointer type for window size callbacks. |
1297 | * |
1298 | * This is the function pointer type for window size callbacks. A window size |
1299 | * callback function has the following signature: |
1300 | * @code |
1301 | * void callback_name(GLFWwindow* window, int width, int height) |
1302 | * @endcode |
1303 | * |
1304 | * @param[in] window The window that was resized. |
1305 | * @param[in] width The new width, in screen coordinates, of the window. |
1306 | * @param[in] height The new height, in screen coordinates, of the window. |
1307 | * |
1308 | * @sa @ref window_size |
1309 | * @sa @ref glfwSetWindowSizeCallback |
1310 | * |
1311 | * @since Added in version 1.0. |
1312 | * @glfw3 Added window handle parameter. |
1313 | * |
1314 | * @ingroup window |
1315 | */ |
1316 | typedef void (* GLFWwindowsizefun)(GLFWwindow*,int,int); |
1317 | |
1318 | /*! @brief The function pointer type for window close callbacks. |
1319 | * |
1320 | * This is the function pointer type for window close callbacks. A window |
1321 | * close callback function has the following signature: |
1322 | * @code |
1323 | * void function_name(GLFWwindow* window) |
1324 | * @endcode |
1325 | * |
1326 | * @param[in] window The window that the user attempted to close. |
1327 | * |
1328 | * @sa @ref window_close |
1329 | * @sa @ref glfwSetWindowCloseCallback |
1330 | * |
1331 | * @since Added in version 2.5. |
1332 | * @glfw3 Added window handle parameter. |
1333 | * |
1334 | * @ingroup window |
1335 | */ |
1336 | typedef void (* GLFWwindowclosefun)(GLFWwindow*); |
1337 | |
1338 | /*! @brief The function pointer type for window content refresh callbacks. |
1339 | * |
1340 | * This is the function pointer type for window content refresh callbacks. |
1341 | * A window content refresh callback function has the following signature: |
1342 | * @code |
1343 | * void function_name(GLFWwindow* window); |
1344 | * @endcode |
1345 | * |
1346 | * @param[in] window The window whose content needs to be refreshed. |
1347 | * |
1348 | * @sa @ref window_refresh |
1349 | * @sa @ref glfwSetWindowRefreshCallback |
1350 | * |
1351 | * @since Added in version 2.5. |
1352 | * @glfw3 Added window handle parameter. |
1353 | * |
1354 | * @ingroup window |
1355 | */ |
1356 | typedef void (* GLFWwindowrefreshfun)(GLFWwindow*); |
1357 | |
1358 | /*! @brief The function pointer type for window focus callbacks. |
1359 | * |
1360 | * This is the function pointer type for window focus callbacks. A window |
1361 | * focus callback function has the following signature: |
1362 | * @code |
1363 | * void function_name(GLFWwindow* window, int focused) |
1364 | * @endcode |
1365 | * |
1366 | * @param[in] window The window that gained or lost input focus. |
1367 | * @param[in] focused `GLFW_TRUE` if the window was given input focus, or |
1368 | * `GLFW_FALSE` if it lost it. |
1369 | * |
1370 | * @sa @ref window_focus |
1371 | * @sa @ref glfwSetWindowFocusCallback |
1372 | * |
1373 | * @since Added in version 3.0. |
1374 | * |
1375 | * @ingroup window |
1376 | */ |
1377 | typedef void (* GLFWwindowfocusfun)(GLFWwindow*,int); |
1378 | |
1379 | /*! @brief The function pointer type for window iconify callbacks. |
1380 | * |
1381 | * This is the function pointer type for window iconify callbacks. A window |
1382 | * iconify callback function has the following signature: |
1383 | * @code |
1384 | * void function_name(GLFWwindow* window, int iconified) |
1385 | * @endcode |
1386 | * |
1387 | * @param[in] window The window that was iconified or restored. |
1388 | * @param[in] iconified `GLFW_TRUE` if the window was iconified, or |
1389 | * `GLFW_FALSE` if it was restored. |
1390 | * |
1391 | * @sa @ref window_iconify |
1392 | * @sa @ref glfwSetWindowIconifyCallback |
1393 | * |
1394 | * @since Added in version 3.0. |
1395 | * |
1396 | * @ingroup window |
1397 | */ |
1398 | typedef void (* GLFWwindowiconifyfun)(GLFWwindow*,int); |
1399 | |
1400 | /*! @brief The function pointer type for window maximize callbacks. |
1401 | * |
1402 | * This is the function pointer type for window maximize callbacks. A window |
1403 | * maximize callback function has the following signature: |
1404 | * @code |
1405 | * void function_name(GLFWwindow* window, int maximized) |
1406 | * @endcode |
1407 | * |
1408 | * @param[in] window The window that was maximized or restored. |
1409 | * @param[in] iconified `GLFW_TRUE` if the window was maximized, or |
1410 | * `GLFW_FALSE` if it was restored. |
1411 | * |
1412 | * @sa @ref window_maximize |
1413 | * @sa glfwSetWindowMaximizeCallback |
1414 | * |
1415 | * @since Added in version 3.3. |
1416 | * |
1417 | * @ingroup window |
1418 | */ |
1419 | typedef void (* GLFWwindowmaximizefun)(GLFWwindow*,int); |
1420 | |
1421 | /*! @brief The function pointer type for framebuffer size callbacks. |
1422 | * |
1423 | * This is the function pointer type for framebuffer size callbacks. |
1424 | * A framebuffer size callback function has the following signature: |
1425 | * @code |
1426 | * void function_name(GLFWwindow* window, int width, int height) |
1427 | * @endcode |
1428 | * |
1429 | * @param[in] window The window whose framebuffer was resized. |
1430 | * @param[in] width The new width, in pixels, of the framebuffer. |
1431 | * @param[in] height The new height, in pixels, of the framebuffer. |
1432 | * |
1433 | * @sa @ref window_fbsize |
1434 | * @sa @ref glfwSetFramebufferSizeCallback |
1435 | * |
1436 | * @since Added in version 3.0. |
1437 | * |
1438 | * @ingroup window |
1439 | */ |
1440 | typedef void (* GLFWframebuffersizefun)(GLFWwindow*,int,int); |
1441 | |
1442 | /*! @brief The function pointer type for window content scale callbacks. |
1443 | * |
1444 | * This is the function pointer type for window content scale callbacks. |
1445 | * A window content scale callback function has the following signature: |
1446 | * @code |
1447 | * void function_name(GLFWwindow* window, float xscale, float yscale) |
1448 | * @endcode |
1449 | * |
1450 | * @param[in] window The window whose content scale changed. |
1451 | * @param[in] xscale The new x-axis content scale of the window. |
1452 | * @param[in] yscale The new y-axis content scale of the window. |
1453 | * |
1454 | * @sa @ref window_scale |
1455 | * @sa @ref glfwSetWindowContentScaleCallback |
1456 | * |
1457 | * @since Added in version 3.3. |
1458 | * |
1459 | * @ingroup window |
1460 | */ |
1461 | typedef void (* GLFWwindowcontentscalefun)(GLFWwindow*,float,float); |
1462 | |
1463 | /*! @brief The function pointer type for mouse button callbacks. |
1464 | * |
1465 | * This is the function pointer type for mouse button callback functions. |
1466 | * A mouse button callback function has the following signature: |
1467 | * @code |
1468 | * void function_name(GLFWwindow* window, int button, int action, int mods) |
1469 | * @endcode |
1470 | * |
1471 | * @param[in] window The window that received the event. |
1472 | * @param[in] button The [mouse button](@ref buttons) that was pressed or |
1473 | * released. |
1474 | * @param[in] action One of `GLFW_PRESS` or `GLFW_RELEASE`. Future releases |
1475 | * may add more actions. |
1476 | * @param[in] mods Bit field describing which [modifier keys](@ref mods) were |
1477 | * held down. |
1478 | * |
1479 | * @sa @ref input_mouse_button |
1480 | * @sa @ref glfwSetMouseButtonCallback |
1481 | * |
1482 | * @since Added in version 1.0. |
1483 | * @glfw3 Added window handle and modifier mask parameters. |
1484 | * |
1485 | * @ingroup input |
1486 | */ |
1487 | typedef void (* GLFWmousebuttonfun)(GLFWwindow*,int,int,int); |
1488 | |
1489 | /*! @brief The function pointer type for cursor position callbacks. |
1490 | * |
1491 | * This is the function pointer type for cursor position callbacks. A cursor |
1492 | * position callback function has the following signature: |
1493 | * @code |
1494 | * void function_name(GLFWwindow* window, double xpos, double ypos); |
1495 | * @endcode |
1496 | * |
1497 | * @param[in] window The window that received the event. |
1498 | * @param[in] xpos The new cursor x-coordinate, relative to the left edge of |
1499 | * the content area. |
1500 | * @param[in] ypos The new cursor y-coordinate, relative to the top edge of the |
1501 | * content area. |
1502 | * |
1503 | * @sa @ref cursor_pos |
1504 | * @sa @ref glfwSetCursorPosCallback |
1505 | * |
1506 | * @since Added in version 3.0. Replaces `GLFWmouseposfun`. |
1507 | * |
1508 | * @ingroup input |
1509 | */ |
1510 | typedef void (* GLFWcursorposfun)(GLFWwindow*,double,double); |
1511 | |
1512 | /*! @brief The function pointer type for cursor enter/leave callbacks. |
1513 | * |
1514 | * This is the function pointer type for cursor enter/leave callbacks. |
1515 | * A cursor enter/leave callback function has the following signature: |
1516 | * @code |
1517 | * void function_name(GLFWwindow* window, int entered) |
1518 | * @endcode |
1519 | * |
1520 | * @param[in] window The window that received the event. |
1521 | * @param[in] entered `GLFW_TRUE` if the cursor entered the window's content |
1522 | * area, or `GLFW_FALSE` if it left it. |
1523 | * |
1524 | * @sa @ref cursor_enter |
1525 | * @sa @ref glfwSetCursorEnterCallback |
1526 | * |
1527 | * @since Added in version 3.0. |
1528 | * |
1529 | * @ingroup input |
1530 | */ |
1531 | typedef void (* GLFWcursorenterfun)(GLFWwindow*,int); |
1532 | |
1533 | /*! @brief The function pointer type for scroll callbacks. |
1534 | * |
1535 | * This is the function pointer type for scroll callbacks. A scroll callback |
1536 | * function has the following signature: |
1537 | * @code |
1538 | * void function_name(GLFWwindow* window, double xoffset, double yoffset) |
1539 | * @endcode |
1540 | * |
1541 | * @param[in] window The window that received the event. |
1542 | * @param[in] xoffset The scroll offset along the x-axis. |
1543 | * @param[in] yoffset The scroll offset along the y-axis. |
1544 | * |
1545 | * @sa @ref scrolling |
1546 | * @sa @ref glfwSetScrollCallback |
1547 | * |
1548 | * @since Added in version 3.0. Replaces `GLFWmousewheelfun`. |
1549 | * |
1550 | * @ingroup input |
1551 | */ |
1552 | typedef void (* GLFWscrollfun)(GLFWwindow*,double,double); |
1553 | |
1554 | /*! @brief The function pointer type for keyboard key callbacks. |
1555 | * |
1556 | * This is the function pointer type for keyboard key callbacks. A keyboard |
1557 | * key callback function has the following signature: |
1558 | * @code |
1559 | * void function_name(GLFWwindow* window, int key, int scancode, int action, int mods) |
1560 | * @endcode |
1561 | * |
1562 | * @param[in] window The window that received the event. |
1563 | * @param[in] key The [keyboard key](@ref keys) that was pressed or released. |
1564 | * @param[in] scancode The system-specific scancode of the key. |
1565 | * @param[in] action `GLFW_PRESS`, `GLFW_RELEASE` or `GLFW_REPEAT`. Future |
1566 | * releases may add more actions. |
1567 | * @param[in] mods Bit field describing which [modifier keys](@ref mods) were |
1568 | * held down. |
1569 | * |
1570 | * @sa @ref input_key |
1571 | * @sa @ref glfwSetKeyCallback |
1572 | * |
1573 | * @since Added in version 1.0. |
1574 | * @glfw3 Added window handle, scancode and modifier mask parameters. |
1575 | * |
1576 | * @ingroup input |
1577 | */ |
1578 | typedef void (* GLFWkeyfun)(GLFWwindow*,int,int,int,int); |
1579 | |
1580 | /*! @brief The function pointer type for Unicode character callbacks. |
1581 | * |
1582 | * This is the function pointer type for Unicode character callbacks. |
1583 | * A Unicode character callback function has the following signature: |
1584 | * @code |
1585 | * void function_name(GLFWwindow* window, unsigned int codepoint) |
1586 | * @endcode |
1587 | * |
1588 | * @param[in] window The window that received the event. |
1589 | * @param[in] codepoint The Unicode code point of the character. |
1590 | * |
1591 | * @sa @ref input_char |
1592 | * @sa @ref glfwSetCharCallback |
1593 | * |
1594 | * @since Added in version 2.4. |
1595 | * @glfw3 Added window handle parameter. |
1596 | * |
1597 | * @ingroup input |
1598 | */ |
1599 | typedef void (* GLFWcharfun)(GLFWwindow*,unsigned int); |
1600 | |
1601 | /*! @brief The function pointer type for Unicode character with modifiers |
1602 | * callbacks. |
1603 | * |
1604 | * This is the function pointer type for Unicode character with modifiers |
1605 | * callbacks. It is called for each input character, regardless of what |
1606 | * modifier keys are held down. A Unicode character with modifiers callback |
1607 | * function has the following signature: |
1608 | * @code |
1609 | * void function_name(GLFWwindow* window, unsigned int codepoint, int mods) |
1610 | * @endcode |
1611 | * |
1612 | * @param[in] window The window that received the event. |
1613 | * @param[in] codepoint The Unicode code point of the character. |
1614 | * @param[in] mods Bit field describing which [modifier keys](@ref mods) were |
1615 | * held down. |
1616 | * |
1617 | * @sa @ref input_char |
1618 | * @sa @ref glfwSetCharModsCallback |
1619 | * |
1620 | * @deprecated Scheduled for removal in version 4.0. |
1621 | * |
1622 | * @since Added in version 3.1. |
1623 | * |
1624 | * @ingroup input |
1625 | */ |
1626 | typedef void (* GLFWcharmodsfun)(GLFWwindow*,unsigned int,int); |
1627 | |
1628 | /*! @brief The function pointer type for path drop callbacks. |
1629 | * |
1630 | * This is the function pointer type for path drop callbacks. A path drop |
1631 | * callback function has the following signature: |
1632 | * @code |
1633 | * void function_name(GLFWwindow* window, int path_count, const char* paths[]) |
1634 | * @endcode |
1635 | * |
1636 | * @param[in] window The window that received the event. |
1637 | * @param[in] path_count The number of dropped paths. |
1638 | * @param[in] paths The UTF-8 encoded file and/or directory path names. |
1639 | * |
1640 | * @pointer_lifetime The path array and its strings are valid until the |
1641 | * callback function returns. |
1642 | * |
1643 | * @sa @ref path_drop |
1644 | * @sa @ref glfwSetDropCallback |
1645 | * |
1646 | * @since Added in version 3.1. |
1647 | * |
1648 | * @ingroup input |
1649 | */ |
1650 | typedef void (* GLFWdropfun)(GLFWwindow*,int,const char*[]); |
1651 | |
1652 | /*! @brief The function pointer type for monitor configuration callbacks. |
1653 | * |
1654 | * This is the function pointer type for monitor configuration callbacks. |
1655 | * A monitor callback function has the following signature: |
1656 | * @code |
1657 | * void function_name(GLFWmonitor* monitor, int event) |
1658 | * @endcode |
1659 | * |
1660 | * @param[in] monitor The monitor that was connected or disconnected. |
1661 | * @param[in] event One of `GLFW_CONNECTED` or `GLFW_DISCONNECTED`. Future |
1662 | * releases may add more events. |
1663 | * |
1664 | * @sa @ref monitor_event |
1665 | * @sa @ref glfwSetMonitorCallback |
1666 | * |
1667 | * @since Added in version 3.0. |
1668 | * |
1669 | * @ingroup monitor |
1670 | */ |
1671 | typedef void (* GLFWmonitorfun)(GLFWmonitor*,int); |
1672 | |
1673 | /*! @brief The function pointer type for joystick configuration callbacks. |
1674 | * |
1675 | * This is the function pointer type for joystick configuration callbacks. |
1676 | * A joystick configuration callback function has the following signature: |
1677 | * @code |
1678 | * void function_name(int jid, int event) |
1679 | * @endcode |
1680 | * |
1681 | * @param[in] jid The joystick that was connected or disconnected. |
1682 | * @param[in] event One of `GLFW_CONNECTED` or `GLFW_DISCONNECTED`. Future |
1683 | * releases may add more events. |
1684 | * |
1685 | * @sa @ref joystick_event |
1686 | * @sa @ref glfwSetJoystickCallback |
1687 | * |
1688 | * @since Added in version 3.2. |
1689 | * |
1690 | * @ingroup input |
1691 | */ |
1692 | typedef void (* GLFWjoystickfun)(int,int); |
1693 | |
1694 | /*! @brief Video mode type. |
1695 | * |
1696 | * This describes a single video mode. |
1697 | * |
1698 | * @sa @ref monitor_modes |
1699 | * @sa @ref glfwGetVideoMode |
1700 | * @sa @ref glfwGetVideoModes |
1701 | * |
1702 | * @since Added in version 1.0. |
1703 | * @glfw3 Added refresh rate member. |
1704 | * |
1705 | * @ingroup monitor |
1706 | */ |
1707 | typedef struct GLFWvidmode |
1708 | { |
1709 | /*! The width, in screen coordinates, of the video mode. |
1710 | */ |
1711 | int width; |
1712 | /*! The height, in screen coordinates, of the video mode. |
1713 | */ |
1714 | int height; |
1715 | /*! The bit depth of the red channel of the video mode. |
1716 | */ |
1717 | int redBits; |
1718 | /*! The bit depth of the green channel of the video mode. |
1719 | */ |
1720 | int greenBits; |
1721 | /*! The bit depth of the blue channel of the video mode. |
1722 | */ |
1723 | int blueBits; |
1724 | /*! The refresh rate, in Hz, of the video mode. |
1725 | */ |
1726 | int refreshRate; |
1727 | } GLFWvidmode; |
1728 | |
1729 | /*! @brief Gamma ramp. |
1730 | * |
1731 | * This describes the gamma ramp for a monitor. |
1732 | * |
1733 | * @sa @ref monitor_gamma |
1734 | * @sa @ref glfwGetGammaRamp |
1735 | * @sa @ref glfwSetGammaRamp |
1736 | * |
1737 | * @since Added in version 3.0. |
1738 | * |
1739 | * @ingroup monitor |
1740 | */ |
1741 | typedef struct GLFWgammaramp |
1742 | { |
1743 | /*! An array of value describing the response of the red channel. |
1744 | */ |
1745 | unsigned short* red; |
1746 | /*! An array of value describing the response of the green channel. |
1747 | */ |
1748 | unsigned short* green; |
1749 | /*! An array of value describing the response of the blue channel. |
1750 | */ |
1751 | unsigned short* blue; |
1752 | /*! The number of elements in each array. |
1753 | */ |
1754 | unsigned int size; |
1755 | } GLFWgammaramp; |
1756 | |
1757 | /*! @brief Image data. |
1758 | * |
1759 | * This describes a single 2D image. See the documentation for each related |
1760 | * function what the expected pixel format is. |
1761 | * |
1762 | * @sa @ref cursor_custom |
1763 | * @sa @ref window_icon |
1764 | * |
1765 | * @since Added in version 2.1. |
1766 | * @glfw3 Removed format and bytes-per-pixel members. |
1767 | * |
1768 | * @ingroup window |
1769 | */ |
1770 | typedef struct GLFWimage |
1771 | { |
1772 | /*! The width, in pixels, of this image. |
1773 | */ |
1774 | int width; |
1775 | /*! The height, in pixels, of this image. |
1776 | */ |
1777 | int height; |
1778 | /*! The pixel data of this image, arranged left-to-right, top-to-bottom. |
1779 | */ |
1780 | unsigned char* pixels; |
1781 | } GLFWimage; |
1782 | |
1783 | /*! @brief Gamepad input state |
1784 | * |
1785 | * This describes the input state of a gamepad. |
1786 | * |
1787 | * @sa @ref gamepad |
1788 | * @sa @ref glfwGetGamepadState |
1789 | * |
1790 | * @since Added in version 3.3. |
1791 | * |
1792 | * @ingroup input |
1793 | */ |
1794 | typedef struct GLFWgamepadstate |
1795 | { |
1796 | /*! The states of each [gamepad button](@ref gamepad_buttons), `GLFW_PRESS` |
1797 | * or `GLFW_RELEASE`. |
1798 | */ |
1799 | unsigned char buttons[15]; |
1800 | /*! The states of each [gamepad axis](@ref gamepad_axes), in the range -1.0 |
1801 | * to 1.0 inclusive. |
1802 | */ |
1803 | float axes[6]; |
1804 | } GLFWgamepadstate; |
1805 | |
1806 | |
1807 | /************************************************************************* |
1808 | * GLFW API functions |
1809 | *************************************************************************/ |
1810 | |
1811 | /*! @brief Initializes the GLFW library. |
1812 | * |
1813 | * This function initializes the GLFW library. Before most GLFW functions can |
1814 | * be used, GLFW must be initialized, and before an application terminates GLFW |
1815 | * should be terminated in order to free any resources allocated during or |
1816 | * after initialization. |
1817 | * |
1818 | * If this function fails, it calls @ref glfwTerminate before returning. If it |
1819 | * succeeds, you should call @ref glfwTerminate before the application exits. |
1820 | * |
1821 | * Additional calls to this function after successful initialization but before |
1822 | * termination will return `GLFW_TRUE` immediately. |
1823 | * |
1824 | * @return `GLFW_TRUE` if successful, or `GLFW_FALSE` if an |
1825 | * [error](@ref error_handling) occurred. |
1826 | * |
1827 | * @errors Possible errors include @ref GLFW_PLATFORM_ERROR. |
1828 | * |
1829 | * @remark @macos This function will change the current directory of the |
1830 | * application to the `Contents/Resources` subdirectory of the application's |
1831 | * bundle, if present. This can be disabled with the @ref |
1832 | * GLFW_COCOA_CHDIR_RESOURCES init hint. |
1833 | * |
1834 | * @thread_safety This function must only be called from the main thread. |
1835 | * |
1836 | * @sa @ref intro_init |
1837 | * @sa @ref glfwTerminate |
1838 | * |
1839 | * @since Added in version 1.0. |
1840 | * |
1841 | * @ingroup init |
1842 | */ |
1843 | GLFWAPI int glfwInit(void); |
1844 | |
1845 | /*! @brief Terminates the GLFW library. |
1846 | * |
1847 | * This function destroys all remaining windows and cursors, restores any |
1848 | * modified gamma ramps and frees any other allocated resources. Once this |
1849 | * function is called, you must again call @ref glfwInit successfully before |
1850 | * you will be able to use most GLFW functions. |
1851 | * |
1852 | * If GLFW has been successfully initialized, this function should be called |
1853 | * before the application exits. If initialization fails, there is no need to |
1854 | * call this function, as it is called by @ref glfwInit before it returns |
1855 | * failure. |
1856 | * |
1857 | * @errors Possible errors include @ref GLFW_PLATFORM_ERROR. |
1858 | * |
1859 | * @remark This function may be called before @ref glfwInit. |
1860 | * |
1861 | * @warning The contexts of any remaining windows must not be current on any |
1862 | * other thread when this function is called. |
1863 | * |
1864 | * @reentrancy This function must not be called from a callback. |
1865 | * |
1866 | * @thread_safety This function must only be called from the main thread. |
1867 | * |
1868 | * @sa @ref intro_init |
1869 | * @sa @ref glfwInit |
1870 | * |
1871 | * @since Added in version 1.0. |
1872 | * |
1873 | * @ingroup init |
1874 | */ |
1875 | GLFWAPI void glfwTerminate(void); |
1876 | |
1877 | /*! @brief Sets the specified init hint to the desired value. |
1878 | * |
1879 | * This function sets hints for the next initialization of GLFW. |
1880 | * |
1881 | * The values you set hints to are never reset by GLFW, but they only take |
1882 | * effect during initialization. Once GLFW has been initialized, any values |
1883 | * you set will be ignored until the library is terminated and initialized |
1884 | * again. |
1885 | * |
1886 | * Some hints are platform specific. These may be set on any platform but they |
1887 | * will only affect their specific platform. Other platforms will ignore them. |
1888 | * Setting these hints requires no platform specific headers or functions. |
1889 | * |
1890 | * @param[in] hint The [init hint](@ref init_hints) to set. |
1891 | * @param[in] value The new value of the init hint. |
1892 | * |
1893 | * @errors Possible errors include @ref GLFW_INVALID_ENUM and @ref |
1894 | * GLFW_INVALID_VALUE. |
1895 | * |
1896 | * @remarks This function may be called before @ref glfwInit. |
1897 | * |
1898 | * @thread_safety This function must only be called from the main thread. |
1899 | * |
1900 | * @sa init_hints |
1901 | * @sa glfwInit |
1902 | * |
1903 | * @since Added in version 3.3. |
1904 | * |
1905 | * @ingroup init |
1906 | */ |
1907 | GLFWAPI void glfwInitHint(int hint, int value); |
1908 | |
1909 | /*! @brief Retrieves the version of the GLFW library. |
1910 | * |
1911 | * This function retrieves the major, minor and revision numbers of the GLFW |
1912 | * library. It is intended for when you are using GLFW as a shared library and |
1913 | * want to ensure that you are using the minimum required version. |
1914 | * |
1915 | * Any or all of the version arguments may be `NULL`. |
1916 | * |
1917 | * @param[out] major Where to store the major version number, or `NULL`. |
1918 | * @param[out] minor Where to store the minor version number, or `NULL`. |
1919 | * @param[out] rev Where to store the revision number, or `NULL`. |
1920 | * |
1921 | * @errors None. |
1922 | * |
1923 | * @remark This function may be called before @ref glfwInit. |
1924 | * |
1925 | * @thread_safety This function may be called from any thread. |
1926 | * |
1927 | * @sa @ref intro_version |
1928 | * @sa @ref glfwGetVersionString |
1929 | * |
1930 | * @since Added in version 1.0. |
1931 | * |
1932 | * @ingroup init |
1933 | */ |
1934 | GLFWAPI void glfwGetVersion(int* major, int* minor, int* rev); |
1935 | |
1936 | /*! @brief Returns a string describing the compile-time configuration. |
1937 | * |
1938 | * This function returns the compile-time generated |
1939 | * [version string](@ref intro_version_string) of the GLFW library binary. It |
1940 | * describes the version, platform, compiler and any platform-specific |
1941 | * compile-time options. It should not be confused with the OpenGL or OpenGL |
1942 | * ES version string, queried with `glGetString`. |
1943 | * |
1944 | * __Do not use the version string__ to parse the GLFW library version. The |
1945 | * @ref glfwGetVersion function provides the version of the running library |
1946 | * binary in numerical format. |
1947 | * |
1948 | * @return The ASCII encoded GLFW version string. |
1949 | * |
1950 | * @errors None. |
1951 | * |
1952 | * @remark This function may be called before @ref glfwInit. |
1953 | * |
1954 | * @pointer_lifetime The returned string is static and compile-time generated. |
1955 | * |
1956 | * @thread_safety This function may be called from any thread. |
1957 | * |
1958 | * @sa @ref intro_version |
1959 | * @sa @ref glfwGetVersion |
1960 | * |
1961 | * @since Added in version 3.0. |
1962 | * |
1963 | * @ingroup init |
1964 | */ |
1965 | GLFWAPI const char* glfwGetVersionString(void); |
1966 | |
1967 | /*! @brief Returns and clears the last error for the calling thread. |
1968 | * |
1969 | * This function returns and clears the [error code](@ref errors) of the last |
1970 | * error that occurred on the calling thread, and optionally a UTF-8 encoded |
1971 | * human-readable description of it. If no error has occurred since the last |
1972 | * call, it returns @ref GLFW_NO_ERROR (zero) and the description pointer is |
1973 | * set to `NULL`. |
1974 | * |
1975 | * @param[in] description Where to store the error description pointer, or `NULL`. |
1976 | * @return The last error code for the calling thread, or @ref GLFW_NO_ERROR |
1977 | * (zero). |
1978 | * |
1979 | * @errors None. |
1980 | * |
1981 | * @pointer_lifetime The returned string is allocated and freed by GLFW. You |
1982 | * should not free it yourself. It is guaranteed to be valid only until the |
1983 | * next error occurs or the library is terminated. |
1984 | * |
1985 | * @remark This function may be called before @ref glfwInit. |
1986 | * |
1987 | * @thread_safety This function may be called from any thread. |
1988 | * |
1989 | * @sa @ref error_handling |
1990 | * @sa @ref glfwSetErrorCallback |
1991 | * |
1992 | * @since Added in version 3.3. |
1993 | * |
1994 | * @ingroup init |
1995 | */ |
1996 | GLFWAPI int glfwGetError(const char** description); |
1997 | |
1998 | /*! @brief Sets the error callback. |
1999 | * |
2000 | * This function sets the error callback, which is called with an error code |
2001 | * and a human-readable description each time a GLFW error occurs. |
2002 | * |
2003 | * The error code is set before the callback is called. Calling @ref |
2004 | * glfwGetError from the error callback will return the same value as the error |
2005 | * code argument. |
2006 | * |
2007 | * The error callback is called on the thread where the error occurred. If you |
2008 | * are using GLFW from multiple threads, your error callback needs to be |
2009 | * written accordingly. |
2010 | * |
2011 | * Because the description string may have been generated specifically for that |
2012 | * error, it is not guaranteed to be valid after the callback has returned. If |
2013 | * you wish to use it after the callback returns, you need to make a copy. |
2014 | * |
2015 | * Once set, the error callback remains set even after the library has been |
2016 | * terminated. |
2017 | * |
2018 | * @param[in] callback The new callback, or `NULL` to remove the currently set |
2019 | * callback. |
2020 | * @return The previously set callback, or `NULL` if no callback was set. |
2021 | * |
2022 | * @callback_signature |
2023 | * @code |
2024 | * void callback_name(int error_code, const char* description) |
2025 | * @endcode |
2026 | * For more information about the callback parameters, see the |
2027 | * [callback pointer type](@ref GLFWerrorfun). |
2028 | * |
2029 | * @errors None. |
2030 | * |
2031 | * @remark This function may be called before @ref glfwInit. |
2032 | * |
2033 | * @thread_safety This function must only be called from the main thread. |
2034 | * |
2035 | * @sa @ref error_handling |
2036 | * @sa @ref glfwGetError |
2037 | * |
2038 | * @since Added in version 3.0. |
2039 | * |
2040 | * @ingroup init |
2041 | */ |
2042 | GLFWAPI GLFWerrorfun glfwSetErrorCallback(GLFWerrorfun callback); |
2043 | |
2044 | /*! @brief Returns the currently connected monitors. |
2045 | * |
2046 | * This function returns an array of handles for all currently connected |
2047 | * monitors. The primary monitor is always first in the returned array. If no |
2048 | * monitors were found, this function returns `NULL`. |
2049 | * |
2050 | * @param[out] count Where to store the number of monitors in the returned |
2051 | * array. This is set to zero if an error occurred. |
2052 | * @return An array of monitor handles, or `NULL` if no monitors were found or |
2053 | * if an [error](@ref error_handling) occurred. |
2054 | * |
2055 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. |
2056 | * |
2057 | * @pointer_lifetime The returned array is allocated and freed by GLFW. You |
2058 | * should not free it yourself. It is guaranteed to be valid only until the |
2059 | * monitor configuration changes or the library is terminated. |
2060 | * |
2061 | * @thread_safety This function must only be called from the main thread. |
2062 | * |
2063 | * @sa @ref monitor_monitors |
2064 | * @sa @ref monitor_event |
2065 | * @sa @ref glfwGetPrimaryMonitor |
2066 | * |
2067 | * @since Added in version 3.0. |
2068 | * |
2069 | * @ingroup monitor |
2070 | */ |
2071 | GLFWAPI GLFWmonitor** glfwGetMonitors(int* count); |
2072 | |
2073 | /*! @brief Returns the primary monitor. |
2074 | * |
2075 | * This function returns the primary monitor. This is usually the monitor |
2076 | * where elements like the task bar or global menu bar are located. |
2077 | * |
2078 | * @return The primary monitor, or `NULL` if no monitors were found or if an |
2079 | * [error](@ref error_handling) occurred. |
2080 | * |
2081 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. |
2082 | * |
2083 | * @thread_safety This function must only be called from the main thread. |
2084 | * |
2085 | * @remark The primary monitor is always first in the array returned by @ref |
2086 | * glfwGetMonitors. |
2087 | * |
2088 | * @sa @ref monitor_monitors |
2089 | * @sa @ref glfwGetMonitors |
2090 | * |
2091 | * @since Added in version 3.0. |
2092 | * |
2093 | * @ingroup monitor |
2094 | */ |
2095 | GLFWAPI GLFWmonitor* glfwGetPrimaryMonitor(void); |
2096 | |
2097 | /*! @brief Returns the position of the monitor's viewport on the virtual screen. |
2098 | * |
2099 | * This function returns the position, in screen coordinates, of the upper-left |
2100 | * corner of the specified monitor. |
2101 | * |
2102 | * Any or all of the position arguments may be `NULL`. If an error occurs, all |
2103 | * non-`NULL` position arguments will be set to zero. |
2104 | * |
2105 | * @param[in] monitor The monitor to query. |
2106 | * @param[out] xpos Where to store the monitor x-coordinate, or `NULL`. |
2107 | * @param[out] ypos Where to store the monitor y-coordinate, or `NULL`. |
2108 | * |
2109 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref |
2110 | * GLFW_PLATFORM_ERROR. |
2111 | * |
2112 | * @thread_safety This function must only be called from the main thread. |
2113 | * |
2114 | * @sa @ref monitor_properties |
2115 | * |
2116 | * @since Added in version 3.0. |
2117 | * |
2118 | * @ingroup monitor |
2119 | */ |
2120 | GLFWAPI void glfwGetMonitorPos(GLFWmonitor* monitor, int* xpos, int* ypos); |
2121 | |
2122 | /*! @brief Retrieves the work area of the monitor. |
2123 | * |
2124 | * This function returns the position, in screen coordinates, of the upper-left |
2125 | * corner of the work area of the specified monitor along with the work area |
2126 | * size in screen coordinates. The work area is defined as the area of the |
2127 | * monitor not occluded by the operating system task bar where present. If no |
2128 | * task bar exists then the work area is the monitor resolution in screen |
2129 | * coordinates. |
2130 | * |
2131 | * Any or all of the position and size arguments may be `NULL`. If an error |
2132 | * occurs, all non-`NULL` position and size arguments will be set to zero. |
2133 | * |
2134 | * @param[in] monitor The monitor to query. |
2135 | * @param[out] xpos Where to store the monitor x-coordinate, or `NULL`. |
2136 | * @param[out] ypos Where to store the monitor y-coordinate, or `NULL`. |
2137 | * @param[out] width Where to store the monitor width, or `NULL`. |
2138 | * @param[out] height Where to store the monitor height, or `NULL`. |
2139 | * |
2140 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref |
2141 | * GLFW_PLATFORM_ERROR. |
2142 | * |
2143 | * @thread_safety This function must only be called from the main thread. |
2144 | * |
2145 | * @sa @ref monitor_workarea |
2146 | * |
2147 | * @since Added in version 3.3. |
2148 | * |
2149 | * @ingroup monitor |
2150 | */ |
2151 | GLFWAPI void glfwGetMonitorWorkarea(GLFWmonitor* monitor, int* xpos, int* ypos, int* width, int* height); |
2152 | |
2153 | /*! @brief Returns the physical size of the monitor. |
2154 | * |
2155 | * This function returns the size, in millimetres, of the display area of the |
2156 | * specified monitor. |
2157 | * |
2158 | * Some systems do not provide accurate monitor size information, either |
2159 | * because the monitor |
2160 | * [EDID](https://en.wikipedia.org/wiki/Extended_display_identification_data) |
2161 | * data is incorrect or because the driver does not report it accurately. |
2162 | * |
2163 | * Any or all of the size arguments may be `NULL`. If an error occurs, all |
2164 | * non-`NULL` size arguments will be set to zero. |
2165 | * |
2166 | * @param[in] monitor The monitor to query. |
2167 | * @param[out] widthMM Where to store the width, in millimetres, of the |
2168 | * monitor's display area, or `NULL`. |
2169 | * @param[out] heightMM Where to store the height, in millimetres, of the |
2170 | * monitor's display area, or `NULL`. |
2171 | * |
2172 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. |
2173 | * |
2174 | * @remark @win32 calculates the returned physical size from the |
2175 | * current resolution and system DPI instead of querying the monitor EDID data. |
2176 | * |
2177 | * @thread_safety This function must only be called from the main thread. |
2178 | * |
2179 | * @sa @ref monitor_properties |
2180 | * |
2181 | * @since Added in version 3.0. |
2182 | * |
2183 | * @ingroup monitor |
2184 | */ |
2185 | GLFWAPI void glfwGetMonitorPhysicalSize(GLFWmonitor* monitor, int* widthMM, int* heightMM); |
2186 | |
2187 | /*! @brief Retrieves the content scale for the specified monitor. |
2188 | * |
2189 | * This function retrieves the content scale for the specified monitor. The |
2190 | * content scale is the ratio between the current DPI and the platform's |
2191 | * default DPI. This is especially important for text and any UI elements. If |
2192 | * the pixel dimensions of your UI scaled by this look appropriate on your |
2193 | * machine then it should appear at a reasonable size on other machines |
2194 | * regardless of their DPI and scaling settings. This relies on the system DPI |
2195 | * and scaling settings being somewhat correct. |
2196 | * |
2197 | * The content scale may depend on both the monitor resolution and pixel |
2198 | * density and on user settings. It may be very different from the raw DPI |
2199 | * calculated from the physical size and current resolution. |
2200 | * |
2201 | * @param[in] monitor The monitor to query. |
2202 | * @param[out] xscale Where to store the x-axis content scale, or `NULL`. |
2203 | * @param[out] yscale Where to store the y-axis content scale, or `NULL`. |
2204 | * |
2205 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref |
2206 | * GLFW_PLATFORM_ERROR. |
2207 | * |
2208 | * @thread_safety This function must only be called from the main thread. |
2209 | * |
2210 | * @sa @ref monitor_scale |
2211 | * @sa @ref glfwGetWindowContentScale |
2212 | * |
2213 | * @since Added in version 3.3. |
2214 | * |
2215 | * @ingroup monitor |
2216 | */ |
2217 | GLFWAPI void glfwGetMonitorContentScale(GLFWmonitor* monitor, float* xscale, float* yscale); |
2218 | |
2219 | /*! @brief Returns the name of the specified monitor. |
2220 | * |
2221 | * This function returns a human-readable name, encoded as UTF-8, of the |
2222 | * specified monitor. The name typically reflects the make and model of the |
2223 | * monitor and is not guaranteed to be unique among the connected monitors. |
2224 | * |
2225 | * @param[in] monitor The monitor to query. |
2226 | * @return The UTF-8 encoded name of the monitor, or `NULL` if an |
2227 | * [error](@ref error_handling) occurred. |
2228 | * |
2229 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. |
2230 | * |
2231 | * @pointer_lifetime The returned string is allocated and freed by GLFW. You |
2232 | * should not free it yourself. It is valid until the specified monitor is |
2233 | * disconnected or the library is terminated. |
2234 | * |
2235 | * @thread_safety This function must only be called from the main thread. |
2236 | * |
2237 | * @sa @ref monitor_properties |
2238 | * |
2239 | * @since Added in version 3.0. |
2240 | * |
2241 | * @ingroup monitor |
2242 | */ |
2243 | GLFWAPI const char* glfwGetMonitorName(GLFWmonitor* monitor); |
2244 | |
2245 | /*! @brief Sets the user pointer of the specified monitor. |
2246 | * |
2247 | * This function sets the user-defined pointer of the specified monitor. The |
2248 | * current value is retained until the monitor is disconnected. The initial |
2249 | * value is `NULL`. |
2250 | * |
2251 | * This function may be called from the monitor callback, even for a monitor |
2252 | * that is being disconnected. |
2253 | * |
2254 | * @param[in] monitor The monitor whose pointer to set. |
2255 | * @param[in] pointer The new value. |
2256 | * |
2257 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. |
2258 | * |
2259 | * @thread_safety This function may be called from any thread. Access is not |
2260 | * synchronized. |
2261 | * |
2262 | * @sa @ref monitor_userptr |
2263 | * @sa @ref glfwGetMonitorUserPointer |
2264 | * |
2265 | * @since Added in version 3.3. |
2266 | * |
2267 | * @ingroup monitor |
2268 | */ |
2269 | GLFWAPI void glfwSetMonitorUserPointer(GLFWmonitor* monitor, void* pointer); |
2270 | |
2271 | /*! @brief Returns the user pointer of the specified monitor. |
2272 | * |
2273 | * This function returns the current value of the user-defined pointer of the |
2274 | * specified monitor. The initial value is `NULL`. |
2275 | * |
2276 | * This function may be called from the monitor callback, even for a monitor |
2277 | * that is being disconnected. |
2278 | * |
2279 | * @param[in] monitor The monitor whose pointer to return. |
2280 | * |
2281 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. |
2282 | * |
2283 | * @thread_safety This function may be called from any thread. Access is not |
2284 | * synchronized. |
2285 | * |
2286 | * @sa @ref monitor_userptr |
2287 | * @sa @ref glfwSetMonitorUserPointer |
2288 | * |
2289 | * @since Added in version 3.3. |
2290 | * |
2291 | * @ingroup monitor |
2292 | */ |
2293 | GLFWAPI void* glfwGetMonitorUserPointer(GLFWmonitor* monitor); |
2294 | |
2295 | /*! @brief Sets the monitor configuration callback. |
2296 | * |
2297 | * This function sets the monitor configuration callback, or removes the |
2298 | * currently set callback. This is called when a monitor is connected to or |
2299 | * disconnected from the system. |
2300 | * |
2301 | * @param[in] callback The new callback, or `NULL` to remove the currently set |
2302 | * callback. |
2303 | * @return The previously set callback, or `NULL` if no callback was set or the |
2304 | * library had not been [initialized](@ref intro_init). |
2305 | * |
2306 | * @callback_signature |
2307 | * @code |
2308 | * void function_name(GLFWmonitor* monitor, int event) |
2309 | * @endcode |
2310 | * For more information about the callback parameters, see the |
2311 | * [function pointer type](@ref GLFWmonitorfun). |
2312 | * |
2313 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. |
2314 | * |
2315 | * @thread_safety This function must only be called from the main thread. |
2316 | * |
2317 | * @sa @ref monitor_event |
2318 | * |
2319 | * @since Added in version 3.0. |
2320 | * |
2321 | * @ingroup monitor |
2322 | */ |
2323 | GLFWAPI GLFWmonitorfun glfwSetMonitorCallback(GLFWmonitorfun callback); |
2324 | |
2325 | /*! @brief Returns the available video modes for the specified monitor. |
2326 | * |
2327 | * This function returns an array of all video modes supported by the specified |
2328 | * monitor. The returned array is sorted in ascending order, first by color |
2329 | * bit depth (the sum of all channel depths) and then by resolution area (the |
2330 | * product of width and height). |
2331 | * |
2332 | * @param[in] monitor The monitor to query. |
2333 | * @param[out] count Where to store the number of video modes in the returned |
2334 | * array. This is set to zero if an error occurred. |
2335 | * @return An array of video modes, or `NULL` if an |
2336 | * [error](@ref error_handling) occurred. |
2337 | * |
2338 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref |
2339 | * GLFW_PLATFORM_ERROR. |
2340 | * |
2341 | * @pointer_lifetime The returned array is allocated and freed by GLFW. You |
2342 | * should not free it yourself. It is valid until the specified monitor is |
2343 | * disconnected, this function is called again for that monitor or the library |
2344 | * is terminated. |
2345 | * |
2346 | * @thread_safety This function must only be called from the main thread. |
2347 | * |
2348 | * @sa @ref monitor_modes |
2349 | * @sa @ref glfwGetVideoMode |
2350 | * |
2351 | * @since Added in version 1.0. |
2352 | * @glfw3 Changed to return an array of modes for a specific monitor. |
2353 | * |
2354 | * @ingroup monitor |
2355 | */ |
2356 | GLFWAPI const GLFWvidmode* glfwGetVideoModes(GLFWmonitor* monitor, int* count); |
2357 | |
2358 | /*! @brief Returns the current mode of the specified monitor. |
2359 | * |
2360 | * This function returns the current video mode of the specified monitor. If |
2361 | * you have created a full screen window for that monitor, the return value |
2362 | * will depend on whether that window is iconified. |
2363 | * |
2364 | * @param[in] monitor The monitor to query. |
2365 | * @return The current mode of the monitor, or `NULL` if an |
2366 | * [error](@ref error_handling) occurred. |
2367 | * |
2368 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref |
2369 | * GLFW_PLATFORM_ERROR. |
2370 | * |
2371 | * @pointer_lifetime The returned array is allocated and freed by GLFW. You |
2372 | * should not free it yourself. It is valid until the specified monitor is |
2373 | * disconnected or the library is terminated. |
2374 | * |
2375 | * @thread_safety This function must only be called from the main thread. |
2376 | * |
2377 | * @sa @ref monitor_modes |
2378 | * @sa @ref glfwGetVideoModes |
2379 | * |
2380 | * @since Added in version 3.0. Replaces `glfwGetDesktopMode`. |
2381 | * |
2382 | * @ingroup monitor |
2383 | */ |
2384 | GLFWAPI const GLFWvidmode* glfwGetVideoMode(GLFWmonitor* monitor); |
2385 | |
2386 | /*! @brief Generates a gamma ramp and sets it for the specified monitor. |
2387 | * |
2388 | * This function generates an appropriately sized gamma ramp from the specified |
2389 | * exponent and then calls @ref glfwSetGammaRamp with it. The value must be |
2390 | * a finite number greater than zero. |
2391 | * |
2392 | * The software controlled gamma ramp is applied _in addition_ to the hardware |
2393 | * gamma correction, which today is usually an approximation of sRGB gamma. |
2394 | * This means that setting a perfectly linear ramp, or gamma 1.0, will produce |
2395 | * the default (usually sRGB-like) behavior. |
2396 | * |
2397 | * For gamma correct rendering with OpenGL or OpenGL ES, see the @ref |
2398 | * GLFW_SRGB_CAPABLE hint. |
2399 | * |
2400 | * @param[in] monitor The monitor whose gamma ramp to set. |
2401 | * @param[in] gamma The desired exponent. |
2402 | * |
2403 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref |
2404 | * GLFW_INVALID_VALUE and @ref GLFW_PLATFORM_ERROR. |
2405 | * |
2406 | * @remark @wayland Gamma handling is a privileged protocol, this function |
2407 | * will thus never be implemented and emits @ref GLFW_PLATFORM_ERROR. |
2408 | * |
2409 | * @thread_safety This function must only be called from the main thread. |
2410 | * |
2411 | * @sa @ref monitor_gamma |
2412 | * |
2413 | * @since Added in version 3.0. |
2414 | * |
2415 | * @ingroup monitor |
2416 | */ |
2417 | GLFWAPI void glfwSetGamma(GLFWmonitor* monitor, float gamma); |
2418 | |
2419 | /*! @brief Returns the current gamma ramp for the specified monitor. |
2420 | * |
2421 | * This function returns the current gamma ramp of the specified monitor. |
2422 | * |
2423 | * @param[in] monitor The monitor to query. |
2424 | * @return The current gamma ramp, or `NULL` if an |
2425 | * [error](@ref error_handling) occurred. |
2426 | * |
2427 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref |
2428 | * GLFW_PLATFORM_ERROR. |
2429 | * |
2430 | * @remark @wayland Gamma handling is a privileged protocol, this function |
2431 | * will thus never be implemented and emits @ref GLFW_PLATFORM_ERROR while |
2432 | * returning `NULL`. |
2433 | * |
2434 | * @pointer_lifetime The returned structure and its arrays are allocated and |
2435 | * freed by GLFW. You should not free them yourself. They are valid until the |
2436 | * specified monitor is disconnected, this function is called again for that |
2437 | * monitor or the library is terminated. |
2438 | * |
2439 | * @thread_safety This function must only be called from the main thread. |
2440 | * |
2441 | * @sa @ref monitor_gamma |
2442 | * |
2443 | * @since Added in version 3.0. |
2444 | * |
2445 | * @ingroup monitor |
2446 | */ |
2447 | GLFWAPI const GLFWgammaramp* glfwGetGammaRamp(GLFWmonitor* monitor); |
2448 | |
2449 | /*! @brief Sets the current gamma ramp for the specified monitor. |
2450 | * |
2451 | * This function sets the current gamma ramp for the specified monitor. The |
2452 | * original gamma ramp for that monitor is saved by GLFW the first time this |
2453 | * function is called and is restored by @ref glfwTerminate. |
2454 | * |
2455 | * The software controlled gamma ramp is applied _in addition_ to the hardware |
2456 | * gamma correction, which today is usually an approximation of sRGB gamma. |
2457 | * This means that setting a perfectly linear ramp, or gamma 1.0, will produce |
2458 | * the default (usually sRGB-like) behavior. |
2459 | * |
2460 | * For gamma correct rendering with OpenGL or OpenGL ES, see the @ref |
2461 | * GLFW_SRGB_CAPABLE hint. |
2462 | * |
2463 | * @param[in] monitor The monitor whose gamma ramp to set. |
2464 | * @param[in] ramp The gamma ramp to use. |
2465 | * |
2466 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref |
2467 | * GLFW_PLATFORM_ERROR. |
2468 | * |
2469 | * @remark The size of the specified gamma ramp should match the size of the |
2470 | * current ramp for that monitor. |
2471 | * |
2472 | * @remark @win32 The gamma ramp size must be 256. |
2473 | * |
2474 | * @remark @wayland Gamma handling is a privileged protocol, this function |
2475 | * will thus never be implemented and emits @ref GLFW_PLATFORM_ERROR. |
2476 | * |
2477 | * @pointer_lifetime The specified gamma ramp is copied before this function |
2478 | * returns. |
2479 | * |
2480 | * @thread_safety This function must only be called from the main thread. |
2481 | * |
2482 | * @sa @ref monitor_gamma |
2483 | * |
2484 | * @since Added in version 3.0. |
2485 | * |
2486 | * @ingroup monitor |
2487 | */ |
2488 | GLFWAPI void glfwSetGammaRamp(GLFWmonitor* monitor, const GLFWgammaramp* ramp); |
2489 | |
2490 | /*! @brief Resets all window hints to their default values. |
2491 | * |
2492 | * This function resets all window hints to their |
2493 | * [default values](@ref window_hints_values). |
2494 | * |
2495 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. |
2496 | * |
2497 | * @thread_safety This function must only be called from the main thread. |
2498 | * |
2499 | * @sa @ref window_hints |
2500 | * @sa @ref glfwWindowHint |
2501 | * @sa @ref glfwWindowHintString |
2502 | * |
2503 | * @since Added in version 3.0. |
2504 | * |
2505 | * @ingroup window |
2506 | */ |
2507 | GLFWAPI void glfwDefaultWindowHints(void); |
2508 | |
2509 | /*! @brief Sets the specified window hint to the desired value. |
2510 | * |
2511 | * This function sets hints for the next call to @ref glfwCreateWindow. The |
2512 | * hints, once set, retain their values until changed by a call to this |
2513 | * function or @ref glfwDefaultWindowHints, or until the library is terminated. |
2514 | * |
2515 | * Only integer value hints can be set with this function. String value hints |
2516 | * are set with @ref glfwWindowHintString. |
2517 | * |
2518 | * This function does not check whether the specified hint values are valid. |
2519 | * If you set hints to invalid values this will instead be reported by the next |
2520 | * call to @ref glfwCreateWindow. |
2521 | * |
2522 | * Some hints are platform specific. These may be set on any platform but they |
2523 | * will only affect their specific platform. Other platforms will ignore them. |
2524 | * Setting these hints requires no platform specific headers or functions. |
2525 | * |
2526 | * @param[in] hint The [window hint](@ref window_hints) to set. |
2527 | * @param[in] value The new value of the window hint. |
2528 | * |
2529 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref |
2530 | * GLFW_INVALID_ENUM. |
2531 | * |
2532 | * @thread_safety This function must only be called from the main thread. |
2533 | * |
2534 | * @sa @ref window_hints |
2535 | * @sa @ref glfwWindowHintString |
2536 | * @sa @ref glfwDefaultWindowHints |
2537 | * |
2538 | * @since Added in version 3.0. Replaces `glfwOpenWindowHint`. |
2539 | * |
2540 | * @ingroup window |
2541 | */ |
2542 | GLFWAPI void glfwWindowHint(int hint, int value); |
2543 | |
2544 | /*! @brief Sets the specified window hint to the desired value. |
2545 | * |
2546 | * This function sets hints for the next call to @ref glfwCreateWindow. The |
2547 | * hints, once set, retain their values until changed by a call to this |
2548 | * function or @ref glfwDefaultWindowHints, or until the library is terminated. |
2549 | * |
2550 | * Only string type hints can be set with this function. Integer value hints |
2551 | * are set with @ref glfwWindowHint. |
2552 | * |
2553 | * This function does not check whether the specified hint values are valid. |
2554 | * If you set hints to invalid values this will instead be reported by the next |
2555 | * call to @ref glfwCreateWindow. |
2556 | * |
2557 | * Some hints are platform specific. These may be set on any platform but they |
2558 | * will only affect their specific platform. Other platforms will ignore them. |
2559 | * Setting these hints requires no platform specific headers or functions. |
2560 | * |
2561 | * @param[in] hint The [window hint](@ref window_hints) to set. |
2562 | * @param[in] value The new value of the window hint. |
2563 | * |
2564 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref |
2565 | * GLFW_INVALID_ENUM. |
2566 | * |
2567 | * @pointer_lifetime The specified string is copied before this function |
2568 | * returns. |
2569 | * |
2570 | * @thread_safety This function must only be called from the main thread. |
2571 | * |
2572 | * @sa @ref window_hints |
2573 | * @sa @ref glfwWindowHint |
2574 | * @sa @ref glfwDefaultWindowHints |
2575 | * |
2576 | * @since Added in version 3.3. |
2577 | * |
2578 | * @ingroup window |
2579 | */ |
2580 | GLFWAPI void glfwWindowHintString(int hint, const char* value); |
2581 | |
2582 | /*! @brief Creates a window and its associated context. |
2583 | * |
2584 | * This function creates a window and its associated OpenGL or OpenGL ES |
2585 | * context. Most of the options controlling how the window and its context |
2586 | * should be created are specified with [window hints](@ref window_hints). |
2587 | * |
2588 | * Successful creation does not change which context is current. Before you |
2589 | * can use the newly created context, you need to |
2590 | * [make it current](@ref context_current). For information about the `share` |
2591 | * parameter, see @ref context_sharing. |
2592 | * |
2593 | * The created window, framebuffer and context may differ from what you |
2594 | * requested, as not all parameters and hints are |
2595 | * [hard constraints](@ref window_hints_hard). This includes the size of the |
2596 | * window, especially for full screen windows. To query the actual attributes |
2597 | * of the created window, framebuffer and context, see @ref |
2598 | * glfwGetWindowAttrib, @ref glfwGetWindowSize and @ref glfwGetFramebufferSize. |
2599 | * |
2600 | * To create a full screen window, you need to specify the monitor the window |
2601 | * will cover. If no monitor is specified, the window will be windowed mode. |
2602 | * Unless you have a way for the user to choose a specific monitor, it is |
2603 | * recommended that you pick the primary monitor. For more information on how |
2604 | * to query connected monitors, see @ref monitor_monitors. |
2605 | * |
2606 | * For full screen windows, the specified size becomes the resolution of the |
2607 | * window's _desired video mode_. As long as a full screen window is not |
2608 | * iconified, the supported video mode most closely matching the desired video |
2609 | * mode is set for the specified monitor. For more information about full |
2610 | * screen windows, including the creation of so called _windowed full screen_ |
2611 | * or _borderless full screen_ windows, see @ref window_windowed_full_screen. |
2612 | * |
2613 | * Once you have created the window, you can switch it between windowed and |
2614 | * full screen mode with @ref glfwSetWindowMonitor. This will not affect its |
2615 | * OpenGL or OpenGL ES context. |
2616 | * |
2617 | * By default, newly created windows use the placement recommended by the |
2618 | * window system. To create the window at a specific position, make it |
2619 | * initially invisible using the [GLFW_VISIBLE](@ref GLFW_VISIBLE_hint) window |
2620 | * hint, set its [position](@ref window_pos) and then [show](@ref window_hide) |
2621 | * it. |
2622 | * |
2623 | * As long as at least one full screen window is not iconified, the screensaver |
2624 | * is prohibited from starting. |
2625 | * |
2626 | * Window systems put limits on window sizes. Very large or very small window |
2627 | * dimensions may be overridden by the window system on creation. Check the |
2628 | * actual [size](@ref window_size) after creation. |
2629 | * |
2630 | * The [swap interval](@ref buffer_swap) is not set during window creation and |
2631 | * the initial value may vary depending on driver settings and defaults. |
2632 | * |
2633 | * @param[in] width The desired width, in screen coordinates, of the window. |
2634 | * This must be greater than zero. |
2635 | * @param[in] height The desired height, in screen coordinates, of the window. |
2636 | * This must be greater than zero. |
2637 | * @param[in] title The initial, UTF-8 encoded window title. |
2638 | * @param[in] monitor The monitor to use for full screen mode, or `NULL` for |
2639 | * windowed mode. |
2640 | * @param[in] share The window whose context to share resources with, or `NULL` |
2641 | * to not share resources. |
2642 | * @return The handle of the created window, or `NULL` if an |
2643 | * [error](@ref error_handling) occurred. |
2644 | * |
2645 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref |
2646 | * GLFW_INVALID_ENUM, @ref GLFW_INVALID_VALUE, @ref GLFW_API_UNAVAILABLE, @ref |
2647 | * GLFW_VERSION_UNAVAILABLE, @ref GLFW_FORMAT_UNAVAILABLE and @ref |
2648 | * GLFW_PLATFORM_ERROR. |
2649 | * |
2650 | * @remark @win32 Window creation will fail if the Microsoft GDI software |
2651 | * OpenGL implementation is the only one available. |
2652 | * |
2653 | * @remark @win32 If the executable has an icon resource named `GLFW_ICON,` it |
2654 | * will be set as the initial icon for the window. If no such icon is present, |
2655 | * the `IDI_APPLICATION` icon will be used instead. To set a different icon, |
2656 | * see @ref glfwSetWindowIcon. |
2657 | * |
2658 | * @remark @win32 The context to share resources with must not be current on |
2659 | * any other thread. |
2660 | * |
2661 | * @remark @macos The OS only supports core profile contexts for OpenGL |
2662 | * versions 3.2 and later. Before creating an OpenGL context of version 3.2 or |
2663 | * later you must set the [GLFW_OPENGL_PROFILE](@ref GLFW_OPENGL_PROFILE_hint) |
2664 | * hint accordingly. OpenGL 3.0 and 3.1 contexts are not supported at all |
2665 | * on macOS. |
2666 | * |
2667 | * @remark @macos The GLFW window has no icon, as it is not a document |
2668 | * window, but the dock icon will be the same as the application bundle's icon. |
2669 | * For more information on bundles, see the |
2670 | * [Bundle Programming Guide](https://developer.apple.com/library/mac/documentation/CoreFoundation/Conceptual/CFBundles/) |
2671 | * in the Mac Developer Library. |
2672 | * |
2673 | * @remark @macos The first time a window is created the menu bar is created. |
2674 | * If GLFW finds a `MainMenu.nib` it is loaded and assumed to contain a menu |
2675 | * bar. Otherwise a minimal menu bar is created manually with common commands |
2676 | * like Hide, Quit and About. The About entry opens a minimal about dialog |
2677 | * with information from the application's bundle. Menu bar creation can be |
2678 | * disabled entirely with the @ref GLFW_COCOA_MENUBAR init hint. |
2679 | * |
2680 | * @remark @macos On OS X 10.10 and later the window frame will not be rendered |
2681 | * at full resolution on Retina displays unless the |
2682 | * [GLFW_COCOA_RETINA_FRAMEBUFFER](@ref GLFW_COCOA_RETINA_FRAMEBUFFER_hint) |
2683 | * hint is `GLFW_TRUE` and the `NSHighResolutionCapable` key is enabled in the |
2684 | * application bundle's `Info.plist`. For more information, see |
2685 | * [High Resolution Guidelines for OS X](https://developer.apple.com/library/mac/documentation/GraphicsAnimation/Conceptual/HighResolutionOSX/Explained/Explained.html) |
2686 | * in the Mac Developer Library. The GLFW test and example programs use |
2687 | * a custom `Info.plist` template for this, which can be found as |
2688 | * `CMake/Info.plist.in` in the source tree. |
2689 | * |
2690 | * @remark @macos When activating frame autosaving with |
2691 | * [GLFW_COCOA_FRAME_NAME](@ref GLFW_COCOA_FRAME_NAME_hint), the specified |
2692 | * window size and position may be overridden by previously saved values. |
2693 | * |
2694 | * @remark @x11 Some window managers will not respect the placement of |
2695 | * initially hidden windows. |
2696 | * |
2697 | * @remark @x11 Due to the asynchronous nature of X11, it may take a moment for |
2698 | * a window to reach its requested state. This means you may not be able to |
2699 | * query the final size, position or other attributes directly after window |
2700 | * creation. |
2701 | * |
2702 | * @remark @x11 The class part of the `WM_CLASS` window property will by |
2703 | * default be set to the window title passed to this function. The instance |
2704 | * part will use the contents of the `RESOURCE_NAME` environment variable, if |
2705 | * present and not empty, or fall back to the window title. Set the |
2706 | * [GLFW_X11_CLASS_NAME](@ref GLFW_X11_CLASS_NAME_hint) and |
2707 | * [GLFW_X11_INSTANCE_NAME](@ref GLFW_X11_INSTANCE_NAME_hint) window hints to |
2708 | * override this. |
2709 | * |
2710 | * @remark @wayland Compositors should implement the xdg-decoration protocol |
2711 | * for GLFW to decorate the window properly. If this protocol isn't |
2712 | * supported, or if the compositor prefers client-side decorations, a very |
2713 | * simple fallback frame will be drawn using the wp_viewporter protocol. A |
2714 | * compositor can still emit close, maximize or fullscreen events, using for |
2715 | * instance a keybind mechanism. If neither of these protocols is supported, |
2716 | * the window won't be decorated. |
2717 | * |
2718 | * @remark @wayland A full screen window will not attempt to change the mode, |
2719 | * no matter what the requested size or refresh rate. |
2720 | * |
2721 | * @remark @wayland Screensaver inhibition requires the idle-inhibit protocol |
2722 | * to be implemented in the user's compositor. |
2723 | * |
2724 | * @thread_safety This function must only be called from the main thread. |
2725 | * |
2726 | * @sa @ref window_creation |
2727 | * @sa @ref glfwDestroyWindow |
2728 | * |
2729 | * @since Added in version 3.0. Replaces `glfwOpenWindow`. |
2730 | * |
2731 | * @ingroup window |
2732 | */ |
2733 | GLFWAPI GLFWwindow* glfwCreateWindow(int width, int height, const char* title, GLFWmonitor* monitor, GLFWwindow* share); |
2734 | |
2735 | /*! @brief Destroys the specified window and its context. |
2736 | * |
2737 | * This function destroys the specified window and its context. On calling |
2738 | * this function, no further callbacks will be called for that window. |
2739 | * |
2740 | * If the context of the specified window is current on the main thread, it is |
2741 | * detached before being destroyed. |
2742 | * |
2743 | * @param[in] window The window to destroy. |
2744 | * |
2745 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref |
2746 | * GLFW_PLATFORM_ERROR. |
2747 | * |
2748 | * @note The context of the specified window must not be current on any other |
2749 | * thread when this function is called. |
2750 | * |
2751 | * @reentrancy This function must not be called from a callback. |
2752 | * |
2753 | * @thread_safety This function must only be called from the main thread. |
2754 | * |
2755 | * @sa @ref window_creation |
2756 | * @sa @ref glfwCreateWindow |
2757 | * |
2758 | * @since Added in version 3.0. Replaces `glfwCloseWindow`. |
2759 | * |
2760 | * @ingroup window |
2761 | */ |
2762 | GLFWAPI void glfwDestroyWindow(GLFWwindow* window); |
2763 | |
2764 | /*! @brief Checks the close flag of the specified window. |
2765 | * |
2766 | * This function returns the value of the close flag of the specified window. |
2767 | * |
2768 | * @param[in] window The window to query. |
2769 | * @return The value of the close flag. |
2770 | * |
2771 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. |
2772 | * |
2773 | * @thread_safety This function may be called from any thread. Access is not |
2774 | * synchronized. |
2775 | * |
2776 | * @sa @ref window_close |
2777 | * |
2778 | * @since Added in version 3.0. |
2779 | * |
2780 | * @ingroup window |
2781 | */ |
2782 | GLFWAPI int glfwWindowShouldClose(GLFWwindow* window); |
2783 | |
2784 | /*! @brief Sets the close flag of the specified window. |
2785 | * |
2786 | * This function sets the value of the close flag of the specified window. |
2787 | * This can be used to override the user's attempt to close the window, or |
2788 | * to signal that it should be closed. |
2789 | * |
2790 | * @param[in] window The window whose flag to change. |
2791 | * @param[in] value The new value. |
2792 | * |
2793 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. |
2794 | * |
2795 | * @thread_safety This function may be called from any thread. Access is not |
2796 | * synchronized. |
2797 | * |
2798 | * @sa @ref window_close |
2799 | * |
2800 | * @since Added in version 3.0. |
2801 | * |
2802 | * @ingroup window |
2803 | */ |
2804 | GLFWAPI void glfwSetWindowShouldClose(GLFWwindow* window, int value); |
2805 | |
2806 | /*! @brief Sets the title of the specified window. |
2807 | * |
2808 | * This function sets the window title, encoded as UTF-8, of the specified |
2809 | * window. |
2810 | * |
2811 | * @param[in] window The window whose title to change. |
2812 | * @param[in] title The UTF-8 encoded window title. |
2813 | * |
2814 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref |
2815 | * GLFW_PLATFORM_ERROR. |
2816 | * |
2817 | * @remark @macos The window title will not be updated until the next time you |
2818 | * process events. |
2819 | * |
2820 | * @thread_safety This function must only be called from the main thread. |
2821 | * |
2822 | * @sa @ref window_title |
2823 | * |
2824 | * @since Added in version 1.0. |
2825 | * @glfw3 Added window handle parameter. |
2826 | * |
2827 | * @ingroup window |
2828 | */ |
2829 | GLFWAPI void glfwSetWindowTitle(GLFWwindow* window, const char* title); |
2830 | |
2831 | /*! @brief Sets the icon for the specified window. |
2832 | * |
2833 | * This function sets the icon of the specified window. If passed an array of |
2834 | * candidate images, those of or closest to the sizes desired by the system are |
2835 | * selected. If no images are specified, the window reverts to its default |
2836 | * icon. |
2837 | * |
2838 | * The pixels are 32-bit, little-endian, non-premultiplied RGBA, i.e. eight |
2839 | * bits per channel with the red channel first. They are arranged canonically |
2840 | * as packed sequential rows, starting from the top-left corner. |
2841 | * |
2842 | * The desired image sizes varies depending on platform and system settings. |
2843 | * The selected images will be rescaled as needed. Good sizes include 16x16, |
2844 | * 32x32 and 48x48. |
2845 | * |
2846 | * @param[in] window The window whose icon to set. |
2847 | * @param[in] count The number of images in the specified array, or zero to |
2848 | * revert to the default window icon. |
2849 | * @param[in] images The images to create the icon from. This is ignored if |
2850 | * count is zero. |
2851 | * |
2852 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref |
2853 | * GLFW_PLATFORM_ERROR. |
2854 | * |
2855 | * @pointer_lifetime The specified image data is copied before this function |
2856 | * returns. |
2857 | * |
2858 | * @remark @macos The GLFW window has no icon, as it is not a document |
2859 | * window, so this function does nothing. The dock icon will be the same as |
2860 | * the application bundle's icon. For more information on bundles, see the |
2861 | * [Bundle Programming Guide](https://developer.apple.com/library/mac/documentation/CoreFoundation/Conceptual/CFBundles/) |
2862 | * in the Mac Developer Library. |
2863 | * |
2864 | * @remark @wayland There is no existing protocol to change an icon, the |
2865 | * window will thus inherit the one defined in the application's desktop file. |
2866 | * This function always emits @ref GLFW_PLATFORM_ERROR. |
2867 | * |
2868 | * @thread_safety This function must only be called from the main thread. |
2869 | * |
2870 | * @sa @ref window_icon |
2871 | * |
2872 | * @since Added in version 3.2. |
2873 | * |
2874 | * @ingroup window |
2875 | */ |
2876 | GLFWAPI void glfwSetWindowIcon(GLFWwindow* window, int count, const GLFWimage* images); |
2877 | |
2878 | /*! @brief Retrieves the position of the content area of the specified window. |
2879 | * |
2880 | * This function retrieves the position, in screen coordinates, of the |
2881 | * upper-left corner of the content area of the specified window. |
2882 | * |
2883 | * Any or all of the position arguments may be `NULL`. If an error occurs, all |
2884 | * non-`NULL` position arguments will be set to zero. |
2885 | * |
2886 | * @param[in] window The window to query. |
2887 | * @param[out] xpos Where to store the x-coordinate of the upper-left corner of |
2888 | * the content area, or `NULL`. |
2889 | * @param[out] ypos Where to store the y-coordinate of the upper-left corner of |
2890 | * the content area, or `NULL`. |
2891 | * |
2892 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref |
2893 | * GLFW_PLATFORM_ERROR. |
2894 | * |
2895 | * @remark @wayland There is no way for an application to retrieve the global |
2896 | * position of its windows, this function will always emit @ref |
2897 | * GLFW_PLATFORM_ERROR. |
2898 | * |
2899 | * @thread_safety This function must only be called from the main thread. |
2900 | * |
2901 | * @sa @ref window_pos |
2902 | * @sa @ref glfwSetWindowPos |
2903 | * |
2904 | * @since Added in version 3.0. |
2905 | * |
2906 | * @ingroup window |
2907 | */ |
2908 | GLFWAPI void glfwGetWindowPos(GLFWwindow* window, int* xpos, int* ypos); |
2909 | |
2910 | /*! @brief Sets the position of the content area of the specified window. |
2911 | * |
2912 | * This function sets the position, in screen coordinates, of the upper-left |
2913 | * corner of the content area of the specified windowed mode window. If the |
2914 | * window is a full screen window, this function does nothing. |
2915 | * |
2916 | * __Do not use this function__ to move an already visible window unless you |
2917 | * have very good reasons for doing so, as it will confuse and annoy the user. |
2918 | * |
2919 | * The window manager may put limits on what positions are allowed. GLFW |
2920 | * cannot and should not override these limits. |
2921 | * |
2922 | * @param[in] window The window to query. |
2923 | * @param[in] xpos The x-coordinate of the upper-left corner of the content area. |
2924 | * @param[in] ypos The y-coordinate of the upper-left corner of the content area. |
2925 | * |
2926 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref |
2927 | * GLFW_PLATFORM_ERROR. |
2928 | * |
2929 | * @remark @wayland There is no way for an application to set the global |
2930 | * position of its windows, this function will always emit @ref |
2931 | * GLFW_PLATFORM_ERROR. |
2932 | * |
2933 | * @thread_safety This function must only be called from the main thread. |
2934 | * |
2935 | * @sa @ref window_pos |
2936 | * @sa @ref glfwGetWindowPos |
2937 | * |
2938 | * @since Added in version 1.0. |
2939 | * @glfw3 Added window handle parameter. |
2940 | * |
2941 | * @ingroup window |
2942 | */ |
2943 | GLFWAPI void glfwSetWindowPos(GLFWwindow* window, int xpos, int ypos); |
2944 | |
2945 | /*! @brief Retrieves the size of the content area of the specified window. |
2946 | * |
2947 | * This function retrieves the size, in screen coordinates, of the content area |
2948 | * of the specified window. If you wish to retrieve the size of the |
2949 | * framebuffer of the window in pixels, see @ref glfwGetFramebufferSize. |
2950 | * |
2951 | * Any or all of the size arguments may be `NULL`. If an error occurs, all |
2952 | * non-`NULL` size arguments will be set to zero. |
2953 | * |
2954 | * @param[in] window The window whose size to retrieve. |
2955 | * @param[out] width Where to store the width, in screen coordinates, of the |
2956 | * content area, or `NULL`. |
2957 | * @param[out] height Where to store the height, in screen coordinates, of the |
2958 | * content area, or `NULL`. |
2959 | * |
2960 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref |
2961 | * GLFW_PLATFORM_ERROR. |
2962 | * |
2963 | * @thread_safety This function must only be called from the main thread. |
2964 | * |
2965 | * @sa @ref window_size |
2966 | * @sa @ref glfwSetWindowSize |
2967 | * |
2968 | * @since Added in version 1.0. |
2969 | * @glfw3 Added window handle parameter. |
2970 | * |
2971 | * @ingroup window |
2972 | */ |
2973 | GLFWAPI void glfwGetWindowSize(GLFWwindow* window, int* width, int* height); |
2974 | |
2975 | /*! @brief Sets the size limits of the specified window. |
2976 | * |
2977 | * This function sets the size limits of the content area of the specified |
2978 | * window. If the window is full screen, the size limits only take effect |
2979 | * once it is made windowed. If the window is not resizable, this function |
2980 | * does nothing. |
2981 | * |
2982 | * The size limits are applied immediately to a windowed mode window and may |
2983 | * cause it to be resized. |
2984 | * |
2985 | * The maximum dimensions must be greater than or equal to the minimum |
2986 | * dimensions and all must be greater than or equal to zero. |
2987 | * |
2988 | * @param[in] window The window to set limits for. |
2989 | * @param[in] minwidth The minimum width, in screen coordinates, of the content |
2990 | * area, or `GLFW_DONT_CARE`. |
2991 | * @param[in] minheight The minimum height, in screen coordinates, of the |
2992 | * content area, or `GLFW_DONT_CARE`. |
2993 | * @param[in] maxwidth The maximum width, in screen coordinates, of the content |
2994 | * area, or `GLFW_DONT_CARE`. |
2995 | * @param[in] maxheight The maximum height, in screen coordinates, of the |
2996 | * content area, or `GLFW_DONT_CARE`. |
2997 | * |
2998 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref |
2999 | * GLFW_INVALID_VALUE and @ref GLFW_PLATFORM_ERROR. |
3000 | * |
3001 | * @remark If you set size limits and an aspect ratio that conflict, the |
3002 | * results are undefined. |
3003 | * |
3004 | * @remark @wayland The size limits will not be applied until the window is |
3005 | * actually resized, either by the user or by the compositor. |
3006 | * |
3007 | * @thread_safety This function must only be called from the main thread. |
3008 | * |
3009 | * @sa @ref window_sizelimits |
3010 | * @sa @ref glfwSetWindowAspectRatio |
3011 | * |
3012 | * @since Added in version 3.2. |
3013 | * |
3014 | * @ingroup window |
3015 | */ |
3016 | GLFWAPI void glfwSetWindowSizeLimits(GLFWwindow* window, int minwidth, int minheight, int maxwidth, int maxheight); |
3017 | |
3018 | /*! @brief Sets the aspect ratio of the specified window. |
3019 | * |
3020 | * This function sets the required aspect ratio of the content area of the |
3021 | * specified window. If the window is full screen, the aspect ratio only takes |
3022 | * effect once it is made windowed. If the window is not resizable, this |
3023 | * function does nothing. |
3024 | * |
3025 | * The aspect ratio is specified as a numerator and a denominator and both |
3026 | * values must be greater than zero. For example, the common 16:9 aspect ratio |
3027 | * is specified as 16 and 9, respectively. |
3028 | * |
3029 | * If the numerator and denominator is set to `GLFW_DONT_CARE` then the aspect |
3030 | * ratio limit is disabled. |
3031 | * |
3032 | * The aspect ratio is applied immediately to a windowed mode window and may |
3033 | * cause it to be resized. |
3034 | * |
3035 | * @param[in] window The window to set limits for. |
3036 | * @param[in] numer The numerator of the desired aspect ratio, or |
3037 | * `GLFW_DONT_CARE`. |
3038 | * @param[in] denom The denominator of the desired aspect ratio, or |
3039 | * `GLFW_DONT_CARE`. |
3040 | * |
3041 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref |
3042 | * GLFW_INVALID_VALUE and @ref GLFW_PLATFORM_ERROR. |
3043 | * |
3044 | * @remark If you set size limits and an aspect ratio that conflict, the |
3045 | * results are undefined. |
3046 | * |
3047 | * @remark @wayland The aspect ratio will not be applied until the window is |
3048 | * actually resized, either by the user or by the compositor. |
3049 | * |
3050 | * @thread_safety This function must only be called from the main thread. |
3051 | * |
3052 | * @sa @ref window_sizelimits |
3053 | * @sa @ref glfwSetWindowSizeLimits |
3054 | * |
3055 | * @since Added in version 3.2. |
3056 | * |
3057 | * @ingroup window |
3058 | */ |
3059 | GLFWAPI void glfwSetWindowAspectRatio(GLFWwindow* window, int numer, int denom); |
3060 | |
3061 | /*! @brief Sets the size of the content area of the specified window. |
3062 | * |
3063 | * This function sets the size, in screen coordinates, of the content area of |
3064 | * the specified window. |
3065 | * |
3066 | * For full screen windows, this function updates the resolution of its desired |
3067 | * video mode and switches to the video mode closest to it, without affecting |
3068 | * the window's context. As the context is unaffected, the bit depths of the |
3069 | * framebuffer remain unchanged. |
3070 | * |
3071 | * If you wish to update the refresh rate of the desired video mode in addition |
3072 | * to its resolution, see @ref glfwSetWindowMonitor. |
3073 | * |
3074 | * The window manager may put limits on what sizes are allowed. GLFW cannot |
3075 | * and should not override these limits. |
3076 | * |
3077 | * @param[in] window The window to resize. |
3078 | * @param[in] width The desired width, in screen coordinates, of the window |
3079 | * content area. |
3080 | * @param[in] height The desired height, in screen coordinates, of the window |
3081 | * content area. |
3082 | * |
3083 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref |
3084 | * GLFW_PLATFORM_ERROR. |
3085 | * |
3086 | * @remark @wayland A full screen window will not attempt to change the mode, |
3087 | * no matter what the requested size. |
3088 | * |
3089 | * @thread_safety This function must only be called from the main thread. |
3090 | * |
3091 | * @sa @ref window_size |
3092 | * @sa @ref glfwGetWindowSize |
3093 | * @sa @ref glfwSetWindowMonitor |
3094 | * |
3095 | * @since Added in version 1.0. |
3096 | * @glfw3 Added window handle parameter. |
3097 | * |
3098 | * @ingroup window |
3099 | */ |
3100 | GLFWAPI void glfwSetWindowSize(GLFWwindow* window, int width, int height); |
3101 | |
3102 | /*! @brief Retrieves the size of the framebuffer of the specified window. |
3103 | * |
3104 | * This function retrieves the size, in pixels, of the framebuffer of the |
3105 | * specified window. If you wish to retrieve the size of the window in screen |
3106 | * coordinates, see @ref glfwGetWindowSize. |
3107 | * |
3108 | * Any or all of the size arguments may be `NULL`. If an error occurs, all |
3109 | * non-`NULL` size arguments will be set to zero. |
3110 | * |
3111 | * @param[in] window The window whose framebuffer to query. |
3112 | * @param[out] width Where to store the width, in pixels, of the framebuffer, |
3113 | * or `NULL`. |
3114 | * @param[out] height Where to store the height, in pixels, of the framebuffer, |
3115 | * or `NULL`. |
3116 | * |
3117 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref |
3118 | * GLFW_PLATFORM_ERROR. |
3119 | * |
3120 | * @thread_safety This function must only be called from the main thread. |
3121 | * |
3122 | * @sa @ref window_fbsize |
3123 | * @sa @ref glfwSetFramebufferSizeCallback |
3124 | * |
3125 | * @since Added in version 3.0. |
3126 | * |
3127 | * @ingroup window |
3128 | */ |
3129 | GLFWAPI void glfwGetFramebufferSize(GLFWwindow* window, int* width, int* height); |
3130 | |
3131 | /*! @brief Retrieves the size of the frame of the window. |
3132 | * |
3133 | * This function retrieves the size, in screen coordinates, of each edge of the |
3134 | * frame of the specified window. This size includes the title bar, if the |
3135 | * window has one. The size of the frame may vary depending on the |
3136 | * [window-related hints](@ref window_hints_wnd) used to create it. |
3137 | * |
3138 | * Because this function retrieves the size of each window frame edge and not |
3139 | * the offset along a particular coordinate axis, the retrieved values will |
3140 | * always be zero or positive. |
3141 | * |
3142 | * Any or all of the size arguments may be `NULL`. If an error occurs, all |
3143 | * non-`NULL` size arguments will be set to zero. |
3144 | * |
3145 | * @param[in] window The window whose frame size to query. |
3146 | * @param[out] left Where to store the size, in screen coordinates, of the left |
3147 | * edge of the window frame, or `NULL`. |
3148 | * @param[out] top Where to store the size, in screen coordinates, of the top |
3149 | * edge of the window frame, or `NULL`. |
3150 | * @param[out] right Where to store the size, in screen coordinates, of the |
3151 | * right edge of the window frame, or `NULL`. |
3152 | * @param[out] bottom Where to store the size, in screen coordinates, of the |
3153 | * bottom edge of the window frame, or `NULL`. |
3154 | * |
3155 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref |
3156 | * GLFW_PLATFORM_ERROR. |
3157 | * |
3158 | * @thread_safety This function must only be called from the main thread. |
3159 | * |
3160 | * @sa @ref window_size |
3161 | * |
3162 | * @since Added in version 3.1. |
3163 | * |
3164 | * @ingroup window |
3165 | */ |
3166 | GLFWAPI void glfwGetWindowFrameSize(GLFWwindow* window, int* left, int* top, int* right, int* bottom); |
3167 | |
3168 | /*! @brief Retrieves the content scale for the specified window. |
3169 | * |
3170 | * This function retrieves the content scale for the specified window. The |
3171 | * content scale is the ratio between the current DPI and the platform's |
3172 | * default DPI. This is especially important for text and any UI elements. If |
3173 | * the pixel dimensions of your UI scaled by this look appropriate on your |
3174 | * machine then it should appear at a reasonable size on other machines |
3175 | * regardless of their DPI and scaling settings. This relies on the system DPI |
3176 | * and scaling settings being somewhat correct. |
3177 | * |
3178 | * On systems where each monitors can have its own content scale, the window |
3179 | * content scale will depend on which monitor the system considers the window |
3180 | * to be on. |
3181 | * |
3182 | * @param[in] window The window to query. |
3183 | * @param[out] xscale Where to store the x-axis content scale, or `NULL`. |
3184 | * @param[out] yscale Where to store the y-axis content scale, or `NULL`. |
3185 | * |
3186 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref |
3187 | * GLFW_PLATFORM_ERROR. |
3188 | * |
3189 | * @thread_safety This function must only be called from the main thread. |
3190 | * |
3191 | * @sa @ref window_scale |
3192 | * @sa @ref glfwSetWindowContentScaleCallback |
3193 | * @sa @ref glfwGetMonitorContentScale |
3194 | * |
3195 | * @since Added in version 3.3. |
3196 | * |
3197 | * @ingroup window |
3198 | */ |
3199 | GLFWAPI void glfwGetWindowContentScale(GLFWwindow* window, float* xscale, float* yscale); |
3200 | |
3201 | /*! @brief Returns the opacity of the whole window. |
3202 | * |
3203 | * This function returns the opacity of the window, including any decorations. |
3204 | * |
3205 | * The opacity (or alpha) value is a positive finite number between zero and |
3206 | * one, where zero is fully transparent and one is fully opaque. If the system |
3207 | * does not support whole window transparency, this function always returns one. |
3208 | * |
3209 | * The initial opacity value for newly created windows is one. |
3210 | * |
3211 | * @param[in] window The window to query. |
3212 | * @return The opacity value of the specified window. |
3213 | * |
3214 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref |
3215 | * GLFW_PLATFORM_ERROR. |
3216 | * |
3217 | * @thread_safety This function must only be called from the main thread. |
3218 | * |
3219 | * @sa @ref window_transparency |
3220 | * @sa @ref glfwSetWindowOpacity |
3221 | * |
3222 | * @since Added in version 3.3. |
3223 | * |
3224 | * @ingroup window |
3225 | */ |
3226 | GLFWAPI float glfwGetWindowOpacity(GLFWwindow* window); |
3227 | |
3228 | /*! @brief Sets the opacity of the whole window. |
3229 | * |
3230 | * This function sets the opacity of the window, including any decorations. |
3231 | * |
3232 | * The opacity (or alpha) value is a positive finite number between zero and |
3233 | * one, where zero is fully transparent and one is fully opaque. |
3234 | * |
3235 | * The initial opacity value for newly created windows is one. |
3236 | * |
3237 | * A window created with framebuffer transparency may not use whole window |
3238 | * transparency. The results of doing this are undefined. |
3239 | * |
3240 | * @param[in] window The window to set the opacity for. |
3241 | * @param[in] opacity The desired opacity of the specified window. |
3242 | * |
3243 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref |
3244 | * GLFW_PLATFORM_ERROR. |
3245 | * |
3246 | * @thread_safety This function must only be called from the main thread. |
3247 | * |
3248 | * @sa @ref window_transparency |
3249 | * @sa @ref glfwGetWindowOpacity |
3250 | * |
3251 | * @since Added in version 3.3. |
3252 | * |
3253 | * @ingroup window |
3254 | */ |
3255 | GLFWAPI void glfwSetWindowOpacity(GLFWwindow* window, float opacity); |
3256 | |
3257 | /*! @brief Iconifies the specified window. |
3258 | * |
3259 | * This function iconifies (minimizes) the specified window if it was |
3260 | * previously restored. If the window is already iconified, this function does |
3261 | * nothing. |
3262 | * |
3263 | * If the specified window is a full screen window, the original monitor |
3264 | * resolution is restored until the window is restored. |
3265 | * |
3266 | * @param[in] window The window to iconify. |
3267 | * |
3268 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref |
3269 | * GLFW_PLATFORM_ERROR. |
3270 | * |
3271 | * @remark @wayland Once a window is iconified, @ref glfwRestoreWindow won’t |
3272 | * be able to restore it. This is a design decision of the xdg-shell |
3273 | * protocol. |
3274 | * |
3275 | * @thread_safety This function must only be called from the main thread. |
3276 | * |
3277 | * @sa @ref window_iconify |
3278 | * @sa @ref glfwRestoreWindow |
3279 | * @sa @ref glfwMaximizeWindow |
3280 | * |
3281 | * @since Added in version 2.1. |
3282 | * @glfw3 Added window handle parameter. |
3283 | * |
3284 | * @ingroup window |
3285 | */ |
3286 | GLFWAPI void glfwIconifyWindow(GLFWwindow* window); |
3287 | |
3288 | /*! @brief Restores the specified window. |
3289 | * |
3290 | * This function restores the specified window if it was previously iconified |
3291 | * (minimized) or maximized. If the window is already restored, this function |
3292 | * does nothing. |
3293 | * |
3294 | * If the specified window is a full screen window, the resolution chosen for |
3295 | * the window is restored on the selected monitor. |
3296 | * |
3297 | * @param[in] window The window to restore. |
3298 | * |
3299 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref |
3300 | * GLFW_PLATFORM_ERROR. |
3301 | * |
3302 | * @thread_safety This function must only be called from the main thread. |
3303 | * |
3304 | * @sa @ref window_iconify |
3305 | * @sa @ref glfwIconifyWindow |
3306 | * @sa @ref glfwMaximizeWindow |
3307 | * |
3308 | * @since Added in version 2.1. |
3309 | * @glfw3 Added window handle parameter. |
3310 | * |
3311 | * @ingroup window |
3312 | */ |
3313 | GLFWAPI void glfwRestoreWindow(GLFWwindow* window); |
3314 | |
3315 | /*! @brief Maximizes the specified window. |
3316 | * |
3317 | * This function maximizes the specified window if it was previously not |
3318 | * maximized. If the window is already maximized, this function does nothing. |
3319 | * |
3320 | * If the specified window is a full screen window, this function does nothing. |
3321 | * |
3322 | * @param[in] window The window to maximize. |
3323 | * |
3324 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref |
3325 | * GLFW_PLATFORM_ERROR. |
3326 | * |
3327 | * @par Thread Safety |
3328 | * This function may only be called from the main thread. |
3329 | * |
3330 | * @sa @ref window_iconify |
3331 | * @sa @ref glfwIconifyWindow |
3332 | * @sa @ref glfwRestoreWindow |
3333 | * |
3334 | * @since Added in GLFW 3.2. |
3335 | * |
3336 | * @ingroup window |
3337 | */ |
3338 | GLFWAPI void glfwMaximizeWindow(GLFWwindow* window); |
3339 | |
3340 | /*! @brief Makes the specified window visible. |
3341 | * |
3342 | * This function makes the specified window visible if it was previously |
3343 | * hidden. If the window is already visible or is in full screen mode, this |
3344 | * function does nothing. |
3345 | * |
3346 | * By default, windowed mode windows are focused when shown |
3347 | * Set the [GLFW_FOCUS_ON_SHOW](@ref GLFW_FOCUS_ON_SHOW_hint) window hint |
3348 | * to change this behavior for all newly created windows, or change the |
3349 | * behavior for an existing window with @ref glfwSetWindowAttrib. |
3350 | * |
3351 | * @param[in] window The window to make visible. |
3352 | * |
3353 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref |
3354 | * GLFW_PLATFORM_ERROR. |
3355 | * |
3356 | * @thread_safety This function must only be called from the main thread. |
3357 | * |
3358 | * @sa @ref window_hide |
3359 | * @sa @ref glfwHideWindow |
3360 | * |
3361 | * @since Added in version 3.0. |
3362 | * |
3363 | * @ingroup window |
3364 | */ |
3365 | GLFWAPI void glfwShowWindow(GLFWwindow* window); |
3366 | |
3367 | /*! @brief Hides the specified window. |
3368 | * |
3369 | * This function hides the specified window if it was previously visible. If |
3370 | * the window is already hidden or is in full screen mode, this function does |
3371 | * nothing. |
3372 | * |
3373 | * @param[in] window The window to hide. |
3374 | * |
3375 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref |
3376 | * GLFW_PLATFORM_ERROR. |
3377 | * |
3378 | * @thread_safety This function must only be called from the main thread. |
3379 | * |
3380 | * @sa @ref window_hide |
3381 | * @sa @ref glfwShowWindow |
3382 | * |
3383 | * @since Added in version 3.0. |
3384 | * |
3385 | * @ingroup window |
3386 | */ |
3387 | GLFWAPI void glfwHideWindow(GLFWwindow* window); |
3388 | |
3389 | /*! @brief Brings the specified window to front and sets input focus. |
3390 | * |
3391 | * This function brings the specified window to front and sets input focus. |
3392 | * The window should already be visible and not iconified. |
3393 | * |
3394 | * By default, both windowed and full screen mode windows are focused when |
3395 | * initially created. Set the [GLFW_FOCUSED](@ref GLFW_FOCUSED_hint) to |
3396 | * disable this behavior. |
3397 | * |
3398 | * Also by default, windowed mode windows are focused when shown |
3399 | * with @ref glfwShowWindow. Set the |
3400 | * [GLFW_FOCUS_ON_SHOW](@ref GLFW_FOCUS_ON_SHOW_hint) to disable this behavior. |
3401 | * |
3402 | * __Do not use this function__ to steal focus from other applications unless |
3403 | * you are certain that is what the user wants. Focus stealing can be |
3404 | * extremely disruptive. |
3405 | * |
3406 | * For a less disruptive way of getting the user's attention, see |
3407 | * [attention requests](@ref window_attention). |
3408 | * |
3409 | * @param[in] window The window to give input focus. |
3410 | * |
3411 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref |
3412 | * GLFW_PLATFORM_ERROR. |
3413 | * |
3414 | * @remark @wayland It is not possible for an application to bring its windows |
3415 | * to front, this function will always emit @ref GLFW_PLATFORM_ERROR. |
3416 | * |
3417 | * @thread_safety This function must only be called from the main thread. |
3418 | * |
3419 | * @sa @ref window_focus |
3420 | * @sa @ref window_attention |
3421 | * |
3422 | * @since Added in version 3.2. |
3423 | * |
3424 | * @ingroup window |
3425 | */ |
3426 | GLFWAPI void glfwFocusWindow(GLFWwindow* window); |
3427 | |
3428 | /*! @brief Requests user attention to the specified window. |
3429 | * |
3430 | * This function requests user attention to the specified window. On |
3431 | * platforms where this is not supported, attention is requested to the |
3432 | * application as a whole. |
3433 | * |
3434 | * Once the user has given attention, usually by focusing the window or |
3435 | * application, the system will end the request automatically. |
3436 | * |
3437 | * @param[in] window The window to request attention to. |
3438 | * |
3439 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref |
3440 | * GLFW_PLATFORM_ERROR. |
3441 | * |
3442 | * @remark @macos Attention is requested to the application as a whole, not the |
3443 | * specific window. |
3444 | * |
3445 | * @thread_safety This function must only be called from the main thread. |
3446 | * |
3447 | * @sa @ref window_attention |
3448 | * |
3449 | * @since Added in version 3.3. |
3450 | * |
3451 | * @ingroup window |
3452 | */ |
3453 | GLFWAPI void glfwRequestWindowAttention(GLFWwindow* window); |
3454 | |
3455 | /*! @brief Returns the monitor that the window uses for full screen mode. |
3456 | * |
3457 | * This function returns the handle of the monitor that the specified window is |
3458 | * in full screen on. |
3459 | * |
3460 | * @param[in] window The window to query. |
3461 | * @return The monitor, or `NULL` if the window is in windowed mode or an |
3462 | * [error](@ref error_handling) occurred. |
3463 | * |
3464 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. |
3465 | * |
3466 | * @thread_safety This function must only be called from the main thread. |
3467 | * |
3468 | * @sa @ref window_monitor |
3469 | * @sa @ref glfwSetWindowMonitor |
3470 | * |
3471 | * @since Added in version 3.0. |
3472 | * |
3473 | * @ingroup window |
3474 | */ |
3475 | GLFWAPI GLFWmonitor* glfwGetWindowMonitor(GLFWwindow* window); |
3476 | |
3477 | /*! @brief Sets the mode, monitor, video mode and placement of a window. |
3478 | * |
3479 | * This function sets the monitor that the window uses for full screen mode or, |
3480 | * if the monitor is `NULL`, makes it windowed mode. |
3481 | * |
3482 | * When setting a monitor, this function updates the width, height and refresh |
3483 | * rate of the desired video mode and switches to the video mode closest to it. |
3484 | * The window position is ignored when setting a monitor. |
3485 | * |
3486 | * When the monitor is `NULL`, the position, width and height are used to |
3487 | * place the window content area. The refresh rate is ignored when no monitor |
3488 | * is specified. |
3489 | * |
3490 | * If you only wish to update the resolution of a full screen window or the |
3491 | * size of a windowed mode window, see @ref glfwSetWindowSize. |
3492 | * |
3493 | * When a window transitions from full screen to windowed mode, this function |
3494 | * restores any previous window settings such as whether it is decorated, |
3495 | * floating, resizable, has size or aspect ratio limits, etc. |
3496 | * |
3497 | * @param[in] window The window whose monitor, size or video mode to set. |
3498 | * @param[in] monitor The desired monitor, or `NULL` to set windowed mode. |
3499 | * @param[in] xpos The desired x-coordinate of the upper-left corner of the |
3500 | * content area. |
3501 | * @param[in] ypos The desired y-coordinate of the upper-left corner of the |
3502 | * content area. |
3503 | * @param[in] width The desired with, in screen coordinates, of the content |
3504 | * area or video mode. |
3505 | * @param[in] height The desired height, in screen coordinates, of the content |
3506 | * area or video mode. |
3507 | * @param[in] refreshRate The desired refresh rate, in Hz, of the video mode, |
3508 | * or `GLFW_DONT_CARE`. |
3509 | * |
3510 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref |
3511 | * GLFW_PLATFORM_ERROR. |
3512 | * |
3513 | * @remark The OpenGL or OpenGL ES context will not be destroyed or otherwise |
3514 | * affected by any resizing or mode switching, although you may need to update |
3515 | * your viewport if the framebuffer size has changed. |
3516 | * |
3517 | * @remark @wayland The desired window position is ignored, as there is no way |
3518 | * for an application to set this property. |
3519 | * |
3520 | * @remark @wayland Setting the window to full screen will not attempt to |
3521 | * change the mode, no matter what the requested size or refresh rate. |
3522 | * |
3523 | * @thread_safety This function must only be called from the main thread. |
3524 | * |
3525 | * @sa @ref window_monitor |
3526 | * @sa @ref window_full_screen |
3527 | * @sa @ref glfwGetWindowMonitor |
3528 | * @sa @ref glfwSetWindowSize |
3529 | * |
3530 | * @since Added in version 3.2. |
3531 | * |
3532 | * @ingroup window |
3533 | */ |
3534 | GLFWAPI void glfwSetWindowMonitor(GLFWwindow* window, GLFWmonitor* monitor, int xpos, int ypos, int width, int height, int refreshRate); |
3535 | |
3536 | /*! @brief Returns an attribute of the specified window. |
3537 | * |
3538 | * This function returns the value of an attribute of the specified window or |
3539 | * its OpenGL or OpenGL ES context. |
3540 | * |
3541 | * @param[in] window The window to query. |
3542 | * @param[in] attrib The [window attribute](@ref window_attribs) whose value to |
3543 | * return. |
3544 | * @return The value of the attribute, or zero if an |
3545 | * [error](@ref error_handling) occurred. |
3546 | * |
3547 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref |
3548 | * GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR. |
3549 | * |
3550 | * @remark Framebuffer related hints are not window attributes. See @ref |
3551 | * window_attribs_fb for more information. |
3552 | * |
3553 | * @remark Zero is a valid value for many window and context related |
3554 | * attributes so you cannot use a return value of zero as an indication of |
3555 | * errors. However, this function should not fail as long as it is passed |
3556 | * valid arguments and the library has been [initialized](@ref intro_init). |
3557 | * |
3558 | * @thread_safety This function must only be called from the main thread. |
3559 | * |
3560 | * @sa @ref window_attribs |
3561 | * @sa @ref glfwSetWindowAttrib |
3562 | * |
3563 | * @since Added in version 3.0. Replaces `glfwGetWindowParam` and |
3564 | * `glfwGetGLVersion`. |
3565 | * |
3566 | * @ingroup window |
3567 | */ |
3568 | GLFWAPI int glfwGetWindowAttrib(GLFWwindow* window, int attrib); |
3569 | |
3570 | /*! @brief Sets an attribute of the specified window. |
3571 | * |
3572 | * This function sets the value of an attribute of the specified window. |
3573 | * |
3574 | * The supported attributes are [GLFW_DECORATED](@ref GLFW_DECORATED_attrib), |
3575 | * [GLFW_RESIZABLE](@ref GLFW_RESIZABLE_attrib), |
3576 | * [GLFW_FLOATING](@ref GLFW_FLOATING_attrib), |
3577 | * [GLFW_AUTO_ICONIFY](@ref GLFW_AUTO_ICONIFY_attrib) and |
3578 | * [GLFW_FOCUS_ON_SHOW](@ref GLFW_FOCUS_ON_SHOW_attrib). |
3579 | * |
3580 | * Some of these attributes are ignored for full screen windows. The new |
3581 | * value will take effect if the window is later made windowed. |
3582 | * |
3583 | * Some of these attributes are ignored for windowed mode windows. The new |
3584 | * value will take effect if the window is later made full screen. |
3585 | * |
3586 | * @param[in] window The window to set the attribute for. |
3587 | * @param[in] attrib A supported window attribute. |
3588 | * @param[in] value `GLFW_TRUE` or `GLFW_FALSE`. |
3589 | * |
3590 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref |
3591 | * GLFW_INVALID_ENUM, @ref GLFW_INVALID_VALUE and @ref GLFW_PLATFORM_ERROR. |
3592 | * |
3593 | * @remark Calling @ref glfwGetWindowAttrib will always return the latest |
3594 | * value, even if that value is ignored by the current mode of the window. |
3595 | * |
3596 | * @thread_safety This function must only be called from the main thread. |
3597 | * |
3598 | * @sa @ref window_attribs |
3599 | * @sa @ref glfwGetWindowAttrib |
3600 | * |
3601 | * @since Added in version 3.3. |
3602 | * |
3603 | * @ingroup window |
3604 | */ |
3605 | GLFWAPI void glfwSetWindowAttrib(GLFWwindow* window, int attrib, int value); |
3606 | |
3607 | /*! @brief Sets the user pointer of the specified window. |
3608 | * |
3609 | * This function sets the user-defined pointer of the specified window. The |
3610 | * current value is retained until the window is destroyed. The initial value |
3611 | * is `NULL`. |
3612 | * |
3613 | * @param[in] window The window whose pointer to set. |
3614 | * @param[in] pointer The new value. |
3615 | * |
3616 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. |
3617 | * |
3618 | * @thread_safety This function may be called from any thread. Access is not |
3619 | * synchronized. |
3620 | * |
3621 | * @sa @ref window_userptr |
3622 | * @sa @ref glfwGetWindowUserPointer |
3623 | * |
3624 | * @since Added in version 3.0. |
3625 | * |
3626 | * @ingroup window |
3627 | */ |
3628 | GLFWAPI void glfwSetWindowUserPointer(GLFWwindow* window, void* pointer); |
3629 | |
3630 | /*! @brief Returns the user pointer of the specified window. |
3631 | * |
3632 | * This function returns the current value of the user-defined pointer of the |
3633 | * specified window. The initial value is `NULL`. |
3634 | * |
3635 | * @param[in] window The window whose pointer to return. |
3636 | * |
3637 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. |
3638 | * |
3639 | * @thread_safety This function may be called from any thread. Access is not |
3640 | * synchronized. |
3641 | * |
3642 | * @sa @ref window_userptr |
3643 | * @sa @ref glfwSetWindowUserPointer |
3644 | * |
3645 | * @since Added in version 3.0. |
3646 | * |
3647 | * @ingroup window |
3648 | */ |
3649 | GLFWAPI void* glfwGetWindowUserPointer(GLFWwindow* window); |
3650 | |
3651 | /*! @brief Sets the position callback for the specified window. |
3652 | * |
3653 | * This function sets the position callback of the specified window, which is |
3654 | * called when the window is moved. The callback is provided with the |
3655 | * position, in screen coordinates, of the upper-left corner of the content |
3656 | * area of the window. |
3657 | * |
3658 | * @param[in] window The window whose callback to set. |
3659 | * @param[in] callback The new callback, or `NULL` to remove the currently set |
3660 | * callback. |
3661 | * @return The previously set callback, or `NULL` if no callback was set or the |
3662 | * library had not been [initialized](@ref intro_init). |
3663 | * |
3664 | * @callback_signature |
3665 | * @code |
3666 | * void function_name(GLFWwindow* window, int xpos, int ypos) |
3667 | * @endcode |
3668 | * For more information about the callback parameters, see the |
3669 | * [function pointer type](@ref GLFWwindowposfun). |
3670 | * |
3671 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. |
3672 | * |
3673 | * @remark @wayland This callback will never be called, as there is no way for |
3674 | * an application to know its global position. |
3675 | * |
3676 | * @thread_safety This function must only be called from the main thread. |
3677 | * |
3678 | * @sa @ref window_pos |
3679 | * |
3680 | * @since Added in version 3.0. |
3681 | * |
3682 | * @ingroup window |
3683 | */ |
3684 | GLFWAPI GLFWwindowposfun glfwSetWindowPosCallback(GLFWwindow* window, GLFWwindowposfun callback); |
3685 | |
3686 | /*! @brief Sets the size callback for the specified window. |
3687 | * |
3688 | * This function sets the size callback of the specified window, which is |
3689 | * called when the window is resized. The callback is provided with the size, |
3690 | * in screen coordinates, of the content area of the window. |
3691 | * |
3692 | * @param[in] window The window whose callback to set. |
3693 | * @param[in] callback The new callback, or `NULL` to remove the currently set |
3694 | * callback. |
3695 | * @return The previously set callback, or `NULL` if no callback was set or the |
3696 | * library had not been [initialized](@ref intro_init). |
3697 | * |
3698 | * @callback_signature |
3699 | * @code |
3700 | * void function_name(GLFWwindow* window, int width, int height) |
3701 | * @endcode |
3702 | * For more information about the callback parameters, see the |
3703 | * [function pointer type](@ref GLFWwindowsizefun). |
3704 | * |
3705 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. |
3706 | * |
3707 | * @thread_safety This function must only be called from the main thread. |
3708 | * |
3709 | * @sa @ref window_size |
3710 | * |
3711 | * @since Added in version 1.0. |
3712 | * @glfw3 Added window handle parameter and return value. |
3713 | * |
3714 | * @ingroup window |
3715 | */ |
3716 | GLFWAPI GLFWwindowsizefun glfwSetWindowSizeCallback(GLFWwindow* window, GLFWwindowsizefun callback); |
3717 | |
3718 | /*! @brief Sets the close callback for the specified window. |
3719 | * |
3720 | * This function sets the close callback of the specified window, which is |
3721 | * called when the user attempts to close the window, for example by clicking |
3722 | * the close widget in the title bar. |
3723 | * |
3724 | * The close flag is set before this callback is called, but you can modify it |
3725 | * at any time with @ref glfwSetWindowShouldClose. |
3726 | * |
3727 | * The close callback is not triggered by @ref glfwDestroyWindow. |
3728 | * |
3729 | * @param[in] window The window whose callback to set. |
3730 | * @param[in] callback The new callback, or `NULL` to remove the currently set |
3731 | * callback. |
3732 | * @return The previously set callback, or `NULL` if no callback was set or the |
3733 | * library had not been [initialized](@ref intro_init). |
3734 | * |
3735 | * @callback_signature |
3736 | * @code |
3737 | * void function_name(GLFWwindow* window) |
3738 | * @endcode |
3739 | * For more information about the callback parameters, see the |
3740 | * [function pointer type](@ref GLFWwindowclosefun). |
3741 | * |
3742 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. |
3743 | * |
3744 | * @remark @macos Selecting Quit from the application menu will trigger the |
3745 | * close callback for all windows. |
3746 | * |
3747 | * @thread_safety This function must only be called from the main thread. |
3748 | * |
3749 | * @sa @ref window_close |
3750 | * |
3751 | * @since Added in version 2.5. |
3752 | * @glfw3 Added window handle parameter and return value. |
3753 | * |
3754 | * @ingroup window |
3755 | */ |
3756 | GLFWAPI GLFWwindowclosefun glfwSetWindowCloseCallback(GLFWwindow* window, GLFWwindowclosefun callback); |
3757 | |
3758 | /*! @brief Sets the refresh callback for the specified window. |
3759 | * |
3760 | * This function sets the refresh callback of the specified window, which is |
3761 | * called when the content area of the window needs to be redrawn, for example |
3762 | * if the window has been exposed after having been covered by another window. |
3763 | * |
3764 | * On compositing window systems such as Aero, Compiz, Aqua or Wayland, where |
3765 | * the window contents are saved off-screen, this callback may be called only |
3766 | * very infrequently or never at all. |
3767 | * |
3768 | * @param[in] window The window whose callback to set. |
3769 | * @param[in] callback The new callback, or `NULL` to remove the currently set |
3770 | * callback. |
3771 | * @return The previously set callback, or `NULL` if no callback was set or the |
3772 | * library had not been [initialized](@ref intro_init). |
3773 | * |
3774 | * @callback_signature |
3775 | * @code |
3776 | * void function_name(GLFWwindow* window); |
3777 | * @endcode |
3778 | * For more information about the callback parameters, see the |
3779 | * [function pointer type](@ref GLFWwindowrefreshfun). |
3780 | * |
3781 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. |
3782 | * |
3783 | * @thread_safety This function must only be called from the main thread. |
3784 | * |
3785 | * @sa @ref window_refresh |
3786 | * |
3787 | * @since Added in version 2.5. |
3788 | * @glfw3 Added window handle parameter and return value. |
3789 | * |
3790 | * @ingroup window |
3791 | */ |
3792 | GLFWAPI GLFWwindowrefreshfun glfwSetWindowRefreshCallback(GLFWwindow* window, GLFWwindowrefreshfun callback); |
3793 | |
3794 | /*! @brief Sets the focus callback for the specified window. |
3795 | * |
3796 | * This function sets the focus callback of the specified window, which is |
3797 | * called when the window gains or loses input focus. |
3798 | * |
3799 | * After the focus callback is called for a window that lost input focus, |
3800 | * synthetic key and mouse button release events will be generated for all such |
3801 | * that had been pressed. For more information, see @ref glfwSetKeyCallback |
3802 | * and @ref glfwSetMouseButtonCallback. |
3803 | * |
3804 | * @param[in] window The window whose callback to set. |
3805 | * @param[in] callback The new callback, or `NULL` to remove the currently set |
3806 | * callback. |
3807 | * @return The previously set callback, or `NULL` if no callback was set or the |
3808 | * library had not been [initialized](@ref intro_init). |
3809 | * |
3810 | * @callback_signature |
3811 | * @code |
3812 | * void function_name(GLFWwindow* window, int focused) |
3813 | * @endcode |
3814 | * For more information about the callback parameters, see the |
3815 | * [function pointer type](@ref GLFWwindowfocusfun). |
3816 | * |
3817 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. |
3818 | * |
3819 | * @thread_safety This function must only be called from the main thread. |
3820 | * |
3821 | * @sa @ref window_focus |
3822 | * |
3823 | * @since Added in version 3.0. |
3824 | * |
3825 | * @ingroup window |
3826 | */ |
3827 | GLFWAPI GLFWwindowfocusfun glfwSetWindowFocusCallback(GLFWwindow* window, GLFWwindowfocusfun callback); |
3828 | |
3829 | /*! @brief Sets the iconify callback for the specified window. |
3830 | * |
3831 | * This function sets the iconification callback of the specified window, which |
3832 | * is called when the window is iconified or restored. |
3833 | * |
3834 | * @param[in] window The window whose callback to set. |
3835 | * @param[in] callback The new callback, or `NULL` to remove the currently set |
3836 | * callback. |
3837 | * @return The previously set callback, or `NULL` if no callback was set or the |
3838 | * library had not been [initialized](@ref intro_init). |
3839 | * |
3840 | * @callback_signature |
3841 | * @code |
3842 | * void function_name(GLFWwindow* window, int iconified) |
3843 | * @endcode |
3844 | * For more information about the callback parameters, see the |
3845 | * [function pointer type](@ref GLFWwindowiconifyfun). |
3846 | * |
3847 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. |
3848 | * |
3849 | * @thread_safety This function must only be called from the main thread. |
3850 | * |
3851 | * @sa @ref window_iconify |
3852 | * |
3853 | * @since Added in version 3.0. |
3854 | * |
3855 | * @ingroup window |
3856 | */ |
3857 | GLFWAPI GLFWwindowiconifyfun glfwSetWindowIconifyCallback(GLFWwindow* window, GLFWwindowiconifyfun callback); |
3858 | |
3859 | /*! @brief Sets the maximize callback for the specified window. |
3860 | * |
3861 | * This function sets the maximization callback of the specified window, which |
3862 | * is called when the window is maximized or restored. |
3863 | * |
3864 | * @param[in] window The window whose callback to set. |
3865 | * @param[in] callback The new callback, or `NULL` to remove the currently set |
3866 | * callback. |
3867 | * @return The previously set callback, or `NULL` if no callback was set or the |
3868 | * library had not been [initialized](@ref intro_init). |
3869 | * |
3870 | * @callback_signature |
3871 | * @code |
3872 | * void function_name(GLFWwindow* window, int maximized) |
3873 | * @endcode |
3874 | * For more information about the callback parameters, see the |
3875 | * [function pointer type](@ref GLFWwindowmaximizefun). |
3876 | * |
3877 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. |
3878 | * |
3879 | * @thread_safety This function must only be called from the main thread. |
3880 | * |
3881 | * @sa @ref window_maximize |
3882 | * |
3883 | * @since Added in version 3.3. |
3884 | * |
3885 | * @ingroup window |
3886 | */ |
3887 | GLFWAPI GLFWwindowmaximizefun glfwSetWindowMaximizeCallback(GLFWwindow* window, GLFWwindowmaximizefun callback); |
3888 | |
3889 | /*! @brief Sets the framebuffer resize callback for the specified window. |
3890 | * |
3891 | * This function sets the framebuffer resize callback of the specified window, |
3892 | * which is called when the framebuffer of the specified window is resized. |
3893 | * |
3894 | * @param[in] window The window whose callback to set. |
3895 | * @param[in] callback The new callback, or `NULL` to remove the currently set |
3896 | * callback. |
3897 | * @return The previously set callback, or `NULL` if no callback was set or the |
3898 | * library had not been [initialized](@ref intro_init). |
3899 | * |
3900 | * @callback_signature |
3901 | * @code |
3902 | * void function_name(GLFWwindow* window, int width, int height) |
3903 | * @endcode |
3904 | * For more information about the callback parameters, see the |
3905 | * [function pointer type](@ref GLFWframebuffersizefun). |
3906 | * |
3907 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. |
3908 | * |
3909 | * @thread_safety This function must only be called from the main thread. |
3910 | * |
3911 | * @sa @ref window_fbsize |
3912 | * |
3913 | * @since Added in version 3.0. |
3914 | * |
3915 | * @ingroup window |
3916 | */ |
3917 | GLFWAPI GLFWframebuffersizefun glfwSetFramebufferSizeCallback(GLFWwindow* window, GLFWframebuffersizefun callback); |
3918 | |
3919 | /*! @brief Sets the window content scale callback for the specified window. |
3920 | * |
3921 | * This function sets the window content scale callback of the specified window, |
3922 | * which is called when the content scale of the specified window changes. |
3923 | * |
3924 | * @param[in] window The window whose callback to set. |
3925 | * @param[in] callback The new callback, or `NULL` to remove the currently set |
3926 | * callback. |
3927 | * @return The previously set callback, or `NULL` if no callback was set or the |
3928 | * library had not been [initialized](@ref intro_init). |
3929 | * |
3930 | * @callback_signature |
3931 | * @code |
3932 | * void function_name(GLFWwindow* window, float xscale, float yscale) |
3933 | * @endcode |
3934 | * For more information about the callback parameters, see the |
3935 | * [function pointer type](@ref GLFWwindowcontentscalefun). |
3936 | * |
3937 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. |
3938 | * |
3939 | * @thread_safety This function must only be called from the main thread. |
3940 | * |
3941 | * @sa @ref window_scale |
3942 | * @sa @ref glfwGetWindowContentScale |
3943 | * |
3944 | * @since Added in version 3.3. |
3945 | * |
3946 | * @ingroup window |
3947 | */ |
3948 | GLFWAPI GLFWwindowcontentscalefun glfwSetWindowContentScaleCallback(GLFWwindow* window, GLFWwindowcontentscalefun callback); |
3949 | |
3950 | /*! @brief Processes all pending events. |
3951 | * |
3952 | * This function processes only those events that are already in the event |
3953 | * queue and then returns immediately. Processing events will cause the window |
3954 | * and input callbacks associated with those events to be called. |
3955 | * |
3956 | * On some platforms, a window move, resize or menu operation will cause event |
3957 | * processing to block. This is due to how event processing is designed on |
3958 | * those platforms. You can use the |
3959 | * [window refresh callback](@ref window_refresh) to redraw the contents of |
3960 | * your window when necessary during such operations. |
3961 | * |
3962 | * Do not assume that callbacks you set will _only_ be called in response to |
3963 | * event processing functions like this one. While it is necessary to poll for |
3964 | * events, window systems that require GLFW to register callbacks of its own |
3965 | * can pass events to GLFW in response to many window system function calls. |
3966 | * GLFW will pass those events on to the application callbacks before |
3967 | * returning. |
3968 | * |
3969 | * Event processing is not required for joystick input to work. |
3970 | * |
3971 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref |
3972 | * GLFW_PLATFORM_ERROR. |
3973 | * |
3974 | * @reentrancy This function must not be called from a callback. |
3975 | * |
3976 | * @thread_safety This function must only be called from the main thread. |
3977 | * |
3978 | * @sa @ref events |
3979 | * @sa @ref glfwWaitEvents |
3980 | * @sa @ref glfwWaitEventsTimeout |
3981 | * |
3982 | * @since Added in version 1.0. |
3983 | * |
3984 | * @ingroup window |
3985 | */ |
3986 | GLFWAPI void glfwPollEvents(void); |
3987 | |
3988 | /*! @brief Waits until events are queued and processes them. |
3989 | * |
3990 | * This function puts the calling thread to sleep until at least one event is |
3991 | * available in the event queue. Once one or more events are available, |
3992 | * it behaves exactly like @ref glfwPollEvents, i.e. the events in the queue |
3993 | * are processed and the function then returns immediately. Processing events |
3994 | * will cause the window and input callbacks associated with those events to be |
3995 | * called. |
3996 | * |
3997 | * Since not all events are associated with callbacks, this function may return |
3998 | * without a callback having been called even if you are monitoring all |
3999 | * callbacks. |
4000 | * |
4001 | * On some platforms, a window move, resize or menu operation will cause event |
4002 | * processing to block. This is due to how event processing is designed on |
4003 | * those platforms. You can use the |
4004 | * [window refresh callback](@ref window_refresh) to redraw the contents of |
4005 | * your window when necessary during such operations. |
4006 | * |
4007 | * Do not assume that callbacks you set will _only_ be called in response to |
4008 | * event processing functions like this one. While it is necessary to poll for |
4009 | * events, window systems that require GLFW to register callbacks of its own |
4010 | * can pass events to GLFW in response to many window system function calls. |
4011 | * GLFW will pass those events on to the application callbacks before |
4012 | * returning. |
4013 | * |
4014 | * Event processing is not required for joystick input to work. |
4015 | * |
4016 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref |
4017 | * GLFW_PLATFORM_ERROR. |
4018 | * |
4019 | * @reentrancy This function must not be called from a callback. |
4020 | * |
4021 | * @thread_safety This function must only be called from the main thread. |
4022 | * |
4023 | * @sa @ref events |
4024 | * @sa @ref glfwPollEvents |
4025 | * @sa @ref glfwWaitEventsTimeout |
4026 | * |
4027 | * @since Added in version 2.5. |
4028 | * |
4029 | * @ingroup window |
4030 | */ |
4031 | GLFWAPI void glfwWaitEvents(void); |
4032 | |
4033 | /*! @brief Waits with timeout until events are queued and processes them. |
4034 | * |
4035 | * This function puts the calling thread to sleep until at least one event is |
4036 | * available in the event queue, or until the specified timeout is reached. If |
4037 | * one or more events are available, it behaves exactly like @ref |
4038 | * glfwPollEvents, i.e. the events in the queue are processed and the function |
4039 | * then returns immediately. Processing events will cause the window and input |
4040 | * callbacks associated with those events to be called. |
4041 | * |
4042 | * The timeout value must be a positive finite number. |
4043 | * |
4044 | * Since not all events are associated with callbacks, this function may return |
4045 | * without a callback having been called even if you are monitoring all |
4046 | * callbacks. |
4047 | * |
4048 | * On some platforms, a window move, resize or menu operation will cause event |
4049 | * processing to block. This is due to how event processing is designed on |
4050 | * those platforms. You can use the |
4051 | * [window refresh callback](@ref window_refresh) to redraw the contents of |
4052 | * your window when necessary during such operations. |
4053 | * |
4054 | * Do not assume that callbacks you set will _only_ be called in response to |
4055 | * event processing functions like this one. While it is necessary to poll for |
4056 | * events, window systems that require GLFW to register callbacks of its own |
4057 | * can pass events to GLFW in response to many window system function calls. |
4058 | * GLFW will pass those events on to the application callbacks before |
4059 | * returning. |
4060 | * |
4061 | * Event processing is not required for joystick input to work. |
4062 | * |
4063 | * @param[in] timeout The maximum amount of time, in seconds, to wait. |
4064 | * |
4065 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref |
4066 | * GLFW_INVALID_VALUE and @ref GLFW_PLATFORM_ERROR. |
4067 | * |
4068 | * @reentrancy This function must not be called from a callback. |
4069 | * |
4070 | * @thread_safety This function must only be called from the main thread. |
4071 | * |
4072 | * @sa @ref events |
4073 | * @sa @ref glfwPollEvents |
4074 | * @sa @ref glfwWaitEvents |
4075 | * |
4076 | * @since Added in version 3.2. |
4077 | * |
4078 | * @ingroup window |
4079 | */ |
4080 | GLFWAPI void glfwWaitEventsTimeout(double timeout); |
4081 | |
4082 | /*! @brief Posts an empty event to the event queue. |
4083 | * |
4084 | * This function posts an empty event from the current thread to the event |
4085 | * queue, causing @ref glfwWaitEvents or @ref glfwWaitEventsTimeout to return. |
4086 | * |
4087 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref |
4088 | * GLFW_PLATFORM_ERROR. |
4089 | * |
4090 | * @thread_safety This function may be called from any thread. |
4091 | * |
4092 | * @sa @ref events |
4093 | * @sa @ref glfwWaitEvents |
4094 | * @sa @ref glfwWaitEventsTimeout |
4095 | * |
4096 | * @since Added in version 3.1. |
4097 | * |
4098 | * @ingroup window |
4099 | */ |
4100 | GLFWAPI void glfwPostEmptyEvent(void); |
4101 | |
4102 | /*! @brief Returns the value of an input option for the specified window. |
4103 | * |
4104 | * This function returns the value of an input option for the specified window. |
4105 | * The mode must be one of @ref GLFW_CURSOR, @ref GLFW_STICKY_KEYS, |
4106 | * @ref GLFW_STICKY_MOUSE_BUTTONS, @ref GLFW_LOCK_KEY_MODS or |
4107 | * @ref GLFW_RAW_MOUSE_MOTION. |
4108 | * |
4109 | * @param[in] window The window to query. |
4110 | * @param[in] mode One of `GLFW_CURSOR`, `GLFW_STICKY_KEYS`, |
4111 | * `GLFW_STICKY_MOUSE_BUTTONS`, `GLFW_LOCK_KEY_MODS` or |
4112 | * `GLFW_RAW_MOUSE_MOTION`. |
4113 | * |
4114 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref |
4115 | * GLFW_INVALID_ENUM. |
4116 | * |
4117 | * @thread_safety This function must only be called from the main thread. |
4118 | * |
4119 | * @sa @ref glfwSetInputMode |
4120 | * |
4121 | * @since Added in version 3.0. |
4122 | * |
4123 | * @ingroup input |
4124 | */ |
4125 | GLFWAPI int glfwGetInputMode(GLFWwindow* window, int mode); |
4126 | |
4127 | /*! @brief Sets an input option for the specified window. |
4128 | * |
4129 | * This function sets an input mode option for the specified window. The mode |
4130 | * must be one of @ref GLFW_CURSOR, @ref GLFW_STICKY_KEYS, |
4131 | * @ref GLFW_STICKY_MOUSE_BUTTONS, @ref GLFW_LOCK_KEY_MODS or |
4132 | * @ref GLFW_RAW_MOUSE_MOTION. |
4133 | * |
4134 | * If the mode is `GLFW_CURSOR`, the value must be one of the following cursor |
4135 | * modes: |
4136 | * - `GLFW_CURSOR_NORMAL` makes the cursor visible and behaving normally. |
4137 | * - `GLFW_CURSOR_HIDDEN` makes the cursor invisible when it is over the |
4138 | * content area of the window but does not restrict the cursor from leaving. |
4139 | * - `GLFW_CURSOR_DISABLED` hides and grabs the cursor, providing virtual |
4140 | * and unlimited cursor movement. This is useful for implementing for |
4141 | * example 3D camera controls. |
4142 | * |
4143 | * If the mode is `GLFW_STICKY_KEYS`, the value must be either `GLFW_TRUE` to |
4144 | * enable sticky keys, or `GLFW_FALSE` to disable it. If sticky keys are |
4145 | * enabled, a key press will ensure that @ref glfwGetKey returns `GLFW_PRESS` |
4146 | * the next time it is called even if the key had been released before the |
4147 | * call. This is useful when you are only interested in whether keys have been |
4148 | * pressed but not when or in which order. |
4149 | * |
4150 | * If the mode is `GLFW_STICKY_MOUSE_BUTTONS`, the value must be either |
4151 | * `GLFW_TRUE` to enable sticky mouse buttons, or `GLFW_FALSE` to disable it. |
4152 | * If sticky mouse buttons are enabled, a mouse button press will ensure that |
4153 | * @ref glfwGetMouseButton returns `GLFW_PRESS` the next time it is called even |
4154 | * if the mouse button had been released before the call. This is useful when |
4155 | * you are only interested in whether mouse buttons have been pressed but not |
4156 | * when or in which order. |
4157 | * |
4158 | * If the mode is `GLFW_LOCK_KEY_MODS`, the value must be either `GLFW_TRUE` to |
4159 | * enable lock key modifier bits, or `GLFW_FALSE` to disable them. If enabled, |
4160 | * callbacks that receive modifier bits will also have the @ref |
4161 | * GLFW_MOD_CAPS_LOCK bit set when the event was generated with Caps Lock on, |
4162 | * and the @ref GLFW_MOD_NUM_LOCK bit when Num Lock was on. |
4163 | * |
4164 | * If the mode is `GLFW_RAW_MOUSE_MOTION`, the value must be either `GLFW_TRUE` |
4165 | * to enable raw (unscaled and unaccelerated) mouse motion when the cursor is |
4166 | * disabled, or `GLFW_FALSE` to disable it. If raw motion is not supported, |
4167 | * attempting to set this will emit @ref GLFW_PLATFORM_ERROR. Call @ref |
4168 | * glfwRawMouseMotionSupported to check for support. |
4169 | * |
4170 | * @param[in] window The window whose input mode to set. |
4171 | * @param[in] mode One of `GLFW_CURSOR`, `GLFW_STICKY_KEYS`, |
4172 | * `GLFW_STICKY_MOUSE_BUTTONS`, `GLFW_LOCK_KEY_MODS` or |
4173 | * `GLFW_RAW_MOUSE_MOTION`. |
4174 | * @param[in] value The new value of the specified input mode. |
4175 | * |
4176 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref |
4177 | * GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR. |
4178 | * |
4179 | * @thread_safety This function must only be called from the main thread. |
4180 | * |
4181 | * @sa @ref glfwGetInputMode |
4182 | * |
4183 | * @since Added in version 3.0. Replaces `glfwEnable` and `glfwDisable`. |
4184 | * |
4185 | * @ingroup input |
4186 | */ |
4187 | GLFWAPI void glfwSetInputMode(GLFWwindow* window, int mode, int value); |
4188 | |
4189 | /*! @brief Returns whether raw mouse motion is supported. |
4190 | * |
4191 | * This function returns whether raw mouse motion is supported on the current |
4192 | * system. This status does not change after GLFW has been initialized so you |
4193 | * only need to check this once. If you attempt to enable raw motion on |
4194 | * a system that does not support it, @ref GLFW_PLATFORM_ERROR will be emitted. |
4195 | * |
4196 | * Raw mouse motion is closer to the actual motion of the mouse across |
4197 | * a surface. It is not affected by the scaling and acceleration applied to |
4198 | * the motion of the desktop cursor. That processing is suitable for a cursor |
4199 | * while raw motion is better for controlling for example a 3D camera. Because |
4200 | * of this, raw mouse motion is only provided when the cursor is disabled. |
4201 | * |
4202 | * @return `GLFW_TRUE` if raw mouse motion is supported on the current machine, |
4203 | * or `GLFW_FALSE` otherwise. |
4204 | * |
4205 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. |
4206 | * |
4207 | * @thread_safety This function must only be called from the main thread. |
4208 | * |
4209 | * @sa @ref raw_mouse_motion |
4210 | * @sa @ref glfwSetInputMode |
4211 | * |
4212 | * @since Added in version 3.3. |
4213 | * |
4214 | * @ingroup input |
4215 | */ |
4216 | GLFWAPI int glfwRawMouseMotionSupported(void); |
4217 | |
4218 | /*! @brief Returns the layout-specific name of the specified printable key. |
4219 | * |
4220 | * This function returns the name of the specified printable key, encoded as |
4221 | * UTF-8. This is typically the character that key would produce without any |
4222 | * modifier keys, intended for displaying key bindings to the user. For dead |
4223 | * keys, it is typically the diacritic it would add to a character. |
4224 | * |
4225 | * __Do not use this function__ for [text input](@ref input_char). You will |
4226 | * break text input for many languages even if it happens to work for yours. |
4227 | * |
4228 | * If the key is `GLFW_KEY_UNKNOWN`, the scancode is used to identify the key, |
4229 | * otherwise the scancode is ignored. If you specify a non-printable key, or |
4230 | * `GLFW_KEY_UNKNOWN` and a scancode that maps to a non-printable key, this |
4231 | * function returns `NULL` but does not emit an error. |
4232 | * |
4233 | * This behavior allows you to always pass in the arguments in the |
4234 | * [key callback](@ref input_key) without modification. |
4235 | * |
4236 | * The printable keys are: |
4237 | * - `GLFW_KEY_APOSTROPHE` |
4238 | * - `GLFW_KEY_COMMA` |
4239 | * - `GLFW_KEY_MINUS` |
4240 | * - `GLFW_KEY_PERIOD` |
4241 | * - `GLFW_KEY_SLASH` |
4242 | * - `GLFW_KEY_SEMICOLON` |
4243 | * - `GLFW_KEY_EQUAL` |
4244 | * - `GLFW_KEY_LEFT_BRACKET` |
4245 | * - `GLFW_KEY_RIGHT_BRACKET` |
4246 | * - `GLFW_KEY_BACKSLASH` |
4247 | * - `GLFW_KEY_WORLD_1` |
4248 | * - `GLFW_KEY_WORLD_2` |
4249 | * - `GLFW_KEY_0` to `GLFW_KEY_9` |
4250 | * - `GLFW_KEY_A` to `GLFW_KEY_Z` |
4251 | * - `GLFW_KEY_KP_0` to `GLFW_KEY_KP_9` |
4252 | * - `GLFW_KEY_KP_DECIMAL` |
4253 | * - `GLFW_KEY_KP_DIVIDE` |
4254 | * - `GLFW_KEY_KP_MULTIPLY` |
4255 | * - `GLFW_KEY_KP_SUBTRACT` |
4256 | * - `GLFW_KEY_KP_ADD` |
4257 | * - `GLFW_KEY_KP_EQUAL` |
4258 | * |
4259 | * Names for printable keys depend on keyboard layout, while names for |
4260 | * non-printable keys are the same across layouts but depend on the application |
4261 | * language and should be localized along with other user interface text. |
4262 | * |
4263 | * @param[in] key The key to query, or `GLFW_KEY_UNKNOWN`. |
4264 | * @param[in] scancode The scancode of the key to query. |
4265 | * @return The UTF-8 encoded, layout-specific name of the key, or `NULL`. |
4266 | * |
4267 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref |
4268 | * GLFW_PLATFORM_ERROR. |
4269 | * |
4270 | * @remark The contents of the returned string may change when a keyboard |
4271 | * layout change event is received. |
4272 | * |
4273 | * @pointer_lifetime The returned string is allocated and freed by GLFW. You |
4274 | * should not free it yourself. It is valid until the library is terminated. |
4275 | * |
4276 | * @thread_safety This function must only be called from the main thread. |
4277 | * |
4278 | * @sa @ref input_key_name |
4279 | * |
4280 | * @since Added in version 3.2. |
4281 | * |
4282 | * @ingroup input |
4283 | */ |
4284 | GLFWAPI const char* glfwGetKeyName(int key, int scancode); |
4285 | |
4286 | /*! @brief Returns the platform-specific scancode of the specified key. |
4287 | * |
4288 | * This function returns the platform-specific scancode of the specified key. |
4289 | * |
4290 | * If the key is `GLFW_KEY_UNKNOWN` or does not exist on the keyboard this |
4291 | * method will return `-1`. |
4292 | * |
4293 | * @param[in] key Any [named key](@ref keys). |
4294 | * @return The platform-specific scancode for the key, or `-1` if an |
4295 | * [error](@ref error_handling) occurred. |
4296 | * |
4297 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref |
4298 | * GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR. |
4299 | * |
4300 | * @thread_safety This function may be called from any thread. |
4301 | * |
4302 | * @sa @ref input_key |
4303 | * |
4304 | * @since Added in version 3.3. |
4305 | * |
4306 | * @ingroup input |
4307 | */ |
4308 | GLFWAPI int glfwGetKeyScancode(int key); |
4309 | |
4310 | /*! @brief Returns the last reported state of a keyboard key for the specified |
4311 | * window. |
4312 | * |
4313 | * This function returns the last state reported for the specified key to the |
4314 | * specified window. The returned state is one of `GLFW_PRESS` or |
4315 | * `GLFW_RELEASE`. The higher-level action `GLFW_REPEAT` is only reported to |
4316 | * the key callback. |
4317 | * |
4318 | * If the @ref GLFW_STICKY_KEYS input mode is enabled, this function returns |
4319 | * `GLFW_PRESS` the first time you call it for a key that was pressed, even if |
4320 | * that key has already been released. |
4321 | * |
4322 | * The key functions deal with physical keys, with [key tokens](@ref keys) |
4323 | * named after their use on the standard US keyboard layout. If you want to |
4324 | * input text, use the Unicode character callback instead. |
4325 | * |
4326 | * The [modifier key bit masks](@ref mods) are not key tokens and cannot be |
4327 | * used with this function. |
4328 | * |
4329 | * __Do not use this function__ to implement [text input](@ref input_char). |
4330 | * |
4331 | * @param[in] window The desired window. |
4332 | * @param[in] key The desired [keyboard key](@ref keys). `GLFW_KEY_UNKNOWN` is |
4333 | * not a valid key for this function. |
4334 | * @return One of `GLFW_PRESS` or `GLFW_RELEASE`. |
4335 | * |
4336 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref |
4337 | * GLFW_INVALID_ENUM. |
4338 | * |
4339 | * @thread_safety This function must only be called from the main thread. |
4340 | * |
4341 | * @sa @ref input_key |
4342 | * |
4343 | * @since Added in version 1.0. |
4344 | * @glfw3 Added window handle parameter. |
4345 | * |
4346 | * @ingroup input |
4347 | */ |
4348 | GLFWAPI int glfwGetKey(GLFWwindow* window, int key); |
4349 | |
4350 | /*! @brief Returns the last reported state of a mouse button for the specified |
4351 | * window. |
4352 | * |
4353 | * This function returns the last state reported for the specified mouse button |
4354 | * to the specified window. The returned state is one of `GLFW_PRESS` or |
4355 | * `GLFW_RELEASE`. |
4356 | * |
4357 | * If the @ref GLFW_STICKY_MOUSE_BUTTONS input mode is enabled, this function |
4358 | * returns `GLFW_PRESS` the first time you call it for a mouse button that was |
4359 | * pressed, even if that mouse button has already been released. |
4360 | * |
4361 | * @param[in] window The desired window. |
4362 | * @param[in] button The desired [mouse button](@ref buttons). |
4363 | * @return One of `GLFW_PRESS` or `GLFW_RELEASE`. |
4364 | * |
4365 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref |
4366 | * GLFW_INVALID_ENUM. |
4367 | * |
4368 | * @thread_safety This function must only be called from the main thread. |
4369 | * |
4370 | * @sa @ref input_mouse_button |
4371 | * |
4372 | * @since Added in version 1.0. |
4373 | * @glfw3 Added window handle parameter. |
4374 | * |
4375 | * @ingroup input |
4376 | */ |
4377 | GLFWAPI int glfwGetMouseButton(GLFWwindow* window, int button); |
4378 | |
4379 | /*! @brief Retrieves the position of the cursor relative to the content area of |
4380 | * the window. |
4381 | * |
4382 | * This function returns the position of the cursor, in screen coordinates, |
4383 | * relative to the upper-left corner of the content area of the specified |
4384 | * window. |
4385 | * |
4386 | * If the cursor is disabled (with `GLFW_CURSOR_DISABLED`) then the cursor |
4387 | * position is unbounded and limited only by the minimum and maximum values of |
4388 | * a `double`. |
4389 | * |
4390 | * The coordinate can be converted to their integer equivalents with the |
4391 | * `floor` function. Casting directly to an integer type works for positive |
4392 | * coordinates, but fails for negative ones. |
4393 | * |
4394 | * Any or all of the position arguments may be `NULL`. If an error occurs, all |
4395 | * non-`NULL` position arguments will be set to zero. |
4396 | * |
4397 | * @param[in] window The desired window. |
4398 | * @param[out] xpos Where to store the cursor x-coordinate, relative to the |
4399 | * left edge of the content area, or `NULL`. |
4400 | * @param[out] ypos Where to store the cursor y-coordinate, relative to the to |
4401 | * top edge of the content area, or `NULL`. |
4402 | * |
4403 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref |
4404 | * GLFW_PLATFORM_ERROR. |
4405 | * |
4406 | * @thread_safety This function must only be called from the main thread. |
4407 | * |
4408 | * @sa @ref cursor_pos |
4409 | * @sa @ref glfwSetCursorPos |
4410 | * |
4411 | * @since Added in version 3.0. Replaces `glfwGetMousePos`. |
4412 | * |
4413 | * @ingroup input |
4414 | */ |
4415 | GLFWAPI void glfwGetCursorPos(GLFWwindow* window, double* xpos, double* ypos); |
4416 | |
4417 | /*! @brief Sets the position of the cursor, relative to the content area of the |
4418 | * window. |
4419 | * |
4420 | * This function sets the position, in screen coordinates, of the cursor |
4421 | * relative to the upper-left corner of the content area of the specified |
4422 | * window. The window must have input focus. If the window does not have |
4423 | * input focus when this function is called, it fails silently. |
4424 | * |
4425 | * __Do not use this function__ to implement things like camera controls. GLFW |
4426 | * already provides the `GLFW_CURSOR_DISABLED` cursor mode that hides the |
4427 | * cursor, transparently re-centers it and provides unconstrained cursor |
4428 | * motion. See @ref glfwSetInputMode for more information. |
4429 | * |
4430 | * If the cursor mode is `GLFW_CURSOR_DISABLED` then the cursor position is |
4431 | * unconstrained and limited only by the minimum and maximum values of |
4432 | * a `double`. |
4433 | * |
4434 | * @param[in] window The desired window. |
4435 | * @param[in] xpos The desired x-coordinate, relative to the left edge of the |
4436 | * content area. |
4437 | * @param[in] ypos The desired y-coordinate, relative to the top edge of the |
4438 | * content area. |
4439 | * |
4440 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref |
4441 | * GLFW_PLATFORM_ERROR. |
4442 | * |
4443 | * @remark @wayland This function will only work when the cursor mode is |
4444 | * `GLFW_CURSOR_DISABLED`, otherwise it will do nothing. |
4445 | * |
4446 | * @thread_safety This function must only be called from the main thread. |
4447 | * |
4448 | * @sa @ref cursor_pos |
4449 | * @sa @ref glfwGetCursorPos |
4450 | * |
4451 | * @since Added in version 3.0. Replaces `glfwSetMousePos`. |
4452 | * |
4453 | * @ingroup input |
4454 | */ |
4455 | GLFWAPI void glfwSetCursorPos(GLFWwindow* window, double xpos, double ypos); |
4456 | |
4457 | /*! @brief Creates a custom cursor. |
4458 | * |
4459 | * Creates a new custom cursor image that can be set for a window with @ref |
4460 | * glfwSetCursor. The cursor can be destroyed with @ref glfwDestroyCursor. |
4461 | * Any remaining cursors are destroyed by @ref glfwTerminate. |
4462 | * |
4463 | * The pixels are 32-bit, little-endian, non-premultiplied RGBA, i.e. eight |
4464 | * bits per channel with the red channel first. They are arranged canonically |
4465 | * as packed sequential rows, starting from the top-left corner. |
4466 | * |
4467 | * The cursor hotspot is specified in pixels, relative to the upper-left corner |
4468 | * of the cursor image. Like all other coordinate systems in GLFW, the X-axis |
4469 | * points to the right and the Y-axis points down. |
4470 | * |
4471 | * @param[in] image The desired cursor image. |
4472 | * @param[in] xhot The desired x-coordinate, in pixels, of the cursor hotspot. |
4473 | * @param[in] yhot The desired y-coordinate, in pixels, of the cursor hotspot. |
4474 | * @return The handle of the created cursor, or `NULL` if an |
4475 | * [error](@ref error_handling) occurred. |
4476 | * |
4477 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref |
4478 | * GLFW_PLATFORM_ERROR. |
4479 | * |
4480 | * @pointer_lifetime The specified image data is copied before this function |
4481 | * returns. |
4482 | * |
4483 | * @thread_safety This function must only be called from the main thread. |
4484 | * |
4485 | * @sa @ref cursor_object |
4486 | * @sa @ref glfwDestroyCursor |
4487 | * @sa @ref glfwCreateStandardCursor |
4488 | * |
4489 | * @since Added in version 3.1. |
4490 | * |
4491 | * @ingroup input |
4492 | */ |
4493 | GLFWAPI GLFWcursor* glfwCreateCursor(const GLFWimage* image, int xhot, int yhot); |
4494 | |
4495 | /*! @brief Creates a cursor with a standard shape. |
4496 | * |
4497 | * Returns a cursor with a standard shape, that can be set for a window with |
4498 | * @ref glfwSetCursor. The images for these cursors come from the system |
4499 | * cursor theme and their exact appearance will vary between platforms. |
4500 | * |
4501 | * Most of these shapes are guaranteed to exist on every supported platform but |
4502 | * a few may not be present. See the table below for details. |
4503 | * |
4504 | * Cursor shape | Windows | macOS | X11 | Wayland |
4505 | * ------------------------------ | ------- | ----- | ------ | ------- |
4506 | * @ref GLFW_ARROW_CURSOR | Yes | Yes | Yes | Yes |
4507 | * @ref GLFW_IBEAM_CURSOR | Yes | Yes | Yes | Yes |
4508 | * @ref GLFW_CROSSHAIR_CURSOR | Yes | Yes | Yes | Yes |
4509 | * @ref GLFW_POINTING_HAND_CURSOR | Yes | Yes | Yes | Yes |
4510 | * @ref GLFW_RESIZE_EW_CURSOR | Yes | Yes | Yes | Yes |
4511 | * @ref GLFW_RESIZE_NS_CURSOR | Yes | Yes | Yes | Yes |
4512 | * @ref GLFW_RESIZE_NWSE_CURSOR | Yes | Yes<sup>1</sup> | Maybe<sup>2</sup> | Maybe<sup>2</sup> |
4513 | * @ref GLFW_RESIZE_NESW_CURSOR | Yes | Yes<sup>1</sup> | Maybe<sup>2</sup> | Maybe<sup>2</sup> |
4514 | * @ref GLFW_RESIZE_ALL_CURSOR | Yes | Yes | Yes | Yes |
4515 | * @ref GLFW_NOT_ALLOWED_CURSOR | Yes | Yes | Maybe<sup>2</sup> | Maybe<sup>2</sup> |
4516 | * |
4517 | * 1) This uses a private system API and may fail in the future. |
4518 | * |
4519 | * 2) This uses a newer standard that not all cursor themes support. |
4520 | * |
4521 | * If the requested shape is not available, this function emits a @ref |
4522 | * GLFW_CURSOR_UNAVAILABLE error and returns `NULL`. |
4523 | * |
4524 | * @param[in] shape One of the [standard shapes](@ref shapes). |
4525 | * @return A new cursor ready to use or `NULL` if an |
4526 | * [error](@ref error_handling) occurred. |
4527 | * |
4528 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref |
4529 | * GLFW_INVALID_ENUM, @ref GLFW_CURSOR_UNAVAILABLE and @ref |
4530 | * GLFW_PLATFORM_ERROR. |
4531 | * |
4532 | * @thread_safety This function must only be called from the main thread. |
4533 | * |
4534 | * @sa @ref cursor_standard |
4535 | * @sa @ref glfwCreateCursor |
4536 | * |
4537 | * @since Added in version 3.1. |
4538 | * |
4539 | * @ingroup input |
4540 | */ |
4541 | GLFWAPI GLFWcursor* glfwCreateStandardCursor(int shape); |
4542 | |
4543 | /*! @brief Destroys a cursor. |
4544 | * |
4545 | * This function destroys a cursor previously created with @ref |
4546 | * glfwCreateCursor. Any remaining cursors will be destroyed by @ref |
4547 | * glfwTerminate. |
4548 | * |
4549 | * If the specified cursor is current for any window, that window will be |
4550 | * reverted to the default cursor. This does not affect the cursor mode. |
4551 | * |
4552 | * @param[in] cursor The cursor object to destroy. |
4553 | * |
4554 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref |
4555 | * GLFW_PLATFORM_ERROR. |
4556 | * |
4557 | * @reentrancy This function must not be called from a callback. |
4558 | * |
4559 | * @thread_safety This function must only be called from the main thread. |
4560 | * |
4561 | * @sa @ref cursor_object |
4562 | * @sa @ref glfwCreateCursor |
4563 | * |
4564 | * @since Added in version 3.1. |
4565 | * |
4566 | * @ingroup input |
4567 | */ |
4568 | GLFWAPI void glfwDestroyCursor(GLFWcursor* cursor); |
4569 | |
4570 | /*! @brief Sets the cursor for the window. |
4571 | * |
4572 | * This function sets the cursor image to be used when the cursor is over the |
4573 | * content area of the specified window. The set cursor will only be visible |
4574 | * when the [cursor mode](@ref cursor_mode) of the window is |
4575 | * `GLFW_CURSOR_NORMAL`. |
4576 | * |
4577 | * On some platforms, the set cursor may not be visible unless the window also |
4578 | * has input focus. |
4579 | * |
4580 | * @param[in] window The window to set the cursor for. |
4581 | * @param[in] cursor The cursor to set, or `NULL` to switch back to the default |
4582 | * arrow cursor. |
4583 | * |
4584 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref |
4585 | * GLFW_PLATFORM_ERROR. |
4586 | * |
4587 | * @thread_safety This function must only be called from the main thread. |
4588 | * |
4589 | * @sa @ref cursor_object |
4590 | * |
4591 | * @since Added in version 3.1. |
4592 | * |
4593 | * @ingroup input |
4594 | */ |
4595 | GLFWAPI void glfwSetCursor(GLFWwindow* window, GLFWcursor* cursor); |
4596 | |
4597 | /*! @brief Sets the key callback. |
4598 | * |
4599 | * This function sets the key callback of the specified window, which is called |
4600 | * when a key is pressed, repeated or released. |
4601 | * |
4602 | * The key functions deal with physical keys, with layout independent |
4603 | * [key tokens](@ref keys) named after their values in the standard US keyboard |
4604 | * layout. If you want to input text, use the |
4605 | * [character callback](@ref glfwSetCharCallback) instead. |
4606 | * |
4607 | * When a window loses input focus, it will generate synthetic key release |
4608 | * events for all pressed keys. You can tell these events from user-generated |
4609 | * events by the fact that the synthetic ones are generated after the focus |
4610 | * loss event has been processed, i.e. after the |
4611 | * [window focus callback](@ref glfwSetWindowFocusCallback) has been called. |
4612 | * |
4613 | * The scancode of a key is specific to that platform or sometimes even to that |
4614 | * machine. Scancodes are intended to allow users to bind keys that don't have |
4615 | * a GLFW key token. Such keys have `key` set to `GLFW_KEY_UNKNOWN`, their |
4616 | * state is not saved and so it cannot be queried with @ref glfwGetKey. |
4617 | * |
4618 | * Sometimes GLFW needs to generate synthetic key events, in which case the |
4619 | * scancode may be zero. |
4620 | * |
4621 | * @param[in] window The window whose callback to set. |
4622 | * @param[in] callback The new key callback, or `NULL` to remove the currently |
4623 | * set callback. |
4624 | * @return The previously set callback, or `NULL` if no callback was set or the |
4625 | * library had not been [initialized](@ref intro_init). |
4626 | * |
4627 | * @callback_signature |
4628 | * @code |
4629 | * void function_name(GLFWwindow* window, int key, int scancode, int action, int mods) |
4630 | * @endcode |
4631 | * For more information about the callback parameters, see the |
4632 | * [function pointer type](@ref GLFWkeyfun). |
4633 | * |
4634 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. |
4635 | * |
4636 | * @thread_safety This function must only be called from the main thread. |
4637 | * |
4638 | * @sa @ref input_key |
4639 | * |
4640 | * @since Added in version 1.0. |
4641 | * @glfw3 Added window handle parameter and return value. |
4642 | * |
4643 | * @ingroup input |
4644 | */ |
4645 | GLFWAPI GLFWkeyfun glfwSetKeyCallback(GLFWwindow* window, GLFWkeyfun callback); |
4646 | |
4647 | /*! @brief Sets the Unicode character callback. |
4648 | * |
4649 | * This function sets the character callback of the specified window, which is |
4650 | * called when a Unicode character is input. |
4651 | * |
4652 | * The character callback is intended for Unicode text input. As it deals with |
4653 | * characters, it is keyboard layout dependent, whereas the |
4654 | * [key callback](@ref glfwSetKeyCallback) is not. Characters do not map 1:1 |
4655 | * to physical keys, as a key may produce zero, one or more characters. If you |
4656 | * want to know whether a specific physical key was pressed or released, see |
4657 | * the key callback instead. |
4658 | * |
4659 | * The character callback behaves as system text input normally does and will |
4660 | * not be called if modifier keys are held down that would prevent normal text |
4661 | * input on that platform, for example a Super (Command) key on macOS or Alt key |
4662 | * on Windows. |
4663 | * |
4664 | * @param[in] window The window whose callback to set. |
4665 | * @param[in] callback The new callback, or `NULL` to remove the currently set |
4666 | * callback. |
4667 | * @return The previously set callback, or `NULL` if no callback was set or the |
4668 | * library had not been [initialized](@ref intro_init). |
4669 | * |
4670 | * @callback_signature |
4671 | * @code |
4672 | * void function_name(GLFWwindow* window, unsigned int codepoint) |
4673 | * @endcode |
4674 | * For more information about the callback parameters, see the |
4675 | * [function pointer type](@ref GLFWcharfun). |
4676 | * |
4677 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. |
4678 | * |
4679 | * @thread_safety This function must only be called from the main thread. |
4680 | * |
4681 | * @sa @ref input_char |
4682 | * |
4683 | * @since Added in version 2.4. |
4684 | * @glfw3 Added window handle parameter and return value. |
4685 | * |
4686 | * @ingroup input |
4687 | */ |
4688 | GLFWAPI GLFWcharfun glfwSetCharCallback(GLFWwindow* window, GLFWcharfun callback); |
4689 | |
4690 | /*! @brief Sets the Unicode character with modifiers callback. |
4691 | * |
4692 | * This function sets the character with modifiers callback of the specified |
4693 | * window, which is called when a Unicode character is input regardless of what |
4694 | * modifier keys are used. |
4695 | * |
4696 | * The character with modifiers callback is intended for implementing custom |
4697 | * Unicode character input. For regular Unicode text input, see the |
4698 | * [character callback](@ref glfwSetCharCallback). Like the character |
4699 | * callback, the character with modifiers callback deals with characters and is |
4700 | * keyboard layout dependent. Characters do not map 1:1 to physical keys, as |
4701 | * a key may produce zero, one or more characters. If you want to know whether |
4702 | * a specific physical key was pressed or released, see the |
4703 | * [key callback](@ref glfwSetKeyCallback) instead. |
4704 | * |
4705 | * @param[in] window The window whose callback to set. |
4706 | * @param[in] callback The new callback, or `NULL` to remove the currently set |
4707 | * callback. |
4708 | * @return The previously set callback, or `NULL` if no callback was set or an |
4709 | * [error](@ref error_handling) occurred. |
4710 | * |
4711 | * @callback_signature |
4712 | * @code |
4713 | * void function_name(GLFWwindow* window, unsigned int codepoint, int mods) |
4714 | * @endcode |
4715 | * For more information about the callback parameters, see the |
4716 | * [function pointer type](@ref GLFWcharmodsfun). |
4717 | * |
4718 | * @deprecated Scheduled for removal in version 4.0. |
4719 | * |
4720 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. |
4721 | * |
4722 | * @thread_safety This function must only be called from the main thread. |
4723 | * |
4724 | * @sa @ref input_char |
4725 | * |
4726 | * @since Added in version 3.1. |
4727 | * |
4728 | * @ingroup input |
4729 | */ |
4730 | GLFWAPI GLFWcharmodsfun glfwSetCharModsCallback(GLFWwindow* window, GLFWcharmodsfun callback); |
4731 | |
4732 | /*! @brief Sets the mouse button callback. |
4733 | * |
4734 | * This function sets the mouse button callback of the specified window, which |
4735 | * is called when a mouse button is pressed or released. |
4736 | * |
4737 | * When a window loses input focus, it will generate synthetic mouse button |
4738 | * release events for all pressed mouse buttons. You can tell these events |
4739 | * from user-generated events by the fact that the synthetic ones are generated |
4740 | * after the focus loss event has been processed, i.e. after the |
4741 | * [window focus callback](@ref glfwSetWindowFocusCallback) has been called. |
4742 | * |
4743 | * @param[in] window The window whose callback to set. |
4744 | * @param[in] callback The new callback, or `NULL` to remove the currently set |
4745 | * callback. |
4746 | * @return The previously set callback, or `NULL` if no callback was set or the |
4747 | * library had not been [initialized](@ref intro_init). |
4748 | * |
4749 | * @callback_signature |
4750 | * @code |
4751 | * void function_name(GLFWwindow* window, int button, int action, int mods) |
4752 | * @endcode |
4753 | * For more information about the callback parameters, see the |
4754 | * [function pointer type](@ref GLFWmousebuttonfun). |
4755 | * |
4756 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. |
4757 | * |
4758 | * @thread_safety This function must only be called from the main thread. |
4759 | * |
4760 | * @sa @ref input_mouse_button |
4761 | * |
4762 | * @since Added in version 1.0. |
4763 | * @glfw3 Added window handle parameter and return value. |
4764 | * |
4765 | * @ingroup input |
4766 | */ |
4767 | GLFWAPI GLFWmousebuttonfun glfwSetMouseButtonCallback(GLFWwindow* window, GLFWmousebuttonfun callback); |
4768 | |
4769 | /*! @brief Sets the cursor position callback. |
4770 | * |
4771 | * This function sets the cursor position callback of the specified window, |
4772 | * which is called when the cursor is moved. The callback is provided with the |
4773 | * position, in screen coordinates, relative to the upper-left corner of the |
4774 | * content area of the window. |
4775 | * |
4776 | * @param[in] window The window whose callback to set. |
4777 | * @param[in] callback The new callback, or `NULL` to remove the currently set |
4778 | * callback. |
4779 | * @return The previously set callback, or `NULL` if no callback was set or the |
4780 | * library had not been [initialized](@ref intro_init). |
4781 | * |
4782 | * @callback_signature |
4783 | * @code |
4784 | * void function_name(GLFWwindow* window, double xpos, double ypos); |
4785 | * @endcode |
4786 | * For more information about the callback parameters, see the |
4787 | * [function pointer type](@ref GLFWcursorposfun). |
4788 | * |
4789 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. |
4790 | * |
4791 | * @thread_safety This function must only be called from the main thread. |
4792 | * |
4793 | * @sa @ref cursor_pos |
4794 | * |
4795 | * @since Added in version 3.0. Replaces `glfwSetMousePosCallback`. |
4796 | * |
4797 | * @ingroup input |
4798 | */ |
4799 | GLFWAPI GLFWcursorposfun glfwSetCursorPosCallback(GLFWwindow* window, GLFWcursorposfun callback); |
4800 | |
4801 | /*! @brief Sets the cursor enter/leave callback. |
4802 | * |
4803 | * This function sets the cursor boundary crossing callback of the specified |
4804 | * window, which is called when the cursor enters or leaves the content area of |
4805 | * the window. |
4806 | * |
4807 | * @param[in] window The window whose callback to set. |
4808 | * @param[in] callback The new callback, or `NULL` to remove the currently set |
4809 | * callback. |
4810 | * @return The previously set callback, or `NULL` if no callback was set or the |
4811 | * library had not been [initialized](@ref intro_init). |
4812 | * |
4813 | * @callback_signature |
4814 | * @code |
4815 | * void function_name(GLFWwindow* window, int entered) |
4816 | * @endcode |
4817 | * For more information about the callback parameters, see the |
4818 | * [function pointer type](@ref GLFWcursorenterfun). |
4819 | * |
4820 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. |
4821 | * |
4822 | * @thread_safety This function must only be called from the main thread. |
4823 | * |
4824 | * @sa @ref cursor_enter |
4825 | * |
4826 | * @since Added in version 3.0. |
4827 | * |
4828 | * @ingroup input |
4829 | */ |
4830 | GLFWAPI GLFWcursorenterfun glfwSetCursorEnterCallback(GLFWwindow* window, GLFWcursorenterfun callback); |
4831 | |
4832 | /*! @brief Sets the scroll callback. |
4833 | * |
4834 | * This function sets the scroll callback of the specified window, which is |
4835 | * called when a scrolling device is used, such as a mouse wheel or scrolling |
4836 | * area of a touchpad. |
4837 | * |
4838 | * The scroll callback receives all scrolling input, like that from a mouse |
4839 | * wheel or a touchpad scrolling area. |
4840 | * |
4841 | * @param[in] window The window whose callback to set. |
4842 | * @param[in] callback The new scroll callback, or `NULL` to remove the |
4843 | * currently set callback. |
4844 | * @return The previously set callback, or `NULL` if no callback was set or the |
4845 | * library had not been [initialized](@ref intro_init). |
4846 | * |
4847 | * @callback_signature |
4848 | * @code |
4849 | * void function_name(GLFWwindow* window, double xoffset, double yoffset) |
4850 | * @endcode |
4851 | * For more information about the callback parameters, see the |
4852 | * [function pointer type](@ref GLFWscrollfun). |
4853 | * |
4854 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. |
4855 | * |
4856 | * @thread_safety This function must only be called from the main thread. |
4857 | * |
4858 | * @sa @ref scrolling |
4859 | * |
4860 | * @since Added in version 3.0. Replaces `glfwSetMouseWheelCallback`. |
4861 | * |
4862 | * @ingroup input |
4863 | */ |
4864 | GLFWAPI GLFWscrollfun glfwSetScrollCallback(GLFWwindow* window, GLFWscrollfun callback); |
4865 | |
4866 | /*! @brief Sets the path drop callback. |
4867 | * |
4868 | * This function sets the path drop callback of the specified window, which is |
4869 | * called when one or more dragged paths are dropped on the window. |
4870 | * |
4871 | * Because the path array and its strings may have been generated specifically |
4872 | * for that event, they are not guaranteed to be valid after the callback has |
4873 | * returned. If you wish to use them after the callback returns, you need to |
4874 | * make a deep copy. |
4875 | * |
4876 | * @param[in] window The window whose callback to set. |
4877 | * @param[in] callback The new file drop callback, or `NULL` to remove the |
4878 | * currently set callback. |
4879 | * @return The previously set callback, or `NULL` if no callback was set or the |
4880 | * library had not been [initialized](@ref intro_init). |
4881 | * |
4882 | * @callback_signature |
4883 | * @code |
4884 | * void function_name(GLFWwindow* window, int path_count, const char* paths[]) |
4885 | * @endcode |
4886 | * For more information about the callback parameters, see the |
4887 | * [function pointer type](@ref GLFWdropfun). |
4888 | * |
4889 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. |
4890 | * |
4891 | * @remark @wayland File drop is currently unimplemented. |
4892 | * |
4893 | * @thread_safety This function must only be called from the main thread. |
4894 | * |
4895 | * @sa @ref path_drop |
4896 | * |
4897 | * @since Added in version 3.1. |
4898 | * |
4899 | * @ingroup input |
4900 | */ |
4901 | GLFWAPI GLFWdropfun glfwSetDropCallback(GLFWwindow* window, GLFWdropfun callback); |
4902 | |
4903 | /*! @brief Returns whether the specified joystick is present. |
4904 | * |
4905 | * This function returns whether the specified joystick is present. |
4906 | * |
4907 | * There is no need to call this function before other functions that accept |
4908 | * a joystick ID, as they all check for presence before performing any other |
4909 | * work. |
4910 | * |
4911 | * @param[in] jid The [joystick](@ref joysticks) to query. |
4912 | * @return `GLFW_TRUE` if the joystick is present, or `GLFW_FALSE` otherwise. |
4913 | * |
4914 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref |
4915 | * GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR. |
4916 | * |
4917 | * @thread_safety This function must only be called from the main thread. |
4918 | * |
4919 | * @sa @ref joystick |
4920 | * |
4921 | * @since Added in version 3.0. Replaces `glfwGetJoystickParam`. |
4922 | * |
4923 | * @ingroup input |
4924 | */ |
4925 | GLFWAPI int glfwJoystickPresent(int jid); |
4926 | |
4927 | /*! @brief Returns the values of all axes of the specified joystick. |
4928 | * |
4929 | * This function returns the values of all axes of the specified joystick. |
4930 | * Each element in the array is a value between -1.0 and 1.0. |
4931 | * |
4932 | * If the specified joystick is not present this function will return `NULL` |
4933 | * but will not generate an error. This can be used instead of first calling |
4934 | * @ref glfwJoystickPresent. |
4935 | * |
4936 | * @param[in] jid The [joystick](@ref joysticks) to query. |
4937 | * @param[out] count Where to store the number of axis values in the returned |
4938 | * array. This is set to zero if the joystick is not present or an error |
4939 | * occurred. |
4940 | * @return An array of axis values, or `NULL` if the joystick is not present or |
4941 | * an [error](@ref error_handling) occurred. |
4942 | * |
4943 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref |
4944 | * GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR. |
4945 | * |
4946 | * @pointer_lifetime The returned array is allocated and freed by GLFW. You |
4947 | * should not free it yourself. It is valid until the specified joystick is |
4948 | * disconnected or the library is terminated. |
4949 | * |
4950 | * @thread_safety This function must only be called from the main thread. |
4951 | * |
4952 | * @sa @ref joystick_axis |
4953 | * |
4954 | * @since Added in version 3.0. Replaces `glfwGetJoystickPos`. |
4955 | * |
4956 | * @ingroup input |
4957 | */ |
4958 | GLFWAPI const float* glfwGetJoystickAxes(int jid, int* count); |
4959 | |
4960 | /*! @brief Returns the state of all buttons of the specified joystick. |
4961 | * |
4962 | * This function returns the state of all buttons of the specified joystick. |
4963 | * Each element in the array is either `GLFW_PRESS` or `GLFW_RELEASE`. |
4964 | * |
4965 | * For backward compatibility with earlier versions that did not have @ref |
4966 | * glfwGetJoystickHats, the button array also includes all hats, each |
4967 | * represented as four buttons. The hats are in the same order as returned by |
4968 | * __glfwGetJoystickHats__ and are in the order _up_, _right_, _down_ and |
4969 | * _left_. To disable these extra buttons, set the @ref |
4970 | * GLFW_JOYSTICK_HAT_BUTTONS init hint before initialization. |
4971 | * |
4972 | * If the specified joystick is not present this function will return `NULL` |
4973 | * but will not generate an error. This can be used instead of first calling |
4974 | * @ref glfwJoystickPresent. |
4975 | * |
4976 | * @param[in] jid The [joystick](@ref joysticks) to query. |
4977 | * @param[out] count Where to store the number of button states in the returned |
4978 | * array. This is set to zero if the joystick is not present or an error |
4979 | * occurred. |
4980 | * @return An array of button states, or `NULL` if the joystick is not present |
4981 | * or an [error](@ref error_handling) occurred. |
4982 | * |
4983 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref |
4984 | * GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR. |
4985 | * |
4986 | * @pointer_lifetime The returned array is allocated and freed by GLFW. You |
4987 | * should not free it yourself. It is valid until the specified joystick is |
4988 | * disconnected or the library is terminated. |
4989 | * |
4990 | * @thread_safety This function must only be called from the main thread. |
4991 | * |
4992 | * @sa @ref joystick_button |
4993 | * |
4994 | * @since Added in version 2.2. |
4995 | * @glfw3 Changed to return a dynamic array. |
4996 | * |
4997 | * @ingroup input |
4998 | */ |
4999 | GLFWAPI const unsigned char* glfwGetJoystickButtons(int jid, int* count); |
5000 | |
5001 | /*! @brief Returns the state of all hats of the specified joystick. |
5002 | * |
5003 | * This function returns the state of all hats of the specified joystick. |
5004 | * Each element in the array is one of the following values: |
5005 | * |
5006 | * Name | Value |
5007 | * ---- | ----- |
5008 | * `GLFW_HAT_CENTERED` | 0 |
5009 | * `GLFW_HAT_UP` | 1 |
5010 | * `GLFW_HAT_RIGHT` | 2 |
5011 | * `GLFW_HAT_DOWN` | 4 |
5012 | * `GLFW_HAT_LEFT` | 8 |
5013 | * `GLFW_HAT_RIGHT_UP` | `GLFW_HAT_RIGHT` \| `GLFW_HAT_UP` |
5014 | * `GLFW_HAT_RIGHT_DOWN` | `GLFW_HAT_RIGHT` \| `GLFW_HAT_DOWN` |
5015 | * `GLFW_HAT_LEFT_UP` | `GLFW_HAT_LEFT` \| `GLFW_HAT_UP` |
5016 | * `GLFW_HAT_LEFT_DOWN` | `GLFW_HAT_LEFT` \| `GLFW_HAT_DOWN` |
5017 | * |
5018 | * The diagonal directions are bitwise combinations of the primary (up, right, |
5019 | * down and left) directions and you can test for these individually by ANDing |
5020 | * it with the corresponding direction. |
5021 | * |
5022 | * @code |
5023 | * if (hats[2] & GLFW_HAT_RIGHT) |
5024 | * { |
5025 | * // State of hat 2 could be right-up, right or right-down |
5026 | * } |
5027 | * @endcode |
5028 | * |
5029 | * If the specified joystick is not present this function will return `NULL` |
5030 | * but will not generate an error. This can be used instead of first calling |
5031 | * @ref glfwJoystickPresent. |
5032 | * |
5033 | * @param[in] jid The [joystick](@ref joysticks) to query. |
5034 | * @param[out] count Where to store the number of hat states in the returned |
5035 | * array. This is set to zero if the joystick is not present or an error |
5036 | * occurred. |
5037 | * @return An array of hat states, or `NULL` if the joystick is not present |
5038 | * or an [error](@ref error_handling) occurred. |
5039 | * |
5040 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref |
5041 | * GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR. |
5042 | * |
5043 | * @pointer_lifetime The returned array is allocated and freed by GLFW. You |
5044 | * should not free it yourself. It is valid until the specified joystick is |
5045 | * disconnected, this function is called again for that joystick or the library |
5046 | * is terminated. |
5047 | * |
5048 | * @thread_safety This function must only be called from the main thread. |
5049 | * |
5050 | * @sa @ref joystick_hat |
5051 | * |
5052 | * @since Added in version 3.3. |
5053 | * |
5054 | * @ingroup input |
5055 | */ |
5056 | GLFWAPI const unsigned char* glfwGetJoystickHats(int jid, int* count); |
5057 | |
5058 | /*! @brief Returns the name of the specified joystick. |
5059 | * |
5060 | * This function returns the name, encoded as UTF-8, of the specified joystick. |
5061 | * The returned string is allocated and freed by GLFW. You should not free it |
5062 | * yourself. |
5063 | * |
5064 | * If the specified joystick is not present this function will return `NULL` |
5065 | * but will not generate an error. This can be used instead of first calling |
5066 | * @ref glfwJoystickPresent. |
5067 | * |
5068 | * @param[in] jid The [joystick](@ref joysticks) to query. |
5069 | * @return The UTF-8 encoded name of the joystick, or `NULL` if the joystick |
5070 | * is not present or an [error](@ref error_handling) occurred. |
5071 | * |
5072 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref |
5073 | * GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR. |
5074 | * |
5075 | * @pointer_lifetime The returned string is allocated and freed by GLFW. You |
5076 | * should not free it yourself. It is valid until the specified joystick is |
5077 | * disconnected or the library is terminated. |
5078 | * |
5079 | * @thread_safety This function must only be called from the main thread. |
5080 | * |
5081 | * @sa @ref joystick_name |
5082 | * |
5083 | * @since Added in version 3.0. |
5084 | * |
5085 | * @ingroup input |
5086 | */ |
5087 | GLFWAPI const char* glfwGetJoystickName(int jid); |
5088 | |
5089 | /*! @brief Returns the SDL compatible GUID of the specified joystick. |
5090 | * |
5091 | * This function returns the SDL compatible GUID, as a UTF-8 encoded |
5092 | * hexadecimal string, of the specified joystick. The returned string is |
5093 | * allocated and freed by GLFW. You should not free it yourself. |
5094 | * |
5095 | * The GUID is what connects a joystick to a gamepad mapping. A connected |
5096 | * joystick will always have a GUID even if there is no gamepad mapping |
5097 | * assigned to it. |
5098 | * |
5099 | * If the specified joystick is not present this function will return `NULL` |
5100 | * but will not generate an error. This can be used instead of first calling |
5101 | * @ref glfwJoystickPresent. |
5102 | * |
5103 | * The GUID uses the format introduced in SDL 2.0.5. This GUID tries to |
5104 | * uniquely identify the make and model of a joystick but does not identify |
5105 | * a specific unit, e.g. all wired Xbox 360 controllers will have the same |
5106 | * GUID on that platform. The GUID for a unit may vary between platforms |
5107 | * depending on what hardware information the platform specific APIs provide. |
5108 | * |
5109 | * @param[in] jid The [joystick](@ref joysticks) to query. |
5110 | * @return The UTF-8 encoded GUID of the joystick, or `NULL` if the joystick |
5111 | * is not present or an [error](@ref error_handling) occurred. |
5112 | * |
5113 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref |
5114 | * GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR. |
5115 | * |
5116 | * @pointer_lifetime The returned string is allocated and freed by GLFW. You |
5117 | * should not free it yourself. It is valid until the specified joystick is |
5118 | * disconnected or the library is terminated. |
5119 | * |
5120 | * @thread_safety This function must only be called from the main thread. |
5121 | * |
5122 | * @sa @ref gamepad |
5123 | * |
5124 | * @since Added in version 3.3. |
5125 | * |
5126 | * @ingroup input |
5127 | */ |
5128 | GLFWAPI const char* glfwGetJoystickGUID(int jid); |
5129 | |
5130 | /*! @brief Sets the user pointer of the specified joystick. |
5131 | * |
5132 | * This function sets the user-defined pointer of the specified joystick. The |
5133 | * current value is retained until the joystick is disconnected. The initial |
5134 | * value is `NULL`. |
5135 | * |
5136 | * This function may be called from the joystick callback, even for a joystick |
5137 | * that is being disconnected. |
5138 | * |
5139 | * @param[in] jid The joystick whose pointer to set. |
5140 | * @param[in] pointer The new value. |
5141 | * |
5142 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. |
5143 | * |
5144 | * @thread_safety This function may be called from any thread. Access is not |
5145 | * synchronized. |
5146 | * |
5147 | * @sa @ref joystick_userptr |
5148 | * @sa @ref glfwGetJoystickUserPointer |
5149 | * |
5150 | * @since Added in version 3.3. |
5151 | * |
5152 | * @ingroup input |
5153 | */ |
5154 | GLFWAPI void glfwSetJoystickUserPointer(int jid, void* pointer); |
5155 | |
5156 | /*! @brief Returns the user pointer of the specified joystick. |
5157 | * |
5158 | * This function returns the current value of the user-defined pointer of the |
5159 | * specified joystick. The initial value is `NULL`. |
5160 | * |
5161 | * This function may be called from the joystick callback, even for a joystick |
5162 | * that is being disconnected. |
5163 | * |
5164 | * @param[in] jid The joystick whose pointer to return. |
5165 | * |
5166 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. |
5167 | * |
5168 | * @thread_safety This function may be called from any thread. Access is not |
5169 | * synchronized. |
5170 | * |
5171 | * @sa @ref joystick_userptr |
5172 | * @sa @ref glfwSetJoystickUserPointer |
5173 | * |
5174 | * @since Added in version 3.3. |
5175 | * |
5176 | * @ingroup input |
5177 | */ |
5178 | GLFWAPI void* glfwGetJoystickUserPointer(int jid); |
5179 | |
5180 | /*! @brief Returns whether the specified joystick has a gamepad mapping. |
5181 | * |
5182 | * This function returns whether the specified joystick is both present and has |
5183 | * a gamepad mapping. |
5184 | * |
5185 | * If the specified joystick is present but does not have a gamepad mapping |
5186 | * this function will return `GLFW_FALSE` but will not generate an error. Call |
5187 | * @ref glfwJoystickPresent to check if a joystick is present regardless of |
5188 | * whether it has a mapping. |
5189 | * |
5190 | * @param[in] jid The [joystick](@ref joysticks) to query. |
5191 | * @return `GLFW_TRUE` if a joystick is both present and has a gamepad mapping, |
5192 | * or `GLFW_FALSE` otherwise. |
5193 | * |
5194 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref |
5195 | * GLFW_INVALID_ENUM. |
5196 | * |
5197 | * @thread_safety This function must only be called from the main thread. |
5198 | * |
5199 | * @sa @ref gamepad |
5200 | * @sa @ref glfwGetGamepadState |
5201 | * |
5202 | * @since Added in version 3.3. |
5203 | * |
5204 | * @ingroup input |
5205 | */ |
5206 | GLFWAPI int glfwJoystickIsGamepad(int jid); |
5207 | |
5208 | /*! @brief Sets the joystick configuration callback. |
5209 | * |
5210 | * This function sets the joystick configuration callback, or removes the |
5211 | * currently set callback. This is called when a joystick is connected to or |
5212 | * disconnected from the system. |
5213 | * |
5214 | * For joystick connection and disconnection events to be delivered on all |
5215 | * platforms, you need to call one of the [event processing](@ref events) |
5216 | * functions. Joystick disconnection may also be detected and the callback |
5217 | * called by joystick functions. The function will then return whatever it |
5218 | * returns if the joystick is not present. |
5219 | * |
5220 | * @param[in] callback The new callback, or `NULL` to remove the currently set |
5221 | * callback. |
5222 | * @return The previously set callback, or `NULL` if no callback was set or the |
5223 | * library had not been [initialized](@ref intro_init). |
5224 | * |
5225 | * @callback_signature |
5226 | * @code |
5227 | * void function_name(int jid, int event) |
5228 | * @endcode |
5229 | * For more information about the callback parameters, see the |
5230 | * [function pointer type](@ref GLFWjoystickfun). |
5231 | * |
5232 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. |
5233 | * |
5234 | * @thread_safety This function must only be called from the main thread. |
5235 | * |
5236 | * @sa @ref joystick_event |
5237 | * |
5238 | * @since Added in version 3.2. |
5239 | * |
5240 | * @ingroup input |
5241 | */ |
5242 | GLFWAPI GLFWjoystickfun glfwSetJoystickCallback(GLFWjoystickfun callback); |
5243 | |
5244 | /*! @brief Adds the specified SDL_GameControllerDB gamepad mappings. |
5245 | * |
5246 | * This function parses the specified ASCII encoded string and updates the |
5247 | * internal list with any gamepad mappings it finds. This string may |
5248 | * contain either a single gamepad mapping or many mappings separated by |
5249 | * newlines. The parser supports the full format of the `gamecontrollerdb.txt` |
5250 | * source file including empty lines and comments. |
5251 | * |
5252 | * See @ref gamepad_mapping for a description of the format. |
5253 | * |
5254 | * If there is already a gamepad mapping for a given GUID in the internal list, |
5255 | * it will be replaced by the one passed to this function. If the library is |
5256 | * terminated and re-initialized the internal list will revert to the built-in |
5257 | * default. |
5258 | * |
5259 | * @param[in] string The string containing the gamepad mappings. |
5260 | * @return `GLFW_TRUE` if successful, or `GLFW_FALSE` if an |
5261 | * [error](@ref error_handling) occurred. |
5262 | * |
5263 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref |
5264 | * GLFW_INVALID_VALUE. |
5265 | * |
5266 | * @thread_safety This function must only be called from the main thread. |
5267 | * |
5268 | * @sa @ref gamepad |
5269 | * @sa @ref glfwJoystickIsGamepad |
5270 | * @sa @ref glfwGetGamepadName |
5271 | * |
5272 | * @since Added in version 3.3. |
5273 | * |
5274 | * @ingroup input |
5275 | */ |
5276 | GLFWAPI int glfwUpdateGamepadMappings(const char* string); |
5277 | |
5278 | /*! @brief Returns the human-readable gamepad name for the specified joystick. |
5279 | * |
5280 | * This function returns the human-readable name of the gamepad from the |
5281 | * gamepad mapping assigned to the specified joystick. |
5282 | * |
5283 | * If the specified joystick is not present or does not have a gamepad mapping |
5284 | * this function will return `NULL` but will not generate an error. Call |
5285 | * @ref glfwJoystickPresent to check whether it is present regardless of |
5286 | * whether it has a mapping. |
5287 | * |
5288 | * @param[in] jid The [joystick](@ref joysticks) to query. |
5289 | * @return The UTF-8 encoded name of the gamepad, or `NULL` if the |
5290 | * joystick is not present, does not have a mapping or an |
5291 | * [error](@ref error_handling) occurred. |
5292 | * |
5293 | * @pointer_lifetime The returned string is allocated and freed by GLFW. You |
5294 | * should not free it yourself. It is valid until the specified joystick is |
5295 | * disconnected, the gamepad mappings are updated or the library is terminated. |
5296 | * |
5297 | * @thread_safety This function must only be called from the main thread. |
5298 | * |
5299 | * @sa @ref gamepad |
5300 | * @sa @ref glfwJoystickIsGamepad |
5301 | * |
5302 | * @since Added in version 3.3. |
5303 | * |
5304 | * @ingroup input |
5305 | */ |
5306 | GLFWAPI const char* glfwGetGamepadName(int jid); |
5307 | |
5308 | /*! @brief Retrieves the state of the specified joystick remapped as a gamepad. |
5309 | * |
5310 | * This function retrieves the state of the specified joystick remapped to |
5311 | * an Xbox-like gamepad. |
5312 | * |
5313 | * If the specified joystick is not present or does not have a gamepad mapping |
5314 | * this function will return `GLFW_FALSE` but will not generate an error. Call |
5315 | * @ref glfwJoystickPresent to check whether it is present regardless of |
5316 | * whether it has a mapping. |
5317 | * |
5318 | * The Guide button may not be available for input as it is often hooked by the |
5319 | * system or the Steam client. |
5320 | * |
5321 | * Not all devices have all the buttons or axes provided by @ref |
5322 | * GLFWgamepadstate. Unavailable buttons and axes will always report |
5323 | * `GLFW_RELEASE` and 0.0 respectively. |
5324 | * |
5325 | * @param[in] jid The [joystick](@ref joysticks) to query. |
5326 | * @param[out] state The gamepad input state of the joystick. |
5327 | * @return `GLFW_TRUE` if successful, or `GLFW_FALSE` if no joystick is |
5328 | * connected, it has no gamepad mapping or an [error](@ref error_handling) |
5329 | * occurred. |
5330 | * |
5331 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref |
5332 | * GLFW_INVALID_ENUM. |
5333 | * |
5334 | * @thread_safety This function must only be called from the main thread. |
5335 | * |
5336 | * @sa @ref gamepad |
5337 | * @sa @ref glfwUpdateGamepadMappings |
5338 | * @sa @ref glfwJoystickIsGamepad |
5339 | * |
5340 | * @since Added in version 3.3. |
5341 | * |
5342 | * @ingroup input |
5343 | */ |
5344 | GLFWAPI int glfwGetGamepadState(int jid, GLFWgamepadstate* state); |
5345 | |
5346 | /*! @brief Sets the clipboard to the specified string. |
5347 | * |
5348 | * This function sets the system clipboard to the specified, UTF-8 encoded |
5349 | * string. |
5350 | * |
5351 | * @param[in] window Deprecated. Any valid window or `NULL`. |
5352 | * @param[in] string A UTF-8 encoded string. |
5353 | * |
5354 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref |
5355 | * GLFW_PLATFORM_ERROR. |
5356 | * |
5357 | * @pointer_lifetime The specified string is copied before this function |
5358 | * returns. |
5359 | * |
5360 | * @thread_safety This function must only be called from the main thread. |
5361 | * |
5362 | * @sa @ref clipboard |
5363 | * @sa @ref glfwGetClipboardString |
5364 | * |
5365 | * @since Added in version 3.0. |
5366 | * |
5367 | * @ingroup input |
5368 | */ |
5369 | GLFWAPI void glfwSetClipboardString(GLFWwindow* window, const char* string); |
5370 | |
5371 | /*! @brief Returns the contents of the clipboard as a string. |
5372 | * |
5373 | * This function returns the contents of the system clipboard, if it contains |
5374 | * or is convertible to a UTF-8 encoded string. If the clipboard is empty or |
5375 | * if its contents cannot be converted, `NULL` is returned and a @ref |
5376 | * GLFW_FORMAT_UNAVAILABLE error is generated. |
5377 | * |
5378 | * @param[in] window Deprecated. Any valid window or `NULL`. |
5379 | * @return The contents of the clipboard as a UTF-8 encoded string, or `NULL` |
5380 | * if an [error](@ref error_handling) occurred. |
5381 | * |
5382 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref |
5383 | * GLFW_PLATFORM_ERROR. |
5384 | * |
5385 | * @pointer_lifetime The returned string is allocated and freed by GLFW. You |
5386 | * should not free it yourself. It is valid until the next call to @ref |
5387 | * glfwGetClipboardString or @ref glfwSetClipboardString, or until the library |
5388 | * is terminated. |
5389 | * |
5390 | * @thread_safety This function must only be called from the main thread. |
5391 | * |
5392 | * @sa @ref clipboard |
5393 | * @sa @ref glfwSetClipboardString |
5394 | * |
5395 | * @since Added in version 3.0. |
5396 | * |
5397 | * @ingroup input |
5398 | */ |
5399 | GLFWAPI const char* glfwGetClipboardString(GLFWwindow* window); |
5400 | |
5401 | /*! @brief Returns the GLFW time. |
5402 | * |
5403 | * This function returns the current GLFW time, in seconds. Unless the time |
5404 | * has been set using @ref glfwSetTime it measures time elapsed since GLFW was |
5405 | * initialized. |
5406 | * |
5407 | * This function and @ref glfwSetTime are helper functions on top of @ref |
5408 | * glfwGetTimerFrequency and @ref glfwGetTimerValue. |
5409 | * |
5410 | * The resolution of the timer is system dependent, but is usually on the order |
5411 | * of a few micro- or nanoseconds. It uses the highest-resolution monotonic |
5412 | * time source on each supported platform. |
5413 | * |
5414 | * @return The current time, in seconds, or zero if an |
5415 | * [error](@ref error_handling) occurred. |
5416 | * |
5417 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. |
5418 | * |
5419 | * @thread_safety This function may be called from any thread. Reading and |
5420 | * writing of the internal base time is not atomic, so it needs to be |
5421 | * externally synchronized with calls to @ref glfwSetTime. |
5422 | * |
5423 | * @sa @ref time |
5424 | * |
5425 | * @since Added in version 1.0. |
5426 | * |
5427 | * @ingroup input |
5428 | */ |
5429 | GLFWAPI double glfwGetTime(void); |
5430 | |
5431 | /*! @brief Sets the GLFW time. |
5432 | * |
5433 | * This function sets the current GLFW time, in seconds. The value must be |
5434 | * a positive finite number less than or equal to 18446744073.0, which is |
5435 | * approximately 584.5 years. |
5436 | * |
5437 | * This function and @ref glfwGetTime are helper functions on top of @ref |
5438 | * glfwGetTimerFrequency and @ref glfwGetTimerValue. |
5439 | * |
5440 | * @param[in] time The new value, in seconds. |
5441 | * |
5442 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref |
5443 | * GLFW_INVALID_VALUE. |
5444 | * |
5445 | * @remark The upper limit of GLFW time is calculated as |
5446 | * floor((2<sup>64</sup> - 1) / 10<sup>9</sup>) and is due to implementations |
5447 | * storing nanoseconds in 64 bits. The limit may be increased in the future. |
5448 | * |
5449 | * @thread_safety This function may be called from any thread. Reading and |
5450 | * writing of the internal base time is not atomic, so it needs to be |
5451 | * externally synchronized with calls to @ref glfwGetTime. |
5452 | * |
5453 | * @sa @ref time |
5454 | * |
5455 | * @since Added in version 2.2. |
5456 | * |
5457 | * @ingroup input |
5458 | */ |
5459 | GLFWAPI void glfwSetTime(double time); |
5460 | |
5461 | /*! @brief Returns the current value of the raw timer. |
5462 | * |
5463 | * This function returns the current value of the raw timer, measured in |
5464 | * 1 / frequency seconds. To get the frequency, call @ref |
5465 | * glfwGetTimerFrequency. |
5466 | * |
5467 | * @return The value of the timer, or zero if an |
5468 | * [error](@ref error_handling) occurred. |
5469 | * |
5470 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. |
5471 | * |
5472 | * @thread_safety This function may be called from any thread. |
5473 | * |
5474 | * @sa @ref time |
5475 | * @sa @ref glfwGetTimerFrequency |
5476 | * |
5477 | * @since Added in version 3.2. |
5478 | * |
5479 | * @ingroup input |
5480 | */ |
5481 | GLFWAPI uint64_t glfwGetTimerValue(void); |
5482 | |
5483 | /*! @brief Returns the frequency, in Hz, of the raw timer. |
5484 | * |
5485 | * This function returns the frequency, in Hz, of the raw timer. |
5486 | * |
5487 | * @return The frequency of the timer, in Hz, or zero if an |
5488 | * [error](@ref error_handling) occurred. |
5489 | * |
5490 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. |
5491 | * |
5492 | * @thread_safety This function may be called from any thread. |
5493 | * |
5494 | * @sa @ref time |
5495 | * @sa @ref glfwGetTimerValue |
5496 | * |
5497 | * @since Added in version 3.2. |
5498 | * |
5499 | * @ingroup input |
5500 | */ |
5501 | GLFWAPI uint64_t glfwGetTimerFrequency(void); |
5502 | |
5503 | /*! @brief Makes the context of the specified window current for the calling |
5504 | * thread. |
5505 | * |
5506 | * This function makes the OpenGL or OpenGL ES context of the specified window |
5507 | * current on the calling thread. A context must only be made current on |
5508 | * a single thread at a time and each thread can have only a single current |
5509 | * context at a time. |
5510 | * |
5511 | * When moving a context between threads, you must make it non-current on the |
5512 | * old thread before making it current on the new one. |
5513 | * |
5514 | * By default, making a context non-current implicitly forces a pipeline flush. |
5515 | * On machines that support `GL_KHR_context_flush_control`, you can control |
5516 | * whether a context performs this flush by setting the |
5517 | * [GLFW_CONTEXT_RELEASE_BEHAVIOR](@ref GLFW_CONTEXT_RELEASE_BEHAVIOR_hint) |
5518 | * hint. |
5519 | * |
5520 | * The specified window must have an OpenGL or OpenGL ES context. Specifying |
5521 | * a window without a context will generate a @ref GLFW_NO_WINDOW_CONTEXT |
5522 | * error. |
5523 | * |
5524 | * @param[in] window The window whose context to make current, or `NULL` to |
5525 | * detach the current context. |
5526 | * |
5527 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref |
5528 | * GLFW_NO_WINDOW_CONTEXT and @ref GLFW_PLATFORM_ERROR. |
5529 | * |
5530 | * @thread_safety This function may be called from any thread. |
5531 | * |
5532 | * @sa @ref context_current |
5533 | * @sa @ref glfwGetCurrentContext |
5534 | * |
5535 | * @since Added in version 3.0. |
5536 | * |
5537 | * @ingroup context |
5538 | */ |
5539 | GLFWAPI void glfwMakeContextCurrent(GLFWwindow* window); |
5540 | |
5541 | /*! @brief Returns the window whose context is current on the calling thread. |
5542 | * |
5543 | * This function returns the window whose OpenGL or OpenGL ES context is |
5544 | * current on the calling thread. |
5545 | * |
5546 | * @return The window whose context is current, or `NULL` if no window's |
5547 | * context is current. |
5548 | * |
5549 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. |
5550 | * |
5551 | * @thread_safety This function may be called from any thread. |
5552 | * |
5553 | * @sa @ref context_current |
5554 | * @sa @ref glfwMakeContextCurrent |
5555 | * |
5556 | * @since Added in version 3.0. |
5557 | * |
5558 | * @ingroup context |
5559 | */ |
5560 | GLFWAPI GLFWwindow* glfwGetCurrentContext(void); |
5561 | |
5562 | /*! @brief Swaps the front and back buffers of the specified window. |
5563 | * |
5564 | * This function swaps the front and back buffers of the specified window when |
5565 | * rendering with OpenGL or OpenGL ES. If the swap interval is greater than |
5566 | * zero, the GPU driver waits the specified number of screen updates before |
5567 | * swapping the buffers. |
5568 | * |
5569 | * The specified window must have an OpenGL or OpenGL ES context. Specifying |
5570 | * a window without a context will generate a @ref GLFW_NO_WINDOW_CONTEXT |
5571 | * error. |
5572 | * |
5573 | * This function does not apply to Vulkan. If you are rendering with Vulkan, |
5574 | * see `vkQueuePresentKHR` instead. |
5575 | * |
5576 | * @param[in] window The window whose buffers to swap. |
5577 | * |
5578 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref |
5579 | * GLFW_NO_WINDOW_CONTEXT and @ref GLFW_PLATFORM_ERROR. |
5580 | * |
5581 | * @remark __EGL:__ The context of the specified window must be current on the |
5582 | * calling thread. |
5583 | * |
5584 | * @thread_safety This function may be called from any thread. |
5585 | * |
5586 | * @sa @ref buffer_swap |
5587 | * @sa @ref glfwSwapInterval |
5588 | * |
5589 | * @since Added in version 1.0. |
5590 | * @glfw3 Added window handle parameter. |
5591 | * |
5592 | * @ingroup window |
5593 | */ |
5594 | GLFWAPI void glfwSwapBuffers(GLFWwindow* window); |
5595 | |
5596 | /*! @brief Sets the swap interval for the current context. |
5597 | * |
5598 | * This function sets the swap interval for the current OpenGL or OpenGL ES |
5599 | * context, i.e. the number of screen updates to wait from the time @ref |
5600 | * glfwSwapBuffers was called before swapping the buffers and returning. This |
5601 | * is sometimes called _vertical synchronization_, _vertical retrace |
5602 | * synchronization_ or just _vsync_. |
5603 | * |
5604 | * A context that supports either of the `WGL_EXT_swap_control_tear` and |
5605 | * `GLX_EXT_swap_control_tear` extensions also accepts _negative_ swap |
5606 | * intervals, which allows the driver to swap immediately even if a frame |
5607 | * arrives a little bit late. You can check for these extensions with @ref |
5608 | * glfwExtensionSupported. |
5609 | * |
5610 | * A context must be current on the calling thread. Calling this function |
5611 | * without a current context will cause a @ref GLFW_NO_CURRENT_CONTEXT error. |
5612 | * |
5613 | * This function does not apply to Vulkan. If you are rendering with Vulkan, |
5614 | * see the present mode of your swapchain instead. |
5615 | * |
5616 | * @param[in] interval The minimum number of screen updates to wait for |
5617 | * until the buffers are swapped by @ref glfwSwapBuffers. |
5618 | * |
5619 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref |
5620 | * GLFW_NO_CURRENT_CONTEXT and @ref GLFW_PLATFORM_ERROR. |
5621 | * |
5622 | * @remark This function is not called during context creation, leaving the |
5623 | * swap interval set to whatever is the default on that platform. This is done |
5624 | * because some swap interval extensions used by GLFW do not allow the swap |
5625 | * interval to be reset to zero once it has been set to a non-zero value. |
5626 | * |
5627 | * @remark Some GPU drivers do not honor the requested swap interval, either |
5628 | * because of a user setting that overrides the application's request or due to |
5629 | * bugs in the driver. |
5630 | * |
5631 | * @thread_safety This function may be called from any thread. |
5632 | * |
5633 | * @sa @ref buffer_swap |
5634 | * @sa @ref glfwSwapBuffers |
5635 | * |
5636 | * @since Added in version 1.0. |
5637 | * |
5638 | * @ingroup context |
5639 | */ |
5640 | GLFWAPI void glfwSwapInterval(int interval); |
5641 | |
5642 | /*! @brief Returns whether the specified extension is available. |
5643 | * |
5644 | * This function returns whether the specified |
5645 | * [API extension](@ref context_glext) is supported by the current OpenGL or |
5646 | * OpenGL ES context. It searches both for client API extension and context |
5647 | * creation API extensions. |
5648 | * |
5649 | * A context must be current on the calling thread. Calling this function |
5650 | * without a current context will cause a @ref GLFW_NO_CURRENT_CONTEXT error. |
5651 | * |
5652 | * As this functions retrieves and searches one or more extension strings each |
5653 | * call, it is recommended that you cache its results if it is going to be used |
5654 | * frequently. The extension strings will not change during the lifetime of |
5655 | * a context, so there is no danger in doing this. |
5656 | * |
5657 | * This function does not apply to Vulkan. If you are using Vulkan, see @ref |
5658 | * glfwGetRequiredInstanceExtensions, `vkEnumerateInstanceExtensionProperties` |
5659 | * and `vkEnumerateDeviceExtensionProperties` instead. |
5660 | * |
5661 | * @param[in] extension The ASCII encoded name of the extension. |
5662 | * @return `GLFW_TRUE` if the extension is available, or `GLFW_FALSE` |
5663 | * otherwise. |
5664 | * |
5665 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref |
5666 | * GLFW_NO_CURRENT_CONTEXT, @ref GLFW_INVALID_VALUE and @ref |
5667 | * GLFW_PLATFORM_ERROR. |
5668 | * |
5669 | * @thread_safety This function may be called from any thread. |
5670 | * |
5671 | * @sa @ref context_glext |
5672 | * @sa @ref glfwGetProcAddress |
5673 | * |
5674 | * @since Added in version 1.0. |
5675 | * |
5676 | * @ingroup context |
5677 | */ |
5678 | GLFWAPI int glfwExtensionSupported(const char* extension); |
5679 | |
5680 | /*! @brief Returns the address of the specified function for the current |
5681 | * context. |
5682 | * |
5683 | * This function returns the address of the specified OpenGL or OpenGL ES |
5684 | * [core or extension function](@ref context_glext), if it is supported |
5685 | * by the current context. |
5686 | * |
5687 | * A context must be current on the calling thread. Calling this function |
5688 | * without a current context will cause a @ref GLFW_NO_CURRENT_CONTEXT error. |
5689 | * |
5690 | * This function does not apply to Vulkan. If you are rendering with Vulkan, |
5691 | * see @ref glfwGetInstanceProcAddress, `vkGetInstanceProcAddr` and |
5692 | * `vkGetDeviceProcAddr` instead. |
5693 | * |
5694 | * @param[in] procname The ASCII encoded name of the function. |
5695 | * @return The address of the function, or `NULL` if an |
5696 | * [error](@ref error_handling) occurred. |
5697 | * |
5698 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref |
5699 | * GLFW_NO_CURRENT_CONTEXT and @ref GLFW_PLATFORM_ERROR. |
5700 | * |
5701 | * @remark The address of a given function is not guaranteed to be the same |
5702 | * between contexts. |
5703 | * |
5704 | * @remark This function may return a non-`NULL` address despite the |
5705 | * associated version or extension not being available. Always check the |
5706 | * context version or extension string first. |
5707 | * |
5708 | * @pointer_lifetime The returned function pointer is valid until the context |
5709 | * is destroyed or the library is terminated. |
5710 | * |
5711 | * @thread_safety This function may be called from any thread. |
5712 | * |
5713 | * @sa @ref context_glext |
5714 | * @sa @ref glfwExtensionSupported |
5715 | * |
5716 | * @since Added in version 1.0. |
5717 | * |
5718 | * @ingroup context |
5719 | */ |
5720 | GLFWAPI GLFWglproc glfwGetProcAddress(const char* procname); |
5721 | |
5722 | /*! @brief Returns whether the Vulkan loader and an ICD have been found. |
5723 | * |
5724 | * This function returns whether the Vulkan loader and any minimally functional |
5725 | * ICD have been found. |
5726 | * |
5727 | * The availability of a Vulkan loader and even an ICD does not by itself |
5728 | * guarantee that surface creation or even instance creation is possible. |
5729 | * For example, on Fermi systems Nvidia will install an ICD that provides no |
5730 | * actual Vulkan support. Call @ref glfwGetRequiredInstanceExtensions to check |
5731 | * whether the extensions necessary for Vulkan surface creation are available |
5732 | * and @ref glfwGetPhysicalDevicePresentationSupport to check whether a queue |
5733 | * family of a physical device supports image presentation. |
5734 | * |
5735 | * @return `GLFW_TRUE` if Vulkan is minimally available, or `GLFW_FALSE` |
5736 | * otherwise. |
5737 | * |
5738 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. |
5739 | * |
5740 | * @thread_safety This function may be called from any thread. |
5741 | * |
5742 | * @sa @ref vulkan_support |
5743 | * |
5744 | * @since Added in version 3.2. |
5745 | * |
5746 | * @ingroup vulkan |
5747 | */ |
5748 | GLFWAPI int glfwVulkanSupported(void); |
5749 | |
5750 | /*! @brief Returns the Vulkan instance extensions required by GLFW. |
5751 | * |
5752 | * This function returns an array of names of Vulkan instance extensions required |
5753 | * by GLFW for creating Vulkan surfaces for GLFW windows. If successful, the |
5754 | * list will always contain `VK_KHR_surface`, so if you don't require any |
5755 | * additional extensions you can pass this list directly to the |
5756 | * `VkInstanceCreateInfo` struct. |
5757 | * |
5758 | * If Vulkan is not available on the machine, this function returns `NULL` and |
5759 | * generates a @ref GLFW_API_UNAVAILABLE error. Call @ref glfwVulkanSupported |
5760 | * to check whether Vulkan is at least minimally available. |
5761 | * |
5762 | * If Vulkan is available but no set of extensions allowing window surface |
5763 | * creation was found, this function returns `NULL`. You may still use Vulkan |
5764 | * for off-screen rendering and compute work. |
5765 | * |
5766 | * @param[out] count Where to store the number of extensions in the returned |
5767 | * array. This is set to zero if an error occurred. |
5768 | * @return An array of ASCII encoded extension names, or `NULL` if an |
5769 | * [error](@ref error_handling) occurred. |
5770 | * |
5771 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref |
5772 | * GLFW_API_UNAVAILABLE. |
5773 | * |
5774 | * @remark Additional extensions may be required by future versions of GLFW. |
5775 | * You should check if any extensions you wish to enable are already in the |
5776 | * returned array, as it is an error to specify an extension more than once in |
5777 | * the `VkInstanceCreateInfo` struct. |
5778 | * |
5779 | * @remark @macos This function currently supports either the |
5780 | * `VK_MVK_macos_surface` extension from MoltenVK or `VK_EXT_metal_surface` |
5781 | * extension. |
5782 | * |
5783 | * @pointer_lifetime The returned array is allocated and freed by GLFW. You |
5784 | * should not free it yourself. It is guaranteed to be valid only until the |
5785 | * library is terminated. |
5786 | * |
5787 | * @thread_safety This function may be called from any thread. |
5788 | * |
5789 | * @sa @ref vulkan_ext |
5790 | * @sa @ref glfwCreateWindowSurface |
5791 | * |
5792 | * @since Added in version 3.2. |
5793 | * |
5794 | * @ingroup vulkan |
5795 | */ |
5796 | GLFWAPI const char** glfwGetRequiredInstanceExtensions(uint32_t* count); |
5797 | |
5798 | #if defined(VK_VERSION_1_0) |
5799 | |
5800 | /*! @brief Returns the address of the specified Vulkan instance function. |
5801 | * |
5802 | * This function returns the address of the specified Vulkan core or extension |
5803 | * function for the specified instance. If instance is set to `NULL` it can |
5804 | * return any function exported from the Vulkan loader, including at least the |
5805 | * following functions: |
5806 | * |
5807 | * - `vkEnumerateInstanceExtensionProperties` |
5808 | * - `vkEnumerateInstanceLayerProperties` |
5809 | * - `vkCreateInstance` |
5810 | * - `vkGetInstanceProcAddr` |
5811 | * |
5812 | * If Vulkan is not available on the machine, this function returns `NULL` and |
5813 | * generates a @ref GLFW_API_UNAVAILABLE error. Call @ref glfwVulkanSupported |
5814 | * to check whether Vulkan is at least minimally available. |
5815 | * |
5816 | * This function is equivalent to calling `vkGetInstanceProcAddr` with |
5817 | * a platform-specific query of the Vulkan loader as a fallback. |
5818 | * |
5819 | * @param[in] instance The Vulkan instance to query, or `NULL` to retrieve |
5820 | * functions related to instance creation. |
5821 | * @param[in] procname The ASCII encoded name of the function. |
5822 | * @return The address of the function, or `NULL` if an |
5823 | * [error](@ref error_handling) occurred. |
5824 | * |
5825 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref |
5826 | * GLFW_API_UNAVAILABLE. |
5827 | * |
5828 | * @pointer_lifetime The returned function pointer is valid until the library |
5829 | * is terminated. |
5830 | * |
5831 | * @thread_safety This function may be called from any thread. |
5832 | * |
5833 | * @sa @ref vulkan_proc |
5834 | * |
5835 | * @since Added in version 3.2. |
5836 | * |
5837 | * @ingroup vulkan |
5838 | */ |
5839 | GLFWAPI GLFWvkproc glfwGetInstanceProcAddress(VkInstance instance, const char* procname); |
5840 | |
5841 | /*! @brief Returns whether the specified queue family can present images. |
5842 | * |
5843 | * This function returns whether the specified queue family of the specified |
5844 | * physical device supports presentation to the platform GLFW was built for. |
5845 | * |
5846 | * If Vulkan or the required window surface creation instance extensions are |
5847 | * not available on the machine, or if the specified instance was not created |
5848 | * with the required extensions, this function returns `GLFW_FALSE` and |
5849 | * generates a @ref GLFW_API_UNAVAILABLE error. Call @ref glfwVulkanSupported |
5850 | * to check whether Vulkan is at least minimally available and @ref |
5851 | * glfwGetRequiredInstanceExtensions to check what instance extensions are |
5852 | * required. |
5853 | * |
5854 | * @param[in] instance The instance that the physical device belongs to. |
5855 | * @param[in] device The physical device that the queue family belongs to. |
5856 | * @param[in] queuefamily The index of the queue family to query. |
5857 | * @return `GLFW_TRUE` if the queue family supports presentation, or |
5858 | * `GLFW_FALSE` otherwise. |
5859 | * |
5860 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref |
5861 | * GLFW_API_UNAVAILABLE and @ref GLFW_PLATFORM_ERROR. |
5862 | * |
5863 | * @remark @macos This function currently always returns `GLFW_TRUE`, as the |
5864 | * `VK_MVK_macos_surface` extension does not provide |
5865 | * a `vkGetPhysicalDevice*PresentationSupport` type function. |
5866 | * |
5867 | * @thread_safety This function may be called from any thread. For |
5868 | * synchronization details of Vulkan objects, see the Vulkan specification. |
5869 | * |
5870 | * @sa @ref vulkan_present |
5871 | * |
5872 | * @since Added in version 3.2. |
5873 | * |
5874 | * @ingroup vulkan |
5875 | */ |
5876 | GLFWAPI int glfwGetPhysicalDevicePresentationSupport(VkInstance instance, VkPhysicalDevice device, uint32_t queuefamily); |
5877 | |
5878 | /*! @brief Creates a Vulkan surface for the specified window. |
5879 | * |
5880 | * This function creates a Vulkan surface for the specified window. |
5881 | * |
5882 | * If the Vulkan loader or at least one minimally functional ICD were not found, |
5883 | * this function returns `VK_ERROR_INITIALIZATION_FAILED` and generates a @ref |
5884 | * GLFW_API_UNAVAILABLE error. Call @ref glfwVulkanSupported to check whether |
5885 | * Vulkan is at least minimally available. |
5886 | * |
5887 | * If the required window surface creation instance extensions are not |
5888 | * available or if the specified instance was not created with these extensions |
5889 | * enabled, this function returns `VK_ERROR_EXTENSION_NOT_PRESENT` and |
5890 | * generates a @ref GLFW_API_UNAVAILABLE error. Call @ref |
5891 | * glfwGetRequiredInstanceExtensions to check what instance extensions are |
5892 | * required. |
5893 | * |
5894 | * The window surface cannot be shared with another API so the window must |
5895 | * have been created with the [client api hint](@ref GLFW_CLIENT_API_attrib) |
5896 | * set to `GLFW_NO_API` otherwise it generates a @ref GLFW_INVALID_VALUE error |
5897 | * and returns `VK_ERROR_NATIVE_WINDOW_IN_USE_KHR`. |
5898 | * |
5899 | * The window surface must be destroyed before the specified Vulkan instance. |
5900 | * It is the responsibility of the caller to destroy the window surface. GLFW |
5901 | * does not destroy it for you. Call `vkDestroySurfaceKHR` to destroy the |
5902 | * surface. |
5903 | * |
5904 | * @param[in] instance The Vulkan instance to create the surface in. |
5905 | * @param[in] window The window to create the surface for. |
5906 | * @param[in] allocator The allocator to use, or `NULL` to use the default |
5907 | * allocator. |
5908 | * @param[out] surface Where to store the handle of the surface. This is set |
5909 | * to `VK_NULL_HANDLE` if an error occurred. |
5910 | * @return `VK_SUCCESS` if successful, or a Vulkan error code if an |
5911 | * [error](@ref error_handling) occurred. |
5912 | * |
5913 | * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref |
5914 | * GLFW_API_UNAVAILABLE, @ref GLFW_PLATFORM_ERROR and @ref GLFW_INVALID_VALUE |
5915 | * |
5916 | * @remark If an error occurs before the creation call is made, GLFW returns |
5917 | * the Vulkan error code most appropriate for the error. Appropriate use of |
5918 | * @ref glfwVulkanSupported and @ref glfwGetRequiredInstanceExtensions should |
5919 | * eliminate almost all occurrences of these errors. |
5920 | * |
5921 | * @remark @macos This function currently only supports the |
5922 | * `VK_MVK_macos_surface` extension from MoltenVK. |
5923 | * |
5924 | * @remark @macos This function creates and sets a `CAMetalLayer` instance for |
5925 | * the window content view, which is required for MoltenVK to function. |
5926 | * |
5927 | * @thread_safety This function may be called from any thread. For |
5928 | * synchronization details of Vulkan objects, see the Vulkan specification. |
5929 | * |
5930 | * @sa @ref vulkan_surface |
5931 | * @sa @ref glfwGetRequiredInstanceExtensions |
5932 | * |
5933 | * @since Added in version 3.2. |
5934 | * |
5935 | * @ingroup vulkan |
5936 | */ |
5937 | GLFWAPI VkResult glfwCreateWindowSurface(VkInstance instance, GLFWwindow* window, const VkAllocationCallbacks* allocator, VkSurfaceKHR* surface); |
5938 | |
5939 | #endif /*VK_VERSION_1_0*/ |
5940 | |
5941 | |
5942 | /************************************************************************* |
5943 | * Global definition cleanup |
5944 | *************************************************************************/ |
5945 | |
5946 | /* ------------------- BEGIN SYSTEM/COMPILER SPECIFIC -------------------- */ |
5947 | |
5948 | #ifdef GLFW_WINGDIAPI_DEFINED |
5949 | #undef WINGDIAPI |
5950 | #undef GLFW_WINGDIAPI_DEFINED |
5951 | #endif |
5952 | |
5953 | #ifdef GLFW_CALLBACK_DEFINED |
5954 | #undef CALLBACK |
5955 | #undef GLFW_CALLBACK_DEFINED |
5956 | #endif |
5957 | |
5958 | /* Some OpenGL related headers need GLAPIENTRY, but it is unconditionally |
5959 | * defined by some gl.h variants (OpenBSD) so define it after if needed. |
5960 | */ |
5961 | #ifndef GLAPIENTRY |
5962 | #define GLAPIENTRY APIENTRY |
5963 | #endif |
5964 | |
5965 | /* -------------------- END SYSTEM/COMPILER SPECIFIC --------------------- */ |
5966 | |
5967 | |
5968 | #ifdef __cplusplus |
5969 | } |
5970 | #endif |
5971 | |
5972 | #endif /* _glfw3_h_ */ |
5973 | |
5974 | |