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