1 /*************************************************************************
2 * GLFW 3.3 - 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>
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.
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:
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.
21 * 2. Altered source versions must be plainly marked as such, and must not
22 * be misrepresented as being the original software.
24 * 3. This notice may not be removed or altered from any source
27 *************************************************************************/
37 /*************************************************************************
38 * Doxygen documentation
39 *************************************************************************/
42 * @brief The header of the GLFW 3 API.
44 * This is the header file of the GLFW 3 API. It defines all its types and
45 * declares all its functions.
47 * For more information about how to use this file, see @ref build_include.
49 /*! @defgroup context Context reference
50 * @brief Functions and types related to OpenGL and OpenGL ES contexts.
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.
55 /*! @defgroup vulkan Vulkan reference
56 * @brief Functions and types related to Vulkan.
58 * This is the reference documentation for Vulkan related functions and types.
59 * For more task-oriented information, see the @ref vulkan_guide.
61 /*! @defgroup init Initialization, version and error reference
62 * @brief Functions and types related to initialization and error handling.
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.
68 /*! @defgroup input Input reference
69 * @brief Functions and types related to input handling.
71 * This is the reference documentation for input related functions and types.
72 * For more task-oriented information, see the @ref input_guide.
74 /*! @defgroup monitor Monitor reference
75 * @brief Functions and types related to monitors.
77 * This is the reference documentation for monitor related functions and types.
78 * For more task-oriented information, see the @ref monitor_guide.
80 /*! @defgroup window Window reference
81 * @brief Functions and types related to windows.
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.
89 /*************************************************************************
90 * Compiler- and platform-specific preprocessor work
91 *************************************************************************/
93 /* If we are we on Windows, we want a single define for it.
95 #if !defined(_WIN32) && (defined(__WIN32__) || defined(WIN32) || defined(__MINGW32__))
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.
105 /* Include because it is needed by Vulkan and related functions.
106 * Include it unconditionally to avoid surprising side-effects.
110 #if defined(GLFW_INCLUDE_VULKAN)
111 #include <vulkan/vulkan.h>
112 #endif /* Vulkan header */
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.
118 /* It is customary to use APIENTRY for OpenGL function pointer declarations on
119 * all platforms. Additionally, the Windows OpenGL header needs APIENTRY.
121 #if !defined(APIENTRY)
123 #define APIENTRY __stdcall
127 #define GLFW_APIENTRY_DEFINED
128 #endif /* APIENTRY */
130 /* Some Windows OpenGL headers need this.
132 #if !defined(WINGDIAPI) && defined(_WIN32)
133 #define WINGDIAPI __declspec(dllimport)
134 #define GLFW_WINGDIAPI_DEFINED
135 #endif /* WINGDIAPI */
137 /* Some Windows GLU headers need this.
139 #if !defined(CALLBACK) && defined(_WIN32)
140 #define CALLBACK __stdcall
141 #define GLFW_CALLBACK_DEFINED
142 #endif /* CALLBACK */
144 /* Include the chosen OpenGL or OpenGL ES headers.
146 #if defined(GLFW_INCLUDE_ES1)
149 #if defined(GLFW_INCLUDE_GLEXT)
150 #include <GLES/glext.h>
153 #elif defined(GLFW_INCLUDE_ES2)
155 #include <GLES2/gl2.h>
156 #if defined(GLFW_INCLUDE_GLEXT)
157 #include <GLES2/gl2ext.h>
160 #elif defined(GLFW_INCLUDE_ES3)
162 #include <GLES3/gl3.h>
163 #if defined(GLFW_INCLUDE_GLEXT)
164 #include <GLES2/gl2ext.h>
167 #elif defined(GLFW_INCLUDE_ES31)
169 #include <GLES3/gl31.h>
170 #if defined(GLFW_INCLUDE_GLEXT)
171 #include <GLES2/gl2ext.h>
174 #elif defined(GLFW_INCLUDE_ES32)
176 #include <GLES3/gl32.h>
177 #if defined(GLFW_INCLUDE_GLEXT)
178 #include <GLES2/gl2ext.h>
181 #elif defined(GLFW_INCLUDE_GLCOREARB)
183 #if defined(__APPLE__)
185 #include <OpenGL/gl3.h>
186 #if defined(GLFW_INCLUDE_GLEXT)
187 #include <OpenGL/gl3ext.h>
188 #endif /*GLFW_INCLUDE_GLEXT*/
192 #include <GL/glcorearb.h>
196 #elif !defined(GLFW_INCLUDE_NONE)
198 #if defined(__APPLE__)
200 #if !defined(GLFW_INCLUDE_GLEXT)
201 #define GL_GLEXT_LEGACY
203 #include <OpenGL/gl.h>
204 #if defined(GLFW_INCLUDE_GLU)
205 #include <OpenGL/glu.h>
211 #if defined(GLFW_INCLUDE_GLEXT)
212 #include <GL/glext.h>
214 #if defined(GLFW_INCLUDE_GLU)
220 #endif /* OpenGL and OpenGL ES headers */
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.
227 #error "You must not have both GLFW_DLL and _GLFW_BUILD_DLL defined"
230 /* GLFWAPI is used to declare public API functions for export
231 * from the DLL / shared library / dynamic library.
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")))
243 /* We are building or calling GLFW as a static library */
248 /*************************************************************************
250 *************************************************************************/
252 /*! @name GLFW version macros
254 /*! @brief The major version number of the GLFW library.
256 * This is incremented when the API is changed in non-compatible ways.
259 #define GLFW_VERSION_MAJOR 3
260 /*! @brief The minor version number of the GLFW library.
262 * This is incremented when features are added to the API but it remains
263 * backward-compatible.
266 #define GLFW_VERSION_MINOR 3
267 /*! @brief The revision number of the GLFW library.
269 * This is incremented when a bug fix release is made that does not contain any
273 #define GLFW_VERSION_REVISION 1
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
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
295 /*! @name Key and button actions
297 /*! @brief The key or mouse button was released.
299 * The key or mouse button was released.
303 #define GLFW_RELEASE 0
304 /*! @brief The key or mouse button was pressed.
306 * The key or mouse button was pressed.
311 /*! @brief The key was held down until it repeated.
313 * The key was held down until it repeated.
317 #define GLFW_REPEAT 2
320 /*! @defgroup hat_state Joystick hat states
321 * @brief Joystick hat states.
323 * See [joystick hat input](@ref joystick_hat) for how these are used.
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)
338 /*! @defgroup keys Keyboard keys
339 * @brief Keyboard key IDs.
341 * See [key input](@ref input_key) for how these are used.
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).
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",
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",
362 /* The unknown key */
363 #define GLFW_KEY_UNKNOWN -1
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 */
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
489 #define GLFW_KEY_LAST GLFW_KEY_MENU
493 /*! @defgroup mods Modifier key flags
494 * @brief Modifier key flags.
496 * See [key input](@ref input_key) for how these are used.
501 /*! @brief If this bit is set one or more Shift keys were held down.
503 * If this bit is set one or more Shift keys were held down.
505 #define GLFW_MOD_SHIFT 0x0001
506 /*! @brief If this bit is set one or more Control keys were held down.
508 * If this bit is set one or more Control keys were held down.
510 #define GLFW_MOD_CONTROL 0x0002
511 /*! @brief If this bit is set one or more Alt keys were held down.
513 * If this bit is set one or more Alt keys were held down.
515 #define GLFW_MOD_ALT 0x0004
516 /*! @brief If this bit is set one or more Super keys were held down.
518 * If this bit is set one or more Super keys were held down.
520 #define GLFW_MOD_SUPER 0x0008
521 /*! @brief If this bit is set the Caps Lock key is enabled.
523 * If this bit is set the Caps Lock key is enabled and the @ref
524 * GLFW_LOCK_KEY_MODS input mode is set.
526 #define GLFW_MOD_CAPS_LOCK 0x0010
527 /*! @brief If this bit is set the Num Lock key is enabled.
529 * If this bit is set the Num Lock key is enabled and the @ref
530 * GLFW_LOCK_KEY_MODS input mode is set.
532 #define GLFW_MOD_NUM_LOCK 0x0020
536 /*! @defgroup buttons Mouse buttons
537 * @brief Mouse button IDs.
539 * See [mouse button input](@ref input_mouse_button) for how these are used.
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
557 /*! @defgroup joysticks Joysticks
558 * @brief Joystick IDs.
560 * See [joystick input](@ref joystick) for how these are used.
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
583 /*! @defgroup gamepad_buttons Gamepad buttons
584 * @brief Gamepad buttons.
586 * See @ref gamepad for how these are used.
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
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
613 /*! @defgroup gamepad_axes Gamepad axes
614 * @brief Gamepad axes.
616 * See @ref gamepad for how these are used.
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
629 /*! @defgroup errors Error codes
630 * @brief Error codes.
632 * See [error handling](@ref error_handling) for how these are used.
636 /*! @brief No error has occurred.
638 * No error has occurred.
642 #define GLFW_NO_ERROR 0
643 /*! @brief GLFW has not been initialized.
645 * This occurs if a GLFW function was called that must not be called unless the
646 * library is [initialized](@ref intro_init).
648 * @analysis Application programmer error. Initialize GLFW before calling any
649 * function that requires initialization.
651 #define GLFW_NOT_INITIALIZED 0x00010001
652 /*! @brief No context is current for this thread.
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.
658 * @analysis Application programmer error. Ensure a context is current before
659 * calling functions that require a current context.
661 #define GLFW_NO_CURRENT_CONTEXT 0x00010002
662 /*! @brief One of the arguments to the function was an invalid enum value.
664 * One of the arguments to the function was an invalid enum value, for example
665 * requesting @ref GLFW_RED_BITS with @ref glfwGetWindowAttrib.
667 * @analysis Application programmer error. Fix the offending call.
669 #define GLFW_INVALID_ENUM 0x00010003
670 /*! @brief One of the arguments to the function was an invalid value.
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.
675 * Requesting a valid but unavailable OpenGL or OpenGL ES version will instead
676 * result in a @ref GLFW_VERSION_UNAVAILABLE error.
678 * @analysis Application programmer error. Fix the offending call.
680 #define GLFW_INVALID_VALUE 0x00010004
681 /*! @brief A memory allocation failed.
683 * A memory allocation failed.
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).
688 #define GLFW_OUT_OF_MEMORY 0x00010005
689 /*! @brief GLFW could not find support for the requested API on the system.
691 * GLFW could not find support for the requested API on the system.
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.
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.
704 #define GLFW_API_UNAVAILABLE 0x00010006
705 /*! @brief The requested OpenGL or OpenGL ES version is not available.
707 * The requested OpenGL or OpenGL ES version (including any requested context
708 * or framebuffer hints) is not available on this machine.
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
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
721 #define GLFW_VERSION_UNAVAILABLE 0x00010007
722 /*! @brief A platform-specific error occurred that does not match any of the
723 * more specific categories.
725 * A platform-specific error occurred that does not match any of the more
726 * specific categories.
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).
732 #define GLFW_PLATFORM_ERROR 0x00010008
733 /*! @brief The requested format is not supported or available.
735 * If emitted during window creation, the requested pixel format is not
738 * If emitted when querying the clipboard, the contents of the clipboard could
739 * not be converted to the requested format.
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.
748 * If emitted when querying the clipboard, ignore the error or report it to
749 * the user, as appropriate.
751 #define GLFW_FORMAT_UNAVAILABLE 0x00010009
752 /*! @brief The specified window does not have an OpenGL or OpenGL ES context.
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.
757 * @analysis Application programmer error. Fix the offending call.
759 #define GLFW_NO_WINDOW_CONTEXT 0x0001000A
762 /*! @addtogroup window
764 /*! @brief Input focus window hint and attribute
766 * Input focus [window hint](@ref GLFW_FOCUSED_hint) or
767 * [window attribute](@ref GLFW_FOCUSED_attrib).
769 #define GLFW_FOCUSED 0x00020001
770 /*! @brief Window iconification window attribute
772 * Window iconification [window attribute](@ref GLFW_ICONIFIED_attrib).
774 #define GLFW_ICONIFIED 0x00020002
775 /*! @brief Window resize-ability window hint and attribute
777 * Window resize-ability [window hint](@ref GLFW_RESIZABLE_hint) and
778 * [window attribute](@ref GLFW_RESIZABLE_attrib).
780 #define GLFW_RESIZABLE 0x00020003
781 /*! @brief Window visibility window hint and attribute
783 * Window visibility [window hint](@ref GLFW_VISIBLE_hint) and
784 * [window attribute](@ref GLFW_VISIBLE_attrib).
786 #define GLFW_VISIBLE 0x00020004
787 /*! @brief Window decoration window hint and attribute
789 * Window decoration [window hint](@ref GLFW_DECORATED_hint) and
790 * [window attribute](@ref GLFW_DECORATED_attrib).
792 #define GLFW_DECORATED 0x00020005
793 /*! @brief Window auto-iconification window hint and attribute
795 * Window auto-iconification [window hint](@ref GLFW_AUTO_ICONIFY_hint) and
796 * [window attribute](@ref GLFW_AUTO_ICONIFY_attrib).
798 #define GLFW_AUTO_ICONIFY 0x00020006
799 /*! @brief Window decoration window hint and attribute
801 * Window decoration [window hint](@ref GLFW_FLOATING_hint) and
802 * [window attribute](@ref GLFW_FLOATING_attrib).
804 #define GLFW_FLOATING 0x00020007
805 /*! @brief Window maximization window hint and attribute
807 * Window maximization [window hint](@ref GLFW_MAXIMIZED_hint) and
808 * [window attribute](@ref GLFW_MAXIMIZED_attrib).
810 #define GLFW_MAXIMIZED 0x00020008
811 /*! @brief Cursor centering window hint
813 * Cursor centering [window hint](@ref GLFW_CENTER_CURSOR_hint).
815 #define GLFW_CENTER_CURSOR 0x00020009
816 /*! @brief Window framebuffer transparency hint and attribute
818 * Window framebuffer transparency
819 * [window hint](@ref GLFW_TRANSPARENT_FRAMEBUFFER_hint) and
820 * [window attribute](@ref GLFW_TRANSPARENT_FRAMEBUFFER_attrib).
822 #define GLFW_TRANSPARENT_FRAMEBUFFER 0x0002000A
823 /*! @brief Mouse cursor hover window attribute.
825 * Mouse cursor hover [window attribute](@ref GLFW_HOVERED_attrib).
827 #define GLFW_HOVERED 0x0002000B
828 /*! @brief Input focus on calling show window hint and attribute
830 * Input focus [window hint](@ref GLFW_FOCUS_ON_SHOW_hint) or
831 * [window attribute](@ref GLFW_FOCUS_ON_SHOW_attrib).
833 #define GLFW_FOCUS_ON_SHOW 0x0002000C
835 /*! @brief Framebuffer bit depth hint.
837 * Framebuffer bit depth [hint](@ref GLFW_RED_BITS).
839 #define GLFW_RED_BITS 0x00021001
840 /*! @brief Framebuffer bit depth hint.
842 * Framebuffer bit depth [hint](@ref GLFW_GREEN_BITS).
844 #define GLFW_GREEN_BITS 0x00021002
845 /*! @brief Framebuffer bit depth hint.
847 * Framebuffer bit depth [hint](@ref GLFW_BLUE_BITS).
849 #define GLFW_BLUE_BITS 0x00021003
850 /*! @brief Framebuffer bit depth hint.
852 * Framebuffer bit depth [hint](@ref GLFW_ALPHA_BITS).
854 #define GLFW_ALPHA_BITS 0x00021004
855 /*! @brief Framebuffer bit depth hint.
857 * Framebuffer bit depth [hint](@ref GLFW_DEPTH_BITS).
859 #define GLFW_DEPTH_BITS 0x00021005
860 /*! @brief Framebuffer bit depth hint.
862 * Framebuffer bit depth [hint](@ref GLFW_STENCIL_BITS).
864 #define GLFW_STENCIL_BITS 0x00021006
865 /*! @brief Framebuffer bit depth hint.
867 * Framebuffer bit depth [hint](@ref GLFW_ACCUM_RED_BITS).
869 #define GLFW_ACCUM_RED_BITS 0x00021007
870 /*! @brief Framebuffer bit depth hint.
872 * Framebuffer bit depth [hint](@ref GLFW_ACCUM_GREEN_BITS).
874 #define GLFW_ACCUM_GREEN_BITS 0x00021008
875 /*! @brief Framebuffer bit depth hint.
877 * Framebuffer bit depth [hint](@ref GLFW_ACCUM_BLUE_BITS).
879 #define GLFW_ACCUM_BLUE_BITS 0x00021009
880 /*! @brief Framebuffer bit depth hint.
882 * Framebuffer bit depth [hint](@ref GLFW_ACCUM_ALPHA_BITS).
884 #define GLFW_ACCUM_ALPHA_BITS 0x0002100A
885 /*! @brief Framebuffer auxiliary buffer hint.
887 * Framebuffer auxiliary buffer [hint](@ref GLFW_AUX_BUFFERS).
889 #define GLFW_AUX_BUFFERS 0x0002100B
890 /*! @brief OpenGL stereoscopic rendering hint.
892 * OpenGL stereoscopic rendering [hint](@ref GLFW_STEREO).
894 #define GLFW_STEREO 0x0002100C
895 /*! @brief Framebuffer MSAA samples hint.
897 * Framebuffer MSAA samples [hint](@ref GLFW_SAMPLES).
899 #define GLFW_SAMPLES 0x0002100D
900 /*! @brief Framebuffer sRGB hint.
902 * Framebuffer sRGB [hint](@ref GLFW_SRGB_CAPABLE).
904 #define GLFW_SRGB_CAPABLE 0x0002100E
905 /*! @brief Monitor refresh rate hint.
907 * Monitor refresh rate [hint](@ref GLFW_REFRESH_RATE).
909 #define GLFW_REFRESH_RATE 0x0002100F
910 /*! @brief Framebuffer double buffering hint.
912 * Framebuffer double buffering [hint](@ref GLFW_DOUBLEBUFFER).
914 #define GLFW_DOUBLEBUFFER 0x00021010
916 /*! @brief Context client API hint and attribute.
918 * Context client API [hint](@ref GLFW_CLIENT_API_hint) and
919 * [attribute](@ref GLFW_CLIENT_API_attrib).
921 #define GLFW_CLIENT_API 0x00022001
922 /*! @brief Context client API major version hint and attribute.
924 * Context client API major version [hint](@ref GLFW_CONTEXT_VERSION_MAJOR_hint)
925 * and [attribute](@ref GLFW_CONTEXT_VERSION_MAJOR_attrib).
927 #define GLFW_CONTEXT_VERSION_MAJOR 0x00022002
928 /*! @brief Context client API minor version hint and attribute.
930 * Context client API minor version [hint](@ref GLFW_CONTEXT_VERSION_MINOR_hint)
931 * and [attribute](@ref GLFW_CONTEXT_VERSION_MINOR_attrib).
933 #define GLFW_CONTEXT_VERSION_MINOR 0x00022003
934 /*! @brief Context client API revision number hint and attribute.
936 * Context client API revision number
937 * [attribute](@ref GLFW_CONTEXT_REVISION_attrib).
939 #define GLFW_CONTEXT_REVISION 0x00022004
940 /*! @brief Context robustness hint and attribute.
942 * Context client API revision number [hint](@ref GLFW_CONTEXT_ROBUSTNESS_hint)
943 * and [attribute](@ref GLFW_CONTEXT_ROBUSTNESS_attrib).
945 #define GLFW_CONTEXT_ROBUSTNESS 0x00022005
946 /*! @brief OpenGL forward-compatibility hint and attribute.
948 * OpenGL forward-compatibility [hint](@ref GLFW_OPENGL_FORWARD_COMPAT_hint)
949 * and [attribute](@ref GLFW_OPENGL_FORWARD_COMPAT_attrib).
951 #define GLFW_OPENGL_FORWARD_COMPAT 0x00022006
952 /*! @brief OpenGL debug context hint and attribute.
954 * OpenGL debug context [hint](@ref GLFW_OPENGL_DEBUG_CONTEXT_hint) and
955 * [attribute](@ref GLFW_OPENGL_DEBUG_CONTEXT_attrib).
957 #define GLFW_OPENGL_DEBUG_CONTEXT 0x00022007
958 /*! @brief OpenGL profile hint and attribute.
960 * OpenGL profile [hint](@ref GLFW_OPENGL_PROFILE_hint) and
961 * [attribute](@ref GLFW_OPENGL_PROFILE_attrib).
963 #define GLFW_OPENGL_PROFILE 0x00022008
964 /*! @brief Context flush-on-release hint and attribute.
966 * Context flush-on-release [hint](@ref GLFW_CONTEXT_RELEASE_BEHAVIOR_hint) and
967 * [attribute](@ref GLFW_CONTEXT_RELEASE_BEHAVIOR_attrib).
969 #define GLFW_CONTEXT_RELEASE_BEHAVIOR 0x00022009
970 /*! @brief Context error suppression hint and attribute.
972 * Context error suppression [hint](@ref GLFW_CONTEXT_NO_ERROR_hint) and
973 * [attribute](@ref GLFW_CONTEXT_NO_ERROR_attrib).
975 #define GLFW_CONTEXT_NO_ERROR 0x0002200A
976 /*! @brief Context creation API hint and attribute.
978 * Context creation API [hint](@ref GLFW_CONTEXT_CREATION_API_hint) and
979 * [attribute](@ref GLFW_CONTEXT_CREATION_API_attrib).
981 #define GLFW_CONTEXT_CREATION_API 0x0002200B
982 /*! @brief Window content area scaling window
983 * [window hint](@ref GLFW_SCALE_TO_MONITOR).
985 #define GLFW_SCALE_TO_MONITOR 0x0002200C
986 /*! @brief macOS specific
987 * [window hint](@ref GLFW_COCOA_RETINA_FRAMEBUFFER_hint).
989 #define GLFW_COCOA_RETINA_FRAMEBUFFER 0x00023001
990 /*! @brief macOS specific
991 * [window hint](@ref GLFW_COCOA_FRAME_NAME_hint).
993 #define GLFW_COCOA_FRAME_NAME 0x00023002
994 /*! @brief macOS specific
995 * [window hint](@ref GLFW_COCOA_GRAPHICS_SWITCHING_hint).
997 #define GLFW_COCOA_GRAPHICS_SWITCHING 0x00023003
998 /*! @brief X11 specific
999 * [window hint](@ref GLFW_X11_CLASS_NAME_hint).
1001 #define GLFW_X11_CLASS_NAME 0x00024001
1002 /*! @brief X11 specific
1003 * [window hint](@ref GLFW_X11_CLASS_NAME_hint).
1005 #define GLFW_X11_INSTANCE_NAME 0x00024002
1008 #define GLFW_NO_API 0
1009 #define GLFW_OPENGL_API 0x00030001
1010 #define GLFW_OPENGL_ES_API 0x00030002
1012 #define GLFW_NO_ROBUSTNESS 0
1013 #define GLFW_NO_RESET_NOTIFICATION 0x00031001
1014 #define GLFW_LOSE_CONTEXT_ON_RESET 0x00031002
1016 #define GLFW_OPENGL_ANY_PROFILE 0
1017 #define GLFW_OPENGL_CORE_PROFILE 0x00032001
1018 #define GLFW_OPENGL_COMPAT_PROFILE 0x00032002
1020 #define GLFW_CURSOR 0x00033001
1021 #define GLFW_STICKY_KEYS 0x00033002
1022 #define GLFW_STICKY_MOUSE_BUTTONS 0x00033003
1023 #define GLFW_LOCK_KEY_MODS 0x00033004
1024 #define GLFW_RAW_MOUSE_MOTION 0x00033005
1026 #define GLFW_CURSOR_NORMAL 0x00034001
1027 #define GLFW_CURSOR_HIDDEN 0x00034002
1028 #define GLFW_CURSOR_DISABLED 0x00034003
1030 #define GLFW_ANY_RELEASE_BEHAVIOR 0
1031 #define GLFW_RELEASE_BEHAVIOR_FLUSH 0x00035001
1032 #define GLFW_RELEASE_BEHAVIOR_NONE 0x00035002
1034 #define GLFW_NATIVE_CONTEXT_API 0x00036001
1035 #define GLFW_EGL_CONTEXT_API 0x00036002
1036 #define GLFW_OSMESA_CONTEXT_API 0x00036003
1038 /*! @defgroup shapes Standard cursor shapes
1039 * @brief Standard system cursor shapes.
1041 * See [standard cursor creation](@ref cursor_standard) for how these are used.
1046 /*! @brief The regular arrow cursor shape.
1048 * The regular arrow cursor.
1050 #define GLFW_ARROW_CURSOR 0x00036001
1051 /*! @brief The text input I-beam cursor shape.
1053 * The text input I-beam cursor shape.
1055 #define GLFW_IBEAM_CURSOR 0x00036002
1056 /*! @brief The crosshair shape.
1058 * The crosshair shape.
1060 #define GLFW_CROSSHAIR_CURSOR 0x00036003
1061 /*! @brief The hand shape.
1065 #define GLFW_HAND_CURSOR 0x00036004
1066 /*! @brief The horizontal resize arrow shape.
1068 * The horizontal resize arrow shape.
1070 #define GLFW_HRESIZE_CURSOR 0x00036005
1071 /*! @brief The vertical resize arrow shape.
1073 * The vertical resize arrow shape.
1075 #define GLFW_VRESIZE_CURSOR 0x00036006
1078 #define GLFW_CONNECTED 0x00040001
1079 #define GLFW_DISCONNECTED 0x00040002
1081 /*! @addtogroup init
1083 /*! @brief Joystick hat buttons init hint.
1085 * Joystick hat buttons [init hint](@ref GLFW_JOYSTICK_HAT_BUTTONS).
1087 #define GLFW_JOYSTICK_HAT_BUTTONS 0x00050001
1088 /*! @brief macOS specific init hint.
1090 * macOS specific [init hint](@ref GLFW_COCOA_CHDIR_RESOURCES_hint).
1092 #define GLFW_COCOA_CHDIR_RESOURCES 0x00051001
1093 /*! @brief macOS specific init hint.
1095 * macOS specific [init hint](@ref GLFW_COCOA_MENUBAR_hint).
1097 #define GLFW_COCOA_MENUBAR 0x00051002
1100 #define GLFW_DONT_CARE -1
1103 /*************************************************************************
1105 *************************************************************************/
1107 /*! @brief Client API function pointer type.
1109 * Generic function pointer used for returning client API function pointers
1110 * without forcing a cast from a regular pointer.
1112 * @sa @ref context_glext
1113 * @sa @ref glfwGetProcAddress
1115 * @since Added in version 3.0.
1119 typedef void (*GLFWglproc
)(void);
1121 /*! @brief Vulkan API function pointer type.
1123 * Generic function pointer used for returning Vulkan API function pointers
1124 * without forcing a cast from a regular pointer.
1126 * @sa @ref vulkan_proc
1127 * @sa @ref glfwGetInstanceProcAddress
1129 * @since Added in version 3.2.
1133 typedef void (*GLFWvkproc
)(void);
1135 /*! @brief Opaque monitor object.
1137 * Opaque monitor object.
1139 * @see @ref monitor_object
1141 * @since Added in version 3.0.
1145 typedef struct GLFWmonitor GLFWmonitor
;
1147 /*! @brief Opaque window object.
1149 * Opaque window object.
1151 * @see @ref window_object
1153 * @since Added in version 3.0.
1157 typedef struct GLFWwindow GLFWwindow
;
1159 /*! @brief Opaque cursor object.
1161 * Opaque cursor object.
1163 * @see @ref cursor_object
1165 * @since Added in version 3.1.
1169 typedef struct GLFWcursor GLFWcursor
;
1171 /*! @brief The function pointer type for error callbacks.
1173 * This is the function pointer type for error callbacks. An error callback
1174 * function has the following signature:
1176 * void callback_name(int error_code, const char* description)
1179 * @param[in] error_code An [error code](@ref errors). Future releases may add
1181 * @param[in] description A UTF-8 encoded string describing the error.
1183 * @pointer_lifetime The error description string is valid until the callback
1186 * @sa @ref error_handling
1187 * @sa @ref glfwSetErrorCallback
1189 * @since Added in version 3.0.
1193 typedef void (* GLFWerrorfun
)(int,const char*);
1195 /*! @brief The function pointer type for window position callbacks.
1197 * This is the function pointer type for window position callbacks. A window
1198 * position callback function has the following signature:
1200 * void callback_name(GLFWwindow* window, int xpos, int ypos)
1203 * @param[in] window The window that was moved.
1204 * @param[in] xpos The new x-coordinate, in screen coordinates, of the
1205 * upper-left corner of the content area of the window.
1206 * @param[in] ypos The new y-coordinate, in screen coordinates, of the
1207 * upper-left corner of the content area of the window.
1209 * @sa @ref window_pos
1210 * @sa @ref glfwSetWindowPosCallback
1212 * @since Added in version 3.0.
1216 typedef void (* GLFWwindowposfun
)(GLFWwindow
*,int,int);
1218 /*! @brief The function pointer type for window size callbacks.
1220 * This is the function pointer type for window size callbacks. A window size
1221 * callback function has the following signature:
1223 * void callback_name(GLFWwindow* window, int width, int height)
1226 * @param[in] window The window that was resized.
1227 * @param[in] width The new width, in screen coordinates, of the window.
1228 * @param[in] height The new height, in screen coordinates, of the window.
1230 * @sa @ref window_size
1231 * @sa @ref glfwSetWindowSizeCallback
1233 * @since Added in version 1.0.
1234 * @glfw3 Added window handle parameter.
1238 typedef void (* GLFWwindowsizefun
)(GLFWwindow
*,int,int);
1240 /*! @brief The function pointer type for window close callbacks.
1242 * This is the function pointer type for window close callbacks. A window
1243 * close callback function has the following signature:
1245 * void function_name(GLFWwindow* window)
1248 * @param[in] window The window that the user attempted to close.
1250 * @sa @ref window_close
1251 * @sa @ref glfwSetWindowCloseCallback
1253 * @since Added in version 2.5.
1254 * @glfw3 Added window handle parameter.
1258 typedef void (* GLFWwindowclosefun
)(GLFWwindow
*);
1260 /*! @brief The function pointer type for window content refresh callbacks.
1262 * This is the function pointer type for window content refresh callbacks.
1263 * A window content refresh callback function has the following signature:
1265 * void function_name(GLFWwindow* window);
1268 * @param[in] window The window whose content needs to be refreshed.
1270 * @sa @ref window_refresh
1271 * @sa @ref glfwSetWindowRefreshCallback
1273 * @since Added in version 2.5.
1274 * @glfw3 Added window handle parameter.
1278 typedef void (* GLFWwindowrefreshfun
)(GLFWwindow
*);
1280 /*! @brief The function pointer type for window focus callbacks.
1282 * This is the function pointer type for window focus callbacks. A window
1283 * focus callback function has the following signature:
1285 * void function_name(GLFWwindow* window, int focused)
1288 * @param[in] window The window that gained or lost input focus.
1289 * @param[in] focused `GLFW_TRUE` if the window was given input focus, or
1290 * `GLFW_FALSE` if it lost it.
1292 * @sa @ref window_focus
1293 * @sa @ref glfwSetWindowFocusCallback
1295 * @since Added in version 3.0.
1299 typedef void (* GLFWwindowfocusfun
)(GLFWwindow
*,int);
1301 /*! @brief The function pointer type for window iconify callbacks.
1303 * This is the function pointer type for window iconify callbacks. A window
1304 * iconify callback function has the following signature:
1306 * void function_name(GLFWwindow* window, int iconified)
1309 * @param[in] window The window that was iconified or restored.
1310 * @param[in] iconified `GLFW_TRUE` if the window was iconified, or
1311 * `GLFW_FALSE` if it was restored.
1313 * @sa @ref window_iconify
1314 * @sa @ref glfwSetWindowIconifyCallback
1316 * @since Added in version 3.0.
1320 typedef void (* GLFWwindowiconifyfun
)(GLFWwindow
*,int);
1322 /*! @brief The function pointer type for window maximize callbacks.
1324 * This is the function pointer type for window maximize callbacks. A window
1325 * maximize callback function has the following signature:
1327 * void function_name(GLFWwindow* window, int maximized)
1330 * @param[in] window The window that was maximized or restored.
1331 * @param[in] iconified `GLFW_TRUE` if the window was maximized, or
1332 * `GLFW_FALSE` if it was restored.
1334 * @sa @ref window_maximize
1335 * @sa glfwSetWindowMaximizeCallback
1337 * @since Added in version 3.3.
1341 typedef void (* GLFWwindowmaximizefun
)(GLFWwindow
*,int);
1343 /*! @brief The function pointer type for framebuffer size callbacks.
1345 * This is the function pointer type for framebuffer size callbacks.
1346 * A framebuffer size callback function has the following signature:
1348 * void function_name(GLFWwindow* window, int width, int height)
1351 * @param[in] window The window whose framebuffer was resized.
1352 * @param[in] width The new width, in pixels, of the framebuffer.
1353 * @param[in] height The new height, in pixels, of the framebuffer.
1355 * @sa @ref window_fbsize
1356 * @sa @ref glfwSetFramebufferSizeCallback
1358 * @since Added in version 3.0.
1362 typedef void (* GLFWframebuffersizefun
)(GLFWwindow
*,int,int);
1364 /*! @brief The function pointer type for window content scale callbacks.
1366 * This is the function pointer type for window content scale callbacks.
1367 * A window content scale callback function has the following signature:
1369 * void function_name(GLFWwindow* window, float xscale, float yscale)
1372 * @param[in] window The window whose content scale changed.
1373 * @param[in] xscale The new x-axis content scale of the window.
1374 * @param[in] yscale The new y-axis content scale of the window.
1376 * @sa @ref window_scale
1377 * @sa @ref glfwSetWindowContentScaleCallback
1379 * @since Added in version 3.3.
1383 typedef void (* GLFWwindowcontentscalefun
)(GLFWwindow
*,float,float);
1385 /*! @brief The function pointer type for mouse button callbacks.
1387 * This is the function pointer type for mouse button callback functions.
1388 * A mouse button callback function has the following signature:
1390 * void function_name(GLFWwindow* window, int button, int action, int mods)
1393 * @param[in] window The window that received the event.
1394 * @param[in] button The [mouse button](@ref buttons) that was pressed or
1396 * @param[in] action One of `GLFW_PRESS` or `GLFW_RELEASE`. Future releases
1397 * may add more actions.
1398 * @param[in] mods Bit field describing which [modifier keys](@ref mods) were
1401 * @sa @ref input_mouse_button
1402 * @sa @ref glfwSetMouseButtonCallback
1404 * @since Added in version 1.0.
1405 * @glfw3 Added window handle and modifier mask parameters.
1409 typedef void (* GLFWmousebuttonfun
)(GLFWwindow
*,int,int,int);
1411 /*! @brief The function pointer type for cursor position callbacks.
1413 * This is the function pointer type for cursor position callbacks. A cursor
1414 * position callback function has the following signature:
1416 * void function_name(GLFWwindow* window, double xpos, double ypos);
1419 * @param[in] window The window that received the event.
1420 * @param[in] xpos The new cursor x-coordinate, relative to the left edge of
1422 * @param[in] ypos The new cursor y-coordinate, relative to the top edge of the
1425 * @sa @ref cursor_pos
1426 * @sa @ref glfwSetCursorPosCallback
1428 * @since Added in version 3.0. Replaces `GLFWmouseposfun`.
1432 typedef void (* GLFWcursorposfun
)(GLFWwindow
*,double,double);
1434 /*! @brief The function pointer type for cursor enter/leave callbacks.
1436 * This is the function pointer type for cursor enter/leave callbacks.
1437 * A cursor enter/leave callback function has the following signature:
1439 * void function_name(GLFWwindow* window, int entered)
1442 * @param[in] window The window that received the event.
1443 * @param[in] entered `GLFW_TRUE` if the cursor entered the window's content
1444 * area, or `GLFW_FALSE` if it left it.
1446 * @sa @ref cursor_enter
1447 * @sa @ref glfwSetCursorEnterCallback
1449 * @since Added in version 3.0.
1453 typedef void (* GLFWcursorenterfun
)(GLFWwindow
*,int);
1455 /*! @brief The function pointer type for scroll callbacks.
1457 * This is the function pointer type for scroll callbacks. A scroll callback
1458 * function has the following signature:
1460 * void function_name(GLFWwindow* window, double xoffset, double yoffset)
1463 * @param[in] window The window that received the event.
1464 * @param[in] xoffset The scroll offset along the x-axis.
1465 * @param[in] yoffset The scroll offset along the y-axis.
1467 * @sa @ref scrolling
1468 * @sa @ref glfwSetScrollCallback
1470 * @since Added in version 3.0. Replaces `GLFWmousewheelfun`.
1474 typedef void (* GLFWscrollfun
)(GLFWwindow
*,double,double);
1476 /*! @brief The function pointer type for keyboard key callbacks.
1478 * This is the function pointer type for keyboard key callbacks. A keyboard
1479 * key callback function has the following signature:
1481 * void function_name(GLFWwindow* window, int key, int scancode, int action, int mods)
1484 * @param[in] window The window that received the event.
1485 * @param[in] key The [keyboard key](@ref keys) that was pressed or released.
1486 * @param[in] scancode The system-specific scancode of the key.
1487 * @param[in] action `GLFW_PRESS`, `GLFW_RELEASE` or `GLFW_REPEAT`. Future
1488 * releases may add more actions.
1489 * @param[in] mods Bit field describing which [modifier keys](@ref mods) were
1492 * @sa @ref input_key
1493 * @sa @ref glfwSetKeyCallback
1495 * @since Added in version 1.0.
1496 * @glfw3 Added window handle, scancode and modifier mask parameters.
1500 typedef void (* GLFWkeyfun
)(GLFWwindow
*,int,int,int,int);
1502 /*! @brief The function pointer type for Unicode character callbacks.
1504 * This is the function pointer type for Unicode character callbacks.
1505 * A Unicode character callback function has the following signature:
1507 * void function_name(GLFWwindow* window, unsigned int codepoint)
1510 * @param[in] window The window that received the event.
1511 * @param[in] codepoint The Unicode code point of the character.
1513 * @sa @ref input_char
1514 * @sa @ref glfwSetCharCallback
1516 * @since Added in version 2.4.
1517 * @glfw3 Added window handle parameter.
1521 typedef void (* GLFWcharfun
)(GLFWwindow
*,unsigned int);
1523 /*! @brief The function pointer type for Unicode character with modifiers
1526 * This is the function pointer type for Unicode character with modifiers
1527 * callbacks. It is called for each input character, regardless of what
1528 * modifier keys are held down. A Unicode character with modifiers callback
1529 * function has the following signature:
1531 * void function_name(GLFWwindow* window, unsigned int codepoint, int mods)
1534 * @param[in] window The window that received the event.
1535 * @param[in] codepoint The Unicode code point of the character.
1536 * @param[in] mods Bit field describing which [modifier keys](@ref mods) were
1539 * @sa @ref input_char
1540 * @sa @ref glfwSetCharModsCallback
1542 * @deprecated Scheduled for removal in version 4.0.
1544 * @since Added in version 3.1.
1548 typedef void (* GLFWcharmodsfun
)(GLFWwindow
*,unsigned int,int);
1550 /*! @brief The function pointer type for path drop callbacks.
1552 * This is the function pointer type for path drop callbacks. A path drop
1553 * callback function has the following signature:
1555 * void function_name(GLFWwindow* window, int path_count, const char* paths[])
1558 * @param[in] window The window that received the event.
1559 * @param[in] path_count The number of dropped paths.
1560 * @param[in] paths The UTF-8 encoded file and/or directory path names.
1562 * @pointer_lifetime The path array and its strings are valid until the
1563 * callback function returns.
1565 * @sa @ref path_drop
1566 * @sa @ref glfwSetDropCallback
1568 * @since Added in version 3.1.
1572 typedef void (* GLFWdropfun
)(GLFWwindow
*,int,const char*[]);
1574 /*! @brief The function pointer type for monitor configuration callbacks.
1576 * This is the function pointer type for monitor configuration callbacks.
1577 * A monitor callback function has the following signature:
1579 * void function_name(GLFWmonitor* monitor, int event)
1582 * @param[in] monitor The monitor that was connected or disconnected.
1583 * @param[in] event One of `GLFW_CONNECTED` or `GLFW_DISCONNECTED`. Future
1584 * releases may add more events.
1586 * @sa @ref monitor_event
1587 * @sa @ref glfwSetMonitorCallback
1589 * @since Added in version 3.0.
1593 typedef void (* GLFWmonitorfun
)(GLFWmonitor
*,int);
1595 /*! @brief The function pointer type for joystick configuration callbacks.
1597 * This is the function pointer type for joystick configuration callbacks.
1598 * A joystick configuration callback function has the following signature:
1600 * void function_name(int jid, int event)
1603 * @param[in] jid The joystick that was connected or disconnected.
1604 * @param[in] event One of `GLFW_CONNECTED` or `GLFW_DISCONNECTED`. Future
1605 * releases may add more events.
1607 * @sa @ref joystick_event
1608 * @sa @ref glfwSetJoystickCallback
1610 * @since Added in version 3.2.
1614 typedef void (* GLFWjoystickfun
)(int,int);
1616 /*! @brief Video mode type.
1618 * This describes a single video mode.
1620 * @sa @ref monitor_modes
1621 * @sa @ref glfwGetVideoMode
1622 * @sa @ref glfwGetVideoModes
1624 * @since Added in version 1.0.
1625 * @glfw3 Added refresh rate member.
1629 typedef struct GLFWvidmode
1631 /*! The width, in screen coordinates, of the video mode.
1634 /*! The height, in screen coordinates, of the video mode.
1637 /*! The bit depth of the red channel of the video mode.
1640 /*! The bit depth of the green channel of the video mode.
1643 /*! The bit depth of the blue channel of the video mode.
1646 /*! The refresh rate, in Hz, of the video mode.
1651 /*! @brief Gamma ramp.
1653 * This describes the gamma ramp for a monitor.
1655 * @sa @ref monitor_gamma
1656 * @sa @ref glfwGetGammaRamp
1657 * @sa @ref glfwSetGammaRamp
1659 * @since Added in version 3.0.
1663 typedef struct GLFWgammaramp
1665 /*! An array of value describing the response of the red channel.
1667 unsigned short* red
;
1668 /*! An array of value describing the response of the green channel.
1670 unsigned short* green
;
1671 /*! An array of value describing the response of the blue channel.
1673 unsigned short* blue
;
1674 /*! The number of elements in each array.
1679 /*! @brief Image data.
1681 * This describes a single 2D image. See the documentation for each related
1682 * function what the expected pixel format is.
1684 * @sa @ref cursor_custom
1685 * @sa @ref window_icon
1687 * @since Added in version 2.1.
1688 * @glfw3 Removed format and bytes-per-pixel members.
1692 typedef struct GLFWimage
1694 /*! The width, in pixels, of this image.
1697 /*! The height, in pixels, of this image.
1700 /*! The pixel data of this image, arranged left-to-right, top-to-bottom.
1702 unsigned char* pixels
;
1705 /*! @brief Gamepad input state
1707 * This describes the input state of a gamepad.
1710 * @sa @ref glfwGetGamepadState
1712 * @since Added in version 3.3.
1716 typedef struct GLFWgamepadstate
1718 /*! The states of each [gamepad button](@ref gamepad_buttons), `GLFW_PRESS`
1719 * or `GLFW_RELEASE`.
1721 unsigned char buttons
[15];
1722 /*! The states of each [gamepad axis](@ref gamepad_axes), in the range -1.0
1729 /*************************************************************************
1730 * GLFW API functions
1731 *************************************************************************/
1733 /*! @brief Initializes the GLFW library.
1735 * This function initializes the GLFW library. Before most GLFW functions can
1736 * be used, GLFW must be initialized, and before an application terminates GLFW
1737 * should be terminated in order to free any resources allocated during or
1738 * after initialization.
1740 * If this function fails, it calls @ref glfwTerminate before returning. If it
1741 * succeeds, you should call @ref glfwTerminate before the application exits.
1743 * Additional calls to this function after successful initialization but before
1744 * termination will return `GLFW_TRUE` immediately.
1746 * @return `GLFW_TRUE` if successful, or `GLFW_FALSE` if an
1747 * [error](@ref error_handling) occurred.
1749 * @errors Possible errors include @ref GLFW_PLATFORM_ERROR.
1751 * @remark @macos This function will change the current directory of the
1752 * application to the `Contents/Resources` subdirectory of the application's
1753 * bundle, if present. This can be disabled with the @ref
1754 * GLFW_COCOA_CHDIR_RESOURCES init hint.
1756 * @thread_safety This function must only be called from the main thread.
1758 * @sa @ref intro_init
1759 * @sa @ref glfwTerminate
1761 * @since Added in version 1.0.
1765 GLFWAPI
int glfwInit(void);
1767 /*! @brief Terminates the GLFW library.
1769 * This function destroys all remaining windows and cursors, restores any
1770 * modified gamma ramps and frees any other allocated resources. Once this
1771 * function is called, you must again call @ref glfwInit successfully before
1772 * you will be able to use most GLFW functions.
1774 * If GLFW has been successfully initialized, this function should be called
1775 * before the application exits. If initialization fails, there is no need to
1776 * call this function, as it is called by @ref glfwInit before it returns
1779 * @errors Possible errors include @ref GLFW_PLATFORM_ERROR.
1781 * @remark This function may be called before @ref glfwInit.
1783 * @warning The contexts of any remaining windows must not be current on any
1784 * other thread when this function is called.
1786 * @reentrancy This function must not be called from a callback.
1788 * @thread_safety This function must only be called from the main thread.
1790 * @sa @ref intro_init
1793 * @since Added in version 1.0.
1797 GLFWAPI
void glfwTerminate(void);
1799 /*! @brief Sets the specified init hint to the desired value.
1801 * This function sets hints for the next initialization of GLFW.
1803 * The values you set hints to are never reset by GLFW, but they only take
1804 * effect during initialization. Once GLFW has been initialized, any values
1805 * you set will be ignored until the library is terminated and initialized
1808 * Some hints are platform specific. These may be set on any platform but they
1809 * will only affect their specific platform. Other platforms will ignore them.
1810 * Setting these hints requires no platform specific headers or functions.
1812 * @param[in] hint The [init hint](@ref init_hints) to set.
1813 * @param[in] value The new value of the init hint.
1815 * @errors Possible errors include @ref GLFW_INVALID_ENUM and @ref
1816 * GLFW_INVALID_VALUE.
1818 * @remarks This function may be called before @ref glfwInit.
1820 * @thread_safety This function must only be called from the main thread.
1825 * @since Added in version 3.3.
1829 GLFWAPI
void glfwInitHint(int hint
, int value
);
1831 /*! @brief Retrieves the version of the GLFW library.
1833 * This function retrieves the major, minor and revision numbers of the GLFW
1834 * library. It is intended for when you are using GLFW as a shared library and
1835 * want to ensure that you are using the minimum required version.
1837 * Any or all of the version arguments may be `NULL`.
1839 * @param[out] major Where to store the major version number, or `NULL`.
1840 * @param[out] minor Where to store the minor version number, or `NULL`.
1841 * @param[out] rev Where to store the revision number, or `NULL`.
1845 * @remark This function may be called before @ref glfwInit.
1847 * @thread_safety This function may be called from any thread.
1849 * @sa @ref intro_version
1850 * @sa @ref glfwGetVersionString
1852 * @since Added in version 1.0.
1856 GLFWAPI
void glfwGetVersion(int* major
, int* minor
, int* rev
);
1858 /*! @brief Returns a string describing the compile-time configuration.
1860 * This function returns the compile-time generated
1861 * [version string](@ref intro_version_string) of the GLFW library binary. It
1862 * describes the version, platform, compiler and any platform-specific
1863 * compile-time options. It should not be confused with the OpenGL or OpenGL
1864 * ES version string, queried with `glGetString`.
1866 * __Do not use the version string__ to parse the GLFW library version. The
1867 * @ref glfwGetVersion function provides the version of the running library
1868 * binary in numerical format.
1870 * @return The ASCII encoded GLFW version string.
1874 * @remark This function may be called before @ref glfwInit.
1876 * @pointer_lifetime The returned string is static and compile-time generated.
1878 * @thread_safety This function may be called from any thread.
1880 * @sa @ref intro_version
1881 * @sa @ref glfwGetVersion
1883 * @since Added in version 3.0.
1887 GLFWAPI
const char* glfwGetVersionString(void);
1889 /*! @brief Returns and clears the last error for the calling thread.
1891 * This function returns and clears the [error code](@ref errors) of the last
1892 * error that occurred on the calling thread, and optionally a UTF-8 encoded
1893 * human-readable description of it. If no error has occurred since the last
1894 * call, it returns @ref GLFW_NO_ERROR (zero) and the description pointer is
1897 * @param[in] description Where to store the error description pointer, or `NULL`.
1898 * @return The last error code for the calling thread, or @ref GLFW_NO_ERROR
1903 * @pointer_lifetime The returned string is allocated and freed by GLFW. You
1904 * should not free it yourself. It is guaranteed to be valid only until the
1905 * next error occurs or the library is terminated.
1907 * @remark This function may be called before @ref glfwInit.
1909 * @thread_safety This function may be called from any thread.
1911 * @sa @ref error_handling
1912 * @sa @ref glfwSetErrorCallback
1914 * @since Added in version 3.3.
1918 GLFWAPI
int glfwGetError(const char** description
);
1920 /*! @brief Sets the error callback.
1922 * This function sets the error callback, which is called with an error code
1923 * and a human-readable description each time a GLFW error occurs.
1925 * The error code is set before the callback is called. Calling @ref
1926 * glfwGetError from the error callback will return the same value as the error
1929 * The error callback is called on the thread where the error occurred. If you
1930 * are using GLFW from multiple threads, your error callback needs to be
1931 * written accordingly.
1933 * Because the description string may have been generated specifically for that
1934 * error, it is not guaranteed to be valid after the callback has returned. If
1935 * you wish to use it after the callback returns, you need to make a copy.
1937 * Once set, the error callback remains set even after the library has been
1940 * @param[in] callback The new callback, or `NULL` to remove the currently set
1942 * @return The previously set callback, or `NULL` if no callback was set.
1944 * @callback_signature
1946 * void callback_name(int error_code, const char* description)
1948 * For more information about the callback parameters, see the
1949 * [callback pointer type](@ref GLFWerrorfun).
1953 * @remark This function may be called before @ref glfwInit.
1955 * @thread_safety This function must only be called from the main thread.
1957 * @sa @ref error_handling
1958 * @sa @ref glfwGetError
1960 * @since Added in version 3.0.
1964 GLFWAPI GLFWerrorfun
glfwSetErrorCallback(GLFWerrorfun callback
);
1966 /*! @brief Returns the currently connected monitors.
1968 * This function returns an array of handles for all currently connected
1969 * monitors. The primary monitor is always first in the returned array. If no
1970 * monitors were found, this function returns `NULL`.
1972 * @param[out] count Where to store the number of monitors in the returned
1973 * array. This is set to zero if an error occurred.
1974 * @return An array of monitor handles, or `NULL` if no monitors were found or
1975 * if an [error](@ref error_handling) occurred.
1977 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
1979 * @pointer_lifetime The returned array is allocated and freed by GLFW. You
1980 * should not free it yourself. It is guaranteed to be valid only until the
1981 * monitor configuration changes or the library is terminated.
1983 * @thread_safety This function must only be called from the main thread.
1985 * @sa @ref monitor_monitors
1986 * @sa @ref monitor_event
1987 * @sa @ref glfwGetPrimaryMonitor
1989 * @since Added in version 3.0.
1993 GLFWAPI GLFWmonitor
** glfwGetMonitors(int* count
);
1995 /*! @brief Returns the primary monitor.
1997 * This function returns the primary monitor. This is usually the monitor
1998 * where elements like the task bar or global menu bar are located.
2000 * @return The primary monitor, or `NULL` if no monitors were found or if an
2001 * [error](@ref error_handling) occurred.
2003 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
2005 * @thread_safety This function must only be called from the main thread.
2007 * @remark The primary monitor is always first in the array returned by @ref
2010 * @sa @ref monitor_monitors
2011 * @sa @ref glfwGetMonitors
2013 * @since Added in version 3.0.
2017 GLFWAPI GLFWmonitor
* glfwGetPrimaryMonitor(void);
2019 /*! @brief Returns the position of the monitor's viewport on the virtual screen.
2021 * This function returns the position, in screen coordinates, of the upper-left
2022 * corner of the specified monitor.
2024 * Any or all of the position arguments may be `NULL`. If an error occurs, all
2025 * non-`NULL` position arguments will be set to zero.
2027 * @param[in] monitor The monitor to query.
2028 * @param[out] xpos Where to store the monitor x-coordinate, or `NULL`.
2029 * @param[out] ypos Where to store the monitor y-coordinate, or `NULL`.
2031 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
2032 * GLFW_PLATFORM_ERROR.
2034 * @thread_safety This function must only be called from the main thread.
2036 * @sa @ref monitor_properties
2038 * @since Added in version 3.0.
2042 GLFWAPI
void glfwGetMonitorPos(GLFWmonitor
* monitor
, int* xpos
, int* ypos
);
2044 /*! @brief Retrieves the work area of the monitor.
2046 * This function returns the position, in screen coordinates, of the upper-left
2047 * corner of the work area of the specified monitor along with the work area
2048 * size in screen coordinates. The work area is defined as the area of the
2049 * monitor not occluded by the operating system task bar where present. If no
2050 * task bar exists then the work area is the monitor resolution in screen
2053 * Any or all of the position and size arguments may be `NULL`. If an error
2054 * occurs, all non-`NULL` position and size arguments will be set to zero.
2056 * @param[in] monitor The monitor to query.
2057 * @param[out] xpos Where to store the monitor x-coordinate, or `NULL`.
2058 * @param[out] ypos Where to store the monitor y-coordinate, or `NULL`.
2059 * @param[out] width Where to store the monitor width, or `NULL`.
2060 * @param[out] height Where to store the monitor height, or `NULL`.
2062 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
2063 * GLFW_PLATFORM_ERROR.
2065 * @thread_safety This function must only be called from the main thread.
2067 * @sa @ref monitor_workarea
2069 * @since Added in version 3.3.
2073 GLFWAPI
void glfwGetMonitorWorkarea(GLFWmonitor
* monitor
, int* xpos
, int* ypos
, int* width
, int* height
);
2075 /*! @brief Returns the physical size of the monitor.
2077 * This function returns the size, in millimetres, of the display area of the
2078 * specified monitor.
2080 * Some systems do not provide accurate monitor size information, either
2081 * because the monitor
2082 * [EDID](https://en.wikipedia.org/wiki/Extended_display_identification_data)
2083 * data is incorrect or because the driver does not report it accurately.
2085 * Any or all of the size arguments may be `NULL`. If an error occurs, all
2086 * non-`NULL` size arguments will be set to zero.
2088 * @param[in] monitor The monitor to query.
2089 * @param[out] widthMM Where to store the width, in millimetres, of the
2090 * monitor's display area, or `NULL`.
2091 * @param[out] heightMM Where to store the height, in millimetres, of the
2092 * monitor's display area, or `NULL`.
2094 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
2096 * @remark @win32 calculates the returned physical size from the
2097 * current resolution and system DPI instead of querying the monitor EDID data.
2099 * @thread_safety This function must only be called from the main thread.
2101 * @sa @ref monitor_properties
2103 * @since Added in version 3.0.
2107 GLFWAPI
void glfwGetMonitorPhysicalSize(GLFWmonitor
* monitor
, int* widthMM
, int* heightMM
);
2109 /*! @brief Retrieves the content scale for the specified monitor.
2111 * This function retrieves the content scale for the specified monitor. The
2112 * content scale is the ratio between the current DPI and the platform's
2113 * default DPI. This is especially important for text and any UI elements. If
2114 * the pixel dimensions of your UI scaled by this look appropriate on your
2115 * machine then it should appear at a reasonable size on other machines
2116 * regardless of their DPI and scaling settings. This relies on the system DPI
2117 * and scaling settings being somewhat correct.
2119 * The content scale may depend on both the monitor resolution and pixel
2120 * density and on user settings. It may be very different from the raw DPI
2121 * calculated from the physical size and current resolution.
2123 * @param[in] monitor The monitor to query.
2124 * @param[out] xscale Where to store the x-axis content scale, or `NULL`.
2125 * @param[out] yscale Where to store the y-axis content scale, or `NULL`.
2127 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
2128 * GLFW_PLATFORM_ERROR.
2130 * @thread_safety This function must only be called from the main thread.
2132 * @sa @ref monitor_scale
2133 * @sa @ref glfwGetWindowContentScale
2135 * @since Added in version 3.3.
2139 GLFWAPI
void glfwGetMonitorContentScale(GLFWmonitor
* monitor
, float* xscale
, float* yscale
);
2141 /*! @brief Returns the name of the specified monitor.
2143 * This function returns a human-readable name, encoded as UTF-8, of the
2144 * specified monitor. The name typically reflects the make and model of the
2145 * monitor and is not guaranteed to be unique among the connected monitors.
2147 * @param[in] monitor The monitor to query.
2148 * @return The UTF-8 encoded name of the monitor, or `NULL` if an
2149 * [error](@ref error_handling) occurred.
2151 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
2153 * @pointer_lifetime The returned string is allocated and freed by GLFW. You
2154 * should not free it yourself. It is valid until the specified monitor is
2155 * disconnected or the library is terminated.
2157 * @thread_safety This function must only be called from the main thread.
2159 * @sa @ref monitor_properties
2161 * @since Added in version 3.0.
2165 GLFWAPI
const char* glfwGetMonitorName(GLFWmonitor
* monitor
);
2167 /*! @brief Sets the user pointer of the specified monitor.
2169 * This function sets the user-defined pointer of the specified monitor. The
2170 * current value is retained until the monitor is disconnected. The initial
2173 * This function may be called from the monitor callback, even for a monitor
2174 * that is being disconnected.
2176 * @param[in] monitor The monitor whose pointer to set.
2177 * @param[in] pointer The new value.
2179 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
2181 * @thread_safety This function may be called from any thread. Access is not
2184 * @sa @ref monitor_userptr
2185 * @sa @ref glfwGetMonitorUserPointer
2187 * @since Added in version 3.3.
2191 GLFWAPI
void glfwSetMonitorUserPointer(GLFWmonitor
* monitor
, void* pointer
);
2193 /*! @brief Returns the user pointer of the specified monitor.
2195 * This function returns the current value of the user-defined pointer of the
2196 * specified monitor. The initial value is `NULL`.
2198 * This function may be called from the monitor callback, even for a monitor
2199 * that is being disconnected.
2201 * @param[in] monitor The monitor whose pointer to return.
2203 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
2205 * @thread_safety This function may be called from any thread. Access is not
2208 * @sa @ref monitor_userptr
2209 * @sa @ref glfwSetMonitorUserPointer
2211 * @since Added in version 3.3.
2215 GLFWAPI
void* glfwGetMonitorUserPointer(GLFWmonitor
* monitor
);
2217 /*! @brief Sets the monitor configuration callback.
2219 * This function sets the monitor configuration callback, or removes the
2220 * currently set callback. This is called when a monitor is connected to or
2221 * disconnected from the system.
2223 * @param[in] callback The new callback, or `NULL` to remove the currently set
2225 * @return The previously set callback, or `NULL` if no callback was set or the
2226 * library had not been [initialized](@ref intro_init).
2228 * @callback_signature
2230 * void function_name(GLFWmonitor* monitor, int event)
2232 * For more information about the callback parameters, see the
2233 * [function pointer type](@ref GLFWmonitorfun).
2235 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
2237 * @thread_safety This function must only be called from the main thread.
2239 * @sa @ref monitor_event
2241 * @since Added in version 3.0.
2245 GLFWAPI GLFWmonitorfun
glfwSetMonitorCallback(GLFWmonitorfun callback
);
2247 /*! @brief Returns the available video modes for the specified monitor.
2249 * This function returns an array of all video modes supported by the specified
2250 * monitor. The returned array is sorted in ascending order, first by color
2251 * bit depth (the sum of all channel depths) and then by resolution area (the
2252 * product of width and height).
2254 * @param[in] monitor The monitor to query.
2255 * @param[out] count Where to store the number of video modes in the returned
2256 * array. This is set to zero if an error occurred.
2257 * @return An array of video modes, or `NULL` if an
2258 * [error](@ref error_handling) occurred.
2260 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
2261 * GLFW_PLATFORM_ERROR.
2263 * @pointer_lifetime The returned array is allocated and freed by GLFW. You
2264 * should not free it yourself. It is valid until the specified monitor is
2265 * disconnected, this function is called again for that monitor or the library
2268 * @thread_safety This function must only be called from the main thread.
2270 * @sa @ref monitor_modes
2271 * @sa @ref glfwGetVideoMode
2273 * @since Added in version 1.0.
2274 * @glfw3 Changed to return an array of modes for a specific monitor.
2278 GLFWAPI
const GLFWvidmode
* glfwGetVideoModes(GLFWmonitor
* monitor
, int* count
);
2280 /*! @brief Returns the current mode of the specified monitor.
2282 * This function returns the current video mode of the specified monitor. If
2283 * you have created a full screen window for that monitor, the return value
2284 * will depend on whether that window is iconified.
2286 * @param[in] monitor The monitor to query.
2287 * @return The current mode of the monitor, or `NULL` if an
2288 * [error](@ref error_handling) occurred.
2290 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
2291 * GLFW_PLATFORM_ERROR.
2293 * @pointer_lifetime The returned array is allocated and freed by GLFW. You
2294 * should not free it yourself. It is valid until the specified monitor is
2295 * disconnected or the library is terminated.
2297 * @thread_safety This function must only be called from the main thread.
2299 * @sa @ref monitor_modes
2300 * @sa @ref glfwGetVideoModes
2302 * @since Added in version 3.0. Replaces `glfwGetDesktopMode`.
2306 GLFWAPI
const GLFWvidmode
* glfwGetVideoMode(GLFWmonitor
* monitor
);
2308 /*! @brief Generates a gamma ramp and sets it for the specified monitor.
2310 * This function generates an appropriately sized gamma ramp from the specified
2311 * exponent and then calls @ref glfwSetGammaRamp with it. The value must be
2312 * a finite number greater than zero.
2314 * The software controlled gamma ramp is applied _in addition_ to the hardware
2315 * gamma correction, which today is usually an approximation of sRGB gamma.
2316 * This means that setting a perfectly linear ramp, or gamma 1.0, will produce
2317 * the default (usually sRGB-like) behavior.
2319 * For gamma correct rendering with OpenGL or OpenGL ES, see the @ref
2320 * GLFW_SRGB_CAPABLE hint.
2322 * @param[in] monitor The monitor whose gamma ramp to set.
2323 * @param[in] gamma The desired exponent.
2325 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
2326 * GLFW_INVALID_VALUE and @ref GLFW_PLATFORM_ERROR.
2328 * @remark @wayland Gamma handling is a privileged protocol, this function
2329 * will thus never be implemented and emits @ref GLFW_PLATFORM_ERROR.
2331 * @thread_safety This function must only be called from the main thread.
2333 * @sa @ref monitor_gamma
2335 * @since Added in version 3.0.
2339 GLFWAPI
void glfwSetGamma(GLFWmonitor
* monitor
, float gamma
);
2341 /*! @brief Returns the current gamma ramp for the specified monitor.
2343 * This function returns the current gamma ramp of the specified monitor.
2345 * @param[in] monitor The monitor to query.
2346 * @return The current gamma ramp, or `NULL` if an
2347 * [error](@ref error_handling) occurred.
2349 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
2350 * GLFW_PLATFORM_ERROR.
2352 * @remark @wayland Gamma handling is a privileged protocol, this function
2353 * will thus never be implemented and emits @ref GLFW_PLATFORM_ERROR while
2356 * @pointer_lifetime The returned structure and its arrays are allocated and
2357 * freed by GLFW. You should not free them yourself. They are valid until the
2358 * specified monitor is disconnected, this function is called again for that
2359 * monitor or the library is terminated.
2361 * @thread_safety This function must only be called from the main thread.
2363 * @sa @ref monitor_gamma
2365 * @since Added in version 3.0.
2369 GLFWAPI
const GLFWgammaramp
* glfwGetGammaRamp(GLFWmonitor
* monitor
);
2371 /*! @brief Sets the current gamma ramp for the specified monitor.
2373 * This function sets the current gamma ramp for the specified monitor. The
2374 * original gamma ramp for that monitor is saved by GLFW the first time this
2375 * function is called and is restored by @ref glfwTerminate.
2377 * The software controlled gamma ramp is applied _in addition_ to the hardware
2378 * gamma correction, which today is usually an approximation of sRGB gamma.
2379 * This means that setting a perfectly linear ramp, or gamma 1.0, will produce
2380 * the default (usually sRGB-like) behavior.
2382 * For gamma correct rendering with OpenGL or OpenGL ES, see the @ref
2383 * GLFW_SRGB_CAPABLE hint.
2385 * @param[in] monitor The monitor whose gamma ramp to set.
2386 * @param[in] ramp The gamma ramp to use.
2388 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
2389 * GLFW_PLATFORM_ERROR.
2391 * @remark The size of the specified gamma ramp should match the size of the
2392 * current ramp for that monitor.
2394 * @remark @win32 The gamma ramp size must be 256.
2396 * @remark @wayland Gamma handling is a privileged protocol, this function
2397 * will thus never be implemented and emits @ref GLFW_PLATFORM_ERROR.
2399 * @pointer_lifetime The specified gamma ramp is copied before this function
2402 * @thread_safety This function must only be called from the main thread.
2404 * @sa @ref monitor_gamma
2406 * @since Added in version 3.0.
2410 GLFWAPI
void glfwSetGammaRamp(GLFWmonitor
* monitor
, const GLFWgammaramp
* ramp
);
2412 /*! @brief Resets all window hints to their default values.
2414 * This function resets all window hints to their
2415 * [default values](@ref window_hints_values).
2417 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
2419 * @thread_safety This function must only be called from the main thread.
2421 * @sa @ref window_hints
2422 * @sa @ref glfwWindowHint
2423 * @sa @ref glfwWindowHintString
2425 * @since Added in version 3.0.
2429 GLFWAPI
void glfwDefaultWindowHints(void);
2431 /*! @brief Sets the specified window hint to the desired value.
2433 * This function sets hints for the next call to @ref glfwCreateWindow. The
2434 * hints, once set, retain their values until changed by a call to this
2435 * function or @ref glfwDefaultWindowHints, or until the library is terminated.
2437 * Only integer value hints can be set with this function. String value hints
2438 * are set with @ref glfwWindowHintString.
2440 * This function does not check whether the specified hint values are valid.
2441 * If you set hints to invalid values this will instead be reported by the next
2442 * call to @ref glfwCreateWindow.
2444 * Some hints are platform specific. These may be set on any platform but they
2445 * will only affect their specific platform. Other platforms will ignore them.
2446 * Setting these hints requires no platform specific headers or functions.
2448 * @param[in] hint The [window hint](@ref window_hints) to set.
2449 * @param[in] value The new value of the window hint.
2451 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
2452 * GLFW_INVALID_ENUM.
2454 * @thread_safety This function must only be called from the main thread.
2456 * @sa @ref window_hints
2457 * @sa @ref glfwWindowHintString
2458 * @sa @ref glfwDefaultWindowHints
2460 * @since Added in version 3.0. Replaces `glfwOpenWindowHint`.
2464 GLFWAPI
void glfwWindowHint(int hint
, int value
);
2466 /*! @brief Sets the specified window hint to the desired value.
2468 * This function sets hints for the next call to @ref glfwCreateWindow. The
2469 * hints, once set, retain their values until changed by a call to this
2470 * function or @ref glfwDefaultWindowHints, or until the library is terminated.
2472 * Only string type hints can be set with this function. Integer value hints
2473 * are set with @ref glfwWindowHint.
2475 * This function does not check whether the specified hint values are valid.
2476 * If you set hints to invalid values this will instead be reported by the next
2477 * call to @ref glfwCreateWindow.
2479 * Some hints are platform specific. These may be set on any platform but they
2480 * will only affect their specific platform. Other platforms will ignore them.
2481 * Setting these hints requires no platform specific headers or functions.
2483 * @param[in] hint The [window hint](@ref window_hints) to set.
2484 * @param[in] value The new value of the window hint.
2486 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
2487 * GLFW_INVALID_ENUM.
2489 * @pointer_lifetime The specified string is copied before this function
2492 * @thread_safety This function must only be called from the main thread.
2494 * @sa @ref window_hints
2495 * @sa @ref glfwWindowHint
2496 * @sa @ref glfwDefaultWindowHints
2498 * @since Added in version 3.3.
2502 GLFWAPI
void glfwWindowHintString(int hint
, const char* value
);
2504 /*! @brief Creates a window and its associated context.
2506 * This function creates a window and its associated OpenGL or OpenGL ES
2507 * context. Most of the options controlling how the window and its context
2508 * should be created are specified with [window hints](@ref window_hints).
2510 * Successful creation does not change which context is current. Before you
2511 * can use the newly created context, you need to
2512 * [make it current](@ref context_current). For information about the `share`
2513 * parameter, see @ref context_sharing.
2515 * The created window, framebuffer and context may differ from what you
2516 * requested, as not all parameters and hints are
2517 * [hard constraints](@ref window_hints_hard). This includes the size of the
2518 * window, especially for full screen windows. To query the actual attributes
2519 * of the created window, framebuffer and context, see @ref
2520 * glfwGetWindowAttrib, @ref glfwGetWindowSize and @ref glfwGetFramebufferSize.
2522 * To create a full screen window, you need to specify the monitor the window
2523 * will cover. If no monitor is specified, the window will be windowed mode.
2524 * Unless you have a way for the user to choose a specific monitor, it is
2525 * recommended that you pick the primary monitor. For more information on how
2526 * to query connected monitors, see @ref monitor_monitors.
2528 * For full screen windows, the specified size becomes the resolution of the
2529 * window's _desired video mode_. As long as a full screen window is not
2530 * iconified, the supported video mode most closely matching the desired video
2531 * mode is set for the specified monitor. For more information about full
2532 * screen windows, including the creation of so called _windowed full screen_
2533 * or _borderless full screen_ windows, see @ref window_windowed_full_screen.
2535 * Once you have created the window, you can switch it between windowed and
2536 * full screen mode with @ref glfwSetWindowMonitor. This will not affect its
2537 * OpenGL or OpenGL ES context.
2539 * By default, newly created windows use the placement recommended by the
2540 * window system. To create the window at a specific position, make it
2541 * initially invisible using the [GLFW_VISIBLE](@ref GLFW_VISIBLE_hint) window
2542 * hint, set its [position](@ref window_pos) and then [show](@ref window_hide)
2545 * As long as at least one full screen window is not iconified, the screensaver
2546 * is prohibited from starting.
2548 * Window systems put limits on window sizes. Very large or very small window
2549 * dimensions may be overridden by the window system on creation. Check the
2550 * actual [size](@ref window_size) after creation.
2552 * The [swap interval](@ref buffer_swap) is not set during window creation and
2553 * the initial value may vary depending on driver settings and defaults.
2555 * @param[in] width The desired width, in screen coordinates, of the window.
2556 * This must be greater than zero.
2557 * @param[in] height The desired height, in screen coordinates, of the window.
2558 * This must be greater than zero.
2559 * @param[in] title The initial, UTF-8 encoded window title.
2560 * @param[in] monitor The monitor to use for full screen mode, or `NULL` for
2562 * @param[in] share The window whose context to share resources with, or `NULL`
2563 * to not share resources.
2564 * @return The handle of the created window, or `NULL` if an
2565 * [error](@ref error_handling) occurred.
2567 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
2568 * GLFW_INVALID_ENUM, @ref GLFW_INVALID_VALUE, @ref GLFW_API_UNAVAILABLE, @ref
2569 * GLFW_VERSION_UNAVAILABLE, @ref GLFW_FORMAT_UNAVAILABLE and @ref
2570 * GLFW_PLATFORM_ERROR.
2572 * @remark @win32 Window creation will fail if the Microsoft GDI software
2573 * OpenGL implementation is the only one available.
2575 * @remark @win32 If the executable has an icon resource named `GLFW_ICON,` it
2576 * will be set as the initial icon for the window. If no such icon is present,
2577 * the `IDI_APPLICATION` icon will be used instead. To set a different icon,
2578 * see @ref glfwSetWindowIcon.
2580 * @remark @win32 The context to share resources with must not be current on
2583 * @remark @macos The OS only supports forward-compatible core profile contexts
2584 * for OpenGL versions 3.2 and later. Before creating an OpenGL context of
2585 * version 3.2 or later you must set the
2586 * [GLFW_OPENGL_FORWARD_COMPAT](@ref GLFW_OPENGL_FORWARD_COMPAT_hint) and
2587 * [GLFW_OPENGL_PROFILE](@ref GLFW_OPENGL_PROFILE_hint) hints accordingly.
2588 * OpenGL 3.0 and 3.1 contexts are not supported at all on macOS.
2590 * @remark @macos The GLFW window has no icon, as it is not a document
2591 * window, but the dock icon will be the same as the application bundle's icon.
2592 * For more information on bundles, see the
2593 * [Bundle Programming Guide](https://developer.apple.com/library/mac/documentation/CoreFoundation/Conceptual/CFBundles/)
2594 * in the Mac Developer Library.
2596 * @remark @macos The first time a window is created the menu bar is created.
2597 * If GLFW finds a `MainMenu.nib` it is loaded and assumed to contain a menu
2598 * bar. Otherwise a minimal menu bar is created manually with common commands
2599 * like Hide, Quit and About. The About entry opens a minimal about dialog
2600 * with information from the application's bundle. Menu bar creation can be
2601 * disabled entirely with the @ref GLFW_COCOA_MENUBAR init hint.
2603 * @remark @macos On OS X 10.10 and later the window frame will not be rendered
2604 * at full resolution on Retina displays unless the
2605 * [GLFW_COCOA_RETINA_FRAMEBUFFER](@ref GLFW_COCOA_RETINA_FRAMEBUFFER_hint)
2606 * hint is `GLFW_TRUE` and the `NSHighResolutionCapable` key is enabled in the
2607 * application bundle's `Info.plist`. For more information, see
2608 * [High Resolution Guidelines for OS X](https://developer.apple.com/library/mac/documentation/GraphicsAnimation/Conceptual/HighResolutionOSX/Explained/Explained.html)
2609 * in the Mac Developer Library. The GLFW test and example programs use
2610 * a custom `Info.plist` template for this, which can be found as
2611 * `CMake/MacOSXBundleInfo.plist.in` in the source tree.
2613 * @remark @macos When activating frame autosaving with
2614 * [GLFW_COCOA_FRAME_NAME](@ref GLFW_COCOA_FRAME_NAME_hint), the specified
2615 * window size and position may be overridden by previously saved values.
2617 * @remark @x11 Some window managers will not respect the placement of
2618 * initially hidden windows.
2620 * @remark @x11 Due to the asynchronous nature of X11, it may take a moment for
2621 * a window to reach its requested state. This means you may not be able to
2622 * query the final size, position or other attributes directly after window
2625 * @remark @x11 The class part of the `WM_CLASS` window property will by
2626 * default be set to the window title passed to this function. The instance
2627 * part will use the contents of the `RESOURCE_NAME` environment variable, if
2628 * present and not empty, or fall back to the window title. Set the
2629 * [GLFW_X11_CLASS_NAME](@ref GLFW_X11_CLASS_NAME_hint) and
2630 * [GLFW_X11_INSTANCE_NAME](@ref GLFW_X11_INSTANCE_NAME_hint) window hints to
2633 * @remark @wayland Compositors should implement the xdg-decoration protocol
2634 * for GLFW to decorate the window properly. If this protocol isn't
2635 * supported, or if the compositor prefers client-side decorations, a very
2636 * simple fallback frame will be drawn using the wp_viewporter protocol. A
2637 * compositor can still emit close, maximize or fullscreen events, using for
2638 * instance a keybind mechanism. If neither of these protocols is supported,
2639 * the window won't be decorated.
2641 * @remark @wayland A full screen window will not attempt to change the mode,
2642 * no matter what the requested size or refresh rate.
2644 * @remark @wayland Screensaver inhibition requires the idle-inhibit protocol
2645 * to be implemented in the user's compositor.
2647 * @thread_safety This function must only be called from the main thread.
2649 * @sa @ref window_creation
2650 * @sa @ref glfwDestroyWindow
2652 * @since Added in version 3.0. Replaces `glfwOpenWindow`.
2656 GLFWAPI GLFWwindow
* glfwCreateWindow(int width
, int height
, const char* title
, GLFWmonitor
* monitor
, GLFWwindow
* share
);
2658 /*! @brief Destroys the specified window and its context.
2660 * This function destroys the specified window and its context. On calling
2661 * this function, no further callbacks will be called for that window.
2663 * If the context of the specified window is current on the main thread, it is
2664 * detached before being destroyed.
2666 * @param[in] window The window to destroy.
2668 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
2669 * GLFW_PLATFORM_ERROR.
2671 * @note The context of the specified window must not be current on any other
2672 * thread when this function is called.
2674 * @reentrancy This function must not be called from a callback.
2676 * @thread_safety This function must only be called from the main thread.
2678 * @sa @ref window_creation
2679 * @sa @ref glfwCreateWindow
2681 * @since Added in version 3.0. Replaces `glfwCloseWindow`.
2685 GLFWAPI
void glfwDestroyWindow(GLFWwindow
* window
);
2687 /*! @brief Checks the close flag of the specified window.
2689 * This function returns the value of the close flag of the specified window.
2691 * @param[in] window The window to query.
2692 * @return The value of the close flag.
2694 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
2696 * @thread_safety This function may be called from any thread. Access is not
2699 * @sa @ref window_close
2701 * @since Added in version 3.0.
2705 GLFWAPI
int glfwWindowShouldClose(GLFWwindow
* window
);
2707 /*! @brief Sets the close flag of the specified window.
2709 * This function sets the value of the close flag of the specified window.
2710 * This can be used to override the user's attempt to close the window, or
2711 * to signal that it should be closed.
2713 * @param[in] window The window whose flag to change.
2714 * @param[in] value The new value.
2716 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
2718 * @thread_safety This function may be called from any thread. Access is not
2721 * @sa @ref window_close
2723 * @since Added in version 3.0.
2727 GLFWAPI
void glfwSetWindowShouldClose(GLFWwindow
* window
, int value
);
2729 /*! @brief Sets the title of the specified window.
2731 * This function sets the window title, encoded as UTF-8, of the specified
2734 * @param[in] window The window whose title to change.
2735 * @param[in] title The UTF-8 encoded window title.
2737 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
2738 * GLFW_PLATFORM_ERROR.
2740 * @remark @macos The window title will not be updated until the next time you
2743 * @thread_safety This function must only be called from the main thread.
2745 * @sa @ref window_title
2747 * @since Added in version 1.0.
2748 * @glfw3 Added window handle parameter.
2752 GLFWAPI
void glfwSetWindowTitle(GLFWwindow
* window
, const char* title
);
2754 /*! @brief Sets the icon for the specified window.
2756 * This function sets the icon of the specified window. If passed an array of
2757 * candidate images, those of or closest to the sizes desired by the system are
2758 * selected. If no images are specified, the window reverts to its default
2761 * The pixels are 32-bit, little-endian, non-premultiplied RGBA, i.e. eight
2762 * bits per channel with the red channel first. They are arranged canonically
2763 * as packed sequential rows, starting from the top-left corner.
2765 * The desired image sizes varies depending on platform and system settings.
2766 * The selected images will be rescaled as needed. Good sizes include 16x16,
2769 * @param[in] window The window whose icon to set.
2770 * @param[in] count The number of images in the specified array, or zero to
2771 * revert to the default window icon.
2772 * @param[in] images The images to create the icon from. This is ignored if
2775 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
2776 * GLFW_PLATFORM_ERROR.
2778 * @pointer_lifetime The specified image data is copied before this function
2781 * @remark @macos The GLFW window has no icon, as it is not a document
2782 * window, so this function does nothing. The dock icon will be the same as
2783 * the application bundle's icon. For more information on bundles, see the
2784 * [Bundle Programming Guide](https://developer.apple.com/library/mac/documentation/CoreFoundation/Conceptual/CFBundles/)
2785 * in the Mac Developer Library.
2787 * @remark @wayland There is no existing protocol to change an icon, the
2788 * window will thus inherit the one defined in the application's desktop file.
2789 * This function always emits @ref GLFW_PLATFORM_ERROR.
2791 * @thread_safety This function must only be called from the main thread.
2793 * @sa @ref window_icon
2795 * @since Added in version 3.2.
2799 GLFWAPI
void glfwSetWindowIcon(GLFWwindow
* window
, int count
, const GLFWimage
* images
);
2801 /*! @brief Retrieves the position of the content area of the specified window.
2803 * This function retrieves the position, in screen coordinates, of the
2804 * upper-left corner of the content area of the specified window.
2806 * Any or all of the position arguments may be `NULL`. If an error occurs, all
2807 * non-`NULL` position arguments will be set to zero.
2809 * @param[in] window The window to query.
2810 * @param[out] xpos Where to store the x-coordinate of the upper-left corner of
2811 * the content area, or `NULL`.
2812 * @param[out] ypos Where to store the y-coordinate of the upper-left corner of
2813 * the content area, or `NULL`.
2815 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
2816 * GLFW_PLATFORM_ERROR.
2818 * @remark @wayland There is no way for an application to retrieve the global
2819 * position of its windows, this function will always emit @ref
2820 * GLFW_PLATFORM_ERROR.
2822 * @thread_safety This function must only be called from the main thread.
2824 * @sa @ref window_pos
2825 * @sa @ref glfwSetWindowPos
2827 * @since Added in version 3.0.
2831 GLFWAPI
void glfwGetWindowPos(GLFWwindow
* window
, int* xpos
, int* ypos
);
2833 /*! @brief Sets the position of the content area of the specified window.
2835 * This function sets the position, in screen coordinates, of the upper-left
2836 * corner of the content area of the specified windowed mode window. If the
2837 * window is a full screen window, this function does nothing.
2839 * __Do not use this function__ to move an already visible window unless you
2840 * have very good reasons for doing so, as it will confuse and annoy the user.
2842 * The window manager may put limits on what positions are allowed. GLFW
2843 * cannot and should not override these limits.
2845 * @param[in] window The window to query.
2846 * @param[in] xpos The x-coordinate of the upper-left corner of the content area.
2847 * @param[in] ypos The y-coordinate of the upper-left corner of the content area.
2849 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
2850 * GLFW_PLATFORM_ERROR.
2852 * @remark @wayland There is no way for an application to set the global
2853 * position of its windows, this function will always emit @ref
2854 * GLFW_PLATFORM_ERROR.
2856 * @thread_safety This function must only be called from the main thread.
2858 * @sa @ref window_pos
2859 * @sa @ref glfwGetWindowPos
2861 * @since Added in version 1.0.
2862 * @glfw3 Added window handle parameter.
2866 GLFWAPI
void glfwSetWindowPos(GLFWwindow
* window
, int xpos
, int ypos
);
2868 /*! @brief Retrieves the size of the content area of the specified window.
2870 * This function retrieves the size, in screen coordinates, of the content area
2871 * of the specified window. If you wish to retrieve the size of the
2872 * framebuffer of the window in pixels, see @ref glfwGetFramebufferSize.
2874 * Any or all of the size arguments may be `NULL`. If an error occurs, all
2875 * non-`NULL` size arguments will be set to zero.
2877 * @param[in] window The window whose size to retrieve.
2878 * @param[out] width Where to store the width, in screen coordinates, of the
2879 * content area, or `NULL`.
2880 * @param[out] height Where to store the height, in screen coordinates, of the
2881 * content area, or `NULL`.
2883 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
2884 * GLFW_PLATFORM_ERROR.
2886 * @thread_safety This function must only be called from the main thread.
2888 * @sa @ref window_size
2889 * @sa @ref glfwSetWindowSize
2891 * @since Added in version 1.0.
2892 * @glfw3 Added window handle parameter.
2896 GLFWAPI
void glfwGetWindowSize(GLFWwindow
* window
, int* width
, int* height
);
2898 /*! @brief Sets the size limits of the specified window.
2900 * This function sets the size limits of the content area of the specified
2901 * window. If the window is full screen, the size limits only take effect
2902 * once it is made windowed. If the window is not resizable, this function
2905 * The size limits are applied immediately to a windowed mode window and may
2906 * cause it to be resized.
2908 * The maximum dimensions must be greater than or equal to the minimum
2909 * dimensions and all must be greater than or equal to zero.
2911 * @param[in] window The window to set limits for.
2912 * @param[in] minwidth The minimum width, in screen coordinates, of the content
2913 * area, or `GLFW_DONT_CARE`.
2914 * @param[in] minheight The minimum height, in screen coordinates, of the
2915 * content area, or `GLFW_DONT_CARE`.
2916 * @param[in] maxwidth The maximum width, in screen coordinates, of the content
2917 * area, or `GLFW_DONT_CARE`.
2918 * @param[in] maxheight The maximum height, in screen coordinates, of the
2919 * content area, or `GLFW_DONT_CARE`.
2921 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
2922 * GLFW_INVALID_VALUE and @ref GLFW_PLATFORM_ERROR.
2924 * @remark If you set size limits and an aspect ratio that conflict, the
2925 * results are undefined.
2927 * @remark @wayland The size limits will not be applied until the window is
2928 * actually resized, either by the user or by the compositor.
2930 * @thread_safety This function must only be called from the main thread.
2932 * @sa @ref window_sizelimits
2933 * @sa @ref glfwSetWindowAspectRatio
2935 * @since Added in version 3.2.
2939 GLFWAPI
void glfwSetWindowSizeLimits(GLFWwindow
* window
, int minwidth
, int minheight
, int maxwidth
, int maxheight
);
2941 /*! @brief Sets the aspect ratio of the specified window.
2943 * This function sets the required aspect ratio of the content area of the
2944 * specified window. If the window is full screen, the aspect ratio only takes
2945 * effect once it is made windowed. If the window is not resizable, this
2946 * function does nothing.
2948 * The aspect ratio is specified as a numerator and a denominator and both
2949 * values must be greater than zero. For example, the common 16:9 aspect ratio
2950 * is specified as 16 and 9, respectively.
2952 * If the numerator and denominator is set to `GLFW_DONT_CARE` then the aspect
2953 * ratio limit is disabled.
2955 * The aspect ratio is applied immediately to a windowed mode window and may
2956 * cause it to be resized.
2958 * @param[in] window The window to set limits for.
2959 * @param[in] numer The numerator of the desired aspect ratio, or
2961 * @param[in] denom The denominator of the desired aspect ratio, or
2964 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
2965 * GLFW_INVALID_VALUE and @ref GLFW_PLATFORM_ERROR.
2967 * @remark If you set size limits and an aspect ratio that conflict, the
2968 * results are undefined.
2970 * @remark @wayland The aspect ratio will not be applied until the window is
2971 * actually resized, either by the user or by the compositor.
2973 * @thread_safety This function must only be called from the main thread.
2975 * @sa @ref window_sizelimits
2976 * @sa @ref glfwSetWindowSizeLimits
2978 * @since Added in version 3.2.
2982 GLFWAPI
void glfwSetWindowAspectRatio(GLFWwindow
* window
, int numer
, int denom
);
2984 /*! @brief Sets the size of the content area of the specified window.
2986 * This function sets the size, in screen coordinates, of the content area of
2987 * the specified window.
2989 * For full screen windows, this function updates the resolution of its desired
2990 * video mode and switches to the video mode closest to it, without affecting
2991 * the window's context. As the context is unaffected, the bit depths of the
2992 * framebuffer remain unchanged.
2994 * If you wish to update the refresh rate of the desired video mode in addition
2995 * to its resolution, see @ref glfwSetWindowMonitor.
2997 * The window manager may put limits on what sizes are allowed. GLFW cannot
2998 * and should not override these limits.
3000 * @param[in] window The window to resize.
3001 * @param[in] width The desired width, in screen coordinates, of the window
3003 * @param[in] height The desired height, in screen coordinates, of the window
3006 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
3007 * GLFW_PLATFORM_ERROR.
3009 * @remark @wayland A full screen window will not attempt to change the mode,
3010 * no matter what the requested size.
3012 * @thread_safety This function must only be called from the main thread.
3014 * @sa @ref window_size
3015 * @sa @ref glfwGetWindowSize
3016 * @sa @ref glfwSetWindowMonitor
3018 * @since Added in version 1.0.
3019 * @glfw3 Added window handle parameter.
3023 GLFWAPI
void glfwSetWindowSize(GLFWwindow
* window
, int width
, int height
);
3025 /*! @brief Retrieves the size of the framebuffer of the specified window.
3027 * This function retrieves the size, in pixels, of the framebuffer of the
3028 * specified window. If you wish to retrieve the size of the window in screen
3029 * coordinates, see @ref glfwGetWindowSize.
3031 * Any or all of the size arguments may be `NULL`. If an error occurs, all
3032 * non-`NULL` size arguments will be set to zero.
3034 * @param[in] window The window whose framebuffer to query.
3035 * @param[out] width Where to store the width, in pixels, of the framebuffer,
3037 * @param[out] height Where to store the height, in pixels, of the framebuffer,
3040 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
3041 * GLFW_PLATFORM_ERROR.
3043 * @thread_safety This function must only be called from the main thread.
3045 * @sa @ref window_fbsize
3046 * @sa @ref glfwSetFramebufferSizeCallback
3048 * @since Added in version 3.0.
3052 GLFWAPI
void glfwGetFramebufferSize(GLFWwindow
* window
, int* width
, int* height
);
3054 /*! @brief Retrieves the size of the frame of the window.
3056 * This function retrieves the size, in screen coordinates, of each edge of the
3057 * frame of the specified window. This size includes the title bar, if the
3058 * window has one. The size of the frame may vary depending on the
3059 * [window-related hints](@ref window_hints_wnd) used to create it.
3061 * Because this function retrieves the size of each window frame edge and not
3062 * the offset along a particular coordinate axis, the retrieved values will
3063 * always be zero or positive.
3065 * Any or all of the size arguments may be `NULL`. If an error occurs, all
3066 * non-`NULL` size arguments will be set to zero.
3068 * @param[in] window The window whose frame size to query.
3069 * @param[out] left Where to store the size, in screen coordinates, of the left
3070 * edge of the window frame, or `NULL`.
3071 * @param[out] top Where to store the size, in screen coordinates, of the top
3072 * edge of the window frame, or `NULL`.
3073 * @param[out] right Where to store the size, in screen coordinates, of the
3074 * right edge of the window frame, or `NULL`.
3075 * @param[out] bottom Where to store the size, in screen coordinates, of the
3076 * bottom edge of the window frame, or `NULL`.
3078 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
3079 * GLFW_PLATFORM_ERROR.
3081 * @thread_safety This function must only be called from the main thread.
3083 * @sa @ref window_size
3085 * @since Added in version 3.1.
3089 GLFWAPI
void glfwGetWindowFrameSize(GLFWwindow
* window
, int* left
, int* top
, int* right
, int* bottom
);
3091 /*! @brief Retrieves the content scale for the specified window.
3093 * This function retrieves the content scale for the specified window. The
3094 * content scale is the ratio between the current DPI and the platform's
3095 * default DPI. This is especially important for text and any UI elements. If
3096 * the pixel dimensions of your UI scaled by this look appropriate on your
3097 * machine then it should appear at a reasonable size on other machines
3098 * regardless of their DPI and scaling settings. This relies on the system DPI
3099 * and scaling settings being somewhat correct.
3101 * On systems where each monitors can have its own content scale, the window
3102 * content scale will depend on which monitor the system considers the window
3105 * @param[in] window The window to query.
3106 * @param[out] xscale Where to store the x-axis content scale, or `NULL`.
3107 * @param[out] yscale Where to store the y-axis content scale, or `NULL`.
3109 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
3110 * GLFW_PLATFORM_ERROR.
3112 * @thread_safety This function must only be called from the main thread.
3114 * @sa @ref window_scale
3115 * @sa @ref glfwSetWindowContentScaleCallback
3116 * @sa @ref glfwGetMonitorContentScale
3118 * @since Added in version 3.3.
3122 GLFWAPI
void glfwGetWindowContentScale(GLFWwindow
* window
, float* xscale
, float* yscale
);
3124 /*! @brief Returns the opacity of the whole window.
3126 * This function returns the opacity of the window, including any decorations.
3128 * The opacity (or alpha) value is a positive finite number between zero and
3129 * one, where zero is fully transparent and one is fully opaque. If the system
3130 * does not support whole window transparency, this function always returns one.
3132 * The initial opacity value for newly created windows is one.
3134 * @param[in] window The window to query.
3135 * @return The opacity value of the specified window.
3137 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
3138 * GLFW_PLATFORM_ERROR.
3140 * @thread_safety This function must only be called from the main thread.
3142 * @sa @ref window_transparency
3143 * @sa @ref glfwSetWindowOpacity
3145 * @since Added in version 3.3.
3149 GLFWAPI
float glfwGetWindowOpacity(GLFWwindow
* window
);
3151 /*! @brief Sets the opacity of the whole window.
3153 * This function sets the opacity of the window, including any decorations.
3155 * The opacity (or alpha) value is a positive finite number between zero and
3156 * one, where zero is fully transparent and one is fully opaque.
3158 * The initial opacity value for newly created windows is one.
3160 * A window created with framebuffer transparency may not use whole window
3161 * transparency. The results of doing this are undefined.
3163 * @param[in] window The window to set the opacity for.
3164 * @param[in] opacity The desired opacity of the specified window.
3166 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
3167 * GLFW_PLATFORM_ERROR.
3169 * @thread_safety This function must only be called from the main thread.
3171 * @sa @ref window_transparency
3172 * @sa @ref glfwGetWindowOpacity
3174 * @since Added in version 3.3.
3178 GLFWAPI
void glfwSetWindowOpacity(GLFWwindow
* window
, float opacity
);
3180 /*! @brief Iconifies the specified window.
3182 * This function iconifies (minimizes) the specified window if it was
3183 * previously restored. If the window is already iconified, this function does
3186 * If the specified window is a full screen window, the original monitor
3187 * resolution is restored until the window is restored.
3189 * @param[in] window The window to iconify.
3191 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
3192 * GLFW_PLATFORM_ERROR.
3194 * @remark @wayland There is no concept of iconification in wl_shell, this
3195 * function will emit @ref GLFW_PLATFORM_ERROR when using this deprecated
3198 * @thread_safety This function must only be called from the main thread.
3200 * @sa @ref window_iconify
3201 * @sa @ref glfwRestoreWindow
3202 * @sa @ref glfwMaximizeWindow
3204 * @since Added in version 2.1.
3205 * @glfw3 Added window handle parameter.
3209 GLFWAPI
void glfwIconifyWindow(GLFWwindow
* window
);
3211 /*! @brief Restores the specified window.
3213 * This function restores the specified window if it was previously iconified
3214 * (minimized) or maximized. If the window is already restored, this function
3217 * If the specified window is a full screen window, the resolution chosen for
3218 * the window is restored on the selected monitor.
3220 * @param[in] window The window to restore.
3222 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
3223 * GLFW_PLATFORM_ERROR.
3225 * @thread_safety This function must only be called from the main thread.
3227 * @sa @ref window_iconify
3228 * @sa @ref glfwIconifyWindow
3229 * @sa @ref glfwMaximizeWindow
3231 * @since Added in version 2.1.
3232 * @glfw3 Added window handle parameter.
3236 GLFWAPI
void glfwRestoreWindow(GLFWwindow
* window
);
3238 /*! @brief Maximizes the specified window.
3240 * This function maximizes the specified window if it was previously not
3241 * maximized. If the window is already maximized, this function does nothing.
3243 * If the specified window is a full screen window, this function does nothing.
3245 * @param[in] window The window to maximize.
3247 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
3248 * GLFW_PLATFORM_ERROR.
3250 * @par Thread Safety
3251 * This function may only be called from the main thread.
3253 * @sa @ref window_iconify
3254 * @sa @ref glfwIconifyWindow
3255 * @sa @ref glfwRestoreWindow
3257 * @since Added in GLFW 3.2.
3261 GLFWAPI
void glfwMaximizeWindow(GLFWwindow
* window
);
3263 /*! @brief Makes the specified window visible.
3265 * This function makes the specified window visible if it was previously
3266 * hidden. If the window is already visible or is in full screen mode, this
3267 * function does nothing.
3269 * By default, windowed mode windows are focused when shown
3270 * Set the [GLFW_FOCUS_ON_SHOW](@ref GLFW_FOCUS_ON_SHOW_hint) window hint
3271 * to change this behavior for all newly created windows, or change the
3272 * behavior for an existing window with @ref glfwSetWindowAttrib.
3274 * @param[in] window The window to make visible.
3276 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
3277 * GLFW_PLATFORM_ERROR.
3279 * @thread_safety This function must only be called from the main thread.
3281 * @sa @ref window_hide
3282 * @sa @ref glfwHideWindow
3284 * @since Added in version 3.0.
3288 GLFWAPI
void glfwShowWindow(GLFWwindow
* window
);
3290 /*! @brief Hides the specified window.
3292 * This function hides the specified window if it was previously visible. If
3293 * the window is already hidden or is in full screen mode, this function does
3296 * @param[in] window The window to hide.
3298 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
3299 * GLFW_PLATFORM_ERROR.
3301 * @thread_safety This function must only be called from the main thread.
3303 * @sa @ref window_hide
3304 * @sa @ref glfwShowWindow
3306 * @since Added in version 3.0.
3310 GLFWAPI
void glfwHideWindow(GLFWwindow
* window
);
3312 /*! @brief Brings the specified window to front and sets input focus.
3314 * This function brings the specified window to front and sets input focus.
3315 * The window should already be visible and not iconified.
3317 * By default, both windowed and full screen mode windows are focused when
3318 * initially created. Set the [GLFW_FOCUSED](@ref GLFW_FOCUSED_hint) to
3319 * disable this behavior.
3321 * Also by default, windowed mode windows are focused when shown
3322 * with @ref glfwShowWindow. Set the
3323 * [GLFW_FOCUS_ON_SHOW](@ref GLFW_FOCUS_ON_SHOW_hint) to disable this behavior.
3325 * __Do not use this function__ to steal focus from other applications unless
3326 * you are certain that is what the user wants. Focus stealing can be
3327 * extremely disruptive.
3329 * For a less disruptive way of getting the user's attention, see
3330 * [attention requests](@ref window_attention).
3332 * @param[in] window The window to give input focus.
3334 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
3335 * GLFW_PLATFORM_ERROR.
3337 * @remark @wayland It is not possible for an application to bring its windows
3338 * to front, this function will always emit @ref GLFW_PLATFORM_ERROR.
3340 * @thread_safety This function must only be called from the main thread.
3342 * @sa @ref window_focus
3343 * @sa @ref window_attention
3345 * @since Added in version 3.2.
3349 GLFWAPI
void glfwFocusWindow(GLFWwindow
* window
);
3351 /*! @brief Requests user attention to the specified window.
3353 * This function requests user attention to the specified window. On
3354 * platforms where this is not supported, attention is requested to the
3355 * application as a whole.
3357 * Once the user has given attention, usually by focusing the window or
3358 * application, the system will end the request automatically.
3360 * @param[in] window The window to request attention to.
3362 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
3363 * GLFW_PLATFORM_ERROR.
3365 * @remark @macos Attention is requested to the application as a whole, not the
3368 * @thread_safety This function must only be called from the main thread.
3370 * @sa @ref window_attention
3372 * @since Added in version 3.3.
3376 GLFWAPI
void glfwRequestWindowAttention(GLFWwindow
* window
);
3378 /*! @brief Returns the monitor that the window uses for full screen mode.
3380 * This function returns the handle of the monitor that the specified window is
3381 * in full screen on.
3383 * @param[in] window The window to query.
3384 * @return The monitor, or `NULL` if the window is in windowed mode or an
3385 * [error](@ref error_handling) occurred.
3387 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
3389 * @thread_safety This function must only be called from the main thread.
3391 * @sa @ref window_monitor
3392 * @sa @ref glfwSetWindowMonitor
3394 * @since Added in version 3.0.
3398 GLFWAPI GLFWmonitor
* glfwGetWindowMonitor(GLFWwindow
* window
);
3400 /*! @brief Sets the mode, monitor, video mode and placement of a window.
3402 * This function sets the monitor that the window uses for full screen mode or,
3403 * if the monitor is `NULL`, makes it windowed mode.
3405 * When setting a monitor, this function updates the width, height and refresh
3406 * rate of the desired video mode and switches to the video mode closest to it.
3407 * The window position is ignored when setting a monitor.
3409 * When the monitor is `NULL`, the position, width and height are used to
3410 * place the window content area. The refresh rate is ignored when no monitor
3413 * If you only wish to update the resolution of a full screen window or the
3414 * size of a windowed mode window, see @ref glfwSetWindowSize.
3416 * When a window transitions from full screen to windowed mode, this function
3417 * restores any previous window settings such as whether it is decorated,
3418 * floating, resizable, has size or aspect ratio limits, etc.
3420 * @param[in] window The window whose monitor, size or video mode to set.
3421 * @param[in] monitor The desired monitor, or `NULL` to set windowed mode.
3422 * @param[in] xpos The desired x-coordinate of the upper-left corner of the
3424 * @param[in] ypos The desired y-coordinate of the upper-left corner of the
3426 * @param[in] width The desired with, in screen coordinates, of the content
3427 * area or video mode.
3428 * @param[in] height The desired height, in screen coordinates, of the content
3429 * area or video mode.
3430 * @param[in] refreshRate The desired refresh rate, in Hz, of the video mode,
3431 * or `GLFW_DONT_CARE`.
3433 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
3434 * GLFW_PLATFORM_ERROR.
3436 * @remark The OpenGL or OpenGL ES context will not be destroyed or otherwise
3437 * affected by any resizing or mode switching, although you may need to update
3438 * your viewport if the framebuffer size has changed.
3440 * @remark @wayland The desired window position is ignored, as there is no way
3441 * for an application to set this property.
3443 * @remark @wayland Setting the window to full screen will not attempt to
3444 * change the mode, no matter what the requested size or refresh rate.
3446 * @thread_safety This function must only be called from the main thread.
3448 * @sa @ref window_monitor
3449 * @sa @ref window_full_screen
3450 * @sa @ref glfwGetWindowMonitor
3451 * @sa @ref glfwSetWindowSize
3453 * @since Added in version 3.2.
3457 GLFWAPI
void glfwSetWindowMonitor(GLFWwindow
* window
, GLFWmonitor
* monitor
, int xpos
, int ypos
, int width
, int height
, int refreshRate
);
3459 /*! @brief Returns an attribute of the specified window.
3461 * This function returns the value of an attribute of the specified window or
3462 * its OpenGL or OpenGL ES context.
3464 * @param[in] window The window to query.
3465 * @param[in] attrib The [window attribute](@ref window_attribs) whose value to
3467 * @return The value of the attribute, or zero if an
3468 * [error](@ref error_handling) occurred.
3470 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
3471 * GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR.
3473 * @remark Framebuffer related hints are not window attributes. See @ref
3474 * window_attribs_fb for more information.
3476 * @remark Zero is a valid value for many window and context related
3477 * attributes so you cannot use a return value of zero as an indication of
3478 * errors. However, this function should not fail as long as it is passed
3479 * valid arguments and the library has been [initialized](@ref intro_init).
3481 * @thread_safety This function must only be called from the main thread.
3483 * @sa @ref window_attribs
3484 * @sa @ref glfwSetWindowAttrib
3486 * @since Added in version 3.0. Replaces `glfwGetWindowParam` and
3487 * `glfwGetGLVersion`.
3491 GLFWAPI
int glfwGetWindowAttrib(GLFWwindow
* window
, int attrib
);
3493 /*! @brief Sets an attribute of the specified window.
3495 * This function sets the value of an attribute of the specified window.
3497 * The supported attributes are [GLFW_DECORATED](@ref GLFW_DECORATED_attrib),
3498 * [GLFW_RESIZABLE](@ref GLFW_RESIZABLE_attrib),
3499 * [GLFW_FLOATING](@ref GLFW_FLOATING_attrib),
3500 * [GLFW_AUTO_ICONIFY](@ref GLFW_AUTO_ICONIFY_attrib) and
3501 * [GLFW_FOCUS_ON_SHOW](@ref GLFW_FOCUS_ON_SHOW_attrib).
3503 * Some of these attributes are ignored for full screen windows. The new
3504 * value will take effect if the window is later made windowed.
3506 * Some of these attributes are ignored for windowed mode windows. The new
3507 * value will take effect if the window is later made full screen.
3509 * @param[in] window The window to set the attribute for.
3510 * @param[in] attrib A supported window attribute.
3511 * @param[in] value `GLFW_TRUE` or `GLFW_FALSE`.
3513 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
3514 * GLFW_INVALID_ENUM, @ref GLFW_INVALID_VALUE and @ref GLFW_PLATFORM_ERROR.
3516 * @remark Calling @ref glfwGetWindowAttrib will always return the latest
3517 * value, even if that value is ignored by the current mode of the window.
3519 * @thread_safety This function must only be called from the main thread.
3521 * @sa @ref window_attribs
3522 * @sa @ref glfwGetWindowAttrib
3524 * @since Added in version 3.3.
3528 GLFWAPI
void glfwSetWindowAttrib(GLFWwindow
* window
, int attrib
, int value
);
3530 /*! @brief Sets the user pointer of the specified window.
3532 * This function sets the user-defined pointer of the specified window. The
3533 * current value is retained until the window is destroyed. The initial value
3536 * @param[in] window The window whose pointer to set.
3537 * @param[in] pointer The new value.
3539 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
3541 * @thread_safety This function may be called from any thread. Access is not
3544 * @sa @ref window_userptr
3545 * @sa @ref glfwGetWindowUserPointer
3547 * @since Added in version 3.0.
3551 GLFWAPI
void glfwSetWindowUserPointer(GLFWwindow
* window
, void* pointer
);
3553 /*! @brief Returns the user pointer of the specified window.
3555 * This function returns the current value of the user-defined pointer of the
3556 * specified window. The initial value is `NULL`.
3558 * @param[in] window The window whose pointer to return.
3560 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
3562 * @thread_safety This function may be called from any thread. Access is not
3565 * @sa @ref window_userptr
3566 * @sa @ref glfwSetWindowUserPointer
3568 * @since Added in version 3.0.
3572 GLFWAPI
void* glfwGetWindowUserPointer(GLFWwindow
* window
);
3574 /*! @brief Sets the position callback for the specified window.
3576 * This function sets the position callback of the specified window, which is
3577 * called when the window is moved. The callback is provided with the
3578 * position, in screen coordinates, of the upper-left corner of the content
3579 * area of the window.
3581 * @param[in] window The window whose callback to set.
3582 * @param[in] callback The new callback, or `NULL` to remove the currently set
3584 * @return The previously set callback, or `NULL` if no callback was set or the
3585 * library had not been [initialized](@ref intro_init).
3587 * @callback_signature
3589 * void function_name(GLFWwindow* window, int xpos, int ypos)
3591 * For more information about the callback parameters, see the
3592 * [function pointer type](@ref GLFWwindowposfun).
3594 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
3596 * @remark @wayland This callback will never be called, as there is no way for
3597 * an application to know its global position.
3599 * @thread_safety This function must only be called from the main thread.
3601 * @sa @ref window_pos
3603 * @since Added in version 3.0.
3607 GLFWAPI GLFWwindowposfun
glfwSetWindowPosCallback(GLFWwindow
* window
, GLFWwindowposfun callback
);
3609 /*! @brief Sets the size callback for the specified window.
3611 * This function sets the size callback of the specified window, which is
3612 * called when the window is resized. The callback is provided with the size,
3613 * in screen coordinates, of the content area of the window.
3615 * @param[in] window The window whose callback to set.
3616 * @param[in] callback The new callback, or `NULL` to remove the currently set
3618 * @return The previously set callback, or `NULL` if no callback was set or the
3619 * library had not been [initialized](@ref intro_init).
3621 * @callback_signature
3623 * void function_name(GLFWwindow* window, int width, int height)
3625 * For more information about the callback parameters, see the
3626 * [function pointer type](@ref GLFWwindowsizefun).
3628 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
3630 * @thread_safety This function must only be called from the main thread.
3632 * @sa @ref window_size
3634 * @since Added in version 1.0.
3635 * @glfw3 Added window handle parameter and return value.
3639 GLFWAPI GLFWwindowsizefun
glfwSetWindowSizeCallback(GLFWwindow
* window
, GLFWwindowsizefun callback
);
3641 /*! @brief Sets the close callback for the specified window.
3643 * This function sets the close callback of the specified window, which is
3644 * called when the user attempts to close the window, for example by clicking
3645 * the close widget in the title bar.
3647 * The close flag is set before this callback is called, but you can modify it
3648 * at any time with @ref glfwSetWindowShouldClose.
3650 * The close callback is not triggered by @ref glfwDestroyWindow.
3652 * @param[in] window The window whose callback to set.
3653 * @param[in] callback The new callback, or `NULL` to remove the currently set
3655 * @return The previously set callback, or `NULL` if no callback was set or the
3656 * library had not been [initialized](@ref intro_init).
3658 * @callback_signature
3660 * void function_name(GLFWwindow* window)
3662 * For more information about the callback parameters, see the
3663 * [function pointer type](@ref GLFWwindowclosefun).
3665 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
3667 * @remark @macos Selecting Quit from the application menu will trigger the
3668 * close callback for all windows.
3670 * @thread_safety This function must only be called from the main thread.
3672 * @sa @ref window_close
3674 * @since Added in version 2.5.
3675 * @glfw3 Added window handle parameter and return value.
3679 GLFWAPI GLFWwindowclosefun
glfwSetWindowCloseCallback(GLFWwindow
* window
, GLFWwindowclosefun callback
);
3681 /*! @brief Sets the refresh callback for the specified window.
3683 * This function sets the refresh callback of the specified window, which is
3684 * called when the content area of the window needs to be redrawn, for example
3685 * if the window has been exposed after having been covered by another window.
3687 * On compositing window systems such as Aero, Compiz, Aqua or Wayland, where
3688 * the window contents are saved off-screen, this callback may be called only
3689 * very infrequently or never at all.
3691 * @param[in] window The window whose callback to set.
3692 * @param[in] callback The new callback, or `NULL` to remove the currently set
3694 * @return The previously set callback, or `NULL` if no callback was set or the
3695 * library had not been [initialized](@ref intro_init).
3697 * @callback_signature
3699 * void function_name(GLFWwindow* window);
3701 * For more information about the callback parameters, see the
3702 * [function pointer type](@ref GLFWwindowrefreshfun).
3704 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
3706 * @thread_safety This function must only be called from the main thread.
3708 * @sa @ref window_refresh
3710 * @since Added in version 2.5.
3711 * @glfw3 Added window handle parameter and return value.
3715 GLFWAPI GLFWwindowrefreshfun
glfwSetWindowRefreshCallback(GLFWwindow
* window
, GLFWwindowrefreshfun callback
);
3717 /*! @brief Sets the focus callback for the specified window.
3719 * This function sets the focus callback of the specified window, which is
3720 * called when the window gains or loses input focus.
3722 * After the focus callback is called for a window that lost input focus,
3723 * synthetic key and mouse button release events will be generated for all such
3724 * that had been pressed. For more information, see @ref glfwSetKeyCallback
3725 * and @ref glfwSetMouseButtonCallback.
3727 * @param[in] window The window whose callback to set.
3728 * @param[in] callback The new callback, or `NULL` to remove the currently set
3730 * @return The previously set callback, or `NULL` if no callback was set or the
3731 * library had not been [initialized](@ref intro_init).
3733 * @callback_signature
3735 * void function_name(GLFWwindow* window, int focused)
3737 * For more information about the callback parameters, see the
3738 * [function pointer type](@ref GLFWwindowfocusfun).
3740 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
3742 * @thread_safety This function must only be called from the main thread.
3744 * @sa @ref window_focus
3746 * @since Added in version 3.0.
3750 GLFWAPI GLFWwindowfocusfun
glfwSetWindowFocusCallback(GLFWwindow
* window
, GLFWwindowfocusfun callback
);
3752 /*! @brief Sets the iconify callback for the specified window.
3754 * This function sets the iconification callback of the specified window, which
3755 * is called when the window is iconified or restored.
3757 * @param[in] window The window whose callback to set.
3758 * @param[in] callback The new callback, or `NULL` to remove the currently set
3760 * @return The previously set callback, or `NULL` if no callback was set or the
3761 * library had not been [initialized](@ref intro_init).
3763 * @callback_signature
3765 * void function_name(GLFWwindow* window, int iconified)
3767 * For more information about the callback parameters, see the
3768 * [function pointer type](@ref GLFWwindowiconifyfun).
3770 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
3772 * @remark @wayland The wl_shell protocol has no concept of iconification,
3773 * this callback will never be called when using this deprecated protocol.
3775 * @thread_safety This function must only be called from the main thread.
3777 * @sa @ref window_iconify
3779 * @since Added in version 3.0.
3783 GLFWAPI GLFWwindowiconifyfun
glfwSetWindowIconifyCallback(GLFWwindow
* window
, GLFWwindowiconifyfun callback
);
3785 /*! @brief Sets the maximize callback for the specified window.
3787 * This function sets the maximization callback of the specified window, which
3788 * is called when the window is maximized or restored.
3790 * @param[in] window The window whose callback to set.
3791 * @param[in] callback The new callback, or `NULL` to remove the currently set
3793 * @return The previously set callback, or `NULL` if no callback was set or the
3794 * library had not been [initialized](@ref intro_init).
3796 * @callback_signature
3798 * void function_name(GLFWwindow* window, int maximized)
3800 * For more information about the callback parameters, see the
3801 * [function pointer type](@ref GLFWwindowmaximizefun).
3803 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
3805 * @thread_safety This function must only be called from the main thread.
3807 * @sa @ref window_maximize
3809 * @since Added in version 3.3.
3813 GLFWAPI GLFWwindowmaximizefun
glfwSetWindowMaximizeCallback(GLFWwindow
* window
, GLFWwindowmaximizefun callback
);
3815 /*! @brief Sets the framebuffer resize callback for the specified window.
3817 * This function sets the framebuffer resize callback of the specified window,
3818 * which is called when the framebuffer of the specified window is resized.
3820 * @param[in] window The window whose callback to set.
3821 * @param[in] callback The new callback, or `NULL` to remove the currently set
3823 * @return The previously set callback, or `NULL` if no callback was set or the
3824 * library had not been [initialized](@ref intro_init).
3826 * @callback_signature
3828 * void function_name(GLFWwindow* window, int width, int height)
3830 * For more information about the callback parameters, see the
3831 * [function pointer type](@ref GLFWframebuffersizefun).
3833 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
3835 * @thread_safety This function must only be called from the main thread.
3837 * @sa @ref window_fbsize
3839 * @since Added in version 3.0.
3843 GLFWAPI GLFWframebuffersizefun
glfwSetFramebufferSizeCallback(GLFWwindow
* window
, GLFWframebuffersizefun callback
);
3845 /*! @brief Sets the window content scale callback for the specified window.
3847 * This function sets the window content scale callback of the specified window,
3848 * which is called when the content scale of the specified window changes.
3850 * @param[in] window The window whose callback to set.
3851 * @param[in] callback The new callback, or `NULL` to remove the currently set
3853 * @return The previously set callback, or `NULL` if no callback was set or the
3854 * library had not been [initialized](@ref intro_init).
3856 * @callback_signature
3858 * void function_name(GLFWwindow* window, float xscale, float yscale)
3860 * For more information about the callback parameters, see the
3861 * [function pointer type](@ref GLFWwindowcontentscalefun).
3863 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
3865 * @thread_safety This function must only be called from the main thread.
3867 * @sa @ref window_scale
3868 * @sa @ref glfwGetWindowContentScale
3870 * @since Added in version 3.3.
3874 GLFWAPI GLFWwindowcontentscalefun
glfwSetWindowContentScaleCallback(GLFWwindow
* window
, GLFWwindowcontentscalefun callback
);
3876 /*! @brief Processes all pending events.
3878 * This function processes only those events that are already in the event
3879 * queue and then returns immediately. Processing events will cause the window
3880 * and input callbacks associated with those events to be called.
3882 * On some platforms, a window move, resize or menu operation will cause event
3883 * processing to block. This is due to how event processing is designed on
3884 * those platforms. You can use the
3885 * [window refresh callback](@ref window_refresh) to redraw the contents of
3886 * your window when necessary during such operations.
3888 * Do not assume that callbacks you set will _only_ be called in response to
3889 * event processing functions like this one. While it is necessary to poll for
3890 * events, window systems that require GLFW to register callbacks of its own
3891 * can pass events to GLFW in response to many window system function calls.
3892 * GLFW will pass those events on to the application callbacks before
3895 * Event processing is not required for joystick input to work.
3897 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
3898 * GLFW_PLATFORM_ERROR.
3900 * @reentrancy This function must not be called from a callback.
3902 * @thread_safety This function must only be called from the main thread.
3905 * @sa @ref glfwWaitEvents
3906 * @sa @ref glfwWaitEventsTimeout
3908 * @since Added in version 1.0.
3912 GLFWAPI
void glfwPollEvents(void);
3914 /*! @brief Waits until events are queued and processes them.
3916 * This function puts the calling thread to sleep until at least one event is
3917 * available in the event queue. Once one or more events are available,
3918 * it behaves exactly like @ref glfwPollEvents, i.e. the events in the queue
3919 * are processed and the function then returns immediately. Processing events
3920 * will cause the window and input callbacks associated with those events to be
3923 * Since not all events are associated with callbacks, this function may return
3924 * without a callback having been called even if you are monitoring all
3927 * On some platforms, a window move, resize or menu operation will cause event
3928 * processing to block. This is due to how event processing is designed on
3929 * those platforms. You can use the
3930 * [window refresh callback](@ref window_refresh) to redraw the contents of
3931 * your window when necessary during such operations.
3933 * Do not assume that callbacks you set will _only_ be called in response to
3934 * event processing functions like this one. While it is necessary to poll for
3935 * events, window systems that require GLFW to register callbacks of its own
3936 * can pass events to GLFW in response to many window system function calls.
3937 * GLFW will pass those events on to the application callbacks before
3940 * Event processing is not required for joystick input to work.
3942 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
3943 * GLFW_PLATFORM_ERROR.
3945 * @reentrancy This function must not be called from a callback.
3947 * @thread_safety This function must only be called from the main thread.
3950 * @sa @ref glfwPollEvents
3951 * @sa @ref glfwWaitEventsTimeout
3953 * @since Added in version 2.5.
3957 GLFWAPI
void glfwWaitEvents(void);
3959 /*! @brief Waits with timeout until events are queued and processes them.
3961 * This function puts the calling thread to sleep until at least one event is
3962 * available in the event queue, or until the specified timeout is reached. If
3963 * one or more events are available, it behaves exactly like @ref
3964 * glfwPollEvents, i.e. the events in the queue are processed and the function
3965 * then returns immediately. Processing events will cause the window and input
3966 * callbacks associated with those events to be called.
3968 * The timeout value must be a positive finite number.
3970 * Since not all events are associated with callbacks, this function may return
3971 * without a callback having been called even if you are monitoring all
3974 * On some platforms, a window move, resize or menu operation will cause event
3975 * processing to block. This is due to how event processing is designed on
3976 * those platforms. You can use the
3977 * [window refresh callback](@ref window_refresh) to redraw the contents of
3978 * your window when necessary during such operations.
3980 * Do not assume that callbacks you set will _only_ be called in response to
3981 * event processing functions like this one. While it is necessary to poll for
3982 * events, window systems that require GLFW to register callbacks of its own
3983 * can pass events to GLFW in response to many window system function calls.
3984 * GLFW will pass those events on to the application callbacks before
3987 * Event processing is not required for joystick input to work.
3989 * @param[in] timeout The maximum amount of time, in seconds, to wait.
3991 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
3992 * GLFW_INVALID_VALUE and @ref GLFW_PLATFORM_ERROR.
3994 * @reentrancy This function must not be called from a callback.
3996 * @thread_safety This function must only be called from the main thread.
3999 * @sa @ref glfwPollEvents
4000 * @sa @ref glfwWaitEvents
4002 * @since Added in version 3.2.
4006 GLFWAPI
void glfwWaitEventsTimeout(double timeout
);
4008 /*! @brief Posts an empty event to the event queue.
4010 * This function posts an empty event from the current thread to the event
4011 * queue, causing @ref glfwWaitEvents or @ref glfwWaitEventsTimeout to return.
4013 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
4014 * GLFW_PLATFORM_ERROR.
4016 * @thread_safety This function may be called from any thread.
4019 * @sa @ref glfwWaitEvents
4020 * @sa @ref glfwWaitEventsTimeout
4022 * @since Added in version 3.1.
4026 GLFWAPI
void glfwPostEmptyEvent(void);
4028 /*! @brief Returns the value of an input option for the specified window.
4030 * This function returns the value of an input option for the specified window.
4031 * The mode must be one of @ref GLFW_CURSOR, @ref GLFW_STICKY_KEYS,
4032 * @ref GLFW_STICKY_MOUSE_BUTTONS, @ref GLFW_LOCK_KEY_MODS or
4033 * @ref GLFW_RAW_MOUSE_MOTION.
4035 * @param[in] window The window to query.
4036 * @param[in] mode One of `GLFW_CURSOR`, `GLFW_STICKY_KEYS`,
4037 * `GLFW_STICKY_MOUSE_BUTTONS`, `GLFW_LOCK_KEY_MODS` or
4038 * `GLFW_RAW_MOUSE_MOTION`.
4040 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
4041 * GLFW_INVALID_ENUM.
4043 * @thread_safety This function must only be called from the main thread.
4045 * @sa @ref glfwSetInputMode
4047 * @since Added in version 3.0.
4051 GLFWAPI
int glfwGetInputMode(GLFWwindow
* window
, int mode
);
4053 /*! @brief Sets an input option for the specified window.
4055 * This function sets an input mode option for the specified window. The mode
4056 * must be one of @ref GLFW_CURSOR, @ref GLFW_STICKY_KEYS,
4057 * @ref GLFW_STICKY_MOUSE_BUTTONS, @ref GLFW_LOCK_KEY_MODS or
4058 * @ref GLFW_RAW_MOUSE_MOTION.
4060 * If the mode is `GLFW_CURSOR`, the value must be one of the following cursor
4062 * - `GLFW_CURSOR_NORMAL` makes the cursor visible and behaving normally.
4063 * - `GLFW_CURSOR_HIDDEN` makes the cursor invisible when it is over the
4064 * content area of the window but does not restrict the cursor from leaving.
4065 * - `GLFW_CURSOR_DISABLED` hides and grabs the cursor, providing virtual
4066 * and unlimited cursor movement. This is useful for implementing for
4067 * example 3D camera controls.
4069 * If the mode is `GLFW_STICKY_KEYS`, the value must be either `GLFW_TRUE` to
4070 * enable sticky keys, or `GLFW_FALSE` to disable it. If sticky keys are
4071 * enabled, a key press will ensure that @ref glfwGetKey returns `GLFW_PRESS`
4072 * the next time it is called even if the key had been released before the
4073 * call. This is useful when you are only interested in whether keys have been
4074 * pressed but not when or in which order.
4076 * If the mode is `GLFW_STICKY_MOUSE_BUTTONS`, the value must be either
4077 * `GLFW_TRUE` to enable sticky mouse buttons, or `GLFW_FALSE` to disable it.
4078 * If sticky mouse buttons are enabled, a mouse button press will ensure that
4079 * @ref glfwGetMouseButton returns `GLFW_PRESS` the next time it is called even
4080 * if the mouse button had been released before the call. This is useful when
4081 * you are only interested in whether mouse buttons have been pressed but not
4082 * when or in which order.
4084 * If the mode is `GLFW_LOCK_KEY_MODS`, the value must be either `GLFW_TRUE` to
4085 * enable lock key modifier bits, or `GLFW_FALSE` to disable them. If enabled,
4086 * callbacks that receive modifier bits will also have the @ref
4087 * GLFW_MOD_CAPS_LOCK bit set when the event was generated with Caps Lock on,
4088 * and the @ref GLFW_MOD_NUM_LOCK bit when Num Lock was on.
4090 * If the mode is `GLFW_RAW_MOUSE_MOTION`, the value must be either `GLFW_TRUE`
4091 * to enable raw (unscaled and unaccelerated) mouse motion when the cursor is
4092 * disabled, or `GLFW_FALSE` to disable it. If raw motion is not supported,
4093 * attempting to set this will emit @ref GLFW_PLATFORM_ERROR. Call @ref
4094 * glfwRawMouseMotionSupported to check for support.
4096 * @param[in] window The window whose input mode to set.
4097 * @param[in] mode One of `GLFW_CURSOR`, `GLFW_STICKY_KEYS`,
4098 * `GLFW_STICKY_MOUSE_BUTTONS`, `GLFW_LOCK_KEY_MODS` or
4099 * `GLFW_RAW_MOUSE_MOTION`.
4100 * @param[in] value The new value of the specified input mode.
4102 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
4103 * GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR.
4105 * @thread_safety This function must only be called from the main thread.
4107 * @sa @ref glfwGetInputMode
4109 * @since Added in version 3.0. Replaces `glfwEnable` and `glfwDisable`.
4113 GLFWAPI
void glfwSetInputMode(GLFWwindow
* window
, int mode
, int value
);
4115 /*! @brief Returns whether raw mouse motion is supported.
4117 * This function returns whether raw mouse motion is supported on the current
4118 * system. This status does not change after GLFW has been initialized so you
4119 * only need to check this once. If you attempt to enable raw motion on
4120 * a system that does not support it, @ref GLFW_PLATFORM_ERROR will be emitted.
4122 * Raw mouse motion is closer to the actual motion of the mouse across
4123 * a surface. It is not affected by the scaling and acceleration applied to
4124 * the motion of the desktop cursor. That processing is suitable for a cursor
4125 * while raw motion is better for controlling for example a 3D camera. Because
4126 * of this, raw mouse motion is only provided when the cursor is disabled.
4128 * @return `GLFW_TRUE` if raw mouse motion is supported on the current machine,
4129 * or `GLFW_FALSE` otherwise.
4131 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
4133 * @thread_safety This function must only be called from the main thread.
4135 * @sa @ref raw_mouse_motion
4136 * @sa @ref glfwSetInputMode
4138 * @since Added in version 3.3.
4142 GLFWAPI
int glfwRawMouseMotionSupported(void);
4144 /*! @brief Returns the layout-specific name of the specified printable key.
4146 * This function returns the name of the specified printable key, encoded as
4147 * UTF-8. This is typically the character that key would produce without any
4148 * modifier keys, intended for displaying key bindings to the user. For dead
4149 * keys, it is typically the diacritic it would add to a character.
4151 * __Do not use this function__ for [text input](@ref input_char). You will
4152 * break text input for many languages even if it happens to work for yours.
4154 * If the key is `GLFW_KEY_UNKNOWN`, the scancode is used to identify the key,
4155 * otherwise the scancode is ignored. If you specify a non-printable key, or
4156 * `GLFW_KEY_UNKNOWN` and a scancode that maps to a non-printable key, this
4157 * function returns `NULL` but does not emit an error.
4159 * This behavior allows you to always pass in the arguments in the
4160 * [key callback](@ref input_key) without modification.
4162 * The printable keys are:
4163 * - `GLFW_KEY_APOSTROPHE`
4164 * - `GLFW_KEY_COMMA`
4165 * - `GLFW_KEY_MINUS`
4166 * - `GLFW_KEY_PERIOD`
4167 * - `GLFW_KEY_SLASH`
4168 * - `GLFW_KEY_SEMICOLON`
4169 * - `GLFW_KEY_EQUAL`
4170 * - `GLFW_KEY_LEFT_BRACKET`
4171 * - `GLFW_KEY_RIGHT_BRACKET`
4172 * - `GLFW_KEY_BACKSLASH`
4173 * - `GLFW_KEY_WORLD_1`
4174 * - `GLFW_KEY_WORLD_2`
4175 * - `GLFW_KEY_0` to `GLFW_KEY_9`
4176 * - `GLFW_KEY_A` to `GLFW_KEY_Z`
4177 * - `GLFW_KEY_KP_0` to `GLFW_KEY_KP_9`
4178 * - `GLFW_KEY_KP_DECIMAL`
4179 * - `GLFW_KEY_KP_DIVIDE`
4180 * - `GLFW_KEY_KP_MULTIPLY`
4181 * - `GLFW_KEY_KP_SUBTRACT`
4182 * - `GLFW_KEY_KP_ADD`
4183 * - `GLFW_KEY_KP_EQUAL`
4185 * Names for printable keys depend on keyboard layout, while names for
4186 * non-printable keys are the same across layouts but depend on the application
4187 * language and should be localized along with other user interface text.
4189 * @param[in] key The key to query, or `GLFW_KEY_UNKNOWN`.
4190 * @param[in] scancode The scancode of the key to query.
4191 * @return The UTF-8 encoded, layout-specific name of the key, or `NULL`.
4193 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
4194 * GLFW_PLATFORM_ERROR.
4196 * @remark The contents of the returned string may change when a keyboard
4197 * layout change event is received.
4199 * @pointer_lifetime The returned string is allocated and freed by GLFW. You
4200 * should not free it yourself. It is valid until the library is terminated.
4202 * @thread_safety This function must only be called from the main thread.
4204 * @sa @ref input_key_name
4206 * @since Added in version 3.2.
4210 GLFWAPI
const char* glfwGetKeyName(int key
, int scancode
);
4212 /*! @brief Returns the platform-specific scancode of the specified key.
4214 * This function returns the platform-specific scancode of the specified key.
4216 * If the key is `GLFW_KEY_UNKNOWN` or does not exist on the keyboard this
4217 * method will return `-1`.
4219 * @param[in] key Any [named key](@ref keys).
4220 * @return The platform-specific scancode for the key, or `-1` if an
4221 * [error](@ref error_handling) occurred.
4223 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
4224 * GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR.
4226 * @thread_safety This function may be called from any thread.
4228 * @sa @ref input_key
4230 * @since Added in version 3.3.
4234 GLFWAPI
int glfwGetKeyScancode(int key
);
4236 /*! @brief Returns the last reported state of a keyboard key for the specified
4239 * This function returns the last state reported for the specified key to the
4240 * specified window. The returned state is one of `GLFW_PRESS` or
4241 * `GLFW_RELEASE`. The higher-level action `GLFW_REPEAT` is only reported to
4244 * If the @ref GLFW_STICKY_KEYS input mode is enabled, this function returns
4245 * `GLFW_PRESS` the first time you call it for a key that was pressed, even if
4246 * that key has already been released.
4248 * The key functions deal with physical keys, with [key tokens](@ref keys)
4249 * named after their use on the standard US keyboard layout. If you want to
4250 * input text, use the Unicode character callback instead.
4252 * The [modifier key bit masks](@ref mods) are not key tokens and cannot be
4253 * used with this function.
4255 * __Do not use this function__ to implement [text input](@ref input_char).
4257 * @param[in] window The desired window.
4258 * @param[in] key The desired [keyboard key](@ref keys). `GLFW_KEY_UNKNOWN` is
4259 * not a valid key for this function.
4260 * @return One of `GLFW_PRESS` or `GLFW_RELEASE`.
4262 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
4263 * GLFW_INVALID_ENUM.
4265 * @thread_safety This function must only be called from the main thread.
4267 * @sa @ref input_key
4269 * @since Added in version 1.0.
4270 * @glfw3 Added window handle parameter.
4274 GLFWAPI
int glfwGetKey(GLFWwindow
* window
, int key
);
4276 /*! @brief Returns the last reported state of a mouse button for the specified
4279 * This function returns the last state reported for the specified mouse button
4280 * to the specified window. The returned state is one of `GLFW_PRESS` or
4283 * If the @ref GLFW_STICKY_MOUSE_BUTTONS input mode is enabled, this function
4284 * returns `GLFW_PRESS` the first time you call it for a mouse button that was
4285 * pressed, even if that mouse button has already been released.
4287 * @param[in] window The desired window.
4288 * @param[in] button The desired [mouse button](@ref buttons).
4289 * @return One of `GLFW_PRESS` or `GLFW_RELEASE`.
4291 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
4292 * GLFW_INVALID_ENUM.
4294 * @thread_safety This function must only be called from the main thread.
4296 * @sa @ref input_mouse_button
4298 * @since Added in version 1.0.
4299 * @glfw3 Added window handle parameter.
4303 GLFWAPI
int glfwGetMouseButton(GLFWwindow
* window
, int button
);
4305 /*! @brief Retrieves the position of the cursor relative to the content area of
4308 * This function returns the position of the cursor, in screen coordinates,
4309 * relative to the upper-left corner of the content area of the specified
4312 * If the cursor is disabled (with `GLFW_CURSOR_DISABLED`) then the cursor
4313 * position is unbounded and limited only by the minimum and maximum values of
4316 * The coordinate can be converted to their integer equivalents with the
4317 * `floor` function. Casting directly to an integer type works for positive
4318 * coordinates, but fails for negative ones.
4320 * Any or all of the position arguments may be `NULL`. If an error occurs, all
4321 * non-`NULL` position arguments will be set to zero.
4323 * @param[in] window The desired window.
4324 * @param[out] xpos Where to store the cursor x-coordinate, relative to the
4325 * left edge of the content area, or `NULL`.
4326 * @param[out] ypos Where to store the cursor y-coordinate, relative to the to
4327 * top edge of the content area, or `NULL`.
4329 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
4330 * GLFW_PLATFORM_ERROR.
4332 * @thread_safety This function must only be called from the main thread.
4334 * @sa @ref cursor_pos
4335 * @sa @ref glfwSetCursorPos
4337 * @since Added in version 3.0. Replaces `glfwGetMousePos`.
4341 GLFWAPI
void glfwGetCursorPos(GLFWwindow
* window
, double* xpos
, double* ypos
);
4343 /*! @brief Sets the position of the cursor, relative to the content area of the
4346 * This function sets the position, in screen coordinates, of the cursor
4347 * relative to the upper-left corner of the content area of the specified
4348 * window. The window must have input focus. If the window does not have
4349 * input focus when this function is called, it fails silently.
4351 * __Do not use this function__ to implement things like camera controls. GLFW
4352 * already provides the `GLFW_CURSOR_DISABLED` cursor mode that hides the
4353 * cursor, transparently re-centers it and provides unconstrained cursor
4354 * motion. See @ref glfwSetInputMode for more information.
4356 * If the cursor mode is `GLFW_CURSOR_DISABLED` then the cursor position is
4357 * unconstrained and limited only by the minimum and maximum values of
4360 * @param[in] window The desired window.
4361 * @param[in] xpos The desired x-coordinate, relative to the left edge of the
4363 * @param[in] ypos The desired y-coordinate, relative to the top edge of the
4366 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
4367 * GLFW_PLATFORM_ERROR.
4369 * @remark @wayland This function will only work when the cursor mode is
4370 * `GLFW_CURSOR_DISABLED`, otherwise it will do nothing.
4372 * @thread_safety This function must only be called from the main thread.
4374 * @sa @ref cursor_pos
4375 * @sa @ref glfwGetCursorPos
4377 * @since Added in version 3.0. Replaces `glfwSetMousePos`.
4381 GLFWAPI
void glfwSetCursorPos(GLFWwindow
* window
, double xpos
, double ypos
);
4383 /*! @brief Creates a custom cursor.
4385 * Creates a new custom cursor image that can be set for a window with @ref
4386 * glfwSetCursor. The cursor can be destroyed with @ref glfwDestroyCursor.
4387 * Any remaining cursors are destroyed by @ref glfwTerminate.
4389 * The pixels are 32-bit, little-endian, non-premultiplied RGBA, i.e. eight
4390 * bits per channel with the red channel first. They are arranged canonically
4391 * as packed sequential rows, starting from the top-left corner.
4393 * The cursor hotspot is specified in pixels, relative to the upper-left corner
4394 * of the cursor image. Like all other coordinate systems in GLFW, the X-axis
4395 * points to the right and the Y-axis points down.
4397 * @param[in] image The desired cursor image.
4398 * @param[in] xhot The desired x-coordinate, in pixels, of the cursor hotspot.
4399 * @param[in] yhot The desired y-coordinate, in pixels, of the cursor hotspot.
4400 * @return The handle of the created cursor, or `NULL` if an
4401 * [error](@ref error_handling) occurred.
4403 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
4404 * GLFW_PLATFORM_ERROR.
4406 * @pointer_lifetime The specified image data is copied before this function
4409 * @thread_safety This function must only be called from the main thread.
4411 * @sa @ref cursor_object
4412 * @sa @ref glfwDestroyCursor
4413 * @sa @ref glfwCreateStandardCursor
4415 * @since Added in version 3.1.
4419 GLFWAPI GLFWcursor
* glfwCreateCursor(const GLFWimage
* image
, int xhot
, int yhot
);
4421 /*! @brief Creates a cursor with a standard shape.
4423 * Returns a cursor with a [standard shape](@ref shapes), that can be set for
4424 * a window with @ref glfwSetCursor.
4426 * @param[in] shape One of the [standard shapes](@ref shapes).
4427 * @return A new cursor ready to use or `NULL` if an
4428 * [error](@ref error_handling) occurred.
4430 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
4431 * GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR.
4433 * @thread_safety This function must only be called from the main thread.
4435 * @sa @ref cursor_object
4436 * @sa @ref glfwCreateCursor
4438 * @since Added in version 3.1.
4442 GLFWAPI GLFWcursor
* glfwCreateStandardCursor(int shape
);
4444 /*! @brief Destroys a cursor.
4446 * This function destroys a cursor previously created with @ref
4447 * glfwCreateCursor. Any remaining cursors will be destroyed by @ref
4450 * If the specified cursor is current for any window, that window will be
4451 * reverted to the default cursor. This does not affect the cursor mode.
4453 * @param[in] cursor The cursor object to destroy.
4455 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
4456 * GLFW_PLATFORM_ERROR.
4458 * @reentrancy This function must not be called from a callback.
4460 * @thread_safety This function must only be called from the main thread.
4462 * @sa @ref cursor_object
4463 * @sa @ref glfwCreateCursor
4465 * @since Added in version 3.1.
4469 GLFWAPI
void glfwDestroyCursor(GLFWcursor
* cursor
);
4471 /*! @brief Sets the cursor for the window.
4473 * This function sets the cursor image to be used when the cursor is over the
4474 * content area of the specified window. The set cursor will only be visible
4475 * when the [cursor mode](@ref cursor_mode) of the window is
4476 * `GLFW_CURSOR_NORMAL`.
4478 * On some platforms, the set cursor may not be visible unless the window also
4481 * @param[in] window The window to set the cursor for.
4482 * @param[in] cursor The cursor to set, or `NULL` to switch back to the default
4485 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
4486 * GLFW_PLATFORM_ERROR.
4488 * @thread_safety This function must only be called from the main thread.
4490 * @sa @ref cursor_object
4492 * @since Added in version 3.1.
4496 GLFWAPI
void glfwSetCursor(GLFWwindow
* window
, GLFWcursor
* cursor
);
4498 /*! @brief Sets the key callback.
4500 * This function sets the key callback of the specified window, which is called
4501 * when a key is pressed, repeated or released.
4503 * The key functions deal with physical keys, with layout independent
4504 * [key tokens](@ref keys) named after their values in the standard US keyboard
4505 * layout. If you want to input text, use the
4506 * [character callback](@ref glfwSetCharCallback) instead.
4508 * When a window loses input focus, it will generate synthetic key release
4509 * events for all pressed keys. You can tell these events from user-generated
4510 * events by the fact that the synthetic ones are generated after the focus
4511 * loss event has been processed, i.e. after the
4512 * [window focus callback](@ref glfwSetWindowFocusCallback) has been called.
4514 * The scancode of a key is specific to that platform or sometimes even to that
4515 * machine. Scancodes are intended to allow users to bind keys that don't have
4516 * a GLFW key token. Such keys have `key` set to `GLFW_KEY_UNKNOWN`, their
4517 * state is not saved and so it cannot be queried with @ref glfwGetKey.
4519 * Sometimes GLFW needs to generate synthetic key events, in which case the
4520 * scancode may be zero.
4522 * @param[in] window The window whose callback to set.
4523 * @param[in] callback The new key callback, or `NULL` to remove the currently
4525 * @return The previously set callback, or `NULL` if no callback was set or the
4526 * library had not been [initialized](@ref intro_init).
4528 * @callback_signature
4530 * void function_name(GLFWwindow* window, int key, int scancode, int action, int mods)
4532 * For more information about the callback parameters, see the
4533 * [function pointer type](@ref GLFWkeyfun).
4535 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
4537 * @thread_safety This function must only be called from the main thread.
4539 * @sa @ref input_key
4541 * @since Added in version 1.0.
4542 * @glfw3 Added window handle parameter and return value.
4546 GLFWAPI GLFWkeyfun
glfwSetKeyCallback(GLFWwindow
* window
, GLFWkeyfun callback
);
4548 /*! @brief Sets the Unicode character callback.
4550 * This function sets the character callback of the specified window, which is
4551 * called when a Unicode character is input.
4553 * The character callback is intended for Unicode text input. As it deals with
4554 * characters, it is keyboard layout dependent, whereas the
4555 * [key callback](@ref glfwSetKeyCallback) is not. Characters do not map 1:1
4556 * to physical keys, as a key may produce zero, one or more characters. If you
4557 * want to know whether a specific physical key was pressed or released, see
4558 * the key callback instead.
4560 * The character callback behaves as system text input normally does and will
4561 * not be called if modifier keys are held down that would prevent normal text
4562 * input on that platform, for example a Super (Command) key on macOS or Alt key
4565 * @param[in] window The window whose callback to set.
4566 * @param[in] callback The new callback, or `NULL` to remove the currently set
4568 * @return The previously set callback, or `NULL` if no callback was set or the
4569 * library had not been [initialized](@ref intro_init).
4571 * @callback_signature
4573 * void function_name(GLFWwindow* window, unsigned int codepoint)
4575 * For more information about the callback parameters, see the
4576 * [function pointer type](@ref GLFWcharfun).
4578 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
4580 * @thread_safety This function must only be called from the main thread.
4582 * @sa @ref input_char
4584 * @since Added in version 2.4.
4585 * @glfw3 Added window handle parameter and return value.
4589 GLFWAPI GLFWcharfun
glfwSetCharCallback(GLFWwindow
* window
, GLFWcharfun callback
);
4591 /*! @brief Sets the Unicode character with modifiers callback.
4593 * This function sets the character with modifiers callback of the specified
4594 * window, which is called when a Unicode character is input regardless of what
4595 * modifier keys are used.
4597 * The character with modifiers callback is intended for implementing custom
4598 * Unicode character input. For regular Unicode text input, see the
4599 * [character callback](@ref glfwSetCharCallback). Like the character
4600 * callback, the character with modifiers callback deals with characters and is
4601 * keyboard layout dependent. Characters do not map 1:1 to physical keys, as
4602 * a key may produce zero, one or more characters. If you want to know whether
4603 * a specific physical key was pressed or released, see the
4604 * [key callback](@ref glfwSetKeyCallback) instead.
4606 * @param[in] window The window whose callback to set.
4607 * @param[in] callback The new callback, or `NULL` to remove the currently set
4609 * @return The previously set callback, or `NULL` if no callback was set or an
4610 * [error](@ref error_handling) occurred.
4612 * @callback_signature
4614 * void function_name(GLFWwindow* window, unsigned int codepoint, int mods)
4616 * For more information about the callback parameters, see the
4617 * [function pointer type](@ref GLFWcharmodsfun).
4619 * @deprecated Scheduled for removal in version 4.0.
4621 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
4623 * @thread_safety This function must only be called from the main thread.
4625 * @sa @ref input_char
4627 * @since Added in version 3.1.
4631 GLFWAPI GLFWcharmodsfun
glfwSetCharModsCallback(GLFWwindow
* window
, GLFWcharmodsfun callback
);
4633 /*! @brief Sets the mouse button callback.
4635 * This function sets the mouse button callback of the specified window, which
4636 * is called when a mouse button is pressed or released.
4638 * When a window loses input focus, it will generate synthetic mouse button
4639 * release events for all pressed mouse buttons. You can tell these events
4640 * from user-generated events by the fact that the synthetic ones are generated
4641 * after the focus loss event has been processed, i.e. after the
4642 * [window focus callback](@ref glfwSetWindowFocusCallback) has been called.
4644 * @param[in] window The window whose callback to set.
4645 * @param[in] callback The new callback, or `NULL` to remove the currently set
4647 * @return The previously set callback, or `NULL` if no callback was set or the
4648 * library had not been [initialized](@ref intro_init).
4650 * @callback_signature
4652 * void function_name(GLFWwindow* window, int button, int action, int mods)
4654 * For more information about the callback parameters, see the
4655 * [function pointer type](@ref GLFWmousebuttonfun).
4657 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
4659 * @thread_safety This function must only be called from the main thread.
4661 * @sa @ref input_mouse_button
4663 * @since Added in version 1.0.
4664 * @glfw3 Added window handle parameter and return value.
4668 GLFWAPI GLFWmousebuttonfun
glfwSetMouseButtonCallback(GLFWwindow
* window
, GLFWmousebuttonfun callback
);
4670 /*! @brief Sets the cursor position callback.
4672 * This function sets the cursor position callback of the specified window,
4673 * which is called when the cursor is moved. The callback is provided with the
4674 * position, in screen coordinates, relative to the upper-left corner of the
4675 * content area of the window.
4677 * @param[in] window The window whose callback to set.
4678 * @param[in] callback The new callback, or `NULL` to remove the currently set
4680 * @return The previously set callback, or `NULL` if no callback was set or the
4681 * library had not been [initialized](@ref intro_init).
4683 * @callback_signature
4685 * void function_name(GLFWwindow* window, double xpos, double ypos);
4687 * For more information about the callback parameters, see the
4688 * [function pointer type](@ref GLFWcursorposfun).
4690 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
4692 * @thread_safety This function must only be called from the main thread.
4694 * @sa @ref cursor_pos
4696 * @since Added in version 3.0. Replaces `glfwSetMousePosCallback`.
4700 GLFWAPI GLFWcursorposfun
glfwSetCursorPosCallback(GLFWwindow
* window
, GLFWcursorposfun callback
);
4702 /*! @brief Sets the cursor enter/leave callback.
4704 * This function sets the cursor boundary crossing callback of the specified
4705 * window, which is called when the cursor enters or leaves the content area of
4708 * @param[in] window The window whose callback to set.
4709 * @param[in] callback The new callback, or `NULL` to remove the currently set
4711 * @return The previously set callback, or `NULL` if no callback was set or the
4712 * library had not been [initialized](@ref intro_init).
4714 * @callback_signature
4716 * void function_name(GLFWwindow* window, int entered)
4718 * For more information about the callback parameters, see the
4719 * [function pointer type](@ref GLFWcursorenterfun).
4721 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
4723 * @thread_safety This function must only be called from the main thread.
4725 * @sa @ref cursor_enter
4727 * @since Added in version 3.0.
4731 GLFWAPI GLFWcursorenterfun
glfwSetCursorEnterCallback(GLFWwindow
* window
, GLFWcursorenterfun callback
);
4733 /*! @brief Sets the scroll callback.
4735 * This function sets the scroll callback of the specified window, which is
4736 * called when a scrolling device is used, such as a mouse wheel or scrolling
4737 * area of a touchpad.
4739 * The scroll callback receives all scrolling input, like that from a mouse
4740 * wheel or a touchpad scrolling area.
4742 * @param[in] window The window whose callback to set.
4743 * @param[in] callback The new scroll callback, or `NULL` to remove the
4744 * currently set callback.
4745 * @return The previously set callback, or `NULL` if no callback was set or the
4746 * library had not been [initialized](@ref intro_init).
4748 * @callback_signature
4750 * void function_name(GLFWwindow* window, double xoffset, double yoffset)
4752 * For more information about the callback parameters, see the
4753 * [function pointer type](@ref GLFWscrollfun).
4755 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
4757 * @thread_safety This function must only be called from the main thread.
4759 * @sa @ref scrolling
4761 * @since Added in version 3.0. Replaces `glfwSetMouseWheelCallback`.
4765 GLFWAPI GLFWscrollfun
glfwSetScrollCallback(GLFWwindow
* window
, GLFWscrollfun callback
);
4767 /*! @brief Sets the path drop callback.
4769 * This function sets the path drop callback of the specified window, which is
4770 * called when one or more dragged paths are dropped on the window.
4772 * Because the path array and its strings may have been generated specifically
4773 * for that event, they are not guaranteed to be valid after the callback has
4774 * returned. If you wish to use them after the callback returns, you need to
4777 * @param[in] window The window whose callback to set.
4778 * @param[in] callback The new file drop callback, or `NULL` to remove the
4779 * currently set callback.
4780 * @return The previously set callback, or `NULL` if no callback was set or the
4781 * library had not been [initialized](@ref intro_init).
4783 * @callback_signature
4785 * void function_name(GLFWwindow* window, int path_count, const char* paths[])
4787 * For more information about the callback parameters, see the
4788 * [function pointer type](@ref GLFWdropfun).
4790 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
4792 * @remark @wayland File drop is currently unimplemented.
4794 * @thread_safety This function must only be called from the main thread.
4796 * @sa @ref path_drop
4798 * @since Added in version 3.1.
4802 GLFWAPI GLFWdropfun
glfwSetDropCallback(GLFWwindow
* window
, GLFWdropfun callback
);
4804 /*! @brief Returns whether the specified joystick is present.
4806 * This function returns whether the specified joystick is present.
4808 * There is no need to call this function before other functions that accept
4809 * a joystick ID, as they all check for presence before performing any other
4812 * @param[in] jid The [joystick](@ref joysticks) to query.
4813 * @return `GLFW_TRUE` if the joystick is present, or `GLFW_FALSE` otherwise.
4815 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
4816 * GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR.
4818 * @thread_safety This function must only be called from the main thread.
4822 * @since Added in version 3.0. Replaces `glfwGetJoystickParam`.
4826 GLFWAPI
int glfwJoystickPresent(int jid
);
4828 /*! @brief Returns the values of all axes of the specified joystick.
4830 * This function returns the values of all axes of the specified joystick.
4831 * Each element in the array is a value between -1.0 and 1.0.
4833 * If the specified joystick is not present this function will return `NULL`
4834 * but will not generate an error. This can be used instead of first calling
4835 * @ref glfwJoystickPresent.
4837 * @param[in] jid The [joystick](@ref joysticks) to query.
4838 * @param[out] count Where to store the number of axis values in the returned
4839 * array. This is set to zero if the joystick is not present or an error
4841 * @return An array of axis values, or `NULL` if the joystick is not present or
4842 * an [error](@ref error_handling) occurred.
4844 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
4845 * GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR.
4847 * @pointer_lifetime The returned array is allocated and freed by GLFW. You
4848 * should not free it yourself. It is valid until the specified joystick is
4849 * disconnected or the library is terminated.
4851 * @thread_safety This function must only be called from the main thread.
4853 * @sa @ref joystick_axis
4855 * @since Added in version 3.0. Replaces `glfwGetJoystickPos`.
4859 GLFWAPI
const float* glfwGetJoystickAxes(int jid
, int* count
);
4861 /*! @brief Returns the state of all buttons of the specified joystick.
4863 * This function returns the state of all buttons of the specified joystick.
4864 * Each element in the array is either `GLFW_PRESS` or `GLFW_RELEASE`.
4866 * For backward compatibility with earlier versions that did not have @ref
4867 * glfwGetJoystickHats, the button array also includes all hats, each
4868 * represented as four buttons. The hats are in the same order as returned by
4869 * __glfwGetJoystickHats__ and are in the order _up_, _right_, _down_ and
4870 * _left_. To disable these extra buttons, set the @ref
4871 * GLFW_JOYSTICK_HAT_BUTTONS init hint before initialization.
4873 * If the specified joystick is not present this function will return `NULL`
4874 * but will not generate an error. This can be used instead of first calling
4875 * @ref glfwJoystickPresent.
4877 * @param[in] jid The [joystick](@ref joysticks) to query.
4878 * @param[out] count Where to store the number of button states in the returned
4879 * array. This is set to zero if the joystick is not present or an error
4881 * @return An array of button states, or `NULL` if the joystick is not present
4882 * or an [error](@ref error_handling) occurred.
4884 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
4885 * GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR.
4887 * @pointer_lifetime The returned array is allocated and freed by GLFW. You
4888 * should not free it yourself. It is valid until the specified joystick is
4889 * disconnected or the library is terminated.
4891 * @thread_safety This function must only be called from the main thread.
4893 * @sa @ref joystick_button
4895 * @since Added in version 2.2.
4896 * @glfw3 Changed to return a dynamic array.
4900 GLFWAPI
const unsigned char* glfwGetJoystickButtons(int jid
, int* count
);
4902 /*! @brief Returns the state of all hats of the specified joystick.
4904 * This function returns the state of all hats of the specified joystick.
4905 * Each element in the array is one of the following values:
4909 * `GLFW_HAT_CENTERED` | 0
4911 * `GLFW_HAT_RIGHT` | 2
4912 * `GLFW_HAT_DOWN` | 4
4913 * `GLFW_HAT_LEFT` | 8
4914 * `GLFW_HAT_RIGHT_UP` | `GLFW_HAT_RIGHT` \| `GLFW_HAT_UP`
4915 * `GLFW_HAT_RIGHT_DOWN` | `GLFW_HAT_RIGHT` \| `GLFW_HAT_DOWN`
4916 * `GLFW_HAT_LEFT_UP` | `GLFW_HAT_LEFT` \| `GLFW_HAT_UP`
4917 * `GLFW_HAT_LEFT_DOWN` | `GLFW_HAT_LEFT` \| `GLFW_HAT_DOWN`
4919 * The diagonal directions are bitwise combinations of the primary (up, right,
4920 * down and left) directions and you can test for these individually by ANDing
4921 * it with the corresponding direction.
4924 * if (hats[2] & GLFW_HAT_RIGHT)
4926 * // State of hat 2 could be right-up, right or right-down
4930 * If the specified joystick is not present this function will return `NULL`
4931 * but will not generate an error. This can be used instead of first calling
4932 * @ref glfwJoystickPresent.
4934 * @param[in] jid The [joystick](@ref joysticks) to query.
4935 * @param[out] count Where to store the number of hat states in the returned
4936 * array. This is set to zero if the joystick is not present or an error
4938 * @return An array of hat states, or `NULL` if the joystick is not present
4939 * or an [error](@ref error_handling) occurred.
4941 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
4942 * GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR.
4944 * @pointer_lifetime The returned array is allocated and freed by GLFW. You
4945 * should not free it yourself. It is valid until the specified joystick is
4946 * disconnected, this function is called again for that joystick or the library
4949 * @thread_safety This function must only be called from the main thread.
4951 * @sa @ref joystick_hat
4953 * @since Added in version 3.3.
4957 GLFWAPI
const unsigned char* glfwGetJoystickHats(int jid
, int* count
);
4959 /*! @brief Returns the name of the specified joystick.
4961 * This function returns the name, encoded as UTF-8, of the specified joystick.
4962 * The returned string is allocated and freed by GLFW. You should not free it
4965 * If the specified joystick is not present this function will return `NULL`
4966 * but will not generate an error. This can be used instead of first calling
4967 * @ref glfwJoystickPresent.
4969 * @param[in] jid The [joystick](@ref joysticks) to query.
4970 * @return The UTF-8 encoded name of the joystick, or `NULL` if the joystick
4971 * is not present or an [error](@ref error_handling) occurred.
4973 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
4974 * GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR.
4976 * @pointer_lifetime The returned string is allocated and freed by GLFW. You
4977 * should not free it yourself. It is valid until the specified joystick is
4978 * disconnected or the library is terminated.
4980 * @thread_safety This function must only be called from the main thread.
4982 * @sa @ref joystick_name
4984 * @since Added in version 3.0.
4988 GLFWAPI
const char* glfwGetJoystickName(int jid
);
4990 /*! @brief Returns the SDL compatible GUID of the specified joystick.
4992 * This function returns the SDL compatible GUID, as a UTF-8 encoded
4993 * hexadecimal string, of the specified joystick. The returned string is
4994 * allocated and freed by GLFW. You should not free it yourself.
4996 * The GUID is what connects a joystick to a gamepad mapping. A connected
4997 * joystick will always have a GUID even if there is no gamepad mapping
5000 * If the specified joystick is not present this function will return `NULL`
5001 * but will not generate an error. This can be used instead of first calling
5002 * @ref glfwJoystickPresent.
5004 * The GUID uses the format introduced in SDL 2.0.5. This GUID tries to
5005 * uniquely identify the make and model of a joystick but does not identify
5006 * a specific unit, e.g. all wired Xbox 360 controllers will have the same
5007 * GUID on that platform. The GUID for a unit may vary between platforms
5008 * depending on what hardware information the platform specific APIs provide.
5010 * @param[in] jid The [joystick](@ref joysticks) to query.
5011 * @return The UTF-8 encoded GUID of the joystick, or `NULL` if the joystick
5012 * is not present or an [error](@ref error_handling) occurred.
5014 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
5015 * GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR.
5017 * @pointer_lifetime The returned string is allocated and freed by GLFW. You
5018 * should not free it yourself. It is valid until the specified joystick is
5019 * disconnected or the library is terminated.
5021 * @thread_safety This function must only be called from the main thread.
5025 * @since Added in version 3.3.
5029 GLFWAPI
const char* glfwGetJoystickGUID(int jid
);
5031 /*! @brief Sets the user pointer of the specified joystick.
5033 * This function sets the user-defined pointer of the specified joystick. The
5034 * current value is retained until the joystick is disconnected. The initial
5037 * This function may be called from the joystick callback, even for a joystick
5038 * that is being disconnected.
5040 * @param[in] jid The joystick whose pointer to set.
5041 * @param[in] pointer The new value.
5043 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
5045 * @thread_safety This function may be called from any thread. Access is not
5048 * @sa @ref joystick_userptr
5049 * @sa @ref glfwGetJoystickUserPointer
5051 * @since Added in version 3.3.
5055 GLFWAPI
void glfwSetJoystickUserPointer(int jid
, void* pointer
);
5057 /*! @brief Returns the user pointer of the specified joystick.
5059 * This function returns the current value of the user-defined pointer of the
5060 * specified joystick. The initial value is `NULL`.
5062 * This function may be called from the joystick callback, even for a joystick
5063 * that is being disconnected.
5065 * @param[in] jid The joystick whose pointer to return.
5067 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
5069 * @thread_safety This function may be called from any thread. Access is not
5072 * @sa @ref joystick_userptr
5073 * @sa @ref glfwSetJoystickUserPointer
5075 * @since Added in version 3.3.
5079 GLFWAPI
void* glfwGetJoystickUserPointer(int jid
);
5081 /*! @brief Returns whether the specified joystick has a gamepad mapping.
5083 * This function returns whether the specified joystick is both present and has
5084 * a gamepad mapping.
5086 * If the specified joystick is present but does not have a gamepad mapping
5087 * this function will return `GLFW_FALSE` but will not generate an error. Call
5088 * @ref glfwJoystickPresent to check if a joystick is present regardless of
5089 * whether it has a mapping.
5091 * @param[in] jid The [joystick](@ref joysticks) to query.
5092 * @return `GLFW_TRUE` if a joystick is both present and has a gamepad mapping,
5093 * or `GLFW_FALSE` otherwise.
5095 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
5096 * GLFW_INVALID_ENUM.
5098 * @thread_safety This function must only be called from the main thread.
5101 * @sa @ref glfwGetGamepadState
5103 * @since Added in version 3.3.
5107 GLFWAPI
int glfwJoystickIsGamepad(int jid
);
5109 /*! @brief Sets the joystick configuration callback.
5111 * This function sets the joystick configuration callback, or removes the
5112 * currently set callback. This is called when a joystick is connected to or
5113 * disconnected from the system.
5115 * For joystick connection and disconnection events to be delivered on all
5116 * platforms, you need to call one of the [event processing](@ref events)
5117 * functions. Joystick disconnection may also be detected and the callback
5118 * called by joystick functions. The function will then return whatever it
5119 * returns if the joystick is not present.
5121 * @param[in] callback The new callback, or `NULL` to remove the currently set
5123 * @return The previously set callback, or `NULL` if no callback was set or the
5124 * library had not been [initialized](@ref intro_init).
5126 * @callback_signature
5128 * void function_name(int jid, int event)
5130 * For more information about the callback parameters, see the
5131 * [function pointer type](@ref GLFWjoystickfun).
5133 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
5135 * @thread_safety This function must only be called from the main thread.
5137 * @sa @ref joystick_event
5139 * @since Added in version 3.2.
5143 GLFWAPI GLFWjoystickfun
glfwSetJoystickCallback(GLFWjoystickfun callback
);
5145 /*! @brief Adds the specified SDL_GameControllerDB gamepad mappings.
5147 * This function parses the specified ASCII encoded string and updates the
5148 * internal list with any gamepad mappings it finds. This string may
5149 * contain either a single gamepad mapping or many mappings separated by
5150 * newlines. The parser supports the full format of the `gamecontrollerdb.txt`
5151 * source file including empty lines and comments.
5153 * See @ref gamepad_mapping for a description of the format.
5155 * If there is already a gamepad mapping for a given GUID in the internal list,
5156 * it will be replaced by the one passed to this function. If the library is
5157 * terminated and re-initialized the internal list will revert to the built-in
5160 * @param[in] string The string containing the gamepad mappings.
5161 * @return `GLFW_TRUE` if successful, or `GLFW_FALSE` if an
5162 * [error](@ref error_handling) occurred.
5164 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
5165 * GLFW_INVALID_VALUE.
5167 * @thread_safety This function must only be called from the main thread.
5170 * @sa @ref glfwJoystickIsGamepad
5171 * @sa @ref glfwGetGamepadName
5173 * @since Added in version 3.3.
5177 GLFWAPI
int glfwUpdateGamepadMappings(const char* string
);
5179 /*! @brief Returns the human-readable gamepad name for the specified joystick.
5181 * This function returns the human-readable name of the gamepad from the
5182 * gamepad mapping assigned to the specified joystick.
5184 * If the specified joystick is not present or does not have a gamepad mapping
5185 * this function will return `NULL` but will not generate an error. Call
5186 * @ref glfwJoystickPresent to check whether it is present regardless of
5187 * whether it has a mapping.
5189 * @param[in] jid The [joystick](@ref joysticks) to query.
5190 * @return The UTF-8 encoded name of the gamepad, or `NULL` if the
5191 * joystick is not present, does not have a mapping or an
5192 * [error](@ref error_handling) occurred.
5194 * @pointer_lifetime The returned string is allocated and freed by GLFW. You
5195 * should not free it yourself. It is valid until the specified joystick is
5196 * disconnected, the gamepad mappings are updated or the library is terminated.
5198 * @thread_safety This function must only be called from the main thread.
5201 * @sa @ref glfwJoystickIsGamepad
5203 * @since Added in version 3.3.
5207 GLFWAPI
const char* glfwGetGamepadName(int jid
);
5209 /*! @brief Retrieves the state of the specified joystick remapped as a gamepad.
5211 * This function retrieves the state of the specified joystick remapped to
5212 * an Xbox-like gamepad.
5214 * If the specified joystick is not present or does not have a gamepad mapping
5215 * this function will return `GLFW_FALSE` but will not generate an error. Call
5216 * @ref glfwJoystickPresent to check whether it is present regardless of
5217 * whether it has a mapping.
5219 * The Guide button may not be available for input as it is often hooked by the
5220 * system or the Steam client.
5222 * Not all devices have all the buttons or axes provided by @ref
5223 * GLFWgamepadstate. Unavailable buttons and axes will always report
5224 * `GLFW_RELEASE` and 0.0 respectively.
5226 * @param[in] jid The [joystick](@ref joysticks) to query.
5227 * @param[out] state The gamepad input state of the joystick.
5228 * @return `GLFW_TRUE` if successful, or `GLFW_FALSE` if no joystick is
5229 * connected, it has no gamepad mapping or an [error](@ref error_handling)
5232 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
5233 * GLFW_INVALID_ENUM.
5235 * @thread_safety This function must only be called from the main thread.
5238 * @sa @ref glfwUpdateGamepadMappings
5239 * @sa @ref glfwJoystickIsGamepad
5241 * @since Added in version 3.3.
5245 GLFWAPI
int glfwGetGamepadState(int jid
, GLFWgamepadstate
* state
);
5247 /*! @brief Sets the clipboard to the specified string.
5249 * This function sets the system clipboard to the specified, UTF-8 encoded
5252 * @param[in] window Deprecated. Any valid window or `NULL`.
5253 * @param[in] string A UTF-8 encoded string.
5255 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
5256 * GLFW_PLATFORM_ERROR.
5258 * @pointer_lifetime The specified string is copied before this function
5261 * @thread_safety This function must only be called from the main thread.
5263 * @sa @ref clipboard
5264 * @sa @ref glfwGetClipboardString
5266 * @since Added in version 3.0.
5270 GLFWAPI
void glfwSetClipboardString(GLFWwindow
* window
, const char* string
);
5272 /*! @brief Returns the contents of the clipboard as a string.
5274 * This function returns the contents of the system clipboard, if it contains
5275 * or is convertible to a UTF-8 encoded string. If the clipboard is empty or
5276 * if its contents cannot be converted, `NULL` is returned and a @ref
5277 * GLFW_FORMAT_UNAVAILABLE error is generated.
5279 * @param[in] window Deprecated. Any valid window or `NULL`.
5280 * @return The contents of the clipboard as a UTF-8 encoded string, or `NULL`
5281 * if an [error](@ref error_handling) occurred.
5283 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
5284 * GLFW_PLATFORM_ERROR.
5286 * @pointer_lifetime The returned string is allocated and freed by GLFW. You
5287 * should not free it yourself. It is valid until the next call to @ref
5288 * glfwGetClipboardString or @ref glfwSetClipboardString, or until the library
5291 * @thread_safety This function must only be called from the main thread.
5293 * @sa @ref clipboard
5294 * @sa @ref glfwSetClipboardString
5296 * @since Added in version 3.0.
5300 GLFWAPI
const char* glfwGetClipboardString(GLFWwindow
* window
);
5302 /*! @brief Returns the GLFW time.
5304 * This function returns the current GLFW time, in seconds. Unless the time
5305 * has been set using @ref glfwSetTime it measures time elapsed since GLFW was
5308 * This function and @ref glfwSetTime are helper functions on top of @ref
5309 * glfwGetTimerFrequency and @ref glfwGetTimerValue.
5311 * The resolution of the timer is system dependent, but is usually on the order
5312 * of a few micro- or nanoseconds. It uses the highest-resolution monotonic
5313 * time source on each supported platform.
5315 * @return The current time, in seconds, or zero if an
5316 * [error](@ref error_handling) occurred.
5318 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
5320 * @thread_safety This function may be called from any thread. Reading and
5321 * writing of the internal base time is not atomic, so it needs to be
5322 * externally synchronized with calls to @ref glfwSetTime.
5326 * @since Added in version 1.0.
5330 GLFWAPI
double glfwGetTime(void);
5332 /*! @brief Sets the GLFW time.
5334 * This function sets the current GLFW time, in seconds. The value must be
5335 * a positive finite number less than or equal to 18446744073.0, which is
5336 * approximately 584.5 years.
5338 * This function and @ref glfwGetTime are helper functions on top of @ref
5339 * glfwGetTimerFrequency and @ref glfwGetTimerValue.
5341 * @param[in] time The new value, in seconds.
5343 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
5344 * GLFW_INVALID_VALUE.
5346 * @remark The upper limit of GLFW time is calculated as
5347 * floor((2<sup>64</sup> - 1) / 10<sup>9</sup>) and is due to implementations
5348 * storing nanoseconds in 64 bits. The limit may be increased in the future.
5350 * @thread_safety This function may be called from any thread. Reading and
5351 * writing of the internal base time is not atomic, so it needs to be
5352 * externally synchronized with calls to @ref glfwGetTime.
5356 * @since Added in version 2.2.
5360 GLFWAPI
void glfwSetTime(double time
);
5362 /*! @brief Returns the current value of the raw timer.
5364 * This function returns the current value of the raw timer, measured in
5365 * 1 / frequency seconds. To get the frequency, call @ref
5366 * glfwGetTimerFrequency.
5368 * @return The value of the timer, or zero if an
5369 * [error](@ref error_handling) occurred.
5371 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
5373 * @thread_safety This function may be called from any thread.
5376 * @sa @ref glfwGetTimerFrequency
5378 * @since Added in version 3.2.
5382 GLFWAPI
uint64_t glfwGetTimerValue(void);
5384 /*! @brief Returns the frequency, in Hz, of the raw timer.
5386 * This function returns the frequency, in Hz, of the raw timer.
5388 * @return The frequency of the timer, in Hz, or zero if an
5389 * [error](@ref error_handling) occurred.
5391 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
5393 * @thread_safety This function may be called from any thread.
5396 * @sa @ref glfwGetTimerValue
5398 * @since Added in version 3.2.
5402 GLFWAPI
uint64_t glfwGetTimerFrequency(void);
5404 /*! @brief Makes the context of the specified window current for the calling
5407 * This function makes the OpenGL or OpenGL ES context of the specified window
5408 * current on the calling thread. A context must only be made current on
5409 * a single thread at a time and each thread can have only a single current
5410 * context at a time.
5412 * When moving a context between threads, you must make it non-current on the
5413 * old thread before making it current on the new one.
5415 * By default, making a context non-current implicitly forces a pipeline flush.
5416 * On machines that support `GL_KHR_context_flush_control`, you can control
5417 * whether a context performs this flush by setting the
5418 * [GLFW_CONTEXT_RELEASE_BEHAVIOR](@ref GLFW_CONTEXT_RELEASE_BEHAVIOR_hint)
5421 * The specified window must have an OpenGL or OpenGL ES context. Specifying
5422 * a window without a context will generate a @ref GLFW_NO_WINDOW_CONTEXT
5425 * @param[in] window The window whose context to make current, or `NULL` to
5426 * detach the current context.
5428 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
5429 * GLFW_NO_WINDOW_CONTEXT and @ref GLFW_PLATFORM_ERROR.
5431 * @thread_safety This function may be called from any thread.
5433 * @sa @ref context_current
5434 * @sa @ref glfwGetCurrentContext
5436 * @since Added in version 3.0.
5440 GLFWAPI
void glfwMakeContextCurrent(GLFWwindow
* window
);
5442 /*! @brief Returns the window whose context is current on the calling thread.
5444 * This function returns the window whose OpenGL or OpenGL ES context is
5445 * current on the calling thread.
5447 * @return The window whose context is current, or `NULL` if no window's
5448 * context is current.
5450 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
5452 * @thread_safety This function may be called from any thread.
5454 * @sa @ref context_current
5455 * @sa @ref glfwMakeContextCurrent
5457 * @since Added in version 3.0.
5461 GLFWAPI GLFWwindow
* glfwGetCurrentContext(void);
5463 /*! @brief Swaps the front and back buffers of the specified window.
5465 * This function swaps the front and back buffers of the specified window when
5466 * rendering with OpenGL or OpenGL ES. If the swap interval is greater than
5467 * zero, the GPU driver waits the specified number of screen updates before
5468 * swapping the buffers.
5470 * The specified window must have an OpenGL or OpenGL ES context. Specifying
5471 * a window without a context will generate a @ref GLFW_NO_WINDOW_CONTEXT
5474 * This function does not apply to Vulkan. If you are rendering with Vulkan,
5475 * see `vkQueuePresentKHR` instead.
5477 * @param[in] window The window whose buffers to swap.
5479 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
5480 * GLFW_NO_WINDOW_CONTEXT and @ref GLFW_PLATFORM_ERROR.
5482 * @remark __EGL:__ The context of the specified window must be current on the
5485 * @thread_safety This function may be called from any thread.
5487 * @sa @ref buffer_swap
5488 * @sa @ref glfwSwapInterval
5490 * @since Added in version 1.0.
5491 * @glfw3 Added window handle parameter.
5495 GLFWAPI
void glfwSwapBuffers(GLFWwindow
* window
);
5497 /*! @brief Sets the swap interval for the current context.
5499 * This function sets the swap interval for the current OpenGL or OpenGL ES
5500 * context, i.e. the number of screen updates to wait from the time @ref
5501 * glfwSwapBuffers was called before swapping the buffers and returning. This
5502 * is sometimes called _vertical synchronization_, _vertical retrace
5503 * synchronization_ or just _vsync_.
5505 * A context that supports either of the `WGL_EXT_swap_control_tear` and
5506 * `GLX_EXT_swap_control_tear` extensions also accepts _negative_ swap
5507 * intervals, which allows the driver to swap immediately even if a frame
5508 * arrives a little bit late. You can check for these extensions with @ref
5509 * glfwExtensionSupported.
5511 * A context must be current on the calling thread. Calling this function
5512 * without a current context will cause a @ref GLFW_NO_CURRENT_CONTEXT error.
5514 * This function does not apply to Vulkan. If you are rendering with Vulkan,
5515 * see the present mode of your swapchain instead.
5517 * @param[in] interval The minimum number of screen updates to wait for
5518 * until the buffers are swapped by @ref glfwSwapBuffers.
5520 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
5521 * GLFW_NO_CURRENT_CONTEXT and @ref GLFW_PLATFORM_ERROR.
5523 * @remark This function is not called during context creation, leaving the
5524 * swap interval set to whatever is the default on that platform. This is done
5525 * because some swap interval extensions used by GLFW do not allow the swap
5526 * interval to be reset to zero once it has been set to a non-zero value.
5528 * @remark Some GPU drivers do not honor the requested swap interval, either
5529 * because of a user setting that overrides the application's request or due to
5530 * bugs in the driver.
5532 * @thread_safety This function may be called from any thread.
5534 * @sa @ref buffer_swap
5535 * @sa @ref glfwSwapBuffers
5537 * @since Added in version 1.0.
5541 GLFWAPI
void glfwSwapInterval(int interval
);
5543 /*! @brief Returns whether the specified extension is available.
5545 * This function returns whether the specified
5546 * [API extension](@ref context_glext) is supported by the current OpenGL or
5547 * OpenGL ES context. It searches both for client API extension and context
5548 * creation API extensions.
5550 * A context must be current on the calling thread. Calling this function
5551 * without a current context will cause a @ref GLFW_NO_CURRENT_CONTEXT error.
5553 * As this functions retrieves and searches one or more extension strings each
5554 * call, it is recommended that you cache its results if it is going to be used
5555 * frequently. The extension strings will not change during the lifetime of
5556 * a context, so there is no danger in doing this.
5558 * This function does not apply to Vulkan. If you are using Vulkan, see @ref
5559 * glfwGetRequiredInstanceExtensions, `vkEnumerateInstanceExtensionProperties`
5560 * and `vkEnumerateDeviceExtensionProperties` instead.
5562 * @param[in] extension The ASCII encoded name of the extension.
5563 * @return `GLFW_TRUE` if the extension is available, or `GLFW_FALSE`
5566 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
5567 * GLFW_NO_CURRENT_CONTEXT, @ref GLFW_INVALID_VALUE and @ref
5568 * GLFW_PLATFORM_ERROR.
5570 * @thread_safety This function may be called from any thread.
5572 * @sa @ref context_glext
5573 * @sa @ref glfwGetProcAddress
5575 * @since Added in version 1.0.
5579 GLFWAPI
int glfwExtensionSupported(const char* extension
);
5581 /*! @brief Returns the address of the specified function for the current
5584 * This function returns the address of the specified OpenGL or OpenGL ES
5585 * [core or extension function](@ref context_glext), if it is supported
5586 * by the current context.
5588 * A context must be current on the calling thread. Calling this function
5589 * without a current context will cause a @ref GLFW_NO_CURRENT_CONTEXT error.
5591 * This function does not apply to Vulkan. If you are rendering with Vulkan,
5592 * see @ref glfwGetInstanceProcAddress, `vkGetInstanceProcAddr` and
5593 * `vkGetDeviceProcAddr` instead.
5595 * @param[in] procname The ASCII encoded name of the function.
5596 * @return The address of the function, or `NULL` if an
5597 * [error](@ref error_handling) occurred.
5599 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
5600 * GLFW_NO_CURRENT_CONTEXT and @ref GLFW_PLATFORM_ERROR.
5602 * @remark The address of a given function is not guaranteed to be the same
5605 * @remark This function may return a non-`NULL` address despite the
5606 * associated version or extension not being available. Always check the
5607 * context version or extension string first.
5609 * @pointer_lifetime The returned function pointer is valid until the context
5610 * is destroyed or the library is terminated.
5612 * @thread_safety This function may be called from any thread.
5614 * @sa @ref context_glext
5615 * @sa @ref glfwExtensionSupported
5617 * @since Added in version 1.0.
5621 GLFWAPI GLFWglproc
glfwGetProcAddress(const char* procname
);
5623 /*! @brief Returns whether the Vulkan loader and an ICD have been found.
5625 * This function returns whether the Vulkan loader and any minimally functional
5626 * ICD have been found.
5628 * The availability of a Vulkan loader and even an ICD does not by itself
5629 * guarantee that surface creation or even instance creation is possible.
5630 * For example, on Fermi systems Nvidia will install an ICD that provides no
5631 * actual Vulkan support. Call @ref glfwGetRequiredInstanceExtensions to check
5632 * whether the extensions necessary for Vulkan surface creation are available
5633 * and @ref glfwGetPhysicalDevicePresentationSupport to check whether a queue
5634 * family of a physical device supports image presentation.
5636 * @return `GLFW_TRUE` if Vulkan is minimally available, or `GLFW_FALSE`
5639 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
5641 * @thread_safety This function may be called from any thread.
5643 * @sa @ref vulkan_support
5645 * @since Added in version 3.2.
5649 GLFWAPI
int glfwVulkanSupported(void);
5651 /*! @brief Returns the Vulkan instance extensions required by GLFW.
5653 * This function returns an array of names of Vulkan instance extensions required
5654 * by GLFW for creating Vulkan surfaces for GLFW windows. If successful, the
5655 * list will always contain `VK_KHR_surface`, so if you don't require any
5656 * additional extensions you can pass this list directly to the
5657 * `VkInstanceCreateInfo` struct.
5659 * If Vulkan is not available on the machine, this function returns `NULL` and
5660 * generates a @ref GLFW_API_UNAVAILABLE error. Call @ref glfwVulkanSupported
5661 * to check whether Vulkan is at least minimally available.
5663 * If Vulkan is available but no set of extensions allowing window surface
5664 * creation was found, this function returns `NULL`. You may still use Vulkan
5665 * for off-screen rendering and compute work.
5667 * @param[out] count Where to store the number of extensions in the returned
5668 * array. This is set to zero if an error occurred.
5669 * @return An array of ASCII encoded extension names, or `NULL` if an
5670 * [error](@ref error_handling) occurred.
5672 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
5673 * GLFW_API_UNAVAILABLE.
5675 * @remark Additional extensions may be required by future versions of GLFW.
5676 * You should check if any extensions you wish to enable are already in the
5677 * returned array, as it is an error to specify an extension more than once in
5678 * the `VkInstanceCreateInfo` struct.
5680 * @remark @macos This function currently only supports the
5681 * `VK_MVK_macos_surface` extension from MoltenVK.
5683 * @pointer_lifetime The returned array is allocated and freed by GLFW. You
5684 * should not free it yourself. It is guaranteed to be valid only until the
5685 * library is terminated.
5687 * @thread_safety This function may be called from any thread.
5689 * @sa @ref vulkan_ext
5690 * @sa @ref glfwCreateWindowSurface
5692 * @since Added in version 3.2.
5696 GLFWAPI
const char** glfwGetRequiredInstanceExtensions(uint32_t* count
);
5698 #if defined(VK_VERSION_1_0)
5700 /*! @brief Returns the address of the specified Vulkan instance function.
5702 * This function returns the address of the specified Vulkan core or extension
5703 * function for the specified instance. If instance is set to `NULL` it can
5704 * return any function exported from the Vulkan loader, including at least the
5705 * following functions:
5707 * - `vkEnumerateInstanceExtensionProperties`
5708 * - `vkEnumerateInstanceLayerProperties`
5709 * - `vkCreateInstance`
5710 * - `vkGetInstanceProcAddr`
5712 * If Vulkan is not available on the machine, this function returns `NULL` and
5713 * generates a @ref GLFW_API_UNAVAILABLE error. Call @ref glfwVulkanSupported
5714 * to check whether Vulkan is at least minimally available.
5716 * This function is equivalent to calling `vkGetInstanceProcAddr` with
5717 * a platform-specific query of the Vulkan loader as a fallback.
5719 * @param[in] instance The Vulkan instance to query, or `NULL` to retrieve
5720 * functions related to instance creation.
5721 * @param[in] procname The ASCII encoded name of the function.
5722 * @return The address of the function, or `NULL` if an
5723 * [error](@ref error_handling) occurred.
5725 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
5726 * GLFW_API_UNAVAILABLE.
5728 * @pointer_lifetime The returned function pointer is valid until the library
5731 * @thread_safety This function may be called from any thread.
5733 * @sa @ref vulkan_proc
5735 * @since Added in version 3.2.
5739 GLFWAPI GLFWvkproc
glfwGetInstanceProcAddress(VkInstance instance
, const char* procname
);
5741 /*! @brief Returns whether the specified queue family can present images.
5743 * This function returns whether the specified queue family of the specified
5744 * physical device supports presentation to the platform GLFW was built for.
5746 * If Vulkan or the required window surface creation instance extensions are
5747 * not available on the machine, or if the specified instance was not created
5748 * with the required extensions, this function returns `GLFW_FALSE` and
5749 * generates a @ref GLFW_API_UNAVAILABLE error. Call @ref glfwVulkanSupported
5750 * to check whether Vulkan is at least minimally available and @ref
5751 * glfwGetRequiredInstanceExtensions to check what instance extensions are
5754 * @param[in] instance The instance that the physical device belongs to.
5755 * @param[in] device The physical device that the queue family belongs to.
5756 * @param[in] queuefamily The index of the queue family to query.
5757 * @return `GLFW_TRUE` if the queue family supports presentation, or
5758 * `GLFW_FALSE` otherwise.
5760 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
5761 * GLFW_API_UNAVAILABLE and @ref GLFW_PLATFORM_ERROR.
5763 * @remark @macos This function currently always returns `GLFW_TRUE`, as the
5764 * `VK_MVK_macos_surface` extension does not provide
5765 * a `vkGetPhysicalDevice*PresentationSupport` type function.
5767 * @thread_safety This function may be called from any thread. For
5768 * synchronization details of Vulkan objects, see the Vulkan specification.
5770 * @sa @ref vulkan_present
5772 * @since Added in version 3.2.
5776 GLFWAPI
int glfwGetPhysicalDevicePresentationSupport(VkInstance instance
, VkPhysicalDevice device
, uint32_t queuefamily
);
5778 /*! @brief Creates a Vulkan surface for the specified window.
5780 * This function creates a Vulkan surface for the specified window.
5782 * If the Vulkan loader or at least one minimally functional ICD were not found,
5783 * this function returns `VK_ERROR_INITIALIZATION_FAILED` and generates a @ref
5784 * GLFW_API_UNAVAILABLE error. Call @ref glfwVulkanSupported to check whether
5785 * Vulkan is at least minimally available.
5787 * If the required window surface creation instance extensions are not
5788 * available or if the specified instance was not created with these extensions
5789 * enabled, this function returns `VK_ERROR_EXTENSION_NOT_PRESENT` and
5790 * generates a @ref GLFW_API_UNAVAILABLE error. Call @ref
5791 * glfwGetRequiredInstanceExtensions to check what instance extensions are
5794 * The window surface cannot be shared with another API so the window must
5795 * have been created with the [client api hint](@ref GLFW_CLIENT_API_attrib)
5796 * set to `GLFW_NO_API` otherwise it generates a @ref GLFW_INVALID_VALUE error
5797 * and returns `VK_ERROR_NATIVE_WINDOW_IN_USE_KHR`.
5799 * The window surface must be destroyed before the specified Vulkan instance.
5800 * It is the responsibility of the caller to destroy the window surface. GLFW
5801 * does not destroy it for you. Call `vkDestroySurfaceKHR` to destroy the
5804 * @param[in] instance The Vulkan instance to create the surface in.
5805 * @param[in] window The window to create the surface for.
5806 * @param[in] allocator The allocator to use, or `NULL` to use the default
5808 * @param[out] surface Where to store the handle of the surface. This is set
5809 * to `VK_NULL_HANDLE` if an error occurred.
5810 * @return `VK_SUCCESS` if successful, or a Vulkan error code if an
5811 * [error](@ref error_handling) occurred.
5813 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
5814 * GLFW_API_UNAVAILABLE, @ref GLFW_PLATFORM_ERROR and @ref GLFW_INVALID_VALUE
5816 * @remark If an error occurs before the creation call is made, GLFW returns
5817 * the Vulkan error code most appropriate for the error. Appropriate use of
5818 * @ref glfwVulkanSupported and @ref glfwGetRequiredInstanceExtensions should
5819 * eliminate almost all occurrences of these errors.
5821 * @remark @macos This function currently only supports the
5822 * `VK_MVK_macos_surface` extension from MoltenVK.
5824 * @remark @macos This function creates and sets a `CAMetalLayer` instance for
5825 * the window content view, which is required for MoltenVK to function.
5827 * @thread_safety This function may be called from any thread. For
5828 * synchronization details of Vulkan objects, see the Vulkan specification.
5830 * @sa @ref vulkan_surface
5831 * @sa @ref glfwGetRequiredInstanceExtensions
5833 * @since Added in version 3.2.
5837 GLFWAPI VkResult
glfwCreateWindowSurface(VkInstance instance
, GLFWwindow
* window
, const VkAllocationCallbacks
* allocator
, VkSurfaceKHR
* surface
);
5839 #endif /*VK_VERSION_1_0*/
5842 /*************************************************************************
5843 * Global definition cleanup
5844 *************************************************************************/
5846 /* ------------------- BEGIN SYSTEM/COMPILER SPECIFIC -------------------- */
5848 #ifdef GLFW_WINGDIAPI_DEFINED
5850 #undef GLFW_WINGDIAPI_DEFINED
5853 #ifdef GLFW_CALLBACK_DEFINED
5855 #undef GLFW_CALLBACK_DEFINED
5858 /* Some OpenGL related headers need GLAPIENTRY, but it is unconditionally
5859 * defined by some gl.h variants (OpenBSD) so define it after if needed.
5862 #define GLAPIENTRY APIENTRY
5865 /* -------------------- END SYSTEM/COMPILER SPECIFIC --------------------- */
5872 #endif /* _glfw3_h_ */