include/SDL_haptic.h
changeset 10956 d9b0b7d337b9
parent 10737 3406a0f8b041
child 11811 5d94cb6b24d3
equal deleted inserted replaced
10955:82bec2d58a45 10956:d9b0b7d337b9
    20 */
    20 */
    21 
    21 
    22 /**
    22 /**
    23  *  \file SDL_haptic.h
    23  *  \file SDL_haptic.h
    24  *
    24  *
    25  *  \brief The SDL Haptic subsystem allows you to control haptic (force feedback)
    25  *  \brief The SDL haptic subsystem allows you to control haptic (force feedback)
    26  *         devices.
    26  *         devices.
    27  *
    27  *
    28  *  The basic usage is as follows:
    28  *  The basic usage is as follows:
    29  *   - Initialize the Subsystem (::SDL_INIT_HAPTIC).
    29  *   - Initialize the subsystem (::SDL_INIT_HAPTIC).
    30  *   - Open a Haptic Device.
    30  *   - Open a haptic device.
    31  *    - SDL_HapticOpen() to open from index.
    31  *    - SDL_HapticOpen() to open from index.
    32  *    - SDL_HapticOpenFromJoystick() to open from an existing joystick.
    32  *    - SDL_HapticOpenFromJoystick() to open from an existing joystick.
    33  *   - Create an effect (::SDL_HapticEffect).
    33  *   - Create an effect (::SDL_HapticEffect).
    34  *   - Upload the effect with SDL_HapticNewEffect().
    34  *   - Upload the effect with SDL_HapticNewEffect().
    35  *   - Run the effect with SDL_HapticRunEffect().
    35  *   - Run the effect with SDL_HapticRunEffect().
   280 #define SDL_HAPTIC_AUTOCENTER (1u<<13)
   280 #define SDL_HAPTIC_AUTOCENTER (1u<<13)
   281 
   281 
   282 /**
   282 /**
   283  *  \brief Device can be queried for effect status.
   283  *  \brief Device can be queried for effect status.
   284  *
   284  *
   285  *  Device can be queried for effect status.
   285  *  Device supports querying effect status.
   286  *
   286  *
   287  *  \sa SDL_HapticGetEffectStatus
   287  *  \sa SDL_HapticGetEffectStatus
   288  */
   288  */
   289 #define SDL_HAPTIC_STATUS     (1u<<14)
   289 #define SDL_HAPTIC_STATUS     (1u<<14)
   290 
   290 
   291 /**
   291 /**
   292  *  \brief Device can be paused.
   292  *  \brief Device can be paused.
       
   293  *
       
   294  *  Devices supports being paused.
   293  *
   295  *
   294  *  \sa SDL_HapticPause
   296  *  \sa SDL_HapticPause
   295  *  \sa SDL_HapticUnpause
   297  *  \sa SDL_HapticUnpause
   296  */
   298  */
   297 #define SDL_HAPTIC_PAUSE      (1u<<15)
   299 #define SDL_HAPTIC_PAUSE      (1u<<15)
   442 
   444 
   443 
   445 
   444 /**
   446 /**
   445  *  \brief A structure containing a template for a Constant effect.
   447  *  \brief A structure containing a template for a Constant effect.
   446  *
   448  *
   447  *  The struct is exclusive to the ::SDL_HAPTIC_CONSTANT effect.
   449  *  This struct is exclusively for the ::SDL_HAPTIC_CONSTANT effect.
   448  *
   450  *
   449  *  A constant effect applies a constant force in the specified direction
   451  *  A constant effect applies a constant force in the specified direction
   450  *  to the joystick.
   452  *  to the joystick.
   451  *
   453  *
   452  *  \sa SDL_HAPTIC_CONSTANT
   454  *  \sa SDL_HAPTIC_CONSTANT
   673     Uint16 small_magnitude; /**< Control of the small controller motor. */
   675     Uint16 small_magnitude; /**< Control of the small controller motor. */
   674 } SDL_HapticLeftRight;
   676 } SDL_HapticLeftRight;
   675 
   677 
   676 /**
   678 /**
   677  *  \brief A structure containing a template for the ::SDL_HAPTIC_CUSTOM effect.
   679  *  \brief A structure containing a template for the ::SDL_HAPTIC_CUSTOM effect.
       
   680  *
       
   681  *  This struct is exclusively for the ::SDL_HAPTIC_CUSTOM effect.
   678  *
   682  *
   679  *  A custom force feedback effect is much like a periodic effect, where the
   683  *  A custom force feedback effect is much like a periodic effect, where the
   680  *  application can define its exact shape.  You will have to allocate the
   684  *  application can define its exact shape.  You will have to allocate the
   681  *  data yourself.  Data should consist of channels * samples Uint16 samples.
   685  *  data yourself.  Data should consist of channels * samples Uint16 samples.
   682  *
   686  *
   802  *  \return Number of haptic devices detected on the system.
   806  *  \return Number of haptic devices detected on the system.
   803  */
   807  */
   804 extern DECLSPEC int SDLCALL SDL_NumHaptics(void);
   808 extern DECLSPEC int SDLCALL SDL_NumHaptics(void);
   805 
   809 
   806 /**
   810 /**
   807  *  \brief Get the implementation dependent name of a Haptic device.
   811  *  \brief Get the implementation dependent name of a haptic device.
   808  *
   812  *
   809  *  This can be called before any joysticks are opened.
   813  *  This can be called before any joysticks are opened.
   810  *  If no name can be found, this function returns NULL.
   814  *  If no name can be found, this function returns NULL.
   811  *
   815  *
   812  *  \param device_index Index of the device to get its name.
   816  *  \param device_index Index of the device to get its name.
   815  *  \sa SDL_NumHaptics
   819  *  \sa SDL_NumHaptics
   816  */
   820  */
   817 extern DECLSPEC const char *SDLCALL SDL_HapticName(int device_index);
   821 extern DECLSPEC const char *SDLCALL SDL_HapticName(int device_index);
   818 
   822 
   819 /**
   823 /**
   820  *  \brief Opens a Haptic device for usage.
   824  *  \brief Opens a haptic device for use.
   821  *
   825  *
   822  *  The index passed as an argument refers to the N'th Haptic device on this
   826  *  The index passed as an argument refers to the N'th haptic device on this
   823  *  system.
   827  *  system.
   824  *
   828  *
   825  *  When opening a haptic device, its gain will be set to maximum and
   829  *  When opening a haptic device, its gain will be set to maximum and
   826  *  autocenter will be disabled.  To modify these values use
   830  *  autocenter will be disabled.  To modify these values use
   827  *  SDL_HapticSetGain() and SDL_HapticSetAutocenter().
   831  *  SDL_HapticSetGain() and SDL_HapticSetAutocenter().
   883 
   887 
   884 /**
   888 /**
   885  *  \brief Checks to see if a joystick has haptic features.
   889  *  \brief Checks to see if a joystick has haptic features.
   886  *
   890  *
   887  *  \param joystick Joystick to test for haptic capabilities.
   891  *  \param joystick Joystick to test for haptic capabilities.
   888  *  \return 1 if the joystick is haptic, 0 if it isn't
   892  *  \return SDL_TRUE if the joystick is haptic, SDL_FALSE if it isn't
   889  *          or -1 if an error ocurred.
   893  *          or -1 if an error occurred.
   890  *
   894  *
   891  *  \sa SDL_HapticOpenFromJoystick
   895  *  \sa SDL_HapticOpenFromJoystick
   892  */
   896  */
   893 extern DECLSPEC int SDLCALL SDL_JoystickIsHaptic(SDL_Joystick * joystick);
   897 extern DECLSPEC int SDLCALL SDL_JoystickIsHaptic(SDL_Joystick * joystick);
   894 
   898 
   895 /**
   899 /**
   896  *  \brief Opens a Haptic device for usage from a Joystick device.
   900  *  \brief Opens a haptic device for use from a joystick device.
   897  *
   901  *
   898  *  You must still close the haptic device separately.  It will not be closed
   902  *  You must still close the haptic device separately.  It will not be closed
   899  *  with the joystick.
   903  *  with the joystick.
   900  *
   904  *
   901  *  When opening from a joystick you should first close the haptic device before
   905  *  When opening from a joystick you should first close the haptic device before
   911  */
   915  */
   912 extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromJoystick(SDL_Joystick *
   916 extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromJoystick(SDL_Joystick *
   913                                                                joystick);
   917                                                                joystick);
   914 
   918 
   915 /**
   919 /**
   916  *  \brief Closes a Haptic device previously opened with SDL_HapticOpen().
   920  *  \brief Closes a haptic device previously opened with SDL_HapticOpen().
   917  *
   921  *
   918  *  \param haptic Haptic device to close.
   922  *  \param haptic Haptic device to close.
   919  */
   923  */
   920 extern DECLSPEC void SDLCALL SDL_HapticClose(SDL_Haptic * haptic);
   924 extern DECLSPEC void SDLCALL SDL_HapticClose(SDL_Haptic * haptic);
   921 
   925 
   955  *  \brief Gets the haptic device's supported features in bitwise manner.
   959  *  \brief Gets the haptic device's supported features in bitwise manner.
   956  *
   960  *
   957  *  Example:
   961  *  Example:
   958  *  \code
   962  *  \code
   959  *  if (SDL_HapticQuery(haptic) & SDL_HAPTIC_CONSTANT) {
   963  *  if (SDL_HapticQuery(haptic) & SDL_HAPTIC_CONSTANT) {
   960  *      printf("We have constant haptic effect!");
   964  *      printf("We have constant haptic effect!\n");
   961  *  }
   965  *  }
   962  *  \endcode
   966  *  \endcode
   963  *
   967  *
   964  *  \param haptic The haptic device to query.
   968  *  \param haptic The haptic device to query.
   965  *  \return Haptic features in bitwise manner (OR'd).
   969  *  \return Haptic features in bitwise manner (OR'd).
   994 /**
   998 /**
   995  *  \brief Creates a new haptic effect on the device.
   999  *  \brief Creates a new haptic effect on the device.
   996  *
  1000  *
   997  *  \param haptic Haptic device to create the effect on.
  1001  *  \param haptic Haptic device to create the effect on.
   998  *  \param effect Properties of the effect to create.
  1002  *  \param effect Properties of the effect to create.
   999  *  \return The id of the effect on success or -1 on error.
  1003  *  \return The identifier of the effect on success or -1 on error.
  1000  *
  1004  *
  1001  *  \sa SDL_HapticUpdateEffect
  1005  *  \sa SDL_HapticUpdateEffect
  1002  *  \sa SDL_HapticRunEffect
  1006  *  \sa SDL_HapticRunEffect
  1003  *  \sa SDL_HapticDestroyEffect
  1007  *  \sa SDL_HapticDestroyEffect
  1004  */
  1008  */
  1006                                                 SDL_HapticEffect * effect);
  1010                                                 SDL_HapticEffect * effect);
  1007 
  1011 
  1008 /**
  1012 /**
  1009  *  \brief Updates the properties of an effect.
  1013  *  \brief Updates the properties of an effect.
  1010  *
  1014  *
  1011  *  Can be used dynamically, although behaviour when dynamically changing
  1015  *  Can be used dynamically, although behavior when dynamically changing
  1012  *  direction may be strange.  Specifically the effect may reupload itself
  1016  *  direction may be strange.  Specifically the effect may reupload itself
  1013  *  and start playing from the start.  You cannot change the type either when
  1017  *  and start playing from the start.  You cannot change the type either when
  1014  *  running SDL_HapticUpdateEffect().
  1018  *  running SDL_HapticUpdateEffect().
  1015  *
  1019  *
  1016  *  \param haptic Haptic device that has the effect.
  1020  *  \param haptic Haptic device that has the effect.
  1017  *  \param effect Effect to update.
  1021  *  \param effect Identifier of the effect to update.
  1018  *  \param data New effect properties to use.
  1022  *  \param data New effect properties to use.
  1019  *  \return 0 on success or -1 on error.
  1023  *  \return 0 on success or -1 on error.
  1020  *
  1024  *
  1021  *  \sa SDL_HapticNewEffect
  1025  *  \sa SDL_HapticNewEffect
  1022  *  \sa SDL_HapticRunEffect
  1026  *  \sa SDL_HapticRunEffect