include/SDL_haptic.h
branchgsoc2008_force_feedback
changeset 2499 cc2b270608b2
parent 2498 ab567bd667bf
child 2500 5251d0510b7e
equal deleted inserted replaced
2498:ab567bd667bf 2499:cc2b270608b2
    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 /**
    24 
    24  * \file SDL_haptic.h
    25 /**
       
    26  * \mainpage SDL_haptic
       
    27  *
    25  *
    28  * \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)
    29  *  devices.
    27  *  devices.
    30  *
    28  *
    31  * The basic usage is as follows:
    29  * The basic usage is as follows:
    59  *    }
    57  *    }
    60  *
    58  *
    61  *    // Create the effect
    59  *    // Create the effect
    62  *    memset( &effect, 0, sizeof(SDL_HapticEffect) ); // 0 is safe default
    60  *    memset( &effect, 0, sizeof(SDL_HapticEffect) ); // 0 is safe default
    63  *    effect.type = SDL_HAPTIC_SINE;
    61  *    effect.type = SDL_HAPTIC_SINE;
       
    62  *    effect.periodic.direction.type = SDL_HAPTIC_POLAR; // Polar coordinates
       
    63  *    effect.periodic.direction.dir[0] = 180000; // Force comes from south
    64  *    effect.periodic.period = 1000; // 1000 ms
    64  *    effect.periodic.period = 1000; // 1000 ms
    65  *    effect.periodic.magnitude = 20000; // 20000/32767 strength
    65  *    effect.periodic.magnitude = 20000; // 20000/32767 strength
    66  *    effect.periodic.length = 5000; // 5 seconds long
    66  *    effect.periodic.length = 5000; // 5 seconds long
    67  *    effect.periodic.attack_length = 1000; // Takes 1 second to get max strength
    67  *    effect.periodic.attack_length = 1000; // Takes 1 second to get max strength
    68  *    effect.periodic.fade_length = 1000; // Takes 1 second to fade away
    68  *    effect.periodic.fade_length = 1000; // Takes 1 second to fade away
   136 #define SDL_HAPTIC_SINE       (1<<1) /* Sine wave effect supported */
   136 #define SDL_HAPTIC_SINE       (1<<1) /* Sine wave effect supported */
   137 /**
   137 /**
   138  * \def SDL_HAPTIC_SQUARE
   138  * \def SDL_HAPTIC_SQUARE
   139  *
   139  *
   140  * \brief Periodic haptic effect that simulates square waves.
   140  * \brief Periodic haptic effect that simulates square waves.
   141  *
   141  * 
   142  * \sa SDL_HapticPeriodic
   142  * \sa SDL_HapticPeriodic
   143  */
   143  */
   144 #define SDL_HAPTIC_SQUARE     (1<<2) /* Square wave effect supported */
   144 #define SDL_HAPTIC_SQUARE     (1<<2) /* Square wave effect supported */
   145 /**
   145 /**
   146  * \def SDL_HAPTIC_TRIANGLE
   146  * \def SDL_HAPTIC_TRIANGLE
   239  * \brief Device can be queried for effect status.
   239  * \brief Device can be queried for effect status.
   240  *
   240  *
   241  * \sa SDL_HapticGetEffectStatus
   241  * \sa SDL_HapticGetEffectStatus
   242  */
   242  */
   243 #define SDL_HAPTIC_STATUS     (1<<14) /* Device can be queried for effect status */
   243 #define SDL_HAPTIC_STATUS     (1<<14) /* Device can be queried for effect status */
       
   244 
       
   245 
       
   246 /*
       
   247  * Direction encodings
       
   248  */
       
   249 /**
       
   250  * \def SDL_HAPTIC_POLAR
       
   251  *
       
   252  * \brief Uses polar coordinates for the direction.
       
   253  *
       
   254  * \sa SDL_HapticDirection
       
   255  */
       
   256 #define SDL_HAPTIC_POLAR      0
       
   257 /**
       
   258  * \def SDL_HAPTIC_CARTESIAN
       
   259  *
       
   260  * \brief Uses cartesian coordinates for the direction.
       
   261  *
       
   262  * \sa SDL_HapticDirection
       
   263  */
       
   264 #define SDL_HAPTIC_CARTESIAN  1
       
   265 
       
   266 
       
   267 /**
       
   268  * \struct SDL_HapticDirection
       
   269  *
       
   270  * \brief Structure that represents a haptic direction.
       
   271  *
       
   272  * Directions can be specified by:
       
   273  *   - SDL_HAPTIC_POLAR: Specified by polar coordinates.
       
   274  *   - SDL_HAPTIC_CARTESIAN: Specified by cartesian coordinates.
       
   275  *
       
   276  * Cardinal directions of the haptic device are relative to the positioning
       
   277  *  of the device.  North is considered to be away from the user.
       
   278  *
       
   279  * The following diagram represents the cardinal directions:
       
   280  * \code
       
   281  *            .--.
       
   282  *            |__| .-------.
       
   283  *            |=.| |.-----.|
       
   284  *            |--| ||     ||
       
   285  *            |  | |'-----'|
       
   286  *            |__|~')_____('
       
   287  *              [ COMPUTER ]
       
   288  *
       
   289  *
       
   290  *                  North (-1)
       
   291  *                    ^
       
   292  *                    |
       
   293  *                    |
       
   294  * (1)  East <----[ HAPTIC ]----> West (-1)
       
   295  *                    |
       
   296  *                    |
       
   297  *                    v
       
   298  *                  South (1)
       
   299  *
       
   300  *
       
   301  *                 [ USER ]
       
   302  *                   \|||/
       
   303  *                   (o o)
       
   304  *             ---ooO-(_)-Ooo---
       
   305  * \endcode
       
   306  *
       
   307  * If type is SDL_HAPTIC_POLAR, direction is encoded by hundredths of a 
       
   308  *  degree starting north and turning clockwise.  The cardinal directions would be:
       
   309  *   - North: 0 (0 degrees)
       
   310  *   - West: 9000 (90 degrees)
       
   311  *   - South: 18000 (180 degrees)
       
   312  *   - East: 27000 (270 degrees)
       
   313  *
       
   314  * If type is SDL_HAPTIC_CARTESIAN, direction is encoded by position.
       
   315  *  The cardinal directions would be:
       
   316  *   - North:  0,-1
       
   317  *   - West:  -1, 0
       
   318  *   - South:  0, 1
       
   319  *   - East:   1, 0
       
   320  *
       
   321  *
       
   322  * Example:
       
   323  * \code
       
   324  * SDL_HapticDirection direction;
       
   325  *
       
   326  * direction.type = SDL_HAPTIC_POLAR; // We'll be using polar direction encoding.
       
   327  * direction.dir = 180000; // Force comes from the south meaning the user will
       
   328  *                         // have to pull the stick to counteract.
       
   329  * \endcode
       
   330  *
       
   331  * \sa SDL_HAPTIC_POLAR
       
   332  * \sa SDL_HAPTIC_CARTESIAN
       
   333  * \sa SDL_HapticEffect
       
   334  */
       
   335 typedef struct SDL_HapticDirection {
       
   336    Uint8 type; /**< The type of encoding. */
       
   337    Uint16 dir[2]; /**< The encoded direction. */
       
   338 } SDL_HapticDirection;
   244 
   339 
   245 
   340 
   246 /**
   341 /**
   247  * \struct SDL_HapticConstant
   342  * \struct SDL_HapticConstant
   248  *
   343  *
   254  * \sa SDL_HapticEffect
   349  * \sa SDL_HapticEffect
   255  */
   350  */
   256 typedef struct SDL_HapticConstant {
   351 typedef struct SDL_HapticConstant {
   257    /* Header */
   352    /* Header */
   258    Uint16 type; /**< SDL_HAPTIC_CONSTANT */
   353    Uint16 type; /**< SDL_HAPTIC_CONSTANT */
   259    Uint16 direction;
   354    SDL_HapticDirection direction; /**< Direction of the effect. */
   260 
   355 
   261    /* Replay */
   356    /* Replay */
   262    Uint16 length; /**< Duration of the effect. */
   357    Uint16 length; /**< Duration of the effect. */
   263    Uint16 delay; /**< Delay before starting the effect. */
   358    Uint16 delay; /**< Delay before starting the effect. */
   264 
   359 
   285  *   - SDL_HAPTIC_SQUARE
   380  *   - SDL_HAPTIC_SQUARE
   286  *   - SDL_HAPTIC_TRIANGLE
   381  *   - SDL_HAPTIC_TRIANGLE
   287  *   - SDL_HAPTIC_SAWTOOTHUP
   382  *   - SDL_HAPTIC_SAWTOOTHUP
   288  *   - SDL_HAPTIC_SAWTOOTHDOWN
   383  *   - SDL_HAPTIC_SAWTOOTHDOWN
   289  *
   384  *
       
   385  * Examples:
       
   386  * \code
       
   387  * SDL_HAPTIC_SINE
       
   388  *   __      __      __      __
       
   389  *  /  \    /  \    /  \    /
       
   390  * /    \__/    \__/    \__/
       
   391  *
       
   392  * SDL_HAPTIC_SQUARE
       
   393  *  __    __    __    __    __
       
   394  * |  |  |  |  |  |  |  |  |  |
       
   395  * |  |__|  |__|  |__|  |__|  |
       
   396  *
       
   397  * SDL_HAPTIC_TRIANGLE
       
   398  *   /\    /\    /\    /\    /\
       
   399  *  /  \  /  \  /  \  /  \  /
       
   400  * /    \/    \/    \/    \/
       
   401  *
       
   402  * SDL_HAPTIC_SAWTOOTHUP
       
   403  *    __    __    __    __    _
       
   404  *   /  |  /  |  /  |  /  |  /
       
   405  *  /   | /   | /   | /   | /
       
   406  * /    |/    |/    |/    |/
       
   407  *
       
   408  * SDL_HAPTIC_SAWTOOTHDOWN
       
   409  * __    __    __    __    __
       
   410  *   \  |  \  |  \  |  \  |  \
       
   411  *    \ |   \ |   \ |   \ |   \
       
   412  *     \|    \|    \|    \|
       
   413  * \endcode
       
   414  *
   290  * \sa SDL_HAPTIC_SINE
   415  * \sa SDL_HAPTIC_SINE
   291  * \sa SDL_HAPTIC_SQUARE
   416  * \sa SDL_HAPTIC_SQUARE
   292  * \sa SDL_HAPTIC_TRIANGLE
   417  * \sa SDL_HAPTIC_TRIANGLE
   293  * \sa SDL_HAPTIC_SAWTOOTHUP
   418  * \sa SDL_HAPTIC_SAWTOOTHUP
   294  * \sa SDL_HAPTIC_SAWTOOTHDOWN
   419  * \sa SDL_HAPTIC SAWTOOTHDOWN
   295  * \sa SDL_HapticEffect
   420  * \sa SDL_HapticEffect
   296  */
   421  */
   297 typedef struct SDL_HapticPeriodic {
   422 typedef struct SDL_HapticPeriodic {
   298    /* Header */
   423    /* Header */
   299    Uint16 type; /* SDL_HAPTIC_{SINE,SQUARE,TRIANGLE,SAWTOOTHUP,SAWTOOTHDOWN} */
   424    Uint16 type; /**< SDL_HAPTIC_{SINE,SQUARE,TRIANGLE,SAWTOOTHUP,SAWTOOTHDOWN} */
   300    Uint16 direction;
   425    SDL_HapticDirection direction; /**< Direction of the effect. */
   301 
   426 
   302    /* Replay */
   427    /* Replay */
   303    Uint16 length; /**< Duration of the effect. */
   428    Uint16 length; /**< Duration of the effect. */
   304    Uint16 delay; /**< Delay before starting the effect. */
   429    Uint16 delay; /**< Delay before starting the effect. */
   305 
   430 
   322 /**
   447 /**
   323  * \struct SDL_HapticCondition
   448  * \struct SDL_HapticCondition
   324  *
   449  *
   325  * \brief A structure containing a template for a Condition effect.
   450  * \brief A structure containing a template for a Condition effect.
   326  *
   451  *
       
   452  * Direction is handled by condition internals instead of a direction member.
       
   453  *
   327  * The struct handles the following effects:
   454  * The struct handles the following effects:
   328  *   - SDL_HAPTIC_SPRING
   455  *   - SDL_HAPTIC_SPRING: Effect based on axes position.
   329  *   - SDL_HAPTIC_DAMPER
   456  *   - SDL_HAPTIC_DAMPER: Effect based on axes velocity.
   330  *   - SDL_HAPTIC_INERTIA
   457  *   - SDL_HAPTIC_INERTIA: Effect based on axes acceleration.
   331  *   - SDL_HAPTIC_FRICTION
   458  *   - SDL_HAPTIC_FRICTION: Effect based on axes movement.
   332  *
   459  *
   333  * \sa SDL_HAPTIC_SPRING
   460  * \sa SDL_HAPTIC_SPRING
   334  * \sa SDL_HAPTIC_DAMPER
   461  * \sa SDL_HAPTIC_DAMPER
   335  * \sa SDL_HAPTIC_INERTIA
   462  * \sa SDL_HAPTIC_INERTIA
   336  * \sa SDL_HAPTIC_FRICTION
   463  * \sa SDL_HAPTIC_FRICTION
   337  * \sa SDL_HapticEffect
   464  * \sa SDL_HapticEffect
   338  */
   465  */
   339 typedef struct SDL_HapticCondition {
   466 typedef struct SDL_HapticCondition {
   340    /* Header */
   467    /* Header */
   341    Uint16 type; /**< SDL_HAPTIC_{SPRING,DAMPER,INERTIA,FRICTION} */
   468    Uint16 type; /**< SDL_HAPTIC_{SPRING,DAMPER,INERTIA,FRICTION} */
   342    Uint16 direction;
       
   343 
   469 
   344    /* Replay */
   470    /* Replay */
   345    Uint16 length; /**< Duration of the effect. */
   471    Uint16 length; /**< Duration of the effect. */
   346    Uint16 delay; /**< Delay before starting the effect. */
   472    Uint16 delay; /**< Delay before starting the effect. */
   347 
   473 
   368  * \sa SDL_HapticEffect
   494  * \sa SDL_HapticEffect
   369  */
   495  */
   370 typedef struct SDL_HapticRamp {
   496 typedef struct SDL_HapticRamp {
   371    /* Header */
   497    /* Header */
   372    Uint16 type; /**< SDL_HAPTIC_RAMP */
   498    Uint16 type; /**< SDL_HAPTIC_RAMP */
   373    Uint16 direction;
   499    SDL_HapticDirection direction; /**< Direction of the effect. */
   374 
   500 
   375    /* Replay */
   501    /* Replay */
   376    Uint16 length; /**< Duration of the effect. */
   502    Uint16 length; /**< Duration of the effect. */
   377    Uint16 delay; /**< Delay before starting the effect. */
   503    Uint16 delay; /**< Delay before starting the effect. */
   378 
   504 
   393 /**
   519 /**
   394  * \union SDL_HapticEffect
   520  * \union SDL_HapticEffect
   395  *
   521  *
   396  * \brief The generic template for any haptic effect.
   522  * \brief The generic template for any haptic effect.
   397  *
   523  *
   398  * All values max at 32767 (0x7fff).  Signed values also can be negative.
   524  * All values max at 32767 (0x7FFF).  Signed values also can be negative.
   399  * Time values unless specified otherwise are in milliseconds.
   525  * Time values unless specified otherwise are in milliseconds.
   400  *
   526  *
   401  * Common parts:
   527  * Common parts:
       
   528  * \code
       
   529  * // Replay - All effects have this
       
   530  * Uint16 length;        // Duration of effect (ms).
       
   531  * Uint16 delay;         // Delay before starting effect.
       
   532  *
       
   533  * // Trigger - All effects have this
       
   534  * Uint16 button;        // Button that triggers effect.
       
   535  * Uint16 interval;      // How soon before effect can be triggered again.
       
   536  *
       
   537  * // Envelope - Not all effects have this
       
   538  * Uint16 attack_length; // Duration of the attack (ms).
       
   539  * Uint16 attack_level;  // Level at the start of the attack.
       
   540  * Uint16 fade_length;   // Duration of the fade out (ms).
       
   541  * Uint16 fade_level;    // Level at the end of the fade.
       
   542  * \endcode
       
   543  *
       
   544  *
       
   545  * Here we have an example of an effect evolution in time:
       
   546  *
       
   547  * \code
       
   548  * Strength
       
   549  * ^
       
   550  * |
       
   551  * | effect strength -->  _________________
       
   552  * |                     /                 \
       
   553  * |                    /                   \
       
   554  * |                   /                     \
       
   555  * |                  /                       \ 
       
   556  * | attack_level --> |                        \
       
   557  * |                  |                        |  <---  fade_level
       
   558  * |
       
   559  * +--------------------------------------------------> Time
       
   560  *                    [--]                 [---]
       
   561  *                    attack_length        fade_length
   402  * 
   562  * 
   403  * Replay:
   563  * [------------------][-----------------------]
   404  *    Uint16 length;    Duration of effect.
   564  * delay               length
   405  *    Uint16 delay;     Delay before starting effect.
   565  * \endcode
   406  *
       
   407  * Trigger:
       
   408  *    Uint16 button;    Button that triggers effect.
       
   409  *    Uint16 interval;  How soon before effect can be triggered again.
       
   410  *
       
   411  * Envelope:
       
   412  *    Uint16 attack_length;   Duration of the attack.
       
   413  *    Uint16 attack_level;    Level at the start of the attack.
       
   414  *    Uint16 fade_length;     Duration of the fade out.
       
   415  *    Uint16 fade_level;      Level at the end of the fade.
       
   416  *
   566  *
   417  * \sa SDL_HapticConstant
   567  * \sa SDL_HapticConstant
   418  * \sa SDL_HapticPeriodic
   568  * \sa SDL_HapticPeriodic
   419  * \sa SDL_HapticCondition
   569  * \sa SDL_HapticCondition
   420  * \sa SDL_HaptiRamp
   570  * \sa SDL_HapticRamp
   421  */
   571  */
   422 typedef union SDL_HapticEffect {
   572 typedef union SDL_HapticEffect {
   423    /* Common for all force feedback effects */
   573    /* Common for all force feedback effects */
   424    Uint16 type; /**< Effect type */
   574    Uint16 type; /**< Effect type. */
   425    SDL_HapticConstant constant; /**< Constant effect */
   575    SDL_HapticConstant constant; /**< Constant effect. */
   426    SDL_HapticPeriodic periodic; /**< Periodic effect */
   576    SDL_HapticPeriodic periodic; /**< Periodic effect. */
   427    SDL_HapticCondition condition; /**< Condition effect */
   577    SDL_HapticCondition condition[2]; /**< Condition effect, one for each axis. */
   428    SDL_HapticRamp ramp; /**< Ramp effect */
   578    SDL_HapticRamp ramp; /**< Ramp effect. */
   429 } SDL_HapticEffect;
   579 } SDL_HapticEffect;
   430 
   580 
   431 
   581 
   432 /* Function prototypes */
   582 /* Function prototypes */
   433 /**
   583 /**
   452  * \sa SDL_NumHaptics
   602  * \sa SDL_NumHaptics
   453  */
   603  */
   454 extern DECLSPEC const char *SDLCALL SDL_HapticName(int device_index);
   604 extern DECLSPEC const char *SDLCALL SDL_HapticName(int device_index);
   455 
   605 
   456 /**
   606 /**
   457  * \fn SDL_Haptic * SDL_HapticOpen(int device_Index)
   607  * \fn SDL_Haptic * SDL_HapticOpen(int device_index)
   458  *
   608  *
   459  * \brief Opens a Haptic device for usage - the index passed as an
   609  * \brief Opens a Haptic device for usage - the index passed as an
   460  * argument refers to the N'th Haptic device on this system.
   610  * argument refers to the N'th Haptic device on this system.
   461  *
   611  *
   462  * This function returns a Haptic device identifier, or Null
   612  * This function returns a Haptic device identifier, or Null
   518  * \sa SDL_HapticQuery
   668  * \sa SDL_HapticQuery
   519  */
   669  */
   520 extern DECLSPEC int SDL_HapticNumEffects(SDL_Haptic * haptic);
   670 extern DECLSPEC int SDL_HapticNumEffects(SDL_Haptic * haptic);
   521 
   671 
   522 /**
   672 /**
   523  * \fn unsigned int SDL_HapticQueryEffects(SDL_Haptic * haptic)
   673  * \fn unsigned int SDL_HapticQuery(SDL_Haptic * haptic)
   524  *
   674  *
   525  * \brief Gets the haptic devices supported features in bitwise matter.
   675  * \brief Gets the haptic devices supported features in bitwise matter.
   526  *
   676  *
   527  * Example: 
   677  * Example: 
   528  * \code
   678  * \code
   539  * \sa SDL_HapticEffectSupported
   689  * \sa SDL_HapticEffectSupported
   540  */
   690  */
   541 extern DECLSPEC unsigned int SDL_HapticQuery(SDL_Haptic * haptic);
   691 extern DECLSPEC unsigned int SDL_HapticQuery(SDL_Haptic * haptic);
   542 
   692 
   543 /**
   693 /**
   544  * \fn int SDL_HapticEffectSupported
   694  * \fn int SDL_HapticEffectSupported(SDL_Haptic * haptic, SDL_HapticEffect * effect)
   545  *
   695  *
   546  * \brief Checks to see if effect is supported by haptic.
   696  * \brief Checks to see if effect is supported by haptic.
   547  *
   697  *
   548  *    \param haptic Haptic device to check on.
   698  *    \param haptic Haptic device to check on.
   549  *    \param effect Effect to check to see if it is supported.
   699  *    \param effect Effect to check to see if it is supported.
   588  * \sa SDL_HapticDestroyEffect
   738  * \sa SDL_HapticDestroyEffect
   589  */
   739  */
   590 extern DECLSPEC int SDL_HapticUpdateEffect(SDL_Haptic * haptic, int effect, SDL_HapticEffect * data);
   740 extern DECLSPEC int SDL_HapticUpdateEffect(SDL_Haptic * haptic, int effect, SDL_HapticEffect * data);
   591 
   741 
   592 /**
   742 /**
   593  * \fn int SDL_HapticRunEffects(SDL_Haptic * haptic, int effect)
   743  * \fn int SDL_HapticRunEffect(SDL_Haptic * haptic, int effect)
   594  *
   744  *
   595  * \brief Runs the haptic effect on it's assosciated haptic device.
   745  * \brief Runs the haptic effect on it's assosciated haptic device.
   596  *
   746  *
   597  *    \param haptic Haptic device to run the effect on.
   747  *    \param haptic Haptic device to run the effect on.
   598  *    \param effect Identifier of the haptic effect to run.
   748  *    \param effect Identifier of the haptic effect to run.
   608  * \fn int SDL_HapticStopEffect(SDL_Haptic * haptic, int effect)
   758  * \fn int SDL_HapticStopEffect(SDL_Haptic * haptic, int effect)
   609  *
   759  *
   610  * \brief Stops the haptic effect on it's assosciated haptic device.
   760  * \brief Stops the haptic effect on it's assosciated haptic device.
   611  *
   761  *
   612  *    \param haptic Haptic device to stop the effect on.
   762  *    \param haptic Haptic device to stop the effect on.
   613  *    \praam effect Identifier of the effect to stop.
   763  *    \param effect Identifier of the effect to stop.
   614  *    \return 0 on success or -1 on error.
   764  *    \return 0 on success or -1 on error.
   615  *
   765  *
   616  * \sa SDL_HapticRunEffect
   766  * \sa SDL_HapticRunEffect
   617  * \sa SDL_HapticDestroyEffect
   767  * \sa SDL_HapticDestroyEffect
   618  */
   768  */