1 /************************************************************************* 2 * GLFW 3.2 - www.glfw.org 3 * A library for OpenGL, window and input 4 *------------------------------------------------------------------------ 5 * Copyright (c) 2002-2006 Marcus Geelnard 6 * Copyright (c) 2006-2010 Camilla Berglund <elmindreda@elmindreda.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 * 51 * This is the reference documentation for OpenGL and OpenGL ES context related 52 * functions. For more task-oriented information, see the @ref context_guide. 53 */ 54 /*! @defgroup vulkan Vulkan reference 55 * 56 * This is the reference documentation for Vulkan related functions and types. 57 * For more task-oriented information, see the @ref vulkan_guide. 58 */ 59 /*! @defgroup init Initialization, version and error reference 60 * 61 * This is the reference documentation for initialization and termination of 62 * the library, version management and error handling. For more task-oriented 63 * information, see the @ref intro_guide. 64 */ 65 /*! @defgroup input Input reference 66 * 67 * This is the reference documentation for input related functions and types. 68 * For more task-oriented information, see the @ref input_guide. 69 */ 70 /*! @defgroup monitor Monitor reference 71 * 72 * This is the reference documentation for monitor related functions and types. 73 * For more task-oriented information, see the @ref monitor_guide. 74 */ 75 /*! @defgroup window Window reference 76 * 77 * This is the reference documentation for window related functions and types, 78 * including creation, deletion and event polling. For more task-oriented 79 * information, see the @ref window_guide. 80 */ 81 82 83 /************************************************************************* 84 * Compiler- and platform-specific preprocessor work 85 *************************************************************************/ 86 87 /* If we are we on Windows, we want a single define for it. 88 */ 89 #if !defined(_WIN32) && (defined(__WIN32__) || defined(WIN32) || defined(__MINGW32__)) 90 #define _WIN32 91 #endif /* _WIN32 */ 92 93 /* It is customary to use APIENTRY for OpenGL function pointer declarations on 94 * all platforms. Additionally, the Windows OpenGL header needs APIENTRY. 95 */ 96 #ifndef APIENTRY 97 #ifdef _WIN32 98 #define APIENTRY __stdcall 99 #else 100 #define APIENTRY 101 #endif 102 #endif /* APIENTRY */ 103 104 /* Some Windows OpenGL headers need this. 105 */ 106 #if !defined(WINGDIAPI) && defined(_WIN32) 107 #define WINGDIAPI __declspec(dllimport) 108 #define GLFW_WINGDIAPI_DEFINED 109 #endif /* WINGDIAPI */ 110 111 /* Some Windows GLU headers need this. 112 */ 113 #if !defined(CALLBACK) && defined(_WIN32) 114 #define CALLBACK __stdcall 115 #define GLFW_CALLBACK_DEFINED 116 #endif /* CALLBACK */ 117 118 /* Most Windows GLU headers need wchar_t. 119 * The OS X OpenGL header blocks the definition of ptrdiff_t by glext.h. 120 * Include it unconditionally to avoid surprising side-effects. 121 */ 122 #include <stddef.h> 123 #include <stdint.h> 124 125 /* Include the chosen client API headers. 126 */ 127 #if defined(__APPLE__) 128 #if defined(GLFW_INCLUDE_GLCOREARB) 129 #include <OpenGL/gl3.h> 130 #if defined(GLFW_INCLUDE_GLEXT) 131 #include <OpenGL/gl3ext.h> 132 #endif 133 #elif !defined(GLFW_INCLUDE_NONE) 134 #if !defined(GLFW_INCLUDE_GLEXT) 135 #define GL_GLEXT_LEGACY 136 #endif 137 #include <OpenGL/gl.h> 138 #endif 139 #if defined(GLFW_INCLUDE_GLU) 140 #include <OpenGL/glu.h> 141 #endif 142 #else 143 #if defined(GLFW_INCLUDE_GLCOREARB) 144 #include <GL/glcorearb.h> 145 #elif defined(GLFW_INCLUDE_ES1) 146 #include <GLES/gl.h> 147 #if defined(GLFW_INCLUDE_GLEXT) 148 #include <GLES/glext.h> 149 #endif 150 #elif defined(GLFW_INCLUDE_ES2) 151 #include <GLES2/gl2.h> 152 #if defined(GLFW_INCLUDE_GLEXT) 153 #include <GLES2/gl2ext.h> 154 #endif 155 #elif defined(GLFW_INCLUDE_ES3) 156 #include <GLES3/gl3.h> 157 #if defined(GLFW_INCLUDE_GLEXT) 158 #include <GLES2/gl2ext.h> 159 #endif 160 #elif defined(GLFW_INCLUDE_ES31) 161 #include <GLES3/gl31.h> 162 #if defined(GLFW_INCLUDE_GLEXT) 163 #include <GLES2/gl2ext.h> 164 #endif 165 #elif defined(GLFW_INCLUDE_VULKAN) 166 #include <vulkan/vulkan.h> 167 #elif !defined(GLFW_INCLUDE_NONE) 168 #include <GL/gl.h> 169 #if defined(GLFW_INCLUDE_GLEXT) 170 #include <GL/glext.h> 171 #endif 172 #endif 173 #if defined(GLFW_INCLUDE_GLU) 174 #include <GL/glu.h> 175 #endif 176 #endif 177 178 #if defined(GLFW_DLL) && defined(_GLFW_BUILD_DLL) 179 /* GLFW_DLL must be defined by applications that are linking against the DLL 180 * version of the GLFW library. _GLFW_BUILD_DLL is defined by the GLFW 181 * configuration header when compiling the DLL version of the library. 182 */ 183 #error "You must not have both GLFW_DLL and _GLFW_BUILD_DLL defined" 184 #endif 185 186 /* GLFWAPI is used to declare public API functions for export 187 * from the DLL / shared library / dynamic library. 188 */ 189 #if defined(_WIN32) && defined(_GLFW_BUILD_DLL) 190 /* We are building GLFW as a Win32 DLL */ 191 #define GLFWAPI __declspec(dllexport) 192 #elif defined(_WIN32) && defined(GLFW_DLL) 193 /* We are calling GLFW as a Win32 DLL */ 194 #define GLFWAPI __declspec(dllimport) 195 #elif defined(__GNUC__) && defined(_GLFW_BUILD_DLL) 196 /* We are building GLFW as a shared / dynamic library */ 197 #define GLFWAPI __attribute__((visibility("default"))) 198 #else 199 /* We are building or calling GLFW as a static library */ 200 #define GLFWAPI 201 #endif 202 203 204 /************************************************************************* 205 * GLFW API tokens 206 *************************************************************************/ 207 208 /*! @name GLFW version macros 209 * @{ */ 210 /*! @brief The major version number of the GLFW library. 211 * 212 * This is incremented when the API is changed in non-compatible ways. 213 * @ingroup init 214 */ 215 #define GLFW_VERSION_MAJOR 3 216 /*! @brief The minor version number of the GLFW library. 217 * 218 * This is incremented when features are added to the API but it remains 219 * backward-compatible. 220 * @ingroup init 221 */ 222 #define GLFW_VERSION_MINOR 2 223 /*! @brief The revision number of the GLFW library. 224 * 225 * This is incremented when a bug fix release is made that does not contain any 226 * API changes. 227 * @ingroup init 228 */ 229 #define GLFW_VERSION_REVISION 0 230 /*! @} */ 231 232 /*! @name Boolean values 233 * @{ */ 234 /*! @brief One. 235 * 236 * One. Seriously. You don't _need_ to use this symbol in your code. It's 237 * just semantic sugar for the number 1. You can use `1` or `true` or `_True` 238 * or `GL_TRUE` or whatever you want. 239 */ 240 #define GLFW_TRUE 1 241 /*! @brief Zero. 242 * 243 * Zero. Seriously. You don't _need_ to use this symbol in your code. It's 244 * just just semantic sugar for the number 0. You can use `0` or `false` or 245 * `_False` or `GL_FALSE` or whatever you want. 246 */ 247 #define GLFW_FALSE 0 248 /*! @} */ 249 250 /*! @name Key and button actions 251 * @{ */ 252 /*! @brief The key or mouse button was released. 253 * 254 * The key or mouse button was released. 255 * 256 * @ingroup input 257 */ 258 #define GLFW_RELEASE 0 259 /*! @brief The key or mouse button was pressed. 260 * 261 * The key or mouse button was pressed. 262 * 263 * @ingroup input 264 */ 265 #define GLFW_PRESS 1 266 /*! @brief The key was held down until it repeated. 267 * 268 * The key was held down until it repeated. 269 * 270 * @ingroup input 271 */ 272 #define GLFW_REPEAT 2 273 /*! @} */ 274 275 /*! @defgroup keys Keyboard keys 276 * 277 * See [key input](@ref input_key) for how these are used. 278 * 279 * These key codes are inspired by the _USB HID Usage Tables v1.12_ (p. 53-60), 280 * but re-arranged to map to 7-bit ASCII for printable keys (function keys are 281 * put in the 256+ range). 282 * 283 * The naming of the key codes follow these rules: 284 * - The US keyboard layout is used 285 * - Names of printable alpha-numeric characters are used (e.g. "A", "R", 286 * "3", etc.) 287 * - For non-alphanumeric characters, Unicode:ish names are used (e.g. 288 * "COMMA", "LEFT_SQUARE_BRACKET", etc.). Note that some names do not 289 * correspond to the Unicode standard (usually for brevity) 290 * - Keys that lack a clear US mapping are named "WORLD_x" 291 * - For non-printable keys, custom names are used (e.g. "F4", 292 * "BACKSPACE", etc.) 293 * 294 * @ingroup input 295 * @{ 296 */ 297 298 /* The unknown key */ 299 #define GLFW_KEY_UNKNOWN -1 300 301 /* Printable keys */ 302 #define GLFW_KEY_SPACE 32 303 #define GLFW_KEY_APOSTROPHE 39 /* ' */ 304 #define GLFW_KEY_COMMA 44 /* , */ 305 #define GLFW_KEY_MINUS 45 /* - */ 306 #define GLFW_KEY_PERIOD 46 /* . */ 307 #define GLFW_KEY_SLASH 47 /* / */ 308 #define GLFW_KEY_0 48 309 #define GLFW_KEY_1 49 310 #define GLFW_KEY_2 50 311 #define GLFW_KEY_3 51 312 #define GLFW_KEY_4 52 313 #define GLFW_KEY_5 53 314 #define GLFW_KEY_6 54 315 #define GLFW_KEY_7 55 316 #define GLFW_KEY_8 56 317 #define GLFW_KEY_9 57 318 #define GLFW_KEY_SEMICOLON 59 /* ; */ 319 #define GLFW_KEY_EQUAL 61 /* = */ 320 #define GLFW_KEY_A 65 321 #define GLFW_KEY_B 66 322 #define GLFW_KEY_C 67 323 #define GLFW_KEY_D 68 324 #define GLFW_KEY_E 69 325 #define GLFW_KEY_F 70 326 #define GLFW_KEY_G 71 327 #define GLFW_KEY_H 72 328 #define GLFW_KEY_I 73 329 #define GLFW_KEY_J 74 330 #define GLFW_KEY_K 75 331 #define GLFW_KEY_L 76 332 #define GLFW_KEY_M 77 333 #define GLFW_KEY_N 78 334 #define GLFW_KEY_O 79 335 #define GLFW_KEY_P 80 336 #define GLFW_KEY_Q 81 337 #define GLFW_KEY_R 82 338 #define GLFW_KEY_S 83 339 #define GLFW_KEY_T 84 340 #define GLFW_KEY_U 85 341 #define GLFW_KEY_V 86 342 #define GLFW_KEY_W 87 343 #define GLFW_KEY_X 88 344 #define GLFW_KEY_Y 89 345 #define GLFW_KEY_Z 90 346 #define GLFW_KEY_LEFT_BRACKET 91 /* [ */ 347 #define GLFW_KEY_BACKSLASH 92 /* \ */ 348 #define GLFW_KEY_RIGHT_BRACKET 93 /* ] */ 349 #define GLFW_KEY_GRAVE_ACCENT 96 /* ` */ 350 #define GLFW_KEY_WORLD_1 161 /* non-US #1 */ 351 #define GLFW_KEY_WORLD_2 162 /* non-US #2 */ 352 353 /* Function keys */ 354 #define GLFW_KEY_ESCAPE 256 355 #define GLFW_KEY_ENTER 257 356 #define GLFW_KEY_TAB 258 357 #define GLFW_KEY_BACKSPACE 259 358 #define GLFW_KEY_INSERT 260 359 #define GLFW_KEY_DELETE 261 360 #define GLFW_KEY_RIGHT 262 361 #define GLFW_KEY_LEFT 263 362 #define GLFW_KEY_DOWN 264 363 #define GLFW_KEY_UP 265 364 #define GLFW_KEY_PAGE_UP 266 365 #define GLFW_KEY_PAGE_DOWN 267 366 #define GLFW_KEY_HOME 268 367 #define GLFW_KEY_END 269 368 #define GLFW_KEY_CAPS_LOCK 280 369 #define GLFW_KEY_SCROLL_LOCK 281 370 #define GLFW_KEY_NUM_LOCK 282 371 #define GLFW_KEY_PRINT_SCREEN 283 372 #define GLFW_KEY_PAUSE 284 373 #define GLFW_KEY_F1 290 374 #define GLFW_KEY_F2 291 375 #define GLFW_KEY_F3 292 376 #define GLFW_KEY_F4 293 377 #define GLFW_KEY_F5 294 378 #define GLFW_KEY_F6 295 379 #define GLFW_KEY_F7 296 380 #define GLFW_KEY_F8 297 381 #define GLFW_KEY_F9 298 382 #define GLFW_KEY_F10 299 383 #define GLFW_KEY_F11 300 384 #define GLFW_KEY_F12 301 385 #define GLFW_KEY_F13 302 386 #define GLFW_KEY_F14 303 387 #define GLFW_KEY_F15 304 388 #define GLFW_KEY_F16 305 389 #define GLFW_KEY_F17 306 390 #define GLFW_KEY_F18 307 391 #define GLFW_KEY_F19 308 392 #define GLFW_KEY_F20 309 393 #define GLFW_KEY_F21 310 394 #define GLFW_KEY_F22 311 395 #define GLFW_KEY_F23 312 396 #define GLFW_KEY_F24 313 397 #define GLFW_KEY_F25 314 398 #define GLFW_KEY_KP_0 320 399 #define GLFW_KEY_KP_1 321 400 #define GLFW_KEY_KP_2 322 401 #define GLFW_KEY_KP_3 323 402 #define GLFW_KEY_KP_4 324 403 #define GLFW_KEY_KP_5 325 404 #define GLFW_KEY_KP_6 326 405 #define GLFW_KEY_KP_7 327 406 #define GLFW_KEY_KP_8 328 407 #define GLFW_KEY_KP_9 329 408 #define GLFW_KEY_KP_DECIMAL 330 409 #define GLFW_KEY_KP_DIVIDE 331 410 #define GLFW_KEY_KP_MULTIPLY 332 411 #define GLFW_KEY_KP_SUBTRACT 333 412 #define GLFW_KEY_KP_ADD 334 413 #define GLFW_KEY_KP_ENTER 335 414 #define GLFW_KEY_KP_EQUAL 336 415 #define GLFW_KEY_LEFT_SHIFT 340 416 #define GLFW_KEY_LEFT_CONTROL 341 417 #define GLFW_KEY_LEFT_ALT 342 418 #define GLFW_KEY_LEFT_SUPER 343 419 #define GLFW_KEY_RIGHT_SHIFT 344 420 #define GLFW_KEY_RIGHT_CONTROL 345 421 #define GLFW_KEY_RIGHT_ALT 346 422 #define GLFW_KEY_RIGHT_SUPER 347 423 #define GLFW_KEY_MENU 348 424 425 #define GLFW_KEY_LAST GLFW_KEY_MENU 426 427 /*! @} */ 428 429 /*! @defgroup mods Modifier key flags 430 * 431 * See [key input](@ref input_key) for how these are used. 432 * 433 * @ingroup input 434 * @{ */ 435 436 /*! @brief If this bit is set one or more Shift keys were held down. 437 */ 438 #define GLFW_MOD_SHIFT 0x0001 439 /*! @brief If this bit is set one or more Control keys were held down. 440 */ 441 #define GLFW_MOD_CONTROL 0x0002 442 /*! @brief If this bit is set one or more Alt keys were held down. 443 */ 444 #define GLFW_MOD_ALT 0x0004 445 /*! @brief If this bit is set one or more Super keys were held down. 446 */ 447 #define GLFW_MOD_SUPER 0x0008 448 449 /*! @} */ 450 451 /*! @defgroup buttons Mouse buttons 452 * 453 * See [mouse button input](@ref input_mouse_button) for how these are used. 454 * 455 * @ingroup input 456 * @{ */ 457 #define GLFW_MOUSE_BUTTON_1 0 458 #define GLFW_MOUSE_BUTTON_2 1 459 #define GLFW_MOUSE_BUTTON_3 2 460 #define GLFW_MOUSE_BUTTON_4 3 461 #define GLFW_MOUSE_BUTTON_5 4 462 #define GLFW_MOUSE_BUTTON_6 5 463 #define GLFW_MOUSE_BUTTON_7 6 464 #define GLFW_MOUSE_BUTTON_8 7 465 #define GLFW_MOUSE_BUTTON_LAST GLFW_MOUSE_BUTTON_8 466 #define GLFW_MOUSE_BUTTON_LEFT GLFW_MOUSE_BUTTON_1 467 #define GLFW_MOUSE_BUTTON_RIGHT GLFW_MOUSE_BUTTON_2 468 #define GLFW_MOUSE_BUTTON_MIDDLE GLFW_MOUSE_BUTTON_3 469 /*! @} */ 470 471 /*! @defgroup joysticks Joysticks 472 * 473 * See [joystick input](@ref joystick) for how these are used. 474 * 475 * @ingroup input 476 * @{ */ 477 #define GLFW_JOYSTICK_1 0 478 #define GLFW_JOYSTICK_2 1 479 #define GLFW_JOYSTICK_3 2 480 #define GLFW_JOYSTICK_4 3 481 #define GLFW_JOYSTICK_5 4 482 #define GLFW_JOYSTICK_6 5 483 #define GLFW_JOYSTICK_7 6 484 #define GLFW_JOYSTICK_8 7 485 #define GLFW_JOYSTICK_9 8 486 #define GLFW_JOYSTICK_10 9 487 #define GLFW_JOYSTICK_11 10 488 #define GLFW_JOYSTICK_12 11 489 #define GLFW_JOYSTICK_13 12 490 #define GLFW_JOYSTICK_14 13 491 #define GLFW_JOYSTICK_15 14 492 #define GLFW_JOYSTICK_16 15 493 #define GLFW_JOYSTICK_LAST GLFW_JOYSTICK_16 494 /*! @} */ 495 496 /*! @defgroup errors Error codes 497 * 498 * See [error handling](@ref error_handling) for how these are used. 499 * 500 * @ingroup init 501 * @{ */ 502 /*! @brief GLFW has not been initialized. 503 * 504 * This occurs if a GLFW function was called that must not be called unless the 505 * library is [initialized](@ref intro_init). 506 * 507 * @analysis Application programmer error. Initialize GLFW before calling any 508 * function that requires initialization. 509 */ 510 #define GLFW_NOT_INITIALIZED 0x00010001 511 /*! @brief No context is current for this thread. 512 * 513 * This occurs if a GLFW function was called that needs and operates on the 514 * current OpenGL or OpenGL ES context but no context is current on the calling 515 * thread. One such function is @ref glfwSwapInterval. 516 * 517 * @analysis Application programmer error. Ensure a context is current before 518 * calling functions that require a current context. 519 */ 520 #define GLFW_NO_CURRENT_CONTEXT 0x00010002 521 /*! @brief One of the arguments to the function was an invalid enum value. 522 * 523 * One of the arguments to the function was an invalid enum value, for example 524 * requesting [GLFW_RED_BITS](@ref window_hints_fb) with @ref 525 * glfwGetWindowAttrib. 526 * 527 * @analysis Application programmer error. Fix the offending call. 528 */ 529 #define GLFW_INVALID_ENUM 0x00010003 530 /*! @brief One of the arguments to the function was an invalid value. 531 * 532 * One of the arguments to the function was an invalid value, for example 533 * requesting a non-existent OpenGL or OpenGL ES version like 2.7. 534 * 535 * Requesting a valid but unavailable OpenGL or OpenGL ES version will instead 536 * result in a @ref GLFW_VERSION_UNAVAILABLE error. 537 * 538 * @analysis Application programmer error. Fix the offending call. 539 */ 540 #define GLFW_INVALID_VALUE 0x00010004 541 /*! @brief A memory allocation failed. 542 * 543 * A memory allocation failed. 544 * 545 * @analysis A bug in GLFW or the underlying operating system. Report the bug 546 * to our [issue tracker](https://github.com/glfw/glfw/issues). 547 */ 548 #define GLFW_OUT_OF_MEMORY 0x00010005 549 /*! @brief GLFW could not find support for the requested API on the system. 550 * 551 * GLFW could not find support for the requested API on the system. 552 * 553 * @analysis The installed graphics driver does not support the requested 554 * API, or does not support it via the chosen context creation backend. 555 * Below are a few examples. 556 * 557 * @par 558 * Some pre-installed Windows graphics drivers do not support OpenGL. AMD only 559 * supports OpenGL ES via EGL, while Nvidia and Intel only support it via 560 * a WGL or GLX extension. OS X does not provide OpenGL ES at all. The Mesa 561 * EGL, OpenGL and OpenGL ES libraries do not interface with the Nvidia binary 562 * driver. Older graphics drivers do not support Vulkan. 563 */ 564 #define GLFW_API_UNAVAILABLE 0x00010006 565 /*! @brief The requested OpenGL or OpenGL ES version is not available. 566 * 567 * The requested OpenGL or OpenGL ES version (including any requested context 568 * or framebuffer hints) is not available on this machine. 569 * 570 * @analysis The machine does not support your requirements. If your 571 * application is sufficiently flexible, downgrade your requirements and try 572 * again. Otherwise, inform the user that their machine does not match your 573 * requirements. 574 * 575 * @par 576 * Future invalid OpenGL and OpenGL ES versions, for example OpenGL 4.8 if 5.0 577 * comes out before the 4.x series gets that far, also fail with this error and 578 * not @ref GLFW_INVALID_VALUE, because GLFW cannot know what future versions 579 * will exist. 580 */ 581 #define GLFW_VERSION_UNAVAILABLE 0x00010007 582 /*! @brief A platform-specific error occurred that does not match any of the 583 * more specific categories. 584 * 585 * A platform-specific error occurred that does not match any of the more 586 * specific categories. 587 * 588 * @analysis A bug or configuration error in GLFW, the underlying operating 589 * system or its drivers, or a lack of required resources. Report the issue to 590 * our [issue tracker](https://github.com/glfw/glfw/issues). 591 */ 592 #define GLFW_PLATFORM_ERROR 0x00010008 593 /*! @brief The requested format is not supported or available. 594 * 595 * If emitted during window creation, the requested pixel format is not 596 * supported. 597 * 598 * If emitted when querying the clipboard, the contents of the clipboard could 599 * not be converted to the requested format. 600 * 601 * @analysis If emitted during window creation, one or more 602 * [hard constraints](@ref window_hints_hard) did not match any of the 603 * available pixel formats. If your application is sufficiently flexible, 604 * downgrade your requirements and try again. Otherwise, inform the user that 605 * their machine does not match your requirements. 606 * 607 * @par 608 * If emitted when querying the clipboard, ignore the error or report it to 609 * the user, as appropriate. 610 */ 611 #define GLFW_FORMAT_UNAVAILABLE 0x00010009 612 /*! @brief The specified window does not have an OpenGL or OpenGL ES context. 613 * 614 * A window that does not have an OpenGL or OpenGL ES context was passed to 615 * a function that requires it to have one. 616 * 617 * @analysis Application programmer error. Fix the offending call. 618 */ 619 #define GLFW_NO_WINDOW_CONTEXT 0x0001000A 620 /*! @} */ 621 622 #define GLFW_FOCUSED 0x00020001 623 #define GLFW_ICONIFIED 0x00020002 624 #define GLFW_RESIZABLE 0x00020003 625 #define GLFW_VISIBLE 0x00020004 626 #define GLFW_DECORATED 0x00020005 627 #define GLFW_AUTO_ICONIFY 0x00020006 628 #define GLFW_FLOATING 0x00020007 629 #define GLFW_MAXIMIZED 0x00020008 630 631 #define GLFW_RED_BITS 0x00021001 632 #define GLFW_GREEN_BITS 0x00021002 633 #define GLFW_BLUE_BITS 0x00021003 634 #define GLFW_ALPHA_BITS 0x00021004 635 #define GLFW_DEPTH_BITS 0x00021005 636 #define GLFW_STENCIL_BITS 0x00021006 637 #define GLFW_ACCUM_RED_BITS 0x00021007 638 #define GLFW_ACCUM_GREEN_BITS 0x00021008 639 #define GLFW_ACCUM_BLUE_BITS 0x00021009 640 #define GLFW_ACCUM_ALPHA_BITS 0x0002100A 641 #define GLFW_AUX_BUFFERS 0x0002100B 642 #define GLFW_STEREO 0x0002100C 643 #define GLFW_SAMPLES 0x0002100D 644 #define GLFW_SRGB_CAPABLE 0x0002100E 645 #define GLFW_REFRESH_RATE 0x0002100F 646 #define GLFW_DOUBLEBUFFER 0x00021010 647 648 #define GLFW_CLIENT_API 0x00022001 649 #define GLFW_CONTEXT_VERSION_MAJOR 0x00022002 650 #define GLFW_CONTEXT_VERSION_MINOR 0x00022003 651 #define GLFW_CONTEXT_REVISION 0x00022004 652 #define GLFW_CONTEXT_ROBUSTNESS 0x00022005 653 #define GLFW_OPENGL_FORWARD_COMPAT 0x00022006 654 #define GLFW_OPENGL_DEBUG_CONTEXT 0x00022007 655 #define GLFW_OPENGL_PROFILE 0x00022008 656 #define GLFW_CONTEXT_RELEASE_BEHAVIOR 0x00022009 657 #define GLFW_CONTEXT_NO_ERROR 0x0002200A 658 659 #define GLFW_NO_API 0 660 #define GLFW_OPENGL_API 0x00030001 661 #define GLFW_OPENGL_ES_API 0x00030002 662 663 #define GLFW_NO_ROBUSTNESS 0 664 #define GLFW_NO_RESET_NOTIFICATION 0x00031001 665 #define GLFW_LOSE_CONTEXT_ON_RESET 0x00031002 666 667 #define GLFW_OPENGL_ANY_PROFILE 0 668 #define GLFW_OPENGL_CORE_PROFILE 0x00032001 669 #define GLFW_OPENGL_COMPAT_PROFILE 0x00032002 670 671 #define GLFW_CURSOR 0x00033001 672 #define GLFW_STICKY_KEYS 0x00033002 673 #define GLFW_STICKY_MOUSE_BUTTONS 0x00033003 674 675 #define GLFW_CURSOR_NORMAL 0x00034001 676 #define GLFW_CURSOR_HIDDEN 0x00034002 677 #define GLFW_CURSOR_DISABLED 0x00034003 678 679 #define GLFW_ANY_RELEASE_BEHAVIOR 0 680 #define GLFW_RELEASE_BEHAVIOR_FLUSH 0x00035001 681 #define GLFW_RELEASE_BEHAVIOR_NONE 0x00035002 682 683 /*! @defgroup shapes Standard cursor shapes 684 * 685 * See [standard cursor creation](@ref cursor_standard) for how these are used. 686 * 687 * @ingroup input 688 * @{ */ 689 690 /*! @brief The regular arrow cursor shape. 691 * 692 * The regular arrow cursor. 693 */ 694 #define GLFW_ARROW_CURSOR 0x00036001 695 /*! @brief The text input I-beam cursor shape. 696 * 697 * The text input I-beam cursor shape. 698 */ 699 #define GLFW_IBEAM_CURSOR 0x00036002 700 /*! @brief The crosshair shape. 701 * 702 * The crosshair shape. 703 */ 704 #define GLFW_CROSSHAIR_CURSOR 0x00036003 705 /*! @brief The hand shape. 706 * 707 * The hand shape. 708 */ 709 #define GLFW_HAND_CURSOR 0x00036004 710 /*! @brief The horizontal resize arrow shape. 711 * 712 * The horizontal resize arrow shape. 713 */ 714 #define GLFW_HRESIZE_CURSOR 0x00036005 715 /*! @brief The vertical resize arrow shape. 716 * 717 * The vertical resize arrow shape. 718 */ 719 #define GLFW_VRESIZE_CURSOR 0x00036006 720 /*! @} */ 721 722 #define GLFW_CONNECTED 0x00040001 723 #define GLFW_DISCONNECTED 0x00040002 724 725 #define GLFW_DONT_CARE -1 726 727 728 /************************************************************************* 729 * GLFW API types 730 *************************************************************************/ 731 732 /*! @brief Client API function pointer type. 733 * 734 * Generic function pointer used for returning client API function pointers 735 * without forcing a cast from a regular pointer. 736 * 737 * @sa @ref context_glext 738 * @sa glfwGetProcAddress 739 * 740 * @since Added in version 3.0. 741 742 * @ingroup context 743 */ 744 typedef void (*GLFWglproc)(void); 745 746 /*! @brief Vulkan API function pointer type. 747 * 748 * Generic function pointer used for returning Vulkan API function pointers 749 * without forcing a cast from a regular pointer. 750 * 751 * @sa @ref vulkan_proc 752 * @sa glfwGetInstanceProcAddress 753 * 754 * @since Added in version 3.2. 755 * 756 * @ingroup vulkan 757 */ 758 typedef void (*GLFWvkproc)(void); 759 760 /*! @brief Opaque monitor object. 761 * 762 * Opaque monitor object. 763 * 764 * @see @ref monitor_object 765 * 766 * @since Added in version 3.0. 767 * 768 * @ingroup monitor 769 */ 770 typedef struct GLFWmonitor GLFWmonitor; 771 772 /*! @brief Opaque window object. 773 * 774 * Opaque window object. 775 * 776 * @see @ref window_object 777 * 778 * @since Added in version 3.0. 779 * 780 * @ingroup window 781 */ 782 typedef struct GLFWwindow GLFWwindow; 783 784 /*! @brief Opaque cursor object. 785 * 786 * Opaque cursor object. 787 * 788 * @see @ref cursor_object 789 * 790 * @since Added in version 3.1. 791 * 792 * @ingroup cursor 793 */ 794 typedef struct GLFWcursor GLFWcursor; 795 796 /*! @brief The function signature for error callbacks. 797 * 798 * This is the function signature for error callback functions. 799 * 800 * @param[in] error An [error code](@ref errors). 801 * @param[in] description A UTF-8 encoded string describing the error. 802 * 803 * @sa @ref error_handling 804 * @sa glfwSetErrorCallback 805 * 806 * @since Added in version 3.0. 807 * 808 * @ingroup init 809 */ 810 typedef void (* GLFWerrorfun)(int,const char*); 811 812 /*! @brief The function signature for window position callbacks. 813 * 814 * This is the function signature for window position callback functions. 815 * 816 * @param[in] window The window that was moved. 817 * @param[in] xpos The new x-coordinate, in screen coordinates, of the 818 * upper-left corner of the client area of the window. 819 * @param[in] ypos The new y-coordinate, in screen coordinates, of the 820 * upper-left corner of the client area of the window. 821 * 822 * @sa @ref window_pos 823 * @sa glfwSetWindowPosCallback 824 * 825 * @since Added in version 3.0. 826 * 827 * @ingroup window 828 */ 829 typedef void (* GLFWwindowposfun)(GLFWwindow*,int,int); 830 831 /*! @brief The function signature for window resize callbacks. 832 * 833 * This is the function signature for window size callback functions. 834 * 835 * @param[in] window The window that was resized. 836 * @param[in] width The new width, in screen coordinates, of the window. 837 * @param[in] height The new height, in screen coordinates, of the window. 838 * 839 * @sa @ref window_size 840 * @sa glfwSetWindowSizeCallback 841 * 842 * @since Added in version 1.0. 843 * @glfw3 Added window handle parameter. 844 * 845 * @ingroup window 846 */ 847 typedef void (* GLFWwindowsizefun)(GLFWwindow*,int,int); 848 849 /*! @brief The function signature for window close callbacks. 850 * 851 * This is the function signature for window close callback functions. 852 * 853 * @param[in] window The window that the user attempted to close. 854 * 855 * @sa @ref window_close 856 * @sa glfwSetWindowCloseCallback 857 * 858 * @since Added in version 2.5. 859 * @glfw3 Added window handle parameter. 860 * 861 * @ingroup window 862 */ 863 typedef void (* GLFWwindowclosefun)(GLFWwindow*); 864 865 /*! @brief The function signature for window content refresh callbacks. 866 * 867 * This is the function signature for window refresh callback functions. 868 * 869 * @param[in] window The window whose content needs to be refreshed. 870 * 871 * @sa @ref window_refresh 872 * @sa glfwSetWindowRefreshCallback 873 * 874 * @since Added in version 2.5. 875 * @glfw3 Added window handle parameter. 876 * 877 * @ingroup window 878 */ 879 typedef void (* GLFWwindowrefreshfun)(GLFWwindow*); 880 881 /*! @brief The function signature for window focus/defocus callbacks. 882 * 883 * This is the function signature for window focus callback functions. 884 * 885 * @param[in] window The window that gained or lost input focus. 886 * @param[in] focused `GLFW_TRUE` if the window was given input focus, or 887 * `GLFW_FALSE` if it lost it. 888 * 889 * @sa @ref window_focus 890 * @sa glfwSetWindowFocusCallback 891 * 892 * @since Added in version 3.0. 893 * 894 * @ingroup window 895 */ 896 typedef void (* GLFWwindowfocusfun)(GLFWwindow*,int); 897 898 /*! @brief The function signature for window iconify/restore callbacks. 899 * 900 * This is the function signature for window iconify/restore callback 901 * functions. 902 * 903 * @param[in] window The window that was iconified or restored. 904 * @param[in] iconified `GLFW_TRUE` if the window was iconified, or 905 * `GLFW_FALSE` if it was restored. 906 * 907 * @sa @ref window_iconify 908 * @sa glfwSetWindowIconifyCallback 909 * 910 * @since Added in version 3.0. 911 * 912 * @ingroup window 913 */ 914 typedef void (* GLFWwindowiconifyfun)(GLFWwindow*,int); 915 916 /*! @brief The function signature for framebuffer resize callbacks. 917 * 918 * This is the function signature for framebuffer resize callback 919 * functions. 920 * 921 * @param[in] window The window whose framebuffer was resized. 922 * @param[in] width The new width, in pixels, of the framebuffer. 923 * @param[in] height The new height, in pixels, of the framebuffer. 924 * 925 * @sa @ref window_fbsize 926 * @sa glfwSetFramebufferSizeCallback 927 * 928 * @since Added in version 3.0. 929 * 930 * @ingroup window 931 */ 932 typedef void (* GLFWframebuffersizefun)(GLFWwindow*,int,int); 933 934 /*! @brief The function signature for mouse button callbacks. 935 * 936 * This is the function signature for mouse button callback functions. 937 * 938 * @param[in] window The window that received the event. 939 * @param[in] button The [mouse button](@ref buttons) that was pressed or 940 * released. 941 * @param[in] action One of `GLFW_PRESS` or `GLFW_RELEASE`. 942 * @param[in] mods Bit field describing which [modifier keys](@ref mods) were 943 * held down. 944 * 945 * @sa @ref input_mouse_button 946 * @sa glfwSetMouseButtonCallback 947 * 948 * @since Added in version 1.0. 949 * @glfw3 Added window handle and modifier mask parameters. 950 * 951 * @ingroup input 952 */ 953 typedef void (* GLFWmousebuttonfun)(GLFWwindow*,int,int,int); 954 955 /*! @brief The function signature for cursor position callbacks. 956 * 957 * This is the function signature for cursor position callback functions. 958 * 959 * @param[in] window The window that received the event. 960 * @param[in] xpos The new cursor x-coordinate, relative to the left edge of 961 * the client area. 962 * @param[in] ypos The new cursor y-coordinate, relative to the top edge of the 963 * client area. 964 * 965 * @sa @ref cursor_pos 966 * @sa glfwSetCursorPosCallback 967 * 968 * @since Added in version 3.0. Replaces `GLFWmouseposfun`. 969 * 970 * @ingroup input 971 */ 972 typedef void (* GLFWcursorposfun)(GLFWwindow*,double,double); 973 974 /*! @brief The function signature for cursor enter/leave callbacks. 975 * 976 * This is the function signature for cursor enter/leave callback functions. 977 * 978 * @param[in] window The window that received the event. 979 * @param[in] entered `GLFW_TRUE` if the cursor entered the window's client 980 * area, or `GLFW_FALSE` if it left it. 981 * 982 * @sa @ref cursor_enter 983 * @sa glfwSetCursorEnterCallback 984 * 985 * @since Added in version 3.0. 986 * 987 * @ingroup input 988 */ 989 typedef void (* GLFWcursorenterfun)(GLFWwindow*,int); 990 991 /*! @brief The function signature for scroll callbacks. 992 * 993 * This is the function signature for scroll callback functions. 994 * 995 * @param[in] window The window that received the event. 996 * @param[in] xoffset The scroll offset along the x-axis. 997 * @param[in] yoffset The scroll offset along the y-axis. 998 * 999 * @sa @ref scrolling 1000 * @sa glfwSetScrollCallback 1001 * 1002 * @since Added in version 3.0. Replaces `GLFWmousewheelfun`. 1003 * 1004 * @ingroup input 1005 */ 1006 typedef void (* GLFWscrollfun)(GLFWwindow*,double,double); 1007 1008 /*! @brief The function signature for keyboard key callbacks. 1009 * 1010 * This is the function signature for keyboard key callback functions. 1011 * 1012 * @param[in] window The window that received the event. 1013 * @param[in] key The [keyboard key](@ref keys) that was pressed or released. 1014 * @param[in] scancode The system-specific scancode of the key. 1015 * @param[in] action `GLFW_PRESS`, `GLFW_RELEASE` or `GLFW_REPEAT`. 1016 * @param[in] mods Bit field describing which [modifier keys](@ref mods) were 1017 * held down. 1018 * 1019 * @sa @ref input_key 1020 * @sa glfwSetKeyCallback 1021 * 1022 * @since Added in version 1.0. 1023 * @glfw3 Added window handle, scancode and modifier mask parameters. 1024 * 1025 * @ingroup input 1026 */ 1027 typedef void (* GLFWkeyfun)(GLFWwindow*,int,int,int,int); 1028 1029 /*! @brief The function signature for Unicode character callbacks. 1030 * 1031 * This is the function signature for Unicode character callback functions. 1032 * 1033 * @param[in] window The window that received the event. 1034 * @param[in] codepoint The Unicode code point of the character. 1035 * 1036 * @sa @ref input_char 1037 * @sa glfwSetCharCallback 1038 * 1039 * @since Added in version 2.4. 1040 * @glfw3 Added window handle parameter. 1041 * 1042 * @ingroup input 1043 */ 1044 typedef void (* GLFWcharfun)(GLFWwindow*,unsigned int); 1045 1046 /*! @brief The function signature for Unicode character with modifiers 1047 * callbacks. 1048 * 1049 * This is the function signature for Unicode character with modifiers callback 1050 * functions. It is called for each input character, regardless of what 1051 * modifier keys are held down. 1052 * 1053 * @param[in] window The window that received the event. 1054 * @param[in] codepoint The Unicode code point of the character. 1055 * @param[in] mods Bit field describing which [modifier keys](@ref mods) were 1056 * held down. 1057 * 1058 * @sa @ref input_char 1059 * @sa glfwSetCharModsCallback 1060 * 1061 * @since Added in version 3.1. 1062 * 1063 * @ingroup input 1064 */ 1065 typedef void (* GLFWcharmodsfun)(GLFWwindow*,unsigned int,int); 1066 1067 /*! @brief The function signature for file drop callbacks. 1068 * 1069 * This is the function signature for file drop callbacks. 1070 * 1071 * @param[in] window The window that received the event. 1072 * @param[in] count The number of dropped files. 1073 * @param[in] paths The UTF-8 encoded file and/or directory path names. 1074 * 1075 * @sa @ref path_drop 1076 * @sa glfwSetDropCallback 1077 * 1078 * @since Added in version 3.1. 1079 * 1080 * @ingroup input 1081 */ 1082 typedef void (* GLFWdropfun)(GLFWwindow*,int,const char**); 1083 1084 /*! @brief The function signature for monitor configuration callbacks. 1085 * 1086 * This is the function signature for monitor configuration callback functions. 1087 * 1088 * @param[in] monitor The monitor that was connected or disconnected. 1089 * @param[in] event One of `GLFW_CONNECTED` or `GLFW_DISCONNECTED`. 1090 * 1091 * @sa @ref monitor_event 1092 * @sa glfwSetMonitorCallback 1093 * 1094 * @since Added in version 3.0. 1095 * 1096 * @ingroup monitor 1097 */ 1098 typedef void (* GLFWmonitorfun)(GLFWmonitor*,int); 1099 1100 /*! @brief The function signature for joystick configuration callbacks. 1101 * 1102 * This is the function signature for joystick configuration callback 1103 * functions. 1104 * 1105 * @param[in] joy The joystick that was connected or disconnected. 1106 * @param[in] event One of `GLFW_CONNECTED` or `GLFW_DISCONNECTED`. 1107 * 1108 * @sa @ref joystick_event 1109 * @sa glfwSetJoystickCallback 1110 * 1111 * @since Added in version 3.2. 1112 * 1113 * @ingroup input 1114 */ 1115 typedef void (* GLFWjoystickfun)(int,int); 1116 1117 /*! @brief Video mode type. 1118 * 1119 * This describes a single video mode. 1120 * 1121 * @sa @ref monitor_modes 1122 * @sa glfwGetVideoMode glfwGetVideoModes 1123 * 1124 * @since Added in version 1.0. 1125 * @glfw3 Added refresh rate member. 1126 * 1127 * @ingroup monitor 1128 */ 1129 typedef struct GLFWvidmode 1130 { 1131 /*! The width, in screen coordinates, of the video mode. 1132 */ 1133 int width; 1134 /*! The height, in screen coordinates, of the video mode. 1135 */ 1136 int height; 1137 /*! The bit depth of the red channel of the video mode. 1138 */ 1139 int redBits; 1140 /*! The bit depth of the green channel of the video mode. 1141 */ 1142 int greenBits; 1143 /*! The bit depth of the blue channel of the video mode. 1144 */ 1145 int blueBits; 1146 /*! The refresh rate, in Hz, of the video mode. 1147 */ 1148 int refreshRate; 1149 } GLFWvidmode; 1150 1151 /*! @brief Gamma ramp. 1152 * 1153 * This describes the gamma ramp for a monitor. 1154 * 1155 * @sa @ref monitor_gamma 1156 * @sa glfwGetGammaRamp glfwSetGammaRamp 1157 * 1158 * @since Added in version 3.0. 1159 * 1160 * @ingroup monitor 1161 */ 1162 typedef struct GLFWgammaramp 1163 { 1164 /*! An array of value describing the response of the red channel. 1165 */ 1166 unsigned short* red; 1167 /*! An array of value describing the response of the green channel. 1168 */ 1169 unsigned short* green; 1170 /*! An array of value describing the response of the blue channel. 1171 */ 1172 unsigned short* blue; 1173 /*! The number of elements in each array. 1174 */ 1175 unsigned int size; 1176 } GLFWgammaramp; 1177 1178 /*! @brief Image data. 1179 * 1180 * @sa @ref cursor_custom 1181 * 1182 * @since Added in version 2.1. 1183 * @glfw3 Removed format and bytes-per-pixel members. 1184 */ 1185 typedef struct GLFWimage 1186 { 1187 /*! The width, in pixels, of this image. 1188 */ 1189 int width; 1190 /*! The height, in pixels, of this image. 1191 */ 1192 int height; 1193 /*! The pixel data of this image, arranged left-to-right, top-to-bottom. 1194 */ 1195 unsigned char* pixels; 1196 } GLFWimage; 1197 1198 1199 /************************************************************************* 1200 * GLFW API functions 1201 *************************************************************************/ 1202 1203 /*! @brief Initializes the GLFW library. 1204 * 1205 * This function initializes the GLFW library. Before most GLFW functions can 1206 * be used, GLFW must be initialized, and before an application terminates GLFW 1207 * should be terminated in order to free any resources allocated during or 1208 * after initialization. 1209 * 1210 * If this function fails, it calls @ref glfwTerminate before returning. If it 1211 * succeeds, you should call @ref glfwTerminate before the application exits. 1212 * 1213 * Additional calls to this function after successful initialization but before 1214 * termination will return `GLFW_TRUE` immediately. 1215 * 1216 * @return `GLFW_TRUE` if successful, or `GLFW_FALSE` if an 1217 * [error](@ref error_handling) occurred. 1218 * 1219 * @errors Possible errors include @ref GLFW_PLATFORM_ERROR. 1220 * 1221 * @remark @osx This function will change the current directory of the 1222 * application to the `Contents/Resources` subdirectory of the application's 1223 * bundle, if present. This can be disabled with a 1224 * [compile-time option](@ref compile_options_osx). 1225 * 1226 * @thread_safety This function must only be called from the main thread. 1227 * 1228 * @sa @ref intro_init 1229 * @sa glfwTerminate 1230 * 1231 * @since Added in version 1.0. 1232 * 1233 * @ingroup init 1234 */ 1235 GLFWAPI int glfwInit(void); 1236 1237 /*! @brief Terminates the GLFW library. 1238 * 1239 * This function destroys all remaining windows and cursors, restores any 1240 * modified gamma ramps and frees any other allocated resources. Once this 1241 * function is called, you must again call @ref glfwInit successfully before 1242 * you will be able to use most GLFW functions. 1243 * 1244 * If GLFW has been successfully initialized, this function should be called 1245 * before the application exits. If initialization fails, there is no need to 1246 * call this function, as it is called by @ref glfwInit before it returns 1247 * failure. 1248 * 1249 * @errors Possible errors include @ref GLFW_PLATFORM_ERROR. 1250 * 1251 * @remark This function may be called before @ref glfwInit. 1252 * 1253 * @warning The contexts of any remaining windows must not be current on any 1254 * other thread when this function is called. 1255 * 1256 * @reentrancy This function must not be called from a callback. 1257 * 1258 * @thread_safety This function must only be called from the main thread. 1259 * 1260 * @sa @ref intro_init 1261 * @sa glfwInit 1262 * 1263 * @since Added in version 1.0. 1264 * 1265 * @ingroup init 1266 */ 1267 GLFWAPI void glfwTerminate(void); 1268 1269 /*! @brief Retrieves the version of the GLFW library. 1270 * 1271 * This function retrieves the major, minor and revision numbers of the GLFW 1272 * library. It is intended for when you are using GLFW as a shared library and 1273 * want to ensure that you are using the minimum required version. 1274 * 1275 * Any or all of the version arguments may be `NULL`. 1276 * 1277 * @param[out] major Where to store the major version number, or `NULL`. 1278 * @param[out] minor Where to store the minor version number, or `NULL`. 1279 * @param[out] rev Where to store the revision number, or `NULL`. 1280 * 1281 * @errors None. 1282 * 1283 * @remark This function may be called before @ref glfwInit. 1284 * 1285 * @thread_safety This function may be called from any thread. 1286 * 1287 * @sa @ref intro_version 1288 * @sa glfwGetVersionString 1289 * 1290 * @since Added in version 1.0. 1291 * 1292 * @ingroup init 1293 */ 1294 GLFWAPI void glfwGetVersion(int* major, int* minor, int* rev); 1295 1296 /*! @brief Returns a string describing the compile-time configuration. 1297 * 1298 * This function returns the compile-time generated 1299 * [version string](@ref intro_version_string) of the GLFW library binary. It 1300 * describes the version, platform, compiler and any platform-specific 1301 * compile-time options. It should not be confused with the OpenGL or OpenGL 1302 * ES version string, queried with `glGetString`. 1303 * 1304 * __Do not use the version string__ to parse the GLFW library version. The 1305 * @ref glfwGetVersion function provides the version of the running library 1306 * binary in numerical format. 1307 * 1308 * @return The ASCII encoded GLFW version string. 1309 * 1310 * @errors None. 1311 * 1312 * @remark This function may be called before @ref glfwInit. 1313 * 1314 * @pointer_lifetime The returned string is static and compile-time generated. 1315 * 1316 * @thread_safety This function may be called from any thread. 1317 * 1318 * @sa @ref intro_version 1319 * @sa glfwGetVersion 1320 * 1321 * @since Added in version 3.0. 1322 * 1323 * @ingroup init 1324 */ 1325 GLFWAPI const char* glfwGetVersionString(void); 1326 1327 /*! @brief Sets the error callback. 1328 * 1329 * This function sets the error callback, which is called with an error code 1330 * and a human-readable description each time a GLFW error occurs. 1331 * 1332 * The error callback is called on the thread where the error occurred. If you 1333 * are using GLFW from multiple threads, your error callback needs to be 1334 * written accordingly. 1335 * 1336 * Because the description string may have been generated specifically for that 1337 * error, it is not guaranteed to be valid after the callback has returned. If 1338 * you wish to use it after the callback returns, you need to make a copy. 1339 * 1340 * Once set, the error callback remains set even after the library has been 1341 * terminated. 1342 * 1343 * @param[in] cbfun The new callback, or `NULL` to remove the currently set 1344 * callback. 1345 * @return The previously set callback, or `NULL` if no callback was set. 1346 * 1347 * @errors None. 1348 * 1349 * @remark This function may be called before @ref glfwInit. 1350 * 1351 * @thread_safety This function must only be called from the main thread. 1352 * 1353 * @sa @ref error_handling 1354 * 1355 * @since Added in version 3.0. 1356 * 1357 * @ingroup init 1358 */ 1359 GLFWAPI GLFWerrorfun glfwSetErrorCallback(GLFWerrorfun cbfun); 1360 1361 /*! @brief Returns the currently connected monitors. 1362 * 1363 * This function returns an array of handles for all currently connected 1364 * monitors. The primary monitor is always first in the returned array. If no 1365 * monitors were found, this function returns `NULL`. 1366 * 1367 * @param[out] count Where to store the number of monitors in the returned 1368 * array. This is set to zero if an error occurred. 1369 * @return An array of monitor handles, or `NULL` if no monitors were found or 1370 * if an [error](@ref error_handling) occurred. 1371 * 1372 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 1373 * 1374 * @pointer_lifetime The returned array is allocated and freed by GLFW. You 1375 * should not free it yourself. It is guaranteed to be valid only until the 1376 * monitor configuration changes or the library is terminated. 1377 * 1378 * @thread_safety This function must only be called from the main thread. 1379 * 1380 * @sa @ref monitor_monitors 1381 * @sa @ref monitor_event 1382 * @sa glfwGetPrimaryMonitor 1383 * 1384 * @since Added in version 3.0. 1385 * 1386 * @ingroup monitor 1387 */ 1388 GLFWAPI GLFWmonitor** glfwGetMonitors(int* count); 1389 1390 /*! @brief Returns the primary monitor. 1391 * 1392 * This function returns the primary monitor. This is usually the monitor 1393 * where elements like the task bar or global menu bar are located. 1394 * 1395 * @return The primary monitor, or `NULL` if no monitors were found or if an 1396 * [error](@ref error_handling) occurred. 1397 * 1398 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 1399 * 1400 * @thread_safety This function must only be called from the main thread. 1401 * 1402 * @remark The primary monitor is always first in the array returned by @ref 1403 * glfwGetMonitors. 1404 * 1405 * @sa @ref monitor_monitors 1406 * @sa glfwGetMonitors 1407 * 1408 * @since Added in version 3.0. 1409 * 1410 * @ingroup monitor 1411 */ 1412 GLFWAPI GLFWmonitor* glfwGetPrimaryMonitor(void); 1413 1414 /*! @brief Returns the position of the monitor's viewport on the virtual screen. 1415 * 1416 * This function returns the position, in screen coordinates, of the upper-left 1417 * corner of the specified monitor. 1418 * 1419 * Any or all of the position arguments may be `NULL`. If an error occurs, all 1420 * non-`NULL` position arguments will be set to zero. 1421 * 1422 * @param[in] monitor The monitor to query. 1423 * @param[out] xpos Where to store the monitor x-coordinate, or `NULL`. 1424 * @param[out] ypos Where to store the monitor y-coordinate, or `NULL`. 1425 * 1426 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 1427 * GLFW_PLATFORM_ERROR. 1428 * 1429 * @thread_safety This function must only be called from the main thread. 1430 * 1431 * @sa @ref monitor_properties 1432 * 1433 * @since Added in version 3.0. 1434 * 1435 * @ingroup monitor 1436 */ 1437 GLFWAPI void glfwGetMonitorPos(GLFWmonitor* monitor, int* xpos, int* ypos); 1438 1439 /*! @brief Returns the physical size of the monitor. 1440 * 1441 * This function returns the size, in millimetres, of the display area of the 1442 * specified monitor. 1443 * 1444 * Some systems do not provide accurate monitor size information, either 1445 * because the monitor 1446 * [EDID](https://en.wikipedia.org/wiki/Extended_display_identification_data) 1447 * data is incorrect or because the driver does not report it accurately. 1448 * 1449 * Any or all of the size arguments may be `NULL`. If an error occurs, all 1450 * non-`NULL` size arguments will be set to zero. 1451 * 1452 * @param[in] monitor The monitor to query. 1453 * @param[out] widthMM Where to store the width, in millimetres, of the 1454 * monitor's display area, or `NULL`. 1455 * @param[out] heightMM Where to store the height, in millimetres, of the 1456 * monitor's display area, or `NULL`. 1457 * 1458 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 1459 * 1460 * @remark @win32 calculates the returned physical size from the 1461 * current resolution and system DPI instead of querying the monitor EDID data. 1462 * 1463 * @thread_safety This function must only be called from the main thread. 1464 * 1465 * @sa @ref monitor_properties 1466 * 1467 * @since Added in version 3.0. 1468 * 1469 * @ingroup monitor 1470 */ 1471 GLFWAPI void glfwGetMonitorPhysicalSize(GLFWmonitor* monitor, int* widthMM, int* heightMM); 1472 1473 /*! @brief Returns the name of the specified monitor. 1474 * 1475 * This function returns a human-readable name, encoded as UTF-8, of the 1476 * specified monitor. The name typically reflects the make and model of the 1477 * monitor and is not guaranteed to be unique among the connected monitors. 1478 * 1479 * @param[in] monitor The monitor to query. 1480 * @return The UTF-8 encoded name of the monitor, or `NULL` if an 1481 * [error](@ref error_handling) occurred. 1482 * 1483 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 1484 * 1485 * @pointer_lifetime The returned string is allocated and freed by GLFW. You 1486 * should not free it yourself. It is valid until the specified monitor is 1487 * disconnected or the library is terminated. 1488 * 1489 * @thread_safety This function must only be called from the main thread. 1490 * 1491 * @sa @ref monitor_properties 1492 * 1493 * @since Added in version 3.0. 1494 * 1495 * @ingroup monitor 1496 */ 1497 GLFWAPI const char* glfwGetMonitorName(GLFWmonitor* monitor); 1498 1499 /*! @brief Sets the monitor configuration callback. 1500 * 1501 * This function sets the monitor configuration callback, or removes the 1502 * currently set callback. This is called when a monitor is connected to or 1503 * disconnected from the system. 1504 * 1505 * @param[in] cbfun The new callback, or `NULL` to remove the currently set 1506 * callback. 1507 * @return The previously set callback, or `NULL` if no callback was set or the 1508 * library had not been [initialized](@ref intro_init). 1509 * 1510 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 1511 * 1512 * @thread_safety This function must only be called from the main thread. 1513 * 1514 * @sa @ref monitor_event 1515 * 1516 * @since Added in version 3.0. 1517 * 1518 * @ingroup monitor 1519 */ 1520 GLFWAPI GLFWmonitorfun glfwSetMonitorCallback(GLFWmonitorfun cbfun); 1521 1522 /*! @brief Returns the available video modes for the specified monitor. 1523 * 1524 * This function returns an array of all video modes supported by the specified 1525 * monitor. The returned array is sorted in ascending order, first by color 1526 * bit depth (the sum of all channel depths) and then by resolution area (the 1527 * product of width and height). 1528 * 1529 * @param[in] monitor The monitor to query. 1530 * @param[out] count Where to store the number of video modes in the returned 1531 * array. This is set to zero if an error occurred. 1532 * @return An array of video modes, or `NULL` if an 1533 * [error](@ref error_handling) occurred. 1534 * 1535 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 1536 * GLFW_PLATFORM_ERROR. 1537 * 1538 * @pointer_lifetime The returned array is allocated and freed by GLFW. You 1539 * should not free it yourself. It is valid until the specified monitor is 1540 * disconnected, this function is called again for that monitor or the library 1541 * is terminated. 1542 * 1543 * @thread_safety This function must only be called from the main thread. 1544 * 1545 * @sa @ref monitor_modes 1546 * @sa glfwGetVideoMode 1547 * 1548 * @since Added in version 1.0. 1549 * @glfw3 Changed to return an array of modes for a specific monitor. 1550 * 1551 * @ingroup monitor 1552 */ 1553 GLFWAPI const GLFWvidmode* glfwGetVideoModes(GLFWmonitor* monitor, int* count); 1554 1555 /*! @brief Returns the current mode of the specified monitor. 1556 * 1557 * This function returns the current video mode of the specified monitor. If 1558 * you have created a full screen window for that monitor, the return value 1559 * will depend on whether that window is iconified. 1560 * 1561 * @param[in] monitor The monitor to query. 1562 * @return The current mode of the monitor, or `NULL` if an 1563 * [error](@ref error_handling) occurred. 1564 * 1565 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 1566 * GLFW_PLATFORM_ERROR. 1567 * 1568 * @pointer_lifetime The returned array is allocated and freed by GLFW. You 1569 * should not free it yourself. It is valid until the specified monitor is 1570 * disconnected or the library is terminated. 1571 * 1572 * @thread_safety This function must only be called from the main thread. 1573 * 1574 * @sa @ref monitor_modes 1575 * @sa glfwGetVideoModes 1576 * 1577 * @since Added in version 3.0. Replaces `glfwGetDesktopMode`. 1578 * 1579 * @ingroup monitor 1580 */ 1581 GLFWAPI const GLFWvidmode* glfwGetVideoMode(GLFWmonitor* monitor); 1582 1583 /*! @brief Generates a gamma ramp and sets it for the specified monitor. 1584 * 1585 * This function generates a 256-element gamma ramp from the specified exponent 1586 * and then calls @ref glfwSetGammaRamp with it. The value must be a finite 1587 * number greater than zero. 1588 * 1589 * @param[in] monitor The monitor whose gamma ramp to set. 1590 * @param[in] gamma The desired exponent. 1591 * 1592 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref 1593 * GLFW_INVALID_VALUE and @ref GLFW_PLATFORM_ERROR. 1594 * 1595 * @thread_safety This function must only be called from the main thread. 1596 * 1597 * @sa @ref monitor_gamma 1598 * 1599 * @since Added in version 3.0. 1600 * 1601 * @ingroup monitor 1602 */ 1603 GLFWAPI void glfwSetGamma(GLFWmonitor* monitor, float gamma); 1604 1605 /*! @brief Returns the current gamma ramp for the specified monitor. 1606 * 1607 * This function returns the current gamma ramp of the specified monitor. 1608 * 1609 * @param[in] monitor The monitor to query. 1610 * @return The current gamma ramp, or `NULL` if an 1611 * [error](@ref error_handling) occurred. 1612 * 1613 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 1614 * GLFW_PLATFORM_ERROR. 1615 * 1616 * @pointer_lifetime The returned structure and its arrays are allocated and 1617 * freed by GLFW. You should not free them yourself. They are valid until the 1618 * specified monitor is disconnected, this function is called again for that 1619 * monitor or the library is terminated. 1620 * 1621 * @thread_safety This function must only be called from the main thread. 1622 * 1623 * @sa @ref monitor_gamma 1624 * 1625 * @since Added in version 3.0. 1626 * 1627 * @ingroup monitor 1628 */ 1629 GLFWAPI const GLFWgammaramp* glfwGetGammaRamp(GLFWmonitor* monitor); 1630 1631 /*! @brief Sets the current gamma ramp for the specified monitor. 1632 * 1633 * This function sets the current gamma ramp for the specified monitor. The 1634 * original gamma ramp for that monitor is saved by GLFW the first time this 1635 * function is called and is restored by @ref glfwTerminate. 1636 * 1637 * @param[in] monitor The monitor whose gamma ramp to set. 1638 * @param[in] ramp The gamma ramp to use. 1639 * 1640 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 1641 * GLFW_PLATFORM_ERROR. 1642 * 1643 * @remark Gamma ramp sizes other than 256 are not supported by all platforms 1644 * or graphics hardware. 1645 * 1646 * @remark @win32 The gamma ramp size must be 256. 1647 * 1648 * @pointer_lifetime The specified gamma ramp is copied before this function 1649 * returns. 1650 * 1651 * @thread_safety This function must only be called from the main thread. 1652 * 1653 * @sa @ref monitor_gamma 1654 * 1655 * @since Added in version 3.0. 1656 * 1657 * @ingroup monitor 1658 */ 1659 GLFWAPI void glfwSetGammaRamp(GLFWmonitor* monitor, const GLFWgammaramp* ramp); 1660 1661 /*! @brief Resets all window hints to their default values. 1662 * 1663 * This function resets all window hints to their 1664 * [default values](@ref window_hints_values). 1665 * 1666 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 1667 * 1668 * @thread_safety This function must only be called from the main thread. 1669 * 1670 * @sa @ref window_hints 1671 * @sa glfwWindowHint 1672 * 1673 * @since Added in version 3.0. 1674 * 1675 * @ingroup window 1676 */ 1677 GLFWAPI void glfwDefaultWindowHints(void); 1678 1679 /*! @brief Sets the specified window hint to the desired value. 1680 * 1681 * This function sets hints for the next call to @ref glfwCreateWindow. The 1682 * hints, once set, retain their values until changed by a call to @ref 1683 * glfwWindowHint or @ref glfwDefaultWindowHints, or until the library is 1684 * terminated. 1685 * 1686 * This function does not check whether the specified hint values are valid. 1687 * If you set hints to invalid values this will instead be reported by the next 1688 * call to @ref glfwCreateWindow. 1689 * 1690 * @param[in] hint The [window hint](@ref window_hints) to set. 1691 * @param[in] value The new value of the window hint. 1692 * 1693 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 1694 * GLFW_INVALID_ENUM. 1695 * 1696 * @thread_safety This function must only be called from the main thread. 1697 * 1698 * @sa @ref window_hints 1699 * @sa glfwDefaultWindowHints 1700 * 1701 * @since Added in version 3.0. Replaces `glfwOpenWindowHint`. 1702 * 1703 * @ingroup window 1704 */ 1705 GLFWAPI void glfwWindowHint(int hint, int value); 1706 1707 /*! @brief Creates a window and its associated context. 1708 * 1709 * This function creates a window and its associated OpenGL or OpenGL ES 1710 * context. Most of the options controlling how the window and its context 1711 * should be created are specified with [window hints](@ref window_hints). 1712 * 1713 * Successful creation does not change which context is current. Before you 1714 * can use the newly created context, you need to 1715 * [make it current](@ref context_current). For information about the `share` 1716 * parameter, see @ref context_sharing. 1717 * 1718 * The created window, framebuffer and context may differ from what you 1719 * requested, as not all parameters and hints are 1720 * [hard constraints](@ref window_hints_hard). This includes the size of the 1721 * window, especially for full screen windows. To query the actual attributes 1722 * of the created window, framebuffer and context, see @ref 1723 * glfwGetWindowAttrib, @ref glfwGetWindowSize and @ref glfwGetFramebufferSize. 1724 * 1725 * To create a full screen window, you need to specify the monitor the window 1726 * will cover. If no monitor is specified, the window will be windowed mode. 1727 * Unless you have a way for the user to choose a specific monitor, it is 1728 * recommended that you pick the primary monitor. For more information on how 1729 * to query connected monitors, see @ref monitor_monitors. 1730 * 1731 * For full screen windows, the specified size becomes the resolution of the 1732 * window's _desired video mode_. As long as a full screen window is not 1733 * iconified, the supported video mode most closely matching the desired video 1734 * mode is set for the specified monitor. For more information about full 1735 * screen windows, including the creation of so called _windowed full screen_ 1736 * or _borderless full screen_ windows, see @ref window_windowed_full_screen. 1737 * 1738 * By default, newly created windows use the placement recommended by the 1739 * window system. To create the window at a specific position, make it 1740 * initially invisible using the [GLFW_VISIBLE](@ref window_hints_wnd) window 1741 * hint, set its [position](@ref window_pos) and then [show](@ref window_hide) 1742 * it. 1743 * 1744 * As long as at least one full screen window is not iconified, the screensaver 1745 * is prohibited from starting. 1746 * 1747 * Window systems put limits on window sizes. Very large or very small window 1748 * dimensions may be overridden by the window system on creation. Check the 1749 * actual [size](@ref window_size) after creation. 1750 * 1751 * The [swap interval](@ref buffer_swap) is not set during window creation and 1752 * the initial value may vary depending on driver settings and defaults. 1753 * 1754 * @param[in] width The desired width, in screen coordinates, of the window. 1755 * This must be greater than zero. 1756 * @param[in] height The desired height, in screen coordinates, of the window. 1757 * This must be greater than zero. 1758 * @param[in] title The initial, UTF-8 encoded window title. 1759 * @param[in] monitor The monitor to use for full screen mode, or `NULL` for 1760 * windowed mode. 1761 * @param[in] share The window whose context to share resources with, or `NULL` 1762 * to not share resources. 1763 * @return The handle of the created window, or `NULL` if an 1764 * [error](@ref error_handling) occurred. 1765 * 1766 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref 1767 * GLFW_INVALID_ENUM, @ref GLFW_INVALID_VALUE, @ref GLFW_API_UNAVAILABLE, @ref 1768 * GLFW_VERSION_UNAVAILABLE, @ref GLFW_FORMAT_UNAVAILABLE and @ref 1769 * GLFW_PLATFORM_ERROR. 1770 * 1771 * @remark @win32 Window creation will fail if the Microsoft GDI software 1772 * OpenGL implementation is the only one available. 1773 * 1774 * @remark @win32 If the executable has an icon resource named `GLFW_ICON,` 1775 * it will be set as the icon for the window. If no such icon is present, the 1776 * `IDI_WINLOGO` icon will be used instead. 1777 * 1778 * @remark @win32 The context to share resources with must not be current on 1779 * any other thread. 1780 * 1781 * @remark @osx The GLFW window has no icon, as it is not a document 1782 * window, but the dock icon will be the same as the application bundle's icon. 1783 * For more information on bundles, see the 1784 * [Bundle Programming Guide](https://developer.apple.com/library/mac/documentation/CoreFoundation/Conceptual/CFBundles/) 1785 * in the Mac Developer Library. 1786 * 1787 * @remark @osx The first time a window is created the menu bar is populated 1788 * with common commands like Hide, Quit and About. The About entry opens 1789 * a minimal about dialog with information from the application's bundle. The 1790 * menu bar can be disabled with a 1791 * [compile-time option](@ref compile_options_osx). 1792 * 1793 * @remark @osx On OS X 10.10 and later the window frame will not be rendered 1794 * at full resolution on Retina displays unless the `NSHighResolutionCapable` 1795 * key is enabled in the application bundle's `Info.plist`. For more 1796 * information, see 1797 * [High Resolution Guidelines for OS X](https://developer.apple.com/library/mac/documentation/GraphicsAnimation/Conceptual/HighResolutionOSX/Explained/Explained.html) 1798 * in the Mac Developer Library. The GLFW test and example programs use 1799 * a custom `Info.plist` template for this, which can be found as 1800 * `CMake/MacOSXBundleInfo.plist.in` in the source tree. 1801 * 1802 * @remark @x11 There is no mechanism for setting the window icon yet. 1803 * 1804 * @remark @x11 Some window managers will not respect the placement of 1805 * initially hidden windows. 1806 * 1807 * @remark @x11 Due to the asynchronous nature of X11, it may take a moment for 1808 * a window to reach its requested state. This means you may not be able to 1809 * query the final size, position or other attributes directly after window 1810 * creation. 1811 * 1812 * @reentrancy This function must not be called from a callback. 1813 * 1814 * @thread_safety This function must only be called from the main thread. 1815 * 1816 * @sa @ref window_creation 1817 * @sa glfwDestroyWindow 1818 * 1819 * @since Added in version 3.0. Replaces `glfwOpenWindow`. 1820 * 1821 * @ingroup window 1822 */ 1823 GLFWAPI GLFWwindow* glfwCreateWindow(int width, int height, const char* title, GLFWmonitor* monitor, GLFWwindow* share); 1824 1825 /*! @brief Destroys the specified window and its context. 1826 * 1827 * This function destroys the specified window and its context. On calling 1828 * this function, no further callbacks will be called for that window. 1829 * 1830 * If the context of the specified window is current on the main thread, it is 1831 * detached before being destroyed. 1832 * 1833 * @param[in] window The window to destroy. 1834 * 1835 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 1836 * GLFW_PLATFORM_ERROR. 1837 * 1838 * @note The context of the specified window must not be current on any other 1839 * thread when this function is called. 1840 * 1841 * @reentrancy This function must not be called from a callback. 1842 * 1843 * @thread_safety This function must only be called from the main thread. 1844 * 1845 * @sa @ref window_creation 1846 * @sa glfwCreateWindow 1847 * 1848 * @since Added in version 3.0. Replaces `glfwCloseWindow`. 1849 * 1850 * @ingroup window 1851 */ 1852 GLFWAPI void glfwDestroyWindow(GLFWwindow* window); 1853 1854 /*! @brief Checks the close flag of the specified window. 1855 * 1856 * This function returns the value of the close flag of the specified window. 1857 * 1858 * @param[in] window The window to query. 1859 * @return The value of the close flag. 1860 * 1861 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 1862 * 1863 * @thread_safety This function may be called from any thread. Access is not 1864 * synchronized. 1865 * 1866 * @sa @ref window_close 1867 * 1868 * @since Added in version 3.0. 1869 * 1870 * @ingroup window 1871 */ 1872 GLFWAPI int glfwWindowShouldClose(GLFWwindow* window); 1873 1874 /*! @brief Sets the close flag of the specified window. 1875 * 1876 * This function sets the value of the close flag of the specified window. 1877 * This can be used to override the user's attempt to close the window, or 1878 * to signal that it should be closed. 1879 * 1880 * @param[in] window The window whose flag to change. 1881 * @param[in] value The new value. 1882 * 1883 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 1884 * 1885 * @thread_safety This function may be called from any thread. Access is not 1886 * synchronized. 1887 * 1888 * @sa @ref window_close 1889 * 1890 * @since Added in version 3.0. 1891 * 1892 * @ingroup window 1893 */ 1894 GLFWAPI void glfwSetWindowShouldClose(GLFWwindow* window, int value); 1895 1896 /*! @brief Sets the title of the specified window. 1897 * 1898 * This function sets the window title, encoded as UTF-8, of the specified 1899 * window. 1900 * 1901 * @param[in] window The window whose title to change. 1902 * @param[in] title The UTF-8 encoded window title. 1903 * 1904 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 1905 * GLFW_PLATFORM_ERROR. 1906 * 1907 * @remark @osx The window title will not be updated until the next time you 1908 * process events. 1909 * 1910 * @thread_safety This function must only be called from the main thread. 1911 * 1912 * @sa @ref window_title 1913 * 1914 * @since Added in version 1.0. 1915 * @glfw3 Added window handle parameter. 1916 * 1917 * @ingroup window 1918 */ 1919 GLFWAPI void glfwSetWindowTitle(GLFWwindow* window, const char* title); 1920 1921 /*! @brief Sets the icon for the specified window. 1922 * 1923 * This function sets the icon of the specified window. If passed an array of 1924 * candidate images, those of or closest to the sizes desired by the system are 1925 * selected. If no images are specified, the window reverts to its default 1926 * icon. 1927 * 1928 * The desired image sizes varies depending on platform and system settings. 1929 * The selected images will be rescaled as needed. Good sizes include 16x16, 1930 * 32x32 and 48x48. 1931 * 1932 * @param[in] window The window whose icon to set. 1933 * @param[in] count The number of images in the specified array, or zero to 1934 * revert to the default window icon. 1935 * @param[in] images The images to create the icon from. This is ignored if 1936 * count is zero. 1937 * 1938 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 1939 * GLFW_PLATFORM_ERROR. 1940 * 1941 * @pointer_lifetime The specified image data is copied before this function 1942 * returns. 1943 * 1944 * @remark @osx The GLFW window has no icon, as it is not a document 1945 * window, but the dock icon will be the same as the application bundle's icon. 1946 * For more information on bundles, see the 1947 * [Bundle Programming Guide](https://developer.apple.com/library/mac/documentation/CoreFoundation/Conceptual/CFBundles/) 1948 * in the Mac Developer Library. 1949 * 1950 * @thread_safety This function must only be called from the main thread. 1951 * 1952 * @sa @ref window_icon 1953 * 1954 * @since Added in version 3.2. 1955 * 1956 * @ingroup window 1957 */ 1958 GLFWAPI void glfwSetWindowIcon(GLFWwindow* window, int count, const GLFWimage* images); 1959 1960 /*! @brief Retrieves the position of the client area of the specified window. 1961 * 1962 * This function retrieves the position, in screen coordinates, of the 1963 * upper-left corner of the client area of the specified window. 1964 * 1965 * Any or all of the position arguments may be `NULL`. If an error occurs, all 1966 * non-`NULL` position arguments will be set to zero. 1967 * 1968 * @param[in] window The window to query. 1969 * @param[out] xpos Where to store the x-coordinate of the upper-left corner of 1970 * the client area, or `NULL`. 1971 * @param[out] ypos Where to store the y-coordinate of the upper-left corner of 1972 * the client area, or `NULL`. 1973 * 1974 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 1975 * GLFW_PLATFORM_ERROR. 1976 * 1977 * @thread_safety This function must only be called from the main thread. 1978 * 1979 * @sa @ref window_pos 1980 * @sa glfwSetWindowPos 1981 * 1982 * @since Added in version 3.0. 1983 * 1984 * @ingroup window 1985 */ 1986 GLFWAPI void glfwGetWindowPos(GLFWwindow* window, int* xpos, int* ypos); 1987 1988 /*! @brief Sets the position of the client area of the specified window. 1989 * 1990 * This function sets the position, in screen coordinates, of the upper-left 1991 * corner of the client area of the specified windowed mode window. If the 1992 * window is a full screen window, this function does nothing. 1993 * 1994 * __Do not use this function__ to move an already visible window unless you 1995 * have very good reasons for doing so, as it will confuse and annoy the user. 1996 * 1997 * The window manager may put limits on what positions are allowed. GLFW 1998 * cannot and should not override these limits. 1999 * 2000 * @param[in] window The window to query. 2001 * @param[in] xpos The x-coordinate of the upper-left corner of the client area. 2002 * @param[in] ypos The y-coordinate of the upper-left corner of the client area. 2003 * 2004 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 2005 * GLFW_PLATFORM_ERROR. 2006 * 2007 * @thread_safety This function must only be called from the main thread. 2008 * 2009 * @sa @ref window_pos 2010 * @sa glfwGetWindowPos 2011 * 2012 * @since Added in version 1.0. 2013 * @glfw3 Added window handle parameter. 2014 * 2015 * @ingroup window 2016 */ 2017 GLFWAPI void glfwSetWindowPos(GLFWwindow* window, int xpos, int ypos); 2018 2019 /*! @brief Retrieves the size of the client area of the specified window. 2020 * 2021 * This function retrieves the size, in screen coordinates, of the client area 2022 * of the specified window. If you wish to retrieve the size of the 2023 * framebuffer of the window in pixels, see @ref glfwGetFramebufferSize. 2024 * 2025 * Any or all of the size arguments may be `NULL`. If an error occurs, all 2026 * non-`NULL` size arguments will be set to zero. 2027 * 2028 * @param[in] window The window whose size to retrieve. 2029 * @param[out] width Where to store the width, in screen coordinates, of the 2030 * client area, or `NULL`. 2031 * @param[out] height Where to store the height, in screen coordinates, of the 2032 * client area, or `NULL`. 2033 * 2034 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 2035 * GLFW_PLATFORM_ERROR. 2036 * 2037 * @thread_safety This function must only be called from the main thread. 2038 * 2039 * @sa @ref window_size 2040 * @sa glfwSetWindowSize 2041 * 2042 * @since Added in version 1.0. 2043 * @glfw3 Added window handle parameter. 2044 * 2045 * @ingroup window 2046 */ 2047 GLFWAPI void glfwGetWindowSize(GLFWwindow* window, int* width, int* height); 2048 2049 /*! @brief Sets the size limits of the specified window. 2050 * 2051 * This function sets the size limits of the client area of the specified 2052 * window. If the window is full screen, the size limits only take effect if 2053 * once it is made windowed. If the window is not resizable, this function 2054 * does nothing. 2055 * 2056 * The size limits are applied immediately to a windowed mode window and may 2057 * cause it to be resized. 2058 * 2059 * @param[in] window The window to set limits for. 2060 * @param[in] minwidth The minimum width, in screen coordinates, of the client 2061 * area, or `GLFW_DONT_CARE`. 2062 * @param[in] minheight The minimum height, in screen coordinates, of the 2063 * client area, or `GLFW_DONT_CARE`. 2064 * @param[in] maxwidth The maximum width, in screen coordinates, of the client 2065 * area, or `GLFW_DONT_CARE`. 2066 * @param[in] maxheight The maximum height, in screen coordinates, of the 2067 * client area, or `GLFW_DONT_CARE`. 2068 * 2069 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 2070 * GLFW_PLATFORM_ERROR. 2071 * 2072 * @remark If you set size limits and an aspect ratio that conflict, the 2073 * results are undefined. 2074 * 2075 * @thread_safety This function must only be called from the main thread. 2076 * 2077 * @sa @ref window_sizelimits 2078 * @sa glfwSetWindowAspectRatio 2079 * 2080 * @since Added in version 3.2. 2081 * 2082 * @ingroup window 2083 */ 2084 GLFWAPI void glfwSetWindowSizeLimits(GLFWwindow* window, int minwidth, int minheight, int maxwidth, int maxheight); 2085 2086 /*! @brief Sets the aspect ratio of the specified window. 2087 * 2088 * This function sets the required aspect ratio of the client area of the 2089 * specified window. If the window is full screen, the aspect ratio only takes 2090 * effect once it is made windowed. If the window is not resizable, this 2091 * function does nothing. 2092 * 2093 * The aspect ratio is specified as a numerator and a denominator and both 2094 * values must be greater than zero. For example, the common 16:9 aspect ratio 2095 * is specified as 16 and 9, respectively. 2096 * 2097 * If the numerator and denominator is set to `GLFW_DONT_CARE` then the aspect 2098 * ratio limit is disabled. 2099 * 2100 * The aspect ratio is applied immediately to a windowed mode window and may 2101 * cause it to be resized. 2102 * 2103 * @param[in] window The window to set limits for. 2104 * @param[in] numer The numerator of the desired aspect ratio, or 2105 * `GLFW_DONT_CARE`. 2106 * @param[in] denom The denominator of the desired aspect ratio, or 2107 * `GLFW_DONT_CARE`. 2108 * 2109 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref 2110 * GLFW_INVALID_VALUE and @ref GLFW_PLATFORM_ERROR. 2111 * 2112 * @remark If you set size limits and an aspect ratio that conflict, the 2113 * results are undefined. 2114 * 2115 * @thread_safety This function must only be called from the main thread. 2116 * 2117 * @sa @ref window_sizelimits 2118 * @sa glfwSetWindowSizeLimits 2119 * 2120 * @since Added in version 3.2. 2121 * 2122 * @ingroup window 2123 */ 2124 GLFWAPI void glfwSetWindowAspectRatio(GLFWwindow* window, int numer, int denom); 2125 2126 /*! @brief Sets the size of the client area of the specified window. 2127 * 2128 * This function sets the size, in screen coordinates, of the client area of 2129 * the specified window. 2130 * 2131 * For full screen windows, this function updates the resolution of its desired 2132 * video mode and switches to the video mode closest to it, without affecting 2133 * the window's context. As the context is unaffected, the bit depths of the 2134 * framebuffer remain unchanged. 2135 * 2136 * If you wish to update the refresh rate of the desired video mode in addition 2137 * to its resolution, see @ref glfwSetWindowMonitor. 2138 * 2139 * The window manager may put limits on what sizes are allowed. GLFW cannot 2140 * and should not override these limits. 2141 * 2142 * @param[in] window The window to resize. 2143 * @param[in] width The desired width, in screen coordinates, of the window 2144 * client area. 2145 * @param[in] height The desired height, in screen coordinates, of the window 2146 * client area. 2147 * 2148 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 2149 * GLFW_PLATFORM_ERROR. 2150 * 2151 * @thread_safety This function must only be called from the main thread. 2152 * 2153 * @sa @ref window_size 2154 * @sa glfwGetWindowSize 2155 * @sa glfwSetWindowMonitor 2156 * 2157 * @since Added in version 1.0. 2158 * @glfw3 Added window handle parameter. 2159 * 2160 * @ingroup window 2161 */ 2162 GLFWAPI void glfwSetWindowSize(GLFWwindow* window, int width, int height); 2163 2164 /*! @brief Retrieves the size of the framebuffer of the specified window. 2165 * 2166 * This function retrieves the size, in pixels, of the framebuffer of the 2167 * specified window. If you wish to retrieve the size of the window in screen 2168 * coordinates, see @ref glfwGetWindowSize. 2169 * 2170 * Any or all of the size arguments may be `NULL`. If an error occurs, all 2171 * non-`NULL` size arguments will be set to zero. 2172 * 2173 * @param[in] window The window whose framebuffer to query. 2174 * @param[out] width Where to store the width, in pixels, of the framebuffer, 2175 * or `NULL`. 2176 * @param[out] height Where to store the height, in pixels, of the framebuffer, 2177 * or `NULL`. 2178 * 2179 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 2180 * GLFW_PLATFORM_ERROR. 2181 * 2182 * @thread_safety This function must only be called from the main thread. 2183 * 2184 * @sa @ref window_fbsize 2185 * @sa glfwSetFramebufferSizeCallback 2186 * 2187 * @since Added in version 3.0. 2188 * 2189 * @ingroup window 2190 */ 2191 GLFWAPI void glfwGetFramebufferSize(GLFWwindow* window, int* width, int* height); 2192 2193 /*! @brief Retrieves the size of the frame of the window. 2194 * 2195 * This function retrieves the size, in screen coordinates, of each edge of the 2196 * frame of the specified window. This size includes the title bar, if the 2197 * window has one. The size of the frame may vary depending on the 2198 * [window-related hints](@ref window_hints_wnd) used to create it. 2199 * 2200 * Because this function retrieves the size of each window frame edge and not 2201 * the offset along a particular coordinate axis, the retrieved values will 2202 * always be zero or positive. 2203 * 2204 * Any or all of the size arguments may be `NULL`. If an error occurs, all 2205 * non-`NULL` size arguments will be set to zero. 2206 * 2207 * @param[in] window The window whose frame size to query. 2208 * @param[out] left Where to store the size, in screen coordinates, of the left 2209 * edge of the window frame, or `NULL`. 2210 * @param[out] top Where to store the size, in screen coordinates, of the top 2211 * edge of the window frame, or `NULL`. 2212 * @param[out] right Where to store the size, in screen coordinates, of the 2213 * right edge of the window frame, or `NULL`. 2214 * @param[out] bottom Where to store the size, in screen coordinates, of the 2215 * bottom edge of the window frame, or `NULL`. 2216 * 2217 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 2218 * GLFW_PLATFORM_ERROR. 2219 * 2220 * @thread_safety This function must only be called from the main thread. 2221 * 2222 * @sa @ref window_size 2223 * 2224 * @since Added in version 3.1. 2225 * 2226 * @ingroup window 2227 */ 2228 GLFWAPI void glfwGetWindowFrameSize(GLFWwindow* window, int* left, int* top, int* right, int* bottom); 2229 2230 /*! @brief Iconifies the specified window. 2231 * 2232 * This function iconifies (minimizes) the specified window if it was 2233 * previously restored. If the window is already iconified, this function does 2234 * nothing. 2235 * 2236 * If the specified window is a full screen window, the original monitor 2237 * resolution is restored until the window is restored. 2238 * 2239 * @param[in] window The window to iconify. 2240 * 2241 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 2242 * GLFW_PLATFORM_ERROR. 2243 * 2244 * @thread_safety This function must only be called from the main thread. 2245 * 2246 * @sa @ref window_iconify 2247 * @sa glfwRestoreWindow 2248 * @sa glfwMaximizeWindow 2249 * 2250 * @since Added in version 2.1. 2251 * @glfw3 Added window handle parameter. 2252 * 2253 * @ingroup window 2254 */ 2255 GLFWAPI void glfwIconifyWindow(GLFWwindow* window); 2256 2257 /*! @brief Restores the specified window. 2258 * 2259 * This function restores the specified window if it was previously iconified 2260 * (minimized) or maximized. If the window is already restored, this function 2261 * does nothing. 2262 * 2263 * If the specified window is a full screen window, the resolution chosen for 2264 * the window is restored on the selected monitor. 2265 * 2266 * @param[in] window The window to restore. 2267 * 2268 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 2269 * GLFW_PLATFORM_ERROR. 2270 * 2271 * @thread_safety This function must only be called from the main thread. 2272 * 2273 * @sa @ref window_iconify 2274 * @sa glfwIconifyWindow 2275 * @sa glfwMaximizeWindow 2276 * 2277 * @since Added in version 2.1. 2278 * @glfw3 Added window handle parameter. 2279 * 2280 * @ingroup window 2281 */ 2282 GLFWAPI void glfwRestoreWindow(GLFWwindow* window); 2283 2284 /*! @brief Maximizes the specified window. 2285 * 2286 * This function maximizes the specified window if it was previously not 2287 * maximized. If the window is already maximized, this function does nothing. 2288 * 2289 * If the specified window is a full screen window, this function does nothing. 2290 * 2291 * @param[in] window The window to maximize. 2292 * 2293 * @par Thread Safety 2294 * This function may only be called from the main thread. 2295 * 2296 * @sa @ref window_iconify 2297 * @sa glfwIconifyWindow 2298 * @sa glfwRestoreWindow 2299 * 2300 * @since Added in GLFW 3.2. 2301 * 2302 * @ingroup window 2303 */ 2304 GLFWAPI void glfwMaximizeWindow(GLFWwindow* window); 2305 2306 /*! @brief Makes the specified window visible. 2307 * 2308 * This function makes the specified window visible if it was previously 2309 * hidden. If the window is already visible or is in full screen mode, this 2310 * function does nothing. 2311 * 2312 * @param[in] window The window to make visible. 2313 * 2314 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 2315 * GLFW_PLATFORM_ERROR. 2316 * 2317 * @thread_safety This function must only be called from the main thread. 2318 * 2319 * @sa @ref window_hide 2320 * @sa glfwHideWindow 2321 * 2322 * @since Added in version 3.0. 2323 * 2324 * @ingroup window 2325 */ 2326 GLFWAPI void glfwShowWindow(GLFWwindow* window); 2327 2328 /*! @brief Hides the specified window. 2329 * 2330 * This function hides the specified window if it was previously visible. If 2331 * the window is already hidden or is in full screen mode, this function does 2332 * nothing. 2333 * 2334 * @param[in] window The window to hide. 2335 * 2336 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 2337 * GLFW_PLATFORM_ERROR. 2338 * 2339 * @thread_safety This function must only be called from the main thread. 2340 * 2341 * @sa @ref window_hide 2342 * @sa glfwShowWindow 2343 * 2344 * @since Added in version 3.0. 2345 * 2346 * @ingroup window 2347 */ 2348 GLFWAPI void glfwHideWindow(GLFWwindow* window); 2349 2350 /*! @brief Brings the specified window to front and sets input focus. 2351 * 2352 * This function brings the specified window to front and sets input focus. 2353 * The window should already be visible and not iconified. 2354 * 2355 * By default, both windowed and full screen mode windows are focused when 2356 * initially created. Set the [GLFW_FOCUSED](@ref window_hints_wnd) to disable 2357 * this behavior. 2358 * 2359 * __Do not use this function__ to steal focus from other applications unless 2360 * you are certain that is what the user wants. Focus stealing can be 2361 * extremely disruptive. 2362 * 2363 * @param[in] window The window to give input focus. 2364 * 2365 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 2366 * GLFW_PLATFORM_ERROR. 2367 * 2368 * @thread_safety This function must only be called from the main thread. 2369 * 2370 * @sa @ref window_focus 2371 * 2372 * @since Added in version 3.2. 2373 * 2374 * @ingroup window 2375 */ 2376 GLFWAPI void glfwFocusWindow(GLFWwindow* window); 2377 2378 /*! @brief Returns the monitor that the window uses for full screen mode. 2379 * 2380 * This function returns the handle of the monitor that the specified window is 2381 * in full screen on. 2382 * 2383 * @param[in] window The window to query. 2384 * @return The monitor, or `NULL` if the window is in windowed mode or an error 2385 * occurred. 2386 * 2387 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 2388 * 2389 * @thread_safety This function must only be called from the main thread. 2390 * 2391 * @sa @ref window_monitor 2392 * @sa glfwSetWindowMonitor 2393 * 2394 * @since Added in version 3.0. 2395 * 2396 * @ingroup window 2397 */ 2398 GLFWAPI GLFWmonitor* glfwGetWindowMonitor(GLFWwindow* window); 2399 2400 /*! @brief Sets the mode, monitor, video mode and placement of a window. 2401 * 2402 * This function sets the monitor that the window uses for full screen mode or, 2403 * if the monitor is `NULL`, makes it windowed mode. 2404 * 2405 * When setting a monitor, this function updates the width, height and refresh 2406 * rate of the desired video mode and switches to the video mode closest to it. 2407 * The window position is ignored when setting a monitor. 2408 * 2409 * When the monitor is `NULL`, the position, width and height are used to 2410 * place the window client area. The refresh rate is ignored when no monitor 2411 * is specified. 2412 * 2413 * If you only wish to update the resolution of a full screen window or the 2414 * size of a windowed mode window, see @ref glfwSetWindowSize. 2415 * 2416 * When a window transitions from full screen to windowed mode, this function 2417 * restores any previous window settings such as whether it is decorated, 2418 * floating, resizable, has size or aspect ratio limits, etc.. 2419 * 2420 * @param[in] window The window whose monitor, size or video mode to set. 2421 * @param[in] monitor The desired monitor, or `NULL` to set windowed mode. 2422 * @param[in] xpos The desired x-coordinate of the upper-left corner of the 2423 * client area. 2424 * @param[in] ypos The desired y-coordinate of the upper-left corner of the 2425 * client area. 2426 * @param[in] width The desired with, in screen coordinates, of the client area 2427 * or video mode. 2428 * @param[in] height The desired height, in screen coordinates, of the client 2429 * area or video mode. 2430 * @param[in] refreshRate The desired refresh rate, in Hz, of the video mode. 2431 * 2432 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 2433 * GLFW_PLATFORM_ERROR. 2434 * 2435 * @thread_safety This function must only be called from the main thread. 2436 * 2437 * @sa @ref window_monitor 2438 * @sa @ref window_full_screen 2439 * @sa glfwGetWindowMonitor 2440 * @sa glfwSetWindowSize 2441 * 2442 * @since Added in version 3.2. 2443 * 2444 * @ingroup window 2445 */ 2446 GLFWAPI void glfwSetWindowMonitor(GLFWwindow* window, GLFWmonitor* monitor, int xpos, int ypos, int width, int height, int refreshRate); 2447 2448 /*! @brief Returns an attribute of the specified window. 2449 * 2450 * This function returns the value of an attribute of the specified window or 2451 * its OpenGL or OpenGL ES context. 2452 * 2453 * @param[in] window The window to query. 2454 * @param[in] attrib The [window attribute](@ref window_attribs) whose value to 2455 * return. 2456 * @return The value of the attribute, or zero if an 2457 * [error](@ref error_handling) occurred. 2458 * 2459 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref 2460 * GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR. 2461 * 2462 * @remark Framebuffer related hints are not window attributes. See @ref 2463 * window_attribs_fb for more information. 2464 * 2465 * @remark Zero is a valid value for many window and context related 2466 * attributes so you cannot use a return value of zero as an indication of 2467 * errors. However, this function should not fail as long as it is passed 2468 * valid arguments and the library has been [initialized](@ref intro_init). 2469 * 2470 * @thread_safety This function must only be called from the main thread. 2471 * 2472 * @sa @ref window_attribs 2473 * 2474 * @since Added in version 3.0. Replaces `glfwGetWindowParam` and 2475 * `glfwGetGLVersion`. 2476 * 2477 * @ingroup window 2478 */ 2479 GLFWAPI int glfwGetWindowAttrib(GLFWwindow* window, int attrib); 2480 2481 /*! @brief Sets the user pointer of the specified window. 2482 * 2483 * This function sets the user-defined pointer of the specified window. The 2484 * current value is retained until the window is destroyed. The initial value 2485 * is `NULL`. 2486 * 2487 * @param[in] window The window whose pointer to set. 2488 * @param[in] pointer The new value. 2489 * 2490 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 2491 * 2492 * @thread_safety This function may be called from any thread. Access is not 2493 * synchronized. 2494 * 2495 * @sa @ref window_userptr 2496 * @sa glfwGetWindowUserPointer 2497 * 2498 * @since Added in version 3.0. 2499 * 2500 * @ingroup window 2501 */ 2502 GLFWAPI void glfwSetWindowUserPointer(GLFWwindow* window, void* pointer); 2503 2504 /*! @brief Returns the user pointer of the specified window. 2505 * 2506 * This function returns the current value of the user-defined pointer of the 2507 * specified window. The initial value is `NULL`. 2508 * 2509 * @param[in] window The window whose pointer to return. 2510 * 2511 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 2512 * 2513 * @thread_safety This function may be called from any thread. Access is not 2514 * synchronized. 2515 * 2516 * @sa @ref window_userptr 2517 * @sa glfwSetWindowUserPointer 2518 * 2519 * @since Added in version 3.0. 2520 * 2521 * @ingroup window 2522 */ 2523 GLFWAPI void* glfwGetWindowUserPointer(GLFWwindow* window); 2524 2525 /*! @brief Sets the position callback for the specified window. 2526 * 2527 * This function sets the position callback of the specified window, which is 2528 * called when the window is moved. The callback is provided with the screen 2529 * position of the upper-left corner of the client area of the window. 2530 * 2531 * @param[in] window The window whose callback to set. 2532 * @param[in] cbfun The new callback, or `NULL` to remove the currently set 2533 * callback. 2534 * @return The previously set callback, or `NULL` if no callback was set or the 2535 * library had not been [initialized](@ref intro_init). 2536 * 2537 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 2538 * 2539 * @thread_safety This function must only be called from the main thread. 2540 * 2541 * @sa @ref window_pos 2542 * 2543 * @since Added in version 3.0. 2544 * 2545 * @ingroup window 2546 */ 2547 GLFWAPI GLFWwindowposfun glfwSetWindowPosCallback(GLFWwindow* window, GLFWwindowposfun cbfun); 2548 2549 /*! @brief Sets the size callback for the specified window. 2550 * 2551 * This function sets the size callback of the specified window, which is 2552 * called when the window is resized. The callback is provided with the size, 2553 * in screen coordinates, of the client area of the window. 2554 * 2555 * @param[in] window The window whose callback to set. 2556 * @param[in] cbfun The new callback, or `NULL` to remove the currently set 2557 * callback. 2558 * @return The previously set callback, or `NULL` if no callback was set or the 2559 * library had not been [initialized](@ref intro_init). 2560 * 2561 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 2562 * 2563 * @thread_safety This function must only be called from the main thread. 2564 * 2565 * @sa @ref window_size 2566 * 2567 * @since Added in version 1.0. 2568 * @glfw3 Added window handle parameter and return value. 2569 * 2570 * @ingroup window 2571 */ 2572 GLFWAPI GLFWwindowsizefun glfwSetWindowSizeCallback(GLFWwindow* window, GLFWwindowsizefun cbfun); 2573 2574 /*! @brief Sets the close callback for the specified window. 2575 * 2576 * This function sets the close callback of the specified window, which is 2577 * called when the user attempts to close the window, for example by clicking 2578 * the close widget in the title bar. 2579 * 2580 * The close flag is set before this callback is called, but you can modify it 2581 * at any time with @ref glfwSetWindowShouldClose. 2582 * 2583 * The close callback is not triggered by @ref glfwDestroyWindow. 2584 * 2585 * @param[in] window The window whose callback to set. 2586 * @param[in] cbfun The new callback, or `NULL` to remove the currently set 2587 * callback. 2588 * @return The previously set callback, or `NULL` if no callback was set or the 2589 * library had not been [initialized](@ref intro_init). 2590 * 2591 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 2592 * 2593 * @remark @osx Selecting Quit from the application menu will trigger the close 2594 * callback for all windows. 2595 * 2596 * @thread_safety This function must only be called from the main thread. 2597 * 2598 * @sa @ref window_close 2599 * 2600 * @since Added in version 2.5. 2601 * @glfw3 Added window handle parameter and return value. 2602 * 2603 * @ingroup window 2604 */ 2605 GLFWAPI GLFWwindowclosefun glfwSetWindowCloseCallback(GLFWwindow* window, GLFWwindowclosefun cbfun); 2606 2607 /*! @brief Sets the refresh callback for the specified window. 2608 * 2609 * This function sets the refresh callback of the specified window, which is 2610 * called when the client area of the window needs to be redrawn, for example 2611 * if the window has been exposed after having been covered by another window. 2612 * 2613 * On compositing window systems such as Aero, Compiz or Aqua, where the window 2614 * contents are saved off-screen, this callback may be called only very 2615 * infrequently or never at all. 2616 * 2617 * @param[in] window The window whose callback to set. 2618 * @param[in] cbfun The new callback, or `NULL` to remove the currently set 2619 * callback. 2620 * @return The previously set callback, or `NULL` if no callback was set or the 2621 * library had not been [initialized](@ref intro_init). 2622 * 2623 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 2624 * 2625 * @thread_safety This function must only be called from the main thread. 2626 * 2627 * @sa @ref window_refresh 2628 * 2629 * @since Added in version 2.5. 2630 * @glfw3 Added window handle parameter and return value. 2631 * 2632 * @ingroup window 2633 */ 2634 GLFWAPI GLFWwindowrefreshfun glfwSetWindowRefreshCallback(GLFWwindow* window, GLFWwindowrefreshfun cbfun); 2635 2636 /*! @brief Sets the focus callback for the specified window. 2637 * 2638 * This function sets the focus callback of the specified window, which is 2639 * called when the window gains or loses input focus. 2640 * 2641 * After the focus callback is called for a window that lost input focus, 2642 * synthetic key and mouse button release events will be generated for all such 2643 * that had been pressed. For more information, see @ref glfwSetKeyCallback 2644 * and @ref glfwSetMouseButtonCallback. 2645 * 2646 * @param[in] window The window whose callback to set. 2647 * @param[in] cbfun The new callback, or `NULL` to remove the currently set 2648 * callback. 2649 * @return The previously set callback, or `NULL` if no callback was set or the 2650 * library had not been [initialized](@ref intro_init). 2651 * 2652 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 2653 * 2654 * @thread_safety This function must only be called from the main thread. 2655 * 2656 * @sa @ref window_focus 2657 * 2658 * @since Added in version 3.0. 2659 * 2660 * @ingroup window 2661 */ 2662 GLFWAPI GLFWwindowfocusfun glfwSetWindowFocusCallback(GLFWwindow* window, GLFWwindowfocusfun cbfun); 2663 2664 /*! @brief Sets the iconify callback for the specified window. 2665 * 2666 * This function sets the iconification callback of the specified window, which 2667 * is called when the window is iconified or restored. 2668 * 2669 * @param[in] window The window whose callback to set. 2670 * @param[in] cbfun The new callback, or `NULL` to remove the currently set 2671 * callback. 2672 * @return The previously set callback, or `NULL` if no callback was set or the 2673 * library had not been [initialized](@ref intro_init). 2674 * 2675 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 2676 * 2677 * @thread_safety This function must only be called from the main thread. 2678 * 2679 * @sa @ref window_iconify 2680 * 2681 * @since Added in version 3.0. 2682 * 2683 * @ingroup window 2684 */ 2685 GLFWAPI GLFWwindowiconifyfun glfwSetWindowIconifyCallback(GLFWwindow* window, GLFWwindowiconifyfun cbfun); 2686 2687 /*! @brief Sets the framebuffer resize callback for the specified window. 2688 * 2689 * This function sets the framebuffer resize callback of the specified window, 2690 * which is called when the framebuffer of the specified window is resized. 2691 * 2692 * @param[in] window The window whose callback to set. 2693 * @param[in] cbfun The new callback, or `NULL` to remove the currently set 2694 * callback. 2695 * @return The previously set callback, or `NULL` if no callback was set or the 2696 * library had not been [initialized](@ref intro_init). 2697 * 2698 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 2699 * 2700 * @thread_safety This function must only be called from the main thread. 2701 * 2702 * @sa @ref window_fbsize 2703 * 2704 * @since Added in version 3.0. 2705 * 2706 * @ingroup window 2707 */ 2708 GLFWAPI GLFWframebuffersizefun glfwSetFramebufferSizeCallback(GLFWwindow* window, GLFWframebuffersizefun cbfun); 2709 2710 /*! @brief Processes all pending events. 2711 * 2712 * This function processes only those events that are already in the event 2713 * queue and then returns immediately. Processing events will cause the window 2714 * and input callbacks associated with those events to be called. 2715 * 2716 * On some platforms, a window move, resize or menu operation will cause event 2717 * processing to block. This is due to how event processing is designed on 2718 * those platforms. You can use the 2719 * [window refresh callback](@ref window_refresh) to redraw the contents of 2720 * your window when necessary during such operations. 2721 * 2722 * On some platforms, certain events are sent directly to the application 2723 * without going through the event queue, causing callbacks to be called 2724 * outside of a call to one of the event processing functions. 2725 * 2726 * Event processing is not required for joystick input to work. 2727 * 2728 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 2729 * GLFW_PLATFORM_ERROR. 2730 * 2731 * @reentrancy This function must not be called from a callback. 2732 * 2733 * @thread_safety This function must only be called from the main thread. 2734 * 2735 * @sa @ref events 2736 * @sa glfwWaitEvents 2737 * @sa glfwWaitEventsTimeout 2738 * 2739 * @since Added in version 1.0. 2740 * 2741 * @ingroup window 2742 */ 2743 GLFWAPI void glfwPollEvents(void); 2744 2745 /*! @brief Waits until events are queued and processes them. 2746 * 2747 * This function puts the calling thread to sleep until at least one event is 2748 * available in the event queue. Once one or more events are available, 2749 * it behaves exactly like @ref glfwPollEvents, i.e. the events in the queue 2750 * are processed and the function then returns immediately. Processing events 2751 * will cause the window and input callbacks associated with those events to be 2752 * called. 2753 * 2754 * Since not all events are associated with callbacks, this function may return 2755 * without a callback having been called even if you are monitoring all 2756 * callbacks. 2757 * 2758 * On some platforms, a window move, resize or menu operation will cause event 2759 * processing to block. This is due to how event processing is designed on 2760 * those platforms. You can use the 2761 * [window refresh callback](@ref window_refresh) to redraw the contents of 2762 * your window when necessary during such operations. 2763 * 2764 * On some platforms, certain callbacks may be called outside of a call to one 2765 * of the event processing functions. 2766 * 2767 * If no windows exist, this function returns immediately. For synchronization 2768 * of threads in applications that do not create windows, use your threading 2769 * library of choice. 2770 * 2771 * Event processing is not required for joystick input to work. 2772 * 2773 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 2774 * GLFW_PLATFORM_ERROR. 2775 * 2776 * @reentrancy This function must not be called from a callback. 2777 * 2778 * @thread_safety This function must only be called from the main thread. 2779 * 2780 * @sa @ref events 2781 * @sa glfwPollEvents 2782 * @sa glfwWaitEventsTimeout 2783 * 2784 * @since Added in version 2.5. 2785 * 2786 * @ingroup window 2787 */ 2788 GLFWAPI void glfwWaitEvents(void); 2789 2790 /*! @brief Waits with timeout until events are queued and processes them. 2791 * 2792 * This function puts the calling thread to sleep until at least one event is 2793 * available in the event queue, or until the specified timeout is reached. If 2794 * one or more events are available, it behaves exactly like @ref 2795 * glfwPollEvents, i.e. the events in the queue are processed and the function 2796 * then returns immediately. Processing events will cause the window and input 2797 * callbacks associated with those events to be called. 2798 * 2799 * The timeout value must be a positive finite number. 2800 * 2801 * Since not all events are associated with callbacks, this function may return 2802 * without a callback having been called even if you are monitoring all 2803 * callbacks. 2804 * 2805 * On some platforms, a window move, resize or menu operation will cause event 2806 * processing to block. This is due to how event processing is designed on 2807 * those platforms. You can use the 2808 * [window refresh callback](@ref window_refresh) to redraw the contents of 2809 * your window when necessary during such operations. 2810 * 2811 * On some platforms, certain callbacks may be called outside of a call to one 2812 * of the event processing functions. 2813 * 2814 * If no windows exist, this function returns immediately. For synchronization 2815 * of threads in applications that do not create windows, use your threading 2816 * library of choice. 2817 * 2818 * Event processing is not required for joystick input to work. 2819 * 2820 * @param[in] timeout The maximum amount of time, in seconds, to wait. 2821 * 2822 * @reentrancy This function must not be called from a callback. 2823 * 2824 * @thread_safety This function must only be called from the main thread. 2825 * 2826 * @sa @ref events 2827 * @sa glfwPollEvents 2828 * @sa glfwWaitEvents 2829 * 2830 * @since Added in version 3.2. 2831 * 2832 * @ingroup window 2833 */ 2834 GLFWAPI void glfwWaitEventsTimeout(double timeout); 2835 2836 /*! @brief Posts an empty event to the event queue. 2837 * 2838 * This function posts an empty event from the current thread to the event 2839 * queue, causing @ref glfwWaitEvents to return. 2840 * 2841 * If no windows exist, this function returns immediately. For synchronization 2842 * of threads in applications that do not create windows, use your threading 2843 * library of choice. 2844 * 2845 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 2846 * GLFW_PLATFORM_ERROR. 2847 * 2848 * @thread_safety This function may be called from any thread. 2849 * 2850 * @sa @ref events 2851 * @sa glfwWaitEvents 2852 * 2853 * @since Added in version 3.1. 2854 * 2855 * @ingroup window 2856 */ 2857 GLFWAPI void glfwPostEmptyEvent(void); 2858 2859 /*! @brief Returns the value of an input option for the specified window. 2860 * 2861 * This function returns the value of an input option for the specified window. 2862 * The mode must be one of `GLFW_CURSOR`, `GLFW_STICKY_KEYS` or 2863 * `GLFW_STICKY_MOUSE_BUTTONS`. 2864 * 2865 * @param[in] window The window to query. 2866 * @param[in] mode One of `GLFW_CURSOR`, `GLFW_STICKY_KEYS` or 2867 * `GLFW_STICKY_MOUSE_BUTTONS`. 2868 * 2869 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 2870 * GLFW_INVALID_ENUM. 2871 * 2872 * @thread_safety This function must only be called from the main thread. 2873 * 2874 * @sa glfwSetInputMode 2875 * 2876 * @since Added in version 3.0. 2877 * 2878 * @ingroup input 2879 */ 2880 GLFWAPI int glfwGetInputMode(GLFWwindow* window, int mode); 2881 2882 /*! @brief Sets an input option for the specified window. 2883 * 2884 * This function sets an input mode option for the specified window. The mode 2885 * must be one of `GLFW_CURSOR`, `GLFW_STICKY_KEYS` or 2886 * `GLFW_STICKY_MOUSE_BUTTONS`. 2887 * 2888 * If the mode is `GLFW_CURSOR`, the value must be one of the following cursor 2889 * modes: 2890 * - `GLFW_CURSOR_NORMAL` makes the cursor visible and behaving normally. 2891 * - `GLFW_CURSOR_HIDDEN` makes the cursor invisible when it is over the client 2892 * area of the window but does not restrict the cursor from leaving. 2893 * - `GLFW_CURSOR_DISABLED` hides and grabs the cursor, providing virtual 2894 * and unlimited cursor movement. This is useful for implementing for 2895 * example 3D camera controls. 2896 * 2897 * If the mode is `GLFW_STICKY_KEYS`, the value must be either `GLFW_TRUE` to 2898 * enable sticky keys, or `GLFW_FALSE` to disable it. If sticky keys are 2899 * enabled, a key press will ensure that @ref glfwGetKey returns `GLFW_PRESS` 2900 * the next time it is called even if the key had been released before the 2901 * call. This is useful when you are only interested in whether keys have been 2902 * pressed but not when or in which order. 2903 * 2904 * If the mode is `GLFW_STICKY_MOUSE_BUTTONS`, the value must be either 2905 * `GLFW_TRUE` to enable sticky mouse buttons, or `GLFW_FALSE` to disable it. 2906 * If sticky mouse buttons are enabled, a mouse button press will ensure that 2907 * @ref glfwGetMouseButton returns `GLFW_PRESS` the next time it is called even 2908 * if the mouse button had been released before the call. This is useful when 2909 * you are only interested in whether mouse buttons have been pressed but not 2910 * when or in which order. 2911 * 2912 * @param[in] window The window whose input mode to set. 2913 * @param[in] mode One of `GLFW_CURSOR`, `GLFW_STICKY_KEYS` or 2914 * `GLFW_STICKY_MOUSE_BUTTONS`. 2915 * @param[in] value The new value of the specified input mode. 2916 * 2917 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref 2918 * GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR. 2919 * 2920 * @thread_safety This function must only be called from the main thread. 2921 * 2922 * @sa glfwGetInputMode 2923 * 2924 * @since Added in version 3.0. Replaces `glfwEnable` and `glfwDisable`. 2925 * 2926 * @ingroup input 2927 */ 2928 GLFWAPI void glfwSetInputMode(GLFWwindow* window, int mode, int value); 2929 2930 /*! @brief Returns the localized name of the specified printable key. 2931 * 2932 * This function returns the localized name of the specified printable key. 2933 * This is intended for displaying key bindings to the user. 2934 * 2935 * If the key is `GLFW_KEY_UNKNOWN`, the scancode is used instead, otherwise 2936 * the scancode is ignored. If a non-printable key or (if the key is 2937 * `GLFW_KEY_UNKNOWN`) a scancode that maps to a non-printable key is 2938 * specified, this function returns `NULL`. 2939 * 2940 * This behavior allows you to pass in the arguments passed to the 2941 * [key callback](@ref input_key) without modification. 2942 * 2943 * The printable keys are: 2944 * - `GLFW_KEY_APOSTROPHE` 2945 * - `GLFW_KEY_COMMA` 2946 * - `GLFW_KEY_MINUS` 2947 * - `GLFW_KEY_PERIOD` 2948 * - `GLFW_KEY_SLASH` 2949 * - `GLFW_KEY_SEMICOLON` 2950 * - `GLFW_KEY_EQUAL` 2951 * - `GLFW_KEY_LEFT_BRACKET` 2952 * - `GLFW_KEY_RIGHT_BRACKET` 2953 * - `GLFW_KEY_BACKSLASH` 2954 * - `GLFW_KEY_WORLD_1` 2955 * - `GLFW_KEY_WORLD_2` 2956 * - `GLFW_KEY_0` to `GLFW_KEY_9` 2957 * - `GLFW_KEY_A` to `GLFW_KEY_Z` 2958 * - `GLFW_KEY_KP_0` to `GLFW_KEY_KP_9` 2959 * - `GLFW_KEY_KP_DECIMAL` 2960 * - `GLFW_KEY_KP_DIVIDE` 2961 * - `GLFW_KEY_KP_MULTIPLY` 2962 * - `GLFW_KEY_KP_SUBTRACT` 2963 * - `GLFW_KEY_KP_ADD` 2964 * - `GLFW_KEY_KP_EQUAL` 2965 * 2966 * @param[in] key The key to query, or `GLFW_KEY_UNKNOWN`. 2967 * @param[in] scancode The scancode of the key to query. 2968 * @return The localized name of the key, or `NULL`. 2969 * 2970 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 2971 * GLFW_PLATFORM_ERROR. 2972 * 2973 * @pointer_lifetime The returned string is allocated and freed by GLFW. You 2974 * should not free it yourself. It is valid until the next call to @ref 2975 * glfwGetKeyName, or until the library is terminated. 2976 * 2977 * @thread_safety This function must only be called from the main thread. 2978 * 2979 * @sa @ref input_key_name 2980 * 2981 * @since Added in version 3.2. 2982 * 2983 * @ingroup input 2984 */ 2985 GLFWAPI const char* glfwGetKeyName(int key, int scancode); 2986 2987 /*! @brief Returns the last reported state of a keyboard key for the specified 2988 * window. 2989 * 2990 * This function returns the last state reported for the specified key to the 2991 * specified window. The returned state is one of `GLFW_PRESS` or 2992 * `GLFW_RELEASE`. The higher-level action `GLFW_REPEAT` is only reported to 2993 * the key callback. 2994 * 2995 * If the `GLFW_STICKY_KEYS` input mode is enabled, this function returns 2996 * `GLFW_PRESS` the first time you call it for a key that was pressed, even if 2997 * that key has already been released. 2998 * 2999 * The key functions deal with physical keys, with [key tokens](@ref keys) 3000 * named after their use on the standard US keyboard layout. If you want to 3001 * input text, use the Unicode character callback instead. 3002 * 3003 * The [modifier key bit masks](@ref mods) are not key tokens and cannot be 3004 * used with this function. 3005 * 3006 * __Do not use this function__ to implement [text input](@ref input_char). 3007 * 3008 * @param[in] window The desired window. 3009 * @param[in] key The desired [keyboard key](@ref keys). `GLFW_KEY_UNKNOWN` is 3010 * not a valid key for this function. 3011 * @return One of `GLFW_PRESS` or `GLFW_RELEASE`. 3012 * 3013 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 3014 * GLFW_INVALID_ENUM. 3015 * 3016 * @thread_safety This function must only be called from the main thread. 3017 * 3018 * @sa @ref input_key 3019 * 3020 * @since Added in version 1.0. 3021 * @glfw3 Added window handle parameter. 3022 * 3023 * @ingroup input 3024 */ 3025 GLFWAPI int glfwGetKey(GLFWwindow* window, int key); 3026 3027 /*! @brief Returns the last reported state of a mouse button for the specified 3028 * window. 3029 * 3030 * This function returns the last state reported for the specified mouse button 3031 * to the specified window. The returned state is one of `GLFW_PRESS` or 3032 * `GLFW_RELEASE`. 3033 * 3034 * If the `GLFW_STICKY_MOUSE_BUTTONS` input mode is enabled, this function 3035 * `GLFW_PRESS` the first time you call it for a mouse button that was pressed, 3036 * even if that mouse button has already been released. 3037 * 3038 * @param[in] window The desired window. 3039 * @param[in] button The desired [mouse button](@ref buttons). 3040 * @return One of `GLFW_PRESS` or `GLFW_RELEASE`. 3041 * 3042 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 3043 * GLFW_INVALID_ENUM. 3044 * 3045 * @thread_safety This function must only be called from the main thread. 3046 * 3047 * @sa @ref input_mouse_button 3048 * 3049 * @since Added in version 1.0. 3050 * @glfw3 Added window handle parameter. 3051 * 3052 * @ingroup input 3053 */ 3054 GLFWAPI int glfwGetMouseButton(GLFWwindow* window, int button); 3055 3056 /*! @brief Retrieves the position of the cursor relative to the client area of 3057 * the window. 3058 * 3059 * This function returns the position of the cursor, in screen coordinates, 3060 * relative to the upper-left corner of the client area of the specified 3061 * window. 3062 * 3063 * If the cursor is disabled (with `GLFW_CURSOR_DISABLED`) then the cursor 3064 * position is unbounded and limited only by the minimum and maximum values of 3065 * a `double`. 3066 * 3067 * The coordinate can be converted to their integer equivalents with the 3068 * `floor` function. Casting directly to an integer type works for positive 3069 * coordinates, but fails for negative ones. 3070 * 3071 * Any or all of the position arguments may be `NULL`. If an error occurs, all 3072 * non-`NULL` position arguments will be set to zero. 3073 * 3074 * @param[in] window The desired window. 3075 * @param[out] xpos Where to store the cursor x-coordinate, relative to the 3076 * left edge of the client area, or `NULL`. 3077 * @param[out] ypos Where to store the cursor y-coordinate, relative to the to 3078 * top edge of the client area, or `NULL`. 3079 * 3080 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 3081 * GLFW_PLATFORM_ERROR. 3082 * 3083 * @thread_safety This function must only be called from the main thread. 3084 * 3085 * @sa @ref cursor_pos 3086 * @sa glfwSetCursorPos 3087 * 3088 * @since Added in version 3.0. Replaces `glfwGetMousePos`. 3089 * 3090 * @ingroup input 3091 */ 3092 GLFWAPI void glfwGetCursorPos(GLFWwindow* window, double* xpos, double* ypos); 3093 3094 /*! @brief Sets the position of the cursor, relative to the client area of the 3095 * window. 3096 * 3097 * This function sets the position, in screen coordinates, of the cursor 3098 * relative to the upper-left corner of the client area of the specified 3099 * window. The window must have input focus. If the window does not have 3100 * input focus when this function is called, it fails silently. 3101 * 3102 * __Do not use this function__ to implement things like camera controls. GLFW 3103 * already provides the `GLFW_CURSOR_DISABLED` cursor mode that hides the 3104 * cursor, transparently re-centers it and provides unconstrained cursor 3105 * motion. See @ref glfwSetInputMode for more information. 3106 * 3107 * If the cursor mode is `GLFW_CURSOR_DISABLED` then the cursor position is 3108 * unconstrained and limited only by the minimum and maximum values of 3109 * a `double`. 3110 * 3111 * @param[in] window The desired window. 3112 * @param[in] xpos The desired x-coordinate, relative to the left edge of the 3113 * client area. 3114 * @param[in] ypos The desired y-coordinate, relative to the top edge of the 3115 * client area. 3116 * 3117 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 3118 * GLFW_PLATFORM_ERROR. 3119 * 3120 * @remark @x11 Due to the asynchronous nature of X11, it may take a moment for 3121 * the window focus event to arrive. This means you may not be able to set the 3122 * cursor position directly after window creation. 3123 * 3124 * @thread_safety This function must only be called from the main thread. 3125 * 3126 * @sa @ref cursor_pos 3127 * @sa glfwGetCursorPos 3128 * 3129 * @since Added in version 3.0. Replaces `glfwSetMousePos`. 3130 * 3131 * @ingroup input 3132 */ 3133 GLFWAPI void glfwSetCursorPos(GLFWwindow* window, double xpos, double ypos); 3134 3135 /*! @brief Creates a custom cursor. 3136 * 3137 * Creates a new custom cursor image that can be set for a window with @ref 3138 * glfwSetCursor. The cursor can be destroyed with @ref glfwDestroyCursor. 3139 * Any remaining cursors are destroyed by @ref glfwTerminate. 3140 * 3141 * The pixels are 32-bit, little-endian, non-premultiplied RGBA, i.e. eight 3142 * bits per channel. They are arranged canonically as packed sequential rows, 3143 * starting from the top-left corner. 3144 * 3145 * The cursor hotspot is specified in pixels, relative to the upper-left corner 3146 * of the cursor image. Like all other coordinate systems in GLFW, the X-axis 3147 * points to the right and the Y-axis points down. 3148 * 3149 * @param[in] image The desired cursor image. 3150 * @param[in] xhot The desired x-coordinate, in pixels, of the cursor hotspot. 3151 * @param[in] yhot The desired y-coordinate, in pixels, of the cursor hotspot. 3152 * @return The handle of the created cursor, or `NULL` if an 3153 * [error](@ref error_handling) occurred. 3154 * 3155 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 3156 * GLFW_PLATFORM_ERROR. 3157 * 3158 * @pointer_lifetime The specified image data is copied before this function 3159 * returns. 3160 * 3161 * @reentrancy This function must not be called from a callback. 3162 * 3163 * @thread_safety This function must only be called from the main thread. 3164 * 3165 * @sa @ref cursor_object 3166 * @sa glfwDestroyCursor 3167 * @sa glfwCreateStandardCursor 3168 * 3169 * @since Added in version 3.1. 3170 * 3171 * @ingroup input 3172 */ 3173 GLFWAPI GLFWcursor* glfwCreateCursor(const GLFWimage* image, int xhot, int yhot); 3174 3175 /*! @brief Creates a cursor with a standard shape. 3176 * 3177 * Returns a cursor with a [standard shape](@ref shapes), that can be set for 3178 * a window with @ref glfwSetCursor. 3179 * 3180 * @param[in] shape One of the [standard shapes](@ref shapes). 3181 * @return A new cursor ready to use or `NULL` if an 3182 * [error](@ref error_handling) occurred. 3183 * 3184 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref 3185 * GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR. 3186 * 3187 * @reentrancy This function must not be called from a callback. 3188 * 3189 * @thread_safety This function must only be called from the main thread. 3190 * 3191 * @sa @ref cursor_object 3192 * @sa glfwCreateCursor 3193 * 3194 * @since Added in version 3.1. 3195 * 3196 * @ingroup input 3197 */ 3198 GLFWAPI GLFWcursor* glfwCreateStandardCursor(int shape); 3199 3200 /*! @brief Destroys a cursor. 3201 * 3202 * This function destroys a cursor previously created with @ref 3203 * glfwCreateCursor. Any remaining cursors will be destroyed by @ref 3204 * glfwTerminate. 3205 * 3206 * @param[in] cursor The cursor object to destroy. 3207 * 3208 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 3209 * GLFW_PLATFORM_ERROR. 3210 * 3211 * @reentrancy This function must not be called from a callback. 3212 * 3213 * @thread_safety This function must only be called from the main thread. 3214 * 3215 * @sa @ref cursor_object 3216 * @sa glfwCreateCursor 3217 * 3218 * @since Added in version 3.1. 3219 * 3220 * @ingroup input 3221 */ 3222 GLFWAPI void glfwDestroyCursor(GLFWcursor* cursor); 3223 3224 /*! @brief Sets the cursor for the window. 3225 * 3226 * This function sets the cursor image to be used when the cursor is over the 3227 * client area of the specified window. The set cursor will only be visible 3228 * when the [cursor mode](@ref cursor_mode) of the window is 3229 * `GLFW_CURSOR_NORMAL`. 3230 * 3231 * On some platforms, the set cursor may not be visible unless the window also 3232 * has input focus. 3233 * 3234 * @param[in] window The window to set the cursor for. 3235 * @param[in] cursor The cursor to set, or `NULL` to switch back to the default 3236 * arrow cursor. 3237 * 3238 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 3239 * GLFW_PLATFORM_ERROR. 3240 * 3241 * @thread_safety This function must only be called from the main thread. 3242 * 3243 * @sa @ref cursor_object 3244 * 3245 * @since Added in version 3.1. 3246 * 3247 * @ingroup input 3248 */ 3249 GLFWAPI void glfwSetCursor(GLFWwindow* window, GLFWcursor* cursor); 3250 3251 /*! @brief Sets the key callback. 3252 * 3253 * This function sets the key callback of the specified window, which is called 3254 * when a key is pressed, repeated or released. 3255 * 3256 * The key functions deal with physical keys, with layout independent 3257 * [key tokens](@ref keys) named after their values in the standard US keyboard 3258 * layout. If you want to input text, use the 3259 * [character callback](@ref glfwSetCharCallback) instead. 3260 * 3261 * When a window loses input focus, it will generate synthetic key release 3262 * events for all pressed keys. You can tell these events from user-generated 3263 * events by the fact that the synthetic ones are generated after the focus 3264 * loss event has been processed, i.e. after the 3265 * [window focus callback](@ref glfwSetWindowFocusCallback) has been called. 3266 * 3267 * The scancode of a key is specific to that platform or sometimes even to that 3268 * machine. Scancodes are intended to allow users to bind keys that don't have 3269 * a GLFW key token. Such keys have `key` set to `GLFW_KEY_UNKNOWN`, their 3270 * state is not saved and so it cannot be queried with @ref glfwGetKey. 3271 * 3272 * Sometimes GLFW needs to generate synthetic key events, in which case the 3273 * scancode may be zero. 3274 * 3275 * @param[in] window The window whose callback to set. 3276 * @param[in] cbfun The new key callback, or `NULL` to remove the currently 3277 * set callback. 3278 * @return The previously set callback, or `NULL` if no callback was set or the 3279 * library had not been [initialized](@ref intro_init). 3280 * 3281 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 3282 * 3283 * @thread_safety This function must only be called from the main thread. 3284 * 3285 * @sa @ref input_key 3286 * 3287 * @since Added in version 1.0. 3288 * @glfw3 Added window handle parameter and return value. 3289 * 3290 * @ingroup input 3291 */ 3292 GLFWAPI GLFWkeyfun glfwSetKeyCallback(GLFWwindow* window, GLFWkeyfun cbfun); 3293 3294 /*! @brief Sets the Unicode character callback. 3295 * 3296 * This function sets the character callback of the specified window, which is 3297 * called when a Unicode character is input. 3298 * 3299 * The character callback is intended for Unicode text input. As it deals with 3300 * characters, it is keyboard layout dependent, whereas the 3301 * [key callback](@ref glfwSetKeyCallback) is not. Characters do not map 1:1 3302 * to physical keys, as a key may produce zero, one or more characters. If you 3303 * want to know whether a specific physical key was pressed or released, see 3304 * the key callback instead. 3305 * 3306 * The character callback behaves as system text input normally does and will 3307 * not be called if modifier keys are held down that would prevent normal text 3308 * input on that platform, for example a Super (Command) key on OS X or Alt key 3309 * on Windows. There is a 3310 * [character with modifiers callback](@ref glfwSetCharModsCallback) that 3311 * receives these events. 3312 * 3313 * @param[in] window The window whose callback to set. 3314 * @param[in] cbfun The new callback, or `NULL` to remove the currently set 3315 * callback. 3316 * @return The previously set callback, or `NULL` if no callback was set or the 3317 * library had not been [initialized](@ref intro_init). 3318 * 3319 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 3320 * 3321 * @thread_safety This function must only be called from the main thread. 3322 * 3323 * @sa @ref input_char 3324 * 3325 * @since Added in version 2.4. 3326 * @glfw3 Added window handle parameter and return value. 3327 * 3328 * @ingroup input 3329 */ 3330 GLFWAPI GLFWcharfun glfwSetCharCallback(GLFWwindow* window, GLFWcharfun cbfun); 3331 3332 /*! @brief Sets the Unicode character with modifiers callback. 3333 * 3334 * This function sets the character with modifiers callback of the specified 3335 * window, which is called when a Unicode character is input regardless of what 3336 * modifier keys are used. 3337 * 3338 * The character with modifiers callback is intended for implementing custom 3339 * Unicode character input. For regular Unicode text input, see the 3340 * [character callback](@ref glfwSetCharCallback). Like the character 3341 * callback, the character with modifiers callback deals with characters and is 3342 * keyboard layout dependent. Characters do not map 1:1 to physical keys, as 3343 * a key may produce zero, one or more characters. If you want to know whether 3344 * a specific physical key was pressed or released, see the 3345 * [key callback](@ref glfwSetKeyCallback) instead. 3346 * 3347 * @param[in] window The window whose callback to set. 3348 * @param[in] cbfun The new callback, or `NULL` to remove the currently set 3349 * callback. 3350 * @return The previously set callback, or `NULL` if no callback was set or an 3351 * error occurred. 3352 * 3353 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 3354 * 3355 * @thread_safety This function must only be called from the main thread. 3356 * 3357 * @sa @ref input_char 3358 * 3359 * @since Added in version 3.1. 3360 * 3361 * @ingroup input 3362 */ 3363 GLFWAPI GLFWcharmodsfun glfwSetCharModsCallback(GLFWwindow* window, GLFWcharmodsfun cbfun); 3364 3365 /*! @brief Sets the mouse button callback. 3366 * 3367 * This function sets the mouse button callback of the specified window, which 3368 * is called when a mouse button is pressed or released. 3369 * 3370 * When a window loses input focus, it will generate synthetic mouse button 3371 * release events for all pressed mouse buttons. You can tell these events 3372 * from user-generated events by the fact that the synthetic ones are generated 3373 * after the focus loss event has been processed, i.e. after the 3374 * [window focus callback](@ref glfwSetWindowFocusCallback) has been called. 3375 * 3376 * @param[in] window The window whose callback to set. 3377 * @param[in] cbfun The new callback, or `NULL` to remove the currently set 3378 * callback. 3379 * @return The previously set callback, or `NULL` if no callback was set or the 3380 * library had not been [initialized](@ref intro_init). 3381 * 3382 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 3383 * 3384 * @thread_safety This function must only be called from the main thread. 3385 * 3386 * @sa @ref input_mouse_button 3387 * 3388 * @since Added in version 1.0. 3389 * @glfw3 Added window handle parameter and return value. 3390 * 3391 * @ingroup input 3392 */ 3393 GLFWAPI GLFWmousebuttonfun glfwSetMouseButtonCallback(GLFWwindow* window, GLFWmousebuttonfun cbfun); 3394 3395 /*! @brief Sets the cursor position callback. 3396 * 3397 * This function sets the cursor position callback of the specified window, 3398 * which is called when the cursor is moved. The callback is provided with the 3399 * position, in screen coordinates, relative to the upper-left corner of the 3400 * client area of the window. 3401 * 3402 * @param[in] window The window whose callback to set. 3403 * @param[in] cbfun The new callback, or `NULL` to remove the currently set 3404 * callback. 3405 * @return The previously set callback, or `NULL` if no callback was set or the 3406 * library had not been [initialized](@ref intro_init). 3407 * 3408 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 3409 * 3410 * @thread_safety This function must only be called from the main thread. 3411 * 3412 * @sa @ref cursor_pos 3413 * 3414 * @since Added in version 3.0. Replaces `glfwSetMousePosCallback`. 3415 * 3416 * @ingroup input 3417 */ 3418 GLFWAPI GLFWcursorposfun glfwSetCursorPosCallback(GLFWwindow* window, GLFWcursorposfun cbfun); 3419 3420 /*! @brief Sets the cursor enter/exit callback. 3421 * 3422 * This function sets the cursor boundary crossing callback of the specified 3423 * window, which is called when the cursor enters or leaves the client area of 3424 * the window. 3425 * 3426 * @param[in] window The window whose callback to set. 3427 * @param[in] cbfun The new callback, or `NULL` to remove the currently set 3428 * callback. 3429 * @return The previously set callback, or `NULL` if no callback was set or the 3430 * library had not been [initialized](@ref intro_init). 3431 * 3432 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 3433 * 3434 * @thread_safety This function must only be called from the main thread. 3435 * 3436 * @sa @ref cursor_enter 3437 * 3438 * @since Added in version 3.0. 3439 * 3440 * @ingroup input 3441 */ 3442 GLFWAPI GLFWcursorenterfun glfwSetCursorEnterCallback(GLFWwindow* window, GLFWcursorenterfun cbfun); 3443 3444 /*! @brief Sets the scroll callback. 3445 * 3446 * This function sets the scroll callback of the specified window, which is 3447 * called when a scrolling device is used, such as a mouse wheel or scrolling 3448 * area of a touchpad. 3449 * 3450 * The scroll callback receives all scrolling input, like that from a mouse 3451 * wheel or a touchpad scrolling area. 3452 * 3453 * @param[in] window The window whose callback to set. 3454 * @param[in] cbfun The new scroll callback, or `NULL` to remove the currently 3455 * set callback. 3456 * @return The previously set callback, or `NULL` if no callback was set or the 3457 * library had not been [initialized](@ref intro_init). 3458 * 3459 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 3460 * 3461 * @thread_safety This function must only be called from the main thread. 3462 * 3463 * @sa @ref scrolling 3464 * 3465 * @since Added in version 3.0. Replaces `glfwSetMouseWheelCallback`. 3466 * 3467 * @ingroup input 3468 */ 3469 GLFWAPI GLFWscrollfun glfwSetScrollCallback(GLFWwindow* window, GLFWscrollfun cbfun); 3470 3471 /*! @brief Sets the file drop callback. 3472 * 3473 * This function sets the file drop callback of the specified window, which is 3474 * called when one or more dragged files are dropped on the window. 3475 * 3476 * Because the path array and its strings may have been generated specifically 3477 * for that event, they are not guaranteed to be valid after the callback has 3478 * returned. If you wish to use them after the callback returns, you need to 3479 * make a deep copy. 3480 * 3481 * @param[in] window The window whose callback to set. 3482 * @param[in] cbfun The new file drop callback, or `NULL` to remove the 3483 * currently set callback. 3484 * @return The previously set callback, or `NULL` if no callback was set or the 3485 * library had not been [initialized](@ref intro_init). 3486 * 3487 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 3488 * 3489 * @thread_safety This function must only be called from the main thread. 3490 * 3491 * @sa @ref path_drop 3492 * 3493 * @since Added in version 3.1. 3494 * 3495 * @ingroup input 3496 */ 3497 GLFWAPI GLFWdropfun glfwSetDropCallback(GLFWwindow* window, GLFWdropfun cbfun); 3498 3499 /*! @brief Returns whether the specified joystick is present. 3500 * 3501 * This function returns whether the specified joystick is present. 3502 * 3503 * @param[in] joy The [joystick](@ref joysticks) to query. 3504 * @return `GLFW_TRUE` if the joystick is present, or `GLFW_FALSE` otherwise. 3505 * 3506 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref 3507 * GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR. 3508 * 3509 * @thread_safety This function must only be called from the main thread. 3510 * 3511 * @sa @ref joystick 3512 * 3513 * @since Added in version 3.0. Replaces `glfwGetJoystickParam`. 3514 * 3515 * @ingroup input 3516 */ 3517 GLFWAPI int glfwJoystickPresent(int joy); 3518 3519 /*! @brief Returns the values of all axes of the specified joystick. 3520 * 3521 * This function returns the values of all axes of the specified joystick. 3522 * Each element in the array is a value between -1.0 and 1.0. 3523 * 3524 * Querying a joystick slot with no device present is not an error, but will 3525 * cause this function to return `NULL`. Call @ref glfwJoystickPresent to 3526 * check device presence. 3527 * 3528 * @param[in] joy The [joystick](@ref joysticks) to query. 3529 * @param[out] count Where to store the number of axis values in the returned 3530 * array. This is set to zero if an error occurred. 3531 * @return An array of axis values, or `NULL` if the joystick is not present. 3532 * 3533 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref 3534 * GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR. 3535 * 3536 * @pointer_lifetime The returned array is allocated and freed by GLFW. You 3537 * should not free it yourself. It is valid until the specified joystick is 3538 * disconnected, this function is called again for that joystick or the library 3539 * is terminated. 3540 * 3541 * @thread_safety This function must only be called from the main thread. 3542 * 3543 * @sa @ref joystick_axis 3544 * 3545 * @since Added in version 3.0. Replaces `glfwGetJoystickPos`. 3546 * 3547 * @ingroup input 3548 */ 3549 GLFWAPI const float* glfwGetJoystickAxes(int joy, int* count); 3550 3551 /*! @brief Returns the state of all buttons of the specified joystick. 3552 * 3553 * This function returns the state of all buttons of the specified joystick. 3554 * Each element in the array is either `GLFW_PRESS` or `GLFW_RELEASE`. 3555 * 3556 * Querying a joystick slot with no device present is not an error, but will 3557 * cause this function to return `NULL`. Call @ref glfwJoystickPresent to 3558 * check device presence. 3559 * 3560 * @param[in] joy The [joystick](@ref joysticks) to query. 3561 * @param[out] count Where to store the number of button states in the returned 3562 * array. This is set to zero if an error occurred. 3563 * @return An array of button states, or `NULL` if the joystick is not present. 3564 * 3565 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref 3566 * GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR. 3567 * 3568 * @pointer_lifetime The returned array is allocated and freed by GLFW. You 3569 * should not free it yourself. It is valid until the specified joystick is 3570 * disconnected, this function is called again for that joystick or the library 3571 * is terminated. 3572 * 3573 * @thread_safety This function must only be called from the main thread. 3574 * 3575 * @sa @ref joystick_button 3576 * 3577 * @since Added in version 2.2. 3578 * @glfw3 Changed to return a dynamic array. 3579 * 3580 * @ingroup input 3581 */ 3582 GLFWAPI const unsigned char* glfwGetJoystickButtons(int joy, int* count); 3583 3584 /*! @brief Returns the name of the specified joystick. 3585 * 3586 * This function returns the name, encoded as UTF-8, of the specified joystick. 3587 * The returned string is allocated and freed by GLFW. You should not free it 3588 * yourself. 3589 * 3590 * Querying a joystick slot with no device present is not an error, but will 3591 * cause this function to return `NULL`. Call @ref glfwJoystickPresent to 3592 * check device presence. 3593 * 3594 * @param[in] joy The [joystick](@ref joysticks) to query. 3595 * @return The UTF-8 encoded name of the joystick, or `NULL` if the joystick 3596 * is not present. 3597 * 3598 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref 3599 * GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR. 3600 * 3601 * @pointer_lifetime The returned string is allocated and freed by GLFW. You 3602 * should not free it yourself. It is valid until the specified joystick is 3603 * disconnected, this function is called again for that joystick or the library 3604 * is terminated. 3605 * 3606 * @thread_safety This function must only be called from the main thread. 3607 * 3608 * @sa @ref joystick_name 3609 * 3610 * @since Added in version 3.0. 3611 * 3612 * @ingroup input 3613 */ 3614 GLFWAPI const char* glfwGetJoystickName(int joy); 3615 3616 /*! @brief Sets the joystick configuration callback. 3617 * 3618 * This function sets the joystick configuration callback, or removes the 3619 * currently set callback. This is called when a joystick is connected to or 3620 * disconnected from the system. 3621 * 3622 * @param[in] cbfun The new callback, or `NULL` to remove the currently set 3623 * callback. 3624 * @return The previously set callback, or `NULL` if no callback was set or the 3625 * library had not been [initialized](@ref intro_init). 3626 * 3627 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 3628 * 3629 * @thread_safety This function must only be called from the main thread. 3630 * 3631 * @sa @ref joystick_event 3632 * 3633 * @since Added in version 3.2. 3634 * 3635 * @ingroup input 3636 */ 3637 GLFWAPI GLFWjoystickfun glfwSetJoystickCallback(GLFWjoystickfun cbfun); 3638 3639 /*! @brief Sets the clipboard to the specified string. 3640 * 3641 * This function sets the system clipboard to the specified, UTF-8 encoded 3642 * string. 3643 * 3644 * @param[in] window The window that will own the clipboard contents. 3645 * @param[in] string A UTF-8 encoded string. 3646 * 3647 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 3648 * GLFW_PLATFORM_ERROR. 3649 * 3650 * @pointer_lifetime The specified string is copied before this function 3651 * returns. 3652 * 3653 * @thread_safety This function must only be called from the main thread. 3654 * 3655 * @sa @ref clipboard 3656 * @sa glfwGetClipboardString 3657 * 3658 * @since Added in version 3.0. 3659 * 3660 * @ingroup input 3661 */ 3662 GLFWAPI void glfwSetClipboardString(GLFWwindow* window, const char* string); 3663 3664 /*! @brief Returns the contents of the clipboard as a string. 3665 * 3666 * This function returns the contents of the system clipboard, if it contains 3667 * or is convertible to a UTF-8 encoded string. If the clipboard is empty or 3668 * if its contents cannot be converted, `NULL` is returned and a @ref 3669 * GLFW_FORMAT_UNAVAILABLE error is generated. 3670 * 3671 * @param[in] window The window that will request the clipboard contents. 3672 * @return The contents of the clipboard as a UTF-8 encoded string, or `NULL` 3673 * if an [error](@ref error_handling) occurred. 3674 * 3675 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 3676 * GLFW_PLATFORM_ERROR. 3677 * 3678 * @pointer_lifetime The returned string is allocated and freed by GLFW. You 3679 * should not free it yourself. It is valid until the next call to @ref 3680 * glfwGetClipboardString or @ref glfwSetClipboardString, or until the library 3681 * is terminated. 3682 * 3683 * @thread_safety This function must only be called from the main thread. 3684 * 3685 * @sa @ref clipboard 3686 * @sa glfwSetClipboardString 3687 * 3688 * @since Added in version 3.0. 3689 * 3690 * @ingroup input 3691 */ 3692 GLFWAPI const char* glfwGetClipboardString(GLFWwindow* window); 3693 3694 /*! @brief Returns the value of the GLFW timer. 3695 * 3696 * This function returns the value of the GLFW timer. Unless the timer has 3697 * been set using @ref glfwSetTime, the timer measures time elapsed since GLFW 3698 * was initialized. 3699 * 3700 * The resolution of the timer is system dependent, but is usually on the order 3701 * of a few micro- or nanoseconds. It uses the highest-resolution monotonic 3702 * time source on each supported platform. 3703 * 3704 * @return The current value, in seconds, or zero if an 3705 * [error](@ref error_handling) occurred. 3706 * 3707 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 3708 * 3709 * @thread_safety This function may be called from any thread. Reading of the 3710 * internal timer offset is not atomic. 3711 * 3712 * @sa @ref time 3713 * 3714 * @since Added in version 1.0. 3715 * 3716 * @ingroup input 3717 */ 3718 GLFWAPI double glfwGetTime(void); 3719 3720 /*! @brief Sets the GLFW timer. 3721 * 3722 * This function sets the value of the GLFW timer. It then continues to count 3723 * up from that value. The value must be a positive finite number less than 3724 * or equal to 18446744073.0, which is approximately 584.5 years. 3725 * 3726 * @param[in] time The new value, in seconds. 3727 * 3728 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 3729 * GLFW_INVALID_VALUE. 3730 * 3731 * @remark The upper limit of the timer is calculated as 3732 * floor((2<sup>64</sup> - 1) / 10<sup>9</sup>) and is due to implementations 3733 * storing nanoseconds in 64 bits. The limit may be increased in the future. 3734 * 3735 * @thread_safety This function may be called from any thread. Writing of the 3736 * internal timer offset is not atomic. 3737 * 3738 * @sa @ref time 3739 * 3740 * @since Added in version 2.2. 3741 * 3742 * @ingroup input 3743 */ 3744 GLFWAPI void glfwSetTime(double time); 3745 3746 /*! @brief Returns the current value of the raw timer. 3747 * 3748 * This function returns the current value of the raw timer, measured in 3749 * 1 / frequency seconds. To get the frequency, call @ref 3750 * glfwGetTimerFrequency. 3751 * 3752 * @return The value of the timer, or zero if an 3753 * [error](@ref error_handling) occurred. 3754 * 3755 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 3756 * 3757 * @thread_safety This function may be called from any thread. 3758 * 3759 * @sa @ref time 3760 * @sa glfwGetTimerFrequency 3761 * 3762 * @since Added in version 3.2. 3763 * 3764 * @ingroup input 3765 */ 3766 GLFWAPI uint64_t glfwGetTimerValue(void); 3767 3768 /*! @brief Returns the frequency, in Hz, of the raw timer. 3769 * 3770 * This function returns the frequency, in Hz, of the raw timer. 3771 * 3772 * @return The frequency of the timer, in Hz, or zero if an 3773 * [error](@ref error_handling) occurred. 3774 * 3775 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 3776 * 3777 * @thread_safety This function may be called from any thread. 3778 * 3779 * @sa @ref time 3780 * @sa glfwGetTimerValue 3781 * 3782 * @since Added in version 3.2. 3783 * 3784 * @ingroup input 3785 */ 3786 GLFWAPI uint64_t glfwGetTimerFrequency(void); 3787 3788 /*! @brief Makes the context of the specified window current for the calling 3789 * thread. 3790 * 3791 * This function makes the OpenGL or OpenGL ES context of the specified window 3792 * current on the calling thread. A context can only be made current on 3793 * a single thread at a time and each thread can have only a single current 3794 * context at a time. 3795 * 3796 * By default, making a context non-current implicitly forces a pipeline flush. 3797 * On machines that support `GL_KHR_context_flush_control`, you can control 3798 * whether a context performs this flush by setting the 3799 * [GLFW_CONTEXT_RELEASE_BEHAVIOR](@ref window_hints_ctx) window hint. 3800 * 3801 * The specified window must have an OpenGL or OpenGL ES context. Specifying 3802 * a window without a context will generate a @ref GLFW_NO_WINDOW_CONTEXT 3803 * error. 3804 * 3805 * @param[in] window The window whose context to make current, or `NULL` to 3806 * detach the current context. 3807 * 3808 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref 3809 * GLFW_NO_WINDOW_CONTEXT and @ref GLFW_PLATFORM_ERROR. 3810 * 3811 * @thread_safety This function may be called from any thread. 3812 * 3813 * @sa @ref context_current 3814 * @sa glfwGetCurrentContext 3815 * 3816 * @since Added in version 3.0. 3817 * 3818 * @ingroup context 3819 */ 3820 GLFWAPI void glfwMakeContextCurrent(GLFWwindow* window); 3821 3822 /*! @brief Returns the window whose context is current on the calling thread. 3823 * 3824 * This function returns the window whose OpenGL or OpenGL ES context is 3825 * current on the calling thread. 3826 * 3827 * @return The window whose context is current, or `NULL` if no window's 3828 * context is current. 3829 * 3830 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 3831 * 3832 * @thread_safety This function may be called from any thread. 3833 * 3834 * @sa @ref context_current 3835 * @sa glfwMakeContextCurrent 3836 * 3837 * @since Added in version 3.0. 3838 * 3839 * @ingroup context 3840 */ 3841 GLFWAPI GLFWwindow* glfwGetCurrentContext(void); 3842 3843 /*! @brief Swaps the front and back buffers of the specified window. 3844 * 3845 * This function swaps the front and back buffers of the specified window when 3846 * rendering with OpenGL or OpenGL ES. If the swap interval is greater than 3847 * zero, the GPU driver waits the specified number of screen updates before 3848 * swapping the buffers. 3849 * 3850 * The specified window must have an OpenGL or OpenGL ES context. Specifying 3851 * a window without a context will generate a @ref GLFW_NO_WINDOW_CONTEXT 3852 * error. 3853 * 3854 * This function does not apply to Vulkan. If you are rendering with Vulkan, 3855 * see `vkQueuePresentKHR` instead. 3856 * 3857 * @param[in] window The window whose buffers to swap. 3858 * 3859 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref 3860 * GLFW_NO_WINDOW_CONTEXT and @ref GLFW_PLATFORM_ERROR. 3861 * 3862 * @remark __EGL:__ The context of the specified window must be current on the 3863 * calling thread. 3864 * 3865 * @thread_safety This function may be called from any thread. 3866 * 3867 * @sa @ref buffer_swap 3868 * @sa glfwSwapInterval 3869 * 3870 * @since Added in version 1.0. 3871 * @glfw3 Added window handle parameter. 3872 * 3873 * @ingroup window 3874 */ 3875 GLFWAPI void glfwSwapBuffers(GLFWwindow* window); 3876 3877 /*! @brief Sets the swap interval for the current context. 3878 * 3879 * This function sets the swap interval for the current OpenGL or OpenGL ES 3880 * context, i.e. the number of screen updates to wait from the time @ref 3881 * glfwSwapBuffers was called before swapping the buffers and returning. This 3882 * is sometimes called _vertical synchronization_, _vertical retrace 3883 * synchronization_ or just _vsync_. 3884 * 3885 * Contexts that support either of the `WGL_EXT_swap_control_tear` and 3886 * `GLX_EXT_swap_control_tear` extensions also accept negative swap intervals, 3887 * which allow the driver to swap even if a frame arrives a little bit late. 3888 * You can check for the presence of these extensions using @ref 3889 * glfwExtensionSupported. For more information about swap tearing, see the 3890 * extension specifications. 3891 * 3892 * A context must be current on the calling thread. Calling this function 3893 * without a current context will cause a @ref GLFW_NO_CURRENT_CONTEXT error. 3894 * 3895 * This function does not apply to Vulkan. If you are rendering with Vulkan, 3896 * see the present mode of your swapchain instead. 3897 * 3898 * @param[in] interval The minimum number of screen updates to wait for 3899 * until the buffers are swapped by @ref glfwSwapBuffers. 3900 * 3901 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref 3902 * GLFW_NO_CURRENT_CONTEXT and @ref GLFW_PLATFORM_ERROR. 3903 * 3904 * @remark This function is not called during context creation, leaving the 3905 * swap interval set to whatever is the default on that platform. This is done 3906 * because some swap interval extensions used by GLFW do not allow the swap 3907 * interval to be reset to zero once it has been set to a non-zero value. 3908 * 3909 * @remark Some GPU drivers do not honor the requested swap interval, either 3910 * because of a user setting that overrides the application's request or due to 3911 * bugs in the driver. 3912 * 3913 * @thread_safety This function may be called from any thread. 3914 * 3915 * @sa @ref buffer_swap 3916 * @sa glfwSwapBuffers 3917 * 3918 * @since Added in version 1.0. 3919 * 3920 * @ingroup context 3921 */ 3922 GLFWAPI void glfwSwapInterval(int interval); 3923 3924 /*! @brief Returns whether the specified extension is available. 3925 * 3926 * This function returns whether the specified 3927 * [API extension](@ref context_glext) is supported by the current OpenGL or 3928 * OpenGL ES context. It searches both for client API extension and context 3929 * creation API extensions. 3930 * 3931 * A context must be current on the calling thread. Calling this function 3932 * without a current context will cause a @ref GLFW_NO_CURRENT_CONTEXT error. 3933 * 3934 * As this functions retrieves and searches one or more extension strings each 3935 * call, it is recommended that you cache its results if it is going to be used 3936 * frequently. The extension strings will not change during the lifetime of 3937 * a context, so there is no danger in doing this. 3938 * 3939 * This function does not apply to Vulkan. If you are using Vulkan, see @ref 3940 * glfwGetRequiredInstanceExtensions, `vkEnumerateInstanceExtensionProperties` 3941 * and `vkEnumerateDeviceExtensionProperties` instead. 3942 * 3943 * @param[in] extension The ASCII encoded name of the extension. 3944 * @return `GLFW_TRUE` if the extension is available, or `GLFW_FALSE` 3945 * otherwise. 3946 * 3947 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref 3948 * GLFW_NO_CURRENT_CONTEXT, @ref GLFW_INVALID_VALUE and @ref 3949 * GLFW_PLATFORM_ERROR. 3950 * 3951 * @thread_safety This function may be called from any thread. 3952 * 3953 * @sa @ref context_glext 3954 * @sa glfwGetProcAddress 3955 * 3956 * @since Added in version 1.0. 3957 * 3958 * @ingroup context 3959 */ 3960 GLFWAPI int glfwExtensionSupported(const char* extension); 3961 3962 /*! @brief Returns the address of the specified function for the current 3963 * context. 3964 * 3965 * This function returns the address of the specified OpenGL or OpenGL ES 3966 * [core or extension function](@ref context_glext), if it is supported 3967 * by the current context. 3968 * 3969 * A context must be current on the calling thread. Calling this function 3970 * without a current context will cause a @ref GLFW_NO_CURRENT_CONTEXT error. 3971 * 3972 * This function does not apply to Vulkan. If you are rendering with Vulkan, 3973 * see @ref glfwGetInstanceProcAddress, `vkGetInstanceProcAddr` and 3974 * `vkGetDeviceProcAddr` instead. 3975 * 3976 * @param[in] procname The ASCII encoded name of the function. 3977 * @return The address of the function, or `NULL` if an 3978 * [error](@ref error_handling) occurred. 3979 * 3980 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref 3981 * GLFW_NO_CURRENT_CONTEXT and @ref GLFW_PLATFORM_ERROR. 3982 * 3983 * @remark The address of a given function is not guaranteed to be the same 3984 * between contexts. 3985 * 3986 * @remark This function may return a non-`NULL` address despite the 3987 * associated version or extension not being available. Always check the 3988 * context version or extension string first. 3989 * 3990 * @pointer_lifetime The returned function pointer is valid until the context 3991 * is destroyed or the library is terminated. 3992 * 3993 * @thread_safety This function may be called from any thread. 3994 * 3995 * @sa @ref context_glext 3996 * @sa glfwExtensionSupported 3997 * 3998 * @since Added in version 1.0. 3999 * 4000 * @ingroup context 4001 */ 4002 GLFWAPI GLFWglproc glfwGetProcAddress(const char* procname); 4003 4004 /*! @brief Returns whether the Vulkan loader has been found. 4005 * 4006 * This function returns whether the Vulkan loader has been found. This check 4007 * is performed by @ref glfwInit. 4008 * 4009 * The availability of a Vulkan loader does not by itself guarantee that window 4010 * surface creation or even device creation is possible. Call @ref 4011 * glfwGetRequiredInstanceExtensions to check whether the extensions necessary 4012 * for Vulkan surface creation are available and @ref 4013 * glfwGetPhysicalDevicePresentationSupport to check whether a queue family of 4014 * a physical device supports image presentation. 4015 * 4016 * @return `GLFW_TRUE` if Vulkan is available, or `GLFW_FALSE` otherwise. 4017 * 4018 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 4019 * 4020 * @thread_safety This function may be called from any thread. 4021 * 4022 * @sa @ref vulkan_support 4023 * 4024 * @since Added in version 3.2. 4025 * 4026 * @ingroup vulkan 4027 */ 4028 GLFWAPI int glfwVulkanSupported(void); 4029 4030 /*! @brief Returns the Vulkan instance extensions required by GLFW. 4031 * 4032 * This function returns an array of names of Vulkan instance extensions required 4033 * by GLFW for creating Vulkan surfaces for GLFW windows. If successful, the 4034 * list will always contains `VK_KHR_surface`, so if you don't require any 4035 * additional extensions you can pass this list directly to the 4036 * `VkInstanceCreateInfo` struct. 4037 * 4038 * If Vulkan is not available on the machine, this function returns `NULL` and 4039 * generates a @ref GLFW_API_UNAVAILABLE error. Call @ref glfwVulkanSupported 4040 * to check whether Vulkan is available. 4041 * 4042 * If Vulkan is available but no set of extensions allowing window surface 4043 * creation was found, this function returns `NULL`. You may still use Vulkan 4044 * for off-screen rendering and compute work. 4045 * 4046 * @param[out] count Where to store the number of extensions in the returned 4047 * array. This is set to zero if an error occurred. 4048 * @return An array of ASCII encoded extension names, or `NULL` if an 4049 * [error](@ref error_handling) occurred. 4050 * 4051 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 4052 * GLFW_API_UNAVAILABLE. 4053 * 4054 * @remarks Additional extensions may be required by future versions of GLFW. 4055 * You should check if any extensions you wish to enable are already in the 4056 * returned array, as it is an error to specify an extension more than once in 4057 * the `VkInstanceCreateInfo` struct. 4058 * 4059 * @pointer_lifetime The returned array is allocated and freed by GLFW. You 4060 * should not free it yourself. It is guaranteed to be valid only until the 4061 * library is terminated. 4062 * 4063 * @thread_safety This function may be called from any thread. 4064 * 4065 * @sa @ref vulkan_ext 4066 * @sa glfwCreateWindowSurface 4067 * 4068 * @since Added in version 3.2. 4069 * 4070 * @ingroup vulkan 4071 */ 4072 GLFWAPI const char** glfwGetRequiredInstanceExtensions(uint32_t* count); 4073 4074 #if defined(VK_VERSION_1_0) 4075 4076 /*! @brief Returns the address of the specified Vulkan instance function. 4077 * 4078 * This function returns the address of the specified Vulkan core or extension 4079 * function for the specified instance. If instance is set to `NULL` it can 4080 * return any function exported from the Vulkan loader, including at least the 4081 * following functions: 4082 * 4083 * - `vkEnumerateInstanceExtensionProperties` 4084 * - `vkEnumerateInstanceLayerProperties` 4085 * - `vkCreateInstance` 4086 * - `vkGetInstanceProcAddr` 4087 * 4088 * If Vulkan is not available on the machine, this function returns `NULL` and 4089 * generates a @ref GLFW_API_UNAVAILABLE error. Call @ref glfwVulkanSupported 4090 * to check whether Vulkan is available. 4091 * 4092 * This function is equivalent to calling `vkGetInstanceProcAddr` with 4093 * a platform-specific query of the Vulkan loader as a fallback. 4094 * 4095 * @param[in] instance The Vulkan instance to query, or `NULL` to retrieve 4096 * functions related to instance creation. 4097 * @param[in] procname The ASCII encoded name of the function. 4098 * @return The address of the function, or `NULL` if an 4099 * [error](@ref error_handling) occurred. 4100 * 4101 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 4102 * GLFW_API_UNAVAILABLE. 4103 * 4104 * @pointer_lifetime The returned function pointer is valid until the library 4105 * is terminated. 4106 * 4107 * @thread_safety This function may be called from any thread. 4108 * 4109 * @sa @ref vulkan_proc 4110 * 4111 * @since Added in version 3.2. 4112 * 4113 * @ingroup vulkan 4114 */ 4115 GLFWAPI GLFWvkproc glfwGetInstanceProcAddress(VkInstance instance, const char* procname); 4116 4117 /*! @brief Returns whether the specified queue family can present images. 4118 * 4119 * This function returns whether the specified queue family of the specified 4120 * physical device supports presentation to the platform GLFW was built for. 4121 * 4122 * If Vulkan or the required window surface creation instance extensions are 4123 * not available on the machine, or if the specified instance was not created 4124 * with the required extensions, this function returns `GLFW_FALSE` and 4125 * generates a @ref GLFW_API_UNAVAILABLE error. Call @ref glfwVulkanSupported 4126 * to check whether Vulkan is available and @ref 4127 * glfwGetRequiredInstanceExtensions to check what instance extensions are 4128 * required. 4129 * 4130 * @param[in] instance The instance that the physical device belongs to. 4131 * @param[in] device The physical device that the queue family belongs to. 4132 * @param[in] queuefamily The index of the queue family to query. 4133 * @return `GLFW_TRUE` if the queue family supports presentation, or 4134 * `GLFW_FALSE` otherwise. 4135 * 4136 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref 4137 * GLFW_API_UNAVAILABLE and @ref GLFW_PLATFORM_ERROR. 4138 * 4139 * @thread_safety This function may be called from any thread. For 4140 * synchronization details of Vulkan objects, see the Vulkan specification. 4141 * 4142 * @sa @ref vulkan_present 4143 * 4144 * @since Added in version 3.2. 4145 * 4146 * @ingroup vulkan 4147 */ 4148 GLFWAPI int glfwGetPhysicalDevicePresentationSupport(VkInstance instance, VkPhysicalDevice device, uint32_t queuefamily); 4149 4150 /*! @brief Creates a Vulkan surface for the specified window. 4151 * 4152 * This function creates a Vulkan surface for the specified window. 4153 * 4154 * If the Vulkan loader was not found at initialization, this function returns 4155 * `VK_ERROR_INITIALIZATION_FAILED` and generates a @ref GLFW_API_UNAVAILABLE 4156 * error. Call @ref glfwVulkanSupported to check whether the Vulkan loader was 4157 * found. 4158 * 4159 * If the required window surface creation instance extensions are not 4160 * available or if the specified instance was not created with these extensions 4161 * enabled, this function returns `VK_ERROR_EXTENSION_NOT_PRESENT` and 4162 * generates a @ref GLFW_API_UNAVAILABLE error. Call @ref 4163 * glfwGetRequiredInstanceExtensions to check what instance extensions are 4164 * required. 4165 * 4166 * The window surface must be destroyed before the specified Vulkan instance. 4167 * It is the responsibility of the caller to destroy the window surface. GLFW 4168 * does not destroy it for you. Call `vkDestroySurfaceKHR` to destroy the 4169 * surface. 4170 * 4171 * @param[in] instance The Vulkan instance to create the surface in. 4172 * @param[in] window The window to create the surface for. 4173 * @param[in] allocator The allocator to use, or `NULL` to use the default 4174 * allocator. 4175 * @param[out] surface Where to store the handle of the surface. This is set 4176 * to `VK_NULL_HANDLE` if an error occurred. 4177 * @return `VK_SUCCESS` if successful, or a Vulkan error code if an 4178 * [error](@ref error_handling) occurred. 4179 * 4180 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref 4181 * GLFW_API_UNAVAILABLE and @ref GLFW_PLATFORM_ERROR. 4182 * 4183 * @remarks If an error occurs before the creation call is made, GLFW returns 4184 * the Vulkan error code most appropriate for the error. Appropriate use of 4185 * @ref glfwVulkanSupported and @ref glfwGetRequiredInstanceExtensions should 4186 * eliminate almost all occurrences of these errors. 4187 * 4188 * @thread_safety This function may be called from any thread. For 4189 * synchronization details of Vulkan objects, see the Vulkan specification. 4190 * 4191 * @sa @ref vulkan_surface 4192 * @sa glfwGetRequiredInstanceExtensions 4193 * 4194 * @since Added in version 3.2. 4195 * 4196 * @ingroup vulkan 4197 */ 4198 GLFWAPI VkResult glfwCreateWindowSurface(VkInstance instance, GLFWwindow* window, const VkAllocationCallbacks* allocator, VkSurfaceKHR* surface); 4199 4200 #endif /*VK_VERSION_1_0*/ 4201 4202 4203 /************************************************************************* 4204 * Global definition cleanup 4205 *************************************************************************/ 4206 4207 /* ------------------- BEGIN SYSTEM/COMPILER SPECIFIC -------------------- */ 4208 4209 #ifdef GLFW_WINGDIAPI_DEFINED 4210 #undef WINGDIAPI 4211 #undef GLFW_WINGDIAPI_DEFINED 4212 #endif 4213 4214 #ifdef GLFW_CALLBACK_DEFINED 4215 #undef CALLBACK 4216 #undef GLFW_CALLBACK_DEFINED 4217 #endif 4218 4219 /* -------------------- END SYSTEM/COMPILER SPECIFIC --------------------- */ 4220 4221 4222 #ifdef __cplusplus 4223 } 4224 #endif 4225 4226 #endif /* _glfw3_h_ */ 4227 4228