include/SDL_haptic.h
changeset 5360 220d3af9121f
parent 5126 ad4141d88412
child 5535 96594ac5fd1a
     1.1 --- a/include/SDL_haptic.h	Sun Feb 20 10:42:51 2011 -0800
     1.2 +++ b/include/SDL_haptic.h	Sun Feb 20 10:54:44 2011 -0800
     1.3 @@ -25,7 +25,7 @@
     1.4   *  
     1.5   *  \brief The SDL Haptic subsystem allows you to control haptic (force feedback)
     1.6   *         devices.
     1.7 - *  
     1.8 + * 
     1.9   *  The basic usage is as follows:
    1.10   *   - Initialize the Subsystem (::SDL_INIT_HAPTIC).
    1.11   *   - Open a Haptic Device.
    1.12 @@ -37,7 +37,29 @@
    1.13   *   - (optional) Free the effect with SDL_HapticDestroyEffect().
    1.14   *   - Close the haptic device with SDL_HapticClose().
    1.15   *
    1.16 - * \par Example:
    1.17 + * \par Simple rumble example:
    1.18 + * \code
    1.19 + *    SDL_Haptic *haptic;
    1.20 + *
    1.21 + *    // Open the device
    1.22 + *    haptic = SDL_HapticOpen( 0 );
    1.23 + *    if (haptic == NULL)
    1.24 + *       return -1;
    1.25 + *
    1.26 + *    // Initialize simple rumble
    1.27 + *    if (SDL_HapticRumbleInit( haptic ) != 0)
    1.28 + *       return -1;
    1.29 + *
    1.30 + *    // Play effect at 50% strength for 2 seconds
    1.31 + *    if (SDL_HapticRumblePlay( haptic, 0.5, 2000 ) != 0)
    1.32 + *       return -1;
    1.33 + *    SDL_Delay( 2000 );
    1.34 + *
    1.35 + *    // Clean up
    1.36 + *    SDL_HapticClose( haptic );
    1.37 + * \endcode
    1.38 + *
    1.39 + * \par Complete example:
    1.40   * \code
    1.41   * int test_haptic( SDL_Joystick * joystick ) {
    1.42   *    SDL_Haptic *haptic;
    1.43 @@ -933,7 +955,7 @@
    1.44   *  
    1.45   *  \param haptic Haptic device to check on.
    1.46   *  \param effect Effect to check to see if it is supported.
    1.47 - *  \return 1 if effect is supported, 0 if it isn't or -1 on error.
    1.48 + *  \return SDL_TRUE if effect is supported, SDL_FALSE if it isn't or -1 on error.
    1.49   *  
    1.50   *  \sa SDL_HapticQuery
    1.51   *  \sa SDL_HapticNewEffect
    1.52 @@ -1113,6 +1135,58 @@
    1.53   */
    1.54  extern DECLSPEC int SDLCALL SDL_HapticStopAll(SDL_Haptic * haptic);
    1.55  
    1.56 +/**
    1.57 + *  \brief Checks to see if rumble is supported on a haptic device..
    1.58 + *
    1.59 + *  \param haptic Haptic device to check to see if it supports rumble.
    1.60 + *  \return SDL_TRUE if effect is supported, SDL_FALSE if it isn't or -1 on error.
    1.61 + *
    1.62 + *  \sa SDL_HapticRumbleInit
    1.63 + *  \sa SDL_HapticRumblePlay
    1.64 + *  \sa SDL_HapticRumbleStop
    1.65 + */
    1.66 +extern DECLSPEC int SDLCALL SDL_HapticRumbleSupported(SDL_Haptic * haptic);
    1.67 +
    1.68 +/**
    1.69 + *  \brief Initializes the haptic device for simple rumble playback.
    1.70 + *
    1.71 + *  \param haptic Haptic device to initialize for simple rumble playback.
    1.72 + *  \return 0 on success or -1 on error.
    1.73 + *
    1.74 + *  \sa SDL_HapticOpen
    1.75 + *  \sa SDL_HapticRumbleSupported
    1.76 + *  \sa SDL_HapticRumblePlay
    1.77 + *  \sa SDL_HapticRumbleStop
    1.78 + */
    1.79 +extern DECLSPEC int SDLCALL SDL_HapticRumbleInit(SDL_Haptic * haptic);
    1.80 +
    1.81 +/**
    1.82 + *  \brief Runs simple rumble on a haptic device
    1.83 + *
    1.84 + *  \param haptic Haptic device to play rumble effect on.
    1.85 + *  \param strength Strength of the rumble to play as a 0-1 float value.
    1.86 + *  \param length Length of the rumble to play in miliseconds.
    1.87 + *  \return 0 on success or -1 on error.
    1.88 + *
    1.89 + *  \sa SDL_HapticRumbleSupported
    1.90 + *  \sa SDL_HapticRumbleInit
    1.91 + *  \sa SDL_HapticRumbleStop
    1.92 + */
    1.93 +extern DECLSPEC int SDLCALL SDL_HapticRumblePlay(SDL_Haptic * haptic, float strength, Uint32 length );
    1.94 +
    1.95 +/**
    1.96 + *  \brief Stops the simple rumble on a haptic device.
    1.97 + *
    1.98 + *  \param haptic Haptic to stop the rumble on.
    1.99 + *  \return 0 on success or -1 on error.
   1.100 + *
   1.101 + *  \sa SDL_HapticRumbleSupported
   1.102 + *  \sa SDL_HapticRumbleInit
   1.103 + *  \sa SDL_HapticRumblePlay
   1.104 + */
   1.105 +extern DECLSPEC int SDLCALL SDL_HapticRumbleStop(SDL_Haptic * haptic);
   1.106 +
   1.107 +
   1.108  
   1.109  /* Ends C function definitions when using C++ */
   1.110  #ifdef __cplusplus