Created SDL_HapticDirection. gsoc2008_force_feedback
authorEdgar Simo <bobbens@gmail.com>
Sun, 06 Jul 2008 20:41:00 +0000
branchgsoc2008_force_feedback
changeset 2499cc2b270608b2
parent 2498 ab567bd667bf
child 2500 5251d0510b7e
Created SDL_HapticDirection.
Fixed all doxygen errors.
Added more diagrams and documentation.
include/SDL_haptic.h
     1.1 --- a/include/SDL_haptic.h	Sun Jul 06 17:06:37 2008 +0000
     1.2 +++ b/include/SDL_haptic.h	Sun Jul 06 20:41:00 2008 +0000
     1.3 @@ -20,10 +20,8 @@
     1.4      slouken@libsdl.org
     1.5  */
     1.6  
     1.7 -/** \file SDL_Haptic.h */
     1.8 -
     1.9  /**
    1.10 - * \mainpage SDL_haptic
    1.11 + * \file SDL_haptic.h
    1.12   *
    1.13   * \brief The SDL Haptic subsystem allows you to control haptic (force feedback)
    1.14   *  devices.
    1.15 @@ -61,6 +59,8 @@
    1.16   *    // Create the effect
    1.17   *    memset( &effect, 0, sizeof(SDL_HapticEffect) ); // 0 is safe default
    1.18   *    effect.type = SDL_HAPTIC_SINE;
    1.19 + *    effect.periodic.direction.type = SDL_HAPTIC_POLAR; // Polar coordinates
    1.20 + *    effect.periodic.direction.dir[0] = 180000; // Force comes from south
    1.21   *    effect.periodic.period = 1000; // 1000 ms
    1.22   *    effect.periodic.magnitude = 20000; // 20000/32767 strength
    1.23   *    effect.periodic.length = 5000; // 5 seconds long
    1.24 @@ -138,7 +138,7 @@
    1.25   * \def SDL_HAPTIC_SQUARE
    1.26   *
    1.27   * \brief Periodic haptic effect that simulates square waves.
    1.28 - *
    1.29 + * 
    1.30   * \sa SDL_HapticPeriodic
    1.31   */
    1.32  #define SDL_HAPTIC_SQUARE     (1<<2) /* Square wave effect supported */
    1.33 @@ -243,6 +243,101 @@
    1.34  #define SDL_HAPTIC_STATUS     (1<<14) /* Device can be queried for effect status */
    1.35  
    1.36  
    1.37 +/*
    1.38 + * Direction encodings
    1.39 + */
    1.40 +/**
    1.41 + * \def SDL_HAPTIC_POLAR
    1.42 + *
    1.43 + * \brief Uses polar coordinates for the direction.
    1.44 + *
    1.45 + * \sa SDL_HapticDirection
    1.46 + */
    1.47 +#define SDL_HAPTIC_POLAR      0
    1.48 +/**
    1.49 + * \def SDL_HAPTIC_CARTESIAN
    1.50 + *
    1.51 + * \brief Uses cartesian coordinates for the direction.
    1.52 + *
    1.53 + * \sa SDL_HapticDirection
    1.54 + */
    1.55 +#define SDL_HAPTIC_CARTESIAN  1
    1.56 +
    1.57 +
    1.58 +/**
    1.59 + * \struct SDL_HapticDirection
    1.60 + *
    1.61 + * \brief Structure that represents a haptic direction.
    1.62 + *
    1.63 + * Directions can be specified by:
    1.64 + *   - SDL_HAPTIC_POLAR: Specified by polar coordinates.
    1.65 + *   - SDL_HAPTIC_CARTESIAN: Specified by cartesian coordinates.
    1.66 + *
    1.67 + * Cardinal directions of the haptic device are relative to the positioning
    1.68 + *  of the device.  North is considered to be away from the user.
    1.69 + *
    1.70 + * The following diagram represents the cardinal directions:
    1.71 + * \code
    1.72 + *            .--.
    1.73 + *            |__| .-------.
    1.74 + *            |=.| |.-----.|
    1.75 + *            |--| ||     ||
    1.76 + *            |  | |'-----'|
    1.77 + *            |__|~')_____('
    1.78 + *              [ COMPUTER ]
    1.79 + *
    1.80 + *
    1.81 + *                  North (-1)
    1.82 + *                    ^
    1.83 + *                    |
    1.84 + *                    |
    1.85 + * (1)  East <----[ HAPTIC ]----> West (-1)
    1.86 + *                    |
    1.87 + *                    |
    1.88 + *                    v
    1.89 + *                  South (1)
    1.90 + *
    1.91 + *
    1.92 + *                 [ USER ]
    1.93 + *                   \|||/
    1.94 + *                   (o o)
    1.95 + *             ---ooO-(_)-Ooo---
    1.96 + * \endcode
    1.97 + *
    1.98 + * If type is SDL_HAPTIC_POLAR, direction is encoded by hundredths of a 
    1.99 + *  degree starting north and turning clockwise.  The cardinal directions would be:
   1.100 + *   - North: 0 (0 degrees)
   1.101 + *   - West: 9000 (90 degrees)
   1.102 + *   - South: 18000 (180 degrees)
   1.103 + *   - East: 27000 (270 degrees)
   1.104 + *
   1.105 + * If type is SDL_HAPTIC_CARTESIAN, direction is encoded by position.
   1.106 + *  The cardinal directions would be:
   1.107 + *   - North:  0,-1
   1.108 + *   - West:  -1, 0
   1.109 + *   - South:  0, 1
   1.110 + *   - East:   1, 0
   1.111 + *
   1.112 + *
   1.113 + * Example:
   1.114 + * \code
   1.115 + * SDL_HapticDirection direction;
   1.116 + *
   1.117 + * direction.type = SDL_HAPTIC_POLAR; // We'll be using polar direction encoding.
   1.118 + * direction.dir = 180000; // Force comes from the south meaning the user will
   1.119 + *                         // have to pull the stick to counteract.
   1.120 + * \endcode
   1.121 + *
   1.122 + * \sa SDL_HAPTIC_POLAR
   1.123 + * \sa SDL_HAPTIC_CARTESIAN
   1.124 + * \sa SDL_HapticEffect
   1.125 + */
   1.126 +typedef struct SDL_HapticDirection {
   1.127 +   Uint8 type; /**< The type of encoding. */
   1.128 +   Uint16 dir[2]; /**< The encoded direction. */
   1.129 +} SDL_HapticDirection;
   1.130 +
   1.131 +
   1.132  /**
   1.133   * \struct SDL_HapticConstant
   1.134   *
   1.135 @@ -256,7 +351,7 @@
   1.136  typedef struct SDL_HapticConstant {
   1.137     /* Header */
   1.138     Uint16 type; /**< SDL_HAPTIC_CONSTANT */
   1.139 -   Uint16 direction;
   1.140 +   SDL_HapticDirection direction; /**< Direction of the effect. */
   1.141  
   1.142     /* Replay */
   1.143     Uint16 length; /**< Duration of the effect. */
   1.144 @@ -287,17 +382,47 @@
   1.145   *   - SDL_HAPTIC_SAWTOOTHUP
   1.146   *   - SDL_HAPTIC_SAWTOOTHDOWN
   1.147   *
   1.148 + * Examples:
   1.149 + * \code
   1.150 + * SDL_HAPTIC_SINE
   1.151 + *   __      __      __      __
   1.152 + *  /  \    /  \    /  \    /
   1.153 + * /    \__/    \__/    \__/
   1.154 + *
   1.155 + * SDL_HAPTIC_SQUARE
   1.156 + *  __    __    __    __    __
   1.157 + * |  |  |  |  |  |  |  |  |  |
   1.158 + * |  |__|  |__|  |__|  |__|  |
   1.159 + *
   1.160 + * SDL_HAPTIC_TRIANGLE
   1.161 + *   /\    /\    /\    /\    /\
   1.162 + *  /  \  /  \  /  \  /  \  /
   1.163 + * /    \/    \/    \/    \/
   1.164 + *
   1.165 + * SDL_HAPTIC_SAWTOOTHUP
   1.166 + *    __    __    __    __    _
   1.167 + *   /  |  /  |  /  |  /  |  /
   1.168 + *  /   | /   | /   | /   | /
   1.169 + * /    |/    |/    |/    |/
   1.170 + *
   1.171 + * SDL_HAPTIC_SAWTOOTHDOWN
   1.172 + * __    __    __    __    __
   1.173 + *   \  |  \  |  \  |  \  |  \
   1.174 + *    \ |   \ |   \ |   \ |   \
   1.175 + *     \|    \|    \|    \|
   1.176 + * \endcode
   1.177 + *
   1.178   * \sa SDL_HAPTIC_SINE
   1.179   * \sa SDL_HAPTIC_SQUARE
   1.180   * \sa SDL_HAPTIC_TRIANGLE
   1.181   * \sa SDL_HAPTIC_SAWTOOTHUP
   1.182 - * \sa SDL_HAPTIC_SAWTOOTHDOWN
   1.183 + * \sa SDL_HAPTIC SAWTOOTHDOWN
   1.184   * \sa SDL_HapticEffect
   1.185   */
   1.186  typedef struct SDL_HapticPeriodic {
   1.187     /* Header */
   1.188 -   Uint16 type; /* SDL_HAPTIC_{SINE,SQUARE,TRIANGLE,SAWTOOTHUP,SAWTOOTHDOWN} */
   1.189 -   Uint16 direction;
   1.190 +   Uint16 type; /**< SDL_HAPTIC_{SINE,SQUARE,TRIANGLE,SAWTOOTHUP,SAWTOOTHDOWN} */
   1.191 +   SDL_HapticDirection direction; /**< Direction of the effect. */
   1.192  
   1.193     /* Replay */
   1.194     Uint16 length; /**< Duration of the effect. */
   1.195 @@ -324,11 +449,13 @@
   1.196   *
   1.197   * \brief A structure containing a template for a Condition effect.
   1.198   *
   1.199 + * Direction is handled by condition internals instead of a direction member.
   1.200 + *
   1.201   * The struct handles the following effects:
   1.202 - *   - SDL_HAPTIC_SPRING
   1.203 - *   - SDL_HAPTIC_DAMPER
   1.204 - *   - SDL_HAPTIC_INERTIA
   1.205 - *   - SDL_HAPTIC_FRICTION
   1.206 + *   - SDL_HAPTIC_SPRING: Effect based on axes position.
   1.207 + *   - SDL_HAPTIC_DAMPER: Effect based on axes velocity.
   1.208 + *   - SDL_HAPTIC_INERTIA: Effect based on axes acceleration.
   1.209 + *   - SDL_HAPTIC_FRICTION: Effect based on axes movement.
   1.210   *
   1.211   * \sa SDL_HAPTIC_SPRING
   1.212   * \sa SDL_HAPTIC_DAMPER
   1.213 @@ -339,7 +466,6 @@
   1.214  typedef struct SDL_HapticCondition {
   1.215     /* Header */
   1.216     Uint16 type; /**< SDL_HAPTIC_{SPRING,DAMPER,INERTIA,FRICTION} */
   1.217 -   Uint16 direction;
   1.218  
   1.219     /* Replay */
   1.220     Uint16 length; /**< Duration of the effect. */
   1.221 @@ -370,7 +496,7 @@
   1.222  typedef struct SDL_HapticRamp {
   1.223     /* Header */
   1.224     Uint16 type; /**< SDL_HAPTIC_RAMP */
   1.225 -   Uint16 direction;
   1.226 +   SDL_HapticDirection direction; /**< Direction of the effect. */
   1.227  
   1.228     /* Replay */
   1.229     Uint16 length; /**< Duration of the effect. */
   1.230 @@ -395,37 +521,61 @@
   1.231   *
   1.232   * \brief The generic template for any haptic effect.
   1.233   *
   1.234 - * All values max at 32767 (0x7fff).  Signed values also can be negative.
   1.235 + * All values max at 32767 (0x7FFF).  Signed values also can be negative.
   1.236   * Time values unless specified otherwise are in milliseconds.
   1.237   *
   1.238   * Common parts:
   1.239 + * \code
   1.240 + * // Replay - All effects have this
   1.241 + * Uint16 length;        // Duration of effect (ms).
   1.242 + * Uint16 delay;         // Delay before starting effect.
   1.243 + *
   1.244 + * // Trigger - All effects have this
   1.245 + * Uint16 button;        // Button that triggers effect.
   1.246 + * Uint16 interval;      // How soon before effect can be triggered again.
   1.247 + *
   1.248 + * // Envelope - Not all effects have this
   1.249 + * Uint16 attack_length; // Duration of the attack (ms).
   1.250 + * Uint16 attack_level;  // Level at the start of the attack.
   1.251 + * Uint16 fade_length;   // Duration of the fade out (ms).
   1.252 + * Uint16 fade_level;    // Level at the end of the fade.
   1.253 + * \endcode
   1.254 + *
   1.255 + *
   1.256 + * Here we have an example of an effect evolution in time:
   1.257 + *
   1.258 + * \code
   1.259 + * Strength
   1.260 + * ^
   1.261 + * |
   1.262 + * | effect strength -->  _________________
   1.263 + * |                     /                 \
   1.264 + * |                    /                   \
   1.265 + * |                   /                     \
   1.266 + * |                  /                       \ 
   1.267 + * | attack_level --> |                        \
   1.268 + * |                  |                        |  <---  fade_level
   1.269 + * |
   1.270 + * +--------------------------------------------------> Time
   1.271 + *                    [--]                 [---]
   1.272 + *                    attack_length        fade_length
   1.273   * 
   1.274 - * Replay:
   1.275 - *    Uint16 length;    Duration of effect.
   1.276 - *    Uint16 delay;     Delay before starting effect.
   1.277 - *
   1.278 - * Trigger:
   1.279 - *    Uint16 button;    Button that triggers effect.
   1.280 - *    Uint16 interval;  How soon before effect can be triggered again.
   1.281 - *
   1.282 - * Envelope:
   1.283 - *    Uint16 attack_length;   Duration of the attack.
   1.284 - *    Uint16 attack_level;    Level at the start of the attack.
   1.285 - *    Uint16 fade_length;     Duration of the fade out.
   1.286 - *    Uint16 fade_level;      Level at the end of the fade.
   1.287 + * [------------------][-----------------------]
   1.288 + * delay               length
   1.289 + * \endcode
   1.290   *
   1.291   * \sa SDL_HapticConstant
   1.292   * \sa SDL_HapticPeriodic
   1.293   * \sa SDL_HapticCondition
   1.294 - * \sa SDL_HaptiRamp
   1.295 + * \sa SDL_HapticRamp
   1.296   */
   1.297  typedef union SDL_HapticEffect {
   1.298     /* Common for all force feedback effects */
   1.299 -   Uint16 type; /**< Effect type */
   1.300 -   SDL_HapticConstant constant; /**< Constant effect */
   1.301 -   SDL_HapticPeriodic periodic; /**< Periodic effect */
   1.302 -   SDL_HapticCondition condition; /**< Condition effect */
   1.303 -   SDL_HapticRamp ramp; /**< Ramp effect */
   1.304 +   Uint16 type; /**< Effect type. */
   1.305 +   SDL_HapticConstant constant; /**< Constant effect. */
   1.306 +   SDL_HapticPeriodic periodic; /**< Periodic effect. */
   1.307 +   SDL_HapticCondition condition[2]; /**< Condition effect, one for each axis. */
   1.308 +   SDL_HapticRamp ramp; /**< Ramp effect. */
   1.309  } SDL_HapticEffect;
   1.310  
   1.311  
   1.312 @@ -454,7 +604,7 @@
   1.313  extern DECLSPEC const char *SDLCALL SDL_HapticName(int device_index);
   1.314  
   1.315  /**
   1.316 - * \fn SDL_Haptic * SDL_HapticOpen(int device_Index)
   1.317 + * \fn SDL_Haptic * SDL_HapticOpen(int device_index)
   1.318   *
   1.319   * \brief Opens a Haptic device for usage - the index passed as an
   1.320   * argument refers to the N'th Haptic device on this system.
   1.321 @@ -520,7 +670,7 @@
   1.322  extern DECLSPEC int SDL_HapticNumEffects(SDL_Haptic * haptic);
   1.323  
   1.324  /**
   1.325 - * \fn unsigned int SDL_HapticQueryEffects(SDL_Haptic * haptic)
   1.326 + * \fn unsigned int SDL_HapticQuery(SDL_Haptic * haptic)
   1.327   *
   1.328   * \brief Gets the haptic devices supported features in bitwise matter.
   1.329   *
   1.330 @@ -541,7 +691,7 @@
   1.331  extern DECLSPEC unsigned int SDL_HapticQuery(SDL_Haptic * haptic);
   1.332  
   1.333  /**
   1.334 - * \fn int SDL_HapticEffectSupported
   1.335 + * \fn int SDL_HapticEffectSupported(SDL_Haptic * haptic, SDL_HapticEffect * effect)
   1.336   *
   1.337   * \brief Checks to see if effect is supported by haptic.
   1.338   *
   1.339 @@ -590,7 +740,7 @@
   1.340  extern DECLSPEC int SDL_HapticUpdateEffect(SDL_Haptic * haptic, int effect, SDL_HapticEffect * data);
   1.341  
   1.342  /**
   1.343 - * \fn int SDL_HapticRunEffects(SDL_Haptic * haptic, int effect)
   1.344 + * \fn int SDL_HapticRunEffect(SDL_Haptic * haptic, int effect)
   1.345   *
   1.346   * \brief Runs the haptic effect on it's assosciated haptic device.
   1.347   *
   1.348 @@ -610,7 +760,7 @@
   1.349   * \brief Stops the haptic effect on it's assosciated haptic device.
   1.350   *
   1.351   *    \param haptic Haptic device to stop the effect on.
   1.352 - *    \praam effect Identifier of the effect to stop.
   1.353 + *    \param effect Identifier of the effect to stop.
   1.354   *    \return 0 on success or -1 on error.
   1.355   *
   1.356   * \sa SDL_HapticRunEffect