Revert "Update Windows 32 bit SDL build dependency to 2.0.10"

[xonotic/xonotic.git] / misc / builddeps / win32 / sdl / include / SDL2 / SDL_haptic.h

diff --git a/misc/builddeps/win32/sdl/include/SDL2/SDL_haptic.h b/misc/builddeps/win32/sdl/include/SDL2/SDL_haptic.h
index 9421c8f17752d038fbf04b5903072517159f7050..0756276856851d34a9dc26cf914a2061564d1e3a 100644 (file)
--- a/misc/builddeps/win32/sdl/include/SDL2/SDL_haptic.h
+++ b/misc/builddeps/win32/sdl/include/SDL2/SDL_haptic.h
@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
 /*
   Simple DirectMedia Layer

-  Copyright (C) 1997-2016 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2019 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
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages


@@ -22,12 +22,12 @@
 /**
  *  \file SDL_haptic.h
  *
 /**
  *  \file SDL_haptic.h
  *

- *  \brief The SDL Haptic subsystem allows you to control haptic (force feedback)
+ *  \brief The SDL haptic subsystem allows you to control haptic (force feedback)

  *         devices.
  *
  *  The basic usage is as follows:
  *         devices.
  *
  *  The basic usage is as follows:

- *   - Initialize the Subsystem (::SDL_INIT_HAPTIC).
- *   - Open a Haptic Device.
+ *   - Initialize the subsystem (::SDL_INIT_HAPTIC).
+ *   - Open a haptic device.

  *    - SDL_HapticOpen() to open from index.
  *    - SDL_HapticOpenFromJoystick() to open from an existing joystick.
  *   - Create an effect (::SDL_HapticEffect).
  *    - SDL_HapticOpen() to open from index.
  *    - SDL_HapticOpenFromJoystick() to open from an existing joystick.
  *   - Create an effect (::SDL_HapticEffect).


@@ -104,8 +104,8 @@
  * \endcode
  */
 
  * \endcode
  */
 

-#ifndef _SDL_haptic_h
-#define _SDL_haptic_h
+#ifndef SDL_haptic_h_
+#define SDL_haptic_h_

 
 #include "SDL_stdinc.h"
 #include "SDL_error.h"
 
 #include "SDL_stdinc.h"
 #include "SDL_error.h"


