include/SDL_haptic.h
author Sam Lantinga <slouken@libsdl.org>
Sun, 02 Aug 2009 12:54:59 +0000
changeset 3220 6290f9bd097d
parent 2713 0906692aa6a4
child 3407 d3baf5ac4e37
permissions -rw-r--r--
Better check which includes #define used in stdint.h
     1 /*
     2     SDL - Simple DirectMedia Layer
     3     Copyright (C) 2008 Edgar Simo
     4 
     5     This library is free software; you can redistribute it and/or
     6     modify it under the terms of the GNU Lesser General Public
     7     License as published by the Free Software Foundation; either
     8     version 2.1 of the License, or (at your option) any later version.
     9 
    10     This library is distributed in the hope that it will be useful,
    11     but WITHOUT ANY WARRANTY; without even the implied warranty of
    12     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    13     Lesser General Public License for more details.
    14 
    15     You should have received a copy of the GNU Lesser General Public
    16     License along with this library; if not, write to the Free Software
    17     Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
    18 
    19     Sam Lantinga
    20     slouken@libsdl.org
    21 */
    22 
    23 /**
    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.
   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  * \def SDL_HAPTIC_PAUSE
   245  *
   246  * \brief Device can be paused.
   247  *
   248  * \sa SDL_HapticPause
   249  * \sa SDL_HapticUnpause
   250  */
   251 #define SDL_HAPTIC_PAUSE      (1<<15)   /* Device can be paused. */
   252 
   253 
   254 /*
   255  * Direction encodings
   256  */
   257 /**
   258  * \def SDL_HAPTIC_POLAR
   259  *
   260  * \brief Uses polar coordinates for the direction.
   261  *
   262  * \sa SDL_HapticDirection
   263  */
   264 #define SDL_HAPTIC_POLAR      0
   265 /**
   266  * \def SDL_HAPTIC_CARTESIAN
   267  *
   268  * \brief Uses cartesian coordinates for the direction.
   269  *
   270  * \sa SDL_HapticDirection
   271  */
   272 #define SDL_HAPTIC_CARTESIAN  1
   273 /**
   274  * \def SDL_HAPTIC_SPHERICAL
   275  *
   276  * \brief Uses spherical coordinates for the direction.
   277  *
   278  * \sa SDL_HapticDirection
   279  */
   280 #define SDL_HAPTIC_SPHERICAL  2
   281 
   282 
   283 /*
   284  * Misc defines.
   285  */
   286 /**
   287  * \def SDL_HAPTIC_INFINITY
   288  *
   289  * \brief Used to play a device an infinite number of times.
   290  *
   291  * \sa SDL_HapticRunEffect
   292  */
   293 #define SDL_HAPTIC_INFINITY   4294967295U
   294 
   295 
   296 /**
   297  * \struct SDL_HapticDirection
   298  *
   299  * \brief Structure that represents a haptic direction.
   300  *
   301  * Directions can be specified by:
   302  *   - SDL_HAPTIC_POLAR : Specified by polar coordinates.
   303  *   - SDL_HAPTIC_CARTESIAN : Specified by cartesian coordinates.
   304  *   - SDL_HAPTIC_SPHERICAL : Specified by spherical coordinates.
   305  *
   306  * Cardinal directions of the haptic device are relative to the positioning
   307  *  of the device.  North is considered to be away from the user.
   308  *
   309  * The following diagram represents the cardinal directions:
   310  * \code
   311  *              .--.
   312  *              |__| .-------.
   313  *              |=.| |.-----.|
   314  *              |--| ||     ||
   315  *              |  | |'-----'|
   316  *              |__|~')_____('
   317  *                [ COMPUTER ]
   318  *
   319  *
   320  *                  North (0,-1)
   321  *                      ^
   322  *                      |
   323  *                      |
   324  * (1,0)  West <----[ HAPTIC ]----> East (-1,0)
   325  *                      |
   326  *                      |
   327  *                      v
   328  *                   South (0,1)
   329  *
   330  *
   331  *                   [ USER ]
   332  *                     \|||/
   333  *                     (o o)
   334  *               ---ooO-(_)-Ooo---
   335  * \endcode
   336  *
   337  * If type is SDL_HAPTIC_POLAR, direction is encoded by hundredths of a 
   338  *  degree starting north and turning clockwise.  SDL_HAPTIC_POLAR only uses
   339  *  the first dir parameter.  The cardinal directions would be:
   340  *   - North: 0 (0 degrees)
   341  *   - East: 9000 (90 degrees)
   342  *   - South: 18000 (180 degrees)
   343  *   - West: 27000 (270 degrees)
   344  *
   345  * If type is SDL_HAPTIC_CARTESIAN, direction is encoded by three positions
   346  *  (X axis, Y axis and Z axis (with 3 axes)).  SDL_HAPTIC_CARTESIAN uses
   347  *  the first three dir parameters.  The cardinal directions would be:
   348  *   - North:  0,-1, 0
   349  *   - East:  -1, 0, 0
   350  *   - South:  0, 1, 0
   351  *   - West:   1, 0, 0
   352  *  The Z axis represents the height of the effect if supported, otherwise
   353  *  it's unused.  In cartesian encoding (1,2) would be the same as (2,4), you
   354  *  can use any multiple you want, only the direction matters.
   355  *
   356  * If type is SDL_HAPTIC_SPHERICAL, direction is encoded by two rotations.
   357  *  The first two  dir parameters are used.  The dir parameters are as follows
   358  *  (all values are in hundredths of degrees):
   359  *    1) Degrees from (1, 0) rotated towards (0, 1).
   360  *    2) Degrees towards (0, 0, 1) (device needs at least 3 axes).
   361  *
   362  *
   363  * Example of force coming from the south with all encodings (force coming
   364  *  from the south means the user will have to pull the stick to counteract):
   365  * \code
   366  * SDL_HapticDirection direction;
   367  *
   368  * // Cartesian directions
   369  * direction.type = SDL_HAPTIC_CARTESIAN; // Using cartesian direction encoding.
   370  * direction.dir[0] = 0; // X position
   371  * direction.dir[1] = 1; // Y position
   372  * // Assuming the device has 2 axes, we don't need to specify third parameter.
   373  *
   374  * // Polar directions
   375  * direction.type = SDL_HAPTIC_POLAR; // We'll be using polar direction encoding.
   376  * direction.dir[0] = 18000; // Polar only uses first parameter
   377  *
   378  * // Spherical coordinates
   379  * direction.type = SDL_HAPTIC_SPHERICAL; // Spherical encoding
   380  * direction.dir[0] = 9000; // Since we only have two axes we don't need more parameters.
   381  * \endcode
   382  *
   383  * \sa SDL_HAPTIC_POLAR
   384  * \sa SDL_HAPTIC_CARTESIAN
   385  * \sa SDL_HAPTIC_SPHERICAL
   386  * \sa SDL_HapticEffect
   387  * \sa SDL_HapticNumAxes
   388  */
   389 typedef struct SDL_HapticDirection
   390 {
   391     Uint8 type;         /**< The type of encoding. */
   392     Uint16 dir[3];      /**< The encoded direction. */
   393 } SDL_HapticDirection;
   394 
   395 
   396 /**
   397  * \struct SDL_HapticConstant
   398  *
   399  * \brief A structure containing a template for a Constant effect.
   400  *
   401  * The struct is exclusive to the SDL_HAPTIC_CONSTANT effect.
   402  *
   403  * A constant effect applies a constant force in the specified direction
   404  *  to the joystick.
   405  *
   406  * \sa SDL_HAPTIC_CONSTANT
   407  * \sa SDL_HapticEffect
   408  */
   409 typedef struct SDL_HapticConstant
   410 {
   411     /* Header */
   412     Uint16 type;            /**< SDL_HAPTIC_CONSTANT */
   413     SDL_HapticDirection direction;  /**< Direction of the effect. */
   414 
   415     /* Replay */
   416     Uint32 length;          /**< Duration of the effect. */
   417     Uint16 delay;           /**< Delay before starting the effect. */
   418 
   419     /* Trigger */
   420     Uint16 button;          /**< Button that triggers the effect. */
   421     Uint16 interval;        /**< How soon it can be triggered again after button. */
   422 
   423     /* Constant */
   424     Sint16 level;           /**< Strength of the constant effect. */
   425 
   426     /* Envelope */
   427     Uint16 attack_length;   /**< Duration of the attack. */
   428     Uint16 attack_level;    /**< Level at the start of the attack. */
   429     Uint16 fade_length;     /**< Duration of the fade. */
   430     Uint16 fade_level;      /**< Level at the end of the fade. */
   431 } SDL_HapticConstant;
   432 /**
   433  * \struct SDL_HapticPeriodic
   434  *
   435  * \brief A structure containing a template for a Periodic effect.
   436  *
   437  * The struct handles the following effects:
   438  *   - SDL_HAPTIC_SINE
   439  *   - SDL_HAPTIC_SQUARE
   440  *   - SDL_HAPTIC_TRIANGLE
   441  *   - SDL_HAPTIC_SAWTOOTHUP
   442  *   - SDL_HAPTIC_SAWTOOTHDOWN
   443  *
   444  * A periodic effect consists in a wave-shaped effect that repeats itself
   445  *  over time.  The type determines the shape of the wave and the parameters
   446  *  determine the dimensions of the wave.
   447  *
   448  * Phase is given by hundredth of a cyle meaning that giving the phase a value
   449  *  of 9000 will displace it 25% of it's period.  Here are sample values:
   450  *    -     0: No phase displacement.
   451  *    -  9000: Displaced 25% of it's period.
   452  *    - 18000: Displaced 50% of it's period.
   453  *    - 27000: Displaced 75% of it's period.
   454  *    - 36000: Displaced 100% of it's period, same as 0, but 0 is preffered.
   455  *
   456  * Examples:
   457  * \code
   458  * SDL_HAPTIC_SINE
   459  *   __      __      __      __
   460  *  /  \    /  \    /  \    /
   461  * /    \__/    \__/    \__/
   462  *
   463  * SDL_HAPTIC_SQUARE
   464  *  __    __    __    __    __
   465  * |  |  |  |  |  |  |  |  |  |
   466  * |  |__|  |__|  |__|  |__|  |
   467  *
   468  * SDL_HAPTIC_TRIANGLE
   469  *   /\    /\    /\    /\    /\
   470  *  /  \  /  \  /  \  /  \  /
   471  * /    \/    \/    \/    \/
   472  *
   473  * SDL_HAPTIC_SAWTOOTHUP
   474  *   /|  /|  /|  /|  /|  /|  /|
   475  *  / | / | / | / | / | / | / |
   476  * /  |/  |/  |/  |/  |/  |/  |
   477  *
   478  * SDL_HAPTIC_SAWTOOTHDOWN
   479  * \  |\  |\  |\  |\  |\  |\  |
   480  *  \ | \ | \ | \ | \ | \ | \ |
   481  *   \|  \|  \|  \|  \|  \|  \|
   482  * \endcode
   483  *
   484  * \sa SDL_HAPTIC_SINE
   485  * \sa SDL_HAPTIC_SQUARE
   486  * \sa SDL_HAPTIC_TRIANGLE
   487  * \sa SDL_HAPTIC_SAWTOOTHUP
   488  * \sa SDL_HAPTIC_SAWTOOTHDOWN
   489  * \sa SDL_HapticEffect
   490  */
   491 typedef struct SDL_HapticPeriodic
   492 {
   493     /* Header */
   494     Uint16 type;        /**< SDL_HAPTIC_SINE, SDL_HAPTIC_SQUARE,
   495                              SDL_HAPTIC_TRIANGLE, SDL_HAPTIC_SAWTOOTHUP or
   496                              SDL_HAPTIC_SAWTOOTHDOWN */
   497     SDL_HapticDirection direction;  /**< Direction of the effect. */
   498 
   499     /* Replay */
   500     Uint32 length;      /**< Duration of the effect. */
   501     Uint16 delay;       /**< Delay before starting the effect. */
   502 
   503     /* Trigger */
   504     Uint16 button;      /**< Button that triggers the effect. */
   505     Uint16 interval;    /**< How soon it can be triggered again after button. */
   506 
   507     /* Periodic */
   508     Uint16 period;      /**< Period of the wave. */
   509     Sint16 magnitude;   /**< Peak value. */
   510     Sint16 offset;      /**< Mean value of the wave. */
   511     Uint16 phase;       /**< Horizontal shift given by hundredth of a cycle. */
   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_HapticPeriodic;
   519 /**
   520  * \struct SDL_HapticCondition
   521  *
   522  * \brief A structure containing a template for a Condition effect.
   523  *
   524  * The struct handles the following effects:
   525  *   - SDL_HAPTIC_SPRING: Effect based on axes position.
   526  *   - SDL_HAPTIC_DAMPER: Effect based on axes velocity.
   527  *   - SDL_HAPTIC_INERTIA: Effect based on axes acceleration.
   528  *   - SDL_HAPTIC_FRICTION: Effect based on axes movement.
   529  *
   530  * Direction is handled by condition internals instead of a direction member.
   531  *  The condition effect specific members have three parameters.  The first
   532  *  refers to the X axis, the second refers to the Y axis and the third
   533  *  refers to the Z axis.  The right terms refer to the positive side of the
   534  *  axis and the left terms refer to the negative side of the axis.  Please 
   535  *  refer to the SDL_HapticDirection  diagram for which side is positive and
   536  *  which is negative.
   537  *
   538  * \sa SDL_HapticDirection
   539  * \sa SDL_HAPTIC_SPRING
   540  * \sa SDL_HAPTIC_DAMPER
   541  * \sa SDL_HAPTIC_INERTIA
   542  * \sa SDL_HAPTIC_FRICTION
   543  * \sa SDL_HapticEffect
   544  */
   545 typedef struct SDL_HapticCondition
   546 {
   547     /* Header */
   548     Uint16 type;            /**< SDL_HAPTIC_SPRING, SDL_HAPTIC_DAMPER,
   549                                  SDL_HAPTIC_INERTIA or SDL_HAPTIC_FRICTION */
   550     SDL_HapticDirection direction;  /**< Direction of the effect - Not used ATM. */
   551 
   552     /* Replay */
   553     Uint32 length;          /**< Duration of the effect. */
   554     Uint16 delay;           /**< Delay before starting the effect. */
   555 
   556     /* Trigger */
   557     Uint16 button;          /**< Button that triggers the effect. */
   558     Uint16 interval;        /**< How soon it can be triggered again after button. */
   559 
   560     /* Condition */
   561     Uint16 right_sat[3];    /**< Level when joystick is to the positive side. */
   562     Uint16 left_sat[3];     /**< Level when joystick is to the negative side. */
   563     Sint16 right_coeff[3];  /**< How fast to increase the force towards the positive side. */
   564     Sint16 left_coeff[3];   /**< How fast to increase the force towards the negative side. */
   565     Uint16 deadband[3];     /**< Size of the dead zone. */
   566     Sint16 center[3];       /**< Position of the dead zone. */
   567 } SDL_HapticCondition;
   568 /**
   569  * \struct SDL_HapticRamp
   570  *
   571  * \brief A structure containing a template for a Ramp effect.
   572  *
   573  * This struct is exclusively for the SDL_HAPTIC_RAMP effect.
   574  *
   575  * The ramp effect starts at start strength and ends at end strength.
   576  *  It augments in linear fashion.  If you use attack and fade with a ramp
   577  *  they effects get added to the ramp effect making the effect become
   578  *  quadratic instead of linear.
   579  *
   580  * \sa SDL_HAPTIC_RAMP
   581  * \sa SDL_HapticEffect
   582  */
   583 typedef struct SDL_HapticRamp
   584 {
   585     /* Header */
   586     Uint16 type;            /**< SDL_HAPTIC_RAMP */
   587     SDL_HapticDirection direction;  /**< Direction of the effect. */
   588 
   589     /* Replay */
   590     Uint32 length;          /**< Duration of the effect. */
   591     Uint16 delay;           /**< Delay before starting the effect. */
   592 
   593     /* Trigger */
   594     Uint16 button;          /**< Button that triggers the effect. */
   595     Uint16 interval;        /**< How soon it can be triggered again after button. */
   596 
   597     /* Ramp */
   598     Sint16 start;           /**< Beginning strength level. */
   599     Sint16 end;             /**< Ending strength level. */
   600 
   601     /* Envelope */
   602     Uint16 attack_length;   /**< Duration of the attack. */
   603     Uint16 attack_level;    /**< Level at the start of the attack. */
   604     Uint16 fade_length;     /**< Duration of the fade. */
   605     Uint16 fade_level;      /**< Level at the end of the fade. */
   606 } SDL_HapticRamp;
   607 /**
   608  * \struct SDL_HapticCustom
   609  *
   610  * \brief A structure containing a template for the SDL_HAPTIC_CUSTOM effect.
   611  *
   612  * A custom force feedback effect is much like a periodic effect, where the
   613  *  application can define it's exact shape.  You will have to allocate the
   614  *  data yourself.  Data should consist of channels * samples Uint16 samples.
   615  *
   616  * If channels is one, the effect is rotated using the defined direction.
   617  *  Otherwise it uses the samples in data for the different axes.
   618  *
   619  * \sa SDL_HAPTIC_CUSTOM
   620  * \sa SDL_HapticEffect
   621  */
   622 typedef struct SDL_HapticCustom
   623 {
   624     /* Header */
   625     Uint16 type;            /**< SDL_HAPTIC_CUSTOM */
   626     SDL_HapticDirection direction;  /**< Direction of the effect. */
   627 
   628     /* Replay */
   629     Uint32 length;          /**< Duration of the effect. */
   630     Uint16 delay;           /**< Delay before starting the effect. */
   631 
   632     /* Trigger */
   633     Uint16 button;          /**< Button that triggers the effect. */
   634     Uint16 interval;        /**< How soon it can be triggered again after button. */
   635 
   636     /* Custom */
   637     Uint8 channels;         /**< Axes to use, minimum of one. */
   638     Uint16 period;          /**< Sample periods. */
   639     Uint16 samples;         /**< Amount of samples. */
   640     Uint16 *data;           /**< Should contain channels*samples items. */
   641 
   642     /* Envelope */
   643     Uint16 attack_length;   /**< Duration of the attack. */
   644     Uint16 attack_level;    /**< Level at the start of the attack. */
   645     Uint16 fade_length;     /**< Duration of the fade. */
   646     Uint16 fade_level;      /**< Level at the end of the fade. */
   647 } SDL_HapticCustom;
   648 /**
   649  * \union SDL_HapticEffect
   650  *
   651  * \brief The generic template for any haptic effect.
   652  *
   653  * All values max at 32767 (0x7FFF).  Signed values also can be negative.
   654  *  Time values unless specified otherwise are in milliseconds.
   655  *
   656  * You can also pass SDL_HAPTIC_INFINITY to length instead of a 0-32767 value.
   657  *  Neither delay, interval, attack_length nor fade_length support 
   658  *  SDL_HAPTIC_INFINITY.  Fade will also not be used since effect never ends.
   659  *
   660  * Additionally, the SDL_HAPTIC_RAMP effect does not support a duration of
   661  *  SDL_HAPTIC_INFINITY.
   662  *
   663  * Button triggers may not be supported on all devices, it is advised to not
   664  *  use them if possible.  Buttons start at index 1 instead of index 0 like
   665  *  they joystick.
   666  *
   667  * If both attack_length and fade_level are 0, the envelope is not used,
   668  *  otherwise both values are used.
   669  *
   670  * Common parts:
   671  * \code
   672  * // Replay - All effects have this
   673  * Uint32 length;        // Duration of effect (ms).
   674  * Uint16 delay;         // Delay before starting effect.
   675  *
   676  * // Trigger - All effects have this
   677  * Uint16 button;        // Button that triggers effect.
   678  * Uint16 interval;      // How soon before effect can be triggered again.
   679  *
   680  * // Envelope - All effects except condition effects have this
   681  * Uint16 attack_length; // Duration of the attack (ms).
   682  * Uint16 attack_level;  // Level at the start of the attack.
   683  * Uint16 fade_length;   // Duration of the fade out (ms).
   684  * Uint16 fade_level;    // Level at the end of the fade.
   685  * \endcode
   686  *
   687  *
   688  * Here we have an example of a constant effect evolution in time:
   689  *
   690  * \code
   691  * Strength
   692  * ^
   693  * |
   694  * |    effect level -->  _________________
   695  * |                     /                 \
   696  * |                    /                   \
   697  * |                   /                     \
   698  * |                  /                       \ 
   699  * | attack_level --> |                        \
   700  * |                  |                        |  <---  fade_level
   701  * |
   702  * +--------------------------------------------------> Time
   703  *                    [--]                 [---]
   704  *                    attack_length        fade_length
   705  * 
   706  * [------------------][-----------------------]
   707  * delay               length
   708  * \endcode
   709  *
   710  * Note either the attack_level or the fade_level may be above the actual
   711  *  effect level.
   712  *
   713  * \sa SDL_HapticConstant
   714  * \sa SDL_HapticPeriodic
   715  * \sa SDL_HapticCondition
   716  * \sa SDL_HapticRamp
   717  * \sa SDL_HapticCustom
   718  */
   719 typedef union SDL_HapticEffect
   720 {
   721     /* Common for all force feedback effects */
   722     Uint16 type;                    /**< Effect type. */
   723     SDL_HapticConstant constant;    /**< Constant effect. */
   724     SDL_HapticPeriodic periodic;    /**< Periodic effect. */
   725     SDL_HapticCondition condition;  /**< Condition effect. */
   726     SDL_HapticRamp ramp;            /**< Ramp effect. */
   727     SDL_HapticCustom custom;        /**< Custom effect. */
   728 } SDL_HapticEffect;
   729 
   730 
   731 /* Function prototypes */
   732 /**
   733  * \fn int SDL_NumHaptics(void)
   734  *
   735  * \brief Count the number of joysticks attached to the system.
   736  *
   737  *    \return Number of haptic devices detected on the system.
   738  */
   739 extern DECLSPEC int SDLCALL SDL_NumHaptics(void);
   740 
   741 /**
   742  * \fn const char * SDL_HapticName(int device_index)
   743  *
   744  * \brief Get the implementation dependent name of a Haptic device.
   745  * This can be called before any joysticks are opened.
   746  * If no name can be found, this function returns NULL.
   747  *
   748  *    \param device_index Index of the device to get it's name.
   749  *    \return Name of the device or NULL on error.
   750  *
   751  * \sa SDL_NumHaptics
   752  */
   753 extern DECLSPEC const char *SDLCALL SDL_HapticName(int device_index);
   754 
   755 /**
   756  * \fn SDL_Haptic * SDL_HapticOpen(int device_index)
   757  *
   758  * \brief Opens a Haptic device for usage - the index passed as an
   759  * argument refers to the N'th Haptic device on this system.
   760  *
   761  * When opening a haptic device, it's gain will be set to maximum and
   762  *  autocenter will be disabled.  To modify these values use
   763  *  SDL_HapticSetGain and SDL_HapticSetAutocenter
   764  *
   765  *    \param device_index Index of the device to open.
   766  *    \return Device identifier or NULL on error.
   767  *
   768  * \sa SDL_HapticIndex
   769  * \sa SDL_HapticOpenFromMouse
   770  * \sa SDL_HapticOpenFromJoystick
   771  * \sa SDL_HapticClose
   772  * \sa SDL_HapticSetGain
   773  * \sa SDL_HapticSetAutocenter
   774  * \sa SDL_HapticPause
   775  * \sa SDL_HapticStopAll
   776  */
   777 extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpen(int device_index);
   778 
   779 /**
   780  * \fn int SDL_HapticOpened(int device_index)
   781  *
   782  * \brief Checks if the haptic device at index has been opened.
   783  *
   784  *    \param device_index Index to check to see if it has been opened.
   785  *    \return 1 if it has been opened or 0 if it hasn't.
   786  * 
   787  * \sa SDL_HapticOpen
   788  * \sa SDL_HapticIndex
   789  */
   790 extern DECLSPEC int SDLCALL SDL_HapticOpened(int device_index);
   791 
   792 /**
   793  * \fn int SDL_HapticIndex(SDL_Haptic * haptic)
   794  *
   795  * \brief Gets the index of a haptic device.
   796  *
   797  *    \param haptic Haptic device to get the index of.
   798  *    \return The index of the haptic device or -1 on error.
   799  *
   800  * \sa SDL_HapticOpen
   801  * \sa SDL_HapticOpened
   802  */
   803 extern DECLSPEC int SDLCALL SDL_HapticIndex(SDL_Haptic * haptic);
   804 
   805 /**
   806  * \fn int SDL_MouseIsHaptic(void)
   807  *
   808  * \brief Gets whether or not the current mouse has haptic capabilities.
   809  *
   810  *    \return SDL_TRUE if the mouse is haptic, SDL_FALSE if it isn't.
   811  *
   812  * \sa SDL_HapticOpenFromMouse
   813  */
   814 extern DECLSPEC int SDLCALL SDL_MouseIsHaptic(void);
   815 
   816 /**
   817  * \fn SDL_Haptic * SDL_HapticOpenFromMouse(void)
   818  *
   819  * \brief Tries to open a haptic device from the current mouse.
   820  *
   821  *    \return The haptic device identifier or NULL on error.
   822  *
   823  * \sa SDL_MouseIsHaptic
   824  * \sa SDL_HapticOpen
   825  */
   826 extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromMouse(void);
   827 
   828 /**
   829  * \fn int SDL_JoystickIsHaptic(SDL_Joystick * joystick)
   830  *
   831  * \brief Checks to see if a joystick has haptic features.
   832  *
   833  *    \param joystick Joystick to test for haptic capabilities.
   834  *    \return SDL_TRUE if the joystick is haptic, SDL_FALSE if it isn't
   835  *            or -1 if an error ocurred.
   836  *
   837  * \sa SDL_HapticOpenFromJoystick
   838  */
   839 extern DECLSPEC int SDLCALL SDL_JoystickIsHaptic(SDL_Joystick * joystick);
   840 
   841 /**
   842  * \fn SDL_Haptic * SDL_HapticOpenFromJoystick(SDL_Joystick * joystick)
   843  *
   844  * \brief Opens a Haptic device for usage from a Joystick device.  Still has
   845  * to be closed seperately to the joystick.
   846  *
   847  * When opening from a joystick you should first close the haptic device before
   848  *  closing the joystick device.  If not, on some implementations the haptic
   849  *  device will also get unallocated and you'll be unable to use force feedback
   850  *  on that device.
   851  *
   852  *    \param joystick Joystick to create a haptic device from.
   853  *    \return A valid haptic device identifier on success or NULL on error.
   854  *
   855  * \sa SDL_HapticOpen
   856  * \sa SDL_HapticClose
   857  */
   858 extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromJoystick(SDL_Joystick *
   859                                                                joystick);
   860 
   861 /**
   862  * \fn void SDL_HapticClose(SDL_Haptic * haptic)
   863  *
   864  * \brief Closes a Haptic device previously opened with SDL_HapticOpen.
   865  *
   866  *    \param haptic Haptic device to close.
   867  */
   868 extern DECLSPEC void SDLCALL SDL_HapticClose(SDL_Haptic * haptic);
   869 
   870 /**
   871  * \fn int SDL_HapticNumEffects(SDL_Haptic * haptic)
   872  *
   873  * \brief Returns the number of effects a haptic device can store.
   874  *
   875  * On some platforms this isn't fully supported, and therefore is an
   876  *  aproximation.  Always check to see if your created effect was actually
   877  *  created and do not rely solely on HapticNumEffects.
   878  *
   879  *    \param haptic The haptic device to query effect max.
   880  *    \return The number of effects the haptic device can store or
   881  *            -1 on error.
   882  *
   883  * \sa SDL_HapticNumEffectsPlaying
   884  * \sa SDL_HapticQuery
   885  */
   886 extern DECLSPEC int SDLCALL SDL_HapticNumEffects(SDL_Haptic * haptic);
   887 
   888 /**
   889  * \fn int SDL_HapticNumEffectsPlaying(SDL_Haptic * haptic)
   890  *
   891  * \brief Returns the number of effects a haptic device can play at the same time.
   892  *
   893  * This is not supported on all platforms, but will always return a value.  Added
   894  *  here for the sake of completness.
   895  *
   896  *    \param haptic The haptic device to query maximum playing effect.s
   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  * \fn unsigned int SDL_HapticQuery(SDL_Haptic * haptic)
   907  *
   908  * \brief Gets the haptic devices supported features in bitwise matter.
   909  *
   910  * Example: 
   911  * \code
   912  * if (SDL_HapticQueryEffects(haptic) & SDL_HAPTIC_CONSTANT) {
   913  *    printf("We have constant haptic effect!");
   914  * }
   915  * \endcode
   916  *    
   917  *
   918  *    \param haptic The haptic device to query.
   919  *    \return Haptic features in bitwise manner (OR'd).
   920  *
   921  * \sa SDL_HapticNumEffects
   922  * \sa SDL_HapticEffectSupported
   923  */
   924 extern DECLSPEC unsigned int SDLCALL SDL_HapticQuery(SDL_Haptic * haptic);
   925 
   926 
   927 /**
   928  * \fn int SDL_HapticNumAxes(SDL_Haptic * haptic)
   929  *
   930  * \brief Gets the number of haptic axes the device has.
   931  *
   932  * \sa SDL_HapticDirection
   933  */
   934 extern DECLSPEC int SDLCALL SDL_HapticNumAxes(SDL_Haptic * haptic);
   935 
   936 /**
   937  * \fn int SDL_HapticEffectSupported(SDL_Haptic * haptic, SDL_HapticEffect * effect)
   938  *
   939  * \brief Checks to see if effect is supported by haptic.
   940  *
   941  *    \param haptic Haptic device to check on.
   942  *    \param effect Effect to check to see if it is supported.
   943  *    \return SDL_TRUE if effect is supported, SDL_FALSE if it isn't or 
   944  *            -1 on error.
   945  * 
   946  * \sa SDL_HapticQuery
   947  * \sa SDL_HapticNewEffect
   948  */
   949 extern DECLSPEC int SDLCALL SDL_HapticEffectSupported(SDL_Haptic * haptic,
   950                                                       SDL_HapticEffect *
   951                                                       effect);
   952 
   953 /**
   954  * \fn int SDL_HapticNewEffect(SDL_Haptic * haptic, SDL_HapticEffect * effect)
   955  *
   956  * \brief Creates a new haptic effect on the device.
   957  *
   958  *    \param haptic Haptic device to create the effect on.
   959  *    \param effect Properties of the effect to create.
   960  *    \return The id of the effect on success or -1 on error.
   961  *
   962  * \sa SDL_HapticUpdateEffect
   963  * \sa SDL_HapticRunEffect
   964  * \sa SDL_HapticDestroyEffect
   965  */
   966 extern DECLSPEC int SDLCALL SDL_HapticNewEffect(SDL_Haptic * haptic,
   967                                                 SDL_HapticEffect * effect);
   968 
   969 /**
   970  * \fn int SDL_HapticUpdateEffect(SDL_Haptic * haptic, int effect, SDL_HapticEffect * data)
   971  *
   972  * \brief Updates the properties of an effect.
   973  *
   974  * Can be used dynamically, although behaviour when dynamically changing
   975  * direction may be strange.  Specifically the effect may reupload itself
   976  * and start playing from the start.  You cannot change the type either when
   977  * running UpdateEffect.
   978  *
   979  *    \param haptic Haptic device that has the effect.
   980  *    \param effect Effect to update.
   981  *    \param data New effect properties to use.
   982  *    \return The id of the effect on success or -1 on error.
   983  *
   984  * \sa SDL_HapticNewEffect
   985  * \sa SDL_HapticRunEffect
   986  * \sa SDL_HapticDestroyEffect
   987  */
   988 extern DECLSPEC int SDLCALL SDL_HapticUpdateEffect(SDL_Haptic * haptic,
   989                                                    int effect,
   990                                                    SDL_HapticEffect * data);
   991 
   992 /**
   993  * \fn int SDL_HapticRunEffect(SDL_Haptic * haptic, int effect, Uint32 iterations)
   994  *
   995  * \brief Runs the haptic effect on it's assosciated haptic device.
   996  *
   997  * If iterations are SDL_HAPTIC_INFINITY, it'll run the effect over and over
   998  *  repeating the envelope (attack and fade) every time.  If you only want the
   999  *  effect to last forever, set SDL_HAPTIC_INFINITY in the effect's length
  1000  *  parameter.
  1001  *
  1002  *    \param haptic Haptic device to run the effect on.
  1003  *    \param effect Identifier of the haptic effect to run.
  1004  *    \param iterations Number of iterations to run the effect. Use
  1005  *           SDL_HAPTIC_INFINITY for infinity.
  1006  *    \return 0 on success or -1 on error.
  1007  *
  1008  * \sa SDL_HapticStopEffect
  1009  * \sa SDL_HapticDestroyEffect
  1010  * \sa SDL_HapticGetEffectStatus
  1011  */
  1012 extern DECLSPEC int SDLCALL SDL_HapticRunEffect(SDL_Haptic * haptic,
  1013                                                 int effect,
  1014                                                 Uint32 iterations);
  1015 
  1016 /**
  1017  * \fn int SDL_HapticStopEffect(SDL_Haptic * haptic, int effect)
  1018  *
  1019  * \brief Stops the haptic effect on it's assosciated haptic device.
  1020  *
  1021  *    \param haptic Haptic device to stop the effect on.
  1022  *    \param effect Identifier of the effect to stop.
  1023  *    \return 0 on success or -1 on error.
  1024  *
  1025  * \sa SDL_HapticRunEffect
  1026  * \sa SDL_HapticDestroyEffect
  1027  */
  1028 extern DECLSPEC int SDLCALL SDL_HapticStopEffect(SDL_Haptic * haptic,
  1029                                                  int effect);
  1030 
  1031 /**
  1032  * \fn void SDL_HapticDestroyEffect(SDL_Haptic * haptic, int effect)
  1033  *
  1034  * \brief Destroys a haptic effect on the device.  This will stop the effect
  1035  * if it's running.  Effects are automatically destroyed when the device is
  1036  * closed.
  1037  *
  1038  *    \param haptic Device to destroy the effect on.
  1039  *    \param effect Identifier of the effect to destroy.
  1040  * 
  1041  * \sa SDL_HapticNewEffect
  1042  */
  1043 extern DECLSPEC void SDLCALL SDL_HapticDestroyEffect(SDL_Haptic * haptic,
  1044                                                      int effect);
  1045 
  1046 /**
  1047  * \fn int SDL_HapticGetEffectStatus(SDL_Haptic *haptic, int effect)
  1048  *
  1049  * \brief Gets the status of the current effect on the haptic device.
  1050  *
  1051  * Device must support the SDL_HAPTIC_STATUS feature.
  1052  *
  1053  *    \param haptic Haptic device to query the effect status on.
  1054  *    \param effect Identifier of the effect to query it's status.
  1055  *    \return 0 if it isn't playing, SDL_HAPTIC_PLAYING if it is playing
  1056  *            or -1 on error.
  1057  *
  1058  * \sa SDL_HapticRunEffect
  1059  * \sa SDL_HapticStopEffect
  1060  */
  1061 extern DECLSPEC int SDLCALL SDL_HapticGetEffectStatus(SDL_Haptic * haptic,
  1062                                                       int effect);
  1063 
  1064 /**
  1065  * \fn int SDL_HapticSetGain(SDL_Haptic * haptic, int gain)
  1066  *
  1067  * \brief Sets the global gain of the device.  Gain should be between 0 and 100.
  1068  *
  1069  * Device must support the SDL_HAPTIC_GAIN feature.
  1070  *
  1071  * The user may specify the maxmimum gain by setting the environment variable
  1072  *  SDL_HAPTIC_GAIN_MAX which should be between 0 and 100.  All calls to
  1073  *  SDL_HapticSetGain will scale linearly using SDL_HAPTIC_GAIN_MAX as the
  1074  *  maximum.
  1075  *
  1076  *    \param haptic Haptic device to set the gain on.
  1077  *    \param gain Value to set the gain to, should be between 0 and 100.
  1078  *    \return 0 on success or -1 on error.
  1079  *
  1080  * \sa SDL_HapticQuery
  1081  */
  1082 extern DECLSPEC int SDLCALL SDL_HapticSetGain(SDL_Haptic * haptic, int gain);
  1083 
  1084 /**
  1085  * \fn int SDL_HapticSetAutocenter(SDL_Haptic * haptic, int autocenter)
  1086  *
  1087  * \brief Sets the global autocenter of the device.  Autocenter should be between
  1088  * 0 and 100.  Setting it to 0 will disable autocentering.
  1089  *
  1090  * Device must support the SDL_HAPTIC_AUTOCENTER feature.
  1091  *
  1092  *    \param haptic Haptic device to set autocentering on.
  1093  *    \param autocenter Value to set autocenter to, 0 disables autocentering.
  1094  *    \return 0 on success or -1 on error.
  1095  *
  1096  * \sa SDL_HapticQuery
  1097  */
  1098 extern DECLSPEC int SDLCALL SDL_HapticSetAutocenter(SDL_Haptic * haptic,
  1099                                                     int autocenter);
  1100 
  1101 /**
  1102  * \fn extern DECLSPEC int SDLCALL SDL_HapticPause(SDL_Haptic * haptic)
  1103  *
  1104  * \brief Pauses a haptic device.
  1105  *
  1106  * Device must support the SDL_HAPTIC_PAUSE feature.  Call SDL_HapticUnpause
  1107  *  to resume playback.
  1108  *
  1109  * Do not modify the effects nor add new ones while the device is paused.
  1110  *  That can cause all sorts of weird errors.
  1111  *
  1112  *    \param haptic Haptic device to pause.
  1113  *    \return 0 on success or -1 on error.
  1114  *
  1115  * \sa SDL_HapticUnpause
  1116  */
  1117 extern DECLSPEC int SDLCALL SDL_HapticPause(SDL_Haptic * haptic);
  1118 
  1119 /**
  1120  * \fn extern DECLSPEC int SDLCALL SDL_HapticUnpause(SDL_Haptic * haptic)
  1121  *
  1122  * \brief Unpauses a haptic device.
  1123  *
  1124  * Call to unpause after SDL_HapticPause.
  1125  *
  1126  *    \param haptic Haptic device to pause.
  1127  *    \return 0 on success or -1 on error.
  1128  *
  1129  * \sa SDL_HapticPause
  1130  */
  1131 extern DECLSPEC int SDLCALL SDL_HapticUnpause(SDL_Haptic * haptic);
  1132 
  1133 /**
  1134  * \fn extern DECSLPEC int SDLCALL SDL_HapticStopAll(SDL_Haptic * haptic)
  1135  *
  1136  * \brief Stops all the currently playing effects on a haptic device.
  1137  *
  1138  *    \param haptic Haptic device to stop.
  1139  *    \return 0 on success or -1 on error.
  1140  */
  1141 extern DECLSPEC int SDLCALL SDL_HapticStopAll(SDL_Haptic * haptic);
  1142 
  1143 
  1144 /* Ends C function definitions when using C++ */
  1145 #ifdef __cplusplus
  1146 /* *INDENT-OFF* */
  1147 }
  1148 /* *INDENT-ON* */
  1149 #endif
  1150 #include "close_code.h"
  1151 
  1152 #endif /* _SDL_haptic_h */
  1153 
  1154 /* vi: set ts=4 sw=4 expandtab: */