include/SDL_haptic.h
branchgsoc2008_force_feedback
changeset 2526 2d88b82ce781
parent 2525 1fb3fba13a2c
child 2532 688cad3f6090
equal deleted inserted replaced
2525:1fb3fba13a2c 2526:2d88b82ce781
   432  *
   432  *
   433  * A periodic effect consists in a wave-shaped effect that repeats itself
   433  * A periodic effect consists in a wave-shaped effect that repeats itself
   434  *  over time.  The type determines the shape of the wave and the parameters
   434  *  over time.  The type determines the shape of the wave and the parameters
   435  *  determine the dimensions of the wave.
   435  *  determine the dimensions of the wave.
   436  *
   436  *
       
   437  * Phase is given by hundredth of a cyle meaning that giving the phase a value
       
   438  *  of 9000 will displace it 25% of it's period.  Here are sample values:
       
   439  *    -     0: No phase displacement.
       
   440  *    -  9000: Displaced 25% of it's period.
       
   441  *    - 18000: Displaced 50% of it's period.
       
   442  *    - 27000: Displaced 75% of it's period.
       
   443  *    - 36000: Displaced 100% of it's period, same as 0, but 0 is preffered.
       
   444  *
   437  * Examples:
   445  * Examples:
   438  * \code
   446  * \code
   439  * SDL_HAPTIC_SINE
   447  * SDL_HAPTIC_SINE
   440  *   __      __      __      __
   448  *   __      __      __      __
   441  *  /  \    /  \    /  \    /
   449  *  /  \    /  \    /  \    /
   486 
   494 
   487    /* Periodic */
   495    /* Periodic */
   488    Uint16 period; /**< Period of the wave. */
   496    Uint16 period; /**< Period of the wave. */
   489    Sint16 magnitude; /**< Peak value. */
   497    Sint16 magnitude; /**< Peak value. */
   490    Sint16 offset; /**< Mean value of the wave. */
   498    Sint16 offset; /**< Mean value of the wave. */
   491    Uint16 phase; /**< Horizontal shift. */
   499    Uint16 phase; /**< Horizontal shift given by hundredth of a cycle. */
   492 
   500 
   493    /* Envelope */
   501    /* Envelope */
   494    Uint16 attack_length; /**< Duration of the attack. */
   502    Uint16 attack_length; /**< Duration of the attack. */
   495    Uint16 attack_level; /**< Level at the start of the attack. */
   503    Uint16 attack_level; /**< Level at the start of the attack. */
   496    Uint16 fade_length; /**< Duration of the fade. */
   504    Uint16 fade_length; /**< Duration of the fade. */
   590  * All values max at 32767 (0x7FFF).  Signed values also can be negative.
   598  * All values max at 32767 (0x7FFF).  Signed values also can be negative.
   591  *  Time values unless specified otherwise are in milliseconds.
   599  *  Time values unless specified otherwise are in milliseconds.
   592  *
   600  *
   593  * You can also pass SDL_HAPTIC_INFINITY to length instead of a 0-32767 value.
   601  * You can also pass SDL_HAPTIC_INFINITY to length instead of a 0-32767 value.
   594  *  Neither delay, interval, attack_length nor fade_length support 
   602  *  Neither delay, interval, attack_length nor fade_length support 
   595  *  SDL_HAPTIC_INFINITY.
   603  *  SDL_HAPTIC_INFINITY.  Fade will also not be used since effect never ends.
   596  *
   604  *
   597  * Common parts:
   605  * Common parts:
   598  * \code
   606  * \code
   599  * // Replay - All effects have this
   607  * // Replay - All effects have this
   600  * Uint32 length;        // Duration of effect (ms).
   608  * Uint32 length;        // Duration of effect (ms).
   873 extern DECLSPEC int SDLCALL SDL_HapticNewEffect(SDL_Haptic * haptic, SDL_HapticEffect * effect);
   881 extern DECLSPEC int SDLCALL SDL_HapticNewEffect(SDL_Haptic * haptic, SDL_HapticEffect * effect);
   874 
   882 
   875 /**
   883 /**
   876  * \fn int SDL_HapticUpdateEffect(SDL_Haptic * haptic, int effect, SDL_HapticEffect * data)
   884  * \fn int SDL_HapticUpdateEffect(SDL_Haptic * haptic, int effect, SDL_HapticEffect * data)
   877  *
   885  *
   878  * \brief Updates an effect.  Can be used dynamically, although behaviour when
   886  * \brief Updates the properties of an effect.
   879  * dynamically changing direction may be strange.  Specifically the effect
   887  *
   880  * may reupload itself and start playing from the start.  You cannot change
   888  * Can be used dynamically, although behaviour when dynamically changing
   881  * the type either when running UpdateEffect.
   889  * direction may be strange.  Specifically the effect may reupload itself
       
   890  * and start playing from the start.  You cannot change the type either when
       
   891  * running UpdateEffect.
   882  *
   892  *
   883  *    \param haptic Haptic device that has the effect.
   893  *    \param haptic Haptic device that has the effect.
   884  *    \param effect Effect to update.
   894  *    \param effect Effect to update.
   885  *    \param data New effect properties to use.
   895  *    \param data New effect properties to use.
   886  *    \return The id of the effect on success or -1 on error.
   896  *    \return The id of the effect on success or -1 on error.
   893 
   903 
   894 /**
   904 /**
   895  * \fn int SDL_HapticRunEffect(SDL_Haptic * haptic, int effect, int iterations)
   905  * \fn int SDL_HapticRunEffect(SDL_Haptic * haptic, int effect, int iterations)
   896  *
   906  *
   897  * \brief Runs the haptic effect on it's assosciated haptic device.
   907  * \brief Runs the haptic effect on it's assosciated haptic device.
       
   908  *
       
   909  * If iterations are SDL_HAPTIC_INFINITY, it'll run the effect over and over
       
   910  *  repeating the envelope (attack and fade) every time.  If you only want the
       
   911  *  effect to last forever, set SDL_HAPTIC_INFINITY in the effect's length
       
   912  *  parameter.
   898  *
   913  *
   899  *    \param haptic Haptic device to run the effect on.
   914  *    \param haptic Haptic device to run the effect on.
   900  *    \param effect Identifier of the haptic effect to run.
   915  *    \param effect Identifier of the haptic effect to run.
   901  *    \param iterations Number of iterations to run the effect. Use
   916  *    \param iterations Number of iterations to run the effect. Use
   902  *           SDL_HAPTIC_INFINITY for infinity.
   917  *           SDL_HAPTIC_INFINITY for infinity.