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