include/SDL_haptic.h
branchgsoc2008_force_feedback
changeset 2519 af9df9662807
parent 2517 37c13c12c878
child 2523 366d84fdf8d1
     1.1 --- a/include/SDL_haptic.h	Tue Jul 15 11:24:25 2008 +0000
     1.2 +++ b/include/SDL_haptic.h	Tue Jul 15 15:53:48 2008 +0000
     1.3 @@ -212,7 +212,7 @@
     1.4  /**
     1.5   * \def SDL_HAPTIC_CUSTOM
     1.6   *
     1.7 - * \brief User defined custom haptic effect. TODO.
     1.8 + * \brief User defined custom haptic effect. @todo.
     1.9   */
    1.10  #define SDL_HAPTIC_CUSTOM     (1<<11) /* Custom effect is supported */
    1.11  /* These last two are features the device has, not effects */
    1.12 @@ -261,6 +261,14 @@
    1.13   * \sa SDL_HapticDirection
    1.14   */
    1.15  #define SDL_HAPTIC_CARTESIAN  1
    1.16 +/**
    1.17 + * \def SDL_HAPTIC_SHPERICAL
    1.18 + *
    1.19 + * \brief Uses spherical coordinates for the direction.
    1.20 + *
    1.21 + * \sa SDL_HapticDirection
    1.22 + */
    1.23 +#define SDL_HAPTIC_SPHERICAL  2
    1.24  
    1.25  
    1.26  /*
    1.27 @@ -273,7 +281,7 @@
    1.28   *
    1.29   * \sa SDL_HapticRunEffect
    1.30   */
    1.31 -#define SDL_HAPTIC_INFINITY   -1
    1.32 +#define SDL_HAPTIC_INFINITY   4294967295U
    1.33  
    1.34  
    1.35  /**
    1.36 @@ -317,19 +325,28 @@
    1.37   * \endcode
    1.38   *
    1.39   * If type is SDL_HAPTIC_POLAR, direction is encoded by hundredths of a 
    1.40 - *  degree starting north and turning clockwise.  The cardinal directions would be:
    1.41 + *  degree starting north and turning clockwise.  SDL_HAPTIC_POLAR only uses
    1.42 + *  the first dir parameter.  The cardinal directions would be:
    1.43   *   - North: 0 (0 degrees)
    1.44   *   - East: 9000 (90 degrees)
    1.45   *   - South: 18000 (180 degrees)
    1.46   *   - West: 27000 (270 degrees)
    1.47   *
    1.48 - * If type is SDL_HAPTIC_CARTESIAN, direction is encoded by position.
    1.49 - *  The cardinal directions would be:
    1.50 + * If type is SDL_HAPTIC_CARTESIAN, direction is encoded by two positions
    1.51 + *  (X axis and Y axis).  SDL_HAPTIC_CARTESIAN uses the first two dir 
    1.52 + *  parameters.  The cardinal directions would be:
    1.53   *   - North:  0,-1
    1.54   *   - East:  -1, 0
    1.55   *   - South:  0, 1
    1.56   *   - West:   1, 0
    1.57   *
    1.58 + * If type is SDL_HAPTIC_SPHERICAL, direction is encoded by three rotations.
    1.59 + *  All three dir parameters are used.  The dir parameters are as follows
    1.60 + *  (all values are in hundredths of degrees):
    1.61 + *    1) Degrees from (1, 0) rotated towards (0, 1).
    1.62 + *    2) Degrees towards (0, 0, 1) (device needs at least 3 axes).
    1.63 + *    3) Degrees tworads (0, 0, 0, 1) (device needs at least 4 axes).
    1.64 + *
    1.65   *
    1.66   * Example:
    1.67   * \code
    1.68 @@ -342,11 +359,12 @@
    1.69   *
    1.70   * \sa SDL_HAPTIC_POLAR
    1.71   * \sa SDL_HAPTIC_CARTESIAN
    1.72 + * \sa SDL_HAPTIC_SHPERICAL
    1.73   * \sa SDL_HapticEffect
    1.74   */
    1.75  typedef struct SDL_HapticDirection {
    1.76     Uint8 type; /**< The type of encoding. */
    1.77 -   Uint16 dir[2]; /**< The encoded direction. */
    1.78 +   Uint16 dir[3]; /**< The encoded direction. */
    1.79  } SDL_HapticDirection;
    1.80  
    1.81  
    1.82 @@ -369,7 +387,7 @@
    1.83     SDL_HapticDirection direction; /**< Direction of the effect. */
    1.84  
    1.85     /* Replay */
    1.86 -   Uint16 length; /**< Duration of the effect. */
    1.87 +   Uint32 length; /**< Duration of the effect. */
    1.88     Uint16 delay; /**< Delay before starting the effect. */
    1.89  
    1.90     /* Trigger */
    1.91 @@ -444,7 +462,7 @@
    1.92     SDL_HapticDirection direction; /**< Direction of the effect. */
    1.93  
    1.94     /* Replay */
    1.95 -   Uint16 length; /**< Duration of the effect. */
    1.96 +   Uint32 length; /**< Duration of the effect. */
    1.97     Uint16 delay; /**< Delay before starting the effect. */
    1.98  
    1.99     /* Trigger */
   1.100 @@ -494,7 +512,7 @@
   1.101                       SDL_HAPTIC_INERTIA or SDL_HAPTIC_FRICTION */
   1.102  
   1.103     /* Replay */
   1.104 -   Uint16 length; /**< Duration of the effect. */
   1.105 +   Uint32 length; /**< Duration of the effect. */
   1.106     Uint16 delay; /**< Delay before starting the effect. */
   1.107  
   1.108     /* Trigger */
   1.109 @@ -530,7 +548,7 @@
   1.110     SDL_HapticDirection direction; /**< Direction of the effect. */
   1.111  
   1.112     /* Replay */
   1.113 -   Uint16 length; /**< Duration of the effect. */
   1.114 +   Uint32 length; /**< Duration of the effect. */
   1.115     Uint16 delay; /**< Delay before starting the effect. */
   1.116  
   1.117     /* Trigger */
   1.118 @@ -555,10 +573,14 @@
   1.119   * All values max at 32767 (0x7FFF).  Signed values also can be negative.
   1.120   *  Time values unless specified otherwise are in milliseconds.
   1.121   *
   1.122 + * You can also pass SDL_HAPTIC_INFINITY to length instead of a 0-32767 value.
   1.123 + *  Neither delay, interval, attack_length nor fade_length support 
   1.124 + *  SDL_HAPTIC_INFINITY.
   1.125 + *
   1.126   * Common parts:
   1.127   * \code
   1.128   * // Replay - All effects have this
   1.129 - * Uint16 length;        // Duration of effect (ms).
   1.130 + * Uint32 length;        // Duration of effect (ms).
   1.131   * Uint16 delay;         // Delay before starting effect.
   1.132   *
   1.133   * // Trigger - All effects have this
   1.134 @@ -857,7 +879,7 @@
   1.135   * \sa SDL_HapticDestroyEffect
   1.136   * \sa SDL_HapticGetEffectStatus
   1.137   */
   1.138 -extern DECLSPEC int SDL_HapticRunEffect(SDL_Haptic * haptic, int effect, int iterations);
   1.139 +extern DECLSPEC int SDL_HapticRunEffect(SDL_Haptic * haptic, int effect, Uint32 iterations);
   1.140  
   1.141  /**
   1.142   * \fn int SDL_HapticStopEffect(SDL_Haptic * haptic, int effect)