libs/SDL2/i686-w64-mingw32/include/SDL2/SDL_gamecontroller.h

 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -31,6 +31,7 @@
 #include "SDL_stdinc.h"
 #include "SDL_error.h"
 #include "SDL_rwops.h"
+#include "SDL_sensor.h"
 #include "SDL_joystick.h"
 
 #include "begin_code.h"
@@ -57,6 +58,23 @@ extern "C" {
 struct _SDL_GameController;
 typedef struct _SDL_GameController SDL_GameController;
 
+typedef enum
+{
+    SDL_CONTROLLER_TYPE_UNKNOWN = 0,
+    SDL_CONTROLLER_TYPE_XBOX360,
+    SDL_CONTROLLER_TYPE_XBOXONE,
+    SDL_CONTROLLER_TYPE_PS3,
+    SDL_CONTROLLER_TYPE_PS4,
+    SDL_CONTROLLER_TYPE_NINTENDO_SWITCH_PRO,
+    SDL_CONTROLLER_TYPE_VIRTUAL,
+    SDL_CONTROLLER_TYPE_PS5,
+    SDL_CONTROLLER_TYPE_AMAZON_LUNA,
+    SDL_CONTROLLER_TYPE_GOOGLE_STADIA,
+    SDL_CONTROLLER_TYPE_NVIDIA_SHIELD,
+    SDL_CONTROLLER_TYPE_NINTENDO_SWITCH_JOYCON_LEFT,
+    SDL_CONTROLLER_TYPE_NINTENDO_SWITCH_JOYCON_RIGHT,
+    SDL_CONTROLLER_TYPE_NINTENDO_SWITCH_JOYCON_PAIR
+} SDL_GameControllerType;
 
 typedef enum
 {
@@ -87,6 +105,8 @@ typedef struct SDL_GameControllerButtonBind
 
 /**
  *  To count the number of game controllers in the system for the following:
+ *
+ *  ```c
  *  int nJoysticks = SDL_NumJoysticks();
  *  int nGameControllers = 0;
  *  for (int i = 0; i < nJoysticks; i++) {
@@ -94,6 +114,7 @@ typedef struct SDL_GameControllerButtonBind
  *          nGameControllers++;
  *      }
  *  }
+ *  ```
  *
  *  Using the SDL_HINT_GAMECONTROLLERCONFIG hint or the SDL_GameControllerAddMapping() you can add support for controllers SDL is unaware of or cause an existing controller to have a different binding. The format is:
  *  guid,name,mappings
@@ -107,17 +128,39 @@ typedef struct SDL_GameControllerButtonBind
  *  Buttons can be used as a controller axis and vice versa.
  *
  *  This string shows an example of a valid mapping for a controller
- *  "03000000341a00003608000000000000,PS3 Controller,a:b1,b:b2,y:b3,x:b0,start:b9,guide:b12,back:b8,dpup:h0.1,dpleft:h0.8,dpdown:h0.4,dpright:h0.2,leftshoulder:b4,rightshoulder:b5,leftstick:b10,rightstick:b11,leftx:a0,lefty:a1,rightx:a2,righty:a3,lefttrigger:b6,righttrigger:b7",
  *
+ * ```c
+ * "03000000341a00003608000000000000,PS3 Controller,a:b1,b:b2,y:b3,x:b0,start:b9,guide:b12,back:b8,dpup:h0.1,dpleft:h0.8,dpdown:h0.4,dpright:h0.2,leftshoulder:b4,rightshoulder:b5,leftstick:b10,rightstick:b11,leftx:a0,lefty:a1,rightx:a2,righty:a3,lefttrigger:b6,righttrigger:b7",
+ * ```
  */
 
 /**
- *  Load a set of mappings from a seekable SDL data stream (memory or file), filtered by the current SDL_GetPlatform()
- *  A community sourced database of controllers is available at https://raw.github.com/gabomdq/SDL_GameControllerDB/master/gamecontrollerdb.txt
+ * Load a set of Game Controller mappings from a seekable SDL data stream.
+ *
+ * You can call this function several times, if needed, to load different
+ * database files.
+ *
+ * If a new mapping is loaded for an already known controller GUID, the later
+ * version will overwrite the one currently loaded.
+ *
+ * Mappings not belonging to the current platform or with no platform field
+ * specified will be ignored (i.e. mappings for Linux will be ignored in
+ * Windows, etc).
+ *
+ * This function will load the text database entirely in memory before
+ * processing it, so take this into consideration if you are in a memory
+ * constrained environment.
+ *
+ * \param rw the data stream for the mappings to be added
+ * \param freerw non-zero to close the stream after being read
+ * \returns the number of mappings added or -1 on error; call SDL_GetError()
+ *          for more information.
  *
- *  If \c freerw is non-zero, the stream will be closed after being read.
- * 
- * \return number of mappings added, -1 on error
+ * \since This function is available since SDL 2.0.2.
+ *
+ * \sa SDL_GameControllerAddMapping
+ * \sa SDL_GameControllerAddMappingsFromFile
+ * \sa SDL_GameControllerMappingForGUID
  */
 extern DECLSPEC int SDLCALL SDL_GameControllerAddMappingsFromRW(SDL_RWops * rw, int freerw);
 
@@ -129,133 +172,421 @@ extern DECLSPEC int SDLCALL SDL_GameControllerAddMappingsFromRW(SDL_RWops * rw,
 #define SDL_GameControllerAddMappingsFromFile(file)   SDL_GameControllerAddMappingsFromRW(SDL_RWFromFile(file, "rb"), 1)
 
 /**
- *  Add or update an existing mapping configuration
+ * Add support for controllers that SDL is unaware of or to cause an existing
+ * controller to have a different binding.
+ *
+ * The mapping string has the format "GUID,name,mapping", where GUID is the
+ * string value from SDL_JoystickGetGUIDString(), name is the human readable
+ * string for the device and mappings are controller mappings to joystick
+ * ones. Under Windows there is a reserved GUID of "xinput" that covers all
+ * XInput devices. The mapping format for joystick is: {| |bX |a joystick
+ * button, index X |- |hX.Y |hat X with value Y |- |aX |axis X of the joystick
+ * |} Buttons can be used as a controller axes and vice versa.
+ *
+ * This string shows an example of a valid mapping for a controller:
+ *
+ * ```c
+ * "341a3608000000000000504944564944,Afterglow PS3 Controller,a:b1,b:b2,y:b3,x:b0,start:b9,guide:b12,back:b8,dpup:h0.1,dpleft:h0.8,dpdown:h0.4,dpright:h0.2,leftshoulder:b4,rightshoulder:b5,leftstick:b10,rightstick:b11,leftx:a0,lefty:a1,rightx:a2,righty:a3,lefttrigger:b6,righttrigger:b7"
+ * ```
  *
- * \return 1 if mapping is added, 0 if updated, -1 on error
+ * \param mappingString the mapping string
+ * \returns 1 if a new mapping is added, 0 if an existing mapping is updated,
+ *          -1 on error; call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerMapping
+ * \sa SDL_GameControllerMappingForGUID
  */
 extern DECLSPEC int SDLCALL SDL_GameControllerAddMapping(const char* mappingString);
 
 /**
- *  Get the number of mappings installed
+ * Get the number of mappings installed.
  *
- *  \return the number of mappings
+ * \returns the number of mappings.
+ *
+ * \since This function is available since SDL 2.0.6.
  */
 extern DECLSPEC int SDLCALL SDL_GameControllerNumMappings(void);
 
 /**
- *  Get the mapping at a particular index.
+ * Get the mapping at a particular index.
+ *
+ * \returns the mapping string. Must be freed with SDL_free(). Returns NULL if
+ *          the index is out of range.
  *
- *  \return the mapping string.  Must be freed with SDL_free().  Returns NULL if the index is out of range.
+ * \since This function is available since SDL 2.0.6.
  */
 extern DECLSPEC char * SDLCALL SDL_GameControllerMappingForIndex(int mapping_index);
 
 /**
- *  Get a mapping string for a GUID
+ * Get the game controller mapping string for a given GUID.
  *
- *  \return the mapping string.  Must be freed with SDL_free().  Returns NULL if no mapping is available
+ * The returned string must be freed with SDL_free().
+ *
+ * \param guid a structure containing the GUID for which a mapping is desired
+ * \returns a mapping string or NULL on error; call SDL_GetError() for more
+ *          information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_JoystickGetDeviceGUID
+ * \sa SDL_JoystickGetGUID
  */
 extern DECLSPEC char * SDLCALL SDL_GameControllerMappingForGUID(SDL_JoystickGUID guid);
 
 /**
- *  Get a mapping string for an open GameController
+ * Get the current mapping of a Game Controller.
+ *
+ * The returned string must be freed with SDL_free().
  *
- *  \return the mapping string.  Must be freed with SDL_free().  Returns NULL if no mapping is available
+ * Details about mappings are discussed with SDL_GameControllerAddMapping().
+ *
+ * \param gamecontroller the game controller you want to get the current
+ *                       mapping for
+ * \returns a string that has the controller's mapping or NULL if no mapping
+ *          is available; call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerAddMapping
+ * \sa SDL_GameControllerMappingForGUID
  */
-extern DECLSPEC char * SDLCALL SDL_GameControllerMapping(SDL_GameController * gamecontroller);
+extern DECLSPEC char * SDLCALL SDL_GameControllerMapping(SDL_GameController *gamecontroller);
 
 /**
- *  Is the joystick on this index supported by the game controller interface?
+ * Check if the given joystick is supported by the game controller interface.
+ *
+ * `joystick_index` is the same as the `device_index` passed to
+ * SDL_JoystickOpen().
+ *
+ * \param joystick_index the device_index of a device, up to
+ *                       SDL_NumJoysticks()
+ * \returns SDL_TRUE if the given joystick is supported by the game controller
+ *          interface, SDL_FALSE if it isn't or it's an invalid index.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerNameForIndex
+ * \sa SDL_GameControllerOpen
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_IsGameController(int joystick_index);
 
 /**
- *  Get the implementation dependent name of a game controller.
- *  This can be called before any controllers are opened.
- *  If no name can be found, this function returns NULL.
+ * Get the implementation dependent name for the game controller.
+ *
+ * This function can be called before any controllers are opened.
+ *
+ * `joystick_index` is the same as the `device_index` passed to
+ * SDL_JoystickOpen().
+ *
+ * \param joystick_index the device_index of a device, from zero to
+ *                       SDL_NumJoysticks()-1
+ * \returns the implementation-dependent name for the game controller, or NULL
+ *          if there is no name or the index is invalid.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerName
+ * \sa SDL_GameControllerOpen
+ * \sa SDL_IsGameController
  */
 extern DECLSPEC const char *SDLCALL SDL_GameControllerNameForIndex(int joystick_index);
 
 /**
- *  Get the mapping of a game controller.
- *  This can be called before any controllers are opened.
+ * Get the implementation dependent path for the game controller.
  *
- *  \return the mapping string.  Must be freed with SDL_free().  Returns NULL if no mapping is available
+ * This function can be called before any controllers are opened.
+ *
+ * `joystick_index` is the same as the `device_index` passed to
+ * SDL_JoystickOpen().
+ *
+ * \param joystick_index the device_index of a device, from zero to
+ *                       SDL_NumJoysticks()-1
+ * \returns the implementation-dependent path for the game controller, or NULL
+ *          if there is no path or the index is invalid.
+ *
+ * \since This function is available since SDL 2.24.0.
+ *
+ * \sa SDL_GameControllerPath
+ */
+extern DECLSPEC const char *SDLCALL SDL_GameControllerPathForIndex(int joystick_index);
+
+/**
+ * Get the type of a game controller.
+ *
+ * This can be called before any controllers are opened.
+ *
+ * \param joystick_index the device_index of a device, from zero to
+ *                       SDL_NumJoysticks()-1
+ * \returns the controller type.
+ *
+ * \since This function is available since SDL 2.0.12.
+ */
+extern DECLSPEC SDL_GameControllerType SDLCALL SDL_GameControllerTypeForIndex(int joystick_index);
+
+/**
+ * Get the mapping of a game controller.
+ *
+ * This can be called before any controllers are opened.
+ *
+ * \param joystick_index the device_index of a device, from zero to
+ *                       SDL_NumJoysticks()-1
+ * \returns the mapping string. Must be freed with SDL_free(). Returns NULL if
+ *          no mapping is available.
+ *
+ * \since This function is available since SDL 2.0.9.
  */
 extern DECLSPEC char *SDLCALL SDL_GameControllerMappingForDeviceIndex(int joystick_index);
 
 /**
- *  Open a game controller for use.
- *  The index passed as an argument refers to the N'th game controller on the system.
- *  This index is not the value which will identify this controller in future
- *  controller events.  The joystick's instance id (::SDL_JoystickID) will be
- *  used there instead.
+ * Open a game controller for use.
  *
- *  \return A controller identifier, or NULL if an error occurred.
+ * `joystick_index` is the same as the `device_index` passed to
+ * SDL_JoystickOpen().
+ *
+ * The index passed as an argument refers to the N'th game controller on the
+ * system. This index is not the value which will identify this controller in
+ * future controller events. The joystick's instance id (SDL_JoystickID) will
+ * be used there instead.
+ *
+ * \param joystick_index the device_index of a device, up to
+ *                       SDL_NumJoysticks()
+ * \returns a gamecontroller identifier or NULL if an error occurred; call
+ *          SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerClose
+ * \sa SDL_GameControllerNameForIndex
+ * \sa SDL_IsGameController
  */
 extern DECLSPEC SDL_GameController *SDLCALL SDL_GameControllerOpen(int joystick_index);
 
 /**
- * Return the SDL_GameController associated with an instance id.
+ * Get the SDL_GameController associated with an instance id.
+ *
+ * \param joyid the instance id to get the SDL_GameController for
+ * \returns an SDL_GameController on success or NULL on failure; call
+ *          SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.4.
  */
 extern DECLSPEC SDL_GameController *SDLCALL SDL_GameControllerFromInstanceID(SDL_JoystickID joyid);
 
 /**
- *  Return the name for this currently opened controller
+ * Get the SDL_GameController associated with a player index.
+ *
+ * Please note that the player index is _not_ the device index, nor is it the
+ * instance id!
+ *
+ * \param player_index the player index, which is not the device index or the
+ *                     instance id!
+ * \returns the SDL_GameController associated with a player index.
+ *
+ * \since This function is available since SDL 2.0.12.
+ *
+ * \sa SDL_GameControllerGetPlayerIndex
+ * \sa SDL_GameControllerSetPlayerIndex
+ */
+extern DECLSPEC SDL_GameController *SDLCALL SDL_GameControllerFromPlayerIndex(int player_index);
+
+/**
+ * Get the implementation-dependent name for an opened game controller.
+ *
+ * This is the same name as returned by SDL_GameControllerNameForIndex(), but
+ * it takes a controller identifier instead of the (unstable) device index.
+ *
+ * \param gamecontroller a game controller identifier previously returned by
+ *                       SDL_GameControllerOpen()
+ * \returns the implementation dependent name for the game controller, or NULL
+ *          if there is no name or the identifier passed is invalid.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerNameForIndex
+ * \sa SDL_GameControllerOpen
  */
 extern DECLSPEC const char *SDLCALL SDL_GameControllerName(SDL_GameController *gamecontroller);
 
 /**
- *  Get the player index of an opened game controller, or -1 if it's not available
+ * Get the implementation-dependent path for an opened game controller.
+ *
+ * This is the same path as returned by SDL_GameControllerNameForIndex(), but
+ * it takes a controller identifier instead of the (unstable) device index.
+ *
+ * \param gamecontroller a game controller identifier previously returned by
+ *                       SDL_GameControllerOpen()
+ * \returns the implementation dependent path for the game controller, or NULL
+ *          if there is no path or the identifier passed is invalid.
+ *
+ * \since This function is available since SDL 2.24.0.
+ *
+ * \sa SDL_GameControllerPathForIndex
+ */
+extern DECLSPEC const char *SDLCALL SDL_GameControllerPath(SDL_GameController *gamecontroller);
+
+/**
+ * Get the type of this currently opened controller
+ *
+ * This is the same name as returned by SDL_GameControllerTypeForIndex(), but
+ * it takes a controller identifier instead of the (unstable) device index.
+ *
+ * \param gamecontroller the game controller object to query.
+ * \returns the controller type.
+ *
+ * \since This function is available since SDL 2.0.12.
+ */
+extern DECLSPEC SDL_GameControllerType SDLCALL SDL_GameControllerGetType(SDL_GameController *gamecontroller);
+
+/**
+ * Get the player index of an opened game controller.
+ *
+ * For XInput controllers this returns the XInput user index.
  *
- *  For XInput controllers this returns the XInput user index.
+ * \param gamecontroller the game controller object to query.
+ * \returns the player index for controller, or -1 if it's not available.
+ *
+ * \since This function is available since SDL 2.0.9.
  */
 extern DECLSPEC int SDLCALL SDL_GameControllerGetPlayerIndex(SDL_GameController *gamecontroller);
 
 /**
- *  Get the USB vendor ID of an opened controller, if available.
- *  If the vendor ID isn't available this function returns 0.
+ * Set the player index of an opened game controller.
+ *
+ * \param gamecontroller the game controller object to adjust.
+ * \param player_index Player index to assign to this controller, or -1 to
+ *                     clear the player index and turn off player LEDs.
+ *
+ * \since This function is available since SDL 2.0.12.
  */
-extern DECLSPEC Uint16 SDLCALL SDL_GameControllerGetVendor(SDL_GameController * gamecontroller);
+extern DECLSPEC void SDLCALL SDL_GameControllerSetPlayerIndex(SDL_GameController *gamecontroller, int player_index);
 
 /**
- *  Get the USB product ID of an opened controller, if available.
- *  If the product ID isn't available this function returns 0.
+ * Get the USB vendor ID of an opened controller, if available.
+ *
+ * If the vendor ID isn't available this function returns 0.
+ *
+ * \param gamecontroller the game controller object to query.
+ * \return the USB vendor ID, or zero if unavailable.
+ *
+ * \since This function is available since SDL 2.0.6.
  */
-extern DECLSPEC Uint16 SDLCALL SDL_GameControllerGetProduct(SDL_GameController * gamecontroller);
+extern DECLSPEC Uint16 SDLCALL SDL_GameControllerGetVendor(SDL_GameController *gamecontroller);
 
 /**
- *  Get the product version of an opened controller, if available.
- *  If the product version isn't available this function returns 0.
+ * Get the USB product ID of an opened controller, if available.
+ *
+ * If the product ID isn't available this function returns 0.
+ *
+ * \param gamecontroller the game controller object to query.
+ * \return the USB product ID, or zero if unavailable.
+ *
+ * \since This function is available since SDL 2.0.6.
  */
-extern DECLSPEC Uint16 SDLCALL SDL_GameControllerGetProductVersion(SDL_GameController * gamecontroller);
+extern DECLSPEC Uint16 SDLCALL SDL_GameControllerGetProduct(SDL_GameController *gamecontroller);
 
 /**
- *  Returns SDL_TRUE if the controller has been opened and currently connected,
- *  or SDL_FALSE if it has not.
+ * Get the product version of an opened controller, if available.
+ *
+ * If the product version isn't available this function returns 0.
+ *
+ * \param gamecontroller the game controller object to query.
+ * \return the USB product version, or zero if unavailable.
+ *
+ * \since This function is available since SDL 2.0.6.
+ */
+extern DECLSPEC Uint16 SDLCALL SDL_GameControllerGetProductVersion(SDL_GameController *gamecontroller);
+
+/**
+ * Get the firmware version of an opened controller, if available.
+ *
+ * If the firmware version isn't available this function returns 0.
+ *
+ * \param gamecontroller the game controller object to query.
+ * \return the controller firmware version, or zero if unavailable.
+ *
+ * \since This function is available since SDL 2.24.0.
+ */
+extern DECLSPEC Uint16 SDLCALL SDL_GameControllerGetFirmwareVersion(SDL_GameController *gamecontroller);
+
+/**
+ * Get the serial number of an opened controller, if available.
+ *
+ * Returns the serial number of the controller, or NULL if it is not
+ * available.
+ *
+ * \param gamecontroller the game controller object to query.
+ * \return the serial number, or NULL if unavailable.
+ *
+ * \since This function is available since SDL 2.0.14.
+ */
+extern DECLSPEC const char * SDLCALL SDL_GameControllerGetSerial(SDL_GameController *gamecontroller);
+
+/**
+ * Check if a controller has been opened and is currently connected.
+ *
+ * \param gamecontroller a game controller identifier previously returned by
+ *                       SDL_GameControllerOpen()
+ * \returns SDL_TRUE if the controller has been opened and is currently
+ *          connected, or SDL_FALSE if not.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerClose
+ * \sa SDL_GameControllerOpen
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerGetAttached(SDL_GameController *gamecontroller);
 
 /**
- *  Get the underlying joystick object used by a controller
+ * Get the Joystick ID from a Game Controller.
+ *
+ * This function will give you a SDL_Joystick object, which allows you to use
+ * the SDL_Joystick functions with a SDL_GameController object. This would be
+ * useful for getting a joystick's position at any given time, even if it
+ * hasn't moved (moving it would produce an event, which would have the axis'
+ * value).
+ *
+ * The pointer returned is owned by the SDL_GameController. You should not
+ * call SDL_JoystickClose() on it, for example, since doing so will likely
+ * cause SDL to crash.
+ *
+ * \param gamecontroller the game controller object that you want to get a
+ *                       joystick from
+ * \returns a SDL_Joystick object; call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
  */
 extern DECLSPEC SDL_Joystick *SDLCALL SDL_GameControllerGetJoystick(SDL_GameController *gamecontroller);
 
 /**
- *  Enable/disable controller event polling.
+ * Query or change current state of Game Controller events.
+ *
+ * If controller events are disabled, you must call SDL_GameControllerUpdate()
+ * yourself and check the state of the controller when you want controller
+ * information.
+ *
+ * Any number can be passed to SDL_GameControllerEventState(), but only -1, 0,
+ * and 1 will have any effect. Other numbers will just be returned.
  *
- *  If controller events are disabled, you must call SDL_GameControllerUpdate()
- *  yourself and check the state of the controller when you want controller
- *  information.
+ * \param state can be one of `SDL_QUERY`, `SDL_IGNORE`, or `SDL_ENABLE`
+ * \returns the same value passed to the function, with exception to -1
+ *          (SDL_QUERY), which will return the current state.
  *
- *  The state can be one of ::SDL_QUERY, ::SDL_ENABLE or ::SDL_IGNORE.
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_JoystickEventState
  */
 extern DECLSPEC int SDLCALL SDL_GameControllerEventState(int state);
 
 /**
- *  Update the current state of the open game controllers.
+ * Manually pump game controller updates if not using the loop.
+ *
+ * This function is called automatically by the event loop if events are
+ * enabled. Under such circumstances, it will not be necessary to call this
+ * function.
  *
- *  This is called automatically by the event loop if any game controller
- *  events are enabled.
+ * \since This function is available since SDL 2.0.0.
  */
 extern DECLSPEC void SDLCALL SDL_GameControllerUpdate(void);
 
@@ -282,33 +613,94 @@ typedef enum
 } SDL_GameControllerAxis;
 
 /**
- *  turn this string into a axis mapping
+ * Convert a string into SDL_GameControllerAxis enum.
+ *
+ * This function is called internally to translate SDL_GameController mapping
+ * strings for the underlying joystick device into the consistent
+ * SDL_GameController mapping. You do not normally need to call this function
+ * unless you are parsing SDL_GameController mappings in your own code.
+ *
+ * Note specially that "righttrigger" and "lefttrigger" map to
+ * `SDL_CONTROLLER_AXIS_TRIGGERRIGHT` and `SDL_CONTROLLER_AXIS_TRIGGERLEFT`,
+ * respectively.
+ *
+ * \param str string representing a SDL_GameController axis
+ * \returns the SDL_GameControllerAxis enum corresponding to the input string,
+ *          or `SDL_CONTROLLER_AXIS_INVALID` if no match was found.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerGetStringForAxis
  */
-extern DECLSPEC SDL_GameControllerAxis SDLCALL SDL_GameControllerGetAxisFromString(const char *pchString);
+extern DECLSPEC SDL_GameControllerAxis SDLCALL SDL_GameControllerGetAxisFromString(const char *str);
 
 /**
- *  turn this axis enum into a string mapping
+ * Convert from an SDL_GameControllerAxis enum to a string.
+ *
+ * The caller should not SDL_free() the returned string.
+ *
+ * \param axis an enum value for a given SDL_GameControllerAxis
+ * \returns a string for the given axis, or NULL if an invalid axis is
+ *          specified. The string returned is of the format used by
+ *          SDL_GameController mapping strings.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerGetAxisFromString
  */
 extern DECLSPEC const char* SDLCALL SDL_GameControllerGetStringForAxis(SDL_GameControllerAxis axis);
 
 /**
- *  Get the SDL joystick layer binding for this controller button mapping
+ * Get the SDL joystick layer binding for a controller axis mapping.
+ *
+ * \param gamecontroller a game controller
+ * \param axis an axis enum value (one of the SDL_GameControllerAxis values)
+ * \returns a SDL_GameControllerButtonBind describing the bind. On failure
+ *          (like the given Controller axis doesn't exist on the device), its
+ *          `.bindType` will be `SDL_CONTROLLER_BINDTYPE_NONE`.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerGetBindForButton
  */
 extern DECLSPEC SDL_GameControllerButtonBind SDLCALL
 SDL_GameControllerGetBindForAxis(SDL_GameController *gamecontroller,
                                  SDL_GameControllerAxis axis);
 
 /**
- *  Get the current state of an axis control on a game controller.
+ * Query whether a game controller has a given axis.
+ *
+ * This merely reports whether the controller's mapping defined this axis, as
+ * that is all the information SDL has about the physical device.
+ *
+ * \param gamecontroller a game controller
+ * \param axis an axis enum value (an SDL_GameControllerAxis value)
+ * \returns SDL_TRUE if the controller has this axis, SDL_FALSE otherwise.
+ *
+ * \since This function is available since SDL 2.0.14.
+ */
+extern DECLSPEC SDL_bool SDLCALL
+SDL_GameControllerHasAxis(SDL_GameController *gamecontroller, SDL_GameControllerAxis axis);
+
+/**
+ * Get the current state of an axis control on a game controller.
+ *
+ * The axis indices start at index 0.
+ *
+ * The state is a value ranging from -32768 to 32767. Triggers, however, range
+ * from 0 to 32767 (they never return a negative value).
+ *
+ * \param gamecontroller a game controller
+ * \param axis an axis index (one of the SDL_GameControllerAxis values)
+ * \returns axis state (including 0) on success or 0 (also) on failure; call
+ *          SDL_GetError() for more information.
  *
- *  The state is a value ranging from -32768 to 32767 (except for the triggers,
- *  which range from 0 to 32767).
+ * \since This function is available since SDL 2.0.0.
  *
- *  The axis indices start at index 0.
+ * \sa SDL_GameControllerGetButton
  */
 extern DECLSPEC Sint16 SDLCALL
-SDL_GameControllerGetAxis(SDL_GameController *gamecontroller,
-                          SDL_GameControllerAxis axis);
+SDL_GameControllerGetAxis(SDL_GameController *gamecontroller, SDL_GameControllerAxis axis);
 
 /**
  *  The list of buttons available from a controller
@@ -331,53 +723,345 @@ typedef enum
     SDL_CONTROLLER_BUTTON_DPAD_DOWN,
     SDL_CONTROLLER_BUTTON_DPAD_LEFT,
     SDL_CONTROLLER_BUTTON_DPAD_RIGHT,
+    SDL_CONTROLLER_BUTTON_MISC1,    /* Xbox Series X share button, PS5 microphone button, Nintendo Switch Pro capture button, Amazon Luna microphone button */
+    SDL_CONTROLLER_BUTTON_PADDLE1,  /* Xbox Elite paddle P1 (upper left, facing the back) */
+    SDL_CONTROLLER_BUTTON_PADDLE2,  /* Xbox Elite paddle P3 (upper right, facing the back) */
+    SDL_CONTROLLER_BUTTON_PADDLE3,  /* Xbox Elite paddle P2 (lower left, facing the back) */
+    SDL_CONTROLLER_BUTTON_PADDLE4,  /* Xbox Elite paddle P4 (lower right, facing the back) */
+    SDL_CONTROLLER_BUTTON_TOUCHPAD, /* PS4/PS5 touchpad button */
     SDL_CONTROLLER_BUTTON_MAX
 } SDL_GameControllerButton;
 
 /**
- *  turn this string into a button mapping
+ * Convert a string into an SDL_GameControllerButton enum.
+ *
+ * This function is called internally to translate SDL_GameController mapping
+ * strings for the underlying joystick device into the consistent
+ * SDL_GameController mapping. You do not normally need to call this function
+ * unless you are parsing SDL_GameController mappings in your own code.
+ *
+ * \param str string representing a SDL_GameController axis
+ * \returns the SDL_GameControllerButton enum corresponding to the input
+ *          string, or `SDL_CONTROLLER_AXIS_INVALID` if no match was found.
+ *
+ * \since This function is available since SDL 2.0.0.
  */
-extern DECLSPEC SDL_GameControllerButton SDLCALL SDL_GameControllerGetButtonFromString(const char *pchString);
+extern DECLSPEC SDL_GameControllerButton SDLCALL SDL_GameControllerGetButtonFromString(const char *str);
 
 /**
- *  turn this button enum into a string mapping
+ * Convert from an SDL_GameControllerButton enum to a string.
+ *
+ * The caller should not SDL_free() the returned string.
+ *
+ * \param button an enum value for a given SDL_GameControllerButton
+ * \returns a string for the given button, or NULL if an invalid button is
+ *          specified. The string returned is of the format used by
+ *          SDL_GameController mapping strings.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerGetButtonFromString
  */
 extern DECLSPEC const char* SDLCALL SDL_GameControllerGetStringForButton(SDL_GameControllerButton button);
 
 /**
- *  Get the SDL joystick layer binding for this controller button mapping
+ * Get the SDL joystick layer binding for a controller button mapping.
+ *
+ * \param gamecontroller a game controller
+ * \param button an button enum value (an SDL_GameControllerButton value)
+ * \returns a SDL_GameControllerButtonBind describing the bind. On failure
+ *          (like the given Controller button doesn't exist on the device),
+ *          its `.bindType` will be `SDL_CONTROLLER_BINDTYPE_NONE`.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerGetBindForAxis
  */
 extern DECLSPEC SDL_GameControllerButtonBind SDLCALL
 SDL_GameControllerGetBindForButton(SDL_GameController *gamecontroller,
                                    SDL_GameControllerButton button);
 
+/**
+ * Query whether a game controller has a given button.
+ *
+ * This merely reports whether the controller's mapping defined this button,
+ * as that is all the information SDL has about the physical device.
+ *
+ * \param gamecontroller a game controller
+ * \param button a button enum value (an SDL_GameControllerButton value)
+ * \returns SDL_TRUE if the controller has this button, SDL_FALSE otherwise.
+ *
+ * \since This function is available since SDL 2.0.14.
+ */
+extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasButton(SDL_GameController *gamecontroller,
+                                                             SDL_GameControllerButton button);
 
 /**
- *  Get the current state of a button on a game controller.
+ * Get the current state of a button on a game controller.
+ *
+ * \param gamecontroller a game controller
+ * \param button a button index (one of the SDL_GameControllerButton values)
+ * \returns 1 for pressed state or 0 for not pressed state or error; call
+ *          SDL_GetError() for more information.
  *
- *  The button indices start at index 0.
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerGetAxis
  */
 extern DECLSPEC Uint8 SDLCALL SDL_GameControllerGetButton(SDL_GameController *gamecontroller,
                                                           SDL_GameControllerButton button);
 
 /**
- *  Trigger a rumble effect
- *  Each call to this function cancels any previous rumble effect, and calling it with 0 intensity stops any rumbling.
+ * Get the number of touchpads on a game controller.
  *
- *  \param gamecontroller The controller to vibrate
- *  \param low_frequency_rumble The intensity of the low frequency (left) rumble motor, from 0 to 0xFFFF
- *  \param high_frequency_rumble The intensity of the high frequency (right) rumble motor, from 0 to 0xFFFF
- *  \param duration_ms The duration of the rumble effect, in milliseconds
+ * \since This function is available since SDL 2.0.14.
+ */
+extern DECLSPEC int SDLCALL SDL_GameControllerGetNumTouchpads(SDL_GameController *gamecontroller);
+
+/**
+ * Get the number of supported simultaneous fingers on a touchpad on a game
+ * controller.
  *
- *  \return 0, or -1 if rumble isn't supported on this joystick
+ * \since This function is available since SDL 2.0.14.
+ */
+extern DECLSPEC int SDLCALL SDL_GameControllerGetNumTouchpadFingers(SDL_GameController *gamecontroller, int touchpad);
+
+/**
+ * Get the current state of a finger on a touchpad on a game controller.
+ *
+ * \since This function is available since SDL 2.0.14.
+ */
+extern DECLSPEC int SDLCALL SDL_GameControllerGetTouchpadFinger(SDL_GameController *gamecontroller, int touchpad, int finger, Uint8 *state, float *x, float *y, float *pressure);
+
+/**
+ * Return whether a game controller has a particular sensor.
+ *
+ * \param gamecontroller The controller to query
+ * \param type The type of sensor to query
+ * \returns SDL_TRUE if the sensor exists, SDL_FALSE otherwise.
+ *
+ * \since This function is available since SDL 2.0.14.
+ */
+extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasSensor(SDL_GameController *gamecontroller, SDL_SensorType type);
+
+/**
+ * Set whether data reporting for a game controller sensor is enabled.
+ *
+ * \param gamecontroller The controller to update
+ * \param type The type of sensor to enable/disable
+ * \param enabled Whether data reporting should be enabled
+ * \returns 0 or -1 if an error occurred.
+ *
+ * \since This function is available since SDL 2.0.14.
+ */
+extern DECLSPEC int SDLCALL SDL_GameControllerSetSensorEnabled(SDL_GameController *gamecontroller, SDL_SensorType type, SDL_bool enabled);
+
+/**
+ * Query whether sensor data reporting is enabled for a game controller.
+ *
+ * \param gamecontroller The controller to query
+ * \param type The type of sensor to query
+ * \returns SDL_TRUE if the sensor is enabled, SDL_FALSE otherwise.
+ *
+ * \since This function is available since SDL 2.0.14.
+ */
+extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerIsSensorEnabled(SDL_GameController *gamecontroller, SDL_SensorType type);
+
+/**
+ * Get the data rate (number of events per second) of a game controller
+ * sensor.
+ *
+ * \param gamecontroller The controller to query
+ * \param type The type of sensor to query
+ * \return the data rate, or 0.0f if the data rate is not available.
+ *
+ * \since This function is available since SDL 2.0.16.
+ */
+extern DECLSPEC float SDLCALL SDL_GameControllerGetSensorDataRate(SDL_GameController *gamecontroller, SDL_SensorType type);
+
+/**
+ * Get the current state of a game controller sensor.
+ *
+ * The number of values and interpretation of the data is sensor dependent.
+ * See SDL_sensor.h for the details for each type of sensor.
+ *
+ * \param gamecontroller The controller to query
+ * \param type The type of sensor to query
+ * \param data A pointer filled with the current sensor state
+ * \param num_values The number of values to write to data
+ * \return 0 or -1 if an error occurred.
+ *
+ * \since This function is available since SDL 2.0.14.
+ */
+extern DECLSPEC int SDLCALL SDL_GameControllerGetSensorData(SDL_GameController *gamecontroller, SDL_SensorType type, float *data, int num_values);
+
+/**
+ * Get the current state of a game controller sensor with the timestamp of the
+ * last update.
+ *
+ * The number of values and interpretation of the data is sensor dependent.
+ * See SDL_sensor.h for the details for each type of sensor.
+ *
+ * \param gamecontroller The controller to query
+ * \param type The type of sensor to query
+ * \param timestamp A pointer filled with the timestamp in microseconds of the
+ *                  current sensor reading if available, or 0 if not
+ * \param data A pointer filled with the current sensor state
+ * \param num_values The number of values to write to data
+ * \return 0 or -1 if an error occurred.
+ *
+ * \since This function is available since SDL 2.26.0.
+ */
+extern DECLSPEC int SDLCALL SDL_GameControllerGetSensorDataWithTimestamp(SDL_GameController *gamecontroller, SDL_SensorType type, Uint64 *timestamp, float *data, int num_values);
+
+/**
+ * Start a rumble effect on a game controller.
+ *
+ * Each call to this function cancels any previous rumble effect, and calling
+ * it with 0 intensity stops any rumbling.
+ *
+ * \param gamecontroller The controller to vibrate
+ * \param low_frequency_rumble The intensity of the low frequency (left)
+ *                             rumble motor, from 0 to 0xFFFF
+ * \param high_frequency_rumble The intensity of the high frequency (right)
+ *                              rumble motor, from 0 to 0xFFFF
+ * \param duration_ms The duration of the rumble effect, in milliseconds
+ * \returns 0, or -1 if rumble isn't supported on this controller
+ *
+ * \since This function is available since SDL 2.0.9.
+ *
+ * \sa SDL_GameControllerHasRumble
  */
 extern DECLSPEC int SDLCALL SDL_GameControllerRumble(SDL_GameController *gamecontroller, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms);
 
 /**
- *  Close a controller previously opened with SDL_GameControllerOpen().
+ * Start a rumble effect in the game controller's triggers.
+ *
+ * Each call to this function cancels any previous trigger rumble effect, and
+ * calling it with 0 intensity stops any rumbling.
+ *
+ * Note that this is rumbling of the _triggers_ and not the game controller as
+ * a whole. This is currently only supported on Xbox One controllers. If you
+ * want the (more common) whole-controller rumble, use
+ * SDL_GameControllerRumble() instead.
+ *
+ * \param gamecontroller The controller to vibrate
+ * \param left_rumble The intensity of the left trigger rumble motor, from 0
+ *                    to 0xFFFF
+ * \param right_rumble The intensity of the right trigger rumble motor, from 0
+ *                     to 0xFFFF
+ * \param duration_ms The duration of the rumble effect, in milliseconds
+ * \returns 0, or -1 if trigger rumble isn't supported on this controller
+ *
+ * \since This function is available since SDL 2.0.14.
+ *
+ * \sa SDL_GameControllerHasRumbleTriggers
+ */
+extern DECLSPEC int SDLCALL SDL_GameControllerRumbleTriggers(SDL_GameController *gamecontroller, Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms);
+
+/**
+ * Query whether a game controller has an LED.
+ *
+ * \param gamecontroller The controller to query
+ * \returns SDL_TRUE, or SDL_FALSE if this controller does not have a
+ *          modifiable LED
+ *
+ * \since This function is available since SDL 2.0.14.
+ */
+extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasLED(SDL_GameController *gamecontroller);
+
+/**
+ * Query whether a game controller has rumble support.
+ *
+ * \param gamecontroller The controller to query
+ * \returns SDL_TRUE, or SDL_FALSE if this controller does not have rumble
+ *          support
+ *
+ * \since This function is available since SDL 2.0.18.
+ *
+ * \sa SDL_GameControllerRumble
+ */
+extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasRumble(SDL_GameController *gamecontroller);
+
+/**
+ * Query whether a game controller has rumble support on triggers.
+ *
+ * \param gamecontroller The controller to query
+ * \returns SDL_TRUE, or SDL_FALSE if this controller does not have trigger
+ *          rumble support
+ *
+ * \since This function is available since SDL 2.0.18.
+ *
+ * \sa SDL_GameControllerRumbleTriggers
+ */
+extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasRumbleTriggers(SDL_GameController *gamecontroller);
+
+/**
+ * Update a game controller's LED color.
+ *
+ * \param gamecontroller The controller to update
+ * \param red The intensity of the red LED
+ * \param green The intensity of the green LED
+ * \param blue The intensity of the blue LED
+ * \returns 0, or -1 if this controller does not have a modifiable LED
+ *
+ * \since This function is available since SDL 2.0.14.
+ */
+extern DECLSPEC int SDLCALL SDL_GameControllerSetLED(SDL_GameController *gamecontroller, Uint8 red, Uint8 green, Uint8 blue);
+
+/**
+ * Send a controller specific effect packet
+ *
+ * \param gamecontroller The controller to affect
+ * \param data The data to send to the controller
+ * \param size The size of the data to send to the controller
+ * \returns 0, or -1 if this controller or driver doesn't support effect
+ *          packets
+ *
+ * \since This function is available since SDL 2.0.16.
+ */
+extern DECLSPEC int SDLCALL SDL_GameControllerSendEffect(SDL_GameController *gamecontroller, const void *data, int size);
+
+/**
+ * Close a game controller previously opened with SDL_GameControllerOpen().
+ *
+ * \param gamecontroller a game controller identifier previously returned by
+ *                       SDL_GameControllerOpen()
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerOpen
  */
 extern DECLSPEC void SDLCALL SDL_GameControllerClose(SDL_GameController *gamecontroller);
 
+/**
+ * Return the sfSymbolsName for a given button on a game controller on Apple
+ * platforms.
+ *
+ * \param gamecontroller the controller to query
+ * \param button a button on the game controller
+ * \returns the sfSymbolsName or NULL if the name can't be found
+ *
+ * \since This function is available since SDL 2.0.18.
+ *
+ * \sa SDL_GameControllerGetAppleSFSymbolsNameForAxis
+ */
+extern DECLSPEC const char* SDLCALL SDL_GameControllerGetAppleSFSymbolsNameForButton(SDL_GameController *gamecontroller, SDL_GameControllerButton button);
+
+/**
+ * Return the sfSymbolsName for a given axis on a game controller on Apple
+ * platforms.
+ *
+ * \param gamecontroller the controller to query
+ * \param axis an axis on the game controller
+ * \returns the sfSymbolsName or NULL if the name can't be found
+ *
+ * \since This function is available since SDL 2.0.18.
+ *
+ * \sa SDL_GameControllerGetAppleSFSymbolsNameForButton
+ */
+extern DECLSPEC const char* SDLCALL SDL_GameControllerGetAppleSFSymbolsNameForAxis(SDL_GameController *gamecontroller, SDL_GameControllerAxis axis);
+
 
 /* Ends C function definitions when using C++ */
 #ifdef __cplusplus

libs/SDL2/i686-w64-mingw32/include/SDL2/SDL_gesture.h

 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -46,36 +46,66 @@ typedef Sint64 SDL_GestureID;
 /* Function prototypes */
 
 /**
- *  \brief Begin Recording a gesture on the specified touch, or all touches (-1)
+ * Begin recording a gesture on a specified touch device or all touch devices.
  *
+ * If the parameter `touchId` is -1 (i.e., all devices), this function will
+ * always return 1, regardless of whether there actually are any devices.
  *
+ * \param touchId the touch device id, or -1 for all touch devices
+ * \returns 1 on success or 0 if the specified device could not be found.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetTouchDevice
  */
 extern DECLSPEC int SDLCALL SDL_RecordGesture(SDL_TouchID touchId);
 
 
 /**
- *  \brief Save all currently loaded Dollar Gesture templates
+ * Save all currently loaded Dollar Gesture templates.
+ *
+ * \param dst a SDL_RWops to save to
+ * \returns the number of saved templates on success or 0 on failure; call
+ *          SDL_GetError() for more information.
  *
+ * \since This function is available since SDL 2.0.0.
  *
+ * \sa SDL_LoadDollarTemplates
+ * \sa SDL_SaveDollarTemplate
  */
 extern DECLSPEC int SDLCALL SDL_SaveAllDollarTemplates(SDL_RWops *dst);
 
 /**
- *  \brief Save a currently loaded Dollar Gesture template
+ * Save a currently loaded Dollar Gesture template.
  *
+ * \param gestureId a gesture id
+ * \param dst a SDL_RWops to save to
+ * \returns 1 on success or 0 on failure; call SDL_GetError() for more
+ *          information.
  *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_LoadDollarTemplates
+ * \sa SDL_SaveAllDollarTemplates
  */
 extern DECLSPEC int SDLCALL SDL_SaveDollarTemplate(SDL_GestureID gestureId,SDL_RWops *dst);
 
 
 /**
- *  \brief Load Dollar Gesture templates from a file
+ * Load Dollar Gesture templates from a file.
+ *
+ * \param touchId a touch id
+ * \param src a SDL_RWops to load from
+ * \returns the number of loaded templates on success or a negative error code
+ *          (or 0) on failure; call SDL_GetError() for more information.
  *
+ * \since This function is available since SDL 2.0.0.
  *
+ * \sa SDL_SaveAllDollarTemplates
+ * \sa SDL_SaveDollarTemplate
  */
 extern DECLSPEC int SDLCALL SDL_LoadDollarTemplates(SDL_TouchID touchId, SDL_RWops *src);
 
-
 /* Ends C function definitions when using C++ */
 #ifdef __cplusplus
 }

libs/SDL2/i686-w64-mingw32/include/SDL2/SDL_guid.h

+/*
+  Simple DirectMedia Layer
+  Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
+
+  This software is provided 'as-is', without any express or implied
+  warranty.  In no event will the authors be held liable for any damages
+  arising from the use of this software.
+
+  Permission is granted to anyone to use this software for any purpose,
+  including commercial applications, and to alter it and redistribute it
+  freely, subject to the following restrictions:
+
+  1. The origin of this software must not be misrepresented; you must not
+     claim that you wrote the original software. If you use this software
+     in a product, an acknowledgment in the product documentation would be
+     appreciated but is not required.
+  2. Altered source versions must be plainly marked as such, and must not be
+     misrepresented as being the original software.
+  3. This notice may not be removed or altered from any source distribution.
+*/
+
+/**
+ *  \file SDL_guid.h
+ *
+ *  Include file for handling ::SDL_GUID values.
+ */
+
+#ifndef SDL_guid_h_
+#define SDL_guid_h_
+
+#include "SDL_stdinc.h"
+#include "SDL_error.h"
+
+#include "begin_code.h"
+/* Set up for C function definitions, even when using C++ */
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * An SDL_GUID is a 128-bit identifier for an input device that
+ *   identifies that device across runs of SDL programs on the same
+ *   platform.  If the device is detached and then re-attached to a
+ *   different port, or if the base system is rebooted, the device
+ *   should still report the same GUID.
+ *
+ * GUIDs are as precise as possible but are not guaranteed to
+ *   distinguish physically distinct but equivalent devices.  For
+ *   example, two game controllers from the same vendor with the same
+ *   product ID and revision may have the same GUID.
+ *
+ * GUIDs may be platform-dependent (i.e., the same device may report
+ *   different GUIDs on different operating systems).
+ */
+typedef struct {
+    Uint8 data[16];
+} SDL_GUID;
+
+/* Function prototypes */
+
+/**
+ * Get an ASCII string representation for a given ::SDL_GUID.
+ *
+ * You should supply at least 33 bytes for pszGUID.
+ *
+ * \param guid the ::SDL_GUID you wish to convert to string
+ * \param pszGUID buffer in which to write the ASCII string
+ * \param cbGUID the size of pszGUID
+ *
+ * \since This function is available since SDL 2.24.0.
+ *
+ * \sa SDL_GUIDFromString
+ */
+extern DECLSPEC void SDLCALL SDL_GUIDToString(SDL_GUID guid, char *pszGUID, int cbGUID);
+
+/**
+ * Convert a GUID string into a ::SDL_GUID structure.
+ *
+ * Performs no error checking. If this function is given a string containing
+ * an invalid GUID, the function will silently succeed, but the GUID generated
+ * will not be useful.
+ *
+ * \param pchGUID string containing an ASCII representation of a GUID
+ * \returns a ::SDL_GUID structure.
+ *
+ * \since This function is available since SDL 2.24.0.
+ *
+ * \sa SDL_GUIDToString
+ */
+extern DECLSPEC SDL_GUID SDLCALL SDL_GUIDFromString(const char *pchGUID);
+
+/* Ends C function definitions when using C++ */
+#ifdef __cplusplus
+}
+#endif
+#include "close_code.h"
+
+#endif /* SDL_guid_h_ */
+
+/* vi: set ts=4 sw=4 expandtab: */

libs/SDL2/i686-w64-mingw32/include/SDL2/SDL_haptic.h

 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -76,7 +76,7 @@
  *    }
  *
  *    // Create the effect
- *    memset( &effect, 0, sizeof(SDL_HapticEffect) ); // 0 is safe default
+ *    SDL_memset( &effect, 0, sizeof(SDL_HapticEffect) ); // 0 is safe default
  *    effect.type = SDL_HAPTIC_SINE;
  *    effect.periodic.direction.type = SDL_HAPTIC_POLAR; // Polar coordinates
  *    effect.periodic.direction.dir[0] = 18000; // Force comes from south
@@ -336,6 +336,14 @@ typedef struct _SDL_Haptic SDL_Haptic;
  */
 #define SDL_HAPTIC_SPHERICAL  2
 
+/**
+ *  \brief Use this value to play an effect on the steering wheel axis. This 
+ *  provides better compatibility across platforms and devices as SDL will guess 
+ *  the correct axis.
+ *  \sa SDL_HapticDirection
+ */
+#define SDL_HAPTIC_STEERING_AXIS 3
+
 /* @} *//* Direction encodings */
 
 /* @} *//* Haptic features */
@@ -444,6 +452,7 @@ typedef struct _SDL_Haptic SDL_Haptic;
  *  \sa SDL_HAPTIC_POLAR
  *  \sa SDL_HAPTIC_CARTESIAN
  *  \sa SDL_HAPTIC_SPHERICAL
+ *  \sa SDL_HAPTIC_STEERING_AXIS
  *  \sa SDL_HapticEffect
  *  \sa SDL_HapticNumAxes
  */
@@ -811,419 +820,513 @@ typedef union SDL_HapticEffect
 
 
 /* Function prototypes */
+
 /**
- *  \brief Count the number of haptic devices attached to the system.
+ * Count the number of haptic devices attached to the system.
+ *
+ * \returns the number of haptic devices detected on the system or a negative
+ *          error code on failure; call SDL_GetError() for more information.
  *
- *  \return Number of haptic devices detected on the system.
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticName
  */
 extern DECLSPEC int SDLCALL SDL_NumHaptics(void);
 
 /**
- *  \brief Get the implementation dependent name of a haptic device.
+ * Get the implementation dependent name of a haptic device.
+ *
+ * This can be called before any joysticks are opened. If no name can be
+ * found, this function returns NULL.
  *
- *  This can be called before any joysticks are opened.
- *  If no name can be found, this function returns NULL.
+ * \param device_index index of the device to query.
+ * \returns the name of the device or NULL on failure; call SDL_GetError() for
+ *          more information.
  *
- *  \param device_index Index of the device to get its name.
- *  \return Name of the device or NULL on error.
+ * \since This function is available since SDL 2.0.0.
  *
- *  \sa SDL_NumHaptics
+ * \sa SDL_NumHaptics
  */
 extern DECLSPEC const char *SDLCALL SDL_HapticName(int device_index);
 
 /**
- *  \brief Opens a haptic device for use.
+ * Open a haptic device for use.
  *
- *  The index passed as an argument refers to the N'th haptic device on this
- *  system.
+ * The index passed as an argument refers to the N'th haptic device on this
+ * system.
  *
- *  When opening a haptic device, its gain will be set to maximum and
- *  autocenter will be disabled.  To modify these values use
- *  SDL_HapticSetGain() and SDL_HapticSetAutocenter().
+ * When opening a haptic device, its gain will be set to maximum and
+ * autocenter will be disabled. To modify these values use SDL_HapticSetGain()
+ * and SDL_HapticSetAutocenter().
  *
- *  \param device_index Index of the device to open.
- *  \return Device identifier or NULL on error.
+ * \param device_index index of the device to open
+ * \returns the device identifier or NULL on failure; call SDL_GetError() for
+ *          more information.
  *
- *  \sa SDL_HapticIndex
- *  \sa SDL_HapticOpenFromMouse
- *  \sa SDL_HapticOpenFromJoystick
- *  \sa SDL_HapticClose
- *  \sa SDL_HapticSetGain
- *  \sa SDL_HapticSetAutocenter
- *  \sa SDL_HapticPause
- *  \sa SDL_HapticStopAll
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticClose
+ * \sa SDL_HapticIndex
+ * \sa SDL_HapticOpenFromJoystick
+ * \sa SDL_HapticOpenFromMouse
+ * \sa SDL_HapticPause
+ * \sa SDL_HapticSetAutocenter
+ * \sa SDL_HapticSetGain
+ * \sa SDL_HapticStopAll
  */
 extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpen(int device_index);
 
 /**
- *  \brief Checks if the haptic device at index has been opened.
+ * Check if the haptic device at the designated index has been opened.
  *
- *  \param device_index Index to check to see if it has been opened.
- *  \return 1 if it has been opened or 0 if it hasn't.
+ * \param device_index the index of the device to query
+ * \returns 1 if it has been opened, 0 if it hasn't or on failure; call
+ *          SDL_GetError() for more information.
  *
- *  \sa SDL_HapticOpen
- *  \sa SDL_HapticIndex
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticIndex
+ * \sa SDL_HapticOpen
  */
 extern DECLSPEC int SDLCALL SDL_HapticOpened(int device_index);
 
 /**
- *  \brief Gets the index of a haptic device.
+ * Get the index of a haptic device.
  *
- *  \param haptic Haptic device to get the index of.
- *  \return The index of the haptic device or -1 on error.
+ * \param haptic the SDL_Haptic device to query
+ * \returns the index of the specified haptic device or a negative error code
+ *          on failure; call SDL_GetError() for more information.
  *
- *  \sa SDL_HapticOpen
- *  \sa SDL_HapticOpened
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticOpen
+ * \sa SDL_HapticOpened
  */
 extern DECLSPEC int SDLCALL SDL_HapticIndex(SDL_Haptic * haptic);
 
 /**
- *  \brief Gets whether or not the current mouse has haptic capabilities.
+ * Query whether or not the current mouse has haptic capabilities.
+ *
+ * \returns SDL_TRUE if the mouse is haptic or SDL_FALSE if it isn't.
  *
- *  \return SDL_TRUE if the mouse is haptic, SDL_FALSE if it isn't.
+ * \since This function is available since SDL 2.0.0.
  *
- *  \sa SDL_HapticOpenFromMouse
+ * \sa SDL_HapticOpenFromMouse
  */
 extern DECLSPEC int SDLCALL SDL_MouseIsHaptic(void);
 
 /**
- *  \brief Tries to open a haptic device from the current mouse.
+ * Try to open a haptic device from the current mouse.
  *
- *  \return The haptic device identifier or NULL on error.
+ * \returns the haptic device identifier or NULL on failure; call
+ *          SDL_GetError() for more information.
  *
- *  \sa SDL_MouseIsHaptic
- *  \sa SDL_HapticOpen
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticOpen
+ * \sa SDL_MouseIsHaptic
  */
 extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromMouse(void);
 
 /**
- *  \brief Checks to see if a joystick has haptic features.
+ * Query if a joystick has haptic features.
  *
- *  \param joystick Joystick to test for haptic capabilities.
- *  \return SDL_TRUE if the joystick is haptic, SDL_FALSE if it isn't
- *          or -1 if an error occurred.
+ * \param joystick the SDL_Joystick to test for haptic capabilities
+ * \returns SDL_TRUE if the joystick is haptic, SDL_FALSE if it isn't, or a
+ *          negative error code on failure; call SDL_GetError() for more
+ *          information.
  *
- *  \sa SDL_HapticOpenFromJoystick
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticOpenFromJoystick
  */
 extern DECLSPEC int SDLCALL SDL_JoystickIsHaptic(SDL_Joystick * joystick);
 
 /**
- *  \brief Opens a haptic device for use from a joystick device.
+ * Open a haptic device for use from a joystick device.
  *
- *  You must still close the haptic device separately.  It will not be closed
- *  with the joystick.
+ * You must still close the haptic device separately. It will not be closed
+ * with the joystick.
  *
- *  When opening from a joystick you should first close the haptic device before
- *  closing the joystick device.  If not, on some implementations the haptic
- *  device will also get unallocated and you'll be unable to use force feedback
- *  on that device.
+ * When opened from a joystick you should first close the haptic device before
+ * closing the joystick device. If not, on some implementations the haptic
+ * device will also get unallocated and you'll be unable to use force feedback
+ * on that device.
  *
- *  \param joystick Joystick to create a haptic device from.
- *  \return A valid haptic device identifier on success or NULL on error.
+ * \param joystick the SDL_Joystick to create a haptic device from
+ * \returns a valid haptic device identifier on success or NULL on failure;
+ *          call SDL_GetError() for more information.
  *
- *  \sa SDL_HapticOpen
- *  \sa SDL_HapticClose
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticClose
+ * \sa SDL_HapticOpen
+ * \sa SDL_JoystickIsHaptic
  */
 extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromJoystick(SDL_Joystick *
                                                                joystick);
 
 /**
- *  \brief Closes a haptic device previously opened with SDL_HapticOpen().
+ * Close a haptic device previously opened with SDL_HapticOpen().
+ *
+ * \param haptic the SDL_Haptic device to close
  *
- *  \param haptic Haptic device to close.
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticOpen
  */
 extern DECLSPEC void SDLCALL SDL_HapticClose(SDL_Haptic * haptic);
 
 /**
- *  \brief Returns the number of effects a haptic device can store.
+ * Get the number of effects a haptic device can store.
+ *
+ * On some platforms this isn't fully supported, and therefore is an
+ * approximation. Always check to see if your created effect was actually
+ * created and do not rely solely on SDL_HapticNumEffects().
  *
- *  On some platforms this isn't fully supported, and therefore is an
- *  approximation.  Always check to see if your created effect was actually
- *  created and do not rely solely on SDL_HapticNumEffects().
+ * \param haptic the SDL_Haptic device to query
+ * \returns the number of effects the haptic device can store or a negative
+ *          error code on failure; call SDL_GetError() for more information.
  *
- *  \param haptic The haptic device to query effect max.
- *  \return The number of effects the haptic device can store or
- *          -1 on error.
+ * \since This function is available since SDL 2.0.0.
  *
- *  \sa SDL_HapticNumEffectsPlaying
- *  \sa SDL_HapticQuery
+ * \sa SDL_HapticNumEffectsPlaying
+ * \sa SDL_HapticQuery
  */
 extern DECLSPEC int SDLCALL SDL_HapticNumEffects(SDL_Haptic * haptic);
 
 /**
- *  \brief Returns the number of effects a haptic device can play at the same
- *         time.
+ * Get the number of effects a haptic device can play at the same time.
+ *
+ * This is not supported on all platforms, but will always return a value.
  *
- *  This is not supported on all platforms, but will always return a value.
- *  Added here for the sake of completeness.
+ * \param haptic the SDL_Haptic device to query maximum playing effects
+ * \returns the number of effects the haptic device can play at the same time
+ *          or a negative error code on failure; call SDL_GetError() for more
+ *          information.
  *
- *  \param haptic The haptic device to query maximum playing effects.
- *  \return The number of effects the haptic device can play at the same time
- *          or -1 on error.
+ * \since This function is available since SDL 2.0.0.
  *
- *  \sa SDL_HapticNumEffects
- *  \sa SDL_HapticQuery
+ * \sa SDL_HapticNumEffects
+ * \sa SDL_HapticQuery
  */
 extern DECLSPEC int SDLCALL SDL_HapticNumEffectsPlaying(SDL_Haptic * haptic);
 
 /**
- *  \brief Gets the haptic device's supported features in bitwise manner.
+ * Get the haptic device's supported features in bitwise manner.
  *
- *  Example:
- *  \code
- *  if (SDL_HapticQuery(haptic) & SDL_HAPTIC_CONSTANT) {
- *      printf("We have constant haptic effect!\n");
- *  }
- *  \endcode
+ * \param haptic the SDL_Haptic device to query
+ * \returns a list of supported haptic features in bitwise manner (OR'd), or 0
+ *          on failure; call SDL_GetError() for more information.
  *
- *  \param haptic The haptic device to query.
- *  \return Haptic features in bitwise manner (OR'd).
+ * \since This function is available since SDL 2.0.0.
  *
- *  \sa SDL_HapticNumEffects
- *  \sa SDL_HapticEffectSupported
+ * \sa SDL_HapticEffectSupported
+ * \sa SDL_HapticNumEffects
  */
 extern DECLSPEC unsigned int SDLCALL SDL_HapticQuery(SDL_Haptic * haptic);
 
 
 /**
- *  \brief Gets the number of haptic axes the device has.
+ * Get the number of haptic axes the device has.
  *
- *  \sa SDL_HapticDirection
+ * The number of haptic axes might be useful if working with the
+ * SDL_HapticDirection effect.
+ *
+ * \param haptic the SDL_Haptic device to query
+ * \returns the number of axes on success or a negative error code on failure;
+ *          call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
  */
 extern DECLSPEC int SDLCALL SDL_HapticNumAxes(SDL_Haptic * haptic);
 
 /**
- *  \brief Checks to see if effect is supported by haptic.
+ * Check to see if an effect is supported by a haptic device.
+ *
+ * \param haptic the SDL_Haptic device to query
+ * \param effect the desired effect to query
+ * \returns SDL_TRUE if effect is supported, SDL_FALSE if it isn't, or a
+ *          negative error code on failure; call SDL_GetError() for more
+ *          information.
  *
- *  \param haptic Haptic device to check on.
- *  \param effect Effect to check to see if it is supported.
- *  \return SDL_TRUE if effect is supported, SDL_FALSE if it isn't or -1 on error.
+ * \since This function is available since SDL 2.0.0.
  *
- *  \sa SDL_HapticQuery
- *  \sa SDL_HapticNewEffect
+ * \sa SDL_HapticNewEffect
+ * \sa SDL_HapticQuery
  */
 extern DECLSPEC int SDLCALL SDL_HapticEffectSupported(SDL_Haptic * haptic,
                                                       SDL_HapticEffect *
                                                       effect);
 
 /**
- *  \brief Creates a new haptic effect on the device.
+ * Create a new haptic effect on a specified device.
  *
- *  \param haptic Haptic device to create the effect on.
- *  \param effect Properties of the effect to create.
- *  \return The identifier of the effect on success or -1 on error.
+ * \param haptic an SDL_Haptic device to create the effect on
+ * \param effect an SDL_HapticEffect structure containing the properties of
+ *               the effect to create
+ * \returns the ID of the effect on success or a negative error code on
+ *          failure; call SDL_GetError() for more information.
  *
- *  \sa SDL_HapticUpdateEffect
- *  \sa SDL_HapticRunEffect
- *  \sa SDL_HapticDestroyEffect
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticDestroyEffect
+ * \sa SDL_HapticRunEffect
+ * \sa SDL_HapticUpdateEffect
  */
 extern DECLSPEC int SDLCALL SDL_HapticNewEffect(SDL_Haptic * haptic,
                                                 SDL_HapticEffect * effect);
 
 /**
- *  \brief Updates the properties of an effect.
+ * Update the properties of an effect.
  *
- *  Can be used dynamically, although behavior when dynamically changing
- *  direction may be strange.  Specifically the effect may reupload itself
- *  and start playing from the start.  You cannot change the type either when
- *  running SDL_HapticUpdateEffect().
+ * Can be used dynamically, although behavior when dynamically changing
+ * direction may be strange. Specifically the effect may re-upload itself and
+ * start playing from the start. You also cannot change the type either when
+ * running SDL_HapticUpdateEffect().
  *
- *  \param haptic Haptic device that has the effect.
- *  \param effect Identifier of the effect to update.
- *  \param data New effect properties to use.
- *  \return 0 on success or -1 on error.
+ * \param haptic the SDL_Haptic device that has the effect
+ * \param effect the identifier of the effect to update
+ * \param data an SDL_HapticEffect structure containing the new effect
+ *             properties to use
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
  *
- *  \sa SDL_HapticNewEffect
- *  \sa SDL_HapticRunEffect
- *  \sa SDL_HapticDestroyEffect
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticDestroyEffect
+ * \sa SDL_HapticNewEffect
+ * \sa SDL_HapticRunEffect
  */
 extern DECLSPEC int SDLCALL SDL_HapticUpdateEffect(SDL_Haptic * haptic,
                                                    int effect,
                                                    SDL_HapticEffect * data);
 
 /**
- *  \brief Runs the haptic effect on its associated haptic device.
+ * Run the haptic effect on its associated haptic device.
  *
- *  If iterations are ::SDL_HAPTIC_INFINITY, it'll run the effect over and over
- *  repeating the envelope (attack and fade) every time.  If you only want the
- *  effect to last forever, set ::SDL_HAPTIC_INFINITY in the effect's length
- *  parameter.
+ * To repeat the effect over and over indefinitely, set `iterations` to
+ * `SDL_HAPTIC_INFINITY`. (Repeats the envelope - attack and fade.) To make
+ * one instance of the effect last indefinitely (so the effect does not fade),
+ * set the effect's `length` in its structure/union to `SDL_HAPTIC_INFINITY`
+ * instead.
  *
- *  \param haptic Haptic device to run the effect on.
- *  \param effect Identifier of the haptic effect to run.
- *  \param iterations Number of iterations to run the effect. Use
- *         ::SDL_HAPTIC_INFINITY for infinity.
- *  \return 0 on success or -1 on error.
+ * \param haptic the SDL_Haptic device to run the effect on
+ * \param effect the ID of the haptic effect to run
+ * \param iterations the number of iterations to run the effect; use
+ *                   `SDL_HAPTIC_INFINITY` to repeat forever
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
  *
- *  \sa SDL_HapticStopEffect
- *  \sa SDL_HapticDestroyEffect
- *  \sa SDL_HapticGetEffectStatus
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticDestroyEffect
+ * \sa SDL_HapticGetEffectStatus
+ * \sa SDL_HapticStopEffect
  */
 extern DECLSPEC int SDLCALL SDL_HapticRunEffect(SDL_Haptic * haptic,
                                                 int effect,
                                                 Uint32 iterations);
 
 /**
- *  \brief Stops the haptic effect on its associated haptic device.
+ * Stop the haptic effect on its associated haptic device.
  *
- *  \param haptic Haptic device to stop the effect on.
- *  \param effect Identifier of the effect to stop.
- *  \return 0 on success or -1 on error.
+ * *
  *
- *  \sa SDL_HapticRunEffect
- *  \sa SDL_HapticDestroyEffect
+ * \param haptic the SDL_Haptic device to stop the effect on
+ * \param effect the ID of the haptic effect to stop
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticDestroyEffect
+ * \sa SDL_HapticRunEffect
  */
 extern DECLSPEC int SDLCALL SDL_HapticStopEffect(SDL_Haptic * haptic,
                                                  int effect);
 
 /**
- *  \brief Destroys a haptic effect on the device.
+ * Destroy a haptic effect on the device.
  *
- *  This will stop the effect if it's running.  Effects are automatically
- *  destroyed when the device is closed.
+ * This will stop the effect if it's running. Effects are automatically
+ * destroyed when the device is closed.
  *
- *  \param haptic Device to destroy the effect on.
- *  \param effect Identifier of the effect to destroy.
+ * \param haptic the SDL_Haptic device to destroy the effect on
+ * \param effect the ID of the haptic effect to destroy
  *
- *  \sa SDL_HapticNewEffect
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticNewEffect
  */
 extern DECLSPEC void SDLCALL SDL_HapticDestroyEffect(SDL_Haptic * haptic,
                                                      int effect);
 
 /**
- *  \brief Gets the status of the current effect on the haptic device.
+ * Get the status of the current effect on the specified haptic device.
+ *
+ * Device must support the SDL_HAPTIC_STATUS feature.
  *
- *  Device must support the ::SDL_HAPTIC_STATUS feature.
+ * \param haptic the SDL_Haptic device to query for the effect status on
+ * \param effect the ID of the haptic effect to query its status
+ * \returns 0 if it isn't playing, 1 if it is playing, or a negative error
+ *          code on failure; call SDL_GetError() for more information.
  *
- *  \param haptic Haptic device to query the effect status on.
- *  \param effect Identifier of the effect to query its status.
- *  \return 0 if it isn't playing, 1 if it is playing or -1 on error.
+ * \since This function is available since SDL 2.0.0.
  *
- *  \sa SDL_HapticRunEffect
- *  \sa SDL_HapticStopEffect
+ * \sa SDL_HapticRunEffect
+ * \sa SDL_HapticStopEffect
  */
 extern DECLSPEC int SDLCALL SDL_HapticGetEffectStatus(SDL_Haptic * haptic,
                                                       int effect);
 
 /**
- *  \brief Sets the global gain of the device.
+ * Set the global gain of the specified haptic device.
+ *
+ * Device must support the SDL_HAPTIC_GAIN feature.
  *
- *  Device must support the ::SDL_HAPTIC_GAIN feature.
+ * The user may specify the maximum gain by setting the environment variable
+ * `SDL_HAPTIC_GAIN_MAX` which should be between 0 and 100. All calls to
+ * SDL_HapticSetGain() will scale linearly using `SDL_HAPTIC_GAIN_MAX` as the
+ * maximum.
  *
- *  The user may specify the maximum gain by setting the environment variable
- *  SDL_HAPTIC_GAIN_MAX which should be between 0 and 100.  All calls to
- *  SDL_HapticSetGain() will scale linearly using SDL_HAPTIC_GAIN_MAX as the
- *  maximum.
+ * \param haptic the SDL_Haptic device to set the gain on
+ * \param gain value to set the gain to, should be between 0 and 100 (0 - 100)
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
  *
- *  \param haptic Haptic device to set the gain on.
- *  \param gain Value to set the gain to, should be between 0 and 100.
- *  \return 0 on success or -1 on error.
+ * \since This function is available since SDL 2.0.0.
  *
- *  \sa SDL_HapticQuery
+ * \sa SDL_HapticQuery
  */
 extern DECLSPEC int SDLCALL SDL_HapticSetGain(SDL_Haptic * haptic, int gain);
 
 /**
- *  \brief Sets the global autocenter of the device.
+ * Set the global autocenter of the device.
  *
- *  Autocenter should be between 0 and 100.  Setting it to 0 will disable
- *  autocentering.
+ * Autocenter should be between 0 and 100. Setting it to 0 will disable
+ * autocentering.
  *
- *  Device must support the ::SDL_HAPTIC_AUTOCENTER feature.
+ * Device must support the SDL_HAPTIC_AUTOCENTER feature.
  *
- *  \param haptic Haptic device to set autocentering on.
- *  \param autocenter Value to set autocenter to, 0 disables autocentering.
- *  \return 0 on success or -1 on error.
+ * \param haptic the SDL_Haptic device to set autocentering on
+ * \param autocenter value to set autocenter to (0-100)
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
  *
- *  \sa SDL_HapticQuery
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticQuery
  */
 extern DECLSPEC int SDLCALL SDL_HapticSetAutocenter(SDL_Haptic * haptic,
                                                     int autocenter);
 
 /**
- *  \brief Pauses a haptic device.
+ * Pause a haptic device.
  *
- *  Device must support the ::SDL_HAPTIC_PAUSE feature.  Call
- *  SDL_HapticUnpause() to resume playback.
+ * Device must support the `SDL_HAPTIC_PAUSE` feature. Call
+ * SDL_HapticUnpause() to resume playback.
  *
- *  Do not modify the effects nor add new ones while the device is paused.
- *  That can cause all sorts of weird errors.
+ * Do not modify the effects nor add new ones while the device is paused. That
+ * can cause all sorts of weird errors.
  *
- *  \param haptic Haptic device to pause.
- *  \return 0 on success or -1 on error.
+ * \param haptic the SDL_Haptic device to pause
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
  *
- *  \sa SDL_HapticUnpause
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticUnpause
  */
 extern DECLSPEC int SDLCALL SDL_HapticPause(SDL_Haptic * haptic);
 
 /**
- *  \brief Unpauses a haptic device.
+ * Unpause a haptic device.
  *
- *  Call to unpause after SDL_HapticPause().
+ * Call to unpause after SDL_HapticPause().
  *
- *  \param haptic Haptic device to unpause.
- *  \return 0 on success or -1 on error.
+ * \param haptic the SDL_Haptic device to unpause
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
  *
- *  \sa SDL_HapticPause
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticPause
  */
 extern DECLSPEC int SDLCALL SDL_HapticUnpause(SDL_Haptic * haptic);
 
 /**
- *  \brief Stops all the currently playing effects on a haptic device.
+ * Stop all the currently playing effects on a haptic device.
+ *
+ * \param haptic the SDL_Haptic device to stop
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
  *
- *  \param haptic Haptic device to stop.
- *  \return 0 on success or -1 on error.
+ * \since This function is available since SDL 2.0.0.
  */
 extern DECLSPEC int SDLCALL SDL_HapticStopAll(SDL_Haptic * haptic);
 
 /**
- *  \brief Checks to see if rumble is supported on a haptic device.
+ * Check whether rumble is supported on a haptic device.
  *
- *  \param haptic Haptic device to check to see if it supports rumble.
- *  \return SDL_TRUE if effect is supported, SDL_FALSE if it isn't or -1 on error.
+ * \param haptic haptic device to check for rumble support
+ * \returns SDL_TRUE if effect is supported, SDL_FALSE if it isn't, or a
+ *          negative error code on failure; call SDL_GetError() for more
+ *          information.
  *
- *  \sa SDL_HapticRumbleInit
- *  \sa SDL_HapticRumblePlay
- *  \sa SDL_HapticRumbleStop
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticRumbleInit
+ * \sa SDL_HapticRumblePlay
+ * \sa SDL_HapticRumbleStop
  */
 extern DECLSPEC int SDLCALL SDL_HapticRumbleSupported(SDL_Haptic * haptic);
 
 /**
- *  \brief Initializes the haptic device for simple rumble playback.
+ * Initialize a haptic device for simple rumble playback.
  *
- *  \param haptic Haptic device to initialize for simple rumble playback.
- *  \return 0 on success or -1 on error.
+ * \param haptic the haptic device to initialize for simple rumble playback
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
  *
- *  \sa SDL_HapticOpen
- *  \sa SDL_HapticRumbleSupported
- *  \sa SDL_HapticRumblePlay
- *  \sa SDL_HapticRumbleStop
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_HapticOpen
+ * \sa SDL_HapticRumblePlay
+ * \sa SDL_HapticRumbleStop
+ * \sa SDL_HapticRumbleSupported
  */
 extern DECLSPEC int SDLCALL SDL_HapticRumbleInit(SDL_Haptic * haptic);
 
 /**
- *  \brief Runs simple rumble on a haptic device
+ * Run a simple rumble effect on a haptic device.
+ *
+ * \param haptic the haptic device to play the rumble effect on
+ * \param strength strength of the rumble to play as a 0-1 float value
+ * \param length length of the rumble to play in milliseconds
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
  *
- *  \param haptic Haptic device to play rumble effect on.
- *  \param strength Strength of the rumble to play as a 0-1 float value.
- *  \param length Length of the rumble to play in milliseconds.
- *  \return 0 on success or -1 on error.
+ * \since This function is available since SDL 2.0.0.
  *
- *  \sa SDL_HapticRumbleSupported
- *  \sa SDL_HapticRumbleInit
- *  \sa SDL_HapticRumbleStop
+ * \sa SDL_HapticRumbleInit
+ * \sa SDL_HapticRumbleStop
+ * \sa SDL_HapticRumbleSupported
  */
 extern DECLSPEC int SDLCALL SDL_HapticRumblePlay(SDL_Haptic * haptic, float strength, Uint32 length );
 
 /**
- *  \brief Stops the simple rumble on a haptic device.
+ * Stop the simple rumble on a haptic device.
+ *
+ * \param haptic the haptic device to stop the rumble effect on
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
  *
- *  \param haptic Haptic to stop the rumble on.
- *  \return 0 on success or -1 on error.
+ * \since This function is available since SDL 2.0.0.
  *
- *  \sa SDL_HapticRumbleSupported
- *  \sa SDL_HapticRumbleInit
- *  \sa SDL_HapticRumblePlay
+ * \sa SDL_HapticRumbleInit
+ * \sa SDL_HapticRumblePlay
+ * \sa SDL_HapticRumbleSupported
  */
 extern DECLSPEC int SDLCALL SDL_HapticRumbleStop(SDL_Haptic * haptic);
 

libs/SDL2/i686-w64-mingw32/include/SDL2/SDL_hidapi.h

+/*
+  Simple DirectMedia Layer
+  Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
+
+  This software is provided 'as-is', without any express or implied
+  warranty.  In no event will the authors be held liable for any damages
+  arising from the use of this software.
+
+  Permission is granted to anyone to use this software for any purpose,
+  including commercial applications, and to alter it and redistribute it
+  freely, subject to the following restrictions:
+
+  1. The origin of this software must not be misrepresented; you must not
+     claim that you wrote the original software. If you use this software
+     in a product, an acknowledgment in the product documentation would be
+     appreciated but is not required.
+  2. Altered source versions must be plainly marked as such, and must not be
+     misrepresented as being the original software.
+  3. This notice may not be removed or altered from any source distribution.
+*/
+
+/**
+ *  \file SDL_hidapi.h
+ *
+ *  Header file for SDL HIDAPI functions.
+ *
+ *  This is an adaptation of the original HIDAPI interface by Alan Ott,
+ *  and includes source code licensed under the following BSD license:
+ *
+    Copyright (c) 2010, Alan Ott, Signal 11 Software
+    All rights reserved.
+
+    Redistribution and use in source and binary forms, with or without
+    modification, are permitted provided that the following conditions are met:
+
+    * Redistributions of source code must retain the above copyright notice,
+      this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright
+      notice, this list of conditions and the following disclaimer in the
+      documentation and/or other materials provided with the distribution.
+    * Neither the name of Signal 11 Software nor the names of its
+      contributors may be used to endorse or promote products derived from
+      this software without specific prior written permission.
+
+    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+    AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+    IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+    ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+    LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+    CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+    SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+    INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+    CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+    ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+    POSSIBILITY OF SUCH DAMAGE.
+ *
+ * If you would like a version of SDL without this code, you can build SDL
+ * with SDL_HIDAPI_DISABLED defined to 1. You might want to do this for example
+ * on iOS or tvOS to avoid a dependency on the CoreBluetooth framework.
+ */
+
+#ifndef SDL_hidapi_h_
+#define SDL_hidapi_h_
+
+#include "SDL_stdinc.h"
+
+#include "begin_code.h"
+/* Set up for C function definitions, even when using C++ */
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ *  \brief  A handle representing an open HID device
+ */
+struct SDL_hid_device_;
+typedef struct SDL_hid_device_ SDL_hid_device; /**< opaque hidapi structure */
+
+/** hidapi info structure */
+/**
+ *  \brief  Information about a connected HID device
+ */
+typedef struct SDL_hid_device_info
+{
+    /** Platform-specific device path */
+    char *path;
+    /** Device Vendor ID */
+    unsigned short vendor_id;
+    /** Device Product ID */
+    unsigned short product_id;
+    /** Serial Number */
+    wchar_t *serial_number;
+    /** Device Release Number in binary-coded decimal,
+        also known as Device Version Number */
+    unsigned short release_number;
+    /** Manufacturer String */
+    wchar_t *manufacturer_string;
+    /** Product string */
+    wchar_t *product_string;
+    /** Usage Page for this Device/Interface
+        (Windows/Mac only). */
+    unsigned short usage_page;
+    /** Usage for this Device/Interface
+        (Windows/Mac only).*/
+    unsigned short usage;
+    /** The USB interface which this logical device
+        represents.
+
+        * Valid on both Linux implementations in all cases.
+        * Valid on the Windows implementation only if the device
+          contains more than one interface. */
+    int interface_number;
+
+    /** Additional information about the USB interface.
+        Valid on libusb and Android implementations. */
+    int interface_class;
+    int interface_subclass;
+    int interface_protocol;
+
+    /** Pointer to the next device */
+    struct SDL_hid_device_info *next;
+} SDL_hid_device_info;
+
+
+/**
+ * Initialize the HIDAPI library.
+ *
+ * This function initializes the HIDAPI library. Calling it is not strictly
+ * necessary, as it will be called automatically by SDL_hid_enumerate() and
+ * any of the SDL_hid_open_*() functions if it is needed. This function should
+ * be called at the beginning of execution however, if there is a chance of
+ * HIDAPI handles being opened by different threads simultaneously.
+ *
+ * Each call to this function should have a matching call to SDL_hid_exit()
+ *
+ * \returns 0 on success and -1 on error.
+ *
+ * \since This function is available since SDL 2.0.18.
+ *
+ * \sa SDL_hid_exit
+ */
+extern DECLSPEC int SDLCALL SDL_hid_init(void);
+
+/**
+ * Finalize the HIDAPI library.
+ *
+ * This function frees all of the static data associated with HIDAPI. It
+ * should be called at the end of execution to avoid memory leaks.
+ *
+ * \returns 0 on success and -1 on error.
+ *
+ * \since This function is available since SDL 2.0.18.
+ *
+ * \sa SDL_hid_init
+ */
+extern DECLSPEC int SDLCALL SDL_hid_exit(void);
+
+/**
+ * Check to see if devices may have been added or removed.
+ *
+ * Enumerating the HID devices is an expensive operation, so you can call this
+ * to see if there have been any system device changes since the last call to
+ * this function. A change in the counter returned doesn't necessarily mean
+ * that anything has changed, but you can call SDL_hid_enumerate() to get an
+ * updated device list.
+ *
+ * Calling this function for the first time may cause a thread or other system
+ * resource to be allocated to track device change notifications.
+ *
+ * \returns a change counter that is incremented with each potential device
+ *          change, or 0 if device change detection isn't available.
+ *
+ * \since This function is available since SDL 2.0.18.
+ *
+ * \sa SDL_hid_enumerate
+ */
+extern DECLSPEC Uint32 SDLCALL SDL_hid_device_change_count(void);
+
+/**
+ * Enumerate the HID Devices.
+ *
+ * This function returns a linked list of all the HID devices attached to the
+ * system which match vendor_id and product_id. If `vendor_id` is set to 0
+ * then any vendor matches. If `product_id` is set to 0 then any product
+ * matches. If `vendor_id` and `product_id` are both set to 0, then all HID
+ * devices will be returned.
+ *
+ * \param vendor_id The Vendor ID (VID) of the types of device to open.
+ * \param product_id The Product ID (PID) of the types of device to open.
+ * \returns a pointer to a linked list of type SDL_hid_device_info, containing
+ *          information about the HID devices attached to the system, or NULL
+ *          in the case of failure. Free this linked list by calling
+ *          SDL_hid_free_enumeration().
+ *
+ * \since This function is available since SDL 2.0.18.
+ *
+ * \sa SDL_hid_device_change_count
+ */
+extern DECLSPEC SDL_hid_device_info * SDLCALL SDL_hid_enumerate(unsigned short vendor_id, unsigned short product_id);
+
+/**
+ * Free an enumeration Linked List
+ *
+ * This function frees a linked list created by SDL_hid_enumerate().
+ *
+ * \param devs Pointer to a list of struct_device returned from
+ *             SDL_hid_enumerate().
+ *
+ * \since This function is available since SDL 2.0.18.
+ */
+extern DECLSPEC void SDLCALL SDL_hid_free_enumeration(SDL_hid_device_info *devs);
+
+/**
+ * Open a HID device using a Vendor ID (VID), Product ID (PID) and optionally
+ * a serial number.
+ *
+ * If `serial_number` is NULL, the first device with the specified VID and PID
+ * is opened.
+ *
+ * \param vendor_id The Vendor ID (VID) of the device to open.
+ * \param product_id The Product ID (PID) of the device to open.
+ * \param serial_number The Serial Number of the device to open (Optionally
+ *                      NULL).
+ * \returns a pointer to a SDL_hid_device object on success or NULL on
+ *          failure.
+ *
+ * \since This function is available since SDL 2.0.18.
+ */
+extern DECLSPEC SDL_hid_device * SDLCALL SDL_hid_open(unsigned short vendor_id, unsigned short product_id, const wchar_t *serial_number);
+
+/**
+ * Open a HID device by its path name.
+ *
+ * The path name be determined by calling SDL_hid_enumerate(), or a
+ * platform-specific path name can be used (eg: /dev/hidraw0 on Linux).
+ *
+ * \param path The path name of the device to open
+ * \returns a pointer to a SDL_hid_device object on success or NULL on
+ *          failure.
+ *
+ * \since This function is available since SDL 2.0.18.
+ */
+extern DECLSPEC SDL_hid_device * SDLCALL SDL_hid_open_path(const char *path, int bExclusive /* = false */);
+
+/**
+ * Write an Output report to a HID device.
+ *
+ * The first byte of `data` must contain the Report ID. For devices which only
+ * support a single report, this must be set to 0x0. The remaining bytes
+ * contain the report data. Since the Report ID is mandatory, calls to
+ * SDL_hid_write() will always contain one more byte than the report contains.
+ * For example, if a hid report is 16 bytes long, 17 bytes must be passed to
+ * SDL_hid_write(), the Report ID (or 0x0, for devices with a single report),
+ * followed by the report data (16 bytes). In this example, the length passed
+ * in would be 17.
+ *
+ * SDL_hid_write() will send the data on the first OUT endpoint, if one
+ * exists. If it does not, it will send the data through the Control Endpoint
+ * (Endpoint 0).
+ *
+ * \param dev A device handle returned from SDL_hid_open().
+ * \param data The data to send, including the report number as the first
+ *             byte.
+ * \param length The length in bytes of the data to send.
+ * \returns the actual number of bytes written and -1 on error.
+ *
+ * \since This function is available since SDL 2.0.18.
+ */
+extern DECLSPEC int SDLCALL SDL_hid_write(SDL_hid_device *dev, const unsigned char *data, size_t length);
+
+/**
+ * Read an Input report from a HID device with timeout.
+ *
+ * Input reports are returned to the host through the INTERRUPT IN endpoint.
+ * The first byte will contain the Report number if the device uses numbered
+ * reports.
+ *
+ * \param dev A device handle returned from SDL_hid_open().
+ * \param data A buffer to put the read data into.
+ * \param length The number of bytes to read. For devices with multiple
+ *               reports, make sure to read an extra byte for the report
+ *               number.
+ * \param milliseconds timeout in milliseconds or -1 for blocking wait.
+ * \returns the actual number of bytes read and -1 on error. If no packet was
+ *          available to be read within the timeout period, this function
+ *          returns 0.
+ *
+ * \since This function is available since SDL 2.0.18.
+ */
+extern DECLSPEC int SDLCALL SDL_hid_read_timeout(SDL_hid_device *dev, unsigned char *data, size_t length, int milliseconds);
+
+/**
+ * Read an Input report from a HID device.
+ *
+ * Input reports are returned to the host through the INTERRUPT IN endpoint.
+ * The first byte will contain the Report number if the device uses numbered
+ * reports.
+ *
+ * \param dev A device handle returned from SDL_hid_open().
+ * \param data A buffer to put the read data into.
+ * \param length The number of bytes to read. For devices with multiple
+ *               reports, make sure to read an extra byte for the report
+ *               number.
+ * \returns the actual number of bytes read and -1 on error. If no packet was
+ *          available to be read and the handle is in non-blocking mode, this
+ *          function returns 0.
+ *
+ * \since This function is available since SDL 2.0.18.
+ */
+extern DECLSPEC int SDLCALL SDL_hid_read(SDL_hid_device *dev, unsigned char *data, size_t length);
+
+/**
+ * Set the device handle to be non-blocking.
+ *
+ * In non-blocking mode calls to SDL_hid_read() will return immediately with a
+ * value of 0 if there is no data to be read. In blocking mode, SDL_hid_read()
+ * will wait (block) until there is data to read before returning.
+ *
+ * Nonblocking can be turned on and off at any time.
+ *
+ * \param dev A device handle returned from SDL_hid_open().
+ * \param nonblock enable or not the nonblocking reads - 1 to enable
+ *                 nonblocking - 0 to disable nonblocking.
+ * \returns 0 on success and -1 on error.
+ *
+ * \since This function is available since SDL 2.0.18.
+ */
+extern DECLSPEC int SDLCALL SDL_hid_set_nonblocking(SDL_hid_device *dev, int nonblock);
+
+/**
+ * Send a Feature report to the device.
+ *
+ * Feature reports are sent over the Control endpoint as a Set_Report
+ * transfer. The first byte of `data` must contain the Report ID. For devices
+ * which only support a single report, this must be set to 0x0. The remaining
+ * bytes contain the report data. Since the Report ID is mandatory, calls to
+ * SDL_hid_send_feature_report() will always contain one more byte than the
+ * report contains. For example, if a hid report is 16 bytes long, 17 bytes
+ * must be passed to SDL_hid_send_feature_report(): the Report ID (or 0x0, for
+ * devices which do not use numbered reports), followed by the report data (16
+ * bytes). In this example, the length passed in would be 17.
+ *
+ * \param dev A device handle returned from SDL_hid_open().
+ * \param data The data to send, including the report number as the first
+ *             byte.
+ * \param length The length in bytes of the data to send, including the report
+ *               number.
+ * \returns the actual number of bytes written and -1 on error.
+ *
+ * \since This function is available since SDL 2.0.18.
+ */
+extern DECLSPEC int SDLCALL SDL_hid_send_feature_report(SDL_hid_device *dev, const unsigned char *data, size_t length);
+
+/**
+ * Get a feature report from a HID device.
+ *
+ * Set the first byte of `data` to the Report ID of the report to be read.
+ * Make sure to allow space for this extra byte in `data`. Upon return, the
+ * first byte will still contain the Report ID, and the report data will start
+ * in data[1].
+ *
+ * \param dev A device handle returned from SDL_hid_open().
+ * \param data A buffer to put the read data into, including the Report ID.
+ *             Set the first byte of `data` to the Report ID of the report to
+ *             be read, or set it to zero if your device does not use numbered
+ *             reports.
+ * \param length The number of bytes to read, including an extra byte for the
+ *               report ID. The buffer can be longer than the actual report.
+ * \returns the number of bytes read plus one for the report ID (which is
+ *          still in the first byte), or -1 on error.
+ *
+ * \since This function is available since SDL 2.0.18.
+ */
+extern DECLSPEC int SDLCALL SDL_hid_get_feature_report(SDL_hid_device *dev, unsigned char *data, size_t length);
+
+/**
+ * Close a HID device.
+ *
+ * \param dev A device handle returned from SDL_hid_open().
+ *
+ * \since This function is available since SDL 2.0.18.
+ */
+extern DECLSPEC void SDLCALL SDL_hid_close(SDL_hid_device *dev);
+
+/**
+ * Get The Manufacturer String from a HID device.
+ *
+ * \param dev A device handle returned from SDL_hid_open().
+ * \param string A wide string buffer to put the data into.
+ * \param maxlen The length of the buffer in multiples of wchar_t.
+ * \returns 0 on success and -1 on error.
+ *
+ * \since This function is available since SDL 2.0.18.
+ */
+extern DECLSPEC int SDLCALL SDL_hid_get_manufacturer_string(SDL_hid_device *dev, wchar_t *string, size_t maxlen);
+
+/**
+ * Get The Product String from a HID device.
+ *
+ * \param dev A device handle returned from SDL_hid_open().
+ * \param string A wide string buffer to put the data into.
+ * \param maxlen The length of the buffer in multiples of wchar_t.
+ * \returns 0 on success and -1 on error.
+ *
+ * \since This function is available since SDL 2.0.18.
+ */
+extern DECLSPEC int SDLCALL SDL_hid_get_product_string(SDL_hid_device *dev, wchar_t *string, size_t maxlen);
+
+/**
+ * Get The Serial Number String from a HID device.
+ *
+ * \param dev A device handle returned from SDL_hid_open().
+ * \param string A wide string buffer to put the data into.
+ * \param maxlen The length of the buffer in multiples of wchar_t.
+ * \returns 0 on success and -1 on error.
+ *
+ * \since This function is available since SDL 2.0.18.
+ */
+extern DECLSPEC int SDLCALL SDL_hid_get_serial_number_string(SDL_hid_device *dev, wchar_t *string, size_t maxlen);
+
+/**
+ * Get a string from a HID device, based on its string index.
+ *
+ * \param dev A device handle returned from SDL_hid_open().
+ * \param string_index The index of the string to get.
+ * \param string A wide string buffer to put the data into.
+ * \param maxlen The length of the buffer in multiples of wchar_t.
+ * \returns 0 on success and -1 on error.
+ *
+ * \since This function is available since SDL 2.0.18.
+ */
+extern DECLSPEC int SDLCALL SDL_hid_get_indexed_string(SDL_hid_device *dev, int string_index, wchar_t *string, size_t maxlen);
+
+/**
+ * Start or stop a BLE scan on iOS and tvOS to pair Steam Controllers
+ *
+ * \param active SDL_TRUE to start the scan, SDL_FALSE to stop the scan
+ *
+ * \since This function is available since SDL 2.0.18.
+ */
+extern DECLSPEC void SDLCALL SDL_hid_ble_scan(SDL_bool active);
+
+/* Ends C function definitions when using C++ */
+#ifdef __cplusplus
+}
+#endif
+#include "close_code.h"
+
+#endif /* SDL_hidapi_h_ */
+
+/* vi: set sts=4 ts=4 sw=4 expandtab: */

libs/SDL2/i686-w64-mingw32/include/SDL2/SDL_hints.h

 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -48,439 +48,575 @@ extern "C" {
 #endif
 
 /**
- *  \brief  A variable controlling how 3D acceleration is used to accelerate the SDL screen surface.
- *
- *  SDL can try to accelerate the SDL screen surface by using streaming
- *  textures with a 3D rendering engine.  This variable controls whether and
- *  how this is done.
+ *  \brief  A variable controlling whether the Android / iOS built-in
+ *  accelerometer should be listed as a joystick device.
  *
  *  This variable can be set to the following values:
- *    "0"       - Disable 3D acceleration
- *    "1"       - Enable 3D acceleration, using the default renderer.
- *    "X"       - Enable 3D acceleration, using X where X is one of the valid rendering drivers.  (e.g. "direct3d", "opengl", etc.)
- *
- *  By default SDL tries to make a best guess for each platform whether
- *  to use acceleration or not.
+ *    "0"       - The accelerometer is not listed as a joystick
+ *    "1"       - The accelerometer is available as a 3 axis joystick (the default).
  */
-#define SDL_HINT_FRAMEBUFFER_ACCELERATION   "SDL_FRAMEBUFFER_ACCELERATION"
+#define SDL_HINT_ACCELEROMETER_AS_JOYSTICK "SDL_ACCELEROMETER_AS_JOYSTICK"
 
 /**
- *  \brief  A variable specifying which render driver to use.
- *
- *  If the application doesn't pick a specific renderer to use, this variable
- *  specifies the name of the preferred renderer.  If the preferred renderer
- *  can't be initialized, the normal default renderer is used.
+ *  \brief Specify the behavior of Alt+Tab while the keyboard is grabbed.
  *
- *  This variable is case insensitive and can be set to the following values:
- *    "direct3d"
- *    "opengl"
- *    "opengles2"
- *    "opengles"
- *    "metal"
- *    "software"
+ * By default, SDL emulates Alt+Tab functionality while the keyboard is grabbed
+ * and your window is full-screen. This prevents the user from getting stuck in
+ * your application if you've enabled keyboard grab.
  *
- *  The default varies by platform, but it's the first one in the list that
- *  is available on the current platform.
- */
-#define SDL_HINT_RENDER_DRIVER              "SDL_RENDER_DRIVER"
+ * The variable can be set to the following values:
+ *   "0"       - SDL will not handle Alt+Tab. Your application is responsible
+                 for handling Alt+Tab while the keyboard is grabbed.
+ *   "1"       - SDL will minimize your window when Alt+Tab is pressed (default)
+*/
+#define SDL_HINT_ALLOW_ALT_TAB_WHILE_GRABBED "SDL_ALLOW_ALT_TAB_WHILE_GRABBED"
 
 /**
- *  \brief  A variable controlling whether the OpenGL render driver uses shaders if they are available.
+ *  \brief If set to "0" then never set the top most bit on a SDL Window, even if the video mode expects it.
+ *      This is a debugging aid for developers and not expected to be used by end users. The default is "1"
  *
  *  This variable can be set to the following values:
- *    "0"       - Disable shaders
- *    "1"       - Enable shaders
- *
- *  By default shaders are used if OpenGL supports them.
+ *    "0"       - don't allow topmost
+ *    "1"       - allow topmost
  */
-#define SDL_HINT_RENDER_OPENGL_SHADERS      "SDL_RENDER_OPENGL_SHADERS"
+#define SDL_HINT_ALLOW_TOPMOST "SDL_ALLOW_TOPMOST"
 
 /**
- *  \brief  A variable controlling whether the Direct3D device is initialized for thread-safe operations.
+ * \brief Android APK expansion main file version. Should be a string number like "1", "2" etc.
  *
- *  This variable can be set to the following values:
- *    "0"       - Thread-safety is not enabled (faster)
- *    "1"       - Thread-safety is enabled
+ * Must be set together with SDL_HINT_ANDROID_APK_EXPANSION_PATCH_FILE_VERSION.
  *
- *  By default the Direct3D device is created with thread-safety disabled.
+ * If both hints were set then SDL_RWFromFile() will look into expansion files
+ * after a given relative path was not found in the internal storage and assets.
+ *
+ * By default this hint is not set and the APK expansion files are not searched.
  */
-#define SDL_HINT_RENDER_DIRECT3D_THREADSAFE "SDL_RENDER_DIRECT3D_THREADSAFE"
+#define SDL_HINT_ANDROID_APK_EXPANSION_MAIN_FILE_VERSION "SDL_ANDROID_APK_EXPANSION_MAIN_FILE_VERSION"
 
 /**
- *  \brief  A variable controlling whether to enable Direct3D 11+'s Debug Layer.
+ * \brief Android APK expansion patch file version. Should be a string number like "1", "2" etc.
  *
- *  This variable does not have any effect on the Direct3D 9 based renderer.
+ * Must be set together with SDL_HINT_ANDROID_APK_EXPANSION_MAIN_FILE_VERSION.
  *
- *  This variable can be set to the following values:
- *    "0"       - Disable Debug Layer use
- *    "1"       - Enable Debug Layer use
+ * If both hints were set then SDL_RWFromFile() will look into expansion files
+ * after a given relative path was not found in the internal storage and assets.
  *
- *  By default, SDL does not use Direct3D Debug Layer.
+ * By default this hint is not set and the APK expansion files are not searched.
  */
-#define SDL_HINT_RENDER_DIRECT3D11_DEBUG    "SDL_RENDER_DIRECT3D11_DEBUG"
+#define SDL_HINT_ANDROID_APK_EXPANSION_PATCH_FILE_VERSION "SDL_ANDROID_APK_EXPANSION_PATCH_FILE_VERSION"
 
 /**
- *  \brief  A variable controlling the scaling policy for SDL_RenderSetLogicalSize.
+ * \brief A variable to control whether the event loop will block itself when the app is paused.
  *
- *  This variable can be set to the following values:
- *    "0" or "letterbox" - Uses letterbox/sidebars to fit the entire rendering on screen
- *    "1" or "overscan"  - Will zoom the rendering so it fills the entire screen, allowing edges to be drawn offscreen
+ * The variable can be set to the following values:
+ *   "0"       - Non blocking.
+ *   "1"       - Blocking. (default)
  *
- *  By default letterbox is used
+ * The value should be set before SDL is initialized.
  */
-#define SDL_HINT_RENDER_LOGICAL_SIZE_MODE       "SDL_RENDER_LOGICAL_SIZE_MODE"
+#define SDL_HINT_ANDROID_BLOCK_ON_PAUSE "SDL_ANDROID_BLOCK_ON_PAUSE"
 
 /**
- *  \brief  A variable controlling the scaling quality
+ * \brief A variable to control whether SDL will pause audio in background
+ *        (Requires SDL_ANDROID_BLOCK_ON_PAUSE as "Non blocking")
  *
- *  This variable can be set to the following values:
- *    "0" or "nearest" - Nearest pixel sampling
- *    "1" or "linear"  - Linear filtering (supported by OpenGL and Direct3D)
- *    "2" or "best"    - Currently this is the same as "linear"
+ * The variable can be set to the following values:
+ *   "0"       - Non paused.
+ *   "1"       - Paused. (default)
  *
- *  By default nearest pixel sampling is used
+ * The value should be set before SDL is initialized.
  */
-#define SDL_HINT_RENDER_SCALE_QUALITY       "SDL_RENDER_SCALE_QUALITY"
+#define SDL_HINT_ANDROID_BLOCK_ON_PAUSE_PAUSEAUDIO "SDL_ANDROID_BLOCK_ON_PAUSE_PAUSEAUDIO"
 
 /**
- *  \brief  A variable controlling whether updates to the SDL screen surface should be synchronized with the vertical refresh, to avoid tearing.
+ * \brief A variable to control whether we trap the Android back button to handle it manually.
+ *        This is necessary for the right mouse button to work on some Android devices, or
+ *        to be able to trap the back button for use in your code reliably.  If set to true,
+ *        the back button will show up as an SDL_KEYDOWN / SDL_KEYUP pair with a keycode of
+ *        SDL_SCANCODE_AC_BACK.
  *
- *  This variable can be set to the following values:
- *    "0"       - Disable vsync
- *    "1"       - Enable vsync
+ * The variable can be set to the following values:
+ *   "0"       - Back button will be handled as usual for system. (default)
+ *   "1"       - Back button will be trapped, allowing you to handle the key press
+ *               manually.  (This will also let right mouse click work on systems
+ *               where the right mouse button functions as back.)
  *
- *  By default SDL does not sync screen surface updates with vertical refresh.
+ * The value of this hint is used at runtime, so it can be changed at any time.
  */
-#define SDL_HINT_RENDER_VSYNC               "SDL_RENDER_VSYNC"
+#define SDL_HINT_ANDROID_TRAP_BACK_BUTTON "SDL_ANDROID_TRAP_BACK_BUTTON"
 
 /**
- *  \brief  A variable controlling whether the screensaver is enabled. 
+ *  \brief Specify an application name.
  *
- *  This variable can be set to the following values:
- *    "0"       - Disable screensaver
- *    "1"       - Enable screensaver
+ * This hint lets you specify the application name sent to the OS when
+ * required. For example, this will often appear in volume control applets for
+ * audio streams, and in lists of applications which are inhibiting the
+ * screensaver.  You should use a string that describes your program ("My Game
+ * 2: The Revenge")
  *
- *  By default SDL will disable the screensaver.
+ * Setting this to "" or leaving it unset will have SDL use a reasonable
+ * default: probably the application's name or "SDL Application" if SDL
+ * doesn't have any better information.
+ *
+ * Note that, for audio streams, this can be overridden with
+ * SDL_HINT_AUDIO_DEVICE_APP_NAME.
+ *
+ * On targets where this is not supported, this hint does nothing.
  */
-#define SDL_HINT_VIDEO_ALLOW_SCREENSAVER    "SDL_VIDEO_ALLOW_SCREENSAVER"
+#define SDL_HINT_APP_NAME "SDL_APP_NAME"
 
 /**
- *  \brief  A variable controlling whether the X11 VidMode extension should be used.
+ *  \brief  A variable controlling whether controllers used with the Apple TV
+ *  generate UI events.
  *
- *  This variable can be set to the following values:
- *    "0"       - Disable XVidMode
- *    "1"       - Enable XVidMode
+ * When UI events are generated by controller input, the app will be
+ * backgrounded when the Apple TV remote's menu button is pressed, and when the
+ * pause or B buttons on gamepads are pressed.
+ *
+ * More information about properly making use of controllers for the Apple TV
+ * can be found here:
+ * https://developer.apple.com/tvos/human-interface-guidelines/remote-and-controllers/
  *
- *  By default SDL will use XVidMode if it is available.
+ *  This variable can be set to the following values:
+ *    "0"       - Controller input does not generate UI events (the default).
+ *    "1"       - Controller input generates UI events.
  */
-#define SDL_HINT_VIDEO_X11_XVIDMODE         "SDL_VIDEO_X11_XVIDMODE"
+#define SDL_HINT_APPLE_TV_CONTROLLER_UI_EVENTS "SDL_APPLE_TV_CONTROLLER_UI_EVENTS"
 
 /**
- *  \brief  A variable controlling whether the X11 Xinerama extension should be used.
+ * \brief  A variable controlling whether the Apple TV remote's joystick axes
+ *         will automatically match the rotation of the remote.
  *
  *  This variable can be set to the following values:
- *    "0"       - Disable Xinerama
- *    "1"       - Enable Xinerama
- *
- *  By default SDL will use Xinerama if it is available.
+ *    "0"       - Remote orientation does not affect joystick axes (the default).
+ *    "1"       - Joystick axes are based on the orientation of the remote.
  */
-#define SDL_HINT_VIDEO_X11_XINERAMA         "SDL_VIDEO_X11_XINERAMA"
+#define SDL_HINT_APPLE_TV_REMOTE_ALLOW_ROTATION "SDL_APPLE_TV_REMOTE_ALLOW_ROTATION"
 
 /**
- *  \brief  A variable controlling whether the X11 XRandR extension should be used.
+ *  \brief  A variable controlling the audio category on iOS and Mac OS X
  *
  *  This variable can be set to the following values:
- *    "0"       - Disable XRandR
- *    "1"       - Enable XRandR
  *
- *  By default SDL will not use XRandR because of window manager issues.
+ *    "ambient"     - Use the AVAudioSessionCategoryAmbient audio category, will be muted by the phone mute switch (default)
+ *    "playback"    - Use the AVAudioSessionCategoryPlayback category
+ *
+ *  For more information, see Apple's documentation:
+ *  https://developer.apple.com/library/content/documentation/Audio/Conceptual/AudioSessionProgrammingGuide/AudioSessionCategoriesandModes/AudioSessionCategoriesandModes.html
  */
-#define SDL_HINT_VIDEO_X11_XRANDR           "SDL_VIDEO_X11_XRANDR"
+#define SDL_HINT_AUDIO_CATEGORY   "SDL_AUDIO_CATEGORY"
 
 /**
- *  \brief  A variable controlling whether the X11 _NET_WM_PING protocol should be supported.
+ *  \brief Specify an application name for an audio device.
  *
- *  This variable can be set to the following values:
- *    "0"       - Disable _NET_WM_PING
- *    "1"       - Enable _NET_WM_PING
+ * Some audio backends (such as PulseAudio) allow you to describe your audio
+ * stream. Among other things, this description might show up in a system
+ * control panel that lets the user adjust the volume on specific audio
+ * streams instead of using one giant master volume slider.
  *
- *  By default SDL will use _NET_WM_PING, but for applications that know they
- *  will not always be able to respond to ping requests in a timely manner they can
- *  turn it off to avoid the window manager thinking the app is hung.
- *  The hint is checked in CreateWindow.
+ * This hints lets you transmit that information to the OS. The contents of
+ * this hint are used while opening an audio device. You should use a string
+ * that describes your program ("My Game 2: The Revenge")
+ *
+ * Setting this to "" or leaving it unset will have SDL use a reasonable
+ * default: this will be the name set with SDL_HINT_APP_NAME, if that hint is
+ * set. Otherwise, it'll probably the application's name or "SDL Application"
+ * if SDL doesn't have any better information.
+ *
+ * On targets where this is not supported, this hint does nothing.
  */
-#define SDL_HINT_VIDEO_X11_NET_WM_PING      "SDL_VIDEO_X11_NET_WM_PING"
+#define SDL_HINT_AUDIO_DEVICE_APP_NAME "SDL_AUDIO_DEVICE_APP_NAME"
 
 /**
- * \brief A variable controlling whether the X11 _NET_WM_BYPASS_COMPOSITOR hint should be used.
- * 
- * This variable can be set to the following values:
- * "0" - Disable _NET_WM_BYPASS_COMPOSITOR
- * "1" - Enable _NET_WM_BYPASS_COMPOSITOR
- * 
- * By default SDL will use _NET_WM_BYPASS_COMPOSITOR
- * 
+ *  \brief Specify an application name for an audio device.
+ *
+ * Some audio backends (such as PulseAudio) allow you to describe your audio
+ * stream. Among other things, this description might show up in a system
+ * control panel that lets the user adjust the volume on specific audio
+ * streams instead of using one giant master volume slider.
+ *
+ * This hints lets you transmit that information to the OS. The contents of
+ * this hint are used while opening an audio device. You should use a string
+ * that describes your what your program is playing ("audio stream" is
+ * probably sufficient in many cases, but this could be useful for something
+ * like "team chat" if you have a headset playing VoIP audio separately).
+ *
+ * Setting this to "" or leaving it unset will have SDL use a reasonable
+ * default: "audio stream" or something similar.
+ *
+ * On targets where this is not supported, this hint does nothing.
  */
-#define SDL_HINT_VIDEO_X11_NET_WM_BYPASS_COMPOSITOR "SDL_VIDEO_X11_NET_WM_BYPASS_COMPOSITOR"
+#define SDL_HINT_AUDIO_DEVICE_STREAM_NAME "SDL_AUDIO_DEVICE_STREAM_NAME"
 
 /**
- *  \brief  A variable controlling whether the window frame and title bar are interactive when the cursor is hidden 
+ *  \brief Specify an application role for an audio device.
  *
- *  This variable can be set to the following values:
- *    "0"       - The window frame is not interactive when the cursor is hidden (no move, resize, etc)
- *    "1"       - The window frame is interactive when the cursor is hidden
+ * Some audio backends (such as Pipewire) allow you to describe the role of
+ * your audio stream. Among other things, this description might show up in
+ * a system control panel or software for displaying and manipulating media
+ * playback/capture graphs.
  *
- *  By default SDL will allow interaction with the window frame when the cursor is hidden
+ * This hints lets you transmit that information to the OS. The contents of
+ * this hint are used while opening an audio device. You should use a string
+ * that describes your what your program is playing (Game, Music, Movie,
+ * etc...).
+ *
+ * Setting this to "" or leaving it unset will have SDL use a reasonable
+ * default: "Game" or something similar.
+ *
+ * On targets where this is not supported, this hint does nothing.
  */
-#define SDL_HINT_WINDOW_FRAME_USABLE_WHILE_CURSOR_HIDDEN    "SDL_WINDOW_FRAME_USABLE_WHILE_CURSOR_HIDDEN"
+#define SDL_HINT_AUDIO_DEVICE_STREAM_ROLE "SDL_AUDIO_DEVICE_STREAM_ROLE"
 
 /**
- * \brief A variable to specify custom icon resource id from RC file on Windows platform 
+ *  \brief  A variable controlling speed/quality tradeoff of audio resampling.
+ *
+ *  If available, SDL can use libsamplerate ( http://www.mega-nerd.com/SRC/ )
+ *  to handle audio resampling. There are different resampling modes available
+ *  that produce different levels of quality, using more CPU.
+ *
+ *  If this hint isn't specified to a valid setting, or libsamplerate isn't
+ *  available, SDL will use the default, internal resampling algorithm.
+ *
+ *  As of SDL 2.26, SDL_ConvertAudio() respects this hint when libsamplerate is available.
+ *
+ *  This hint is currently only checked at audio subsystem initialization.
+ *
+ *  This variable can be set to the following values:
+ *
+ *    "0" or "default" - Use SDL's internal resampling (Default when not set - low quality, fast)
+ *    "1" or "fast"    - Use fast, slightly higher quality resampling, if available
+ *    "2" or "medium"  - Use medium quality resampling, if available
+ *    "3" or "best"    - Use high quality resampling, if available
  */
-#define SDL_HINT_WINDOWS_INTRESOURCE_ICON       "SDL_WINDOWS_INTRESOURCE_ICON"
-#define SDL_HINT_WINDOWS_INTRESOURCE_ICON_SMALL "SDL_WINDOWS_INTRESOURCE_ICON_SMALL"
+#define SDL_HINT_AUDIO_RESAMPLING_MODE   "SDL_AUDIO_RESAMPLING_MODE"
 
 /**
- *  \brief  A variable controlling whether the windows message loop is processed by SDL 
+ *  \brief  A variable controlling whether SDL updates joystick state when getting input events
  *
  *  This variable can be set to the following values:
- *    "0"       - The window message loop is not run
- *    "1"       - The window message loop is processed in SDL_PumpEvents()
  *
- *  By default SDL will process the windows message loop
+ *    "0"     - You'll call SDL_JoystickUpdate() manually
+ *    "1"     - SDL will automatically call SDL_JoystickUpdate() (default)
+ *
+ *  This hint can be toggled on and off at runtime.
  */
-#define SDL_HINT_WINDOWS_ENABLE_MESSAGELOOP "SDL_WINDOWS_ENABLE_MESSAGELOOP"
+#define SDL_HINT_AUTO_UPDATE_JOYSTICKS  "SDL_AUTO_UPDATE_JOYSTICKS"
 
 /**
- *  \brief  A variable controlling whether grabbing input grabs the keyboard
+ *  \brief  A variable controlling whether SDL updates sensor state when getting input events
  *
  *  This variable can be set to the following values:
- *    "0"       - Grab will affect only the mouse
- *    "1"       - Grab will affect mouse and keyboard
  *
- *  By default SDL will not grab the keyboard so system shortcuts still work.
+ *    "0"     - You'll call SDL_SensorUpdate() manually
+ *    "1"     - SDL will automatically call SDL_SensorUpdate() (default)
+ *
+ *  This hint can be toggled on and off at runtime.
  */
-#define SDL_HINT_GRAB_KEYBOARD              "SDL_GRAB_KEYBOARD"
+#define SDL_HINT_AUTO_UPDATE_SENSORS    "SDL_AUTO_UPDATE_SENSORS"
 
 /**
- *  \brief  A variable setting the double click time, in milliseconds.
+ *  \brief Prevent SDL from using version 4 of the bitmap header when saving BMPs.
+ *
+ * The bitmap header version 4 is required for proper alpha channel support and
+ * SDL will use it when required. Should this not be desired, this hint can
+ * force the use of the 40 byte header version which is supported everywhere.
+ *
+ * The variable can be set to the following values:
+ *   "0"       - Surfaces with a colorkey or an alpha channel are saved to a
+ *               32-bit BMP file with an alpha mask. SDL will use the bitmap
+ *               header version 4 and set the alpha mask accordingly.
+ *   "1"       - Surfaces with a colorkey or an alpha channel are saved to a
+ *               32-bit BMP file without an alpha mask. The alpha channel data
+ *               will be in the file, but applications are going to ignore it.
+ *
+ * The default value is "0".
  */
-#define SDL_HINT_MOUSE_DOUBLE_CLICK_TIME    "SDL_MOUSE_DOUBLE_CLICK_TIME"
+#define SDL_HINT_BMP_SAVE_LEGACY_FORMAT "SDL_BMP_SAVE_LEGACY_FORMAT"
 
 /**
- *  \brief  A variable setting the double click radius, in pixels.
+ *  \brief Override for SDL_GetDisplayUsableBounds()
+ *
+ *  If set, this hint will override the expected results for
+ *  SDL_GetDisplayUsableBounds() for display index 0. Generally you don't want
+ *  to do this, but this allows an embedded system to request that some of the
+ *  screen be reserved for other uses when paired with a well-behaved
+ *  application.
+ *
+ *  The contents of this hint must be 4 comma-separated integers, the first
+ *  is the bounds x, then y, width and height, in that order.
  */
-#define SDL_HINT_MOUSE_DOUBLE_CLICK_RADIUS    "SDL_MOUSE_DOUBLE_CLICK_RADIUS"
+#define SDL_HINT_DISPLAY_USABLE_BOUNDS "SDL_DISPLAY_USABLE_BOUNDS"
 
 /**
- *  \brief  A variable setting the speed scale for mouse motion, in floating point, when the mouse is not in relative mode
+ *  \brief Disable giving back control to the browser automatically
+ *  when running with asyncify
+ *
+ * With -s ASYNCIFY, SDL2 calls emscripten_sleep during operations
+ * such as refreshing the screen or polling events.
+ *
+ * This hint only applies to the emscripten platform
+ *
+ * The variable can be set to the following values:
+ *    "0"       - Disable emscripten_sleep calls (if you give back browser control manually or use asyncify for other purposes)
+ *    "1"       - Enable emscripten_sleep calls (the default)
  */
-#define SDL_HINT_MOUSE_NORMAL_SPEED_SCALE    "SDL_MOUSE_NORMAL_SPEED_SCALE"
+#define SDL_HINT_EMSCRIPTEN_ASYNCIFY   "SDL_EMSCRIPTEN_ASYNCIFY"
 
 /**
- *  \brief  A variable setting the scale for mouse motion, in floating point, when the mouse is in relative mode
+ *  \brief override the binding element for keyboard inputs for Emscripten builds
+ *
+ * This hint only applies to the emscripten platform
+ *
+ * The variable can be one of
+ *    "#window"      - The javascript window object (this is the default)
+ *    "#document"    - The javascript document object
+ *    "#screen"      - the javascript window.screen object
+ *    "#canvas"      - the WebGL canvas element
+ *    any other string without a leading # sign applies to the element on the page with that ID.
  */
-#define SDL_HINT_MOUSE_RELATIVE_SPEED_SCALE    "SDL_MOUSE_RELATIVE_SPEED_SCALE"
+#define SDL_HINT_EMSCRIPTEN_KEYBOARD_ELEMENT   "SDL_EMSCRIPTEN_KEYBOARD_ELEMENT"
 
 /**
- *  \brief  A variable controlling whether relative mouse mode is implemented using mouse warping
+ *  \brief  A variable that controls whether the on-screen keyboard should be shown when text input is active
  *
- *  This variable can be set to the following values:
- *    "0"       - Relative mouse mode uses raw input
- *    "1"       - Relative mouse mode uses mouse warping
+ *  The variable can be set to the following values:
+ *    "0"       - Do not show the on-screen keyboard
+ *    "1"       - Show the on-screen keyboard
  *
- *  By default SDL will use raw input for relative mouse mode
+ *  The default value is "1". This hint must be set before text input is activated.
  */
-#define SDL_HINT_MOUSE_RELATIVE_MODE_WARP    "SDL_MOUSE_RELATIVE_MODE_WARP"
+#define SDL_HINT_ENABLE_SCREEN_KEYBOARD "SDL_ENABLE_SCREEN_KEYBOARD"
 
 /**
- *  \brief Allow mouse click events when clicking to focus an SDL window
+ *  \brief  A variable that controls whether Steam Controllers should be exposed using the SDL joystick and game controller APIs
  *
- *  This variable can be set to the following values:
- *    "0"       - Ignore mouse clicks that activate a window
- *    "1"       - Generate events for mouse clicks that activate a window
+ *  The variable can be set to the following values:
+ *    "0"       - Do not scan for Steam Controllers
+ *    "1"       - Scan for Steam Controllers (the default)
  *
- *  By default SDL will ignore mouse clicks that activate a window
+ *  The default value is "1".  This hint must be set before initializing the joystick subsystem.
  */
-#define SDL_HINT_MOUSE_FOCUS_CLICKTHROUGH "SDL_MOUSE_FOCUS_CLICKTHROUGH"
+#define SDL_HINT_ENABLE_STEAM_CONTROLLERS "SDL_ENABLE_STEAM_CONTROLLERS"
 
 /**
- *  \brief  A variable controlling whether touch events should generate synthetic mouse events
+ *  \brief  A variable controlling verbosity of the logging of SDL events pushed onto the internal queue.
  *
- *  This variable can be set to the following values:
- *    "0"       - Touch events will not generate mouse events
- *    "1"       - Touch events will generate mouse events
+ *  This variable can be set to the following values, from least to most verbose:
  *
- *  By default SDL will generate mouse events for touch events
+ *    "0"     - Don't log any events (default)
+ *    "1"     - Log most events (other than the really spammy ones).
+ *    "2"     - Include mouse and finger motion events.
+ *    "3"     - Include SDL_SysWMEvent events.
+ *
+ *  This is generally meant to be used to debug SDL itself, but can be useful
+ *  for application developers that need better visibility into what is going
+ *  on in the event queue. Logged events are sent through SDL_Log(), which
+ *  means by default they appear on stdout on most platforms or maybe
+ *  OutputDebugString() on Windows, and can be funneled by the app with
+ *  SDL_LogSetOutputFunction(), etc.
+ *
+ *  This hint can be toggled on and off at runtime, if you only need to log
+ *  events for a small subset of program execution.
  */
-#define SDL_HINT_TOUCH_MOUSE_EVENTS    "SDL_TOUCH_MOUSE_EVENTS"
+#define SDL_HINT_EVENT_LOGGING   "SDL_EVENT_LOGGING"
 
 /**
- *  \brief  A variable controlling whether mouse events should generate synthetic touch events
+ *  \brief  A variable controlling whether raising the window should be done more forcefully
  *
  *  This variable can be set to the following values:
- *    "0"       - Mouse events will not generate touch events (default for desktop platforms)
- *    "1"       - Mouse events will generate touch events (default for mobile platforms, such as Android and iOS)
+ *    "0"       - No forcing (the default)
+ *    "1"       - Extra level of forcing
+ *
+ *  At present, this is only an issue under MS Windows, which makes it nearly impossible to
+ *  programmatically move a window to the foreground, for "security" reasons. See
+ *  http://stackoverflow.com/a/34414846 for a discussion.
  */
-
-#define SDL_HINT_MOUSE_TOUCH_EVENTS    "SDL_MOUSE_TOUCH_EVENTS"
+#define SDL_HINT_FORCE_RAISEWINDOW    "SDL_HINT_FORCE_RAISEWINDOW"
 
 /**
- *  \brief Minimize your SDL_Window if it loses key focus when in fullscreen mode. Defaults to true.
+ *  \brief  A variable controlling how 3D acceleration is used to accelerate the SDL screen surface.
+ *
+ *  SDL can try to accelerate the SDL screen surface by using streaming
+ *  textures with a 3D rendering engine.  This variable controls whether and
+ *  how this is done.
+ *
+ *  This variable can be set to the following values:
+ *    "0"       - Disable 3D acceleration
+ *    "1"       - Enable 3D acceleration, using the default renderer.
+ *    "X"       - Enable 3D acceleration, using X where X is one of the valid rendering drivers.  (e.g. "direct3d", "opengl", etc.)
  *
+ *  By default SDL tries to make a best guess for each platform whether
+ *  to use acceleration or not.
  */
-#define SDL_HINT_VIDEO_MINIMIZE_ON_FOCUS_LOSS   "SDL_VIDEO_MINIMIZE_ON_FOCUS_LOSS"
+#define SDL_HINT_FRAMEBUFFER_ACCELERATION   "SDL_FRAMEBUFFER_ACCELERATION"
 
 /**
- *  \brief  A variable controlling whether the idle timer is disabled on iOS.
- *
- *  When an iOS app does not receive touches for some time, the screen is
- *  dimmed automatically. For games where the accelerometer is the only input
- *  this is problematic. This functionality can be disabled by setting this
- *  hint.
+ *  \brief  A variable that lets you manually hint extra gamecontroller db entries.
  *
- *  As of SDL 2.0.4, SDL_EnableScreenSaver() and SDL_DisableScreenSaver()
- *  accomplish the same thing on iOS. They should be preferred over this hint.
+ *  The variable should be newline delimited rows of gamecontroller config data, see SDL_gamecontroller.h
  *
- *  This variable can be set to the following values:
- *    "0"       - Enable idle timer
- *    "1"       - Disable idle timer
+ *  This hint must be set before calling SDL_Init(SDL_INIT_GAMECONTROLLER)
+ *  You can update mappings after the system is initialized with SDL_GameControllerMappingForGUID() and SDL_GameControllerAddMapping()
  */
-#define SDL_HINT_IDLE_TIMER_DISABLED "SDL_IOS_IDLE_TIMER_DISABLED"
+#define SDL_HINT_GAMECONTROLLERCONFIG "SDL_GAMECONTROLLERCONFIG"
 
 /**
- *  \brief  A variable controlling which orientations are allowed on iOS/Android.
+ *  \brief  A variable that lets you provide a file with extra gamecontroller db entries.
  *
- *  In some circumstances it is necessary to be able to explicitly control
- *  which UI orientations are allowed.
+ *  The file should contain lines of gamecontroller config data, see SDL_gamecontroller.h
  *
- *  This variable is a space delimited list of the following values:
- *    "LandscapeLeft", "LandscapeRight", "Portrait" "PortraitUpsideDown"
+ *  This hint must be set before calling SDL_Init(SDL_INIT_GAMECONTROLLER)
+ *  You can update mappings after the system is initialized with SDL_GameControllerMappingForGUID() and SDL_GameControllerAddMapping()
  */
-#define SDL_HINT_ORIENTATIONS "SDL_IOS_ORIENTATIONS"
+#define SDL_HINT_GAMECONTROLLERCONFIG_FILE "SDL_GAMECONTROLLERCONFIG_FILE"
 
 /**
- *  \brief  A variable controlling whether controllers used with the Apple TV
- *  generate UI events.
+ *  \brief  A variable that overrides the automatic controller type detection
  *
- * When UI events are generated by controller input, the app will be
- * backgrounded when the Apple TV remote's menu button is pressed, and when the
- * pause or B buttons on gamepads are pressed.
+ *  The variable should be comma separated entries, in the form: VID/PID=type
  *
- * More information about properly making use of controllers for the Apple TV
- * can be found here:
- * https://developer.apple.com/tvos/human-interface-guidelines/remote-and-controllers/
+ *  The VID and PID should be hexadecimal with exactly 4 digits, e.g. 0x00fd
  *
- *  This variable can be set to the following values:
- *    "0"       - Controller input does not generate UI events (the default).
- *    "1"       - Controller input generates UI events.
+ *  The type should be one of:
+ *      Xbox360
+ *      XboxOne
+ *      PS3
+ *      PS4
+ *      PS5
+ *      SwitchPro
+ *
+ *  This hint affects what driver is used, and must be set before calling SDL_Init(SDL_INIT_GAMECONTROLLER)
  */
-#define SDL_HINT_APPLE_TV_CONTROLLER_UI_EVENTS "SDL_APPLE_TV_CONTROLLER_UI_EVENTS"
+#define SDL_HINT_GAMECONTROLLERTYPE "SDL_GAMECONTROLLERTYPE"
 
 /**
- * \brief  A variable controlling whether the Apple TV remote's joystick axes
- *         will automatically match the rotation of the remote.
+ *  \brief  A variable containing a list of devices to skip when scanning for game controllers.
  *
- *  This variable can be set to the following values:
- *    "0"       - Remote orientation does not affect joystick axes (the default).
- *    "1"       - Joystick axes are based on the orientation of the remote.
+ *  The format of the string is a comma separated list of USB VID/PID pairs
+ *  in hexadecimal form, e.g.
+ *
+ *      0xAAAA/0xBBBB,0xCCCC/0xDDDD
+ *
+ *  The variable can also take the form of @file, in which case the named
+ *  file will be loaded and interpreted as the value of the variable.
  */
-#define SDL_HINT_APPLE_TV_REMOTE_ALLOW_ROTATION "SDL_APPLE_TV_REMOTE_ALLOW_ROTATION"
+#define SDL_HINT_GAMECONTROLLER_IGNORE_DEVICES "SDL_GAMECONTROLLER_IGNORE_DEVICES"
 
 /**
- * \brief  A variable controlling whether the home indicator bar on iPhone X
- *         should be hidden.
+ *  \brief  If set, all devices will be skipped when scanning for game controllers except for the ones listed in this variable.
  *
- *  This variable can be set to the following values:
- *    "0"       - The indicator bar is not hidden (default for windowed applications)
- *    "1"       - The indicator bar is hidden and is shown when the screen is touched (useful for movie playback applications)
- *    "2"       - The indicator bar is dim and the first swipe makes it visible and the second swipe performs the "home" action (default for fullscreen applications)
+ *  The format of the string is a comma separated list of USB VID/PID pairs
+ *  in hexadecimal form, e.g.
+ *
+ *      0xAAAA/0xBBBB,0xCCCC/0xDDDD
+ *
+ *  The variable can also take the form of @file, in which case the named
+ *  file will be loaded and interpreted as the value of the variable.
  */
-#define SDL_HINT_IOS_HIDE_HOME_INDICATOR "SDL_IOS_HIDE_HOME_INDICATOR"
+#define SDL_HINT_GAMECONTROLLER_IGNORE_DEVICES_EXCEPT "SDL_GAMECONTROLLER_IGNORE_DEVICES_EXCEPT"
 
 /**
- *  \brief  A variable controlling whether the Android / iOS built-in
- *  accelerometer should be listed as a joystick device.
+ *  \brief  If set, game controller face buttons report their values according to their labels instead of their positional layout.
  *
- *  This variable can be set to the following values:
- *    "0"       - The accelerometer is not listed as a joystick
- *    "1"       - The accelerometer is available as a 3 axis joystick (the default).
+ *  For example, on Nintendo Switch controllers, normally you'd get:
+ *
+ *      (Y)
+ *  (X)     (B)
+ *      (A)
+ *
+ *  but if this hint is set, you'll get:
+ *
+ *      (X)
+ *  (Y)     (A)
+ *      (B)
+ *
+ *  The variable can be set to the following values:
+ *    "0"       - Report the face buttons by position, as though they were on an Xbox controller.
+ *    "1"       - Report the face buttons by label instead of position
+ *
+ *  The default value is "1".  This hint may be set at any time.
  */
-#define SDL_HINT_ACCELEROMETER_AS_JOYSTICK "SDL_ACCELEROMETER_AS_JOYSTICK"
+#define SDL_HINT_GAMECONTROLLER_USE_BUTTON_LABELS "SDL_GAMECONTROLLER_USE_BUTTON_LABELS"
 
 /**
- *  \brief  A variable controlling whether the Android / tvOS remotes
- *  should be listed as joystick devices, instead of sending keyboard events.
+ *  \brief  A variable controlling whether grabbing input grabs the keyboard
  *
  *  This variable can be set to the following values:
- *    "0"       - Remotes send enter/escape/arrow key events
- *    "1"       - Remotes are available as 2 axis, 2 button joysticks (the default).
+ *    "0"       - Grab will affect only the mouse
+ *    "1"       - Grab will affect mouse and keyboard
+ *
+ *  By default SDL will not grab the keyboard so system shortcuts still work.
  */
-#define SDL_HINT_TV_REMOTE_AS_JOYSTICK "SDL_TV_REMOTE_AS_JOYSTICK"
+#define SDL_HINT_GRAB_KEYBOARD              "SDL_GRAB_KEYBOARD"
 
 /**
- *  \brief  A variable that lets you disable the detection and use of Xinput gamepad devices
+ *  \brief  A variable containing a list of devices to ignore in SDL_hid_enumerate()
  *
- *  The variable can be set to the following values:
- *    "0"       - Disable XInput detection (only uses direct input)
- *    "1"       - Enable XInput detection (the default)
+ *  For example, to ignore the Shanwan DS3 controller and any Valve controller, you might
+ *  have the string "0x2563/0x0523,0x28de/0x0000"
  */
-#define SDL_HINT_XINPUT_ENABLED "SDL_XINPUT_ENABLED"
+#define SDL_HINT_HIDAPI_IGNORE_DEVICES "SDL_HIDAPI_IGNORE_DEVICES"
 
 /**
- *  \brief  A variable that causes SDL to use the old axis and button mapping for XInput devices.
+ *  \brief  A variable controlling whether the idle timer is disabled on iOS.
  *
- *  This hint is for backwards compatibility only and will be removed in SDL 2.1
+ *  When an iOS app does not receive touches for some time, the screen is
+ *  dimmed automatically. For games where the accelerometer is the only input
+ *  this is problematic. This functionality can be disabled by setting this
+ *  hint.
  *
- *  The default value is "0".  This hint must be set before SDL_Init()
+ *  As of SDL 2.0.4, SDL_EnableScreenSaver() and SDL_DisableScreenSaver()
+ *  accomplish the same thing on iOS. They should be preferred over this hint.
+ *
+ *  This variable can be set to the following values:
+ *    "0"       - Enable idle timer
+ *    "1"       - Disable idle timer
  */
-#define SDL_HINT_XINPUT_USE_OLD_JOYSTICK_MAPPING "SDL_XINPUT_USE_OLD_JOYSTICK_MAPPING"
+#define SDL_HINT_IDLE_TIMER_DISABLED "SDL_IOS_IDLE_TIMER_DISABLED"
 
 /**
- *  \brief  A variable that lets you manually hint extra gamecontroller db entries.
- *
- *  The variable should be newline delimited rows of gamecontroller config data, see SDL_gamecontroller.h
+ * \brief A variable to control whether certain IMEs should handle text editing internally instead of sending SDL_TEXTEDITING events.
  *
- *  This hint must be set before calling SDL_Init(SDL_INIT_GAMECONTROLLER)
- *  You can update mappings after the system is initialized with SDL_GameControllerMappingForGUID() and SDL_GameControllerAddMapping()
+ * The variable can be set to the following values:
+ *   "0"       - SDL_TEXTEDITING events are sent, and it is the application's
+ *               responsibility to render the text from these events and
+ *               differentiate it somehow from committed text. (default)
+ *   "1"       - If supported by the IME then SDL_TEXTEDITING events are not sent,
+ *               and text that is being composed will be rendered in its own UI.
  */
-#define SDL_HINT_GAMECONTROLLERCONFIG "SDL_GAMECONTROLLERCONFIG"
+#define SDL_HINT_IME_INTERNAL_EDITING "SDL_IME_INTERNAL_EDITING"
 
 /**
- *  \brief  A variable that lets you provide a file with extra gamecontroller db entries.
- *
- *  The file should contain lines of gamecontroller config data, see SDL_gamecontroller.h
+ * \brief A variable to control whether certain IMEs should show native UI components (such as the Candidate List) instead of suppressing them.
  *
- *  This hint must be set before calling SDL_Init(SDL_INIT_GAMECONTROLLER)
- *  You can update mappings after the system is initialized with SDL_GameControllerMappingForGUID() and SDL_GameControllerAddMapping()
+ * The variable can be set to the following values:
+ *   "0"       - Native UI components are not display. (default)
+ *   "1"       - Native UI components are displayed.
  */
-#define SDL_HINT_GAMECONTROLLERCONFIG_FILE "SDL_GAMECONTROLLERCONFIG_FILE"
+#define SDL_HINT_IME_SHOW_UI "SDL_IME_SHOW_UI"
 
 /**
- *  \brief  A variable containing a list of devices to skip when scanning for game controllers.
- *
- *  The format of the string is a comma separated list of USB VID/PID pairs
- *  in hexadecimal form, e.g.
- *
- *      0xAAAA/0xBBBB,0xCCCC/0xDDDD
+ * \brief A variable to control if extended IME text support is enabled.
+ * If enabled then SDL_TextEditingExtEvent will be issued if the text would be truncated otherwise.
+ * Additionally SDL_TextInputEvent will be dispatched multiple times so that it is not truncated.
  *
- *  The variable can also take the form of @file, in which case the named
- *  file will be loaded and interpreted as the value of the variable.
+ * The variable can be set to the following values:
+ *   "0"       - Legacy behavior. Text can be truncated, no heap allocations. (default)
+ *   "1"       - Modern behavior.
  */
-#define SDL_HINT_GAMECONTROLLER_IGNORE_DEVICES "SDL_GAMECONTROLLER_IGNORE_DEVICES"
+#define SDL_HINT_IME_SUPPORT_EXTENDED_TEXT "SDL_IME_SUPPORT_EXTENDED_TEXT"
 
 /**
- *  \brief  If set, all devices will be skipped when scanning for game controllers except for the ones listed in this variable.
- *
- *  The format of the string is a comma separated list of USB VID/PID pairs
- *  in hexadecimal form, e.g.
- *
- *      0xAAAA/0xBBBB,0xCCCC/0xDDDD
+ * \brief  A variable controlling whether the home indicator bar on iPhone X
+ *         should be hidden.
  *
- *  The variable can also take the form of @file, in which case the named
- *  file will be loaded and interpreted as the value of the variable.
+ *  This variable can be set to the following values:
+ *    "0"       - The indicator bar is not hidden (default for windowed applications)
+ *    "1"       - The indicator bar is hidden and is shown when the screen is touched (useful for movie playback applications)
+ *    "2"       - The indicator bar is dim and the first swipe makes it visible and the second swipe performs the "home" action (default for fullscreen applications)
  */
-#define SDL_HINT_GAMECONTROLLER_IGNORE_DEVICES_EXCEPT "SDL_GAMECONTROLLER_IGNORE_DEVICES_EXCEPT"
+#define SDL_HINT_IOS_HIDE_HOME_INDICATOR "SDL_IOS_HIDE_HOME_INDICATOR"
 
 /**
  *  \brief  A variable that lets you enable joystick (and gamecontroller) events even when your app is in the background.
@@ -506,6 +642,110 @@ extern "C" {
  */
 #define SDL_HINT_JOYSTICK_HIDAPI "SDL_JOYSTICK_HIDAPI"
 
+/**
+ *  \brief  A variable controlling whether the HIDAPI driver for Nintendo GameCube controllers should be used.
+ *
+ *  This variable can be set to the following values:
+ *    "0"       - HIDAPI driver is not used
+ *    "1"       - HIDAPI driver is used
+ *
+ *  The default is the value of SDL_HINT_JOYSTICK_HIDAPI
+ */
+#define SDL_HINT_JOYSTICK_HIDAPI_GAMECUBE "SDL_JOYSTICK_HIDAPI_GAMECUBE"
+
+/**
+ *  \brief  A variable controlling whether "low_frequency_rumble" and "high_frequency_rumble" is used to implement
+ *          the GameCube controller's 3 rumble modes, Stop(0), Rumble(1), and StopHard(2)
+ *          this is useful for applications that need full compatibility for things like ADSR envelopes.
+ *          Stop is implemented by setting "low_frequency_rumble" to "0" and "high_frequency_rumble" ">0"
+ *          Rumble is both at any arbitrary value,
+ *          StopHard is implemented by setting both "low_frequency_rumble" and "high_frequency_rumble" to "0"
+ *
+ *  This variable can be set to the following values:
+ *    "0"       - Normal rumble behavior is behavior is used (default)
+ *    "1"       - Proper GameCube controller rumble behavior is used
+ *
+ */
+#define SDL_HINT_JOYSTICK_GAMECUBE_RUMBLE_BRAKE "SDL_JOYSTICK_GAMECUBE_RUMBLE_BRAKE"
+
+/**
+  *  \brief  A variable controlling whether the HIDAPI driver for Nintendo Switch Joy-Cons should be used.
+  *
+  *  This variable can be set to the following values:
+  *    "0"       - HIDAPI driver is not used
+  *    "1"       - HIDAPI driver is used
+  *
+  *  The default is the value of SDL_HINT_JOYSTICK_HIDAPI
+  */
+#define SDL_HINT_JOYSTICK_HIDAPI_JOY_CONS "SDL_JOYSTICK_HIDAPI_JOY_CONS"
+
+/**
+  *  \brief  A variable controlling whether Nintendo Switch Joy-Con controllers will be combined into a single Pro-like controller when using the HIDAPI driver
+  *
+  *  This variable can be set to the following values:
+  *    "0"       - Left and right Joy-Con controllers will not be combined and each will be a mini-gamepad
+  *    "1"       - Left and right Joy-Con controllers will be combined into a single controller (the default)
+  */
+#define SDL_HINT_JOYSTICK_HIDAPI_COMBINE_JOY_CONS "SDL_JOYSTICK_HIDAPI_COMBINE_JOY_CONS"
+
+/**
+  *  \brief  A variable controlling whether Nintendo Switch Joy-Con controllers will be in vertical mode when using the HIDAPI driver
+  *
+  *  This variable can be set to the following values:
+  *    "0"       - Left and right Joy-Con controllers will not be in vertical mode (the default)
+  *    "1"       - Left and right Joy-Con controllers will be in vertical mode
+  *
+  *  This hint must be set before calling SDL_Init(SDL_INIT_GAMECONTROLLER)
+  */
+#define SDL_HINT_JOYSTICK_HIDAPI_VERTICAL_JOY_CONS "SDL_JOYSTICK_HIDAPI_VERTICAL_JOY_CONS"
+
+/**
+  *  \brief  A variable controlling whether the HIDAPI driver for Amazon Luna controllers connected via Bluetooth should be used.
+  *
+  *  This variable can be set to the following values:
+  *    "0"       - HIDAPI driver is not used
+  *    "1"       - HIDAPI driver is used
+  *
+  *  The default is the value of SDL_HINT_JOYSTICK_HIDAPI
+  */
+#define SDL_HINT_JOYSTICK_HIDAPI_LUNA "SDL_JOYSTICK_HIDAPI_LUNA"
+
+/**
+  *  \brief  A variable controlling whether the HIDAPI driver for Nintendo Online classic controllers should be used.
+  *
+  *  This variable can be set to the following values:
+  *    "0"       - HIDAPI driver is not used
+  *    "1"       - HIDAPI driver is used
+  *
+  *  The default is the value of SDL_HINT_JOYSTICK_HIDAPI
+  */
+#define SDL_HINT_JOYSTICK_HIDAPI_NINTENDO_CLASSIC "SDL_JOYSTICK_HIDAPI_NINTENDO_CLASSIC"
+
+/**
+  *  \brief  A variable controlling whether the HIDAPI driver for NVIDIA SHIELD controllers should be used.
+  *
+  *  This variable can be set to the following values:
+  *    "0"       - HIDAPI driver is not used
+  *    "1"       - HIDAPI driver is used
+  *
+  *  The default is the value of SDL_HINT_JOYSTICK_HIDAPI
+  */
+#define SDL_HINT_JOYSTICK_HIDAPI_SHIELD "SDL_JOYSTICK_HIDAPI_SHIELD"
+
+/**
+ *  \brief  A variable controlling whether the HIDAPI driver for PS3 controllers should be used.
+ *
+ *  This variable can be set to the following values:
+ *    "0"       - HIDAPI driver is not used
+ *    "1"       - HIDAPI driver is used
+ *
+ *  The default is the value of SDL_HINT_JOYSTICK_HIDAPI on macOS, and "0" on other platforms.
+ *
+ *  It is not possible to use this driver on Windows, due to limitations in the default drivers
+ *  installed. See https://github.com/ViGEm/DsHidMini for an alternative driver on Windows.
+ */
+#define SDL_HINT_JOYSTICK_HIDAPI_PS3 "SDL_JOYSTICK_HIDAPI_PS3"
+
 /**
  *  \brief  A variable controlling whether the HIDAPI driver for PS4 controllers should be used.
  *
@@ -529,11 +769,16 @@ extern "C" {
  *
  *  Once extended reports are enabled, they can not be disabled without
  *  power cycling the controller.
+ *
+ *  For compatibility with applications written for versions of SDL prior
+ *  to the introduction of PS5 controller support, this value will also
+ *  control the state of extended reports on PS5 controllers when the
+ *  SDL_HINT_JOYSTICK_HIDAPI_PS5_RUMBLE hint is not explicitly set.
  */
 #define SDL_HINT_JOYSTICK_HIDAPI_PS4_RUMBLE "SDL_JOYSTICK_HIDAPI_PS4_RUMBLE"
 
 /**
- *  \brief  A variable controlling whether the HIDAPI driver for Steam Controllers should be used.
+ *  \brief  A variable controlling whether the HIDAPI driver for PS5 controllers should be used.
  *
  *  This variable can be set to the following values:
  *    "0"       - HIDAPI driver is not used
@@ -541,21 +786,38 @@ extern "C" {
  *
  *  The default is the value of SDL_HINT_JOYSTICK_HIDAPI
  */
-#define SDL_HINT_JOYSTICK_HIDAPI_STEAM "SDL_JOYSTICK_HIDAPI_STEAM"
+#define SDL_HINT_JOYSTICK_HIDAPI_PS5 "SDL_JOYSTICK_HIDAPI_PS5"
 
 /**
- *  \brief  A variable controlling whether the HIDAPI driver for Nintendo Switch controllers should be used.
+ *  \brief  A variable controlling whether the player LEDs should be lit to indicate which player is associated with a PS5 controller.
  *
  *  This variable can be set to the following values:
- *    "0"       - HIDAPI driver is not used
- *    "1"       - HIDAPI driver is used
+ *    "0"       - player LEDs are not enabled
+ *    "1"       - player LEDs are enabled (the default)
+ */
+#define SDL_HINT_JOYSTICK_HIDAPI_PS5_PLAYER_LED "SDL_JOYSTICK_HIDAPI_PS5_PLAYER_LED"
+
+/**
+ *  \brief  A variable controlling whether extended input reports should be used for PS5 controllers when using the HIDAPI driver.
  *
- *  The default is the value of SDL_HINT_JOYSTICK_HIDAPI
+ *  This variable can be set to the following values:
+ *    "0"       - extended reports are not enabled (the default)
+ *    "1"       - extended reports
+ *
+ *  Extended input reports allow rumble on Bluetooth PS5 controllers, but
+ *  break DirectInput handling for applications that don't use SDL.
+ *
+ *  Once extended reports are enabled, they can not be disabled without
+ *  power cycling the controller.
+ *
+ *  For compatibility with applications written for versions of SDL prior
+ *  to the introduction of PS5 controller support, this value defaults to
+ *  the value of SDL_HINT_JOYSTICK_HIDAPI_PS4_RUMBLE.
  */
-#define SDL_HINT_JOYSTICK_HIDAPI_SWITCH "SDL_JOYSTICK_HIDAPI_SWITCH"
+#define SDL_HINT_JOYSTICK_HIDAPI_PS5_RUMBLE "SDL_JOYSTICK_HIDAPI_PS5_RUMBLE"
 
 /**
- *  \brief  A variable controlling whether the HIDAPI driver for XBox controllers should be used.
+ *  \brief  A variable controlling whether the HIDAPI driver for Google Stadia controllers should be used.
  *
  *  This variable can be set to the following values:
  *    "0"       - HIDAPI driver is not used
@@ -563,183 +825,1338 @@ extern "C" {
  *
  *  The default is the value of SDL_HINT_JOYSTICK_HIDAPI
  */
-#define SDL_HINT_JOYSTICK_HIDAPI_XBOX   "SDL_JOYSTICK_HIDAPI_XBOX"
+#define SDL_HINT_JOYSTICK_HIDAPI_STADIA "SDL_JOYSTICK_HIDAPI_STADIA"
 
 /**
- *  \brief  A variable that controls whether Steam Controllers should be exposed using the SDL joystick and game controller APIs
+ *  \brief  A variable controlling whether the HIDAPI driver for Bluetooth Steam Controllers should be used.
  *
- *  The variable can be set to the following values:
- *    "0"       - Do not scan for Steam Controllers
- *    "1"       - Scan for Steam Controllers (the default)
+ *  This variable can be set to the following values:
+ *    "0"       - HIDAPI driver is not used
+ *    "1"       - HIDAPI driver is used for Steam Controllers, which requires Bluetooth access
+ *                and may prompt the user for permission on iOS and Android.
+ *
+ *  The default is "0"
+ */
+#define SDL_HINT_JOYSTICK_HIDAPI_STEAM "SDL_JOYSTICK_HIDAPI_STEAM"
+
+/**
+ *  \brief  A variable controlling whether the HIDAPI driver for Nintendo Switch controllers should be used.
+ *
+ *  This variable can be set to the following values:
+ *    "0"       - HIDAPI driver is not used
+ *    "1"       - HIDAPI driver is used
+ *
+ *  The default is the value of SDL_HINT_JOYSTICK_HIDAPI
+ */
+#define SDL_HINT_JOYSTICK_HIDAPI_SWITCH "SDL_JOYSTICK_HIDAPI_SWITCH"
+
+/**
+ *  \brief  A variable controlling whether the Home button LED should be turned on when a Nintendo Switch Pro controller is opened
+ *
+ *  This variable can be set to the following values:
+ *    "0"       - home button LED is turned off
+ *    "1"       - home button LED is turned on
+ *
+ *  By default the Home button LED state is not changed. This hint can also be set to a floating point value between 0.0 and 1.0 which controls the brightness of the Home button LED.
+ */
+#define SDL_HINT_JOYSTICK_HIDAPI_SWITCH_HOME_LED "SDL_JOYSTICK_HIDAPI_SWITCH_HOME_LED"
+
+/**
+ *  \brief  A variable controlling whether the Home button LED should be turned on when a Nintendo Switch Joy-Con controller is opened
+ *
+ *  This variable can be set to the following values:
+ *    "0"       - home button LED is turned off
+ *    "1"       - home button LED is turned on
+ *
+ *  By default the Home button LED state is not changed. This hint can also be set to a floating point value between 0.0 and 1.0 which controls the brightness of the Home button LED.
+ */
+#define SDL_HINT_JOYSTICK_HIDAPI_JOYCON_HOME_LED "SDL_JOYSTICK_HIDAPI_JOYCON_HOME_LED"
+
+/**
+ *  \brief  A variable controlling whether the player LEDs should be lit to indicate which player is associated with a Nintendo Switch controller.
+ *
+ *  This variable can be set to the following values:
+ *    "0"       - player LEDs are not enabled
+ *    "1"       - player LEDs are enabled (the default)
+ */
+#define SDL_HINT_JOYSTICK_HIDAPI_SWITCH_PLAYER_LED "SDL_JOYSTICK_HIDAPI_SWITCH_PLAYER_LED"
+
+/**
+ *  \brief  A variable controlling whether the HIDAPI driver for Nintendo Wii and Wii U controllers should be used.
+ *
+ *  This variable can be set to the following values:
+ *    "0"       - HIDAPI driver is not used
+ *    "1"       - HIDAPI driver is used
+ *
+ *  This driver doesn't work with the dolphinbar, so the default is SDL_FALSE for now.
+ */
+#define SDL_HINT_JOYSTICK_HIDAPI_WII "SDL_JOYSTICK_HIDAPI_WII"
+
+/**
+ *  \brief  A variable controlling whether the player LEDs should be lit to indicate which player is associated with a Wii controller.
+ *
+ *  This variable can be set to the following values:
+ *    "0"       - player LEDs are not enabled
+ *    "1"       - player LEDs are enabled (the default)
+ */
+#define SDL_HINT_JOYSTICK_HIDAPI_WII_PLAYER_LED "SDL_JOYSTICK_HIDAPI_WII_PLAYER_LED"
+
+/**
+ *  \brief  A variable controlling whether the HIDAPI driver for XBox controllers should be used.
+ *
+ *  This variable can be set to the following values:
+ *    "0"       - HIDAPI driver is not used
+ *    "1"       - HIDAPI driver is used
+ *
+ *  The default is "0" on Windows, otherwise the value of SDL_HINT_JOYSTICK_HIDAPI
+ */
+#define SDL_HINT_JOYSTICK_HIDAPI_XBOX   "SDL_JOYSTICK_HIDAPI_XBOX"
+
+/**
+ *  \brief  A variable controlling whether the HIDAPI driver for XBox 360 controllers should be used.
+ *
+ *  This variable can be set to the following values:
+ *    "0"       - HIDAPI driver is not used
+ *    "1"       - HIDAPI driver is used
+ *
+ *  The default is the value of SDL_HINT_JOYSTICK_HIDAPI_XBOX
+ */
+#define SDL_HINT_JOYSTICK_HIDAPI_XBOX_360   "SDL_JOYSTICK_HIDAPI_XBOX_360"
+
+/**
+ *  \brief  A variable controlling whether the player LEDs should be lit to indicate which player is associated with an Xbox 360 controller.
+ *
+ *  This variable can be set to the following values:
+ *    "0"       - player LEDs are not enabled
+ *    "1"       - player LEDs are enabled (the default)
+ */
+#define SDL_HINT_JOYSTICK_HIDAPI_XBOX_360_PLAYER_LED "SDL_JOYSTICK_HIDAPI_XBOX_360_PLAYER_LED"
+
+/**
+ *  \brief  A variable controlling whether the HIDAPI driver for XBox 360 wireless controllers should be used.
+ *
+ *  This variable can be set to the following values:
+ *    "0"       - HIDAPI driver is not used
+ *    "1"       - HIDAPI driver is used
+ *
+ *  The default is the value of SDL_HINT_JOYSTICK_HIDAPI_XBOX_360
+ */
+#define SDL_HINT_JOYSTICK_HIDAPI_XBOX_360_WIRELESS   "SDL_JOYSTICK_HIDAPI_XBOX_360_WIRELESS"
+
+/**
+ *  \brief  A variable controlling whether the HIDAPI driver for XBox One controllers should be used.
+ *
+ *  This variable can be set to the following values:
+ *    "0"       - HIDAPI driver is not used
+ *    "1"       - HIDAPI driver is used
+ *
+ *  The default is the value of SDL_HINT_JOYSTICK_HIDAPI_XBOX
+ */
+#define SDL_HINT_JOYSTICK_HIDAPI_XBOX_ONE   "SDL_JOYSTICK_HIDAPI_XBOX_ONE"
+
+/**
+ *  \brief  A variable controlling whether the Home button LED should be turned on when an Xbox One controller is opened
+ *
+ *  This variable can be set to the following values:
+ *    "0"       - home button LED is turned off
+ *    "1"       - home button LED is turned on
+ *
+ *  By default the Home button LED state is not changed. This hint can also be set to a floating point value between 0.0 and 1.0 which controls the brightness of the Home button LED. The default brightness is 0.4.
+ */
+#define SDL_HINT_JOYSTICK_HIDAPI_XBOX_ONE_HOME_LED "SDL_JOYSTICK_HIDAPI_XBOX_ONE_HOME_LED"
+
+/**
+  *  \brief  A variable controlling whether the RAWINPUT joystick drivers should be used for better handling XInput-capable devices.
+  *
+  *  This variable can be set to the following values:
+  *    "0"       - RAWINPUT drivers are not used
+  *    "1"       - RAWINPUT drivers are used (the default)
+  */
+#define SDL_HINT_JOYSTICK_RAWINPUT "SDL_JOYSTICK_RAWINPUT"
+
+/**
+  *  \brief  A variable controlling whether the RAWINPUT driver should pull correlated data from XInput.
+  *
+  *  This variable can be set to the following values:
+  *    "0"       - RAWINPUT driver will only use data from raw input APIs
+  *    "1"       - RAWINPUT driver will also pull data from XInput, providing
+  *                better trigger axes, guide button presses, and rumble support
+  *                for Xbox controllers
+  *
+  *  The default is "1".  This hint applies to any joysticks opened after setting the hint.
+  */
+#define SDL_HINT_JOYSTICK_RAWINPUT_CORRELATE_XINPUT   "SDL_JOYSTICK_RAWINPUT_CORRELATE_XINPUT"
+
+/**
+  *  \brief  A variable controlling whether the ROG Chakram mice should show up as joysticks
+  *
+  *  This variable can be set to the following values:
+  *    "0"       - ROG Chakram mice do not show up as joysticks (the default)
+  *    "1"       - ROG Chakram mice show up as joysticks
+  */
+#define SDL_HINT_JOYSTICK_ROG_CHAKRAM "SDL_JOYSTICK_ROG_CHAKRAM"
+
+/**
+  *  \brief  A variable controlling whether a separate thread should be used
+  *          for handling joystick detection and raw input messages on Windows
+  *
+  *  This variable can be set to the following values:
+  *    "0"       - A separate thread is not used (the default)
+  *    "1"       - A separate thread is used for handling raw input messages
+  *
+  */
+#define SDL_HINT_JOYSTICK_THREAD "SDL_JOYSTICK_THREAD"
+
+/**
+  *  \brief  A variable controlling whether Windows.Gaming.Input should be used for controller handling.
+  *
+  *  This variable can be set to the following values:
+  *    "0"       - WGI is not used
+  *    "1"       - WGI is used (the default)
+  */
+#define SDL_HINT_JOYSTICK_WGI "SDL_JOYSTICK_WGI"
+
+/**
+ * \brief Determines whether SDL enforces that DRM master is required in order
+ *        to initialize the KMSDRM video backend.
+ *
+ * The DRM subsystem has a concept of a "DRM master" which is a DRM client that
+ * has the ability to set planes, set cursor, etc. When SDL is DRM master, it
+ * can draw to the screen using the SDL rendering APIs. Without DRM master, SDL
+ * is still able to process input and query attributes of attached displays,
+ * but it cannot change display state or draw to the screen directly.
+ *
+ * In some cases, it can be useful to have the KMSDRM backend even if it cannot
+ * be used for rendering. An app may want to use SDL for input processing while
+ * using another rendering API (such as an MMAL overlay on Raspberry Pi) or
+ * using its own code to render to DRM overlays that SDL doesn't support.
+ *
+ * This hint must be set before initializing the video subsystem.
+ *
+ * This variable can be set to the following values:
+ *    "0"       - SDL will allow usage of the KMSDRM backend without DRM master
+ *    "1"       - SDL Will require DRM master to use the KMSDRM backend (default)
+ */
+#define SDL_HINT_KMSDRM_REQUIRE_DRM_MASTER      "SDL_KMSDRM_REQUIRE_DRM_MASTER"
+
+/**
+  *  \brief  A comma separated list of devices to open as joysticks
+  *
+  *  This variable is currently only used by the Linux joystick driver.
+  */
+#define SDL_HINT_JOYSTICK_DEVICE "SDL_JOYSTICK_DEVICE"
+
+/**
+  *  \brief  A variable controlling whether joysticks on Linux will always treat 'hat' axis inputs (ABS_HAT0X - ABS_HAT3Y) as 8-way digital hats without checking whether they may be analog.
+  *
+  *  This variable can be set to the following values:
+  *    "0"       - Only map hat axis inputs to digital hat outputs if the input axes appear to actually be digital (the default)
+  *    "1"       - Always handle the input axes numbered ABS_HAT0X to ABS_HAT3Y as digital hats
+  */
+#define SDL_HINT_LINUX_DIGITAL_HATS "SDL_LINUX_DIGITAL_HATS"
+
+/**
+  *  \brief  A variable controlling whether digital hats on Linux will apply deadzones to their underlying input axes or use unfiltered values.
+  *
+  *  This variable can be set to the following values:
+  *    "0"       - Return digital hat values based on unfiltered input axis values
+  *    "1"       - Return digital hat values with deadzones on the input axes taken into account (the default)
+  */
+#define SDL_HINT_LINUX_HAT_DEADZONES "SDL_LINUX_HAT_DEADZONES"
+
+/**
+  *  \brief  A variable controlling whether to use the classic /dev/input/js* joystick interface or the newer /dev/input/event* joystick interface on Linux
+  *
+  *  This variable can be set to the following values:
+  *    "0"       - Use /dev/input/event*
+  *    "1"       - Use /dev/input/js*
+  *
+  *  By default the /dev/input/event* interfaces are used
+  */
+#define SDL_HINT_LINUX_JOYSTICK_CLASSIC "SDL_LINUX_JOYSTICK_CLASSIC"
+
+/**
+  *  \brief  A variable controlling whether joysticks on Linux adhere to their HID-defined deadzones or return unfiltered values.
+  *
+  *  This variable can be set to the following values:
+  *    "0"       - Return unfiltered joystick axis values (the default)
+  *    "1"       - Return axis values with deadzones taken into account
+  */
+#define SDL_HINT_LINUX_JOYSTICK_DEADZONES "SDL_LINUX_JOYSTICK_DEADZONES"
+
+/**
+*  \brief  When set don't force the SDL app to become a foreground process
+*
+*  This hint only applies to Mac OS X.
+*
+*/
+#define SDL_HINT_MAC_BACKGROUND_APP    "SDL_MAC_BACKGROUND_APP"
+
+/**
+ *  \brief A variable that determines whether ctrl+click should generate a right-click event on Mac
+ *
+ *  If present, holding ctrl while left clicking will generate a right click
+ *  event when on Mac.
+ */
+#define SDL_HINT_MAC_CTRL_CLICK_EMULATE_RIGHT_CLICK "SDL_MAC_CTRL_CLICK_EMULATE_RIGHT_CLICK"
+
+/**
+ *  \brief   A variable controlling whether dispatching OpenGL context updates should block the dispatching thread until the main thread finishes processing
+ *
+ *  This variable can be set to the following values:
+ *    "0"       - Dispatching OpenGL context updates will block the dispatching thread until the main thread finishes processing (default).
+ *    "1"       - Dispatching OpenGL context updates will allow the dispatching thread to continue execution.
+ *
+ *  Generally you want the default, but if you have OpenGL code in a background thread on a Mac, and the main thread
+ *  hangs because it's waiting for that background thread, but that background thread is also hanging because it's
+ *  waiting for the main thread to do an update, this might fix your issue.
+ *
+ *  This hint only applies to macOS.
+ *
+ *  This hint is available since SDL 2.24.0.
+ *
+ */
+#define SDL_HINT_MAC_OPENGL_ASYNC_DISPATCH "SDL_MAC_OPENGL_ASYNC_DISPATCH"
+
+/**
+ *  \brief  A variable setting the double click radius, in pixels.
+ */
+#define SDL_HINT_MOUSE_DOUBLE_CLICK_RADIUS    "SDL_MOUSE_DOUBLE_CLICK_RADIUS"
+
+/**
+ *  \brief  A variable setting the double click time, in milliseconds.
+ */
+#define SDL_HINT_MOUSE_DOUBLE_CLICK_TIME    "SDL_MOUSE_DOUBLE_CLICK_TIME"
+
+/**
+ *  \brief Allow mouse click events when clicking to focus an SDL window
+ *
+ *  This variable can be set to the following values:
+ *    "0"       - Ignore mouse clicks that activate a window
+ *    "1"       - Generate events for mouse clicks that activate a window
+ *
+ *  By default SDL will ignore mouse clicks that activate a window
+ */
+#define SDL_HINT_MOUSE_FOCUS_CLICKTHROUGH "SDL_MOUSE_FOCUS_CLICKTHROUGH"
+
+/**
+ *  \brief  A variable setting the speed scale for mouse motion, in floating point, when the mouse is not in relative mode
+ */
+#define SDL_HINT_MOUSE_NORMAL_SPEED_SCALE    "SDL_MOUSE_NORMAL_SPEED_SCALE"
+
+/**
+ *  \brief  A variable controlling whether relative mouse mode constrains the mouse to the center of the window
+ *
+ *  This variable can be set to the following values:
+ *    "0"       - Relative mouse mode constrains the mouse to the window
+ *    "1"       - Relative mouse mode constrains the mouse to the center of the window
+ *
+ *  Constraining to the center of the window works better for FPS games and when the
+ *  application is running over RDP. Constraining to the whole window works better
+ *  for 2D games and increases the chance that the mouse will be in the correct
+ *  position when using high DPI mice.
+ *
+ *  By default SDL will constrain the mouse to the center of the window
+ */
+#define SDL_HINT_MOUSE_RELATIVE_MODE_CENTER    "SDL_MOUSE_RELATIVE_MODE_CENTER"
+
+/**
+ *  \brief  A variable controlling whether relative mouse mode is implemented using mouse warping
+ *
+ *  This variable can be set to the following values:
+ *    "0"       - Relative mouse mode uses raw input
+ *    "1"       - Relative mouse mode uses mouse warping
+ *
+ *  By default SDL will use raw input for relative mouse mode
+ */
+#define SDL_HINT_MOUSE_RELATIVE_MODE_WARP    "SDL_MOUSE_RELATIVE_MODE_WARP"
+
+/**
+ *  \brief  A variable controlling whether relative mouse motion is affected by renderer scaling
+ *
+ *  This variable can be set to the following values:
+ *    "0"       - Relative motion is unaffected by DPI or renderer's logical size
+ *    "1"       - Relative motion is scaled according to DPI scaling and logical size
+ *
+ *  By default relative mouse deltas are affected by DPI and renderer scaling
+ */
+#define SDL_HINT_MOUSE_RELATIVE_SCALING "SDL_MOUSE_RELATIVE_SCALING"
+
+/**
+ *  \brief  A variable setting the scale for mouse motion, in floating point, when the mouse is in relative mode
+ */
+#define SDL_HINT_MOUSE_RELATIVE_SPEED_SCALE    "SDL_MOUSE_RELATIVE_SPEED_SCALE"
+
+/**
+ *  \brief  A variable controlling whether the system mouse acceleration curve is used for relative mouse motion.
+ *
+ *  This variable can be set to the following values:
+ *    "0"       - Relative mouse motion will be unscaled (the default)
+ *    "1"       - Relative mouse motion will be scaled using the system mouse acceleration curve.
+ *
+ *    If SDL_HINT_MOUSE_RELATIVE_SPEED_SCALE is set, that will override the system speed scale.
+ */
+#define SDL_HINT_MOUSE_RELATIVE_SYSTEM_SCALE    "SDL_MOUSE_RELATIVE_SYSTEM_SCALE"
+
+/**
+ *  \brief  A variable controlling whether a motion event should be generated for mouse warping in relative mode.
+ *
+ *  This variable can be set to the following values:
+ *    "0"       - Warping the mouse will not generate a motion event in relative mode
+ *    "1"       - Warping the mouse will generate a motion event in relative mode
+ *
+ *  By default warping the mouse will not generate motion events in relative mode. This avoids the application having to filter out large relative motion due to warping.
+ */
+#define SDL_HINT_MOUSE_RELATIVE_WARP_MOTION  "SDL_MOUSE_RELATIVE_WARP_MOTION"
+
+/**
+ *  \brief  A variable controlling whether mouse events should generate synthetic touch events
+ *
+ *  This variable can be set to the following values:
+ *    "0"       - Mouse events will not generate touch events (default for desktop platforms)
+ *    "1"       - Mouse events will generate touch events (default for mobile platforms, such as Android and iOS)
+ */
+#define SDL_HINT_MOUSE_TOUCH_EVENTS    "SDL_MOUSE_TOUCH_EVENTS"
+
+/**
+ *  \brief  A variable controlling whether the mouse is captured while mouse buttons are pressed
+ *
+ *  This variable can be set to the following values:
+ *    "0"       - The mouse is not captured while mouse buttons are pressed
+ *    "1"       - The mouse is captured while mouse buttons are pressed
+ *
+ *  By default the mouse is captured while mouse buttons are pressed so if the mouse is dragged
+ *  outside the window, the application continues to receive mouse events until the button is
+ *  released.
+ */
+#define SDL_HINT_MOUSE_AUTO_CAPTURE    "SDL_MOUSE_AUTO_CAPTURE"
+
+/**
+ *  \brief Tell SDL not to catch the SIGINT or SIGTERM signals.
+ *
+ * This hint only applies to Unix-like platforms, and should set before
+ * any calls to SDL_Init()
+ *
+ * The variable can be set to the following values:
+ *   "0"       - SDL will install a SIGINT and SIGTERM handler, and when it
+ *               catches a signal, convert it into an SDL_QUIT event.
+ *   "1"       - SDL will not install a signal handler at all.
+ */
+#define SDL_HINT_NO_SIGNAL_HANDLERS   "SDL_NO_SIGNAL_HANDLERS"
+
+/**
+ *  \brief  A variable controlling what driver to use for OpenGL ES contexts.
+ *
+ *  On some platforms, currently Windows and X11, OpenGL drivers may support
+ *  creating contexts with an OpenGL ES profile. By default SDL uses these
+ *  profiles, when available, otherwise it attempts to load an OpenGL ES
+ *  library, e.g. that provided by the ANGLE project. This variable controls
+ *  whether SDL follows this default behaviour or will always load an
+ *  OpenGL ES library.
+ *
+ *  Circumstances where this is useful include
+ *  - Testing an app with a particular OpenGL ES implementation, e.g ANGLE,
+ *    or emulator, e.g. those from ARM, Imagination or Qualcomm.
+ *  - Resolving OpenGL ES function addresses at link time by linking with
+ *    the OpenGL ES library instead of querying them at run time with
+ *    SDL_GL_GetProcAddress().
+ *
+ *  Caution: for an application to work with the default behaviour across
+ *  different OpenGL drivers it must query the OpenGL ES function
+ *  addresses at run time using SDL_GL_GetProcAddress().
+ *
+ *  This variable is ignored on most platforms because OpenGL ES is native
+ *  or not supported.
+ *
+ *  This variable can be set to the following values:
+ *    "0"       - Use ES profile of OpenGL, if available. (Default when not set.)
+ *    "1"       - Load OpenGL ES library using the default library names.
+ *
+ */
+#define SDL_HINT_OPENGL_ES_DRIVER   "SDL_OPENGL_ES_DRIVER"
+
+/**
+ *  \brief  A variable controlling which orientations are allowed on iOS/Android.
+ *
+ *  In some circumstances it is necessary to be able to explicitly control
+ *  which UI orientations are allowed.
+ *
+ *  This variable is a space delimited list of the following values:
+ *    "LandscapeLeft", "LandscapeRight", "Portrait" "PortraitUpsideDown"
+ */
+#define SDL_HINT_ORIENTATIONS "SDL_IOS_ORIENTATIONS"
+
+/**
+ *  \brief  A variable controlling the use of a sentinel event when polling the event queue
+ *
+ *  This variable can be set to the following values:
+ *    "0"       - Disable poll sentinels
+ *    "1"       - Enable poll sentinels
+ *
+ *  When polling for events, SDL_PumpEvents is used to gather new events from devices.
+ *  If a device keeps producing new events between calls to SDL_PumpEvents, a poll loop will
+ *  become stuck until the new events stop.
+ *  This is most noticeable when moving a high frequency mouse.
+ *
+ *  By default, poll sentinels are enabled.
+ */
+#define SDL_HINT_POLL_SENTINEL "SDL_POLL_SENTINEL"
+
+/**
+ *  \brief Override for SDL_GetPreferredLocales()
+ *
+ *  If set, this will be favored over anything the OS might report for the
+ *  user's preferred locales. Changing this hint at runtime will not generate
+ *  a SDL_LOCALECHANGED event (but if you can change the hint, you can push
+ *  your own event, if you want).
+ *
+ *  The format of this hint is a comma-separated list of language and locale,
+ *  combined with an underscore, as is a common format: "en_GB". Locale is
+ *  optional: "en". So you might have a list like this: "en_GB,jp,es_PT"
+ */
+#define SDL_HINT_PREFERRED_LOCALES "SDL_PREFERRED_LOCALES"
+
+/**
+ *  \brief  A variable describing the content orientation on QtWayland-based platforms.
+ *
+ *  On QtWayland platforms, windows are rotated client-side to allow for custom
+ *  transitions. In order to correctly position overlays (e.g. volume bar) and
+ *  gestures (e.g. events view, close/minimize gestures), the system needs to
+ *  know in which orientation the application is currently drawing its contents.
+ *
+ *  This does not cause the window to be rotated or resized, the application
+ *  needs to take care of drawing the content in the right orientation (the
+ *  framebuffer is always in portrait mode).
+ *
+ *  This variable can be one of the following values:
+ *    "primary" (default), "portrait", "landscape", "inverted-portrait", "inverted-landscape"
+ *
+ *  Since SDL 2.0.22 this variable accepts a comma-separated list of values above.
+ */
+#define SDL_HINT_QTWAYLAND_CONTENT_ORIENTATION "SDL_QTWAYLAND_CONTENT_ORIENTATION"
+
+/**
+ *  \brief  Flags to set on QtWayland windows to integrate with the native window manager.
+ *
+ *  On QtWayland platforms, this hint controls the flags to set on the windows.
+ *  For example, on Sailfish OS "OverridesSystemGestures" disables swipe gestures.
+ *
+ *  This variable is a space-separated list of the following values (empty = no flags):
+ *    "OverridesSystemGestures", "StaysOnTop", "BypassWindowManager"
+ */
+#define SDL_HINT_QTWAYLAND_WINDOW_FLAGS "SDL_QTWAYLAND_WINDOW_FLAGS"
+
+/**
+ *  \brief  A variable controlling whether the 2D render API is compatible or efficient.
+ *
+ *  This variable can be set to the following values:
+ *
+ *    "0"     - Don't use batching to make rendering more efficient.
+ *    "1"     - Use batching, but might cause problems if app makes its own direct OpenGL calls.
+ *
+ *  Up to SDL 2.0.9, the render API would draw immediately when requested. Now
+ *  it batches up draw requests and sends them all to the GPU only when forced
+ *  to (during SDL_RenderPresent, when changing render targets, by updating a
+ *  texture that the batch needs, etc). This is significantly more efficient,
+ *  but it can cause problems for apps that expect to render on top of the
+ *  render API's output. As such, SDL will disable batching if a specific
+ *  render backend is requested (since this might indicate that the app is
+ *  planning to use the underlying graphics API directly). This hint can
+ *  be used to explicitly request batching in this instance. It is a contract
+ *  that you will either never use the underlying graphics API directly, or
+ *  if you do, you will call SDL_RenderFlush() before you do so any current
+ *  batch goes to the GPU before your work begins. Not following this contract
+ *  will result in undefined behavior.
+ */
+#define SDL_HINT_RENDER_BATCHING  "SDL_RENDER_BATCHING"
+
+/**
+ *  \brief  A variable controlling how the 2D render API renders lines
+ *
+ *  This variable can be set to the following values:
+ *    "0"     - Use the default line drawing method (Bresenham's line algorithm as of SDL 2.0.20)
+ *    "1"     - Use the driver point API using Bresenham's line algorithm (correct, draws many points)
+ *    "2"     - Use the driver line API (occasionally misses line endpoints based on hardware driver quirks, was the default before 2.0.20)
+ *    "3"     - Use the driver geometry API (correct, draws thicker diagonal lines)
+ *
+ *  This variable should be set when the renderer is created.
+ */
+#define SDL_HINT_RENDER_LINE_METHOD "SDL_RENDER_LINE_METHOD"
+
+/**
+ *  \brief  A variable controlling whether to enable Direct3D 11+'s Debug Layer.
+ *
+ *  This variable does not have any effect on the Direct3D 9 based renderer.
+ *
+ *  This variable can be set to the following values:
+ *    "0"       - Disable Debug Layer use
+ *    "1"       - Enable Debug Layer use
+ *
+ *  By default, SDL does not use Direct3D Debug Layer.
+ */
+#define SDL_HINT_RENDER_DIRECT3D11_DEBUG    "SDL_RENDER_DIRECT3D11_DEBUG"
+
+/**
+ *  \brief  A variable controlling whether the Direct3D device is initialized for thread-safe operations.
+ *
+ *  This variable can be set to the following values:
+ *    "0"       - Thread-safety is not enabled (faster)
+ *    "1"       - Thread-safety is enabled
+ *
+ *  By default the Direct3D device is created with thread-safety disabled.
+ */
+#define SDL_HINT_RENDER_DIRECT3D_THREADSAFE "SDL_RENDER_DIRECT3D_THREADSAFE"
+
+/**
+ *  \brief  A variable specifying which render driver to use.
+ *
+ *  If the application doesn't pick a specific renderer to use, this variable
+ *  specifies the name of the preferred renderer.  If the preferred renderer
+ *  can't be initialized, the normal default renderer is used.
+ *
+ *  This variable is case insensitive and can be set to the following values:
+ *    "direct3d"
+ *    "direct3d11"
+ *    "direct3d12"
+ *    "opengl"
+ *    "opengles2"
+ *    "opengles"
+ *    "metal"
+ *    "software"
+ *
+ *  The default varies by platform, but it's the first one in the list that
+ *  is available on the current platform.
+ */
+#define SDL_HINT_RENDER_DRIVER              "SDL_RENDER_DRIVER"
+
+/**
+ *  \brief  A variable controlling the scaling policy for SDL_RenderSetLogicalSize.
+ *
+ *  This variable can be set to the following values:
+ *    "0" or "letterbox" - Uses letterbox/sidebars to fit the entire rendering on screen
+ *    "1" or "overscan"  - Will zoom the rendering so it fills the entire screen, allowing edges to be drawn offscreen
+ *
+ *  By default letterbox is used
+ */
+#define SDL_HINT_RENDER_LOGICAL_SIZE_MODE       "SDL_RENDER_LOGICAL_SIZE_MODE"
+
+/**
+ *  \brief  A variable controlling whether the OpenGL render driver uses shaders if they are available.
+ *
+ *  This variable can be set to the following values:
+ *    "0"       - Disable shaders
+ *    "1"       - Enable shaders
+ *
+ *  By default shaders are used if OpenGL supports them.
+ */
+#define SDL_HINT_RENDER_OPENGL_SHADERS      "SDL_RENDER_OPENGL_SHADERS"
+
+/**
+ *  \brief  A variable controlling the scaling quality
+ *
+ *  This variable can be set to the following values:
+ *    "0" or "nearest" - Nearest pixel sampling
+ *    "1" or "linear"  - Linear filtering (supported by OpenGL and Direct3D)
+ *    "2" or "best"    - Currently this is the same as "linear"
+ *
+ *  By default nearest pixel sampling is used
+ */
+#define SDL_HINT_RENDER_SCALE_QUALITY       "SDL_RENDER_SCALE_QUALITY"
+
+/**
+ *  \brief  A variable controlling whether updates to the SDL screen surface should be synchronized with the vertical refresh, to avoid tearing.
+ *
+ *  This variable can be set to the following values:
+ *    "0"       - Disable vsync
+ *    "1"       - Enable vsync
+ *
+ *  By default SDL does not sync screen surface updates with vertical refresh.
+ */
+#define SDL_HINT_RENDER_VSYNC               "SDL_RENDER_VSYNC"
+
+/**
+ *  \brief  A variable controlling whether the Metal render driver select low power device over default one
+ *
+ *  This variable can be set to the following values:
+ *    "0"       - Use the prefered OS device
+ *    "1"       - Select a low power one
+ *
+ *  By default the prefered OS device is used.
+ */
+#define SDL_HINT_RENDER_METAL_PREFER_LOW_POWER_DEVICE "SDL_RENDER_METAL_PREFER_LOW_POWER_DEVICE"
+
+/**
+ *  \brief  A variable controlling if VSYNC is automatically disable if doesn't reach the enough FPS
+ *
+ *  This variable can be set to the following values:
+ *    "0"       - It will be using VSYNC as defined in the main flag. Default
+ *    "1"       - If VSYNC was previously enabled, then it will disable VSYNC if doesn't reach enough speed
+ *
+ *  By default SDL does not enable the automatic VSYNC
+ */
+#define SDL_HINT_PS2_DYNAMIC_VSYNC    "SDL_PS2_DYNAMIC_VSYNC"
+
+/**
+ * \brief A variable to control whether the return key on the soft keyboard
+ *        should hide the soft keyboard on Android and iOS.
+ *
+ * The variable can be set to the following values:
+ *   "0"       - The return key will be handled as a key event. This is the behaviour of SDL <= 2.0.3. (default)
+ *   "1"       - The return key will hide the keyboard.
+ *
+ * The value of this hint is used at runtime, so it can be changed at any time.
+ */
+#define SDL_HINT_RETURN_KEY_HIDES_IME "SDL_RETURN_KEY_HIDES_IME"
+
+/**
+ * \brief Tell SDL which Dispmanx layer to use on a Raspberry PI
+ *
+ * Also known as Z-order. The variable can take a negative or positive value.
+ * The default is 10000.
+ */
+#define SDL_HINT_RPI_VIDEO_LAYER           "SDL_RPI_VIDEO_LAYER"
+
+/**
+ *  \brief Specify an "activity name" for screensaver inhibition.
+ *
+ * Some platforms, notably Linux desktops, list the applications which are
+ * inhibiting the screensaver or other power-saving features.
+ *
+ * This hint lets you specify the "activity name" sent to the OS when
+ * SDL_DisableScreenSaver() is used (or the screensaver is automatically
+ * disabled). The contents of this hint are used when the screensaver is
+ * disabled. You should use a string that describes what your program is doing
+ * (and, therefore, why the screensaver is disabled).  For example, "Playing a
+ * game" or "Watching a video".
+ *
+ * Setting this to "" or leaving it unset will have SDL use a reasonable
+ * default: "Playing a game" or something similar.
+ *
+ * On targets where this is not supported, this hint does nothing.
+ */
+#define SDL_HINT_SCREENSAVER_INHIBIT_ACTIVITY_NAME "SDL_SCREENSAVER_INHIBIT_ACTIVITY_NAME"
+
+/**
+ *  \brief Specifies whether SDL_THREAD_PRIORITY_TIME_CRITICAL should be treated as realtime.
+ *
+ *  On some platforms, like Linux, a realtime priority thread may be subject to restrictions
+ *  that require special handling by the application. This hint exists to let SDL know that
+ *  the app is prepared to handle said restrictions.
+ *
+ *  On Linux, SDL will apply the following configuration to any thread that becomes realtime:
+ *   * The SCHED_RESET_ON_FORK bit will be set on the scheduling policy,
+ *   * An RLIMIT_RTTIME budget will be configured to the rtkit specified limit.
+ *     * Exceeding this limit will result in the kernel sending SIGKILL to the app,
+ *     * Refer to the man pages for more information.
+ *
+ *  This variable can be set to the following values:
+ *    "0"       - default platform specific behaviour
+ *    "1"       - Force SDL_THREAD_PRIORITY_TIME_CRITICAL to a realtime scheduling policy
+ */
+#define SDL_HINT_THREAD_FORCE_REALTIME_TIME_CRITICAL "SDL_THREAD_FORCE_REALTIME_TIME_CRITICAL"
+
+/**
+*  \brief  A string specifying additional information to use with SDL_SetThreadPriority.
+*
+*  By default SDL_SetThreadPriority will make appropriate system changes in order to
+*  apply a thread priority.  For example on systems using pthreads the scheduler policy
+*  is changed automatically to a policy that works well with a given priority.
+*  Code which has specific requirements can override SDL's default behavior with this hint.
+*
+*  pthread hint values are "current", "other", "fifo" and "rr".
+*  Currently no other platform hint values are defined but may be in the future.
+*
+*  \note On Linux, the kernel may send SIGKILL to realtime tasks which exceed the distro
+*  configured execution budget for rtkit. This budget can be queried through RLIMIT_RTTIME
+*  after calling SDL_SetThreadPriority().
+*/
+#define SDL_HINT_THREAD_PRIORITY_POLICY         "SDL_THREAD_PRIORITY_POLICY"
+
+/**
+*  \brief  A string specifying SDL's threads stack size in bytes or "0" for the backend's default size
+*
+*  Use this hint in case you need to set SDL's threads stack size to other than the default.
+*  This is specially useful if you build SDL against a non glibc libc library (such as musl) which
+*  provides a relatively small default thread stack size (a few kilobytes versus the default 8MB glibc uses).
+*  Support for this hint is currently available only in the pthread, Windows, and PSP backend.
+*
+*  Instead of this hint, in 2.0.9 and later, you can use
+*  SDL_CreateThreadWithStackSize(). This hint only works with the classic
+*  SDL_CreateThread().
+*/
+#define SDL_HINT_THREAD_STACK_SIZE              "SDL_THREAD_STACK_SIZE"
+
+/**
+ *  \brief A variable that controls the timer resolution, in milliseconds.
+ *
+ *  The higher resolution the timer, the more frequently the CPU services
+ *  timer interrupts, and the more precise delays are, but this takes up
+ *  power and CPU time.  This hint is only used on Windows.
+ *
+ *  See this blog post for more information:
+ *  http://randomascii.wordpress.com/2013/07/08/windows-timer-resolution-megawatts-wasted/
+ *
+ *  If this variable is set to "0", the system timer resolution is not set.
+ *
+ *  The default value is "1". This hint may be set at any time.
+ */
+#define SDL_HINT_TIMER_RESOLUTION "SDL_TIMER_RESOLUTION"
+
+/**
+ *  \brief  A variable controlling whether touch events should generate synthetic mouse events
+ *
+ *  This variable can be set to the following values:
+ *    "0"       - Touch events will not generate mouse events
+ *    "1"       - Touch events will generate mouse events
+ *
+ *  By default SDL will generate mouse events for touch events
+ */
+#define SDL_HINT_TOUCH_MOUSE_EVENTS    "SDL_TOUCH_MOUSE_EVENTS"
+
+/**
+ *  \brief  A variable controlling which touchpad should generate synthetic mouse events
+ *
+ *  This variable can be set to the following values:
+ *    "0"       - Only front touchpad should generate mouse events. Default
+ *    "1"       - Only back touchpad should generate mouse events.
+ *    "2"       - Both touchpads should generate mouse events.
+ *
+ *  By default SDL will generate mouse events for all touch devices
+ */
+#define SDL_HINT_VITA_TOUCH_MOUSE_DEVICE    "SDL_HINT_VITA_TOUCH_MOUSE_DEVICE"
+
+/**
+ *  \brief  A variable controlling whether the Android / tvOS remotes
+ *  should be listed as joystick devices, instead of sending keyboard events.
+ *
+ *  This variable can be set to the following values:
+ *    "0"       - Remotes send enter/escape/arrow key events
+ *    "1"       - Remotes are available as 2 axis, 2 button joysticks (the default).
+ */
+#define SDL_HINT_TV_REMOTE_AS_JOYSTICK "SDL_TV_REMOTE_AS_JOYSTICK"
+
+/**
+ *  \brief  A variable controlling whether the screensaver is enabled.
+ *
+ *  This variable can be set to the following values:
+ *    "0"       - Disable screensaver
+ *    "1"       - Enable screensaver
+ *
+ *  By default SDL will disable the screensaver.
+ */
+#define SDL_HINT_VIDEO_ALLOW_SCREENSAVER    "SDL_VIDEO_ALLOW_SCREENSAVER"
+
+/**
+ * \brief Tell the video driver that we only want a double buffer.
+ *
+ * By default, most lowlevel 2D APIs will use a triple buffer scheme that
+ * wastes no CPU time on waiting for vsync after issuing a flip, but
+ * introduces a frame of latency. On the other hand, using a double buffer
+ * scheme instead is recommended for cases where low latency is an important
+ * factor because we save a whole frame of latency.
+ * We do so by waiting for vsync immediately after issuing a flip, usually just
+ * after eglSwapBuffers call in the backend's *_SwapWindow function.
+ *
+ * Since it's driver-specific, it's only supported where possible and
+ * implemented. Currently supported the following drivers:
+ *
+ * - KMSDRM (kmsdrm)
+ * - Raspberry Pi (raspberrypi)
+ */
+#define SDL_HINT_VIDEO_DOUBLE_BUFFER      "SDL_VIDEO_DOUBLE_BUFFER"
+
+/**
+ * \brief A variable controlling whether the EGL window is allowed to be
+ * composited as transparent, rather than opaque.
  *
- *  The default value is "1".  This hint must be set before initializing the joystick subsystem.
+ * Most window systems will always render windows opaque, even if the surface
+ * format has an alpha channel. This is not always true, however, so by default
+ * SDL will try to enforce opaque composition. To override this behavior, you
+ * can set this hint to "1".
  */
-#define SDL_HINT_ENABLE_STEAM_CONTROLLERS "SDL_ENABLE_STEAM_CONTROLLERS"
+#define SDL_HINT_VIDEO_EGL_ALLOW_TRANSPARENCY "SDL_VIDEO_EGL_ALLOW_TRANSPARENCY"
 
+/**
+ * \brief A variable controlling whether the graphics context is externally managed.
+ *
+ * This variable can be set to the following values:
+ *  "0"         - SDL will manage graphics contexts that are attached to windows.
+ *  "1"         - Disable graphics context management on windows.
+ *
+ * By default SDL will manage OpenGL contexts in certain situations. For example, on Android the
+ * context will be automatically saved and restored when pausing the application. Additionally, some
+ * platforms will assume usage of OpenGL if Vulkan isn't used. Setting this to "1" will prevent this
+ * behavior, which is desireable when the application manages the graphics context, such as
+ * an externally managed OpenGL context or attaching a Vulkan surface to the window.
+ */
+#define SDL_HINT_VIDEO_EXTERNAL_CONTEXT    "SDL_VIDEO_EXTERNAL_CONTEXT"
 
 /**
- *  \brief If set to "0" then never set the top most bit on a SDL Window, even if the video mode expects it.
- *      This is a debugging aid for developers and not expected to be used by end users. The default is "1"
+ *  \brief If set to 1, then do not allow high-DPI windows. ("Retina" on Mac and iOS)
+ */
+#define SDL_HINT_VIDEO_HIGHDPI_DISABLED "SDL_VIDEO_HIGHDPI_DISABLED"
+
+/**
+ *  \brief  A variable that dictates policy for fullscreen Spaces on Mac OS X.
+ *
+ *  This hint only applies to Mac OS X.
+ *
+ *  The variable can be set to the following values:
+ *    "0"       - Disable Spaces support (FULLSCREEN_DESKTOP won't use them and
+ *                SDL_WINDOW_RESIZABLE windows won't offer the "fullscreen"
+ *                button on their titlebars).
+ *    "1"       - Enable Spaces support (FULLSCREEN_DESKTOP will use them and
+ *                SDL_WINDOW_RESIZABLE windows will offer the "fullscreen"
+ *                button on their titlebars).
+ *
+ *  The default value is "1". This hint must be set before any windows are created.
+ */
+#define SDL_HINT_VIDEO_MAC_FULLSCREEN_SPACES    "SDL_VIDEO_MAC_FULLSCREEN_SPACES"
+
+/**
+ *  \brief Minimize your SDL_Window if it loses key focus when in fullscreen mode. Defaults to false.
+ *  \warning  Before SDL 2.0.14, this defaulted to true! In 2.0.14, we're
+ *            seeing if "true" causes more problems than it solves in modern times.
+ *
+ */
+#define SDL_HINT_VIDEO_MINIMIZE_ON_FOCUS_LOSS   "SDL_VIDEO_MINIMIZE_ON_FOCUS_LOSS"
+
+/**
+ *  \brief  A variable controlling whether the libdecor Wayland backend is allowed to be used.
  *
  *  This variable can be set to the following values:
- *    "0"       - don't allow topmost
- *    "1"       - allow topmost
+ *    "0"       - libdecor use is disabled.
+ *    "1"       - libdecor use is enabled (default).
+ *
+ *  libdecor is used over xdg-shell when xdg-decoration protocol is unavailable.
  */
-#define SDL_HINT_ALLOW_TOPMOST "SDL_ALLOW_TOPMOST"
+#define SDL_HINT_VIDEO_WAYLAND_ALLOW_LIBDECOR "SDL_VIDEO_WAYLAND_ALLOW_LIBDECOR"
 
 /**
- *  \brief A variable that controls the timer resolution, in milliseconds.
+ *  \brief  A variable controlling whether the libdecor Wayland backend is preferred over native decrations.
  *
- *  The higher resolution the timer, the more frequently the CPU services
- *  timer interrupts, and the more precise delays are, but this takes up
- *  power and CPU time.  This hint is only used on Windows 7 and earlier.
+ *  When this hint is set, libdecor will be used to provide window decorations, even if xdg-decoration is
+ *  available. (Note that, by default, libdecor will use xdg-decoration itself if available).
  *
- *  See this blog post for more information:
- *  http://randomascii.wordpress.com/2013/07/08/windows-timer-resolution-megawatts-wasted/
+ *  This variable can be set to the following values:
+ *    "0"       - libdecor is enabled only if server-side decorations are unavailable.
+ *    "1"       - libdecor is always enabled if available.
  *
- *  If this variable is set to "0", the system timer resolution is not set.
+ *  libdecor is used over xdg-shell when xdg-decoration protocol is unavailable.
+ */
+#define SDL_HINT_VIDEO_WAYLAND_PREFER_LIBDECOR "SDL_VIDEO_WAYLAND_PREFER_LIBDECOR"
+
+/**
+ *  \brief  A variable controlling whether video mode emulation is enabled under Wayland.
  *
- *  The default value is "1". This hint may be set at any time.
+ *  When this hint is set, a standard set of emulated CVT video modes will be exposed for use by the application.
+ *  If it is disabled, the only modes exposed will be the logical desktop size and, in the case of a scaled
+ *  desktop, the native display resolution.
+ *
+ *  This variable can be set to the following values:
+ *    "0"       - Video mode emulation is disabled.
+ *    "1"       - Video mode emulation is enabled.
+ *
+ *  By default video mode emulation is enabled.
+ */
+#define SDL_HINT_VIDEO_WAYLAND_MODE_EMULATION "SDL_VIDEO_WAYLAND_MODE_EMULATION"
+
+/**
+ *  \brief  Enable or disable mouse pointer warp emulation, needed by some older games.
+ *
+ *  When this hint is set, any SDL will emulate mouse warps using relative mouse mode.
+ *  This is required for some older games (such as Source engine games), which warp the
+ *  mouse to the centre of the screen rather than using relative mouse motion. Note that
+ *  relative mouse mode may have different mouse acceleration behaviour than pointer warps.
+ *
+ *  This variable can be set to the following values:
+ *    "0"       - All mouse warps fail, as mouse warping is not available under wayland.
+ *    "1"       - Some mouse warps will be emulated by forcing relative mouse mode.
+ *
+ *  If not set, this is automatically enabled unless an application uses relative mouse
+ *  mode directly.
+ */
+#define SDL_HINT_VIDEO_WAYLAND_EMULATE_MOUSE_WARP "SDL_VIDEO_WAYLAND_EMULATE_MOUSE_WARP"
+
+/**
+*  \brief  A variable that is the address of another SDL_Window* (as a hex string formatted with "%p").
+*
+*  If this hint is set before SDL_CreateWindowFrom() and the SDL_Window* it is set to has
+*  SDL_WINDOW_OPENGL set (and running on WGL only, currently), then two things will occur on the newly
+*  created SDL_Window:
+*
+*  1. Its pixel format will be set to the same pixel format as this SDL_Window.  This is
+*  needed for example when sharing an OpenGL context across multiple windows.
+*
+*  2. The flag SDL_WINDOW_OPENGL will be set on the new window so it can be used for
+*  OpenGL rendering.
+*
+*  This variable can be set to the following values:
+*    The address (as a string "%p") of the SDL_Window* that new windows created with SDL_CreateWindowFrom() should
+*    share a pixel format with.
+*/
+#define SDL_HINT_VIDEO_WINDOW_SHARE_PIXEL_FORMAT    "SDL_VIDEO_WINDOW_SHARE_PIXEL_FORMAT"
+
+/**
+ *  \brief  When calling SDL_CreateWindowFrom(), make the window compatible with OpenGL.
+ *
+ * This variable can be set to the following values:
+ * "0" - Don't add any graphics flags to the SDL_WindowFlags
+ * "1" - Add SDL_WINDOW_OPENGL to the SDL_WindowFlags
+ *
+ * By default SDL will not make the foreign window compatible with OpenGL.
+ */
+#define SDL_HINT_VIDEO_FOREIGN_WINDOW_OPENGL "SDL_VIDEO_FOREIGN_WINDOW_OPENGL"
+
+/**
+ *  \brief  When calling SDL_CreateWindowFrom(), make the window compatible with Vulkan.
+ *
+ * This variable can be set to the following values:
+ * "0" - Don't add any graphics flags to the SDL_WindowFlags
+ * "1" - Add SDL_WINDOW_VULKAN to the SDL_WindowFlags
+ *
+ * By default SDL will not make the foreign window compatible with Vulkan.
+ */
+#define SDL_HINT_VIDEO_FOREIGN_WINDOW_VULKAN "SDL_VIDEO_FOREIGN_WINDOW_VULKAN"
+
+/**
+*  \brief  A variable specifying which shader compiler to preload when using the Chrome ANGLE binaries
+*
+*  SDL has EGL and OpenGL ES2 support on Windows via the ANGLE project. It
+*  can use two different sets of binaries, those compiled by the user from source
+*  or those provided by the Chrome browser. In the later case, these binaries require
+*  that SDL loads a DLL providing the shader compiler.
+*
+*  This variable can be set to the following values:
+*    "d3dcompiler_46.dll" - default, best for Vista or later.
+*    "d3dcompiler_43.dll" - for XP support.
+*    "none" - do not load any library, useful if you compiled ANGLE from source and included the compiler in your binaries.
+*
+*/
+#define SDL_HINT_VIDEO_WIN_D3DCOMPILER              "SDL_VIDEO_WIN_D3DCOMPILER"
+
+/**
+ * \brief A variable controlling whether X11 should use GLX or EGL by default
+ *
+ * This variable can be set to the following values:
+ * "0" - Use GLX
+ * "1" - Use EGL
+ *
+ * By default SDL will use GLX when both are present.
+ */
+#define SDL_HINT_VIDEO_X11_FORCE_EGL "SDL_VIDEO_X11_FORCE_EGL"
+
+/**
+ * \brief A variable controlling whether the X11 _NET_WM_BYPASS_COMPOSITOR hint should be used.
+ *
+ * This variable can be set to the following values:
+ * "0" - Disable _NET_WM_BYPASS_COMPOSITOR
+ * "1" - Enable _NET_WM_BYPASS_COMPOSITOR
+ *
+ * By default SDL will use _NET_WM_BYPASS_COMPOSITOR
+ *
+ */
+#define SDL_HINT_VIDEO_X11_NET_WM_BYPASS_COMPOSITOR "SDL_VIDEO_X11_NET_WM_BYPASS_COMPOSITOR"
+
+/**
+ *  \brief  A variable controlling whether the X11 _NET_WM_PING protocol should be supported.
+ *
+ *  This variable can be set to the following values:
+ *    "0"       - Disable _NET_WM_PING
+ *    "1"       - Enable _NET_WM_PING
+ *
+ *  By default SDL will use _NET_WM_PING, but for applications that know they
+ *  will not always be able to respond to ping requests in a timely manner they can
+ *  turn it off to avoid the window manager thinking the app is hung.
+ *  The hint is checked in CreateWindow.
+ */
+#define SDL_HINT_VIDEO_X11_NET_WM_PING      "SDL_VIDEO_X11_NET_WM_PING"
+
+/**
+ *  \brief  A variable forcing the visual ID chosen for new X11 windows
+ *
+ */
+#define SDL_HINT_VIDEO_X11_WINDOW_VISUALID      "SDL_VIDEO_X11_WINDOW_VISUALID"
+
+/**
+ *  \brief  A no-longer-used variable controlling whether the X11 Xinerama extension should be used.
+ *
+ * Before SDL 2.0.24, this would let apps and users disable Xinerama support on X11.
+ *  Now SDL never uses Xinerama, and does not check for this hint at all.
+ *  The preprocessor define is left here for source compatibility.
+ */
+#define SDL_HINT_VIDEO_X11_XINERAMA         "SDL_VIDEO_X11_XINERAMA"
+
+/**
+ *  \brief  A variable controlling whether the X11 XRandR extension should be used.
+ *
+ *  This variable can be set to the following values:
+ *    "0"       - Disable XRandR
+ *    "1"       - Enable XRandR
+ *
+ *  By default SDL will use XRandR.
+ */
+#define SDL_HINT_VIDEO_X11_XRANDR           "SDL_VIDEO_X11_XRANDR"
+
+/**
+ *  \brief  A no-longer-used variable controlling whether the X11 VidMode extension should be used.
+ *
+ * Before SDL 2.0.24, this would let apps and users disable XVidMode support on X11.
+ *  Now SDL never uses XVidMode, and does not check for this hint at all.
+ *  The preprocessor define is left here for source compatibility.
+ */
+#define SDL_HINT_VIDEO_X11_XVIDMODE         "SDL_VIDEO_X11_XVIDMODE"
+
+/**
+ *  \brief  Controls how the fact chunk affects the loading of a WAVE file.
+ *
+ *  The fact chunk stores information about the number of samples of a WAVE
+ *  file. The Standards Update from Microsoft notes that this value can be used
+ *  to 'determine the length of the data in seconds'. This is especially useful
+ *  for compressed formats (for which this is a mandatory chunk) if they produce
+ *  multiple sample frames per block and truncating the block is not allowed.
+ *  The fact chunk can exactly specify how many sample frames there should be
+ *  in this case.
+ *
+ *  Unfortunately, most application seem to ignore the fact chunk and so SDL
+ *  ignores it by default as well.
+ *
+ *  This variable can be set to the following values:
+ *
+ *    "truncate"    - Use the number of samples to truncate the wave data if
+ *                    the fact chunk is present and valid
+ *    "strict"      - Like "truncate", but raise an error if the fact chunk
+ *                    is invalid, not present for non-PCM formats, or if the
+ *                    data chunk doesn't have that many samples
+ *    "ignorezero"  - Like "truncate", but ignore fact chunk if the number of
+ *                    samples is zero
+ *    "ignore"      - Ignore fact chunk entirely (default)
+ */
+#define SDL_HINT_WAVE_FACT_CHUNK   "SDL_WAVE_FACT_CHUNK"
+
+/**
+ *  \brief  Controls how the size of the RIFF chunk affects the loading of a WAVE file.
+ *
+ *  The size of the RIFF chunk (which includes all the sub-chunks of the WAVE
+ *  file) is not always reliable. In case the size is wrong, it's possible to
+ *  just ignore it and step through the chunks until a fixed limit is reached.
+ *
+ *  Note that files that have trailing data unrelated to the WAVE file or
+ *  corrupt files may slow down the loading process without a reliable boundary.
+ *  By default, SDL stops after 10000 chunks to prevent wasting time. Use the
+ *  environment variable SDL_WAVE_CHUNK_LIMIT to adjust this value.
+ *
+ *  This variable can be set to the following values:
+ *
+ *    "force"        - Always use the RIFF chunk size as a boundary for the chunk search
+ *    "ignorezero"   - Like "force", but a zero size searches up to 4 GiB (default)
+ *    "ignore"       - Ignore the RIFF chunk size and always search up to 4 GiB
+ *    "maximum"      - Search for chunks until the end of file (not recommended)
+ */
+#define SDL_HINT_WAVE_RIFF_CHUNK_SIZE   "SDL_WAVE_RIFF_CHUNK_SIZE"
+
+/**
+ *  \brief  Controls how a truncated WAVE file is handled.
+ *
+ *  A WAVE file is considered truncated if any of the chunks are incomplete or
+ *  the data chunk size is not a multiple of the block size. By default, SDL
+ *  decodes until the first incomplete block, as most applications seem to do.
+ *
+ *  This variable can be set to the following values:
+ *
+ *    "verystrict" - Raise an error if the file is truncated
+ *    "strict"     - Like "verystrict", but the size of the RIFF chunk is ignored
+ *    "dropframe"  - Decode until the first incomplete sample frame
+ *    "dropblock"  - Decode until the first incomplete block (default)
+ */
+#define SDL_HINT_WAVE_TRUNCATION   "SDL_WAVE_TRUNCATION"
+
+/**
+ * \brief Tell SDL not to name threads on Windows with the 0x406D1388 Exception.
+ *        The 0x406D1388 Exception is a trick used to inform Visual Studio of a
+ *        thread's name, but it tends to cause problems with other debuggers,
+ *        and the .NET runtime. Note that SDL 2.0.6 and later will still use
+ *        the (safer) SetThreadDescription API, introduced in the Windows 10
+ *        Creators Update, if available.
+ *
+ * The variable can be set to the following values:
+ *   "0"       - SDL will raise the 0x406D1388 Exception to name threads.
+ *               This is the default behavior of SDL <= 2.0.4.
+ *   "1"       - SDL will not raise this exception, and threads will be unnamed. (default)
+ *               This is necessary with .NET languages or debuggers that aren't Visual Studio.
+ */
+#define SDL_HINT_WINDOWS_DISABLE_THREAD_NAMING "SDL_WINDOWS_DISABLE_THREAD_NAMING"
+
+/**
+ *  \brief Controls whether menus can be opened with their keyboard shortcut (Alt+mnemonic).
+ *
+ *  If the mnemonics are enabled, then menus can be opened by pressing the Alt
+ *  key and the corresponding mnemonic (for example, Alt+F opens the File menu).
+ *  However, in case an invalid mnemonic is pressed, Windows makes an audible
+ *  beep to convey that nothing happened. This is true even if the window has
+ *  no menu at all!
+ *
+ *  Because most SDL applications don't have menus, and some want to use the Alt
+ *  key for other purposes, SDL disables mnemonics (and the beeping) by default.
+ *
+ *  Note: This also affects keyboard events: with mnemonics enabled, when a
+ *  menu is opened from the keyboard, you will not receive a KEYUP event for
+ *  the mnemonic key, and *might* not receive one for Alt.
+ *
+ *  This variable can be set to the following values:
+ *    "0"       - Alt+mnemonic does nothing, no beeping. (default)
+ *    "1"       - Alt+mnemonic opens menus, invalid mnemonics produce a beep.
  */
-#define SDL_HINT_TIMER_RESOLUTION "SDL_TIMER_RESOLUTION"
-
+#define SDL_HINT_WINDOWS_ENABLE_MENU_MNEMONICS "SDL_WINDOWS_ENABLE_MENU_MNEMONICS"
 
 /**
- *  \brief  A variable describing the content orientation on QtWayland-based platforms.
- *
- *  On QtWayland platforms, windows are rotated client-side to allow for custom
- *  transitions. In order to correctly position overlays (e.g. volume bar) and
- *  gestures (e.g. events view, close/minimize gestures), the system needs to
- *  know in which orientation the application is currently drawing its contents.
+ *  \brief  A variable controlling whether the windows message loop is processed by SDL
  *
- *  This does not cause the window to be rotated or resized, the application
- *  needs to take care of drawing the content in the right orientation (the
- *  framebuffer is always in portrait mode).
+ *  This variable can be set to the following values:
+ *    "0"       - The window message loop is not run
+ *    "1"       - The window message loop is processed in SDL_PumpEvents()
  *
- *  This variable can be one of the following values:
- *    "primary" (default), "portrait", "landscape", "inverted-portrait", "inverted-landscape"
+ *  By default SDL will process the windows message loop
  */
-#define SDL_HINT_QTWAYLAND_CONTENT_ORIENTATION "SDL_QTWAYLAND_CONTENT_ORIENTATION"
+#define SDL_HINT_WINDOWS_ENABLE_MESSAGELOOP "SDL_WINDOWS_ENABLE_MESSAGELOOP"
 
 /**
- *  \brief  Flags to set on QtWayland windows to integrate with the native window manager.
+ * \brief Force SDL to use Critical Sections for mutexes on Windows.
+ *        On Windows 7 and newer, Slim Reader/Writer Locks are available.
+ *        They offer better performance, allocate no kernel ressources and
+ *        use less memory. SDL will fall back to Critical Sections on older
+ *        OS versions or if forced to by this hint.
  *
- *  On QtWayland platforms, this hint controls the flags to set on the windows.
- *  For example, on Sailfish OS "OverridesSystemGestures" disables swipe gestures.
+ *  This variable can be set to the following values:
+ *    "0"       - Use SRW Locks when available. If not, fall back to Critical Sections. (default)
+ *    "1"       - Force the use of Critical Sections in all cases.
  *
- *  This variable is a space-separated list of the following values (empty = no flags):
- *    "OverridesSystemGestures", "StaysOnTop", "BypassWindowManager"
  */
-#define SDL_HINT_QTWAYLAND_WINDOW_FLAGS "SDL_QTWAYLAND_WINDOW_FLAGS"
+#define SDL_HINT_WINDOWS_FORCE_MUTEX_CRITICAL_SECTIONS "SDL_WINDOWS_FORCE_MUTEX_CRITICAL_SECTIONS"
 
 /**
-*  \brief  A string specifying SDL's threads stack size in bytes or "0" for the backend's default size
-*
-*  Use this hint in case you need to set SDL's threads stack size to other than the default.
-*  This is specially useful if you build SDL against a non glibc libc library (such as musl) which
-*  provides a relatively small default thread stack size (a few kilobytes versus the default 8MB glibc uses).
-*  Support for this hint is currently available only in the pthread, Windows, and PSP backend.
-*
-*  Instead of this hint, in 2.0.9 and later, you can use
-*  SDL_CreateThreadWithStackSize(). This hint only works with the classic
-*  SDL_CreateThread().
-*/
-#define SDL_HINT_THREAD_STACK_SIZE              "SDL_THREAD_STACK_SIZE"
+ * \brief Force SDL to use Kernel Semaphores on Windows.
+ *        Kernel Semaphores are inter-process and require a context
+ *        switch on every interaction. On Windows 8 and newer, the
+ *        WaitOnAddress API is available. Using that and atomics to
+ *        implement semaphores increases performance.
+ *        SDL will fall back to Kernel Objects on older OS versions
+ *        or if forced to by this hint.
+ *
+ *  This variable can be set to the following values:
+ *    "0"       - Use Atomics and WaitOnAddress API when available. If not, fall back to Kernel Objects. (default)
+ *    "1"       - Force the use of Kernel Objects in all cases.
+ *
+ */
+#define SDL_HINT_WINDOWS_FORCE_SEMAPHORE_KERNEL "SDL_WINDOWS_FORCE_SEMAPHORE_KERNEL"
 
 /**
- *  \brief If set to 1, then do not allow high-DPI windows. ("Retina" on Mac and iOS)
+ * \brief A variable to specify custom icon resource id from RC file on Windows platform
  */
-#define SDL_HINT_VIDEO_HIGHDPI_DISABLED "SDL_VIDEO_HIGHDPI_DISABLED"
+#define SDL_HINT_WINDOWS_INTRESOURCE_ICON       "SDL_WINDOWS_INTRESOURCE_ICON"
+#define SDL_HINT_WINDOWS_INTRESOURCE_ICON_SMALL "SDL_WINDOWS_INTRESOURCE_ICON_SMALL"
 
 /**
- *  \brief A variable that determines whether ctrl+click should generate a right-click event on Mac
+ *  \brief Tell SDL not to generate window-close events for Alt+F4 on Windows.
  *
- *  If present, holding ctrl while left clicking will generate a right click
- *  event when on Mac.
+ * The variable can be set to the following values:
+ *   "0"       - SDL will generate a window-close event when it sees Alt+F4.
+ *   "1"       - SDL will only do normal key handling for Alt+F4.
  */
-#define SDL_HINT_MAC_CTRL_CLICK_EMULATE_RIGHT_CLICK "SDL_MAC_CTRL_CLICK_EMULATE_RIGHT_CLICK"
-
-/**
-*  \brief  A variable specifying which shader compiler to preload when using the Chrome ANGLE binaries
-*
-*  SDL has EGL and OpenGL ES2 support on Windows via the ANGLE project. It
-*  can use two different sets of binaries, those compiled by the user from source
-*  or those provided by the Chrome browser. In the later case, these binaries require
-*  that SDL loads a DLL providing the shader compiler.
-*
-*  This variable can be set to the following values:
-*    "d3dcompiler_46.dll" - default, best for Vista or later.
-*    "d3dcompiler_43.dll" - for XP support.
-*    "none" - do not load any library, useful if you compiled ANGLE from source and included the compiler in your binaries.
-*
-*/
-#define SDL_HINT_VIDEO_WIN_D3DCOMPILER              "SDL_VIDEO_WIN_D3DCOMPILER"
+#define SDL_HINT_WINDOWS_NO_CLOSE_ON_ALT_F4 "SDL_WINDOWS_NO_CLOSE_ON_ALT_F4"
 
 /**
-*  \brief  A variable that is the address of another SDL_Window* (as a hex string formatted with "%p").
-*  
-*  If this hint is set before SDL_CreateWindowFrom() and the SDL_Window* it is set to has
-*  SDL_WINDOW_OPENGL set (and running on WGL only, currently), then two things will occur on the newly 
-*  created SDL_Window:
-*
-*  1. Its pixel format will be set to the same pixel format as this SDL_Window.  This is
-*  needed for example when sharing an OpenGL context across multiple windows.
-*
-*  2. The flag SDL_WINDOW_OPENGL will be set on the new window so it can be used for
-*  OpenGL rendering.
-*
-*  This variable can be set to the following values:
-*    The address (as a string "%p") of the SDL_Window* that new windows created with SDL_CreateWindowFrom() should
-*    share a pixel format with.
-*/
-#define SDL_HINT_VIDEO_WINDOW_SHARE_PIXEL_FORMAT    "SDL_VIDEO_WINDOW_SHARE_PIXEL_FORMAT"
+ * \brief Use the D3D9Ex API introduced in Windows Vista, instead of normal D3D9.
+ *        Direct3D 9Ex contains changes to state management that can eliminate device
+ *        loss errors during scenarios like Alt+Tab or UAC prompts. D3D9Ex may require
+ *        some changes to your application to cope with the new behavior, so this
+ *        is disabled by default.
+ *
+ *  This hint must be set before initializing the video subsystem.
+ *
+ *  For more information on Direct3D 9Ex, see:
+ *    - https://docs.microsoft.com/en-us/windows/win32/direct3darticles/graphics-apis-in-windows-vista#direct3d-9ex
+ *    - https://docs.microsoft.com/en-us/windows/win32/direct3darticles/direct3d-9ex-improvements
+ *
+ *  This variable can be set to the following values:
+ *    "0"       - Use the original Direct3D 9 API (default)
+ *    "1"       - Use the Direct3D 9Ex API on Vista and later (and fall back if D3D9Ex is unavailable)
+ *
+ */
+#define SDL_HINT_WINDOWS_USE_D3D9EX "SDL_WINDOWS_USE_D3D9EX"
 
 /**
- *  \brief A URL to a WinRT app's privacy policy
+ * \brief Controls whether SDL will declare the process to be DPI aware.
  *
- *  All network-enabled WinRT apps must make a privacy policy available to its
- *  users.  On Windows 8, 8.1, and RT, Microsoft mandates that this policy be
- *  be available in the Windows Settings charm, as accessed from within the app.
- *  SDL provides code to add a URL-based link there, which can point to the app's
- *  privacy policy.
+ *  This hint must be set before initializing the video subsystem.
  *
- *  To setup a URL to an app's privacy policy, set SDL_HINT_WINRT_PRIVACY_POLICY_URL
- *  before calling any SDL_Init() functions.  The contents of the hint should
- *  be a valid URL.  For example, "http://www.example.com".
+ *  The main purpose of declaring DPI awareness is to disable OS bitmap scaling of SDL windows on monitors with
+ *  a DPI scale factor.
  *
- *  The default value is "", which will prevent SDL from adding a privacy policy
- *  link to the Settings charm.  This hint should only be set during app init.
+ *  This hint is equivalent to requesting DPI awareness via external means (e.g. calling SetProcessDpiAwarenessContext)
+ *  and does not cause SDL to use a virtualized coordinate system, so it will generally give you 1 SDL coordinate = 1 pixel
+ *  even on high-DPI displays.
  *
- *  The label text of an app's "Privacy Policy" link may be customized via another
- *  hint, SDL_HINT_WINRT_PRIVACY_POLICY_LABEL.
+ *  For more information, see:
+ *  https://docs.microsoft.com/en-us/windows/win32/hidpi/high-dpi-desktop-application-development-on-windows
  *
- *  Please note that on Windows Phone, Microsoft does not provide standard UI
- *  for displaying a privacy policy link, and as such, SDL_HINT_WINRT_PRIVACY_POLICY_URL
- *  will not get used on that platform.  Network-enabled phone apps should display
- *  their privacy policy through some other, in-app means.
+ *  This variable can be set to the following values:
+ *    ""             - Do not change the DPI awareness (default).
+ *    "unaware"      - Declare the process as DPI unaware. (Windows 8.1 and later).
+ *    "system"       - Request system DPI awareness. (Vista and later).
+ *    "permonitor"   - Request per-monitor DPI awareness. (Windows 8.1 and later).
+ *    "permonitorv2" - Request per-monitor V2 DPI awareness. (Windows 10, version 1607 and later).
+ *                     The most visible difference from "permonitor" is that window title bar will be scaled
+ *                     to the visually correct size when dragging between monitors with different scale factors.
+ *                     This is the preferred DPI awareness level.
+ *
+ * If the requested DPI awareness is not available on the currently running OS, SDL will try to request the best
+ * available match.
  */
-#define SDL_HINT_WINRT_PRIVACY_POLICY_URL "SDL_WINRT_PRIVACY_POLICY_URL"
+#define SDL_HINT_WINDOWS_DPI_AWARENESS "SDL_WINDOWS_DPI_AWARENESS"
 
-/** \brief Label text for a WinRT app's privacy policy link
+/**
+ * \brief Uses DPI-scaled points as the SDL coordinate system on Windows.
  *
- *  Network-enabled WinRT apps must include a privacy policy.  On Windows 8, 8.1, and RT,
- *  Microsoft mandates that this policy be available via the Windows Settings charm.
- *  SDL provides code to add a link there, with its label text being set via the
- *  optional hint, SDL_HINT_WINRT_PRIVACY_POLICY_LABEL.
+ *  This changes the SDL coordinate system units to be DPI-scaled points, rather than pixels everywhere.
+ *  This means windows will be appropriately sized, even when created on high-DPI displays with scaling.
  *
- *  Please note that a privacy policy's contents are not set via this hint.  A separate
- *  hint, SDL_HINT_WINRT_PRIVACY_POLICY_URL, is used to link to the actual text of the
- *  policy.
+ *  e.g. requesting a 640x480 window from SDL, on a display with 125% scaling in Windows display settings,
+ *  will create a window with an 800x600 client area (in pixels).
  *
- *  The contents of this hint should be encoded as a UTF8 string.
+ *  Setting this to "1" implicitly requests process DPI awareness (setting SDL_WINDOWS_DPI_AWARENESS is unnecessary),
+ *  and forces SDL_WINDOW_ALLOW_HIGHDPI on all windows.
  *
- *  The default value is "Privacy Policy".  This hint should only be set during app
- *  initialization, preferably before any calls to SDL_Init().
+ *  This variable can be set to the following values:
+ *    "0"       - SDL coordinates equal Windows coordinates. No automatic window resizing when dragging
+ *                between monitors with different scale factors (unless this is performed by
+ *                Windows itself, which is the case when the process is DPI unaware).
+ *    "1"       - SDL coordinates are in DPI-scaled points. Automatically resize windows as needed on
+ *                displays with non-100% scale factors.
+ */
+#define SDL_HINT_WINDOWS_DPI_SCALING "SDL_WINDOWS_DPI_SCALING"
+
+/**
+ *  \brief  A variable controlling whether the window frame and title bar are interactive when the cursor is hidden
  *
- *  For additional information on linking to a privacy policy, see the documentation for
- *  SDL_HINT_WINRT_PRIVACY_POLICY_URL.
+ *  This variable can be set to the following values:
+ *    "0"       - The window frame is not interactive when the cursor is hidden (no move, resize, etc)
+ *    "1"       - The window frame is interactive when the cursor is hidden
+ *
+ *  By default SDL will allow interaction with the window frame when the cursor is hidden
  */
-#define SDL_HINT_WINRT_PRIVACY_POLICY_LABEL "SDL_WINRT_PRIVACY_POLICY_LABEL"
+#define SDL_HINT_WINDOW_FRAME_USABLE_WHILE_CURSOR_HIDDEN    "SDL_WINDOW_FRAME_USABLE_WHILE_CURSOR_HIDDEN"
+
+/**
+*  \brief  A variable controlling whether the window is activated when the SDL_ShowWindow function is called
+*
+*  This variable can be set to the following values:
+*    "0"       - The window is activated when the SDL_ShowWindow function is called
+*    "1"       - The window is not activated when the SDL_ShowWindow function is called
+*
+*  By default SDL will activate the window when the SDL_ShowWindow function is called
+*/
+#define SDL_HINT_WINDOW_NO_ACTIVATION_WHEN_SHOWN    "SDL_WINDOW_NO_ACTIVATION_WHEN_SHOWN"
 
 /** \brief Allows back-button-press events on Windows Phone to be marked as handled
  *
@@ -793,386 +2210,238 @@ extern "C" {
  */
 #define SDL_HINT_WINRT_HANDLE_BACK_BUTTON "SDL_WINRT_HANDLE_BACK_BUTTON"
 
-/**
- *  \brief  A variable that dictates policy for fullscreen Spaces on Mac OS X.
- *
- *  This hint only applies to Mac OS X.
- *
- *  The variable can be set to the following values:
- *    "0"       - Disable Spaces support (FULLSCREEN_DESKTOP won't use them and
- *                SDL_WINDOW_RESIZABLE windows won't offer the "fullscreen"
- *                button on their titlebars).
- *    "1"       - Enable Spaces support (FULLSCREEN_DESKTOP will use them and
- *                SDL_WINDOW_RESIZABLE windows will offer the "fullscreen"
- *                button on their titlebars).
- *
- *  The default value is "1". Spaces are disabled regardless of this hint if
- *   the OS isn't at least Mac OS X Lion (10.7). This hint must be set before
- *   any windows are created.
- */
-#define SDL_HINT_VIDEO_MAC_FULLSCREEN_SPACES    "SDL_VIDEO_MAC_FULLSCREEN_SPACES"
-
-/**
-*  \brief  When set don't force the SDL app to become a foreground process
-*
-*  This hint only applies to Mac OS X.
-*
-*/
-#define SDL_HINT_MAC_BACKGROUND_APP    "SDL_MAC_BACKGROUND_APP"
-
-/**
- * \brief Android APK expansion main file version. Should be a string number like "1", "2" etc.
- *
- * Must be set together with SDL_HINT_ANDROID_APK_EXPANSION_PATCH_FILE_VERSION.
- *
- * If both hints were set then SDL_RWFromFile() will look into expansion files
- * after a given relative path was not found in the internal storage and assets.
- *
- * By default this hint is not set and the APK expansion files are not searched.
- */
-#define SDL_HINT_ANDROID_APK_EXPANSION_MAIN_FILE_VERSION "SDL_ANDROID_APK_EXPANSION_MAIN_FILE_VERSION"
- 
-/**
- * \brief Android APK expansion patch file version. Should be a string number like "1", "2" etc.
- *
- * Must be set together with SDL_HINT_ANDROID_APK_EXPANSION_MAIN_FILE_VERSION.
- *
- * If both hints were set then SDL_RWFromFile() will look into expansion files
- * after a given relative path was not found in the internal storage and assets.
- *
- * By default this hint is not set and the APK expansion files are not searched.
- */
-#define SDL_HINT_ANDROID_APK_EXPANSION_PATCH_FILE_VERSION "SDL_ANDROID_APK_EXPANSION_PATCH_FILE_VERSION"
-
-/**
- * \brief A variable to control whether certain IMEs should handle text editing internally instead of sending SDL_TEXTEDITING events.
- *
- * The variable can be set to the following values:
- *   "0"       - SDL_TEXTEDITING events are sent, and it is the application's
- *               responsibility to render the text from these events and 
- *               differentiate it somehow from committed text. (default)
- *   "1"       - If supported by the IME then SDL_TEXTEDITING events are not sent, 
- *               and text that is being composed will be rendered in its own UI.
- */
-#define SDL_HINT_IME_INTERNAL_EDITING "SDL_IME_INTERNAL_EDITING"
-
-/**
- * \brief A variable to control whether we trap the Android back button to handle it manually.
- *        This is necessary for the right mouse button to work on some Android devices, or
- *        to be able to trap the back button for use in your code reliably.  If set to true,
- *        the back button will show up as an SDL_KEYDOWN / SDL_KEYUP pair with a keycode of 
- *        SDL_SCANCODE_AC_BACK.
- *
- * The variable can be set to the following values:
- *   "0"       - Back button will be handled as usual for system. (default)
- *   "1"       - Back button will be trapped, allowing you to handle the key press
- *               manually.  (This will also let right mouse click work on systems 
- *               where the right mouse button functions as back.)
- *
- * The value of this hint is used at runtime, so it can be changed at any time.
- */
-#define SDL_HINT_ANDROID_TRAP_BACK_BUTTON "SDL_ANDROID_TRAP_BACK_BUTTON"
-
-/**
- * \brief A variable to control whether the event loop will block itself when the app is paused.
- *
- * The variable can be set to the following values:
- *   "0"       - Non blocking.
- *   "1"       - Blocking. (default)
- *
- * The value should be set before SDL is initialized.
- */
-#define SDL_HINT_ANDROID_BLOCK_ON_PAUSE "SDL_ANDROID_BLOCK_ON_PAUSE"
-
- /**
- * \brief A variable to control whether the return key on the soft keyboard
- *        should hide the soft keyboard on Android and iOS.
- *
- * The variable can be set to the following values:
- *   "0"       - The return key will be handled as a key event. This is the behaviour of SDL <= 2.0.3. (default)
- *   "1"       - The return key will hide the keyboard.
- *
- * The value of this hint is used at runtime, so it can be changed at any time.
- */
-#define SDL_HINT_RETURN_KEY_HIDES_IME "SDL_RETURN_KEY_HIDES_IME"
-
-/**
- *  \brief override the binding element for keyboard inputs for Emscripten builds
- *
- * This hint only applies to the emscripten platform
+/** \brief Label text for a WinRT app's privacy policy link
  *
- * The variable can be one of
- *    "#window"      - The javascript window object (this is the default)
- *    "#document"    - The javascript document object
- *    "#screen"      - the javascript window.screen object
- *    "#canvas"      - the WebGL canvas element
- *    any other string without a leading # sign applies to the element on the page with that ID.
- */
-#define SDL_HINT_EMSCRIPTEN_KEYBOARD_ELEMENT   "SDL_EMSCRIPTEN_KEYBOARD_ELEMENT"
-
-/**
- *  \brief Tell SDL not to catch the SIGINT or SIGTERM signals.
+ *  Network-enabled WinRT apps must include a privacy policy.  On Windows 8, 8.1, and RT,
+ *  Microsoft mandates that this policy be available via the Windows Settings charm.
+ *  SDL provides code to add a link there, with its label text being set via the
+ *  optional hint, SDL_HINT_WINRT_PRIVACY_POLICY_LABEL.
  *
- * This hint only applies to Unix-like platforms.
+ *  Please note that a privacy policy's contents are not set via this hint.  A separate
+ *  hint, SDL_HINT_WINRT_PRIVACY_POLICY_URL, is used to link to the actual text of the
+ *  policy.
  *
- * The variable can be set to the following values:
- *   "0"       - SDL will install a SIGINT and SIGTERM handler, and when it
- *               catches a signal, convert it into an SDL_QUIT event.
- *   "1"       - SDL will not install a signal handler at all.
- */
-#define SDL_HINT_NO_SIGNAL_HANDLERS   "SDL_NO_SIGNAL_HANDLERS"
-
-/**
- *  \brief Tell SDL not to generate window-close events for Alt+F4 on Windows.
+ *  The contents of this hint should be encoded as a UTF8 string.
  *
- * The variable can be set to the following values:
- *   "0"       - SDL will generate a window-close event when it sees Alt+F4.
- *   "1"       - SDL will only do normal key handling for Alt+F4.
+ *  The default value is "Privacy Policy".  This hint should only be set during app
+ *  initialization, preferably before any calls to SDL_Init().
+ *
+ *  For additional information on linking to a privacy policy, see the documentation for
+ *  SDL_HINT_WINRT_PRIVACY_POLICY_URL.
  */
-#define SDL_HINT_WINDOWS_NO_CLOSE_ON_ALT_F4 "SDL_WINDOWS_NO_CLOSE_ON_ALT_F4"
+#define SDL_HINT_WINRT_PRIVACY_POLICY_LABEL "SDL_WINRT_PRIVACY_POLICY_LABEL"
 
 /**
- *  \brief Prevent SDL from using version 4 of the bitmap header when saving BMPs.
+ *  \brief A URL to a WinRT app's privacy policy
  *
- * The bitmap header version 4 is required for proper alpha channel support and
- * SDL will use it when required. Should this not be desired, this hint can
- * force the use of the 40 byte header version which is supported everywhere.
+ *  All network-enabled WinRT apps must make a privacy policy available to its
+ *  users.  On Windows 8, 8.1, and RT, Microsoft mandates that this policy be
+ *  be available in the Windows Settings charm, as accessed from within the app.
+ *  SDL provides code to add a URL-based link there, which can point to the app's
+ *  privacy policy.
  *
- * The variable can be set to the following values:
- *   "0"       - Surfaces with a colorkey or an alpha channel are saved to a
- *               32-bit BMP file with an alpha mask. SDL will use the bitmap
- *               header version 4 and set the alpha mask accordingly.
- *   "1"       - Surfaces with a colorkey or an alpha channel are saved to a
- *               32-bit BMP file without an alpha mask. The alpha channel data
- *               will be in the file, but applications are going to ignore it.
+ *  To setup a URL to an app's privacy policy, set SDL_HINT_WINRT_PRIVACY_POLICY_URL
+ *  before calling any SDL_Init() functions.  The contents of the hint should
+ *  be a valid URL.  For example, "http://www.example.com".
  *
- * The default value is "0".
+ *  The default value is "", which will prevent SDL from adding a privacy policy
+ *  link to the Settings charm.  This hint should only be set during app init.
+ *
+ *  The label text of an app's "Privacy Policy" link may be customized via another
+ *  hint, SDL_HINT_WINRT_PRIVACY_POLICY_LABEL.
+ *
+ *  Please note that on Windows Phone, Microsoft does not provide standard UI
+ *  for displaying a privacy policy link, and as such, SDL_HINT_WINRT_PRIVACY_POLICY_URL
+ *  will not get used on that platform.  Network-enabled phone apps should display
+ *  their privacy policy through some other, in-app means.
  */
-#define SDL_HINT_BMP_SAVE_LEGACY_FORMAT "SDL_BMP_SAVE_LEGACY_FORMAT"
+#define SDL_HINT_WINRT_PRIVACY_POLICY_URL "SDL_WINRT_PRIVACY_POLICY_URL"
 
 /**
- * \brief Tell SDL not to name threads on Windows with the 0x406D1388 Exception.
- *        The 0x406D1388 Exception is a trick used to inform Visual Studio of a
- *        thread's name, but it tends to cause problems with other debuggers,
- *        and the .NET runtime. Note that SDL 2.0.6 and later will still use
- *        the (safer) SetThreadDescription API, introduced in the Windows 10
- *        Creators Update, if available.
+ *  \brief Mark X11 windows as override-redirect.
  *
- * The variable can be set to the following values:
- *   "0"       - SDL will raise the 0x406D1388 Exception to name threads.
- *               This is the default behavior of SDL <= 2.0.4.
- *   "1"       - SDL will not raise this exception, and threads will be unnamed. (default)
- *               This is necessary with .NET languages or debuggers that aren't Visual Studio.
+ *  If set, this _might_ increase framerate at the expense of the desktop
+ *  not working as expected. Override-redirect windows aren't noticed by the
+ *  window manager at all.
+ *
+ *  You should probably only use this for fullscreen windows, and you probably
+ *  shouldn't even use it for that. But it's here if you want to try!
  */
-#define SDL_HINT_WINDOWS_DISABLE_THREAD_NAMING "SDL_WINDOWS_DISABLE_THREAD_NAMING"
+#define SDL_HINT_X11_FORCE_OVERRIDE_REDIRECT "SDL_X11_FORCE_OVERRIDE_REDIRECT"
 
 /**
- * \brief Tell SDL which Dispmanx layer to use on a Raspberry PI
+ *  \brief  A variable that lets you disable the detection and use of Xinput gamepad devices
  *
- * Also known as Z-order. The variable can take a negative or positive value.
- * The default is 10000.
+ *  The variable can be set to the following values:
+ *    "0"       - Disable XInput detection (only uses direct input)
+ *    "1"       - Enable XInput detection (the default)
  */
-#define SDL_HINT_RPI_VIDEO_LAYER           "SDL_RPI_VIDEO_LAYER"
+#define SDL_HINT_XINPUT_ENABLED "SDL_XINPUT_ENABLED"
+
+ /**
+  *  \brief  A variable that lets you disable the detection and use of DirectInput gamepad devices
+  *
+  *  The variable can be set to the following values:
+  *    "0"       - Disable DirectInput detection (only uses XInput)
+  *    "1"       - Enable DirectInput detection (the default)
+  */
+#define SDL_HINT_DIRECTINPUT_ENABLED "SDL_DIRECTINPUT_ENABLED"
 
 /**
- * \brief Tell the video driver that we only want a double buffer.
+ *  \brief  A variable that causes SDL to use the old axis and button mapping for XInput devices.
  *
- * By default, most lowlevel 2D APIs will use a triple buffer scheme that 
- * wastes no CPU time on waiting for vsync after issuing a flip, but
- * introduces a frame of latency. On the other hand, using a double buffer
- * scheme instead is recommended for cases where low latency is an important
- * factor because we save a whole frame of latency.
- * We do so by waiting for vsync immediately after issuing a flip, usually just
- * after eglSwapBuffers call in the backend's *_SwapWindow function.
+ *  This hint is for backwards compatibility only and will be removed in SDL 2.1
  *
- * Since it's driver-specific, it's only supported where possible and
- * implemented. Currently supported the following drivers:
- * - KMSDRM (kmsdrm)
- * - Raspberry Pi (raspberrypi)
+ *  The default value is "0".  This hint must be set before SDL_Init()
  */
-#define SDL_HINT_VIDEO_DOUBLE_BUFFER      "SDL_VIDEO_DOUBLE_BUFFER"
+#define SDL_HINT_XINPUT_USE_OLD_JOYSTICK_MAPPING "SDL_XINPUT_USE_OLD_JOYSTICK_MAPPING"
 
 /**
- *  \brief  A variable controlling what driver to use for OpenGL ES contexts.
- *
- *  On some platforms, currently Windows and X11, OpenGL drivers may support
- *  creating contexts with an OpenGL ES profile. By default SDL uses these
- *  profiles, when available, otherwise it attempts to load an OpenGL ES
- *  library, e.g. that provided by the ANGLE project. This variable controls
- *  whether SDL follows this default behaviour or will always load an
- *  OpenGL ES library.
- *
- *  Circumstances where this is useful include
- *  - Testing an app with a particular OpenGL ES implementation, e.g ANGLE,
- *    or emulator, e.g. those from ARM, Imagination or Qualcomm.
- *  - Resolving OpenGL ES function addresses at link time by linking with
- *    the OpenGL ES library instead of querying them at run time with
- *    SDL_GL_GetProcAddress().
+ *  \brief  A variable that causes SDL to not ignore audio "monitors"
  *
- *  Caution: for an application to work with the default behaviour across
- *  different OpenGL drivers it must query the OpenGL ES function
- *  addresses at run time using SDL_GL_GetProcAddress().
+ *  This is currently only used for PulseAudio and ignored elsewhere.
  *
- *  This variable is ignored on most platforms because OpenGL ES is native
- *  or not supported.
+ *  By default, SDL ignores audio devices that aren't associated with physical
+ *  hardware. Changing this hint to "1" will expose anything SDL sees that
+ *  appears to be an audio source or sink. This will add "devices" to the list
+ *  that the user probably doesn't want or need, but it can be useful in
+ *  scenarios where you want to hook up SDL to some sort of virtual device,
+ *  etc.
  *
- *  This variable can be set to the following values:
- *    "0"       - Use ES profile of OpenGL, if available. (Default when not set.)
- *    "1"       - Load OpenGL ES library using the default library names.
+ *  The default value is "0".  This hint must be set before SDL_Init().
  *
+ *  This hint is available since SDL 2.0.16. Before then, virtual devices are
+ *  always ignored.
  */
-#define SDL_HINT_OPENGL_ES_DRIVER   "SDL_OPENGL_ES_DRIVER"
+#define SDL_HINT_AUDIO_INCLUDE_MONITORS "SDL_AUDIO_INCLUDE_MONITORS"
 
 /**
- *  \brief  A variable controlling speed/quality tradeoff of audio resampling.
- *
- *  If available, SDL can use libsamplerate ( http://www.mega-nerd.com/SRC/ )
- *  to handle audio resampling. There are different resampling modes available
- *  that produce different levels of quality, using more CPU.
- *
- *  If this hint isn't specified to a valid setting, or libsamplerate isn't
- *  available, SDL will use the default, internal resampling algorithm.
+ *  \brief  A variable that forces X11 windows to create as a custom type.
  *
- *  Note that this is currently only applicable to resampling audio that is
- *  being written to a device for playback or audio being read from a device
- *  for capture. SDL_AudioCVT always uses the default resampler (although this
- *  might change for SDL 2.1).
+ *  This is currently only used for X11 and ignored elsewhere.
  *
- *  This hint is currently only checked at audio subsystem initialization.
+ *  During SDL_CreateWindow, SDL uses the _NET_WM_WINDOW_TYPE X11 property
+ *  to report to the window manager the type of window it wants to create.
+ *  This might be set to various things if SDL_WINDOW_TOOLTIP or
+ *  SDL_WINDOW_POPUP_MENU, etc, were specified. For "normal" windows that
+ *  haven't set a specific type, this hint can be used to specify a custom
+ *  type. For example, a dock window might set this to
+ *  "_NET_WM_WINDOW_TYPE_DOCK".
  *
- *  This variable can be set to the following values:
+ *  If not set or set to "", this hint is ignored. This hint must be set
+ *  before the SDL_CreateWindow() call that it is intended to affect.
  *
- *    "0" or "default" - Use SDL's internal resampling (Default when not set - low quality, fast)
- *    "1" or "fast"    - Use fast, slightly higher quality resampling, if available
- *    "2" or "medium"  - Use medium quality resampling, if available
- *    "3" or "best"    - Use high quality resampling, if available
+ *  This hint is available since SDL 2.0.22.
  */
-#define SDL_HINT_AUDIO_RESAMPLING_MODE   "SDL_AUDIO_RESAMPLING_MODE"
+#define SDL_HINT_X11_WINDOW_TYPE "SDL_X11_WINDOW_TYPE"
 
 /**
- *  \brief  A variable controlling the audio category on iOS and Mac OS X
- *
- *  This variable can be set to the following values:
+ *  \brief  A variable that decides whether to send SDL_QUIT when closing the final window.
  *
- *    "ambient"     - Use the AVAudioSessionCategoryAmbient audio category, will be muted by the phone mute switch (default)
- *    "playback"    - Use the AVAudioSessionCategoryPlayback category
+ *  By default, SDL sends an SDL_QUIT event when there is only one window
+ *  and it receives an SDL_WINDOWEVENT_CLOSE event, under the assumption most
+ *  apps would also take the loss of this window as a signal to terminate the
+ *  program.
  *
- *  For more information, see Apple's documentation:
- *  https://developer.apple.com/library/content/documentation/Audio/Conceptual/AudioSessionProgrammingGuide/AudioSessionCategoriesandModes/AudioSessionCategoriesandModes.html
- */
-#define SDL_HINT_AUDIO_CATEGORY   "SDL_AUDIO_CATEGORY"
-
-/**
- *  \brief  A variable controlling whether the 2D render API is compatible or efficient.
+ *  However, it's not unreasonable in some cases to have the program continue
+ *  to live on, perhaps to create new windows later.
  *
- *  This variable can be set to the following values:
+ *  Changing this hint to "0" will cause SDL to not send an SDL_QUIT event
+ *  when the final window is requesting to close. Note that in this case,
+ *  there are still other legitimate reasons one might get an SDL_QUIT
+ *  event: choosing "Quit" from the macOS menu bar, sending a SIGINT (ctrl-c)
+ *  on Unix, etc.
  *
- *    "0"     - Don't use batching to make rendering more efficient.
- *    "1"     - Use batching, but might cause problems if app makes its own direct OpenGL calls.
+ *  The default value is "1".  This hint can be changed at any time.
  *
- *  Up to SDL 2.0.9, the render API would draw immediately when requested. Now
- *  it batches up draw requests and sends them all to the GPU only when forced
- *  to (during SDL_RenderPresent, when changing render targets, by updating a
- *  texture that the batch needs, etc). This is significantly more efficient,
- *  but it can cause problems for apps that expect to render on top of the
- *  render API's output. As such, SDL will disable batching if a specific
- *  render backend is requested (since this might indicate that the app is
- *  planning to use the underlying graphics API directly). This hint can
- *  be used to explicitly request batching in this instance. It is a contract
- *  that you will either never use the underlying graphics API directly, or
- *  if you do, you will call SDL_RenderFlush() before you do so any current
- *  batch goes to the GPU before your work begins. Not following this contract
- *  will result in undefined behavior.
+ *  This hint is available since SDL 2.0.22. Before then, you always get
+ *  an SDL_QUIT event when closing the final window.
  */
-#define SDL_HINT_RENDER_BATCHING  "SDL_RENDER_BATCHING"
+#define SDL_HINT_QUIT_ON_LAST_WINDOW_CLOSE "SDL_QUIT_ON_LAST_WINDOW_CLOSE"
 
 
 /**
- *  \brief  A variable controlling whether SDL logs all events pushed onto its internal queue.
+ *  \brief  A variable that decides what video backend to use.
  *
- *  This variable can be set to the following values:
+ *  By default, SDL will try all available video backends in a reasonable
+ *  order until it finds one that can work, but this hint allows the app
+ *  or user to force a specific target, such as "x11" if, say, you are
+ *  on Wayland but want to try talking to the X server instead.
  *
- *    "0"     - Don't log any events (default)
- *    "1"     - Log all events except mouse and finger motion, which are pretty spammy.
- *    "2"     - Log all events.
+ *  This functionality has existed since SDL 2.0.0 (indeed, before that)
+ *  but before 2.0.22 this was an environment variable only. In 2.0.22,
+ *  it was upgraded to a full SDL hint, so you can set the environment
+ *  variable as usual or programatically set the hint with SDL_SetHint,
+ *  which won't propagate to child processes.
  *
- *  This is generally meant to be used to debug SDL itself, but can be useful
- *  for application developers that need better visibility into what is going
- *  on in the event queue. Logged events are sent through SDL_Log(), which
- *  means by default they appear on stdout on most platforms or maybe
- *  OutputDebugString() on Windows, and can be funneled by the app with
- *  SDL_LogSetOutputFunction(), etc.
+ *  The default value is unset, in which case SDL will try to figure out
+ *  the best video backend on your behalf. This hint needs to be set
+ *  before SDL_Init() is called to be useful.
  *
- *  This hint can be toggled on and off at runtime, if you only need to log
- *  events for a small subset of program execution.
+ *  This hint is available since SDL 2.0.22. Before then, you could set
+ *  the environment variable to get the same effect.
  */
-#define SDL_HINT_EVENT_LOGGING   "SDL_EVENT_LOGGING"
-
-
+#define SDL_HINT_VIDEODRIVER "SDL_VIDEODRIVER"
 
 /**
- *  \brief  Controls how the size of the RIFF chunk affects the loading of a WAVE file.
+ *  \brief  A variable that decides what audio backend to use.
  *
- *  The size of the RIFF chunk (which includes all the sub-chunks of the WAVE
- *  file) is not always reliable. In case the size is wrong, it's possible to
- *  just ignore it and step through the chunks until a fixed limit is reached.
+ *  By default, SDL will try all available audio backends in a reasonable
+ *  order until it finds one that can work, but this hint allows the app
+ *  or user to force a specific target, such as "alsa" if, say, you are
+ *  on PulseAudio but want to try talking to the lower level instead.
  *
- *  Note that files that have trailing data unrelated to the WAVE file or
- *  corrupt files may slow down the loading process without a reliable boundary.
- *  By default, SDL stops after 10000 chunks to prevent wasting time. Use the
- *  environment variable SDL_WAVE_CHUNK_LIMIT to adjust this value.
+ *  This functionality has existed since SDL 2.0.0 (indeed, before that)
+ *  but before 2.0.22 this was an environment variable only. In 2.0.22,
+ *  it was upgraded to a full SDL hint, so you can set the environment
+ *  variable as usual or programatically set the hint with SDL_SetHint,
+ *  which won't propagate to child processes.
  *
- *  This variable can be set to the following values:
+ *  The default value is unset, in which case SDL will try to figure out
+ *  the best audio backend on your behalf. This hint needs to be set
+ *  before SDL_Init() is called to be useful.
  *
- *    "force"        - Always use the RIFF chunk size as a boundary for the chunk search
- *    "ignorezero"   - Like "force", but a zero size searches up to 4 GiB (default)
- *    "ignore"       - Ignore the RIFF chunk size and always search up to 4 GiB
- *    "maximum"      - Search for chunks until the end of file (not recommended)
+ *  This hint is available since SDL 2.0.22. Before then, you could set
+ *  the environment variable to get the same effect.
  */
-#define SDL_HINT_WAVE_RIFF_CHUNK_SIZE   "SDL_WAVE_RIFF_CHUNK_SIZE"
+#define SDL_HINT_AUDIODRIVER "SDL_AUDIODRIVER"
 
 /**
- *  \brief  Controls how a truncated WAVE file is handled.
+ *  \brief  A variable that decides what KMSDRM device to use.
  *
- *  A WAVE file is considered truncated if any of the chunks are incomplete or
- *  the data chunk size is not a multiple of the block size. By default, SDL
- *  decodes until the first incomplete block, as most applications seem to do.
+ *  Internally, SDL might open something like "/dev/dri/cardNN" to
+ *  access KMSDRM functionality, where "NN" is a device index number.
  *
- *  This variable can be set to the following values:
+ *  SDL makes a guess at the best index to use (usually zero), but the
+ *  app or user can set this hint to a number between 0 and 99 to
+ *  force selection.
  *
- *    "verystrict" - Raise an error if the file is truncated
- *    "strict"     - Like "verystrict", but the size of the RIFF chunk is ignored
- *    "dropframe"  - Decode until the first incomplete sample frame
- *    "dropblock"  - Decode until the first incomplete block (default)
+ *  This hint is available since SDL 2.24.0.
  */
-#define SDL_HINT_WAVE_TRUNCATION   "SDL_WAVE_TRUNCATION"
+#define SDL_HINT_KMSDRM_DEVICE_INDEX "SDL_KMSDRM_DEVICE_INDEX"
+
 
 /**
- *  \brief  Controls how the fact chunk affects the loading of a WAVE file.
+ *  \brief  A variable that treats trackpads as touch devices.
  *
- *  The fact chunk stores information about the number of samples of a WAVE
- *  file. The Standards Update from Microsoft notes that this value can be used
- *  to 'determine the length of the data in seconds'. This is especially useful
- *  for compressed formats (for which this is a mandatory chunk) if they produce
- *  multiple sample frames per block and truncating the block is not allowed.
- *  The fact chunk can exactly specify how many sample frames there should be
- *  in this case.
+ *  On macOS (and possibly other platforms in the future), SDL will report
+ *  touches on a trackpad as mouse input, which is generally what users
+ *  expect from this device; however, these are often actually full
+ *  multitouch-capable touch devices, so it might be preferable to some apps
+ *  to treat them as such.
  *
- *  Unfortunately, most application seem to ignore the fact chunk and so SDL
- *  ignores it by default as well.
+ *  Setting this hint to true will make the trackpad input report as a
+ *  multitouch device instead of a mouse. The default is false.
  *
- *  This variable can be set to the following values:
+ *  Note that most platforms don't support this hint. As of 2.24.0, it
+ *  only supports MacBooks' trackpads on macOS. Others may follow later.
  *
- *    "truncate"    - Use the number of samples to truncate the wave data if
- *                    the fact chunk is present and valid
- *    "strict"      - Like "truncate", but raise an error if the fact chunk
- *                    is invalid, not present for non-PCM formats, or if the
- *                    data chunk doesn't have that many samples
- *    "ignorezero"  - Like "truncate", but ignore fact chunk if the number of
- *                    samples is zero
- *    "ignore"      - Ignore fact chunk entirely (default)
+ *  This hint is checked during SDL_Init and can not be changed after.
+ *
+ *  This hint is available since SDL 2.24.0.
  */
-#define SDL_HINT_WAVE_FACT_CHUNK   "SDL_WAVE_FACT_CHUNK"
+#define SDL_HINT_TRACKPAD_IS_TOUCH_ONLY "SDL_TRACKPAD_IS_TOUCH_ONLY"
+
 
 /**
  *  \brief  An enumeration of hint priorities
@@ -1186,71 +2455,160 @@ typedef enum
 
 
 /**
- *  \brief Set a hint with a specific priority
+ * Set a hint with a specific priority.
+ *
+ * The priority controls the behavior when setting a hint that already has a
+ * value. Hints will replace existing hints of their priority and lower.
+ * Environment variables are considered to have override priority.
+ *
+ * \param name the hint to set
+ * \param value the value of the hint variable
+ * \param priority the SDL_HintPriority level for the hint
+ * \returns SDL_TRUE if the hint was set, SDL_FALSE otherwise.
  *
- *  The priority controls the behavior when setting a hint that already
- *  has a value.  Hints will replace existing hints of their priority and
- *  lower.  Environment variables are considered to have override priority.
+ * \since This function is available since SDL 2.0.0.
  *
- *  \return SDL_TRUE if the hint was set, SDL_FALSE otherwise
+ * \sa SDL_GetHint
+ * \sa SDL_SetHint
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_SetHintWithPriority(const char *name,
                                                          const char *value,
                                                          SDL_HintPriority priority);
 
 /**
- *  \brief Set a hint with normal priority
+ * Set a hint with normal priority.
  *
- *  \return SDL_TRUE if the hint was set, SDL_FALSE otherwise
+ * Hints will not be set if there is an existing override hint or environment
+ * variable that takes precedence. You can use SDL_SetHintWithPriority() to
+ * set the hint with override priority instead.
+ *
+ * \param name the hint to set
+ * \param value the value of the hint variable
+ * \returns SDL_TRUE if the hint was set, SDL_FALSE otherwise.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetHint
+ * \sa SDL_SetHintWithPriority
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_SetHint(const char *name,
                                              const char *value);
 
 /**
- *  \brief Get a hint
+ * Reset a hint to the default value.
+ *
+ * This will reset a hint to the value of the environment variable, or NULL if
+ * the environment isn't set. Callbacks will be called normally with this
+ * change.
+ *
+ * \param name the hint to set
+ * \returns SDL_TRUE if the hint was set, SDL_FALSE otherwise.
+ *
+ * \since This function is available since SDL 2.24.0.
+ *
+ * \sa SDL_GetHint
+ * \sa SDL_SetHint
+ */
+extern DECLSPEC SDL_bool SDLCALL SDL_ResetHint(const char *name);
+
+/**
+ * Reset all hints to the default values.
+ *
+ * This will reset all hints to the value of the associated environment
+ * variable, or NULL if the environment isn't set. Callbacks will be called
+ * normally with this change.
+ *
+ * \since This function is available since SDL 2.26.0.
+ *
+ * \sa SDL_GetHint
+ * \sa SDL_SetHint
+ * \sa SDL_ResetHint
+ */
+extern DECLSPEC void SDLCALL SDL_ResetHints(void);
+
+/**
+ * Get the value of a hint.
  *
- *  \return The string value of a hint variable.
+ * \param name the hint to query
+ * \returns the string value of a hint or NULL if the hint isn't set.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_SetHint
+ * \sa SDL_SetHintWithPriority
  */
 extern DECLSPEC const char * SDLCALL SDL_GetHint(const char *name);
 
 /**
- *  \brief Get a hint
+ * Get the boolean value of a hint variable.
+ *
+ * \param name the name of the hint to get the boolean value from
+ * \param default_value the value to return if the hint does not exist
+ * \returns the boolean value of a hint or the provided default value if the
+ *          hint does not exist.
+ *
+ * \since This function is available since SDL 2.0.5.
  *
- *  \return The boolean value of a hint variable.
+ * \sa SDL_GetHint
+ * \sa SDL_SetHint
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_GetHintBoolean(const char *name, SDL_bool default_value);
 
 /**
- * \brief type definition of the hint callback function.
+ * Type definition of the hint callback function.
+ *
+ * \param userdata what was passed as `userdata` to SDL_AddHintCallback()
+ * \param name what was passed as `name` to SDL_AddHintCallback()
+ * \param oldValue the previous hint value
+ * \param newValue the new value hint is to be set to
  */
 typedef void (SDLCALL *SDL_HintCallback)(void *userdata, const char *name, const char *oldValue, const char *newValue);
 
 /**
- *  \brief Add a function to watch a particular hint
+ * Add a function to watch a particular hint.
+ *
+ * \param name the hint to watch
+ * \param callback An SDL_HintCallback function that will be called when the
+ *                 hint value changes
+ * \param userdata a pointer to pass to the callback function
  *
- *  \param name The hint to watch
- *  \param callback The function to call when the hint value changes
- *  \param userdata A pointer to pass to the callback function
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_DelHintCallback
  */
 extern DECLSPEC void SDLCALL SDL_AddHintCallback(const char *name,
                                                  SDL_HintCallback callback,
                                                  void *userdata);
 
 /**
- *  \brief Remove a function watching a particular hint
+ * Remove a function watching a particular hint.
+ *
+ * \param name the hint being watched
+ * \param callback An SDL_HintCallback function that will be called when the
+ *                 hint value changes
+ * \param userdata a pointer being passed to the callback function
  *
- *  \param name The hint being watched
- *  \param callback The function being called when the hint value changes
- *  \param userdata A pointer being passed to the callback function
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_AddHintCallback
  */
 extern DECLSPEC void SDLCALL SDL_DelHintCallback(const char *name,
                                                  SDL_HintCallback callback,
                                                  void *userdata);
 
 /**
- *  \brief  Clear all hints
+ * Clear all hints.
+ *
+ * This function is automatically called during SDL_Quit(), and deletes all
+ * callbacks without calling them and frees all memory associated with hints.
+ * If you're calling this from application code you probably want to call
+ * SDL_ResetHints() instead.
+ *
+ * This function will be removed from the API the next time we rev the ABI.
+ *
+ * \since This function is available since SDL 2.0.0.
  *
- *  This function is called during SDL_Quit() to free stored hints.
+ * \sa SDL_ResetHints
  */
 extern DECLSPEC void SDLCALL SDL_ClearHints(void);
 

libs/SDL2/i686-w64-mingw32/include/SDL2/SDL_joystick.h

 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -30,10 +30,12 @@
  * The term "instance_id" is the current instantiation of a joystick device in the system, if the joystick is removed and then re-inserted
  *   then it will get a new instance_id, instance_id's are monotonically increasing identifiers of a joystick plugged in.
  *
+ * The term "player_index" is the number assigned to a player on a specific
+ *   controller. For XInput controllers this returns the XInput user index.
+ *   Many joysticks will not be able to supply this information.
+ *
  * The term JoystickGUID is a stable 128-bit identifier for a joystick device that does not change over time, it identifies class of
  *   the device (a X360 wired controller for example). This identifier is platform dependent.
- *
- *
  */
 
 #ifndef SDL_joystick_h_
@@ -41,6 +43,8 @@
 
 #include "SDL_stdinc.h"
 #include "SDL_error.h"
+#include "SDL_guid.h"
+#include "SDL_mutex.h"
 
 #include "begin_code.h"
 /* Set up for C function definitions, even when using C++ */
@@ -63,13 +67,14 @@ extern "C" {
 /**
  * The joystick structure used to identify an SDL joystick
  */
+#ifdef SDL_THREAD_SAFETY_ANALYSIS
+extern SDL_mutex *SDL_joystick_lock;
+#endif
 struct _SDL_Joystick;
 typedef struct _SDL_Joystick SDL_Joystick;
 
 /* A structure that encodes the stable unique id for a joystick device */
-typedef struct {
-    Uint8 data[16];
-} SDL_JoystickGUID;
+typedef SDL_GUID SDL_JoystickGUID;
 
 /**
  * This is a unique ID for a joystick for the time it is connected to the system,
@@ -105,6 +110,12 @@ typedef enum
     SDL_JOYSTICK_POWER_MAX
 } SDL_JoystickPowerLevel;
 
+/* Set max recognized G-force from accelerometer
+   See src/joystick/uikit/SDL_sysjoystick.m for notes on why this is needed
+ */
+#define SDL_IPHONE_MAX_GFORCE 5.0
+
+
 /* Function prototypes */
 
 /**
@@ -116,210 +127,725 @@ typedef enum
  * In particular, you are guaranteed that the joystick list won't change, so
  * the API functions that take a joystick index will be valid, and joystick
  * and game controller events will not be delivered.
+ *
+ * As of SDL 2.26.0, you can take the joystick lock around reinitializing the
+ * joystick subsystem, to prevent other threads from seeing joysticks in an
+ * uninitialized state. However, all open joysticks will be closed and SDL
+ * functions called with them will fail.
+ *
+ * \since This function is available since SDL 2.0.7.
  */
-extern DECLSPEC void SDLCALL SDL_LockJoysticks(void);
-extern DECLSPEC void SDLCALL SDL_UnlockJoysticks(void);
+extern DECLSPEC void SDLCALL SDL_LockJoysticks(void) SDL_ACQUIRE(SDL_joystick_lock);
+
 
 /**
- *  Count the number of joysticks attached to the system right now
+ * Unlocking for multi-threaded access to the joystick API
+ *
+ * If you are using the joystick API or handling events from multiple threads
+ * you should use these locking functions to protect access to the joysticks.
+ *
+ * In particular, you are guaranteed that the joystick list won't change, so
+ * the API functions that take a joystick index will be valid, and joystick
+ * and game controller events will not be delivered.
+ *
+ * \since This function is available since SDL 2.0.7.
+ */
+extern DECLSPEC void SDLCALL SDL_UnlockJoysticks(void) SDL_RELEASE(SDL_joystick_lock);
+
+/**
+ * Count the number of joysticks attached to the system.
+ *
+ * \returns the number of attached joysticks on success or a negative error
+ *          code on failure; call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_JoystickName
+ * \sa SDL_JoystickPath
+ * \sa SDL_JoystickOpen
  */
 extern DECLSPEC int SDLCALL SDL_NumJoysticks(void);
 
 /**
- *  Get the implementation dependent name of a joystick.
- *  This can be called before any joysticks are opened.
- *  If no name can be found, this function returns NULL.
+ * Get the implementation dependent name of a joystick.
+ *
+ * This can be called before any joysticks are opened.
+ *
+ * \param device_index the index of the joystick to query (the N'th joystick
+ *                     on the system)
+ * \returns the name of the selected joystick. If no name can be found, this
+ *          function returns NULL; call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_JoystickName
+ * \sa SDL_JoystickOpen
  */
 extern DECLSPEC const char *SDLCALL SDL_JoystickNameForIndex(int device_index);
 
 /**
- *  Get the player index of a joystick, or -1 if it's not available
- *  This can be called before any joysticks are opened.
+ * Get the implementation dependent path of a joystick.
+ *
+ * This can be called before any joysticks are opened.
+ *
+ * \param device_index the index of the joystick to query (the N'th joystick
+ *                     on the system)
+ * \returns the path of the selected joystick. If no path can be found, this
+ *          function returns NULL; call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.24.0.
+ *
+ * \sa SDL_JoystickPath
+ * \sa SDL_JoystickOpen
+ */
+extern DECLSPEC const char *SDLCALL SDL_JoystickPathForIndex(int device_index);
+
+/**
+ * Get the player index of a joystick, or -1 if it's not available This can be
+ * called before any joysticks are opened.
+ *
+ * \since This function is available since SDL 2.0.9.
  */
 extern DECLSPEC int SDLCALL SDL_JoystickGetDevicePlayerIndex(int device_index);
 
 /**
- *  Return the GUID for the joystick at this index
- *  This can be called before any joysticks are opened.
+ * Get the implementation-dependent GUID for the joystick at a given device
+ * index.
+ *
+ * This function can be called before any joysticks are opened.
+ *
+ * \param device_index the index of the joystick to query (the N'th joystick
+ *                     on the system
+ * \returns the GUID of the selected joystick. If called on an invalid index,
+ *          this function returns a zero GUID
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_JoystickGetGUID
+ * \sa SDL_JoystickGetGUIDString
  */
 extern DECLSPEC SDL_JoystickGUID SDLCALL SDL_JoystickGetDeviceGUID(int device_index);
 
 /**
- *  Get the USB vendor ID of a joystick, if available.
- *  This can be called before any joysticks are opened.
- *  If the vendor ID isn't available this function returns 0.
+ * Get the USB vendor ID of a joystick, if available.
+ *
+ * This can be called before any joysticks are opened. If the vendor ID isn't
+ * available this function returns 0.
+ *
+ * \param device_index the index of the joystick to query (the N'th joystick
+ *                     on the system
+ * \returns the USB vendor ID of the selected joystick. If called on an
+ *          invalid index, this function returns zero
+ *
+ * \since This function is available since SDL 2.0.6.
  */
 extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetDeviceVendor(int device_index);
 
 /**
- *  Get the USB product ID of a joystick, if available.
- *  This can be called before any joysticks are opened.
- *  If the product ID isn't available this function returns 0.
+ * Get the USB product ID of a joystick, if available.
+ *
+ * This can be called before any joysticks are opened. If the product ID isn't
+ * available this function returns 0.
+ *
+ * \param device_index the index of the joystick to query (the N'th joystick
+ *                     on the system
+ * \returns the USB product ID of the selected joystick. If called on an
+ *          invalid index, this function returns zero
+ *
+ * \since This function is available since SDL 2.0.6.
  */
 extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetDeviceProduct(int device_index);
 
 /**
- *  Get the product version of a joystick, if available.
- *  This can be called before any joysticks are opened.
- *  If the product version isn't available this function returns 0.
+ * Get the product version of a joystick, if available.
+ *
+ * This can be called before any joysticks are opened. If the product version
+ * isn't available this function returns 0.
+ *
+ * \param device_index the index of the joystick to query (the N'th joystick
+ *                     on the system
+ * \returns the product version of the selected joystick. If called on an
+ *          invalid index, this function returns zero
+ *
+ * \since This function is available since SDL 2.0.6.
  */
 extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetDeviceProductVersion(int device_index);
 
 /**
- *  Get the type of a joystick, if available.
- *  This can be called before any joysticks are opened.
+ * Get the type of a joystick, if available.
+ *
+ * This can be called before any joysticks are opened.
+ *
+ * \param device_index the index of the joystick to query (the N'th joystick
+ *                     on the system
+ * \returns the SDL_JoystickType of the selected joystick. If called on an
+ *          invalid index, this function returns `SDL_JOYSTICK_TYPE_UNKNOWN`
+ *
+ * \since This function is available since SDL 2.0.6.
  */
 extern DECLSPEC SDL_JoystickType SDLCALL SDL_JoystickGetDeviceType(int device_index);
 
 /**
- *  Get the instance ID of a joystick.
- *  This can be called before any joysticks are opened.
- *  If the index is out of range, this function will return -1.
+ * Get the instance ID of a joystick.
+ *
+ * This can be called before any joysticks are opened.
+ *
+ * \param device_index the index of the joystick to query (the N'th joystick
+ *                     on the system
+ * \returns the instance id of the selected joystick. If called on an invalid
+ *          index, this function returns -1.
+ *
+ * \since This function is available since SDL 2.0.6.
  */
 extern DECLSPEC SDL_JoystickID SDLCALL SDL_JoystickGetDeviceInstanceID(int device_index);
 
 /**
- *  Open a joystick for use.
- *  The index passed as an argument refers to the N'th joystick on the system.
- *  This index is not the value which will identify this joystick in future
- *  joystick events.  The joystick's instance id (::SDL_JoystickID) will be used
- *  there instead.
+ * Open a joystick for use.
+ *
+ * The `device_index` argument refers to the N'th joystick presently
+ * recognized by SDL on the system. It is **NOT** the same as the instance ID
+ * used to identify the joystick in future events. See
+ * SDL_JoystickInstanceID() for more details about instance IDs.
+ *
+ * The joystick subsystem must be initialized before a joystick can be opened
+ * for use.
  *
- *  \return A joystick identifier, or NULL if an error occurred.
+ * \param device_index the index of the joystick to query
+ * \returns a joystick identifier or NULL if an error occurred; call
+ *          SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_JoystickClose
+ * \sa SDL_JoystickInstanceID
  */
 extern DECLSPEC SDL_Joystick *SDLCALL SDL_JoystickOpen(int device_index);
 
 /**
- * Return the SDL_Joystick associated with an instance id.
+ * Get the SDL_Joystick associated with an instance id.
+ *
+ * \param instance_id the instance id to get the SDL_Joystick for
+ * \returns an SDL_Joystick on success or NULL on failure; call SDL_GetError()
+ *          for more information.
+ *
+ * \since This function is available since SDL 2.0.4.
  */
-extern DECLSPEC SDL_Joystick *SDLCALL SDL_JoystickFromInstanceID(SDL_JoystickID joyid);
+extern DECLSPEC SDL_Joystick *SDLCALL SDL_JoystickFromInstanceID(SDL_JoystickID instance_id);
 
 /**
- *  Return the name for this currently opened joystick.
- *  If no name can be found, this function returns NULL.
+ * Get the SDL_Joystick associated with a player index.
+ *
+ * \param player_index the player index to get the SDL_Joystick for
+ * \returns an SDL_Joystick on success or NULL on failure; call SDL_GetError()
+ *          for more information.
+ *
+ * \since This function is available since SDL 2.0.12.
  */
-extern DECLSPEC const char *SDLCALL SDL_JoystickName(SDL_Joystick * joystick);
+extern DECLSPEC SDL_Joystick *SDLCALL SDL_JoystickFromPlayerIndex(int player_index);
 
 /**
- *  Get the player index of an opened joystick, or -1 if it's not available
+ * Attach a new virtual joystick.
  *
- *  For XInput controllers this returns the XInput user index.
+ * \returns the joystick's device index, or -1 if an error occurred.
+ *
+ * \since This function is available since SDL 2.0.14.
  */
-extern DECLSPEC int SDLCALL SDL_JoystickGetPlayerIndex(SDL_Joystick * joystick);
+extern DECLSPEC int SDLCALL SDL_JoystickAttachVirtual(SDL_JoystickType type,
+                                                      int naxes,
+                                                      int nbuttons,
+                                                      int nhats);
 
 /**
- *  Return the GUID for this opened joystick
+ * The structure that defines an extended virtual joystick description
+ *
+ * The caller must zero the structure and then initialize the version with `SDL_VIRTUAL_JOYSTICK_DESC_VERSION` before passing it to SDL_JoystickAttachVirtualEx()
+ *  All other elements of this structure are optional and can be left 0.
+ *
+ * \sa SDL_JoystickAttachVirtualEx
+ */
+typedef struct SDL_VirtualJoystickDesc
+{
+    Uint16 version;     /**< `SDL_VIRTUAL_JOYSTICK_DESC_VERSION` */
+    Uint16 type;        /**< `SDL_JoystickType` */
+    Uint16 naxes;       /**< the number of axes on this joystick */
+    Uint16 nbuttons;    /**< the number of buttons on this joystick */
+    Uint16 nhats;       /**< the number of hats on this joystick */
+    Uint16 vendor_id;   /**< the USB vendor ID of this joystick */
+    Uint16 product_id;  /**< the USB product ID of this joystick */
+    Uint16 padding;     /**< unused */
+    Uint32 button_mask; /**< A mask of which buttons are valid for this controller
+                             e.g. (1 << SDL_CONTROLLER_BUTTON_A) */
+    Uint32 axis_mask;   /**< A mask of which axes are valid for this controller
+                             e.g. (1 << SDL_CONTROLLER_AXIS_LEFTX) */
+    const char *name;   /**< the name of the joystick */
+
+    void *userdata;     /**< User data pointer passed to callbacks */
+    void (SDLCALL *Update)(void *userdata); /**< Called when the joystick state should be updated */
+    void (SDLCALL *SetPlayerIndex)(void *userdata, int player_index); /**< Called when the player index is set */
+    int (SDLCALL *Rumble)(void *userdata, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble); /**< Implements SDL_JoystickRumble() */
+    int (SDLCALL *RumbleTriggers)(void *userdata, Uint16 left_rumble, Uint16 right_rumble); /**< Implements SDL_JoystickRumbleTriggers() */
+    int (SDLCALL *SetLED)(void *userdata, Uint8 red, Uint8 green, Uint8 blue); /**< Implements SDL_JoystickSetLED() */
+    int (SDLCALL *SendEffect)(void *userdata, const void *data, int size); /**< Implements SDL_JoystickSendEffect() */
+
+} SDL_VirtualJoystickDesc;
+
+/**
+ * \brief The current version of the SDL_VirtualJoystickDesc structure
+ */
+#define SDL_VIRTUAL_JOYSTICK_DESC_VERSION   1
+
+/**
+ * Attach a new virtual joystick with extended properties.
+ *
+ * \returns the joystick's device index, or -1 if an error occurred.
+ *
+ * \since This function is available since SDL 2.24.0.
+ */
+extern DECLSPEC int SDLCALL SDL_JoystickAttachVirtualEx(const SDL_VirtualJoystickDesc *desc);
+
+/**
+ * Detach a virtual joystick.
+ *
+ * \param device_index a value previously returned from
+ *                     SDL_JoystickAttachVirtual()
+ * \returns 0 on success, or -1 if an error occurred.
+ *
+ * \since This function is available since SDL 2.0.14.
+ */
+extern DECLSPEC int SDLCALL SDL_JoystickDetachVirtual(int device_index);
+
+/**
+ * Query whether or not the joystick at a given device index is virtual.
+ *
+ * \param device_index a joystick device index.
+ * \returns SDL_TRUE if the joystick is virtual, SDL_FALSE otherwise.
+ *
+ * \since This function is available since SDL 2.0.14.
+ */
+extern DECLSPEC SDL_bool SDLCALL SDL_JoystickIsVirtual(int device_index);
+
+/**
+ * Set values on an opened, virtual-joystick's axis.
+ *
+ * Please note that values set here will not be applied until the next call to
+ * SDL_JoystickUpdate, which can either be called directly, or can be called
+ * indirectly through various other SDL APIs, including, but not limited to
+ * the following: SDL_PollEvent, SDL_PumpEvents, SDL_WaitEventTimeout,
+ * SDL_WaitEvent.
+ *
+ * Note that when sending trigger axes, you should scale the value to the full
+ * range of Sint16. For example, a trigger at rest would have the value of
+ * `SDL_JOYSTICK_AXIS_MIN`.
+ *
+ * \param joystick the virtual joystick on which to set state.
+ * \param axis the specific axis on the virtual joystick to set.
+ * \param value the new value for the specified axis.
+ * \returns 0 on success, -1 on error.
+ *
+ * \since This function is available since SDL 2.0.14.
+ */
+extern DECLSPEC int SDLCALL SDL_JoystickSetVirtualAxis(SDL_Joystick *joystick, int axis, Sint16 value);
+
+/**
+ * Set values on an opened, virtual-joystick's button.
+ *
+ * Please note that values set here will not be applied until the next call to
+ * SDL_JoystickUpdate, which can either be called directly, or can be called
+ * indirectly through various other SDL APIs, including, but not limited to
+ * the following: SDL_PollEvent, SDL_PumpEvents, SDL_WaitEventTimeout,
+ * SDL_WaitEvent.
+ *
+ * \param joystick the virtual joystick on which to set state.
+ * \param button the specific button on the virtual joystick to set.
+ * \param value the new value for the specified button.
+ * \returns 0 on success, -1 on error.
+ *
+ * \since This function is available since SDL 2.0.14.
+ */
+extern DECLSPEC int SDLCALL SDL_JoystickSetVirtualButton(SDL_Joystick *joystick, int button, Uint8 value);
+
+/**
+ * Set values on an opened, virtual-joystick's hat.
+ *
+ * Please note that values set here will not be applied until the next call to
+ * SDL_JoystickUpdate, which can either be called directly, or can be called
+ * indirectly through various other SDL APIs, including, but not limited to
+ * the following: SDL_PollEvent, SDL_PumpEvents, SDL_WaitEventTimeout,
+ * SDL_WaitEvent.
+ *
+ * \param joystick the virtual joystick on which to set state.
+ * \param hat the specific hat on the virtual joystick to set.
+ * \param value the new value for the specified hat.
+ * \returns 0 on success, -1 on error.
+ *
+ * \since This function is available since SDL 2.0.14.
+ */
+extern DECLSPEC int SDLCALL SDL_JoystickSetVirtualHat(SDL_Joystick *joystick, int hat, Uint8 value);
+
+/**
+ * Get the implementation dependent name of a joystick.
+ *
+ * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen()
+ * \returns the name of the selected joystick. If no name can be found, this
+ *          function returns NULL; call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_JoystickNameForIndex
+ * \sa SDL_JoystickOpen
  */
-extern DECLSPEC SDL_JoystickGUID SDLCALL SDL_JoystickGetGUID(SDL_Joystick * joystick);
+extern DECLSPEC const char *SDLCALL SDL_JoystickName(SDL_Joystick *joystick);
 
 /**
- *  Get the USB vendor ID of an opened joystick, if available.
- *  If the vendor ID isn't available this function returns 0.
+ * Get the implementation dependent path of a joystick.
+ *
+ * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen()
+ * \returns the path of the selected joystick. If no path can be found, this
+ *          function returns NULL; call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.24.0.
+ *
+ * \sa SDL_JoystickPathForIndex
  */
-extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetVendor(SDL_Joystick * joystick);
+extern DECLSPEC const char *SDLCALL SDL_JoystickPath(SDL_Joystick *joystick);
 
 /**
- *  Get the USB product ID of an opened joystick, if available.
- *  If the product ID isn't available this function returns 0.
+ * Get the player index of an opened joystick.
+ *
+ * For XInput controllers this returns the XInput user index. Many joysticks
+ * will not be able to supply this information.
+ *
+ * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen()
+ * \returns the player index, or -1 if it's not available.
+ *
+ * \since This function is available since SDL 2.0.9.
  */
-extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetProduct(SDL_Joystick * joystick);
+extern DECLSPEC int SDLCALL SDL_JoystickGetPlayerIndex(SDL_Joystick *joystick);
 
 /**
- *  Get the product version of an opened joystick, if available.
- *  If the product version isn't available this function returns 0.
+ * Set the player index of an opened joystick.
+ *
+ * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen()
+ * \param player_index Player index to assign to this joystick, or -1 to clear
+ *                     the player index and turn off player LEDs.
+ *
+ * \since This function is available since SDL 2.0.12.
  */
-extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetProductVersion(SDL_Joystick * joystick);
+extern DECLSPEC void SDLCALL SDL_JoystickSetPlayerIndex(SDL_Joystick *joystick, int player_index);
 
 /**
- *  Get the type of an opened joystick.
+ * Get the implementation-dependent GUID for the joystick.
+ *
+ * This function requires an open joystick.
+ *
+ * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen()
+ * \returns the GUID of the given joystick. If called on an invalid index,
+ *          this function returns a zero GUID; call SDL_GetError() for more
+ *          information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_JoystickGetDeviceGUID
+ * \sa SDL_JoystickGetGUIDString
  */
-extern DECLSPEC SDL_JoystickType SDLCALL SDL_JoystickGetType(SDL_Joystick * joystick);
+extern DECLSPEC SDL_JoystickGUID SDLCALL SDL_JoystickGetGUID(SDL_Joystick *joystick);
 
 /**
- *  Return a string representation for this guid. pszGUID must point to at least 33 bytes
- *  (32 for the string plus a NULL terminator).
+ * Get the USB vendor ID of an opened joystick, if available.
+ *
+ * If the vendor ID isn't available this function returns 0.
+ *
+ * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen()
+ * \returns the USB vendor ID of the selected joystick, or 0 if unavailable.
+ *
+ * \since This function is available since SDL 2.0.6.
+ */
+extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetVendor(SDL_Joystick *joystick);
+
+/**
+ * Get the USB product ID of an opened joystick, if available.
+ *
+ * If the product ID isn't available this function returns 0.
+ *
+ * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen()
+ * \returns the USB product ID of the selected joystick, or 0 if unavailable.
+ *
+ * \since This function is available since SDL 2.0.6.
+ */
+extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetProduct(SDL_Joystick *joystick);
+
+/**
+ * Get the product version of an opened joystick, if available.
+ *
+ * If the product version isn't available this function returns 0.
+ *
+ * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen()
+ * \returns the product version of the selected joystick, or 0 if unavailable.
+ *
+ * \since This function is available since SDL 2.0.6.
+ */
+extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetProductVersion(SDL_Joystick *joystick);
+
+/**
+ * Get the firmware version of an opened joystick, if available.
+ *
+ * If the firmware version isn't available this function returns 0.
+ *
+ * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen()
+ * \returns the firmware version of the selected joystick, or 0 if
+ *          unavailable.
+ *
+ * \since This function is available since SDL 2.24.0.
+ */
+extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetFirmwareVersion(SDL_Joystick *joystick);
+
+/**
+ * Get the serial number of an opened joystick, if available.
+ *
+ * Returns the serial number of the joystick, or NULL if it is not available.
+ *
+ * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen()
+ * \returns the serial number of the selected joystick, or NULL if
+ *          unavailable.
+ *
+ * \since This function is available since SDL 2.0.14.
+ */
+extern DECLSPEC const char * SDLCALL SDL_JoystickGetSerial(SDL_Joystick *joystick);
+
+/**
+ * Get the type of an opened joystick.
+ *
+ * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen()
+ * \returns the SDL_JoystickType of the selected joystick.
+ *
+ * \since This function is available since SDL 2.0.6.
+ */
+extern DECLSPEC SDL_JoystickType SDLCALL SDL_JoystickGetType(SDL_Joystick *joystick);
+
+/**
+ * Get an ASCII string representation for a given SDL_JoystickGUID.
+ *
+ * You should supply at least 33 bytes for pszGUID.
+ *
+ * \param guid the SDL_JoystickGUID you wish to convert to string
+ * \param pszGUID buffer in which to write the ASCII string
+ * \param cbGUID the size of pszGUID
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_JoystickGetDeviceGUID
+ * \sa SDL_JoystickGetGUID
+ * \sa SDL_JoystickGetGUIDFromString
  */
 extern DECLSPEC void SDLCALL SDL_JoystickGetGUIDString(SDL_JoystickGUID guid, char *pszGUID, int cbGUID);
 
 /**
- *  Convert a string into a joystick guid
+ * Convert a GUID string into a SDL_JoystickGUID structure.
+ *
+ * Performs no error checking. If this function is given a string containing
+ * an invalid GUID, the function will silently succeed, but the GUID generated
+ * will not be useful.
+ *
+ * \param pchGUID string containing an ASCII representation of a GUID
+ * \returns a SDL_JoystickGUID structure.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_JoystickGetGUIDString
  */
 extern DECLSPEC SDL_JoystickGUID SDLCALL SDL_JoystickGetGUIDFromString(const char *pchGUID);
 
 /**
- *  Returns SDL_TRUE if the joystick has been opened and currently connected, or SDL_FALSE if it has not.
+ * Get the device information encoded in a SDL_JoystickGUID structure
+ *
+ * \param guid the SDL_JoystickGUID you wish to get info about
+ * \param vendor A pointer filled in with the device VID, or 0 if not
+ *               available
+ * \param product A pointer filled in with the device PID, or 0 if not
+ *                available
+ * \param version A pointer filled in with the device version, or 0 if not
+ *                available
+ * \param crc16 A pointer filled in with a CRC used to distinguish different
+ *              products with the same VID/PID, or 0 if not available
+ *
+ * \since This function is available since SDL 2.26.0.
+ *
+ * \sa SDL_JoystickGetDeviceGUID
+ */
+extern DECLSPEC void SDLCALL SDL_GetJoystickGUIDInfo(SDL_JoystickGUID guid, Uint16 *vendor, Uint16 *product, Uint16 *version, Uint16 *crc16);
+
+/**
+ * Get the status of a specified joystick.
+ *
+ * \param joystick the joystick to query
+ * \returns SDL_TRUE if the joystick has been opened, SDL_FALSE if it has not;
+ *          call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_JoystickClose
+ * \sa SDL_JoystickOpen
  */
-extern DECLSPEC SDL_bool SDLCALL SDL_JoystickGetAttached(SDL_Joystick * joystick);
+extern DECLSPEC SDL_bool SDLCALL SDL_JoystickGetAttached(SDL_Joystick *joystick);
 
 /**
- *  Get the instance ID of an opened joystick or -1 if the joystick is invalid.
+ * Get the instance ID of an opened joystick.
+ *
+ * \param joystick an SDL_Joystick structure containing joystick information
+ * \returns the instance ID of the specified joystick on success or a negative
+ *          error code on failure; call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_JoystickOpen
  */
-extern DECLSPEC SDL_JoystickID SDLCALL SDL_JoystickInstanceID(SDL_Joystick * joystick);
+extern DECLSPEC SDL_JoystickID SDLCALL SDL_JoystickInstanceID(SDL_Joystick *joystick);
 
 /**
- *  Get the number of general axis controls on a joystick.
+ * Get the number of general axis controls on a joystick.
+ *
+ * Often, the directional pad on a game controller will either look like 4
+ * separate buttons or a POV hat, and not axes, but all of this is up to the
+ * device and platform.
+ *
+ * \param joystick an SDL_Joystick structure containing joystick information
+ * \returns the number of axis controls/number of axes on success or a
+ *          negative error code on failure; call SDL_GetError() for more
+ *          information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_JoystickGetAxis
+ * \sa SDL_JoystickOpen
  */
-extern DECLSPEC int SDLCALL SDL_JoystickNumAxes(SDL_Joystick * joystick);
+extern DECLSPEC int SDLCALL SDL_JoystickNumAxes(SDL_Joystick *joystick);
 
 /**
- *  Get the number of trackballs on a joystick.
+ * Get the number of trackballs on a joystick.
+ *
+ * Joystick trackballs have only relative motion events associated with them
+ * and their state cannot be polled.
+ *
+ * Most joysticks do not have trackballs.
  *
- *  Joystick trackballs have only relative motion events associated
- *  with them and their state cannot be polled.
+ * \param joystick an SDL_Joystick structure containing joystick information
+ * \returns the number of trackballs on success or a negative error code on
+ *          failure; call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_JoystickGetBall
  */
-extern DECLSPEC int SDLCALL SDL_JoystickNumBalls(SDL_Joystick * joystick);
+extern DECLSPEC int SDLCALL SDL_JoystickNumBalls(SDL_Joystick *joystick);
 
 /**
- *  Get the number of POV hats on a joystick.
+ * Get the number of POV hats on a joystick.
+ *
+ * \param joystick an SDL_Joystick structure containing joystick information
+ * \returns the number of POV hats on success or a negative error code on
+ *          failure; call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_JoystickGetHat
+ * \sa SDL_JoystickOpen
  */
-extern DECLSPEC int SDLCALL SDL_JoystickNumHats(SDL_Joystick * joystick);
+extern DECLSPEC int SDLCALL SDL_JoystickNumHats(SDL_Joystick *joystick);
 
 /**
- *  Get the number of buttons on a joystick.
+ * Get the number of buttons on a joystick.
+ *
+ * \param joystick an SDL_Joystick structure containing joystick information
+ * \returns the number of buttons on success or a negative error code on
+ *          failure; call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_JoystickGetButton
+ * \sa SDL_JoystickOpen
  */
-extern DECLSPEC int SDLCALL SDL_JoystickNumButtons(SDL_Joystick * joystick);
+extern DECLSPEC int SDLCALL SDL_JoystickNumButtons(SDL_Joystick *joystick);
 
 /**
- *  Update the current state of the open joysticks.
+ * Update the current state of the open joysticks.
  *
- *  This is called automatically by the event loop if any joystick
- *  events are enabled.
+ * This is called automatically by the event loop if any joystick events are
+ * enabled.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_JoystickEventState
  */
 extern DECLSPEC void SDLCALL SDL_JoystickUpdate(void);
 
 /**
- *  Enable/disable joystick event polling.
+ * Enable/disable joystick event polling.
+ *
+ * If joystick events are disabled, you must call SDL_JoystickUpdate()
+ * yourself and manually check the state of the joystick when you want
+ * joystick information.
+ *
+ * It is recommended that you leave joystick event handling enabled.
  *
- *  If joystick events are disabled, you must call SDL_JoystickUpdate()
- *  yourself and check the state of the joystick when you want joystick
- *  information.
+ * **WARNING**: Calling this function may delete all events currently in SDL's
+ * event queue.
  *
- *  The state can be one of ::SDL_QUERY, ::SDL_ENABLE or ::SDL_IGNORE.
+ * \param state can be one of `SDL_QUERY`, `SDL_IGNORE`, or `SDL_ENABLE`
+ * \returns 1 if enabled, 0 if disabled, or a negative error code on failure;
+ *          call SDL_GetError() for more information.
+ *
+ *          If `state` is `SDL_QUERY` then the current state is returned,
+ *          otherwise the new processing state is returned.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GameControllerEventState
  */
 extern DECLSPEC int SDLCALL SDL_JoystickEventState(int state);
 
 #define SDL_JOYSTICK_AXIS_MAX   32767
 #define SDL_JOYSTICK_AXIS_MIN   -32768
+
 /**
- *  Get the current state of an axis control on a joystick.
+ * Get the current state of an axis control on a joystick.
  *
- *  The state is a value ranging from -32768 to 32767.
+ * SDL makes no promises about what part of the joystick any given axis refers
+ * to. Your game should have some sort of configuration UI to let users
+ * specify what each axis should be bound to. Alternately, SDL's higher-level
+ * Game Controller API makes a great effort to apply order to this lower-level
+ * interface, so you know that a specific axis is the "left thumb stick," etc.
  *
- *  The axis indices start at index 0.
+ * The value returned by SDL_JoystickGetAxis() is a signed integer (-32768 to
+ * 32767) representing the current position of the axis. It may be necessary
+ * to impose certain tolerances on these values to account for jitter.
+ *
+ * \param joystick an SDL_Joystick structure containing joystick information
+ * \param axis the axis to query; the axis indices start at index 0
+ * \returns a 16-bit signed integer representing the current position of the
+ *          axis or 0 on failure; call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_JoystickNumAxes
  */
-extern DECLSPEC Sint16 SDLCALL SDL_JoystickGetAxis(SDL_Joystick * joystick,
+extern DECLSPEC Sint16 SDLCALL SDL_JoystickGetAxis(SDL_Joystick *joystick,
                                                    int axis);
 
 /**
- *  Get the initial state of an axis control on a joystick.
+ * Get the initial state of an axis control on a joystick.
+ *
+ * The state is a value ranging from -32768 to 32767.
  *
- *  The state is a value ranging from -32768 to 32767.
+ * The axis indices start at index 0.
  *
- *  The axis indices start at index 0.
+ * \param joystick an SDL_Joystick structure containing joystick information
+ * \param axis the axis to query; the axis indices start at index 0
+ * \param state Upon return, the initial value is supplied here.
+ * \return SDL_TRUE if this axis has any initial value, or SDL_FALSE if not.
  *
- *  \return SDL_TRUE if this axis has any initial value, or SDL_FALSE if not.
+ * \since This function is available since SDL 2.0.6.
  */
-extern DECLSPEC SDL_bool SDLCALL SDL_JoystickGetAxisInitialState(SDL_Joystick * joystick,
+extern DECLSPEC SDL_bool SDLCALL SDL_JoystickGetAxisInitialState(SDL_Joystick *joystick,
                                                    int axis, Sint16 *state);
 
 /**
@@ -338,64 +864,199 @@ extern DECLSPEC SDL_bool SDLCALL SDL_JoystickGetAxisInitialState(SDL_Joystick *
 /* @} */
 
 /**
- *  Get the current state of a POV hat on a joystick.
+ * Get the current state of a POV hat on a joystick.
  *
- *  The hat indices start at index 0.
+ * The returned value will be one of the following positions:
  *
- *  \return The return value is one of the following positions:
- *           - ::SDL_HAT_CENTERED
- *           - ::SDL_HAT_UP
- *           - ::SDL_HAT_RIGHT
- *           - ::SDL_HAT_DOWN
- *           - ::SDL_HAT_LEFT
- *           - ::SDL_HAT_RIGHTUP
- *           - ::SDL_HAT_RIGHTDOWN
- *           - ::SDL_HAT_LEFTUP
- *           - ::SDL_HAT_LEFTDOWN
+ * - `SDL_HAT_CENTERED`
+ * - `SDL_HAT_UP`
+ * - `SDL_HAT_RIGHT`
+ * - `SDL_HAT_DOWN`
+ * - `SDL_HAT_LEFT`
+ * - `SDL_HAT_RIGHTUP`
+ * - `SDL_HAT_RIGHTDOWN`
+ * - `SDL_HAT_LEFTUP`
+ * - `SDL_HAT_LEFTDOWN`
+ *
+ * \param joystick an SDL_Joystick structure containing joystick information
+ * \param hat the hat index to get the state from; indices start at index 0
+ * \returns the current hat position.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_JoystickNumHats
  */
-extern DECLSPEC Uint8 SDLCALL SDL_JoystickGetHat(SDL_Joystick * joystick,
+extern DECLSPEC Uint8 SDLCALL SDL_JoystickGetHat(SDL_Joystick *joystick,
                                                  int hat);
 
 /**
- *  Get the ball axis change since the last poll.
+ * Get the ball axis change since the last poll.
+ *
+ * Trackballs can only return relative motion since the last call to
+ * SDL_JoystickGetBall(), these motion deltas are placed into `dx` and `dy`.
  *
- *  \return 0, or -1 if you passed it invalid parameters.
+ * Most joysticks do not have trackballs.
  *
- *  The ball indices start at index 0.
+ * \param joystick the SDL_Joystick to query
+ * \param ball the ball index to query; ball indices start at index 0
+ * \param dx stores the difference in the x axis position since the last poll
+ * \param dy stores the difference in the y axis position since the last poll
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_JoystickNumBalls
  */
-extern DECLSPEC int SDLCALL SDL_JoystickGetBall(SDL_Joystick * joystick,
+extern DECLSPEC int SDLCALL SDL_JoystickGetBall(SDL_Joystick *joystick,
                                                 int ball, int *dx, int *dy);
 
 /**
- *  Get the current state of a button on a joystick.
+ * Get the current state of a button on a joystick.
+ *
+ * \param joystick an SDL_Joystick structure containing joystick information
+ * \param button the button index to get the state from; indices start at
+ *               index 0
+ * \returns 1 if the specified button is pressed, 0 otherwise.
+ *
+ * \since This function is available since SDL 2.0.0.
  *
- *  The button indices start at index 0.
+ * \sa SDL_JoystickNumButtons
  */
-extern DECLSPEC Uint8 SDLCALL SDL_JoystickGetButton(SDL_Joystick * joystick,
+extern DECLSPEC Uint8 SDLCALL SDL_JoystickGetButton(SDL_Joystick *joystick,
                                                     int button);
 
 /**
- *  Trigger a rumble effect
- *  Each call to this function cancels any previous rumble effect, and calling it with 0 intensity stops any rumbling.
+ * Start a rumble effect.
+ *
+ * Each call to this function cancels any previous rumble effect, and calling
+ * it with 0 intensity stops any rumbling.
+ *
+ * \param joystick The joystick to vibrate
+ * \param low_frequency_rumble The intensity of the low frequency (left)
+ *                             rumble motor, from 0 to 0xFFFF
+ * \param high_frequency_rumble The intensity of the high frequency (right)
+ *                              rumble motor, from 0 to 0xFFFF
+ * \param duration_ms The duration of the rumble effect, in milliseconds
+ * \returns 0, or -1 if rumble isn't supported on this joystick
+ *
+ * \since This function is available since SDL 2.0.9.
+ *
+ * \sa SDL_JoystickHasRumble
+ */
+extern DECLSPEC int SDLCALL SDL_JoystickRumble(SDL_Joystick *joystick, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms);
+
+/**
+ * Start a rumble effect in the joystick's triggers
+ *
+ * Each call to this function cancels any previous trigger rumble effect, and
+ * calling it with 0 intensity stops any rumbling.
+ *
+ * Note that this is rumbling of the _triggers_ and not the game controller as
+ * a whole. This is currently only supported on Xbox One controllers. If you
+ * want the (more common) whole-controller rumble, use SDL_JoystickRumble()
+ * instead.
+ *
+ * \param joystick The joystick to vibrate
+ * \param left_rumble The intensity of the left trigger rumble motor, from 0
+ *                    to 0xFFFF
+ * \param right_rumble The intensity of the right trigger rumble motor, from 0
+ *                     to 0xFFFF
+ * \param duration_ms The duration of the rumble effect, in milliseconds
+ * \returns 0, or -1 if trigger rumble isn't supported on this joystick
+ *
+ * \since This function is available since SDL 2.0.14.
+ *
+ * \sa SDL_JoystickHasRumbleTriggers
+ */
+extern DECLSPEC int SDLCALL SDL_JoystickRumbleTriggers(SDL_Joystick *joystick, Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms);
+
+/**
+ * Query whether a joystick has an LED.
+ *
+ * An example of a joystick LED is the light on the back of a PlayStation 4's
+ * DualShock 4 controller.
+ *
+ * \param joystick The joystick to query
+ * \return SDL_TRUE if the joystick has a modifiable LED, SDL_FALSE otherwise.
+ *
+ * \since This function is available since SDL 2.0.14.
+ */
+extern DECLSPEC SDL_bool SDLCALL SDL_JoystickHasLED(SDL_Joystick *joystick);
+
+/**
+ * Query whether a joystick has rumble support.
+ *
+ * \param joystick The joystick to query
+ * \return SDL_TRUE if the joystick has rumble, SDL_FALSE otherwise.
+ *
+ * \since This function is available since SDL 2.0.18.
+ *
+ * \sa SDL_JoystickRumble
+ */
+extern DECLSPEC SDL_bool SDLCALL SDL_JoystickHasRumble(SDL_Joystick *joystick);
+
+/**
+ * Query whether a joystick has rumble support on triggers.
+ *
+ * \param joystick The joystick to query
+ * \return SDL_TRUE if the joystick has trigger rumble, SDL_FALSE otherwise.
+ *
+ * \since This function is available since SDL 2.0.18.
+ *
+ * \sa SDL_JoystickRumbleTriggers
+ */
+extern DECLSPEC SDL_bool SDLCALL SDL_JoystickHasRumbleTriggers(SDL_Joystick *joystick);
+
+/**
+ * Update a joystick's LED color.
+ *
+ * An example of a joystick LED is the light on the back of a PlayStation 4's
+ * DualShock 4 controller.
+ *
+ * \param joystick The joystick to update
+ * \param red The intensity of the red LED
+ * \param green The intensity of the green LED
+ * \param blue The intensity of the blue LED
+ * \returns 0 on success, -1 if this joystick does not have a modifiable LED
+ *
+ * \since This function is available since SDL 2.0.14.
+ */
+extern DECLSPEC int SDLCALL SDL_JoystickSetLED(SDL_Joystick *joystick, Uint8 red, Uint8 green, Uint8 blue);
+
+/**
+ * Send a joystick specific effect packet
  *
- *  \param joystick The joystick to vibrate
- *  \param low_frequency_rumble The intensity of the low frequency (left) rumble motor, from 0 to 0xFFFF
- *  \param high_frequency_rumble The intensity of the high frequency (right) rumble motor, from 0 to 0xFFFF
- *  \param duration_ms The duration of the rumble effect, in milliseconds
+ * \param joystick The joystick to affect
+ * \param data The data to send to the joystick
+ * \param size The size of the data to send to the joystick
+ * \returns 0, or -1 if this joystick or driver doesn't support effect packets
  *
- *  \return 0, or -1 if rumble isn't supported on this joystick
+ * \since This function is available since SDL 2.0.16.
  */
-extern DECLSPEC int SDLCALL SDL_JoystickRumble(SDL_Joystick * joystick, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms);
+extern DECLSPEC int SDLCALL SDL_JoystickSendEffect(SDL_Joystick *joystick, const void *data, int size);
 
 /**
- *  Close a joystick previously opened with SDL_JoystickOpen().
+ * Close a joystick previously opened with SDL_JoystickOpen().
+ *
+ * \param joystick The joystick device to close
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_JoystickOpen
  */
-extern DECLSPEC void SDLCALL SDL_JoystickClose(SDL_Joystick * joystick);
+extern DECLSPEC void SDLCALL SDL_JoystickClose(SDL_Joystick *joystick);
 
 /**
- *  Return the battery level of this joystick
+ * Get the battery level of a joystick as SDL_JoystickPowerLevel.
+ *
+ * \param joystick the SDL_Joystick to query
+ * \returns the current battery level as SDL_JoystickPowerLevel on success or
+ *          `SDL_JOYSTICK_POWER_UNKNOWN` if it is unknown
+ *
+ * \since This function is available since SDL 2.0.4.
  */
-extern DECLSPEC SDL_JoystickPowerLevel SDLCALL SDL_JoystickCurrentPowerLevel(SDL_Joystick * joystick);
+extern DECLSPEC SDL_JoystickPowerLevel SDLCALL SDL_JoystickCurrentPowerLevel(SDL_Joystick *joystick);
 
 /* Ends C function definitions when using C++ */
 #ifdef __cplusplus

libs/SDL2/i686-w64-mingw32/include/SDL2/SDL_keyboard.h

 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -55,154 +55,290 @@ typedef struct SDL_Keysym
 /* Function prototypes */
 
 /**
- *  \brief Get the window which currently has keyboard focus.
+ * Query the window which currently has keyboard focus.
+ *
+ * \returns the window with keyboard focus.
+ *
+ * \since This function is available since SDL 2.0.0.
  */
 extern DECLSPEC SDL_Window * SDLCALL SDL_GetKeyboardFocus(void);
 
 /**
- *  \brief Get a snapshot of the current state of the keyboard.
+ * Get a snapshot of the current state of the keyboard.
+ *
+ * The pointer returned is a pointer to an internal SDL array. It will be
+ * valid for the whole lifetime of the application and should not be freed by
+ * the caller.
+ *
+ * A array element with a value of 1 means that the key is pressed and a value
+ * of 0 means that it is not. Indexes into this array are obtained by using
+ * SDL_Scancode values.
+ *
+ * Use SDL_PumpEvents() to update the state array.
+ *
+ * This function gives you the current state after all events have been
+ * processed, so if a key or button has been pressed and released before you
+ * process events, then the pressed state will never show up in the
+ * SDL_GetKeyboardState() calls.
+ *
+ * Note: This function doesn't take into account whether shift has been
+ * pressed or not.
  *
- *  \param numkeys if non-NULL, receives the length of the returned array.
+ * \param numkeys if non-NULL, receives the length of the returned array
+ * \returns a pointer to an array of key states.
  *
- *  \return An array of key states. Indexes into this array are obtained by using ::SDL_Scancode values.
+ * \since This function is available since SDL 2.0.0.
  *
- *  \b Example:
- *  \code
- *  const Uint8 *state = SDL_GetKeyboardState(NULL);
- *  if ( state[SDL_SCANCODE_RETURN] )   {
- *      printf("<RETURN> is pressed.\n");
- *  }
- *  \endcode
+ * \sa SDL_PumpEvents
+ * \sa SDL_ResetKeyboard
  */
 extern DECLSPEC const Uint8 *SDLCALL SDL_GetKeyboardState(int *numkeys);
 
 /**
- *  \brief Get the current key modifier state for the keyboard.
+ * Clear the state of the keyboard
+ *
+ * This function will generate key up events for all pressed keys.
+ *
+ * \since This function is available since SDL 2.24.0.
+ *
+ * \sa SDL_GetKeyboardState
+ */
+extern DECLSPEC void SDLCALL SDL_ResetKeyboard(void);
+
+/**
+ * Get the current key modifier state for the keyboard.
+ *
+ * \returns an OR'd combination of the modifier keys for the keyboard. See
+ *          SDL_Keymod for details.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetKeyboardState
+ * \sa SDL_SetModState
  */
 extern DECLSPEC SDL_Keymod SDLCALL SDL_GetModState(void);
 
 /**
- *  \brief Set the current key modifier state for the keyboard.
+ * Set the current key modifier state for the keyboard.
+ *
+ * The inverse of SDL_GetModState(), SDL_SetModState() allows you to impose
+ * modifier key states on your application. Simply pass your desired modifier
+ * states into `modstate`. This value may be a bitwise, OR'd combination of
+ * SDL_Keymod values.
+ *
+ * This does not change the keyboard state, only the key modifier flags that
+ * SDL reports.
+ *
+ * \param modstate the desired SDL_Keymod for the keyboard
  *
- *  \note This does not change the keyboard state, only the key modifier flags.
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetModState
  */
 extern DECLSPEC void SDLCALL SDL_SetModState(SDL_Keymod modstate);
 
 /**
- *  \brief Get the key code corresponding to the given scancode according
- *         to the current keyboard layout.
+ * Get the key code corresponding to the given scancode according to the
+ * current keyboard layout.
+ *
+ * See SDL_Keycode for details.
+ *
+ * \param scancode the desired SDL_Scancode to query
+ * \returns the SDL_Keycode that corresponds to the given SDL_Scancode.
  *
- *  See ::SDL_Keycode for details.
+ * \since This function is available since SDL 2.0.0.
  *
- *  \sa SDL_GetKeyName()
+ * \sa SDL_GetKeyName
+ * \sa SDL_GetScancodeFromKey
  */
 extern DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromScancode(SDL_Scancode scancode);
 
 /**
- *  \brief Get the scancode corresponding to the given key code according to the
- *         current keyboard layout.
+ * Get the scancode corresponding to the given key code according to the
+ * current keyboard layout.
  *
- *  See ::SDL_Scancode for details.
+ * See SDL_Scancode for details.
  *
- *  \sa SDL_GetScancodeName()
+ * \param key the desired SDL_Keycode to query
+ * \returns the SDL_Scancode that corresponds to the given SDL_Keycode.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetKeyFromScancode
+ * \sa SDL_GetScancodeName
  */
 extern DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromKey(SDL_Keycode key);
 
 /**
- *  \brief Get a human-readable name for a scancode.
+ * Get a human-readable name for a scancode.
+ *
+ * See SDL_Scancode for details.
  *
- *  \return A pointer to the name for the scancode.
- *          If the scancode doesn't have a name, this function returns
- *          an empty string ("").
+ * **Warning**: The returned name is by design not stable across platforms,
+ * e.g. the name for `SDL_SCANCODE_LGUI` is "Left GUI" under Linux but "Left
+ * Windows" under Microsoft Windows, and some scancodes like
+ * `SDL_SCANCODE_NONUSBACKSLASH` don't have any name at all. There are even
+ * scancodes that share names, e.g. `SDL_SCANCODE_RETURN` and
+ * `SDL_SCANCODE_RETURN2` (both called "Return"). This function is therefore
+ * unsuitable for creating a stable cross-platform two-way mapping between
+ * strings and scancodes.
  *
- *  \sa SDL_Scancode
+ * \param scancode the desired SDL_Scancode to query
+ * \returns a pointer to the name for the scancode. If the scancode doesn't
+ *          have a name this function returns an empty string ("").
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetScancodeFromKey
+ * \sa SDL_GetScancodeFromName
  */
 extern DECLSPEC const char *SDLCALL SDL_GetScancodeName(SDL_Scancode scancode);
 
 /**
- *  \brief Get a scancode from a human-readable name
+ * Get a scancode from a human-readable name.
  *
- *  \return scancode, or SDL_SCANCODE_UNKNOWN if the name wasn't recognized
+ * \param name the human-readable scancode name
+ * \returns the SDL_Scancode, or `SDL_SCANCODE_UNKNOWN` if the name wasn't
+ *          recognized; call SDL_GetError() for more information.
  *
- *  \sa SDL_Scancode
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetKeyFromName
+ * \sa SDL_GetScancodeFromKey
+ * \sa SDL_GetScancodeName
  */
 extern DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromName(const char *name);
 
 /**
- *  \brief Get a human-readable name for a key.
+ * Get a human-readable name for a key.
+ *
+ * See SDL_Scancode and SDL_Keycode for details.
  *
- *  \return A pointer to a UTF-8 string that stays valid at least until the next
- *          call to this function. If you need it around any longer, you must
- *          copy it.  If the key doesn't have a name, this function returns an
- *          empty string ("").
+ * \param key the desired SDL_Keycode to query
+ * \returns a pointer to a UTF-8 string that stays valid at least until the
+ *          next call to this function. If you need it around any longer, you
+ *          must copy it. If the key doesn't have a name, this function
+ *          returns an empty string ("").
  *
- *  \sa SDL_Keycode
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetKeyFromName
+ * \sa SDL_GetKeyFromScancode
+ * \sa SDL_GetScancodeFromKey
  */
 extern DECLSPEC const char *SDLCALL SDL_GetKeyName(SDL_Keycode key);
 
 /**
- *  \brief Get a key code from a human-readable name
+ * Get a key code from a human-readable name.
+ *
+ * \param name the human-readable key name
+ * \returns key code, or `SDLK_UNKNOWN` if the name wasn't recognized; call
+ *          SDL_GetError() for more information.
  *
- *  \return key code, or SDLK_UNKNOWN if the name wasn't recognized
+ * \since This function is available since SDL 2.0.0.
  *
- *  \sa SDL_Keycode
+ * \sa SDL_GetKeyFromScancode
+ * \sa SDL_GetKeyName
+ * \sa SDL_GetScancodeFromName
  */
 extern DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromName(const char *name);
 
 /**
- *  \brief Start accepting Unicode text input events.
- *         This function will show the on-screen keyboard if supported.
+ * Start accepting Unicode text input events.
+ *
+ * This function will start accepting Unicode text input events in the focused
+ * SDL window, and start emitting SDL_TextInputEvent (SDL_TEXTINPUT) and
+ * SDL_TextEditingEvent (SDL_TEXTEDITING) events. Please use this function in
+ * pair with SDL_StopTextInput().
  *
- *  \sa SDL_StopTextInput()
- *  \sa SDL_SetTextInputRect()
- *  \sa SDL_HasScreenKeyboardSupport()
+ * On some platforms using this function activates the screen keyboard.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_SetTextInputRect
+ * \sa SDL_StopTextInput
  */
 extern DECLSPEC void SDLCALL SDL_StartTextInput(void);
 
 /**
- *  \brief Return whether or not Unicode text input events are enabled.
+ * Check whether or not Unicode text input events are enabled.
+ *
+ * \returns SDL_TRUE if text input events are enabled else SDL_FALSE.
  *
- *  \sa SDL_StartTextInput()
- *  \sa SDL_StopTextInput()
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_StartTextInput
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_IsTextInputActive(void);
 
 /**
- *  \brief Stop receiving any text input events.
- *         This function will hide the on-screen keyboard if supported.
+ * Stop receiving any text input events.
+ *
+ * \since This function is available since SDL 2.0.0.
  *
- *  \sa SDL_StartTextInput()
- *  \sa SDL_HasScreenKeyboardSupport()
+ * \sa SDL_StartTextInput
  */
 extern DECLSPEC void SDLCALL SDL_StopTextInput(void);
 
 /**
- *  \brief Set the rectangle used to type Unicode text inputs.
- *         This is used as a hint for IME and on-screen keyboard placement.
+ * Dismiss the composition window/IME without disabling the subsystem.
+ *
+ * \since This function is available since SDL 2.0.22.
+ *
+ * \sa SDL_StartTextInput
+ * \sa SDL_StopTextInput
+ */
+extern DECLSPEC void SDLCALL SDL_ClearComposition(void);
+
+/**
+ * Returns if an IME Composite or Candidate window is currently shown.
+ *
+ * \since This function is available since SDL 2.0.22.
+ */
+extern DECLSPEC SDL_bool SDLCALL SDL_IsTextInputShown(void);
+
+/**
+ * Set the rectangle used to type Unicode text inputs.
+ *
+ * To start text input in a given location, this function is intended to be
+ * called before SDL_StartTextInput, although some platforms support moving
+ * the rectangle even while text input (and a composition) is active.
+ *
+ * Note: If you want to use the system native IME window, try setting hint
+ * **SDL_HINT_IME_SHOW_UI** to **1**, otherwise this function won't give you
+ * any feedback.
+ *
+ * \param rect the SDL_Rect structure representing the rectangle to receive
+ *             text (ignored if NULL)
+ *
+ * \since This function is available since SDL 2.0.0.
  *
- *  \sa SDL_StartTextInput()
+ * \sa SDL_StartTextInput
  */
-extern DECLSPEC void SDLCALL SDL_SetTextInputRect(SDL_Rect *rect);
+extern DECLSPEC void SDLCALL SDL_SetTextInputRect(const SDL_Rect *rect);
 
 /**
- *  \brief Returns whether the platform has some screen keyboard support.
+ * Check whether the platform has screen keyboard support.
  *
- *  \return SDL_TRUE if some keyboard support is available else SDL_FALSE.
+ * \returns SDL_TRUE if the platform has some screen keyboard support or
+ *          SDL_FALSE if not.
  *
- *  \note Not all screen keyboard functions are supported on all platforms.
+ * \since This function is available since SDL 2.0.0.
  *
- *  \sa SDL_IsScreenKeyboardShown()
+ * \sa SDL_StartTextInput
+ * \sa SDL_IsScreenKeyboardShown
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_HasScreenKeyboardSupport(void);
 
 /**
- *  \brief Returns whether the screen keyboard is shown for given window.
+ * Check whether the screen keyboard is shown for given window.
  *
- *  \param window The window for which screen keyboard should be queried.
+ * \param window the window for which screen keyboard should be queried
+ * \returns SDL_TRUE if screen keyboard is shown or SDL_FALSE if not.
  *
- *  \return SDL_TRUE if screen keyboard is shown else SDL_FALSE.
+ * \since This function is available since SDL 2.0.0.
  *
- *  \sa SDL_HasScreenKeyboardSupport()
+ * \sa SDL_HasScreenKeyboardSupport
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_IsScreenKeyboardShown(SDL_Window *window);
 

libs/SDL2/i686-w64-mingw32/include/SDL2/SDL_keycode.h

 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -40,19 +40,19 @@
  *  an SDLK_* constant for those keys that do not generate characters.
  *
  *  A special exception is the number keys at the top of the keyboard which
- *  always map to SDLK_0...SDLK_9, regardless of layout.
+ *  map to SDLK_0...SDLK_9 on AZERTY layouts.
  */
 typedef Sint32 SDL_Keycode;
 
 #define SDLK_SCANCODE_MASK (1<<30)
 #define SDL_SCANCODE_TO_KEYCODE(X)  (X | SDLK_SCANCODE_MASK)
 
-enum
+typedef enum
 {
     SDLK_UNKNOWN = 0,
 
     SDLK_RETURN = '\r',
-    SDLK_ESCAPE = '\033',
+    SDLK_ESCAPE = '\x1B',
     SDLK_BACKSPACE = '\b',
     SDLK_TAB = '\t',
     SDLK_SPACE = ' ',
@@ -88,9 +88,11 @@ enum
     SDLK_GREATER = '>',
     SDLK_QUESTION = '?',
     SDLK_AT = '@',
+
     /*
        Skip uppercase letters
      */
+
     SDLK_LEFTBRACKET = '[',
     SDLK_BACKSLASH = '\\',
     SDLK_RIGHTBRACKET = ']',
@@ -145,7 +147,7 @@ enum
     SDLK_INSERT = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_INSERT),
     SDLK_HOME = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_HOME),
     SDLK_PAGEUP = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PAGEUP),
-    SDLK_DELETE = '\177',
+    SDLK_DELETE = '\x7F',
     SDLK_END = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_END),
     SDLK_PAGEDOWN = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_PAGEDOWN),
     SDLK_RIGHT = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_RIGHT),
@@ -316,8 +318,13 @@ enum
     SDLK_APP2 = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_APP2),
 
     SDLK_AUDIOREWIND = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AUDIOREWIND),
-    SDLK_AUDIOFASTFORWARD = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AUDIOFASTFORWARD)
-};
+    SDLK_AUDIOFASTFORWARD = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_AUDIOFASTFORWARD),
+
+    SDLK_SOFTLEFT = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SOFTLEFT),
+    SDLK_SOFTRIGHT = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SOFTRIGHT),
+    SDLK_CALL = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CALL),
+    SDLK_ENDCALL = SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_ENDCALL)
+} SDL_KeyCode;
 
 /**
  * \brief Enumeration of valid key mods (possibly OR'd together).
@@ -336,13 +343,15 @@ typedef enum
     KMOD_NUM = 0x1000,
     KMOD_CAPS = 0x2000,
     KMOD_MODE = 0x4000,
-    KMOD_RESERVED = 0x8000
-} SDL_Keymod;
+    KMOD_SCROLL = 0x8000,
+
+    KMOD_CTRL = KMOD_LCTRL | KMOD_RCTRL,
+    KMOD_SHIFT = KMOD_LSHIFT | KMOD_RSHIFT,
+    KMOD_ALT = KMOD_LALT | KMOD_RALT,
+    KMOD_GUI = KMOD_LGUI | KMOD_RGUI,
 
-#define KMOD_CTRL   (KMOD_LCTRL|KMOD_RCTRL)
-#define KMOD_SHIFT  (KMOD_LSHIFT|KMOD_RSHIFT)
-#define KMOD_ALT    (KMOD_LALT|KMOD_RALT)
-#define KMOD_GUI    (KMOD_LGUI|KMOD_RGUI)
+    KMOD_RESERVED = KMOD_SCROLL /* This is for source-level compatibility with SDL 2.0.0. */
+} SDL_Keymod;
 
 #endif /* SDL_keycode_h_ */
 

libs/SDL2/i686-w64-mingw32/include/SDL2/SDL_loadso.h

 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -51,22 +51,56 @@ extern "C" {
 #endif
 
 /**
- *  This function dynamically loads a shared object and returns a pointer
- *  to the object handle (or NULL if there was an error).
- *  The 'sofile' parameter is a system dependent name of the object file.
+ * Dynamically load a shared object.
+ *
+ * \param sofile a system-dependent name of the object file
+ * \returns an opaque pointer to the object handle or NULL if there was an
+ *          error; call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_LoadFunction
+ * \sa SDL_UnloadObject
  */
 extern DECLSPEC void *SDLCALL SDL_LoadObject(const char *sofile);
 
 /**
- *  Given an object handle, this function looks up the address of the
- *  named function in the shared object and returns it.  This address
- *  is no longer valid after calling SDL_UnloadObject().
+ * Look up the address of the named function in a shared object.
+ *
+ * This function pointer is no longer valid after calling SDL_UnloadObject().
+ *
+ * This function can only look up C function names. Other languages may have
+ * name mangling and intrinsic language support that varies from compiler to
+ * compiler.
+ *
+ * Make sure you declare your function pointers with the same calling
+ * convention as the actual library function. Your code will crash
+ * mysteriously if you do not do this.
+ *
+ * If the requested function doesn't exist, NULL is returned.
+ *
+ * \param handle a valid shared object handle returned by SDL_LoadObject()
+ * \param name the name of the function to look up
+ * \returns a pointer to the function or NULL if there was an error; call
+ *          SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_LoadObject
+ * \sa SDL_UnloadObject
  */
 extern DECLSPEC void *SDLCALL SDL_LoadFunction(void *handle,
                                                const char *name);
 
 /**
- *  Unload a shared object from memory.
+ * Unload a shared object from memory.
+ *
+ * \param handle a valid shared object handle returned by SDL_LoadObject()
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_LoadFunction
+ * \sa SDL_LoadObject
  */
 extern DECLSPEC void SDLCALL SDL_UnloadObject(void *handle);
 

libs/SDL2/i686-w64-mingw32/include/SDL2/SDL_locale.h

+/*
+  Simple DirectMedia Layer
+  Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
+
+  This software is provided 'as-is', without any express or implied
+  warranty.  In no event will the authors be held liable for any damages
+  arising from the use of this software.
+
+  Permission is granted to anyone to use this software for any purpose,
+  including commercial applications, and to alter it and redistribute it
+  freely, subject to the following restrictions:
+
+  1. The origin of this software must not be misrepresented; you must not
+     claim that you wrote the original software. If you use this software
+     in a product, an acknowledgment in the product documentation would be
+     appreciated but is not required.
+  2. Altered source versions must be plainly marked as such, and must not be
+     misrepresented as being the original software.
+  3. This notice may not be removed or altered from any source distribution.
+*/
+
+/**
+ *  \file SDL_locale.h
+ *
+ *  Include file for SDL locale services
+ */
+
+#ifndef _SDL_locale_h
+#define _SDL_locale_h
+
+#include "SDL_stdinc.h"
+#include "SDL_error.h"
+
+#include "begin_code.h"
+/* Set up for C function definitions, even when using C++ */
+#ifdef __cplusplus
+/* *INDENT-OFF* */
+extern "C" {
+/* *INDENT-ON* */
+#endif
+
+
+typedef struct SDL_Locale
+{
+    const char *language;  /**< A language name, like "en" for English. */
+    const char *country;  /**< A country, like "US" for America. Can be NULL. */
+} SDL_Locale;
+
+/**
+ * Report the user's preferred locale.
+ *
+ * This returns an array of SDL_Locale structs, the final item zeroed out.
+ * When the caller is done with this array, it should call SDL_free() on the
+ * returned value; all the memory involved is allocated in a single block, so
+ * a single SDL_free() will suffice.
+ *
+ * Returned language strings are in the format xx, where 'xx' is an ISO-639
+ * language specifier (such as "en" for English, "de" for German, etc).
+ * Country strings are in the format YY, where "YY" is an ISO-3166 country
+ * code (such as "US" for the United States, "CA" for Canada, etc). Country
+ * might be NULL if there's no specific guidance on them (so you might get {
+ * "en", "US" } for American English, but { "en", NULL } means "English
+ * language, generically"). Language strings are never NULL, except to
+ * terminate the array.
+ *
+ * Please note that not all of these strings are 2 characters; some are three
+ * or more.
+ *
+ * The returned list of locales are in the order of the user's preference. For
+ * example, a German citizen that is fluent in US English and knows enough
+ * Japanese to navigate around Tokyo might have a list like: { "de", "en_US",
+ * "jp", NULL }. Someone from England might prefer British English (where
+ * "color" is spelled "colour", etc), but will settle for anything like it: {
+ * "en_GB", "en", NULL }.
+ *
+ * This function returns NULL on error, including when the platform does not
+ * supply this information at all.
+ *
+ * This might be a "slow" call that has to query the operating system. It's
+ * best to ask for this once and save the results. However, this list can
+ * change, usually because the user has changed a system preference outside of
+ * your program; SDL will send an SDL_LOCALECHANGED event in this case, if
+ * possible, and you can call this function again to get an updated copy of
+ * preferred locales.
+ *
+ * \return array of locales, terminated with a locale with a NULL language
+ *         field. Will return NULL on error.
+ *
+ * \since This function is available since SDL 2.0.14.
+ */
+extern DECLSPEC SDL_Locale * SDLCALL SDL_GetPreferredLocales(void);
+
+/* Ends C function definitions when using C++ */
+#ifdef __cplusplus
+/* *INDENT-OFF* */
+}
+/* *INDENT-ON* */
+#endif
+#include "close_code.h"
+
+#endif /* _SDL_locale_h */
+
+/* vi: set ts=4 sw=4 expandtab: */

libs/SDL2/i686-w64-mingw32/include/SDL2/SDL_log.h

 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -47,9 +47,9 @@ extern "C" {
 
 
 /**
- *  \brief The maximum size of a log message
+ *  \brief The maximum size of a log message prior to SDL 2.0.24
  *
- *  Messages longer than the maximum size will be truncated
+ *  As of 2.0.24 there is no limit to the length of SDL log messages.
  */
 #define SDL_MAX_LOG_MESSAGE 4096
 
@@ -61,7 +61,7 @@ extern "C" {
  *  at the VERBOSE level and all other categories are enabled at the
  *  CRITICAL level.
  */
-enum
+typedef enum
 {
     SDL_LOG_CATEGORY_APPLICATION,
     SDL_LOG_CATEGORY_ERROR,
@@ -94,7 +94,7 @@ enum
        };
      */
     SDL_LOG_CATEGORY_CUSTOM
-};
+} SDL_LogCategory;
 
 /**
  *  \brief The predefined log priorities
@@ -112,90 +112,283 @@ typedef enum
 
 
 /**
- *  \brief Set the priority of all log categories
+ * Set the priority of all log categories.
+ *
+ * \param priority the SDL_LogPriority to assign
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_LogSetPriority
  */
 extern DECLSPEC void SDLCALL SDL_LogSetAllPriority(SDL_LogPriority priority);
 
 /**
- *  \brief Set the priority of a particular log category
+ * Set the priority of a particular log category.
+ *
+ * \param category the category to assign a priority to
+ * \param priority the SDL_LogPriority to assign
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_LogGetPriority
+ * \sa SDL_LogSetAllPriority
  */
 extern DECLSPEC void SDLCALL SDL_LogSetPriority(int category,
                                                 SDL_LogPriority priority);
 
 /**
- *  \brief Get the priority of a particular log category
+ * Get the priority of a particular log category.
+ *
+ * \param category the category to query
+ * \returns the SDL_LogPriority for the requested category
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_LogSetPriority
  */
 extern DECLSPEC SDL_LogPriority SDLCALL SDL_LogGetPriority(int category);
 
 /**
- *  \brief Reset all priorities to default.
+ * Reset all priorities to default.
+ *
+ * This is called by SDL_Quit().
+ *
+ * \since This function is available since SDL 2.0.0.
  *
- *  \note This is called in SDL_Quit().
+ * \sa SDL_LogSetAllPriority
+ * \sa SDL_LogSetPriority
  */
 extern DECLSPEC void SDLCALL SDL_LogResetPriorities(void);
 
 /**
- *  \brief Log a message with SDL_LOG_CATEGORY_APPLICATION and SDL_LOG_PRIORITY_INFO
+ * Log a message with SDL_LOG_CATEGORY_APPLICATION and SDL_LOG_PRIORITY_INFO.
+ *
+ * = * \param fmt a printf() style message format string
+ *
+ * \param ... additional parameters matching % tokens in the `fmt` string, if
+ *            any
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_LogCritical
+ * \sa SDL_LogDebug
+ * \sa SDL_LogError
+ * \sa SDL_LogInfo
+ * \sa SDL_LogMessage
+ * \sa SDL_LogMessageV
+ * \sa SDL_LogVerbose
+ * \sa SDL_LogWarn
  */
 extern DECLSPEC void SDLCALL SDL_Log(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1);
 
 /**
- *  \brief Log a message with SDL_LOG_PRIORITY_VERBOSE
+ * Log a message with SDL_LOG_PRIORITY_VERBOSE.
+ *
+ * \param category the category of the message
+ * \param fmt a printf() style message format string
+ * \param ... additional parameters matching % tokens in the **fmt** string,
+ *            if any
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_Log
+ * \sa SDL_LogCritical
+ * \sa SDL_LogDebug
+ * \sa SDL_LogError
+ * \sa SDL_LogInfo
+ * \sa SDL_LogMessage
+ * \sa SDL_LogMessageV
+ * \sa SDL_LogWarn
  */
 extern DECLSPEC void SDLCALL SDL_LogVerbose(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
 
 /**
- *  \brief Log a message with SDL_LOG_PRIORITY_DEBUG
+ * Log a message with SDL_LOG_PRIORITY_DEBUG.
+ *
+ * \param category the category of the message
+ * \param fmt a printf() style message format string
+ * \param ... additional parameters matching % tokens in the **fmt** string,
+ *            if any
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_Log
+ * \sa SDL_LogCritical
+ * \sa SDL_LogError
+ * \sa SDL_LogInfo
+ * \sa SDL_LogMessage
+ * \sa SDL_LogMessageV
+ * \sa SDL_LogVerbose
+ * \sa SDL_LogWarn
  */
 extern DECLSPEC void SDLCALL SDL_LogDebug(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
 
 /**
- *  \brief Log a message with SDL_LOG_PRIORITY_INFO
+ * Log a message with SDL_LOG_PRIORITY_INFO.
+ *
+ * \param category the category of the message
+ * \param fmt a printf() style message format string
+ * \param ... additional parameters matching % tokens in the **fmt** string,
+ *            if any
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_Log
+ * \sa SDL_LogCritical
+ * \sa SDL_LogDebug
+ * \sa SDL_LogError
+ * \sa SDL_LogMessage
+ * \sa SDL_LogMessageV
+ * \sa SDL_LogVerbose
+ * \sa SDL_LogWarn
  */
 extern DECLSPEC void SDLCALL SDL_LogInfo(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
 
 /**
- *  \brief Log a message with SDL_LOG_PRIORITY_WARN
+ * Log a message with SDL_LOG_PRIORITY_WARN.
+ *
+ * \param category the category of the message
+ * \param fmt a printf() style message format string
+ * \param ... additional parameters matching % tokens in the **fmt** string,
+ *            if any
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_Log
+ * \sa SDL_LogCritical
+ * \sa SDL_LogDebug
+ * \sa SDL_LogError
+ * \sa SDL_LogInfo
+ * \sa SDL_LogMessage
+ * \sa SDL_LogMessageV
+ * \sa SDL_LogVerbose
  */
 extern DECLSPEC void SDLCALL SDL_LogWarn(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
 
 /**
- *  \brief Log a message with SDL_LOG_PRIORITY_ERROR
+ * Log a message with SDL_LOG_PRIORITY_ERROR.
+ *
+ * \param category the category of the message
+ * \param fmt a printf() style message format string
+ * \param ... additional parameters matching % tokens in the **fmt** string,
+ *            if any
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_Log
+ * \sa SDL_LogCritical
+ * \sa SDL_LogDebug
+ * \sa SDL_LogInfo
+ * \sa SDL_LogMessage
+ * \sa SDL_LogMessageV
+ * \sa SDL_LogVerbose
+ * \sa SDL_LogWarn
  */
 extern DECLSPEC void SDLCALL SDL_LogError(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
 
 /**
- *  \brief Log a message with SDL_LOG_PRIORITY_CRITICAL
+ * Log a message with SDL_LOG_PRIORITY_CRITICAL.
+ *
+ * \param category the category of the message
+ * \param fmt a printf() style message format string
+ * \param ... additional parameters matching % tokens in the **fmt** string,
+ *            if any
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_Log
+ * \sa SDL_LogDebug
+ * \sa SDL_LogError
+ * \sa SDL_LogInfo
+ * \sa SDL_LogMessage
+ * \sa SDL_LogMessageV
+ * \sa SDL_LogVerbose
+ * \sa SDL_LogWarn
  */
 extern DECLSPEC void SDLCALL SDL_LogCritical(int category, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
 
 /**
- *  \brief Log a message with the specified category and priority.
+ * Log a message with the specified category and priority.
+ *
+ * \param category the category of the message
+ * \param priority the priority of the message
+ * \param fmt a printf() style message format string
+ * \param ... additional parameters matching % tokens in the **fmt** string,
+ *            if any
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_Log
+ * \sa SDL_LogCritical
+ * \sa SDL_LogDebug
+ * \sa SDL_LogError
+ * \sa SDL_LogInfo
+ * \sa SDL_LogMessageV
+ * \sa SDL_LogVerbose
+ * \sa SDL_LogWarn
  */
 extern DECLSPEC void SDLCALL SDL_LogMessage(int category,
                                             SDL_LogPriority priority,
                                             SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(3);
 
 /**
- *  \brief Log a message with the specified category and priority.
+ * Log a message with the specified category and priority.
+ *
+ * \param category the category of the message
+ * \param priority the priority of the message
+ * \param fmt a printf() style message format string
+ * \param ap a variable argument list
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_Log
+ * \sa SDL_LogCritical
+ * \sa SDL_LogDebug
+ * \sa SDL_LogError
+ * \sa SDL_LogInfo
+ * \sa SDL_LogMessage
+ * \sa SDL_LogVerbose
+ * \sa SDL_LogWarn
  */
 extern DECLSPEC void SDLCALL SDL_LogMessageV(int category,
                                              SDL_LogPriority priority,
                                              const char *fmt, va_list ap);
 
 /**
- *  \brief The prototype for the log output function
+ * The prototype for the log output callback function.
+ *
+ * This function is called by SDL when there is new text to be logged.
+ *
+ * \param userdata what was passed as `userdata` to SDL_LogSetOutputFunction()
+ * \param category the category of the message
+ * \param priority the priority of the message
+ * \param message the message being output
  */
 typedef void (SDLCALL *SDL_LogOutputFunction)(void *userdata, int category, SDL_LogPriority priority, const char *message);
 
 /**
- *  \brief Get the current log output function.
+ * Get the current log output function.
+ *
+ * \param callback an SDL_LogOutputFunction filled in with the current log
+ *                 callback
+ * \param userdata a pointer filled in with the pointer that is passed to
+ *                 `callback`
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_LogSetOutputFunction
  */
 extern DECLSPEC void SDLCALL SDL_LogGetOutputFunction(SDL_LogOutputFunction *callback, void **userdata);
 
 /**
- *  \brief This function allows you to replace the default log output
- *         function with one of your own.
+ * Replace the default log output function with one of your own.
+ *
+ * \param callback an SDL_LogOutputFunction to call instead of the default
+ * \param userdata a pointer that is passed to `callback`
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_LogGetOutputFunction
  */
 extern DECLSPEC void SDLCALL SDL_LogSetOutputFunction(SDL_LogOutputFunction callback, void *userdata);
 

libs/SDL2/i686-w64-mingw32/include/SDL2/SDL_main.h

 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -51,6 +51,15 @@
 */
 #define SDL_MAIN_NEEDED
 
+#elif defined(__GDK__)
+/* On GDK, SDL provides a main function that initializes the game runtime.
+
+   Please note that #include'ing SDL_main.h is not enough to get a main()
+   function working. You must either link against SDL2main or, if not possible,
+   call the SDL_GDKRunApp function from your entry point.
+*/
+#define SDL_MAIN_NEEDED
+
 #elif defined(__IPHONEOS__)
 /* On iOS SDL provides a main function that creates an application delegate
    and starts the iOS application run loop.
@@ -83,6 +92,31 @@
 */
 #define SDL_MAIN_NEEDED
 
+#elif defined(__PSP__)
+/* On PSP SDL provides a main function that sets the module info,
+   activates the GPU and starts the thread required to be able to exit
+   the software.
+
+   If you provide this yourself, you may define SDL_MAIN_HANDLED
+ */
+#define SDL_MAIN_AVAILABLE
+
+#elif defined(__PS2__)
+#define SDL_MAIN_AVAILABLE
+
+#define SDL_PS2_SKIP_IOP_RESET() \
+   void reset_IOP(); \
+   void reset_IOP() {}
+
+#elif defined(__3DS__)
+/*
+  On N3DS, SDL provides a main function that sets up the screens
+  and storage.
+
+  If you provide this yourself, you may define SDL_MAIN_HANDLED
+*/
+#define SDL_MAIN_AVAILABLE
+
 #endif
 #endif /* SDL_MAIN_HANDLED */
 
@@ -122,34 +156,78 @@ extern SDLMAIN_DECLSPEC int SDL_main(int argc, char *argv[]);
 
 
 /**
- *  This is called by the real SDL main function to let the rest of the
- *  library know that initialization was done properly.
+ * Circumvent failure of SDL_Init() when not using SDL_main() as an entry
+ * point.
+ *
+ * This function is defined in SDL_main.h, along with the preprocessor rule to
+ * redefine main() as SDL_main(). Thus to ensure that your main() function
+ * will not be changed it is necessary to define SDL_MAIN_HANDLED before
+ * including SDL.h.
+ *
+ * \since This function is available since SDL 2.0.0.
  *
- *  Calling this yourself without knowing what you're doing can cause
- *  crashes and hard to diagnose problems with your application.
+ * \sa SDL_Init
  */
 extern DECLSPEC void SDLCALL SDL_SetMainReady(void);
 
-#ifdef __WIN32__
+#if defined(__WIN32__) || defined(__GDK__)
+
+/**
+ * Register a win32 window class for SDL's use.
+ *
+ * This can be called to set the application window class at startup. It is
+ * safe to call this multiple times, as long as every call is eventually
+ * paired with a call to SDL_UnregisterApp, but a second registration attempt
+ * while a previous registration is still active will be ignored, other than
+ * to increment a counter.
+ *
+ * Most applications do not need to, and should not, call this directly; SDL
+ * will call it when initializing the video subsystem.
+ *
+ * \param name the window class name, in UTF-8 encoding. If NULL, SDL
+ *             currently uses "SDL_app" but this isn't guaranteed.
+ * \param style the value to use in WNDCLASSEX::style. If `name` is NULL, SDL
+ *              currently uses `(CS_BYTEALIGNCLIENT | CS_OWNDC)` regardless of
+ *              what is specified here.
+ * \param hInst the HINSTANCE to use in WNDCLASSEX::hInstance. If zero, SDL
+ *              will use `GetModuleHandle(NULL)` instead.
+ * \returns 0 on success, -1 on error. SDL_GetError() may have details.
+ *
+ * \since This function is available since SDL 2.0.2.
+ */
+extern DECLSPEC int SDLCALL SDL_RegisterApp(const char *name, Uint32 style, void *hInst);
 
 /**
- *  This can be called to set the application class at startup
+ * Deregister the win32 window class from an SDL_RegisterApp call.
+ *
+ * This can be called to undo the effects of SDL_RegisterApp.
+ *
+ * Most applications do not need to, and should not, call this directly; SDL
+ * will call it when deinitializing the video subsystem.
+ *
+ * It is safe to call this multiple times, as long as every call is eventually
+ * paired with a prior call to SDL_RegisterApp. The window class will only be
+ * deregistered when the registration counter in SDL_RegisterApp decrements to
+ * zero through calls to this function.
+ *
+ * \since This function is available since SDL 2.0.2.
  */
-extern DECLSPEC int SDLCALL SDL_RegisterApp(char *name, Uint32 style, void *hInst);
 extern DECLSPEC void SDLCALL SDL_UnregisterApp(void);
 
-#endif /* __WIN32__ */
+#endif /* defined(__WIN32__) || defined(__GDK__) */
 
 
 #ifdef __WINRT__
 
 /**
- *  \brief Initializes and launches an SDL/WinRT application.
+ * Initialize and launch an SDL/WinRT application.
  *
- *  \param mainFunction The SDL app's C-style main().
- *  \param reserved Reserved for future use; should be NULL
- *  \return 0 on success, -1 on failure.  On failure, use SDL_GetError to retrieve more
- *      information on the failure.
+ * \param mainFunction the SDL app's C-style main(), an SDL_main_func
+ * \param reserved reserved for future use; should be NULL
+ * \returns 0 on success or -1 on failure; call SDL_GetError() to retrieve
+ *          more information on the failure.
+ *
+ * \since This function is available since SDL 2.0.3.
  */
 extern DECLSPEC int SDLCALL SDL_WinRTRunApp(SDL_main_func mainFunction, void * reserved);
 
@@ -158,17 +236,41 @@ extern DECLSPEC int SDLCALL SDL_WinRTRunApp(SDL_main_func mainFunction, void * r
 #if defined(__IPHONEOS__)
 
 /**
- *  \brief Initializes and launches an SDL application.
+ * Initializes and launches an SDL application.
+ *
+ * \param argc The argc parameter from the application's main() function
+ * \param argv The argv parameter from the application's main() function
+ * \param mainFunction The SDL app's C-style main(), an SDL_main_func
+ * \return the return value from mainFunction
  *
- *  \param argc The argc parameter from the application's main() function
- *  \param argv The argv parameter from the application's main() function
- *  \param mainFunction The SDL app's C-style main().
- *  \return the return value from mainFunction
+ * \since This function is available since SDL 2.0.10.
  */
 extern DECLSPEC int SDLCALL SDL_UIKitRunApp(int argc, char *argv[], SDL_main_func mainFunction);
 
 #endif /* __IPHONEOS__ */
 
+#ifdef __GDK__
+
+/**
+ * Initialize and launch an SDL GDK application.
+ *
+ * \param mainFunction the SDL app's C-style main(), an SDL_main_func
+ * \param reserved reserved for future use; should be NULL
+ * \returns 0 on success or -1 on failure; call SDL_GetError() to retrieve
+ *          more information on the failure.
+ *
+ * \since This function is available since SDL 2.24.0.
+ */
+extern DECLSPEC int SDLCALL SDL_GDKRunApp(SDL_main_func mainFunction, void *reserved);
+
+/**
+ * Callback from the application to let the suspend continue.
+ *
+ * \since This function is available since SDL 2.28.0.
+ */
+extern DECLSPEC void SDLCALL SDL_GDKSuspendComplete(void);
+
+#endif /* __GDK__ */
 
 #ifdef __cplusplus
 }

libs/SDL2/i686-w64-mingw32/include/SDL2/SDL_messagebox.h

 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -32,17 +32,19 @@ extern "C" {
 #endif
 
 /**
- * \brief SDL_MessageBox flags. If supported will display warning icon, etc.
+ * SDL_MessageBox flags. If supported will display warning icon, etc.
  */
 typedef enum
 {
-    SDL_MESSAGEBOX_ERROR        = 0x00000010,   /**< error dialog */
-    SDL_MESSAGEBOX_WARNING      = 0x00000020,   /**< warning dialog */
-    SDL_MESSAGEBOX_INFORMATION  = 0x00000040    /**< informational dialog */
+    SDL_MESSAGEBOX_ERROR                 = 0x00000010,   /**< error dialog */
+    SDL_MESSAGEBOX_WARNING               = 0x00000020,   /**< warning dialog */
+    SDL_MESSAGEBOX_INFORMATION           = 0x00000040,   /**< informational dialog */
+    SDL_MESSAGEBOX_BUTTONS_LEFT_TO_RIGHT = 0x00000080,   /**< buttons placed left to right */
+    SDL_MESSAGEBOX_BUTTONS_RIGHT_TO_LEFT = 0x00000100    /**< buttons placed right to left */
 } SDL_MessageBoxFlags;
 
 /**
- * \brief Flags for SDL_MessageBoxButtonData.
+ * Flags for SDL_MessageBoxButtonData.
  */
 typedef enum
 {
@@ -51,7 +53,7 @@ typedef enum
 } SDL_MessageBoxButtonFlags;
 
 /**
- *  \brief Individual button data.
+ * Individual button data.
  */
 typedef struct
 {
@@ -61,7 +63,7 @@ typedef struct
 } SDL_MessageBoxButtonData;
 
 /**
- * \brief RGB value used in a message box color scheme
+ * RGB value used in a message box color scheme
  */
 typedef struct
 {
@@ -79,7 +81,7 @@ typedef enum
 } SDL_MessageBoxColorType;
 
 /**
- * \brief A set of colors to use for message box dialogs
+ * A set of colors to use for message box dialogs
  */
 typedef struct
 {
@@ -87,7 +89,7 @@ typedef struct
 } SDL_MessageBoxColorScheme;
 
 /**
- *  \brief MessageBox structure containing title, text, window, etc.
+ * MessageBox structure containing title, text, window, etc.
  */
 typedef struct
 {
@@ -103,32 +105,79 @@ typedef struct
 } SDL_MessageBoxData;
 
 /**
- *  \brief Create a modal message box.
+ * Create a modal message box.
  *
- *  \param messageboxdata The SDL_MessageBoxData structure with title, text, etc.
- *  \param buttonid The pointer to which user id of hit button should be copied.
+ * If your needs aren't complex, it might be easier to use
+ * SDL_ShowSimpleMessageBox.
  *
- *  \return -1 on error, otherwise 0 and buttonid contains user id of button
- *          hit or -1 if dialog was closed.
+ * This function should be called on the thread that created the parent
+ * window, or on the main thread if the messagebox has no parent. It will
+ * block execution of that thread until the user clicks a button or closes the
+ * messagebox.
  *
- *  \note This function should be called on the thread that created the parent
- *        window, or on the main thread if the messagebox has no parent.  It will
- *        block execution of that thread until the user clicks a button or
- *        closes the messagebox.
+ * This function may be called at any time, even before SDL_Init(). This makes
+ * it useful for reporting errors like a failure to create a renderer or
+ * OpenGL context.
+ *
+ * On X11, SDL rolls its own dialog box with X11 primitives instead of a
+ * formal toolkit like GTK+ or Qt.
+ *
+ * Note that if SDL_Init() would fail because there isn't any available video
+ * target, this function is likely to fail for the same reasons. If this is a
+ * concern, check the return value from this function and fall back to writing
+ * to stderr if you can.
+ *
+ * \param messageboxdata the SDL_MessageBoxData structure with title, text and
+ *                       other options
+ * \param buttonid the pointer to which user id of hit button should be copied
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_ShowSimpleMessageBox
  */
 extern DECLSPEC int SDLCALL SDL_ShowMessageBox(const SDL_MessageBoxData *messageboxdata, int *buttonid);
 
 /**
- *  \brief Create a simple modal message box
+ * Display a simple modal message box.
+ *
+ * If your needs aren't complex, this function is preferred over
+ * SDL_ShowMessageBox.
+ *
+ * `flags` may be any of the following:
+ *
+ * - `SDL_MESSAGEBOX_ERROR`: error dialog
+ * - `SDL_MESSAGEBOX_WARNING`: warning dialog
+ * - `SDL_MESSAGEBOX_INFORMATION`: informational dialog
+ *
+ * This function should be called on the thread that created the parent
+ * window, or on the main thread if the messagebox has no parent. It will
+ * block execution of that thread until the user clicks a button or closes the
+ * messagebox.
+ *
+ * This function may be called at any time, even before SDL_Init(). This makes
+ * it useful for reporting errors like a failure to create a renderer or
+ * OpenGL context.
+ *
+ * On X11, SDL rolls its own dialog box with X11 primitives instead of a
+ * formal toolkit like GTK+ or Qt.
+ *
+ * Note that if SDL_Init() would fail because there isn't any available video
+ * target, this function is likely to fail for the same reasons. If this is a
+ * concern, check the return value from this function and fall back to writing
+ * to stderr if you can.
  *
- *  \param flags    ::SDL_MessageBoxFlags
- *  \param title    UTF-8 title text
- *  \param message  UTF-8 message text
- *  \param window   The parent window, or NULL for no parent
+ * \param flags an SDL_MessageBoxFlags value
+ * \param title UTF-8 title text
+ * \param message UTF-8 message text
+ * \param window the parent window, or NULL for no parent
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
  *
- *  \return 0 on success, -1 on error
+ * \since This function is available since SDL 2.0.0.
  *
- *  \sa SDL_ShowMessageBox
+ * \sa SDL_ShowMessageBox
  */
 extern DECLSPEC int SDLCALL SDL_ShowSimpleMessageBox(Uint32 flags, const char *title, const char *message, SDL_Window *window);
 

libs/SDL2/i686-w64-mingw32/include/SDL2/SDL_metal.h

+/*
+  Simple DirectMedia Layer
+  Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
+
+  This software is provided 'as-is', without any express or implied
+  warranty.  In no event will the authors be held liable for any damages
+  arising from the use of this software.
+
+  Permission is granted to anyone to use this software for any purpose,
+  including commercial applications, and to alter it and redistribute it
+  freely, subject to the following restrictions:
+
+  1. The origin of this software must not be misrepresented; you must not
+     claim that you wrote the original software. If you use this software
+     in a product, an acknowledgment in the product documentation would be
+     appreciated but is not required.
+  2. Altered source versions must be plainly marked as such, and must not be
+     misrepresented as being the original software.
+  3. This notice may not be removed or altered from any source distribution.
+*/
+
+/**
+ *  \file SDL_metal.h
+ *
+ *  Header file for functions to creating Metal layers and views on SDL windows.
+ */
+
+#ifndef SDL_metal_h_
+#define SDL_metal_h_
+
+#include "SDL_video.h"
+
+#include "begin_code.h"
+/* Set up for C function definitions, even when using C++ */
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ *  \brief A handle to a CAMetalLayer-backed NSView (macOS) or UIView (iOS/tvOS).
+ *
+ *  \note This can be cast directly to an NSView or UIView.
+ */
+typedef void *SDL_MetalView;
+
+/**
+ *  \name Metal support functions
+ */
+/* @{ */
+
+/**
+ * Create a CAMetalLayer-backed NSView/UIView and attach it to the specified
+ * window.
+ *
+ * On macOS, this does *not* associate a MTLDevice with the CAMetalLayer on
+ * its own. It is up to user code to do that.
+ *
+ * The returned handle can be casted directly to a NSView or UIView. To access
+ * the backing CAMetalLayer, call SDL_Metal_GetLayer().
+ *
+ * \since This function is available since SDL 2.0.12.
+ *
+ * \sa SDL_Metal_DestroyView
+ * \sa SDL_Metal_GetLayer
+ */
+extern DECLSPEC SDL_MetalView SDLCALL SDL_Metal_CreateView(SDL_Window * window);
+
+/**
+ * Destroy an existing SDL_MetalView object.
+ *
+ * This should be called before SDL_DestroyWindow, if SDL_Metal_CreateView was
+ * called after SDL_CreateWindow.
+ *
+ * \since This function is available since SDL 2.0.12.
+ *
+ * \sa SDL_Metal_CreateView
+ */
+extern DECLSPEC void SDLCALL SDL_Metal_DestroyView(SDL_MetalView view);
+
+/**
+ * Get a pointer to the backing CAMetalLayer for the given view.
+ *
+ * \since This function is available since SDL 2.0.14.
+ *
+ * \sa SDL_Metal_CreateView
+ */
+extern DECLSPEC void *SDLCALL SDL_Metal_GetLayer(SDL_MetalView view);
+
+/**
+ * Get the size of a window's underlying drawable in pixels (for use with
+ * setting viewport, scissor & etc).
+ *
+ * \param window SDL_Window from which the drawable size should be queried
+ * \param w Pointer to variable for storing the width in pixels, may be NULL
+ * \param h Pointer to variable for storing the height in pixels, may be NULL
+ *
+ * \since This function is available since SDL 2.0.14.
+ *
+ * \sa SDL_GetWindowSize
+ * \sa SDL_CreateWindow
+ */
+extern DECLSPEC void SDLCALL SDL_Metal_GetDrawableSize(SDL_Window* window, int *w,
+                                                       int *h);
+
+/* @} *//* Metal support functions */
+
+/* Ends C function definitions when using C++ */
+#ifdef __cplusplus
+}
+#endif
+#include "close_code.h"
+
+#endif /* SDL_metal_h_ */

libs/SDL2/include/SDL_config_minimal.h → libs/SDL2/i686-w64-mingw32/include/SDL2/SDL_misc.h

 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2017 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -19,64 +19,61 @@
   3. This notice may not be removed or altered from any source distribution.
 */
 
-#ifndef SDL_config_minimal_h_
-#define SDL_config_minimal_h_
-#define SDL_config_h_
-
-#include "SDL_platform.h"
-
 /**
- *  \file SDL_config_minimal.h
+ *  \file SDL_misc.h
  *
- *  This is the minimal configuration that can be used to build SDL.
+ *  \brief Include file for SDL API functions that don't fit elsewhere.
  */
 
-#define HAVE_STDARG_H   1
-#define HAVE_STDDEF_H   1
-
-/* Most everything except Visual Studio 2008 and earlier has stdint.h now */
-#if defined(_MSC_VER) && (_MSC_VER < 1600)
-/* Here are some reasonable defaults */
-typedef unsigned int size_t;
-typedef signed char int8_t;
-typedef unsigned char uint8_t;
-typedef signed short int16_t;
-typedef unsigned short uint16_t;
-typedef signed int int32_t;
-typedef unsigned int uint32_t;
-typedef signed long long int64_t;
-typedef unsigned long long uint64_t;
-typedef unsigned long uintptr_t;
-#else
-#define HAVE_STDINT_H 1
-#endif /* Visual Studio 2008 */
-
-#ifdef __GNUC__
-#define HAVE_GCC_SYNC_LOCK_TEST_AND_SET 1
-#endif
+#ifndef SDL_misc_h_
+#define SDL_misc_h_
 
-/* Enable the dummy audio driver (src/audio/dummy/\*.c) */
-#define SDL_AUDIO_DRIVER_DUMMY  1
+#include "SDL_stdinc.h"
 
-/* Enable the stub joystick driver (src/joystick/dummy/\*.c) */
-#define SDL_JOYSTICK_DISABLED   1
+#include "begin_code.h"
 
-/* Enable the stub haptic driver (src/haptic/dummy/\*.c) */
-#define SDL_HAPTIC_DISABLED 1
-
-/* Enable the stub shared object loader (src/loadso/dummy/\*.c) */
-#define SDL_LOADSO_DISABLED 1
-
-/* Enable the stub thread support (src/thread/generic/\*.c) */
-#define SDL_THREADS_DISABLED    1
+/* Set up for C function definitions, even when using C++ */
+#ifdef __cplusplus
+extern "C" {
+#endif
 
-/* Enable the stub timer support (src/timer/dummy/\*.c) */
-#define SDL_TIMERS_DISABLED 1
+/**
+ * Open a URL/URI in the browser or other appropriate external application.
+ *
+ * Open a URL in a separate, system-provided application. How this works will
+ * vary wildly depending on the platform. This will likely launch what makes
+ * sense to handle a specific URL's protocol (a web browser for `http://`,
+ * etc), but it might also be able to launch file managers for directories and
+ * other things.
+ *
+ * What happens when you open a URL varies wildly as well: your game window
+ * may lose focus (and may or may not lose focus if your game was fullscreen
+ * or grabbing input at the time). On mobile devices, your app will likely
+ * move to the background or your process might be paused. Any given platform
+ * may or may not handle a given URL.
+ *
+ * If this is unimplemented (or simply unavailable) for a platform, this will
+ * fail with an error. A successful result does not mean the URL loaded, just
+ * that we launched _something_ to handle it (or at least believe we did).
+ *
+ * All this to say: this function can be useful, but you should definitely
+ * test it on every platform you target.
+ *
+ * \param url A valid URL/URI to open. Use `file:///full/path/to/file` for
+ *            local files, if supported.
+ * \returns 0 on success, or -1 on error; call SDL_GetError() for more
+ *          information.
+ *
+ * \since This function is available since SDL 2.0.14.
+ */
+extern DECLSPEC int SDLCALL SDL_OpenURL(const char *url);
 
-/* Enable the dummy video driver (src/video/dummy/\*.c) */
-#define SDL_VIDEO_DRIVER_DUMMY  1
+/* Ends C function definitions when using C++ */
+#ifdef __cplusplus
+}
+#endif
+#include "close_code.h"
 
-/* Enable the dummy filesystem driver (src/filesystem/dummy/\*.c) */
-#define SDL_FILESYSTEM_DUMMY  1
+#endif /* SDL_misc_h_ */
 
-#endif /* SDL_config_minimal_h_ */
+/* vi: set ts=4 sw=4 expandtab: */

libs/SDL2/i686-w64-mingw32/include/SDL2/SDL_mouse.h

 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -72,150 +72,247 @@ typedef enum
 /* Function prototypes */
 
 /**
- *  \brief Get the window which currently has mouse focus.
+ * Get the window which currently has mouse focus.
+ *
+ * \returns the window with mouse focus.
+ *
+ * \since This function is available since SDL 2.0.0.
  */
 extern DECLSPEC SDL_Window * SDLCALL SDL_GetMouseFocus(void);
 
 /**
- *  \brief Retrieve the current state of the mouse.
+ * Retrieve the current state of the mouse.
+ *
+ * The current button state is returned as a button bitmask, which can be
+ * tested using the `SDL_BUTTON(X)` macros (where `X` is generally 1 for the
+ * left, 2 for middle, 3 for the right button), and `x` and `y` are set to the
+ * mouse cursor position relative to the focus window. You can pass NULL for
+ * either `x` or `y`.
+ *
+ * \param x the x coordinate of the mouse cursor position relative to the
+ *          focus window
+ * \param y the y coordinate of the mouse cursor position relative to the
+ *          focus window
+ * \returns a 32-bit button bitmask of the current button state.
  *
- *  The current button state is returned as a button bitmask, which can
- *  be tested using the SDL_BUTTON(X) macros, and x and y are set to the
- *  mouse cursor position relative to the focus window for the currently
- *  selected mouse.  You can pass NULL for either x or y.
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetGlobalMouseState
+ * \sa SDL_GetRelativeMouseState
+ * \sa SDL_PumpEvents
  */
 extern DECLSPEC Uint32 SDLCALL SDL_GetMouseState(int *x, int *y);
 
 /**
- *  \brief Get the current state of the mouse, in relation to the desktop
- *
- *  This works just like SDL_GetMouseState(), but the coordinates will be
- *  reported relative to the top-left of the desktop. This can be useful if
- *  you need to track the mouse outside of a specific window and
- *  SDL_CaptureMouse() doesn't fit your needs. For example, it could be
- *  useful if you need to track the mouse while dragging a window, where
- *  coordinates relative to a window might not be in sync at all times.
- *
- *  \note SDL_GetMouseState() returns the mouse position as SDL understands
- *        it from the last pump of the event queue. This function, however,
- *        queries the OS for the current mouse position, and as such, might
- *        be a slightly less efficient function. Unless you know what you're
- *        doing and have a good reason to use this function, you probably want
- *        SDL_GetMouseState() instead.
- *
- *  \param x Returns the current X coord, relative to the desktop. Can be NULL.
- *  \param y Returns the current Y coord, relative to the desktop. Can be NULL.
- *  \return The current button state as a bitmask, which can be tested using the SDL_BUTTON(X) macros.
- *
- *  \sa SDL_GetMouseState
+ * Get the current state of the mouse in relation to the desktop.
+ *
+ * This works similarly to SDL_GetMouseState(), but the coordinates will be
+ * reported relative to the top-left of the desktop. This can be useful if you
+ * need to track the mouse outside of a specific window and SDL_CaptureMouse()
+ * doesn't fit your needs. For example, it could be useful if you need to
+ * track the mouse while dragging a window, where coordinates relative to a
+ * window might not be in sync at all times.
+ *
+ * Note: SDL_GetMouseState() returns the mouse position as SDL understands it
+ * from the last pump of the event queue. This function, however, queries the
+ * OS for the current mouse position, and as such, might be a slightly less
+ * efficient function. Unless you know what you're doing and have a good
+ * reason to use this function, you probably want SDL_GetMouseState() instead.
+ *
+ * \param x filled in with the current X coord relative to the desktop; can be
+ *          NULL
+ * \param y filled in with the current Y coord relative to the desktop; can be
+ *          NULL
+ * \returns the current button state as a bitmask which can be tested using
+ *          the SDL_BUTTON(X) macros.
+ *
+ * \since This function is available since SDL 2.0.4.
+ *
+ * \sa SDL_CaptureMouse
  */
 extern DECLSPEC Uint32 SDLCALL SDL_GetGlobalMouseState(int *x, int *y);
 
 /**
- *  \brief Retrieve the relative state of the mouse.
+ * Retrieve the relative state of the mouse.
+ *
+ * The current button state is returned as a button bitmask, which can be
+ * tested using the `SDL_BUTTON(X)` macros (where `X` is generally 1 for the
+ * left, 2 for middle, 3 for the right button), and `x` and `y` are set to the
+ * mouse deltas since the last call to SDL_GetRelativeMouseState() or since
+ * event initialization. You can pass NULL for either `x` or `y`.
+ *
+ * \param x a pointer filled with the last recorded x coordinate of the mouse
+ * \param y a pointer filled with the last recorded y coordinate of the mouse
+ * \returns a 32-bit button bitmask of the relative button state.
  *
- *  The current button state is returned as a button bitmask, which can
- *  be tested using the SDL_BUTTON(X) macros, and x and y are set to the
- *  mouse deltas since the last call to SDL_GetRelativeMouseState().
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetMouseState
  */
 extern DECLSPEC Uint32 SDLCALL SDL_GetRelativeMouseState(int *x, int *y);
 
 /**
- *  \brief Moves the mouse to the given position within the window.
+ * Move the mouse cursor to the given position within the window.
+ *
+ * This function generates a mouse motion event if relative mode is not
+ * enabled. If relative mode is enabled, you can force mouse events for the
+ * warp by setting the SDL_HINT_MOUSE_RELATIVE_WARP_MOTION hint.
+ *
+ * Note that this function will appear to succeed, but not actually move the
+ * mouse when used over Microsoft Remote Desktop.
  *
- *  \param window The window to move the mouse into, or NULL for the current mouse focus
- *  \param x The x coordinate within the window
- *  \param y The y coordinate within the window
+ * \param window the window to move the mouse into, or NULL for the current
+ *               mouse focus
+ * \param x the x coordinate within the window
+ * \param y the y coordinate within the window
  *
- *  \note This function generates a mouse motion event
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_WarpMouseGlobal
  */
 extern DECLSPEC void SDLCALL SDL_WarpMouseInWindow(SDL_Window * window,
                                                    int x, int y);
 
 /**
- *  \brief Moves the mouse to the given position in global screen space.
+ * Move the mouse to the given position in global screen space.
+ *
+ * This function generates a mouse motion event.
+ *
+ * A failure of this function usually means that it is unsupported by a
+ * platform.
+ *
+ * Note that this function will appear to succeed, but not actually move the
+ * mouse when used over Microsoft Remote Desktop.
  *
- *  \param x The x coordinate
- *  \param y The y coordinate
- *  \return 0 on success, -1 on error (usually: unsupported by a platform).
+ * \param x the x coordinate
+ * \param y the y coordinate
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
  *
- *  \note This function generates a mouse motion event
+ * \since This function is available since SDL 2.0.4.
+ *
+ * \sa SDL_WarpMouseInWindow
  */
 extern DECLSPEC int SDLCALL SDL_WarpMouseGlobal(int x, int y);
 
 /**
- *  \brief Set relative mouse mode.
+ * Set relative mouse mode.
+ *
+ * While the mouse is in relative mode, the cursor is hidden, the mouse
+ * position is constrained to the window, and SDL will report continuous
+ * relative mouse motion even if the mouse is at the edge of the window.
  *
- *  \param enabled Whether or not to enable relative mode
+ * This function will flush any pending mouse motion.
  *
- *  \return 0 on success, or -1 if relative mode is not supported.
+ * \param enabled SDL_TRUE to enable relative mode, SDL_FALSE to disable.
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
  *
- *  While the mouse is in relative mode, the cursor is hidden, and the
- *  driver will try to report continuous motion in the current window.
- *  Only relative motion events will be delivered, the mouse position
- *  will not change.
+ *          If relative mode is not supported, this returns -1.
  *
- *  \note This function will flush any pending mouse motion.
+ * \since This function is available since SDL 2.0.0.
  *
- *  \sa SDL_GetRelativeMouseMode()
+ * \sa SDL_GetRelativeMouseMode
  */
 extern DECLSPEC int SDLCALL SDL_SetRelativeMouseMode(SDL_bool enabled);
 
 /**
- *  \brief Capture the mouse, to track input outside an SDL window.
+ * Capture the mouse and to track input outside an SDL window.
+ *
+ * Capturing enables your app to obtain mouse events globally, instead of just
+ * within your window. Not all video targets support this function. When
+ * capturing is enabled, the current window will get all mouse events, but
+ * unlike relative mode, no change is made to the cursor and it is not
+ * restrained to your window.
+ *
+ * This function may also deny mouse input to other windows--both those in
+ * your application and others on the system--so you should use this function
+ * sparingly, and in small bursts. For example, you might want to track the
+ * mouse while the user is dragging something, until the user releases a mouse
+ * button. It is not recommended that you capture the mouse for long periods
+ * of time, such as the entire time your app is running. For that, you should
+ * probably use SDL_SetRelativeMouseMode() or SDL_SetWindowGrab(), depending
+ * on your goals.
  *
- *  \param enabled Whether or not to enable capturing
+ * While captured, mouse events still report coordinates relative to the
+ * current (foreground) window, but those coordinates may be outside the
+ * bounds of the window (including negative values). Capturing is only allowed
+ * for the foreground window. If the window loses focus while capturing, the
+ * capture will be disabled automatically.
  *
- *  Capturing enables your app to obtain mouse events globally, instead of
- *  just within your window. Not all video targets support this function.
- *  When capturing is enabled, the current window will get all mouse events,
- *  but unlike relative mode, no change is made to the cursor and it is
- *  not restrained to your window.
+ * While capturing is enabled, the current window will have the
+ * `SDL_WINDOW_MOUSE_CAPTURE` flag set.
  *
- *  This function may also deny mouse input to other windows--both those in
- *  your application and others on the system--so you should use this
- *  function sparingly, and in small bursts. For example, you might want to
- *  track the mouse while the user is dragging something, until the user
- *  releases a mouse button. It is not recommended that you capture the mouse
- *  for long periods of time, such as the entire time your app is running.
+ * Please note that as of SDL 2.0.22, SDL will attempt to "auto capture" the
+ * mouse while the user is pressing a button; this is to try and make mouse
+ * behavior more consistent between platforms, and deal with the common case
+ * of a user dragging the mouse outside of the window. This means that if you
+ * are calling SDL_CaptureMouse() only to deal with this situation, you no
+ * longer have to (although it is safe to do so). If this causes problems for
+ * your app, you can disable auto capture by setting the
+ * `SDL_HINT_MOUSE_AUTO_CAPTURE` hint to zero.
  *
- *  While captured, mouse events still report coordinates relative to the
- *  current (foreground) window, but those coordinates may be outside the
- *  bounds of the window (including negative values). Capturing is only
- *  allowed for the foreground window. If the window loses focus while
- *  capturing, the capture will be disabled automatically.
+ * \param enabled SDL_TRUE to enable capturing, SDL_FALSE to disable.
+ * \returns 0 on success or -1 if not supported; call SDL_GetError() for more
+ *          information.
  *
- *  While capturing is enabled, the current window will have the
- *  SDL_WINDOW_MOUSE_CAPTURE flag set.
+ * \since This function is available since SDL 2.0.4.
  *
- *  \return 0 on success, or -1 if not supported.
+ * \sa SDL_GetGlobalMouseState
  */
 extern DECLSPEC int SDLCALL SDL_CaptureMouse(SDL_bool enabled);
 
 /**
- *  \brief Query whether relative mouse mode is enabled.
+ * Query whether relative mouse mode is enabled.
  *
- *  \sa SDL_SetRelativeMouseMode()
+ * \returns SDL_TRUE if relative mode is enabled or SDL_FALSE otherwise.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_SetRelativeMouseMode
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_GetRelativeMouseMode(void);
 
 /**
- *  \brief Create a cursor, using the specified bitmap data and
- *         mask (in MSB format).
- *
- *  The cursor width must be a multiple of 8 bits.
- *
- *  The cursor is created in black and white according to the following:
- *  <table>
- *  <tr><td> data </td><td> mask </td><td> resulting pixel on screen </td></tr>
- *  <tr><td>  0   </td><td>  1   </td><td> White </td></tr>
- *  <tr><td>  1   </td><td>  1   </td><td> Black </td></tr>
- *  <tr><td>  0   </td><td>  0   </td><td> Transparent </td></tr>
- *  <tr><td>  1   </td><td>  0   </td><td> Inverted color if possible, black
- *                                         if not. </td></tr>
- *  </table>
- *
- *  \sa SDL_FreeCursor()
+ * Create a cursor using the specified bitmap data and mask (in MSB format).
+ *
+ * `mask` has to be in MSB (Most Significant Bit) format.
+ *
+ * The cursor width (`w`) must be a multiple of 8 bits.
+ *
+ * The cursor is created in black and white according to the following:
+ *
+ * - data=0, mask=1: white
+ * - data=1, mask=1: black
+ * - data=0, mask=0: transparent
+ * - data=1, mask=0: inverted color if possible, black if not.
+ *
+ * Cursors created with this function must be freed with SDL_FreeCursor().
+ *
+ * If you want to have a color cursor, or create your cursor from an
+ * SDL_Surface, you should use SDL_CreateColorCursor(). Alternately, you can
+ * hide the cursor and draw your own as part of your game's rendering, but it
+ * will be bound to the framerate.
+ *
+ * Also, since SDL 2.0.0, SDL_CreateSystemCursor() is available, which
+ * provides twelve readily available system cursors to pick from.
+ *
+ * \param data the color value for each pixel of the cursor
+ * \param mask the mask value for each pixel of the cursor
+ * \param w the width of the cursor
+ * \param h the height of the cursor
+ * \param hot_x the X-axis location of the upper left corner of the cursor
+ *              relative to the actual mouse position
+ * \param hot_y the Y-axis location of the upper left corner of the cursor
+ *              relative to the actual mouse position
+ * \returns a new cursor with the specified parameters on success or NULL on
+ *          failure; call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_FreeCursor
+ * \sa SDL_SetCursor
+ * \sa SDL_ShowCursor
  */
 extern DECLSPEC SDL_Cursor *SDLCALL SDL_CreateCursor(const Uint8 * data,
                                                      const Uint8 * mask,
@@ -223,60 +320,126 @@ extern DECLSPEC SDL_Cursor *SDLCALL SDL_CreateCursor(const Uint8 * data,
                                                      int hot_y);
 
 /**
- *  \brief Create a color cursor.
+ * Create a color cursor.
+ *
+ * \param surface an SDL_Surface structure representing the cursor image
+ * \param hot_x the x position of the cursor hot spot
+ * \param hot_y the y position of the cursor hot spot
+ * \returns the new cursor on success or NULL on failure; call SDL_GetError()
+ *          for more information.
  *
- *  \sa SDL_FreeCursor()
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_CreateCursor
+ * \sa SDL_FreeCursor
  */
 extern DECLSPEC SDL_Cursor *SDLCALL SDL_CreateColorCursor(SDL_Surface *surface,
                                                           int hot_x,
                                                           int hot_y);
 
 /**
- *  \brief Create a system cursor.
+ * Create a system cursor.
+ *
+ * \param id an SDL_SystemCursor enum value
+ * \returns a cursor on success or NULL on failure; call SDL_GetError() for
+ *          more information.
  *
- *  \sa SDL_FreeCursor()
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_FreeCursor
  */
 extern DECLSPEC SDL_Cursor *SDLCALL SDL_CreateSystemCursor(SDL_SystemCursor id);
 
 /**
- *  \brief Set the active cursor.
+ * Set the active cursor.
+ *
+ * This function sets the currently active cursor to the specified one. If the
+ * cursor is currently visible, the change will be immediately represented on
+ * the display. SDL_SetCursor(NULL) can be used to force cursor redraw, if
+ * this is desired for any reason.
+ *
+ * \param cursor a cursor to make active
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_CreateCursor
+ * \sa SDL_GetCursor
+ * \sa SDL_ShowCursor
  */
 extern DECLSPEC void SDLCALL SDL_SetCursor(SDL_Cursor * cursor);
 
 /**
- *  \brief Return the active cursor.
+ * Get the active cursor.
+ *
+ * This function returns a pointer to the current cursor which is owned by the
+ * library. It is not necessary to free the cursor with SDL_FreeCursor().
+ *
+ * \returns the active cursor or NULL if there is no mouse.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_SetCursor
  */
 extern DECLSPEC SDL_Cursor *SDLCALL SDL_GetCursor(void);
 
 /**
- *  \brief Return the default cursor.
+ * Get the default cursor.
+ *
+ * You do not have to call SDL_FreeCursor() on the return value, but it is
+ * safe to do so.
+ *
+ * \returns the default cursor on success or NULL on failure.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_CreateSystemCursor
  */
 extern DECLSPEC SDL_Cursor *SDLCALL SDL_GetDefaultCursor(void);
 
 /**
- *  \brief Frees a cursor created with SDL_CreateCursor() or similar functions.
+ * Free a previously-created cursor.
+ *
+ * Use this function to free cursor resources created with SDL_CreateCursor(),
+ * SDL_CreateColorCursor() or SDL_CreateSystemCursor().
  *
- *  \sa SDL_CreateCursor()
- *  \sa SDL_CreateColorCursor()
- *  \sa SDL_CreateSystemCursor()
+ * \param cursor the cursor to free
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_CreateColorCursor
+ * \sa SDL_CreateCursor
+ * \sa SDL_CreateSystemCursor
  */
 extern DECLSPEC void SDLCALL SDL_FreeCursor(SDL_Cursor * cursor);
 
 /**
- *  \brief Toggle whether or not the cursor is shown.
+ * Toggle whether or not the cursor is shown.
+ *
+ * The cursor starts off displayed but can be turned off. Passing `SDL_ENABLE`
+ * displays the cursor and passing `SDL_DISABLE` hides it.
+ *
+ * The current state of the mouse cursor can be queried by passing
+ * `SDL_QUERY`; either `SDL_DISABLE` or `SDL_ENABLE` will be returned.
  *
- *  \param toggle 1 to show the cursor, 0 to hide it, -1 to query the current
- *                state.
+ * \param toggle `SDL_ENABLE` to show the cursor, `SDL_DISABLE` to hide it,
+ *               `SDL_QUERY` to query the current state without changing it.
+ * \returns `SDL_ENABLE` if the cursor is shown, or `SDL_DISABLE` if the
+ *          cursor is hidden, or a negative error code on failure; call
+ *          SDL_GetError() for more information.
  *
- *  \return 1 if the cursor is shown, or 0 if the cursor is hidden.
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_CreateCursor
+ * \sa SDL_SetCursor
  */
 extern DECLSPEC int SDLCALL SDL_ShowCursor(int toggle);
 
 /**
- *  Used as a mask when testing buttons in buttonstate.
- *   - Button 1:  Left mouse button
- *   - Button 2:  Middle mouse button
- *   - Button 3:  Right mouse button
+ * Used as a mask when testing buttons in buttonstate.
+ *
+ * - Button 1:  Left mouse button
+ * - Button 2:  Middle mouse button
+ * - Button 3:  Right mouse button
  */
 #define SDL_BUTTON(X)       (1 << ((X)-1))
 #define SDL_BUTTON_LEFT     1
@@ -290,7 +453,6 @@ extern DECLSPEC int SDLCALL SDL_ShowCursor(int toggle);
 #define SDL_BUTTON_X1MASK   SDL_BUTTON(SDL_BUTTON_X1)
 #define SDL_BUTTON_X2MASK   SDL_BUTTON(SDL_BUTTON_X2)
 
-
 /* Ends C function definitions when using C++ */
 #ifdef __cplusplus
 }