include/SDL_haptic.h
changeset 7191 75360622e65f
parent 7125 082c0c53ac16
child 7221 122c97a210bc
     1.1 --- a/include/SDL_haptic.h	Sat May 18 12:48:50 2013 -0700
     1.2 +++ b/include/SDL_haptic.h	Sat May 18 14:17:52 2013 -0700
     1.3 @@ -21,10 +21,10 @@
     1.4  
     1.5  /**
     1.6   *  \file SDL_haptic.h
     1.7 - *  
     1.8 + *
     1.9   *  \brief The SDL Haptic subsystem allows you to control haptic (force feedback)
    1.10   *         devices.
    1.11 - * 
    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 @@ -119,16 +119,14 @@
    1.17  #include "begin_code.h"
    1.18  /* Set up for C function definitions, even when using C++ */
    1.19  #ifdef __cplusplus
    1.20 -/* *INDENT-OFF* */
    1.21  extern "C" {
    1.22 -   /* *INDENT-ON* */                                                         
    1.23  #endif /* __cplusplus */
    1.24  
    1.25  /**
    1.26   *  \typedef SDL_Haptic
    1.27 - *  
    1.28 + *
    1.29   *  \brief The haptic structure used to identify an SDL haptic.
    1.30 - *  
    1.31 + *
    1.32   *  \sa SDL_HapticOpen
    1.33   *  \sa SDL_HapticOpenFromJoystick
    1.34   *  \sa SDL_HapticClose
    1.35 @@ -139,7 +137,7 @@
    1.36  
    1.37  /**
    1.38   *  \name Haptic features
    1.39 - *  
    1.40 + *
    1.41   *  Different haptic features a device can have.
    1.42   */
    1.43  /*@{*/
    1.44 @@ -153,68 +151,68 @@
    1.45   *  \brief Constant effect supported.
    1.46   *
    1.47   *  Constant haptic effect.
    1.48 - *  
    1.49 + *
    1.50   *  \sa SDL_HapticCondition
    1.51   */
    1.52  #define SDL_HAPTIC_CONSTANT   (1<<0)
    1.53  
    1.54  /**
    1.55   *  \brief Sine wave effect supported.
    1.56 - *  
    1.57 + *
    1.58   *  Periodic haptic effect that simulates sine waves.
    1.59 - *  
    1.60 + *
    1.61   *  \sa SDL_HapticPeriodic
    1.62   */
    1.63  #define SDL_HAPTIC_SINE       (1<<1)
    1.64  
    1.65  /**
    1.66   *  \brief Square wave effect supported.
    1.67 - *  
    1.68 + *
    1.69   *  Periodic haptic effect that simulates square waves.
    1.70 - * 
    1.71 + *
    1.72   *  \sa SDL_HapticPeriodic
    1.73   */
    1.74  #define SDL_HAPTIC_SQUARE     (1<<2)
    1.75  
    1.76  /**
    1.77   *  \brief Triangle wave effect supported.
    1.78 - *  
    1.79 + *
    1.80   *  Periodic haptic effect that simulates triangular waves.
    1.81 - *  
    1.82 + *
    1.83   *  \sa SDL_HapticPeriodic
    1.84   */
    1.85  #define SDL_HAPTIC_TRIANGLE   (1<<3)
    1.86  
    1.87  /**
    1.88   *  \brief Sawtoothup wave effect supported.
    1.89 - *  
    1.90 + *
    1.91   *  Periodic haptic effect that simulates saw tooth up waves.
    1.92 - *  
    1.93 + *
    1.94   *  \sa SDL_HapticPeriodic
    1.95   */
    1.96  #define SDL_HAPTIC_SAWTOOTHUP (1<<4)
    1.97  
    1.98  /**
    1.99   *  \brief Sawtoothdown wave effect supported.
   1.100 - *  
   1.101 + *
   1.102   *  Periodic haptic effect that simulates saw tooth down waves.
   1.103 - *  
   1.104 + *
   1.105   *  \sa SDL_HapticPeriodic
   1.106   */
   1.107  #define SDL_HAPTIC_SAWTOOTHDOWN (1<<5)
   1.108  
   1.109  /**
   1.110   *  \brief Ramp effect supported.
   1.111 - *  
   1.112 + *
   1.113   *  Ramp haptic effect.
   1.114 - *  
   1.115 + *
   1.116   *  \sa SDL_HapticRamp
   1.117   */
   1.118  #define SDL_HAPTIC_RAMP       (1<<6)
   1.119  
   1.120  /**
   1.121   *  \brief Spring effect supported - uses axes position.
   1.122 - *  
   1.123 + *
   1.124   *  Condition haptic effect that simulates a spring.  Effect is based on the
   1.125   *  axes position.
   1.126   *
   1.127 @@ -224,17 +222,17 @@
   1.128  
   1.129  /**
   1.130   *  \brief Damper effect supported - uses axes velocity.
   1.131 - *  
   1.132 + *
   1.133   *  Condition haptic effect that simulates dampening.  Effect is based on the
   1.134   *  axes velocity.
   1.135 - *  
   1.136 + *
   1.137   *  \sa SDL_HapticCondition
   1.138   */
   1.139  #define SDL_HAPTIC_DAMPER     (1<<8)
   1.140  
   1.141  /**
   1.142   *  \brief Inertia effect supported - uses axes acceleration.
   1.143 - *  
   1.144 + *
   1.145   *  Condition haptic effect that simulates inertia.  Effect is based on the axes
   1.146   *  acceleration.
   1.147   *
   1.148 @@ -244,17 +242,17 @@
   1.149  
   1.150  /**
   1.151   *  \brief Friction effect supported - uses axes movement.
   1.152 - *  
   1.153 - *  Condition haptic effect that simulates friction.  Effect is based on the 
   1.154 + *
   1.155 + *  Condition haptic effect that simulates friction.  Effect is based on the
   1.156   *  axes movement.
   1.157 - *  
   1.158 + *
   1.159   *  \sa SDL_HapticCondition
   1.160   */
   1.161  #define SDL_HAPTIC_FRICTION   (1<<10)
   1.162  
   1.163  /**
   1.164   *  \brief Custom effect is supported.
   1.165 - *  
   1.166 + *
   1.167   *  User defined custom haptic effect.
   1.168   */
   1.169  #define SDL_HAPTIC_CUSTOM     (1<<11)
   1.170 @@ -265,34 +263,34 @@
   1.171  
   1.172  /**
   1.173   *  \brief Device can set global gain.
   1.174 - *  
   1.175 + *
   1.176   *  Device supports setting the global gain.
   1.177 - *  
   1.178 + *
   1.179   *  \sa SDL_HapticSetGain
   1.180   */
   1.181  #define SDL_HAPTIC_GAIN       (1<<12)
   1.182  
   1.183  /**
   1.184   *  \brief Device can set autocenter.
   1.185 - *  
   1.186 + *
   1.187   *  Device supports setting autocenter.
   1.188 - *  
   1.189 + *
   1.190   *  \sa SDL_HapticSetAutocenter
   1.191   */
   1.192  #define SDL_HAPTIC_AUTOCENTER (1<<13)
   1.193  
   1.194  /**
   1.195   *  \brief Device can be queried for effect status.
   1.196 - *  
   1.197 + *
   1.198   *  Device can be queried for effect status.
   1.199 - *  
   1.200 + *
   1.201   *  \sa SDL_HapticGetEffectStatus
   1.202   */
   1.203  #define SDL_HAPTIC_STATUS     (1<<14)
   1.204  
   1.205  /**
   1.206   *  \brief Device can be paused.
   1.207 - *  
   1.208 + *
   1.209   *  \sa SDL_HapticPause
   1.210   *  \sa SDL_HapticUnpause
   1.211   */
   1.212 @@ -306,21 +304,21 @@
   1.213  
   1.214  /**
   1.215   *  \brief Uses polar coordinates for the direction.
   1.216 - *  
   1.217 + *
   1.218   *  \sa SDL_HapticDirection
   1.219   */
   1.220  #define SDL_HAPTIC_POLAR      0
   1.221  
   1.222  /**
   1.223   *  \brief Uses cartesian coordinates for the direction.
   1.224 - *  
   1.225 + *
   1.226   *  \sa SDL_HapticDirection
   1.227   */
   1.228  #define SDL_HAPTIC_CARTESIAN  1
   1.229  
   1.230  /**
   1.231   *  \brief Uses spherical coordinates for the direction.
   1.232 - *  
   1.233 + *
   1.234   *  \sa SDL_HapticDirection
   1.235   */
   1.236  #define SDL_HAPTIC_SPHERICAL  2
   1.237 @@ -343,7 +341,7 @@
   1.238  
   1.239  /**
   1.240   *  \brief Structure that represents a haptic direction.
   1.241 - *  
   1.242 + *
   1.243   *  Directions can be specified by:
   1.244   *   - ::SDL_HAPTIC_POLAR : Specified by polar coordinates.
   1.245   *   - ::SDL_HAPTIC_CARTESIAN : Specified by cartesian coordinates.
   1.246 @@ -361,8 +359,8 @@
   1.247                   |  | |'-----'|
   1.248                   |__|~')_____('
   1.249                     [ COMPUTER ]
   1.250 -    
   1.251 -    
   1.252 +
   1.253 +
   1.254                       North (0,-1)
   1.255                           ^
   1.256                           |
   1.257 @@ -372,22 +370,22 @@
   1.258                           |
   1.259                           v
   1.260                        South (0,1)
   1.261 -    
   1.262 -    
   1.263 +
   1.264 +
   1.265                        [ USER ]
   1.266                          \|||/
   1.267                          (o o)
   1.268                    ---ooO-(_)-Ooo---
   1.269      \endverbatim
   1.270 - *  
   1.271 - *  If type is ::SDL_HAPTIC_POLAR, direction is encoded by hundredths of a 
   1.272 + *
   1.273 + *  If type is ::SDL_HAPTIC_POLAR, direction is encoded by hundredths of a
   1.274   *  degree starting north and turning clockwise.  ::SDL_HAPTIC_POLAR only uses
   1.275   *  the first \c dir parameter.  The cardinal directions would be:
   1.276   *   - North: 0 (0 degrees)
   1.277   *   - East: 9000 (90 degrees)
   1.278   *   - South: 18000 (180 degrees)
   1.279   *   - West: 27000 (270 degrees)
   1.280 - *  
   1.281 + *
   1.282   *  If type is ::SDL_HAPTIC_CARTESIAN, direction is encoded by three positions
   1.283   *  (X axis, Y axis and Z axis (with 3 axes)).  ::SDL_HAPTIC_CARTESIAN uses
   1.284   *  the first three \c dir parameters.  The cardinal directions would be:
   1.285 @@ -395,13 +393,13 @@
   1.286   *   - East:  -1, 0, 0
   1.287   *   - South:  0, 1, 0
   1.288   *   - West:   1, 0, 0
   1.289 - *  
   1.290 + *
   1.291   *  The Z axis represents the height of the effect if supported, otherwise
   1.292   *  it's unused.  In cartesian encoding (1, 2) would be the same as (2, 4), you
   1.293   *  can use any multiple you want, only the direction matters.
   1.294 - *  
   1.295 + *
   1.296   *  If type is ::SDL_HAPTIC_SPHERICAL, direction is encoded by two rotations.
   1.297 - *  The first two \c dir parameters are used.  The \c dir parameters are as 
   1.298 + *  The first two \c dir parameters are used.  The \c dir parameters are as
   1.299   *  follows (all values are in hundredths of degrees):
   1.300   *   - Degrees from (1, 0) rotated towards (0, 1).
   1.301   *   - Degrees towards (0, 0, 1) (device needs at least 3 axes).
   1.302 @@ -411,17 +409,17 @@
   1.303   *  from the south means the user will have to pull the stick to counteract):
   1.304   *  \code
   1.305   *  SDL_HapticDirection direction;
   1.306 - *  
   1.307 + *
   1.308   *  // Cartesian directions
   1.309   *  direction.type = SDL_HAPTIC_CARTESIAN; // Using cartesian direction encoding.
   1.310   *  direction.dir[0] = 0; // X position
   1.311   *  direction.dir[1] = 1; // Y position
   1.312   *  // Assuming the device has 2 axes, we don't need to specify third parameter.
   1.313 - *  
   1.314 + *
   1.315   *  // Polar directions
   1.316   *  direction.type = SDL_HAPTIC_POLAR; // We'll be using polar direction encoding.
   1.317   *  direction.dir[0] = 18000; // Polar only uses first parameter
   1.318 - *  
   1.319 + *
   1.320   *  // Spherical coordinates
   1.321   *  direction.type = SDL_HAPTIC_SPHERICAL; // Spherical encoding
   1.322   *  direction.dir[0] = 9000; // Since we only have two axes we don't need more parameters.
   1.323 @@ -442,12 +440,12 @@
   1.324  
   1.325  /**
   1.326   *  \brief A structure containing a template for a Constant effect.
   1.327 - *  
   1.328 + *
   1.329   *  The struct is exclusive to the ::SDL_HAPTIC_CONSTANT effect.
   1.330 - *  
   1.331 + *
   1.332   *  A constant effect applies a constant force in the specified direction
   1.333   *  to the joystick.
   1.334 - *  
   1.335 + *
   1.336   *  \sa SDL_HAPTIC_CONSTANT
   1.337   *  \sa SDL_HapticEffect
   1.338   */
   1.339 @@ -477,18 +475,18 @@
   1.340  
   1.341  /**
   1.342   *  \brief A structure containing a template for a Periodic effect.
   1.343 - *  
   1.344 + *
   1.345   *  The struct handles the following effects:
   1.346   *   - ::SDL_HAPTIC_SINE
   1.347   *   - ::SDL_HAPTIC_SQUARE
   1.348   *   - ::SDL_HAPTIC_TRIANGLE
   1.349   *   - ::SDL_HAPTIC_SAWTOOTHUP
   1.350   *   - ::SDL_HAPTIC_SAWTOOTHDOWN
   1.351 - *  
   1.352 + *
   1.353   *  A periodic effect consists in a wave-shaped effect that repeats itself
   1.354   *  over time.  The type determines the shape of the wave and the parameters
   1.355   *  determine the dimensions of the wave.
   1.356 - *  
   1.357 + *
   1.358   *  Phase is given by hundredth of a cycle meaning that giving the phase a value
   1.359   *  of 9000 will displace it 25% of its period.  Here are sample values:
   1.360   *   -     0: No phase displacement.
   1.361 @@ -503,28 +501,28 @@
   1.362        __      __      __      __
   1.363       /  \    /  \    /  \    /
   1.364      /    \__/    \__/    \__/
   1.365 -    
   1.366 +
   1.367      SDL_HAPTIC_SQUARE
   1.368       __    __    __    __    __
   1.369      |  |  |  |  |  |  |  |  |  |
   1.370      |  |__|  |__|  |__|  |__|  |
   1.371 -    
   1.372 +
   1.373      SDL_HAPTIC_TRIANGLE
   1.374        /\    /\    /\    /\    /\
   1.375       /  \  /  \  /  \  /  \  /
   1.376      /    \/    \/    \/    \/
   1.377 -    
   1.378 +
   1.379      SDL_HAPTIC_SAWTOOTHUP
   1.380        /|  /|  /|  /|  /|  /|  /|
   1.381       / | / | / | / | / | / | / |
   1.382      /  |/  |/  |/  |/  |/  |/  |
   1.383 -    
   1.384 +
   1.385      SDL_HAPTIC_SAWTOOTHDOWN
   1.386      \  |\  |\  |\  |\  |\  |\  |
   1.387       \ | \ | \ | \ | \ | \ | \ |
   1.388        \|  \|  \|  \|  \|  \|  \|
   1.389      \endverbatim
   1.390 - *  
   1.391 + *
   1.392   *  \sa SDL_HAPTIC_SINE
   1.393   *  \sa SDL_HAPTIC_SQUARE
   1.394   *  \sa SDL_HAPTIC_TRIANGLE
   1.395 @@ -563,21 +561,21 @@
   1.396  
   1.397  /**
   1.398   *  \brief A structure containing a template for a Condition effect.
   1.399 - *  
   1.400 + *
   1.401   *  The struct handles the following effects:
   1.402   *   - ::SDL_HAPTIC_SPRING: Effect based on axes position.
   1.403   *   - ::SDL_HAPTIC_DAMPER: Effect based on axes velocity.
   1.404   *   - ::SDL_HAPTIC_INERTIA: Effect based on axes acceleration.
   1.405   *   - ::SDL_HAPTIC_FRICTION: Effect based on axes movement.
   1.406 - *  
   1.407 + *
   1.408   *  Direction is handled by condition internals instead of a direction member.
   1.409   *  The condition effect specific members have three parameters.  The first
   1.410   *  refers to the X axis, the second refers to the Y axis and the third
   1.411   *  refers to the Z axis.  The right terms refer to the positive side of the
   1.412 - *  axis and the left terms refer to the negative side of the axis.  Please 
   1.413 + *  axis and the left terms refer to the negative side of the axis.  Please
   1.414   *  refer to the ::SDL_HapticDirection diagram for which side is positive and
   1.415   *  which is negative.
   1.416 - *  
   1.417 + *
   1.418   *  \sa SDL_HapticDirection
   1.419   *  \sa SDL_HAPTIC_SPRING
   1.420   *  \sa SDL_HAPTIC_DAMPER
   1.421 @@ -611,14 +609,14 @@
   1.422  
   1.423  /**
   1.424   *  \brief A structure containing a template for a Ramp effect.
   1.425 - *  
   1.426 + *
   1.427   *  This struct is exclusively for the ::SDL_HAPTIC_RAMP effect.
   1.428 - *  
   1.429 + *
   1.430   *  The ramp effect starts at start strength and ends at end strength.
   1.431   *  It augments in linear fashion.  If you use attack and fade with a ramp
   1.432   *  they effects get added to the ramp effect making the effect become
   1.433   *  quadratic instead of linear.
   1.434 - *  
   1.435 + *
   1.436   *  \sa SDL_HAPTIC_RAMP
   1.437   *  \sa SDL_HapticEffect
   1.438   */
   1.439 @@ -649,14 +647,14 @@
   1.440  
   1.441  /**
   1.442   *  \brief A structure containing a template for the ::SDL_HAPTIC_CUSTOM effect.
   1.443 - *  
   1.444 + *
   1.445   *  A custom force feedback effect is much like a periodic effect, where the
   1.446   *  application can define its exact shape.  You will have to allocate the
   1.447   *  data yourself.  Data should consist of channels * samples Uint16 samples.
   1.448 - *  
   1.449 + *
   1.450   *  If channels is one, the effect is rotated using the defined direction.
   1.451   *  Otherwise it uses the samples in data for the different axes.
   1.452 - *  
   1.453 + *
   1.454   *  \sa SDL_HAPTIC_CUSTOM
   1.455   *  \sa SDL_HapticEffect
   1.456   */
   1.457 @@ -689,34 +687,34 @@
   1.458  
   1.459  /**
   1.460   *  \brief The generic template for any haptic effect.
   1.461 - *  
   1.462 + *
   1.463   *  All values max at 32767 (0x7FFF).  Signed values also can be negative.
   1.464   *  Time values unless specified otherwise are in milliseconds.
   1.465 - *  
   1.466 - *  You can also pass ::SDL_HAPTIC_INFINITY to length instead of a 0-32767 
   1.467 - *  value.  Neither delay, interval, attack_length nor fade_length support 
   1.468 + *
   1.469 + *  You can also pass ::SDL_HAPTIC_INFINITY to length instead of a 0-32767
   1.470 + *  value.  Neither delay, interval, attack_length nor fade_length support
   1.471   *  ::SDL_HAPTIC_INFINITY.  Fade will also not be used since effect never ends.
   1.472 - *  
   1.473 + *
   1.474   *  Additionally, the ::SDL_HAPTIC_RAMP effect does not support a duration of
   1.475   *  ::SDL_HAPTIC_INFINITY.
   1.476 - *  
   1.477 + *
   1.478   *  Button triggers may not be supported on all devices, it is advised to not
   1.479   *  use them if possible.  Buttons start at index 1 instead of index 0 like
   1.480   *  they joystick.
   1.481 - *  
   1.482 + *
   1.483   *  If both attack_length and fade_level are 0, the envelope is not used,
   1.484   *  otherwise both values are used.
   1.485 - *  
   1.486 + *
   1.487   *  Common parts:
   1.488   *  \code
   1.489   *  // Replay - All effects have this
   1.490   *  Uint32 length;        // Duration of effect (ms).
   1.491   *  Uint16 delay;         // Delay before starting effect.
   1.492 - *  
   1.493 + *
   1.494   *  // Trigger - All effects have this
   1.495   *  Uint16 button;        // Button that triggers effect.
   1.496   *  Uint16 interval;      // How soon before effect can be triggered again.
   1.497 - *  
   1.498 + *
   1.499   *  // Envelope - All effects except condition effects have this
   1.500   *  Uint16 attack_length; // Duration of the attack (ms).
   1.501   *  Uint16 attack_level;  // Level at the start of the attack.
   1.502 @@ -734,18 +732,18 @@
   1.503      |                     /                 \
   1.504      |                    /                   \
   1.505      |                   /                     \
   1.506 -    |                  /                       \ 
   1.507 +    |                  /                       \
   1.508      | attack_level --> |                        \
   1.509      |                  |                        |  <---  fade_level
   1.510      |
   1.511      +--------------------------------------------------> Time
   1.512                         [--]                 [---]
   1.513                         attack_length        fade_length
   1.514 -    
   1.515 +
   1.516      [------------------][-----------------------]
   1.517      delay               length
   1.518      \endverbatim
   1.519 - *  
   1.520 + *
   1.521   *  Note either the attack_level or the fade_level may be above the actual
   1.522   *  effect level.
   1.523   *
   1.524 @@ -770,17 +768,17 @@
   1.525  /* Function prototypes */
   1.526  /**
   1.527   *  \brief Count the number of joysticks attached to the system.
   1.528 - *  
   1.529 + *
   1.530   *  \return Number of haptic devices detected on the system.
   1.531   */
   1.532  extern DECLSPEC int SDLCALL SDL_NumHaptics(void);
   1.533  
   1.534  /**
   1.535   *  \brief Get the implementation dependent name of a Haptic device.
   1.536 - *  
   1.537 + *
   1.538   *  This can be called before any joysticks are opened.
   1.539   *  If no name can be found, this function returns NULL.
   1.540 - *  
   1.541 + *
   1.542   *  \param device_index Index of the device to get its name.
   1.543   *  \return Name of the device or NULL on error.
   1.544   *
   1.545 @@ -790,8 +788,8 @@
   1.546  
   1.547  /**
   1.548   *  \brief Opens a Haptic device for usage.
   1.549 - *  
   1.550 - *  The index passed as an argument refers to the N'th Haptic device on this 
   1.551 + *
   1.552 + *  The index passed as an argument refers to the N'th Haptic device on this
   1.553   *  system.
   1.554   *
   1.555   *  When opening a haptic device, its gain will be set to maximum and
   1.556 @@ -814,10 +812,10 @@
   1.557  
   1.558  /**
   1.559   *  \brief Checks if the haptic device at index has been opened.
   1.560 - *  
   1.561 + *
   1.562   *  \param device_index Index to check to see if it has been opened.
   1.563   *  \return 1 if it has been opened or 0 if it hasn't.
   1.564 - *  
   1.565 + *
   1.566   *  \sa SDL_HapticOpen
   1.567   *  \sa SDL_HapticIndex
   1.568   */
   1.569 @@ -825,10 +823,10 @@
   1.570  
   1.571  /**
   1.572   *  \brief Gets the index of a haptic device.
   1.573 - *  
   1.574 + *
   1.575   *  \param haptic Haptic device to get the index of.
   1.576   *  \return The index of the haptic device or -1 on error.
   1.577 - *  
   1.578 + *
   1.579   *  \sa SDL_HapticOpen
   1.580   *  \sa SDL_HapticOpened
   1.581   */
   1.582 @@ -836,18 +834,18 @@
   1.583  
   1.584  /**
   1.585   *  \brief Gets whether or not the current mouse has haptic capabilities.
   1.586 - *  
   1.587 + *
   1.588   *  \return SDL_TRUE if the mouse is haptic, SDL_FALSE if it isn't.
   1.589 - *  
   1.590 + *
   1.591   *  \sa SDL_HapticOpenFromMouse
   1.592   */
   1.593  extern DECLSPEC int SDLCALL SDL_MouseIsHaptic(void);
   1.594  
   1.595  /**
   1.596   *  \brief Tries to open a haptic device from the current mouse.
   1.597 - *  
   1.598 + *
   1.599   *  \return The haptic device identifier or NULL on error.
   1.600 - *  
   1.601 + *
   1.602   *  \sa SDL_MouseIsHaptic
   1.603   *  \sa SDL_HapticOpen
   1.604   */
   1.605 @@ -855,29 +853,29 @@
   1.606  
   1.607  /**
   1.608   *  \brief Checks to see if a joystick has haptic features.
   1.609 - *  
   1.610 + *
   1.611   *  \param joystick Joystick to test for haptic capabilities.
   1.612   *  \return 1 if the joystick is haptic, 0 if it isn't
   1.613   *          or -1 if an error ocurred.
   1.614 - *  
   1.615 + *
   1.616   *  \sa SDL_HapticOpenFromJoystick
   1.617   */
   1.618  extern DECLSPEC int SDLCALL SDL_JoystickIsHaptic(SDL_Joystick * joystick);
   1.619  
   1.620  /**
   1.621   *  \brief Opens a Haptic device for usage from a Joystick device.
   1.622 - *  
   1.623 - *  You must still close the haptic device seperately.  It will not be closed 
   1.624 + *
   1.625 + *  You must still close the haptic device seperately.  It will not be closed
   1.626   *  with the joystick.
   1.627 - *  
   1.628 + *
   1.629   *  When opening from a joystick you should first close the haptic device before
   1.630   *  closing the joystick device.  If not, on some implementations the haptic
   1.631   *  device will also get unallocated and you'll be unable to use force feedback
   1.632   *  on that device.
   1.633 - *  
   1.634 + *
   1.635   *  \param joystick Joystick to create a haptic device from.
   1.636   *  \return A valid haptic device identifier on success or NULL on error.
   1.637 - *  
   1.638 + *
   1.639   *  \sa SDL_HapticOpen
   1.640   *  \sa SDL_HapticClose
   1.641   */
   1.642 @@ -886,34 +884,34 @@
   1.643  
   1.644  /**
   1.645   *  \brief Closes a Haptic device previously opened with SDL_HapticOpen().
   1.646 - *  
   1.647 + *
   1.648   *  \param haptic Haptic device to close.
   1.649   */
   1.650  extern DECLSPEC void SDLCALL SDL_HapticClose(SDL_Haptic * haptic);
   1.651  
   1.652  /**
   1.653   *  \brief Returns the number of effects a haptic device can store.
   1.654 - *  
   1.655 + *
   1.656   *  On some platforms this isn't fully supported, and therefore is an
   1.657   *  approximation.  Always check to see if your created effect was actually
   1.658   *  created and do not rely solely on SDL_HapticNumEffects().
   1.659 - *  
   1.660 + *
   1.661   *  \param haptic The haptic device to query effect max.
   1.662   *  \return The number of effects the haptic device can store or
   1.663   *          -1 on error.
   1.664 - *  
   1.665 + *
   1.666   *  \sa SDL_HapticNumEffectsPlaying
   1.667   *  \sa SDL_HapticQuery
   1.668   */
   1.669  extern DECLSPEC int SDLCALL SDL_HapticNumEffects(SDL_Haptic * haptic);
   1.670  
   1.671  /**
   1.672 - *  \brief Returns the number of effects a haptic device can play at the same 
   1.673 + *  \brief Returns the number of effects a haptic device can play at the same
   1.674   *         time.
   1.675 - *  
   1.676 - *  This is not supported on all platforms, but will always return a value.  
   1.677 + *
   1.678 + *  This is not supported on all platforms, but will always return a value.
   1.679   *  Added here for the sake of completeness.
   1.680 - *  
   1.681 + *
   1.682   *  \param haptic The haptic device to query maximum playing effects.
   1.683   *  \return The number of effects the haptic device can play at the same time
   1.684   *          or -1 on error.
   1.685 @@ -925,17 +923,17 @@
   1.686  
   1.687  /**
   1.688   *  \brief Gets the haptic devices supported features in bitwise matter.
   1.689 - *  
   1.690 - *  Example: 
   1.691 + *
   1.692 + *  Example:
   1.693   *  \code
   1.694   *  if (SDL_HapticQueryEffects(haptic) & SDL_HAPTIC_CONSTANT) {
   1.695   *      printf("We have constant haptic effect!");
   1.696   *  }
   1.697   *  \endcode
   1.698 - *  
   1.699 + *
   1.700   *  \param haptic The haptic device to query.
   1.701   *  \return Haptic features in bitwise manner (OR'd).
   1.702 - *  
   1.703 + *
   1.704   *  \sa SDL_HapticNumEffects
   1.705   *  \sa SDL_HapticEffectSupported
   1.706   */
   1.707 @@ -944,18 +942,18 @@
   1.708  
   1.709  /**
   1.710   *  \brief Gets the number of haptic axes the device has.
   1.711 - *  
   1.712 + *
   1.713   *  \sa SDL_HapticDirection
   1.714   */
   1.715  extern DECLSPEC int SDLCALL SDL_HapticNumAxes(SDL_Haptic * haptic);
   1.716  
   1.717  /**
   1.718   *  \brief Checks to see if effect is supported by haptic.
   1.719 - *  
   1.720 + *
   1.721   *  \param haptic Haptic device to check on.
   1.722   *  \param effect Effect to check to see if it is supported.
   1.723   *  \return SDL_TRUE if effect is supported, SDL_FALSE if it isn't or -1 on error.
   1.724 - *  
   1.725 + *
   1.726   *  \sa SDL_HapticQuery
   1.727   *  \sa SDL_HapticNewEffect
   1.728   */
   1.729 @@ -965,11 +963,11 @@
   1.730  
   1.731  /**
   1.732   *  \brief Creates a new haptic effect on the device.
   1.733 - *  
   1.734 + *
   1.735   *  \param haptic Haptic device to create the effect on.
   1.736   *  \param effect Properties of the effect to create.
   1.737   *  \return The id of the effect on success or -1 on error.
   1.738 - *  
   1.739 + *
   1.740   *  \sa SDL_HapticUpdateEffect
   1.741   *  \sa SDL_HapticRunEffect
   1.742   *  \sa SDL_HapticDestroyEffect
   1.743 @@ -979,17 +977,17 @@
   1.744  
   1.745  /**
   1.746   *  \brief Updates the properties of an effect.
   1.747 - *  
   1.748 + *
   1.749   *  Can be used dynamically, although behaviour when dynamically changing
   1.750   *  direction may be strange.  Specifically the effect may reupload itself
   1.751   *  and start playing from the start.  You cannot change the type either when
   1.752   *  running SDL_HapticUpdateEffect().
   1.753 - *  
   1.754 + *
   1.755   *  \param haptic Haptic device that has the effect.
   1.756   *  \param effect Effect to update.
   1.757   *  \param data New effect properties to use.
   1.758   *  \return The id of the effect on success or -1 on error.
   1.759 - *  
   1.760 + *
   1.761   *  \sa SDL_HapticNewEffect
   1.762   *  \sa SDL_HapticRunEffect
   1.763   *  \sa SDL_HapticDestroyEffect
   1.764 @@ -1000,18 +998,18 @@
   1.765  
   1.766  /**
   1.767   *  \brief Runs the haptic effect on its associated haptic device.
   1.768 - *  
   1.769 + *
   1.770   *  If iterations are ::SDL_HAPTIC_INFINITY, it'll run the effect over and over
   1.771   *  repeating the envelope (attack and fade) every time.  If you only want the
   1.772   *  effect to last forever, set ::SDL_HAPTIC_INFINITY in the effect's length
   1.773   *  parameter.
   1.774 - *  
   1.775 + *
   1.776   *  \param haptic Haptic device to run the effect on.
   1.777   *  \param effect Identifier of the haptic effect to run.
   1.778   *  \param iterations Number of iterations to run the effect. Use
   1.779   *         ::SDL_HAPTIC_INFINITY for infinity.
   1.780   *  \return 0 on success or -1 on error.
   1.781 - *  
   1.782 + *
   1.783   *  \sa SDL_HapticStopEffect
   1.784   *  \sa SDL_HapticDestroyEffect
   1.785   *  \sa SDL_HapticGetEffectStatus
   1.786 @@ -1022,11 +1020,11 @@
   1.787  
   1.788  /**
   1.789   *  \brief Stops the haptic effect on its associated haptic device.
   1.790 - *  
   1.791 + *
   1.792   *  \param haptic Haptic device to stop the effect on.
   1.793   *  \param effect Identifier of the effect to stop.
   1.794   *  \return 0 on success or -1 on error.
   1.795 - *  
   1.796 + *
   1.797   *  \sa SDL_HapticRunEffect
   1.798   *  \sa SDL_HapticDestroyEffect
   1.799   */
   1.800 @@ -1035,13 +1033,13 @@
   1.801  
   1.802  /**
   1.803   *  \brief Destroys a haptic effect on the device.
   1.804 - *  
   1.805 - *  This will stop the effect if it's running.  Effects are automatically 
   1.806 + *
   1.807 + *  This will stop the effect if it's running.  Effects are automatically
   1.808   *  destroyed when the device is closed.
   1.809 - *  
   1.810 + *
   1.811   *  \param haptic Device to destroy the effect on.
   1.812   *  \param effect Identifier of the effect to destroy.
   1.813 - *  
   1.814 + *
   1.815   *  \sa SDL_HapticNewEffect
   1.816   */
   1.817  extern DECLSPEC void SDLCALL SDL_HapticDestroyEffect(SDL_Haptic * haptic,
   1.818 @@ -1049,14 +1047,14 @@
   1.819  
   1.820  /**
   1.821   *  \brief Gets the status of the current effect on the haptic device.
   1.822 - *  
   1.823 + *
   1.824   *  Device must support the ::SDL_HAPTIC_STATUS feature.
   1.825 - *  
   1.826 + *
   1.827   *  \param haptic Haptic device to query the effect status on.
   1.828   *  \param effect Identifier of the effect to query its status.
   1.829   *  \return 0 if it isn't playing, ::SDL_HAPTIC_PLAYING if it is playing
   1.830   *          or -1 on error.
   1.831 - *  
   1.832 + *
   1.833   *  \sa SDL_HapticRunEffect
   1.834   *  \sa SDL_HapticStopEffect
   1.835   */
   1.836 @@ -1065,26 +1063,26 @@
   1.837  
   1.838  /**
   1.839   *  \brief Sets the global gain of the device.
   1.840 - *  
   1.841 + *
   1.842   *  Device must support the ::SDL_HAPTIC_GAIN feature.
   1.843 - *  
   1.844 + *
   1.845   *  The user may specify the maximum gain by setting the environment variable
   1.846   *  ::SDL_HAPTIC_GAIN_MAX which should be between 0 and 100.  All calls to
   1.847   *  SDL_HapticSetGain() will scale linearly using ::SDL_HAPTIC_GAIN_MAX as the
   1.848   *  maximum.
   1.849 - *  
   1.850 + *
   1.851   *  \param haptic Haptic device to set the gain on.
   1.852   *  \param gain Value to set the gain to, should be between 0 and 100.
   1.853   *  \return 0 on success or -1 on error.
   1.854 - *  
   1.855 + *
   1.856   *  \sa SDL_HapticQuery
   1.857   */
   1.858  extern DECLSPEC int SDLCALL SDL_HapticSetGain(SDL_Haptic * haptic, int gain);
   1.859  
   1.860  /**
   1.861   *  \brief Sets the global autocenter of the device.
   1.862 - *  
   1.863 - *  Autocenter should be between 0 and 100.  Setting it to 0 will disable 
   1.864 + *
   1.865 + *  Autocenter should be between 0 and 100.  Setting it to 0 will disable
   1.866   *  autocentering.
   1.867   *
   1.868   *  Device must support the ::SDL_HAPTIC_AUTOCENTER feature.
   1.869 @@ -1092,7 +1090,7 @@
   1.870   *  \param haptic Haptic device to set autocentering on.
   1.871   *  \param autocenter Value to set autocenter to, 0 disables autocentering.
   1.872   *  \return 0 on success or -1 on error.
   1.873 - *  
   1.874 + *
   1.875   *  \sa SDL_HapticQuery
   1.876   */
   1.877  extern DECLSPEC int SDLCALL SDL_HapticSetAutocenter(SDL_Haptic * haptic,
   1.878 @@ -1100,35 +1098,35 @@
   1.879  
   1.880  /**
   1.881   *  \brief Pauses a haptic device.
   1.882 - *  
   1.883 - *  Device must support the ::SDL_HAPTIC_PAUSE feature.  Call 
   1.884 + *
   1.885 + *  Device must support the ::SDL_HAPTIC_PAUSE feature.  Call
   1.886   *  SDL_HapticUnpause() to resume playback.
   1.887 - *  
   1.888 + *
   1.889   *  Do not modify the effects nor add new ones while the device is paused.
   1.890   *  That can cause all sorts of weird errors.
   1.891 - *  
   1.892 + *
   1.893   *  \param haptic Haptic device to pause.
   1.894   *  \return 0 on success or -1 on error.
   1.895 - *  
   1.896 + *
   1.897   *  \sa SDL_HapticUnpause
   1.898   */
   1.899  extern DECLSPEC int SDLCALL SDL_HapticPause(SDL_Haptic * haptic);
   1.900  
   1.901  /**
   1.902   *  \brief Unpauses a haptic device.
   1.903 - *  
   1.904 + *
   1.905   *  Call to unpause after SDL_HapticPause().
   1.906 - *  
   1.907 + *
   1.908   *  \param haptic Haptic device to pause.
   1.909   *  \return 0 on success or -1 on error.
   1.910 - *  
   1.911 + *
   1.912   *  \sa SDL_HapticPause
   1.913   */
   1.914  extern DECLSPEC int SDLCALL SDL_HapticUnpause(SDL_Haptic * haptic);
   1.915  
   1.916  /**
   1.917   *  \brief Stops all the currently playing effects on a haptic device.
   1.918 - *  
   1.919 + *
   1.920   *  \param haptic Haptic device to stop.
   1.921   *  \return 0 on success or -1 on error.
   1.922   */
   1.923 @@ -1189,9 +1187,7 @@
   1.924  
   1.925  /* Ends C function definitions when using C++ */
   1.926  #ifdef __cplusplus
   1.927 -/* *INDENT-OFF* */
   1.928  }
   1.929 -/* *INDENT-ON* */
   1.930  #endif
   1.931  #include "close_code.h"
   1.932