1 //from "sdl_haptic.h"
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 *}
92 {$I jedi.inc}
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;
107 {**
108 * Haptic features
109 *
110 * Different haptic features a device can have.
111 *}
113 {**
114 * Haptic effects
115 *}
117 {**
118 * Constant effect supported.
119 *
120 * Constant haptic effect.
121 *
122 * SDL_HapticCondition
123 *}
124 const
125 SDL_HAPTIC_CONSTANT = (1 shl 0);
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);
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);
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);
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);
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);
177 {**
178 * Ramp effect supported.
179 *
180 * Ramp haptic effect.
181 *
182 * SDL_HapticRamp
183 *}
184 const
185 SDL_HAPTIC_RAMP = (1 shl 6);
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);
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);
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);
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);
231 {**
232 * Custom effect is supported.
233 *
234 * User defined custom haptic effect.
235 *}
236 const
237 SDL_HAPTIC_CUSTOM = (1 shl 11);
239 {*Haptic effects*}
241 {* These last few are features the device has, not effects *}
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);
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);
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);
273 {**
274 * Device can be paused.
275 *
276 * SDL_HapticPause
277 * SDL_HapticUnpause
278 *}
279 const
280 SDL_HAPTIC_PAUSE = (1 shl 15);
282 {**
283 * Direction encodings
284 *}
286 {**
287 * Uses polar coordinates for the direction.
288 *
289 * SDL_HapticDirection
290 *}
291 const
292 SDL_HAPTIC_POLAR = 0;
294 {**
295 * Uses cartesian coordinates for the direction.
296 *
297 * SDL_HapticDirection
298 *}
299 const
300 SDL_HAPTIC_CARTESIAN = 1;
302 {**
303 * Uses spherical coordinates for the direction.
304 *
305 * SDL_HapticDirection
306 *}
307 const
308 SDL_HAPTIC_SPHERICAL = 2;
310 {*Direction encodings*}
312 {*Haptic features*}
314 {*
315 * Misc defines.
316 *}
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?!
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 ]
349 North (0,-1)
350 ^
351 |
352 |
353 (1,0) West <----[ HAPTIC ]----> East (-1,0)
354 |
355 |
356 v
357 South (0,1)
360 [ USER ]
361 \|||/
362 (o o)
363 ---ooO-(_)-Ooo---
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;
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. *}
442 {* Replay *}
443 length: UInt32; {**< Duration of the effect. *}
444 delay: UInt16; {**< Delay before starting the effect. *}
446 {* Trigger *}
447 button: UInt16; {**< Button that triggers the effect. *}
448 interval: UInt16; {**< How soon it can be triggered again after button. *}
450 {* Constant *}
451 level: SInt16; {**< Strength of the constant effect. *}
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;
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 / \__/ \__/ \__/
489 SDL_HAPTIC_SQUARE
490 __ __ __ __ __
491 | | | | | | | | | |
492 | |__| |__| |__| |__| |
494 SDL_HAPTIC_TRIANGLE
495 /\ /\ /\ /\ /\
496 / \ / \ / \ / \ /
497 / \/ \/ \/ \/
499 SDL_HAPTIC_SAWTOOTHUP
500 /| /| /| /| /| /| /|
501 / | / | / | / | / | / | / |
502 / |/ |/ |/ |/ |/ |/ |
504 SDL_HAPTIC_SAWTOOTHDOWN
505 \ |\ |\ |\ |\ |\ |\ |
506 \ | \ | \ | \ | \ | \ | \ |
507 \| \| \| \| \| \| \|
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. *}
525 {* Replay *}
526 length: UInt32; {**< Duration of the effect. *}
527 delay: UInt16; {**< Delay before starting the effect. *}
529 {* Trigger *}
530 button: UInt16; {**< Button that triggers the effect. *}
531 interval: UInt16; {**< How soon it can be triggered again after button. *}
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. *}
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;
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. *}
577 {* Replay *}
578 length: UInt32; {**< Duration of the effect. *}
579 delay: UInt16; {**< Delay before starting the effect. *}
581 {* Trigger *}
582 button: UInt16; {**< Button that triggers the effect. *}
583 interval: UInt16; {**< How soon it can be triggered again after button. *}
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;
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. *}
613 {* Replay *}
614 length: UInt32; {**< Duration of the effect. *}
615 delay: UInt16; {**< Delay before starting the effect. *}
617 {* Trigger *}
618 button: UInt16; {**< Button that triggers the effect. *}
619 interval: UInt16; {**< How soon it can be triggered again after button. *}
621 {* Ramp *}
622 start: SInt16; {**< Beginning strength level. *}
623 _end: SInt16; {**< Ending strength level. *}
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;
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. *}
651 {* Replay *}
652 length: UInt32; {**< Duration of the effect. *}
653 delay: UInt16; {**< Delay before starting the effect. *}
655 {* Trigger *}
656 button: UInt16; {**< Button that triggers the effect. *}
657 interval: UInt16; {**< How soon it can be triggered again after button. *}
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. *}
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;
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
727 [------------------][-----------------------]
728 delay length
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;
753 {* Function prototypes *}
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};
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};
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};
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};
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};
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};
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};
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};
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};
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};
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};
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};
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};
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};
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};
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};
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};
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};
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};
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};
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};
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};
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};
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};
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};
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};
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};
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};
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};
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};