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