include/SDL_haptic.h
changeset 3407 d3baf5ac4e37
parent 2713 0906692aa6a4
child 3496 78fc8ea578b2
     1.1 --- a/include/SDL_haptic.h	Sun Oct 18 23:21:15 2009 +0000
     1.2 +++ b/include/SDL_haptic.h	Mon Oct 19 13:31:58 2009 +0000
     1.3 @@ -21,24 +21,23 @@
     1.4  */
     1.5  
     1.6  /**
     1.7 - * \file SDL_haptic.h
     1.8 + *  \file SDL_haptic.h
     1.9 + *  
    1.10 + *  \brief The SDL Haptic subsystem allows you to control haptic (force feedback)
    1.11 + *         devices.
    1.12 + *  
    1.13 + *  The basic usage is as follows:
    1.14 + *   - Initialize the Subsystem (::SDL_INIT_HAPTIC).
    1.15 + *   - Open a Haptic Device.
    1.16 + *    - SDL_HapticOpen() to open from index.
    1.17 + *    - SDL_HapticOpenFromJoystick() to open from an existing joystick.
    1.18 + *   - Create an effect (::SDL_HapticEffect).
    1.19 + *   - Upload the effect with SDL_HapticNewEffect().
    1.20 + *   - Run the effect with SDL_HapticRunEffect().
    1.21 + *   - (optional) Free the effect with SDL_HapticDestroyEffect().
    1.22 + *   - Close the haptic device with SDL_HapticClose().
    1.23   *
    1.24 - * \brief The SDL Haptic subsystem allows you to control haptic (force feedback)
    1.25 - *  devices.
    1.26 - *
    1.27 - * The basic usage is as follows:
    1.28 - *   - Initialize the Subsystem (SDL_INIT_HAPTIC).
    1.29 - *   - Open a Haptic Device.
    1.30 - *     - SDL_HapticOpen(...) to open from index.
    1.31 - *     - SDL_HapticOpenFromJoystick(...) to open from an existing joystick.
    1.32 - *   - Create an effect (SDL_HapticEffect).
    1.33 - *   - Upload the effect with SDL_HapticNewEffect(...).
    1.34 - *   - Run the effect with SDL_HapticRunEffect(...).
    1.35 - *   - (optional) Free the effect with SDL_HapticDestroyEffect(...).
    1.36 - *   - Close the haptic device with SDL_HapticClose(...).
    1.37 - *
    1.38 - * Example:
    1.39 - *
    1.40 + * \par Example:
    1.41   * \code
    1.42   * int test_haptic( SDL_Joystick * joystick ) {
    1.43   *    SDL_Haptic *haptic;
    1.44 @@ -82,7 +81,6 @@
    1.45   *    return 0; // Success
    1.46   * }
    1.47   * \endcode
    1.48 - *
    1.49   * \author Edgar Simo Serra
    1.50   */
    1.51  
    1.52 @@ -102,190 +100,215 @@
    1.53  #endif /* __cplusplus */
    1.54  
    1.55  /**
    1.56 - * \typedef SDL_Haptic
    1.57 - *
    1.58 - * \brief The haptic structure used to identify an SDL haptic.
    1.59 - *
    1.60 - * \sa SDL_HapticOpen
    1.61 - * \sa SDL_HapticOpenFromJoystick
    1.62 - * \sa SDL_HapticClose
    1.63 + *  \typedef SDL_Haptic
    1.64 + *  
    1.65 + *  \brief The haptic structure used to identify an SDL haptic.
    1.66 + *  
    1.67 + *  \sa SDL_HapticOpen
    1.68 + *  \sa SDL_HapticOpenFromJoystick
    1.69 + *  \sa SDL_HapticClose
    1.70   */
    1.71  struct _SDL_Haptic;
    1.72  typedef struct _SDL_Haptic SDL_Haptic;
    1.73  
    1.74  
    1.75 -/*
    1.76 - * Different haptic features a device can have.
    1.77 +/**
    1.78 + *  \name Haptic features
    1.79 + *  
    1.80 + *  Different haptic features a device can have.
    1.81   */
    1.82 +/*@{*/
    1.83 +
    1.84  /**
    1.85 - * \def SDL_HAPTIC_CONSTANT
    1.86 + *  \name Haptic effects
    1.87 + */
    1.88 +/*@{*/
    1.89 +
    1.90 +/**
    1.91 + *  \brief Constant effect supported.
    1.92   *
    1.93 - * \brief Constant haptic effect.
    1.94 + *  Constant haptic effect.
    1.95 + *  
    1.96 + *  \sa SDL_HapticCondition
    1.97 + */
    1.98 +#define SDL_HAPTIC_CONSTANT   (1<<0)
    1.99 +
   1.100 +/**
   1.101 + *  \brief Sine wave effect supported.
   1.102 + *  
   1.103 + *  Periodic haptic effect that simulates sine waves.
   1.104 + *  
   1.105 + *  \sa SDL_HapticPeriodic
   1.106 + */
   1.107 +#define SDL_HAPTIC_SINE       (1<<1)
   1.108 +
   1.109 +/**
   1.110 + *  \brief Square wave effect supported.
   1.111 + *  
   1.112 + *  Periodic haptic effect that simulates square waves.
   1.113 + * 
   1.114 + *  \sa SDL_HapticPeriodic
   1.115 + */
   1.116 +#define SDL_HAPTIC_SQUARE     (1<<2)
   1.117 +
   1.118 +/**
   1.119 + *  \brief Triangle wave effect supported.
   1.120 + *  
   1.121 + *  Periodic haptic effect that simulates triangular waves.
   1.122 + *  
   1.123 + *  \sa SDL_HapticPeriodic
   1.124 + */
   1.125 +#define SDL_HAPTIC_TRIANGLE   (1<<3)
   1.126 +
   1.127 +/**
   1.128 + *  \brief Sawtoothup wave effect supported.
   1.129 + *  
   1.130 + *  Periodic haptic effect that simulates saw tooth up waves.
   1.131 + *  
   1.132 + *  \sa SDL_HapticPeriodic
   1.133 + */
   1.134 +#define SDL_HAPTIC_SAWTOOTHUP (1<<4)
   1.135 +
   1.136 +/**
   1.137 + *  \brief Sawtoothdown wave effect supported.
   1.138 + *  
   1.139 + *  Periodic haptic effect that simulates saw tooth down waves.
   1.140 + *  
   1.141 + *  \sa SDL_HapticPeriodic
   1.142 + */
   1.143 +#define SDL_HAPTIC_SAWTOOTHDOWN (1<<5)
   1.144 +
   1.145 +/**
   1.146 + *  \brief Ramp effect supported.
   1.147 + *  
   1.148 + *  Ramp haptic effect.
   1.149 + *  
   1.150 + *  \sa SDL_HapticRamp
   1.151 + */
   1.152 +#define SDL_HAPTIC_RAMP       (1<<6)
   1.153 +
   1.154 +/**
   1.155 + *  \brief Spring effect supported - uses axes position.
   1.156 + *  
   1.157 + *  Condition haptic effect that simulates a spring.  Effect is based on the
   1.158 + *  axes position.
   1.159   *
   1.160 - * \sa SDL_HapticCondition
   1.161 + *  \sa SDL_HapticCondition
   1.162   */
   1.163 -#define SDL_HAPTIC_CONSTANT   (1<<0)    /* Constant effect supported */
   1.164 +#define SDL_HAPTIC_SPRING     (1<<7)
   1.165 +
   1.166  /**
   1.167 - * \def SDL_HAPTIC_SINE
   1.168 + *  \brief Damper effect supported - uses axes velocity.
   1.169 + *  
   1.170 + *  Condition haptic effect that simulates dampening.  Effect is based on the
   1.171 + *  axes velocity.
   1.172 + *  
   1.173 + *  \sa SDL_HapticCondition
   1.174 + */
   1.175 +#define SDL_HAPTIC_DAMPER     (1<<8)
   1.176 +
   1.177 +/**
   1.178 + *  \brief Inertia effect supported - uses axes acceleration.
   1.179 + *  
   1.180 + *  Condition haptic effect that simulates inertia.  Effect is based on the axes
   1.181 + *  acceleration.
   1.182   *
   1.183 - * \brief Periodic haptic effect that simulates sine waves.
   1.184 - *
   1.185 - * \sa SDL_HapticPeriodic
   1.186 + *  \sa SDL_HapticCondition
   1.187   */
   1.188 -#define SDL_HAPTIC_SINE       (1<<1)    /* Sine wave effect supported */
   1.189 +#define SDL_HAPTIC_INERTIA    (1<<9)
   1.190 +
   1.191  /**
   1.192 - * \def SDL_HAPTIC_SQUARE
   1.193 - *
   1.194 - * \brief Periodic haptic effect that simulates square waves.
   1.195 - * 
   1.196 - * \sa SDL_HapticPeriodic
   1.197 + *  \brief Friction effect supported - uses axes movement.
   1.198 + *  
   1.199 + *  Condition haptic effect that simulates friction.  Effect is based on the 
   1.200 + *  axes movement.
   1.201 + *  
   1.202 + *  \sa SDL_HapticCondition
   1.203   */
   1.204 -#define SDL_HAPTIC_SQUARE     (1<<2)    /* Square wave effect supported */
   1.205 +#define SDL_HAPTIC_FRICTION   (1<<10)
   1.206 +
   1.207  /**
   1.208 - * \def SDL_HAPTIC_TRIANGLE
   1.209 - *
   1.210 - * \brief Periodic haptic effect that simulates triangular waves.
   1.211 - *
   1.212 - * \sa SDL_HapticPeriodic
   1.213 + *  \brief Custom effect is supported.
   1.214 + *  
   1.215 + *  User defined custom haptic effect.
   1.216   */
   1.217 -#define SDL_HAPTIC_TRIANGLE   (1<<3)    /* Triangle wave effect supported */
   1.218 +#define SDL_HAPTIC_CUSTOM     (1<<11)
   1.219 +
   1.220 +/*@}*//*Haptic effects*/
   1.221 +
   1.222 +/* These last few are features the device has, not effects */
   1.223 +
   1.224  /**
   1.225 - * \def SDL_HAPTIC_SAWTOOTHUP
   1.226 - *
   1.227 - * \brief Periodic haptic effect that simulates saw tooth up waves.
   1.228 - *
   1.229 - * \sa SDL_HapticPeriodic
   1.230 + *  \brief Device can set global gain.
   1.231 + *  
   1.232 + *  Device supports setting the global gain.
   1.233 + *  
   1.234 + *  \sa SDL_HapticSetGain
   1.235   */
   1.236 -#define SDL_HAPTIC_SAWTOOTHUP (1<<4)    /* Sawtoothup wave effect supported */
   1.237 +#define SDL_HAPTIC_GAIN       (1<<12)
   1.238 +
   1.239  /**
   1.240 - * \def SDL_HAPTIC_SAWTOOTHDOWN
   1.241 - *
   1.242 - * \brief Periodic haptic effect that simulates saw tooth down waves.
   1.243 - *
   1.244 - * \sa SDL_HapticPeriodic
   1.245 + *  \brief Device can set autocenter.
   1.246 + *  
   1.247 + *  Device supports setting autocenter.
   1.248 + *  
   1.249 + *  \sa SDL_HapticSetAutocenter
   1.250   */
   1.251 -#define SDL_HAPTIC_SAWTOOTHDOWN (1<<5)  /* Sawtoothdown wave effect supported */
   1.252 +#define SDL_HAPTIC_AUTOCENTER (1<<13)
   1.253 +
   1.254  /**
   1.255 - * \def SDL_HAPTIC_RAMP
   1.256 - *
   1.257 - * \brief Ramp haptic effect.
   1.258 - *
   1.259 - * \sa SDL_HapticRamp
   1.260 + *  \brief Device can be queried for effect status.
   1.261 + *  
   1.262 + *  Device can be queried for effect status.
   1.263 + *  
   1.264 + *  \sa SDL_HapticGetEffectStatus
   1.265   */
   1.266 -#define SDL_HAPTIC_RAMP       (1<<6)    /* Ramp effect supported */
   1.267 +#define SDL_HAPTIC_STATUS     (1<<14)
   1.268 +
   1.269  /**
   1.270 - * \def SDL_HAPTIC_SPRING
   1.271 - *
   1.272 - * \brief Condition haptic effect that simulates a spring.  Effect is based on the
   1.273 - * axes position.
   1.274 - *
   1.275 - * \sa SDL_HapticCondition
   1.276 + *  \brief Device can be paused.
   1.277 + *  
   1.278 + *  \sa SDL_HapticPause
   1.279 + *  \sa SDL_HapticUnpause
   1.280   */
   1.281 -#define SDL_HAPTIC_SPRING     (1<<7)    /* Spring effect supported - uses axes position */
   1.282 +#define SDL_HAPTIC_PAUSE      (1<<15)
   1.283 +
   1.284 +
   1.285  /**
   1.286 - * \def SDL_HAPTIC_DAMPER
   1.287 - *
   1.288 - * \brief Condition haptic effect that simulates dampening.  Effect is based on the
   1.289 - * axes velocity.
   1.290 - *
   1.291 - * \sa SDL_HapticCondition
   1.292 + * \name Direction encodings
   1.293   */
   1.294 -#define SDL_HAPTIC_DAMPER     (1<<8)    /* Damper effect supported - uses axes velocity */
   1.295 +/*@{*/
   1.296 +
   1.297  /**
   1.298 - * \def SDL_HAPTIC_INERTIA
   1.299 - *
   1.300 - * \brief Condition haptic effect that simulates inertia.  Effect is based on the axes
   1.301 - * acceleration.
   1.302 - *
   1.303 - * \sa SDL_HapticCondition
   1.304 - */
   1.305 -#define SDL_HAPTIC_INERTIA    (1<<9)    /* Inertia effect supported - uses axes acceleration */
   1.306 -/**
   1.307 - * \def SDL_HAPTIC_FRICTION
   1.308 - *
   1.309 - * \brief Condition haptic effect that simulates friction.  Effect is based on the axes
   1.310 - * movement.
   1.311 - *
   1.312 - * \sa SDL_HapticCondition
   1.313 - */
   1.314 -#define SDL_HAPTIC_FRICTION   (1<<10)   /* Friction effect supported - uses axes movement */
   1.315 -/**
   1.316 - * \def SDL_HAPTIC_CUSTOM
   1.317 - *
   1.318 - * \brief User defined custom haptic effect.
   1.319 - */
   1.320 -#define SDL_HAPTIC_CUSTOM     (1<<11)   /* Custom effect is supported */
   1.321 -/* These last two are features the device has, not effects */
   1.322 -/**
   1.323 - * \def SDL_HAPTIC_GAIN
   1.324 - *
   1.325 - * \brief Device supports setting the global gain.
   1.326 - *
   1.327 - * \sa SDL_HapticSetGain
   1.328 - */
   1.329 -#define SDL_HAPTIC_GAIN       (1<<12)   /* Device can set global gain */
   1.330 -/**
   1.331 - * \def SDL_HAPTIC_AUTOCENTER
   1.332 - *
   1.333 - * \brief Device supports setting autocenter.
   1.334 - *
   1.335 - * \sa SDL_HapticSetAutocenter
   1.336 - */
   1.337 -#define SDL_HAPTIC_AUTOCENTER (1<<13)   /* Device can set autocenter */
   1.338 -/**
   1.339 - * \def SDL_HAPTIC_STATUS
   1.340 - *
   1.341 - * \brief Device can be queried for effect status.
   1.342 - *
   1.343 - * \sa SDL_HapticGetEffectStatus
   1.344 - */
   1.345 -#define SDL_HAPTIC_STATUS     (1<<14)   /* Device can be queried for effect status */
   1.346 -/**
   1.347 - * \def SDL_HAPTIC_PAUSE
   1.348 - *
   1.349 - * \brief Device can be paused.
   1.350 - *
   1.351 - * \sa SDL_HapticPause
   1.352 - * \sa SDL_HapticUnpause
   1.353 - */
   1.354 -#define SDL_HAPTIC_PAUSE      (1<<15)   /* Device can be paused. */
   1.355 -
   1.356 -
   1.357 -/*
   1.358 - * Direction encodings
   1.359 - */
   1.360 -/**
   1.361 - * \def SDL_HAPTIC_POLAR
   1.362 - *
   1.363 - * \brief Uses polar coordinates for the direction.
   1.364 - *
   1.365 - * \sa SDL_HapticDirection
   1.366 + *  \brief Uses polar coordinates for the direction.
   1.367 + *  
   1.368 + *  \sa SDL_HapticDirection
   1.369   */
   1.370  #define SDL_HAPTIC_POLAR      0
   1.371 +
   1.372  /**
   1.373 - * \def SDL_HAPTIC_CARTESIAN
   1.374 - *
   1.375 - * \brief Uses cartesian coordinates for the direction.
   1.376 - *
   1.377 - * \sa SDL_HapticDirection
   1.378 + *  \brief Uses cartesian coordinates for the direction.
   1.379 + *  
   1.380 + *  \sa SDL_HapticDirection
   1.381   */
   1.382  #define SDL_HAPTIC_CARTESIAN  1
   1.383 +
   1.384  /**
   1.385 - * \def SDL_HAPTIC_SPHERICAL
   1.386 - *
   1.387 - * \brief Uses spherical coordinates for the direction.
   1.388 - *
   1.389 - * \sa SDL_HapticDirection
   1.390 + *  \brief Uses spherical coordinates for the direction.
   1.391 + *  
   1.392 + *  \sa SDL_HapticDirection
   1.393   */
   1.394  #define SDL_HAPTIC_SPHERICAL  2
   1.395  
   1.396 +/*@}*//*Direction encodings*/
   1.397 +
   1.398 +/*@}*//*Haptic features*/
   1.399  
   1.400  /*
   1.401   * Misc defines.
   1.402   */
   1.403 +
   1.404  /**
   1.405 - * \def SDL_HAPTIC_INFINITY
   1.406 - *
   1.407   * \brief Used to play a device an infinite number of times.
   1.408   *
   1.409   * \sa SDL_HapticRunEffect
   1.410 @@ -294,97 +317,96 @@
   1.411  
   1.412  
   1.413  /**
   1.414 - * \struct SDL_HapticDirection
   1.415 + *  \brief Structure that represents a haptic direction.
   1.416 + *  
   1.417 + *  Directions can be specified by:
   1.418 + *   - ::SDL_HAPTIC_POLAR : Specified by polar coordinates.
   1.419 + *   - ::SDL_HAPTIC_CARTESIAN : Specified by cartesian coordinates.
   1.420 + *   - ::SDL_HAPTIC_SPHERICAL : Specified by spherical coordinates.
   1.421   *
   1.422 - * \brief Structure that represents a haptic direction.
   1.423 - *
   1.424 - * Directions can be specified by:
   1.425 - *   - SDL_HAPTIC_POLAR : Specified by polar coordinates.
   1.426 - *   - SDL_HAPTIC_CARTESIAN : Specified by cartesian coordinates.
   1.427 - *   - SDL_HAPTIC_SPHERICAL : Specified by spherical coordinates.
   1.428 - *
   1.429 - * Cardinal directions of the haptic device are relative to the positioning
   1.430 + *  Cardinal directions of the haptic device are relative to the positioning
   1.431   *  of the device.  North is considered to be away from the user.
   1.432   *
   1.433 - * The following diagram represents the cardinal directions:
   1.434 - * \code
   1.435 - *              .--.
   1.436 - *              |__| .-------.
   1.437 - *              |=.| |.-----.|
   1.438 - *              |--| ||     ||
   1.439 - *              |  | |'-----'|
   1.440 - *              |__|~')_____('
   1.441 - *                [ COMPUTER ]
   1.442 - *
   1.443 - *
   1.444 - *                  North (0,-1)
   1.445 - *                      ^
   1.446 - *                      |
   1.447 - *                      |
   1.448 - * (1,0)  West <----[ HAPTIC ]----> East (-1,0)
   1.449 - *                      |
   1.450 - *                      |
   1.451 - *                      v
   1.452 - *                   South (0,1)
   1.453 - *
   1.454 - *
   1.455 - *                   [ USER ]
   1.456 - *                     \|||/
   1.457 - *                     (o o)
   1.458 - *               ---ooO-(_)-Ooo---
   1.459 - * \endcode
   1.460 - *
   1.461 - * If type is SDL_HAPTIC_POLAR, direction is encoded by hundredths of a 
   1.462 - *  degree starting north and turning clockwise.  SDL_HAPTIC_POLAR only uses
   1.463 - *  the first dir parameter.  The cardinal directions would be:
   1.464 + *  The following diagram represents the cardinal directions:
   1.465 + *  \verbatim
   1.466 +                 .--.
   1.467 +                 |__| .-------.
   1.468 +                 |=.| |.-----.|
   1.469 +                 |--| ||     ||
   1.470 +                 |  | |'-----'|
   1.471 +                 |__|~')_____('
   1.472 +                   [ COMPUTER ]
   1.473 +    
   1.474 +    
   1.475 +                     North (0,-1)
   1.476 +                         ^
   1.477 +                         |
   1.478 +                         |
   1.479 +    (1,0)  West <----[ HAPTIC ]----> East (-1,0)
   1.480 +                         |
   1.481 +                         |
   1.482 +                         v
   1.483 +                      South (0,1)
   1.484 +    
   1.485 +    
   1.486 +                      [ USER ]
   1.487 +                        \|||/
   1.488 +                        (o o)
   1.489 +                  ---ooO-(_)-Ooo---
   1.490 +    \endverbatim
   1.491 + *  
   1.492 + *  If type is ::SDL_HAPTIC_POLAR, direction is encoded by hundredths of a 
   1.493 + *  degree starting north and turning clockwise.  ::SDL_HAPTIC_POLAR only uses
   1.494 + *  the first \c dir parameter.  The cardinal directions would be:
   1.495   *   - North: 0 (0 degrees)
   1.496   *   - East: 9000 (90 degrees)
   1.497   *   - South: 18000 (180 degrees)
   1.498   *   - West: 27000 (270 degrees)
   1.499 - *
   1.500 - * If type is SDL_HAPTIC_CARTESIAN, direction is encoded by three positions
   1.501 - *  (X axis, Y axis and Z axis (with 3 axes)).  SDL_HAPTIC_CARTESIAN uses
   1.502 - *  the first three dir parameters.  The cardinal directions would be:
   1.503 + *  
   1.504 + *  If type is ::SDL_HAPTIC_CARTESIAN, direction is encoded by three positions
   1.505 + *  (X axis, Y axis and Z axis (with 3 axes)).  ::SDL_HAPTIC_CARTESIAN uses
   1.506 + *  the first three \c dir parameters.  The cardinal directions would be:
   1.507   *   - North:  0,-1, 0
   1.508   *   - East:  -1, 0, 0
   1.509   *   - South:  0, 1, 0
   1.510   *   - West:   1, 0, 0
   1.511 + *  
   1.512   *  The Z axis represents the height of the effect if supported, otherwise
   1.513 - *  it's unused.  In cartesian encoding (1,2) would be the same as (2,4), you
   1.514 + *  it's unused.  In cartesian encoding (1, 2) would be the same as (2, 4), you
   1.515   *  can use any multiple you want, only the direction matters.
   1.516 + *  
   1.517 + *  If type is ::SDL_HAPTIC_SPHERICAL, direction is encoded by two rotations.
   1.518 + *  The first two \c dir parameters are used.  The \c dir parameters are as 
   1.519 + *  follows (all values are in hundredths of degrees):
   1.520 + *   - Degrees from (1, 0) rotated towards (0, 1).
   1.521 + *   - Degrees towards (0, 0, 1) (device needs at least 3 axes).
   1.522   *
   1.523 - * If type is SDL_HAPTIC_SPHERICAL, direction is encoded by two rotations.
   1.524 - *  The first two  dir parameters are used.  The dir parameters are as follows
   1.525 - *  (all values are in hundredths of degrees):
   1.526 - *    1) Degrees from (1, 0) rotated towards (0, 1).
   1.527 - *    2) Degrees towards (0, 0, 1) (device needs at least 3 axes).
   1.528   *
   1.529 + *  Example of force coming from the south with all encodings (force coming
   1.530 + *  from the south means the user will have to pull the stick to counteract):
   1.531 + *  \code
   1.532 + *  SDL_HapticDirection direction;
   1.533 + *  
   1.534 + *  // Cartesian directions
   1.535 + *  direction.type = SDL_HAPTIC_CARTESIAN; // Using cartesian direction encoding.
   1.536 + *  direction.dir[0] = 0; // X position
   1.537 + *  direction.dir[1] = 1; // Y position
   1.538 + *  // Assuming the device has 2 axes, we don't need to specify third parameter.
   1.539 + *  
   1.540 + *  // Polar directions
   1.541 + *  direction.type = SDL_HAPTIC_POLAR; // We'll be using polar direction encoding.
   1.542 + *  direction.dir[0] = 18000; // Polar only uses first parameter
   1.543 + *  
   1.544 + *  // Spherical coordinates
   1.545 + *  direction.type = SDL_HAPTIC_SPHERICAL; // Spherical encoding
   1.546 + *  direction.dir[0] = 9000; // Since we only have two axes we don't need more parameters.
   1.547 + *  \endcode
   1.548   *
   1.549 - * Example of force coming from the south with all encodings (force coming
   1.550 - *  from the south means the user will have to pull the stick to counteract):
   1.551 - * \code
   1.552 - * SDL_HapticDirection direction;
   1.553 - *
   1.554 - * // Cartesian directions
   1.555 - * direction.type = SDL_HAPTIC_CARTESIAN; // Using cartesian direction encoding.
   1.556 - * direction.dir[0] = 0; // X position
   1.557 - * direction.dir[1] = 1; // Y position
   1.558 - * // Assuming the device has 2 axes, we don't need to specify third parameter.
   1.559 - *
   1.560 - * // Polar directions
   1.561 - * direction.type = SDL_HAPTIC_POLAR; // We'll be using polar direction encoding.
   1.562 - * direction.dir[0] = 18000; // Polar only uses first parameter
   1.563 - *
   1.564 - * // Spherical coordinates
   1.565 - * direction.type = SDL_HAPTIC_SPHERICAL; // Spherical encoding
   1.566 - * direction.dir[0] = 9000; // Since we only have two axes we don't need more parameters.
   1.567 - * \endcode
   1.568 - *
   1.569 - * \sa SDL_HAPTIC_POLAR
   1.570 - * \sa SDL_HAPTIC_CARTESIAN
   1.571 - * \sa SDL_HAPTIC_SPHERICAL
   1.572 - * \sa SDL_HapticEffect
   1.573 - * \sa SDL_HapticNumAxes
   1.574 + *  \sa SDL_HAPTIC_POLAR
   1.575 + *  \sa SDL_HAPTIC_CARTESIAN
   1.576 + *  \sa SDL_HAPTIC_SPHERICAL
   1.577 + *  \sa SDL_HapticEffect
   1.578 + *  \sa SDL_HapticNumAxes
   1.579   */
   1.580  typedef struct SDL_HapticDirection
   1.581  {
   1.582 @@ -394,22 +416,20 @@
   1.583  
   1.584  
   1.585  /**
   1.586 - * \struct SDL_HapticConstant
   1.587 - *
   1.588 - * \brief A structure containing a template for a Constant effect.
   1.589 - *
   1.590 - * The struct is exclusive to the SDL_HAPTIC_CONSTANT effect.
   1.591 - *
   1.592 - * A constant effect applies a constant force in the specified direction
   1.593 + *  \brief A structure containing a template for a Constant effect.
   1.594 + *  
   1.595 + *  The struct is exclusive to the ::SDL_HAPTIC_CONSTANT effect.
   1.596 + *  
   1.597 + *  A constant effect applies a constant force in the specified direction
   1.598   *  to the joystick.
   1.599 - *
   1.600 - * \sa SDL_HAPTIC_CONSTANT
   1.601 - * \sa SDL_HapticEffect
   1.602 + *  
   1.603 + *  \sa SDL_HAPTIC_CONSTANT
   1.604 + *  \sa SDL_HapticEffect
   1.605   */
   1.606  typedef struct SDL_HapticConstant
   1.607  {
   1.608      /* Header */
   1.609 -    Uint16 type;            /**< SDL_HAPTIC_CONSTANT */
   1.610 +    Uint16 type;            /**< ::SDL_HAPTIC_CONSTANT */
   1.611      SDL_HapticDirection direction;  /**< Direction of the effect. */
   1.612  
   1.613      /* Replay */
   1.614 @@ -429,71 +449,70 @@
   1.615      Uint16 fade_length;     /**< Duration of the fade. */
   1.616      Uint16 fade_level;      /**< Level at the end of the fade. */
   1.617  } SDL_HapticConstant;
   1.618 +
   1.619  /**
   1.620 - * \struct SDL_HapticPeriodic
   1.621 - *
   1.622 - * \brief A structure containing a template for a Periodic effect.
   1.623 - *
   1.624 - * The struct handles the following effects:
   1.625 - *   - SDL_HAPTIC_SINE
   1.626 - *   - SDL_HAPTIC_SQUARE
   1.627 - *   - SDL_HAPTIC_TRIANGLE
   1.628 - *   - SDL_HAPTIC_SAWTOOTHUP
   1.629 - *   - SDL_HAPTIC_SAWTOOTHDOWN
   1.630 - *
   1.631 - * A periodic effect consists in a wave-shaped effect that repeats itself
   1.632 + *  \brief A structure containing a template for a Periodic effect.
   1.633 + *  
   1.634 + *  The struct handles the following effects:
   1.635 + *   - ::SDL_HAPTIC_SINE
   1.636 + *   - ::SDL_HAPTIC_SQUARE
   1.637 + *   - ::SDL_HAPTIC_TRIANGLE
   1.638 + *   - ::SDL_HAPTIC_SAWTOOTHUP
   1.639 + *   - ::SDL_HAPTIC_SAWTOOTHDOWN
   1.640 + *  
   1.641 + *  A periodic effect consists in a wave-shaped effect that repeats itself
   1.642   *  over time.  The type determines the shape of the wave and the parameters
   1.643   *  determine the dimensions of the wave.
   1.644 + *  
   1.645 + *  Phase is given by hundredth of a cyle meaning that giving the phase a value
   1.646 + *  of 9000 will displace it 25% of it's period.  Here are sample values:
   1.647 + *   -     0: No phase displacement.
   1.648 + *   -  9000: Displaced 25% of it's period.
   1.649 + *   - 18000: Displaced 50% of it's period.
   1.650 + *   - 27000: Displaced 75% of it's period.
   1.651 + *   - 36000: Displaced 100% of it's period, same as 0, but 0 is preffered.
   1.652   *
   1.653 - * Phase is given by hundredth of a cyle meaning that giving the phase a value
   1.654 - *  of 9000 will displace it 25% of it's period.  Here are sample values:
   1.655 - *    -     0: No phase displacement.
   1.656 - *    -  9000: Displaced 25% of it's period.
   1.657 - *    - 18000: Displaced 50% of it's period.
   1.658 - *    - 27000: Displaced 75% of it's period.
   1.659 - *    - 36000: Displaced 100% of it's period, same as 0, but 0 is preffered.
   1.660 - *
   1.661 - * Examples:
   1.662 - * \code
   1.663 - * SDL_HAPTIC_SINE
   1.664 - *   __      __      __      __
   1.665 - *  /  \    /  \    /  \    /
   1.666 - * /    \__/    \__/    \__/
   1.667 - *
   1.668 - * SDL_HAPTIC_SQUARE
   1.669 - *  __    __    __    __    __
   1.670 - * |  |  |  |  |  |  |  |  |  |
   1.671 - * |  |__|  |__|  |__|  |__|  |
   1.672 - *
   1.673 - * SDL_HAPTIC_TRIANGLE
   1.674 - *   /\    /\    /\    /\    /\
   1.675 - *  /  \  /  \  /  \  /  \  /
   1.676 - * /    \/    \/    \/    \/
   1.677 - *
   1.678 - * SDL_HAPTIC_SAWTOOTHUP
   1.679 - *   /|  /|  /|  /|  /|  /|  /|
   1.680 - *  / | / | / | / | / | / | / |
   1.681 - * /  |/  |/  |/  |/  |/  |/  |
   1.682 - *
   1.683 - * SDL_HAPTIC_SAWTOOTHDOWN
   1.684 - * \  |\  |\  |\  |\  |\  |\  |
   1.685 - *  \ | \ | \ | \ | \ | \ | \ |
   1.686 - *   \|  \|  \|  \|  \|  \|  \|
   1.687 - * \endcode
   1.688 - *
   1.689 - * \sa SDL_HAPTIC_SINE
   1.690 - * \sa SDL_HAPTIC_SQUARE
   1.691 - * \sa SDL_HAPTIC_TRIANGLE
   1.692 - * \sa SDL_HAPTIC_SAWTOOTHUP
   1.693 - * \sa SDL_HAPTIC_SAWTOOTHDOWN
   1.694 - * \sa SDL_HapticEffect
   1.695 + *  Examples:
   1.696 + *  \verbatim
   1.697 +    SDL_HAPTIC_SINE
   1.698 +      __      __      __      __
   1.699 +     /  \    /  \    /  \    /
   1.700 +    /    \__/    \__/    \__/
   1.701 +    
   1.702 +    SDL_HAPTIC_SQUARE
   1.703 +     __    __    __    __    __
   1.704 +    |  |  |  |  |  |  |  |  |  |
   1.705 +    |  |__|  |__|  |__|  |__|  |
   1.706 +    
   1.707 +    SDL_HAPTIC_TRIANGLE
   1.708 +      /\    /\    /\    /\    /\
   1.709 +     /  \  /  \  /  \  /  \  /
   1.710 +    /    \/    \/    \/    \/
   1.711 +    
   1.712 +    SDL_HAPTIC_SAWTOOTHUP
   1.713 +      /|  /|  /|  /|  /|  /|  /|
   1.714 +     / | / | / | / | / | / | / |
   1.715 +    /  |/  |/  |/  |/  |/  |/  |
   1.716 +    
   1.717 +    SDL_HAPTIC_SAWTOOTHDOWN
   1.718 +    \  |\  |\  |\  |\  |\  |\  |
   1.719 +     \ | \ | \ | \ | \ | \ | \ |
   1.720 +      \|  \|  \|  \|  \|  \|  \|
   1.721 +    \endverbatim
   1.722 + *  
   1.723 + *  \sa SDL_HAPTIC_SINE
   1.724 + *  \sa SDL_HAPTIC_SQUARE
   1.725 + *  \sa SDL_HAPTIC_TRIANGLE
   1.726 + *  \sa SDL_HAPTIC_SAWTOOTHUP
   1.727 + *  \sa SDL_HAPTIC_SAWTOOTHDOWN
   1.728 + *  \sa SDL_HapticEffect
   1.729   */
   1.730  typedef struct SDL_HapticPeriodic
   1.731  {
   1.732      /* Header */
   1.733 -    Uint16 type;        /**< SDL_HAPTIC_SINE, SDL_HAPTIC_SQUARE,
   1.734 -                             SDL_HAPTIC_TRIANGLE, SDL_HAPTIC_SAWTOOTHUP or
   1.735 -                             SDL_HAPTIC_SAWTOOTHDOWN */
   1.736 +    Uint16 type;        /**< ::SDL_HAPTIC_SINE, ::SDL_HAPTIC_SQUARE,
   1.737 +                             ::SDL_HAPTIC_TRIANGLE, ::SDL_HAPTIC_SAWTOOTHUP or
   1.738 +                             ::SDL_HAPTIC_SAWTOOTHDOWN */
   1.739      SDL_HapticDirection direction;  /**< Direction of the effect. */
   1.740  
   1.741      /* Replay */
   1.742 @@ -516,37 +535,36 @@
   1.743      Uint16 fade_length; /**< Duration of the fade. */
   1.744      Uint16 fade_level;  /**< Level at the end of the fade. */
   1.745  } SDL_HapticPeriodic;
   1.746 +
   1.747  /**
   1.748 - * \struct SDL_HapticCondition
   1.749 - *
   1.750 - * \brief A structure containing a template for a Condition effect.
   1.751 - *
   1.752 - * The struct handles the following effects:
   1.753 - *   - SDL_HAPTIC_SPRING: Effect based on axes position.
   1.754 - *   - SDL_HAPTIC_DAMPER: Effect based on axes velocity.
   1.755 - *   - SDL_HAPTIC_INERTIA: Effect based on axes acceleration.
   1.756 - *   - SDL_HAPTIC_FRICTION: Effect based on axes movement.
   1.757 - *
   1.758 - * Direction is handled by condition internals instead of a direction member.
   1.759 + *  \brief A structure containing a template for a Condition effect.
   1.760 + *  
   1.761 + *  The struct handles the following effects:
   1.762 + *   - ::SDL_HAPTIC_SPRING: Effect based on axes position.
   1.763 + *   - ::SDL_HAPTIC_DAMPER: Effect based on axes velocity.
   1.764 + *   - ::SDL_HAPTIC_INERTIA: Effect based on axes acceleration.
   1.765 + *   - ::SDL_HAPTIC_FRICTION: Effect based on axes movement.
   1.766 + *  
   1.767 + *  Direction is handled by condition internals instead of a direction member.
   1.768   *  The condition effect specific members have three parameters.  The first
   1.769   *  refers to the X axis, the second refers to the Y axis and the third
   1.770   *  refers to the Z axis.  The right terms refer to the positive side of the
   1.771   *  axis and the left terms refer to the negative side of the axis.  Please 
   1.772 - *  refer to the SDL_HapticDirection  diagram for which side is positive and
   1.773 + *  refer to the ::SDL_HapticDirection diagram for which side is positive and
   1.774   *  which is negative.
   1.775 - *
   1.776 - * \sa SDL_HapticDirection
   1.777 - * \sa SDL_HAPTIC_SPRING
   1.778 - * \sa SDL_HAPTIC_DAMPER
   1.779 - * \sa SDL_HAPTIC_INERTIA
   1.780 - * \sa SDL_HAPTIC_FRICTION
   1.781 - * \sa SDL_HapticEffect
   1.782 + *  
   1.783 + *  \sa SDL_HapticDirection
   1.784 + *  \sa SDL_HAPTIC_SPRING
   1.785 + *  \sa SDL_HAPTIC_DAMPER
   1.786 + *  \sa SDL_HAPTIC_INERTIA
   1.787 + *  \sa SDL_HAPTIC_FRICTION
   1.788 + *  \sa SDL_HapticEffect
   1.789   */
   1.790  typedef struct SDL_HapticCondition
   1.791  {
   1.792      /* Header */
   1.793 -    Uint16 type;            /**< SDL_HAPTIC_SPRING, SDL_HAPTIC_DAMPER,
   1.794 -                                 SDL_HAPTIC_INERTIA or SDL_HAPTIC_FRICTION */
   1.795 +    Uint16 type;            /**< ::SDL_HAPTIC_SPRING, ::SDL_HAPTIC_DAMPER,
   1.796 +                                 ::SDL_HAPTIC_INERTIA or ::SDL_HAPTIC_FRICTION */
   1.797      SDL_HapticDirection direction;  /**< Direction of the effect - Not used ATM. */
   1.798  
   1.799      /* Replay */
   1.800 @@ -565,25 +583,24 @@
   1.801      Uint16 deadband[3];     /**< Size of the dead zone. */
   1.802      Sint16 center[3];       /**< Position of the dead zone. */
   1.803  } SDL_HapticCondition;
   1.804 +
   1.805  /**
   1.806 - * \struct SDL_HapticRamp
   1.807 - *
   1.808 - * \brief A structure containing a template for a Ramp effect.
   1.809 - *
   1.810 - * This struct is exclusively for the SDL_HAPTIC_RAMP effect.
   1.811 - *
   1.812 - * The ramp effect starts at start strength and ends at end strength.
   1.813 + *  \brief A structure containing a template for a Ramp effect.
   1.814 + *  
   1.815 + *  This struct is exclusively for the ::SDL_HAPTIC_RAMP effect.
   1.816 + *  
   1.817 + *  The ramp effect starts at start strength and ends at end strength.
   1.818   *  It augments in linear fashion.  If you use attack and fade with a ramp
   1.819   *  they effects get added to the ramp effect making the effect become
   1.820   *  quadratic instead of linear.
   1.821 - *
   1.822 - * \sa SDL_HAPTIC_RAMP
   1.823 - * \sa SDL_HapticEffect
   1.824 + *  
   1.825 + *  \sa SDL_HAPTIC_RAMP
   1.826 + *  \sa SDL_HapticEffect
   1.827   */
   1.828  typedef struct SDL_HapticRamp
   1.829  {
   1.830      /* Header */
   1.831 -    Uint16 type;            /**< SDL_HAPTIC_RAMP */
   1.832 +    Uint16 type;            /**< ::SDL_HAPTIC_RAMP */
   1.833      SDL_HapticDirection direction;  /**< Direction of the effect. */
   1.834  
   1.835      /* Replay */
   1.836 @@ -604,25 +621,24 @@
   1.837      Uint16 fade_length;     /**< Duration of the fade. */
   1.838      Uint16 fade_level;      /**< Level at the end of the fade. */
   1.839  } SDL_HapticRamp;
   1.840 +
   1.841  /**
   1.842 - * \struct SDL_HapticCustom
   1.843 - *
   1.844 - * \brief A structure containing a template for the SDL_HAPTIC_CUSTOM effect.
   1.845 - *
   1.846 - * A custom force feedback effect is much like a periodic effect, where the
   1.847 + *  \brief A structure containing a template for the ::SDL_HAPTIC_CUSTOM effect.
   1.848 + *  
   1.849 + *  A custom force feedback effect is much like a periodic effect, where the
   1.850   *  application can define it's exact shape.  You will have to allocate the
   1.851   *  data yourself.  Data should consist of channels * samples Uint16 samples.
   1.852 - *
   1.853 - * If channels is one, the effect is rotated using the defined direction.
   1.854 + *  
   1.855 + *  If channels is one, the effect is rotated using the defined direction.
   1.856   *  Otherwise it uses the samples in data for the different axes.
   1.857 - *
   1.858 - * \sa SDL_HAPTIC_CUSTOM
   1.859 - * \sa SDL_HapticEffect
   1.860 + *  
   1.861 + *  \sa SDL_HAPTIC_CUSTOM
   1.862 + *  \sa SDL_HapticEffect
   1.863   */
   1.864  typedef struct SDL_HapticCustom
   1.865  {
   1.866      /* Header */
   1.867 -    Uint16 type;            /**< SDL_HAPTIC_CUSTOM */
   1.868 +    Uint16 type;            /**< ::SDL_HAPTIC_CUSTOM */
   1.869      SDL_HapticDirection direction;  /**< Direction of the effect. */
   1.870  
   1.871      /* Replay */
   1.872 @@ -645,76 +661,74 @@
   1.873      Uint16 fade_length;     /**< Duration of the fade. */
   1.874      Uint16 fade_level;      /**< Level at the end of the fade. */
   1.875  } SDL_HapticCustom;
   1.876 +
   1.877  /**
   1.878 - * \union SDL_HapticEffect
   1.879 - *
   1.880 - * \brief The generic template for any haptic effect.
   1.881 - *
   1.882 - * All values max at 32767 (0x7FFF).  Signed values also can be negative.
   1.883 + *  \brief The generic template for any haptic effect.
   1.884 + *  
   1.885 + *  All values max at 32767 (0x7FFF).  Signed values also can be negative.
   1.886   *  Time values unless specified otherwise are in milliseconds.
   1.887 - *
   1.888 - * You can also pass SDL_HAPTIC_INFINITY to length instead of a 0-32767 value.
   1.889 - *  Neither delay, interval, attack_length nor fade_length support 
   1.890 - *  SDL_HAPTIC_INFINITY.  Fade will also not be used since effect never ends.
   1.891 - *
   1.892 - * Additionally, the SDL_HAPTIC_RAMP effect does not support a duration of
   1.893 - *  SDL_HAPTIC_INFINITY.
   1.894 - *
   1.895 - * Button triggers may not be supported on all devices, it is advised to not
   1.896 + *  
   1.897 + *  You can also pass ::SDL_HAPTIC_INFINITY to length instead of a 0-32767 
   1.898 + *  value.  Neither delay, interval, attack_length nor fade_length support 
   1.899 + *  ::SDL_HAPTIC_INFINITY.  Fade will also not be used since effect never ends.
   1.900 + *  
   1.901 + *  Additionally, the ::SDL_HAPTIC_RAMP effect does not support a duration of
   1.902 + *  ::SDL_HAPTIC_INFINITY.
   1.903 + *  
   1.904 + *  Button triggers may not be supported on all devices, it is advised to not
   1.905   *  use them if possible.  Buttons start at index 1 instead of index 0 like
   1.906   *  they joystick.
   1.907 + *  
   1.908 + *  If both attack_length and fade_level are 0, the envelope is not used,
   1.909 + *  otherwise both values are used.
   1.910 + *  
   1.911 + *  Common parts:
   1.912 + *  \code
   1.913 + *  // Replay - All effects have this
   1.914 + *  Uint32 length;        // Duration of effect (ms).
   1.915 + *  Uint16 delay;         // Delay before starting effect.
   1.916 + *  
   1.917 + *  // Trigger - All effects have this
   1.918 + *  Uint16 button;        // Button that triggers effect.
   1.919 + *  Uint16 interval;      // How soon before effect can be triggered again.
   1.920 + *  
   1.921 + *  // Envelope - All effects except condition effects have this
   1.922 + *  Uint16 attack_length; // Duration of the attack (ms).
   1.923 + *  Uint16 attack_level;  // Level at the start of the attack.
   1.924 + *  Uint16 fade_length;   // Duration of the fade out (ms).
   1.925 + *  Uint16 fade_level;    // Level at the end of the fade.
   1.926 + *  \endcode
   1.927   *
   1.928 - * If both attack_length and fade_level are 0, the envelope is not used,
   1.929 - *  otherwise both values are used.
   1.930   *
   1.931 - * Common parts:
   1.932 - * \code
   1.933 - * // Replay - All effects have this
   1.934 - * Uint32 length;        // Duration of effect (ms).
   1.935 - * Uint16 delay;         // Delay before starting effect.
   1.936 - *
   1.937 - * // Trigger - All effects have this
   1.938 - * Uint16 button;        // Button that triggers effect.
   1.939 - * Uint16 interval;      // How soon before effect can be triggered again.
   1.940 - *
   1.941 - * // Envelope - All effects except condition effects have this
   1.942 - * Uint16 attack_length; // Duration of the attack (ms).
   1.943 - * Uint16 attack_level;  // Level at the start of the attack.
   1.944 - * Uint16 fade_length;   // Duration of the fade out (ms).
   1.945 - * Uint16 fade_level;    // Level at the end of the fade.
   1.946 - * \endcode
   1.947 - *
   1.948 - *
   1.949 - * Here we have an example of a constant effect evolution in time:
   1.950 - *
   1.951 - * \code
   1.952 - * Strength
   1.953 - * ^
   1.954 - * |
   1.955 - * |    effect level -->  _________________
   1.956 - * |                     /                 \
   1.957 - * |                    /                   \
   1.958 - * |                   /                     \
   1.959 - * |                  /                       \ 
   1.960 - * | attack_level --> |                        \
   1.961 - * |                  |                        |  <---  fade_level
   1.962 - * |
   1.963 - * +--------------------------------------------------> Time
   1.964 - *                    [--]                 [---]
   1.965 - *                    attack_length        fade_length
   1.966 - * 
   1.967 - * [------------------][-----------------------]
   1.968 - * delay               length
   1.969 - * \endcode
   1.970 - *
   1.971 - * Note either the attack_level or the fade_level may be above the actual
   1.972 + *  Here we have an example of a constant effect evolution in time:
   1.973 + *  \verbatim
   1.974 +    Strength
   1.975 +    ^
   1.976 +    |
   1.977 +    |    effect level -->  _________________
   1.978 +    |                     /                 \
   1.979 +    |                    /                   \
   1.980 +    |                   /                     \
   1.981 +    |                  /                       \ 
   1.982 +    | attack_level --> |                        \
   1.983 +    |                  |                        |  <---  fade_level
   1.984 +    |
   1.985 +    +--------------------------------------------------> Time
   1.986 +                       [--]                 [---]
   1.987 +                       attack_length        fade_length
   1.988 +    
   1.989 +    [------------------][-----------------------]
   1.990 +    delay               length
   1.991 +    \endverbatim
   1.992 + *  
   1.993 + *  Note either the attack_level or the fade_level may be above the actual
   1.994   *  effect level.
   1.995   *
   1.996 - * \sa SDL_HapticConstant
   1.997 - * \sa SDL_HapticPeriodic
   1.998 - * \sa SDL_HapticCondition
   1.999 - * \sa SDL_HapticRamp
  1.1000 - * \sa SDL_HapticCustom
  1.1001 + *  \sa SDL_HapticConstant
  1.1002 + *  \sa SDL_HapticPeriodic
  1.1003 + *  \sa SDL_HapticCondition
  1.1004 + *  \sa SDL_HapticRamp
  1.1005 + *  \sa SDL_HapticCustom
  1.1006   */
  1.1007  typedef union SDL_HapticEffect
  1.1008  {
  1.1009 @@ -730,413 +744,368 @@
  1.1010  
  1.1011  /* Function prototypes */
  1.1012  /**
  1.1013 - * \fn int SDL_NumHaptics(void)
  1.1014 - *
  1.1015 - * \brief Count the number of joysticks attached to the system.
  1.1016 - *
  1.1017 - *    \return Number of haptic devices detected on the system.
  1.1018 + *  \brief Count the number of joysticks attached to the system.
  1.1019 + *  
  1.1020 + *  \return Number of haptic devices detected on the system.
  1.1021   */
  1.1022  extern DECLSPEC int SDLCALL SDL_NumHaptics(void);
  1.1023  
  1.1024  /**
  1.1025 - * \fn const char * SDL_HapticName(int device_index)
  1.1026 + *  \brief Get the implementation dependent name of a Haptic device.
  1.1027 + *  
  1.1028 + *  This can be called before any joysticks are opened.
  1.1029 + *  If no name can be found, this function returns NULL.
  1.1030 + *  
  1.1031 + *  \param device_index Index of the device to get it's name.
  1.1032 + *  \return Name of the device or NULL on error.
  1.1033   *
  1.1034 - * \brief Get the implementation dependent name of a Haptic device.
  1.1035 - * This can be called before any joysticks are opened.
  1.1036 - * If no name can be found, this function returns NULL.
  1.1037 - *
  1.1038 - *    \param device_index Index of the device to get it's name.
  1.1039 - *    \return Name of the device or NULL on error.
  1.1040 - *
  1.1041 - * \sa SDL_NumHaptics
  1.1042 + *  \sa SDL_NumHaptics
  1.1043   */
  1.1044  extern DECLSPEC const char *SDLCALL SDL_HapticName(int device_index);
  1.1045  
  1.1046  /**
  1.1047 - * \fn SDL_Haptic * SDL_HapticOpen(int device_index)
  1.1048 + *  \brief Opens a Haptic device for usage.
  1.1049 + *  
  1.1050 + *  The index passed as an argument refers to the N'th Haptic device on this 
  1.1051 + *  system.
  1.1052   *
  1.1053 - * \brief Opens a Haptic device for usage - the index passed as an
  1.1054 - * argument refers to the N'th Haptic device on this system.
  1.1055 + *  When opening a haptic device, it's gain will be set to maximum and
  1.1056 + *  autocenter will be disabled.  To modify these values use
  1.1057 + *  SDL_HapticSetGain() and SDL_HapticSetAutocenter().
  1.1058   *
  1.1059 - * When opening a haptic device, it's gain will be set to maximum and
  1.1060 - *  autocenter will be disabled.  To modify these values use
  1.1061 - *  SDL_HapticSetGain and SDL_HapticSetAutocenter
  1.1062 + *  \param device_index Index of the device to open.
  1.1063 + *  \return Device identifier or NULL on error.
  1.1064   *
  1.1065 - *    \param device_index Index of the device to open.
  1.1066 - *    \return Device identifier or NULL on error.
  1.1067 - *
  1.1068 - * \sa SDL_HapticIndex
  1.1069 - * \sa SDL_HapticOpenFromMouse
  1.1070 - * \sa SDL_HapticOpenFromJoystick
  1.1071 - * \sa SDL_HapticClose
  1.1072 - * \sa SDL_HapticSetGain
  1.1073 - * \sa SDL_HapticSetAutocenter
  1.1074 - * \sa SDL_HapticPause
  1.1075 - * \sa SDL_HapticStopAll
  1.1076 + *  \sa SDL_HapticIndex
  1.1077 + *  \sa SDL_HapticOpenFromMouse
  1.1078 + *  \sa SDL_HapticOpenFromJoystick
  1.1079 + *  \sa SDL_HapticClose
  1.1080 + *  \sa SDL_HapticSetGain
  1.1081 + *  \sa SDL_HapticSetAutocenter
  1.1082 + *  \sa SDL_HapticPause
  1.1083 + *  \sa SDL_HapticStopAll
  1.1084   */
  1.1085  extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpen(int device_index);
  1.1086  
  1.1087  /**
  1.1088 - * \fn int SDL_HapticOpened(int device_index)
  1.1089 - *
  1.1090 - * \brief Checks if the haptic device at index has been opened.
  1.1091 - *
  1.1092 - *    \param device_index Index to check to see if it has been opened.
  1.1093 - *    \return 1 if it has been opened or 0 if it hasn't.
  1.1094 - * 
  1.1095 - * \sa SDL_HapticOpen
  1.1096 - * \sa SDL_HapticIndex
  1.1097 + *  \brief Checks if the haptic device at index has been opened.
  1.1098 + *  
  1.1099 + *  \param device_index Index to check to see if it has been opened.
  1.1100 + *  \return 1 if it has been opened or 0 if it hasn't.
  1.1101 + *  
  1.1102 + *  \sa SDL_HapticOpen
  1.1103 + *  \sa SDL_HapticIndex
  1.1104   */
  1.1105  extern DECLSPEC int SDLCALL SDL_HapticOpened(int device_index);
  1.1106  
  1.1107  /**
  1.1108 - * \fn int SDL_HapticIndex(SDL_Haptic * haptic)
  1.1109 - *
  1.1110 - * \brief Gets the index of a haptic device.
  1.1111 - *
  1.1112 - *    \param haptic Haptic device to get the index of.
  1.1113 - *    \return The index of the haptic device or -1 on error.
  1.1114 - *
  1.1115 - * \sa SDL_HapticOpen
  1.1116 - * \sa SDL_HapticOpened
  1.1117 + *  \brief Gets the index of a haptic device.
  1.1118 + *  
  1.1119 + *  \param haptic Haptic device to get the index of.
  1.1120 + *  \return The index of the haptic device or -1 on error.
  1.1121 + *  
  1.1122 + *  \sa SDL_HapticOpen
  1.1123 + *  \sa SDL_HapticOpened
  1.1124   */
  1.1125  extern DECLSPEC int SDLCALL SDL_HapticIndex(SDL_Haptic * haptic);
  1.1126  
  1.1127  /**
  1.1128 - * \fn int SDL_MouseIsHaptic(void)
  1.1129 - *
  1.1130 - * \brief Gets whether or not the current mouse has haptic capabilities.
  1.1131 - *
  1.1132 - *    \return SDL_TRUE if the mouse is haptic, SDL_FALSE if it isn't.
  1.1133 - *
  1.1134 - * \sa SDL_HapticOpenFromMouse
  1.1135 + *  \brief Gets whether or not the current mouse has haptic capabilities.
  1.1136 + *  
  1.1137 + *  \return SDL_TRUE if the mouse is haptic, SDL_FALSE if it isn't.
  1.1138 + *  
  1.1139 + *  \sa SDL_HapticOpenFromMouse
  1.1140   */
  1.1141  extern DECLSPEC int SDLCALL SDL_MouseIsHaptic(void);
  1.1142  
  1.1143  /**
  1.1144 - * \fn SDL_Haptic * SDL_HapticOpenFromMouse(void)
  1.1145 - *
  1.1146 - * \brief Tries to open a haptic device from the current mouse.
  1.1147 - *
  1.1148 - *    \return The haptic device identifier or NULL on error.
  1.1149 - *
  1.1150 - * \sa SDL_MouseIsHaptic
  1.1151 - * \sa SDL_HapticOpen
  1.1152 + *  \brief Tries to open a haptic device from the current mouse.
  1.1153 + *  
  1.1154 + *  \return The haptic device identifier or NULL on error.
  1.1155 + *  
  1.1156 + *  \sa SDL_MouseIsHaptic
  1.1157 + *  \sa SDL_HapticOpen
  1.1158   */
  1.1159  extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromMouse(void);
  1.1160  
  1.1161  /**
  1.1162 - * \fn int SDL_JoystickIsHaptic(SDL_Joystick * joystick)
  1.1163 - *
  1.1164 - * \brief Checks to see if a joystick has haptic features.
  1.1165 - *
  1.1166 - *    \param joystick Joystick to test for haptic capabilities.
  1.1167 - *    \return SDL_TRUE if the joystick is haptic, SDL_FALSE if it isn't
  1.1168 - *            or -1 if an error ocurred.
  1.1169 - *
  1.1170 - * \sa SDL_HapticOpenFromJoystick
  1.1171 + *  \brief Checks to see if a joystick has haptic features.
  1.1172 + *  
  1.1173 + *  \param joystick Joystick to test for haptic capabilities.
  1.1174 + *  \return 1 if the joystick is haptic, 0 if it isn't
  1.1175 + *          or -1 if an error ocurred.
  1.1176 + *  
  1.1177 + *  \sa SDL_HapticOpenFromJoystick
  1.1178   */
  1.1179  extern DECLSPEC int SDLCALL SDL_JoystickIsHaptic(SDL_Joystick * joystick);
  1.1180  
  1.1181  /**
  1.1182 - * \fn SDL_Haptic * SDL_HapticOpenFromJoystick(SDL_Joystick * joystick)
  1.1183 - *
  1.1184 - * \brief Opens a Haptic device for usage from a Joystick device.  Still has
  1.1185 - * to be closed seperately to the joystick.
  1.1186 - *
  1.1187 - * When opening from a joystick you should first close the haptic device before
  1.1188 + *  \brief Opens a Haptic device for usage from a Joystick device.
  1.1189 + *  
  1.1190 + *  You must still close the haptic device seperately.  It will not be closed 
  1.1191 + *  with the joystick.
  1.1192 + *  
  1.1193 + *  When opening from a joystick you should first close the haptic device before
  1.1194   *  closing the joystick device.  If not, on some implementations the haptic
  1.1195   *  device will also get unallocated and you'll be unable to use force feedback
  1.1196   *  on that device.
  1.1197 - *
  1.1198 - *    \param joystick Joystick to create a haptic device from.
  1.1199 - *    \return A valid haptic device identifier on success or NULL on error.
  1.1200 - *
  1.1201 - * \sa SDL_HapticOpen
  1.1202 - * \sa SDL_HapticClose
  1.1203 + *  
  1.1204 + *  \param joystick Joystick to create a haptic device from.
  1.1205 + *  \return A valid haptic device identifier on success or NULL on error.
  1.1206 + *  
  1.1207 + *  \sa SDL_HapticOpen
  1.1208 + *  \sa SDL_HapticClose
  1.1209   */
  1.1210  extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromJoystick(SDL_Joystick *
  1.1211                                                                 joystick);
  1.1212  
  1.1213  /**
  1.1214 - * \fn void SDL_HapticClose(SDL_Haptic * haptic)
  1.1215 - *
  1.1216 - * \brief Closes a Haptic device previously opened with SDL_HapticOpen.
  1.1217 - *
  1.1218 - *    \param haptic Haptic device to close.
  1.1219 + *  \brief Closes a Haptic device previously opened with SDL_HapticOpen().
  1.1220 + *  
  1.1221 + *  \param haptic Haptic device to close.
  1.1222   */
  1.1223  extern DECLSPEC void SDLCALL SDL_HapticClose(SDL_Haptic * haptic);
  1.1224  
  1.1225  /**
  1.1226 - * \fn int SDL_HapticNumEffects(SDL_Haptic * haptic)
  1.1227 - *
  1.1228 - * \brief Returns the number of effects a haptic device can store.
  1.1229 - *
  1.1230 - * On some platforms this isn't fully supported, and therefore is an
  1.1231 + *  \brief Returns the number of effects a haptic device can store.
  1.1232 + *  
  1.1233 + *  On some platforms this isn't fully supported, and therefore is an
  1.1234   *  aproximation.  Always check to see if your created effect was actually
  1.1235 - *  created and do not rely solely on HapticNumEffects.
  1.1236 - *
  1.1237 - *    \param haptic The haptic device to query effect max.
  1.1238 - *    \return The number of effects the haptic device can store or
  1.1239 - *            -1 on error.
  1.1240 - *
  1.1241 - * \sa SDL_HapticNumEffectsPlaying
  1.1242 - * \sa SDL_HapticQuery
  1.1243 + *  created and do not rely solely on SDL_HapticNumEffects().
  1.1244 + *  
  1.1245 + *  \param haptic The haptic device to query effect max.
  1.1246 + *  \return The number of effects the haptic device can store or
  1.1247 + *          -1 on error.
  1.1248 + *  
  1.1249 + *  \sa SDL_HapticNumEffectsPlaying
  1.1250 + *  \sa SDL_HapticQuery
  1.1251   */
  1.1252  extern DECLSPEC int SDLCALL SDL_HapticNumEffects(SDL_Haptic * haptic);
  1.1253  
  1.1254  /**
  1.1255 - * \fn int SDL_HapticNumEffectsPlaying(SDL_Haptic * haptic)
  1.1256 + *  \brief Returns the number of effects a haptic device can play at the same 
  1.1257 + *         time.
  1.1258 + *  
  1.1259 + *  This is not supported on all platforms, but will always return a value.  
  1.1260 + *  Added here for the sake of completness.
  1.1261 + *  
  1.1262 + *  \param haptic The haptic device to query maximum playing effects.
  1.1263 + *  \return The number of effects the haptic device can play at the same time
  1.1264 + *          or -1 on error.
  1.1265   *
  1.1266 - * \brief Returns the number of effects a haptic device can play at the same time.
  1.1267 - *
  1.1268 - * This is not supported on all platforms, but will always return a value.  Added
  1.1269 - *  here for the sake of completness.
  1.1270 - *
  1.1271 - *    \param haptic The haptic device to query maximum playing effect.s
  1.1272 - *    \return The number of effects the haptic device can play at the same time
  1.1273 - *            or -1 on error.
  1.1274 - *
  1.1275 - * \sa SDL_HapticNumEffects
  1.1276 - * \sa SDL_HapticQuery
  1.1277 + *  \sa SDL_HapticNumEffects
  1.1278 + *  \sa SDL_HapticQuery
  1.1279   */
  1.1280  extern DECLSPEC int SDLCALL SDL_HapticNumEffectsPlaying(SDL_Haptic * haptic);
  1.1281  
  1.1282  /**
  1.1283 - * \fn unsigned int SDL_HapticQuery(SDL_Haptic * haptic)
  1.1284 - *
  1.1285 - * \brief Gets the haptic devices supported features in bitwise matter.
  1.1286 - *
  1.1287 - * Example: 
  1.1288 - * \code
  1.1289 - * if (SDL_HapticQueryEffects(haptic) & SDL_HAPTIC_CONSTANT) {
  1.1290 - *    printf("We have constant haptic effect!");
  1.1291 - * }
  1.1292 - * \endcode
  1.1293 - *    
  1.1294 - *
  1.1295 - *    \param haptic The haptic device to query.
  1.1296 - *    \return Haptic features in bitwise manner (OR'd).
  1.1297 - *
  1.1298 - * \sa SDL_HapticNumEffects
  1.1299 - * \sa SDL_HapticEffectSupported
  1.1300 + *  \brief Gets the haptic devices supported features in bitwise matter.
  1.1301 + *  
  1.1302 + *  Example: 
  1.1303 + *  \code
  1.1304 + *  if (SDL_HapticQueryEffects(haptic) & SDL_HAPTIC_CONSTANT) {
  1.1305 + *      printf("We have constant haptic effect!");
  1.1306 + *  }
  1.1307 + *  \endcode
  1.1308 + *  
  1.1309 + *  \param haptic The haptic device to query.
  1.1310 + *  \return Haptic features in bitwise manner (OR'd).
  1.1311 + *  
  1.1312 + *  \sa SDL_HapticNumEffects
  1.1313 + *  \sa SDL_HapticEffectSupported
  1.1314   */
  1.1315  extern DECLSPEC unsigned int SDLCALL SDL_HapticQuery(SDL_Haptic * haptic);
  1.1316  
  1.1317  
  1.1318  /**
  1.1319 - * \fn int SDL_HapticNumAxes(SDL_Haptic * haptic)
  1.1320 - *
  1.1321 - * \brief Gets the number of haptic axes the device has.
  1.1322 - *
  1.1323 - * \sa SDL_HapticDirection
  1.1324 + *  \brief Gets the number of haptic axes the device has.
  1.1325 + *  
  1.1326 + *  \sa SDL_HapticDirection
  1.1327   */
  1.1328  extern DECLSPEC int SDLCALL SDL_HapticNumAxes(SDL_Haptic * haptic);
  1.1329  
  1.1330  /**
  1.1331 - * \fn int SDL_HapticEffectSupported(SDL_Haptic * haptic, SDL_HapticEffect * effect)
  1.1332 - *
  1.1333 - * \brief Checks to see if effect is supported by haptic.
  1.1334 - *
  1.1335 - *    \param haptic Haptic device to check on.
  1.1336 - *    \param effect Effect to check to see if it is supported.
  1.1337 - *    \return SDL_TRUE if effect is supported, SDL_FALSE if it isn't or 
  1.1338 - *            -1 on error.
  1.1339 - * 
  1.1340 - * \sa SDL_HapticQuery
  1.1341 - * \sa SDL_HapticNewEffect
  1.1342 + *  \brief Checks to see if effect is supported by haptic.
  1.1343 + *  
  1.1344 + *  \param haptic Haptic device to check on.
  1.1345 + *  \param effect Effect to check to see if it is supported.
  1.1346 + *  \return 1 if effect is supported, 0 if it isn't or -1 on error.
  1.1347 + *  
  1.1348 + *  \sa SDL_HapticQuery
  1.1349 + *  \sa SDL_HapticNewEffect
  1.1350   */
  1.1351  extern DECLSPEC int SDLCALL SDL_HapticEffectSupported(SDL_Haptic * haptic,
  1.1352                                                        SDL_HapticEffect *
  1.1353                                                        effect);
  1.1354  
  1.1355  /**
  1.1356 - * \fn int SDL_HapticNewEffect(SDL_Haptic * haptic, SDL_HapticEffect * effect)
  1.1357 - *
  1.1358 - * \brief Creates a new haptic effect on the device.
  1.1359 - *
  1.1360 - *    \param haptic Haptic device to create the effect on.
  1.1361 - *    \param effect Properties of the effect to create.
  1.1362 - *    \return The id of the effect on success or -1 on error.
  1.1363 - *
  1.1364 - * \sa SDL_HapticUpdateEffect
  1.1365 - * \sa SDL_HapticRunEffect
  1.1366 - * \sa SDL_HapticDestroyEffect
  1.1367 + *  \brief Creates a new haptic effect on the device.
  1.1368 + *  
  1.1369 + *  \param haptic Haptic device to create the effect on.
  1.1370 + *  \param effect Properties of the effect to create.
  1.1371 + *  \return The id of the effect on success or -1 on error.
  1.1372 + *  
  1.1373 + *  \sa SDL_HapticUpdateEffect
  1.1374 + *  \sa SDL_HapticRunEffect
  1.1375 + *  \sa SDL_HapticDestroyEffect
  1.1376   */
  1.1377  extern DECLSPEC int SDLCALL SDL_HapticNewEffect(SDL_Haptic * haptic,
  1.1378                                                  SDL_HapticEffect * effect);
  1.1379  
  1.1380  /**
  1.1381 - * \fn int SDL_HapticUpdateEffect(SDL_Haptic * haptic, int effect, SDL_HapticEffect * data)
  1.1382 - *
  1.1383 - * \brief Updates the properties of an effect.
  1.1384 - *
  1.1385 - * Can be used dynamically, although behaviour when dynamically changing
  1.1386 - * direction may be strange.  Specifically the effect may reupload itself
  1.1387 - * and start playing from the start.  You cannot change the type either when
  1.1388 - * running UpdateEffect.
  1.1389 - *
  1.1390 - *    \param haptic Haptic device that has the effect.
  1.1391 - *    \param effect Effect to update.
  1.1392 - *    \param data New effect properties to use.
  1.1393 - *    \return The id of the effect on success or -1 on error.
  1.1394 - *
  1.1395 - * \sa SDL_HapticNewEffect
  1.1396 - * \sa SDL_HapticRunEffect
  1.1397 - * \sa SDL_HapticDestroyEffect
  1.1398 + *  \brief Updates the properties of an effect.
  1.1399 + *  
  1.1400 + *  Can be used dynamically, although behaviour when dynamically changing
  1.1401 + *  direction may be strange.  Specifically the effect may reupload itself
  1.1402 + *  and start playing from the start.  You cannot change the type either when
  1.1403 + *  running SDL_HapticUpdateEffect().
  1.1404 + *  
  1.1405 + *  \param haptic Haptic device that has the effect.
  1.1406 + *  \param effect Effect to update.
  1.1407 + *  \param data New effect properties to use.
  1.1408 + *  \return The id of the effect on success or -1 on error.
  1.1409 + *  
  1.1410 + *  \sa SDL_HapticNewEffect
  1.1411 + *  \sa SDL_HapticRunEffect
  1.1412 + *  \sa SDL_HapticDestroyEffect
  1.1413   */
  1.1414  extern DECLSPEC int SDLCALL SDL_HapticUpdateEffect(SDL_Haptic * haptic,
  1.1415                                                     int effect,
  1.1416                                                     SDL_HapticEffect * data);
  1.1417  
  1.1418  /**
  1.1419 - * \fn int SDL_HapticRunEffect(SDL_Haptic * haptic, int effect, Uint32 iterations)
  1.1420 - *
  1.1421 - * \brief Runs the haptic effect on it's assosciated haptic device.
  1.1422 - *
  1.1423 - * If iterations are SDL_HAPTIC_INFINITY, it'll run the effect over and over
  1.1424 + *  \brief Runs the haptic effect on it's assosciated haptic device.
  1.1425 + *  
  1.1426 + *  If iterations are ::SDL_HAPTIC_INFINITY, it'll run the effect over and over
  1.1427   *  repeating the envelope (attack and fade) every time.  If you only want the
  1.1428 - *  effect to last forever, set SDL_HAPTIC_INFINITY in the effect's length
  1.1429 + *  effect to last forever, set ::SDL_HAPTIC_INFINITY in the effect's length
  1.1430   *  parameter.
  1.1431 - *
  1.1432 - *    \param haptic Haptic device to run the effect on.
  1.1433 - *    \param effect Identifier of the haptic effect to run.
  1.1434 - *    \param iterations Number of iterations to run the effect. Use
  1.1435 - *           SDL_HAPTIC_INFINITY for infinity.
  1.1436 - *    \return 0 on success or -1 on error.
  1.1437 - *
  1.1438 - * \sa SDL_HapticStopEffect
  1.1439 - * \sa SDL_HapticDestroyEffect
  1.1440 - * \sa SDL_HapticGetEffectStatus
  1.1441 + *  
  1.1442 + *  \param haptic Haptic device to run the effect on.
  1.1443 + *  \param effect Identifier of the haptic effect to run.
  1.1444 + *  \param iterations Number of iterations to run the effect. Use
  1.1445 + *         ::SDL_HAPTIC_INFINITY for infinity.
  1.1446 + *  \return 0 on success or -1 on error.
  1.1447 + *  
  1.1448 + *  \sa SDL_HapticStopEffect
  1.1449 + *  \sa SDL_HapticDestroyEffect
  1.1450 + *  \sa SDL_HapticGetEffectStatus
  1.1451   */
  1.1452  extern DECLSPEC int SDLCALL SDL_HapticRunEffect(SDL_Haptic * haptic,
  1.1453                                                  int effect,
  1.1454                                                  Uint32 iterations);
  1.1455  
  1.1456  /**
  1.1457 - * \fn int SDL_HapticStopEffect(SDL_Haptic * haptic, int effect)
  1.1458 - *
  1.1459 - * \brief Stops the haptic effect on it's assosciated haptic device.
  1.1460 - *
  1.1461 - *    \param haptic Haptic device to stop the effect on.
  1.1462 - *    \param effect Identifier of the effect to stop.
  1.1463 - *    \return 0 on success or -1 on error.
  1.1464 - *
  1.1465 - * \sa SDL_HapticRunEffect
  1.1466 - * \sa SDL_HapticDestroyEffect
  1.1467 + *  \brief Stops the haptic effect on it's assosciated haptic device.
  1.1468 + *  
  1.1469 + *  \param haptic Haptic device to stop the effect on.
  1.1470 + *  \param effect Identifier of the effect to stop.
  1.1471 + *  \return 0 on success or -1 on error.
  1.1472 + *  
  1.1473 + *  \sa SDL_HapticRunEffect
  1.1474 + *  \sa SDL_HapticDestroyEffect
  1.1475   */
  1.1476  extern DECLSPEC int SDLCALL SDL_HapticStopEffect(SDL_Haptic * haptic,
  1.1477                                                   int effect);
  1.1478  
  1.1479  /**
  1.1480 - * \fn void SDL_HapticDestroyEffect(SDL_Haptic * haptic, int effect)
  1.1481 - *
  1.1482 - * \brief Destroys a haptic effect on the device.  This will stop the effect
  1.1483 - * if it's running.  Effects are automatically destroyed when the device is
  1.1484 - * closed.
  1.1485 - *
  1.1486 - *    \param haptic Device to destroy the effect on.
  1.1487 - *    \param effect Identifier of the effect to destroy.
  1.1488 - * 
  1.1489 - * \sa SDL_HapticNewEffect
  1.1490 + *  \brief Destroys a haptic effect on the device.
  1.1491 + *  
  1.1492 + *  This will stop the effect if it's running.  Effects are automatically 
  1.1493 + *  destroyed when the device is closed.
  1.1494 + *  
  1.1495 + *  \param haptic Device to destroy the effect on.
  1.1496 + *  \param effect Identifier of the effect to destroy.
  1.1497 + *  
  1.1498 + *  \sa SDL_HapticNewEffect
  1.1499   */
  1.1500  extern DECLSPEC void SDLCALL SDL_HapticDestroyEffect(SDL_Haptic * haptic,
  1.1501                                                       int effect);
  1.1502  
  1.1503  /**
  1.1504 - * \fn int SDL_HapticGetEffectStatus(SDL_Haptic *haptic, int effect)
  1.1505 - *
  1.1506 - * \brief Gets the status of the current effect on the haptic device.
  1.1507 - *
  1.1508 - * Device must support the SDL_HAPTIC_STATUS feature.
  1.1509 - *
  1.1510 - *    \param haptic Haptic device to query the effect status on.
  1.1511 - *    \param effect Identifier of the effect to query it's status.
  1.1512 - *    \return 0 if it isn't playing, SDL_HAPTIC_PLAYING if it is playing
  1.1513 - *            or -1 on error.
  1.1514 - *
  1.1515 - * \sa SDL_HapticRunEffect
  1.1516 - * \sa SDL_HapticStopEffect
  1.1517 + *  \brief Gets the status of the current effect on the haptic device.
  1.1518 + *  
  1.1519 + *  Device must support the ::SDL_HAPTIC_STATUS feature.
  1.1520 + *  
  1.1521 + *  \param haptic Haptic device to query the effect status on.
  1.1522 + *  \param effect Identifier of the effect to query it's status.
  1.1523 + *  \return 0 if it isn't playing, ::SDL_HAPTIC_PLAYING if it is playing
  1.1524 + *          or -1 on error.
  1.1525 + *  
  1.1526 + *  \sa SDL_HapticRunEffect
  1.1527 + *  \sa SDL_HapticStopEffect
  1.1528   */
  1.1529  extern DECLSPEC int SDLCALL SDL_HapticGetEffectStatus(SDL_Haptic * haptic,
  1.1530                                                        int effect);
  1.1531  
  1.1532  /**
  1.1533 - * \fn int SDL_HapticSetGain(SDL_Haptic * haptic, int gain)
  1.1534 - *
  1.1535 - * \brief Sets the global gain of the device.  Gain should be between 0 and 100.
  1.1536 - *
  1.1537 - * Device must support the SDL_HAPTIC_GAIN feature.
  1.1538 - *
  1.1539 - * The user may specify the maxmimum gain by setting the environment variable
  1.1540 - *  SDL_HAPTIC_GAIN_MAX which should be between 0 and 100.  All calls to
  1.1541 - *  SDL_HapticSetGain will scale linearly using SDL_HAPTIC_GAIN_MAX as the
  1.1542 + *  \brief Sets the global gain of the device.
  1.1543 + *  
  1.1544 + *  Device must support the ::SDL_HAPTIC_GAIN feature.
  1.1545 + *  
  1.1546 + *  The user may specify the maxmimum gain by setting the environment variable
  1.1547 + *  ::SDL_HAPTIC_GAIN_MAX which should be between 0 and 100.  All calls to
  1.1548 + *  SDL_HapticSetGain() will scale linearly using ::SDL_HAPTIC_GAIN_MAX as the
  1.1549   *  maximum.
  1.1550 - *
  1.1551 - *    \param haptic Haptic device to set the gain on.
  1.1552 - *    \param gain Value to set the gain to, should be between 0 and 100.
  1.1553 - *    \return 0 on success or -1 on error.
  1.1554 - *
  1.1555 - * \sa SDL_HapticQuery
  1.1556 + *  
  1.1557 + *  \param haptic Haptic device to set the gain on.
  1.1558 + *  \param gain Value to set the gain to, should be between 0 and 100.
  1.1559 + *  \return 0 on success or -1 on error.
  1.1560 + *  
  1.1561 + *  \sa SDL_HapticQuery
  1.1562   */
  1.1563  extern DECLSPEC int SDLCALL SDL_HapticSetGain(SDL_Haptic * haptic, int gain);
  1.1564  
  1.1565  /**
  1.1566 - * \fn int SDL_HapticSetAutocenter(SDL_Haptic * haptic, int autocenter)
  1.1567 + *  \brief Sets the global autocenter of the device.
  1.1568 + *  
  1.1569 + *  Autocenter should be between 0 and 100.  Setting it to 0 will disable 
  1.1570 + *  autocentering.
  1.1571   *
  1.1572 - * \brief Sets the global autocenter of the device.  Autocenter should be between
  1.1573 - * 0 and 100.  Setting it to 0 will disable autocentering.
  1.1574 + *  Device must support the ::SDL_HAPTIC_AUTOCENTER feature.
  1.1575   *
  1.1576 - * Device must support the SDL_HAPTIC_AUTOCENTER feature.
  1.1577 - *
  1.1578 - *    \param haptic Haptic device to set autocentering on.
  1.1579 - *    \param autocenter Value to set autocenter to, 0 disables autocentering.
  1.1580 - *    \return 0 on success or -1 on error.
  1.1581 - *
  1.1582 - * \sa SDL_HapticQuery
  1.1583 + *  \param haptic Haptic device to set autocentering on.
  1.1584 + *  \param autocenter Value to set autocenter to, 0 disables autocentering.
  1.1585 + *  \return 0 on success or -1 on error.
  1.1586 + *  
  1.1587 + *  \sa SDL_HapticQuery
  1.1588   */
  1.1589  extern DECLSPEC int SDLCALL SDL_HapticSetAutocenter(SDL_Haptic * haptic,
  1.1590                                                      int autocenter);
  1.1591  
  1.1592  /**
  1.1593 - * \fn extern DECLSPEC int SDLCALL SDL_HapticPause(SDL_Haptic * haptic)
  1.1594 - *
  1.1595 - * \brief Pauses a haptic device.
  1.1596 - *
  1.1597 - * Device must support the SDL_HAPTIC_PAUSE feature.  Call SDL_HapticUnpause
  1.1598 - *  to resume playback.
  1.1599 - *
  1.1600 - * Do not modify the effects nor add new ones while the device is paused.
  1.1601 + *  \brief Pauses a haptic device.
  1.1602 + *  
  1.1603 + *  Device must support the ::SDL_HAPTIC_PAUSE feature.  Call 
  1.1604 + *  SDL_HapticUnpause() to resume playback.
  1.1605 + *  
  1.1606 + *  Do not modify the effects nor add new ones while the device is paused.
  1.1607   *  That can cause all sorts of weird errors.
  1.1608 - *
  1.1609 - *    \param haptic Haptic device to pause.
  1.1610 - *    \return 0 on success or -1 on error.
  1.1611 - *
  1.1612 - * \sa SDL_HapticUnpause
  1.1613 + *  
  1.1614 + *  \param haptic Haptic device to pause.
  1.1615 + *  \return 0 on success or -1 on error.
  1.1616 + *  
  1.1617 + *  \sa SDL_HapticUnpause
  1.1618   */
  1.1619  extern DECLSPEC int SDLCALL SDL_HapticPause(SDL_Haptic * haptic);
  1.1620  
  1.1621  /**
  1.1622 - * \fn extern DECLSPEC int SDLCALL SDL_HapticUnpause(SDL_Haptic * haptic)
  1.1623 - *
  1.1624 - * \brief Unpauses a haptic device.
  1.1625 - *
  1.1626 - * Call to unpause after SDL_HapticPause.
  1.1627 - *
  1.1628 - *    \param haptic Haptic device to pause.
  1.1629 - *    \return 0 on success or -1 on error.
  1.1630 - *
  1.1631 - * \sa SDL_HapticPause
  1.1632 + *  \brief Unpauses a haptic device.
  1.1633 + *  
  1.1634 + *  Call to unpause after SDL_HapticPause().
  1.1635 + *  
  1.1636 + *  \param haptic Haptic device to pause.
  1.1637 + *  \return 0 on success or -1 on error.
  1.1638 + *  
  1.1639 + *  \sa SDL_HapticPause
  1.1640   */
  1.1641  extern DECLSPEC int SDLCALL SDL_HapticUnpause(SDL_Haptic * haptic);
  1.1642  
  1.1643  /**
  1.1644 - * \fn extern DECSLPEC int SDLCALL SDL_HapticStopAll(SDL_Haptic * haptic)
  1.1645 - *
  1.1646 - * \brief Stops all the currently playing effects on a haptic device.
  1.1647 - *
  1.1648 - *    \param haptic Haptic device to stop.
  1.1649 - *    \return 0 on success or -1 on error.
  1.1650 + *  \brief Stops all the currently playing effects on a haptic device.
  1.1651 + *  
  1.1652 + *  \param haptic Haptic device to stop.
  1.1653 + *  \return 0 on success or -1 on error.
  1.1654   */
  1.1655  extern DECLSPEC int SDLCALL SDL_HapticStopAll(SDL_Haptic * haptic);
  1.1656