include/SDL_haptic.h
author Edgar Simo <bobbens@gmail.com>
Mon, 07 Jul 2008 16:58:16 +0000
branchgsoc2008_force_feedback
changeset 2502 5356ca0c36a3
parent 2501 ff12f79dfc8d
child 2504 e68c99a19a2f
permissions -rw-r--r--
Fixed linux directions being inverted.
     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 /**
    24  * \file SDL_haptic.h
    25  *
    26  * \brief The SDL Haptic subsystem allows you to control haptic (force feedback)
    27  *  devices.
    28  *
    29  * The basic usage is as follows:
    30  *   - Initialize the Subsystem (SDL_INIT_HAPTIC).
    31  *   - Open a Haptic Device.
    32  *     - SDL_HapticOpen(...) to open from index.
    33  *     - SDL_HapticOpenFromJoystick(...) to open from an existing joystick.
    34  *   - Create an effect (SDL_HapticEffect).
    35  *   - Upload the effect with SDL_HapticNewEffect(...).
    36  *   - Run the effect with SDL_HapticRunEffect(...).
    37  *   - (optional) Free the effect with SDL_HapticDestroyEffect(...).
    38  *   - Close the haptic device with SDL_HapticClose(...).
    39  *
    40  *
    41  * Example:
    42  *
    43  * \code
    44  * int test_haptic( SDL_Joystick * joystick ) {
    45  *    SDL_Haptic *haptic;
    46  *    SDL_HapticEffect effect;
    47  *    int effect_id;
    48  *
    49  *    // Open the device
    50  *    haptic = SDL_HapticOpenFromJoystick( joystick );
    51  *    if (haptic == NULL) return -1; // Most likely joystick isn't haptic
    52  *
    53  *    // See if it can do sine waves
    54  *    if ((SDL_HapticQueryEffects(haptic) & SDL_HAPTIC_SINE)==0) {
    55  *       SDL_HapticClose(haptic); // No sine effect
    56  *       return -1;
    57  *    }
    58  *
    59  *    // Create the effect
    60  *    memset( &effect, 0, sizeof(SDL_HapticEffect) ); // 0 is safe default
    61  *    effect.type = SDL_HAPTIC_SINE;
    62  *    effect.periodic.direction.type = SDL_HAPTIC_POLAR; // Polar coordinates
    63  *    effect.periodic.direction.dir[0] = 18000; // Force comes from south
    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  * Direction encodings
   248  */
   249 /**
   250  * \def SDL_HAPTIC_POLAR
   251  *
   252  * \brief Uses polar coordinates for the direction.
   253  *
   254  * \sa SDL_HapticDirection
   255  */
   256 #define SDL_HAPTIC_POLAR      0
   257 /**
   258  * \def SDL_HAPTIC_CARTESIAN
   259  *
   260  * \brief Uses cartesian coordinates for the direction.
   261  *
   262  * \sa SDL_HapticDirection
   263  */
   264 #define SDL_HAPTIC_CARTESIAN  1
   265 
   266 
   267 /**
   268  * \struct SDL_HapticDirection
   269  *
   270  * \brief Structure that represents a haptic direction.
   271  *
   272  * Directions can be specified by:
   273  *   - SDL_HAPTIC_POLAR: Specified by polar coordinates.
   274  *   - SDL_HAPTIC_CARTESIAN: Specified by cartesian coordinates.
   275  *
   276  * Cardinal directions of the haptic device are relative to the positioning
   277  *  of the device.  North is considered to be away from the user.
   278  *
   279  * The following diagram represents the cardinal directions:
   280  * \code
   281  *            .--.
   282  *            |__| .-------.
   283  *            |=.| |.-----.|
   284  *            |--| ||     ||
   285  *            |  | |'-----'|
   286  *            |__|~')_____('
   287  *              [ COMPUTER ]
   288  *
   289  *
   290  *                  North (-1)
   291  *                    ^
   292  *                    |
   293  *                    |
   294  * (1)  West <----[ HAPTIC ]----> East (-1)
   295  *                    |
   296  *                    |
   297  *                    v
   298  *                  South (1)
   299  *
   300  *
   301  *                 [ USER ]
   302  *                   \|||/
   303  *                   (o o)
   304  *             ---ooO-(_)-Ooo---
   305  * \endcode
   306  *
   307  * If type is SDL_HAPTIC_POLAR, direction is encoded by hundredths of a 
   308  *  degree starting north and turning clockwise.  The cardinal directions would be:
   309  *   - North: 0 (0 degrees)
   310  *   - West: 9000 (90 degrees)
   311  *   - South: 18000 (180 degrees)
   312  *   - East: 27000 (270 degrees)
   313  *
   314  * If type is SDL_HAPTIC_CARTESIAN, direction is encoded by position.
   315  *  The cardinal directions would be:
   316  *   - North:  0,-1
   317  *   - West:  -1, 0
   318  *   - South:  0, 1
   319  *   - East:   1, 0
   320  *
   321  *
   322  * Example:
   323  * \code
   324  * SDL_HapticDirection direction;
   325  *
   326  * direction.type = SDL_HAPTIC_POLAR; // We'll be using polar direction encoding.
   327  * direction.dir = 180000; // Force comes from the south meaning the user will
   328  *                         // have to pull the stick to counteract.
   329  * \endcode
   330  *
   331  * \sa SDL_HAPTIC_POLAR
   332  * \sa SDL_HAPTIC_CARTESIAN
   333  * \sa SDL_HapticEffect
   334  */
   335 typedef struct SDL_HapticDirection {
   336    Uint8 type; /**< The type of encoding. */
   337    Uint16 dir[2]; /**< The encoded direction. */
   338 } SDL_HapticDirection;
   339 
   340 
   341 /**
   342  * \struct SDL_HapticConstant
   343  *
   344  * \brief A structure containing a template for a Constant effect.
   345  *
   346  * The struct is exclusive to the SDL_HAPTIC_CONSTANT effect.
   347  *
   348  * \sa SDL_HAPTIC_CONSTANT
   349  * \sa SDL_HapticEffect
   350  */
   351 typedef struct SDL_HapticConstant {
   352    /* Header */
   353    Uint16 type; /**< SDL_HAPTIC_CONSTANT */
   354    SDL_HapticDirection direction; /**< Direction of the effect. */
   355 
   356    /* Replay */
   357    Uint16 length; /**< Duration of the effect. */
   358    Uint16 delay; /**< Delay before starting the effect. */
   359 
   360    /* Trigger */
   361    Uint16 button; /**< Button that triggers the effect. */
   362    Uint16 interval; /**< How soon it can be triggered again after button. */
   363 
   364    /* Constant */
   365    Sint16 level; /**< Strength of the constant effect. */
   366 
   367    /* Envelope */
   368    Uint16 attack_length; /**< Duration of the attack. */
   369    Uint16 attack_level; /**< Level at the start of the attack. */
   370    Uint16 fade_length; /**< Duration of the fade. */
   371    Uint16 fade_level; /**< Level at the end of the fade. */
   372 } SDL_HapticConstant;
   373 /**
   374  * \struct SDL_HapticPeriodic
   375  *
   376  * \brief A structure containing a template for a Periodic effect.
   377  *
   378  * The struct handles the following effects:
   379  *   - SDL_HAPTIC_SINE
   380  *   - SDL_HAPTIC_SQUARE
   381  *   - SDL_HAPTIC_TRIANGLE
   382  *   - SDL_HAPTIC_SAWTOOTHUP
   383  *   - SDL_HAPTIC_SAWTOOTHDOWN
   384  *
   385  * Examples:
   386  * \code
   387  * SDL_HAPTIC_SINE
   388  *   __      __      __      __
   389  *  /  \    /  \    /  \    /
   390  * /    \__/    \__/    \__/
   391  *
   392  * SDL_HAPTIC_SQUARE
   393  *  __    __    __    __    __
   394  * |  |  |  |  |  |  |  |  |  |
   395  * |  |__|  |__|  |__|  |__|  |
   396  *
   397  * SDL_HAPTIC_TRIANGLE
   398  *   /\    /\    /\    /\    /\
   399  *  /  \  /  \  /  \  /  \  /
   400  * /    \/    \/    \/    \/
   401  *
   402  * SDL_HAPTIC_SAWTOOTHUP
   403  *    __    __    __    __    _
   404  *   /  |  /  |  /  |  /  |  /
   405  *  /   | /   | /   | /   | /
   406  * /    |/    |/    |/    |/
   407  *
   408  * SDL_HAPTIC_SAWTOOTHDOWN
   409  * __    __    __    __    __
   410  *   \  |  \  |  \  |  \  |  \
   411  *    \ |   \ |   \ |   \ |   \
   412  *     \|    \|    \|    \|
   413  * \endcode
   414  *
   415  * \sa SDL_HAPTIC_SINE
   416  * \sa SDL_HAPTIC_SQUARE
   417  * \sa SDL_HAPTIC_TRIANGLE
   418  * \sa SDL_HAPTIC_SAWTOOTHUP
   419  * \sa SDL_HAPTIC SAWTOOTHDOWN
   420  * \sa SDL_HapticEffect
   421  */
   422 typedef struct SDL_HapticPeriodic {
   423    /* Header */
   424    Uint16 type; /**< SDL_HAPTIC_{SINE,SQUARE,TRIANGLE,SAWTOOTHUP,SAWTOOTHDOWN} */
   425    SDL_HapticDirection direction; /**< Direction of the effect. */
   426 
   427    /* Replay */
   428    Uint16 length; /**< Duration of the effect. */
   429    Uint16 delay; /**< Delay before starting the effect. */
   430 
   431    /* Trigger */
   432    Uint16 button; /**< Button that triggers the effect. */
   433    Uint16 interval; /**< How soon it can be triggered again after button. */
   434 
   435    /* Periodic */
   436    Uint16 period; /**< Period of the wave. */
   437    Sint16 magnitude; /**< Peak value. */
   438    Sint16 offset; /**< Mean value of the wave. */
   439    Uint16 phase; /**< Horizontal shift. */
   440 
   441    /* Envelope */
   442    Uint16 attack_length; /**< Duration of the attack. */
   443    Uint16 attack_level; /**< Level at the start of the attack. */
   444    Uint16 fade_length; /**< Duration of the fade. */
   445    Uint16 fade_level; /**< Level at the end of the fade. */
   446 } SDL_HapticPeriodic;
   447 /**
   448  * \struct SDL_HapticCondition
   449  *
   450  * \brief A structure containing a template for a Condition effect.
   451  *
   452  * Direction is handled by condition internals instead of a direction member.
   453  *  Each of right_sat, lefT-sat, right_coeff, left_coeff, deadband and center
   454  *  have two parameters, first is for x value, second is for y value following
   455  *  the scheme set by SDL_HapticDirection.
   456  *
   457  * The struct handles the following effects:
   458  *   - SDL_HAPTIC_SPRING: Effect based on axes position.
   459  *   - SDL_HAPTIC_DAMPER: Effect based on axes velocity.
   460  *   - SDL_HAPTIC_INERTIA: Effect based on axes acceleration.
   461  *   - SDL_HAPTIC_FRICTION: Effect based on axes movement.
   462  *
   463  * \sa SDL_HapticDirection
   464  * \sa SDL_HAPTIC_SPRING
   465  * \sa SDL_HAPTIC_DAMPER
   466  * \sa SDL_HAPTIC_INERTIA
   467  * \sa SDL_HAPTIC_FRICTION
   468  * \sa SDL_HapticEffect
   469  */
   470 typedef struct SDL_HapticCondition {
   471    /* Header */
   472    Uint16 type; /**< SDL_HAPTIC_{SPRING,DAMPER,INERTIA,FRICTION} */
   473 
   474    /* Replay */
   475    Uint16 length; /**< Duration of the effect. */
   476    Uint16 delay; /**< Delay before starting the effect. */
   477 
   478    /* Trigger */
   479    Uint16 button; /**< Button that triggers the effect. */
   480    Uint16 interval; /**< How soon it can be triggered again after button. */
   481 
   482    /* Condition */
   483    Uint16 right_sat[2]; /**< Level when joystick is to the right. */
   484    Uint16 left_sat[2]; /**< Level when joystick is to the left. */
   485    Sint16 right_coeff[2]; /**< How fast to increase the force towards the right. */
   486    Sint16 left_coeff[2]; /**< How fast to increase the force towards the left. */
   487    Uint16 deadband[2]; /**< Size of the dead zone. */
   488    Sint16 center[2]; /**< Position of the dead zone. */
   489 } SDL_HapticCondition;
   490 /**
   491  * \struct SDL_HapticRamp
   492  *
   493  * \brief A structure containing a template for a Ramp effect.
   494  *
   495  * This struct is exclusively for the SDL_HAPTIC_RAMP effect.
   496  *
   497  * \sa SDL_HAPTIC_RAMP
   498  * \sa SDL_HapticEffect
   499  */
   500 typedef struct SDL_HapticRamp {
   501    /* Header */
   502    Uint16 type; /**< SDL_HAPTIC_RAMP */
   503    SDL_HapticDirection direction; /**< Direction of the effect. */
   504 
   505    /* Replay */
   506    Uint16 length; /**< Duration of the effect. */
   507    Uint16 delay; /**< Delay before starting the effect. */
   508 
   509    /* Trigger */
   510    Uint16 button; /**< Button that triggers the effect. */
   511    Uint16 interval; /**< How soon it can be triggered again after button. */
   512 
   513    /* Ramp */
   514    Sint16 start; /**< Beginning strength level. */
   515    Sint16 end; /**< Ending strength level. */
   516 
   517    /* Envelope */
   518    Uint16 attack_length; /**< Duration of the attack. */
   519    Uint16 attack_level; /**< Level at the start of the attack. */
   520    Uint16 fade_length; /**< Duration of the fade. */
   521    Uint16 fade_level; /**< Level at the end of the fade. */
   522 } SDL_HapticRamp;
   523 /**
   524  * \union SDL_HapticEffect
   525  *
   526  * \brief The generic template for any haptic effect.
   527  *
   528  * All values max at 32767 (0x7FFF).  Signed values also can be negative.
   529  * Time values unless specified otherwise are in milliseconds.
   530  *
   531  * Common parts:
   532  * \code
   533  * // Replay - All effects have this
   534  * Uint16 length;        // Duration of effect (ms).
   535  * Uint16 delay;         // Delay before starting effect.
   536  *
   537  * // Trigger - All effects have this
   538  * Uint16 button;        // Button that triggers effect.
   539  * Uint16 interval;      // How soon before effect can be triggered again.
   540  *
   541  * // Envelope - Not all effects have this
   542  * Uint16 attack_length; // Duration of the attack (ms).
   543  * Uint16 attack_level;  // Level at the start of the attack.
   544  * Uint16 fade_length;   // Duration of the fade out (ms).
   545  * Uint16 fade_level;    // Level at the end of the fade.
   546  * \endcode
   547  *
   548  *
   549  * Here we have an example of an effect evolution in time:
   550  *
   551  * \code
   552  * Strength
   553  * ^
   554  * |
   555  * | effect strength -->  _________________
   556  * |                     /                 \
   557  * |                    /                   \
   558  * |                   /                     \
   559  * |                  /                       \ 
   560  * | attack_level --> |                        \
   561  * |                  |                        |  <---  fade_level
   562  * |
   563  * +--------------------------------------------------> Time
   564  *                    [--]                 [---]
   565  *                    attack_length        fade_length
   566  * 
   567  * [------------------][-----------------------]
   568  * delay               length
   569  * \endcode
   570  *
   571  * \sa SDL_HapticConstant
   572  * \sa SDL_HapticPeriodic
   573  * \sa SDL_HapticCondition
   574  * \sa SDL_HapticRamp
   575  */
   576 typedef union SDL_HapticEffect {
   577    /* Common for all force feedback effects */
   578    Uint16 type; /**< Effect type. */
   579    SDL_HapticConstant constant; /**< Constant effect. */
   580    SDL_HapticPeriodic periodic; /**< Periodic effect. */
   581    SDL_HapticCondition condition; /**< Condition effect. */
   582    SDL_HapticRamp ramp; /**< Ramp effect. */
   583 } SDL_HapticEffect;
   584 
   585 
   586 /* Function prototypes */
   587 /**
   588  * \fn int SDL_NumHaptics(void)
   589  *
   590  * \brief Count the number of joysticks attached to the system.
   591  *
   592  *    \return Number of haptic devices detected on the system.
   593  */
   594 extern DECLSPEC int SDLCALL SDL_NumHaptics(void);
   595 
   596 /**
   597  * \fn const char * SDL_HapticName(int device_index)
   598  *
   599  * \brief Get the implementation dependent name of a Haptic device.
   600  * This can be called before any joysticks are opened.
   601  * If no name can be found, this function returns NULL.
   602  *
   603  *    \param device_index Index of the device to get it's name.
   604  *    \return Name of the device or NULL on error.
   605  *
   606  * \sa SDL_NumHaptics
   607  */
   608 extern DECLSPEC const char *SDLCALL SDL_HapticName(int device_index);
   609 
   610 /**
   611  * \fn SDL_Haptic * SDL_HapticOpen(int device_index)
   612  *
   613  * \brief Opens a Haptic device for usage - the index passed as an
   614  * argument refers to the N'th Haptic device on this system.
   615  *
   616  * This function returns a Haptic device identifier, or Null
   617  * if an error occurred.
   618  *
   619  *    \param device_index Index of the device to open.
   620  *    \return Device identifier or NULL on error.
   621  *
   622  * \sa SDL_HapticOpenFromJoystick
   623  * \sa SDL_HapticClose
   624  */
   625 extern DECLSPEC SDL_Haptic * SDL_HapticOpen(int device_index);
   626 
   627 /**
   628  * \fn int SDL_JoystickIsHaptic(SDL_Joystick * joystick)
   629  *
   630  * \brief Checks to see if a joystick has haptic features.
   631  *
   632  *    \param joystick Joystick to test for haptic capabilities.
   633  *    \return SDL_TRUE if the joystick is haptic, SDL_FALSE if it isn't
   634  *            or -1 if an error ocurred.
   635  *
   636  * \sa SDL_HapticOpenFromJoystick
   637  */
   638 extern DECLSPEC int SDL_JoystickIsHaptic(SDL_Joystick * joystick);
   639 
   640 /**
   641  * \fn SDL_Haptic * SDL_HapticOpenFromJoystick(SDL_Joystick * joystick)
   642  *
   643  * \brief Opens a Haptic device for usage from a Joystick device.  Still has
   644  * to be closed seperately to the joystick.
   645  *
   646  *    \param joystick Joystick to create a haptic device from.
   647  *    \return A valid haptic device identifier on success or NULL on error.
   648  *
   649  * \sa SDL_HapticOpen
   650  * \sa SDL_HapticClose
   651  */
   652 extern DECLSPEC SDL_Haptic * SDL_HapticOpenFromJoystick(SDL_Joystick * joystick);
   653 
   654 /**
   655  * \fn void SDL_HapticClose(SDL_Haptic * haptic)
   656  *
   657  * \brief Closes a Haptic device previously opened with SDL_HapticOpen.
   658  *
   659  *    \param haptic Haptic device to close.
   660  */
   661 extern DECLSPEC void SDL_HapticClose(SDL_Haptic * haptic);
   662 
   663 /**
   664  * \fn int SDL_HapticNumEffects(SDL_Haptic * haptic)
   665  *
   666  * \brief Returns the number of effects a haptic device can store.
   667  *
   668  *    \param haptic The haptic device to query effect max.
   669  *    \return The number of effects the haptic device can store or
   670  *            -1 on error.
   671  *
   672  * \sa SDL_HapticQuery
   673  */
   674 extern DECLSPEC int SDL_HapticNumEffects(SDL_Haptic * haptic);
   675 
   676 /**
   677  * \fn unsigned int SDL_HapticQuery(SDL_Haptic * haptic)
   678  *
   679  * \brief Gets the haptic devices supported features in bitwise matter.
   680  *
   681  * Example: 
   682  * \code
   683  * if (SDL_HapticQueryEffects(haptic) & SDL_HAPTIC_CONSTANT) {
   684  *    printf("We have constant haptic effect!");
   685  * }
   686  * \endcode
   687  *    
   688  *
   689  *    \param haptic The haptic device to query.
   690  *    \return Haptic features in bitwise manner (OR'd).
   691  *
   692  * \sa SDL_HapticNumEffects
   693  * \sa SDL_HapticEffectSupported
   694  */
   695 extern DECLSPEC unsigned int SDL_HapticQuery(SDL_Haptic * haptic);
   696 
   697 /**
   698  * \fn int SDL_HapticEffectSupported(SDL_Haptic * haptic, SDL_HapticEffect * effect)
   699  *
   700  * \brief Checks to see if effect is supported by haptic.
   701  *
   702  *    \param haptic Haptic device to check on.
   703  *    \param effect Effect to check to see if it is supported.
   704  *    \return SDL_TRUE if effect is supported, SDL_FALSE if it isn't or 
   705  *            -1 on error.
   706  * 
   707  * \sa SDL_HapticQuery
   708  * \sa SDL_HapticNewEffect
   709  */
   710 extern DECLSPEC int SDL_HapticEffectSupported(SDL_Haptic * haptic, SDL_HapticEffect * effect);
   711 
   712 /**
   713  * \fn int SDL_HapticNewEffect(SDL_Haptic * haptic, SDL_HapticEffect * effect)
   714  *
   715  * \brief Creates a new haptic effect on the device.
   716  *
   717  *    \param haptic Haptic device to create the effect on.
   718  *    \param effect Properties of the effect to create.
   719  *    \return The id of the effect on success or -1 on error.
   720  *
   721  * \sa SDL_HapticUpdateEffect
   722  * \sa SDL_HapticRunEffect
   723  * \sa SDL_HapticDestroyEffect
   724  */
   725 extern DECLSPEC int SDL_HapticNewEffect(SDL_Haptic * haptic, SDL_HapticEffect * effect);
   726 
   727 /**
   728  * \fn int SDL_HapticUpdateEffect(SDL_Haptic * haptic, int effect, SDL_HapticEffect * data)
   729  *
   730  * \brief Updates an effect.  Can be used dynamically, although behaviour when
   731  * dynamically changing direction may be strange.  Specifically the effect
   732  * may reupload itself and start playing from the start.  You cannot change
   733  * the type either when running UpdateEffect.
   734  *
   735  *    \param haptic Haptic device that has the effect.
   736  *    \param effect Effect to update.
   737  *    \param data New effect properties to use.
   738  *    \return The id of the effect on success or -1 on error.
   739  *
   740  * \sa SDL_HapticNewEffect
   741  * \sa SDL_HapticRunEffect
   742  * \sa SDL_HapticDestroyEffect
   743  */
   744 extern DECLSPEC int SDL_HapticUpdateEffect(SDL_Haptic * haptic, int effect, SDL_HapticEffect * data);
   745 
   746 /**
   747  * \fn int SDL_HapticRunEffect(SDL_Haptic * haptic, int effect)
   748  *
   749  * \brief Runs the haptic effect on it's assosciated haptic device.
   750  *
   751  *    \param haptic Haptic device to run the effect on.
   752  *    \param effect Identifier of the haptic effect to run.
   753  *    \return 0 on success or -1 on error.
   754  *
   755  * \sa SDL_HapticStopEffect
   756  * \sa SDL_HapticDestroyEffect
   757  * \sa SDL_HapticGetEffectStatus
   758  */
   759 extern DECLSPEC int SDL_HapticRunEffect(SDL_Haptic * haptic, int effect);
   760 
   761 /**
   762  * \fn int SDL_HapticStopEffect(SDL_Haptic * haptic, int effect)
   763  *
   764  * \brief Stops the haptic effect on it's assosciated haptic device.
   765  *
   766  *    \param haptic Haptic device to stop the effect on.
   767  *    \param effect Identifier of the effect to stop.
   768  *    \return 0 on success or -1 on error.
   769  *
   770  * \sa SDL_HapticRunEffect
   771  * \sa SDL_HapticDestroyEffect
   772  */
   773 extern DECLSPEC int SDL_HapticStopEffect(SDL_Haptic * haptic, int effect);
   774 
   775 /**
   776  * \fn void SDL_HapticDestroyEffect(SDL_Haptic * haptic, int effect)
   777  *
   778  * \brief Destroys a haptic effect on the device.  This will stop the effect
   779  * if it's running.  Effects are automatically destroyed when the device is
   780  * closed.
   781  *
   782  *    \param haptic Device to destroy the effect on.
   783  *    \param effect Identifier of the effect to destroy.
   784  * 
   785  * \sa SDL_HapticNewEffect
   786  */
   787 extern DECLSPEC void SDL_HapticDestroyEffect(SDL_Haptic * haptic, int effect);
   788 
   789 /**
   790  * \fn int SDL_HapticGetEffectStatus(SDL_Haptic *haptic, int effect)
   791  *
   792  * \brief Gets the status of the current effect on the haptic device.
   793  *
   794  * Device must support the SDL_HAPTIC_STATUS feature.
   795  *
   796  *    \param haptic Haptic device to query the effect status on.
   797  *    \param effect Identifier of the effect to query it's status.
   798  *    \return 0 if it isn't playing, SDL_HAPTIC_PLAYING if it is playing
   799  *            or -1 on error.
   800  *
   801  * \sa SDL_HapticRunEffect
   802  * \sa SDL_HapticStopEffect
   803  */
   804 extern DECLSPEC int SDL_HapticGetEffectStatus(SDL_Haptic *haptic, int effect);
   805 
   806 /**
   807  * \fn int SDL_HapticSetGain(SDL_Haptic * haptic, int gain)
   808  *
   809  * \brief Sets the global gain of the device.  Gain should be between 0 and 100.
   810  *
   811  * Device must support the SDL_HAPTIC_GAIN feature.
   812  *
   813  *    \param haptic Haptic device to set the gain on.
   814  *    \param gain Value to set the gain to, should be between 0 and 100.
   815  *    \return 0 on success or -1 on error.
   816  *
   817  * \sa SDL_HapticQuery
   818  */
   819 extern DECLSPEC int SDL_HapticSetGain(SDL_Haptic * haptic, int gain);
   820 
   821 /**
   822  * \fn int SDL_HapticSetAutocenter(SDL_Haptic * haptic, int autocenter)
   823  *
   824  * \brief Sets the global autocenter of the device.  Autocenter should be between
   825  * 0 and 100.  Setting it to 0 will disable autocentering.
   826  *
   827  * Device must support the SDL_HAPTIC_AUTOCENTER feature.
   828  *
   829  *    \param haptic Haptic device to set autocentering on.
   830  *    \param autocenter Value to set autocenter to, 0 disables autocentering.
   831  *    \return 0 on success or -1 on error.
   832  *
   833  * \sa SDL_HapticQuery
   834  */
   835 extern DECLSPEC int SDL_HapticSetAutocenter(SDL_Haptic * haptic, int autocenter);
   836 
   837 
   838 /* Ends C function definitions when using C++ */
   839 #ifdef __cplusplus
   840 /* *INDENT-OFF* */
   841 }
   842 /* *INDENT-ON* */
   843 #endif
   844 #include "close_code.h"
   845 
   846 #endif /* _SDL_haptic_h */
   847 
   848 /* vi: set ts=4 sw=4 expandtab: */
   849 
   850