include/SDL_haptic.h
changeset 5360 220d3af9121f
parent 5126 ad4141d88412
child 5535 96594ac5fd1a
equal deleted inserted replaced
5359:d5fe4ed3a28d 5360:220d3af9121f
    23 /**
    23 /**
    24  *  \file SDL_haptic.h
    24  *  \file SDL_haptic.h
    25  *  
    25  *  
    26  *  \brief The SDL Haptic subsystem allows you to control haptic (force feedback)
    26  *  \brief The SDL Haptic subsystem allows you to control haptic (force feedback)
    27  *         devices.
    27  *         devices.
    28  *  
    28  * 
    29  *  The basic usage is as follows:
    29  *  The basic usage is as follows:
    30  *   - Initialize the Subsystem (::SDL_INIT_HAPTIC).
    30  *   - Initialize the Subsystem (::SDL_INIT_HAPTIC).
    31  *   - Open a Haptic Device.
    31  *   - Open a Haptic Device.
    32  *    - SDL_HapticOpen() to open from index.
    32  *    - SDL_HapticOpen() to open from index.
    33  *    - SDL_HapticOpenFromJoystick() to open from an existing joystick.
    33  *    - SDL_HapticOpenFromJoystick() to open from an existing joystick.
    35  *   - Upload the effect with SDL_HapticNewEffect().
    35  *   - Upload the effect with SDL_HapticNewEffect().
    36  *   - Run the effect with SDL_HapticRunEffect().
    36  *   - Run the effect with SDL_HapticRunEffect().
    37  *   - (optional) Free the effect with SDL_HapticDestroyEffect().
    37  *   - (optional) Free the effect with SDL_HapticDestroyEffect().
    38  *   - Close the haptic device with SDL_HapticClose().
    38  *   - Close the haptic device with SDL_HapticClose().
    39  *
    39  *
    40  * \par Example:
    40  * \par Simple rumble example:
       
    41  * \code
       
    42  *    SDL_Haptic *haptic;
       
    43  *
       
    44  *    // Open the device
       
    45  *    haptic = SDL_HapticOpen( 0 );
       
    46  *    if (haptic == NULL)
       
    47  *       return -1;
       
    48  *
       
    49  *    // Initialize simple rumble
       
    50  *    if (SDL_HapticRumbleInit( haptic ) != 0)
       
    51  *       return -1;
       
    52  *
       
    53  *    // Play effect at 50% strength for 2 seconds
       
    54  *    if (SDL_HapticRumblePlay( haptic, 0.5, 2000 ) != 0)
       
    55  *       return -1;
       
    56  *    SDL_Delay( 2000 );
       
    57  *
       
    58  *    // Clean up
       
    59  *    SDL_HapticClose( haptic );
       
    60  * \endcode
       
    61  *
       
    62  * \par Complete example:
    41  * \code
    63  * \code
    42  * int test_haptic( SDL_Joystick * joystick ) {
    64  * int test_haptic( SDL_Joystick * joystick ) {
    43  *    SDL_Haptic *haptic;
    65  *    SDL_Haptic *haptic;
    44  *    SDL_HapticEffect effect;
    66  *    SDL_HapticEffect effect;
    45  *    int effect_id;
    67  *    int effect_id;
   931 /**
   953 /**
   932  *  \brief Checks to see if effect is supported by haptic.
   954  *  \brief Checks to see if effect is supported by haptic.
   933  *  
   955  *  
   934  *  \param haptic Haptic device to check on.
   956  *  \param haptic Haptic device to check on.
   935  *  \param effect Effect to check to see if it is supported.
   957  *  \param effect Effect to check to see if it is supported.
   936  *  \return 1 if effect is supported, 0 if it isn't or -1 on error.
   958  *  \return SDL_TRUE if effect is supported, SDL_FALSE if it isn't or -1 on error.
   937  *  
   959  *  
   938  *  \sa SDL_HapticQuery
   960  *  \sa SDL_HapticQuery
   939  *  \sa SDL_HapticNewEffect
   961  *  \sa SDL_HapticNewEffect
   940  */
   962  */
   941 extern DECLSPEC int SDLCALL SDL_HapticEffectSupported(SDL_Haptic * haptic,
   963 extern DECLSPEC int SDLCALL SDL_HapticEffectSupported(SDL_Haptic * haptic,
  1110  *  
  1132  *  
  1111  *  \param haptic Haptic device to stop.
  1133  *  \param haptic Haptic device to stop.
  1112  *  \return 0 on success or -1 on error.
  1134  *  \return 0 on success or -1 on error.
  1113  */
  1135  */
  1114 extern DECLSPEC int SDLCALL SDL_HapticStopAll(SDL_Haptic * haptic);
  1136 extern DECLSPEC int SDLCALL SDL_HapticStopAll(SDL_Haptic * haptic);
       
  1137 
       
  1138 /**
       
  1139  *  \brief Checks to see if rumble is supported on a haptic device..
       
  1140  *
       
  1141  *  \param haptic Haptic device to check to see if it supports rumble.
       
  1142  *  \return SDL_TRUE if effect is supported, SDL_FALSE if it isn't or -1 on error.
       
  1143  *
       
  1144  *  \sa SDL_HapticRumbleInit
       
  1145  *  \sa SDL_HapticRumblePlay
       
  1146  *  \sa SDL_HapticRumbleStop
       
  1147  */
       
  1148 extern DECLSPEC int SDLCALL SDL_HapticRumbleSupported(SDL_Haptic * haptic);
       
  1149 
       
  1150 /**
       
  1151  *  \brief Initializes the haptic device for simple rumble playback.
       
  1152  *
       
  1153  *  \param haptic Haptic device to initialize for simple rumble playback.
       
  1154  *  \return 0 on success or -1 on error.
       
  1155  *
       
  1156  *  \sa SDL_HapticOpen
       
  1157  *  \sa SDL_HapticRumbleSupported
       
  1158  *  \sa SDL_HapticRumblePlay
       
  1159  *  \sa SDL_HapticRumbleStop
       
  1160  */
       
  1161 extern DECLSPEC int SDLCALL SDL_HapticRumbleInit(SDL_Haptic * haptic);
       
  1162 
       
  1163 /**
       
  1164  *  \brief Runs simple rumble on a haptic device
       
  1165  *
       
  1166  *  \param haptic Haptic device to play rumble effect on.
       
  1167  *  \param strength Strength of the rumble to play as a 0-1 float value.
       
  1168  *  \param length Length of the rumble to play in miliseconds.
       
  1169  *  \return 0 on success or -1 on error.
       
  1170  *
       
  1171  *  \sa SDL_HapticRumbleSupported
       
  1172  *  \sa SDL_HapticRumbleInit
       
  1173  *  \sa SDL_HapticRumbleStop
       
  1174  */
       
  1175 extern DECLSPEC int SDLCALL SDL_HapticRumblePlay(SDL_Haptic * haptic, float strength, Uint32 length );
       
  1176 
       
  1177 /**
       
  1178  *  \brief Stops the simple rumble on a haptic device.
       
  1179  *
       
  1180  *  \param haptic Haptic to stop the rumble on.
       
  1181  *  \return 0 on success or -1 on error.
       
  1182  *
       
  1183  *  \sa SDL_HapticRumbleSupported
       
  1184  *  \sa SDL_HapticRumbleInit
       
  1185  *  \sa SDL_HapticRumblePlay
       
  1186  */
       
  1187 extern DECLSPEC int SDLCALL SDL_HapticRumbleStop(SDL_Haptic * haptic);
       
  1188 
  1115 
  1189 
  1116 
  1190 
  1117 /* Ends C function definitions when using C++ */
  1191 /* Ends C function definitions when using C++ */
  1118 #ifdef __cplusplus
  1192 #ifdef __cplusplus
  1119 /* *INDENT-OFF* */
  1193 /* *INDENT-OFF* */