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