include/SDL_haptic.h
author Sam Lantinga <slouken@libsdl.org>
Fri, 28 Jan 2011 12:09:25 -0800
changeset 5126 ad4141d88412
parent 3496 78fc8ea578b2
child 5360 220d3af9121f
permissions -rw-r--r--
Added Edgar's blog to the haptic 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  * \par Example:
    41  * \code
    42  * int test_haptic( SDL_Joystick * joystick ) {
    43  *    SDL_Haptic *haptic;
    44  *    SDL_HapticEffect effect;
    45  *    int effect_id;
    46  *
    47  *    // Open the device
    48  *    haptic = SDL_HapticOpenFromJoystick( joystick );
    49  *    if (haptic == NULL) return -1; // Most likely joystick isn't haptic
    50  *
    51  *    // See if it can do sine waves
    52  *    if ((SDL_HapticQuery(haptic) & SDL_HAPTIC_SINE)==0) {
    53  *       SDL_HapticClose(haptic); // No sine effect
    54  *       return -1;
    55  *    }
    56  *
    57  *    // Create the effect
    58  *    memset( &effect, 0, sizeof(SDL_HapticEffect) ); // 0 is safe default
    59  *    effect.type = SDL_HAPTIC_SINE;
    60  *    effect.periodic.direction.type = SDL_HAPTIC_POLAR; // Polar coordinates
    61  *    effect.periodic.direction.dir[0] = 18000; // Force comes from south
    62  *    effect.periodic.period = 1000; // 1000 ms
    63  *    effect.periodic.magnitude = 20000; // 20000/32767 strength
    64  *    effect.periodic.length = 5000; // 5 seconds long
    65  *    effect.periodic.attack_length = 1000; // Takes 1 second to get max strength
    66  *    effect.periodic.fade_length = 1000; // Takes 1 second to fade away
    67  *
    68  *    // Upload the effect
    69  *    effect_id = SDL_HapticNewEffect( haptic, &effect );
    70  *
    71  *    // Test the effect
    72  *    SDL_HapticRunEffect( haptic, effect_id, 1 );
    73  *    SDL_Delay( 5000); // Wait for the effect to finish
    74  *
    75  *    // We destroy the effect, although closing the device also does this
    76  *    SDL_HapticDestroyEffect( haptic, effect_id );
    77  *
    78  *    // Close the device
    79  *    SDL_HapticClose(haptic);
    80  *
    81  *    return 0; // Success
    82  * }
    83  * \endcode
    84  *
    85  * You can also find out more information on my blog:
    86  * http://bobbens.dyndns.org/journal/2010/sdl_haptic/
    87  *
    88  * \author Edgar Simo Serra
    89  */
    90 
    91 #ifndef _SDL_haptic_h
    92 #define _SDL_haptic_h
    93 
    94 #include "SDL_stdinc.h"
    95 #include "SDL_error.h"
    96 #include "SDL_joystick.h"
    97 
    98 #include "begin_code.h"
    99 /* Set up for C function definitions, even when using C++ */
   100 #ifdef __cplusplus
   101 /* *INDENT-OFF* */
   102 extern "C" {
   103    /* *INDENT-ON* */                                                         
   104 #endif /* __cplusplus */
   105 
   106 /**
   107  *  \typedef SDL_Haptic
   108  *  
   109  *  \brief The haptic structure used to identify an SDL haptic.
   110  *  
   111  *  \sa SDL_HapticOpen
   112  *  \sa SDL_HapticOpenFromJoystick
   113  *  \sa SDL_HapticClose
   114  */
   115 struct _SDL_Haptic;
   116 typedef struct _SDL_Haptic SDL_Haptic;
   117 
   118 
   119 /**
   120  *  \name Haptic features
   121  *  
   122  *  Different haptic features a device can have.
   123  */
   124 /*@{*/
   125 
   126 /**
   127  *  \name Haptic effects
   128  */
   129 /*@{*/
   130 
   131 /**
   132  *  \brief Constant effect supported.
   133  *
   134  *  Constant haptic effect.
   135  *  
   136  *  \sa SDL_HapticCondition
   137  */
   138 #define SDL_HAPTIC_CONSTANT   (1<<0)
   139 
   140 /**
   141  *  \brief Sine wave effect supported.
   142  *  
   143  *  Periodic haptic effect that simulates sine waves.
   144  *  
   145  *  \sa SDL_HapticPeriodic
   146  */
   147 #define SDL_HAPTIC_SINE       (1<<1)
   148 
   149 /**
   150  *  \brief Square wave effect supported.
   151  *  
   152  *  Periodic haptic effect that simulates square waves.
   153  * 
   154  *  \sa SDL_HapticPeriodic
   155  */
   156 #define SDL_HAPTIC_SQUARE     (1<<2)
   157 
   158 /**
   159  *  \brief Triangle wave effect supported.
   160  *  
   161  *  Periodic haptic effect that simulates triangular waves.
   162  *  
   163  *  \sa SDL_HapticPeriodic
   164  */
   165 #define SDL_HAPTIC_TRIANGLE   (1<<3)
   166 
   167 /**
   168  *  \brief Sawtoothup wave effect supported.
   169  *  
   170  *  Periodic haptic effect that simulates saw tooth up waves.
   171  *  
   172  *  \sa SDL_HapticPeriodic
   173  */
   174 #define SDL_HAPTIC_SAWTOOTHUP (1<<4)
   175 
   176 /**
   177  *  \brief Sawtoothdown wave effect supported.
   178  *  
   179  *  Periodic haptic effect that simulates saw tooth down waves.
   180  *  
   181  *  \sa SDL_HapticPeriodic
   182  */
   183 #define SDL_HAPTIC_SAWTOOTHDOWN (1<<5)
   184 
   185 /**
   186  *  \brief Ramp effect supported.
   187  *  
   188  *  Ramp haptic effect.
   189  *  
   190  *  \sa SDL_HapticRamp
   191  */
   192 #define SDL_HAPTIC_RAMP       (1<<6)
   193 
   194 /**
   195  *  \brief Spring effect supported - uses axes position.
   196  *  
   197  *  Condition haptic effect that simulates a spring.  Effect is based on the
   198  *  axes position.
   199  *
   200  *  \sa SDL_HapticCondition
   201  */
   202 #define SDL_HAPTIC_SPRING     (1<<7)
   203 
   204 /**
   205  *  \brief Damper effect supported - uses axes velocity.
   206  *  
   207  *  Condition haptic effect that simulates dampening.  Effect is based on the
   208  *  axes velocity.
   209  *  
   210  *  \sa SDL_HapticCondition
   211  */
   212 #define SDL_HAPTIC_DAMPER     (1<<8)
   213 
   214 /**
   215  *  \brief Inertia effect supported - uses axes acceleration.
   216  *  
   217  *  Condition haptic effect that simulates inertia.  Effect is based on the axes
   218  *  acceleration.
   219  *
   220  *  \sa SDL_HapticCondition
   221  */
   222 #define SDL_HAPTIC_INERTIA    (1<<9)
   223 
   224 /**
   225  *  \brief Friction effect supported - uses axes movement.
   226  *  
   227  *  Condition haptic effect that simulates friction.  Effect is based on the 
   228  *  axes movement.
   229  *  
   230  *  \sa SDL_HapticCondition
   231  */
   232 #define SDL_HAPTIC_FRICTION   (1<<10)
   233 
   234 /**
   235  *  \brief Custom effect is supported.
   236  *  
   237  *  User defined custom haptic effect.
   238  */
   239 #define SDL_HAPTIC_CUSTOM     (1<<11)
   240 
   241 /*@}*//*Haptic effects*/
   242 
   243 /* These last few are features the device has, not effects */
   244 
   245 /**
   246  *  \brief Device can set global gain.
   247  *  
   248  *  Device supports setting the global gain.
   249  *  
   250  *  \sa SDL_HapticSetGain
   251  */
   252 #define SDL_HAPTIC_GAIN       (1<<12)
   253 
   254 /**
   255  *  \brief Device can set autocenter.
   256  *  
   257  *  Device supports setting autocenter.
   258  *  
   259  *  \sa SDL_HapticSetAutocenter
   260  */
   261 #define SDL_HAPTIC_AUTOCENTER (1<<13)
   262 
   263 /**
   264  *  \brief Device can be queried for effect status.
   265  *  
   266  *  Device can be queried for effect status.
   267  *  
   268  *  \sa SDL_HapticGetEffectStatus
   269  */
   270 #define SDL_HAPTIC_STATUS     (1<<14)
   271 
   272 /**
   273  *  \brief Device can be paused.
   274  *  
   275  *  \sa SDL_HapticPause
   276  *  \sa SDL_HapticUnpause
   277  */
   278 #define SDL_HAPTIC_PAUSE      (1<<15)
   279 
   280 
   281 /**
   282  * \name Direction encodings
   283  */
   284 /*@{*/
   285 
   286 /**
   287  *  \brief Uses polar coordinates for the direction.
   288  *  
   289  *  \sa SDL_HapticDirection
   290  */
   291 #define SDL_HAPTIC_POLAR      0
   292 
   293 /**
   294  *  \brief Uses cartesian coordinates for the direction.
   295  *  
   296  *  \sa SDL_HapticDirection
   297  */
   298 #define SDL_HAPTIC_CARTESIAN  1
   299 
   300 /**
   301  *  \brief Uses spherical coordinates for the direction.
   302  *  
   303  *  \sa SDL_HapticDirection
   304  */
   305 #define SDL_HAPTIC_SPHERICAL  2
   306 
   307 /*@}*//*Direction encodings*/
   308 
   309 /*@}*//*Haptic features*/
   310 
   311 /*
   312  * Misc defines.
   313  */
   314 
   315 /**
   316  * \brief Used to play a device an infinite number of times.
   317  *
   318  * \sa SDL_HapticRunEffect
   319  */
   320 #define SDL_HAPTIC_INFINITY   4294967295U
   321 
   322 
   323 /**
   324  *  \brief Structure that represents a haptic direction.
   325  *  
   326  *  Directions can be specified by:
   327  *   - ::SDL_HAPTIC_POLAR : Specified by polar coordinates.
   328  *   - ::SDL_HAPTIC_CARTESIAN : Specified by cartesian coordinates.
   329  *   - ::SDL_HAPTIC_SPHERICAL : Specified by spherical coordinates.
   330  *
   331  *  Cardinal directions of the haptic device are relative to the positioning
   332  *  of the device.  North is considered to be away from the user.
   333  *
   334  *  The following diagram represents the cardinal directions:
   335  *  \verbatim
   336                  .--.
   337                  |__| .-------.
   338                  |=.| |.-----.|
   339                  |--| ||     ||
   340                  |  | |'-----'|
   341                  |__|~')_____('
   342                    [ COMPUTER ]
   343     
   344     
   345                      North (0,-1)
   346                          ^
   347                          |
   348                          |
   349     (1,0)  West <----[ HAPTIC ]----> East (-1,0)
   350                          |
   351                          |
   352                          v
   353                       South (0,1)
   354     
   355     
   356                       [ USER ]
   357                         \|||/
   358                         (o o)
   359                   ---ooO-(_)-Ooo---
   360     \endverbatim
   361  *  
   362  *  If type is ::SDL_HAPTIC_POLAR, direction is encoded by hundredths of a 
   363  *  degree starting north and turning clockwise.  ::SDL_HAPTIC_POLAR only uses
   364  *  the first \c dir parameter.  The cardinal directions would be:
   365  *   - North: 0 (0 degrees)
   366  *   - East: 9000 (90 degrees)
   367  *   - South: 18000 (180 degrees)
   368  *   - West: 27000 (270 degrees)
   369  *  
   370  *  If type is ::SDL_HAPTIC_CARTESIAN, direction is encoded by three positions
   371  *  (X axis, Y axis and Z axis (with 3 axes)).  ::SDL_HAPTIC_CARTESIAN uses
   372  *  the first three \c dir parameters.  The cardinal directions would be:
   373  *   - North:  0,-1, 0
   374  *   - East:  -1, 0, 0
   375  *   - South:  0, 1, 0
   376  *   - West:   1, 0, 0
   377  *  
   378  *  The Z axis represents the height of the effect if supported, otherwise
   379  *  it's unused.  In cartesian encoding (1, 2) would be the same as (2, 4), you
   380  *  can use any multiple you want, only the direction matters.
   381  *  
   382  *  If type is ::SDL_HAPTIC_SPHERICAL, direction is encoded by two rotations.
   383  *  The first two \c dir parameters are used.  The \c dir parameters are as 
   384  *  follows (all values are in hundredths of degrees):
   385  *   - Degrees from (1, 0) rotated towards (0, 1).
   386  *   - Degrees towards (0, 0, 1) (device needs at least 3 axes).
   387  *
   388  *
   389  *  Example of force coming from the south with all encodings (force coming
   390  *  from the south means the user will have to pull the stick to counteract):
   391  *  \code
   392  *  SDL_HapticDirection direction;
   393  *  
   394  *  // Cartesian directions
   395  *  direction.type = SDL_HAPTIC_CARTESIAN; // Using cartesian direction encoding.
   396  *  direction.dir[0] = 0; // X position
   397  *  direction.dir[1] = 1; // Y position
   398  *  // Assuming the device has 2 axes, we don't need to specify third parameter.
   399  *  
   400  *  // Polar directions
   401  *  direction.type = SDL_HAPTIC_POLAR; // We'll be using polar direction encoding.
   402  *  direction.dir[0] = 18000; // Polar only uses first parameter
   403  *  
   404  *  // Spherical coordinates
   405  *  direction.type = SDL_HAPTIC_SPHERICAL; // Spherical encoding
   406  *  direction.dir[0] = 9000; // Since we only have two axes we don't need more parameters.
   407  *  \endcode
   408  *
   409  *  \sa SDL_HAPTIC_POLAR
   410  *  \sa SDL_HAPTIC_CARTESIAN
   411  *  \sa SDL_HAPTIC_SPHERICAL
   412  *  \sa SDL_HapticEffect
   413  *  \sa SDL_HapticNumAxes
   414  */
   415 typedef struct SDL_HapticDirection
   416 {
   417     Uint8 type;         /**< The type of encoding. */
   418     Sint32 dir[3];      /**< The encoded direction. */
   419 } SDL_HapticDirection;
   420 
   421 
   422 /**
   423  *  \brief A structure containing a template for a Constant effect.
   424  *  
   425  *  The struct is exclusive to the ::SDL_HAPTIC_CONSTANT effect.
   426  *  
   427  *  A constant effect applies a constant force in the specified direction
   428  *  to the joystick.
   429  *  
   430  *  \sa SDL_HAPTIC_CONSTANT
   431  *  \sa SDL_HapticEffect
   432  */
   433 typedef struct SDL_HapticConstant
   434 {
   435     /* Header */
   436     Uint16 type;            /**< ::SDL_HAPTIC_CONSTANT */
   437     SDL_HapticDirection direction;  /**< Direction of the effect. */
   438 
   439     /* Replay */
   440     Uint32 length;          /**< Duration of the effect. */
   441     Uint16 delay;           /**< Delay before starting the effect. */
   442 
   443     /* Trigger */
   444     Uint16 button;          /**< Button that triggers the effect. */
   445     Uint16 interval;        /**< How soon it can be triggered again after button. */
   446 
   447     /* Constant */
   448     Sint16 level;           /**< Strength of the constant effect. */
   449 
   450     /* Envelope */
   451     Uint16 attack_length;   /**< Duration of the attack. */
   452     Uint16 attack_level;    /**< Level at the start of the attack. */
   453     Uint16 fade_length;     /**< Duration of the fade. */
   454     Uint16 fade_level;      /**< Level at the end of the fade. */
   455 } SDL_HapticConstant;
   456 
   457 /**
   458  *  \brief A structure containing a template for a Periodic effect.
   459  *  
   460  *  The struct handles the following effects:
   461  *   - ::SDL_HAPTIC_SINE
   462  *   - ::SDL_HAPTIC_SQUARE
   463  *   - ::SDL_HAPTIC_TRIANGLE
   464  *   - ::SDL_HAPTIC_SAWTOOTHUP
   465  *   - ::SDL_HAPTIC_SAWTOOTHDOWN
   466  *  
   467  *  A periodic effect consists in a wave-shaped effect that repeats itself
   468  *  over time.  The type determines the shape of the wave and the parameters
   469  *  determine the dimensions of the wave.
   470  *  
   471  *  Phase is given by hundredth of a cyle meaning that giving the phase a value
   472  *  of 9000 will displace it 25% of it's period.  Here are sample values:
   473  *   -     0: No phase displacement.
   474  *   -  9000: Displaced 25% of it's period.
   475  *   - 18000: Displaced 50% of it's period.
   476  *   - 27000: Displaced 75% of it's period.
   477  *   - 36000: Displaced 100% of it's period, same as 0, but 0 is preffered.
   478  *
   479  *  Examples:
   480  *  \verbatim
   481     SDL_HAPTIC_SINE
   482       __      __      __      __
   483      /  \    /  \    /  \    /
   484     /    \__/    \__/    \__/
   485     
   486     SDL_HAPTIC_SQUARE
   487      __    __    __    __    __
   488     |  |  |  |  |  |  |  |  |  |
   489     |  |__|  |__|  |__|  |__|  |
   490     
   491     SDL_HAPTIC_TRIANGLE
   492       /\    /\    /\    /\    /\
   493      /  \  /  \  /  \  /  \  /
   494     /    \/    \/    \/    \/
   495     
   496     SDL_HAPTIC_SAWTOOTHUP
   497       /|  /|  /|  /|  /|  /|  /|
   498      / | / | / | / | / | / | / |
   499     /  |/  |/  |/  |/  |/  |/  |
   500     
   501     SDL_HAPTIC_SAWTOOTHDOWN
   502     \  |\  |\  |\  |\  |\  |\  |
   503      \ | \ | \ | \ | \ | \ | \ |
   504       \|  \|  \|  \|  \|  \|  \|
   505     \endverbatim
   506  *  
   507  *  \sa SDL_HAPTIC_SINE
   508  *  \sa SDL_HAPTIC_SQUARE
   509  *  \sa SDL_HAPTIC_TRIANGLE
   510  *  \sa SDL_HAPTIC_SAWTOOTHUP
   511  *  \sa SDL_HAPTIC_SAWTOOTHDOWN
   512  *  \sa SDL_HapticEffect
   513  */
   514 typedef struct SDL_HapticPeriodic
   515 {
   516     /* Header */
   517     Uint16 type;        /**< ::SDL_HAPTIC_SINE, ::SDL_HAPTIC_SQUARE,
   518                              ::SDL_HAPTIC_TRIANGLE, ::SDL_HAPTIC_SAWTOOTHUP or
   519                              ::SDL_HAPTIC_SAWTOOTHDOWN */
   520     SDL_HapticDirection direction;  /**< Direction of the effect. */
   521 
   522     /* Replay */
   523     Uint32 length;      /**< Duration of the effect. */
   524     Uint16 delay;       /**< Delay before starting the effect. */
   525 
   526     /* Trigger */
   527     Uint16 button;      /**< Button that triggers the effect. */
   528     Uint16 interval;    /**< How soon it can be triggered again after button. */
   529 
   530     /* Periodic */
   531     Uint16 period;      /**< Period of the wave. */
   532     Sint16 magnitude;   /**< Peak value. */
   533     Sint16 offset;      /**< Mean value of the wave. */
   534     Uint16 phase;       /**< Horizontal shift given by hundredth of a cycle. */
   535 
   536     /* Envelope */
   537     Uint16 attack_length;   /**< Duration of the attack. */
   538     Uint16 attack_level;    /**< Level at the start of the attack. */
   539     Uint16 fade_length; /**< Duration of the fade. */
   540     Uint16 fade_level;  /**< Level at the end of the fade. */
   541 } SDL_HapticPeriodic;
   542 
   543 /**
   544  *  \brief A structure containing a template for a Condition effect.
   545  *  
   546  *  The struct handles the following effects:
   547  *   - ::SDL_HAPTIC_SPRING: Effect based on axes position.
   548  *   - ::SDL_HAPTIC_DAMPER: Effect based on axes velocity.
   549  *   - ::SDL_HAPTIC_INERTIA: Effect based on axes acceleration.
   550  *   - ::SDL_HAPTIC_FRICTION: Effect based on axes movement.
   551  *  
   552  *  Direction is handled by condition internals instead of a direction member.
   553  *  The condition effect specific members have three parameters.  The first
   554  *  refers to the X axis, the second refers to the Y axis and the third
   555  *  refers to the Z axis.  The right terms refer to the positive side of the
   556  *  axis and the left terms refer to the negative side of the axis.  Please 
   557  *  refer to the ::SDL_HapticDirection diagram for which side is positive and
   558  *  which is negative.
   559  *  
   560  *  \sa SDL_HapticDirection
   561  *  \sa SDL_HAPTIC_SPRING
   562  *  \sa SDL_HAPTIC_DAMPER
   563  *  \sa SDL_HAPTIC_INERTIA
   564  *  \sa SDL_HAPTIC_FRICTION
   565  *  \sa SDL_HapticEffect
   566  */
   567 typedef struct SDL_HapticCondition
   568 {
   569     /* Header */
   570     Uint16 type;            /**< ::SDL_HAPTIC_SPRING, ::SDL_HAPTIC_DAMPER,
   571                                  ::SDL_HAPTIC_INERTIA or ::SDL_HAPTIC_FRICTION */
   572     SDL_HapticDirection direction;  /**< Direction of the effect - Not used ATM. */
   573 
   574     /* Replay */
   575     Uint32 length;          /**< Duration of the effect. */
   576     Uint16 delay;           /**< Delay before starting the effect. */
   577 
   578     /* Trigger */
   579     Uint16 button;          /**< Button that triggers the effect. */
   580     Uint16 interval;        /**< How soon it can be triggered again after button. */
   581 
   582     /* Condition */
   583     Uint16 right_sat[3];    /**< Level when joystick is to the positive side. */
   584     Uint16 left_sat[3];     /**< Level when joystick is to the negative side. */
   585     Sint16 right_coeff[3];  /**< How fast to increase the force towards the positive side. */
   586     Sint16 left_coeff[3];   /**< How fast to increase the force towards the negative side. */
   587     Uint16 deadband[3];     /**< Size of the dead zone. */
   588     Sint16 center[3];       /**< Position of the dead zone. */
   589 } SDL_HapticCondition;
   590 
   591 /**
   592  *  \brief A structure containing a template for a Ramp effect.
   593  *  
   594  *  This struct is exclusively for the ::SDL_HAPTIC_RAMP effect.
   595  *  
   596  *  The ramp effect starts at start strength and ends at end strength.
   597  *  It augments in linear fashion.  If you use attack and fade with a ramp
   598  *  they effects get added to the ramp effect making the effect become
   599  *  quadratic instead of linear.
   600  *  
   601  *  \sa SDL_HAPTIC_RAMP
   602  *  \sa SDL_HapticEffect
   603  */
   604 typedef struct SDL_HapticRamp
   605 {
   606     /* Header */
   607     Uint16 type;            /**< ::SDL_HAPTIC_RAMP */
   608     SDL_HapticDirection direction;  /**< Direction of the effect. */
   609 
   610     /* Replay */
   611     Uint32 length;          /**< Duration of the effect. */
   612     Uint16 delay;           /**< Delay before starting the effect. */
   613 
   614     /* Trigger */
   615     Uint16 button;          /**< Button that triggers the effect. */
   616     Uint16 interval;        /**< How soon it can be triggered again after button. */
   617 
   618     /* Ramp */
   619     Sint16 start;           /**< Beginning strength level. */
   620     Sint16 end;             /**< Ending strength level. */
   621 
   622     /* Envelope */
   623     Uint16 attack_length;   /**< Duration of the attack. */
   624     Uint16 attack_level;    /**< Level at the start of the attack. */
   625     Uint16 fade_length;     /**< Duration of the fade. */
   626     Uint16 fade_level;      /**< Level at the end of the fade. */
   627 } SDL_HapticRamp;
   628 
   629 /**
   630  *  \brief A structure containing a template for the ::SDL_HAPTIC_CUSTOM effect.
   631  *  
   632  *  A custom force feedback effect is much like a periodic effect, where the
   633  *  application can define it's exact shape.  You will have to allocate the
   634  *  data yourself.  Data should consist of channels * samples Uint16 samples.
   635  *  
   636  *  If channels is one, the effect is rotated using the defined direction.
   637  *  Otherwise it uses the samples in data for the different axes.
   638  *  
   639  *  \sa SDL_HAPTIC_CUSTOM
   640  *  \sa SDL_HapticEffect
   641  */
   642 typedef struct SDL_HapticCustom
   643 {
   644     /* Header */
   645     Uint16 type;            /**< ::SDL_HAPTIC_CUSTOM */
   646     SDL_HapticDirection direction;  /**< Direction of the effect. */
   647 
   648     /* Replay */
   649     Uint32 length;          /**< Duration of the effect. */
   650     Uint16 delay;           /**< Delay before starting the effect. */
   651 
   652     /* Trigger */
   653     Uint16 button;          /**< Button that triggers the effect. */
   654     Uint16 interval;        /**< How soon it can be triggered again after button. */
   655 
   656     /* Custom */
   657     Uint8 channels;         /**< Axes to use, minimum of one. */
   658     Uint16 period;          /**< Sample periods. */
   659     Uint16 samples;         /**< Amount of samples. */
   660     Uint16 *data;           /**< Should contain channels*samples items. */
   661 
   662     /* Envelope */
   663     Uint16 attack_length;   /**< Duration of the attack. */
   664     Uint16 attack_level;    /**< Level at the start of the attack. */
   665     Uint16 fade_length;     /**< Duration of the fade. */
   666     Uint16 fade_level;      /**< Level at the end of the fade. */
   667 } SDL_HapticCustom;
   668 
   669 /**
   670  *  \brief The generic template for any haptic effect.
   671  *  
   672  *  All values max at 32767 (0x7FFF).  Signed values also can be negative.
   673  *  Time values unless specified otherwise are in milliseconds.
   674  *  
   675  *  You can also pass ::SDL_HAPTIC_INFINITY to length instead of a 0-32767 
   676  *  value.  Neither delay, interval, attack_length nor fade_length support 
   677  *  ::SDL_HAPTIC_INFINITY.  Fade will also not be used since effect never ends.
   678  *  
   679  *  Additionally, the ::SDL_HAPTIC_RAMP effect does not support a duration of
   680  *  ::SDL_HAPTIC_INFINITY.
   681  *  
   682  *  Button triggers may not be supported on all devices, it is advised to not
   683  *  use them if possible.  Buttons start at index 1 instead of index 0 like
   684  *  they joystick.
   685  *  
   686  *  If both attack_length and fade_level are 0, the envelope is not used,
   687  *  otherwise both values are used.
   688  *  
   689  *  Common parts:
   690  *  \code
   691  *  // Replay - All effects have this
   692  *  Uint32 length;        // Duration of effect (ms).
   693  *  Uint16 delay;         // Delay before starting effect.
   694  *  
   695  *  // Trigger - All effects have this
   696  *  Uint16 button;        // Button that triggers effect.
   697  *  Uint16 interval;      // How soon before effect can be triggered again.
   698  *  
   699  *  // Envelope - All effects except condition effects have this
   700  *  Uint16 attack_length; // Duration of the attack (ms).
   701  *  Uint16 attack_level;  // Level at the start of the attack.
   702  *  Uint16 fade_length;   // Duration of the fade out (ms).
   703  *  Uint16 fade_level;    // Level at the end of the fade.
   704  *  \endcode
   705  *
   706  *
   707  *  Here we have an example of a constant effect evolution in time:
   708  *  \verbatim
   709     Strength
   710     ^
   711     |
   712     |    effect level -->  _________________
   713     |                     /                 \
   714     |                    /                   \
   715     |                   /                     \
   716     |                  /                       \ 
   717     | attack_level --> |                        \
   718     |                  |                        |  <---  fade_level
   719     |
   720     +--------------------------------------------------> Time
   721                        [--]                 [---]
   722                        attack_length        fade_length
   723     
   724     [------------------][-----------------------]
   725     delay               length
   726     \endverbatim
   727  *  
   728  *  Note either the attack_level or the fade_level may be above the actual
   729  *  effect level.
   730  *
   731  *  \sa SDL_HapticConstant
   732  *  \sa SDL_HapticPeriodic
   733  *  \sa SDL_HapticCondition
   734  *  \sa SDL_HapticRamp
   735  *  \sa SDL_HapticCustom
   736  */
   737 typedef union SDL_HapticEffect
   738 {
   739     /* Common for all force feedback effects */
   740     Uint16 type;                    /**< Effect type. */
   741     SDL_HapticConstant constant;    /**< Constant effect. */
   742     SDL_HapticPeriodic periodic;    /**< Periodic effect. */
   743     SDL_HapticCondition condition;  /**< Condition effect. */
   744     SDL_HapticRamp ramp;            /**< Ramp effect. */
   745     SDL_HapticCustom custom;        /**< Custom effect. */
   746 } SDL_HapticEffect;
   747 
   748 
   749 /* Function prototypes */
   750 /**
   751  *  \brief Count the number of joysticks attached to the system.
   752  *  
   753  *  \return Number of haptic devices detected on the system.
   754  */
   755 extern DECLSPEC int SDLCALL SDL_NumHaptics(void);
   756 
   757 /**
   758  *  \brief Get the implementation dependent name of a Haptic device.
   759  *  
   760  *  This can be called before any joysticks are opened.
   761  *  If no name can be found, this function returns NULL.
   762  *  
   763  *  \param device_index Index of the device to get it's name.
   764  *  \return Name of the device or NULL on error.
   765  *
   766  *  \sa SDL_NumHaptics
   767  */
   768 extern DECLSPEC const char *SDLCALL SDL_HapticName(int device_index);
   769 
   770 /**
   771  *  \brief Opens a Haptic device for usage.
   772  *  
   773  *  The index passed as an argument refers to the N'th Haptic device on this 
   774  *  system.
   775  *
   776  *  When opening a haptic device, it's gain will be set to maximum and
   777  *  autocenter will be disabled.  To modify these values use
   778  *  SDL_HapticSetGain() and SDL_HapticSetAutocenter().
   779  *
   780  *  \param device_index Index of the device to open.
   781  *  \return Device identifier or NULL on error.
   782  *
   783  *  \sa SDL_HapticIndex
   784  *  \sa SDL_HapticOpenFromMouse
   785  *  \sa SDL_HapticOpenFromJoystick
   786  *  \sa SDL_HapticClose
   787  *  \sa SDL_HapticSetGain
   788  *  \sa SDL_HapticSetAutocenter
   789  *  \sa SDL_HapticPause
   790  *  \sa SDL_HapticStopAll
   791  */
   792 extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpen(int device_index);
   793 
   794 /**
   795  *  \brief Checks if the haptic device at index has been opened.
   796  *  
   797  *  \param device_index Index to check to see if it has been opened.
   798  *  \return 1 if it has been opened or 0 if it hasn't.
   799  *  
   800  *  \sa SDL_HapticOpen
   801  *  \sa SDL_HapticIndex
   802  */
   803 extern DECLSPEC int SDLCALL SDL_HapticOpened(int device_index);
   804 
   805 /**
   806  *  \brief Gets the index of a haptic device.
   807  *  
   808  *  \param haptic Haptic device to get the index of.
   809  *  \return The index of the haptic device or -1 on error.
   810  *  
   811  *  \sa SDL_HapticOpen
   812  *  \sa SDL_HapticOpened
   813  */
   814 extern DECLSPEC int SDLCALL SDL_HapticIndex(SDL_Haptic * haptic);
   815 
   816 /**
   817  *  \brief Gets whether or not the current mouse has haptic capabilities.
   818  *  
   819  *  \return SDL_TRUE if the mouse is haptic, SDL_FALSE if it isn't.
   820  *  
   821  *  \sa SDL_HapticOpenFromMouse
   822  */
   823 extern DECLSPEC int SDLCALL SDL_MouseIsHaptic(void);
   824 
   825 /**
   826  *  \brief Tries to open a haptic device from the current mouse.
   827  *  
   828  *  \return The haptic device identifier or NULL on error.
   829  *  
   830  *  \sa SDL_MouseIsHaptic
   831  *  \sa SDL_HapticOpen
   832  */
   833 extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromMouse(void);
   834 
   835 /**
   836  *  \brief Checks to see if a joystick has haptic features.
   837  *  
   838  *  \param joystick Joystick to test for haptic capabilities.
   839  *  \return 1 if the joystick is haptic, 0 if it isn't
   840  *          or -1 if an error ocurred.
   841  *  
   842  *  \sa SDL_HapticOpenFromJoystick
   843  */
   844 extern DECLSPEC int SDLCALL SDL_JoystickIsHaptic(SDL_Joystick * joystick);
   845 
   846 /**
   847  *  \brief Opens a Haptic device for usage from a Joystick device.
   848  *  
   849  *  You must still close the haptic device seperately.  It will not be closed 
   850  *  with the joystick.
   851  *  
   852  *  When opening from a joystick you should first close the haptic device before
   853  *  closing the joystick device.  If not, on some implementations the haptic
   854  *  device will also get unallocated and you'll be unable to use force feedback
   855  *  on that device.
   856  *  
   857  *  \param joystick Joystick to create a haptic device from.
   858  *  \return A valid haptic device identifier on success or NULL on error.
   859  *  
   860  *  \sa SDL_HapticOpen
   861  *  \sa SDL_HapticClose
   862  */
   863 extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromJoystick(SDL_Joystick *
   864                                                                joystick);
   865 
   866 /**
   867  *  \brief Closes a Haptic device previously opened with SDL_HapticOpen().
   868  *  
   869  *  \param haptic Haptic device to close.
   870  */
   871 extern DECLSPEC void SDLCALL SDL_HapticClose(SDL_Haptic * haptic);
   872 
   873 /**
   874  *  \brief Returns the number of effects a haptic device can store.
   875  *  
   876  *  On some platforms this isn't fully supported, and therefore is an
   877  *  aproximation.  Always check to see if your created effect was actually
   878  *  created and do not rely solely on SDL_HapticNumEffects().
   879  *  
   880  *  \param haptic The haptic device to query effect max.
   881  *  \return The number of effects the haptic device can store or
   882  *          -1 on error.
   883  *  
   884  *  \sa SDL_HapticNumEffectsPlaying
   885  *  \sa SDL_HapticQuery
   886  */
   887 extern DECLSPEC int SDLCALL SDL_HapticNumEffects(SDL_Haptic * haptic);
   888 
   889 /**
   890  *  \brief Returns the number of effects a haptic device can play at the same 
   891  *         time.
   892  *  
   893  *  This is not supported on all platforms, but will always return a value.  
   894  *  Added here for the sake of completness.
   895  *  
   896  *  \param haptic The haptic device to query maximum playing effects.
   897  *  \return The number of effects the haptic device can play at the same time
   898  *          or -1 on error.
   899  *
   900  *  \sa SDL_HapticNumEffects
   901  *  \sa SDL_HapticQuery
   902  */
   903 extern DECLSPEC int SDLCALL SDL_HapticNumEffectsPlaying(SDL_Haptic * haptic);
   904 
   905 /**
   906  *  \brief Gets the haptic devices supported features in bitwise matter.
   907  *  
   908  *  Example: 
   909  *  \code
   910  *  if (SDL_HapticQueryEffects(haptic) & SDL_HAPTIC_CONSTANT) {
   911  *      printf("We have constant haptic effect!");
   912  *  }
   913  *  \endcode
   914  *  
   915  *  \param haptic The haptic device to query.
   916  *  \return Haptic features in bitwise manner (OR'd).
   917  *  
   918  *  \sa SDL_HapticNumEffects
   919  *  \sa SDL_HapticEffectSupported
   920  */
   921 extern DECLSPEC unsigned int SDLCALL SDL_HapticQuery(SDL_Haptic * haptic);
   922 
   923 
   924 /**
   925  *  \brief Gets the number of haptic axes the device has.
   926  *  
   927  *  \sa SDL_HapticDirection
   928  */
   929 extern DECLSPEC int SDLCALL SDL_HapticNumAxes(SDL_Haptic * haptic);
   930 
   931 /**
   932  *  \brief Checks to see if effect is supported by haptic.
   933  *  
   934  *  \param haptic Haptic device to check on.
   935  *  \param effect Effect to check to see if it is supported.
   936  *  \return 1 if effect is supported, 0 if it isn't or -1 on error.
   937  *  
   938  *  \sa SDL_HapticQuery
   939  *  \sa SDL_HapticNewEffect
   940  */
   941 extern DECLSPEC int SDLCALL SDL_HapticEffectSupported(SDL_Haptic * haptic,
   942                                                       SDL_HapticEffect *
   943                                                       effect);
   944 
   945 /**
   946  *  \brief Creates a new haptic effect on the device.
   947  *  
   948  *  \param haptic Haptic device to create the effect on.
   949  *  \param effect Properties of the effect to create.
   950  *  \return The id of the effect on success or -1 on error.
   951  *  
   952  *  \sa SDL_HapticUpdateEffect
   953  *  \sa SDL_HapticRunEffect
   954  *  \sa SDL_HapticDestroyEffect
   955  */
   956 extern DECLSPEC int SDLCALL SDL_HapticNewEffect(SDL_Haptic * haptic,
   957                                                 SDL_HapticEffect * effect);
   958 
   959 /**
   960  *  \brief Updates the properties of an effect.
   961  *  
   962  *  Can be used dynamically, although behaviour when dynamically changing
   963  *  direction may be strange.  Specifically the effect may reupload itself
   964  *  and start playing from the start.  You cannot change the type either when
   965  *  running SDL_HapticUpdateEffect().
   966  *  
   967  *  \param haptic Haptic device that has the effect.
   968  *  \param effect Effect to update.
   969  *  \param data New effect properties to use.
   970  *  \return The id of the effect on success or -1 on error.
   971  *  
   972  *  \sa SDL_HapticNewEffect
   973  *  \sa SDL_HapticRunEffect
   974  *  \sa SDL_HapticDestroyEffect
   975  */
   976 extern DECLSPEC int SDLCALL SDL_HapticUpdateEffect(SDL_Haptic * haptic,
   977                                                    int effect,
   978                                                    SDL_HapticEffect * data);
   979 
   980 /**
   981  *  \brief Runs the haptic effect on it's assosciated haptic device.
   982  *  
   983  *  If iterations are ::SDL_HAPTIC_INFINITY, it'll run the effect over and over
   984  *  repeating the envelope (attack and fade) every time.  If you only want the
   985  *  effect to last forever, set ::SDL_HAPTIC_INFINITY in the effect's length
   986  *  parameter.
   987  *  
   988  *  \param haptic Haptic device to run the effect on.
   989  *  \param effect Identifier of the haptic effect to run.
   990  *  \param iterations Number of iterations to run the effect. Use
   991  *         ::SDL_HAPTIC_INFINITY for infinity.
   992  *  \return 0 on success or -1 on error.
   993  *  
   994  *  \sa SDL_HapticStopEffect
   995  *  \sa SDL_HapticDestroyEffect
   996  *  \sa SDL_HapticGetEffectStatus
   997  */
   998 extern DECLSPEC int SDLCALL SDL_HapticRunEffect(SDL_Haptic * haptic,
   999                                                 int effect,
  1000                                                 Uint32 iterations);
  1001 
  1002 /**
  1003  *  \brief Stops the haptic effect on it's assosciated haptic device.
  1004  *  
  1005  *  \param haptic Haptic device to stop the effect on.
  1006  *  \param effect Identifier of the effect to stop.
  1007  *  \return 0 on success or -1 on error.
  1008  *  
  1009  *  \sa SDL_HapticRunEffect
  1010  *  \sa SDL_HapticDestroyEffect
  1011  */
  1012 extern DECLSPEC int SDLCALL SDL_HapticStopEffect(SDL_Haptic * haptic,
  1013                                                  int effect);
  1014 
  1015 /**
  1016  *  \brief Destroys a haptic effect on the device.
  1017  *  
  1018  *  This will stop the effect if it's running.  Effects are automatically 
  1019  *  destroyed when the device is closed.
  1020  *  
  1021  *  \param haptic Device to destroy the effect on.
  1022  *  \param effect Identifier of the effect to destroy.
  1023  *  
  1024  *  \sa SDL_HapticNewEffect
  1025  */
  1026 extern DECLSPEC void SDLCALL SDL_HapticDestroyEffect(SDL_Haptic * haptic,
  1027                                                      int effect);
  1028 
  1029 /**
  1030  *  \brief Gets the status of the current effect on the haptic device.
  1031  *  
  1032  *  Device must support the ::SDL_HAPTIC_STATUS feature.
  1033  *  
  1034  *  \param haptic Haptic device to query the effect status on.
  1035  *  \param effect Identifier of the effect to query it's status.
  1036  *  \return 0 if it isn't playing, ::SDL_HAPTIC_PLAYING if it is playing
  1037  *          or -1 on error.
  1038  *  
  1039  *  \sa SDL_HapticRunEffect
  1040  *  \sa SDL_HapticStopEffect
  1041  */
  1042 extern DECLSPEC int SDLCALL SDL_HapticGetEffectStatus(SDL_Haptic * haptic,
  1043                                                       int effect);
  1044 
  1045 /**
  1046  *  \brief Sets the global gain of the device.
  1047  *  
  1048  *  Device must support the ::SDL_HAPTIC_GAIN feature.
  1049  *  
  1050  *  The user may specify the maxmimum gain by setting the environment variable
  1051  *  ::SDL_HAPTIC_GAIN_MAX which should be between 0 and 100.  All calls to
  1052  *  SDL_HapticSetGain() will scale linearly using ::SDL_HAPTIC_GAIN_MAX as the
  1053  *  maximum.
  1054  *  
  1055  *  \param haptic Haptic device to set the gain on.
  1056  *  \param gain Value to set the gain to, should be between 0 and 100.
  1057  *  \return 0 on success or -1 on error.
  1058  *  
  1059  *  \sa SDL_HapticQuery
  1060  */
  1061 extern DECLSPEC int SDLCALL SDL_HapticSetGain(SDL_Haptic * haptic, int gain);
  1062 
  1063 /**
  1064  *  \brief Sets the global autocenter of the device.
  1065  *  
  1066  *  Autocenter should be between 0 and 100.  Setting it to 0 will disable 
  1067  *  autocentering.
  1068  *
  1069  *  Device must support the ::SDL_HAPTIC_AUTOCENTER feature.
  1070  *
  1071  *  \param haptic Haptic device to set autocentering on.
  1072  *  \param autocenter Value to set autocenter to, 0 disables autocentering.
  1073  *  \return 0 on success or -1 on error.
  1074  *  
  1075  *  \sa SDL_HapticQuery
  1076  */
  1077 extern DECLSPEC int SDLCALL SDL_HapticSetAutocenter(SDL_Haptic * haptic,
  1078                                                     int autocenter);
  1079 
  1080 /**
  1081  *  \brief Pauses a haptic device.
  1082  *  
  1083  *  Device must support the ::SDL_HAPTIC_PAUSE feature.  Call 
  1084  *  SDL_HapticUnpause() to resume playback.
  1085  *  
  1086  *  Do not modify the effects nor add new ones while the device is paused.
  1087  *  That can cause all sorts of weird errors.
  1088  *  
  1089  *  \param haptic Haptic device to pause.
  1090  *  \return 0 on success or -1 on error.
  1091  *  
  1092  *  \sa SDL_HapticUnpause
  1093  */
  1094 extern DECLSPEC int SDLCALL SDL_HapticPause(SDL_Haptic * haptic);
  1095 
  1096 /**
  1097  *  \brief Unpauses a haptic device.
  1098  *  
  1099  *  Call to unpause after SDL_HapticPause().
  1100  *  
  1101  *  \param haptic Haptic device to pause.
  1102  *  \return 0 on success or -1 on error.
  1103  *  
  1104  *  \sa SDL_HapticPause
  1105  */
  1106 extern DECLSPEC int SDLCALL SDL_HapticUnpause(SDL_Haptic * haptic);
  1107 
  1108 /**
  1109  *  \brief Stops all the currently playing effects on a haptic device.
  1110  *  
  1111  *  \param haptic Haptic device to stop.
  1112  *  \return 0 on success or -1 on error.
  1113  */
  1114 extern DECLSPEC int SDLCALL SDL_HapticStopAll(SDL_Haptic * haptic);
  1115 
  1116 
  1117 /* Ends C function definitions when using C++ */
  1118 #ifdef __cplusplus
  1119 /* *INDENT-OFF* */
  1120 }
  1121 /* *INDENT-ON* */
  1122 #endif
  1123 #include "close_code.h"
  1124 
  1125 #endif /* _SDL_haptic_h */
  1126 
  1127 /* vi: set ts=4 sw=4 expandtab: */