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
33extern "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 GLFW_KEY_MENU 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 GLFW_WIN32_KEYBOARD_MENU 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 GLFW_COCOA_MENUBAR 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 */
1197typedef 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 */
1211typedef 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 */
1223typedef 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 */
1235typedef 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 */
1247typedef 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 */
1271typedef 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 */
1294typedef 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 */
1316typedef 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 */
1336typedef 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 */
1356typedef 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 */
1377typedef 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 */
1398typedef 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 */
1419typedef 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 */
1440typedef 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 */
1461typedef 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 */
1487typedef 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 */
1510typedef 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 */
1531typedef 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 */
1552typedef 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 */
1578typedef 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 */
1599typedef 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 */
1626typedef 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 */
1650typedef 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 */
1671typedef 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 */
1692typedef 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 */
1707typedef 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 */
1741typedef 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 */
1770typedef 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 */
1794typedef 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 */
1843GLFWAPI 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 */
1875GLFWAPI 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 */
1907GLFWAPI 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 */
1934GLFWAPI 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 */
1965GLFWAPI 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 */
1996GLFWAPI 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 */
2042GLFWAPI 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 */
2071GLFWAPI 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 */
2095GLFWAPI 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 */
2120GLFWAPI 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 */
2151GLFWAPI 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 */
2185GLFWAPI 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 */
2217GLFWAPI 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 */
2243GLFWAPI 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 */
2269GLFWAPI 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 */
2293GLFWAPI 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 */
2323GLFWAPI 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 */
2356GLFWAPI 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 */
2384GLFWAPI 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 */
2417GLFWAPI 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 */
2447GLFWAPI 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 */
2488GLFWAPI 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 */
2507GLFWAPI 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 */
2542GLFWAPI 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 */
2580GLFWAPI 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 */
2733GLFWAPI 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 */
2762GLFWAPI 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 */
2782GLFWAPI 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 */
2804GLFWAPI 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 */
2829GLFWAPI 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 */
2876GLFWAPI 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 */
2908GLFWAPI 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 */
2943GLFWAPI 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 */
2973GLFWAPI 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 */
3016GLFWAPI 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 */
3059GLFWAPI 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 */
3100GLFWAPI 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 */
3129GLFWAPI 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 */
3166GLFWAPI 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 */
3199GLFWAPI 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 */
3226GLFWAPI 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 */
3255GLFWAPI 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 */
3286GLFWAPI 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 */
3313GLFWAPI 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 */
3338GLFWAPI 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 */
3365GLFWAPI 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 */
3387GLFWAPI 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 */
3426GLFWAPI 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 */
3453GLFWAPI 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 */
3475GLFWAPI 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 */
3534GLFWAPI 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 */
3568GLFWAPI 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 */
3605GLFWAPI 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 */
3628GLFWAPI 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 */
3649GLFWAPI 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 */
3684GLFWAPI 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 */
3716GLFWAPI 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 */
3756GLFWAPI 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 */
3792GLFWAPI 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 */
3827GLFWAPI 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 */
3857GLFWAPI 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 */
3887GLFWAPI 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 */
3917GLFWAPI 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 */
3948GLFWAPI 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 */
3986GLFWAPI 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 */
4031GLFWAPI 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 */
4080GLFWAPI 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 */
4100GLFWAPI 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 */
4125GLFWAPI 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 */
4187GLFWAPI 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 */
4216GLFWAPI 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 */
4284GLFWAPI 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 */
4308GLFWAPI 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 */
4348GLFWAPI 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 */
4377GLFWAPI 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 */
4415GLFWAPI 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 */
4455GLFWAPI 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 */
4493GLFWAPI 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 */
4541GLFWAPI 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 */
4568GLFWAPI 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 */
4595GLFWAPI 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 */
4645GLFWAPI 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 */
4688GLFWAPI 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 */
4730GLFWAPI 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 */
4767GLFWAPI 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 */
4799GLFWAPI 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 */
4830GLFWAPI 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 */
4864GLFWAPI 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 */
4901GLFWAPI 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 */
4925GLFWAPI 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 */
4958GLFWAPI 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 */
4999GLFWAPI 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 */
5056GLFWAPI 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 */
5087GLFWAPI 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 */
5128GLFWAPI 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 */
5154GLFWAPI 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 */
5178GLFWAPI 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 */
5206GLFWAPI 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 */
5242GLFWAPI 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 */
5276GLFWAPI 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 */
5306GLFWAPI 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 */
5344GLFWAPI 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 */
5369GLFWAPI 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 */
5399GLFWAPI 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 */
5429GLFWAPI 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 */
5459GLFWAPI 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&nbsp;/&nbsp;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 */
5481GLFWAPI 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 */
5501GLFWAPI 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 */
5539GLFWAPI 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 */
5560GLFWAPI 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 */
5594GLFWAPI 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 */
5640GLFWAPI 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 */
5678GLFWAPI 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 */
5720GLFWAPI 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 */
5748GLFWAPI 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 */
5796GLFWAPI 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 */
5839GLFWAPI 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 */
5876GLFWAPI 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 */
5937GLFWAPI 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