include/SDL_haptic.h
author Edgar Simo <bobbens@gmail.com>
Sun, 06 Jul 2008 16:53:32 +0000
branchgsoc2008_force_feedback
changeset 2497 0893fbf73b3d
parent 2495 66c02abeef0e
child 2498 ab567bd667bf
permissions -rw-r--r--
Renamed SDL_HapticQueryEffects to SDL_HapticQuery.
Added doxygen to SDL_Haptic.h.
     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  * \mainpage SDL_haptic
    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
    87  */
    88 
    89 #ifndef _SDL_haptic_h
    90 #define _SDL_haptic_h
    91 
    92 #include "SDL_stdinc.h"
    93 #include "SDL_error.h"
    94 #include "SDL_joystick.h"
    95 
    96 #include "begin_code.h"
    97 /* Set up for C function definitions, even when using C++ */
    98 #ifdef __cplusplus
    99 /* *INDENT-OFF* */
   100 extern "C" {
   101    /* *INDENT-ON* */                                                         
   102 #endif /* __cpluspuls */
   103 
   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  */
   113 struct _SDL_Haptic;                                                     
   114 typedef struct _SDL_Haptic SDL_Haptic;
   115 
   116 
   117 /*
   118  * Different haptic features a device can have.
   119  */
   120 /**
   121  * \def SDL_HAPTIC_CONSTANT
   122  *
   123  * \brief Constant haptic effect.
   124  *
   125  * \sa SDL_HapticCondition
   126  */
   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  */
   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  */
   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  */
   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  */
   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  */
   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  */
   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  */
   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  */
   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  */
   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  */
   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  */
   217 #define SDL_HAPTIC_CUSTOM     (1<<11) /* Custom effect is supported */
   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  */
   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  */
   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  */
   242 #define SDL_HAPTIC_STATUS     (1<<14) /* Device can be queried for effect status */
   243 
   244 
   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  *
   397  * All values max at 32767 (0x7fff).  Signed values also can be negative.
   398  * Time values unless specified otherwise are in milliseconds.
   399  *
   400  * Common parts:
   401  * 
   402  * Replay:
   403  *    Uint16 length;    Duration of effect.
   404  *    Uint16 delay;     Delay before starting effect.
   405  *
   406  * Trigger:
   407  *    Uint16 button;    Button that triggers effect.
   408  *    Uint16 interval;  How soon before effect can be triggered again.
   409  *
   410  * Envelope:
   411  *    Uint16 attack_length;   Duration of the attack.
   412  *    Uint16 attack_level;    Level at the start of the attack.
   413  *    Uint16 fade_length;     Duration of the fade out.
   414  *    Uint16 fade_level;      Level at the end of the fade.
   415  *
   416  * \sa SDL_HapticConstant
   417  * \sa SDL_HapticPeriodic
   418  * \sa SDL_HapticCondition
   419  * \sa SDL_HaptiRamp
   420  */
   421 typedef union SDL_HapticEffect {
   422    /* Common for all force feedback effects */
   423    Uint16 type; /**< Effect type */
   424    SDL_HapticConstant constant; /**< Constant effect */
   425    SDL_HapticPeriodic periodic; /**< Periodic effect */
   426    SDL_HapticCondition condition; /**< Condition effect */
   427    SDL_HapticRamp ramp; /**< Ramp effect */
   428 } SDL_HapticEffect;
   429 
   430 
   431 /* Function prototypes */
   432 /*
   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.
   438  */
   439 extern DECLSPEC int SDLCALL SDL_NumHaptics(void);
   440 
   441 /*
   442  * \fn const char * SDL_HapticName(int device_index)
   443  *
   444  * \brief Get the implementation dependent name of a Haptic device.
   445  * This can be called before any joysticks are opened.
   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
   452  */
   453 extern DECLSPEC const char *SDLCALL SDL_HapticName(int device_index);
   454 
   455 /*
   456  * \fn SDL_Haptic * SDL_HapticOpen(int device_Index)
   457  *
   458  * \brief Opens a Haptic device for usage - the index passed as an
   459  * argument refers to the N'th Haptic device on this system.
   460  *
   461  * This function returns a Haptic device identifier, or Null
   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
   469  */
   470 extern DECLSPEC SDL_Haptic * SDL_HapticOpen(int device_index);
   471 
   472 /*
   473  * \fn int SDL_JoystickIsHaptic(SDL_Joystick * joysticke)
   474  *
   475  * \brief Checks to see if a joystick has haptic features.
   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
   482  */
   483 extern DECLSPEC int SDL_JoystickIsHaptic(SDL_Joystick * joystick);
   484 
   485 /*
   486  * \fn SDL_Haptic * SDL_HapticOpenFromJoystick(SDL_Joystick * joystick)
   487  *
   488  * \brief Opens a Haptic device for usage from a Joystick device.  Still has
   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
   496  */
   497 extern DECLSPEC SDL_Haptic * SDL_HapticOpenFromJoystick(SDL_Joystick * joystick);
   498 
   499 /* 
   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.
   505  */
   506 extern DECLSPEC void SDL_HapticClose(SDL_Haptic * haptic);
   507 
   508 /*
   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
   518  */
   519 extern DECLSPEC int SDL_HapticNumEffects(SDL_Haptic * haptic);
   520 
   521 /*
   522  * \fn unsigned int SDL_HapticQueryEffects(SDL_Haptic * haptic)
   523  *
   524  * \brief Gets the haptic devices supported features in bitwise matter.
   525  *
   526  * Example: 
   527  * \code
   528  * if (SDL_HapticQueryEffects(haptic) & SDL_HAPTIC_CONSTANT) {
   529  *    printf("We have constant haptic effect!");
   530  * }
   531  * \endcode
   532  *    
   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
   554  */
   555 extern DECLSPEC int SDL_HapticEffectSupported(SDL_Haptic * haptic, SDL_HapticEffect * effect);
   556 
   557 /*
   558  * \fn int SDL_HapticNewEffect(SDL_Haptic * haptic, SDL_HapticEffect * effect)
   559  *
   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
   569  */
   570 extern DECLSPEC int SDL_HapticNewEffect(SDL_Haptic * haptic, SDL_HapticEffect * effect);
   571 
   572 /*
   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
   576  * dynamically changing direction may be strange.  Specifically the effect
   577  * may reupload itself and start playing from the start.  You cannot change
   578  * the type either when running UpdateEffect.
   579  *
   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
   588  */
   589 extern DECLSPEC int SDL_HapticUpdateEffect(SDL_Haptic * haptic, int effect, SDL_HapticEffect * data);
   590 
   591 /*
   592  * \fn int SDL_HapticRunEffects(SDL_Haptic * haptic, int effect)
   593  *
   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
   603  */
   604 extern DECLSPEC int SDL_HapticRunEffect(SDL_Haptic * haptic, int effect);
   605 
   606 /*
   607  * \fn int SDL_HapticStopEffect(SDL_Haptic * haptic, int effect)
   608  *
   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
   617  */
   618 extern DECLSPEC int SDL_HapticStopEffect(SDL_Haptic * haptic, int effect);
   619 
   620 /*
   621  * \fn void SDL_HapticDestroyEffect(SDL_Haptic * haptic, int effect)
   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
   631  */
   632 extern DECLSPEC void SDL_HapticDestroyEffect(SDL_Haptic * haptic, int effect);
   633 
   634 /*
   635  * \fn int SDL_HapticGetEffectStatus(SDL_Haptic *haptic, int effect)
   636  *
   637  * \brief Gets the status of the current effect on the haptic device.
   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
   648  */
   649 extern DECLSPEC int SDL_HapticGetEffectStatus(SDL_Haptic *haptic, int effect);
   650 
   651 /*
   652  * \fn int SDL_HapticSetGain(SDL_Haptic * haptic, int gain)
   653  *
   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
   663  */
   664 extern DECLSPEC int SDL_HapticSetGain(SDL_Haptic * haptic, int gain);
   665 
   666 /*
   667  * \fn int SDL_HapticSetAutocenter(SDL_Haptic * haptic, int autocenter)
   668  *
   669  * \brief Sets the global autocenter of the device.  Autocenter should be between
   670  * 0 and 100.  Setting it to 0 will disable autocentering.
   671  *
   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
   679  */
   680 extern DECLSPEC int SDL_HapticSetAutocenter(SDL_Haptic * haptic, int autocenter);
   681 
   682 
   683 /* Ends C function definitions when using C++ */
   684 #ifdef __cplusplus
   685 /* *INDENT-OFF* */
   686 }
   687 /* *INDENT-ON* */
   688 #endif
   689 #include "close_code.h"
   690 
   691 #endif /* _SDL_haptic_h */
   692 
   693 /* vi: set ts=4 sw=4 expandtab: */
   694 
   695