include/SDL_haptic.h
changeset 7191 75360622e65f
parent 7125 082c0c53ac16
child 7221 122c97a210bc
equal deleted inserted replaced
7190:11612d544fcd 7191:75360622e65f
    19   3. This notice may not be removed or altered from any source distribution.
    19   3. This notice may not be removed or altered from any source distribution.
    20 */
    20 */
    21 
    21 
    22 /**
    22 /**
    23  *  \file SDL_haptic.h
    23  *  \file SDL_haptic.h
    24  *  
    24  *
    25  *  \brief The SDL Haptic subsystem allows you to control haptic (force feedback)
    25  *  \brief The SDL Haptic subsystem allows you to control haptic (force feedback)
    26  *         devices.
    26  *         devices.
    27  * 
    27  *
    28  *  The basic usage is as follows:
    28  *  The basic usage is as follows:
    29  *   - Initialize the Subsystem (::SDL_INIT_HAPTIC).
    29  *   - Initialize the Subsystem (::SDL_INIT_HAPTIC).
    30  *   - Open a Haptic Device.
    30  *   - Open a Haptic Device.
    31  *    - SDL_HapticOpen() to open from index.
    31  *    - SDL_HapticOpen() to open from index.
    32  *    - SDL_HapticOpenFromJoystick() to open from an existing joystick.
    32  *    - SDL_HapticOpenFromJoystick() to open from an existing joystick.
   117 #include "SDL_joystick.h"
   117 #include "SDL_joystick.h"
   118 
   118 
   119 #include "begin_code.h"
   119 #include "begin_code.h"
   120 /* Set up for C function definitions, even when using C++ */
   120 /* Set up for C function definitions, even when using C++ */
   121 #ifdef __cplusplus
   121 #ifdef __cplusplus
   122 /* *INDENT-OFF* */
       
   123 extern "C" {
   122 extern "C" {
   124    /* *INDENT-ON* */                                                         
       
   125 #endif /* __cplusplus */
   123 #endif /* __cplusplus */
   126 
   124 
   127 /**
   125 /**
   128  *  \typedef SDL_Haptic
   126  *  \typedef SDL_Haptic
   129  *  
   127  *
   130  *  \brief The haptic structure used to identify an SDL haptic.
   128  *  \brief The haptic structure used to identify an SDL haptic.
   131  *  
   129  *
   132  *  \sa SDL_HapticOpen
   130  *  \sa SDL_HapticOpen
   133  *  \sa SDL_HapticOpenFromJoystick
   131  *  \sa SDL_HapticOpenFromJoystick
   134  *  \sa SDL_HapticClose
   132  *  \sa SDL_HapticClose
   135  */
   133  */
   136 struct _SDL_Haptic;
   134 struct _SDL_Haptic;
   137 typedef struct _SDL_Haptic SDL_Haptic;
   135 typedef struct _SDL_Haptic SDL_Haptic;
   138 
   136 
   139 
   137 
   140 /**
   138 /**
   141  *  \name Haptic features
   139  *  \name Haptic features
   142  *  
   140  *
   143  *  Different haptic features a device can have.
   141  *  Different haptic features a device can have.
   144  */
   142  */
   145 /*@{*/
   143 /*@{*/
   146 
   144 
   147 /**
   145 /**
   151 
   149 
   152 /**
   150 /**
   153  *  \brief Constant effect supported.
   151  *  \brief Constant effect supported.
   154  *
   152  *
   155  *  Constant haptic effect.
   153  *  Constant haptic effect.
   156  *  
   154  *
   157  *  \sa SDL_HapticCondition
   155  *  \sa SDL_HapticCondition
   158  */
   156  */
   159 #define SDL_HAPTIC_CONSTANT   (1<<0)
   157 #define SDL_HAPTIC_CONSTANT   (1<<0)
   160 
   158 
   161 /**
   159 /**
   162  *  \brief Sine wave effect supported.
   160  *  \brief Sine wave effect supported.
   163  *  
   161  *
   164  *  Periodic haptic effect that simulates sine waves.
   162  *  Periodic haptic effect that simulates sine waves.
   165  *  
   163  *
   166  *  \sa SDL_HapticPeriodic
   164  *  \sa SDL_HapticPeriodic
   167  */
   165  */
   168 #define SDL_HAPTIC_SINE       (1<<1)
   166 #define SDL_HAPTIC_SINE       (1<<1)
   169 
   167 
   170 /**
   168 /**
   171  *  \brief Square wave effect supported.
   169  *  \brief Square wave effect supported.
   172  *  
   170  *
   173  *  Periodic haptic effect that simulates square waves.
   171  *  Periodic haptic effect that simulates square waves.
   174  * 
   172  *
   175  *  \sa SDL_HapticPeriodic
   173  *  \sa SDL_HapticPeriodic
   176  */
   174  */
   177 #define SDL_HAPTIC_SQUARE     (1<<2)
   175 #define SDL_HAPTIC_SQUARE     (1<<2)
   178 
   176 
   179 /**
   177 /**
   180  *  \brief Triangle wave effect supported.
   178  *  \brief Triangle wave effect supported.
   181  *  
   179  *
   182  *  Periodic haptic effect that simulates triangular waves.
   180  *  Periodic haptic effect that simulates triangular waves.
   183  *  
   181  *
   184  *  \sa SDL_HapticPeriodic
   182  *  \sa SDL_HapticPeriodic
   185  */
   183  */
   186 #define SDL_HAPTIC_TRIANGLE   (1<<3)
   184 #define SDL_HAPTIC_TRIANGLE   (1<<3)
   187 
   185 
   188 /**
   186 /**
   189  *  \brief Sawtoothup wave effect supported.
   187  *  \brief Sawtoothup wave effect supported.
   190  *  
   188  *
   191  *  Periodic haptic effect that simulates saw tooth up waves.
   189  *  Periodic haptic effect that simulates saw tooth up waves.
   192  *  
   190  *
   193  *  \sa SDL_HapticPeriodic
   191  *  \sa SDL_HapticPeriodic
   194  */
   192  */
   195 #define SDL_HAPTIC_SAWTOOTHUP (1<<4)
   193 #define SDL_HAPTIC_SAWTOOTHUP (1<<4)
   196 
   194 
   197 /**
   195 /**
   198  *  \brief Sawtoothdown wave effect supported.
   196  *  \brief Sawtoothdown wave effect supported.
   199  *  
   197  *
   200  *  Periodic haptic effect that simulates saw tooth down waves.
   198  *  Periodic haptic effect that simulates saw tooth down waves.
   201  *  
   199  *
   202  *  \sa SDL_HapticPeriodic
   200  *  \sa SDL_HapticPeriodic
   203  */
   201  */
   204 #define SDL_HAPTIC_SAWTOOTHDOWN (1<<5)
   202 #define SDL_HAPTIC_SAWTOOTHDOWN (1<<5)
   205 
   203 
   206 /**
   204 /**
   207  *  \brief Ramp effect supported.
   205  *  \brief Ramp effect supported.
   208  *  
   206  *
   209  *  Ramp haptic effect.
   207  *  Ramp haptic effect.
   210  *  
   208  *
   211  *  \sa SDL_HapticRamp
   209  *  \sa SDL_HapticRamp
   212  */
   210  */
   213 #define SDL_HAPTIC_RAMP       (1<<6)
   211 #define SDL_HAPTIC_RAMP       (1<<6)
   214 
   212 
   215 /**
   213 /**
   216  *  \brief Spring effect supported - uses axes position.
   214  *  \brief Spring effect supported - uses axes position.
   217  *  
   215  *
   218  *  Condition haptic effect that simulates a spring.  Effect is based on the
   216  *  Condition haptic effect that simulates a spring.  Effect is based on the
   219  *  axes position.
   217  *  axes position.
   220  *
   218  *
   221  *  \sa SDL_HapticCondition
   219  *  \sa SDL_HapticCondition
   222  */
   220  */
   223 #define SDL_HAPTIC_SPRING     (1<<7)
   221 #define SDL_HAPTIC_SPRING     (1<<7)
   224 
   222 
   225 /**
   223 /**
   226  *  \brief Damper effect supported - uses axes velocity.
   224  *  \brief Damper effect supported - uses axes velocity.
   227  *  
   225  *
   228  *  Condition haptic effect that simulates dampening.  Effect is based on the
   226  *  Condition haptic effect that simulates dampening.  Effect is based on the
   229  *  axes velocity.
   227  *  axes velocity.
   230  *  
   228  *
   231  *  \sa SDL_HapticCondition
   229  *  \sa SDL_HapticCondition
   232  */
   230  */
   233 #define SDL_HAPTIC_DAMPER     (1<<8)
   231 #define SDL_HAPTIC_DAMPER     (1<<8)
   234 
   232 
   235 /**
   233 /**
   236  *  \brief Inertia effect supported - uses axes acceleration.
   234  *  \brief Inertia effect supported - uses axes acceleration.
   237  *  
   235  *
   238  *  Condition haptic effect that simulates inertia.  Effect is based on the axes
   236  *  Condition haptic effect that simulates inertia.  Effect is based on the axes
   239  *  acceleration.
   237  *  acceleration.
   240  *
   238  *
   241  *  \sa SDL_HapticCondition
   239  *  \sa SDL_HapticCondition
   242  */
   240  */
   243 #define SDL_HAPTIC_INERTIA    (1<<9)
   241 #define SDL_HAPTIC_INERTIA    (1<<9)
   244 
   242 
   245 /**
   243 /**
   246  *  \brief Friction effect supported - uses axes movement.
   244  *  \brief Friction effect supported - uses axes movement.
   247  *  
   245  *
   248  *  Condition haptic effect that simulates friction.  Effect is based on the 
   246  *  Condition haptic effect that simulates friction.  Effect is based on the
   249  *  axes movement.
   247  *  axes movement.
   250  *  
   248  *
   251  *  \sa SDL_HapticCondition
   249  *  \sa SDL_HapticCondition
   252  */
   250  */
   253 #define SDL_HAPTIC_FRICTION   (1<<10)
   251 #define SDL_HAPTIC_FRICTION   (1<<10)
   254 
   252 
   255 /**
   253 /**
   256  *  \brief Custom effect is supported.
   254  *  \brief Custom effect is supported.
   257  *  
   255  *
   258  *  User defined custom haptic effect.
   256  *  User defined custom haptic effect.
   259  */
   257  */
   260 #define SDL_HAPTIC_CUSTOM     (1<<11)
   258 #define SDL_HAPTIC_CUSTOM     (1<<11)
   261 
   259 
   262 /*@}*//*Haptic effects*/
   260 /*@}*//*Haptic effects*/
   263 
   261 
   264 /* These last few are features the device has, not effects */
   262 /* These last few are features the device has, not effects */
   265 
   263 
   266 /**
   264 /**
   267  *  \brief Device can set global gain.
   265  *  \brief Device can set global gain.
   268  *  
   266  *
   269  *  Device supports setting the global gain.
   267  *  Device supports setting the global gain.
   270  *  
   268  *
   271  *  \sa SDL_HapticSetGain
   269  *  \sa SDL_HapticSetGain
   272  */
   270  */
   273 #define SDL_HAPTIC_GAIN       (1<<12)
   271 #define SDL_HAPTIC_GAIN       (1<<12)
   274 
   272 
   275 /**
   273 /**
   276  *  \brief Device can set autocenter.
   274  *  \brief Device can set autocenter.
   277  *  
   275  *
   278  *  Device supports setting autocenter.
   276  *  Device supports setting autocenter.
   279  *  
   277  *
   280  *  \sa SDL_HapticSetAutocenter
   278  *  \sa SDL_HapticSetAutocenter
   281  */
   279  */
   282 #define SDL_HAPTIC_AUTOCENTER (1<<13)
   280 #define SDL_HAPTIC_AUTOCENTER (1<<13)
   283 
   281 
   284 /**
   282 /**
   285  *  \brief Device can be queried for effect status.
   283  *  \brief Device can be queried for effect status.
   286  *  
   284  *
   287  *  Device can be queried for effect status.
   285  *  Device can be queried for effect status.
   288  *  
   286  *
   289  *  \sa SDL_HapticGetEffectStatus
   287  *  \sa SDL_HapticGetEffectStatus
   290  */
   288  */
   291 #define SDL_HAPTIC_STATUS     (1<<14)
   289 #define SDL_HAPTIC_STATUS     (1<<14)
   292 
   290 
   293 /**
   291 /**
   294  *  \brief Device can be paused.
   292  *  \brief Device can be paused.
   295  *  
   293  *
   296  *  \sa SDL_HapticPause
   294  *  \sa SDL_HapticPause
   297  *  \sa SDL_HapticUnpause
   295  *  \sa SDL_HapticUnpause
   298  */
   296  */
   299 #define SDL_HAPTIC_PAUSE      (1<<15)
   297 #define SDL_HAPTIC_PAUSE      (1<<15)
   300 
   298 
   304  */
   302  */
   305 /*@{*/
   303 /*@{*/
   306 
   304 
   307 /**
   305 /**
   308  *  \brief Uses polar coordinates for the direction.
   306  *  \brief Uses polar coordinates for the direction.
   309  *  
   307  *
   310  *  \sa SDL_HapticDirection
   308  *  \sa SDL_HapticDirection
   311  */
   309  */
   312 #define SDL_HAPTIC_POLAR      0
   310 #define SDL_HAPTIC_POLAR      0
   313 
   311 
   314 /**
   312 /**
   315  *  \brief Uses cartesian coordinates for the direction.
   313  *  \brief Uses cartesian coordinates for the direction.
   316  *  
   314  *
   317  *  \sa SDL_HapticDirection
   315  *  \sa SDL_HapticDirection
   318  */
   316  */
   319 #define SDL_HAPTIC_CARTESIAN  1
   317 #define SDL_HAPTIC_CARTESIAN  1
   320 
   318 
   321 /**
   319 /**
   322  *  \brief Uses spherical coordinates for the direction.
   320  *  \brief Uses spherical coordinates for the direction.
   323  *  
   321  *
   324  *  \sa SDL_HapticDirection
   322  *  \sa SDL_HapticDirection
   325  */
   323  */
   326 #define SDL_HAPTIC_SPHERICAL  2
   324 #define SDL_HAPTIC_SPHERICAL  2
   327 
   325 
   328 /*@}*//*Direction encodings*/
   326 /*@}*//*Direction encodings*/
   341 #define SDL_HAPTIC_INFINITY   4294967295U
   339 #define SDL_HAPTIC_INFINITY   4294967295U
   342 
   340 
   343 
   341 
   344 /**
   342 /**
   345  *  \brief Structure that represents a haptic direction.
   343  *  \brief Structure that represents a haptic direction.
   346  *  
   344  *
   347  *  Directions can be specified by:
   345  *  Directions can be specified by:
   348  *   - ::SDL_HAPTIC_POLAR : Specified by polar coordinates.
   346  *   - ::SDL_HAPTIC_POLAR : Specified by polar coordinates.
   349  *   - ::SDL_HAPTIC_CARTESIAN : Specified by cartesian coordinates.
   347  *   - ::SDL_HAPTIC_CARTESIAN : Specified by cartesian coordinates.
   350  *   - ::SDL_HAPTIC_SPHERICAL : Specified by spherical coordinates.
   348  *   - ::SDL_HAPTIC_SPHERICAL : Specified by spherical coordinates.
   351  *
   349  *
   359                  |=.| |.-----.|
   357                  |=.| |.-----.|
   360                  |--| ||     ||
   358                  |--| ||     ||
   361                  |  | |'-----'|
   359                  |  | |'-----'|
   362                  |__|~')_____('
   360                  |__|~')_____('
   363                    [ COMPUTER ]
   361                    [ COMPUTER ]
   364     
   362 
   365     
   363 
   366                      North (0,-1)
   364                      North (0,-1)
   367                          ^
   365                          ^
   368                          |
   366                          |
   369                          |
   367                          |
   370     (1,0)  West <----[ HAPTIC ]----> East (-1,0)
   368     (1,0)  West <----[ HAPTIC ]----> East (-1,0)
   371                          |
   369                          |
   372                          |
   370                          |
   373                          v
   371                          v
   374                       South (0,1)
   372                       South (0,1)
   375     
   373 
   376     
   374 
   377                       [ USER ]
   375                       [ USER ]
   378                         \|||/
   376                         \|||/
   379                         (o o)
   377                         (o o)
   380                   ---ooO-(_)-Ooo---
   378                   ---ooO-(_)-Ooo---
   381     \endverbatim
   379     \endverbatim
   382  *  
   380  *
   383  *  If type is ::SDL_HAPTIC_POLAR, direction is encoded by hundredths of a 
   381  *  If type is ::SDL_HAPTIC_POLAR, direction is encoded by hundredths of a
   384  *  degree starting north and turning clockwise.  ::SDL_HAPTIC_POLAR only uses
   382  *  degree starting north and turning clockwise.  ::SDL_HAPTIC_POLAR only uses
   385  *  the first \c dir parameter.  The cardinal directions would be:
   383  *  the first \c dir parameter.  The cardinal directions would be:
   386  *   - North: 0 (0 degrees)
   384  *   - North: 0 (0 degrees)
   387  *   - East: 9000 (90 degrees)
   385  *   - East: 9000 (90 degrees)
   388  *   - South: 18000 (180 degrees)
   386  *   - South: 18000 (180 degrees)
   389  *   - West: 27000 (270 degrees)
   387  *   - West: 27000 (270 degrees)
   390  *  
   388  *
   391  *  If type is ::SDL_HAPTIC_CARTESIAN, direction is encoded by three positions
   389  *  If type is ::SDL_HAPTIC_CARTESIAN, direction is encoded by three positions
   392  *  (X axis, Y axis and Z axis (with 3 axes)).  ::SDL_HAPTIC_CARTESIAN uses
   390  *  (X axis, Y axis and Z axis (with 3 axes)).  ::SDL_HAPTIC_CARTESIAN uses
   393  *  the first three \c dir parameters.  The cardinal directions would be:
   391  *  the first three \c dir parameters.  The cardinal directions would be:
   394  *   - North:  0,-1, 0
   392  *   - North:  0,-1, 0
   395  *   - East:  -1, 0, 0
   393  *   - East:  -1, 0, 0
   396  *   - South:  0, 1, 0
   394  *   - South:  0, 1, 0
   397  *   - West:   1, 0, 0
   395  *   - West:   1, 0, 0
   398  *  
   396  *
   399  *  The Z axis represents the height of the effect if supported, otherwise
   397  *  The Z axis represents the height of the effect if supported, otherwise
   400  *  it's unused.  In cartesian encoding (1, 2) would be the same as (2, 4), you
   398  *  it's unused.  In cartesian encoding (1, 2) would be the same as (2, 4), you
   401  *  can use any multiple you want, only the direction matters.
   399  *  can use any multiple you want, only the direction matters.
   402  *  
   400  *
   403  *  If type is ::SDL_HAPTIC_SPHERICAL, direction is encoded by two rotations.
   401  *  If type is ::SDL_HAPTIC_SPHERICAL, direction is encoded by two rotations.
   404  *  The first two \c dir parameters are used.  The \c dir parameters are as 
   402  *  The first two \c dir parameters are used.  The \c dir parameters are as
   405  *  follows (all values are in hundredths of degrees):
   403  *  follows (all values are in hundredths of degrees):
   406  *   - Degrees from (1, 0) rotated towards (0, 1).
   404  *   - Degrees from (1, 0) rotated towards (0, 1).
   407  *   - Degrees towards (0, 0, 1) (device needs at least 3 axes).
   405  *   - Degrees towards (0, 0, 1) (device needs at least 3 axes).
   408  *
   406  *
   409  *
   407  *
   410  *  Example of force coming from the south with all encodings (force coming
   408  *  Example of force coming from the south with all encodings (force coming
   411  *  from the south means the user will have to pull the stick to counteract):
   409  *  from the south means the user will have to pull the stick to counteract):
   412  *  \code
   410  *  \code
   413  *  SDL_HapticDirection direction;
   411  *  SDL_HapticDirection direction;
   414  *  
   412  *
   415  *  // Cartesian directions
   413  *  // Cartesian directions
   416  *  direction.type = SDL_HAPTIC_CARTESIAN; // Using cartesian direction encoding.
   414  *  direction.type = SDL_HAPTIC_CARTESIAN; // Using cartesian direction encoding.
   417  *  direction.dir[0] = 0; // X position
   415  *  direction.dir[0] = 0; // X position
   418  *  direction.dir[1] = 1; // Y position
   416  *  direction.dir[1] = 1; // Y position
   419  *  // Assuming the device has 2 axes, we don't need to specify third parameter.
   417  *  // Assuming the device has 2 axes, we don't need to specify third parameter.
   420  *  
   418  *
   421  *  // Polar directions
   419  *  // Polar directions
   422  *  direction.type = SDL_HAPTIC_POLAR; // We'll be using polar direction encoding.
   420  *  direction.type = SDL_HAPTIC_POLAR; // We'll be using polar direction encoding.
   423  *  direction.dir[0] = 18000; // Polar only uses first parameter
   421  *  direction.dir[0] = 18000; // Polar only uses first parameter
   424  *  
   422  *
   425  *  // Spherical coordinates
   423  *  // Spherical coordinates
   426  *  direction.type = SDL_HAPTIC_SPHERICAL; // Spherical encoding
   424  *  direction.type = SDL_HAPTIC_SPHERICAL; // Spherical encoding
   427  *  direction.dir[0] = 9000; // Since we only have two axes we don't need more parameters.
   425  *  direction.dir[0] = 9000; // Since we only have two axes we don't need more parameters.
   428  *  \endcode
   426  *  \endcode
   429  *
   427  *
   440 } SDL_HapticDirection;
   438 } SDL_HapticDirection;
   441 
   439 
   442 
   440 
   443 /**
   441 /**
   444  *  \brief A structure containing a template for a Constant effect.
   442  *  \brief A structure containing a template for a Constant effect.
   445  *  
   443  *
   446  *  The struct is exclusive to the ::SDL_HAPTIC_CONSTANT effect.
   444  *  The struct is exclusive to the ::SDL_HAPTIC_CONSTANT effect.
   447  *  
   445  *
   448  *  A constant effect applies a constant force in the specified direction
   446  *  A constant effect applies a constant force in the specified direction
   449  *  to the joystick.
   447  *  to the joystick.
   450  *  
   448  *
   451  *  \sa SDL_HAPTIC_CONSTANT
   449  *  \sa SDL_HAPTIC_CONSTANT
   452  *  \sa SDL_HapticEffect
   450  *  \sa SDL_HapticEffect
   453  */
   451  */
   454 typedef struct SDL_HapticConstant
   452 typedef struct SDL_HapticConstant
   455 {
   453 {
   475     Uint16 fade_level;      /**< Level at the end of the fade. */
   473     Uint16 fade_level;      /**< Level at the end of the fade. */
   476 } SDL_HapticConstant;
   474 } SDL_HapticConstant;
   477 
   475 
   478 /**
   476 /**
   479  *  \brief A structure containing a template for a Periodic effect.
   477  *  \brief A structure containing a template for a Periodic effect.
   480  *  
   478  *
   481  *  The struct handles the following effects:
   479  *  The struct handles the following effects:
   482  *   - ::SDL_HAPTIC_SINE
   480  *   - ::SDL_HAPTIC_SINE
   483  *   - ::SDL_HAPTIC_SQUARE
   481  *   - ::SDL_HAPTIC_SQUARE
   484  *   - ::SDL_HAPTIC_TRIANGLE
   482  *   - ::SDL_HAPTIC_TRIANGLE
   485  *   - ::SDL_HAPTIC_SAWTOOTHUP
   483  *   - ::SDL_HAPTIC_SAWTOOTHUP
   486  *   - ::SDL_HAPTIC_SAWTOOTHDOWN
   484  *   - ::SDL_HAPTIC_SAWTOOTHDOWN
   487  *  
   485  *
   488  *  A periodic effect consists in a wave-shaped effect that repeats itself
   486  *  A periodic effect consists in a wave-shaped effect that repeats itself
   489  *  over time.  The type determines the shape of the wave and the parameters
   487  *  over time.  The type determines the shape of the wave and the parameters
   490  *  determine the dimensions of the wave.
   488  *  determine the dimensions of the wave.
   491  *  
   489  *
   492  *  Phase is given by hundredth of a cycle meaning that giving the phase a value
   490  *  Phase is given by hundredth of a cycle meaning that giving the phase a value
   493  *  of 9000 will displace it 25% of its period.  Here are sample values:
   491  *  of 9000 will displace it 25% of its period.  Here are sample values:
   494  *   -     0: No phase displacement.
   492  *   -     0: No phase displacement.
   495  *   -  9000: Displaced 25% of its period.
   493  *   -  9000: Displaced 25% of its period.
   496  *   - 18000: Displaced 50% of its period.
   494  *   - 18000: Displaced 50% of its period.
   501  *  \verbatim
   499  *  \verbatim
   502     SDL_HAPTIC_SINE
   500     SDL_HAPTIC_SINE
   503       __      __      __      __
   501       __      __      __      __
   504      /  \    /  \    /  \    /
   502      /  \    /  \    /  \    /
   505     /    \__/    \__/    \__/
   503     /    \__/    \__/    \__/
   506     
   504 
   507     SDL_HAPTIC_SQUARE
   505     SDL_HAPTIC_SQUARE
   508      __    __    __    __    __
   506      __    __    __    __    __
   509     |  |  |  |  |  |  |  |  |  |
   507     |  |  |  |  |  |  |  |  |  |
   510     |  |__|  |__|  |__|  |__|  |
   508     |  |__|  |__|  |__|  |__|  |
   511     
   509 
   512     SDL_HAPTIC_TRIANGLE
   510     SDL_HAPTIC_TRIANGLE
   513       /\    /\    /\    /\    /\
   511       /\    /\    /\    /\    /\
   514      /  \  /  \  /  \  /  \  /
   512      /  \  /  \  /  \  /  \  /
   515     /    \/    \/    \/    \/
   513     /    \/    \/    \/    \/
   516     
   514 
   517     SDL_HAPTIC_SAWTOOTHUP
   515     SDL_HAPTIC_SAWTOOTHUP
   518       /|  /|  /|  /|  /|  /|  /|
   516       /|  /|  /|  /|  /|  /|  /|
   519      / | / | / | / | / | / | / |
   517      / | / | / | / | / | / | / |
   520     /  |/  |/  |/  |/  |/  |/  |
   518     /  |/  |/  |/  |/  |/  |/  |
   521     
   519 
   522     SDL_HAPTIC_SAWTOOTHDOWN
   520     SDL_HAPTIC_SAWTOOTHDOWN
   523     \  |\  |\  |\  |\  |\  |\  |
   521     \  |\  |\  |\  |\  |\  |\  |
   524      \ | \ | \ | \ | \ | \ | \ |
   522      \ | \ | \ | \ | \ | \ | \ |
   525       \|  \|  \|  \|  \|  \|  \|
   523       \|  \|  \|  \|  \|  \|  \|
   526     \endverbatim
   524     \endverbatim
   527  *  
   525  *
   528  *  \sa SDL_HAPTIC_SINE
   526  *  \sa SDL_HAPTIC_SINE
   529  *  \sa SDL_HAPTIC_SQUARE
   527  *  \sa SDL_HAPTIC_SQUARE
   530  *  \sa SDL_HAPTIC_TRIANGLE
   528  *  \sa SDL_HAPTIC_TRIANGLE
   531  *  \sa SDL_HAPTIC_SAWTOOTHUP
   529  *  \sa SDL_HAPTIC_SAWTOOTHUP
   532  *  \sa SDL_HAPTIC_SAWTOOTHDOWN
   530  *  \sa SDL_HAPTIC_SAWTOOTHDOWN
   561     Uint16 fade_level;  /**< Level at the end of the fade. */
   559     Uint16 fade_level;  /**< Level at the end of the fade. */
   562 } SDL_HapticPeriodic;
   560 } SDL_HapticPeriodic;
   563 
   561 
   564 /**
   562 /**
   565  *  \brief A structure containing a template for a Condition effect.
   563  *  \brief A structure containing a template for a Condition effect.
   566  *  
   564  *
   567  *  The struct handles the following effects:
   565  *  The struct handles the following effects:
   568  *   - ::SDL_HAPTIC_SPRING: Effect based on axes position.
   566  *   - ::SDL_HAPTIC_SPRING: Effect based on axes position.
   569  *   - ::SDL_HAPTIC_DAMPER: Effect based on axes velocity.
   567  *   - ::SDL_HAPTIC_DAMPER: Effect based on axes velocity.
   570  *   - ::SDL_HAPTIC_INERTIA: Effect based on axes acceleration.
   568  *   - ::SDL_HAPTIC_INERTIA: Effect based on axes acceleration.
   571  *   - ::SDL_HAPTIC_FRICTION: Effect based on axes movement.
   569  *   - ::SDL_HAPTIC_FRICTION: Effect based on axes movement.
   572  *  
   570  *
   573  *  Direction is handled by condition internals instead of a direction member.
   571  *  Direction is handled by condition internals instead of a direction member.
   574  *  The condition effect specific members have three parameters.  The first
   572  *  The condition effect specific members have three parameters.  The first
   575  *  refers to the X axis, the second refers to the Y axis and the third
   573  *  refers to the X axis, the second refers to the Y axis and the third
   576  *  refers to the Z axis.  The right terms refer to the positive side of the
   574  *  refers to the Z axis.  The right terms refer to the positive side of the
   577  *  axis and the left terms refer to the negative side of the axis.  Please 
   575  *  axis and the left terms refer to the negative side of the axis.  Please
   578  *  refer to the ::SDL_HapticDirection diagram for which side is positive and
   576  *  refer to the ::SDL_HapticDirection diagram for which side is positive and
   579  *  which is negative.
   577  *  which is negative.
   580  *  
   578  *
   581  *  \sa SDL_HapticDirection
   579  *  \sa SDL_HapticDirection
   582  *  \sa SDL_HAPTIC_SPRING
   580  *  \sa SDL_HAPTIC_SPRING
   583  *  \sa SDL_HAPTIC_DAMPER
   581  *  \sa SDL_HAPTIC_DAMPER
   584  *  \sa SDL_HAPTIC_INERTIA
   582  *  \sa SDL_HAPTIC_INERTIA
   585  *  \sa SDL_HAPTIC_FRICTION
   583  *  \sa SDL_HAPTIC_FRICTION
   609     Sint16 center[3];       /**< Position of the dead zone. */
   607     Sint16 center[3];       /**< Position of the dead zone. */
   610 } SDL_HapticCondition;
   608 } SDL_HapticCondition;
   611 
   609 
   612 /**
   610 /**
   613  *  \brief A structure containing a template for a Ramp effect.
   611  *  \brief A structure containing a template for a Ramp effect.
   614  *  
   612  *
   615  *  This struct is exclusively for the ::SDL_HAPTIC_RAMP effect.
   613  *  This struct is exclusively for the ::SDL_HAPTIC_RAMP effect.
   616  *  
   614  *
   617  *  The ramp effect starts at start strength and ends at end strength.
   615  *  The ramp effect starts at start strength and ends at end strength.
   618  *  It augments in linear fashion.  If you use attack and fade with a ramp
   616  *  It augments in linear fashion.  If you use attack and fade with a ramp
   619  *  they effects get added to the ramp effect making the effect become
   617  *  they effects get added to the ramp effect making the effect become
   620  *  quadratic instead of linear.
   618  *  quadratic instead of linear.
   621  *  
   619  *
   622  *  \sa SDL_HAPTIC_RAMP
   620  *  \sa SDL_HAPTIC_RAMP
   623  *  \sa SDL_HapticEffect
   621  *  \sa SDL_HapticEffect
   624  */
   622  */
   625 typedef struct SDL_HapticRamp
   623 typedef struct SDL_HapticRamp
   626 {
   624 {
   647     Uint16 fade_level;      /**< Level at the end of the fade. */
   645     Uint16 fade_level;      /**< Level at the end of the fade. */
   648 } SDL_HapticRamp;
   646 } SDL_HapticRamp;
   649 
   647 
   650 /**
   648 /**
   651  *  \brief A structure containing a template for the ::SDL_HAPTIC_CUSTOM effect.
   649  *  \brief A structure containing a template for the ::SDL_HAPTIC_CUSTOM effect.
   652  *  
   650  *
   653  *  A custom force feedback effect is much like a periodic effect, where the
   651  *  A custom force feedback effect is much like a periodic effect, where the
   654  *  application can define its exact shape.  You will have to allocate the
   652  *  application can define its exact shape.  You will have to allocate the
   655  *  data yourself.  Data should consist of channels * samples Uint16 samples.
   653  *  data yourself.  Data should consist of channels * samples Uint16 samples.
   656  *  
   654  *
   657  *  If channels is one, the effect is rotated using the defined direction.
   655  *  If channels is one, the effect is rotated using the defined direction.
   658  *  Otherwise it uses the samples in data for the different axes.
   656  *  Otherwise it uses the samples in data for the different axes.
   659  *  
   657  *
   660  *  \sa SDL_HAPTIC_CUSTOM
   658  *  \sa SDL_HAPTIC_CUSTOM
   661  *  \sa SDL_HapticEffect
   659  *  \sa SDL_HapticEffect
   662  */
   660  */
   663 typedef struct SDL_HapticCustom
   661 typedef struct SDL_HapticCustom
   664 {
   662 {
   687     Uint16 fade_level;      /**< Level at the end of the fade. */
   685     Uint16 fade_level;      /**< Level at the end of the fade. */
   688 } SDL_HapticCustom;
   686 } SDL_HapticCustom;
   689 
   687 
   690 /**
   688 /**
   691  *  \brief The generic template for any haptic effect.
   689  *  \brief The generic template for any haptic effect.
   692  *  
   690  *
   693  *  All values max at 32767 (0x7FFF).  Signed values also can be negative.
   691  *  All values max at 32767 (0x7FFF).  Signed values also can be negative.
   694  *  Time values unless specified otherwise are in milliseconds.
   692  *  Time values unless specified otherwise are in milliseconds.
   695  *  
   693  *
   696  *  You can also pass ::SDL_HAPTIC_INFINITY to length instead of a 0-32767 
   694  *  You can also pass ::SDL_HAPTIC_INFINITY to length instead of a 0-32767
   697  *  value.  Neither delay, interval, attack_length nor fade_length support 
   695  *  value.  Neither delay, interval, attack_length nor fade_length support
   698  *  ::SDL_HAPTIC_INFINITY.  Fade will also not be used since effect never ends.
   696  *  ::SDL_HAPTIC_INFINITY.  Fade will also not be used since effect never ends.
   699  *  
   697  *
   700  *  Additionally, the ::SDL_HAPTIC_RAMP effect does not support a duration of
   698  *  Additionally, the ::SDL_HAPTIC_RAMP effect does not support a duration of
   701  *  ::SDL_HAPTIC_INFINITY.
   699  *  ::SDL_HAPTIC_INFINITY.
   702  *  
   700  *
   703  *  Button triggers may not be supported on all devices, it is advised to not
   701  *  Button triggers may not be supported on all devices, it is advised to not
   704  *  use them if possible.  Buttons start at index 1 instead of index 0 like
   702  *  use them if possible.  Buttons start at index 1 instead of index 0 like
   705  *  they joystick.
   703  *  they joystick.
   706  *  
   704  *
   707  *  If both attack_length and fade_level are 0, the envelope is not used,
   705  *  If both attack_length and fade_level are 0, the envelope is not used,
   708  *  otherwise both values are used.
   706  *  otherwise both values are used.
   709  *  
   707  *
   710  *  Common parts:
   708  *  Common parts:
   711  *  \code
   709  *  \code
   712  *  // Replay - All effects have this
   710  *  // Replay - All effects have this
   713  *  Uint32 length;        // Duration of effect (ms).
   711  *  Uint32 length;        // Duration of effect (ms).
   714  *  Uint16 delay;         // Delay before starting effect.
   712  *  Uint16 delay;         // Delay before starting effect.
   715  *  
   713  *
   716  *  // Trigger - All effects have this
   714  *  // Trigger - All effects have this
   717  *  Uint16 button;        // Button that triggers effect.
   715  *  Uint16 button;        // Button that triggers effect.
   718  *  Uint16 interval;      // How soon before effect can be triggered again.
   716  *  Uint16 interval;      // How soon before effect can be triggered again.
   719  *  
   717  *
   720  *  // Envelope - All effects except condition effects have this
   718  *  // Envelope - All effects except condition effects have this
   721  *  Uint16 attack_length; // Duration of the attack (ms).
   719  *  Uint16 attack_length; // Duration of the attack (ms).
   722  *  Uint16 attack_level;  // Level at the start of the attack.
   720  *  Uint16 attack_level;  // Level at the start of the attack.
   723  *  Uint16 fade_length;   // Duration of the fade out (ms).
   721  *  Uint16 fade_length;   // Duration of the fade out (ms).
   724  *  Uint16 fade_level;    // Level at the end of the fade.
   722  *  Uint16 fade_level;    // Level at the end of the fade.
   732     |
   730     |
   733     |    effect level -->  _________________
   731     |    effect level -->  _________________
   734     |                     /                 \
   732     |                     /                 \
   735     |                    /                   \
   733     |                    /                   \
   736     |                   /                     \
   734     |                   /                     \
   737     |                  /                       \ 
   735     |                  /                       \
   738     | attack_level --> |                        \
   736     | attack_level --> |                        \
   739     |                  |                        |  <---  fade_level
   737     |                  |                        |  <---  fade_level
   740     |
   738     |
   741     +--------------------------------------------------> Time
   739     +--------------------------------------------------> Time
   742                        [--]                 [---]
   740                        [--]                 [---]
   743                        attack_length        fade_length
   741                        attack_length        fade_length
   744     
   742 
   745     [------------------][-----------------------]
   743     [------------------][-----------------------]
   746     delay               length
   744     delay               length
   747     \endverbatim
   745     \endverbatim
   748  *  
   746  *
   749  *  Note either the attack_level or the fade_level may be above the actual
   747  *  Note either the attack_level or the fade_level may be above the actual
   750  *  effect level.
   748  *  effect level.
   751  *
   749  *
   752  *  \sa SDL_HapticConstant
   750  *  \sa SDL_HapticConstant
   753  *  \sa SDL_HapticPeriodic
   751  *  \sa SDL_HapticPeriodic
   768 
   766 
   769 
   767 
   770 /* Function prototypes */
   768 /* Function prototypes */
   771 /**
   769 /**
   772  *  \brief Count the number of joysticks attached to the system.
   770  *  \brief Count the number of joysticks attached to the system.
   773  *  
   771  *
   774  *  \return Number of haptic devices detected on the system.
   772  *  \return Number of haptic devices detected on the system.
   775  */
   773  */
   776 extern DECLSPEC int SDLCALL SDL_NumHaptics(void);
   774 extern DECLSPEC int SDLCALL SDL_NumHaptics(void);
   777 
   775 
   778 /**
   776 /**
   779  *  \brief Get the implementation dependent name of a Haptic device.
   777  *  \brief Get the implementation dependent name of a Haptic device.
   780  *  
   778  *
   781  *  This can be called before any joysticks are opened.
   779  *  This can be called before any joysticks are opened.
   782  *  If no name can be found, this function returns NULL.
   780  *  If no name can be found, this function returns NULL.
   783  *  
   781  *
   784  *  \param device_index Index of the device to get its name.
   782  *  \param device_index Index of the device to get its name.
   785  *  \return Name of the device or NULL on error.
   783  *  \return Name of the device or NULL on error.
   786  *
   784  *
   787  *  \sa SDL_NumHaptics
   785  *  \sa SDL_NumHaptics
   788  */
   786  */
   789 extern DECLSPEC const char *SDLCALL SDL_HapticName(int device_index);
   787 extern DECLSPEC const char *SDLCALL SDL_HapticName(int device_index);
   790 
   788 
   791 /**
   789 /**
   792  *  \brief Opens a Haptic device for usage.
   790  *  \brief Opens a Haptic device for usage.
   793  *  
   791  *
   794  *  The index passed as an argument refers to the N'th Haptic device on this 
   792  *  The index passed as an argument refers to the N'th Haptic device on this
   795  *  system.
   793  *  system.
   796  *
   794  *
   797  *  When opening a haptic device, its gain will be set to maximum and
   795  *  When opening a haptic device, its gain will be set to maximum and
   798  *  autocenter will be disabled.  To modify these values use
   796  *  autocenter will be disabled.  To modify these values use
   799  *  SDL_HapticSetGain() and SDL_HapticSetAutocenter().
   797  *  SDL_HapticSetGain() and SDL_HapticSetAutocenter().
   812  */
   810  */
   813 extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpen(int device_index);
   811 extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpen(int device_index);
   814 
   812 
   815 /**
   813 /**
   816  *  \brief Checks if the haptic device at index has been opened.
   814  *  \brief Checks if the haptic device at index has been opened.
   817  *  
   815  *
   818  *  \param device_index Index to check to see if it has been opened.
   816  *  \param device_index Index to check to see if it has been opened.
   819  *  \return 1 if it has been opened or 0 if it hasn't.
   817  *  \return 1 if it has been opened or 0 if it hasn't.
   820  *  
   818  *
   821  *  \sa SDL_HapticOpen
   819  *  \sa SDL_HapticOpen
   822  *  \sa SDL_HapticIndex
   820  *  \sa SDL_HapticIndex
   823  */
   821  */
   824 extern DECLSPEC int SDLCALL SDL_HapticOpened(int device_index);
   822 extern DECLSPEC int SDLCALL SDL_HapticOpened(int device_index);
   825 
   823 
   826 /**
   824 /**
   827  *  \brief Gets the index of a haptic device.
   825  *  \brief Gets the index of a haptic device.
   828  *  
   826  *
   829  *  \param haptic Haptic device to get the index of.
   827  *  \param haptic Haptic device to get the index of.
   830  *  \return The index of the haptic device or -1 on error.
   828  *  \return The index of the haptic device or -1 on error.
   831  *  
   829  *
   832  *  \sa SDL_HapticOpen
   830  *  \sa SDL_HapticOpen
   833  *  \sa SDL_HapticOpened
   831  *  \sa SDL_HapticOpened
   834  */
   832  */
   835 extern DECLSPEC int SDLCALL SDL_HapticIndex(SDL_Haptic * haptic);
   833 extern DECLSPEC int SDLCALL SDL_HapticIndex(SDL_Haptic * haptic);
   836 
   834 
   837 /**
   835 /**
   838  *  \brief Gets whether or not the current mouse has haptic capabilities.
   836  *  \brief Gets whether or not the current mouse has haptic capabilities.
   839  *  
   837  *
   840  *  \return SDL_TRUE if the mouse is haptic, SDL_FALSE if it isn't.
   838  *  \return SDL_TRUE if the mouse is haptic, SDL_FALSE if it isn't.
   841  *  
   839  *
   842  *  \sa SDL_HapticOpenFromMouse
   840  *  \sa SDL_HapticOpenFromMouse
   843  */
   841  */
   844 extern DECLSPEC int SDLCALL SDL_MouseIsHaptic(void);
   842 extern DECLSPEC int SDLCALL SDL_MouseIsHaptic(void);
   845 
   843 
   846 /**
   844 /**
   847  *  \brief Tries to open a haptic device from the current mouse.
   845  *  \brief Tries to open a haptic device from the current mouse.
   848  *  
   846  *
   849  *  \return The haptic device identifier or NULL on error.
   847  *  \return The haptic device identifier or NULL on error.
   850  *  
   848  *
   851  *  \sa SDL_MouseIsHaptic
   849  *  \sa SDL_MouseIsHaptic
   852  *  \sa SDL_HapticOpen
   850  *  \sa SDL_HapticOpen
   853  */
   851  */
   854 extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromMouse(void);
   852 extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromMouse(void);
   855 
   853 
   856 /**
   854 /**
   857  *  \brief Checks to see if a joystick has haptic features.
   855  *  \brief Checks to see if a joystick has haptic features.
   858  *  
   856  *
   859  *  \param joystick Joystick to test for haptic capabilities.
   857  *  \param joystick Joystick to test for haptic capabilities.
   860  *  \return 1 if the joystick is haptic, 0 if it isn't
   858  *  \return 1 if the joystick is haptic, 0 if it isn't
   861  *          or -1 if an error ocurred.
   859  *          or -1 if an error ocurred.
   862  *  
   860  *
   863  *  \sa SDL_HapticOpenFromJoystick
   861  *  \sa SDL_HapticOpenFromJoystick
   864  */
   862  */
   865 extern DECLSPEC int SDLCALL SDL_JoystickIsHaptic(SDL_Joystick * joystick);
   863 extern DECLSPEC int SDLCALL SDL_JoystickIsHaptic(SDL_Joystick * joystick);
   866 
   864 
   867 /**
   865 /**
   868  *  \brief Opens a Haptic device for usage from a Joystick device.
   866  *  \brief Opens a Haptic device for usage from a Joystick device.
   869  *  
   867  *
   870  *  You must still close the haptic device seperately.  It will not be closed 
   868  *  You must still close the haptic device seperately.  It will not be closed
   871  *  with the joystick.
   869  *  with the joystick.
   872  *  
   870  *
   873  *  When opening from a joystick you should first close the haptic device before
   871  *  When opening from a joystick you should first close the haptic device before
   874  *  closing the joystick device.  If not, on some implementations the haptic
   872  *  closing the joystick device.  If not, on some implementations the haptic
   875  *  device will also get unallocated and you'll be unable to use force feedback
   873  *  device will also get unallocated and you'll be unable to use force feedback
   876  *  on that device.
   874  *  on that device.
   877  *  
   875  *
   878  *  \param joystick Joystick to create a haptic device from.
   876  *  \param joystick Joystick to create a haptic device from.
   879  *  \return A valid haptic device identifier on success or NULL on error.
   877  *  \return A valid haptic device identifier on success or NULL on error.
   880  *  
   878  *
   881  *  \sa SDL_HapticOpen
   879  *  \sa SDL_HapticOpen
   882  *  \sa SDL_HapticClose
   880  *  \sa SDL_HapticClose
   883  */
   881  */
   884 extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromJoystick(SDL_Joystick *
   882 extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromJoystick(SDL_Joystick *
   885                                                                joystick);
   883                                                                joystick);
   886 
   884 
   887 /**
   885 /**
   888  *  \brief Closes a Haptic device previously opened with SDL_HapticOpen().
   886  *  \brief Closes a Haptic device previously opened with SDL_HapticOpen().
   889  *  
   887  *
   890  *  \param haptic Haptic device to close.
   888  *  \param haptic Haptic device to close.
   891  */
   889  */
   892 extern DECLSPEC void SDLCALL SDL_HapticClose(SDL_Haptic * haptic);
   890 extern DECLSPEC void SDLCALL SDL_HapticClose(SDL_Haptic * haptic);
   893 
   891 
   894 /**
   892 /**
   895  *  \brief Returns the number of effects a haptic device can store.
   893  *  \brief Returns the number of effects a haptic device can store.
   896  *  
   894  *
   897  *  On some platforms this isn't fully supported, and therefore is an
   895  *  On some platforms this isn't fully supported, and therefore is an
   898  *  approximation.  Always check to see if your created effect was actually
   896  *  approximation.  Always check to see if your created effect was actually
   899  *  created and do not rely solely on SDL_HapticNumEffects().
   897  *  created and do not rely solely on SDL_HapticNumEffects().
   900  *  
   898  *
   901  *  \param haptic The haptic device to query effect max.
   899  *  \param haptic The haptic device to query effect max.
   902  *  \return The number of effects the haptic device can store or
   900  *  \return The number of effects the haptic device can store or
   903  *          -1 on error.
   901  *          -1 on error.
   904  *  
   902  *
   905  *  \sa SDL_HapticNumEffectsPlaying
   903  *  \sa SDL_HapticNumEffectsPlaying
   906  *  \sa SDL_HapticQuery
   904  *  \sa SDL_HapticQuery
   907  */
   905  */
   908 extern DECLSPEC int SDLCALL SDL_HapticNumEffects(SDL_Haptic * haptic);
   906 extern DECLSPEC int SDLCALL SDL_HapticNumEffects(SDL_Haptic * haptic);
   909 
   907 
   910 /**
   908 /**
   911  *  \brief Returns the number of effects a haptic device can play at the same 
   909  *  \brief Returns the number of effects a haptic device can play at the same
   912  *         time.
   910  *         time.
   913  *  
   911  *
   914  *  This is not supported on all platforms, but will always return a value.  
   912  *  This is not supported on all platforms, but will always return a value.
   915  *  Added here for the sake of completeness.
   913  *  Added here for the sake of completeness.
   916  *  
   914  *
   917  *  \param haptic The haptic device to query maximum playing effects.
   915  *  \param haptic The haptic device to query maximum playing effects.
   918  *  \return The number of effects the haptic device can play at the same time
   916  *  \return The number of effects the haptic device can play at the same time
   919  *          or -1 on error.
   917  *          or -1 on error.
   920  *
   918  *
   921  *  \sa SDL_HapticNumEffects
   919  *  \sa SDL_HapticNumEffects
   923  */
   921  */
   924 extern DECLSPEC int SDLCALL SDL_HapticNumEffectsPlaying(SDL_Haptic * haptic);
   922 extern DECLSPEC int SDLCALL SDL_HapticNumEffectsPlaying(SDL_Haptic * haptic);
   925 
   923 
   926 /**
   924 /**
   927  *  \brief Gets the haptic devices supported features in bitwise matter.
   925  *  \brief Gets the haptic devices supported features in bitwise matter.
   928  *  
   926  *
   929  *  Example: 
   927  *  Example:
   930  *  \code
   928  *  \code
   931  *  if (SDL_HapticQueryEffects(haptic) & SDL_HAPTIC_CONSTANT) {
   929  *  if (SDL_HapticQueryEffects(haptic) & SDL_HAPTIC_CONSTANT) {
   932  *      printf("We have constant haptic effect!");
   930  *      printf("We have constant haptic effect!");
   933  *  }
   931  *  }
   934  *  \endcode
   932  *  \endcode
   935  *  
   933  *
   936  *  \param haptic The haptic device to query.
   934  *  \param haptic The haptic device to query.
   937  *  \return Haptic features in bitwise manner (OR'd).
   935  *  \return Haptic features in bitwise manner (OR'd).
   938  *  
   936  *
   939  *  \sa SDL_HapticNumEffects
   937  *  \sa SDL_HapticNumEffects
   940  *  \sa SDL_HapticEffectSupported
   938  *  \sa SDL_HapticEffectSupported
   941  */
   939  */
   942 extern DECLSPEC unsigned int SDLCALL SDL_HapticQuery(SDL_Haptic * haptic);
   940 extern DECLSPEC unsigned int SDLCALL SDL_HapticQuery(SDL_Haptic * haptic);
   943 
   941 
   944 
   942 
   945 /**
   943 /**
   946  *  \brief Gets the number of haptic axes the device has.
   944  *  \brief Gets the number of haptic axes the device has.
   947  *  
   945  *
   948  *  \sa SDL_HapticDirection
   946  *  \sa SDL_HapticDirection
   949  */
   947  */
   950 extern DECLSPEC int SDLCALL SDL_HapticNumAxes(SDL_Haptic * haptic);
   948 extern DECLSPEC int SDLCALL SDL_HapticNumAxes(SDL_Haptic * haptic);
   951 
   949 
   952 /**
   950 /**
   953  *  \brief Checks to see if effect is supported by haptic.
   951  *  \brief Checks to see if effect is supported by haptic.
   954  *  
   952  *
   955  *  \param haptic Haptic device to check on.
   953  *  \param haptic Haptic device to check on.
   956  *  \param effect Effect to check to see if it is supported.
   954  *  \param effect Effect to check to see if it is supported.
   957  *  \return SDL_TRUE if effect is supported, SDL_FALSE if it isn't or -1 on error.
   955  *  \return SDL_TRUE if effect is supported, SDL_FALSE if it isn't or -1 on error.
   958  *  
   956  *
   959  *  \sa SDL_HapticQuery
   957  *  \sa SDL_HapticQuery
   960  *  \sa SDL_HapticNewEffect
   958  *  \sa SDL_HapticNewEffect
   961  */
   959  */
   962 extern DECLSPEC int SDLCALL SDL_HapticEffectSupported(SDL_Haptic * haptic,
   960 extern DECLSPEC int SDLCALL SDL_HapticEffectSupported(SDL_Haptic * haptic,
   963                                                       SDL_HapticEffect *
   961                                                       SDL_HapticEffect *
   964                                                       effect);
   962                                                       effect);
   965 
   963 
   966 /**
   964 /**
   967  *  \brief Creates a new haptic effect on the device.
   965  *  \brief Creates a new haptic effect on the device.
   968  *  
   966  *
   969  *  \param haptic Haptic device to create the effect on.
   967  *  \param haptic Haptic device to create the effect on.
   970  *  \param effect Properties of the effect to create.
   968  *  \param effect Properties of the effect to create.
   971  *  \return The id of the effect on success or -1 on error.
   969  *  \return The id of the effect on success or -1 on error.
   972  *  
   970  *
   973  *  \sa SDL_HapticUpdateEffect
   971  *  \sa SDL_HapticUpdateEffect
   974  *  \sa SDL_HapticRunEffect
   972  *  \sa SDL_HapticRunEffect
   975  *  \sa SDL_HapticDestroyEffect
   973  *  \sa SDL_HapticDestroyEffect
   976  */
   974  */
   977 extern DECLSPEC int SDLCALL SDL_HapticNewEffect(SDL_Haptic * haptic,
   975 extern DECLSPEC int SDLCALL SDL_HapticNewEffect(SDL_Haptic * haptic,
   978                                                 SDL_HapticEffect * effect);
   976                                                 SDL_HapticEffect * effect);
   979 
   977 
   980 /**
   978 /**
   981  *  \brief Updates the properties of an effect.
   979  *  \brief Updates the properties of an effect.
   982  *  
   980  *
   983  *  Can be used dynamically, although behaviour when dynamically changing
   981  *  Can be used dynamically, although behaviour when dynamically changing
   984  *  direction may be strange.  Specifically the effect may reupload itself
   982  *  direction may be strange.  Specifically the effect may reupload itself
   985  *  and start playing from the start.  You cannot change the type either when
   983  *  and start playing from the start.  You cannot change the type either when
   986  *  running SDL_HapticUpdateEffect().
   984  *  running SDL_HapticUpdateEffect().
   987  *  
   985  *
   988  *  \param haptic Haptic device that has the effect.
   986  *  \param haptic Haptic device that has the effect.
   989  *  \param effect Effect to update.
   987  *  \param effect Effect to update.
   990  *  \param data New effect properties to use.
   988  *  \param data New effect properties to use.
   991  *  \return The id of the effect on success or -1 on error.
   989  *  \return The id of the effect on success or -1 on error.
   992  *  
   990  *
   993  *  \sa SDL_HapticNewEffect
   991  *  \sa SDL_HapticNewEffect
   994  *  \sa SDL_HapticRunEffect
   992  *  \sa SDL_HapticRunEffect
   995  *  \sa SDL_HapticDestroyEffect
   993  *  \sa SDL_HapticDestroyEffect
   996  */
   994  */
   997 extern DECLSPEC int SDLCALL SDL_HapticUpdateEffect(SDL_Haptic * haptic,
   995 extern DECLSPEC int SDLCALL SDL_HapticUpdateEffect(SDL_Haptic * haptic,
   998                                                    int effect,
   996                                                    int effect,
   999                                                    SDL_HapticEffect * data);
   997                                                    SDL_HapticEffect * data);
  1000 
   998 
  1001 /**
   999 /**
  1002  *  \brief Runs the haptic effect on its associated haptic device.
  1000  *  \brief Runs the haptic effect on its associated haptic device.
  1003  *  
  1001  *
  1004  *  If iterations are ::SDL_HAPTIC_INFINITY, it'll run the effect over and over
  1002  *  If iterations are ::SDL_HAPTIC_INFINITY, it'll run the effect over and over
  1005  *  repeating the envelope (attack and fade) every time.  If you only want the
  1003  *  repeating the envelope (attack and fade) every time.  If you only want the
  1006  *  effect to last forever, set ::SDL_HAPTIC_INFINITY in the effect's length
  1004  *  effect to last forever, set ::SDL_HAPTIC_INFINITY in the effect's length
  1007  *  parameter.
  1005  *  parameter.
  1008  *  
  1006  *
  1009  *  \param haptic Haptic device to run the effect on.
  1007  *  \param haptic Haptic device to run the effect on.
  1010  *  \param effect Identifier of the haptic effect to run.
  1008  *  \param effect Identifier of the haptic effect to run.
  1011  *  \param iterations Number of iterations to run the effect. Use
  1009  *  \param iterations Number of iterations to run the effect. Use
  1012  *         ::SDL_HAPTIC_INFINITY for infinity.
  1010  *         ::SDL_HAPTIC_INFINITY for infinity.
  1013  *  \return 0 on success or -1 on error.
  1011  *  \return 0 on success or -1 on error.
  1014  *  
  1012  *
  1015  *  \sa SDL_HapticStopEffect
  1013  *  \sa SDL_HapticStopEffect
  1016  *  \sa SDL_HapticDestroyEffect
  1014  *  \sa SDL_HapticDestroyEffect
  1017  *  \sa SDL_HapticGetEffectStatus
  1015  *  \sa SDL_HapticGetEffectStatus
  1018  */
  1016  */
  1019 extern DECLSPEC int SDLCALL SDL_HapticRunEffect(SDL_Haptic * haptic,
  1017 extern DECLSPEC int SDLCALL SDL_HapticRunEffect(SDL_Haptic * haptic,
  1020                                                 int effect,
  1018                                                 int effect,
  1021                                                 Uint32 iterations);
  1019                                                 Uint32 iterations);
  1022 
  1020 
  1023 /**
  1021 /**
  1024  *  \brief Stops the haptic effect on its associated haptic device.
  1022  *  \brief Stops the haptic effect on its associated haptic device.
  1025  *  
  1023  *
  1026  *  \param haptic Haptic device to stop the effect on.
  1024  *  \param haptic Haptic device to stop the effect on.
  1027  *  \param effect Identifier of the effect to stop.
  1025  *  \param effect Identifier of the effect to stop.
  1028  *  \return 0 on success or -1 on error.
  1026  *  \return 0 on success or -1 on error.
  1029  *  
  1027  *
  1030  *  \sa SDL_HapticRunEffect
  1028  *  \sa SDL_HapticRunEffect
  1031  *  \sa SDL_HapticDestroyEffect
  1029  *  \sa SDL_HapticDestroyEffect
  1032  */
  1030  */
  1033 extern DECLSPEC int SDLCALL SDL_HapticStopEffect(SDL_Haptic * haptic,
  1031 extern DECLSPEC int SDLCALL SDL_HapticStopEffect(SDL_Haptic * haptic,
  1034                                                  int effect);
  1032                                                  int effect);
  1035 
  1033 
  1036 /**
  1034 /**
  1037  *  \brief Destroys a haptic effect on the device.
  1035  *  \brief Destroys a haptic effect on the device.
  1038  *  
  1036  *
  1039  *  This will stop the effect if it's running.  Effects are automatically 
  1037  *  This will stop the effect if it's running.  Effects are automatically
  1040  *  destroyed when the device is closed.
  1038  *  destroyed when the device is closed.
  1041  *  
  1039  *
  1042  *  \param haptic Device to destroy the effect on.
  1040  *  \param haptic Device to destroy the effect on.
  1043  *  \param effect Identifier of the effect to destroy.
  1041  *  \param effect Identifier of the effect to destroy.
  1044  *  
  1042  *
  1045  *  \sa SDL_HapticNewEffect
  1043  *  \sa SDL_HapticNewEffect
  1046  */
  1044  */
  1047 extern DECLSPEC void SDLCALL SDL_HapticDestroyEffect(SDL_Haptic * haptic,
  1045 extern DECLSPEC void SDLCALL SDL_HapticDestroyEffect(SDL_Haptic * haptic,
  1048                                                      int effect);
  1046                                                      int effect);
  1049 
  1047 
  1050 /**
  1048 /**
  1051  *  \brief Gets the status of the current effect on the haptic device.
  1049  *  \brief Gets the status of the current effect on the haptic device.
  1052  *  
  1050  *
  1053  *  Device must support the ::SDL_HAPTIC_STATUS feature.
  1051  *  Device must support the ::SDL_HAPTIC_STATUS feature.
  1054  *  
  1052  *
  1055  *  \param haptic Haptic device to query the effect status on.
  1053  *  \param haptic Haptic device to query the effect status on.
  1056  *  \param effect Identifier of the effect to query its status.
  1054  *  \param effect Identifier of the effect to query its status.
  1057  *  \return 0 if it isn't playing, ::SDL_HAPTIC_PLAYING if it is playing
  1055  *  \return 0 if it isn't playing, ::SDL_HAPTIC_PLAYING if it is playing
  1058  *          or -1 on error.
  1056  *          or -1 on error.
  1059  *  
  1057  *
  1060  *  \sa SDL_HapticRunEffect
  1058  *  \sa SDL_HapticRunEffect
  1061  *  \sa SDL_HapticStopEffect
  1059  *  \sa SDL_HapticStopEffect
  1062  */
  1060  */
  1063 extern DECLSPEC int SDLCALL SDL_HapticGetEffectStatus(SDL_Haptic * haptic,
  1061 extern DECLSPEC int SDLCALL SDL_HapticGetEffectStatus(SDL_Haptic * haptic,
  1064                                                       int effect);
  1062                                                       int effect);
  1065 
  1063 
  1066 /**
  1064 /**
  1067  *  \brief Sets the global gain of the device.
  1065  *  \brief Sets the global gain of the device.
  1068  *  
  1066  *
  1069  *  Device must support the ::SDL_HAPTIC_GAIN feature.
  1067  *  Device must support the ::SDL_HAPTIC_GAIN feature.
  1070  *  
  1068  *
  1071  *  The user may specify the maximum gain by setting the environment variable
  1069  *  The user may specify the maximum gain by setting the environment variable
  1072  *  ::SDL_HAPTIC_GAIN_MAX which should be between 0 and 100.  All calls to
  1070  *  ::SDL_HAPTIC_GAIN_MAX which should be between 0 and 100.  All calls to
  1073  *  SDL_HapticSetGain() will scale linearly using ::SDL_HAPTIC_GAIN_MAX as the
  1071  *  SDL_HapticSetGain() will scale linearly using ::SDL_HAPTIC_GAIN_MAX as the
  1074  *  maximum.
  1072  *  maximum.
  1075  *  
  1073  *
  1076  *  \param haptic Haptic device to set the gain on.
  1074  *  \param haptic Haptic device to set the gain on.
  1077  *  \param gain Value to set the gain to, should be between 0 and 100.
  1075  *  \param gain Value to set the gain to, should be between 0 and 100.
  1078  *  \return 0 on success or -1 on error.
  1076  *  \return 0 on success or -1 on error.
  1079  *  
  1077  *
  1080  *  \sa SDL_HapticQuery
  1078  *  \sa SDL_HapticQuery
  1081  */
  1079  */
  1082 extern DECLSPEC int SDLCALL SDL_HapticSetGain(SDL_Haptic * haptic, int gain);
  1080 extern DECLSPEC int SDLCALL SDL_HapticSetGain(SDL_Haptic * haptic, int gain);
  1083 
  1081 
  1084 /**
  1082 /**
  1085  *  \brief Sets the global autocenter of the device.
  1083  *  \brief Sets the global autocenter of the device.
  1086  *  
  1084  *
  1087  *  Autocenter should be between 0 and 100.  Setting it to 0 will disable 
  1085  *  Autocenter should be between 0 and 100.  Setting it to 0 will disable
  1088  *  autocentering.
  1086  *  autocentering.
  1089  *
  1087  *
  1090  *  Device must support the ::SDL_HAPTIC_AUTOCENTER feature.
  1088  *  Device must support the ::SDL_HAPTIC_AUTOCENTER feature.
  1091  *
  1089  *
  1092  *  \param haptic Haptic device to set autocentering on.
  1090  *  \param haptic Haptic device to set autocentering on.
  1093  *  \param autocenter Value to set autocenter to, 0 disables autocentering.
  1091  *  \param autocenter Value to set autocenter to, 0 disables autocentering.
  1094  *  \return 0 on success or -1 on error.
  1092  *  \return 0 on success or -1 on error.
  1095  *  
  1093  *
  1096  *  \sa SDL_HapticQuery
  1094  *  \sa SDL_HapticQuery
  1097  */
  1095  */
  1098 extern DECLSPEC int SDLCALL SDL_HapticSetAutocenter(SDL_Haptic * haptic,
  1096 extern DECLSPEC int SDLCALL SDL_HapticSetAutocenter(SDL_Haptic * haptic,
  1099                                                     int autocenter);
  1097                                                     int autocenter);
  1100 
  1098 
  1101 /**
  1099 /**
  1102  *  \brief Pauses a haptic device.
  1100  *  \brief Pauses a haptic device.
  1103  *  
  1101  *
  1104  *  Device must support the ::SDL_HAPTIC_PAUSE feature.  Call 
  1102  *  Device must support the ::SDL_HAPTIC_PAUSE feature.  Call
  1105  *  SDL_HapticUnpause() to resume playback.
  1103  *  SDL_HapticUnpause() to resume playback.
  1106  *  
  1104  *
  1107  *  Do not modify the effects nor add new ones while the device is paused.
  1105  *  Do not modify the effects nor add new ones while the device is paused.
  1108  *  That can cause all sorts of weird errors.
  1106  *  That can cause all sorts of weird errors.
  1109  *  
  1107  *
  1110  *  \param haptic Haptic device to pause.
  1108  *  \param haptic Haptic device to pause.
  1111  *  \return 0 on success or -1 on error.
  1109  *  \return 0 on success or -1 on error.
  1112  *  
  1110  *
  1113  *  \sa SDL_HapticUnpause
  1111  *  \sa SDL_HapticUnpause
  1114  */
  1112  */
  1115 extern DECLSPEC int SDLCALL SDL_HapticPause(SDL_Haptic * haptic);
  1113 extern DECLSPEC int SDLCALL SDL_HapticPause(SDL_Haptic * haptic);
  1116 
  1114 
  1117 /**
  1115 /**
  1118  *  \brief Unpauses a haptic device.
  1116  *  \brief Unpauses a haptic device.
  1119  *  
  1117  *
  1120  *  Call to unpause after SDL_HapticPause().
  1118  *  Call to unpause after SDL_HapticPause().
  1121  *  
  1119  *
  1122  *  \param haptic Haptic device to pause.
  1120  *  \param haptic Haptic device to pause.
  1123  *  \return 0 on success or -1 on error.
  1121  *  \return 0 on success or -1 on error.
  1124  *  
  1122  *
  1125  *  \sa SDL_HapticPause
  1123  *  \sa SDL_HapticPause
  1126  */
  1124  */
  1127 extern DECLSPEC int SDLCALL SDL_HapticUnpause(SDL_Haptic * haptic);
  1125 extern DECLSPEC int SDLCALL SDL_HapticUnpause(SDL_Haptic * haptic);
  1128 
  1126 
  1129 /**
  1127 /**
  1130  *  \brief Stops all the currently playing effects on a haptic device.
  1128  *  \brief Stops all the currently playing effects on a haptic device.
  1131  *  
  1129  *
  1132  *  \param haptic Haptic device to stop.
  1130  *  \param haptic Haptic device to stop.
  1133  *  \return 0 on success or -1 on error.
  1131  *  \return 0 on success or -1 on error.
  1134  */
  1132  */
  1135 extern DECLSPEC int SDLCALL SDL_HapticStopAll(SDL_Haptic * haptic);
  1133 extern DECLSPEC int SDLCALL SDL_HapticStopAll(SDL_Haptic * haptic);
  1136 
  1134 
  1187 
  1185 
  1188 
  1186 
  1189 
  1187 
  1190 /* Ends C function definitions when using C++ */
  1188 /* Ends C function definitions when using C++ */
  1191 #ifdef __cplusplus
  1189 #ifdef __cplusplus
  1192 /* *INDENT-OFF* */
       
  1193 }
  1190 }
  1194 /* *INDENT-ON* */
       
  1195 #endif
  1191 #endif
  1196 #include "close_code.h"
  1192 #include "close_code.h"
  1197 
  1193 
  1198 #endif /* _SDL_haptic_h */
  1194 #endif /* _SDL_haptic_h */
  1199 
  1195