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