sdlhaptic.inc

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