ScrapExplorer - glfw3.h
Home / ext / glfw / include / GLFW Lines: 1 | Size: 243257 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#define GLFW_DONT_CARE -1 1348 1349 1350/************************************************************************* 1351 * GLFW API types 1352 *************************************************************************/ 1353 1354/*! @brief Client API function pointer type. 1355 * 1356 * Generic function pointer used for returning client API function pointers 1357 * without forcing a cast from a regular pointer. 1358 * 1359 * @sa @ref context_glext 1360 * @sa @ref glfwGetProcAddress 1361 * 1362 * @since Added in version 3.0. 1363 * 1364 * @ingroup context 1365 */ 1366typedef void (*GLFWglproc)(void); 1367 1368/*! @brief Vulkan API function pointer type. 1369 * 1370 * Generic function pointer used for returning Vulkan API function pointers 1371 * without forcing a cast from a regular pointer. 1372 * 1373 * @sa @ref vulkan_proc 1374 * @sa @ref glfwGetInstanceProcAddress 1375 * 1376 * @since Added in version 3.2. 1377 * 1378 * @ingroup vulkan 1379 */ 1380typedef void (*GLFWvkproc)(void); 1381 1382/*! @brief Opaque monitor object. 1383 * 1384 * Opaque monitor object. 1385 * 1386 * @see @ref monitor_object 1387 * 1388 * @since Added in version 3.0. 1389 * 1390 * @ingroup monitor 1391 */ 1392typedef struct GLFWmonitor GLFWmonitor; 1393 1394/*! @brief Opaque window object. 1395 * 1396 * Opaque window object. 1397 * 1398 * @see @ref window_object 1399 * 1400 * @since Added in version 3.0. 1401 * 1402 * @ingroup window 1403 */ 1404typedef struct GLFWwindow GLFWwindow; 1405 1406/*! @brief Opaque cursor object. 1407 * 1408 * Opaque cursor object. 1409 * 1410 * @see @ref cursor_object 1411 * 1412 * @since Added in version 3.1. 1413 * 1414 * @ingroup input 1415 */ 1416typedef struct GLFWcursor GLFWcursor; 1417 1418/*! @brief The function pointer type for memory allocation callbacks. 1419 * 1420 * This is the function pointer type for memory allocation callbacks. A memory 1421 * allocation callback function has the following signature: 1422 * @code 1423 * void* function_name(size_t size, void* user) 1424 * @endcode 1425 * 1426 * This function must return either a memory block at least `size` bytes long, 1427 * or `NULL` if allocation failed. Note that not all parts of GLFW handle allocation 1428 * failures gracefully yet. 1429 * 1430 * This function must support being called during @ref glfwInit but before the library is 1431 * flagged as initialized, as well as during @ref glfwTerminate after the library is no 1432 * longer flagged as initialized. 1433 * 1434 * Any memory allocated via this function will be deallocated via the same allocator 1435 * during library termination or earlier. 1436 * 1437 * Any memory allocated via this function must be suitably aligned for any object type. 1438 * If you are using C99 or earlier, this alignment is platform-dependent but will be the 1439 * same as what `malloc` provides. If you are using C11 or later, this is the value of 1440 * `alignof(max_align_t)`. 1441 * 1442 * The size will always be greater than zero. Allocations of size zero are filtered out 1443 * before reaching the custom allocator. 1444 * 1445 * If this function returns `NULL`, GLFW will emit @ref GLFW_OUT_OF_MEMORY. 1446 * 1447 * This function must not call any GLFW function. 1448 * 1449 * @param[in] size The minimum size, in bytes, of the memory block. 1450 * @param[in] user The user-defined pointer from the allocator. 1451 * @return The address of the newly allocated memory block, or `NULL` if an 1452 * error occurred. 1453 * 1454 * @pointer_lifetime The returned memory block must be valid at least until it 1455 * is deallocated. 1456 * 1457 * @reentrancy This function should not call any GLFW function. 1458 * 1459 * @thread_safety This function must support being called from any thread that calls GLFW 1460 * functions. 1461 * 1462 * @sa @ref init_allocator 1463 * @sa @ref GLFWallocator 1464 * 1465 * @since Added in version 3.4. 1466 * 1467 * @ingroup init 1468 */ 1469typedef void* (* GLFWallocatefun)(size_t size, void* user); 1470 1471/*! @brief The function pointer type for memory reallocation callbacks. 1472 * 1473 * This is the function pointer type for memory reallocation callbacks. 1474 * A memory reallocation callback function has the following signature: 1475 * @code 1476 * void* function_name(void* block, size_t size, void* user) 1477 * @endcode 1478 * 1479 * This function must return a memory block at least `size` bytes long, or 1480 * `NULL` if allocation failed. Note that not all parts of GLFW handle allocation 1481 * failures gracefully yet. 1482 * 1483 * This function must support being called during @ref glfwInit but before the library is 1484 * flagged as initialized, as well as during @ref glfwTerminate after the library is no 1485 * longer flagged as initialized. 1486 * 1487 * Any memory allocated via this function will be deallocated via the same allocator 1488 * during library termination or earlier. 1489 * 1490 * Any memory allocated via this function must be suitably aligned for any object type. 1491 * If you are using C99 or earlier, this alignment is platform-dependent but will be the 1492 * same as what `realloc` provides. If you are using C11 or later, this is the value of 1493 * `alignof(max_align_t)`. 1494 * 1495 * The block address will never be `NULL` and the size will always be greater than zero. 1496 * Reallocations of a block to size zero are converted into deallocations before reaching 1497 * the custom allocator. Reallocations of `NULL` to a non-zero size are converted into 1498 * regular allocations before reaching the custom allocator. 1499 * 1500 * If this function returns `NULL`, GLFW will emit @ref GLFW_OUT_OF_MEMORY. 1501 * 1502 * This function must not call any GLFW function. 1503 * 1504 * @param[in] block The address of the memory block to reallocate. 1505 * @param[in] size The new minimum size, in bytes, of the memory block. 1506 * @param[in] user The user-defined pointer from the allocator. 1507 * @return The address of the newly allocated or resized memory block, or 1508 * `NULL` if an error occurred. 1509 * 1510 * @pointer_lifetime The returned memory block must be valid at least until it 1511 * is deallocated. 1512 * 1513 * @reentrancy This function should not call any GLFW function. 1514 * 1515 * @thread_safety This function must support being called from any thread that calls GLFW 1516 * functions. 1517 * 1518 * @sa @ref init_allocator 1519 * @sa @ref GLFWallocator 1520 * 1521 * @since Added in version 3.4. 1522 * 1523 * @ingroup init 1524 */ 1525typedef void* (* GLFWreallocatefun)(void* block, size_t size, void* user); 1526 1527/*! @brief The function pointer type for memory deallocation callbacks. 1528 * 1529 * This is the function pointer type for memory deallocation callbacks. 1530 * A memory deallocation callback function has the following signature: 1531 * @code 1532 * void function_name(void* block, void* user) 1533 * @endcode 1534 * 1535 * This function may deallocate the specified memory block. This memory block 1536 * will have been allocated with the same allocator. 1537 * 1538 * This function must support being called during @ref glfwInit but before the library is 1539 * flagged as initialized, as well as during @ref glfwTerminate after the library is no 1540 * longer flagged as initialized. 1541 * 1542 * The block address will never be `NULL`. Deallocations of `NULL` are filtered out 1543 * before reaching the custom allocator. 1544 * 1545 * If this function returns `NULL`, GLFW will emit @ref GLFW_OUT_OF_MEMORY. 1546 * 1547 * This function must not call any GLFW function. 1548 * 1549 * @param[in] block The address of the memory block to deallocate. 1550 * @param[in] user The user-defined pointer from the allocator. 1551 * 1552 * @pointer_lifetime The specified memory block will not be accessed by GLFW 1553 * after this function is called. 1554 * 1555 * @reentrancy This function should not call any GLFW function. 1556 * 1557 * @thread_safety This function must support being called from any thread that calls GLFW 1558 * functions. 1559 * 1560 * @sa @ref init_allocator 1561 * @sa @ref GLFWallocator 1562 * 1563 * @since Added in version 3.4. 1564 * 1565 * @ingroup init 1566 */ 1567typedef void (* GLFWdeallocatefun)(void* block, void* user); 1568 1569/*! @brief The function pointer type for error callbacks. 1570 * 1571 * This is the function pointer type for error callbacks. An error callback 1572 * function has the following signature: 1573 * @code 1574 * void callback_name(int error_code, const char* description) 1575 * @endcode 1576 * 1577 * @param[in] error_code An [error code](@ref errors). Future releases may add 1578 * more error codes. 1579 * @param[in] description A UTF-8 encoded string describing the error. 1580 * 1581 * @pointer_lifetime The error description string is valid until the callback 1582 * function returns. 1583 * 1584 * @sa @ref error_handling 1585 * @sa @ref glfwSetErrorCallback 1586 * 1587 * @since Added in version 3.0. 1588 * 1589 * @ingroup init 1590 */ 1591typedef void (* GLFWerrorfun)(int error_code, const char* description); 1592 1593/*! @brief The function pointer type for window position callbacks. 1594 * 1595 * This is the function pointer type for window position callbacks. A window 1596 * position callback function has the following signature: 1597 * @code 1598 * void callback_name(GLFWwindow* window, int xpos, int ypos) 1599 * @endcode 1600 * 1601 * @param[in] window The window that was moved. 1602 * @param[in] xpos The new x-coordinate, in screen coordinates, of the 1603 * upper-left corner of the content area of the window. 1604 * @param[in] ypos The new y-coordinate, in screen coordinates, of the 1605 * upper-left corner of the content area of the window. 1606 * 1607 * @sa @ref window_pos 1608 * @sa @ref glfwSetWindowPosCallback 1609 * 1610 * @since Added in version 3.0. 1611 * 1612 * @ingroup window 1613 */ 1614typedef void (* GLFWwindowposfun)(GLFWwindow* window, int xpos, int ypos); 1615 1616/*! @brief The function pointer type for window size callbacks. 1617 * 1618 * This is the function pointer type for window size callbacks. A window size 1619 * callback function has the following signature: 1620 * @code 1621 * void callback_name(GLFWwindow* window, int width, int height) 1622 * @endcode 1623 * 1624 * @param[in] window The window that was resized. 1625 * @param[in] width The new width, in screen coordinates, of the window. 1626 * @param[in] height The new height, in screen coordinates, of the window. 1627 * 1628 * @sa @ref window_size 1629 * @sa @ref glfwSetWindowSizeCallback 1630 * 1631 * @since Added in version 1.0. 1632 * __GLFW 3:__ Added window handle parameter. 1633 * 1634 * @ingroup window 1635 */ 1636typedef void (* GLFWwindowsizefun)(GLFWwindow* window, int width, int height); 1637 1638/*! @brief The function pointer type for window close callbacks. 1639 * 1640 * This is the function pointer type for window close callbacks. A window 1641 * close callback function has the following signature: 1642 * @code 1643 * void function_name(GLFWwindow* window) 1644 * @endcode 1645 * 1646 * @param[in] window The window that the user attempted to close. 1647 * 1648 * @sa @ref window_close 1649 * @sa @ref glfwSetWindowCloseCallback 1650 * 1651 * @since Added in version 2.5. 1652 * __GLFW 3:__ Added window handle parameter. 1653 * 1654 * @ingroup window 1655 */ 1656typedef void (* GLFWwindowclosefun)(GLFWwindow* window); 1657 1658/*! @brief The function pointer type for window content refresh callbacks. 1659 * 1660 * This is the function pointer type for window content refresh callbacks. 1661 * A window content refresh callback function has the following signature: 1662 * @code 1663 * void function_name(GLFWwindow* window); 1664 * @endcode 1665 * 1666 * @param[in] window The window whose content needs to be refreshed. 1667 * 1668 * @sa @ref window_refresh 1669 * @sa @ref glfwSetWindowRefreshCallback 1670 * 1671 * @since Added in version 2.5. 1672 * __GLFW 3:__ Added window handle parameter. 1673 * 1674 * @ingroup window 1675 */ 1676typedef void (* GLFWwindowrefreshfun)(GLFWwindow* window); 1677 1678/*! @brief The function pointer type for window focus callbacks. 1679 * 1680 * This is the function pointer type for window focus callbacks. A window 1681 * focus callback function has the following signature: 1682 * @code 1683 * void function_name(GLFWwindow* window, int focused) 1684 * @endcode 1685 * 1686 * @param[in] window The window that gained or lost input focus. 1687 * @param[in] focused `GLFW_TRUE` if the window was given input focus, or 1688 * `GLFW_FALSE` if it lost it. 1689 * 1690 * @sa @ref window_focus 1691 * @sa @ref glfwSetWindowFocusCallback 1692 * 1693 * @since Added in version 3.0. 1694 * 1695 * @ingroup window 1696 */ 1697typedef void (* GLFWwindowfocusfun)(GLFWwindow* window, int focused); 1698 1699/*! @brief The function pointer type for window iconify callbacks. 1700 * 1701 * This is the function pointer type for window iconify callbacks. A window 1702 * iconify callback function has the following signature: 1703 * @code 1704 * void function_name(GLFWwindow* window, int iconified) 1705 * @endcode 1706 * 1707 * @param[in] window The window that was iconified or restored. 1708 * @param[in] iconified `GLFW_TRUE` if the window was iconified, or 1709 * `GLFW_FALSE` if it was restored. 1710 * 1711 * @sa @ref window_iconify 1712 * @sa @ref glfwSetWindowIconifyCallback 1713 * 1714 * @since Added in version 3.0. 1715 * 1716 * @ingroup window 1717 */ 1718typedef void (* GLFWwindowiconifyfun)(GLFWwindow* window, int iconified); 1719 1720/*! @brief The function pointer type for window maximize callbacks. 1721 * 1722 * This is the function pointer type for window maximize callbacks. A window 1723 * maximize callback function has the following signature: 1724 * @code 1725 * void function_name(GLFWwindow* window, int maximized) 1726 * @endcode 1727 * 1728 * @param[in] window The window that was maximized or restored. 1729 * @param[in] maximized `GLFW_TRUE` if the window was maximized, or 1730 * `GLFW_FALSE` if it was restored. 1731 * 1732 * @sa @ref window_maximize 1733 * @sa glfwSetWindowMaximizeCallback 1734 * 1735 * @since Added in version 3.3. 1736 * 1737 * @ingroup window 1738 */ 1739typedef void (* GLFWwindowmaximizefun)(GLFWwindow* window, int maximized); 1740 1741/*! @brief The function pointer type for framebuffer size callbacks. 1742 * 1743 * This is the function pointer type for framebuffer size callbacks. 1744 * A framebuffer size callback function has the following signature: 1745 * @code 1746 * void function_name(GLFWwindow* window, int width, int height) 1747 * @endcode 1748 * 1749 * @param[in] window The window whose framebuffer was resized. 1750 * @param[in] width The new width, in pixels, of the framebuffer. 1751 * @param[in] height The new height, in pixels, of the framebuffer. 1752 * 1753 * @sa @ref window_fbsize 1754 * @sa @ref glfwSetFramebufferSizeCallback 1755 * 1756 * @since Added in version 3.0. 1757 * 1758 * @ingroup window 1759 */ 1760typedef void (* GLFWframebuffersizefun)(GLFWwindow* window, int width, int height); 1761 1762/*! @brief The function pointer type for window content scale callbacks. 1763 * 1764 * This is the function pointer type for window content scale callbacks. 1765 * A window content scale callback function has the following signature: 1766 * @code 1767 * void function_name(GLFWwindow* window, float xscale, float yscale) 1768 * @endcode 1769 * 1770 * @param[in] window The window whose content scale changed. 1771 * @param[in] xscale The new x-axis content scale of the window. 1772 * @param[in] yscale The new y-axis content scale of the window. 1773 * 1774 * @sa @ref window_scale 1775 * @sa @ref glfwSetWindowContentScaleCallback 1776 * 1777 * @since Added in version 3.3. 1778 * 1779 * @ingroup window 1780 */ 1781typedef void (* GLFWwindowcontentscalefun)(GLFWwindow* window, float xscale, float yscale); 1782 1783/*! @brief The function pointer type for mouse button callbacks. 1784 * 1785 * This is the function pointer type for mouse button callback functions. 1786 * A mouse button callback function has the following signature: 1787 * @code 1788 * void function_name(GLFWwindow* window, int button, int action, int mods) 1789 * @endcode 1790 * 1791 * @param[in] window The window that received the event. 1792 * @param[in] button The [mouse button](@ref buttons) that was pressed or 1793 * released. 1794 * @param[in] action One of `GLFW_PRESS` or `GLFW_RELEASE`. Future releases 1795 * may add more actions. 1796 * @param[in] mods Bit field describing which [modifier keys](@ref mods) were 1797 * held down. 1798 * 1799 * @sa @ref input_mouse_button 1800 * @sa @ref glfwSetMouseButtonCallback 1801 * 1802 * @since Added in version 1.0. 1803 * __GLFW 3:__ Added window handle and modifier mask parameters. 1804 * 1805 * @ingroup input 1806 */ 1807typedef void (* GLFWmousebuttonfun)(GLFWwindow* window, int button, int action, int mods); 1808 1809/*! @brief The function pointer type for cursor position callbacks. 1810 * 1811 * This is the function pointer type for cursor position callbacks. A cursor 1812 * position callback function has the following signature: 1813 * @code 1814 * void function_name(GLFWwindow* window, double xpos, double ypos); 1815 * @endcode 1816 * 1817 * @param[in] window The window that received the event. 1818 * @param[in] xpos The new cursor x-coordinate, relative to the left edge of 1819 * the content area. 1820 * @param[in] ypos The new cursor y-coordinate, relative to the top edge of the 1821 * content area. 1822 * 1823 * @sa @ref cursor_pos 1824 * @sa @ref glfwSetCursorPosCallback 1825 * 1826 * @since Added in version 3.0. Replaces `GLFWmouseposfun`. 1827 * 1828 * @ingroup input 1829 */ 1830typedef void (* GLFWcursorposfun)(GLFWwindow* window, double xpos, double ypos); 1831 1832/*! @brief The function pointer type for cursor enter/leave callbacks. 1833 * 1834 * This is the function pointer type for cursor enter/leave callbacks. 1835 * A cursor enter/leave callback function has the following signature: 1836 * @code 1837 * void function_name(GLFWwindow* window, int entered) 1838 * @endcode 1839 * 1840 * @param[in] window The window that received the event. 1841 * @param[in] entered `GLFW_TRUE` if the cursor entered the window's content 1842 * area, or `GLFW_FALSE` if it left it. 1843 * 1844 * @sa @ref cursor_enter 1845 * @sa @ref glfwSetCursorEnterCallback 1846 * 1847 * @since Added in version 3.0. 1848 * 1849 * @ingroup input 1850 */ 1851typedef void (* GLFWcursorenterfun)(GLFWwindow* window, int entered); 1852 1853/*! @brief The function pointer type for scroll callbacks. 1854 * 1855 * This is the function pointer type for scroll callbacks. A scroll callback 1856 * function has the following signature: 1857 * @code 1858 * void function_name(GLFWwindow* window, double xoffset, double yoffset) 1859 * @endcode 1860 * 1861 * @param[in] window The window that received the event. 1862 * @param[in] xoffset The scroll offset along the x-axis. 1863 * @param[in] yoffset The scroll offset along the y-axis. 1864 * 1865 * @sa @ref scrolling 1866 * @sa @ref glfwSetScrollCallback 1867 * 1868 * @since Added in version 3.0. Replaces `GLFWmousewheelfun`. 1869 * 1870 * @ingroup input 1871 */ 1872typedef void (* GLFWscrollfun)(GLFWwindow* window, double xoffset, double yoffset); 1873 1874/*! @brief The function pointer type for keyboard key callbacks. 1875 * 1876 * This is the function pointer type for keyboard key callbacks. A keyboard 1877 * key callback function has the following signature: 1878 * @code 1879 * void function_name(GLFWwindow* window, int key, int scancode, int action, int mods) 1880 * @endcode 1881 * 1882 * @param[in] window The window that received the event. 1883 * @param[in] key The [keyboard key](@ref keys) that was pressed or released. 1884 * @param[in] scancode The platform-specific scancode of the key. 1885 * @param[in] action `GLFW_PRESS`, `GLFW_RELEASE` or `GLFW_REPEAT`. Future 1886 * releases may add more actions. 1887 * @param[in] mods Bit field describing which [modifier keys](@ref mods) were 1888 * held down. 1889 * 1890 * @sa @ref input_key 1891 * @sa @ref glfwSetKeyCallback 1892 * 1893 * @since Added in version 1.0. 1894 * __GLFW 3:__ Added window handle, scancode and modifier mask parameters. 1895 * 1896 * @ingroup input 1897 */ 1898typedef void (* GLFWkeyfun)(GLFWwindow* window, int key, int scancode, int action, int mods); 1899 1900/*! @brief The function pointer type for Unicode character callbacks. 1901 * 1902 * This is the function pointer type for Unicode character callbacks. 1903 * A Unicode character callback function has the following signature: 1904 * @code 1905 * void function_name(GLFWwindow* window, unsigned int codepoint) 1906 * @endcode 1907 * 1908 * @param[in] window The window that received the event. 1909 * @param[in] codepoint The Unicode code point of the character. 1910 * 1911 * @sa @ref input_char 1912 * @sa @ref glfwSetCharCallback 1913 * 1914 * @since Added in version 2.4. 1915 * __GLFW 3:__ Added window handle parameter. 1916 * 1917 * @ingroup input 1918 */ 1919typedef void (* GLFWcharfun)(GLFWwindow* window, unsigned int codepoint); 1920 1921/*! @brief The function pointer type for Unicode character with modifiers 1922 * callbacks. 1923 * 1924 * This is the function pointer type for Unicode character with modifiers 1925 * callbacks. It is called for each input character, regardless of what 1926 * modifier keys are held down. A Unicode character with modifiers callback 1927 * function has the following signature: 1928 * @code 1929 * void function_name(GLFWwindow* window, unsigned int codepoint, int mods) 1930 * @endcode 1931 * 1932 * @param[in] window The window that received the event. 1933 * @param[in] codepoint The Unicode code point of the character. 1934 * @param[in] mods Bit field describing which [modifier keys](@ref mods) were 1935 * held down. 1936 * 1937 * @sa @ref input_char 1938 * @sa @ref glfwSetCharModsCallback 1939 * 1940 * @deprecated Scheduled for removal in version 4.0. 1941 * 1942 * @since Added in version 3.1. 1943 * 1944 * @ingroup input 1945 */ 1946typedef void (* GLFWcharmodsfun)(GLFWwindow* window, unsigned int codepoint, int mods); 1947 1948/*! @brief The function pointer type for path drop callbacks. 1949 * 1950 * This is the function pointer type for path drop callbacks. A path drop 1951 * callback function has the following signature: 1952 * @code 1953 * void function_name(GLFWwindow* window, int path_count, const char* paths[]) 1954 * @endcode 1955 * 1956 * @param[in] window The window that received the event. 1957 * @param[in] path_count The number of dropped paths. 1958 * @param[in] paths The UTF-8 encoded file and/or directory path names. 1959 * 1960 * @pointer_lifetime The path array and its strings are valid until the 1961 * callback function returns. 1962 * 1963 * @sa @ref path_drop 1964 * @sa @ref glfwSetDropCallback 1965 * 1966 * @since Added in version 3.1. 1967 * 1968 * @ingroup input 1969 */ 1970typedef void (* GLFWdropfun)(GLFWwindow* window, int path_count, const char* paths[]); 1971 1972/*! @brief The function pointer type for monitor configuration callbacks. 1973 * 1974 * This is the function pointer type for monitor configuration callbacks. 1975 * A monitor callback function has the following signature: 1976 * @code 1977 * void function_name(GLFWmonitor* monitor, int event) 1978 * @endcode 1979 * 1980 * @param[in] monitor The monitor that was connected or disconnected. 1981 * @param[in] event One of `GLFW_CONNECTED` or `GLFW_DISCONNECTED`. Future 1982 * releases may add more events. 1983 * 1984 * @sa @ref monitor_event 1985 * @sa @ref glfwSetMonitorCallback 1986 * 1987 * @since Added in version 3.0. 1988 * 1989 * @ingroup monitor 1990 */ 1991typedef void (* GLFWmonitorfun)(GLFWmonitor* monitor, int event); 1992 1993/*! @brief The function pointer type for joystick configuration callbacks. 1994 * 1995 * This is the function pointer type for joystick configuration callbacks. 1996 * A joystick configuration callback function has the following signature: 1997 * @code 1998 * void function_name(int jid, int event) 1999 * @endcode 2000 * 2001 * @param[in] jid The joystick that was connected or disconnected. 2002 * @param[in] event One of `GLFW_CONNECTED` or `GLFW_DISCONNECTED`. Future 2003 * releases may add more events. 2004 * 2005 * @sa @ref joystick_event 2006 * @sa @ref glfwSetJoystickCallback 2007 * 2008 * @since Added in version 3.2. 2009 * 2010 * @ingroup input 2011 */ 2012typedef void (* GLFWjoystickfun)(int jid, int event); 2013 2014/*! @brief Video mode type. 2015 * 2016 * This describes a single video mode. 2017 * 2018 * @sa @ref monitor_modes 2019 * @sa @ref glfwGetVideoMode 2020 * @sa @ref glfwGetVideoModes 2021 * 2022 * @since Added in version 1.0. 2023 * __GLFW 3:__ Added refresh rate member. 2024 * 2025 * @ingroup monitor 2026 */ 2027typedef struct GLFWvidmode 2028{ 2029 /*! The width, in screen coordinates, of the video mode. 2030 */ 2031 int width; 2032 /*! The height, in screen coordinates, of the video mode. 2033 */ 2034 int height; 2035 /*! The bit depth of the red channel of the video mode. 2036 */ 2037 int redBits; 2038 /*! The bit depth of the green channel of the video mode. 2039 */ 2040 int greenBits; 2041 /*! The bit depth of the blue channel of the video mode. 2042 */ 2043 int blueBits; 2044 /*! The refresh rate, in Hz, of the video mode. 2045 */ 2046 int refreshRate; 2047} GLFWvidmode; 2048 2049/*! @brief Gamma ramp. 2050 * 2051 * This describes the gamma ramp for a monitor. 2052 * 2053 * @sa @ref monitor_gamma 2054 * @sa @ref glfwGetGammaRamp 2055 * @sa @ref glfwSetGammaRamp 2056 * 2057 * @since Added in version 3.0. 2058 * 2059 * @ingroup monitor 2060 */ 2061typedef struct GLFWgammaramp 2062{ 2063 /*! An array of value describing the response of the red channel. 2064 */ 2065 unsigned short* red; 2066 /*! An array of value describing the response of the green channel. 2067 */ 2068 unsigned short* green; 2069 /*! An array of value describing the response of the blue channel. 2070 */ 2071 unsigned short* blue; 2072 /*! The number of elements in each array. 2073 */ 2074 unsigned int size; 2075} GLFWgammaramp; 2076 2077/*! @brief Image data. 2078 * 2079 * This describes a single 2D image. See the documentation for each related 2080 * function what the expected pixel format is. 2081 * 2082 * @sa @ref cursor_custom 2083 * @sa @ref window_icon 2084 * 2085 * @since Added in version 2.1. 2086 * __GLFW 3:__ Removed format and bytes-per-pixel members. 2087 * 2088 * @ingroup window 2089 */ 2090typedef struct GLFWimage 2091{ 2092 /*! The width, in pixels, of this image. 2093 */ 2094 int width; 2095 /*! The height, in pixels, of this image. 2096 */ 2097 int height; 2098 /*! The pixel data of this image, arranged left-to-right, top-to-bottom. 2099 */ 2100 unsigned char* pixels; 2101} GLFWimage; 2102 2103/*! @brief Gamepad input state 2104 * 2105 * This describes the input state of a gamepad. 2106 * 2107 * @sa @ref gamepad 2108 * @sa @ref glfwGetGamepadState 2109 * 2110 * @since Added in version 3.3. 2111 * 2112 * @ingroup input 2113 */ 2114typedef struct GLFWgamepadstate 2115{ 2116 /*! The states of each [gamepad button](@ref gamepad_buttons), `GLFW_PRESS` 2117 * or `GLFW_RELEASE`. 2118 */ 2119 unsigned char buttons[15]; 2120 /*! The states of each [gamepad axis](@ref gamepad_axes), in the range -1.0 2121 * to 1.0 inclusive. 2122 */ 2123 float axes[6]; 2124} GLFWgamepadstate; 2125 2126/*! @brief Custom heap memory allocator. 2127 * 2128 * This describes a custom heap memory allocator for GLFW. To set an allocator, pass it 2129 * to @ref glfwInitAllocator before initializing the library. 2130 * 2131 * @sa @ref init_allocator 2132 * @sa @ref glfwInitAllocator 2133 * 2134 * @since Added in version 3.4. 2135 * 2136 * @ingroup init 2137 */ 2138typedef struct GLFWallocator 2139{ 2140 /*! The memory allocation function. See @ref GLFWallocatefun for details about 2141 * allocation function. 2142 */ 2143 GLFWallocatefun allocate; 2144 /*! The memory reallocation function. See @ref GLFWreallocatefun for details about 2145 * reallocation function. 2146 */ 2147 GLFWreallocatefun reallocate; 2148 /*! The memory deallocation function. See @ref GLFWdeallocatefun for details about 2149 * deallocation function. 2150 */ 2151 GLFWdeallocatefun deallocate; 2152 /*! The user pointer for this custom allocator. This value will be passed to the 2153 * allocator functions. 2154 */ 2155 void* user; 2156} GLFWallocator; 2157 2158 2159/************************************************************************* 2160 * GLFW API functions 2161 *************************************************************************/ 2162 2163/*! @brief Initializes the GLFW library. 2164 * 2165 * This function initializes the GLFW library. Before most GLFW functions can 2166 * be used, GLFW must be initialized, and before an application terminates GLFW 2167 * should be terminated in order to free any resources allocated during or 2168 * after initialization. 2169 * 2170 * If this function fails, it calls @ref glfwTerminate before returning. If it 2171 * succeeds, you should call @ref glfwTerminate before the application exits. 2172 * 2173 * Additional calls to this function after successful initialization but before 2174 * termination will return `GLFW_TRUE` immediately. 2175 * 2176 * The @ref GLFW_PLATFORM init hint controls which platforms are considered during 2177 * initialization. This also depends on which platforms the library was compiled to 2178 * support. 2179 * 2180 * @return `GLFW_TRUE` if successful, or `GLFW_FALSE` if an 2181 * [error](@ref error_handling) occurred. 2182 * 2183 * @errors Possible errors include @ref GLFW_PLATFORM_UNAVAILABLE and @ref 2184 * GLFW_PLATFORM_ERROR. 2185 * 2186 * @remark __macOS:__ This function will change the current directory of the 2187 * application to the `Contents/Resources` subdirectory of the application's 2188 * bundle, if present. This can be disabled with the @ref 2189 * GLFW_COCOA_CHDIR_RESOURCES init hint. 2190 * 2191 * @remark __macOS:__ This function will create the main menu and dock icon for the 2192 * application. If GLFW finds a `MainMenu.nib` it is loaded and assumed to 2193 * contain a menu bar. Otherwise a minimal menu bar is created manually with 2194 * common commands like Hide, Quit and About. The About entry opens a minimal 2195 * about dialog with information from the application's bundle. The menu bar 2196 * and dock icon can be disabled entirely with the @ref GLFW_COCOA_MENUBAR init 2197 * hint. 2198 * 2199 * @remark __Wayland, X11:__ If the library was compiled with support for both 2200 * Wayland and X11, and the @ref GLFW_PLATFORM init hint is set to 2201 * `GLFW_ANY_PLATFORM`, the `XDG_SESSION_TYPE` environment variable affects 2202 * which platform is picked. If the environment variable is not set, or is set 2203 * to something other than `wayland` or `x11`, the regular detection mechanism 2204 * will be used instead. 2205 * 2206 * @remark __X11:__ This function will set the `LC_CTYPE` category of the 2207 * application locale according to the current environment if that category is 2208 * still "C". This is because the "C" locale breaks Unicode text input. 2209 * 2210 * @thread_safety This function must only be called from the main thread. 2211 * 2212 * @sa @ref intro_init 2213 * @sa @ref glfwInitHint 2214 * @sa @ref glfwInitAllocator 2215 * @sa @ref glfwTerminate 2216 * 2217 * @since Added in version 1.0. 2218 * 2219 * @ingroup init 2220 */ 2221GLFWAPI int glfwInit(void); 2222 2223/*! @brief Terminates the GLFW library. 2224 * 2225 * This function destroys all remaining windows and cursors, restores any 2226 * modified gamma ramps and frees any other allocated resources. Once this 2227 * function is called, you must again call @ref glfwInit successfully before 2228 * you will be able to use most GLFW functions. 2229 * 2230 * If GLFW has been successfully initialized, this function should be called 2231 * before the application exits. If initialization fails, there is no need to 2232 * call this function, as it is called by @ref glfwInit before it returns 2233 * failure. 2234 * 2235 * This function has no effect if GLFW is not initialized. 2236 * 2237 * @errors Possible errors include @ref GLFW_PLATFORM_ERROR. 2238 * 2239 * @remark This function may be called before @ref glfwInit. 2240 * 2241 * @warning The contexts of any remaining windows must not be current on any 2242 * other thread when this function is called. 2243 * 2244 * @reentrancy This function must not be called from a callback. 2245 * 2246 * @thread_safety This function must only be called from the main thread. 2247 * 2248 * @sa @ref intro_init 2249 * @sa @ref glfwInit 2250 * 2251 * @since Added in version 1.0. 2252 * 2253 * @ingroup init 2254 */ 2255GLFWAPI void glfwTerminate(void); 2256 2257/*! @brief Sets the specified init hint to the desired value. 2258 * 2259 * This function sets hints for the next initialization of GLFW. 2260 * 2261 * The values you set hints to are never reset by GLFW, but they only take 2262 * effect during initialization. Once GLFW has been initialized, any values 2263 * you set will be ignored until the library is terminated and initialized 2264 * again. 2265 * 2266 * Some hints are platform specific. These may be set on any platform but they 2267 * will only affect their specific platform. Other platforms will ignore them. 2268 * Setting these hints requires no platform specific headers or functions. 2269 * 2270 * @param[in] hint The [init hint](@ref init_hints) to set. 2271 * @param[in] value The new value of the init hint. 2272 * 2273 * @errors Possible errors include @ref GLFW_INVALID_ENUM and @ref 2274 * GLFW_INVALID_VALUE. 2275 * 2276 * @remarks This function may be called before @ref glfwInit. 2277 * 2278 * @thread_safety This function must only be called from the main thread. 2279 * 2280 * @sa init_hints 2281 * @sa glfwInit 2282 * 2283 * @since Added in version 3.3. 2284 * 2285 * @ingroup init 2286 */ 2287GLFWAPI void glfwInitHint(int hint, int value); 2288 2289/*! @brief Sets the init allocator to the desired value. 2290 * 2291 * To use the default allocator, call this function with a `NULL` argument. 2292 * 2293 * If you specify an allocator struct, every member must be a valid function 2294 * pointer. If any member is `NULL`, this function will emit @ref 2295 * GLFW_INVALID_VALUE and the init allocator will be unchanged. 2296 * 2297 * The functions in the allocator must fulfil a number of requirements. See the 2298 * documentation for @ref GLFWallocatefun, @ref GLFWreallocatefun and @ref 2299 * GLFWdeallocatefun for details. 2300 * 2301 * @param[in] allocator The allocator to use at the next initialization, or 2302 * `NULL` to use the default one. 2303 * 2304 * @errors Possible errors include @ref GLFW_INVALID_VALUE. 2305 * 2306 * @pointer_lifetime The specified allocator is copied before this function 2307 * returns. 2308 * 2309 * @thread_safety This function must only be called from the main thread. 2310 * 2311 * @sa @ref init_allocator 2312 * @sa @ref glfwInit 2313 * 2314 * @since Added in version 3.4. 2315 * 2316 * @ingroup init 2317 */ 2318GLFWAPI void glfwInitAllocator(const GLFWallocator* allocator); 2319 2320#if defined(VK_VERSION_1_0) 2321 2322/*! @brief Sets the desired Vulkan `vkGetInstanceProcAddr` function. 2323 * 2324 * This function sets the `vkGetInstanceProcAddr` function that GLFW will use for all 2325 * Vulkan related entry point queries. 2326 * 2327 * This feature is mostly useful on macOS, if your copy of the Vulkan loader is in 2328 * a location where GLFW cannot find it through dynamic loading, or if you are still 2329 * using the static library version of the loader. 2330 * 2331 * If set to `NULL`, GLFW will try to load the Vulkan loader dynamically by its standard 2332 * name and get this function from there. This is the default behavior. 2333 * 2334 * The standard name of the loader is `vulkan-1.dll` on Windows, `libvulkan.so.1` on 2335 * Linux and other Unix-like systems and `libvulkan.1.dylib` on macOS. If your code is 2336 * also loading it via these names then you probably don't need to use this function. 2337 * 2338 * The function address you set is never reset by GLFW, but it only takes effect during 2339 * initialization. Once GLFW has been initialized, any updates will be ignored until the 2340 * library is terminated and initialized again. 2341 * 2342 * @param[in] loader The address of the function to use, or `NULL`. 2343 * 2344 * @par Loader function signature 2345 * @code 2346 * PFN_vkVoidFunction vkGetInstanceProcAddr(VkInstance instance, const char* name) 2347 * @endcode 2348 * For more information about this function, see the 2349 * [Vulkan Registry](https://www.khronos.org/registry/vulkan/). 2350 * 2351 * @errors None. 2352 * 2353 * @remark This function may be called before @ref glfwInit. 2354 * 2355 * @thread_safety This function must only be called from the main thread. 2356 * 2357 * @sa @ref vulkan_loader 2358 * @sa @ref glfwInit 2359 * 2360 * @since Added in version 3.4. 2361 * 2362 * @ingroup init 2363 */ 2364GLFWAPI void glfwInitVulkanLoader(PFN_vkGetInstanceProcAddr loader); 2365 2366#endif /*VK_VERSION_1_0*/ 2367 2368/*! @brief Retrieves the version of the GLFW library. 2369 * 2370 * This function retrieves the major, minor and revision numbers of the GLFW 2371 * library. It is intended for when you are using GLFW as a shared library and 2372 * want to ensure that you are using the minimum required version. 2373 * 2374 * Any or all of the version arguments may be `NULL`. 2375 * 2376 * @param[out] major Where to store the major version number, or `NULL`. 2377 * @param[out] minor Where to store the minor version number, or `NULL`. 2378 * @param[out] rev Where to store the revision number, or `NULL`. 2379 * 2380 * @errors None. 2381 * 2382 * @remark This function may be called before @ref glfwInit. 2383 * 2384 * @thread_safety This function may be called from any thread. 2385 * 2386 * @sa @ref intro_version 2387 * @sa @ref glfwGetVersionString 2388 * 2389 * @since Added in version 1.0. 2390 * 2391 * @ingroup init 2392 */ 2393GLFWAPI void glfwGetVersion(int* major, int* minor, int* rev); 2394 2395/*! @brief Returns a string describing the compile-time configuration. 2396 * 2397 * This function returns the compile-time generated 2398 * [version string](@ref intro_version_string) of the GLFW library binary. It describes 2399 * the version, platforms, compiler and any platform or operating system specific 2400 * compile-time options. It should not be confused with the OpenGL or OpenGL ES version 2401 * string, queried with `glGetString`. 2402 * 2403 * __Do not use the version string__ to parse the GLFW library version. The 2404 * @ref glfwGetVersion function provides the version of the running library 2405 * binary in numerical format. 2406 * 2407 * __Do not use the version string__ to parse what platforms are supported. The @ref 2408 * glfwPlatformSupported function lets you query platform support. 2409 * 2410 * @return The ASCII encoded GLFW version string. 2411 * 2412 * @errors None. 2413 * 2414 * @remark This function may be called before @ref glfwInit. 2415 * 2416 * @pointer_lifetime The returned string is static and compile-time generated. 2417 * 2418 * @thread_safety This function may be called from any thread. 2419 * 2420 * @sa @ref intro_version 2421 * @sa @ref glfwGetVersion 2422 * 2423 * @since Added in version 3.0. 2424 * 2425 * @ingroup init 2426 */ 2427GLFWAPI const char* glfwGetVersionString(void); 2428 2429/*! @brief Returns and clears the last error for the calling thread. 2430 * 2431 * This function returns and clears the [error code](@ref errors) of the last 2432 * error that occurred on the calling thread, and optionally a UTF-8 encoded 2433 * human-readable description of it. If no error has occurred since the last 2434 * call, it returns @ref GLFW_NO_ERROR (zero) and the description pointer is 2435 * set to `NULL`. 2436 * 2437 * @param[in] description Where to store the error description pointer, or `NULL`. 2438 * @return The last error code for the calling thread, or @ref GLFW_NO_ERROR 2439 * (zero). 2440 * 2441 * @errors None. 2442 * 2443 * @pointer_lifetime The returned string is allocated and freed by GLFW. You 2444 * should not free it yourself. It is guaranteed to be valid only until the 2445 * next error occurs or the library is terminated. 2446 * 2447 * @remark This function may be called before @ref glfwInit. 2448 * 2449 * @thread_safety This function may be called from any thread. 2450 * 2451 * @sa @ref error_handling 2452 * @sa @ref glfwSetErrorCallback 2453 * 2454 * @since Added in version 3.3. 2455 * 2456 * @ingroup init 2457 */ 2458GLFWAPI int glfwGetError(const char** description); 2459 2460/*! @brief Sets the error callback. 2461 * 2462 * This function sets the error callback, which is called with an error code 2463 * and a human-readable description each time a GLFW error occurs. 2464 * 2465 * The error code is set before the callback is called. Calling @ref 2466 * glfwGetError from the error callback will return the same value as the error 2467 * code argument. 2468 * 2469 * The error callback is called on the thread where the error occurred. If you 2470 * are using GLFW from multiple threads, your error callback needs to be 2471 * written accordingly. 2472 * 2473 * Because the description string may have been generated specifically for that 2474 * error, it is not guaranteed to be valid after the callback has returned. If 2475 * you wish to use it after the callback returns, you need to make a copy. 2476 * 2477 * Once set, the error callback remains set even after the library has been 2478 * terminated. 2479 * 2480 * @param[in] callback The new callback, or `NULL` to remove the currently set 2481 * callback. 2482 * @return The previously set callback, or `NULL` if no callback was set. 2483 * 2484 * @callback_signature 2485 * @code 2486 * void callback_name(int error_code, const char* description) 2487 * @endcode 2488 * For more information about the callback parameters, see the 2489 * [callback pointer type](@ref GLFWerrorfun). 2490 * 2491 * @errors None. 2492 * 2493 * @remark This function may be called before @ref glfwInit. 2494 * 2495 * @thread_safety This function must only be called from the main thread. 2496 * 2497 * @sa @ref error_handling 2498 * @sa @ref glfwGetError 2499 * 2500 * @since Added in version 3.0. 2501 * 2502 * @ingroup init 2503 */ 2504GLFWAPI GLFWerrorfun glfwSetErrorCallback(GLFWerrorfun callback); 2505 2506/*! @brief Returns the currently selected platform. 2507 * 2508 * This function returns the platform that was selected during initialization. The 2509 * returned value will be one of `GLFW_PLATFORM_WIN32`, `GLFW_PLATFORM_COCOA`, 2510 * `GLFW_PLATFORM_WAYLAND`, `GLFW_PLATFORM_X11` or `GLFW_PLATFORM_NULL`. 2511 * 2512 * @return The currently selected platform, or zero if an error occurred. 2513 * 2514 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 2515 * 2516 * @thread_safety This function may be called from any thread. 2517 * 2518 * @sa @ref platform 2519 * @sa @ref glfwPlatformSupported 2520 * 2521 * @since Added in version 3.4. 2522 * 2523 * @ingroup init 2524 */ 2525GLFWAPI int glfwGetPlatform(void); 2526 2527/*! @brief Returns whether the library includes support for the specified platform. 2528 * 2529 * This function returns whether the library was compiled with support for the specified 2530 * platform. The platform must be one of `GLFW_PLATFORM_WIN32`, `GLFW_PLATFORM_COCOA`, 2531 * `GLFW_PLATFORM_WAYLAND`, `GLFW_PLATFORM_X11` or `GLFW_PLATFORM_NULL`. 2532 * 2533 * @param[in] platform The platform to query. 2534 * @return `GLFW_TRUE` if the platform is supported, or `GLFW_FALSE` otherwise. 2535 * 2536 * @errors Possible errors include @ref GLFW_INVALID_ENUM. 2537 * 2538 * @remark This function may be called before @ref glfwInit. 2539 * 2540 * @thread_safety This function may be called from any thread. 2541 * 2542 * @sa @ref platform 2543 * @sa @ref glfwGetPlatform 2544 * 2545 * @since Added in version 3.4. 2546 * 2547 * @ingroup init 2548 */ 2549GLFWAPI int glfwPlatformSupported(int platform); 2550 2551/*! @brief Returns the currently connected monitors. 2552 * 2553 * This function returns an array of handles for all currently connected 2554 * monitors. The primary monitor is always first in the returned array. If no 2555 * monitors were found, this function returns `NULL`. 2556 * 2557 * @param[out] count Where to store the number of monitors in the returned 2558 * array. This is set to zero if an error occurred. 2559 * @return An array of monitor handles, or `NULL` if no monitors were found or 2560 * if an [error](@ref error_handling) occurred. 2561 * 2562 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 2563 * 2564 * @pointer_lifetime The returned array is allocated and freed by GLFW. You 2565 * should not free it yourself. It is guaranteed to be valid only until the 2566 * monitor configuration changes or the library is terminated. 2567 * 2568 * @thread_safety This function must only be called from the main thread. 2569 * 2570 * @sa @ref monitor_monitors 2571 * @sa @ref monitor_event 2572 * @sa @ref glfwGetPrimaryMonitor 2573 * 2574 * @since Added in version 3.0. 2575 * 2576 * @ingroup monitor 2577 */ 2578GLFWAPI GLFWmonitor** glfwGetMonitors(int* count); 2579 2580/*! @brief Returns the primary monitor. 2581 * 2582 * This function returns the primary monitor. This is usually the monitor 2583 * where elements like the task bar or global menu bar are located. 2584 * 2585 * @return The primary monitor, or `NULL` if no monitors were found or if an 2586 * [error](@ref error_handling) occurred. 2587 * 2588 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 2589 * 2590 * @thread_safety This function must only be called from the main thread. 2591 * 2592 * @remark The primary monitor is always first in the array returned by @ref 2593 * glfwGetMonitors. 2594 * 2595 * @sa @ref monitor_monitors 2596 * @sa @ref glfwGetMonitors 2597 * 2598 * @since Added in version 3.0. 2599 * 2600 * @ingroup monitor 2601 */ 2602GLFWAPI GLFWmonitor* glfwGetPrimaryMonitor(void); 2603 2604/*! @brief Returns the position of the monitor's viewport on the virtual screen. 2605 * 2606 * This function returns the position, in screen coordinates, of the upper-left 2607 * corner of the specified monitor. 2608 * 2609 * Any or all of the position arguments may be `NULL`. If an error occurs, all 2610 * non-`NULL` position arguments will be set to zero. 2611 * 2612 * @param[in] monitor The monitor to query. 2613 * @param[out] xpos Where to store the monitor x-coordinate, or `NULL`. 2614 * @param[out] ypos Where to store the monitor y-coordinate, or `NULL`. 2615 * 2616 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 2617 * GLFW_PLATFORM_ERROR. 2618 * 2619 * @thread_safety This function must only be called from the main thread. 2620 * 2621 * @sa @ref monitor_properties 2622 * 2623 * @since Added in version 3.0. 2624 * 2625 * @ingroup monitor 2626 */ 2627GLFWAPI void glfwGetMonitorPos(GLFWmonitor* monitor, int* xpos, int* ypos); 2628 2629/*! @brief Retrieves the work area of the monitor. 2630 * 2631 * This function returns the position, in screen coordinates, of the upper-left 2632 * corner of the work area of the specified monitor along with the work area 2633 * size in screen coordinates. The work area is defined as the area of the 2634 * monitor not occluded by the window system task bar where present. If no 2635 * task bar exists then the work area is the monitor resolution in screen 2636 * coordinates. 2637 * 2638 * Any or all of the position and size arguments may be `NULL`. If an error 2639 * occurs, all non-`NULL` position and size arguments will be set to zero. 2640 * 2641 * @param[in] monitor The monitor to query. 2642 * @param[out] xpos Where to store the monitor x-coordinate, or `NULL`. 2643 * @param[out] ypos Where to store the monitor y-coordinate, or `NULL`. 2644 * @param[out] width Where to store the monitor width, or `NULL`. 2645 * @param[out] height Where to store the monitor height, or `NULL`. 2646 * 2647 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 2648 * GLFW_PLATFORM_ERROR. 2649 * 2650 * @thread_safety This function must only be called from the main thread. 2651 * 2652 * @sa @ref monitor_workarea 2653 * 2654 * @since Added in version 3.3. 2655 * 2656 * @ingroup monitor 2657 */ 2658GLFWAPI void glfwGetMonitorWorkarea(GLFWmonitor* monitor, int* xpos, int* ypos, int* width, int* height); 2659 2660/*! @brief Returns the physical size of the monitor. 2661 * 2662 * This function returns the size, in millimetres, of the display area of the 2663 * specified monitor. 2664 * 2665 * Some platforms do not provide accurate monitor size information, either 2666 * because the monitor [EDID][] data is incorrect or because the driver does 2667 * not report it accurately. 2668 * 2669 * [EDID]: https://en.wikipedia.org/wiki/Extended_display_identification_data 2670 * 2671 * Any or all of the size arguments may be `NULL`. If an error occurs, all 2672 * non-`NULL` size arguments will be set to zero. 2673 * 2674 * @param[in] monitor The monitor to query. 2675 * @param[out] widthMM Where to store the width, in millimetres, of the 2676 * monitor's display area, or `NULL`. 2677 * @param[out] heightMM Where to store the height, in millimetres, of the 2678 * monitor's display area, or `NULL`. 2679 * 2680 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 2681 * 2682 * @remark __Win32:__ On Windows 8 and earlier the physical size is calculated from 2683 * the current resolution and system DPI instead of querying the monitor EDID data. 2684 * 2685 * @thread_safety This function must only be called from the main thread. 2686 * 2687 * @sa @ref monitor_properties 2688 * 2689 * @since Added in version 3.0. 2690 * 2691 * @ingroup monitor 2692 */ 2693GLFWAPI void glfwGetMonitorPhysicalSize(GLFWmonitor* monitor, int* widthMM, int* heightMM); 2694 2695/*! @brief Retrieves the content scale for the specified monitor. 2696 * 2697 * This function retrieves the content scale for the specified monitor. The 2698 * content scale is the ratio between the current DPI and the platform's 2699 * default DPI. This is especially important for text and any UI elements. If 2700 * the pixel dimensions of your UI scaled by this look appropriate on your 2701 * machine then it should appear at a reasonable size on other machines 2702 * regardless of their DPI and scaling settings. This relies on the system DPI 2703 * and scaling settings being somewhat correct. 2704 * 2705 * The content scale may depend on both the monitor resolution and pixel 2706 * density and on user settings. It may be very different from the raw DPI 2707 * calculated from the physical size and current resolution. 2708 * 2709 * @param[in] monitor The monitor to query. 2710 * @param[out] xscale Where to store the x-axis content scale, or `NULL`. 2711 * @param[out] yscale Where to store the y-axis content scale, or `NULL`. 2712 * 2713 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 2714 * GLFW_PLATFORM_ERROR. 2715 * 2716 * @remark __Wayland:__ Fractional scaling information is not yet available for 2717 * monitors, so this function only returns integer content scales. 2718 * 2719 * @thread_safety This function must only be called from the main thread. 2720 * 2721 * @sa @ref monitor_scale 2722 * @sa @ref glfwGetWindowContentScale 2723 * 2724 * @since Added in version 3.3. 2725 * 2726 * @ingroup monitor 2727 */ 2728GLFWAPI void glfwGetMonitorContentScale(GLFWmonitor* monitor, float* xscale, float* yscale); 2729 2730/*! @brief Returns the name of the specified monitor. 2731 * 2732 * This function returns a human-readable name, encoded as UTF-8, of the 2733 * specified monitor. The name typically reflects the make and model of the 2734 * monitor and is not guaranteed to be unique among the connected monitors. 2735 * 2736 * @param[in] monitor The monitor to query. 2737 * @return The UTF-8 encoded name of the monitor, or `NULL` if an 2738 * [error](@ref error_handling) occurred. 2739 * 2740 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 2741 * 2742 * @pointer_lifetime The returned string is allocated and freed by GLFW. You 2743 * should not free it yourself. It is valid until the specified monitor is 2744 * disconnected or the library is terminated. 2745 * 2746 * @thread_safety This function must only be called from the main thread. 2747 * 2748 * @sa @ref monitor_properties 2749 * 2750 * @since Added in version 3.0. 2751 * 2752 * @ingroup monitor 2753 */ 2754GLFWAPI const char* glfwGetMonitorName(GLFWmonitor* monitor); 2755 2756/*! @brief Sets the user pointer of the specified monitor. 2757 * 2758 * This function sets the user-defined pointer of the specified monitor. The 2759 * current value is retained until the monitor is disconnected. The initial 2760 * value is `NULL`. 2761 * 2762 * This function may be called from the monitor callback, even for a monitor 2763 * that is being disconnected. 2764 * 2765 * @param[in] monitor The monitor whose pointer to set. 2766 * @param[in] pointer The new value. 2767 * 2768 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 2769 * 2770 * @thread_safety This function may be called from any thread. Access is not 2771 * synchronized. 2772 * 2773 * @sa @ref monitor_userptr 2774 * @sa @ref glfwGetMonitorUserPointer 2775 * 2776 * @since Added in version 3.3. 2777 * 2778 * @ingroup monitor 2779 */ 2780GLFWAPI void glfwSetMonitorUserPointer(GLFWmonitor* monitor, void* pointer); 2781 2782/*! @brief Returns the user pointer of the specified monitor. 2783 * 2784 * This function returns the current value of the user-defined pointer of the 2785 * specified monitor. The initial value is `NULL`. 2786 * 2787 * This function may be called from the monitor callback, even for a monitor 2788 * that is being disconnected. 2789 * 2790 * @param[in] monitor The monitor whose pointer to return. 2791 * 2792 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 2793 * 2794 * @thread_safety This function may be called from any thread. Access is not 2795 * synchronized. 2796 * 2797 * @sa @ref monitor_userptr 2798 * @sa @ref glfwSetMonitorUserPointer 2799 * 2800 * @since Added in version 3.3. 2801 * 2802 * @ingroup monitor 2803 */ 2804GLFWAPI void* glfwGetMonitorUserPointer(GLFWmonitor* monitor); 2805 2806/*! @brief Sets the monitor configuration callback. 2807 * 2808 * This function sets the monitor configuration callback, or removes the 2809 * currently set callback. This is called when a monitor is connected to or 2810 * disconnected from the system. 2811 * 2812 * @param[in] callback The new callback, or `NULL` to remove the currently set 2813 * callback. 2814 * @return The previously set callback, or `NULL` if no callback was set or the 2815 * library had not been [initialized](@ref intro_init). 2816 * 2817 * @callback_signature 2818 * @code 2819 * void function_name(GLFWmonitor* monitor, int event) 2820 * @endcode 2821 * For more information about the callback parameters, see the 2822 * [function pointer type](@ref GLFWmonitorfun). 2823 * 2824 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 2825 * 2826 * @thread_safety This function must only be called from the main thread. 2827 * 2828 * @sa @ref monitor_event 2829 * 2830 * @since Added in version 3.0. 2831 * 2832 * @ingroup monitor 2833 */ 2834GLFWAPI GLFWmonitorfun glfwSetMonitorCallback(GLFWmonitorfun callback); 2835 2836/*! @brief Returns the available video modes for the specified monitor. 2837 * 2838 * This function returns an array of all video modes supported by the specified 2839 * monitor. The returned array is sorted in ascending order, first by color 2840 * bit depth (the sum of all channel depths), then by resolution area (the 2841 * product of width and height), then resolution width and finally by refresh 2842 * rate. 2843 * 2844 * @param[in] monitor The monitor to query. 2845 * @param[out] count Where to store the number of video modes in the returned 2846 * array. This is set to zero if an error occurred. 2847 * @return An array of video modes, or `NULL` if an 2848 * [error](@ref error_handling) occurred. 2849 * 2850 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 2851 * GLFW_PLATFORM_ERROR. 2852 * 2853 * @pointer_lifetime The returned array is allocated and freed by GLFW. You 2854 * should not free it yourself. It is valid until the specified monitor is 2855 * disconnected, this function is called again for that monitor or the library 2856 * is terminated. 2857 * 2858 * @thread_safety This function must only be called from the main thread. 2859 * 2860 * @sa @ref monitor_modes 2861 * @sa @ref glfwGetVideoMode 2862 * 2863 * @since Added in version 1.0. 2864 * __GLFW 3:__ Changed to return an array of modes for a specific monitor. 2865 * 2866 * @ingroup monitor 2867 */ 2868GLFWAPI const GLFWvidmode* glfwGetVideoModes(GLFWmonitor* monitor, int* count); 2869 2870/*! @brief Returns the current mode of the specified monitor. 2871 * 2872 * This function returns the current video mode of the specified monitor. If 2873 * you have created a full screen window for that monitor, the return value 2874 * will depend on whether that window is iconified. 2875 * 2876 * @param[in] monitor The monitor to query. 2877 * @return The current mode of the monitor, or `NULL` if an 2878 * [error](@ref error_handling) occurred. 2879 * 2880 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 2881 * GLFW_PLATFORM_ERROR. 2882 * 2883 * @pointer_lifetime The returned array is allocated and freed by GLFW. You 2884 * should not free it yourself. It is valid until the specified monitor is 2885 * disconnected or the library is terminated. 2886 * 2887 * @thread_safety This function must only be called from the main thread. 2888 * 2889 * @sa @ref monitor_modes 2890 * @sa @ref glfwGetVideoModes 2891 * 2892 * @since Added in version 3.0. Replaces `glfwGetDesktopMode`. 2893 * 2894 * @ingroup monitor 2895 */ 2896GLFWAPI const GLFWvidmode* glfwGetVideoMode(GLFWmonitor* monitor); 2897 2898/*! @brief Generates a gamma ramp and sets it for the specified monitor. 2899 * 2900 * This function generates an appropriately sized gamma ramp from the specified 2901 * exponent and then calls @ref glfwSetGammaRamp with it. The value must be 2902 * a finite number greater than zero. 2903 * 2904 * The software controlled gamma ramp is applied _in addition_ to the hardware 2905 * gamma correction, which today is usually an approximation of sRGB gamma. 2906 * This means that setting a perfectly linear ramp, or gamma 1.0, will produce 2907 * the default (usually sRGB-like) behavior. 2908 * 2909 * For gamma correct rendering with OpenGL or OpenGL ES, see the @ref 2910 * GLFW_SRGB_CAPABLE hint. 2911 * 2912 * @param[in] monitor The monitor whose gamma ramp to set. 2913 * @param[in] gamma The desired exponent. 2914 * 2915 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref GLFW_INVALID_VALUE, 2916 * @ref GLFW_PLATFORM_ERROR and @ref GLFW_FEATURE_UNAVAILABLE (see remarks). 2917 * 2918 * @remark __Wayland:__ Monitor gamma is a privileged protocol, so this function 2919 * cannot be implemented and emits @ref GLFW_FEATURE_UNAVAILABLE. 2920 * 2921 * @thread_safety This function must only be called from the main thread. 2922 * 2923 * @sa @ref monitor_gamma 2924 * 2925 * @since Added in version 3.0. 2926 * 2927 * @ingroup monitor 2928 */ 2929GLFWAPI void glfwSetGamma(GLFWmonitor* monitor, float gamma); 2930 2931/*! @brief Returns the current gamma ramp for the specified monitor. 2932 * 2933 * This function returns the current gamma ramp of the specified monitor. 2934 * 2935 * @param[in] monitor The monitor to query. 2936 * @return The current gamma ramp, or `NULL` if an 2937 * [error](@ref error_handling) occurred. 2938 * 2939 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref GLFW_PLATFORM_ERROR 2940 * and @ref GLFW_FEATURE_UNAVAILABLE (see remarks). 2941 * 2942 * @remark __Wayland:__ Monitor gamma is a privileged protocol, so this function 2943 * cannot be implemented and emits @ref GLFW_FEATURE_UNAVAILABLE while 2944 * returning `NULL`. 2945 * 2946 * @pointer_lifetime The returned structure and its arrays are allocated and 2947 * freed by GLFW. You should not free them yourself. They are valid until the 2948 * specified monitor is disconnected, this function is called again for that 2949 * monitor or the library is terminated. 2950 * 2951 * @thread_safety This function must only be called from the main thread. 2952 * 2953 * @sa @ref monitor_gamma 2954 * 2955 * @since Added in version 3.0. 2956 * 2957 * @ingroup monitor 2958 */ 2959GLFWAPI const GLFWgammaramp* glfwGetGammaRamp(GLFWmonitor* monitor); 2960 2961/*! @brief Sets the current gamma ramp for the specified monitor. 2962 * 2963 * This function sets the current gamma ramp for the specified monitor. The 2964 * original gamma ramp for that monitor is saved by GLFW the first time this 2965 * function is called and is restored by @ref glfwTerminate. 2966 * 2967 * The software controlled gamma ramp is applied _in addition_ to the hardware 2968 * gamma correction, which today is usually an approximation of sRGB gamma. 2969 * This means that setting a perfectly linear ramp, or gamma 1.0, will produce 2970 * the default (usually sRGB-like) behavior. 2971 * 2972 * For gamma correct rendering with OpenGL or OpenGL ES, see the @ref 2973 * GLFW_SRGB_CAPABLE hint. 2974 * 2975 * @param[in] monitor The monitor whose gamma ramp to set. 2976 * @param[in] ramp The gamma ramp to use. 2977 * 2978 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref GLFW_PLATFORM_ERROR 2979 * and @ref GLFW_FEATURE_UNAVAILABLE (see remarks). 2980 * 2981 * @remark The size of the specified gamma ramp should match the size of the 2982 * current ramp for that monitor. 2983 * 2984 * @remark __Win32:__ The gamma ramp size must be 256. 2985 * 2986 * @remark __Wayland:__ Monitor gamma is a privileged protocol, so this function 2987 * cannot be implemented and emits @ref GLFW_FEATURE_UNAVAILABLE. 2988 * 2989 * @pointer_lifetime The specified gamma ramp is copied before this function 2990 * returns. 2991 * 2992 * @thread_safety This function must only be called from the main thread. 2993 * 2994 * @sa @ref monitor_gamma 2995 * 2996 * @since Added in version 3.0. 2997 * 2998 * @ingroup monitor 2999 */ 3000GLFWAPI void glfwSetGammaRamp(GLFWmonitor* monitor, const GLFWgammaramp* ramp); 3001 3002/*! @brief Resets all window hints to their default values. 3003 * 3004 * This function resets all window hints to their 3005 * [default values](@ref window_hints_values). 3006 * 3007 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 3008 * 3009 * @thread_safety This function must only be called from the main thread. 3010 * 3011 * @sa @ref window_hints 3012 * @sa @ref glfwWindowHint 3013 * @sa @ref glfwWindowHintString 3014 * 3015 * @since Added in version 3.0. 3016 * 3017 * @ingroup window 3018 */ 3019GLFWAPI void glfwDefaultWindowHints(void); 3020 3021/*! @brief Sets the specified window hint to the desired value. 3022 * 3023 * This function sets hints for the next call to @ref glfwCreateWindow. The 3024 * hints, once set, retain their values until changed by a call to this 3025 * function or @ref glfwDefaultWindowHints, or until the library is terminated. 3026 * 3027 * Only integer value hints can be set with this function. String value hints 3028 * are set with @ref glfwWindowHintString. 3029 * 3030 * This function does not check whether the specified hint values are valid. 3031 * If you set hints to invalid values this will instead be reported by the next 3032 * call to @ref glfwCreateWindow. 3033 * 3034 * Some hints are platform specific. These may be set on any platform but they 3035 * will only affect their specific platform. Other platforms will ignore them. 3036 * Setting these hints requires no platform specific headers or functions. 3037 * 3038 * @param[in] hint The [window hint](@ref window_hints) to set. 3039 * @param[in] value The new value of the window hint. 3040 * 3041 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 3042 * GLFW_INVALID_ENUM. 3043 * 3044 * @thread_safety This function must only be called from the main thread. 3045 * 3046 * @sa @ref window_hints 3047 * @sa @ref glfwWindowHintString 3048 * @sa @ref glfwDefaultWindowHints 3049 * 3050 * @since Added in version 3.0. Replaces `glfwOpenWindowHint`. 3051 * 3052 * @ingroup window 3053 */ 3054GLFWAPI void glfwWindowHint(int hint, int value); 3055 3056/*! @brief Sets the specified window hint to the desired value. 3057 * 3058 * This function sets hints for the next call to @ref glfwCreateWindow. The 3059 * hints, once set, retain their values until changed by a call to this 3060 * function or @ref glfwDefaultWindowHints, or until the library is terminated. 3061 * 3062 * Only string type hints can be set with this function. Integer value hints 3063 * are set with @ref glfwWindowHint. 3064 * 3065 * This function does not check whether the specified hint values are valid. 3066 * If you set hints to invalid values this will instead be reported by the next 3067 * call to @ref glfwCreateWindow. 3068 * 3069 * Some hints are platform specific. These may be set on any platform but they 3070 * will only affect their specific platform. Other platforms will ignore them. 3071 * Setting these hints requires no platform specific headers or functions. 3072 * 3073 * @param[in] hint The [window hint](@ref window_hints) to set. 3074 * @param[in] value The new value of the window hint. 3075 * 3076 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 3077 * GLFW_INVALID_ENUM. 3078 * 3079 * @pointer_lifetime The specified string is copied before this function 3080 * returns. 3081 * 3082 * @thread_safety This function must only be called from the main thread. 3083 * 3084 * @sa @ref window_hints 3085 * @sa @ref glfwWindowHint 3086 * @sa @ref glfwDefaultWindowHints 3087 * 3088 * @since Added in version 3.3. 3089 * 3090 * @ingroup window 3091 */ 3092GLFWAPI void glfwWindowHintString(int hint, const char* value); 3093 3094/*! @brief Creates a window and its associated context. 3095 * 3096 * This function creates a window and its associated OpenGL or OpenGL ES 3097 * context. Most of the options controlling how the window and its context 3098 * should be created are specified with [window hints](@ref window_hints). 3099 * 3100 * Successful creation does not change which context is current. Before you 3101 * can use the newly created context, you need to 3102 * [make it current](@ref context_current). For information about the `share` 3103 * parameter, see @ref context_sharing. 3104 * 3105 * The created window, framebuffer and context may differ from what you 3106 * requested, as not all parameters and hints are 3107 * [hard constraints](@ref window_hints_hard). This includes the size of the 3108 * window, especially for full screen windows. To query the actual attributes 3109 * of the created window, framebuffer and context, see @ref 3110 * glfwGetWindowAttrib, @ref glfwGetWindowSize and @ref glfwGetFramebufferSize. 3111 * 3112 * To create a full screen window, you need to specify the monitor the window 3113 * will cover. If no monitor is specified, the window will be windowed mode. 3114 * Unless you have a way for the user to choose a specific monitor, it is 3115 * recommended that you pick the primary monitor. For more information on how 3116 * to query connected monitors, see @ref monitor_monitors. 3117 * 3118 * For full screen windows, the specified size becomes the resolution of the 3119 * window's _desired video mode_. As long as a full screen window is not 3120 * iconified, the supported video mode most closely matching the desired video 3121 * mode is set for the specified monitor. For more information about full 3122 * screen windows, including the creation of so called _windowed full screen_ 3123 * or _borderless full screen_ windows, see @ref window_windowed_full_screen. 3124 * 3125 * Once you have created the window, you can switch it between windowed and 3126 * full screen mode with @ref glfwSetWindowMonitor. This will not affect its 3127 * OpenGL or OpenGL ES context. 3128 * 3129 * By default, newly created windows use the placement recommended by the 3130 * window system. To create the window at a specific position, set the @ref 3131 * GLFW_POSITION_X and @ref GLFW_POSITION_Y window hints before creation. To 3132 * restore the default behavior, set either or both hints back to 3133 * `GLFW_ANY_POSITION`. 3134 * 3135 * As long as at least one full screen window is not iconified, the screensaver 3136 * is prohibited from starting. 3137 * 3138 * Window systems put limits on window sizes. Very large or very small window 3139 * dimensions may be overridden by the window system on creation. Check the 3140 * actual [size](@ref window_size) after creation. 3141 * 3142 * The [swap interval](@ref buffer_swap) is not set during window creation and 3143 * the initial value may vary depending on driver settings and defaults. 3144 * 3145 * @param[in] width The desired width, in screen coordinates, of the window. 3146 * This must be greater than zero. 3147 * @param[in] height The desired height, in screen coordinates, of the window. 3148 * This must be greater than zero. 3149 * @param[in] title The initial, UTF-8 encoded window title. 3150 * @param[in] monitor The monitor to use for full screen mode, or `NULL` for 3151 * windowed mode. 3152 * @param[in] share The window whose context to share resources with, or `NULL` 3153 * to not share resources. 3154 * @return The handle of the created window, or `NULL` if an 3155 * [error](@ref error_handling) occurred. 3156 * 3157 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref 3158 * GLFW_INVALID_ENUM, @ref GLFW_INVALID_VALUE, @ref GLFW_API_UNAVAILABLE, @ref 3159 * GLFW_VERSION_UNAVAILABLE, @ref GLFW_FORMAT_UNAVAILABLE, @ref 3160 * GLFW_NO_WINDOW_CONTEXT and @ref GLFW_PLATFORM_ERROR. 3161 * 3162 * @remark __Win32:__ Window creation will fail if the Microsoft GDI software 3163 * OpenGL implementation is the only one available. 3164 * 3165 * @remark __Win32:__ If the executable has an icon resource named `GLFW_ICON,` it 3166 * will be set as the initial icon for the window. If no such icon is present, 3167 * the `IDI_APPLICATION` icon will be used instead. To set a different icon, 3168 * see @ref glfwSetWindowIcon. 3169 * 3170 * @remark __Win32:__ The context to share resources with must not be current on 3171 * any other thread. 3172 * 3173 * @remark __macOS:__ The OS only supports core profile contexts for OpenGL 3174 * versions 3.2 and later. Before creating an OpenGL context of version 3.2 or 3175 * later you must set the [GLFW_OPENGL_PROFILE](@ref GLFW_OPENGL_PROFILE_hint) 3176 * hint accordingly. OpenGL 3.0 and 3.1 contexts are not supported at all 3177 * on macOS. 3178 * 3179 * @remark __macOS:__ The GLFW window has no icon, as it is not a document 3180 * window, but the dock icon will be the same as the application bundle's icon. 3181 * For more information on bundles, see the 3182 * [Bundle Programming Guide][bundle-guide] in the Mac Developer Library. 3183 * 3184 * [bundle-guide]: https://developer.apple.com/library/mac/documentation/CoreFoundation/Conceptual/CFBundles/ 3185 * 3186 * @remark __macOS:__ The window frame will not be rendered at full resolution 3187 * on Retina displays unless the 3188 * [GLFW_SCALE_FRAMEBUFFER](@ref GLFW_SCALE_FRAMEBUFFER_hint) 3189 * hint is `GLFW_TRUE` and the `NSHighResolutionCapable` key is enabled in the 3190 * application bundle's `Info.plist`. For more information, see 3191 * [High Resolution Guidelines for OS X][hidpi-guide] in the Mac Developer 3192 * Library. The GLFW test and example programs use a custom `Info.plist` 3193 * template for this, which can be found as `CMake/Info.plist.in` in the source 3194 * tree. 3195 * 3196 * [hidpi-guide]: https://developer.apple.com/library/mac/documentation/GraphicsAnimation/Conceptual/HighResolutionOSX/Explained/Explained.html 3197 * 3198 * @remark __macOS:__ When activating frame autosaving with 3199 * [GLFW_COCOA_FRAME_NAME](@ref GLFW_COCOA_FRAME_NAME_hint), the specified 3200 * window size and position may be overridden by previously saved values. 3201 * 3202 * @remark __Wayland:__ GLFW uses [libdecor][] where available to create its window 3203 * decorations. This in turn uses server-side XDG decorations where available 3204 * and provides high quality client-side decorations on compositors like GNOME. 3205 * If both XDG decorations and libdecor are unavailable, GLFW falls back to 3206 * a very simple set of window decorations that only support moving, resizing 3207 * and the window manager's right-click menu. 3208 * 3209 * [libdecor]: https://gitlab.freedesktop.org/libdecor/libdecor 3210 * 3211 * @remark __X11:__ Some window managers will not respect the placement of 3212 * initially hidden windows. 3213 * 3214 * @remark __X11:__ Due to the asynchronous nature of X11, it may take a moment for 3215 * a window to reach its requested state. This means you may not be able to 3216 * query the final size, position or other attributes directly after window 3217 * creation. 3218 * 3219 * @remark __X11:__ The class part of the `WM_CLASS` window property will by 3220 * default be set to the window title passed to this function. The instance 3221 * part will use the contents of the `RESOURCE_NAME` environment variable, if 3222 * present and not empty, or fall back to the window title. Set the 3223 * [GLFW_X11_CLASS_NAME](@ref GLFW_X11_CLASS_NAME_hint) and 3224 * [GLFW_X11_INSTANCE_NAME](@ref GLFW_X11_INSTANCE_NAME_hint) window hints to 3225 * override this. 3226 * 3227 * @thread_safety This function must only be called from the main thread. 3228 * 3229 * @sa @ref window_creation 3230 * @sa @ref glfwDestroyWindow 3231 * 3232 * @since Added in version 3.0. Replaces `glfwOpenWindow`. 3233 * 3234 * @ingroup window 3235 */ 3236GLFWAPI GLFWwindow* glfwCreateWindow(int width, int height, const char* title, GLFWmonitor* monitor, GLFWwindow* share); 3237 3238/*! @brief Destroys the specified window and its context. 3239 * 3240 * This function destroys the specified window and its context. On calling 3241 * this function, no further callbacks will be called for that window. 3242 * 3243 * If the context of the specified window is current on the main thread, it is 3244 * detached before being destroyed. 3245 * 3246 * @param[in] window The window to destroy. 3247 * 3248 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 3249 * GLFW_PLATFORM_ERROR. 3250 * 3251 * @note The context of the specified window must not be current on any other 3252 * thread when this function is called. 3253 * 3254 * @reentrancy This function must not be called from a callback. 3255 * 3256 * @thread_safety This function must only be called from the main thread. 3257 * 3258 * @sa @ref window_creation 3259 * @sa @ref glfwCreateWindow 3260 * 3261 * @since Added in version 3.0. Replaces `glfwCloseWindow`. 3262 * 3263 * @ingroup window 3264 */ 3265GLFWAPI void glfwDestroyWindow(GLFWwindow* window); 3266 3267/*! @brief Checks the close flag of the specified window. 3268 * 3269 * This function returns the value of the close flag of the specified window. 3270 * 3271 * @param[in] window The window to query. 3272 * @return The value of the close flag. 3273 * 3274 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 3275 * 3276 * @thread_safety This function may be called from any thread. Access is not 3277 * synchronized. 3278 * 3279 * @sa @ref window_close 3280 * 3281 * @since Added in version 3.0. 3282 * 3283 * @ingroup window 3284 */ 3285GLFWAPI int glfwWindowShouldClose(GLFWwindow* window); 3286 3287/*! @brief Sets the close flag of the specified window. 3288 * 3289 * This function sets the value of the close flag of the specified window. 3290 * This can be used to override the user's attempt to close the window, or 3291 * to signal that it should be closed. 3292 * 3293 * @param[in] window The window whose flag to change. 3294 * @param[in] value The new value. 3295 * 3296 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 3297 * 3298 * @thread_safety This function may be called from any thread. Access is not 3299 * synchronized. 3300 * 3301 * @sa @ref window_close 3302 * 3303 * @since Added in version 3.0. 3304 * 3305 * @ingroup window 3306 */ 3307GLFWAPI void glfwSetWindowShouldClose(GLFWwindow* window, int value); 3308 3309/*! @brief Returns the title of the specified window. 3310 * 3311 * This function returns the window title, encoded as UTF-8, of the specified 3312 * window. This is the title set previously by @ref glfwCreateWindow 3313 * or @ref glfwSetWindowTitle. 3314 * 3315 * @param[in] window The window to query. 3316 * @return The UTF-8 encoded window title, or `NULL` if an 3317 * [error](@ref error_handling) occurred. 3318 * 3319 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 3320 * 3321 * @remark The returned title is currently a copy of the title last set by @ref 3322 * glfwCreateWindow or @ref glfwSetWindowTitle. It does not include any 3323 * additional text which may be appended by the platform or another program. 3324 * 3325 * @pointer_lifetime The returned string is allocated and freed by GLFW. You 3326 * should not free it yourself. It is valid until the next call to @ref 3327 * glfwGetWindowTitle or @ref glfwSetWindowTitle, or until the library is 3328 * terminated. 3329 * 3330 * @thread_safety This function must only be called from the main thread. 3331 * 3332 * @sa @ref window_title 3333 * @sa @ref glfwSetWindowTitle 3334 * 3335 * @since Added in version 3.4. 3336 * 3337 * @ingroup window 3338 */ 3339GLFWAPI const char* glfwGetWindowTitle(GLFWwindow* window); 3340 3341/*! @brief Sets the title of the specified window. 3342 * 3343 * This function sets the window title, encoded as UTF-8, of the specified 3344 * window. 3345 * 3346 * @param[in] window The window whose title to change. 3347 * @param[in] title The UTF-8 encoded window title. 3348 * 3349 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 3350 * GLFW_PLATFORM_ERROR. 3351 * 3352 * @remark __macOS:__ The window title will not be updated until the next time you 3353 * process events. 3354 * 3355 * @thread_safety This function must only be called from the main thread. 3356 * 3357 * @sa @ref window_title 3358 * @sa @ref glfwGetWindowTitle 3359 * 3360 * @since Added in version 1.0. 3361 * __GLFW 3:__ Added window handle parameter. 3362 * 3363 * @ingroup window 3364 */ 3365GLFWAPI void glfwSetWindowTitle(GLFWwindow* window, const char* title); 3366 3367/*! @brief Sets the icon for the specified window. 3368 * 3369 * This function sets the icon of the specified window. If passed an array of 3370 * candidate images, those of or closest to the sizes desired by the system are 3371 * selected. If no images are specified, the window reverts to its default 3372 * icon. 3373 * 3374 * The pixels are 32-bit, little-endian, non-premultiplied RGBA, i.e. eight 3375 * bits per channel with the red channel first. They are arranged canonically 3376 * as packed sequential rows, starting from the top-left corner. 3377 * 3378 * The desired image sizes varies depending on platform and system settings. 3379 * The selected images will be rescaled as needed. Good sizes include 16x16, 3380 * 32x32 and 48x48. 3381 * 3382 * @param[in] window The window whose icon to set. 3383 * @param[in] count The number of images in the specified array, or zero to 3384 * revert to the default window icon. 3385 * @param[in] images The images to create the icon from. This is ignored if 3386 * count is zero. 3387 * 3388 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref 3389 * GLFW_INVALID_VALUE, @ref GLFW_PLATFORM_ERROR and @ref 3390 * GLFW_FEATURE_UNAVAILABLE (see remarks). 3391 * 3392 * @pointer_lifetime The specified image data is copied before this function 3393 * returns. 3394 * 3395 * @remark __macOS:__ Regular windows do not have icons on macOS. This function 3396 * will emit @ref GLFW_FEATURE_UNAVAILABLE. The dock icon will be the same as 3397 * the application bundle's icon. For more information on bundles, see the 3398 * [Bundle Programming Guide][bundle-guide] in the Mac Developer Library. 3399 * 3400 * [bundle-guide]: https://developer.apple.com/library/mac/documentation/CoreFoundation/Conceptual/CFBundles/ 3401 * 3402 * @remark __Wayland:__ There is no existing protocol to change an icon, the 3403 * window will thus inherit the one defined in the application's desktop file. 3404 * This function will emit @ref GLFW_FEATURE_UNAVAILABLE. 3405 * 3406 * @thread_safety This function must only be called from the main thread. 3407 * 3408 * @sa @ref window_icon 3409 * 3410 * @since Added in version 3.2. 3411 * 3412 * @ingroup window 3413 */ 3414GLFWAPI void glfwSetWindowIcon(GLFWwindow* window, int count, const GLFWimage* images); 3415 3416/*! @brief Retrieves the position of the content area of the specified window. 3417 * 3418 * This function retrieves the position, in screen coordinates, of the 3419 * upper-left corner of the content area of the specified window. 3420 * 3421 * Any or all of the position arguments may be `NULL`. If an error occurs, all 3422 * non-`NULL` position arguments will be set to zero. 3423 * 3424 * @param[in] window The window to query. 3425 * @param[out] xpos Where to store the x-coordinate of the upper-left corner of 3426 * the content area, or `NULL`. 3427 * @param[out] ypos Where to store the y-coordinate of the upper-left corner of 3428 * the content area, or `NULL`. 3429 * 3430 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref 3431 * GLFW_PLATFORM_ERROR and @ref GLFW_FEATURE_UNAVAILABLE (see remarks). 3432 * 3433 * @remark __Wayland:__ Window positions are not currently part of any common 3434 * Wayland protocol, so this function cannot be implemented and will emit @ref 3435 * GLFW_FEATURE_UNAVAILABLE. 3436 * 3437 * @thread_safety This function must only be called from the main thread. 3438 * 3439 * @sa @ref window_pos 3440 * @sa @ref glfwSetWindowPos 3441 * 3442 * @since Added in version 3.0. 3443 * 3444 * @ingroup window 3445 */ 3446GLFWAPI void glfwGetWindowPos(GLFWwindow* window, int* xpos, int* ypos); 3447 3448/*! @brief Sets the position of the content area of the specified window. 3449 * 3450 * This function sets the position, in screen coordinates, of the upper-left 3451 * corner of the content area of the specified windowed mode window. If the 3452 * window is a full screen window, this function does nothing. 3453 * 3454 * __Do not use this function__ to move an already visible window unless you 3455 * have very good reasons for doing so, as it will confuse and annoy the user. 3456 * 3457 * The window manager may put limits on what positions are allowed. GLFW 3458 * cannot and should not override these limits. 3459 * 3460 * @param[in] window The window to query. 3461 * @param[in] xpos The x-coordinate of the upper-left corner of the content area. 3462 * @param[in] ypos The y-coordinate of the upper-left corner of the content area. 3463 * 3464 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref 3465 * GLFW_PLATFORM_ERROR and @ref GLFW_FEATURE_UNAVAILABLE (see remarks). 3466 * 3467 * @remark __Wayland:__ Window positions are not currently part of any common 3468 * Wayland protocol, so this function cannot be implemented and will emit @ref 3469 * GLFW_FEATURE_UNAVAILABLE. 3470 * 3471 * @thread_safety This function must only be called from the main thread. 3472 * 3473 * @sa @ref window_pos 3474 * @sa @ref glfwGetWindowPos 3475 * 3476 * @since Added in version 1.0. 3477 * __GLFW 3:__ Added window handle parameter. 3478 * 3479 * @ingroup window 3480 */ 3481GLFWAPI void glfwSetWindowPos(GLFWwindow* window, int xpos, int ypos); 3482 3483/*! @brief Retrieves the size of the content area of the specified window. 3484 * 3485 * This function retrieves the size, in screen coordinates, of the content area 3486 * of the specified window. If you wish to retrieve the size of the 3487 * framebuffer of the window in pixels, see @ref glfwGetFramebufferSize. 3488 * 3489 * Any or all of the size arguments may be `NULL`. If an error occurs, all 3490 * non-`NULL` size arguments will be set to zero. 3491 * 3492 * @param[in] window The window whose size to retrieve. 3493 * @param[out] width Where to store the width, in screen coordinates, of the 3494 * content area, or `NULL`. 3495 * @param[out] height Where to store the height, in screen coordinates, of the 3496 * content area, or `NULL`. 3497 * 3498 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 3499 * GLFW_PLATFORM_ERROR. 3500 * 3501 * @thread_safety This function must only be called from the main thread. 3502 * 3503 * @sa @ref window_size 3504 * @sa @ref glfwSetWindowSize 3505 * 3506 * @since Added in version 1.0. 3507 * __GLFW 3:__ Added window handle parameter. 3508 * 3509 * @ingroup window 3510 */ 3511GLFWAPI void glfwGetWindowSize(GLFWwindow* window, int* width, int* height); 3512 3513/*! @brief Sets the size limits of the specified window. 3514 * 3515 * This function sets the size limits of the content area of the specified 3516 * window. If the window is full screen, the size limits only take effect 3517 * once it is made windowed. If the window is not resizable, this function 3518 * does nothing. 3519 * 3520 * The size limits are applied immediately to a windowed mode window and may 3521 * cause it to be resized. 3522 * 3523 * The maximum dimensions must be greater than or equal to the minimum 3524 * dimensions and all must be greater than or equal to zero. 3525 * 3526 * @param[in] window The window to set limits for. 3527 * @param[in] minwidth The minimum width, in screen coordinates, of the content 3528 * area, or `GLFW_DONT_CARE`. 3529 * @param[in] minheight The minimum height, in screen coordinates, of the 3530 * content area, or `GLFW_DONT_CARE`. 3531 * @param[in] maxwidth The maximum width, in screen coordinates, of the content 3532 * area, or `GLFW_DONT_CARE`. 3533 * @param[in] maxheight The maximum height, in screen coordinates, of the 3534 * content area, or `GLFW_DONT_CARE`. 3535 * 3536 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref 3537 * GLFW_INVALID_VALUE and @ref GLFW_PLATFORM_ERROR. 3538 * 3539 * @remark If you set size limits and an aspect ratio that conflict, the 3540 * results are undefined. 3541 * 3542 * @remark __Wayland:__ The size limits will not be applied until the window is 3543 * actually resized, either by the user or by the compositor. 3544 * 3545 * @thread_safety This function must only be called from the main thread. 3546 * 3547 * @sa @ref window_sizelimits 3548 * @sa @ref glfwSetWindowAspectRatio 3549 * 3550 * @since Added in version 3.2. 3551 * 3552 * @ingroup window 3553 */ 3554GLFWAPI void glfwSetWindowSizeLimits(GLFWwindow* window, int minwidth, int minheight, int maxwidth, int maxheight); 3555 3556/*! @brief Sets the aspect ratio of the specified window. 3557 * 3558 * This function sets the required aspect ratio of the content area of the 3559 * specified window. If the window is full screen, the aspect ratio only takes 3560 * effect once it is made windowed. If the window is not resizable, this 3561 * function does nothing. 3562 * 3563 * The aspect ratio is specified as a numerator and a denominator and both 3564 * values must be greater than zero. For example, the common 16:9 aspect ratio 3565 * is specified as 16 and 9, respectively. 3566 * 3567 * If the numerator and denominator is set to `GLFW_DONT_CARE` then the aspect 3568 * ratio limit is disabled. 3569 * 3570 * The aspect ratio is applied immediately to a windowed mode window and may 3571 * cause it to be resized. 3572 * 3573 * @param[in] window The window to set limits for. 3574 * @param[in] numer The numerator of the desired aspect ratio, or 3575 * `GLFW_DONT_CARE`. 3576 * @param[in] denom The denominator of the desired aspect ratio, or 3577 * `GLFW_DONT_CARE`. 3578 * 3579 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref 3580 * GLFW_INVALID_VALUE and @ref GLFW_PLATFORM_ERROR. 3581 * 3582 * @remark If you set size limits and an aspect ratio that conflict, the 3583 * results are undefined. 3584 * 3585 * @remark __Wayland:__ The aspect ratio will not be applied until the window is 3586 * actually resized, either by the user or by the compositor. 3587 * 3588 * @thread_safety This function must only be called from the main thread. 3589 * 3590 * @sa @ref window_sizelimits 3591 * @sa @ref glfwSetWindowSizeLimits 3592 * 3593 * @since Added in version 3.2. 3594 * 3595 * @ingroup window 3596 */ 3597GLFWAPI void glfwSetWindowAspectRatio(GLFWwindow* window, int numer, int denom); 3598 3599/*! @brief Sets the size of the content area of the specified window. 3600 * 3601 * This function sets the size, in screen coordinates, of the content area of 3602 * the specified window. 3603 * 3604 * For full screen windows, this function updates the resolution of its desired 3605 * video mode and switches to the video mode closest to it, without affecting 3606 * the window's context. As the context is unaffected, the bit depths of the 3607 * framebuffer remain unchanged. 3608 * 3609 * If you wish to update the refresh rate of the desired video mode in addition 3610 * to its resolution, see @ref glfwSetWindowMonitor. 3611 * 3612 * The window manager may put limits on what sizes are allowed. GLFW cannot 3613 * and should not override these limits. 3614 * 3615 * @param[in] window The window to resize. 3616 * @param[in] width The desired width, in screen coordinates, of the window 3617 * content area. 3618 * @param[in] height The desired height, in screen coordinates, of the window 3619 * content area. 3620 * 3621 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 3622 * GLFW_PLATFORM_ERROR. 3623 * 3624 * @thread_safety This function must only be called from the main thread. 3625 * 3626 * @sa @ref window_size 3627 * @sa @ref glfwGetWindowSize 3628 * @sa @ref glfwSetWindowMonitor 3629 * 3630 * @since Added in version 1.0. 3631 * __GLFW 3:__ Added window handle parameter. 3632 * 3633 * @ingroup window 3634 */ 3635GLFWAPI void glfwSetWindowSize(GLFWwindow* window, int width, int height); 3636 3637/*! @brief Retrieves the size of the framebuffer of the specified window. 3638 * 3639 * This function retrieves the size, in pixels, of the framebuffer of the 3640 * specified window. If you wish to retrieve the size of the window in screen 3641 * coordinates, see @ref glfwGetWindowSize. 3642 * 3643 * Any or all of the size arguments may be `NULL`. If an error occurs, all 3644 * non-`NULL` size arguments will be set to zero. 3645 * 3646 * @param[in] window The window whose framebuffer to query. 3647 * @param[out] width Where to store the width, in pixels, of the framebuffer, 3648 * or `NULL`. 3649 * @param[out] height Where to store the height, in pixels, of the framebuffer, 3650 * or `NULL`. 3651 * 3652 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 3653 * GLFW_PLATFORM_ERROR. 3654 * 3655 * @thread_safety This function must only be called from the main thread. 3656 * 3657 * @sa @ref window_fbsize 3658 * @sa @ref glfwSetFramebufferSizeCallback 3659 * 3660 * @since Added in version 3.0. 3661 * 3662 * @ingroup window 3663 */ 3664GLFWAPI void glfwGetFramebufferSize(GLFWwindow* window, int* width, int* height); 3665 3666/*! @brief Retrieves the size of the frame of the window. 3667 * 3668 * This function retrieves the size, in screen coordinates, of each edge of the 3669 * frame of the specified window. This size includes the title bar, if the 3670 * window has one. The size of the frame may vary depending on the 3671 * [window-related hints](@ref window_hints_wnd) used to create it. 3672 * 3673 * Because this function retrieves the size of each window frame edge and not 3674 * the offset along a particular coordinate axis, the retrieved values will 3675 * always be zero or positive. 3676 * 3677 * Any or all of the size arguments may be `NULL`. If an error occurs, all 3678 * non-`NULL` size arguments will be set to zero. 3679 * 3680 * @param[in] window The window whose frame size to query. 3681 * @param[out] left Where to store the size, in screen coordinates, of the left 3682 * edge of the window frame, or `NULL`. 3683 * @param[out] top Where to store the size, in screen coordinates, of the top 3684 * edge of the window frame, or `NULL`. 3685 * @param[out] right Where to store the size, in screen coordinates, of the 3686 * right edge of the window frame, or `NULL`. 3687 * @param[out] bottom Where to store the size, in screen coordinates, of the 3688 * bottom edge of the window frame, or `NULL`. 3689 * 3690 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 3691 * GLFW_PLATFORM_ERROR. 3692 * 3693 * @thread_safety This function must only be called from the main thread. 3694 * 3695 * @sa @ref window_size 3696 * 3697 * @since Added in version 3.1. 3698 * 3699 * @ingroup window 3700 */ 3701GLFWAPI void glfwGetWindowFrameSize(GLFWwindow* window, int* left, int* top, int* right, int* bottom); 3702 3703/*! @brief Retrieves the content scale for the specified window. 3704 * 3705 * This function retrieves the content scale for the specified window. The 3706 * content scale is the ratio between the current DPI and the platform's 3707 * default DPI. This is especially important for text and any UI elements. If 3708 * the pixel dimensions of your UI scaled by this look appropriate on your 3709 * machine then it should appear at a reasonable size on other machines 3710 * regardless of their DPI and scaling settings. This relies on the system DPI 3711 * and scaling settings being somewhat correct. 3712 * 3713 * On platforms where each monitors can have its own content scale, the window 3714 * content scale will depend on which monitor the system considers the window 3715 * to be on. 3716 * 3717 * @param[in] window The window to query. 3718 * @param[out] xscale Where to store the x-axis content scale, or `NULL`. 3719 * @param[out] yscale Where to store the y-axis content scale, or `NULL`. 3720 * 3721 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 3722 * GLFW_PLATFORM_ERROR. 3723 * 3724 * @thread_safety This function must only be called from the main thread. 3725 * 3726 * @sa @ref window_scale 3727 * @sa @ref glfwSetWindowContentScaleCallback 3728 * @sa @ref glfwGetMonitorContentScale 3729 * 3730 * @since Added in version 3.3. 3731 * 3732 * @ingroup window 3733 */ 3734GLFWAPI void glfwGetWindowContentScale(GLFWwindow* window, float* xscale, float* yscale); 3735 3736/*! @brief Returns the opacity of the whole window. 3737 * 3738 * This function returns the opacity of the window, including any decorations. 3739 * 3740 * The opacity (or alpha) value is a positive finite number between zero and 3741 * one, where zero is fully transparent and one is fully opaque. If the system 3742 * does not support whole window transparency, this function always returns one. 3743 * 3744 * The initial opacity value for newly created windows is one. 3745 * 3746 * @param[in] window The window to query. 3747 * @return The opacity value of the specified window. 3748 * 3749 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 3750 * GLFW_PLATFORM_ERROR. 3751 * 3752 * @thread_safety This function must only be called from the main thread. 3753 * 3754 * @sa @ref window_transparency 3755 * @sa @ref glfwSetWindowOpacity 3756 * 3757 * @since Added in version 3.3. 3758 * 3759 * @ingroup window 3760 */ 3761GLFWAPI float glfwGetWindowOpacity(GLFWwindow* window); 3762 3763/*! @brief Sets the opacity of the whole window. 3764 * 3765 * This function sets the opacity of the window, including any decorations. 3766 * 3767 * The opacity (or alpha) value is a positive finite number between zero and 3768 * one, where zero is fully transparent and one is fully opaque. 3769 * 3770 * The initial opacity value for newly created windows is one. 3771 * 3772 * A window created with framebuffer transparency may not use whole window 3773 * transparency. The results of doing this are undefined. 3774 * 3775 * @param[in] window The window to set the opacity for. 3776 * @param[in] opacity The desired opacity of the specified window. 3777 * 3778 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref 3779 * GLFW_PLATFORM_ERROR and @ref GLFW_FEATURE_UNAVAILABLE (see remarks). 3780 * 3781 * @remark __Wayland:__ There is no way to set an opacity factor for a window. 3782 * This function will emit @ref GLFW_FEATURE_UNAVAILABLE. 3783 * 3784 * @thread_safety This function must only be called from the main thread. 3785 * 3786 * @sa @ref window_transparency 3787 * @sa @ref glfwGetWindowOpacity 3788 * 3789 * @since Added in version 3.3. 3790 * 3791 * @ingroup window 3792 */ 3793GLFWAPI void glfwSetWindowOpacity(GLFWwindow* window, float opacity); 3794 3795/*! @brief Iconifies the specified window. 3796 * 3797 * This function iconifies (minimizes) the specified window if it was 3798 * previously restored. If the window is already iconified, this function does 3799 * nothing. 3800 * 3801 * If the specified window is a full screen window, GLFW restores the original 3802 * video mode of the monitor. The window's desired video mode is set again 3803 * when the window is restored. 3804 * 3805 * @param[in] window The window to iconify. 3806 * 3807 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 3808 * GLFW_PLATFORM_ERROR. 3809 * 3810 * @thread_safety This function must only be called from the main thread. 3811 * 3812 * @sa @ref window_iconify 3813 * @sa @ref glfwRestoreWindow 3814 * @sa @ref glfwMaximizeWindow 3815 * 3816 * @since Added in version 2.1. 3817 * __GLFW 3:__ Added window handle parameter. 3818 * 3819 * @ingroup window 3820 */ 3821GLFWAPI void glfwIconifyWindow(GLFWwindow* window); 3822 3823/*! @brief Restores the specified window. 3824 * 3825 * This function restores the specified window if it was previously iconified 3826 * (minimized) or maximized. If the window is already restored, this function 3827 * does nothing. 3828 * 3829 * If the specified window is an iconified full screen window, its desired 3830 * video mode is set again for its monitor when the window is restored. 3831 * 3832 * @param[in] window The window to restore. 3833 * 3834 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 3835 * GLFW_PLATFORM_ERROR. 3836 * 3837 * @remark __Wayland:__ Restoring a window from maximization is not currently 3838 * part of any common Wayland protocol, so this function can only restore 3839 * windows from maximization. 3840 * 3841 * @thread_safety This function must only be called from the main thread. 3842 * 3843 * @sa @ref window_iconify 3844 * @sa @ref glfwIconifyWindow 3845 * @sa @ref glfwMaximizeWindow 3846 * 3847 * @since Added in version 2.1. 3848 * __GLFW 3:__ Added window handle parameter. 3849 * 3850 * @ingroup window 3851 */ 3852GLFWAPI void glfwRestoreWindow(GLFWwindow* window); 3853 3854/*! @brief Maximizes the specified window. 3855 * 3856 * This function maximizes the specified window if it was previously not 3857 * maximized. If the window is already maximized, this function does nothing. 3858 * 3859 * If the specified window is a full screen window, this function does nothing. 3860 * 3861 * @param[in] window The window to maximize. 3862 * 3863 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 3864 * GLFW_PLATFORM_ERROR. 3865 * 3866 * @par Thread Safety 3867 * This function may only be called from the main thread. 3868 * 3869 * @sa @ref window_iconify 3870 * @sa @ref glfwIconifyWindow 3871 * @sa @ref glfwRestoreWindow 3872 * 3873 * @since Added in GLFW 3.2. 3874 * 3875 * @ingroup window 3876 */ 3877GLFWAPI void glfwMaximizeWindow(GLFWwindow* window); 3878 3879/*! @brief Makes the specified window visible. 3880 * 3881 * This function makes the specified window visible if it was previously 3882 * hidden. If the window is already visible or is in full screen mode, this 3883 * function does nothing. 3884 * 3885 * By default, windowed mode windows are focused when shown 3886 * Set the [GLFW_FOCUS_ON_SHOW](@ref GLFW_FOCUS_ON_SHOW_hint) window hint 3887 * to change this behavior for all newly created windows, or change the 3888 * behavior for an existing window with @ref glfwSetWindowAttrib. 3889 * 3890 * @param[in] window The window to make visible. 3891 * 3892 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 3893 * GLFW_PLATFORM_ERROR. 3894 * 3895 * @remark __Wayland:__ Because Wayland wants every frame of the desktop to be 3896 * complete, this function does not immediately make the window visible. 3897 * Instead it will become visible the next time the window framebuffer is 3898 * updated after this call. 3899 * 3900 * @thread_safety This function must only be called from the main thread. 3901 * 3902 * @sa @ref window_hide 3903 * @sa @ref glfwHideWindow 3904 * 3905 * @since Added in version 3.0. 3906 * 3907 * @ingroup window 3908 */ 3909GLFWAPI void glfwShowWindow(GLFWwindow* window); 3910 3911/*! @brief Hides the specified window. 3912 * 3913 * This function hides the specified window if it was previously visible. If 3914 * the window is already hidden or is in full screen mode, this function does 3915 * nothing. 3916 * 3917 * @param[in] window The window to hide. 3918 * 3919 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 3920 * GLFW_PLATFORM_ERROR. 3921 * 3922 * @thread_safety This function must only be called from the main thread. 3923 * 3924 * @sa @ref window_hide 3925 * @sa @ref glfwShowWindow 3926 * 3927 * @since Added in version 3.0. 3928 * 3929 * @ingroup window 3930 */ 3931GLFWAPI void glfwHideWindow(GLFWwindow* window); 3932 3933/*! @brief Brings the specified window to front and sets input focus. 3934 * 3935 * This function brings the specified window to front and sets input focus. 3936 * The window should already be visible and not iconified. 3937 * 3938 * By default, both windowed and full screen mode windows are focused when 3939 * initially created. Set the [GLFW_FOCUSED](@ref GLFW_FOCUSED_hint) to 3940 * disable this behavior. 3941 * 3942 * Also by default, windowed mode windows are focused when shown 3943 * with @ref glfwShowWindow. Set the 3944 * [GLFW_FOCUS_ON_SHOW](@ref GLFW_FOCUS_ON_SHOW_hint) to disable this behavior. 3945 * 3946 * __Do not use this function__ to steal focus from other applications unless 3947 * you are certain that is what the user wants. Focus stealing can be 3948 * extremely disruptive. 3949 * 3950 * For a less disruptive way of getting the user's attention, see 3951 * [attention requests](@ref window_attention). 3952 * 3953 * @param[in] window The window to give input focus. 3954 * 3955 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 3956 * GLFW_PLATFORM_ERROR. 3957 * 3958 * @remark __Wayland:__ The compositor will likely ignore focus requests unless 3959 * another window created by the same application already has input focus. 3960 * 3961 * @thread_safety This function must only be called from the main thread. 3962 * 3963 * @sa @ref window_focus 3964 * @sa @ref window_attention 3965 * 3966 * @since Added in version 3.2. 3967 * 3968 * @ingroup window 3969 */ 3970GLFWAPI void glfwFocusWindow(GLFWwindow* window); 3971 3972/*! @brief Requests user attention to the specified window. 3973 * 3974 * This function requests user attention to the specified window. On 3975 * platforms where this is not supported, attention is requested to the 3976 * application as a whole. 3977 * 3978 * Once the user has given attention, usually by focusing the window or 3979 * application, the system will end the request automatically. 3980 * 3981 * @param[in] window The window to request attention to. 3982 * 3983 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 3984 * GLFW_PLATFORM_ERROR. 3985 * 3986 * @remark __macOS:__ Attention is requested to the application as a whole, not the 3987 * specific window. 3988 * 3989 * @thread_safety This function must only be called from the main thread. 3990 * 3991 * @sa @ref window_attention 3992 * 3993 * @since Added in version 3.3. 3994 * 3995 * @ingroup window 3996 */ 3997GLFWAPI void glfwRequestWindowAttention(GLFWwindow* window); 3998 3999/*! @brief Returns the monitor that the window uses for full screen mode. 4000 * 4001 * This function returns the handle of the monitor that the specified window is 4002 * in full screen on. 4003 * 4004 * @param[in] window The window to query. 4005 * @return The monitor, or `NULL` if the window is in windowed mode or an 4006 * [error](@ref error_handling) occurred. 4007 * 4008 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 4009 * 4010 * @thread_safety This function must only be called from the main thread. 4011 * 4012 * @sa @ref window_monitor 4013 * @sa @ref glfwSetWindowMonitor 4014 * 4015 * @since Added in version 3.0. 4016 * 4017 * @ingroup window 4018 */ 4019GLFWAPI GLFWmonitor* glfwGetWindowMonitor(GLFWwindow* window); 4020 4021/*! @brief Sets the mode, monitor, video mode and placement of a window. 4022 * 4023 * This function sets the monitor that the window uses for full screen mode or, 4024 * if the monitor is `NULL`, makes it windowed mode. 4025 * 4026 * When setting a monitor, this function updates the width, height and refresh 4027 * rate of the desired video mode and switches to the video mode closest to it. 4028 * The window position is ignored when setting a monitor. 4029 * 4030 * When the monitor is `NULL`, the position, width and height are used to 4031 * place the window content area. The refresh rate is ignored when no monitor 4032 * is specified. 4033 * 4034 * If you only wish to update the resolution of a full screen window or the 4035 * size of a windowed mode window, see @ref glfwSetWindowSize. 4036 * 4037 * When a window transitions from full screen to windowed mode, this function 4038 * restores any previous window settings such as whether it is decorated, 4039 * floating, resizable, has size or aspect ratio limits, etc. 4040 * 4041 * @param[in] window The window whose monitor, size or video mode to set. 4042 * @param[in] monitor The desired monitor, or `NULL` to set windowed mode. 4043 * @param[in] xpos The desired x-coordinate of the upper-left corner of the 4044 * content area. 4045 * @param[in] ypos The desired y-coordinate of the upper-left corner of the 4046 * content area. 4047 * @param[in] width The desired with, in screen coordinates, of the content 4048 * area or video mode. 4049 * @param[in] height The desired height, in screen coordinates, of the content 4050 * area or video mode. 4051 * @param[in] refreshRate The desired refresh rate, in Hz, of the video mode, 4052 * or `GLFW_DONT_CARE`. 4053 * 4054 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 4055 * GLFW_PLATFORM_ERROR. 4056 * 4057 * @remark The OpenGL or OpenGL ES context will not be destroyed or otherwise 4058 * affected by any resizing or mode switching, although you may need to update 4059 * your viewport if the framebuffer size has changed. 4060 * 4061 * @remark __Wayland:__ Window positions are not currently part of any common 4062 * Wayland protocol. The window position arguments are ignored. 4063 * 4064 * @thread_safety This function must only be called from the main thread. 4065 * 4066 * @sa @ref window_monitor 4067 * @sa @ref window_full_screen 4068 * @sa @ref glfwGetWindowMonitor 4069 * @sa @ref glfwSetWindowSize 4070 * 4071 * @since Added in version 3.2. 4072 * 4073 * @ingroup window 4074 */ 4075GLFWAPI void glfwSetWindowMonitor(GLFWwindow* window, GLFWmonitor* monitor, int xpos, int ypos, int width, int height, int refreshRate); 4076 4077/*! @brief Returns an attribute of the specified window. 4078 * 4079 * This function returns the value of an attribute of the specified window or 4080 * its OpenGL or OpenGL ES context. 4081 * 4082 * @param[in] window The window to query. 4083 * @param[in] attrib The [window attribute](@ref window_attribs) whose value to 4084 * return. 4085 * @return The value of the attribute, or zero if an 4086 * [error](@ref error_handling) occurred. 4087 * 4088 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref 4089 * GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR. 4090 * 4091 * @remark Framebuffer related hints are not window attributes. See @ref 4092 * window_attribs_fb for more information. 4093 * 4094 * @remark Zero is a valid value for many window and context related 4095 * attributes so you cannot use a return value of zero as an indication of 4096 * errors. However, this function should not fail as long as it is passed 4097 * valid arguments and the library has been [initialized](@ref intro_init). 4098 * 4099 * @remark __Wayland:__ Checking whether a window is iconified is not currently 4100 * part of any common Wayland protocol, so the @ref GLFW_ICONIFIED attribute 4101 * cannot be implemented and is always `GLFW_FALSE`. 4102 * 4103 * @thread_safety This function must only be called from the main thread. 4104 * 4105 * @sa @ref window_attribs 4106 * @sa @ref glfwSetWindowAttrib 4107 * 4108 * @since Added in version 3.0. Replaces `glfwGetWindowParam` and 4109 * `glfwGetGLVersion`. 4110 * 4111 * @ingroup window 4112 */ 4113GLFWAPI int glfwGetWindowAttrib(GLFWwindow* window, int attrib); 4114 4115/*! @brief Sets an attribute of the specified window. 4116 * 4117 * This function sets the value of an attribute of the specified window. 4118 * 4119 * The supported attributes are [GLFW_DECORATED](@ref GLFW_DECORATED_attrib), 4120 * [GLFW_RESIZABLE](@ref GLFW_RESIZABLE_attrib), 4121 * [GLFW_FLOATING](@ref GLFW_FLOATING_attrib), 4122 * [GLFW_AUTO_ICONIFY](@ref GLFW_AUTO_ICONIFY_attrib) and 4123 * [GLFW_FOCUS_ON_SHOW](@ref GLFW_FOCUS_ON_SHOW_attrib). 4124 * [GLFW_MOUSE_PASSTHROUGH](@ref GLFW_MOUSE_PASSTHROUGH_attrib) 4125 * 4126 * Some of these attributes are ignored for full screen windows. The new 4127 * value will take effect if the window is later made windowed. 4128 * 4129 * Some of these attributes are ignored for windowed mode windows. The new 4130 * value will take effect if the window is later made full screen. 4131 * 4132 * @param[in] window The window to set the attribute for. 4133 * @param[in] attrib A supported window attribute. 4134 * @param[in] value `GLFW_TRUE` or `GLFW_FALSE`. 4135 * 4136 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref 4137 * GLFW_INVALID_ENUM, @ref GLFW_INVALID_VALUE, @ref GLFW_PLATFORM_ERROR and @ref 4138 * GLFW_FEATURE_UNAVAILABLE (see remarks). 4139 * 4140 * @remark Calling @ref glfwGetWindowAttrib will always return the latest 4141 * value, even if that value is ignored by the current mode of the window. 4142 * 4143 * @remark __Wayland:__ The [GLFW_FLOATING](@ref GLFW_FLOATING_attrib) window attribute is 4144 * not supported. Setting this will emit @ref GLFW_FEATURE_UNAVAILABLE. 4145 * 4146 * @thread_safety This function must only be called from the main thread. 4147 * 4148 * @sa @ref window_attribs 4149 * @sa @ref glfwGetWindowAttrib 4150 * 4151 * @since Added in version 3.3. 4152 * 4153 * @ingroup window 4154 */ 4155GLFWAPI void glfwSetWindowAttrib(GLFWwindow* window, int attrib, int value); 4156 4157/*! @brief Sets the user pointer of the specified window. 4158 * 4159 * This function sets the user-defined pointer of the specified window. The 4160 * current value is retained until the window is destroyed. The initial value 4161 * is `NULL`. 4162 * 4163 * @param[in] window The window whose pointer to set. 4164 * @param[in] pointer The new value. 4165 * 4166 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 4167 * 4168 * @thread_safety This function may be called from any thread. Access is not 4169 * synchronized. 4170 * 4171 * @sa @ref window_userptr 4172 * @sa @ref glfwGetWindowUserPointer 4173 * 4174 * @since Added in version 3.0. 4175 * 4176 * @ingroup window 4177 */ 4178GLFWAPI void glfwSetWindowUserPointer(GLFWwindow* window, void* pointer); 4179 4180/*! @brief Returns the user pointer of the specified window. 4181 * 4182 * This function returns the current value of the user-defined pointer of the 4183 * specified window. The initial value is `NULL`. 4184 * 4185 * @param[in] window The window whose pointer to return. 4186 * 4187 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 4188 * 4189 * @thread_safety This function may be called from any thread. Access is not 4190 * synchronized. 4191 * 4192 * @sa @ref window_userptr 4193 * @sa @ref glfwSetWindowUserPointer 4194 * 4195 * @since Added in version 3.0. 4196 * 4197 * @ingroup window 4198 */ 4199GLFWAPI void* glfwGetWindowUserPointer(GLFWwindow* window); 4200 4201/*! @brief Sets the position callback for the specified window. 4202 * 4203 * This function sets the position callback of the specified window, which is 4204 * called when the window is moved. The callback is provided with the 4205 * position, in screen coordinates, of the upper-left corner of the content 4206 * area of the window. 4207 * 4208 * @param[in] window The window whose callback to set. 4209 * @param[in] callback The new callback, or `NULL` to remove the currently set 4210 * callback. 4211 * @return The previously set callback, or `NULL` if no callback was set or the 4212 * library had not been [initialized](@ref intro_init). 4213 * 4214 * @callback_signature 4215 * @code 4216 * void function_name(GLFWwindow* window, int xpos, int ypos) 4217 * @endcode 4218 * For more information about the callback parameters, see the 4219 * [function pointer type](@ref GLFWwindowposfun). 4220 * 4221 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 4222 * 4223 * @remark __Wayland:__ This callback will not be called. The Wayland protocol 4224 * provides no way to be notified of when a window is moved. 4225 * 4226 * @thread_safety This function must only be called from the main thread. 4227 * 4228 * @sa @ref window_pos 4229 * 4230 * @since Added in version 3.0. 4231 * 4232 * @ingroup window 4233 */ 4234GLFWAPI GLFWwindowposfun glfwSetWindowPosCallback(GLFWwindow* window, GLFWwindowposfun callback); 4235 4236/*! @brief Sets the size callback for the specified window. 4237 * 4238 * This function sets the size callback of the specified window, which is 4239 * called when the window is resized. The callback is provided with the size, 4240 * in screen coordinates, of the content area of the window. 4241 * 4242 * @param[in] window The window whose callback to set. 4243 * @param[in] callback The new callback, or `NULL` to remove the currently set 4244 * callback. 4245 * @return The previously set callback, or `NULL` if no callback was set or the 4246 * library had not been [initialized](@ref intro_init). 4247 * 4248 * @callback_signature 4249 * @code 4250 * void function_name(GLFWwindow* window, int width, int height) 4251 * @endcode 4252 * For more information about the callback parameters, see the 4253 * [function pointer type](@ref GLFWwindowsizefun). 4254 * 4255 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 4256 * 4257 * @thread_safety This function must only be called from the main thread. 4258 * 4259 * @sa @ref window_size 4260 * 4261 * @since Added in version 1.0. 4262 * __GLFW 3:__ Added window handle parameter and return value. 4263 * 4264 * @ingroup window 4265 */ 4266GLFWAPI GLFWwindowsizefun glfwSetWindowSizeCallback(GLFWwindow* window, GLFWwindowsizefun callback); 4267 4268/*! @brief Sets the close callback for the specified window. 4269 * 4270 * This function sets the close callback of the specified window, which is 4271 * called when the user attempts to close the window, for example by clicking 4272 * the close widget in the title bar. 4273 * 4274 * The close flag is set before this callback is called, but you can modify it 4275 * at any time with @ref glfwSetWindowShouldClose. 4276 * 4277 * The close callback is not triggered by @ref glfwDestroyWindow. 4278 * 4279 * @param[in] window The window whose callback to set. 4280 * @param[in] callback The new callback, or `NULL` to remove the currently set 4281 * callback. 4282 * @return The previously set callback, or `NULL` if no callback was set or the 4283 * library had not been [initialized](@ref intro_init). 4284 * 4285 * @callback_signature 4286 * @code 4287 * void function_name(GLFWwindow* window) 4288 * @endcode 4289 * For more information about the callback parameters, see the 4290 * [function pointer type](@ref GLFWwindowclosefun). 4291 * 4292 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 4293 * 4294 * @remark __macOS:__ Selecting Quit from the application menu will trigger the 4295 * close callback for all windows. 4296 * 4297 * @thread_safety This function must only be called from the main thread. 4298 * 4299 * @sa @ref window_close 4300 * 4301 * @since Added in version 2.5. 4302 * __GLFW 3:__ Added window handle parameter and return value. 4303 * 4304 * @ingroup window 4305 */ 4306GLFWAPI GLFWwindowclosefun glfwSetWindowCloseCallback(GLFWwindow* window, GLFWwindowclosefun callback); 4307 4308/*! @brief Sets the refresh callback for the specified window. 4309 * 4310 * This function sets the refresh callback of the specified window, which is 4311 * called when the content area of the window needs to be redrawn, for example 4312 * if the window has been exposed after having been covered by another window. 4313 * 4314 * On compositing window systems such as Aero, Compiz, Aqua or Wayland, where 4315 * the window contents are saved off-screen, this callback may be called only 4316 * very infrequently or never at all. 4317 * 4318 * @param[in] window The window whose callback to set. 4319 * @param[in] callback The new callback, or `NULL` to remove the currently set 4320 * callback. 4321 * @return The previously set callback, or `NULL` if no callback was set or the 4322 * library had not been [initialized](@ref intro_init). 4323 * 4324 * @callback_signature 4325 * @code 4326 * void function_name(GLFWwindow* window); 4327 * @endcode 4328 * For more information about the callback parameters, see the 4329 * [function pointer type](@ref GLFWwindowrefreshfun). 4330 * 4331 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 4332 * 4333 * @thread_safety This function must only be called from the main thread. 4334 * 4335 * @sa @ref window_refresh 4336 * 4337 * @since Added in version 2.5. 4338 * __GLFW 3:__ Added window handle parameter and return value. 4339 * 4340 * @ingroup window 4341 */ 4342GLFWAPI GLFWwindowrefreshfun glfwSetWindowRefreshCallback(GLFWwindow* window, GLFWwindowrefreshfun callback); 4343 4344/*! @brief Sets the focus callback for the specified window. 4345 * 4346 * This function sets the focus callback of the specified window, which is 4347 * called when the window gains or loses input focus. 4348 * 4349 * After the focus callback is called for a window that lost input focus, 4350 * synthetic key and mouse button release events will be generated for all such 4351 * that had been pressed. For more information, see @ref glfwSetKeyCallback 4352 * and @ref glfwSetMouseButtonCallback. 4353 * 4354 * @param[in] window The window whose callback to set. 4355 * @param[in] callback The new callback, or `NULL` to remove the currently set 4356 * callback. 4357 * @return The previously set callback, or `NULL` if no callback was set or the 4358 * library had not been [initialized](@ref intro_init). 4359 * 4360 * @callback_signature 4361 * @code 4362 * void function_name(GLFWwindow* window, int focused) 4363 * @endcode 4364 * For more information about the callback parameters, see the 4365 * [function pointer type](@ref GLFWwindowfocusfun). 4366 * 4367 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 4368 * 4369 * @thread_safety This function must only be called from the main thread. 4370 * 4371 * @sa @ref window_focus 4372 * 4373 * @since Added in version 3.0. 4374 * 4375 * @ingroup window 4376 */ 4377GLFWAPI GLFWwindowfocusfun glfwSetWindowFocusCallback(GLFWwindow* window, GLFWwindowfocusfun callback); 4378 4379/*! @brief Sets the iconify callback for the specified window. 4380 * 4381 * This function sets the iconification callback of the specified window, which 4382 * is called when the window is iconified or restored. 4383 * 4384 * @param[in] window The window whose callback to set. 4385 * @param[in] callback The new callback, or `NULL` to remove the currently set 4386 * callback. 4387 * @return The previously set callback, or `NULL` if no callback was set or the 4388 * library had not been [initialized](@ref intro_init). 4389 * 4390 * @callback_signature 4391 * @code 4392 * void function_name(GLFWwindow* window, int iconified) 4393 * @endcode 4394 * For more information about the callback parameters, see the 4395 * [function pointer type](@ref GLFWwindowiconifyfun). 4396 * 4397 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 4398 * 4399 * @remark __Wayland:__ This callback will not be called. The Wayland protocol 4400 * provides no way to be notified of when a window is iconified, and no way to 4401 * check whether a window is currently iconified. 4402 * 4403 * @thread_safety This function must only be called from the main thread. 4404 * 4405 * @sa @ref window_iconify 4406 * 4407 * @since Added in version 3.0. 4408 * 4409 * @ingroup window 4410 */ 4411GLFWAPI GLFWwindowiconifyfun glfwSetWindowIconifyCallback(GLFWwindow* window, GLFWwindowiconifyfun callback); 4412 4413/*! @brief Sets the maximize callback for the specified window. 4414 * 4415 * This function sets the maximization callback of the specified window, which 4416 * is called when the window is maximized or restored. 4417 * 4418 * @param[in] window The window whose callback to set. 4419 * @param[in] callback The new callback, or `NULL` to remove the currently set 4420 * callback. 4421 * @return The previously set callback, or `NULL` if no callback was set or the 4422 * library had not been [initialized](@ref intro_init). 4423 * 4424 * @callback_signature 4425 * @code 4426 * void function_name(GLFWwindow* window, int maximized) 4427 * @endcode 4428 * For more information about the callback parameters, see the 4429 * [function pointer type](@ref GLFWwindowmaximizefun). 4430 * 4431 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 4432 * 4433 * @thread_safety This function must only be called from the main thread. 4434 * 4435 * @sa @ref window_maximize 4436 * 4437 * @since Added in version 3.3. 4438 * 4439 * @ingroup window 4440 */ 4441GLFWAPI GLFWwindowmaximizefun glfwSetWindowMaximizeCallback(GLFWwindow* window, GLFWwindowmaximizefun callback); 4442 4443/*! @brief Sets the framebuffer resize callback for the specified window. 4444 * 4445 * This function sets the framebuffer resize callback of the specified window, 4446 * which is called when the framebuffer of the specified window is resized. 4447 * 4448 * @param[in] window The window whose callback to set. 4449 * @param[in] callback The new callback, or `NULL` to remove the currently set 4450 * callback. 4451 * @return The previously set callback, or `NULL` if no callback was set or the 4452 * library had not been [initialized](@ref intro_init). 4453 * 4454 * @callback_signature 4455 * @code 4456 * void function_name(GLFWwindow* window, int width, int height) 4457 * @endcode 4458 * For more information about the callback parameters, see the 4459 * [function pointer type](@ref GLFWframebuffersizefun). 4460 * 4461 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 4462 * 4463 * @thread_safety This function must only be called from the main thread. 4464 * 4465 * @sa @ref window_fbsize 4466 * 4467 * @since Added in version 3.0. 4468 * 4469 * @ingroup window 4470 */ 4471GLFWAPI GLFWframebuffersizefun glfwSetFramebufferSizeCallback(GLFWwindow* window, GLFWframebuffersizefun callback); 4472 4473/*! @brief Sets the window content scale callback for the specified window. 4474 * 4475 * This function sets the window content scale callback of the specified window, 4476 * which is called when the content scale of the specified window changes. 4477 * 4478 * @param[in] window The window whose callback to set. 4479 * @param[in] callback The new callback, or `NULL` to remove the currently set 4480 * callback. 4481 * @return The previously set callback, or `NULL` if no callback was set or the 4482 * library had not been [initialized](@ref intro_init). 4483 * 4484 * @callback_signature 4485 * @code 4486 * void function_name(GLFWwindow* window, float xscale, float yscale) 4487 * @endcode 4488 * For more information about the callback parameters, see the 4489 * [function pointer type](@ref GLFWwindowcontentscalefun). 4490 * 4491 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 4492 * 4493 * @thread_safety This function must only be called from the main thread. 4494 * 4495 * @sa @ref window_scale 4496 * @sa @ref glfwGetWindowContentScale 4497 * 4498 * @since Added in version 3.3. 4499 * 4500 * @ingroup window 4501 */ 4502GLFWAPI GLFWwindowcontentscalefun glfwSetWindowContentScaleCallback(GLFWwindow* window, GLFWwindowcontentscalefun callback); 4503 4504/*! @brief Processes all pending events. 4505 * 4506 * This function processes only those events that are already in the event 4507 * queue and then returns immediately. Processing events will cause the window 4508 * and input callbacks associated with those events to be called. 4509 * 4510 * On some platforms, a window move, resize or menu operation will cause event 4511 * processing to block. This is due to how event processing is designed on 4512 * those platforms. You can use the 4513 * [window refresh callback](@ref window_refresh) to redraw the contents of 4514 * your window when necessary during such operations. 4515 * 4516 * Do not assume that callbacks you set will _only_ be called in response to 4517 * event processing functions like this one. While it is necessary to poll for 4518 * events, window systems that require GLFW to register callbacks of its own 4519 * can pass events to GLFW in response to many window system function calls. 4520 * GLFW will pass those events on to the application callbacks before 4521 * returning. 4522 * 4523 * Event processing is not required for joystick input to work. 4524 * 4525 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 4526 * GLFW_PLATFORM_ERROR. 4527 * 4528 * @reentrancy This function must not be called from a callback. 4529 * 4530 * @thread_safety This function must only be called from the main thread. 4531 * 4532 * @sa @ref events 4533 * @sa @ref glfwWaitEvents 4534 * @sa @ref glfwWaitEventsTimeout 4535 * 4536 * @since Added in version 1.0. 4537 * 4538 * @ingroup window 4539 */ 4540GLFWAPI void glfwPollEvents(void); 4541 4542/*! @brief Waits until events are queued and processes them. 4543 * 4544 * This function puts the calling thread to sleep until at least one event is 4545 * available in the event queue. Once one or more events are available, 4546 * it behaves exactly like @ref glfwPollEvents, i.e. the events in the queue 4547 * are processed and the function then returns immediately. Processing events 4548 * will cause the window and input callbacks associated with those events to be 4549 * called. 4550 * 4551 * Since not all events are associated with callbacks, this function may return 4552 * without a callback having been called even if you are monitoring all 4553 * callbacks. 4554 * 4555 * On some platforms, a window move, resize or menu operation will cause event 4556 * processing to block. This is due to how event processing is designed on 4557 * those platforms. You can use the 4558 * [window refresh callback](@ref window_refresh) to redraw the contents of 4559 * your window when necessary during such operations. 4560 * 4561 * Do not assume that callbacks you set will _only_ be called in response to 4562 * event processing functions like this one. While it is necessary to poll for 4563 * events, window systems that require GLFW to register callbacks of its own 4564 * can pass events to GLFW in response to many window system function calls. 4565 * GLFW will pass those events on to the application callbacks before 4566 * returning. 4567 * 4568 * Event processing is not required for joystick input to work. 4569 * 4570 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 4571 * GLFW_PLATFORM_ERROR. 4572 * 4573 * @reentrancy This function must not be called from a callback. 4574 * 4575 * @thread_safety This function must only be called from the main thread. 4576 * 4577 * @sa @ref events 4578 * @sa @ref glfwPollEvents 4579 * @sa @ref glfwWaitEventsTimeout 4580 * 4581 * @since Added in version 2.5. 4582 * 4583 * @ingroup window 4584 */ 4585GLFWAPI void glfwWaitEvents(void); 4586 4587/*! @brief Waits with timeout until events are queued and processes them. 4588 * 4589 * This function puts the calling thread to sleep until at least one event is 4590 * available in the event queue, or until the specified timeout is reached. If 4591 * one or more events are available, it behaves exactly like @ref 4592 * glfwPollEvents, i.e. the events in the queue are processed and the function 4593 * then returns immediately. Processing events will cause the window and input 4594 * callbacks associated with those events to be called. 4595 * 4596 * The timeout value must be a positive finite number. 4597 * 4598 * Since not all events are associated with callbacks, this function may return 4599 * without a callback having been called even if you are monitoring all 4600 * callbacks. 4601 * 4602 * On some platforms, a window move, resize or menu operation will cause event 4603 * processing to block. This is due to how event processing is designed on 4604 * those platforms. You can use the 4605 * [window refresh callback](@ref window_refresh) to redraw the contents of 4606 * your window when necessary during such operations. 4607 * 4608 * Do not assume that callbacks you set will _only_ be called in response to 4609 * event processing functions like this one. While it is necessary to poll for 4610 * events, window systems that require GLFW to register callbacks of its own 4611 * can pass events to GLFW in response to many window system function calls. 4612 * GLFW will pass those events on to the application callbacks before 4613 * returning. 4614 * 4615 * Event processing is not required for joystick input to work. 4616 * 4617 * @param[in] timeout The maximum amount of time, in seconds, to wait. 4618 * 4619 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref 4620 * GLFW_INVALID_VALUE and @ref GLFW_PLATFORM_ERROR. 4621 * 4622 * @reentrancy This function must not be called from a callback. 4623 * 4624 * @thread_safety This function must only be called from the main thread. 4625 * 4626 * @sa @ref events 4627 * @sa @ref glfwPollEvents 4628 * @sa @ref glfwWaitEvents 4629 * 4630 * @since Added in version 3.2. 4631 * 4632 * @ingroup window 4633 */ 4634GLFWAPI void glfwWaitEventsTimeout(double timeout); 4635 4636/*! @brief Posts an empty event to the event queue. 4637 * 4638 * This function posts an empty event from the current thread to the event 4639 * queue, causing @ref glfwWaitEvents or @ref glfwWaitEventsTimeout to return. 4640 * 4641 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 4642 * GLFW_PLATFORM_ERROR. 4643 * 4644 * @thread_safety This function may be called from any thread. 4645 * 4646 * @sa @ref events 4647 * @sa @ref glfwWaitEvents 4648 * @sa @ref glfwWaitEventsTimeout 4649 * 4650 * @since Added in version 3.1. 4651 * 4652 * @ingroup window 4653 */ 4654GLFWAPI void glfwPostEmptyEvent(void); 4655 4656/*! @brief Returns the value of an input option for the specified window. 4657 * 4658 * This function returns the value of an input option for the specified window. 4659 * The mode must be one of @ref GLFW_CURSOR, @ref GLFW_STICKY_KEYS, 4660 * @ref GLFW_STICKY_MOUSE_BUTTONS, @ref GLFW_LOCK_KEY_MODS or 4661 * @ref GLFW_RAW_MOUSE_MOTION. 4662 * 4663 * @param[in] window The window to query. 4664 * @param[in] mode One of `GLFW_CURSOR`, `GLFW_STICKY_KEYS`, 4665 * `GLFW_STICKY_MOUSE_BUTTONS`, `GLFW_LOCK_KEY_MODS` or 4666 * `GLFW_RAW_MOUSE_MOTION`. 4667 * 4668 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 4669 * GLFW_INVALID_ENUM. 4670 * 4671 * @thread_safety This function must only be called from the main thread. 4672 * 4673 * @sa @ref glfwSetInputMode 4674 * 4675 * @since Added in version 3.0. 4676 * 4677 * @ingroup input 4678 */ 4679GLFWAPI int glfwGetInputMode(GLFWwindow* window, int mode); 4680 4681/*! @brief Sets an input option for the specified window. 4682 * 4683 * This function sets an input mode option for the specified window. The mode 4684 * must be one of @ref GLFW_CURSOR, @ref GLFW_STICKY_KEYS, 4685 * @ref GLFW_STICKY_MOUSE_BUTTONS, @ref GLFW_LOCK_KEY_MODS 4686 * @ref GLFW_RAW_MOUSE_MOTION, or @ref GLFW_UNLIMITED_MOUSE_BUTTONS. 4687 * 4688 * If the mode is `GLFW_CURSOR`, the value must be one of the following cursor 4689 * modes: 4690 * - `GLFW_CURSOR_NORMAL` makes the cursor visible and behaving normally. 4691 * - `GLFW_CURSOR_HIDDEN` makes the cursor invisible when it is over the 4692 * content area of the window but does not restrict the cursor from leaving. 4693 * - `GLFW_CURSOR_DISABLED` hides and grabs the cursor, providing virtual 4694 * and unlimited cursor movement. This is useful for implementing for 4695 * example 3D camera controls. 4696 * - `GLFW_CURSOR_CAPTURED` makes the cursor visible and confines it to the 4697 * content area of the window. 4698 * 4699 * If the mode is `GLFW_STICKY_KEYS`, the value must be either `GLFW_TRUE` to 4700 * enable sticky keys, or `GLFW_FALSE` to disable it. If sticky keys are 4701 * enabled, a key press will ensure that @ref glfwGetKey returns `GLFW_PRESS` 4702 * the next time it is called even if the key had been released before the 4703 * call. This is useful when you are only interested in whether keys have been 4704 * pressed but not when or in which order. 4705 * 4706 * If the mode is `GLFW_STICKY_MOUSE_BUTTONS`, the value must be either 4707 * `GLFW_TRUE` to enable sticky mouse buttons, or `GLFW_FALSE` to disable it. 4708 * If sticky mouse buttons are enabled, a mouse button press will ensure that 4709 * @ref glfwGetMouseButton returns `GLFW_PRESS` the next time it is called even 4710 * if the mouse button had been released before the call. This is useful when 4711 * you are only interested in whether mouse buttons have been pressed but not 4712 * when or in which order. 4713 * 4714 * If the mode is `GLFW_LOCK_KEY_MODS`, the value must be either `GLFW_TRUE` to 4715 * enable lock key modifier bits, or `GLFW_FALSE` to disable them. If enabled, 4716 * callbacks that receive modifier bits will also have the @ref 4717 * GLFW_MOD_CAPS_LOCK bit set when the event was generated with Caps Lock on, 4718 * and the @ref GLFW_MOD_NUM_LOCK bit when Num Lock was on. 4719 * 4720 * If the mode is `GLFW_RAW_MOUSE_MOTION`, the value must be either `GLFW_TRUE` 4721 * to enable raw (unscaled and unaccelerated) mouse motion when the cursor is 4722 * disabled, or `GLFW_FALSE` to disable it. If raw motion is not supported, 4723 * attempting to set this will emit @ref GLFW_FEATURE_UNAVAILABLE. Call @ref 4724 * glfwRawMouseMotionSupported to check for support. 4725 * 4726 * If the mode is `GLFW_UNLIMITED_MOUSE_BUTTONS`, the value must be either 4727 * `GLFW_TRUE` to disable the mouse button limit when calling the mouse button 4728 * callback, or `GLFW_FALSE` to limit the mouse buttons sent to the callback 4729 * to the mouse button token values up to `GLFW_MOUSE_BUTTON_LAST`. 4730 * 4731 * @param[in] window The window whose input mode to set. 4732 * @param[in] mode One of `GLFW_CURSOR`, `GLFW_STICKY_KEYS`, 4733 * `GLFW_STICKY_MOUSE_BUTTONS`, `GLFW_LOCK_KEY_MODS` or 4734 * `GLFW_RAW_MOUSE_MOTION`. 4735 * @param[in] value The new value of the specified input mode. 4736 * 4737 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref 4738 * GLFW_INVALID_ENUM, @ref GLFW_PLATFORM_ERROR and @ref 4739 * GLFW_FEATURE_UNAVAILABLE (see above). 4740 * 4741 * @thread_safety This function must only be called from the main thread. 4742 * 4743 * @sa @ref glfwGetInputMode 4744 * 4745 * @since Added in version 3.0. Replaces `glfwEnable` and `glfwDisable`. 4746 * 4747 * @ingroup input 4748 */ 4749GLFWAPI void glfwSetInputMode(GLFWwindow* window, int mode, int value); 4750 4751/*! @brief Returns whether raw mouse motion is supported. 4752 * 4753 * This function returns whether raw mouse motion is supported on the current 4754 * system. This status does not change after GLFW has been initialized so you 4755 * only need to check this once. If you attempt to enable raw motion on 4756 * a system that does not support it, @ref GLFW_PLATFORM_ERROR will be emitted. 4757 * 4758 * Raw mouse motion is closer to the actual motion of the mouse across 4759 * a surface. It is not affected by the scaling and acceleration applied to 4760 * the motion of the desktop cursor. That processing is suitable for a cursor 4761 * while raw motion is better for controlling for example a 3D camera. Because 4762 * of this, raw mouse motion is only provided when the cursor is disabled. 4763 * 4764 * @return `GLFW_TRUE` if raw mouse motion is supported on the current machine, 4765 * or `GLFW_FALSE` otherwise. 4766 * 4767 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 4768 * 4769 * @thread_safety This function must only be called from the main thread. 4770 * 4771 * @sa @ref raw_mouse_motion 4772 * @sa @ref glfwSetInputMode 4773 * 4774 * @since Added in version 3.3. 4775 * 4776 * @ingroup input 4777 */ 4778GLFWAPI int glfwRawMouseMotionSupported(void); 4779 4780/*! @brief Returns the layout-specific name of the specified printable key. 4781 * 4782 * This function returns the name of the specified printable key, encoded as 4783 * UTF-8. This is typically the character that key would produce without any 4784 * modifier keys, intended for displaying key bindings to the user. For dead 4785 * keys, it is typically the diacritic it would add to a character. 4786 * 4787 * __Do not use this function__ for [text input](@ref input_char). You will 4788 * break text input for many languages even if it happens to work for yours. 4789 * 4790 * If the key is `GLFW_KEY_UNKNOWN`, the scancode is used to identify the key, 4791 * otherwise the scancode is ignored. If you specify a non-printable key, or 4792 * `GLFW_KEY_UNKNOWN` and a scancode that maps to a non-printable key, this 4793 * function returns `NULL` but does not emit an error. 4794 * 4795 * This behavior allows you to always pass in the arguments in the 4796 * [key callback](@ref input_key) without modification. 4797 * 4798 * The printable keys are: 4799 * - `GLFW_KEY_APOSTROPHE` 4800 * - `GLFW_KEY_COMMA` 4801 * - `GLFW_KEY_MINUS` 4802 * - `GLFW_KEY_PERIOD` 4803 * - `GLFW_KEY_SLASH` 4804 * - `GLFW_KEY_SEMICOLON` 4805 * - `GLFW_KEY_EQUAL` 4806 * - `GLFW_KEY_LEFT_BRACKET` 4807 * - `GLFW_KEY_RIGHT_BRACKET` 4808 * - `GLFW_KEY_BACKSLASH` 4809 * - `GLFW_KEY_WORLD_1` 4810 * - `GLFW_KEY_WORLD_2` 4811 * - `GLFW_KEY_0` to `GLFW_KEY_9` 4812 * - `GLFW_KEY_A` to `GLFW_KEY_Z` 4813 * - `GLFW_KEY_KP_0` to `GLFW_KEY_KP_9` 4814 * - `GLFW_KEY_KP_DECIMAL` 4815 * - `GLFW_KEY_KP_DIVIDE` 4816 * - `GLFW_KEY_KP_MULTIPLY` 4817 * - `GLFW_KEY_KP_SUBTRACT` 4818 * - `GLFW_KEY_KP_ADD` 4819 * - `GLFW_KEY_KP_EQUAL` 4820 * 4821 * Names for printable keys depend on keyboard layout, while names for 4822 * non-printable keys are the same across layouts but depend on the application 4823 * language and should be localized along with other user interface text. 4824 * 4825 * @param[in] key The key to query, or `GLFW_KEY_UNKNOWN`. 4826 * @param[in] scancode The scancode of the key to query. 4827 * @return The UTF-8 encoded, layout-specific name of the key, or `NULL`. 4828 * 4829 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref 4830 * GLFW_INVALID_VALUE, @ref GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR. 4831 * 4832 * @remark The contents of the returned string may change when a keyboard 4833 * layout change event is received. 4834 * 4835 * @pointer_lifetime The returned string is allocated and freed by GLFW. You 4836 * should not free it yourself. It is valid until the library is terminated. 4837 * 4838 * @thread_safety This function must only be called from the main thread. 4839 * 4840 * @sa @ref input_key_name 4841 * 4842 * @since Added in version 3.2. 4843 * 4844 * @ingroup input 4845 */ 4846GLFWAPI const char* glfwGetKeyName(int key, int scancode); 4847 4848/*! @brief Returns the platform-specific scancode of the specified key. 4849 * 4850 * This function returns the platform-specific scancode of the specified key. 4851 * 4852 * If the specified [key token](@ref keys) corresponds to a physical key not 4853 * supported on the current platform then this method will return `-1`. 4854 * Calling this function with anything other than a key token will return `-1` 4855 * and generate a @ref GLFW_INVALID_ENUM error. 4856 * 4857 * @param[in] key Any [key token](@ref keys). 4858 * @return The platform-specific scancode for the key, or `-1` if the key is 4859 * not supported on the current platform or an [error](@ref error_handling) 4860 * occurred. 4861 * 4862 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 4863 * GLFW_INVALID_ENUM. 4864 * 4865 * @thread_safety This function may be called from any thread. 4866 * 4867 * @sa @ref input_key 4868 * 4869 * @since Added in version 3.3. 4870 * 4871 * @ingroup input 4872 */ 4873GLFWAPI int glfwGetKeyScancode(int key); 4874 4875/*! @brief Returns the last reported state of a keyboard key for the specified 4876 * window. 4877 * 4878 * This function returns the last state reported for the specified key to the 4879 * specified window. The returned state is one of `GLFW_PRESS` or 4880 * `GLFW_RELEASE`. The action `GLFW_REPEAT` is only reported to the key callback. 4881 * 4882 * If the @ref GLFW_STICKY_KEYS input mode is enabled, this function returns 4883 * `GLFW_PRESS` the first time you call it for a key that was pressed, even if 4884 * that key has already been released. 4885 * 4886 * The key functions deal with physical keys, with [key tokens](@ref keys) 4887 * named after their use on the standard US keyboard layout. If you want to 4888 * input text, use the Unicode character callback instead. 4889 * 4890 * The [modifier key bit masks](@ref mods) are not key tokens and cannot be 4891 * used with this function. 4892 * 4893 * __Do not use this function__ to implement [text input](@ref input_char). 4894 * 4895 * @param[in] window The desired window. 4896 * @param[in] key The desired [keyboard key](@ref keys). `GLFW_KEY_UNKNOWN` is 4897 * not a valid key for this function. 4898 * @return One of `GLFW_PRESS` or `GLFW_RELEASE`. 4899 * 4900 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 4901 * GLFW_INVALID_ENUM. 4902 * 4903 * @thread_safety This function must only be called from the main thread. 4904 * 4905 * @sa @ref input_key 4906 * 4907 * @since Added in version 1.0. 4908 * __GLFW 3:__ Added window handle parameter. 4909 * 4910 * @ingroup input 4911 */ 4912GLFWAPI int glfwGetKey(GLFWwindow* window, int key); 4913 4914/*! @brief Returns the last reported state of a mouse button for the specified 4915 * window. 4916 * 4917 * This function returns the last state reported for the specified mouse button 4918 * to the specified window. The returned state is one of `GLFW_PRESS` or 4919 * `GLFW_RELEASE`. 4920 * 4921 * If the @ref GLFW_STICKY_MOUSE_BUTTONS input mode is enabled, this function 4922 * returns `GLFW_PRESS` the first time you call it for a mouse button that was 4923 * pressed, even if that mouse button has already been released. 4924 * 4925 * The @ref GLFW_UNLIMITED_MOUSE_BUTTONS input mode does not effect the 4926 * limit on buttons which can be polled with this function. 4927 * 4928 * @param[in] window The desired window. 4929 * @param[in] button The desired [mouse button token](@ref buttons). 4930 * @return One of `GLFW_PRESS` or `GLFW_RELEASE`. 4931 * 4932 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 4933 * GLFW_INVALID_ENUM. 4934 * 4935 * @thread_safety This function must only be called from the main thread. 4936 * 4937 * @sa @ref input_mouse_button 4938 * 4939 * @since Added in version 1.0. 4940 * __GLFW 3:__ Added window handle parameter. 4941 * 4942 * @ingroup input 4943 */ 4944GLFWAPI int glfwGetMouseButton(GLFWwindow* window, int button); 4945 4946/*! @brief Retrieves the position of the cursor relative to the content area of 4947 * the window. 4948 * 4949 * This function returns the position of the cursor, in screen coordinates, 4950 * relative to the upper-left corner of the content area of the specified 4951 * window. 4952 * 4953 * If the cursor is disabled (with `GLFW_CURSOR_DISABLED`) then the cursor 4954 * position is unbounded and limited only by the minimum and maximum values of 4955 * a `double`. 4956 * 4957 * The coordinate can be converted to their integer equivalents with the 4958 * `floor` function. Casting directly to an integer type works for positive 4959 * coordinates, but fails for negative ones. 4960 * 4961 * Any or all of the position arguments may be `NULL`. If an error occurs, all 4962 * non-`NULL` position arguments will be set to zero. 4963 * 4964 * @param[in] window The desired window. 4965 * @param[out] xpos Where to store the cursor x-coordinate, relative to the 4966 * left edge of the content area, or `NULL`. 4967 * @param[out] ypos Where to store the cursor y-coordinate, relative to the to 4968 * top edge of the content area, or `NULL`. 4969 * 4970 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 4971 * GLFW_PLATFORM_ERROR. 4972 * 4973 * @thread_safety This function must only be called from the main thread. 4974 * 4975 * @sa @ref cursor_pos 4976 * @sa @ref glfwSetCursorPos 4977 * 4978 * @since Added in version 3.0. Replaces `glfwGetMousePos`. 4979 * 4980 * @ingroup input 4981 */ 4982GLFWAPI void glfwGetCursorPos(GLFWwindow* window, double* xpos, double* ypos); 4983 4984/*! @brief Sets the position of the cursor, relative to the content area of the 4985 * window. 4986 * 4987 * This function sets the position, in screen coordinates, of the cursor 4988 * relative to the upper-left corner of the content area of the specified 4989 * window. The window must have input focus. If the window does not have 4990 * input focus when this function is called, it fails silently. 4991 * 4992 * __Do not use this function__ to implement things like camera controls. GLFW 4993 * already provides the `GLFW_CURSOR_DISABLED` cursor mode that hides the 4994 * cursor, transparently re-centers it and provides unconstrained cursor 4995 * motion. See @ref glfwSetInputMode for more information. 4996 * 4997 * If the cursor mode is `GLFW_CURSOR_DISABLED` then the cursor position is 4998 * unconstrained and limited only by the minimum and maximum values of 4999 * a `double`. 5000 * 5001 * @param[in] window The desired window. 5002 * @param[in] xpos The desired x-coordinate, relative to the left edge of the 5003 * content area. 5004 * @param[in] ypos The desired y-coordinate, relative to the top edge of the 5005 * content area. 5006 * 5007 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref 5008 * GLFW_PLATFORM_ERROR and @ref GLFW_FEATURE_UNAVAILABLE (see remarks). 5009 * 5010 * @remark __Wayland:__ This function will only work when the cursor mode is 5011 * `GLFW_CURSOR_DISABLED`, otherwise it will emit @ref GLFW_FEATURE_UNAVAILABLE. 5012 * 5013 * @thread_safety This function must only be called from the main thread. 5014 * 5015 * @sa @ref cursor_pos 5016 * @sa @ref glfwGetCursorPos 5017 * 5018 * @since Added in version 3.0. Replaces `glfwSetMousePos`. 5019 * 5020 * @ingroup input 5021 */ 5022GLFWAPI void glfwSetCursorPos(GLFWwindow* window, double xpos, double ypos); 5023 5024/*! @brief Creates a custom cursor. 5025 * 5026 * Creates a new custom cursor image that can be set for a window with @ref 5027 * glfwSetCursor. The cursor can be destroyed with @ref glfwDestroyCursor. 5028 * Any remaining cursors are destroyed by @ref glfwTerminate. 5029 * 5030 * The pixels are 32-bit, little-endian, non-premultiplied RGBA, i.e. eight 5031 * bits per channel with the red channel first. They are arranged canonically 5032 * as packed sequential rows, starting from the top-left corner. 5033 * 5034 * The cursor hotspot is specified in pixels, relative to the upper-left corner 5035 * of the cursor image. Like all other coordinate systems in GLFW, the X-axis 5036 * points to the right and the Y-axis points down. 5037 * 5038 * @param[in] image The desired cursor image. 5039 * @param[in] xhot The desired x-coordinate, in pixels, of the cursor hotspot. 5040 * @param[in] yhot The desired y-coordinate, in pixels, of the cursor hotspot. 5041 * @return The handle of the created cursor, or `NULL` if an 5042 * [error](@ref error_handling) occurred. 5043 * 5044 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref 5045 * GLFW_INVALID_VALUE and @ref GLFW_PLATFORM_ERROR. 5046 * 5047 * @pointer_lifetime The specified image data is copied before this function 5048 * returns. 5049 * 5050 * @thread_safety This function must only be called from the main thread. 5051 * 5052 * @sa @ref cursor_object 5053 * @sa @ref glfwDestroyCursor 5054 * @sa @ref glfwCreateStandardCursor 5055 * 5056 * @since Added in version 3.1. 5057 * 5058 * @ingroup input 5059 */ 5060GLFWAPI GLFWcursor* glfwCreateCursor(const GLFWimage* image, int xhot, int yhot); 5061 5062/*! @brief Creates a cursor with a standard shape. 5063 * 5064 * Returns a cursor with a standard shape, that can be set for a window with 5065 * @ref glfwSetCursor. The images for these cursors come from the system 5066 * cursor theme and their exact appearance will vary between platforms. 5067 * 5068 * Most of these shapes are guaranteed to exist on every supported platform but 5069 * a few may not be present. See the table below for details. 5070 * 5071 * Cursor shape | Windows | macOS | X11 | Wayland 5072 * ------------------------------ | ------- | ----- | ------ | ------- 5073 * @ref GLFW_ARROW_CURSOR | Yes | Yes | Yes | Yes 5074 * @ref GLFW_IBEAM_CURSOR | Yes | Yes | Yes | Yes 5075 * @ref GLFW_CROSSHAIR_CURSOR | Yes | Yes | Yes | Yes 5076 * @ref GLFW_POINTING_HAND_CURSOR | Yes | Yes | Yes | Yes 5077 * @ref GLFW_RESIZE_EW_CURSOR | Yes | Yes | Yes | Yes 5078 * @ref GLFW_RESIZE_NS_CURSOR | Yes | Yes | Yes | Yes 5079 * @ref GLFW_RESIZE_NWSE_CURSOR | Yes | Yes<sup>1</sup> | Maybe<sup>2</sup> | Maybe<sup>2</sup> 5080 * @ref GLFW_RESIZE_NESW_CURSOR | Yes | Yes<sup>1</sup> | Maybe<sup>2</sup> | Maybe<sup>2</sup> 5081 * @ref GLFW_RESIZE_ALL_CURSOR | Yes | Yes | Yes | Yes 5082 * @ref GLFW_NOT_ALLOWED_CURSOR | Yes | Yes | Maybe<sup>2</sup> | Maybe<sup>2</sup> 5083 * 5084 * 1) This uses a private system API and may fail in the future. 5085 * 5086 * 2) This uses a newer standard that not all cursor themes support. 5087 * 5088 * If the requested shape is not available, this function emits a @ref 5089 * GLFW_CURSOR_UNAVAILABLE error and returns `NULL`. 5090 * 5091 * @param[in] shape One of the [standard shapes](@ref shapes). 5092 * @return A new cursor ready to use or `NULL` if an 5093 * [error](@ref error_handling) occurred. 5094 * 5095 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref 5096 * GLFW_INVALID_ENUM, @ref GLFW_CURSOR_UNAVAILABLE and @ref 5097 * GLFW_PLATFORM_ERROR. 5098 * 5099 * @thread_safety This function must only be called from the main thread. 5100 * 5101 * @sa @ref cursor_standard 5102 * @sa @ref glfwCreateCursor 5103 * 5104 * @since Added in version 3.1. 5105 * 5106 * @ingroup input 5107 */ 5108GLFWAPI GLFWcursor* glfwCreateStandardCursor(int shape); 5109 5110/*! @brief Destroys a cursor. 5111 * 5112 * This function destroys a cursor previously created with @ref 5113 * glfwCreateCursor. Any remaining cursors will be destroyed by @ref 5114 * glfwTerminate. 5115 * 5116 * If the specified cursor is current for any window, that window will be 5117 * reverted to the default cursor. This does not affect the cursor mode. 5118 * 5119 * @param[in] cursor The cursor object to destroy. 5120 * 5121 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 5122 * GLFW_PLATFORM_ERROR. 5123 * 5124 * @reentrancy This function must not be called from a callback. 5125 * 5126 * @thread_safety This function must only be called from the main thread. 5127 * 5128 * @sa @ref cursor_object 5129 * @sa @ref glfwCreateCursor 5130 * 5131 * @since Added in version 3.1. 5132 * 5133 * @ingroup input 5134 */ 5135GLFWAPI void glfwDestroyCursor(GLFWcursor* cursor); 5136 5137/*! @brief Sets the cursor for the window. 5138 * 5139 * This function sets the cursor image to be used when the cursor is over the 5140 * content area of the specified window. The set cursor will only be visible 5141 * when the [cursor mode](@ref cursor_mode) of the window is 5142 * `GLFW_CURSOR_NORMAL`. 5143 * 5144 * On some platforms, the set cursor may not be visible unless the window also 5145 * has input focus. 5146 * 5147 * @param[in] window The window to set the cursor for. 5148 * @param[in] cursor The cursor to set, or `NULL` to switch back to the default 5149 * arrow cursor. 5150 * 5151 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 5152 * GLFW_PLATFORM_ERROR. 5153 * 5154 * @thread_safety This function must only be called from the main thread. 5155 * 5156 * @sa @ref cursor_object 5157 * 5158 * @since Added in version 3.1. 5159 * 5160 * @ingroup input 5161 */ 5162GLFWAPI void glfwSetCursor(GLFWwindow* window, GLFWcursor* cursor); 5163 5164/*! @brief Sets the key callback. 5165 * 5166 * This function sets the key callback of the specified window, which is called 5167 * when a key is pressed, repeated or released. 5168 * 5169 * The key functions deal with physical keys, with layout independent 5170 * [key tokens](@ref keys) named after their values in the standard US keyboard 5171 * layout. If you want to input text, use the 5172 * [character callback](@ref glfwSetCharCallback) instead. 5173 * 5174 * When a window loses input focus, it will generate synthetic key release 5175 * events for all pressed keys with associated key tokens. You can tell these 5176 * events from user-generated events by the fact that the synthetic ones are 5177 * generated after the focus loss event has been processed, i.e. after the 5178 * [window focus callback](@ref glfwSetWindowFocusCallback) has been called. 5179 * 5180 * The scancode of a key is specific to that platform or sometimes even to that 5181 * machine. Scancodes are intended to allow users to bind keys that don't have 5182 * a GLFW key token. Such keys have `key` set to `GLFW_KEY_UNKNOWN`, their 5183 * state is not saved and so it cannot be queried with @ref glfwGetKey. 5184 * 5185 * Sometimes GLFW needs to generate synthetic key events, in which case the 5186 * scancode may be zero. 5187 * 5188 * @param[in] window The window whose callback to set. 5189 * @param[in] callback The new key callback, or `NULL` to remove the currently 5190 * set callback. 5191 * @return The previously set callback, or `NULL` if no callback was set or the 5192 * library had not been [initialized](@ref intro_init). 5193 * 5194 * @callback_signature 5195 * @code 5196 * void function_name(GLFWwindow* window, int key, int scancode, int action, int mods) 5197 * @endcode 5198 * For more information about the callback parameters, see the 5199 * [function pointer type](@ref GLFWkeyfun). 5200 * 5201 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 5202 * 5203 * @thread_safety This function must only be called from the main thread. 5204 * 5205 * @sa @ref input_key 5206 * 5207 * @since Added in version 1.0. 5208 * __GLFW 3:__ Added window handle parameter and return value. 5209 * 5210 * @ingroup input 5211 */ 5212GLFWAPI GLFWkeyfun glfwSetKeyCallback(GLFWwindow* window, GLFWkeyfun callback); 5213 5214/*! @brief Sets the Unicode character callback. 5215 * 5216 * This function sets the character callback of the specified window, which is 5217 * called when a Unicode character is input. 5218 * 5219 * The character callback is intended for Unicode text input. As it deals with 5220 * characters, it is keyboard layout dependent, whereas the 5221 * [key callback](@ref glfwSetKeyCallback) is not. Characters do not map 1:1 5222 * to physical keys, as a key may produce zero, one or more characters. If you 5223 * want to know whether a specific physical key was pressed or released, see 5224 * the key callback instead. 5225 * 5226 * The character callback behaves as system text input normally does and will 5227 * not be called if modifier keys are held down that would prevent normal text 5228 * input on that platform, for example a Super (Command) key on macOS or Alt key 5229 * on Windows. 5230 * 5231 * @param[in] window The window whose callback to set. 5232 * @param[in] callback The new callback, or `NULL` to remove the currently set 5233 * callback. 5234 * @return The previously set callback, or `NULL` if no callback was set or the 5235 * library had not been [initialized](@ref intro_init). 5236 * 5237 * @callback_signature 5238 * @code 5239 * void function_name(GLFWwindow* window, unsigned int codepoint) 5240 * @endcode 5241 * For more information about the callback parameters, see the 5242 * [function pointer type](@ref GLFWcharfun). 5243 * 5244 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 5245 * 5246 * @thread_safety This function must only be called from the main thread. 5247 * 5248 * @sa @ref input_char 5249 * 5250 * @since Added in version 2.4. 5251 * __GLFW 3:__ Added window handle parameter and return value. 5252 * 5253 * @ingroup input 5254 */ 5255GLFWAPI GLFWcharfun glfwSetCharCallback(GLFWwindow* window, GLFWcharfun callback); 5256 5257/*! @brief Sets the Unicode character with modifiers callback. 5258 * 5259 * This function sets the character with modifiers callback of the specified 5260 * window, which is called when a Unicode character is input regardless of what 5261 * modifier keys are used. 5262 * 5263 * The character with modifiers callback is intended for implementing custom 5264 * Unicode character input. For regular Unicode text input, see the 5265 * [character callback](@ref glfwSetCharCallback). Like the character 5266 * callback, the character with modifiers callback deals with characters and is 5267 * keyboard layout dependent. Characters do not map 1:1 to physical keys, as 5268 * a key may produce zero, one or more characters. If you want to know whether 5269 * a specific physical key was pressed or released, see the 5270 * [key callback](@ref glfwSetKeyCallback) instead. 5271 * 5272 * @param[in] window The window whose callback to set. 5273 * @param[in] callback The new callback, or `NULL` to remove the currently set 5274 * callback. 5275 * @return The previously set callback, or `NULL` if no callback was set or an 5276 * [error](@ref error_handling) occurred. 5277 * 5278 * @callback_signature 5279 * @code 5280 * void function_name(GLFWwindow* window, unsigned int codepoint, int mods) 5281 * @endcode 5282 * For more information about the callback parameters, see the 5283 * [function pointer type](@ref GLFWcharmodsfun). 5284 * 5285 * @deprecated Scheduled for removal in version 4.0. 5286 * 5287 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 5288 * 5289 * @thread_safety This function must only be called from the main thread. 5290 * 5291 * @sa @ref input_char 5292 * 5293 * @since Added in version 3.1. 5294 * 5295 * @ingroup input 5296 */ 5297GLFWAPI GLFWcharmodsfun glfwSetCharModsCallback(GLFWwindow* window, GLFWcharmodsfun callback); 5298 5299/*! @brief Sets the mouse button callback. 5300 * 5301 * This function sets the mouse button callback of the specified window, which 5302 * is called when a mouse button is pressed or released. 5303 * 5304 * When a window loses input focus, it will generate synthetic mouse button 5305 * release events for all pressed mouse buttons with associated button tokens. 5306 * You can tell these events from user-generated events by the fact that the 5307 * synthetic ones are generated after the focus loss event has been processed, 5308 * i.e. after the [window focus callback](@ref glfwSetWindowFocusCallback) has 5309 * been called. 5310 * 5311 * The reported `button` value can be higher than `GLFW_MOUSE_BUTTON_LAST` if 5312 * the button does not have an associated [button token](@ref buttons) and the 5313 * @ref GLFW_UNLIMITED_MOUSE_BUTTONS input mode is set. 5314 * 5315 * @param[in] window The window whose callback to set. 5316 * @param[in] callback The new callback, or `NULL` to remove the currently set 5317 * callback. 5318 * @return The previously set callback, or `NULL` if no callback was set or the 5319 * library had not been [initialized](@ref intro_init). 5320 * 5321 * @callback_signature 5322 * @code 5323 * void function_name(GLFWwindow* window, int button, int action, int mods) 5324 * @endcode 5325 * For more information about the callback parameters, see the 5326 * [function pointer type](@ref GLFWmousebuttonfun). 5327 * 5328 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 5329 * 5330 * @thread_safety This function must only be called from the main thread. 5331 * 5332 * @sa @ref input_mouse_button 5333 * 5334 * @since Added in version 1.0. 5335 * __GLFW 3:__ Added window handle parameter and return value. 5336 * 5337 * @ingroup input 5338 */ 5339GLFWAPI GLFWmousebuttonfun glfwSetMouseButtonCallback(GLFWwindow* window, GLFWmousebuttonfun callback); 5340 5341/*! @brief Sets the cursor position callback. 5342 * 5343 * This function sets the cursor position callback of the specified window, 5344 * which is called when the cursor is moved. The callback is provided with the 5345 * position, in screen coordinates, relative to the upper-left corner of the 5346 * content area of the window. 5347 * 5348 * @param[in] window The window whose callback to set. 5349 * @param[in] callback The new callback, or `NULL` to remove the currently set 5350 * callback. 5351 * @return The previously set callback, or `NULL` if no callback was set or the 5352 * library had not been [initialized](@ref intro_init). 5353 * 5354 * @callback_signature 5355 * @code 5356 * void function_name(GLFWwindow* window, double xpos, double ypos); 5357 * @endcode 5358 * For more information about the callback parameters, see the 5359 * [function pointer type](@ref GLFWcursorposfun). 5360 * 5361 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 5362 * 5363 * @thread_safety This function must only be called from the main thread. 5364 * 5365 * @sa @ref cursor_pos 5366 * 5367 * @since Added in version 3.0. Replaces `glfwSetMousePosCallback`. 5368 * 5369 * @ingroup input 5370 */ 5371GLFWAPI GLFWcursorposfun glfwSetCursorPosCallback(GLFWwindow* window, GLFWcursorposfun callback); 5372 5373/*! @brief Sets the cursor enter/leave callback. 5374 * 5375 * This function sets the cursor boundary crossing callback of the specified 5376 * window, which is called when the cursor enters or leaves the content area of 5377 * the window. 5378 * 5379 * @param[in] window The window whose callback to set. 5380 * @param[in] callback The new callback, or `NULL` to remove the currently set 5381 * callback. 5382 * @return The previously set callback, or `NULL` if no callback was set or the 5383 * library had not been [initialized](@ref intro_init). 5384 * 5385 * @callback_signature 5386 * @code 5387 * void function_name(GLFWwindow* window, int entered) 5388 * @endcode 5389 * For more information about the callback parameters, see the 5390 * [function pointer type](@ref GLFWcursorenterfun). 5391 * 5392 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 5393 * 5394 * @thread_safety This function must only be called from the main thread. 5395 * 5396 * @sa @ref cursor_enter 5397 * 5398 * @since Added in version 3.0. 5399 * 5400 * @ingroup input 5401 */ 5402GLFWAPI GLFWcursorenterfun glfwSetCursorEnterCallback(GLFWwindow* window, GLFWcursorenterfun callback); 5403 5404/*! @brief Sets the scroll callback. 5405 * 5406 * This function sets the scroll callback of the specified window, which is 5407 * called when a scrolling device is used, such as a mouse wheel or scrolling 5408 * area of a touchpad. 5409 * 5410 * The scroll callback receives all scrolling input, like that from a mouse 5411 * wheel or a touchpad scrolling area. 5412 * 5413 * @param[in] window The window whose callback to set. 5414 * @param[in] callback The new scroll callback, or `NULL` to remove the 5415 * currently set callback. 5416 * @return The previously set callback, or `NULL` if no callback was set or the 5417 * library had not been [initialized](@ref intro_init). 5418 * 5419 * @callback_signature 5420 * @code 5421 * void function_name(GLFWwindow* window, double xoffset, double yoffset) 5422 * @endcode 5423 * For more information about the callback parameters, see the 5424 * [function pointer type](@ref GLFWscrollfun). 5425 * 5426 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 5427 * 5428 * @thread_safety This function must only be called from the main thread. 5429 * 5430 * @sa @ref scrolling 5431 * 5432 * @since Added in version 3.0. Replaces `glfwSetMouseWheelCallback`. 5433 * 5434 * @ingroup input 5435 */ 5436GLFWAPI GLFWscrollfun glfwSetScrollCallback(GLFWwindow* window, GLFWscrollfun callback); 5437 5438/*! @brief Sets the path drop callback. 5439 * 5440 * This function sets the path drop callback of the specified window, which is 5441 * called when one or more dragged paths are dropped on the window. 5442 * 5443 * Because the path array and its strings may have been generated specifically 5444 * for that event, they are not guaranteed to be valid after the callback has 5445 * returned. If you wish to use them after the callback returns, you need to 5446 * make a deep copy. 5447 * 5448 * @param[in] window The window whose callback to set. 5449 * @param[in] callback The new file drop callback, or `NULL` to remove the 5450 * currently set callback. 5451 * @return The previously set callback, or `NULL` if no callback was set or the 5452 * library had not been [initialized](@ref intro_init). 5453 * 5454 * @callback_signature 5455 * @code 5456 * void function_name(GLFWwindow* window, int path_count, const char* paths[]) 5457 * @endcode 5458 * For more information about the callback parameters, see the 5459 * [function pointer type](@ref GLFWdropfun). 5460 * 5461 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 5462 * 5463 * @thread_safety This function must only be called from the main thread. 5464 * 5465 * @sa @ref path_drop 5466 * 5467 * @since Added in version 3.1. 5468 * 5469 * @ingroup input 5470 */ 5471GLFWAPI GLFWdropfun glfwSetDropCallback(GLFWwindow* window, GLFWdropfun callback); 5472 5473/*! @brief Returns whether the specified joystick is present. 5474 * 5475 * This function returns whether the specified joystick is present. 5476 * 5477 * There is no need to call this function before other functions that accept 5478 * a joystick ID, as they all check for presence before performing any other 5479 * work. 5480 * 5481 * @param[in] jid The [joystick](@ref joysticks) to query. 5482 * @return `GLFW_TRUE` if the joystick is present, or `GLFW_FALSE` otherwise. 5483 * 5484 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref 5485 * GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR. 5486 * 5487 * @thread_safety This function must only be called from the main thread. 5488 * 5489 * @sa @ref joystick 5490 * 5491 * @since Added in version 3.0. Replaces `glfwGetJoystickParam`. 5492 * 5493 * @ingroup input 5494 */ 5495GLFWAPI int glfwJoystickPresent(int jid); 5496 5497/*! @brief Returns the values of all axes of the specified joystick. 5498 * 5499 * This function returns the values of all axes of the specified joystick. 5500 * Each element in the array is a value between -1.0 and 1.0. 5501 * 5502 * If the specified joystick is not present this function will return `NULL` 5503 * but will not generate an error. This can be used instead of first calling 5504 * @ref glfwJoystickPresent. 5505 * 5506 * @param[in] jid The [joystick](@ref joysticks) to query. 5507 * @param[out] count Where to store the number of axis values in the returned 5508 * array. This is set to zero if the joystick is not present or an error 5509 * occurred. 5510 * @return An array of axis values, or `NULL` if the joystick is not present or 5511 * an [error](@ref error_handling) occurred. 5512 * 5513 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref 5514 * GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR. 5515 * 5516 * @pointer_lifetime The returned array is allocated and freed by GLFW. You 5517 * should not free it yourself. It is valid until the specified joystick is 5518 * disconnected or the library is terminated. 5519 * 5520 * @thread_safety This function must only be called from the main thread. 5521 * 5522 * @sa @ref joystick_axis 5523 * 5524 * @since Added in version 3.0. Replaces `glfwGetJoystickPos`. 5525 * 5526 * @ingroup input 5527 */ 5528GLFWAPI const float* glfwGetJoystickAxes(int jid, int* count); 5529 5530/*! @brief Returns the state of all buttons of the specified joystick. 5531 * 5532 * This function returns the state of all buttons of the specified joystick. 5533 * Each element in the array is either `GLFW_PRESS` or `GLFW_RELEASE`. 5534 * 5535 * For backward compatibility with earlier versions that did not have @ref 5536 * glfwGetJoystickHats, the button array also includes all hats, each 5537 * represented as four buttons. The hats are in the same order as returned by 5538 * __glfwGetJoystickHats__ and are in the order _up_, _right_, _down_ and 5539 * _left_. To disable these extra buttons, set the @ref 5540 * GLFW_JOYSTICK_HAT_BUTTONS init hint before initialization. 5541 * 5542 * If the specified joystick is not present this function will return `NULL` 5543 * but will not generate an error. This can be used instead of first calling 5544 * @ref glfwJoystickPresent. 5545 * 5546 * @param[in] jid The [joystick](@ref joysticks) to query. 5547 * @param[out] count Where to store the number of button states in the returned 5548 * array. This is set to zero if the joystick is not present or an error 5549 * occurred. 5550 * @return An array of button states, or `NULL` if the joystick is not present 5551 * or an [error](@ref error_handling) occurred. 5552 * 5553 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref 5554 * GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR. 5555 * 5556 * @pointer_lifetime The returned array is allocated and freed by GLFW. You 5557 * should not free it yourself. It is valid until the specified joystick is 5558 * disconnected or the library is terminated. 5559 * 5560 * @thread_safety This function must only be called from the main thread. 5561 * 5562 * @sa @ref joystick_button 5563 * 5564 * @since Added in version 2.2. 5565 * __GLFW 3:__ Changed to return a dynamic array. 5566 * 5567 * @ingroup input 5568 */ 5569GLFWAPI const unsigned char* glfwGetJoystickButtons(int jid, int* count); 5570 5571/*! @brief Returns the state of all hats of the specified joystick. 5572 * 5573 * This function returns the state of all hats of the specified joystick. 5574 * Each element in the array is one of the following values: 5575 * 5576 * Name | Value 5577 * ---- | ----- 5578 * `GLFW_HAT_CENTERED` | 0 5579 * `GLFW_HAT_UP` | 1 5580 * `GLFW_HAT_RIGHT` | 2 5581 * `GLFW_HAT_DOWN` | 4 5582 * `GLFW_HAT_LEFT` | 8 5583 * `GLFW_HAT_RIGHT_UP` | `GLFW_HAT_RIGHT` \| `GLFW_HAT_UP` 5584 * `GLFW_HAT_RIGHT_DOWN` | `GLFW_HAT_RIGHT` \| `GLFW_HAT_DOWN` 5585 * `GLFW_HAT_LEFT_UP` | `GLFW_HAT_LEFT` \| `GLFW_HAT_UP` 5586 * `GLFW_HAT_LEFT_DOWN` | `GLFW_HAT_LEFT` \| `GLFW_HAT_DOWN` 5587 * 5588 * The diagonal directions are bitwise combinations of the primary (up, right, 5589 * down and left) directions and you can test for these individually by ANDing 5590 * it with the corresponding direction. 5591 * 5592 * @code 5593 * if (hats[2] & GLFW_HAT_RIGHT) 5594 * { 5595 * // State of hat 2 could be right-up, right or right-down 5596 * } 5597 * @endcode 5598 * 5599 * If the specified joystick is not present this function will return `NULL` 5600 * but will not generate an error. This can be used instead of first calling 5601 * @ref glfwJoystickPresent. 5602 * 5603 * @param[in] jid The [joystick](@ref joysticks) to query. 5604 * @param[out] count Where to store the number of hat states in the returned 5605 * array. This is set to zero if the joystick is not present or an error 5606 * occurred. 5607 * @return An array of hat states, or `NULL` if the joystick is not present 5608 * or an [error](@ref error_handling) occurred. 5609 * 5610 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref 5611 * GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR. 5612 * 5613 * @pointer_lifetime The returned array is allocated and freed by GLFW. You 5614 * should not free it yourself. It is valid until the specified joystick is 5615 * disconnected, this function is called again for that joystick or the library 5616 * is terminated. 5617 * 5618 * @thread_safety This function must only be called from the main thread. 5619 * 5620 * @sa @ref joystick_hat 5621 * 5622 * @since Added in version 3.3. 5623 * 5624 * @ingroup input 5625 */ 5626GLFWAPI const unsigned char* glfwGetJoystickHats(int jid, int* count); 5627 5628/*! @brief Returns the name of the specified joystick. 5629 * 5630 * This function returns the name, encoded as UTF-8, of the specified joystick. 5631 * The returned string is allocated and freed by GLFW. You should not free it 5632 * yourself. 5633 * 5634 * If the specified joystick is not present this function will return `NULL` 5635 * but will not generate an error. This can be used instead of first calling 5636 * @ref glfwJoystickPresent. 5637 * 5638 * @param[in] jid The [joystick](@ref joysticks) to query. 5639 * @return The UTF-8 encoded name of the joystick, or `NULL` if the joystick 5640 * is not present or an [error](@ref error_handling) occurred. 5641 * 5642 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref 5643 * GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR. 5644 * 5645 * @pointer_lifetime The returned string is allocated and freed by GLFW. You 5646 * should not free it yourself. It is valid until the specified joystick is 5647 * disconnected or the library is terminated. 5648 * 5649 * @thread_safety This function must only be called from the main thread. 5650 * 5651 * @sa @ref joystick_name 5652 * 5653 * @since Added in version 3.0. 5654 * 5655 * @ingroup input 5656 */ 5657GLFWAPI const char* glfwGetJoystickName(int jid); 5658 5659/*! @brief Returns the SDL compatible GUID of the specified joystick. 5660 * 5661 * This function returns the SDL compatible GUID, as a UTF-8 encoded 5662 * hexadecimal string, of the specified joystick. The returned string is 5663 * allocated and freed by GLFW. You should not free it yourself. 5664 * 5665 * The GUID is what connects a joystick to a gamepad mapping. A connected 5666 * joystick will always have a GUID even if there is no gamepad mapping 5667 * assigned to it. 5668 * 5669 * If the specified joystick is not present this function will return `NULL` 5670 * but will not generate an error. This can be used instead of first calling 5671 * @ref glfwJoystickPresent. 5672 * 5673 * The GUID uses the format introduced in SDL 2.0.5. This GUID tries to 5674 * uniquely identify the make and model of a joystick but does not identify 5675 * a specific unit, e.g. all wired Xbox 360 controllers will have the same 5676 * GUID on that platform. The GUID for a unit may vary between platforms 5677 * depending on what hardware information the platform specific APIs provide. 5678 * 5679 * @param[in] jid The [joystick](@ref joysticks) to query. 5680 * @return The UTF-8 encoded GUID of the joystick, or `NULL` if the joystick 5681 * is not present or an [error](@ref error_handling) occurred. 5682 * 5683 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref 5684 * GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR. 5685 * 5686 * @pointer_lifetime The returned string is allocated and freed by GLFW. You 5687 * should not free it yourself. It is valid until the specified joystick is 5688 * disconnected or the library is terminated. 5689 * 5690 * @thread_safety This function must only be called from the main thread. 5691 * 5692 * @sa @ref gamepad 5693 * 5694 * @since Added in version 3.3. 5695 * 5696 * @ingroup input 5697 */ 5698GLFWAPI const char* glfwGetJoystickGUID(int jid); 5699 5700/*! @brief Sets the user pointer of the specified joystick. 5701 * 5702 * This function sets the user-defined pointer of the specified joystick. The 5703 * current value is retained until the joystick is disconnected. The initial 5704 * value is `NULL`. 5705 * 5706 * This function may be called from the joystick callback, even for a joystick 5707 * that is being disconnected. 5708 * 5709 * @param[in] jid The joystick whose pointer to set. 5710 * @param[in] pointer The new value. 5711 * 5712 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 5713 * 5714 * @thread_safety This function may be called from any thread. Access is not 5715 * synchronized. 5716 * 5717 * @sa @ref joystick_userptr 5718 * @sa @ref glfwGetJoystickUserPointer 5719 * 5720 * @since Added in version 3.3. 5721 * 5722 * @ingroup input 5723 */ 5724GLFWAPI void glfwSetJoystickUserPointer(int jid, void* pointer); 5725 5726/*! @brief Returns the user pointer of the specified joystick. 5727 * 5728 * This function returns the current value of the user-defined pointer of the 5729 * specified joystick. The initial value is `NULL`. 5730 * 5731 * This function may be called from the joystick callback, even for a joystick 5732 * that is being disconnected. 5733 * 5734 * @param[in] jid The joystick whose pointer to return. 5735 * 5736 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 5737 * 5738 * @thread_safety This function may be called from any thread. Access is not 5739 * synchronized. 5740 * 5741 * @sa @ref joystick_userptr 5742 * @sa @ref glfwSetJoystickUserPointer 5743 * 5744 * @since Added in version 3.3. 5745 * 5746 * @ingroup input 5747 */ 5748GLFWAPI void* glfwGetJoystickUserPointer(int jid); 5749 5750/*! @brief Returns whether the specified joystick has a gamepad mapping. 5751 * 5752 * This function returns whether the specified joystick is both present and has 5753 * a gamepad mapping. 5754 * 5755 * If the specified joystick is present but does not have a gamepad mapping 5756 * this function will return `GLFW_FALSE` but will not generate an error. Call 5757 * @ref glfwJoystickPresent to check if a joystick is present regardless of 5758 * whether it has a mapping. 5759 * 5760 * @param[in] jid The [joystick](@ref joysticks) to query. 5761 * @return `GLFW_TRUE` if a joystick is both present and has a gamepad mapping, 5762 * or `GLFW_FALSE` otherwise. 5763 * 5764 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 5765 * GLFW_INVALID_ENUM. 5766 * 5767 * @thread_safety This function must only be called from the main thread. 5768 * 5769 * @sa @ref gamepad 5770 * @sa @ref glfwGetGamepadState 5771 * 5772 * @since Added in version 3.3. 5773 * 5774 * @ingroup input 5775 */ 5776GLFWAPI int glfwJoystickIsGamepad(int jid); 5777 5778/*! @brief Sets the joystick configuration callback. 5779 * 5780 * This function sets the joystick configuration callback, or removes the 5781 * currently set callback. This is called when a joystick is connected to or 5782 * disconnected from the system. 5783 * 5784 * For joystick connection and disconnection events to be delivered on all 5785 * platforms, you need to call one of the [event processing](@ref events) 5786 * functions. Joystick disconnection may also be detected and the callback 5787 * called by joystick functions. The function will then return whatever it 5788 * returns if the joystick is not present. 5789 * 5790 * @param[in] callback The new callback, or `NULL` to remove the currently set 5791 * callback. 5792 * @return The previously set callback, or `NULL` if no callback was set or the 5793 * library had not been [initialized](@ref intro_init). 5794 * 5795 * @callback_signature 5796 * @code 5797 * void function_name(int jid, int event) 5798 * @endcode 5799 * For more information about the callback parameters, see the 5800 * [function pointer type](@ref GLFWjoystickfun). 5801 * 5802 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 5803 * 5804 * @thread_safety This function must only be called from the main thread. 5805 * 5806 * @sa @ref joystick_event 5807 * 5808 * @since Added in version 3.2. 5809 * 5810 * @ingroup input 5811 */ 5812GLFWAPI GLFWjoystickfun glfwSetJoystickCallback(GLFWjoystickfun callback); 5813 5814/*! @brief Adds the specified SDL_GameControllerDB gamepad mappings. 5815 * 5816 * This function parses the specified ASCII encoded string and updates the 5817 * internal list with any gamepad mappings it finds. This string may 5818 * contain either a single gamepad mapping or many mappings separated by 5819 * newlines. The parser supports the full format of the `gamecontrollerdb.txt` 5820 * source file including empty lines and comments. 5821 * 5822 * See @ref gamepad_mapping for a description of the format. 5823 * 5824 * If there is already a gamepad mapping for a given GUID in the internal list, 5825 * it will be replaced by the one passed to this function. If the library is 5826 * terminated and re-initialized the internal list will revert to the built-in 5827 * default. 5828 * 5829 * @param[in] string The string containing the gamepad mappings. 5830 * @return `GLFW_TRUE` if successful, or `GLFW_FALSE` if an 5831 * [error](@ref error_handling) occurred. 5832 * 5833 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 5834 * GLFW_INVALID_VALUE. 5835 * 5836 * @thread_safety This function must only be called from the main thread. 5837 * 5838 * @sa @ref gamepad 5839 * @sa @ref glfwJoystickIsGamepad 5840 * @sa @ref glfwGetGamepadName 5841 * 5842 * @since Added in version 3.3. 5843 * 5844 * @ingroup input 5845 */ 5846GLFWAPI int glfwUpdateGamepadMappings(const char* string); 5847 5848/*! @brief Returns the human-readable gamepad name for the specified joystick. 5849 * 5850 * This function returns the human-readable name of the gamepad from the 5851 * gamepad mapping assigned to the specified joystick. 5852 * 5853 * If the specified joystick is not present or does not have a gamepad mapping 5854 * this function will return `NULL` but will not generate an error. Call 5855 * @ref glfwJoystickPresent to check whether it is present regardless of 5856 * whether it has a mapping. 5857 * 5858 * @param[in] jid The [joystick](@ref joysticks) to query. 5859 * @return The UTF-8 encoded name of the gamepad, or `NULL` if the 5860 * joystick is not present, does not have a mapping or an 5861 * [error](@ref error_handling) occurred. 5862 * 5863 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref GLFW_INVALID_ENUM. 5864 * 5865 * @pointer_lifetime The returned string is allocated and freed by GLFW. You 5866 * should not free it yourself. It is valid until the specified joystick is 5867 * disconnected, the gamepad mappings are updated or the library is terminated. 5868 * 5869 * @thread_safety This function must only be called from the main thread. 5870 * 5871 * @sa @ref gamepad 5872 * @sa @ref glfwJoystickIsGamepad 5873 * 5874 * @since Added in version 3.3. 5875 * 5876 * @ingroup input 5877 */ 5878GLFWAPI const char* glfwGetGamepadName(int jid); 5879 5880/*! @brief Retrieves the state of the specified joystick remapped as a gamepad. 5881 * 5882 * This function retrieves the state of the specified joystick remapped to 5883 * an Xbox-like gamepad. 5884 * 5885 * If the specified joystick is not present or does not have a gamepad mapping 5886 * this function will return `GLFW_FALSE` but will not generate an error. Call 5887 * @ref glfwJoystickPresent to check whether it is present regardless of 5888 * whether it has a mapping. 5889 * 5890 * The Guide button may not be available for input as it is often hooked by the 5891 * system or the Steam client. 5892 * 5893 * Not all devices have all the buttons or axes provided by @ref 5894 * GLFWgamepadstate. Unavailable buttons and axes will always report 5895 * `GLFW_RELEASE` and 0.0 respectively. 5896 * 5897 * @param[in] jid The [joystick](@ref joysticks) to query. 5898 * @param[out] state The gamepad input state of the joystick. 5899 * @return `GLFW_TRUE` if successful, or `GLFW_FALSE` if no joystick is 5900 * connected, it has no gamepad mapping or an [error](@ref error_handling) 5901 * occurred. 5902 * 5903 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 5904 * GLFW_INVALID_ENUM. 5905 * 5906 * @thread_safety This function must only be called from the main thread. 5907 * 5908 * @sa @ref gamepad 5909 * @sa @ref glfwUpdateGamepadMappings 5910 * @sa @ref glfwJoystickIsGamepad 5911 * 5912 * @since Added in version 3.3. 5913 * 5914 * @ingroup input 5915 */ 5916GLFWAPI int glfwGetGamepadState(int jid, GLFWgamepadstate* state); 5917 5918/*! @brief Sets the clipboard to the specified string. 5919 * 5920 * This function sets the system clipboard to the specified, UTF-8 encoded 5921 * string. 5922 * 5923 * @param[in] window Deprecated. Any valid window or `NULL`. 5924 * @param[in] string A UTF-8 encoded string. 5925 * 5926 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 5927 * GLFW_PLATFORM_ERROR. 5928 * 5929 * @remark __Win32:__ The clipboard on Windows has a single global lock for reading and 5930 * writing. GLFW tries to acquire it a few times, which is almost always enough. If it 5931 * cannot acquire the lock then this function emits @ref GLFW_PLATFORM_ERROR and returns. 5932 * It is safe to try this multiple times. 5933 * 5934 * @pointer_lifetime The specified string is copied before this function 5935 * returns. 5936 * 5937 * @thread_safety This function must only be called from the main thread. 5938 * 5939 * @sa @ref clipboard 5940 * @sa @ref glfwGetClipboardString 5941 * 5942 * @since Added in version 3.0. 5943 * 5944 * @ingroup input 5945 */ 5946GLFWAPI void glfwSetClipboardString(GLFWwindow* window, const char* string); 5947 5948/*! @brief Returns the contents of the clipboard as a string. 5949 * 5950 * This function returns the contents of the system clipboard, if it contains 5951 * or is convertible to a UTF-8 encoded string. If the clipboard is empty or 5952 * if its contents cannot be converted, `NULL` is returned and a @ref 5953 * GLFW_FORMAT_UNAVAILABLE error is generated. 5954 * 5955 * @param[in] window Deprecated. Any valid window or `NULL`. 5956 * @return The contents of the clipboard as a UTF-8 encoded string, or `NULL` 5957 * if an [error](@ref error_handling) occurred. 5958 * 5959 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref 5960 * GLFW_FORMAT_UNAVAILABLE and @ref GLFW_PLATFORM_ERROR. 5961 * 5962 * @remark __Win32:__ The clipboard on Windows has a single global lock for reading and 5963 * writing. GLFW tries to acquire it a few times, which is almost always enough. If it 5964 * cannot acquire the lock then this function emits @ref GLFW_PLATFORM_ERROR and returns. 5965 * It is safe to try this multiple times. 5966 * 5967 * @pointer_lifetime The returned string is allocated and freed by GLFW. You 5968 * should not free it yourself. It is valid until the next call to @ref 5969 * glfwGetClipboardString or @ref glfwSetClipboardString, or until the library 5970 * is terminated. 5971 * 5972 * @thread_safety This function must only be called from the main thread. 5973 * 5974 * @sa @ref clipboard 5975 * @sa @ref glfwSetClipboardString 5976 * 5977 * @since Added in version 3.0. 5978 * 5979 * @ingroup input 5980 */ 5981GLFWAPI const char* glfwGetClipboardString(GLFWwindow* window); 5982 5983/*! @brief Returns the GLFW time. 5984 * 5985 * This function returns the current GLFW time, in seconds. Unless the time 5986 * has been set using @ref glfwSetTime it measures time elapsed since GLFW was 5987 * initialized. 5988 * 5989 * This function and @ref glfwSetTime are helper functions on top of @ref 5990 * glfwGetTimerFrequency and @ref glfwGetTimerValue. 5991 * 5992 * The resolution of the timer is system dependent, but is usually on the order 5993 * of a few micro- or nanoseconds. It uses the highest-resolution monotonic 5994 * time source on each operating system. 5995 * 5996 * @return The current time, in seconds, or zero if an 5997 * [error](@ref error_handling) occurred. 5998 * 5999 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 6000 * 6001 * @thread_safety This function may be called from any thread. Reading and 6002 * writing of the internal base time is not atomic, so it needs to be 6003 * externally synchronized with calls to @ref glfwSetTime. 6004 * 6005 * @sa @ref time 6006 * 6007 * @since Added in version 1.0. 6008 * 6009 * @ingroup input 6010 */ 6011GLFWAPI double glfwGetTime(void); 6012 6013/*! @brief Sets the GLFW time. 6014 * 6015 * This function sets the current GLFW time, in seconds. The value must be 6016 * a positive finite number less than or equal to 18446744073.0, which is 6017 * approximately 584.5 years. 6018 * 6019 * This function and @ref glfwGetTime are helper functions on top of @ref 6020 * glfwGetTimerFrequency and @ref glfwGetTimerValue. 6021 * 6022 * @param[in] time The new value, in seconds. 6023 * 6024 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 6025 * GLFW_INVALID_VALUE. 6026 * 6027 * @remark The upper limit of GLFW time is calculated as 6028 * floor((2<sup>64</sup> - 1) / 10<sup>9</sup>) and is due to implementations 6029 * storing nanoseconds in 64 bits. The limit may be increased in the future. 6030 * 6031 * @thread_safety This function may be called from any thread. Reading and 6032 * writing of the internal base time is not atomic, so it needs to be 6033 * externally synchronized with calls to @ref glfwGetTime. 6034 * 6035 * @sa @ref time 6036 * 6037 * @since Added in version 2.2. 6038 * 6039 * @ingroup input 6040 */ 6041GLFWAPI void glfwSetTime(double time); 6042 6043/*! @brief Returns the current value of the raw timer. 6044 * 6045 * This function returns the current value of the raw timer, measured in 6046 * 1 / frequency seconds. To get the frequency, call @ref 6047 * glfwGetTimerFrequency. 6048 * 6049 * @return The value of the timer, or zero if an 6050 * [error](@ref error_handling) occurred. 6051 * 6052 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 6053 * 6054 * @thread_safety This function may be called from any thread. 6055 * 6056 * @sa @ref time 6057 * @sa @ref glfwGetTimerFrequency 6058 * 6059 * @since Added in version 3.2. 6060 * 6061 * @ingroup input 6062 */ 6063GLFWAPI uint64_t glfwGetTimerValue(void); 6064 6065/*! @brief Returns the frequency, in Hz, of the raw timer. 6066 * 6067 * This function returns the frequency, in Hz, of the raw timer. 6068 * 6069 * @return The frequency of the timer, in Hz, or zero if an 6070 * [error](@ref error_handling) occurred. 6071 * 6072 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 6073 * 6074 * @thread_safety This function may be called from any thread. 6075 * 6076 * @sa @ref time 6077 * @sa @ref glfwGetTimerValue 6078 * 6079 * @since Added in version 3.2. 6080 * 6081 * @ingroup input 6082 */ 6083GLFWAPI uint64_t glfwGetTimerFrequency(void); 6084 6085/*! @brief Makes the context of the specified window current for the calling 6086 * thread. 6087 * 6088 * This function makes the OpenGL or OpenGL ES context of the specified window 6089 * current on the calling thread. It can also detach the current context from 6090 * the calling thread without making a new one current by passing in `NULL`. 6091 * 6092 * A context must only be made current on a single thread at a time and each 6093 * thread can have only a single current context at a time. Making a context 6094 * current detaches any previously current context on the calling thread. 6095 * 6096 * When moving a context between threads, you must detach it (make it 6097 * non-current) on the old thread before making it current on the new one. 6098 * 6099 * By default, making a context non-current implicitly forces a pipeline flush. 6100 * On machines that support `GL_KHR_context_flush_control`, you can control 6101 * whether a context performs this flush by setting the 6102 * [GLFW_CONTEXT_RELEASE_BEHAVIOR](@ref GLFW_CONTEXT_RELEASE_BEHAVIOR_hint) 6103 * hint. 6104 * 6105 * The specified window must have an OpenGL or OpenGL ES context. Specifying 6106 * a window without a context will generate a @ref GLFW_NO_WINDOW_CONTEXT 6107 * error. 6108 * 6109 * @param[in] window The window whose context to make current, or `NULL` to 6110 * detach the current context. 6111 * 6112 * @remarks If the previously current context was created via a different 6113 * context creation API than the one passed to this function, GLFW will still 6114 * detach the previous one from its API before making the new one current. 6115 * 6116 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref 6117 * GLFW_NO_WINDOW_CONTEXT and @ref GLFW_PLATFORM_ERROR. 6118 * 6119 * @thread_safety This function may be called from any thread. 6120 * 6121 * @sa @ref context_current 6122 * @sa @ref glfwGetCurrentContext 6123 * 6124 * @since Added in version 3.0. 6125 * 6126 * @ingroup context 6127 */ 6128GLFWAPI void glfwMakeContextCurrent(GLFWwindow* window); 6129 6130/*! @brief Returns the window whose context is current on the calling thread. 6131 * 6132 * This function returns the window whose OpenGL or OpenGL ES context is 6133 * current on the calling thread. 6134 * 6135 * @return The window whose context is current, or `NULL` if no window's 6136 * context is current. 6137 * 6138 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 6139 * 6140 * @thread_safety This function may be called from any thread. 6141 * 6142 * @sa @ref context_current 6143 * @sa @ref glfwMakeContextCurrent 6144 * 6145 * @since Added in version 3.0. 6146 * 6147 * @ingroup context 6148 */ 6149GLFWAPI GLFWwindow* glfwGetCurrentContext(void); 6150 6151/*! @brief Swaps the front and back buffers of the specified window. 6152 * 6153 * This function swaps the front and back buffers of the specified window when 6154 * rendering with OpenGL or OpenGL ES. If the swap interval is greater than 6155 * zero, the GPU driver waits the specified number of screen updates before 6156 * swapping the buffers. 6157 * 6158 * The specified window must have an OpenGL or OpenGL ES context. Specifying 6159 * a window without a context will generate a @ref GLFW_NO_WINDOW_CONTEXT 6160 * error. 6161 * 6162 * This function does not apply to Vulkan. If you are rendering with Vulkan, 6163 * see `vkQueuePresentKHR` instead. 6164 * 6165 * @param[in] window The window whose buffers to swap. 6166 * 6167 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref 6168 * GLFW_NO_WINDOW_CONTEXT and @ref GLFW_PLATFORM_ERROR. 6169 * 6170 * @remark __EGL:__ The context of the specified window must be current on the 6171 * calling thread. 6172 * 6173 * @thread_safety This function may be called from any thread. 6174 * 6175 * @sa @ref buffer_swap 6176 * @sa @ref glfwSwapInterval 6177 * 6178 * @since Added in version 1.0. 6179 * __GLFW 3:__ Added window handle parameter. 6180 * 6181 * @ingroup window 6182 */ 6183GLFWAPI void glfwSwapBuffers(GLFWwindow* window); 6184 6185/*! @brief Sets the swap interval for the current context. 6186 * 6187 * This function sets the swap interval for the current OpenGL or OpenGL ES 6188 * context, i.e. the number of screen updates to wait from the time @ref 6189 * glfwSwapBuffers was called before swapping the buffers and returning. This 6190 * is sometimes called _vertical synchronization_, _vertical retrace 6191 * synchronization_ or just _vsync_. 6192 * 6193 * A context that supports either of the `WGL_EXT_swap_control_tear` and 6194 * `GLX_EXT_swap_control_tear` extensions also accepts _negative_ swap 6195 * intervals, which allows the driver to swap immediately even if a frame 6196 * arrives a little bit late. You can check for these extensions with @ref 6197 * glfwExtensionSupported. 6198 * 6199 * A context must be current on the calling thread. Calling this function 6200 * without a current context will cause a @ref GLFW_NO_CURRENT_CONTEXT error. 6201 * 6202 * This function does not apply to Vulkan. If you are rendering with Vulkan, 6203 * see the present mode of your swapchain instead. 6204 * 6205 * @param[in] interval The minimum number of screen updates to wait for 6206 * until the buffers are swapped by @ref glfwSwapBuffers. 6207 * 6208 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref 6209 * GLFW_NO_CURRENT_CONTEXT and @ref GLFW_PLATFORM_ERROR. 6210 * 6211 * @remark This function is not called during context creation, leaving the 6212 * swap interval set to whatever is the default for that API. This is done 6213 * because some swap interval extensions used by GLFW do not allow the swap 6214 * interval to be reset to zero once it has been set to a non-zero value. 6215 * 6216 * @remark Some GPU drivers do not honor the requested swap interval, either 6217 * because of a user setting that overrides the application's request or due to 6218 * bugs in the driver. 6219 * 6220 * @thread_safety This function may be called from any thread. 6221 * 6222 * @sa @ref buffer_swap 6223 * @sa @ref glfwSwapBuffers 6224 * 6225 * @since Added in version 1.0. 6226 * 6227 * @ingroup context 6228 */ 6229GLFWAPI void glfwSwapInterval(int interval); 6230 6231/*! @brief Returns whether the specified extension is available. 6232 * 6233 * This function returns whether the specified 6234 * [API extension](@ref context_glext) is supported by the current OpenGL or 6235 * OpenGL ES context. It searches both for client API extension and context 6236 * creation API extensions. 6237 * 6238 * A context must be current on the calling thread. Calling this function 6239 * without a current context will cause a @ref GLFW_NO_CURRENT_CONTEXT error. 6240 * 6241 * As this functions retrieves and searches one or more extension strings each 6242 * call, it is recommended that you cache its results if it is going to be used 6243 * frequently. The extension strings will not change during the lifetime of 6244 * a context, so there is no danger in doing this. 6245 * 6246 * This function does not apply to Vulkan. If you are using Vulkan, see @ref 6247 * glfwGetRequiredInstanceExtensions, `vkEnumerateInstanceExtensionProperties` 6248 * and `vkEnumerateDeviceExtensionProperties` instead. 6249 * 6250 * @param[in] extension The ASCII encoded name of the extension. 6251 * @return `GLFW_TRUE` if the extension is available, or `GLFW_FALSE` 6252 * otherwise. 6253 * 6254 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref 6255 * GLFW_NO_CURRENT_CONTEXT, @ref GLFW_INVALID_VALUE and @ref 6256 * GLFW_PLATFORM_ERROR. 6257 * 6258 * @thread_safety This function may be called from any thread. 6259 * 6260 * @sa @ref context_glext 6261 * @sa @ref glfwGetProcAddress 6262 * 6263 * @since Added in version 1.0. 6264 * 6265 * @ingroup context 6266 */ 6267GLFWAPI int glfwExtensionSupported(const char* extension); 6268 6269/*! @brief Returns the address of the specified function for the current 6270 * context. 6271 * 6272 * This function returns the address of the specified OpenGL or OpenGL ES 6273 * [core or extension function](@ref context_glext), if it is supported 6274 * by the current context. 6275 * 6276 * A context must be current on the calling thread. Calling this function 6277 * without a current context will cause a @ref GLFW_NO_CURRENT_CONTEXT error. 6278 * 6279 * This function does not apply to Vulkan. If you are rendering with Vulkan, 6280 * see @ref glfwGetInstanceProcAddress, `vkGetInstanceProcAddr` and 6281 * `vkGetDeviceProcAddr` instead. 6282 * 6283 * @param[in] procname The ASCII encoded name of the function. 6284 * @return The address of the function, or `NULL` if an 6285 * [error](@ref error_handling) occurred. 6286 * 6287 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref 6288 * GLFW_NO_CURRENT_CONTEXT and @ref GLFW_PLATFORM_ERROR. 6289 * 6290 * @remark The address of a given function is not guaranteed to be the same 6291 * between contexts. 6292 * 6293 * @remark This function may return a non-`NULL` address despite the 6294 * associated version or extension not being available. Always check the 6295 * context version or extension string first. 6296 * 6297 * @pointer_lifetime The returned function pointer is valid until the context 6298 * is destroyed or the library is terminated. 6299 * 6300 * @thread_safety This function may be called from any thread. 6301 * 6302 * @sa @ref context_glext 6303 * @sa @ref glfwExtensionSupported 6304 * 6305 * @since Added in version 1.0. 6306 * 6307 * @ingroup context 6308 */ 6309GLFWAPI GLFWglproc glfwGetProcAddress(const char* procname); 6310 6311/*! @brief Returns whether the Vulkan loader and an ICD have been found. 6312 * 6313 * This function returns whether the Vulkan loader and any minimally functional 6314 * ICD have been found. 6315 * 6316 * The availability of a Vulkan loader and even an ICD does not by itself guarantee that 6317 * surface creation or even instance creation is possible. Call @ref 6318 * glfwGetRequiredInstanceExtensions to check whether the extensions necessary for Vulkan 6319 * surface creation are available and @ref glfwGetPhysicalDevicePresentationSupport to 6320 * check whether a queue family of a physical device supports image presentation. 6321 * 6322 * @return `GLFW_TRUE` if Vulkan is minimally available, or `GLFW_FALSE` 6323 * otherwise. 6324 * 6325 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED. 6326 * 6327 * @thread_safety This function may be called from any thread. 6328 * 6329 * @sa @ref vulkan_support 6330 * 6331 * @since Added in version 3.2. 6332 * 6333 * @ingroup vulkan 6334 */ 6335GLFWAPI int glfwVulkanSupported(void); 6336 6337/*! @brief Returns the Vulkan instance extensions required by GLFW. 6338 * 6339 * This function returns an array of names of Vulkan instance extensions required 6340 * by GLFW for creating Vulkan surfaces for GLFW windows. If successful, the 6341 * list will always contain `VK_KHR_surface`, so if you don't require any 6342 * additional extensions you can pass this list directly to the 6343 * `VkInstanceCreateInfo` struct. 6344 * 6345 * If Vulkan is not available on the machine, this function returns `NULL` and 6346 * generates a @ref GLFW_API_UNAVAILABLE error. Call @ref glfwVulkanSupported 6347 * to check whether Vulkan is at least minimally available. 6348 * 6349 * If Vulkan is available but no set of extensions allowing window surface 6350 * creation was found, this function returns `NULL`. You may still use Vulkan 6351 * for off-screen rendering and compute work. 6352 * 6353 * @param[out] count Where to store the number of extensions in the returned 6354 * array. This is set to zero if an error occurred. 6355 * @return An array of ASCII encoded extension names, or `NULL` if an 6356 * [error](@ref error_handling) occurred. 6357 * 6358 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 6359 * GLFW_API_UNAVAILABLE. 6360 * 6361 * @remark Additional extensions may be required by future versions of GLFW. 6362 * You should check if any extensions you wish to enable are already in the 6363 * returned array, as it is an error to specify an extension more than once in 6364 * the `VkInstanceCreateInfo` struct. 6365 * 6366 * @pointer_lifetime The returned array is allocated and freed by GLFW. You 6367 * should not free it yourself. It is guaranteed to be valid only until the 6368 * library is terminated. 6369 * 6370 * @thread_safety This function may be called from any thread. 6371 * 6372 * @sa @ref vulkan_ext 6373 * @sa @ref glfwCreateWindowSurface 6374 * 6375 * @since Added in version 3.2. 6376 * 6377 * @ingroup vulkan 6378 */ 6379GLFWAPI const char** glfwGetRequiredInstanceExtensions(uint32_t* count); 6380 6381#if defined(VK_VERSION_1_0) 6382 6383/*! @brief Returns the address of the specified Vulkan instance function. 6384 * 6385 * This function returns the address of the specified Vulkan core or extension 6386 * function for the specified instance. If instance is set to `NULL` it can 6387 * return any function exported from the Vulkan loader, including at least the 6388 * following functions: 6389 * 6390 * - `vkEnumerateInstanceExtensionProperties` 6391 * - `vkEnumerateInstanceLayerProperties` 6392 * - `vkCreateInstance` 6393 * - `vkGetInstanceProcAddr` 6394 * 6395 * If Vulkan is not available on the machine, this function returns `NULL` and 6396 * generates a @ref GLFW_API_UNAVAILABLE error. Call @ref glfwVulkanSupported 6397 * to check whether Vulkan is at least minimally available. 6398 * 6399 * This function is equivalent to calling `vkGetInstanceProcAddr` with 6400 * a platform-specific query of the Vulkan loader as a fallback. 6401 * 6402 * @param[in] instance The Vulkan instance to query, or `NULL` to retrieve 6403 * functions related to instance creation. 6404 * @param[in] procname The ASCII encoded name of the function. 6405 * @return The address of the function, or `NULL` if an 6406 * [error](@ref error_handling) occurred. 6407 * 6408 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref 6409 * GLFW_API_UNAVAILABLE. 6410 * 6411 * @pointer_lifetime The returned function pointer is valid until the library 6412 * is terminated. 6413 * 6414 * @thread_safety This function may be called from any thread. 6415 * 6416 * @sa @ref vulkan_proc 6417 * 6418 * @since Added in version 3.2. 6419 * 6420 * @ingroup vulkan 6421 */ 6422GLFWAPI GLFWvkproc glfwGetInstanceProcAddress(VkInstance instance, const char* procname); 6423 6424/*! @brief Returns whether the specified queue family can present images. 6425 * 6426 * This function returns whether the specified queue family of the specified 6427 * physical device supports presentation to the platform GLFW was built for. 6428 * 6429 * If Vulkan or the required window surface creation instance extensions are 6430 * not available on the machine, or if the specified instance was not created 6431 * with the required extensions, this function returns `GLFW_FALSE` and 6432 * generates a @ref GLFW_API_UNAVAILABLE error. Call @ref glfwVulkanSupported 6433 * to check whether Vulkan is at least minimally available and @ref 6434 * glfwGetRequiredInstanceExtensions to check what instance extensions are 6435 * required. 6436 * 6437 * @param[in] instance The instance that the physical device belongs to. 6438 * @param[in] device The physical device that the queue family belongs to. 6439 * @param[in] queuefamily The index of the queue family to query. 6440 * @return `GLFW_TRUE` if the queue family supports presentation, or 6441 * `GLFW_FALSE` otherwise. 6442 * 6443 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref 6444 * GLFW_API_UNAVAILABLE and @ref GLFW_PLATFORM_ERROR. 6445 * 6446 * @remark __macOS:__ This function currently always returns `GLFW_TRUE`, as the 6447 * `VK_MVK_macos_surface` and `VK_EXT_metal_surface` extensions do not provide 6448 * a `vkGetPhysicalDevice*PresentationSupport` type function. 6449 * 6450 * @thread_safety This function may be called from any thread. For 6451 * synchronization details of Vulkan objects, see the Vulkan specification. 6452 * 6453 * @sa @ref vulkan_present 6454 * 6455 * @since Added in version 3.2. 6456 * 6457 * @ingroup vulkan 6458 */ 6459GLFWAPI int glfwGetPhysicalDevicePresentationSupport(VkInstance instance, VkPhysicalDevice device, uint32_t queuefamily); 6460 6461/*! @brief Creates a Vulkan surface for the specified window. 6462 * 6463 * This function creates a Vulkan surface for the specified window. 6464 * 6465 * If the Vulkan loader or at least one minimally functional ICD were not found, 6466 * this function returns `VK_ERROR_INITIALIZATION_FAILED` and generates a @ref 6467 * GLFW_API_UNAVAILABLE error. Call @ref glfwVulkanSupported to check whether 6468 * Vulkan is at least minimally available. 6469 * 6470 * If the required window surface creation instance extensions are not 6471 * available or if the specified instance was not created with these extensions 6472 * enabled, this function returns `VK_ERROR_EXTENSION_NOT_PRESENT` and 6473 * generates a @ref GLFW_API_UNAVAILABLE error. Call @ref 6474 * glfwGetRequiredInstanceExtensions to check what instance extensions are 6475 * required. 6476 * 6477 * The window surface cannot be shared with another API so the window must 6478 * have been created with the [client api hint](@ref GLFW_CLIENT_API_attrib) 6479 * set to `GLFW_NO_API` otherwise it generates a @ref GLFW_INVALID_VALUE error 6480 * and returns `VK_ERROR_NATIVE_WINDOW_IN_USE_KHR`. 6481 * 6482 * The window surface must be destroyed before the specified Vulkan instance. 6483 * It is the responsibility of the caller to destroy the window surface. GLFW 6484 * does not destroy it for you. Call `vkDestroySurfaceKHR` to destroy the 6485 * surface. 6486 * 6487 * @param[in] instance The Vulkan instance to create the surface in. 6488 * @param[in] window The window to create the surface for. 6489 * @param[in] allocator The allocator to use, or `NULL` to use the default 6490 * allocator. 6491 * @param[out] surface Where to store the handle of the surface. This is set 6492 * to `VK_NULL_HANDLE` if an error occurred. 6493 * @return `VK_SUCCESS` if successful, or a Vulkan error code if an 6494 * [error](@ref error_handling) occurred. 6495 * 6496 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref 6497 * GLFW_API_UNAVAILABLE, @ref GLFW_PLATFORM_ERROR and @ref GLFW_INVALID_VALUE 6498 * 6499 * @remark If an error occurs before the creation call is made, GLFW returns 6500 * the Vulkan error code most appropriate for the error. Appropriate use of 6501 * @ref glfwVulkanSupported and @ref glfwGetRequiredInstanceExtensions should 6502 * eliminate almost all occurrences of these errors. 6503 * 6504 * @remark __macOS:__ GLFW prefers the `VK_EXT_metal_surface` extension, with the 6505 * `VK_MVK_macos_surface` extension as a fallback. The name of the selected 6506 * extension, if any, is included in the array returned by @ref 6507 * glfwGetRequiredInstanceExtensions. 6508 * 6509 * @remark __macOS:__ This function creates and sets a `CAMetalLayer` instance for 6510 * the window content view, which is required for MoltenVK to function. 6511 * 6512 * @remark __X11:__ By default GLFW prefers the `VK_KHR_xcb_surface` extension, 6513 * with the `VK_KHR_xlib_surface` extension as a fallback. You can make 6514 * `VK_KHR_xlib_surface` the preferred extension by setting the 6515 * [GLFW_X11_XCB_VULKAN_SURFACE](@ref GLFW_X11_XCB_VULKAN_SURFACE_hint) init 6516 * hint. The name of the selected extension, if any, is included in the array 6517 * returned by @ref glfwGetRequiredInstanceExtensions. 6518 * 6519 * @thread_safety This function may be called from any thread. For 6520 * synchronization details of Vulkan objects, see the Vulkan specification. 6521 * 6522 * @sa @ref vulkan_surface 6523 * @sa @ref glfwGetRequiredInstanceExtensions 6524 * 6525 * @since Added in version 3.2. 6526 * 6527 * @ingroup vulkan 6528 */ 6529GLFWAPI VkResult glfwCreateWindowSurface(VkInstance instance, GLFWwindow* window, const VkAllocationCallbacks* allocator, VkSurfaceKHR* surface); 6530 6531#endif /*VK_VERSION_1_0*/ 6532 6533 6534/************************************************************************* 6535 * Global definition cleanup 6536 *************************************************************************/ 6537 6538/* ------------------- BEGIN SYSTEM/COMPILER SPECIFIC -------------------- */ 6539 6540#ifdef GLFW_WINGDIAPI_DEFINED 6541 #undef WINGDIAPI 6542 #undef GLFW_WINGDIAPI_DEFINED 6543#endif 6544 6545#ifdef GLFW_CALLBACK_DEFINED 6546 #undef CALLBACK 6547 #undef GLFW_CALLBACK_DEFINED 6548#endif 6549 6550/* Some OpenGL related headers need GLAPIENTRY, but it is unconditionally 6551 * defined by some gl.h variants (OpenBSD) so define it after if needed. 6552 */ 6553#ifndef GLAPIENTRY 6554 #define GLAPIENTRY APIENTRY 6555 #define GLFW_GLAPIENTRY_DEFINED 6556#endif 6557 6558/* -------------------- END SYSTEM/COMPILER SPECIFIC --------------------- */ 6559 6560 6561#ifdef __cplusplus 6562} 6563#endif 6564 6565#endif /* _glfw3_h_ */ 6566 6567[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.