include/SDL_haptic.h
branchgsoc2008_force_feedback
changeset 2498 ab567bd667bf
parent 2497 0893fbf73b3d
child 2499 cc2b270608b2
equal deleted inserted replaced
2497:0893fbf73b3d 2498:ab567bd667bf
    18 
    18 
    19     Sam Lantinga
    19     Sam Lantinga
    20     slouken@libsdl.org
    20     slouken@libsdl.org
    21 */
    21 */
    22 
    22 
    23 /** \file SDL_haptic.h */
    23 /** \file SDL_Haptic.h */
       
    24 
    24 /**
    25 /**
    25  * \mainpage SDL_haptic
    26  * \mainpage SDL_haptic
    26  *
    27  *
    27  * The SDL Haptic subsystem allows you to control haptic (force feedback)
    28  * \brief The SDL Haptic subsystem allows you to control haptic (force feedback)
    28  *  devices.
    29  *  devices.
    29  *
    30  *
    30  * The basic usage is as follows:
    31  * The basic usage is as follows:
    31  *   - Initialize the Subsystem (SDL_INIT_HAPTIC).
    32  *   - Initialize the Subsystem (SDL_INIT_HAPTIC).
    32  *   - Open a Haptic Device.
    33  *   - Open a Haptic Device.
   100 extern "C" {
   101 extern "C" {
   101    /* *INDENT-ON* */                                                         
   102    /* *INDENT-ON* */                                                         
   102 #endif /* __cpluspuls */
   103 #endif /* __cpluspuls */
   103 
   104 
   104 /**
   105 /**
   105  * \struct SDL_Haptic
   106  * \typedef SDL_Haptic
   106  *
   107  *
   107  * \brief The haptic structure used to identify an SDL haptic.
   108  * \brief The haptic structure used to identify an SDL haptic.
   108  *
   109  *
   109  * \sa SDL_HapticOpen
   110  * \sa SDL_HapticOpen
   110  * \sa SDL_HapticOpenFromJoystick
   111  * \sa SDL_HapticOpenFromJoystick
   387    Uint16 attack_length; /**< Duration of the attack. */
   388    Uint16 attack_length; /**< Duration of the attack. */
   388    Uint16 attack_level; /**< Level at the start of the attack. */
   389    Uint16 attack_level; /**< Level at the start of the attack. */
   389    Uint16 fade_length; /**< Duration of the fade. */
   390    Uint16 fade_length; /**< Duration of the fade. */
   390    Uint16 fade_level; /**< Level at the end of the fade. */
   391    Uint16 fade_level; /**< Level at the end of the fade. */
   391 } SDL_HapticRamp;
   392 } SDL_HapticRamp;
   392 /*
   393 /**
   393  * \union SDL_HapticEffect
   394  * \union SDL_HapticEffect
   394  *
   395  *
   395  * \brief The generic template for any haptic effect.
   396  * \brief The generic template for any haptic effect.
   396  *
   397  *
   397  * All values max at 32767 (0x7fff).  Signed values also can be negative.
   398  * All values max at 32767 (0x7fff).  Signed values also can be negative.
   427    SDL_HapticRamp ramp; /**< Ramp effect */
   428    SDL_HapticRamp ramp; /**< Ramp effect */
   428 } SDL_HapticEffect;
   429 } SDL_HapticEffect;
   429 
   430 
   430 
   431 
   431 /* Function prototypes */
   432 /* Function prototypes */
   432 /*
   433 /**
   433  * \fn int SDL_NumHaptics(void)
   434  * \fn int SDL_NumHaptics(void)
   434  *
   435  *
   435  * \brief Count the number of joysticks attached to the system.
   436  * \brief Count the number of joysticks attached to the system.
   436  *
   437  *
   437  *    \return Number of haptic devices detected on the system.
   438  *    \return Number of haptic devices detected on the system.
   438  */
   439  */
   439 extern DECLSPEC int SDLCALL SDL_NumHaptics(void);
   440 extern DECLSPEC int SDLCALL SDL_NumHaptics(void);
   440 
   441 
   441 /*
   442 /**
   442  * \fn const char * SDL_HapticName(int device_index)
   443  * \fn const char * SDL_HapticName(int device_index)
   443  *
   444  *
   444  * \brief Get the implementation dependent name of a Haptic device.
   445  * \brief Get the implementation dependent name of a Haptic device.
   445  * This can be called before any joysticks are opened.
   446  * This can be called before any joysticks are opened.
   446  * If no name can be found, this function returns NULL.
   447  * If no name can be found, this function returns NULL.
   450  *
   451  *
   451  * \sa SDL_NumHaptics
   452  * \sa SDL_NumHaptics
   452  */
   453  */
   453 extern DECLSPEC const char *SDLCALL SDL_HapticName(int device_index);
   454 extern DECLSPEC const char *SDLCALL SDL_HapticName(int device_index);
   454 
   455 
   455 /*
   456 /**
   456  * \fn SDL_Haptic * SDL_HapticOpen(int device_Index)
   457  * \fn SDL_Haptic * SDL_HapticOpen(int device_Index)
   457  *
   458  *
   458  * \brief Opens a Haptic device for usage - the index passed as an
   459  * \brief Opens a Haptic device for usage - the index passed as an
   459  * argument refers to the N'th Haptic device on this system.
   460  * argument refers to the N'th Haptic device on this system.
   460  *
   461  *
   467  * \sa SDL_HapticOpenFromJoystick
   468  * \sa SDL_HapticOpenFromJoystick
   468  * \sa SDL_HapticClose
   469  * \sa SDL_HapticClose
   469  */
   470  */
   470 extern DECLSPEC SDL_Haptic * SDL_HapticOpen(int device_index);
   471 extern DECLSPEC SDL_Haptic * SDL_HapticOpen(int device_index);
   471 
   472 
   472 /*
   473 /**
   473  * \fn int SDL_JoystickIsHaptic(SDL_Joystick * joysticke)
   474  * \fn int SDL_JoystickIsHaptic(SDL_Joystick * joystick)
   474  *
   475  *
   475  * \brief Checks to see if a joystick has haptic features.
   476  * \brief Checks to see if a joystick has haptic features.
   476  *
   477  *
   477  *    \param joystick Joystick to test for haptic capabilities.
   478  *    \param joystick Joystick to test for haptic capabilities.
   478  *    \return SDL_TRUE if the joystick is haptic, SDL_FALSE if it isn't
   479  *    \return SDL_TRUE if the joystick is haptic, SDL_FALSE if it isn't
   480  *
   481  *
   481  * \sa SDL_HapticOpenFromJoystick
   482  * \sa SDL_HapticOpenFromJoystick
   482  */
   483  */
   483 extern DECLSPEC int SDL_JoystickIsHaptic(SDL_Joystick * joystick);
   484 extern DECLSPEC int SDL_JoystickIsHaptic(SDL_Joystick * joystick);
   484 
   485 
   485 /*
   486 /**
   486  * \fn SDL_Haptic * SDL_HapticOpenFromJoystick(SDL_Joystick * joystick)
   487  * \fn SDL_Haptic * SDL_HapticOpenFromJoystick(SDL_Joystick * joystick)
   487  *
   488  *
   488  * \brief Opens a Haptic device for usage from a Joystick device.  Still has
   489  * \brief Opens a Haptic device for usage from a Joystick device.  Still has
   489  * to be closed seperately to the joystick.
   490  * to be closed seperately to the joystick.
   490  *
   491  *
   494  * \sa SDL_HapticOpen
   495  * \sa SDL_HapticOpen
   495  * \sa SDL_HapticClose
   496  * \sa SDL_HapticClose
   496  */
   497  */
   497 extern DECLSPEC SDL_Haptic * SDL_HapticOpenFromJoystick(SDL_Joystick * joystick);
   498 extern DECLSPEC SDL_Haptic * SDL_HapticOpenFromJoystick(SDL_Joystick * joystick);
   498 
   499 
   499 /* 
   500 /**
   500  * \fn void SDL_HapticClose(SDL_Haptic * haptic)
   501  * \fn void SDL_HapticClose(SDL_Haptic * haptic)
   501  *
   502  *
   502  * \brief Closes a Haptic device previously opened with SDL_HapticOpen.
   503  * \brief Closes a Haptic device previously opened with SDL_HapticOpen.
   503  *
   504  *
   504  *    \param haptic Haptic device to close.
   505  *    \param haptic Haptic device to close.
   505  */
   506  */
   506 extern DECLSPEC void SDL_HapticClose(SDL_Haptic * haptic);
   507 extern DECLSPEC void SDL_HapticClose(SDL_Haptic * haptic);
   507 
   508 
   508 /*
   509 /**
   509  * \fn int SDL_HapticNumEffects(SDL_Haptic * haptic)
   510  * \fn int SDL_HapticNumEffects(SDL_Haptic * haptic)
   510  *
   511  *
   511  * \brief Returns the number of effects a haptic device can store.
   512  * \brief Returns the number of effects a haptic device can store.
   512  *
   513  *
   513  *    \param haptic The haptic device to query effect max.
   514  *    \param haptic The haptic device to query effect max.
   516  *
   517  *
   517  * \sa SDL_HapticQuery
   518  * \sa SDL_HapticQuery
   518  */
   519  */
   519 extern DECLSPEC int SDL_HapticNumEffects(SDL_Haptic * haptic);
   520 extern DECLSPEC int SDL_HapticNumEffects(SDL_Haptic * haptic);
   520 
   521 
   521 /*
   522 /**
   522  * \fn unsigned int SDL_HapticQueryEffects(SDL_Haptic * haptic)
   523  * \fn unsigned int SDL_HapticQueryEffects(SDL_Haptic * haptic)
   523  *
   524  *
   524  * \brief Gets the haptic devices supported features in bitwise matter.
   525  * \brief Gets the haptic devices supported features in bitwise matter.
   525  *
   526  *
   526  * Example: 
   527  * Example: 
   537  * \sa SDL_HapticNumEffects
   538  * \sa SDL_HapticNumEffects
   538  * \sa SDL_HapticEffectSupported
   539  * \sa SDL_HapticEffectSupported
   539  */
   540  */
   540 extern DECLSPEC unsigned int SDL_HapticQuery(SDL_Haptic * haptic);
   541 extern DECLSPEC unsigned int SDL_HapticQuery(SDL_Haptic * haptic);
   541 
   542 
   542 /*
   543 /**
   543  * \fn int SDL_HapticEffectSupported
   544  * \fn int SDL_HapticEffectSupported
   544  *
   545  *
   545  * \brief Checks to see if effect is supported by haptic.
   546  * \brief Checks to see if effect is supported by haptic.
   546  *
   547  *
   547  *    \param haptic Haptic device to check on.
   548  *    \param haptic Haptic device to check on.
   552  * \sa SDL_HapticQuery
   553  * \sa SDL_HapticQuery
   553  * \sa SDL_HapticNewEffect
   554  * \sa SDL_HapticNewEffect
   554  */
   555  */
   555 extern DECLSPEC int SDL_HapticEffectSupported(SDL_Haptic * haptic, SDL_HapticEffect * effect);
   556 extern DECLSPEC int SDL_HapticEffectSupported(SDL_Haptic * haptic, SDL_HapticEffect * effect);
   556 
   557 
   557 /*
   558 /**
   558  * \fn int SDL_HapticNewEffect(SDL_Haptic * haptic, SDL_HapticEffect * effect)
   559  * \fn int SDL_HapticNewEffect(SDL_Haptic * haptic, SDL_HapticEffect * effect)
   559  *
   560  *
   560  * \brief Creates a new haptic effect on the device.
   561  * \brief Creates a new haptic effect on the device.
   561  *
   562  *
   562  *    \param haptic Haptic device to create the effect on.
   563  *    \param haptic Haptic device to create the effect on.
   567  * \sa SDL_HapticRunEffect
   568  * \sa SDL_HapticRunEffect
   568  * \sa SDL_HapticDestroyEffect
   569  * \sa SDL_HapticDestroyEffect
   569  */
   570  */
   570 extern DECLSPEC int SDL_HapticNewEffect(SDL_Haptic * haptic, SDL_HapticEffect * effect);
   571 extern DECLSPEC int SDL_HapticNewEffect(SDL_Haptic * haptic, SDL_HapticEffect * effect);
   571 
   572 
   572 /*
   573 /**
   573  * \fn int SDL_HapticUpdateEffect(SDL_Haptic * haptic, int effect, SDL_HapticEffect * data)
   574  * \fn int SDL_HapticUpdateEffect(SDL_Haptic * haptic, int effect, SDL_HapticEffect * data)
   574  *
   575  *
   575  * \brief Updates an effect.  Can be used dynamically, although behaviour when
   576  * \brief Updates an effect.  Can be used dynamically, although behaviour when
   576  * dynamically changing direction may be strange.  Specifically the effect
   577  * dynamically changing direction may be strange.  Specifically the effect
   577  * may reupload itself and start playing from the start.  You cannot change
   578  * may reupload itself and start playing from the start.  You cannot change
   586  * \sa SDL_HapticRunEffect
   587  * \sa SDL_HapticRunEffect
   587  * \sa SDL_HapticDestroyEffect
   588  * \sa SDL_HapticDestroyEffect
   588  */
   589  */
   589 extern DECLSPEC int SDL_HapticUpdateEffect(SDL_Haptic * haptic, int effect, SDL_HapticEffect * data);
   590 extern DECLSPEC int SDL_HapticUpdateEffect(SDL_Haptic * haptic, int effect, SDL_HapticEffect * data);
   590 
   591 
   591 /*
   592 /**
   592  * \fn int SDL_HapticRunEffects(SDL_Haptic * haptic, int effect)
   593  * \fn int SDL_HapticRunEffects(SDL_Haptic * haptic, int effect)
   593  *
   594  *
   594  * \brief Runs the haptic effect on it's assosciated haptic device.
   595  * \brief Runs the haptic effect on it's assosciated haptic device.
   595  *
   596  *
   596  *    \param haptic Haptic device to run the effect on.
   597  *    \param haptic Haptic device to run the effect on.
   601  * \sa SDL_HapticDestroyEffect
   602  * \sa SDL_HapticDestroyEffect
   602  * \sa SDL_HapticGetEffectStatus
   603  * \sa SDL_HapticGetEffectStatus
   603  */
   604  */
   604 extern DECLSPEC int SDL_HapticRunEffect(SDL_Haptic * haptic, int effect);
   605 extern DECLSPEC int SDL_HapticRunEffect(SDL_Haptic * haptic, int effect);
   605 
   606 
   606 /*
   607 /**
   607  * \fn int SDL_HapticStopEffect(SDL_Haptic * haptic, int effect)
   608  * \fn int SDL_HapticStopEffect(SDL_Haptic * haptic, int effect)
   608  *
   609  *
   609  * \brief Stops the haptic effect on it's assosciated haptic device.
   610  * \brief Stops the haptic effect on it's assosciated haptic device.
   610  *
   611  *
   611  *    \param haptic Haptic device to stop the effect on.
   612  *    \param haptic Haptic device to stop the effect on.
   615  * \sa SDL_HapticRunEffect
   616  * \sa SDL_HapticRunEffect
   616  * \sa SDL_HapticDestroyEffect
   617  * \sa SDL_HapticDestroyEffect
   617  */
   618  */
   618 extern DECLSPEC int SDL_HapticStopEffect(SDL_Haptic * haptic, int effect);
   619 extern DECLSPEC int SDL_HapticStopEffect(SDL_Haptic * haptic, int effect);
   619 
   620 
   620 /*
   621 /**
   621  * \fn void SDL_HapticDestroyEffect(SDL_Haptic * haptic, int effect)
   622  * \fn void SDL_HapticDestroyEffect(SDL_Haptic * haptic, int effect)
   622  *
   623  *
   623  * \brief Destroys a haptic effect on the device.  This will stop the effect
   624  * \brief Destroys a haptic effect on the device.  This will stop the effect
   624  * if it's running.  Effects are automatically destroyed when the device is
   625  * if it's running.  Effects are automatically destroyed when the device is
   625  * closed.
   626  * closed.
   629  * 
   630  * 
   630  * \sa SDL_HapticNewEffect
   631  * \sa SDL_HapticNewEffect
   631  */
   632  */
   632 extern DECLSPEC void SDL_HapticDestroyEffect(SDL_Haptic * haptic, int effect);
   633 extern DECLSPEC void SDL_HapticDestroyEffect(SDL_Haptic * haptic, int effect);
   633 
   634 
   634 /*
   635 /**
   635  * \fn int SDL_HapticGetEffectStatus(SDL_Haptic *haptic, int effect)
   636  * \fn int SDL_HapticGetEffectStatus(SDL_Haptic *haptic, int effect)
   636  *
   637  *
   637  * \brief Gets the status of the current effect on the haptic device.
   638  * \brief Gets the status of the current effect on the haptic device.
   638  *
   639  *
   639  * Device must support the SDL_HAPTIC_STATUS feature.
   640  * Device must support the SDL_HAPTIC_STATUS feature.
   646  * \sa SDL_HapticRunEffect
   647  * \sa SDL_HapticRunEffect
   647  * \sa SDL_HapticStopEffect
   648  * \sa SDL_HapticStopEffect
   648  */
   649  */
   649 extern DECLSPEC int SDL_HapticGetEffectStatus(SDL_Haptic *haptic, int effect);
   650 extern DECLSPEC int SDL_HapticGetEffectStatus(SDL_Haptic *haptic, int effect);
   650 
   651 
   651 /*
   652 /**
   652  * \fn int SDL_HapticSetGain(SDL_Haptic * haptic, int gain)
   653  * \fn int SDL_HapticSetGain(SDL_Haptic * haptic, int gain)
   653  *
   654  *
   654  * \brief Sets the global gain of the device.  Gain should be between 0 and 100.
   655  * \brief Sets the global gain of the device.  Gain should be between 0 and 100.
   655  *
   656  *
   656  * Device must support the SDL_HAPTIC_GAIN feature.
   657  * Device must support the SDL_HAPTIC_GAIN feature.
   661  *
   662  *
   662  * \sa SDL_HapticQuery
   663  * \sa SDL_HapticQuery
   663  */
   664  */
   664 extern DECLSPEC int SDL_HapticSetGain(SDL_Haptic * haptic, int gain);
   665 extern DECLSPEC int SDL_HapticSetGain(SDL_Haptic * haptic, int gain);
   665 
   666 
   666 /*
   667 /**
   667  * \fn int SDL_HapticSetAutocenter(SDL_Haptic * haptic, int autocenter)
   668  * \fn int SDL_HapticSetAutocenter(SDL_Haptic * haptic, int autocenter)
   668  *
   669  *
   669  * \brief Sets the global autocenter of the device.  Autocenter should be between
   670  * \brief Sets the global autocenter of the device.  Autocenter should be between
   670  * 0 and 100.  Setting it to 0 will disable autocentering.
   671  * 0 and 100.  Setting it to 0 will disable autocentering.
   671  *
   672  *