1/*! 2 3@page input_guide Input guide 4 5@tableofcontents 6 7This guide introduces the input related functions of GLFW. For details on 8a specific function in this category, see the @ref input. There are also guides 9for the other areas of GLFW. 10 11 - @ref intro_guide 12 - @ref window_guide 13 - @ref context_guide 14 - @ref vulkan_guide 15 - @ref monitor_guide 16 17GLFW provides many kinds of input. While some can only be polled, like time, or 18only received via callbacks, like scrolling, many provide both callbacks and 19polling. Callbacks are more work to use than polling but is less CPU intensive 20and guarantees that you do not miss state changes. 21 22All input callbacks receive a window handle. By using the 23[window user pointer](@ref window_userptr), you can access non-global structures 24or objects from your callbacks. 25 26To get a better feel for how the various events callbacks behave, run the 27`events` test program. It register every callback supported by GLFW and prints 28out all arguments provided for every event, along with time and sequence 29information. 30 31 32@section events Event processing 33 34GLFW needs to poll the window system for events both to provide input to the 35application and to prove to the window system that the application hasn't locked 36up. Event processing is normally done each frame after 37[buffer swapping](@ref buffer_swap). Even when you have no windows, event 38polling needs to be done in order to receive monitor and joystick connection 39events. 40 41There are three functions for processing pending events. @ref glfwPollEvents, 42processes only those events that have already been received and then returns 43immediately. 44 45@code 46glfwPollEvents(); 47@endcode 48 49This is the best choice when rendering continuously, like most games do. 50 51If you only need to update the contents of the window when you receive new 52input, @ref glfwWaitEvents is a better choice. 53 54@code 55glfwWaitEvents(); 56@endcode 57 58It puts the thread to sleep until at least one event has been received and then 59processes all received events. This saves a great deal of CPU cycles and is 60useful for, for example, editing tools. 61 62If you want to wait for events but have UI elements or other tasks that need 63periodic updates, @ref glfwWaitEventsTimeout lets you specify a timeout. 64 65@code 66glfwWaitEventsTimeout(0.7); 67@endcode 68 69It puts the thread to sleep until at least one event has been received, or until 70the specified number of seconds have elapsed. It then processes any received 71events. 72 73If the main thread is sleeping in @ref glfwWaitEvents, you can wake it from 74another thread by posting an empty event to the event queue with @ref 75glfwPostEmptyEvent. 76 77@code 78glfwPostEmptyEvent(); 79@endcode 80 81Do not assume that callbacks will _only_ be called in response to the above 82functions. While it is necessary to process events in one or more of the ways 83above, window systems that require GLFW to register callbacks of its own can 84pass events to GLFW in response to many window system function calls. GLFW will 85pass those events on to the application callbacks before returning. 86 87For example, on Windows the system function that @ref glfwSetWindowSize is 88implemented with will send window size events directly to the event callback 89that every window has and that GLFW implements for its windows. If you have set 90a [window size callback](@ref window_size) GLFW will call it in turn with the 91new size before everything returns back out of the @ref glfwSetWindowSize call. 92 93 94@section input_keyboard Keyboard input 95 96GLFW divides keyboard input into two categories; key events and character 97events. Key events relate to actual physical keyboard keys, whereas character 98events relate to the Unicode code points generated by pressing some of them. 99 100Keys and characters do not map 1:1. A single key press may produce several 101characters, and a single character may require several keys to produce. This 102may not be the case on your machine, but your users are likely not all using the 103same keyboard layout, input method or even operating system as you. 104 105 106@subsection input_key Key input 107 108If you wish to be notified when a physical key is pressed or released or when it 109repeats, set a key callback. 110 111@code 112glfwSetKeyCallback(window, key_callback); 113@endcode 114 115The callback function receives the [keyboard key](@ref keys), platform-specific 116scancode, key action and [modifier bits](@ref mods). 117 118@code 119void key_callback(GLFWwindow* window, int key, int scancode, int action, int mods) 120{ 121 if (key == GLFW_KEY_E && action == GLFW_PRESS) 122 activate_airship(); 123} 124@endcode 125 126The action is one of `GLFW_PRESS`, `GLFW_REPEAT` or `GLFW_RELEASE`. The key 127will be `GLFW_KEY_UNKNOWN` if GLFW lacks a key token for it, for example 128_E-mail_ and _Play_ keys. 129 130The scancode is unique for every key, regardless of whether it has a key token. 131Scancodes are platform-specific but consistent over time, so keys will have 132different scancodes depending on the platform but they are safe to save to disk. 133You can query the scancode for any [named key](@ref keys) on the current 134platform with @ref glfwGetKeyScancode. 135 136@code 137const int scancode = glfwGetKeyScancode(GLFW_KEY_X); 138set_key_mapping(scancode, swap_weapons); 139@endcode 140 141The last reported state for every [named key](@ref keys) is also saved in 142per-window state arrays that can be polled with @ref glfwGetKey. 143 144@code 145int state = glfwGetKey(window, GLFW_KEY_E); 146if (state == GLFW_PRESS) 147{ 148 activate_airship(); 149} 150@endcode 151 152The returned state is one of `GLFW_PRESS` or `GLFW_RELEASE`. 153 154This function only returns cached key event state. It does not poll the 155system for the current physical state of the key. 156 157@anchor GLFW_STICKY_KEYS 158Whenever you poll state, you risk missing the state change you are looking for. 159If a pressed key is released again before you poll its state, you will have 160missed the key press. The recommended solution for this is to use a 161key callback, but there is also the `GLFW_STICKY_KEYS` input mode. 162 163@code 164glfwSetInputMode(window, GLFW_STICKY_KEYS, GLFW_TRUE); 165@endcode 166 167When sticky keys mode is enabled, the pollable state of a key will remain 168`GLFW_PRESS` until the state of that key is polled with @ref glfwGetKey. Once 169it has been polled, if a key release event had been processed in the meantime, 170the state will reset to `GLFW_RELEASE`, otherwise it will remain `GLFW_PRESS`. 171 172@anchor GLFW_LOCK_KEY_MODS 173If you wish to know what the state of the Caps Lock and Num Lock keys was when 174input events were generated, set the `GLFW_LOCK_KEY_MODS` input mode. 175 176@code 177glfwSetInputMode(window, GLFW_LOCK_KEY_MODS, GLFW_TRUE); 178@endcode 179 180When this input mode is enabled, any callback that receives 181[modifier bits](@ref mods) will have the @ref GLFW_MOD_CAPS_LOCK bit set if Caps 182Lock was on when the event occurred and the @ref GLFW_MOD_NUM_LOCK bit set if 183Num Lock was on. 184 185The `GLFW_KEY_LAST` constant holds the highest value of any 186[named key](@ref keys). 187 188 189@subsection input_char Text input 190 191GLFW supports text input in the form of a stream of 192[Unicode code points](https://en.wikipedia.org/wiki/Unicode), as produced by the 193operating system text input system. Unlike key input, text input obeys keyboard 194layouts and modifier keys and supports composing characters using 195[dead keys](https://en.wikipedia.org/wiki/Dead_key). Once received, you can 196encode the code points into UTF-8 or any other encoding you prefer. 197 198Because an `unsigned int` is 32 bits long on all platforms supported by GLFW, 199you can treat the code point argument as native endian UTF-32. 200 201If you wish to offer regular text input, set a character callback. 202 203@code 204glfwSetCharCallback(window, character_callback); 205@endcode 206 207The callback function receives Unicode code points for key events that would 208have led to regular text input and generally behaves as a standard text field on 209that platform. 210 211@code 212void character_callback(GLFWwindow* window, unsigned int codepoint) 213{ 214} 215@endcode 216 217 218@subsection input_key_name Key names 219 220If you wish to refer to keys by name, you can query the keyboard layout 221dependent name of printable keys with @ref glfwGetKeyName. 222 223@code 224const char* key_name = glfwGetKeyName(GLFW_KEY_W, 0); 225show_tutorial_hint("Press %s to move forward", key_name); 226@endcode 227 228This function can handle both [keys and scancodes](@ref input_key). If the 229specified key is `GLFW_KEY_UNKNOWN` then the scancode is used, otherwise it is 230ignored. This matches the behavior of the key callback, meaning the callback 231arguments can always be passed unmodified to this function. 232 233 234@section input_mouse Mouse input 235 236Mouse input comes in many forms, including mouse motion, button presses and 237scrolling offsets. The cursor appearance can also be changed, either to 238a custom image or a standard cursor shape from the system theme. 239 240 241@subsection cursor_pos Cursor position 242 243If you wish to be notified when the cursor moves over the window, set a cursor 244position callback. 245 246@code 247glfwSetCursorPosCallback(window, cursor_position_callback); 248@endcode 249 250The callback functions receives the cursor position, measured in screen 251coordinates but relative to the top-left corner of the window content area. On 252platforms that provide it, the full sub-pixel cursor position is passed on. 253 254@code 255static void cursor_position_callback(GLFWwindow* window, double xpos, double ypos) 256{ 257} 258@endcode 259 260The cursor position is also saved per-window and can be polled with @ref 261glfwGetCursorPos. 262 263@code 264double xpos, ypos; 265glfwGetCursorPos(window, &xpos, &ypos); 266@endcode 267 268 269@subsection cursor_mode Cursor mode 270 271@anchor GLFW_CURSOR 272The `GLFW_CURSOR` input mode provides several cursor modes for special forms of 273mouse motion input. By default, the cursor mode is `GLFW_CURSOR_NORMAL`, 274meaning the regular arrow cursor (or another cursor set with @ref glfwSetCursor) 275is used and cursor motion is not limited. 276 277If you wish to implement mouse motion based camera controls or other input 278schemes that require unlimited mouse movement, set the cursor mode to 279`GLFW_CURSOR_DISABLED`. 280 281@code 282glfwSetInputMode(window, GLFW_CURSOR, GLFW_CURSOR_DISABLED); 283@endcode 284 285This will hide the cursor and lock it to the specified window. GLFW will then 286take care of all the details of cursor re-centering and offset calculation and 287providing the application with a virtual cursor position. This virtual position 288is provided normally via both the cursor position callback and through polling. 289 290@note You should not implement your own version of this functionality using 291other features of GLFW. It is not supported and will not work as robustly as 292`GLFW_CURSOR_DISABLED`. 293 294If you only wish the cursor to become hidden when it is over a window but still 295want it to behave normally, set the cursor mode to `GLFW_CURSOR_HIDDEN`. 296 297@code 298glfwSetInputMode(window, GLFW_CURSOR, GLFW_CURSOR_HIDDEN); 299@endcode 300 301This mode puts no limit on the motion of the cursor. 302 303To exit out of either of these special modes, restore the `GLFW_CURSOR_NORMAL` 304cursor mode. 305 306@code 307glfwSetInputMode(window, GLFW_CURSOR, GLFW_CURSOR_NORMAL); 308@endcode 309 310 311@anchor GLFW_RAW_MOUSE_MOTION 312@subsection raw_mouse_motion Raw mouse motion 313 314When the cursor is disabled, raw (unscaled and unaccelerated) mouse motion can 315be enabled if available. 316 317Raw mouse motion is closer to the actual motion of the mouse across a surface. 318It is not affected by the scaling and acceleration applied to the motion of the 319desktop cursor. That processing is suitable for a cursor while raw motion is 320better for controlling for example a 3D camera. Because of this, raw mouse 321motion is only provided when the cursor is disabled. 322 323Call @ref glfwRawMouseMotionSupported to check if the current machine provides 324raw motion and set the `GLFW_RAW_MOUSE_MOTION` input mode to enable it. It is 325disabled by default. 326 327@code 328if (glfwRawMouseMotionSupported()) 329 glfwSetInputMode(window, GLFW_RAW_MOUSE_MOTION, GLFW_TRUE); 330@endcode 331 332If supported, raw mouse motion can be enabled or disabled per-window and at any 333time but it will only be provided when the cursor is disabled. 334 335 336@subsection cursor_object Cursor objects 337 338GLFW supports creating both custom and system theme cursor images, encapsulated 339as @ref GLFWcursor objects. They are created with @ref glfwCreateCursor or @ref 340glfwCreateStandardCursor and destroyed with @ref glfwDestroyCursor, or @ref 341glfwTerminate, if any remain. 342 343 344@subsubsection cursor_custom Custom cursor creation 345 346A custom cursor is created with @ref glfwCreateCursor, which returns a handle to 347the created cursor object. For example, this creates a 16x16 white square 348cursor with the hot-spot in the upper-left corner: 349 350@code 351unsigned char pixels[16 * 16 * 4]; 352memset(pixels, 0xff, sizeof(pixels)); 353 354GLFWimage image; 355image.width = 16; 356image.height = 16; 357image.pixels = pixels; 358 359GLFWcursor* cursor = glfwCreateCursor(&image, 0, 0); 360@endcode 361 362If cursor creation fails, `NULL` will be returned, so it is necessary to check 363the return value. 364 365The image data is 32-bit, little-endian, non-premultiplied RGBA, i.e. eight bits 366per channel with the red channel first. The pixels are arranged canonically as 367sequential rows, starting from the top-left corner. 368 369 370@subsubsection cursor_standard Standard cursor creation 371 372A cursor with a [standard shape](@ref shapes) from the current system cursor 373theme can be can be created with @ref glfwCreateStandardCursor. 374 375@code 376GLFWcursor* cursor = glfwCreateStandardCursor(GLFW_HRESIZE_CURSOR); 377@endcode 378 379These cursor objects behave in the exact same way as those created with @ref 380glfwCreateCursor except that the system cursor theme provides the actual image. 381 382 383@subsubsection cursor_destruction Cursor destruction 384 385When a cursor is no longer needed, destroy it with @ref glfwDestroyCursor. 386 387@code 388glfwDestroyCursor(cursor); 389@endcode 390 391Cursor destruction always succeeds. If the cursor is current for any window, 392that window will revert to the default cursor. This does not affect the cursor 393mode. All remaining cursors are destroyed when @ref glfwTerminate is called. 394 395 396@subsubsection cursor_set Cursor setting 397 398A cursor can be set as current for a window with @ref glfwSetCursor. 399 400@code 401glfwSetCursor(window, cursor); 402@endcode 403 404Once set, the cursor image will be used as long as the system cursor is over the 405content area of the window and the [cursor mode](@ref cursor_mode) is set 406to `GLFW_CURSOR_NORMAL`. 407 408A single cursor may be set for any number of windows. 409 410To revert to the default cursor, set the cursor of that window to `NULL`. 411 412@code 413glfwSetCursor(window, NULL); 414@endcode 415 416When a cursor is destroyed, any window that has it set will revert to the 417default cursor. This does not affect the cursor mode. 418 419 420@subsection cursor_enter Cursor enter/leave events 421 422If you wish to be notified when the cursor enters or leaves the content area of 423a window, set a cursor enter/leave callback. 424 425@code 426glfwSetCursorEnterCallback(window, cursor_enter_callback); 427@endcode 428 429The callback function receives the new classification of the cursor. 430 431@code 432void cursor_enter_callback(GLFWwindow* window, int entered) 433{ 434 if (entered) 435 { 436 // The cursor entered the content area of the window 437 } 438 else 439 { 440 // The cursor left the content area of the window 441 } 442} 443@endcode 444 445You can query whether the cursor is currently inside the content area of the 446window with the [GLFW_HOVERED](@ref GLFW_HOVERED_attrib) window attribute. 447 448@code 449if (glfwGetWindowAttrib(window, GLFW_HOVERED)) 450{ 451 highlight_interface(); 452} 453@endcode 454 455 456@subsection input_mouse_button Mouse button input 457 458If you wish to be notified when a mouse button is pressed or released, set 459a mouse button callback. 460 461@code 462glfwSetMouseButtonCallback(window, mouse_button_callback); 463@endcode 464 465The callback function receives the [mouse button](@ref buttons), button action 466and [modifier bits](@ref mods). 467 468@code 469void mouse_button_callback(GLFWwindow* window, int button, int action, int mods) 470{ 471 if (button == GLFW_MOUSE_BUTTON_RIGHT && action == GLFW_PRESS) 472 popup_menu(); 473} 474@endcode 475 476The action is one of `GLFW_PRESS` or `GLFW_RELEASE`. 477 478Mouse button states for [named buttons](@ref buttons) are also saved in 479per-window state arrays that can be polled with @ref glfwGetMouseButton. 480 481@code 482int state = glfwGetMouseButton(window, GLFW_MOUSE_BUTTON_LEFT); 483if (state == GLFW_PRESS) 484{ 485 upgrade_cow(); 486} 487@endcode 488 489The returned state is one of `GLFW_PRESS` or `GLFW_RELEASE`. 490 491This function only returns cached mouse button event state. It does not poll 492the system for the current state of the mouse button. 493 494@anchor GLFW_STICKY_MOUSE_BUTTONS 495Whenever you poll state, you risk missing the state change you are looking for. 496If a pressed mouse button is released again before you poll its state, you will have 497missed the button press. The recommended solution for this is to use a 498mouse button callback, but there is also the `GLFW_STICKY_MOUSE_BUTTONS` 499input mode. 500 501@code 502glfwSetInputMode(window, GLFW_STICKY_MOUSE_BUTTONS, GLFW_TRUE); 503@endcode 504 505When sticky mouse buttons mode is enabled, the pollable state of a mouse button 506will remain `GLFW_PRESS` until the state of that button is polled with @ref 507glfwGetMouseButton. Once it has been polled, if a mouse button release event 508had been processed in the meantime, the state will reset to `GLFW_RELEASE`, 509otherwise it will remain `GLFW_PRESS`. 510 511The `GLFW_MOUSE_BUTTON_LAST` constant holds the highest value of any 512[named button](@ref buttons). 513 514 515@subsection scrolling Scroll input 516 517If you wish to be notified when the user scrolls, whether with a mouse wheel or 518touchpad gesture, set a scroll callback. 519 520@code 521glfwSetScrollCallback(window, scroll_callback); 522@endcode 523 524The callback function receives two-dimensional scroll offsets. 525 526@code 527void scroll_callback(GLFWwindow* window, double xoffset, double yoffset) 528{ 529} 530@endcode 531 532A normal mouse wheel, being vertical, provides offsets along the Y-axis. 533 534 535@section joystick Joystick input 536 537The joystick functions expose connected joysticks and controllers, with both 538referred to as joysticks. It supports up to sixteen joysticks, ranging from 539`GLFW_JOYSTICK_1`, `GLFW_JOYSTICK_2` up to and including `GLFW_JOYSTICK_16` or 540`GLFW_JOYSTICK_LAST`. You can test whether a [joystick](@ref joysticks) is 541present with @ref glfwJoystickPresent. 542 543@code 544int present = glfwJoystickPresent(GLFW_JOYSTICK_1); 545@endcode 546 547Each joystick has zero or more axes, zero or more buttons, zero or more hats, 548a human-readable name, a user pointer and an SDL compatible GUID. 549 550When GLFW is initialized, detected joysticks are added to the beginning of 551the array. Once a joystick is detected, it keeps its assigned ID until it is 552disconnected or the library is terminated, so as joysticks are connected and 553disconnected, there may appear gaps in the IDs. 554 555Joystick axis, button and hat state is updated when polled and does not require 556a window to be created or events to be processed. However, if you want joystick 557connection and disconnection events reliably delivered to the 558[joystick callback](@ref joystick_event) then you must 559[process events](@ref events). 560 561To see all the properties of all connected joysticks in real-time, run the 562`joysticks` test program. 563 564 565@subsection joystick_axis Joystick axis states 566 567The positions of all axes of a joystick are returned by @ref 568glfwGetJoystickAxes. See the reference documentation for the lifetime of the 569returned array. 570 571@code 572int count; 573const float* axes = glfwGetJoystickAxes(GLFW_JOYSTICK_5, &count); 574@endcode 575 576Each element in the returned array is a value between -1.0 and 1.0. 577 578 579@subsection joystick_button Joystick button states 580 581The states of all buttons of a joystick are returned by @ref 582glfwGetJoystickButtons. See the reference documentation for the lifetime of the 583returned array. 584 585@code 586int count; 587const unsigned char* buttons = glfwGetJoystickButtons(GLFW_JOYSTICK_3, &count); 588@endcode 589 590Each element in the returned array is either `GLFW_PRESS` or `GLFW_RELEASE`. 591 592For backward compatibility with earlier versions that did not have @ref 593glfwGetJoystickHats, the button array by default also includes all hats. See 594the reference documentation for @ref glfwGetJoystickButtons for details. 595 596 597@subsection joystick_hat Joystick hat states 598 599The states of all hats are returned by @ref glfwGetJoystickHats. See the 600reference documentation for the lifetime of the returned array. 601 602@code 603int count; 604const unsigned char* hats = glfwGetJoystickHats(GLFW_JOYSTICK_7, &count); 605@endcode 606 607Each element in the returned array is one of the following: 608 609Name | Value 610---- | ----- 611`GLFW_HAT_CENTERED` | 0 612`GLFW_HAT_UP` | 1 613`GLFW_HAT_RIGHT` | 2 614`GLFW_HAT_DOWN` | 4 615`GLFW_HAT_LEFT` | 8 616`GLFW_HAT_RIGHT_UP` | `GLFW_HAT_RIGHT` \| `GLFW_HAT_UP` 617`GLFW_HAT_RIGHT_DOWN` | `GLFW_HAT_RIGHT` \| `GLFW_HAT_DOWN` 618`GLFW_HAT_LEFT_UP` | `GLFW_HAT_LEFT` \| `GLFW_HAT_UP` 619`GLFW_HAT_LEFT_DOWN` | `GLFW_HAT_LEFT` \| `GLFW_HAT_DOWN` 620 621The diagonal directions are bitwise combinations of the primary (up, right, down 622and left) directions and you can test for these individually by ANDing it with 623the corresponding direction. 624 625@code 626if (hats[2] & GLFW_HAT_RIGHT) 627{ 628 // State of hat 2 could be right-up, right or right-down 629} 630@endcode 631 632For backward compatibility with earlier versions that did not have @ref 633glfwGetJoystickHats, all hats are by default also included in the button array. 634See the reference documentation for @ref glfwGetJoystickButtons for details. 635 636 637@subsection joystick_name Joystick name 638 639The human-readable, UTF-8 encoded name of a joystick is returned by @ref 640glfwGetJoystickName. See the reference documentation for the lifetime of the 641returned string. 642 643@code 644const char* name = glfwGetJoystickName(GLFW_JOYSTICK_4); 645@endcode 646 647Joystick names are not guaranteed to be unique. Two joysticks of the same model 648and make may have the same name. Only the [joystick token](@ref joysticks) is 649guaranteed to be unique, and only until that joystick is disconnected. 650 651 652@subsection joystick_userptr Joystick user pointer 653 654Each joystick has a user pointer that can be set with @ref 655glfwSetJoystickUserPointer and queried with @ref glfwGetJoystickUserPointer. 656This can be used for any purpose you need and will not be modified by GLFW. The 657value will be kept until the joystick is disconnected or until the library is 658terminated. 659 660The initial value of the pointer is `NULL`. 661 662 663@subsection joystick_event Joystick configuration changes 664 665If you wish to be notified when a joystick is connected or disconnected, set 666a joystick callback. 667 668@code 669glfwSetJoystickCallback(joystick_callback); 670@endcode 671 672The callback function receives the ID of the joystick that has been connected 673and disconnected and the event that occurred. 674 675@code 676void joystick_callback(int jid, int event) 677{ 678 if (event == GLFW_CONNECTED) 679 { 680 // The joystick was connected 681 } 682 else if (event == GLFW_DISCONNECTED) 683 { 684 // The joystick was disconnected 685 } 686} 687@endcode 688 689For joystick connection and disconnection events to be delivered on all 690platforms, you need to call one of the [event processing](@ref events) 691functions. Joystick disconnection may also be detected and the callback 692called by joystick functions. The function will then return whatever it 693returns for a disconnected joystick. 694 695Only @ref glfwGetJoystickName and @ref glfwGetJoystickUserPointer will return 696useful values for a disconnected joystick and only before the monitor callback 697returns. 698 699 700@subsection gamepad Gamepad input 701 702The joystick functions provide unlabeled axes, buttons and hats, with no 703indication of where they are located on the device. Their order may also vary 704between platforms even with the same device. 705 706To solve this problem the SDL community crowdsourced the 707[SDL_GameControllerDB](https://github.com/gabomdq/SDL_GameControllerDB) project, 708a database of mappings from many different devices to an Xbox-like gamepad. 709 710GLFW supports this mapping format and contains a copy of the mappings 711available at the time of release. See @ref gamepad_mapping for how to update 712this at runtime. Mappings will be assigned to joysticks automatically any time 713a joystick is connected or the mappings are updated. 714 715You can check whether a joystick is both present and has a gamepad mapping with 716@ref glfwJoystickIsGamepad. 717 718@code 719if (glfwJoystickIsGamepad(GLFW_JOYSTICK_2)) 720{ 721 // Use as gamepad 722} 723@endcode 724 725If you are only interested in gamepad input you can use this function instead of 726@ref glfwJoystickPresent. 727 728You can query the human-readable name provided by the gamepad mapping with @ref 729glfwGetGamepadName. This may or may not be the same as the 730[joystick name](@ref joystick_name). 731 732@code 733const char* name = glfwGetGamepadName(GLFW_JOYSTICK_7); 734@endcode 735 736To retrieve the gamepad state of a joystick, call @ref glfwGetGamepadState. 737 738@code 739GLFWgamepadstate state; 740 741if (glfwGetGamepadState(GLFW_JOYSTICK_3, &state)) 742{ 743 if (state.buttons[GLFW_GAMEPAD_BUTTON_A]) 744 { 745 input_jump(); 746 } 747 748 input_speed(state.axes[GLFW_GAMEPAD_AXIS_RIGHT_TRIGGER]); 749} 750@endcode 751 752The @ref GLFWgamepadstate struct has two arrays; one for button states and one 753for axis states. The values for each button and axis are the same as for the 754@ref glfwGetJoystickButtons and @ref glfwGetJoystickAxes functions, i.e. 755`GLFW_PRESS` or `GLFW_RELEASE` for buttons and -1.0 to 1.0 inclusive for axes. 756 757The sizes of the arrays and the positions within each array are fixed. 758 759The [button indices](@ref gamepad_buttons) are `GLFW_GAMEPAD_BUTTON_A`, 760`GLFW_GAMEPAD_BUTTON_B`, `GLFW_GAMEPAD_BUTTON_X`, `GLFW_GAMEPAD_BUTTON_Y`, 761`GLFW_GAMEPAD_BUTTON_LEFT_BUMPER`, `GLFW_GAMEPAD_BUTTON_RIGHT_BUMPER`, 762`GLFW_GAMEPAD_BUTTON_BACK`, `GLFW_GAMEPAD_BUTTON_START`, 763`GLFW_GAMEPAD_BUTTON_GUIDE`, `GLFW_GAMEPAD_BUTTON_LEFT_THUMB`, 764`GLFW_GAMEPAD_BUTTON_RIGHT_THUMB`, `GLFW_GAMEPAD_BUTTON_DPAD_UP`, 765`GLFW_GAMEPAD_BUTTON_DPAD_RIGHT`, `GLFW_GAMEPAD_BUTTON_DPAD_DOWN` and 766`GLFW_GAMEPAD_BUTTON_DPAD_LEFT`. 767 768For those who prefer, there are also the `GLFW_GAMEPAD_BUTTON_CROSS`, 769`GLFW_GAMEPAD_BUTTON_CIRCLE`, `GLFW_GAMEPAD_BUTTON_SQUARE` and 770`GLFW_GAMEPAD_BUTTON_TRIANGLE` aliases for the A, B, X and Y button indices. 771 772The [axis indices](@ref gamepad_axes) are `GLFW_GAMEPAD_AXIS_LEFT_X`, 773`GLFW_GAMEPAD_AXIS_LEFT_Y`, `GLFW_GAMEPAD_AXIS_RIGHT_X`, 774`GLFW_GAMEPAD_AXIS_RIGHT_Y`, `GLFW_GAMEPAD_AXIS_LEFT_TRIGGER` and 775`GLFW_GAMEPAD_AXIS_RIGHT_TRIGGER`. 776 777The `GLFW_GAMEPAD_BUTTON_LAST` and `GLFW_GAMEPAD_AXIS_LAST` constants equal 778the largest available index for each array. 779 780 781@subsection gamepad_mapping Gamepad mappings 782 783GLFW contains a copy of the mappings available in 784[SDL_GameControllerDB](https://github.com/gabomdq/SDL_GameControllerDB) at the 785time of release. Newer ones can be added at runtime with @ref 786glfwUpdateGamepadMappings. 787 788@code 789const char* mappings = load_file_contents("game/data/gamecontrollerdb.txt"); 790 791glfwUpdateGamepadMappings(mappings); 792@endcode 793 794This function supports everything from single lines up to and including the 795unmodified contents of the whole `gamecontrollerdb.txt` file. 796 797Below is a description of the mapping format. Please keep in mind that __this 798description is not authoritative__. The format is defined by the SDL and 799SDL_GameControllerDB projects and their documentation and code takes precedence. 800 801Each mapping is a single line of comma-separated values describing the GUID, 802name and layout of the gamepad. Lines that do not begin with a hexadecimal 803digit are ignored. 804 805The first value is always the gamepad GUID, a 32 character long hexadecimal 806string that typically identifies its make, model, revision and the type of 807connection to the computer. When this information is not available, the GUID is 808generated using the gamepad name. GLFW uses the SDL 2.0.5+ GUID format but can 809convert from the older formats. 810 811The second value is always the human-readable name of the gamepad. 812 813All subsequent values are in the form `<field>:<value>` and describe the layout 814of the mapping. These fields may not all be present and may occur in any order. 815 816The button fields are `a`, `b`, `c`, `d`, `back`, `start`, `guide`, `dpup`, 817`dpright`, `dpdown`, `dpleft`, `leftshoulder`, `rightshoulder`, `leftstick` and 818`rightstick`. 819 820The axis fields are `leftx`, `lefty`, `rightx`, `righty`, `lefttrigger` and 821`righttrigger`. 822 823The value of an axis or button field can be a joystick button, a joystick axis, 824a hat bitmask or empty. Joystick buttons are specified as `bN`, for example 825`b2` for the third button. Joystick axes are specified as `aN`, for example 826`a7` for the eighth button. Joystick hat bit masks are specified as `hN.N`, for 827example `h0.8` for left on the first hat. More than one bit may be set in the 828mask. 829 830Before an axis there may be a `+` or `-` range modifier, for example `+a3` for 831the positive half of the fourth axis. This restricts input to only the positive 832or negative halves of the joystick axis. After an axis or half-axis there may 833be the `~` inversion modifier, for example `a2~` or `-a7~`. This negates the 834values of the gamepad axis. 835 836The hat bit mask match the [hat states](@ref hat_state) in the joystick 837functions. 838 839There is also the special `platform` field that specifies which platform the 840mapping is valid for. Possible values are `Windows`, `Mac OS X` and `Linux`. 841 842Below is an example of what a gamepad mapping might look like. It is the 843one built into GLFW for Xbox controllers accessed via the XInput API on Windows. 844This example has been broken into several lines to fit on the page, but real 845gamepad mappings must be a single line. 846 847@code{.unparsed} 84878696e70757401000000000000000000,XInput Gamepad (GLFW),platform:Windows,a:b0, 849b:b1,x:b2,y:b3,leftshoulder:b4,rightshoulder:b5,back:b6,start:b7,leftstick:b8, 850rightstick:b9,leftx:a0,lefty:a1,rightx:a2,righty:a3,lefttrigger:a4, 851righttrigger:a5,dpup:h0.1,dpright:h0.2,dpdown:h0.4,dpleft:h0.8, 852@endcode 853 854@note GLFW does not yet support the output range and modifiers `+` and `-` that 855were recently added to SDL. The input modifiers `+`, `-` and `~` are supported 856and described above. 857 858 859@section time Time input 860 861GLFW provides high-resolution time input, in seconds, with @ref glfwGetTime. 862 863@code 864double seconds = glfwGetTime(); 865@endcode 866 867It returns the number of seconds since the library was initialized with @ref 868glfwInit. The platform-specific time sources used typically have micro- or 869nanosecond resolution. 870 871You can modify the base time with @ref glfwSetTime. 872 873@code 874glfwSetTime(4.0); 875@endcode 876 877This sets the time to the specified time, in seconds, and it continues to count 878from there. 879 880You can also access the raw timer used to implement the functions above, 881with @ref glfwGetTimerValue. 882 883@code 884uint64_t value = glfwGetTimerValue(); 885@endcode 886 887This value is in 1 / frequency seconds. The frequency of the raw 888timer varies depending on the operating system and hardware. You can query the 889frequency, in Hz, with @ref glfwGetTimerFrequency. 890 891@code 892uint64_t frequency = glfwGetTimerFrequency(); 893@endcode 894 895 896@section clipboard Clipboard input and output 897 898If the system clipboard contains a UTF-8 encoded string or if it can be 899converted to one, you can retrieve it with @ref glfwGetClipboardString. See the 900reference documentation for the lifetime of the returned string. 901 902@code 903const char* text = glfwGetClipboardString(NULL); 904if (text) 905{ 906 insert_text(text); 907} 908@endcode 909 910If the clipboard is empty or if its contents could not be converted, `NULL` is 911returned. 912 913The contents of the system clipboard can be set to a UTF-8 encoded string with 914@ref glfwSetClipboardString. 915 916@code 917glfwSetClipboardString(NULL, "A string with words in it"); 918@endcode 919 920 921@section path_drop Path drop input 922 923If you wish to receive the paths of files and/or directories dropped on 924a window, set a file drop callback. 925 926@code 927glfwSetDropCallback(window, drop_callback); 928@endcode 929 930The callback function receives an array of paths encoded as UTF-8. 931 932@code 933void drop_callback(GLFWwindow* window, int count, const char** paths) 934{ 935 int i; 936 for (i = 0; i < count; i++) 937 handle_dropped_file(paths[i]); 938} 939@endcode 940 941The path array and its strings are only valid until the file drop callback 942returns, as they may have been generated specifically for that event. You need 943to make a deep copy of the array if you want to keep the paths. 944 945*/ 946