include/SDL_haptic.h
branchgsoc2008_force_feedback
changeset 2497 0893fbf73b3d
parent 2495 66c02abeef0e
child 2498 ab567bd667bf
equal deleted inserted replaced
2496:8f840a6cdf01 2497:0893fbf73b3d
    18 
    18 
    19     Sam Lantinga
    19     Sam Lantinga
    20     slouken@libsdl.org
    20     slouken@libsdl.org
    21 */
    21 */
    22 
    22 
    23 /**
    23 /** \file SDL_haptic.h */
    24  * \file SDL_haptic.h
    24 /**
    25  *
    25  * \mainpage SDL_haptic
    26  * Include file for SDL haptic subsystem
    26  *
       
    27  * The SDL Haptic subsystem allows you to control haptic (force feedback)
       
    28  *  devices.
       
    29  *
       
    30  * The basic usage is as follows:
       
    31  *   - Initialize the Subsystem (SDL_INIT_HAPTIC).
       
    32  *   - Open a Haptic Device.
       
    33  *     - SDL_HapticOpen(...) to open from index.
       
    34  *     - SDL_HapticOpenFromJoystick(...) to open from an existing joystick.
       
    35  *   - Create an effect (SDL_HapticEffect).
       
    36  *   - Upload the effect with SDL_HapticNewEffect(...).
       
    37  *   - Run the effect with SDL_HapticRunEffect(...).
       
    38  *   - (optional) Free the effect with SDL_HapticDestroyEffect(...).
       
    39  *   - Close the haptic device with SDL_HapticClose(...).
       
    40  *
       
    41  *
       
    42  * Example:
       
    43  *
       
    44  * \code
       
    45  * int test_haptic( SDL_Joystick * joystick ) {
       
    46  *    SDL_Haptic *haptic;
       
    47  *    SDL_HapticEffect effect;
       
    48  *    int effect_id;
       
    49  *
       
    50  *    // Open the device
       
    51  *    haptic = SDL_HapticOpenFromJoystick( joystick );
       
    52  *    if (haptic == NULL) return -1; // Most likely joystick isn't haptic
       
    53  *
       
    54  *    // See if it can do sine waves
       
    55  *    if ((SDL_HapticQueryEffects(haptic) & SDL_HAPTIC_SINE)==0) {
       
    56  *       SDL_HapticClose(haptic); // No sine effect
       
    57  *       return -1;
       
    58  *    }
       
    59  *
       
    60  *    // Create the effect
       
    61  *    memset( &effect, 0, sizeof(SDL_HapticEffect) ); // 0 is safe default
       
    62  *    effect.type = SDL_HAPTIC_SINE;
       
    63  *    effect.periodic.period = 1000; // 1000 ms
       
    64  *    effect.periodic.magnitude = 20000; // 20000/32767 strength
       
    65  *    effect.periodic.length = 5000; // 5 seconds long
       
    66  *    effect.periodic.attack_length = 1000; // Takes 1 second to get max strength
       
    67  *    effect.periodic.fade_length = 1000; // Takes 1 second to fade away
       
    68  *
       
    69  *    // Upload the effect
       
    70  *    effect_id = SDL_HapticNewEffect( haptic, &effect );
       
    71  *
       
    72  *    // Test the effect
       
    73  *    SDL_HapticRunEffect( haptic, effect_id );
       
    74  *    SDL_Delay( 5000); // Wait for the effect to finish
       
    75  *
       
    76  *    // We destroy the effect, although closing the device also does this
       
    77  *    SDL_HapticDestroyEffect( haptic, effect_id );
       
    78  *
       
    79  *    // Close the device
       
    80  *    SDL_HapticClose(haptic);
       
    81  *
       
    82  *    return 0; // Success
       
    83  * }
       
    84  * \endcode
       
    85  *
       
    86  * \author Edgar Simo Serra
    27  */
    87  */
    28 
    88 
    29 #ifndef _SDL_haptic_h
    89 #ifndef _SDL_haptic_h
    30 #define _SDL_haptic_h
    90 #define _SDL_haptic_h
    31 
    91 
    37 /* Set up for C function definitions, even when using C++ */
    97 /* Set up for C function definitions, even when using C++ */
    38 #ifdef __cplusplus
    98 #ifdef __cplusplus
    39 /* *INDENT-OFF* */
    99 /* *INDENT-OFF* */
    40 extern "C" {
   100 extern "C" {
    41    /* *INDENT-ON* */                                                         
   101    /* *INDENT-ON* */                                                         
    42 #endif
   102 #endif /* __cpluspuls */
    43 
   103 
    44 /* The haptic structure used to identify an SDL haptic */
   104 /**
       
   105  * \struct SDL_Haptic
       
   106  *
       
   107  * \brief The haptic structure used to identify an SDL haptic.
       
   108  *
       
   109  * \sa SDL_HapticOpen
       
   110  * \sa SDL_HapticOpenFromJoystick
       
   111  * \sa SDL_HapticClose
       
   112  */
    45 struct _SDL_Haptic;                                                     
   113 struct _SDL_Haptic;                                                     
    46 typedef struct _SDL_Haptic SDL_Haptic;
   114 typedef struct _SDL_Haptic SDL_Haptic;
    47 
   115 
    48 
   116 
    49 /*
   117 /*
    50  * Different haptic features a device can have.
   118  * Different haptic features a device can have.
    51  */
   119  */
       
   120 /**
       
   121  * \def SDL_HAPTIC_CONSTANT
       
   122  *
       
   123  * \brief Constant haptic effect.
       
   124  *
       
   125  * \sa SDL_HapticCondition
       
   126  */
    52 #define SDL_HAPTIC_CONSTANT   (1<<0) /* Constant effect supported */
   127 #define SDL_HAPTIC_CONSTANT   (1<<0) /* Constant effect supported */
       
   128 /**
       
   129  * \def SDL_HAPTIC_SINE
       
   130  *
       
   131  * \brief Periodic haptic effect that simulates sine waves.
       
   132  *
       
   133  * \sa SDL_HapticPeriodic
       
   134  */
    53 #define SDL_HAPTIC_SINE       (1<<1) /* Sine wave effect supported */
   135 #define SDL_HAPTIC_SINE       (1<<1) /* Sine wave effect supported */
       
   136 /**
       
   137  * \def SDL_HAPTIC_SQUARE
       
   138  *
       
   139  * \brief Periodic haptic effect that simulates square waves.
       
   140  *
       
   141  * \sa SDL_HapticPeriodic
       
   142  */
    54 #define SDL_HAPTIC_SQUARE     (1<<2) /* Square wave effect supported */
   143 #define SDL_HAPTIC_SQUARE     (1<<2) /* Square wave effect supported */
       
   144 /**
       
   145  * \def SDL_HAPTIC_TRIANGLE
       
   146  *
       
   147  * \brief Periodic haptic effect that simulates triangular waves.
       
   148  *
       
   149  * \sa SDL_HapticPeriodic
       
   150  */
    55 #define SDL_HAPTIC_TRIANGLE   (1<<3) /* Triangle wave effect supported */
   151 #define SDL_HAPTIC_TRIANGLE   (1<<3) /* Triangle wave effect supported */
       
   152 /**
       
   153  * \def SDL_HAPTIC_SAWTOOTHUP
       
   154  *
       
   155  * \brief Periodic haptic effect that simulates saw tooth up waves.
       
   156  *
       
   157  * \sa SDL_HapticPeriodic
       
   158  */
    56 #define SDL_HAPTIC_SAWTOOTHUP (1<<4) /* Sawtoothup wave effect supported */
   159 #define SDL_HAPTIC_SAWTOOTHUP (1<<4) /* Sawtoothup wave effect supported */
       
   160 /**
       
   161  * \def SDL_HAPTIC_SAWTOOTHDOWN
       
   162  *
       
   163  * \brief Periodic haptic effect that simulates saw tooth down waves.
       
   164  *
       
   165  * \sa SDL_HapticPeriodic
       
   166  */
    57 #define SDL_HAPTIC_SAWTOOTHDOWN (1<<5) /* Sawtoothdown wave effect supported */
   167 #define SDL_HAPTIC_SAWTOOTHDOWN (1<<5) /* Sawtoothdown wave effect supported */
       
   168 /**
       
   169  * \def SDL_HAPTIC_RAMP
       
   170  *
       
   171  * \brief Ramp haptic effect.
       
   172  *
       
   173  * \sa SDL_HapticRamp
       
   174  */
    58 #define SDL_HAPTIC_RAMP       (1<<6) /* Ramp effect supported */
   175 #define SDL_HAPTIC_RAMP       (1<<6) /* Ramp effect supported */
       
   176 /**
       
   177  * \def SDL_HAPTIC_SPRING
       
   178  *
       
   179  * \brief Condition haptic effect that simulates a spring.  Effect is based on the
       
   180  * axes position.
       
   181  *
       
   182  * \sa SDL_HapticCondition
       
   183  */
    59 #define SDL_HAPTIC_SPRING     (1<<7) /* Spring effect supported - uses axes position */
   184 #define SDL_HAPTIC_SPRING     (1<<7) /* Spring effect supported - uses axes position */
       
   185 /**
       
   186  * \def SDL_HAPTIC_DAMPER
       
   187  *
       
   188  * \brief Condition haptic effect that simulates dampening.  Effect is based on the
       
   189  * axes velocity.
       
   190  *
       
   191  * \sa SDL_HapticCondition
       
   192  */
    60 #define SDL_HAPTIC_DAMPER     (1<<8) /* Damper effect supported - uses axes velocity */
   193 #define SDL_HAPTIC_DAMPER     (1<<8) /* Damper effect supported - uses axes velocity */
       
   194 /**
       
   195  * \def SDL_HAPTIC_INERTIA
       
   196  *
       
   197  * \brief Condition haptic effect that simulates inertia.  Effect is based on the axes
       
   198  * acceleration.
       
   199  *
       
   200  * \sa SDL_HapticCondition
       
   201  */
    61 #define SDL_HAPTIC_INERTIA    (1<<9) /* Inertia effect supported - uses axes acceleration */
   202 #define SDL_HAPTIC_INERTIA    (1<<9) /* Inertia effect supported - uses axes acceleration */
       
   203 /**
       
   204  * \def SDL_HAPTIC_FRICTION
       
   205  *
       
   206  * \brief Condition haptic effect that simulates friction.  Effect is based on the axes
       
   207  * movement.
       
   208  *
       
   209  * \sa SDL_HapticCondition
       
   210  */
    62 #define SDL_HAPTIC_FRICTION   (1<<10) /* Friction effect supported - uses axes movement */
   211 #define SDL_HAPTIC_FRICTION   (1<<10) /* Friction effect supported - uses axes movement */
       
   212 /**
       
   213  * \def SDL_HAPTIC_CUSTOM
       
   214  *
       
   215  * \brief User defined custom haptic effect. TODO.
       
   216  */
    63 #define SDL_HAPTIC_CUSTOM     (1<<11) /* Custom effect is supported */
   217 #define SDL_HAPTIC_CUSTOM     (1<<11) /* Custom effect is supported */
    64 /* These last two are features the device has, not effects */
   218 /* These last two are features the device has, not effects */
       
   219 /**
       
   220  * \def SDL_HAPTIC_GAIN
       
   221  *
       
   222  * \brief Device supports setting the global gain.
       
   223  *
       
   224  * \sa SDL_HapticSetGain
       
   225  */
    65 #define SDL_HAPTIC_GAIN       (1<<12) /* Device can set global gain */
   226 #define SDL_HAPTIC_GAIN       (1<<12) /* Device can set global gain */
       
   227 /**
       
   228  * \def SDL_HAPTIC_AUTOCENTER
       
   229  *
       
   230  * \brief Device supports setting autocenter.
       
   231  *
       
   232  * \sa SDL_HapticSetAutocenter
       
   233  */
    66 #define SDL_HAPTIC_AUTOCENTER (1<<13) /* Device can set autocenter */
   234 #define SDL_HAPTIC_AUTOCENTER (1<<13) /* Device can set autocenter */
       
   235 /**
       
   236  * \def SDL_HAPTIC_STATUS
       
   237  *
       
   238  * \brief Device can be queried for effect status.
       
   239  *
       
   240  * \sa SDL_HapticGetEffectStatus
       
   241  */
    67 #define SDL_HAPTIC_STATUS     (1<<14) /* Device can be queried for effect status */
   242 #define SDL_HAPTIC_STATUS     (1<<14) /* Device can be queried for effect status */
    68 
   243 
    69 
   244 
    70 /*
   245 /**
       
   246  * \struct SDL_HapticConstant
       
   247  *
       
   248  * \brief A structure containing a template for a Constant effect.
       
   249  *
       
   250  * The struct is exclusive to the SDL_HAPTIC_CONSTANT effect.
       
   251  *
       
   252  * \sa SDL_HAPTIC_CONSTANT
       
   253  * \sa SDL_HapticEffect
       
   254  */
       
   255 typedef struct SDL_HapticConstant {
       
   256    /* Header */
       
   257    Uint16 type; /**< SDL_HAPTIC_CONSTANT */
       
   258    Uint16 direction;
       
   259 
       
   260    /* Replay */
       
   261    Uint16 length; /**< Duration of the effect. */
       
   262    Uint16 delay; /**< Delay before starting the effect. */
       
   263 
       
   264    /* Trigger */
       
   265    Uint16 button; /**< Button that triggers the effect. */
       
   266    Uint16 interval; /**< How soon it can be triggered again after button. */
       
   267 
       
   268    /* Constant */
       
   269    Sint16 level; /**< Strength of the constant effect. */
       
   270 
       
   271    /* Envelope */
       
   272    Uint16 attack_length; /**< Duration of the attack. */
       
   273    Uint16 attack_level; /**< Level at the start of the attack. */
       
   274    Uint16 fade_length; /**< Duration of the fade. */
       
   275    Uint16 fade_level; /**< Level at the end of the fade. */
       
   276 } SDL_HapticConstant;
       
   277 /**
       
   278  * \struct SDL_HapticPeriodic
       
   279  *
       
   280  * \brief A structure containing a template for a Periodic effect.
       
   281  *
       
   282  * The struct handles the following effects:
       
   283  *   - SDL_HAPTIC_SINE
       
   284  *   - SDL_HAPTIC_SQUARE
       
   285  *   - SDL_HAPTIC_TRIANGLE
       
   286  *   - SDL_HAPTIC_SAWTOOTHUP
       
   287  *   - SDL_HAPTIC_SAWTOOTHDOWN
       
   288  *
       
   289  * \sa SDL_HAPTIC_SINE
       
   290  * \sa SDL_HAPTIC_SQUARE
       
   291  * \sa SDL_HAPTIC_TRIANGLE
       
   292  * \sa SDL_HAPTIC_SAWTOOTHUP
       
   293  * \sa SDL_HAPTIC_SAWTOOTHDOWN
       
   294  * \sa SDL_HapticEffect
       
   295  */
       
   296 typedef struct SDL_HapticPeriodic {
       
   297    /* Header */
       
   298    Uint16 type; /* SDL_HAPTIC_{SINE,SQUARE,TRIANGLE,SAWTOOTHUP,SAWTOOTHDOWN} */
       
   299    Uint16 direction;
       
   300 
       
   301    /* Replay */
       
   302    Uint16 length; /**< Duration of the effect. */
       
   303    Uint16 delay; /**< Delay before starting the effect. */
       
   304 
       
   305    /* Trigger */
       
   306    Uint16 button; /**< Button that triggers the effect. */
       
   307    Uint16 interval; /**< How soon it can be triggered again after button. */
       
   308 
       
   309    /* Periodic */
       
   310    Uint16 period; /**< Period of the wave. */
       
   311    Sint16 magnitude; /**< Peak value. */
       
   312    Sint16 offset; /**< Mean value of the wave. */
       
   313    Uint16 phase; /**< Horizontal shift. */
       
   314 
       
   315    /* Envelope */
       
   316    Uint16 attack_length; /**< Duration of the attack. */
       
   317    Uint16 attack_level; /**< Level at the start of the attack. */
       
   318    Uint16 fade_length; /**< Duration of the fade. */
       
   319    Uint16 fade_level; /**< Level at the end of the fade. */
       
   320 } SDL_HapticPeriodic;
       
   321 /**
       
   322  * \struct SDL_HapticCondition
       
   323  *
       
   324  * \brief A structure containing a template for a Condition effect.
       
   325  *
       
   326  * The struct handles the following effects:
       
   327  *   - SDL_HAPTIC_SPRING
       
   328  *   - SDL_HAPTIC_DAMPER
       
   329  *   - SDL_HAPTIC_INERTIA
       
   330  *   - SDL_HAPTIC_FRICTION
       
   331  *
       
   332  * \sa SDL_HAPTIC_SPRING
       
   333  * \sa SDL_HAPTIC_DAMPER
       
   334  * \sa SDL_HAPTIC_INERTIA
       
   335  * \sa SDL_HAPTIC_FRICTION
       
   336  * \sa SDL_HapticEffect
       
   337  */
       
   338 typedef struct SDL_HapticCondition {
       
   339    /* Header */
       
   340    Uint16 type; /**< SDL_HAPTIC_{SPRING,DAMPER,INERTIA,FRICTION} */
       
   341    Uint16 direction;
       
   342 
       
   343    /* Replay */
       
   344    Uint16 length; /**< Duration of the effect. */
       
   345    Uint16 delay; /**< Delay before starting the effect. */
       
   346 
       
   347    /* Trigger */
       
   348    Uint16 button; /**< Button that triggers the effect. */
       
   349    Uint16 interval; /**< How soon it can be triggered again after button. */
       
   350 
       
   351    /* Condition */
       
   352    Uint16 right_sat; /**< Level when joystick is to the right. */
       
   353    Uint16 left_sat; /**< Level when joystick is to the left. */
       
   354    Sint16 right_coeff; /**< How fast to increase the force towards the right. */
       
   355    Sint16 left_coeff; /**< How fast to increase the force towards the left. */
       
   356    Uint16 deadband; /**< Size of the dead zone. */
       
   357    Sint16 center; /**< Position of the dead zone. */
       
   358 } SDL_HapticCondition;
       
   359 /**
       
   360  * \struct SDL_HapticRamp
       
   361  *
       
   362  * \brief A structure containing a template for a Ramp effect.
       
   363  *
       
   364  * This struct is exclusively for the SDL_HAPTIC_RAMP effect.
       
   365  *
       
   366  * \sa SDL_HAPTIC_RAMP
       
   367  * \sa SDL_HapticEffect
       
   368  */
       
   369 typedef struct SDL_HapticRamp {
       
   370    /* Header */
       
   371    Uint16 type; /**< SDL_HAPTIC_RAMP */
       
   372    Uint16 direction;
       
   373 
       
   374    /* Replay */
       
   375    Uint16 length; /**< Duration of the effect. */
       
   376    Uint16 delay; /**< Delay before starting the effect. */
       
   377 
       
   378    /* Trigger */
       
   379    Uint16 button; /**< Button that triggers the effect. */
       
   380    Uint16 interval; /**< How soon it can be triggered again after button. */
       
   381 
       
   382    /* Ramp */
       
   383    Sint16 start; /**< Beginning strength level. */
       
   384    Sint16 end; /**< Ending strength level. */
       
   385 
       
   386    /* Envelope */
       
   387    Uint16 attack_length; /**< Duration of the attack. */
       
   388    Uint16 attack_level; /**< Level at the start of the attack. */
       
   389    Uint16 fade_length; /**< Duration of the fade. */
       
   390    Uint16 fade_level; /**< Level at the end of the fade. */
       
   391 } SDL_HapticRamp;
       
   392 /*
       
   393  * \union SDL_HapticEffect
       
   394  *
       
   395  * \brief The generic template for any haptic effect.
       
   396  *
    71  * All values max at 32767 (0x7fff).  Signed values also can be negative.
   397  * All values max at 32767 (0x7fff).  Signed values also can be negative.
    72  * Time values unless specified otherwise are in milliseconds.
   398  * Time values unless specified otherwise are in milliseconds.
    73  *
   399  *
    74  * Common parts:
   400  * Common parts:
    75  * 
   401  * 
    84  * Envelope:
   410  * Envelope:
    85  *    Uint16 attack_length;   Duration of the attack.
   411  *    Uint16 attack_length;   Duration of the attack.
    86  *    Uint16 attack_level;    Level at the start of the attack.
   412  *    Uint16 attack_level;    Level at the start of the attack.
    87  *    Uint16 fade_length;     Duration of the fade out.
   413  *    Uint16 fade_length;     Duration of the fade out.
    88  *    Uint16 fade_level;      Level at the end of the fade.
   414  *    Uint16 fade_level;      Level at the end of the fade.
    89  */
   415  *
    90 typedef struct SDL_HapticConstant {
   416  * \sa SDL_HapticConstant
    91    /* Header */
   417  * \sa SDL_HapticPeriodic
    92    Uint16 type; /* SDL_HAPTIC_CONSTANT */
   418  * \sa SDL_HapticCondition
    93    Uint16 direction;
   419  * \sa SDL_HaptiRamp
    94 
   420  */
    95    /* Replay */
       
    96    Uint16 length;
       
    97    Uint16 delay;
       
    98 
       
    99    /* Trigger */
       
   100    Uint16 button;
       
   101    Uint16 interval;
       
   102 
       
   103    /* Constant */
       
   104    Sint16 level; /* Strength of the constant effect. */
       
   105 
       
   106    /* Envelope */
       
   107    Uint16 attack_length;
       
   108    Uint16 attack_level;
       
   109    Uint16 fade_length;
       
   110    Uint16 fade_level;
       
   111 } SDL_HapticConstant;
       
   112 typedef struct SDL_HapticPeriodic {
       
   113    /* Header */
       
   114    Uint16 type; /* SDL_HAPTIC_{SINE,SQUARE,TRIANGLE,SAWTOOTHUP,SAWTOOTHDOWN} */
       
   115    Uint16 direction;
       
   116 
       
   117    /* Replay */
       
   118    Uint16 length;
       
   119    Uint16 delay;
       
   120 
       
   121    /* Trigger */
       
   122    Uint16 button;
       
   123    Uint16 interval;
       
   124 
       
   125    /* Periodic */
       
   126    Uint16 period; /* Period of the wave */
       
   127    Sint16 magnitude; /* Peak value */
       
   128    Sint16 offset; /* Mean value of the wave */
       
   129    Uint16 phase; /* Horizontal shift */
       
   130 
       
   131    /* Envelope */
       
   132    Uint16 attack_length;
       
   133    Uint16 attack_level;
       
   134    Uint16 fade_length;
       
   135    Uint16 fade_level;
       
   136 } SDL_HapticPeriodic;
       
   137 typedef struct SDL_HapticCondition {
       
   138    /* Header */
       
   139    Uint16 type; /* SDL_HAPTIC_{SPRING,DAMPER,INERTIA,FRICTION} */
       
   140    Uint16 direction;
       
   141 
       
   142    /* Replay */
       
   143    Uint16 length;
       
   144    Uint16 delay;
       
   145 
       
   146    /* Trigger */
       
   147    Uint16 button;
       
   148    Uint16 interval;
       
   149 
       
   150    /* Condition */
       
   151    Uint16 right_sat; /* Level when joystick is to the right. */
       
   152    Uint16 left_sat; /* Level when joystick is to the left */
       
   153    Sint16 right_coeff; /* How fast to increase the force towards the right */
       
   154    Sint16 left_coeff; /* How fast to increase the force towards the left */
       
   155    Uint16 deadband; /* Size of the dead zone */
       
   156    Sint16 center; /* Position of the dead zone */
       
   157 } SDL_HapticCondition;
       
   158 typedef struct SDL_HapticRamp {
       
   159    /* Header */
       
   160    Uint16 type; /* SDL_HAPTIC_RAMP */
       
   161    Uint16 direction;
       
   162 
       
   163    /* Replay */
       
   164    Uint16 length;
       
   165    Uint16 delay;
       
   166 
       
   167    /* Trigger */
       
   168    Uint16 button;
       
   169    Uint16 interval;
       
   170 
       
   171    /* Ramp */
       
   172    Sint16 start; /* Beginning strength level. */
       
   173    Sint16 end; /* Ending strength level. */
       
   174 
       
   175    /* Envelope */
       
   176    Uint16 attack_length;
       
   177    Uint16 attack_level;
       
   178    Uint16 fade_length;
       
   179    Uint16 fade_level;
       
   180 } SDL_HapticRamp;
       
   181 
       
   182 typedef union SDL_HapticEffect {
   421 typedef union SDL_HapticEffect {
   183    /* Common for all force feedback effects */
   422    /* Common for all force feedback effects */
   184    Uint16 type; /* Effect type */
   423    Uint16 type; /**< Effect type */
   185    SDL_HapticConstant constant; /* Constant effect */
   424    SDL_HapticConstant constant; /**< Constant effect */
   186    SDL_HapticPeriodic periodic; /* Periodic effect */
   425    SDL_HapticPeriodic periodic; /**< Periodic effect */
   187    SDL_HapticCondition condition; /* Condition effect */
   426    SDL_HapticCondition condition; /**< Condition effect */
   188    SDL_HapticRamp ramp; /* Ramp effect */
   427    SDL_HapticRamp ramp; /**< Ramp effect */
   189 } SDL_HapticEffect;
   428 } SDL_HapticEffect;
   190 
   429 
   191 
   430 
   192 /* Function prototypes */
   431 /* Function prototypes */
   193 /*
   432 /*
   194  * Count the number of joysticks attached to the system
   433  * \fn int SDL_NumHaptics(void)
       
   434  *
       
   435  * \brief Count the number of joysticks attached to the system.
       
   436  *
       
   437  *    \return Number of haptic devices detected on the system.
   195  */
   438  */
   196 extern DECLSPEC int SDLCALL SDL_NumHaptics(void);
   439 extern DECLSPEC int SDLCALL SDL_NumHaptics(void);
   197 
   440 
   198 /*
   441 /*
   199  * Get the implementation dependent name of a Haptic device.
   442  * \fn const char * SDL_HapticName(int device_index)
       
   443  *
       
   444  * \brief Get the implementation dependent name of a Haptic device.
   200  * This can be called before any joysticks are opened.
   445  * This can be called before any joysticks are opened.
   201  * If no name can be found, this function returns NULL.
   446  * If no name can be found, this function returns NULL.
       
   447  *
       
   448  *    \param device_index Index of the device to get it's name.
       
   449  *    \return Name of the device or NULL on error.
       
   450  *
       
   451  * \sa SDL_NumHaptics
   202  */
   452  */
   203 extern DECLSPEC const char *SDLCALL SDL_HapticName(int device_index);
   453 extern DECLSPEC const char *SDLCALL SDL_HapticName(int device_index);
   204 
   454 
   205 /*
   455 /*
   206  * Opens a Haptic device for usage - the index passed as an
   456  * \fn SDL_Haptic * SDL_HapticOpen(int device_Index)
       
   457  *
       
   458  * \brief Opens a Haptic device for usage - the index passed as an
   207  * argument refers to the N'th Haptic device on this system.
   459  * argument refers to the N'th Haptic device on this system.
   208  *
   460  *
   209  * This function returns a Haptic device identifier, or Null
   461  * This function returns a Haptic device identifier, or Null
   210  * if an error occurred.
   462  * if an error occurred.
       
   463  *
       
   464  *    \param device_index Index of the device to open.
       
   465  *    \return Device identifier or NULL on error.
       
   466  *
       
   467  * \sa SDL_HapticOpenFromJoystick
       
   468  * \sa SDL_HapticClose
   211  */
   469  */
   212 extern DECLSPEC SDL_Haptic * SDL_HapticOpen(int device_index);
   470 extern DECLSPEC SDL_Haptic * SDL_HapticOpen(int device_index);
   213 
   471 
   214 /*
   472 /*
   215  * Checks to see if a joystick has haptic features.
   473  * \fn int SDL_JoystickIsHaptic(SDL_Joystick * joysticke)
   216  *
   474  *
   217  * Returns SDL_TRUE if the joystick is haptic, SDL_FALSE if it isn't
   475  * \brief Checks to see if a joystick has haptic features.
   218  * and -1 on error.
   476  *
       
   477  *    \param joystick Joystick to test for haptic capabilities.
       
   478  *    \return SDL_TRUE if the joystick is haptic, SDL_FALSE if it isn't
       
   479  *            or -1 if an error ocurred.
       
   480  *
       
   481  * \sa SDL_HapticOpenFromJoystick
   219  */
   482  */
   220 extern DECLSPEC int SDL_JoystickIsHaptic(SDL_Joystick * joystick);
   483 extern DECLSPEC int SDL_JoystickIsHaptic(SDL_Joystick * joystick);
   221 
   484 
   222 /*
   485 /*
   223  * Opens a Haptic device for usage from a Joystick device.
   486  * \fn SDL_Haptic * SDL_HapticOpenFromJoystick(SDL_Joystick * joystick)
   224  *
   487  *
   225  * Returns a valid pointer to a haptic device on success or NULL
   488  * \brief Opens a Haptic device for usage from a Joystick device.  Still has
   226  * if an error occurred.
   489  * to be closed seperately to the joystick.
       
   490  *
       
   491  *    \param joystick Joystick to create a haptic device from.
       
   492  *    \return A valid haptic device identifier on success or NULL on error.
       
   493  *
       
   494  * \sa SDL_HapticOpen
       
   495  * \sa SDL_HapticClose
   227  */
   496  */
   228 extern DECLSPEC SDL_Haptic * SDL_HapticOpenFromJoystick(SDL_Joystick * joystick);
   497 extern DECLSPEC SDL_Haptic * SDL_HapticOpenFromJoystick(SDL_Joystick * joystick);
   229 
   498 
   230 /* 
   499 /* 
   231  * Closes a Haptic device previously opened with SDL_HapticOpen.
   500  * \fn void SDL_HapticClose(SDL_Haptic * haptic)
       
   501  *
       
   502  * \brief Closes a Haptic device previously opened with SDL_HapticOpen.
       
   503  *
       
   504  *    \param haptic Haptic device to close.
   232  */
   505  */
   233 extern DECLSPEC void SDL_HapticClose(SDL_Haptic * haptic);
   506 extern DECLSPEC void SDL_HapticClose(SDL_Haptic * haptic);
   234 
   507 
   235 /*
   508 /*
   236  * Returns the number of effects a haptic device can store.
   509  * \fn int SDL_HapticNumEffects(SDL_Haptic * haptic)
       
   510  *
       
   511  * \brief Returns the number of effects a haptic device can store.
       
   512  *
       
   513  *    \param haptic The haptic device to query effect max.
       
   514  *    \return The number of effects the haptic device can store or
       
   515  *            -1 on error.
       
   516  *
       
   517  * \sa SDL_HapticQuery
   237  */
   518  */
   238 extern DECLSPEC int SDL_HapticNumEffects(SDL_Haptic * haptic);
   519 extern DECLSPEC int SDL_HapticNumEffects(SDL_Haptic * haptic);
   239 
   520 
   240 /*
   521 /*
   241  * Returns the supported effects.  Individual effects can be queried by
   522  * \fn unsigned int SDL_HapticQueryEffects(SDL_Haptic * haptic)
   242  * bitwise operators.
   523  *
   243  *
   524  * \brief Gets the haptic devices supported features in bitwise matter.
   244  * Example:  (SDL_HapticQueryEffects(haptic) & SDL_HAPTIC_CONSTANT)
   525  *
   245  */
   526  * Example: 
   246 extern DECLSPEC unsigned int SDL_HapticQueryEffects(SDL_Haptic * haptic);
   527  * \code
   247 
   528  * if (SDL_HapticQueryEffects(haptic) & SDL_HAPTIC_CONSTANT) {
   248 /*
   529  *    printf("We have constant haptic effect!");
   249  * Checks to see if effect is supported by haptic.
   530  * }
   250  *
   531  * \endcode
   251  * Returns SDL_TRUE if effect is supported, SDL_FALSE if it isn't and -1
   532  *    
   252  * on error.
   533  *
       
   534  *    \param haptic The haptic device to query.
       
   535  *    \return Haptic features in bitwise manner (OR'd).
       
   536  *
       
   537  * \sa SDL_HapticNumEffects
       
   538  * \sa SDL_HapticEffectSupported
       
   539  */
       
   540 extern DECLSPEC unsigned int SDL_HapticQuery(SDL_Haptic * haptic);
       
   541 
       
   542 /*
       
   543  * \fn int SDL_HapticEffectSupported
       
   544  *
       
   545  * \brief Checks to see if effect is supported by haptic.
       
   546  *
       
   547  *    \param haptic Haptic device to check on.
       
   548  *    \param effect Effect to check to see if it is supported.
       
   549  *    \return SDL_TRUE if effect is supported, SDL_FALSE if it isn't or 
       
   550  *            -1 on error.
       
   551  * 
       
   552  * \sa SDL_HapticQuery
       
   553  * \sa SDL_HapticNewEffect
   253  */
   554  */
   254 extern DECLSPEC int SDL_HapticEffectSupported(SDL_Haptic * haptic, SDL_HapticEffect * effect);
   555 extern DECLSPEC int SDL_HapticEffectSupported(SDL_Haptic * haptic, SDL_HapticEffect * effect);
   255 
   556 
   256 /*
   557 /*
   257  * Creates a new haptic effect on the device.
   558  * \fn int SDL_HapticNewEffect(SDL_Haptic * haptic, SDL_HapticEffect * effect)
   258  *
   559  *
   259  * Returns the id of the effect on success, -1 on failure.
   560  * \brief Creates a new haptic effect on the device.
       
   561  *
       
   562  *    \param haptic Haptic device to create the effect on.
       
   563  *    \param effect Properties of the effect to create.
       
   564  *    \return The id of the effect on success or -1 on error.
       
   565  *
       
   566  * \sa SDL_HapticUpdateEffect
       
   567  * \sa SDL_HapticRunEffect
       
   568  * \sa SDL_HapticDestroyEffect
   260  */
   569  */
   261 extern DECLSPEC int SDL_HapticNewEffect(SDL_Haptic * haptic, SDL_HapticEffect * effect);
   570 extern DECLSPEC int SDL_HapticNewEffect(SDL_Haptic * haptic, SDL_HapticEffect * effect);
   262 
   571 
   263 /*
   572 /*
   264  * Uploads an effect.  Can be used dynamically, although behaviour when
   573  * \fn int SDL_HapticUpdateEffect(SDL_Haptic * haptic, int effect, SDL_HapticEffect * data)
       
   574  *
       
   575  * \brief Updates an effect.  Can be used dynamically, although behaviour when
   265  * dynamically changing direction may be strange.  Specifically the effect
   576  * dynamically changing direction may be strange.  Specifically the effect
   266  * may reupload itself and start playing from the start.  You cannot change
   577  * may reupload itself and start playing from the start.  You cannot change
   267  * the type either when running UpdateEffect.
   578  * the type either when running UpdateEffect.
   268  *
   579  *
   269  * Returns the id of the effect on success, -1 on failure.
   580  *    \param haptic Haptic device that has the effect.
       
   581  *    \param effect Effect to update.
       
   582  *    \param data New effect properties to use.
       
   583  *    \return The id of the effect on success or -1 on error.
       
   584  *
       
   585  * \sa SDL_HapticNewEffect
       
   586  * \sa SDL_HapticRunEffect
       
   587  * \sa SDL_HapticDestroyEffect
   270  */
   588  */
   271 extern DECLSPEC int SDL_HapticUpdateEffect(SDL_Haptic * haptic, int effect, SDL_HapticEffect * data);
   589 extern DECLSPEC int SDL_HapticUpdateEffect(SDL_Haptic * haptic, int effect, SDL_HapticEffect * data);
   272 
   590 
   273 /*
   591 /*
   274  * Runs the haptic effect on it's assosciated haptic device.
   592  * \fn int SDL_HapticRunEffects(SDL_Haptic * haptic, int effect)
   275  *
   593  *
   276  * Returns 0 on success or -1 on failure.
   594  * \brief Runs the haptic effect on it's assosciated haptic device.
       
   595  *
       
   596  *    \param haptic Haptic device to run the effect on.
       
   597  *    \param effect Identifier of the haptic effect to run.
       
   598  *    \return 0 on success or -1 on error.
       
   599  *
       
   600  * \sa SDL_HapticStopEffect
       
   601  * \sa SDL_HapticDestroyEffect
       
   602  * \sa SDL_HapticGetEffectStatus
   277  */
   603  */
   278 extern DECLSPEC int SDL_HapticRunEffect(SDL_Haptic * haptic, int effect);
   604 extern DECLSPEC int SDL_HapticRunEffect(SDL_Haptic * haptic, int effect);
   279 
   605 
   280 /*
   606 /*
   281  * Stops the haptic effect on it's assosciated haptic device.
   607  * \fn int SDL_HapticStopEffect(SDL_Haptic * haptic, int effect)
   282  *
   608  *
   283  * Returns 0 on success or -1 on failure.
   609  * \brief Stops the haptic effect on it's assosciated haptic device.
       
   610  *
       
   611  *    \param haptic Haptic device to stop the effect on.
       
   612  *    \praam effect Identifier of the effect to stop.
       
   613  *    \return 0 on success or -1 on error.
       
   614  *
       
   615  * \sa SDL_HapticRunEffect
       
   616  * \sa SDL_HapticDestroyEffect
   284  */
   617  */
   285 extern DECLSPEC int SDL_HapticStopEffect(SDL_Haptic * haptic, int effect);
   618 extern DECLSPEC int SDL_HapticStopEffect(SDL_Haptic * haptic, int effect);
   286 
   619 
   287 /*
   620 /*
   288  * Destroys a haptic effect on the device.  This will stop the effect if it's
   621  * \fn void SDL_HapticDestroyEffect(SDL_Haptic * haptic, int effect)
   289  * running.
   622  *
       
   623  * \brief Destroys a haptic effect on the device.  This will stop the effect
       
   624  * if it's running.  Effects are automatically destroyed when the device is
       
   625  * closed.
       
   626  *
       
   627  *    \param haptic Device to destroy the effect on.
       
   628  *    \param effect Identifier of the effect to destroy.
       
   629  * 
       
   630  * \sa SDL_HapticNewEffect
   290  */
   631  */
   291 extern DECLSPEC void SDL_HapticDestroyEffect(SDL_Haptic * haptic, int effect);
   632 extern DECLSPEC void SDL_HapticDestroyEffect(SDL_Haptic * haptic, int effect);
   292 
   633 
   293 /*
   634 /*
   294  * Gets the status of the current effect on the haptic device.
   635  * \fn int SDL_HapticGetEffectStatus(SDL_Haptic *haptic, int effect)
   295  *
   636  *
   296  * Returns 0 if it isn't playing, SDL_HAPTIC_PLAYING if it is playing
   637  * \brief Gets the status of the current effect on the haptic device.
   297  * or -1 on failure.
   638  *
       
   639  * Device must support the SDL_HAPTIC_STATUS feature.
       
   640  *
       
   641  *    \param haptic Haptic device to query the effect status on.
       
   642  *    \param effect Identifier of the effect to query it's status.
       
   643  *    \return 0 if it isn't playing, SDL_HAPTIC_PLAYING if it is playing
       
   644  *            or -1 on error.
       
   645  *
       
   646  * \sa SDL_HapticRunEffect
       
   647  * \sa SDL_HapticStopEffect
   298  */
   648  */
   299 extern DECLSPEC int SDL_HapticGetEffectStatus(SDL_Haptic *haptic, int effect);
   649 extern DECLSPEC int SDL_HapticGetEffectStatus(SDL_Haptic *haptic, int effect);
   300 
   650 
   301 /*
   651 /*
   302  * Sets the global gain of the device.  Gain should be between 0 and 100.
   652  * \fn int SDL_HapticSetGain(SDL_Haptic * haptic, int gain)
   303  *
   653  *
   304  * Returns 0 on success or -1 on failure.
   654  * \brief Sets the global gain of the device.  Gain should be between 0 and 100.
       
   655  *
       
   656  * Device must support the SDL_HAPTIC_GAIN feature.
       
   657  *
       
   658  *    \param haptic Haptic device to set the gain on.
       
   659  *    \param gain Value to set the gain to, should be between 0 and 100.
       
   660  *    \return 0 on success or -1 on error.
       
   661  *
       
   662  * \sa SDL_HapticQuery
   305  */
   663  */
   306 extern DECLSPEC int SDL_HapticSetGain(SDL_Haptic * haptic, int gain);
   664 extern DECLSPEC int SDL_HapticSetGain(SDL_Haptic * haptic, int gain);
   307 
   665 
   308 /*
   666 /*
   309  * Sets the global autocenter of the device.  Autocenter should be between
   667  * \fn int SDL_HapticSetAutocenter(SDL_Haptic * haptic, int autocenter)
       
   668  *
       
   669  * \brief Sets the global autocenter of the device.  Autocenter should be between
   310  * 0 and 100.  Setting it to 0 will disable autocentering.
   670  * 0 and 100.  Setting it to 0 will disable autocentering.
   311  *
   671  *
   312  * Returns 0 on success or -1 on failure.
   672  * Device must support the SDL_HAPTIC_AUTOCENTER feature.
       
   673  *
       
   674  *    \param haptic Haptic device to set autocentering on.
       
   675  *    \param autocenter Value to set autocenter to, 0 disables autocentering.
       
   676  *    \return 0 on success or -1 on error.
       
   677  *
       
   678  * \sa SDL_HapticQuery
   313  */
   679  */
   314 extern DECLSPEC int SDL_HapticSetAutocenter(SDL_Haptic * haptic, int autocenter);
   680 extern DECLSPEC int SDL_HapticSetAutocenter(SDL_Haptic * haptic, int autocenter);
   315 
   681 
   316 
   682 
   317 /* Ends C function definitions when using C++ */
   683 /* Ends C function definitions when using C++ */