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