include/SDL_haptic.h
branchgsoc2008_force_feedback
changeset 2526 2d88b82ce781
parent 2525 1fb3fba13a2c
child 2532 688cad3f6090
     1.1 --- a/include/SDL_haptic.h	Thu Jul 17 16:08:46 2008 +0000
     1.2 +++ b/include/SDL_haptic.h	Fri Jul 18 08:00:16 2008 +0000
     1.3 @@ -434,6 +434,14 @@
     1.4   *  over time.  The type determines the shape of the wave and the parameters
     1.5   *  determine the dimensions of the wave.
     1.6   *
     1.7 + * Phase is given by hundredth of a cyle meaning that giving the phase a value
     1.8 + *  of 9000 will displace it 25% of it's period.  Here are sample values:
     1.9 + *    -     0: No phase displacement.
    1.10 + *    -  9000: Displaced 25% of it's period.
    1.11 + *    - 18000: Displaced 50% of it's period.
    1.12 + *    - 27000: Displaced 75% of it's period.
    1.13 + *    - 36000: Displaced 100% of it's period, same as 0, but 0 is preffered.
    1.14 + *
    1.15   * Examples:
    1.16   * \code
    1.17   * SDL_HAPTIC_SINE
    1.18 @@ -488,7 +496,7 @@
    1.19     Uint16 period; /**< Period of the wave. */
    1.20     Sint16 magnitude; /**< Peak value. */
    1.21     Sint16 offset; /**< Mean value of the wave. */
    1.22 -   Uint16 phase; /**< Horizontal shift. */
    1.23 +   Uint16 phase; /**< Horizontal shift given by hundredth of a cycle. */
    1.24  
    1.25     /* Envelope */
    1.26     Uint16 attack_length; /**< Duration of the attack. */
    1.27 @@ -592,7 +600,7 @@
    1.28   *
    1.29   * You can also pass SDL_HAPTIC_INFINITY to length instead of a 0-32767 value.
    1.30   *  Neither delay, interval, attack_length nor fade_length support 
    1.31 - *  SDL_HAPTIC_INFINITY.
    1.32 + *  SDL_HAPTIC_INFINITY.  Fade will also not be used since effect never ends.
    1.33   *
    1.34   * Common parts:
    1.35   * \code
    1.36 @@ -875,10 +883,12 @@
    1.37  /**
    1.38   * \fn int SDL_HapticUpdateEffect(SDL_Haptic * haptic, int effect, SDL_HapticEffect * data)
    1.39   *
    1.40 - * \brief Updates an effect.  Can be used dynamically, although behaviour when
    1.41 - * dynamically changing direction may be strange.  Specifically the effect
    1.42 - * may reupload itself and start playing from the start.  You cannot change
    1.43 - * the type either when running UpdateEffect.
    1.44 + * \brief Updates the properties of an effect.
    1.45 + *
    1.46 + * Can be used dynamically, although behaviour when dynamically changing
    1.47 + * direction may be strange.  Specifically the effect may reupload itself
    1.48 + * and start playing from the start.  You cannot change the type either when
    1.49 + * running UpdateEffect.
    1.50   *
    1.51   *    \param haptic Haptic device that has the effect.
    1.52   *    \param effect Effect to update.
    1.53 @@ -896,6 +906,11 @@
    1.54   *
    1.55   * \brief Runs the haptic effect on it's assosciated haptic device.
    1.56   *
    1.57 + * If iterations are SDL_HAPTIC_INFINITY, it'll run the effect over and over
    1.58 + *  repeating the envelope (attack and fade) every time.  If you only want the
    1.59 + *  effect to last forever, set SDL_HAPTIC_INFINITY in the effect's length
    1.60 + *  parameter.
    1.61 + *
    1.62   *    \param haptic Haptic device to run the effect on.
    1.63   *    \param effect Identifier of the haptic effect to run.
    1.64   *    \param iterations Number of iterations to run the effect. Use