:wMerge branch 'gl-window' into main

1 files changed, 962 insertions, 0 deletions

diff --git a/libs/glfw-3.3.8/docs/input.dox b/libs/glfw-3.3.8/docs/input.dox
new file mode 100644
index 0000000..1d61e5b
--- /dev/null
+++ b/libs/glfw-3.3.8/docs/input.dox
@@ -0,0 +1,962 @@
+/*!
+
+@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`.  Events with
+`GLFW_PRESS` and `GLFW_RELEASE` actions are emitted for every key press.  Most
+keys will also emit events with `GLFW_REPEAT` actions while a key is held down.
+
+Key events with `GLFW_REPEAT` actions are intended for text input.  They are
+emitted at the rate set in the user's keyboard settings.  At most one key is
+repeated even if several keys are held down.  `GLFW_REPEAT` actions should not
+be relied on to know which keys are being held down or to drive animation.
+Instead you should either save the state of relevant keys based on `GLFW_PRESS`
+and `GLFW_RELEASE` actions, or call @ref glfwGetKey, which provides basic cached
+key state.
+
+The key will be one of the existing [key tokens](@ref keys), or
+`GLFW_KEY_UNKNOWN` if GLFW lacks a 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* cursor = glfwCreateStandardCursor(GLFW_HRESIZE_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.
+
+
+@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.
+
+When GLFW is initialized, 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&nbsp;/&nbsp;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.
+
+*/