diff options
Diffstat (limited to '3rdparty/glfw/source/docs/input.dox')
| -rw-r--r-- | 3rdparty/glfw/source/docs/input.dox | 953 |
1 files changed, 0 insertions, 953 deletions
diff --git a/3rdparty/glfw/source/docs/input.dox b/3rdparty/glfw/source/docs/input.dox deleted file mode 100644 index faa94cd..0000000 --- a/3rdparty/glfw/source/docs/input.dox +++ /dev/null @@ -1,953 +0,0 @@ -/*! - -@page input_guide Input guide - -@tableofcontents - -This guide introduces the input related functions of GLFW. For details on -a specific function in this category, see the @ref input. There are also guides -for the other areas of GLFW. - - - @ref intro_guide - - @ref window_guide - - @ref context_guide - - @ref vulkan_guide - - @ref monitor_guide - -GLFW provides many kinds of input. While some can only be polled, like time, or -only received via callbacks, like scrolling, many provide both callbacks and -polling. Callbacks are more work to use than polling but is less CPU intensive -and guarantees that you do not miss state changes. - -All input callbacks receive a window handle. By using the -[window user pointer](@ref window_userptr), you can access non-global structures -or objects from your callbacks. - -To get a better feel for how the various events callbacks behave, run the -`events` test program. It register every callback supported by GLFW and prints -out all arguments provided for every event, along with time and sequence -information. - - -@section events Event processing - -GLFW needs to poll the window system for events both to provide input to the -application and to prove to the window system that the application hasn't locked -up. Event processing is normally done each frame after -[buffer swapping](@ref buffer_swap). Even when you have no windows, event -polling needs to be done in order to receive monitor and joystick connection -events. - -There are three functions for processing pending events. @ref glfwPollEvents, -processes only those events that have already been received and then returns -immediately. - -@code -glfwPollEvents(); -@endcode - -This is the best choice when rendering continuously, like most games do. - -If you only need to update the contents of the window when you receive new -input, @ref glfwWaitEvents is a better choice. - -@code -glfwWaitEvents(); -@endcode - -It puts the thread to sleep until at least one event has been received and then -processes all received events. This saves a great deal of CPU cycles and is -useful for, for example, editing tools. - -If you want to wait for events but have UI elements or other tasks that need -periodic updates, @ref glfwWaitEventsTimeout lets you specify a timeout. - -@code -glfwWaitEventsTimeout(0.7); -@endcode - -It puts the thread to sleep until at least one event has been received, or until -the specified number of seconds have elapsed. It then processes any received -events. - -If the main thread is sleeping in @ref glfwWaitEvents, you can wake it from -another thread by posting an empty event to the event queue with @ref -glfwPostEmptyEvent. - -@code -glfwPostEmptyEvent(); -@endcode - -Do not assume that callbacks will _only_ be called in response to the above -functions. While it is necessary to process events in one or more of the ways -above, window systems that require GLFW to register callbacks of its own can -pass events to GLFW in response to many window system function calls. GLFW will -pass those events on to the application callbacks before returning. - -For example, on Windows the system function that @ref glfwSetWindowSize is -implemented with will send window size events directly to the event callback -that every window has and that GLFW implements for its windows. If you have set -a [window size callback](@ref window_size) GLFW will call it in turn with the -new size before everything returns back out of the @ref glfwSetWindowSize call. - - -@section input_keyboard Keyboard input - -GLFW divides keyboard input into two categories; key events and character -events. Key events relate to actual physical keyboard keys, whereas character -events relate to the Unicode code points generated by pressing some of them. - -Keys and characters do not map 1:1. A single key press may produce several -characters, and a single character may require several keys to produce. This -may not be the case on your machine, but your users are likely not all using the -same keyboard layout, input method or even operating system as you. - - -@subsection input_key Key input - -If you wish to be notified when a physical key is pressed or released or when it -repeats, set a key callback. - -@code -glfwSetKeyCallback(window, key_callback); -@endcode - -The callback function receives the [keyboard key](@ref keys), platform-specific -scancode, key action and [modifier bits](@ref mods). - -@code -void key_callback(GLFWwindow* window, int key, int scancode, int action, int mods) -{ - if (key == GLFW_KEY_E && action == GLFW_PRESS) - activate_airship(); -} -@endcode - -The action is one of `GLFW_PRESS`, `GLFW_REPEAT` or `GLFW_RELEASE`. The key -will be `GLFW_KEY_UNKNOWN` if GLFW lacks a key token for it, for example -_E-mail_ and _Play_ keys. - -The scancode is unique for every key, regardless of whether it has a key token. -Scancodes are platform-specific but consistent over time, so keys will have -different scancodes depending on the platform but they are safe to save to disk. -You can query the scancode for any [named key](@ref keys) on the current -platform with @ref glfwGetKeyScancode. - -@code -const int scancode = glfwGetKeyScancode(GLFW_KEY_X); -set_key_mapping(scancode, swap_weapons); -@endcode - -The last reported state for every [named key](@ref keys) is also saved in -per-window state arrays that can be polled with @ref glfwGetKey. - -@code -int state = glfwGetKey(window, GLFW_KEY_E); -if (state == GLFW_PRESS) -{ - activate_airship(); -} -@endcode - -The returned state is one of `GLFW_PRESS` or `GLFW_RELEASE`. - -This function only returns cached key event state. It does not poll the -system for the current physical state of the key. - -@anchor GLFW_STICKY_KEYS -Whenever you poll state, you risk missing the state change you are looking for. -If a pressed key is released again before you poll its state, you will have -missed the key press. The recommended solution for this is to use a -key callback, but there is also the `GLFW_STICKY_KEYS` input mode. - -@code -glfwSetInputMode(window, GLFW_STICKY_KEYS, GLFW_TRUE); -@endcode - -When sticky keys mode is enabled, the pollable state of a key will remain -`GLFW_PRESS` until the state of that key is polled with @ref glfwGetKey. Once -it has been polled, if a key release event had been processed in the meantime, -the state will reset to `GLFW_RELEASE`, otherwise it will remain `GLFW_PRESS`. - -@anchor GLFW_LOCK_KEY_MODS -If you wish to know what the state of the Caps Lock and Num Lock keys was when -input events were generated, set the `GLFW_LOCK_KEY_MODS` input mode. - -@code -glfwSetInputMode(window, GLFW_LOCK_KEY_MODS, GLFW_TRUE); -@endcode - -When this input mode is enabled, any callback that receives -[modifier bits](@ref mods) will have the @ref GLFW_MOD_CAPS_LOCK bit set if Caps -Lock was on when the event occurred and the @ref GLFW_MOD_NUM_LOCK bit set if -Num Lock was on. - -The `GLFW_KEY_LAST` constant holds the highest value of any -[named key](@ref keys). - - -@subsection input_char Text input - -GLFW supports text input in the form of a stream of -[Unicode code points](https://en.wikipedia.org/wiki/Unicode), as produced by the -operating system text input system. Unlike key input, text input obeys keyboard -layouts and modifier keys and supports composing characters using -[dead keys](https://en.wikipedia.org/wiki/Dead_key). Once received, you can -encode the code points into UTF-8 or any other encoding you prefer. - -Because an `unsigned int` is 32 bits long on all platforms supported by GLFW, -you can treat the code point argument as native endian UTF-32. - -If you wish to offer regular text input, set a character callback. - -@code -glfwSetCharCallback(window, character_callback); -@endcode - -The callback function receives Unicode code points for key events that would -have led to regular text input and generally behaves as a standard text field on -that platform. - -@code -void character_callback(GLFWwindow* window, unsigned int codepoint) -{ -} -@endcode - - -@subsection input_key_name Key names - -If you wish to refer to keys by name, you can query the keyboard layout -dependent name of printable keys with @ref glfwGetKeyName. - -@code -const char* key_name = glfwGetKeyName(GLFW_KEY_W, 0); -show_tutorial_hint("Press %s to move forward", key_name); -@endcode - -This function can handle both [keys and scancodes](@ref input_key). If the -specified key is `GLFW_KEY_UNKNOWN` then the scancode is used, otherwise it is -ignored. This matches the behavior of the key callback, meaning the callback -arguments can always be passed unmodified to this function. - - -@section input_mouse Mouse input - -Mouse input comes in many forms, including mouse motion, button presses and -scrolling offsets. The cursor appearance can also be changed, either to -a custom image or a standard cursor shape from the system theme. - - -@subsection cursor_pos Cursor position - -If you wish to be notified when the cursor moves over the window, set a cursor -position callback. - -@code -glfwSetCursorPosCallback(window, cursor_position_callback); -@endcode - -The callback functions receives the cursor position, measured in screen -coordinates but relative to the top-left corner of the window content area. On -platforms that provide it, the full sub-pixel cursor position is passed on. - -@code -static void cursor_position_callback(GLFWwindow* window, double xpos, double ypos) -{ -} -@endcode - -The cursor position is also saved per-window and can be polled with @ref -glfwGetCursorPos. - -@code -double xpos, ypos; -glfwGetCursorPos(window, &xpos, &ypos); -@endcode - - -@subsection cursor_mode Cursor mode - -@anchor GLFW_CURSOR -The `GLFW_CURSOR` input mode provides several cursor modes for special forms of -mouse motion input. By default, the cursor mode is `GLFW_CURSOR_NORMAL`, -meaning the regular arrow cursor (or another cursor set with @ref glfwSetCursor) -is used and cursor motion is not limited. - -If you wish to implement mouse motion based camera controls or other input -schemes that require unlimited mouse movement, set the cursor mode to -`GLFW_CURSOR_DISABLED`. - -@code -glfwSetInputMode(window, GLFW_CURSOR, GLFW_CURSOR_DISABLED); -@endcode - -This will hide the cursor and lock it to the specified window. GLFW will then -take care of all the details of cursor re-centering and offset calculation and -providing the application with a virtual cursor position. This virtual position -is provided normally via both the cursor position callback and through polling. - -@note You should not implement your own version of this functionality using -other features of GLFW. It is not supported and will not work as robustly as -`GLFW_CURSOR_DISABLED`. - -If you only wish the cursor to become hidden when it is over a window but still -want it to behave normally, set the cursor mode to `GLFW_CURSOR_HIDDEN`. - -@code -glfwSetInputMode(window, GLFW_CURSOR, GLFW_CURSOR_HIDDEN); -@endcode - -This mode puts no limit on the motion of the cursor. - -To exit out of either of these special modes, restore the `GLFW_CURSOR_NORMAL` -cursor mode. - -@code -glfwSetInputMode(window, GLFW_CURSOR, GLFW_CURSOR_NORMAL); -@endcode - - -@anchor GLFW_RAW_MOUSE_MOTION -@subsection raw_mouse_motion Raw mouse motion - -When the cursor is disabled, raw (unscaled and unaccelerated) mouse motion can -be enabled if available. - -Raw mouse motion is closer to the actual motion of the mouse across a surface. -It is not affected by the scaling and acceleration applied to the motion of the -desktop cursor. That processing is suitable for a cursor while raw motion is -better for controlling for example a 3D camera. Because of this, raw mouse -motion is only provided when the cursor is disabled. - -Call @ref glfwRawMouseMotionSupported to check if the current machine provides -raw motion and set the `GLFW_RAW_MOUSE_MOTION` input mode to enable it. It is -disabled by default. - -@code -if (glfwRawMouseMotionSupported()) - glfwSetInputMode(window, GLFW_RAW_MOUSE_MOTION, GLFW_TRUE); -@endcode - -If supported, raw mouse motion can be enabled or disabled per-window and at any -time but it will only be provided when the cursor is disabled. - - -@subsection cursor_object Cursor objects - -GLFW supports creating both custom and system theme cursor images, encapsulated -as @ref GLFWcursor objects. They are created with @ref glfwCreateCursor or @ref -glfwCreateStandardCursor and destroyed with @ref glfwDestroyCursor, or @ref -glfwTerminate, if any remain. - - -@subsubsection cursor_custom Custom cursor creation - -A custom cursor is created with @ref glfwCreateCursor, which returns a handle to -the created cursor object. For example, this creates a 16x16 white square -cursor with the hot-spot in the upper-left corner: - -@code -unsigned char pixels[16 * 16 * 4]; -memset(pixels, 0xff, sizeof(pixels)); - -GLFWimage image; -image.width = 16; -image.height = 16; -image.pixels = pixels; - -GLFWcursor* cursor = glfwCreateCursor(&image, 0, 0); -@endcode - -If cursor creation fails, `NULL` will be returned, so it is necessary to check -the return value. - -The image data is 32-bit, little-endian, non-premultiplied RGBA, i.e. eight bits -per channel with the red channel first. The pixels are arranged canonically as -sequential rows, starting from the top-left corner. - - -@subsubsection cursor_standard Standard cursor creation - -A cursor with a [standard shape](@ref shapes) from the current system cursor -theme can be can be created with @ref glfwCreateStandardCursor. - -@code -GLFWcursor* url_cursor = glfwCreateStandardCursor(GLFW_POINTING_HAND_CURSOR); -@endcode - -These cursor objects behave in the exact same way as those created with @ref -glfwCreateCursor except that the system cursor theme provides the actual image. - -A few of these shapes are not available everywhere. If a shape is unavailable, -`NULL` is returned. See @ref glfwCreateStandardCursor for details. - - -@subsubsection cursor_destruction Cursor destruction - -When a cursor is no longer needed, destroy it with @ref glfwDestroyCursor. - -@code -glfwDestroyCursor(cursor); -@endcode - -Cursor destruction always succeeds. If the cursor is current for any window, -that window will revert to the default cursor. This does not affect the cursor -mode. All remaining cursors are destroyed when @ref glfwTerminate is called. - - -@subsubsection cursor_set Cursor setting - -A cursor can be set as current for a window with @ref glfwSetCursor. - -@code -glfwSetCursor(window, cursor); -@endcode - -Once set, the cursor image will be used as long as the system cursor is over the -content area of the window and the [cursor mode](@ref cursor_mode) is set -to `GLFW_CURSOR_NORMAL`. - -A single cursor may be set for any number of windows. - -To revert to the default cursor, set the cursor of that window to `NULL`. - -@code -glfwSetCursor(window, NULL); -@endcode - -When a cursor is destroyed, any window that has it set will revert to the -default cursor. This does not affect the cursor mode. - - -@subsection cursor_enter Cursor enter/leave events - -If you wish to be notified when the cursor enters or leaves the content area of -a window, set a cursor enter/leave callback. - -@code -glfwSetCursorEnterCallback(window, cursor_enter_callback); -@endcode - -The callback function receives the new classification of the cursor. - -@code -void cursor_enter_callback(GLFWwindow* window, int entered) -{ - if (entered) - { - // The cursor entered the content area of the window - } - else - { - // The cursor left the content area of the window - } -} -@endcode - -You can query whether the cursor is currently inside the content area of the -window with the [GLFW_HOVERED](@ref GLFW_HOVERED_attrib) window attribute. - -@code -if (glfwGetWindowAttrib(window, GLFW_HOVERED)) -{ - highlight_interface(); -} -@endcode - - -@subsection input_mouse_button Mouse button input - -If you wish to be notified when a mouse button is pressed or released, set -a mouse button callback. - -@code -glfwSetMouseButtonCallback(window, mouse_button_callback); -@endcode - -The callback function receives the [mouse button](@ref buttons), button action -and [modifier bits](@ref mods). - -@code -void mouse_button_callback(GLFWwindow* window, int button, int action, int mods) -{ - if (button == GLFW_MOUSE_BUTTON_RIGHT && action == GLFW_PRESS) - popup_menu(); -} -@endcode - -The action is one of `GLFW_PRESS` or `GLFW_RELEASE`. - -Mouse button states for [named buttons](@ref buttons) are also saved in -per-window state arrays that can be polled with @ref glfwGetMouseButton. - -@code -int state = glfwGetMouseButton(window, GLFW_MOUSE_BUTTON_LEFT); -if (state == GLFW_PRESS) -{ - upgrade_cow(); -} -@endcode - -The returned state is one of `GLFW_PRESS` or `GLFW_RELEASE`. - -This function only returns cached mouse button event state. It does not poll -the system for the current state of the mouse button. - -@anchor GLFW_STICKY_MOUSE_BUTTONS -Whenever you poll state, you risk missing the state change you are looking for. -If a pressed mouse button is released again before you poll its state, you will have -missed the button press. The recommended solution for this is to use a -mouse button callback, but there is also the `GLFW_STICKY_MOUSE_BUTTONS` -input mode. - -@code -glfwSetInputMode(window, GLFW_STICKY_MOUSE_BUTTONS, GLFW_TRUE); -@endcode - -When sticky mouse buttons mode is enabled, the pollable state of a mouse button -will remain `GLFW_PRESS` until the state of that button is polled with @ref -glfwGetMouseButton. Once it has been polled, if a mouse button release event -had been processed in the meantime, the state will reset to `GLFW_RELEASE`, -otherwise it will remain `GLFW_PRESS`. - -The `GLFW_MOUSE_BUTTON_LAST` constant holds the highest value of any -[named button](@ref buttons). - - -@subsection scrolling Scroll input - -If you wish to be notified when the user scrolls, whether with a mouse wheel or -touchpad gesture, set a scroll callback. - -@code -glfwSetScrollCallback(window, scroll_callback); -@endcode - -The callback function receives two-dimensional scroll offsets. - -@code -void scroll_callback(GLFWwindow* window, double xoffset, double yoffset) -{ -} -@endcode - -A normal mouse wheel, being vertical, provides offsets along the Y-axis. - - -@section joystick Joystick input - -The joystick functions expose connected joysticks and controllers, with both -referred to as joysticks. It supports up to sixteen joysticks, ranging from -`GLFW_JOYSTICK_1`, `GLFW_JOYSTICK_2` up to and including `GLFW_JOYSTICK_16` or -`GLFW_JOYSTICK_LAST`. You can test whether a [joystick](@ref joysticks) is -present with @ref glfwJoystickPresent. - -@code -int present = glfwJoystickPresent(GLFW_JOYSTICK_1); -@endcode - -Each joystick has zero or more axes, zero or more buttons, zero or more hats, -a human-readable name, a user pointer and an SDL compatible GUID. - -Detected joysticks are added to the beginning of the array. Once a joystick is -detected, it keeps its assigned ID until it is disconnected or the library is -terminated, so as joysticks are connected and disconnected, there may appear -gaps in the IDs. - -Joystick axis, button and hat state is updated when polled and does not require -a window to be created or events to be processed. However, if you want joystick -connection and disconnection events reliably delivered to the -[joystick callback](@ref joystick_event) then you must -[process events](@ref events). - -To see all the properties of all connected joysticks in real-time, run the -`joysticks` test program. - - -@subsection joystick_axis Joystick axis states - -The positions of all axes of a joystick are returned by @ref -glfwGetJoystickAxes. See the reference documentation for the lifetime of the -returned array. - -@code -int count; -const float* axes = glfwGetJoystickAxes(GLFW_JOYSTICK_5, &count); -@endcode - -Each element in the returned array is a value between -1.0 and 1.0. - - -@subsection joystick_button Joystick button states - -The states of all buttons of a joystick are returned by @ref -glfwGetJoystickButtons. See the reference documentation for the lifetime of the -returned array. - -@code -int count; -const unsigned char* buttons = glfwGetJoystickButtons(GLFW_JOYSTICK_3, &count); -@endcode - -Each element in the returned array is either `GLFW_PRESS` or `GLFW_RELEASE`. - -For backward compatibility with earlier versions that did not have @ref -glfwGetJoystickHats, the button array by default also includes all hats. See -the reference documentation for @ref glfwGetJoystickButtons for details. - - -@subsection joystick_hat Joystick hat states - -The states of all hats are returned by @ref glfwGetJoystickHats. See the -reference documentation for the lifetime of the returned array. - -@code -int count; -const unsigned char* hats = glfwGetJoystickHats(GLFW_JOYSTICK_7, &count); -@endcode - -Each element in the returned array is one of the following: - -Name | Value ----- | ----- -`GLFW_HAT_CENTERED` | 0 -`GLFW_HAT_UP` | 1 -`GLFW_HAT_RIGHT` | 2 -`GLFW_HAT_DOWN` | 4 -`GLFW_HAT_LEFT` | 8 -`GLFW_HAT_RIGHT_UP` | `GLFW_HAT_RIGHT` \| `GLFW_HAT_UP` -`GLFW_HAT_RIGHT_DOWN` | `GLFW_HAT_RIGHT` \| `GLFW_HAT_DOWN` -`GLFW_HAT_LEFT_UP` | `GLFW_HAT_LEFT` \| `GLFW_HAT_UP` -`GLFW_HAT_LEFT_DOWN` | `GLFW_HAT_LEFT` \| `GLFW_HAT_DOWN` - -The diagonal directions are bitwise combinations of the primary (up, right, down -and left) directions and you can test for these individually by ANDing it with -the corresponding direction. - -@code -if (hats[2] & GLFW_HAT_RIGHT) -{ - // State of hat 2 could be right-up, right or right-down -} -@endcode - -For backward compatibility with earlier versions that did not have @ref -glfwGetJoystickHats, all hats are by default also included in the button array. -See the reference documentation for @ref glfwGetJoystickButtons for details. - - -@subsection joystick_name Joystick name - -The human-readable, UTF-8 encoded name of a joystick is returned by @ref -glfwGetJoystickName. See the reference documentation for the lifetime of the -returned string. - -@code -const char* name = glfwGetJoystickName(GLFW_JOYSTICK_4); -@endcode - -Joystick names are not guaranteed to be unique. Two joysticks of the same model -and make may have the same name. Only the [joystick ID](@ref joysticks) is -guaranteed to be unique, and only until that joystick is disconnected. - - -@subsection joystick_userptr Joystick user pointer - -Each joystick has a user pointer that can be set with @ref -glfwSetJoystickUserPointer and queried with @ref glfwGetJoystickUserPointer. -This can be used for any purpose you need and will not be modified by GLFW. The -value will be kept until the joystick is disconnected or until the library is -terminated. - -The initial value of the pointer is `NULL`. - - -@subsection joystick_event Joystick configuration changes - -If you wish to be notified when a joystick is connected or disconnected, set -a joystick callback. - -@code -glfwSetJoystickCallback(joystick_callback); -@endcode - -The callback function receives the ID of the joystick that has been connected -and disconnected and the event that occurred. - -@code -void joystick_callback(int jid, int event) -{ - if (event == GLFW_CONNECTED) - { - // The joystick was connected - } - else if (event == GLFW_DISCONNECTED) - { - // The joystick was disconnected - } -} -@endcode - -For joystick connection and disconnection events to be delivered on all -platforms, you need to call one of the [event processing](@ref events) -functions. Joystick disconnection may also be detected and the callback -called by joystick functions. The function will then return whatever it -returns for a disconnected joystick. - -Only @ref glfwGetJoystickName and @ref glfwGetJoystickUserPointer will return -useful values for a disconnected joystick and only before the monitor callback -returns. - - -@subsection gamepad Gamepad input - -The joystick functions provide unlabeled axes, buttons and hats, with no -indication of where they are located on the device. Their order may also vary -between platforms even with the same device. - -To solve this problem the SDL community crowdsourced the -[SDL_GameControllerDB](https://github.com/gabomdq/SDL_GameControllerDB) project, -a database of mappings from many different devices to an Xbox-like gamepad. - -GLFW supports this mapping format and contains a copy of the mappings -available at the time of release. See @ref gamepad_mapping for how to update -this at runtime. Mappings will be assigned to joysticks automatically any time -a joystick is connected or the mappings are updated. - -You can check whether a joystick is both present and has a gamepad mapping with -@ref glfwJoystickIsGamepad. - -@code -if (glfwJoystickIsGamepad(GLFW_JOYSTICK_2)) -{ - // Use as gamepad -} -@endcode - -If you are only interested in gamepad input you can use this function instead of -@ref glfwJoystickPresent. - -You can query the human-readable name provided by the gamepad mapping with @ref -glfwGetGamepadName. This may or may not be the same as the -[joystick name](@ref joystick_name). - -@code -const char* name = glfwGetGamepadName(GLFW_JOYSTICK_7); -@endcode - -To retrieve the gamepad state of a joystick, call @ref glfwGetGamepadState. - -@code -GLFWgamepadstate state; - -if (glfwGetGamepadState(GLFW_JOYSTICK_3, &state)) -{ - if (state.buttons[GLFW_GAMEPAD_BUTTON_A]) - { - input_jump(); - } - - input_speed(state.axes[GLFW_GAMEPAD_AXIS_RIGHT_TRIGGER]); -} -@endcode - -The @ref GLFWgamepadstate struct has two arrays; one for button states and one -for axis states. The values for each button and axis are the same as for the -@ref glfwGetJoystickButtons and @ref glfwGetJoystickAxes functions, i.e. -`GLFW_PRESS` or `GLFW_RELEASE` for buttons and -1.0 to 1.0 inclusive for axes. - -The sizes of the arrays and the positions within each array are fixed. - -The [button indices](@ref gamepad_buttons) are `GLFW_GAMEPAD_BUTTON_A`, -`GLFW_GAMEPAD_BUTTON_B`, `GLFW_GAMEPAD_BUTTON_X`, `GLFW_GAMEPAD_BUTTON_Y`, -`GLFW_GAMEPAD_BUTTON_LEFT_BUMPER`, `GLFW_GAMEPAD_BUTTON_RIGHT_BUMPER`, -`GLFW_GAMEPAD_BUTTON_BACK`, `GLFW_GAMEPAD_BUTTON_START`, -`GLFW_GAMEPAD_BUTTON_GUIDE`, `GLFW_GAMEPAD_BUTTON_LEFT_THUMB`, -`GLFW_GAMEPAD_BUTTON_RIGHT_THUMB`, `GLFW_GAMEPAD_BUTTON_DPAD_UP`, -`GLFW_GAMEPAD_BUTTON_DPAD_RIGHT`, `GLFW_GAMEPAD_BUTTON_DPAD_DOWN` and -`GLFW_GAMEPAD_BUTTON_DPAD_LEFT`. - -For those who prefer, there are also the `GLFW_GAMEPAD_BUTTON_CROSS`, -`GLFW_GAMEPAD_BUTTON_CIRCLE`, `GLFW_GAMEPAD_BUTTON_SQUARE` and -`GLFW_GAMEPAD_BUTTON_TRIANGLE` aliases for the A, B, X and Y button indices. - -The [axis indices](@ref gamepad_axes) are `GLFW_GAMEPAD_AXIS_LEFT_X`, -`GLFW_GAMEPAD_AXIS_LEFT_Y`, `GLFW_GAMEPAD_AXIS_RIGHT_X`, -`GLFW_GAMEPAD_AXIS_RIGHT_Y`, `GLFW_GAMEPAD_AXIS_LEFT_TRIGGER` and -`GLFW_GAMEPAD_AXIS_RIGHT_TRIGGER`. - -The `GLFW_GAMEPAD_BUTTON_LAST` and `GLFW_GAMEPAD_AXIS_LAST` constants equal -the largest available index for each array. - - -@subsection gamepad_mapping Gamepad mappings - -GLFW contains a copy of the mappings available in -[SDL_GameControllerDB](https://github.com/gabomdq/SDL_GameControllerDB) at the -time of release. Newer ones can be added at runtime with @ref -glfwUpdateGamepadMappings. - -@code -const char* mappings = load_file_contents("game/data/gamecontrollerdb.txt"); - -glfwUpdateGamepadMappings(mappings); -@endcode - -This function supports everything from single lines up to and including the -unmodified contents of the whole `gamecontrollerdb.txt` file. - -If you are compiling GLFW from source with CMake you can update the built-in mappings by -building the _update_mappings_ target. This runs the `GenerateMappings.cmake` CMake -script, which downloads `gamecontrollerdb.txt` and regenerates the `mappings.h` header -file. - -Below is a description of the mapping format. Please keep in mind that __this -description is not authoritative__. The format is defined by the SDL and -SDL_GameControllerDB projects and their documentation and code takes precedence. - -Each mapping is a single line of comma-separated values describing the GUID, -name and layout of the gamepad. Lines that do not begin with a hexadecimal -digit are ignored. - -The first value is always the gamepad GUID, a 32 character long hexadecimal -string that typically identifies its make, model, revision and the type of -connection to the computer. When this information is not available, the GUID is -generated using the gamepad name. GLFW uses the SDL 2.0.5+ GUID format but can -convert from the older formats. - -The second value is always the human-readable name of the gamepad. - -All subsequent values are in the form `<field>:<value>` and describe the layout -of the mapping. These fields may not all be present and may occur in any order. - -The button fields are `a`, `b`, `x`, `y`, `back`, `start`, `guide`, `dpup`, -`dpright`, `dpdown`, `dpleft`, `leftshoulder`, `rightshoulder`, `leftstick` and -`rightstick`. - -The axis fields are `leftx`, `lefty`, `rightx`, `righty`, `lefttrigger` and -`righttrigger`. - -The value of an axis or button field can be a joystick button, a joystick axis, -a hat bitmask or empty. Joystick buttons are specified as `bN`, for example -`b2` for the third button. Joystick axes are specified as `aN`, for example -`a7` for the eighth button. Joystick hat bit masks are specified as `hN.N`, for -example `h0.8` for left on the first hat. More than one bit may be set in the -mask. - -Before an axis there may be a `+` or `-` range modifier, for example `+a3` for -the positive half of the fourth axis. This restricts input to only the positive -or negative halves of the joystick axis. After an axis or half-axis there may -be the `~` inversion modifier, for example `a2~` or `-a7~`. This negates the -values of the gamepad axis. - -The hat bit mask match the [hat states](@ref hat_state) in the joystick -functions. - -There is also the special `platform` field that specifies which platform the -mapping is valid for. Possible values are `Windows`, `Mac OS X` and `Linux`. - -Below is an example of what a gamepad mapping might look like. It is the -one built into GLFW for Xbox controllers accessed via the XInput API on Windows. -This example has been broken into several lines to fit on the page, but real -gamepad mappings must be a single line. - -@code{.unparsed} -78696e70757401000000000000000000,XInput Gamepad (GLFW),platform:Windows,a:b0, -b:b1,x:b2,y:b3,leftshoulder:b4,rightshoulder:b5,back:b6,start:b7,leftstick:b8, -rightstick:b9,leftx:a0,lefty:a1,rightx:a2,righty:a3,lefttrigger:a4, -righttrigger:a5,dpup:h0.1,dpright:h0.2,dpdown:h0.4,dpleft:h0.8, -@endcode - -@note GLFW does not yet support the output range and modifiers `+` and `-` that -were recently added to SDL. The input modifiers `+`, `-` and `~` are supported -and described above. - - -@section time Time input - -GLFW provides high-resolution time input, in seconds, with @ref glfwGetTime. - -@code -double seconds = glfwGetTime(); -@endcode - -It returns the number of seconds since the library was initialized with @ref -glfwInit. The platform-specific time sources used typically have micro- or -nanosecond resolution. - -You can modify the base time with @ref glfwSetTime. - -@code -glfwSetTime(4.0); -@endcode - -This sets the time to the specified time, in seconds, and it continues to count -from there. - -You can also access the raw timer used to implement the functions above, -with @ref glfwGetTimerValue. - -@code -uint64_t value = glfwGetTimerValue(); -@endcode - -This value is in 1 / frequency seconds. The frequency of the raw -timer varies depending on the operating system and hardware. You can query the -frequency, in Hz, with @ref glfwGetTimerFrequency. - -@code -uint64_t frequency = glfwGetTimerFrequency(); -@endcode - - -@section clipboard Clipboard input and output - -If the system clipboard contains a UTF-8 encoded string or if it can be -converted to one, you can retrieve it with @ref glfwGetClipboardString. See the -reference documentation for the lifetime of the returned string. - -@code -const char* text = glfwGetClipboardString(NULL); -if (text) -{ - insert_text(text); -} -@endcode - -If the clipboard is empty or if its contents could not be converted, `NULL` is -returned. - -The contents of the system clipboard can be set to a UTF-8 encoded string with -@ref glfwSetClipboardString. - -@code -glfwSetClipboardString(NULL, "A string with words in it"); -@endcode - - -@section path_drop Path drop input - -If you wish to receive the paths of files and/or directories dropped on -a window, set a file drop callback. - -@code -glfwSetDropCallback(window, drop_callback); -@endcode - -The callback function receives an array of paths encoded as UTF-8. - -@code -void drop_callback(GLFWwindow* window, int count, const char** paths) -{ - int i; - for (i = 0; i < count; i++) - handle_dropped_file(paths[i]); -} -@endcode - -The path array and its strings are only valid until the file drop callback -returns, as they may have been generated specifically for that event. You need -to make a deep copy of the array if you want to keep the paths. - -*/ |