Fixed more mistakes in documentation. gsoc2008_force_feedback
authorEdgar Simo <bobbens@gmail.com>
Mon, 07 Jul 2008 18:42:10 +0000
branchgsoc2008_force_feedback
changeset 2504e68c99a19a2f
parent 2503 84a634009a83
child 2505 abfcba0f3bd1
Fixed more mistakes in documentation.
include/SDL_haptic.h
     1.1 --- a/include/SDL_haptic.h	Mon Jul 07 17:01:14 2008 +0000
     1.2 +++ b/include/SDL_haptic.h	Mon Jul 07 18:42:10 2008 +0000
     1.3 @@ -37,7 +37,6 @@
     1.4   *   - (optional) Free the effect with SDL_HapticDestroyEffect(...).
     1.5   *   - Close the haptic device with SDL_HapticClose(...).
     1.6   *
     1.7 - *
     1.8   * Example:
     1.9   *
    1.10   * \code
    1.11 @@ -51,7 +50,7 @@
    1.12   *    if (haptic == NULL) return -1; // Most likely joystick isn't haptic
    1.13   *
    1.14   *    // See if it can do sine waves
    1.15 - *    if ((SDL_HapticQueryEffects(haptic) & SDL_HAPTIC_SINE)==0) {
    1.16 + *    if ((SDL_HapticQuery(haptic) & SDL_HAPTIC_SINE)==0) {
    1.17   *       SDL_HapticClose(haptic); // No sine effect
    1.18   *       return -1;
    1.19   *    }
    1.20 @@ -100,7 +99,7 @@
    1.21  /* *INDENT-OFF* */
    1.22  extern "C" {
    1.23     /* *INDENT-ON* */                                                         
    1.24 -#endif /* __cpluspuls */
    1.25 +#endif /* __cplusplus */
    1.26  
    1.27  /**
    1.28   * \typedef SDL_Haptic
    1.29 @@ -270,8 +269,8 @@
    1.30   * \brief Structure that represents a haptic direction.
    1.31   *
    1.32   * Directions can be specified by:
    1.33 - *   - SDL_HAPTIC_POLAR: Specified by polar coordinates.
    1.34 - *   - SDL_HAPTIC_CARTESIAN: Specified by cartesian coordinates.
    1.35 + *   - SDL_HAPTIC_POLAR : Specified by polar coordinates.
    1.36 + *   - SDL_HAPTIC_CARTESIAN : Specified by cartesian coordinates.
    1.37   *
    1.38   * Cardinal directions of the haptic device are relative to the positioning
    1.39   *  of the device.  North is considered to be away from the user.
    1.40 @@ -345,6 +344,9 @@
    1.41   *
    1.42   * The struct is exclusive to the SDL_HAPTIC_CONSTANT effect.
    1.43   *
    1.44 + * A constant effect applies a constant force in the specified direction
    1.45 + *  to the joystick.
    1.46 + *
    1.47   * \sa SDL_HAPTIC_CONSTANT
    1.48   * \sa SDL_HapticEffect
    1.49   */
    1.50 @@ -382,6 +384,10 @@
    1.51   *   - SDL_HAPTIC_SAWTOOTHUP
    1.52   *   - SDL_HAPTIC_SAWTOOTHDOWN
    1.53   *
    1.54 + * A periodic effect consists in a wave-shaped effect that repeats itself
    1.55 + *  over time.  The type determines the shape of the wave and the parameters
    1.56 + *  determine the dimensions of the wave.
    1.57 + *
    1.58   * Examples:
    1.59   * \code
    1.60   * SDL_HAPTIC_SINE
    1.61 @@ -400,28 +406,28 @@
    1.62   * /    \/    \/    \/    \/
    1.63   *
    1.64   * SDL_HAPTIC_SAWTOOTHUP
    1.65 - *    __    __    __    __    _
    1.66 - *   /  |  /  |  /  |  /  |  /
    1.67 - *  /   | /   | /   | /   | /
    1.68 - * /    |/    |/    |/    |/
    1.69 + *   /|  /|  /|  /|  /|  /|  /|
    1.70 + *  / | / | / | / | / | / | / |
    1.71 + * /  |/  |/  |/  |/  |/  |/  |
    1.72   *
    1.73   * SDL_HAPTIC_SAWTOOTHDOWN
    1.74 - * __    __    __    __    __
    1.75 - *   \  |  \  |  \  |  \  |  \
    1.76 - *    \ |   \ |   \ |   \ |   \
    1.77 - *     \|    \|    \|    \|
    1.78 + * \  |\  |\  |\  |\  |\  |\  |
    1.79 + *  \ | \ | \ | \ | \ | \ | \ |
    1.80 + *   \|  \|  \|  \|  \|  \|  \|
    1.81   * \endcode
    1.82   *
    1.83   * \sa SDL_HAPTIC_SINE
    1.84   * \sa SDL_HAPTIC_SQUARE
    1.85   * \sa SDL_HAPTIC_TRIANGLE
    1.86   * \sa SDL_HAPTIC_SAWTOOTHUP
    1.87 - * \sa SDL_HAPTIC SAWTOOTHDOWN
    1.88 + * \sa SDL_HAPTIC_SAWTOOTHDOWN
    1.89   * \sa SDL_HapticEffect
    1.90   */
    1.91  typedef struct SDL_HapticPeriodic {
    1.92     /* Header */
    1.93 -   Uint16 type; /**< SDL_HAPTIC_{SINE,SQUARE,TRIANGLE,SAWTOOTHUP,SAWTOOTHDOWN} */
    1.94 +   Uint16 type; /**< SDL_HAPTIC_SINE, SDL_HAPTIC_SQUARE,
    1.95 +                     SDL_HAPTIC_TRIANGLE, SDL_HAPTIC_SAWTOOTHUP or
    1.96 +                     SDL_HAPTIC_SAWTOOTHDOWN */
    1.97     SDL_HapticDirection direction; /**< Direction of the effect. */
    1.98  
    1.99     /* Replay */
   1.100 @@ -449,17 +455,19 @@
   1.101   *
   1.102   * \brief A structure containing a template for a Condition effect.
   1.103   *
   1.104 - * Direction is handled by condition internals instead of a direction member.
   1.105 - *  Each of right_sat, lefT-sat, right_coeff, left_coeff, deadband and center
   1.106 - *  have two parameters, first is for x value, second is for y value following
   1.107 - *  the scheme set by SDL_HapticDirection.
   1.108 - *
   1.109   * The struct handles the following effects:
   1.110   *   - SDL_HAPTIC_SPRING: Effect based on axes position.
   1.111   *   - SDL_HAPTIC_DAMPER: Effect based on axes velocity.
   1.112   *   - SDL_HAPTIC_INERTIA: Effect based on axes acceleration.
   1.113   *   - SDL_HAPTIC_FRICTION: Effect based on axes movement.
   1.114   *
   1.115 + * Direction is handled by condition internals instead of a direction member.
   1.116 + *  The condition effect specific members have two parameters.  The first
   1.117 + *  refers to the X axis, the second refers to the Y axis.  The right terms
   1.118 + *  refer to the positive side of the axis and the left terms refer to the
   1.119 + *  negative side of the axis.  Please refer to the SDL_HapticDirection 
   1.120 + *  diagram for which side is positive and which is negative.
   1.121 + *
   1.122   * \sa SDL_HapticDirection
   1.123   * \sa SDL_HAPTIC_SPRING
   1.124   * \sa SDL_HAPTIC_DAMPER
   1.125 @@ -469,7 +477,8 @@
   1.126   */
   1.127  typedef struct SDL_HapticCondition {
   1.128     /* Header */
   1.129 -   Uint16 type; /**< SDL_HAPTIC_{SPRING,DAMPER,INERTIA,FRICTION} */
   1.130 +   Uint16 type; /**< SDL_HAPTIC_SPRING, SDL_HAPTIC_DAMPER,
   1.131 +                     SDL_HAPTIC_INERTIA or SDL_HAPTIC_FRICTION */
   1.132  
   1.133     /* Replay */
   1.134     Uint16 length; /**< Duration of the effect. */
   1.135 @@ -480,10 +489,10 @@
   1.136     Uint16 interval; /**< How soon it can be triggered again after button. */
   1.137  
   1.138     /* Condition */
   1.139 -   Uint16 right_sat[2]; /**< Level when joystick is to the right. */
   1.140 -   Uint16 left_sat[2]; /**< Level when joystick is to the left. */
   1.141 -   Sint16 right_coeff[2]; /**< How fast to increase the force towards the right. */
   1.142 -   Sint16 left_coeff[2]; /**< How fast to increase the force towards the left. */
   1.143 +   Uint16 right_sat[2]; /**< Level when joystick is to the positive side. */
   1.144 +   Uint16 left_sat[2]; /**< Level when joystick is to the negative side. */
   1.145 +   Sint16 right_coeff[2]; /**< How fast to increase the force towards the positive side. */
   1.146 +   Sint16 left_coeff[2]; /**< How fast to increase the force towards the negative side. */
   1.147     Uint16 deadband[2]; /**< Size of the dead zone. */
   1.148     Sint16 center[2]; /**< Position of the dead zone. */
   1.149  } SDL_HapticCondition;
   1.150 @@ -494,6 +503,11 @@
   1.151   *
   1.152   * This struct is exclusively for the SDL_HAPTIC_RAMP effect.
   1.153   *
   1.154 + * The ramp effect starts at start strength and ends at end strength.
   1.155 + *  It augments in linear fashion.  If you use attack and fade with a ramp
   1.156 + *  they effects get added to the ramp effect making the effect become
   1.157 + *  quadratic instead of linear.
   1.158 + *
   1.159   * \sa SDL_HAPTIC_RAMP
   1.160   * \sa SDL_HapticEffect
   1.161   */
   1.162 @@ -526,7 +540,7 @@
   1.163   * \brief The generic template for any haptic effect.
   1.164   *
   1.165   * All values max at 32767 (0x7FFF).  Signed values also can be negative.
   1.166 - * Time values unless specified otherwise are in milliseconds.
   1.167 + *  Time values unless specified otherwise are in milliseconds.
   1.168   *
   1.169   * Common parts:
   1.170   * \code
   1.171 @@ -538,7 +552,7 @@
   1.172   * Uint16 button;        // Button that triggers effect.
   1.173   * Uint16 interval;      // How soon before effect can be triggered again.
   1.174   *
   1.175 - * // Envelope - Not all effects have this
   1.176 + * // Envelope - All effects except condition effects have this
   1.177   * Uint16 attack_length; // Duration of the attack (ms).
   1.178   * Uint16 attack_level;  // Level at the start of the attack.
   1.179   * Uint16 fade_length;   // Duration of the fade out (ms).
   1.180 @@ -546,13 +560,13 @@
   1.181   * \endcode
   1.182   *
   1.183   *
   1.184 - * Here we have an example of an effect evolution in time:
   1.185 + * Here we have an example of a constant effect evolution in time:
   1.186   *
   1.187   * \code
   1.188   * Strength
   1.189   * ^
   1.190   * |
   1.191 - * | effect strength -->  _________________
   1.192 + * |    effect level -->  _________________
   1.193   * |                     /                 \
   1.194   * |                    /                   \
   1.195   * |                   /                     \
   1.196 @@ -568,6 +582,9 @@
   1.197   * delay               length
   1.198   * \endcode
   1.199   *
   1.200 + * Note either the attack_level or the fade_level may be above the actual
   1.201 + *  effect level.
   1.202 + *
   1.203   * \sa SDL_HapticConstant
   1.204   * \sa SDL_HapticPeriodic
   1.205   * \sa SDL_HapticCondition