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