Renamed SDL_HapticQueryEffects to SDL_HapticQuery. gsoc2008_force_feedback
authorEdgar Simo <bobbens@gmail.com>
Sun, 06 Jul 2008 16:53:32 +0000
branchgsoc2008_force_feedback
changeset 24970893fbf73b3d
parent 2496 8f840a6cdf01
child 2498 ab567bd667bf
Renamed SDL_HapticQueryEffects to SDL_HapticQuery.
Added doxygen to SDL_Haptic.h.
include/SDL_haptic.h
src/haptic/SDL_haptic.c
     1.1 --- a/include/SDL_haptic.h	Thu Jul 03 21:03:25 2008 +0000
     1.2 +++ b/include/SDL_haptic.h	Sun Jul 06 16:53:32 2008 +0000
     1.3 @@ -20,10 +20,70 @@
     1.4      slouken@libsdl.org
     1.5  */
     1.6  
     1.7 +/** \file SDL_haptic.h */
     1.8  /**
     1.9 - * \file SDL_haptic.h
    1.10 + * \mainpage SDL_haptic
    1.11   *
    1.12 - * Include file for SDL haptic subsystem
    1.13 + * The SDL Haptic subsystem allows you to control haptic (force feedback)
    1.14 + *  devices.
    1.15 + *
    1.16 + * The basic usage is as follows:
    1.17 + *   - Initialize the Subsystem (SDL_INIT_HAPTIC).
    1.18 + *   - Open a Haptic Device.
    1.19 + *     - SDL_HapticOpen(...) to open from index.
    1.20 + *     - SDL_HapticOpenFromJoystick(...) to open from an existing joystick.
    1.21 + *   - Create an effect (SDL_HapticEffect).
    1.22 + *   - Upload the effect with SDL_HapticNewEffect(...).
    1.23 + *   - Run the effect with SDL_HapticRunEffect(...).
    1.24 + *   - (optional) Free the effect with SDL_HapticDestroyEffect(...).
    1.25 + *   - Close the haptic device with SDL_HapticClose(...).
    1.26 + *
    1.27 + *
    1.28 + * Example:
    1.29 + *
    1.30 + * \code
    1.31 + * int test_haptic( SDL_Joystick * joystick ) {
    1.32 + *    SDL_Haptic *haptic;
    1.33 + *    SDL_HapticEffect effect;
    1.34 + *    int effect_id;
    1.35 + *
    1.36 + *    // Open the device
    1.37 + *    haptic = SDL_HapticOpenFromJoystick( joystick );
    1.38 + *    if (haptic == NULL) return -1; // Most likely joystick isn't haptic
    1.39 + *
    1.40 + *    // See if it can do sine waves
    1.41 + *    if ((SDL_HapticQueryEffects(haptic) & SDL_HAPTIC_SINE)==0) {
    1.42 + *       SDL_HapticClose(haptic); // No sine effect
    1.43 + *       return -1;
    1.44 + *    }
    1.45 + *
    1.46 + *    // Create the effect
    1.47 + *    memset( &effect, 0, sizeof(SDL_HapticEffect) ); // 0 is safe default
    1.48 + *    effect.type = SDL_HAPTIC_SINE;
    1.49 + *    effect.periodic.period = 1000; // 1000 ms
    1.50 + *    effect.periodic.magnitude = 20000; // 20000/32767 strength
    1.51 + *    effect.periodic.length = 5000; // 5 seconds long
    1.52 + *    effect.periodic.attack_length = 1000; // Takes 1 second to get max strength
    1.53 + *    effect.periodic.fade_length = 1000; // Takes 1 second to fade away
    1.54 + *
    1.55 + *    // Upload the effect
    1.56 + *    effect_id = SDL_HapticNewEffect( haptic, &effect );
    1.57 + *
    1.58 + *    // Test the effect
    1.59 + *    SDL_HapticRunEffect( haptic, effect_id );
    1.60 + *    SDL_Delay( 5000); // Wait for the effect to finish
    1.61 + *
    1.62 + *    // We destroy the effect, although closing the device also does this
    1.63 + *    SDL_HapticDestroyEffect( haptic, effect_id );
    1.64 + *
    1.65 + *    // Close the device
    1.66 + *    SDL_HapticClose(haptic);
    1.67 + *
    1.68 + *    return 0; // Success
    1.69 + * }
    1.70 + * \endcode
    1.71 + *
    1.72 + * \author Edgar Simo Serra
    1.73   */
    1.74  
    1.75  #ifndef _SDL_haptic_h
    1.76 @@ -39,9 +99,17 @@
    1.77  /* *INDENT-OFF* */
    1.78  extern "C" {
    1.79     /* *INDENT-ON* */                                                         
    1.80 -#endif
    1.81 +#endif /* __cpluspuls */
    1.82  
    1.83 -/* The haptic structure used to identify an SDL haptic */
    1.84 +/**
    1.85 + * \struct SDL_Haptic
    1.86 + *
    1.87 + * \brief The haptic structure used to identify an SDL haptic.
    1.88 + *
    1.89 + * \sa SDL_HapticOpen
    1.90 + * \sa SDL_HapticOpenFromJoystick
    1.91 + * \sa SDL_HapticClose
    1.92 + */
    1.93  struct _SDL_Haptic;                                                     
    1.94  typedef struct _SDL_Haptic SDL_Haptic;
    1.95  
    1.96 @@ -49,25 +117,283 @@
    1.97  /*
    1.98   * Different haptic features a device can have.
    1.99   */
   1.100 +/**
   1.101 + * \def SDL_HAPTIC_CONSTANT
   1.102 + *
   1.103 + * \brief Constant haptic effect.
   1.104 + *
   1.105 + * \sa SDL_HapticCondition
   1.106 + */
   1.107  #define SDL_HAPTIC_CONSTANT   (1<<0) /* Constant effect supported */
   1.108 +/**
   1.109 + * \def SDL_HAPTIC_SINE
   1.110 + *
   1.111 + * \brief Periodic haptic effect that simulates sine waves.
   1.112 + *
   1.113 + * \sa SDL_HapticPeriodic
   1.114 + */
   1.115  #define SDL_HAPTIC_SINE       (1<<1) /* Sine wave effect supported */
   1.116 +/**
   1.117 + * \def SDL_HAPTIC_SQUARE
   1.118 + *
   1.119 + * \brief Periodic haptic effect that simulates square waves.
   1.120 + *
   1.121 + * \sa SDL_HapticPeriodic
   1.122 + */
   1.123  #define SDL_HAPTIC_SQUARE     (1<<2) /* Square wave effect supported */
   1.124 +/**
   1.125 + * \def SDL_HAPTIC_TRIANGLE
   1.126 + *
   1.127 + * \brief Periodic haptic effect that simulates triangular waves.
   1.128 + *
   1.129 + * \sa SDL_HapticPeriodic
   1.130 + */
   1.131  #define SDL_HAPTIC_TRIANGLE   (1<<3) /* Triangle wave effect supported */
   1.132 +/**
   1.133 + * \def SDL_HAPTIC_SAWTOOTHUP
   1.134 + *
   1.135 + * \brief Periodic haptic effect that simulates saw tooth up waves.
   1.136 + *
   1.137 + * \sa SDL_HapticPeriodic
   1.138 + */
   1.139  #define SDL_HAPTIC_SAWTOOTHUP (1<<4) /* Sawtoothup wave effect supported */
   1.140 +/**
   1.141 + * \def SDL_HAPTIC_SAWTOOTHDOWN
   1.142 + *
   1.143 + * \brief Periodic haptic effect that simulates saw tooth down waves.
   1.144 + *
   1.145 + * \sa SDL_HapticPeriodic
   1.146 + */
   1.147  #define SDL_HAPTIC_SAWTOOTHDOWN (1<<5) /* Sawtoothdown wave effect supported */
   1.148 +/**
   1.149 + * \def SDL_HAPTIC_RAMP
   1.150 + *
   1.151 + * \brief Ramp haptic effect.
   1.152 + *
   1.153 + * \sa SDL_HapticRamp
   1.154 + */
   1.155  #define SDL_HAPTIC_RAMP       (1<<6) /* Ramp effect supported */
   1.156 +/**
   1.157 + * \def SDL_HAPTIC_SPRING
   1.158 + *
   1.159 + * \brief Condition haptic effect that simulates a spring.  Effect is based on the
   1.160 + * axes position.
   1.161 + *
   1.162 + * \sa SDL_HapticCondition
   1.163 + */
   1.164  #define SDL_HAPTIC_SPRING     (1<<7) /* Spring effect supported - uses axes position */
   1.165 +/**
   1.166 + * \def SDL_HAPTIC_DAMPER
   1.167 + *
   1.168 + * \brief Condition haptic effect that simulates dampening.  Effect is based on the
   1.169 + * axes velocity.
   1.170 + *
   1.171 + * \sa SDL_HapticCondition
   1.172 + */
   1.173  #define SDL_HAPTIC_DAMPER     (1<<8) /* Damper effect supported - uses axes velocity */
   1.174 +/**
   1.175 + * \def SDL_HAPTIC_INERTIA
   1.176 + *
   1.177 + * \brief Condition haptic effect that simulates inertia.  Effect is based on the axes
   1.178 + * acceleration.
   1.179 + *
   1.180 + * \sa SDL_HapticCondition
   1.181 + */
   1.182  #define SDL_HAPTIC_INERTIA    (1<<9) /* Inertia effect supported - uses axes acceleration */
   1.183 +/**
   1.184 + * \def SDL_HAPTIC_FRICTION
   1.185 + *
   1.186 + * \brief Condition haptic effect that simulates friction.  Effect is based on the axes
   1.187 + * movement.
   1.188 + *
   1.189 + * \sa SDL_HapticCondition
   1.190 + */
   1.191  #define SDL_HAPTIC_FRICTION   (1<<10) /* Friction effect supported - uses axes movement */
   1.192 +/**
   1.193 + * \def SDL_HAPTIC_CUSTOM
   1.194 + *
   1.195 + * \brief User defined custom haptic effect. TODO.
   1.196 + */
   1.197  #define SDL_HAPTIC_CUSTOM     (1<<11) /* Custom effect is supported */
   1.198  /* These last two are features the device has, not effects */
   1.199 +/**
   1.200 + * \def SDL_HAPTIC_GAIN
   1.201 + *
   1.202 + * \brief Device supports setting the global gain.
   1.203 + *
   1.204 + * \sa SDL_HapticSetGain
   1.205 + */
   1.206  #define SDL_HAPTIC_GAIN       (1<<12) /* Device can set global gain */
   1.207 +/**
   1.208 + * \def SDL_HAPTIC_AUTOCENTER
   1.209 + *
   1.210 + * \brief Device supports setting autocenter.
   1.211 + *
   1.212 + * \sa SDL_HapticSetAutocenter
   1.213 + */
   1.214  #define SDL_HAPTIC_AUTOCENTER (1<<13) /* Device can set autocenter */
   1.215 +/**
   1.216 + * \def SDL_HAPTIC_STATUS
   1.217 + *
   1.218 + * \brief Device can be queried for effect status.
   1.219 + *
   1.220 + * \sa SDL_HapticGetEffectStatus
   1.221 + */
   1.222  #define SDL_HAPTIC_STATUS     (1<<14) /* Device can be queried for effect status */
   1.223  
   1.224  
   1.225 +/**
   1.226 + * \struct SDL_HapticConstant
   1.227 + *
   1.228 + * \brief A structure containing a template for a Constant effect.
   1.229 + *
   1.230 + * The struct is exclusive to the SDL_HAPTIC_CONSTANT effect.
   1.231 + *
   1.232 + * \sa SDL_HAPTIC_CONSTANT
   1.233 + * \sa SDL_HapticEffect
   1.234 + */
   1.235 +typedef struct SDL_HapticConstant {
   1.236 +   /* Header */
   1.237 +   Uint16 type; /**< SDL_HAPTIC_CONSTANT */
   1.238 +   Uint16 direction;
   1.239 +
   1.240 +   /* Replay */
   1.241 +   Uint16 length; /**< Duration of the effect. */
   1.242 +   Uint16 delay; /**< Delay before starting the effect. */
   1.243 +
   1.244 +   /* Trigger */
   1.245 +   Uint16 button; /**< Button that triggers the effect. */
   1.246 +   Uint16 interval; /**< How soon it can be triggered again after button. */
   1.247 +
   1.248 +   /* Constant */
   1.249 +   Sint16 level; /**< Strength of the constant effect. */
   1.250 +
   1.251 +   /* Envelope */
   1.252 +   Uint16 attack_length; /**< Duration of the attack. */
   1.253 +   Uint16 attack_level; /**< Level at the start of the attack. */
   1.254 +   Uint16 fade_length; /**< Duration of the fade. */
   1.255 +   Uint16 fade_level; /**< Level at the end of the fade. */
   1.256 +} SDL_HapticConstant;
   1.257 +/**
   1.258 + * \struct SDL_HapticPeriodic
   1.259 + *
   1.260 + * \brief A structure containing a template for a Periodic effect.
   1.261 + *
   1.262 + * The struct handles the following effects:
   1.263 + *   - SDL_HAPTIC_SINE
   1.264 + *   - SDL_HAPTIC_SQUARE
   1.265 + *   - SDL_HAPTIC_TRIANGLE
   1.266 + *   - SDL_HAPTIC_SAWTOOTHUP
   1.267 + *   - SDL_HAPTIC_SAWTOOTHDOWN
   1.268 + *
   1.269 + * \sa SDL_HAPTIC_SINE
   1.270 + * \sa SDL_HAPTIC_SQUARE
   1.271 + * \sa SDL_HAPTIC_TRIANGLE
   1.272 + * \sa SDL_HAPTIC_SAWTOOTHUP
   1.273 + * \sa SDL_HAPTIC_SAWTOOTHDOWN
   1.274 + * \sa SDL_HapticEffect
   1.275 + */
   1.276 +typedef struct SDL_HapticPeriodic {
   1.277 +   /* Header */
   1.278 +   Uint16 type; /* SDL_HAPTIC_{SINE,SQUARE,TRIANGLE,SAWTOOTHUP,SAWTOOTHDOWN} */
   1.279 +   Uint16 direction;
   1.280 +
   1.281 +   /* Replay */
   1.282 +   Uint16 length; /**< Duration of the effect. */
   1.283 +   Uint16 delay; /**< Delay before starting the effect. */
   1.284 +
   1.285 +   /* Trigger */
   1.286 +   Uint16 button; /**< Button that triggers the effect. */
   1.287 +   Uint16 interval; /**< How soon it can be triggered again after button. */
   1.288 +
   1.289 +   /* Periodic */
   1.290 +   Uint16 period; /**< Period of the wave. */
   1.291 +   Sint16 magnitude; /**< Peak value. */
   1.292 +   Sint16 offset; /**< Mean value of the wave. */
   1.293 +   Uint16 phase; /**< Horizontal shift. */
   1.294 +
   1.295 +   /* Envelope */
   1.296 +   Uint16 attack_length; /**< Duration of the attack. */
   1.297 +   Uint16 attack_level; /**< Level at the start of the attack. */
   1.298 +   Uint16 fade_length; /**< Duration of the fade. */
   1.299 +   Uint16 fade_level; /**< Level at the end of the fade. */
   1.300 +} SDL_HapticPeriodic;
   1.301 +/**
   1.302 + * \struct SDL_HapticCondition
   1.303 + *
   1.304 + * \brief A structure containing a template for a Condition effect.
   1.305 + *
   1.306 + * The struct handles the following effects:
   1.307 + *   - SDL_HAPTIC_SPRING
   1.308 + *   - SDL_HAPTIC_DAMPER
   1.309 + *   - SDL_HAPTIC_INERTIA
   1.310 + *   - SDL_HAPTIC_FRICTION
   1.311 + *
   1.312 + * \sa SDL_HAPTIC_SPRING
   1.313 + * \sa SDL_HAPTIC_DAMPER
   1.314 + * \sa SDL_HAPTIC_INERTIA
   1.315 + * \sa SDL_HAPTIC_FRICTION
   1.316 + * \sa SDL_HapticEffect
   1.317 + */
   1.318 +typedef struct SDL_HapticCondition {
   1.319 +   /* Header */
   1.320 +   Uint16 type; /**< SDL_HAPTIC_{SPRING,DAMPER,INERTIA,FRICTION} */
   1.321 +   Uint16 direction;
   1.322 +
   1.323 +   /* Replay */
   1.324 +   Uint16 length; /**< Duration of the effect. */
   1.325 +   Uint16 delay; /**< Delay before starting the effect. */
   1.326 +
   1.327 +   /* Trigger */
   1.328 +   Uint16 button; /**< Button that triggers the effect. */
   1.329 +   Uint16 interval; /**< How soon it can be triggered again after button. */
   1.330 +
   1.331 +   /* Condition */
   1.332 +   Uint16 right_sat; /**< Level when joystick is to the right. */
   1.333 +   Uint16 left_sat; /**< Level when joystick is to the left. */
   1.334 +   Sint16 right_coeff; /**< How fast to increase the force towards the right. */
   1.335 +   Sint16 left_coeff; /**< How fast to increase the force towards the left. */
   1.336 +   Uint16 deadband; /**< Size of the dead zone. */
   1.337 +   Sint16 center; /**< Position of the dead zone. */
   1.338 +} SDL_HapticCondition;
   1.339 +/**
   1.340 + * \struct SDL_HapticRamp
   1.341 + *
   1.342 + * \brief A structure containing a template for a Ramp effect.
   1.343 + *
   1.344 + * This struct is exclusively for the SDL_HAPTIC_RAMP effect.
   1.345 + *
   1.346 + * \sa SDL_HAPTIC_RAMP
   1.347 + * \sa SDL_HapticEffect
   1.348 + */
   1.349 +typedef struct SDL_HapticRamp {
   1.350 +   /* Header */
   1.351 +   Uint16 type; /**< SDL_HAPTIC_RAMP */
   1.352 +   Uint16 direction;
   1.353 +
   1.354 +   /* Replay */
   1.355 +   Uint16 length; /**< Duration of the effect. */
   1.356 +   Uint16 delay; /**< Delay before starting the effect. */
   1.357 +
   1.358 +   /* Trigger */
   1.359 +   Uint16 button; /**< Button that triggers the effect. */
   1.360 +   Uint16 interval; /**< How soon it can be triggered again after button. */
   1.361 +
   1.362 +   /* Ramp */
   1.363 +   Sint16 start; /**< Beginning strength level. */
   1.364 +   Sint16 end; /**< Ending strength level. */
   1.365 +
   1.366 +   /* Envelope */
   1.367 +   Uint16 attack_length; /**< Duration of the attack. */
   1.368 +   Uint16 attack_level; /**< Level at the start of the attack. */
   1.369 +   Uint16 fade_length; /**< Duration of the fade. */
   1.370 +   Uint16 fade_level; /**< Level at the end of the fade. */
   1.371 +} SDL_HapticRamp;
   1.372  /*
   1.373 + * \union SDL_HapticEffect
   1.374 + *
   1.375 + * \brief The generic template for any haptic effect.
   1.376 + *
   1.377   * All values max at 32767 (0x7fff).  Signed values also can be negative.
   1.378   * Time values unless specified otherwise are in milliseconds.
   1.379   *
   1.380 @@ -86,230 +412,270 @@
   1.381   *    Uint16 attack_level;    Level at the start of the attack.
   1.382   *    Uint16 fade_length;     Duration of the fade out.
   1.383   *    Uint16 fade_level;      Level at the end of the fade.
   1.384 + *
   1.385 + * \sa SDL_HapticConstant
   1.386 + * \sa SDL_HapticPeriodic
   1.387 + * \sa SDL_HapticCondition
   1.388 + * \sa SDL_HaptiRamp
   1.389   */
   1.390 -typedef struct SDL_HapticConstant {
   1.391 -   /* Header */
   1.392 -   Uint16 type; /* SDL_HAPTIC_CONSTANT */
   1.393 -   Uint16 direction;
   1.394 -
   1.395 -   /* Replay */
   1.396 -   Uint16 length;
   1.397 -   Uint16 delay;
   1.398 -
   1.399 -   /* Trigger */
   1.400 -   Uint16 button;
   1.401 -   Uint16 interval;
   1.402 -
   1.403 -   /* Constant */
   1.404 -   Sint16 level; /* Strength of the constant effect. */
   1.405 -
   1.406 -   /* Envelope */
   1.407 -   Uint16 attack_length;
   1.408 -   Uint16 attack_level;
   1.409 -   Uint16 fade_length;
   1.410 -   Uint16 fade_level;
   1.411 -} SDL_HapticConstant;
   1.412 -typedef struct SDL_HapticPeriodic {
   1.413 -   /* Header */
   1.414 -   Uint16 type; /* SDL_HAPTIC_{SINE,SQUARE,TRIANGLE,SAWTOOTHUP,SAWTOOTHDOWN} */
   1.415 -   Uint16 direction;
   1.416 -
   1.417 -   /* Replay */
   1.418 -   Uint16 length;
   1.419 -   Uint16 delay;
   1.420 -
   1.421 -   /* Trigger */
   1.422 -   Uint16 button;
   1.423 -   Uint16 interval;
   1.424 -
   1.425 -   /* Periodic */
   1.426 -   Uint16 period; /* Period of the wave */
   1.427 -   Sint16 magnitude; /* Peak value */
   1.428 -   Sint16 offset; /* Mean value of the wave */
   1.429 -   Uint16 phase; /* Horizontal shift */
   1.430 -
   1.431 -   /* Envelope */
   1.432 -   Uint16 attack_length;
   1.433 -   Uint16 attack_level;
   1.434 -   Uint16 fade_length;
   1.435 -   Uint16 fade_level;
   1.436 -} SDL_HapticPeriodic;
   1.437 -typedef struct SDL_HapticCondition {
   1.438 -   /* Header */
   1.439 -   Uint16 type; /* SDL_HAPTIC_{SPRING,DAMPER,INERTIA,FRICTION} */
   1.440 -   Uint16 direction;
   1.441 -
   1.442 -   /* Replay */
   1.443 -   Uint16 length;
   1.444 -   Uint16 delay;
   1.445 -
   1.446 -   /* Trigger */
   1.447 -   Uint16 button;
   1.448 -   Uint16 interval;
   1.449 -
   1.450 -   /* Condition */
   1.451 -   Uint16 right_sat; /* Level when joystick is to the right. */
   1.452 -   Uint16 left_sat; /* Level when joystick is to the left */
   1.453 -   Sint16 right_coeff; /* How fast to increase the force towards the right */
   1.454 -   Sint16 left_coeff; /* How fast to increase the force towards the left */
   1.455 -   Uint16 deadband; /* Size of the dead zone */
   1.456 -   Sint16 center; /* Position of the dead zone */
   1.457 -} SDL_HapticCondition;
   1.458 -typedef struct SDL_HapticRamp {
   1.459 -   /* Header */
   1.460 -   Uint16 type; /* SDL_HAPTIC_RAMP */
   1.461 -   Uint16 direction;
   1.462 -
   1.463 -   /* Replay */
   1.464 -   Uint16 length;
   1.465 -   Uint16 delay;
   1.466 -
   1.467 -   /* Trigger */
   1.468 -   Uint16 button;
   1.469 -   Uint16 interval;
   1.470 -
   1.471 -   /* Ramp */
   1.472 -   Sint16 start; /* Beginning strength level. */
   1.473 -   Sint16 end; /* Ending strength level. */
   1.474 -
   1.475 -   /* Envelope */
   1.476 -   Uint16 attack_length;
   1.477 -   Uint16 attack_level;
   1.478 -   Uint16 fade_length;
   1.479 -   Uint16 fade_level;
   1.480 -} SDL_HapticRamp;
   1.481 -
   1.482  typedef union SDL_HapticEffect {
   1.483     /* Common for all force feedback effects */
   1.484 -   Uint16 type; /* Effect type */
   1.485 -   SDL_HapticConstant constant; /* Constant effect */
   1.486 -   SDL_HapticPeriodic periodic; /* Periodic effect */
   1.487 -   SDL_HapticCondition condition; /* Condition effect */
   1.488 -   SDL_HapticRamp ramp; /* Ramp effect */
   1.489 +   Uint16 type; /**< Effect type */
   1.490 +   SDL_HapticConstant constant; /**< Constant effect */
   1.491 +   SDL_HapticPeriodic periodic; /**< Periodic effect */
   1.492 +   SDL_HapticCondition condition; /**< Condition effect */
   1.493 +   SDL_HapticRamp ramp; /**< Ramp effect */
   1.494  } SDL_HapticEffect;
   1.495  
   1.496  
   1.497  /* Function prototypes */
   1.498  /*
   1.499 - * Count the number of joysticks attached to the system
   1.500 + * \fn int SDL_NumHaptics(void)
   1.501 + *
   1.502 + * \brief Count the number of joysticks attached to the system.
   1.503 + *
   1.504 + *    \return Number of haptic devices detected on the system.
   1.505   */
   1.506  extern DECLSPEC int SDLCALL SDL_NumHaptics(void);
   1.507  
   1.508  /*
   1.509 - * Get the implementation dependent name of a Haptic device.
   1.510 + * \fn const char * SDL_HapticName(int device_index)
   1.511 + *
   1.512 + * \brief Get the implementation dependent name of a Haptic device.
   1.513   * This can be called before any joysticks are opened.
   1.514   * If no name can be found, this function returns NULL.
   1.515 + *
   1.516 + *    \param device_index Index of the device to get it's name.
   1.517 + *    \return Name of the device or NULL on error.
   1.518 + *
   1.519 + * \sa SDL_NumHaptics
   1.520   */
   1.521  extern DECLSPEC const char *SDLCALL SDL_HapticName(int device_index);
   1.522  
   1.523  /*
   1.524 - * Opens a Haptic device for usage - the index passed as an
   1.525 + * \fn SDL_Haptic * SDL_HapticOpen(int device_Index)
   1.526 + *
   1.527 + * \brief Opens a Haptic device for usage - the index passed as an
   1.528   * argument refers to the N'th Haptic device on this system.
   1.529   *
   1.530   * This function returns a Haptic device identifier, or Null
   1.531   * if an error occurred.
   1.532 + *
   1.533 + *    \param device_index Index of the device to open.
   1.534 + *    \return Device identifier or NULL on error.
   1.535 + *
   1.536 + * \sa SDL_HapticOpenFromJoystick
   1.537 + * \sa SDL_HapticClose
   1.538   */
   1.539  extern DECLSPEC SDL_Haptic * SDL_HapticOpen(int device_index);
   1.540  
   1.541  /*
   1.542 - * Checks to see if a joystick has haptic features.
   1.543 + * \fn int SDL_JoystickIsHaptic(SDL_Joystick * joysticke)
   1.544   *
   1.545 - * Returns SDL_TRUE if the joystick is haptic, SDL_FALSE if it isn't
   1.546 - * and -1 on error.
   1.547 + * \brief Checks to see if a joystick has haptic features.
   1.548 + *
   1.549 + *    \param joystick Joystick to test for haptic capabilities.
   1.550 + *    \return SDL_TRUE if the joystick is haptic, SDL_FALSE if it isn't
   1.551 + *            or -1 if an error ocurred.
   1.552 + *
   1.553 + * \sa SDL_HapticOpenFromJoystick
   1.554   */
   1.555  extern DECLSPEC int SDL_JoystickIsHaptic(SDL_Joystick * joystick);
   1.556  
   1.557  /*
   1.558 - * Opens a Haptic device for usage from a Joystick device.
   1.559 + * \fn SDL_Haptic * SDL_HapticOpenFromJoystick(SDL_Joystick * joystick)
   1.560   *
   1.561 - * Returns a valid pointer to a haptic device on success or NULL
   1.562 - * if an error occurred.
   1.563 + * \brief Opens a Haptic device for usage from a Joystick device.  Still has
   1.564 + * to be closed seperately to the joystick.
   1.565 + *
   1.566 + *    \param joystick Joystick to create a haptic device from.
   1.567 + *    \return A valid haptic device identifier on success or NULL on error.
   1.568 + *
   1.569 + * \sa SDL_HapticOpen
   1.570 + * \sa SDL_HapticClose
   1.571   */
   1.572  extern DECLSPEC SDL_Haptic * SDL_HapticOpenFromJoystick(SDL_Joystick * joystick);
   1.573  
   1.574  /* 
   1.575 - * Closes a Haptic device previously opened with SDL_HapticOpen.
   1.576 + * \fn void SDL_HapticClose(SDL_Haptic * haptic)
   1.577 + *
   1.578 + * \brief Closes a Haptic device previously opened with SDL_HapticOpen.
   1.579 + *
   1.580 + *    \param haptic Haptic device to close.
   1.581   */
   1.582  extern DECLSPEC void SDL_HapticClose(SDL_Haptic * haptic);
   1.583  
   1.584  /*
   1.585 - * Returns the number of effects a haptic device can store.
   1.586 + * \fn int SDL_HapticNumEffects(SDL_Haptic * haptic)
   1.587 + *
   1.588 + * \brief Returns the number of effects a haptic device can store.
   1.589 + *
   1.590 + *    \param haptic The haptic device to query effect max.
   1.591 + *    \return The number of effects the haptic device can store or
   1.592 + *            -1 on error.
   1.593 + *
   1.594 + * \sa SDL_HapticQuery
   1.595   */
   1.596  extern DECLSPEC int SDL_HapticNumEffects(SDL_Haptic * haptic);
   1.597  
   1.598  /*
   1.599 - * Returns the supported effects.  Individual effects can be queried by
   1.600 - * bitwise operators.
   1.601 + * \fn unsigned int SDL_HapticQueryEffects(SDL_Haptic * haptic)
   1.602   *
   1.603 - * Example:  (SDL_HapticQueryEffects(haptic) & SDL_HAPTIC_CONSTANT)
   1.604 + * \brief Gets the haptic devices supported features in bitwise matter.
   1.605 + *
   1.606 + * Example: 
   1.607 + * \code
   1.608 + * if (SDL_HapticQueryEffects(haptic) & SDL_HAPTIC_CONSTANT) {
   1.609 + *    printf("We have constant haptic effect!");
   1.610 + * }
   1.611 + * \endcode
   1.612 + *    
   1.613 + *
   1.614 + *    \param haptic The haptic device to query.
   1.615 + *    \return Haptic features in bitwise manner (OR'd).
   1.616 + *
   1.617 + * \sa SDL_HapticNumEffects
   1.618 + * \sa SDL_HapticEffectSupported
   1.619   */
   1.620 -extern DECLSPEC unsigned int SDL_HapticQueryEffects(SDL_Haptic * haptic);
   1.621 +extern DECLSPEC unsigned int SDL_HapticQuery(SDL_Haptic * haptic);
   1.622  
   1.623  /*
   1.624 - * Checks to see if effect is supported by haptic.
   1.625 + * \fn int SDL_HapticEffectSupported
   1.626   *
   1.627 - * Returns SDL_TRUE if effect is supported, SDL_FALSE if it isn't and -1
   1.628 - * on error.
   1.629 + * \brief Checks to see if effect is supported by haptic.
   1.630 + *
   1.631 + *    \param haptic Haptic device to check on.
   1.632 + *    \param effect Effect to check to see if it is supported.
   1.633 + *    \return SDL_TRUE if effect is supported, SDL_FALSE if it isn't or 
   1.634 + *            -1 on error.
   1.635 + * 
   1.636 + * \sa SDL_HapticQuery
   1.637 + * \sa SDL_HapticNewEffect
   1.638   */
   1.639  extern DECLSPEC int SDL_HapticEffectSupported(SDL_Haptic * haptic, SDL_HapticEffect * effect);
   1.640  
   1.641  /*
   1.642 - * Creates a new haptic effect on the device.
   1.643 + * \fn int SDL_HapticNewEffect(SDL_Haptic * haptic, SDL_HapticEffect * effect)
   1.644   *
   1.645 - * Returns the id of the effect on success, -1 on failure.
   1.646 + * \brief Creates a new haptic effect on the device.
   1.647 + *
   1.648 + *    \param haptic Haptic device to create the effect on.
   1.649 + *    \param effect Properties of the effect to create.
   1.650 + *    \return The id of the effect on success or -1 on error.
   1.651 + *
   1.652 + * \sa SDL_HapticUpdateEffect
   1.653 + * \sa SDL_HapticRunEffect
   1.654 + * \sa SDL_HapticDestroyEffect
   1.655   */
   1.656  extern DECLSPEC int SDL_HapticNewEffect(SDL_Haptic * haptic, SDL_HapticEffect * effect);
   1.657  
   1.658  /*
   1.659 - * Uploads an effect.  Can be used dynamically, although behaviour when
   1.660 + * \fn int SDL_HapticUpdateEffect(SDL_Haptic * haptic, int effect, SDL_HapticEffect * data)
   1.661 + *
   1.662 + * \brief Updates an effect.  Can be used dynamically, although behaviour when
   1.663   * dynamically changing direction may be strange.  Specifically the effect
   1.664   * may reupload itself and start playing from the start.  You cannot change
   1.665   * the type either when running UpdateEffect.
   1.666   *
   1.667 - * Returns the id of the effect on success, -1 on failure.
   1.668 + *    \param haptic Haptic device that has the effect.
   1.669 + *    \param effect Effect to update.
   1.670 + *    \param data New effect properties to use.
   1.671 + *    \return The id of the effect on success or -1 on error.
   1.672 + *
   1.673 + * \sa SDL_HapticNewEffect
   1.674 + * \sa SDL_HapticRunEffect
   1.675 + * \sa SDL_HapticDestroyEffect
   1.676   */
   1.677  extern DECLSPEC int SDL_HapticUpdateEffect(SDL_Haptic * haptic, int effect, SDL_HapticEffect * data);
   1.678  
   1.679  /*
   1.680 - * Runs the haptic effect on it's assosciated haptic device.
   1.681 + * \fn int SDL_HapticRunEffects(SDL_Haptic * haptic, int effect)
   1.682   *
   1.683 - * Returns 0 on success or -1 on failure.
   1.684 + * \brief Runs the haptic effect on it's assosciated haptic device.
   1.685 + *
   1.686 + *    \param haptic Haptic device to run the effect on.
   1.687 + *    \param effect Identifier of the haptic effect to run.
   1.688 + *    \return 0 on success or -1 on error.
   1.689 + *
   1.690 + * \sa SDL_HapticStopEffect
   1.691 + * \sa SDL_HapticDestroyEffect
   1.692 + * \sa SDL_HapticGetEffectStatus
   1.693   */
   1.694  extern DECLSPEC int SDL_HapticRunEffect(SDL_Haptic * haptic, int effect);
   1.695  
   1.696  /*
   1.697 - * Stops the haptic effect on it's assosciated haptic device.
   1.698 + * \fn int SDL_HapticStopEffect(SDL_Haptic * haptic, int effect)
   1.699   *
   1.700 - * Returns 0 on success or -1 on failure.
   1.701 + * \brief Stops the haptic effect on it's assosciated haptic device.
   1.702 + *
   1.703 + *    \param haptic Haptic device to stop the effect on.
   1.704 + *    \praam effect Identifier of the effect to stop.
   1.705 + *    \return 0 on success or -1 on error.
   1.706 + *
   1.707 + * \sa SDL_HapticRunEffect
   1.708 + * \sa SDL_HapticDestroyEffect
   1.709   */
   1.710  extern DECLSPEC int SDL_HapticStopEffect(SDL_Haptic * haptic, int effect);
   1.711  
   1.712  /*
   1.713 - * Destroys a haptic effect on the device.  This will stop the effect if it's
   1.714 - * running.
   1.715 + * \fn void SDL_HapticDestroyEffect(SDL_Haptic * haptic, int effect)
   1.716 + *
   1.717 + * \brief Destroys a haptic effect on the device.  This will stop the effect
   1.718 + * if it's running.  Effects are automatically destroyed when the device is
   1.719 + * closed.
   1.720 + *
   1.721 + *    \param haptic Device to destroy the effect on.
   1.722 + *    \param effect Identifier of the effect to destroy.
   1.723 + * 
   1.724 + * \sa SDL_HapticNewEffect
   1.725   */
   1.726  extern DECLSPEC void SDL_HapticDestroyEffect(SDL_Haptic * haptic, int effect);
   1.727  
   1.728  /*
   1.729 - * Gets the status of the current effect on the haptic device.
   1.730 + * \fn int SDL_HapticGetEffectStatus(SDL_Haptic *haptic, int effect)
   1.731   *
   1.732 - * Returns 0 if it isn't playing, SDL_HAPTIC_PLAYING if it is playing
   1.733 - * or -1 on failure.
   1.734 + * \brief Gets the status of the current effect on the haptic device.
   1.735 + *
   1.736 + * Device must support the SDL_HAPTIC_STATUS feature.
   1.737 + *
   1.738 + *    \param haptic Haptic device to query the effect status on.
   1.739 + *    \param effect Identifier of the effect to query it's status.
   1.740 + *    \return 0 if it isn't playing, SDL_HAPTIC_PLAYING if it is playing
   1.741 + *            or -1 on error.
   1.742 + *
   1.743 + * \sa SDL_HapticRunEffect
   1.744 + * \sa SDL_HapticStopEffect
   1.745   */
   1.746  extern DECLSPEC int SDL_HapticGetEffectStatus(SDL_Haptic *haptic, int effect);
   1.747  
   1.748  /*
   1.749 - * Sets the global gain of the device.  Gain should be between 0 and 100.
   1.750 + * \fn int SDL_HapticSetGain(SDL_Haptic * haptic, int gain)
   1.751   *
   1.752 - * Returns 0 on success or -1 on failure.
   1.753 + * \brief Sets the global gain of the device.  Gain should be between 0 and 100.
   1.754 + *
   1.755 + * Device must support the SDL_HAPTIC_GAIN feature.
   1.756 + *
   1.757 + *    \param haptic Haptic device to set the gain on.
   1.758 + *    \param gain Value to set the gain to, should be between 0 and 100.
   1.759 + *    \return 0 on success or -1 on error.
   1.760 + *
   1.761 + * \sa SDL_HapticQuery
   1.762   */
   1.763  extern DECLSPEC int SDL_HapticSetGain(SDL_Haptic * haptic, int gain);
   1.764  
   1.765  /*
   1.766 - * Sets the global autocenter of the device.  Autocenter should be between
   1.767 + * \fn int SDL_HapticSetAutocenter(SDL_Haptic * haptic, int autocenter)
   1.768 + *
   1.769 + * \brief Sets the global autocenter of the device.  Autocenter should be between
   1.770   * 0 and 100.  Setting it to 0 will disable autocentering.
   1.771   *
   1.772 - * Returns 0 on success or -1 on failure.
   1.773 + * Device must support the SDL_HAPTIC_AUTOCENTER feature.
   1.774 + *
   1.775 + *    \param haptic Haptic device to set autocentering on.
   1.776 + *    \param autocenter Value to set autocenter to, 0 disables autocentering.
   1.777 + *    \return 0 on success or -1 on error.
   1.778 + *
   1.779 + * \sa SDL_HapticQuery
   1.780   */
   1.781  extern DECLSPEC int SDL_HapticSetAutocenter(SDL_Haptic * haptic, int autocenter);
   1.782  
     2.1 --- a/src/haptic/SDL_haptic.c	Thu Jul 03 21:03:25 2008 +0000
     2.2 +++ b/src/haptic/SDL_haptic.c	Sun Jul 06 16:53:32 2008 +0000
     2.3 @@ -292,7 +292,7 @@
     2.4   * Returns supported effects by the device.
     2.5   */
     2.6  unsigned int
     2.7 -SDL_HapticQueryEffects(SDL_Haptic * haptic)
     2.8 +SDL_HapticQuery(SDL_Haptic * haptic)
     2.9  {
    2.10     if (!ValidHaptic(&haptic)) {
    2.11        return -1;