@@ -117,6 +117,17 @@
 extern "C" {
 #endif /* __cplusplus */
 
 extern "C" {
 #endif /* __cplusplus */
 

+/* FIXME: For SDL 2.1, adjust all the magnitude variables to be Uint16 (0xFFFF).
+ *
+ * At the moment the magnitude variables are mixed between signed/unsigned, and
+ * it is also not made clear that ALL of those variables expect a max of 0x7FFF.
+ *
+ * Some platforms may have higher precision than that (Linux FF, Windows XInput)
+ * so we should fix the inconsistency in favor of higher possible precision,
+ * adjusting for platforms that use different scales.
+ * -flibit
+ */
+

 /**
  *  \typedef SDL_Haptic
  *
 /**
  *  \typedef SDL_Haptic
  *


@@ -282,7 +293,7 @@ typedef struct _SDL_Haptic SDL_Haptic;
 /**
  *  \brief Device can be queried for effect status.
  *
 /**
  *  \brief Device can be queried for effect status.
  *

- *  Device can be queried for effect status.
+ *  Device supports querying effect status.

  *
  *  \sa SDL_HapticGetEffectStatus
  */
  *
  *  \sa SDL_HapticGetEffectStatus
  */


@@ -291,6 +302,8 @@ typedef struct _SDL_Haptic SDL_Haptic;
 /**
  *  \brief Device can be paused.
  *
 /**
  *  \brief Device can be paused.
  *

+ *  Devices supports being paused.
+ *

  *  \sa SDL_HapticPause
  *  \sa SDL_HapticUnpause
  */
  *  \sa SDL_HapticPause
  *  \sa SDL_HapticUnpause
  */


@@ -444,7 +457,7 @@ typedef struct SDL_HapticDirection
 /**
  *  \brief A structure containing a template for a Constant effect.
  *
 /**
  *  \brief A structure containing a template for a Constant effect.
  *

- *  The struct is exclusive to the ::SDL_HAPTIC_CONSTANT effect.
+ *  This struct is exclusively for the ::SDL_HAPTIC_CONSTANT effect.

  *
  *  A constant effect applies a constant force in the specified direction
  *  to the joystick.
  *
  *  A constant effect applies a constant force in the specified direction
  *  to the joystick.


@@ -654,8 +667,8 @@ typedef struct SDL_HapticRamp
  * This struct is exclusively for the ::SDL_HAPTIC_LEFTRIGHT effect.
  *
  * The Left/Right effect is used to explicitly control the large and small
  * This struct is exclusively for the ::SDL_HAPTIC_LEFTRIGHT effect.
  *
  * The Left/Right effect is used to explicitly control the large and small

- * motors, commonly found in modern game controllers. One motor is high
- * frequency, the other is low frequency.
+ * motors, commonly found in modern game controllers. The small (right) motor
+ * is high frequency, and the large (left) motor is low frequency.

  *
  * \sa SDL_HAPTIC_LEFTRIGHT
  * \sa SDL_HapticEffect
  *
  * \sa SDL_HAPTIC_LEFTRIGHT
  * \sa SDL_HapticEffect


@@ -666,7 +679,7 @@ typedef struct SDL_HapticLeftRight
     Uint16 type;            /**< ::SDL_HAPTIC_LEFTRIGHT */
 
     /* Replay */
     Uint16 type;            /**< ::SDL_HAPTIC_LEFTRIGHT */
 
     /* Replay */

-    Uint32 length;          /**< Duration of the effect. */
+    Uint32 length;          /**< Duration of the effect in milliseconds. */

 
     /* Rumble */
     Uint16 large_magnitude; /**< Control of the large controller motor. */
 
     /* Rumble */
     Uint16 large_magnitude; /**< Control of the large controller motor. */


@@ -676,6 +689,8 @@ typedef struct SDL_HapticLeftRight
 /**
  *  \brief A structure containing a template for the ::SDL_HAPTIC_CUSTOM effect.
  *
 /**
  *  \brief A structure containing a template for the ::SDL_HAPTIC_CUSTOM effect.
  *

+ *  This struct is exclusively for the ::SDL_HAPTIC_CUSTOM effect.
+ *

  *  A custom force feedback effect is much like a periodic effect, where the
  *  application can define its exact shape.  You will have to allocate the
  *  data yourself.  Data should consist of channels * samples Uint16 samples.
  *  A custom force feedback effect is much like a periodic effect, where the
  *  application can define its exact shape.  You will have to allocate the
  *  data yourself.  Data should consist of channels * samples Uint16 samples.


@@ -804,7 +819,7 @@ typedef union SDL_HapticEffect
 extern DECLSPEC int SDLCALL SDL_NumHaptics(void);
 
 /**
 extern DECLSPEC int SDLCALL SDL_NumHaptics(void);
 
 /**

- *  \brief Get the implementation dependent name of a Haptic device.
+ *  \brief 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.


@@ -817,9 +832,9 @@ extern DECLSPEC int SDLCALL SDL_NumHaptics(void);
 extern DECLSPEC const char *SDLCALL SDL_HapticName(int device_index);
 
 /**
 extern DECLSPEC const char *SDLCALL SDL_HapticName(int device_index);
 
 /**

- *  \brief Opens a Haptic device for usage.
+ *  \brief Opens a haptic device for use.

  *
  *

- *  The index passed as an argument refers to the N'th Haptic device on this
+ *  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
  *  system.
  *
  *  When opening a haptic device, its gain will be set to maximum and


@@ -885,15 +900,15 @@ extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromMouse(void);
  *  \brief Checks to see if a joystick has haptic features.
  *
  *  \param joystick Joystick to test for haptic capabilities.
  *  \brief Checks to see if a joystick has haptic features.
  *
  *  \param joystick Joystick to test for haptic capabilities.

- *  \return 1 if the joystick is haptic, 0 if it isn't
- *          or -1 if an error ocurred.
+ *  \return SDL_TRUE if the joystick is haptic, SDL_FALSE if it isn't
+ *          or -1 if an error occurred.

  *
  *  \sa SDL_HapticOpenFromJoystick
  */
 extern DECLSPEC int SDLCALL SDL_JoystickIsHaptic(SDL_Joystick * joystick);
 
 /**
  *
  *  \sa SDL_HapticOpenFromJoystick
  */
 extern DECLSPEC int SDLCALL SDL_JoystickIsHaptic(SDL_Joystick * joystick);
 
 /**

- *  \brief Opens a Haptic device for usage from a Joystick device.
+ *  \brief Opens 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.


@@ -913,7 +928,7 @@ extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromJoystick(SDL_Joystick *
                                                                joystick);
 
 /**
                                                                joystick);
 
 /**

- *  \brief Closes a Haptic device previously opened with SDL_HapticOpen().
+ *  \brief Closes a haptic device previously opened with SDL_HapticOpen().

  *
  *  \param haptic Haptic device to close.
  */
  *
  *  \param haptic Haptic device to close.
  */


@@ -957,7 +972,7 @@ extern DECLSPEC int SDLCALL SDL_HapticNumEffectsPlaying(SDL_Haptic * haptic);
  *  Example:
  *  \code
  *  if (SDL_HapticQuery(haptic) & SDL_HAPTIC_CONSTANT) {
  *  Example:
  *  \code
  *  if (SDL_HapticQuery(haptic) & SDL_HAPTIC_CONSTANT) {

- *      printf("We have constant haptic effect!");
+ *      printf("We have constant haptic effect!\n");

  *  }
  *  \endcode
  *
  *  }
  *  \endcode
  *


@@ -996,7 +1011,7 @@ extern DECLSPEC int SDLCALL SDL_HapticEffectSupported(SDL_Haptic * haptic,
  *
  *  \param haptic Haptic device to create the effect on.
  *  \param effect Properties of the effect to create.
  *
  *  \param haptic Haptic device to create the effect on.
  *  \param effect Properties of the effect to create.

- *  \return The id of the effect on success or -1 on error.
+ *  \return The identifier of the effect on success or -1 on error.

  *
  *  \sa SDL_HapticUpdateEffect
  *  \sa SDL_HapticRunEffect
  *
  *  \sa SDL_HapticUpdateEffect
  *  \sa SDL_HapticRunEffect


@@ -1008,13 +1023,13 @@ extern DECLSPEC int SDLCALL SDL_HapticNewEffect(SDL_Haptic * haptic,
 /**
  *  \brief Updates the properties of an effect.
  *
 /**
  *  \brief Updates the properties of an effect.
  *

- *  Can be used dynamically, although behaviour when dynamically changing
+ *  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().
  *
  *  \param haptic Haptic device that has the effect.
  *  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().
  *
  *  \param haptic Haptic device that has the effect.

- *  \param effect Effect to update.
+ *  \param effect Identifier of the effect to update.

  *  \param data New effect properties to use.
  *  \return 0 on success or -1 on error.
  *
  *  \param data New effect properties to use.
  *  \return 0 on success or -1 on error.
  *


@@ -1218,6 +1233,6 @@ extern DECLSPEC int SDLCALL SDL_HapticRumbleStop(SDL_Haptic * haptic);
 #endif
 #include "close_code.h"
 
 #endif
 #include "close_code.h"
 

-#endif /* _SDL_haptic_h */
+#endif /* SDL_haptic_h_ */

 
 /* vi: set ts=4 sw=4 expandtab: */
 
 /* vi: set ts=4 sw=4 expandtab: */