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