include/SDL_haptic.h
author Edgar Simo <bobbens@gmail.com>
Sun, 06 Jul 2008 20:41:00 +0000
branchgsoc2008_force_feedback
changeset 2499 cc2b270608b2
parent 2498 ab567bd667bf
child 2500 5251d0510b7e
permissions -rw-r--r--
Created SDL_HapticDirection.
Fixed all doxygen errors.
Added more diagrams and documentation.
     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] = 180000; // 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)  East <----[ HAPTIC ]----> West (-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  *
   454  * The struct handles the following effects:
   455  *   - SDL_HAPTIC_SPRING: Effect based on axes position.
   456  *   - SDL_HAPTIC_DAMPER: Effect based on axes velocity.
   457  *   - SDL_HAPTIC_INERTIA: Effect based on axes acceleration.
   458  *   - SDL_HAPTIC_FRICTION: Effect based on axes movement.
   459  *
   460  * \sa SDL_HAPTIC_SPRING
   461  * \sa SDL_HAPTIC_DAMPER
   462  * \sa SDL_HAPTIC_INERTIA
   463  * \sa SDL_HAPTIC_FRICTION
   464  * \sa SDL_HapticEffect
   465  */
   466 typedef struct SDL_HapticCondition {
   467    /* Header */
   468    Uint16 type; /**< SDL_HAPTIC_{SPRING,DAMPER,INERTIA,FRICTION} */
   469 
   470    /* Replay */
   471    Uint16 length; /**< Duration of the effect. */
   472    Uint16 delay; /**< Delay before starting the effect. */
   473 
   474    /* Trigger */
   475    Uint16 button; /**< Button that triggers the effect. */
   476    Uint16 interval; /**< How soon it can be triggered again after button. */
   477 
   478    /* Condition */
   479    Uint16 right_sat; /**< Level when joystick is to the right. */
   480    Uint16 left_sat; /**< Level when joystick is to the left. */
   481    Sint16 right_coeff; /**< How fast to increase the force towards the right. */
   482    Sint16 left_coeff; /**< How fast to increase the force towards the left. */
   483    Uint16 deadband; /**< Size of the dead zone. */
   484    Sint16 center; /**< Position of the dead zone. */
   485 } SDL_HapticCondition;
   486 /**
   487  * \struct SDL_HapticRamp
   488  *
   489  * \brief A structure containing a template for a Ramp effect.
   490  *
   491  * This struct is exclusively for the SDL_HAPTIC_RAMP effect.
   492  *
   493  * \sa SDL_HAPTIC_RAMP
   494  * \sa SDL_HapticEffect
   495  */
   496 typedef struct SDL_HapticRamp {
   497    /* Header */
   498    Uint16 type; /**< SDL_HAPTIC_RAMP */
   499    SDL_HapticDirection direction; /**< Direction of the effect. */
   500 
   501    /* Replay */
   502    Uint16 length; /**< Duration of the effect. */
   503    Uint16 delay; /**< Delay before starting the effect. */
   504 
   505    /* Trigger */
   506    Uint16 button; /**< Button that triggers the effect. */
   507    Uint16 interval; /**< How soon it can be triggered again after button. */
   508 
   509    /* Ramp */
   510    Sint16 start; /**< Beginning strength level. */
   511    Sint16 end; /**< Ending strength level. */
   512 
   513    /* Envelope */
   514    Uint16 attack_length; /**< Duration of the attack. */
   515    Uint16 attack_level; /**< Level at the start of the attack. */
   516    Uint16 fade_length; /**< Duration of the fade. */
   517    Uint16 fade_level; /**< Level at the end of the fade. */
   518 } SDL_HapticRamp;
   519 /**
   520  * \union SDL_HapticEffect
   521  *
   522  * \brief The generic template for any haptic effect.
   523  *
   524  * All values max at 32767 (0x7FFF).  Signed values also can be negative.
   525  * Time values unless specified otherwise are in milliseconds.
   526  *
   527  * Common parts:
   528  * \code
   529  * // Replay - All effects have this
   530  * Uint16 length;        // Duration of effect (ms).
   531  * Uint16 delay;         // Delay before starting effect.
   532  *
   533  * // Trigger - All effects have this
   534  * Uint16 button;        // Button that triggers effect.
   535  * Uint16 interval;      // How soon before effect can be triggered again.
   536  *
   537  * // Envelope - Not all effects have this
   538  * Uint16 attack_length; // Duration of the attack (ms).
   539  * Uint16 attack_level;  // Level at the start of the attack.
   540  * Uint16 fade_length;   // Duration of the fade out (ms).
   541  * Uint16 fade_level;    // Level at the end of the fade.
   542  * \endcode
   543  *
   544  *
   545  * Here we have an example of an effect evolution in time:
   546  *
   547  * \code
   548  * Strength
   549  * ^
   550  * |
   551  * | effect strength -->  _________________
   552  * |                     /                 \
   553  * |                    /                   \
   554  * |                   /                     \
   555  * |                  /                       \ 
   556  * | attack_level --> |                        \
   557  * |                  |                        |  <---  fade_level
   558  * |
   559  * +--------------------------------------------------> Time
   560  *                    [--]                 [---]
   561  *                    attack_length        fade_length
   562  * 
   563  * [------------------][-----------------------]
   564  * delay               length
   565  * \endcode
   566  *
   567  * \sa SDL_HapticConstant
   568  * \sa SDL_HapticPeriodic
   569  * \sa SDL_HapticCondition
   570  * \sa SDL_HapticRamp
   571  */
   572 typedef union SDL_HapticEffect {
   573    /* Common for all force feedback effects */
   574    Uint16 type; /**< Effect type. */
   575    SDL_HapticConstant constant; /**< Constant effect. */
   576    SDL_HapticPeriodic periodic; /**< Periodic effect. */
   577    SDL_HapticCondition condition[2]; /**< Condition effect, one for each axis. */
   578    SDL_HapticRamp ramp; /**< Ramp effect. */
   579 } SDL_HapticEffect;
   580 
   581 
   582 /* Function prototypes */
   583 /**
   584  * \fn int SDL_NumHaptics(void)
   585  *
   586  * \brief Count the number of joysticks attached to the system.
   587  *
   588  *    \return Number of haptic devices detected on the system.
   589  */
   590 extern DECLSPEC int SDLCALL SDL_NumHaptics(void);
   591 
   592 /**
   593  * \fn const char * SDL_HapticName(int device_index)
   594  *
   595  * \brief Get the implementation dependent name of a Haptic device.
   596  * This can be called before any joysticks are opened.
   597  * If no name can be found, this function returns NULL.
   598  *
   599  *    \param device_index Index of the device to get it's name.
   600  *    \return Name of the device or NULL on error.
   601  *
   602  * \sa SDL_NumHaptics
   603  */
   604 extern DECLSPEC const char *SDLCALL SDL_HapticName(int device_index);
   605 
   606 /**
   607  * \fn SDL_Haptic * SDL_HapticOpen(int device_index)
   608  *
   609  * \brief Opens a Haptic device for usage - the index passed as an
   610  * argument refers to the N'th Haptic device on this system.
   611  *
   612  * This function returns a Haptic device identifier, or Null
   613  * if an error occurred.
   614  *
   615  *    \param device_index Index of the device to open.
   616  *    \return Device identifier or NULL on error.
   617  *
   618  * \sa SDL_HapticOpenFromJoystick
   619  * \sa SDL_HapticClose
   620  */
   621 extern DECLSPEC SDL_Haptic * SDL_HapticOpen(int device_index);
   622 
   623 /**
   624  * \fn int SDL_JoystickIsHaptic(SDL_Joystick * joystick)
   625  *
   626  * \brief Checks to see if a joystick has haptic features.
   627  *
   628  *    \param joystick Joystick to test for haptic capabilities.
   629  *    \return SDL_TRUE if the joystick is haptic, SDL_FALSE if it isn't
   630  *            or -1 if an error ocurred.
   631  *
   632  * \sa SDL_HapticOpenFromJoystick
   633  */
   634 extern DECLSPEC int SDL_JoystickIsHaptic(SDL_Joystick * joystick);
   635 
   636 /**
   637  * \fn SDL_Haptic * SDL_HapticOpenFromJoystick(SDL_Joystick * joystick)
   638  *
   639  * \brief Opens a Haptic device for usage from a Joystick device.  Still has
   640  * to be closed seperately to the joystick.
   641  *
   642  *    \param joystick Joystick to create a haptic device from.
   643  *    \return A valid haptic device identifier on success or NULL on error.
   644  *
   645  * \sa SDL_HapticOpen
   646  * \sa SDL_HapticClose
   647  */
   648 extern DECLSPEC SDL_Haptic * SDL_HapticOpenFromJoystick(SDL_Joystick * joystick);
   649 
   650 /**
   651  * \fn void SDL_HapticClose(SDL_Haptic * haptic)
   652  *
   653  * \brief Closes a Haptic device previously opened with SDL_HapticOpen.
   654  *
   655  *    \param haptic Haptic device to close.
   656  */
   657 extern DECLSPEC void SDL_HapticClose(SDL_Haptic * haptic);
   658 
   659 /**
   660  * \fn int SDL_HapticNumEffects(SDL_Haptic * haptic)
   661  *
   662  * \brief Returns the number of effects a haptic device can store.
   663  *
   664  *    \param haptic The haptic device to query effect max.
   665  *    \return The number of effects the haptic device can store or
   666  *            -1 on error.
   667  *
   668  * \sa SDL_HapticQuery
   669  */
   670 extern DECLSPEC int SDL_HapticNumEffects(SDL_Haptic * haptic);
   671 
   672 /**
   673  * \fn unsigned int SDL_HapticQuery(SDL_Haptic * haptic)
   674  *
   675  * \brief Gets the haptic devices supported features in bitwise matter.
   676  *
   677  * Example: 
   678  * \code
   679  * if (SDL_HapticQueryEffects(haptic) & SDL_HAPTIC_CONSTANT) {
   680  *    printf("We have constant haptic effect!");
   681  * }
   682  * \endcode
   683  *    
   684  *
   685  *    \param haptic The haptic device to query.
   686  *    \return Haptic features in bitwise manner (OR'd).
   687  *
   688  * \sa SDL_HapticNumEffects
   689  * \sa SDL_HapticEffectSupported
   690  */
   691 extern DECLSPEC unsigned int SDL_HapticQuery(SDL_Haptic * haptic);
   692 
   693 /**
   694  * \fn int SDL_HapticEffectSupported(SDL_Haptic * haptic, SDL_HapticEffect * effect)
   695  *
   696  * \brief Checks to see if effect is supported by haptic.
   697  *
   698  *    \param haptic Haptic device to check on.
   699  *    \param effect Effect to check to see if it is supported.
   700  *    \return SDL_TRUE if effect is supported, SDL_FALSE if it isn't or 
   701  *            -1 on error.
   702  * 
   703  * \sa SDL_HapticQuery
   704  * \sa SDL_HapticNewEffect
   705  */
   706 extern DECLSPEC int SDL_HapticEffectSupported(SDL_Haptic * haptic, SDL_HapticEffect * effect);
   707 
   708 /**
   709  * \fn int SDL_HapticNewEffect(SDL_Haptic * haptic, SDL_HapticEffect * effect)
   710  *
   711  * \brief Creates a new haptic effect on the device.
   712  *
   713  *    \param haptic Haptic device to create the effect on.
   714  *    \param effect Properties of the effect to create.
   715  *    \return The id of the effect on success or -1 on error.
   716  *
   717  * \sa SDL_HapticUpdateEffect
   718  * \sa SDL_HapticRunEffect
   719  * \sa SDL_HapticDestroyEffect
   720  */
   721 extern DECLSPEC int SDL_HapticNewEffect(SDL_Haptic * haptic, SDL_HapticEffect * effect);
   722 
   723 /**
   724  * \fn int SDL_HapticUpdateEffect(SDL_Haptic * haptic, int effect, SDL_HapticEffect * data)
   725  *
   726  * \brief Updates an effect.  Can be used dynamically, although behaviour when
   727  * dynamically changing direction may be strange.  Specifically the effect
   728  * may reupload itself and start playing from the start.  You cannot change
   729  * the type either when running UpdateEffect.
   730  *
   731  *    \param haptic Haptic device that has the effect.
   732  *    \param effect Effect to update.
   733  *    \param data New effect properties to use.
   734  *    \return The id of the effect on success or -1 on error.
   735  *
   736  * \sa SDL_HapticNewEffect
   737  * \sa SDL_HapticRunEffect
   738  * \sa SDL_HapticDestroyEffect
   739  */
   740 extern DECLSPEC int SDL_HapticUpdateEffect(SDL_Haptic * haptic, int effect, SDL_HapticEffect * data);
   741 
   742 /**
   743  * \fn int SDL_HapticRunEffect(SDL_Haptic * haptic, int effect)
   744  *
   745  * \brief Runs the haptic effect on it's assosciated haptic device.
   746  *
   747  *    \param haptic Haptic device to run the effect on.
   748  *    \param effect Identifier of the haptic effect to run.
   749  *    \return 0 on success or -1 on error.
   750  *
   751  * \sa SDL_HapticStopEffect
   752  * \sa SDL_HapticDestroyEffect
   753  * \sa SDL_HapticGetEffectStatus
   754  */
   755 extern DECLSPEC int SDL_HapticRunEffect(SDL_Haptic * haptic, int effect);
   756 
   757 /**
   758  * \fn int SDL_HapticStopEffect(SDL_Haptic * haptic, int effect)
   759  *
   760  * \brief Stops the haptic effect on it's assosciated haptic device.
   761  *
   762  *    \param haptic Haptic device to stop the effect on.
   763  *    \param effect Identifier of the effect to stop.
   764  *    \return 0 on success or -1 on error.
   765  *
   766  * \sa SDL_HapticRunEffect
   767  * \sa SDL_HapticDestroyEffect
   768  */
   769 extern DECLSPEC int SDL_HapticStopEffect(SDL_Haptic * haptic, int effect);
   770 
   771 /**
   772  * \fn void SDL_HapticDestroyEffect(SDL_Haptic * haptic, int effect)
   773  *
   774  * \brief Destroys a haptic effect on the device.  This will stop the effect
   775  * if it's running.  Effects are automatically destroyed when the device is
   776  * closed.
   777  *
   778  *    \param haptic Device to destroy the effect on.
   779  *    \param effect Identifier of the effect to destroy.
   780  * 
   781  * \sa SDL_HapticNewEffect
   782  */
   783 extern DECLSPEC void SDL_HapticDestroyEffect(SDL_Haptic * haptic, int effect);
   784 
   785 /**
   786  * \fn int SDL_HapticGetEffectStatus(SDL_Haptic *haptic, int effect)
   787  *
   788  * \brief Gets the status of the current effect on the haptic device.
   789  *
   790  * Device must support the SDL_HAPTIC_STATUS feature.
   791  *
   792  *    \param haptic Haptic device to query the effect status on.
   793  *    \param effect Identifier of the effect to query it's status.
   794  *    \return 0 if it isn't playing, SDL_HAPTIC_PLAYING if it is playing
   795  *            or -1 on error.
   796  *
   797  * \sa SDL_HapticRunEffect
   798  * \sa SDL_HapticStopEffect
   799  */
   800 extern DECLSPEC int SDL_HapticGetEffectStatus(SDL_Haptic *haptic, int effect);
   801 
   802 /**
   803  * \fn int SDL_HapticSetGain(SDL_Haptic * haptic, int gain)
   804  *
   805  * \brief Sets the global gain of the device.  Gain should be between 0 and 100.
   806  *
   807  * Device must support the SDL_HAPTIC_GAIN feature.
   808  *
   809  *    \param haptic Haptic device to set the gain on.
   810  *    \param gain Value to set the gain to, should be between 0 and 100.
   811  *    \return 0 on success or -1 on error.
   812  *
   813  * \sa SDL_HapticQuery
   814  */
   815 extern DECLSPEC int SDL_HapticSetGain(SDL_Haptic * haptic, int gain);
   816 
   817 /**
   818  * \fn int SDL_HapticSetAutocenter(SDL_Haptic * haptic, int autocenter)
   819  *
   820  * \brief Sets the global autocenter of the device.  Autocenter should be between
   821  * 0 and 100.  Setting it to 0 will disable autocentering.
   822  *
   823  * Device must support the SDL_HAPTIC_AUTOCENTER feature.
   824  *
   825  *    \param haptic Haptic device to set autocentering on.
   826  *    \param autocenter Value to set autocenter to, 0 disables autocentering.
   827  *    \return 0 on success or -1 on error.
   828  *
   829  * \sa SDL_HapticQuery
   830  */
   831 extern DECLSPEC int SDL_HapticSetAutocenter(SDL_Haptic * haptic, int autocenter);
   832 
   833 
   834 /* Ends C function definitions when using C++ */
   835 #ifdef __cplusplus
   836 /* *INDENT-OFF* */
   837 }
   838 /* *INDENT-ON* */
   839 #endif
   840 #include "close_code.h"
   841 
   842 #endif /* _SDL_haptic_h */
   843 
   844 /* vi: set ts=4 sw=4 expandtab: */
   845 
   846