Mercurial > sdl-ios-xcode

comparison include/SDL_haptic.h @ 2713:0906692aa6a4

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