include/SDL_haptic.h
 author Edgar Simo Sun, 24 Aug 2008 17:17:45 +0000 branch gsoc2008_force_feedback changeset 2645 269ba4f28d0e parent 2630 776f7f800131 child 2646 9408be170bff permissions -rw-r--r--
Added support for pausing/unpausing haptic devices.
     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    Uint8 type; /**< The type of encoding. */

   391    Uint16 dir[3]; /**< The encoded direction. */

   392 } SDL_HapticDirection;

   393

   394

   395 /**

   396  * \struct SDL_HapticConstant

   397  *

   398  * \brief A structure containing a template for a Constant effect.

   399  *

   400  * The struct is exclusive to the SDL_HAPTIC_CONSTANT effect.

   401  *

   402  * A constant effect applies a constant force in the specified direction

   403  *  to the joystick.

   404  *

   405  * \sa SDL_HAPTIC_CONSTANT

   406  * \sa SDL_HapticEffect

   407  */

   408 typedef struct SDL_HapticConstant {

   409    /* Header */

   410    Uint16 type; /**< SDL_HAPTIC_CONSTANT */

   411    SDL_HapticDirection direction; /**< Direction of the effect. */

   412

   413    /* Replay */

   414    Uint32 length; /**< Duration of the effect. */

   415    Uint16 delay; /**< Delay before starting the effect. */

   416

   417    /* Trigger */

   418    Uint16 button; /**< Button that triggers the effect. */

   419    Uint16 interval; /**< How soon it can be triggered again after button. */

   420

   421    /* Constant */

   422    Sint16 level; /**< Strength of the constant effect. */

   423

   424    /* Envelope */

   425    Uint16 attack_length; /**< Duration of the attack. */

   426    Uint16 attack_level; /**< Level at the start of the attack. */

   427    Uint16 fade_length; /**< Duration of the fade. */

   428    Uint16 fade_level; /**< Level at the end of the fade. */

   429 } SDL_HapticConstant;

   430 /**

   431  * \struct SDL_HapticPeriodic

   432  *

   433  * \brief A structure containing a template for a Periodic effect.

   434  *

   435  * The struct handles the following effects:

   436  *   - SDL_HAPTIC_SINE

   437  *   - SDL_HAPTIC_SQUARE

   438  *   - SDL_HAPTIC_TRIANGLE

   439  *   - SDL_HAPTIC_SAWTOOTHUP

   440  *   - SDL_HAPTIC_SAWTOOTHDOWN

   441  *

   442  * A periodic effect consists in a wave-shaped effect that repeats itself

   443  *  over time.  The type determines the shape of the wave and the parameters

   444  *  determine the dimensions of the wave.

   445  *

   446  * Phase is given by hundredth of a cyle meaning that giving the phase a value

   447  *  of 9000 will displace it 25% of it's period.  Here are sample values:

   448  *    -     0: No phase displacement.

   449  *    -  9000: Displaced 25% of it's period.

   450  *    - 18000: Displaced 50% of it's period.

   451  *    - 27000: Displaced 75% of it's period.

   452  *    - 36000: Displaced 100% of it's period, same as 0, but 0 is preffered.

   453  *

   454  * Examples:

   455  * \code

   456  * SDL_HAPTIC_SINE

   457  *   __      __      __      __

   458  *  /  \    /  \    /  \    /

   459  * /    \__/    \__/    \__/

   460  *

   461  * SDL_HAPTIC_SQUARE

   462  *  __    __    __    __    __

   463  * |  |  |  |  |  |  |  |  |  |

   464  * |  |__|  |__|  |__|  |__|  |

   465  *

   466  * SDL_HAPTIC_TRIANGLE

   467  *   /\    /\    /\    /\    /\

   468  *  /  \  /  \  /  \  /  \  /

   469  * /    \/    \/    \/    \/

   470  *

   471  * SDL_HAPTIC_SAWTOOTHUP

   472  *   /|  /|  /|  /|  /|  /|  /|

   473  *  / | / | / | / | / | / | / |

   474  * /  |/  |/  |/  |/  |/  |/  |

   475  *

   476  * SDL_HAPTIC_SAWTOOTHDOWN

   477  * \  |\  |\  |\  |\  |\  |\  |

   478  *  \ | \ | \ | \ | \ | \ | \ |

   479  *   \|  \|  \|  \|  \|  \|  \|

   480  * \endcode

   481  *

   482  * \sa SDL_HAPTIC_SINE

   483  * \sa SDL_HAPTIC_SQUARE

   484  * \sa SDL_HAPTIC_TRIANGLE

   485  * \sa SDL_HAPTIC_SAWTOOTHUP

   486  * \sa SDL_HAPTIC_SAWTOOTHDOWN

   487  * \sa SDL_HapticEffect

   488  */

   489 typedef struct SDL_HapticPeriodic {

   490    /* Header */

   491    Uint16 type; /**< SDL_HAPTIC_SINE, SDL_HAPTIC_SQUARE,

   492                      SDL_HAPTIC_TRIANGLE, SDL_HAPTIC_SAWTOOTHUP or

   493                      SDL_HAPTIC_SAWTOOTHDOWN */

   494    SDL_HapticDirection direction; /**< Direction of the effect. */

   495

   496    /* Replay */

   497    Uint32 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    /* Periodic */

   505    Uint16 period; /**< Period of the wave. */

   506    Sint16 magnitude; /**< Peak value. */

   507    Sint16 offset; /**< Mean value of the wave. */

   508    Uint16 phase; /**< Horizontal shift given by hundredth of a cycle. */

   509

   510    /* Envelope */

   511    Uint16 attack_length; /**< Duration of the attack. */

   512    Uint16 attack_level; /**< Level at the start of the attack. */

   513    Uint16 fade_length; /**< Duration of the fade. */

   514    Uint16 fade_level; /**< Level at the end of the fade. */

   515 } SDL_HapticPeriodic;

   516 /**

   517  * \struct SDL_HapticCondition

   518  *

   519  * \brief A structure containing a template for a Condition effect.

   520  *

   521  * The struct handles the following effects:

   522  *   - SDL_HAPTIC_SPRING: Effect based on axes position.

   523  *   - SDL_HAPTIC_DAMPER: Effect based on axes velocity.

   524  *   - SDL_HAPTIC_INERTIA: Effect based on axes acceleration.

   525  *   - SDL_HAPTIC_FRICTION: Effect based on axes movement.

   526  *

   527  * Direction is handled by condition internals instead of a direction member.

   528  *  The condition effect specific members have three parameters.  The first

   529  *  refers to the X axis, the second refers to the Y axis and the third

   530  *  refers to the Z axis.  The right terms refer to the positive side of the

   531  *  axis and the left terms refer to the negative side of the axis.  Please

   532  *  refer to the SDL_HapticDirection  diagram for which side is positive and

   533  *  which is negative.

   534  *

   535  * \sa SDL_HapticDirection

   536  * \sa SDL_HAPTIC_SPRING

   537  * \sa SDL_HAPTIC_DAMPER

   538  * \sa SDL_HAPTIC_INERTIA

   539  * \sa SDL_HAPTIC_FRICTION

   540  * \sa SDL_HapticEffect

   541  */

   542 typedef struct SDL_HapticCondition {

   543    /* Header */

   544    Uint16 type; /**< SDL_HAPTIC_SPRING, SDL_HAPTIC_DAMPER,

   545                      SDL_HAPTIC_INERTIA or SDL_HAPTIC_FRICTION */

   546    SDL_HapticDirection direction; /**< Direction of the effect - Not used ATM. */

   547

   548    /* Replay */

   549    Uint32 length; /**< Duration of the effect. */

   550    Uint16 delay; /**< Delay before starting the effect. */

   551

   552    /* Trigger */

   553    Uint16 button; /**< Button that triggers the effect. */

   554    Uint16 interval; /**< How soon it can be triggered again after button. */

   555

   556    /* Condition */

   557    Uint16 right_sat[3]; /**< Level when joystick is to the positive side. */

   558    Uint16 left_sat[3]; /**< Level when joystick is to the negative side. */

   559    Sint16 right_coeff[3]; /**< How fast to increase the force towards the positive side. */

   560    Sint16 left_coeff[3]; /**< How fast to increase the force towards the negative side. */

   561    Uint16 deadband[3]; /**< Size of the dead zone. */

   562    Sint16 center[3]; /**< Position of the dead zone. */

   563 } SDL_HapticCondition;

   564 /**

   565  * \struct SDL_HapticRamp

   566  *

   567  * \brief A structure containing a template for a Ramp effect.

   568  *

   569  * This struct is exclusively for the SDL_HAPTIC_RAMP effect.

   570  *

   571  * The ramp effect starts at start strength and ends at end strength.

   572  *  It augments in linear fashion.  If you use attack and fade with a ramp

   573  *  they effects get added to the ramp effect making the effect become

   574  *  quadratic instead of linear.

   575  *

   576  * \sa SDL_HAPTIC_RAMP

   577  * \sa SDL_HapticEffect

   578  */

   579 typedef struct SDL_HapticRamp {

   580    /* Header */

   581    Uint16 type; /**< SDL_HAPTIC_RAMP */

   582    SDL_HapticDirection direction; /**< Direction of the effect. */

   583

   584    /* Replay */

   585    Uint32 length; /**< Duration of the effect. */

   586    Uint16 delay; /**< Delay before starting the effect. */

   587

   588    /* Trigger */

   589    Uint16 button; /**< Button that triggers the effect. */

   590    Uint16 interval; /**< How soon it can be triggered again after button. */

   591

   592    /* Ramp */

   593    Sint16 start; /**< Beginning strength level. */

   594    Sint16 end; /**< Ending strength level. */

   595

   596    /* Envelope */

   597    Uint16 attack_length; /**< Duration of the attack. */

   598    Uint16 attack_level; /**< Level at the start of the attack. */

   599    Uint16 fade_length; /**< Duration of the fade. */

   600    Uint16 fade_level; /**< Level at the end of the fade. */

   601 } SDL_HapticRamp;

   602 /**

   603  * \struct SDL_HapticCustom

   604  *

   605  * \brief A structure containing a template for the SDL_HAPTIC_CUSTOM effect.

   606  *

   607  * A custom force feedback effect is much like a periodic effect, where the

   608  *  application can define it's exact shape.  You will have to allocate the

   609  *  data yourself.  Data should consist of channels * samples Uint16 samples.

   610  *

   611  * If channels is one, the effect is rotated using the defined direction.

   612  *  Otherwise it uses the samples in data for the different axes.

   613  *

   614  * \sa SDL_HAPTIC_CUSTOM

   615  * \sa SDL_HapticEffect

   616  */

   617 typedef struct SDL_HapticCustom {

   618    /* Header */

   619    Uint16 type; /**< SDL_HAPTIC_CUSTOM */

   620    SDL_HapticDirection direction; /**< Direction of the effect. */

   621

   622    /* Replay */

   623    Uint32 length; /**< Duration of the effect. */

   624    Uint16 delay; /**< Delay before starting the effect. */

   625

   626    /* Trigger */

   627    Uint16 button; /**< Button that triggers the effect. */

   628    Uint16 interval; /**< How soon it can be triggered again after button. */

   629

   630    /* Custom */

   631    Uint8 channels; /**< Axes to use, minimum of one. */

   632    Uint16 period; /**< Sample periods. */

   633    Uint16 samples; /**< Amount of samples. */

   634    Uint16 *data; /**< Should contain channels*samples items. */

   635

   636    /* Envelope */

   637    Uint16 attack_length; /**< Duration of the attack. */

   638    Uint16 attack_level; /**< Level at the start of the attack. */

   639    Uint16 fade_length; /**< Duration of the fade. */

   640    Uint16 fade_level; /**< Level at the end of the fade. */

   641 } SDL_HapticCustom;

   642 /**

   643  * \union SDL_HapticEffect

   644  *

   645  * \brief The generic template for any haptic effect.

   646  *

   647  * All values max at 32767 (0x7FFF).  Signed values also can be negative.

   648  *  Time values unless specified otherwise are in milliseconds.

   649  *

   650  * You can also pass SDL_HAPTIC_INFINITY to length instead of a 0-32767 value.

   651  *  Neither delay, interval, attack_length nor fade_length support

   652  *  SDL_HAPTIC_INFINITY.  Fade will also not be used since effect never ends.

   653  *

   654  * Additionally, the SDL_HAPTIC_RAMP effect does not support a duration of

   655  *  SDL_HAPTIC_INFINITY.

   656  *

   657  * Button triggers may not be supported on all devices, it is advised to not

   658  *  use them if possible.  Buttons start at index 1 instead of index 0 like

   659  *  they joystick.

   660  *

   661  * If both attack_length and fade_level are 0, the envelope is not used,

   662  *  otherwise both values are used.

   663  *

   664  * Common parts:

   665  * \code

   666  * // Replay - All effects have this

   667  * Uint32 length;        // Duration of effect (ms).

   668  * Uint16 delay;         // Delay before starting effect.

   669  *

   670  * // Trigger - All effects have this

   671  * Uint16 button;        // Button that triggers effect.

   672  * Uint16 interval;      // How soon before effect can be triggered again.

   673  *

   674  * // Envelope - All effects except condition effects have this

   675  * Uint16 attack_length; // Duration of the attack (ms).

   676  * Uint16 attack_level;  // Level at the start of the attack.

   677  * Uint16 fade_length;   // Duration of the fade out (ms).

   678  * Uint16 fade_level;    // Level at the end of the fade.

   679  * \endcode

   680  *

   681  *

   682  * Here we have an example of a constant effect evolution in time:

   683  *

   684  * \code

   685  * Strength

   686  * ^

   687  * |

   688  * |    effect level -->  _________________

   689  * |                     /                 \

   690  * |                    /                   \

   691  * |                   /                     \

   692  * |                  /                       \

   693  * | attack_level --> |                        \

   694  * |                  |                        |  <---  fade_level

   695  * |

   696  * +--------------------------------------------------> Time

   697  *                    [--]                 [---]

   698  *                    attack_length        fade_length

   699  *

   700  * [------------------][-----------------------]

   701  * delay               length

   702  * \endcode

   703  *

   704  * Note either the attack_level or the fade_level may be above the actual

   705  *  effect level.

   706  *

   707  * \sa SDL_HapticConstant

   708  * \sa SDL_HapticPeriodic

   709  * \sa SDL_HapticCondition

   710  * \sa SDL_HapticRamp

   711  * \sa SDL_HapticCustom

   712  */

   713 typedef union SDL_HapticEffect {

   714    /* Common for all force feedback effects */

   715    Uint16 type; /**< Effect type. */

   716    SDL_HapticConstant constant; /**< Constant effect. */

   717    SDL_HapticPeriodic periodic; /**< Periodic effect. */

   718    SDL_HapticCondition condition; /**< Condition effect. */

   719    SDL_HapticRamp ramp; /**< Ramp effect. */

   720    SDL_HapticCustom custom; /**< Custom effect. */

   721 } SDL_HapticEffect;

   722

   723

   724 /* Function prototypes */

   725 /**

   726  * \fn int SDL_NumHaptics(void)

   727  *

   728  * \brief Count the number of joysticks attached to the system.

   729  *

   730  *    \return Number of haptic devices detected on the system.

   731  */

   732 extern DECLSPEC int SDLCALL SDL_NumHaptics(void);

   733

   734 /**

   735  * \fn const char * SDL_HapticName(int device_index)

   736  *

   737  * \brief Get the implementation dependent name of a Haptic device.

   738  * This can be called before any joysticks are opened.

   739  * If no name can be found, this function returns NULL.

   740  *

   741  *    \param device_index Index of the device to get it's name.

   742  *    \return Name of the device or NULL on error.

   743  *

   744  * \sa SDL_NumHaptics

   745  */

   746 extern DECLSPEC const char *SDLCALL SDL_HapticName(int device_index);

   747

   748 /**

   749  * \fn SDL_Haptic * SDL_HapticOpen(int device_index)

   750  *

   751  * \brief Opens a Haptic device for usage - the index passed as an

   752  * argument refers to the N'th Haptic device on this system.

   753  *

   754  * When opening a haptic device, it's gain will be set to maximum and

   755  *  autocenter will be disabled.  To modify these values use

   756  *  SDL_HapticSetGain and SDL_HapticSetAutocenter

   757  *

   758  *    \param device_index Index of the device to open.

   759  *    \return Device identifier or NULL on error.

   760  *

   761  * \sa SDL_HapticIndex

   762  * \sa SDL_HapticOpenFromMouse

   763  * \sa SDL_HapticOpenFromJoystick

   764  * \sa SDL_HapticClose

   765  * \sa SDL_HapticSetGain

   766  * \sa SDL_HapticSetAutocenter

   767  */

   768 extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpen(int device_index);

   769

   770 /**

   771  * \fn int SDL_HapticOpened(int device_index)

   772  *

   773  * \brief Checks if the haptic device at index has been opened.

   774  *

   775  *    \param device_index Index to check to see if it has been opened.

   776  *    \return 1 if it has been opened or 0 if it hasn't.

   777  *

   778  * \sa SDL_HapticOpen

   779  * \sa SDL_HapticIndex

   780  */

   781 extern DECLSPEC int SDLCALL SDL_HapticOpened(int device_index);

   782

   783 /**

   784  * \fn int SDL_HapticIndex(SDL_Haptic * haptic)

   785  *

   786  * \brief Gets the index of a haptic device.

   787  *

   788  *    \param haptic Haptic device to get the index of.

   789  *    \return The index of the haptic device or -1 on error.

   790  *

   791  * \sa SDL_HapticOpen

   792  * \sa SDL_HapticOpened

   793  */

   794 extern DECLSPEC int SDLCALL SDL_HapticIndex(SDL_Haptic * haptic);

   795

   796 /**

   797  * \fn int SDL_MouseIsHaptic(void)

   798  *

   799  * \brief Gets whether or not the current mouse has haptic capabilities.

   800  *

   801  *    \return SDL_TRUE if the mouse is haptic, SDL_FALSE if it isn't.

   802  *

   803  * \sa SDL_HapticOpenFromMouse

   804  */

   805 extern DECLSPEC int SDLCALL SDL_MouseIsHaptic(void);

   806

   807 /**

   808  * \fn SDL_Haptic * SDL_HapticOpenFromMouse(void)

   809  *

   810  * \brief Tries to open a haptic device from the current mouse.

   811  *

   812  *    \return The haptic device identifier or NULL on error.

   813  *

   814  * \sa SDL_MouseIsHaptic

   815  * \sa SDL_HapticOpen

   816  */

   817 extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromMouse(void);

   818

   819 /**

   820  * \fn int SDL_JoystickIsHaptic(SDL_Joystick * joystick)

   821  *

   822  * \brief Checks to see if a joystick has haptic features.

   823  *

   824  *    \param joystick Joystick to test for haptic capabilities.

   825  *    \return SDL_TRUE if the joystick is haptic, SDL_FALSE if it isn't

   826  *            or -1 if an error ocurred.

   827  *

   828  * \sa SDL_HapticOpenFromJoystick

   829  */

   830 extern DECLSPEC int SDLCALL SDL_JoystickIsHaptic(SDL_Joystick * joystick);

   831

   832 /**

   833  * \fn SDL_Haptic * SDL_HapticOpenFromJoystick(SDL_Joystick * joystick)

   834  *

   835  * \brief Opens a Haptic device for usage from a Joystick device.  Still has

   836  * to be closed seperately to the joystick.

   837  *

   838  * When opening from a joystick you should first close the haptic device before

   839  *  closing the joystick device.  If not, on some implementations the haptic

   840  *  device will also get unallocated and you'll be unable to use force feedback

   841  *  on that device.

   842  *

   843  *    \param joystick Joystick to create a haptic device from.

   844  *    \return A valid haptic device identifier on success or NULL on error.

   845  *

   846  * \sa SDL_HapticOpen

   847  * \sa SDL_HapticClose

   848  */

   849 extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromJoystick(SDL_Joystick * joystick);

   850

   851 /**

   852  * \fn void SDL_HapticClose(SDL_Haptic * haptic)

   853  *

   854  * \brief Closes a Haptic device previously opened with SDL_HapticOpen.

   855  *

   856  *    \param haptic Haptic device to close.

   857  */

   858 extern DECLSPEC void SDLCALL SDL_HapticClose(SDL_Haptic * haptic);

   859

   860 /**

   861  * \fn int SDL_HapticNumEffects(SDL_Haptic * haptic)

   862  *

   863  * \brief Returns the number of effects a haptic device can store.

   864  *

   865  * On some platforms this isn't fully supported, and therefore is an

   866  *  aproximation.  Always check to see if your created effect was actually

   867  *  created and do not rely solely on HapticNumEffects.

   868  *

   869  *    \param haptic The haptic device to query effect max.

   870  *    \return The number of effects the haptic device can store or

   871  *            -1 on error.

   872  *

   873  * \sa SDL_HapticNumEffectsPlaying

   874  * \sa SDL_HapticQuery

   875  */

   876 extern DECLSPEC int SDLCALL SDL_HapticNumEffects(SDL_Haptic * haptic);

   877

   878 /**

   879  * \fn int SDL_HapticNumEffectsPlaying(SDL_Haptic * haptic)

   880  *

   881  * \brief Returns the number of effects a haptic device can play at the same time.

   882  *

   883  * This is not supported on all platforms, but will always return a value.  Added

   884  *  here for the sake of completness.

   885  *

   886  *    \param haptic The haptic device to query maximum playing effect.s

   887  *    \return The number of effects the haptic device can play at the same time

   888  *            or -1 on error.

   889  *

   890  * \sa SDL_HapticNumEffects

   891  * \sa SDL_HapticQuery

   892  */

   893 extern DECLSPEC int SDLCALL SDL_HapticNumEffectsPlaying(SDL_Haptic * haptic);

   894

   895 /**

   896  * \fn unsigned int SDL_HapticQuery(SDL_Haptic * haptic)

   897  *

   898  * \brief Gets the haptic devices supported features in bitwise matter.

   899  *

   900  * Example:

   901  * \code

   902  * if (SDL_HapticQueryEffects(haptic) & SDL_HAPTIC_CONSTANT) {

   903  *    printf("We have constant haptic effect!");

   904  * }

   905  * \endcode

   906  *

   907  *

   908  *    \param haptic The haptic device to query.

   909  *    \return Haptic features in bitwise manner (OR'd).

   910  *

   911  * \sa SDL_HapticNumEffects

   912  * \sa SDL_HapticEffectSupported

   913  */

   914 extern DECLSPEC unsigned int SDLCALL SDL_HapticQuery(SDL_Haptic * haptic);

   915

   916

   917 /**

   918  * \fn int SDL_HapticNumAxes(SDL_Haptic * haptic)

   919  *

   920  * \brief Gets the number of haptic axes the device has.

   921  *

   922  * \sa SDL_HapticDirection

   923  */

   924 extern DECLSPEC int SDLCALL SDL_HapticNumAxes(SDL_Haptic * haptic);

   925

   926 /**

   927  * \fn int SDL_HapticEffectSupported(SDL_Haptic * haptic, SDL_HapticEffect * effect)

   928  *

   929  * \brief Checks to see if effect is supported by haptic.

   930  *

   931  *    \param haptic Haptic device to check on.

   932  *    \param effect Effect to check to see if it is supported.

   933  *    \return SDL_TRUE if effect is supported, SDL_FALSE if it isn't or

   934  *            -1 on error.

   935  *

   936  * \sa SDL_HapticQuery

   937  * \sa SDL_HapticNewEffect

   938  */

   939 extern DECLSPEC int SDLCALL SDL_HapticEffectSupported(SDL_Haptic * haptic, SDL_HapticEffect * effect);

   940

   941 /**

   942  * \fn int SDL_HapticNewEffect(SDL_Haptic * haptic, SDL_HapticEffect * effect)

   943  *

   944  * \brief Creates a new haptic effect on the device.

   945  *

   946  *    \param haptic Haptic device to create the effect on.

   947  *    \param effect Properties of the effect to create.

   948  *    \return The id of the effect on success or -1 on error.

   949  *

   950  * \sa SDL_HapticUpdateEffect

   951  * \sa SDL_HapticRunEffect

   952  * \sa SDL_HapticDestroyEffect

   953  */

   954 extern DECLSPEC int SDLCALL SDL_HapticNewEffect(SDL_Haptic * haptic, SDL_HapticEffect * effect);

   955

   956 /**

   957  * \fn int SDL_HapticUpdateEffect(SDL_Haptic * haptic, int effect, SDL_HapticEffect * data)

   958  *

   959  * \brief Updates the properties of an effect.

   960  *

   961  * Can be used dynamically, although behaviour when dynamically changing

   962  * direction may be strange.  Specifically the effect may reupload itself

   963  * and start playing from the start.  You cannot change the type either when

   964  * running UpdateEffect.

   965  *

   966  *    \param haptic Haptic device that has the effect.

   967  *    \param effect Effect to update.

   968  *    \param data New effect properties to use.

   969  *    \return The id of the effect on success or -1 on error.

   970  *

   971  * \sa SDL_HapticNewEffect

   972  * \sa SDL_HapticRunEffect

   973  * \sa SDL_HapticDestroyEffect

   974  */

   975 extern DECLSPEC int SDLCALL SDL_HapticUpdateEffect(SDL_Haptic * haptic, int effect, SDL_HapticEffect * data);

   976

   977 /**

   978  * \fn int SDL_HapticRunEffect(SDL_Haptic * haptic, int effect, Uint32 iterations)

   979  *

   980  * \brief Runs the haptic effect on it's assosciated haptic device.

   981  *

   982  * If iterations are SDL_HAPTIC_INFINITY, it'll run the effect over and over

   983  *  repeating the envelope (attack and fade) every time.  If you only want the

   984  *  effect to last forever, set SDL_HAPTIC_INFINITY in the effect's length

   985  *  parameter.

   986  *

   987  *    \param haptic Haptic device to run the effect on.

   988  *    \param effect Identifier of the haptic effect to run.

   989  *    \param iterations Number of iterations to run the effect. Use

   990  *           SDL_HAPTIC_INFINITY for infinity.

   991  *    \return 0 on success or -1 on error.

   992  *

   993  * \sa SDL_HapticStopEffect

   994  * \sa SDL_HapticDestroyEffect

   995  * \sa SDL_HapticGetEffectStatus

   996  */

   997 extern DECLSPEC int SDLCALL SDL_HapticRunEffect(SDL_Haptic * haptic, int effect, Uint32 iterations);

   998

   999 /**

  1000  * \fn int SDL_HapticStopEffect(SDL_Haptic * haptic, int effect)

  1001  *

  1002  * \brief Stops the haptic effect on it's assosciated haptic device.

  1003  *

  1004  *    \param haptic Haptic device to stop the effect on.

  1005  *    \param effect Identifier of the effect to stop.

  1006  *    \return 0 on success or -1 on error.

  1007  *

  1008  * \sa SDL_HapticRunEffect

  1009  * \sa SDL_HapticDestroyEffect

  1010  */

  1011 extern DECLSPEC int SDLCALL SDL_HapticStopEffect(SDL_Haptic * haptic, int effect);

  1012

  1013 /**

  1014  * \fn void SDL_HapticDestroyEffect(SDL_Haptic * haptic, int effect)

  1015  *

  1016  * \brief Destroys a haptic effect on the device.  This will stop the effect

  1017  * if it's running.  Effects are automatically destroyed when the device is

  1018  * closed.

  1019  *

  1020  *    \param haptic Device to destroy the effect on.

  1021  *    \param effect Identifier of the effect to destroy.

  1022  *

  1023  * \sa SDL_HapticNewEffect

  1024  */

  1025 extern DECLSPEC void SDLCALL SDL_HapticDestroyEffect(SDL_Haptic * haptic, int effect);

  1026

  1027 /**

  1028  * \fn int SDL_HapticGetEffectStatus(SDL_Haptic *haptic, int effect)

  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, int effect);

  1043

  1044 /**

  1045  * \fn int SDL_HapticSetGain(SDL_Haptic * haptic, int gain)

  1046  *

  1047  * \brief Sets the global gain of the device.  Gain should be between 0 and 100.

  1048  *

  1049  * Device must support the SDL_HAPTIC_GAIN feature.

  1050  *

  1051  * The user may specify the maxmimum gain by setting the environment variable

  1052  *  SDL_HAPTIC_GAIN_MAX which should be between 0 and 100.  All calls to

  1053  *  SDL_HapticSetGain will scale linearly using SDL_HAPTIC_GAIN_MAX as the

  1054  *  maximum.

  1055  *

  1056  *    \param haptic Haptic device to set the gain on.

  1057  *    \param gain Value to set the gain to, should be between 0 and 100.

  1058  *    \return 0 on success or -1 on error.

  1059  *

  1060  * \sa SDL_HapticQuery

  1061  */

  1062 extern DECLSPEC int SDLCALL SDL_HapticSetGain(SDL_Haptic * haptic, int gain);

  1063

  1064 /**

  1065  * \fn int SDL_HapticSetAutocenter(SDL_Haptic * haptic, int autocenter)

  1066  *

  1067  * \brief Sets the global autocenter of the device.  Autocenter should be between

  1068  * 0 and 100.  Setting it to 0 will disable autocentering.

  1069  *

  1070  * Device must support the SDL_HAPTIC_AUTOCENTER feature.

  1071  *

  1072  *    \param haptic Haptic device to set autocentering on.

  1073  *    \param autocenter Value to set autocenter to, 0 disables autocentering.

  1074  *    \return 0 on success or -1 on error.

  1075  *

  1076  * \sa SDL_HapticQuery

  1077  */

  1078 extern DECLSPEC int SDLCALL SDL_HapticSetAutocenter(SDL_Haptic * haptic, int autocenter);

  1079

  1080 /**

  1081  * \fn extern DECLSPEC int SDLCALL SDL_HapticPause(SDL_Haptic * haptic)

  1082  *

  1083  * \brief Pauses the haptic device.

  1084  *

  1085  * Device must support the SDL_HAPTIC_PAUSE feature.  Call SDL_HapticUnpause

  1086  *  to resume playback.

  1087  *

  1088  * Do not modify the effects nor add new ones while the device is paused.

  1089  *  That can cause all sorts of weird errors.

  1090  *

  1091  *    \param haptic Haptic device to pause.

  1092  *    \return 0 on success or -1 on error.

  1093  *

  1094  * \sa SDL_HapticUnpause

  1095  */

  1096 extern DECLSPEC int SDLCALL SDL_HapticPause(SDL_Haptic * haptic);

  1097

  1098 /**

  1099  * \fn extern DECLSPEC int SDLCALL SDL_HapticUnpause(SDL_Haptic * haptic)

  1100  *

  1101  * \brief Unpauses the haptic device.

  1102  *

  1103  * Call to unpause after SDL_HapticPause.

  1104  *

  1105  *    \param haptic Haptic device to pause.

  1106  *     \return 0 on success or -1 on error.

  1107  *

  1108  * \sa SDL_HapticPause

  1109  */

  1110 extern DECLSPEC int SDLCALL SDL_HapticUnpause(SDL_Haptic * haptic);

  1111

  1112

  1113 /* Ends C function definitions when using C++ */

  1114 #ifdef __cplusplus

  1115 /* *INDENT-OFF* */

  1116 }

  1117 /* *INDENT-ON* */

  1118 #endif

  1119 #include "close_code.h"

  1120

  1121 #endif /* _SDL_haptic_h */

  1122

  1123 /* vi: set ts=4 sw=4 expandtab: */

  1124

  1125