This repository has been archived by the owner on Feb 11, 2021. It is now read-only.
/
SDL_haptic.h
850 lines (794 loc) · 25 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
/*
SDL - Simple DirectMedia Layer
Copyright (C) 2008 Edgar Simo
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
Sam Lantinga
slouken@libsdl.org
*/
/**
24
* \file SDL_haptic.h
25
*
26
* \brief The SDL Haptic subsystem allows you to control haptic (force feedback)
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
* devices.
*
* The basic usage is as follows:
* - Initialize the Subsystem (SDL_INIT_HAPTIC).
* - Open a Haptic Device.
* - SDL_HapticOpen(...) to open from index.
* - SDL_HapticOpenFromJoystick(...) to open from an existing joystick.
* - Create an effect (SDL_HapticEffect).
* - Upload the effect with SDL_HapticNewEffect(...).
* - Run the effect with SDL_HapticRunEffect(...).
* - (optional) Free the effect with SDL_HapticDestroyEffect(...).
* - Close the haptic device with SDL_HapticClose(...).
*
*
* Example:
*
* \code
* int test_haptic( SDL_Joystick * joystick ) {
* SDL_Haptic *haptic;
* SDL_HapticEffect effect;
* int effect_id;
*
* // Open the device
* haptic = SDL_HapticOpenFromJoystick( joystick );
* if (haptic == NULL) return -1; // Most likely joystick isn't haptic
*
* // See if it can do sine waves
* if ((SDL_HapticQueryEffects(haptic) & SDL_HAPTIC_SINE)==0) {
* SDL_HapticClose(haptic); // No sine effect
* return -1;
* }
*
* // Create the effect
* memset( &effect, 0, sizeof(SDL_HapticEffect) ); // 0 is safe default
* effect.type = SDL_HAPTIC_SINE;
62
* effect.periodic.direction.type = SDL_HAPTIC_POLAR; // Polar coordinates
63
* effect.periodic.direction.dir[0] = 18000; // Force comes from south
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
* effect.periodic.period = 1000; // 1000 ms
* effect.periodic.magnitude = 20000; // 20000/32767 strength
* effect.periodic.length = 5000; // 5 seconds long
* effect.periodic.attack_length = 1000; // Takes 1 second to get max strength
* effect.periodic.fade_length = 1000; // Takes 1 second to fade away
*
* // Upload the effect
* effect_id = SDL_HapticNewEffect( haptic, &effect );
*
* // Test the effect
* SDL_HapticRunEffect( haptic, effect_id );
* SDL_Delay( 5000); // Wait for the effect to finish
*
* // We destroy the effect, although closing the device also does this
* SDL_HapticDestroyEffect( haptic, effect_id );
*
* // Close the device
* SDL_HapticClose(haptic);
*
* return 0; // Success
* }
* \endcode
*
* \author Edgar Simo Serra
88
89
90
91
92
93
94
*/
#ifndef _SDL_haptic_h
#define _SDL_haptic_h
#include "SDL_stdinc.h"
#include "SDL_error.h"
95
#include "SDL_joystick.h"
96
97
98
99
100
101
102
#include "begin_code.h"
/* Set up for C function definitions, even when using C++ */
#ifdef __cplusplus
/* *INDENT-OFF* */
extern "C" {
/* *INDENT-ON* */
103
#endif /* __cpluspuls */
104
105
/**
106
* \typedef SDL_Haptic
107
108
109
110
111
112
113
*
* \brief The haptic structure used to identify an SDL haptic.
*
* \sa SDL_HapticOpen
* \sa SDL_HapticOpenFromJoystick
* \sa SDL_HapticClose
*/
114
115
116
117
struct _SDL_Haptic;
typedef struct _SDL_Haptic SDL_Haptic;
118
119
120
/*
* Different haptic features a device can have.
*/
121
122
123
124
125
126
127
/**
* \def SDL_HAPTIC_CONSTANT
*
* \brief Constant haptic effect.
*
* \sa SDL_HapticCondition
*/
128
#define SDL_HAPTIC_CONSTANT (1<<0) /* Constant effect supported */
129
130
131
132
133
134
135
/**
* \def SDL_HAPTIC_SINE
*
* \brief Periodic haptic effect that simulates sine waves.
*
* \sa SDL_HapticPeriodic
*/
136
#define SDL_HAPTIC_SINE (1<<1) /* Sine wave effect supported */
137
138
139
140
/**
* \def SDL_HAPTIC_SQUARE
*
* \brief Periodic haptic effect that simulates square waves.
141
*
142
143
* \sa SDL_HapticPeriodic
*/
144
#define SDL_HAPTIC_SQUARE (1<<2) /* Square wave effect supported */
145
146
147
148
149
150
151
/**
* \def SDL_HAPTIC_TRIANGLE
*
* \brief Periodic haptic effect that simulates triangular waves.
*
* \sa SDL_HapticPeriodic
*/
152
#define SDL_HAPTIC_TRIANGLE (1<<3) /* Triangle wave effect supported */
153
154
155
156
157
158
159
/**
* \def SDL_HAPTIC_SAWTOOTHUP
*
* \brief Periodic haptic effect that simulates saw tooth up waves.
*
* \sa SDL_HapticPeriodic
*/
160
#define SDL_HAPTIC_SAWTOOTHUP (1<<4) /* Sawtoothup wave effect supported */
161
162
163
164
165
166
167
/**
* \def SDL_HAPTIC_SAWTOOTHDOWN
*
* \brief Periodic haptic effect that simulates saw tooth down waves.
*
* \sa SDL_HapticPeriodic
*/
168
#define SDL_HAPTIC_SAWTOOTHDOWN (1<<5) /* Sawtoothdown wave effect supported */
169
170
171
172
173
174
175
/**
* \def SDL_HAPTIC_RAMP
*
* \brief Ramp haptic effect.
*
* \sa SDL_HapticRamp
*/
176
#define SDL_HAPTIC_RAMP (1<<6) /* Ramp effect supported */
177
178
179
180
181
182
183
184
/**
* \def SDL_HAPTIC_SPRING
*
* \brief Condition haptic effect that simulates a spring. Effect is based on the
* axes position.
*
* \sa SDL_HapticCondition
*/
185
#define SDL_HAPTIC_SPRING (1<<7) /* Spring effect supported - uses axes position */
186
187
188
189
190
191
192
193
/**
* \def SDL_HAPTIC_DAMPER
*
* \brief Condition haptic effect that simulates dampening. Effect is based on the
* axes velocity.
*
* \sa SDL_HapticCondition
*/
194
#define SDL_HAPTIC_DAMPER (1<<8) /* Damper effect supported - uses axes velocity */
195
196
197
198
199
200
201
202
/**
* \def SDL_HAPTIC_INERTIA
*
* \brief Condition haptic effect that simulates inertia. Effect is based on the axes
* acceleration.
*
* \sa SDL_HapticCondition
*/
203
#define SDL_HAPTIC_INERTIA (1<<9) /* Inertia effect supported - uses axes acceleration */
204
205
206
207
208
209
210
211
/**
* \def SDL_HAPTIC_FRICTION
*
* \brief Condition haptic effect that simulates friction. Effect is based on the axes
* movement.
*
* \sa SDL_HapticCondition
*/
212
#define SDL_HAPTIC_FRICTION (1<<10) /* Friction effect supported - uses axes movement */
213
214
215
216
217
/**
* \def SDL_HAPTIC_CUSTOM
*
* \brief User defined custom haptic effect. TODO.
*/
218
#define SDL_HAPTIC_CUSTOM (1<<11) /* Custom effect is supported */
219
/* These last two are features the device has, not effects */
220
221
222
223
224
225
226
/**
* \def SDL_HAPTIC_GAIN
*
* \brief Device supports setting the global gain.
*
* \sa SDL_HapticSetGain
*/
227
#define SDL_HAPTIC_GAIN (1<<12) /* Device can set global gain */
228
229
230
231
232
233
234
/**
* \def SDL_HAPTIC_AUTOCENTER
*
* \brief Device supports setting autocenter.
*
* \sa SDL_HapticSetAutocenter
*/
235
#define SDL_HAPTIC_AUTOCENTER (1<<13) /* Device can set autocenter */
236
237
238
239
240
241
242
/**
* \def SDL_HAPTIC_STATUS
*
* \brief Device can be queried for effect status.
*
* \sa SDL_HapticGetEffectStatus
*/
243
#define SDL_HAPTIC_STATUS (1<<14) /* Device can be queried for effect status */
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
/*
* Direction encodings
*/
/**
* \def SDL_HAPTIC_POLAR
*
* \brief Uses polar coordinates for the direction.
*
* \sa SDL_HapticDirection
*/
#define SDL_HAPTIC_POLAR 0
/**
* \def SDL_HAPTIC_CARTESIAN
*
* \brief Uses cartesian coordinates for the direction.
*
* \sa SDL_HapticDirection
*/
#define SDL_HAPTIC_CARTESIAN 1
/**
* \struct SDL_HapticDirection
*
* \brief Structure that represents a haptic direction.
*
* Directions can be specified by:
* - SDL_HAPTIC_POLAR: Specified by polar coordinates.
* - SDL_HAPTIC_CARTESIAN: Specified by cartesian coordinates.
*
* Cardinal directions of the haptic device are relative to the positioning
* of the device. North is considered to be away from the user.
*
* The following diagram represents the cardinal directions:
* \code
* .--.
* |__| .-------.
* |=.| |.-----.|
* |--| || ||
* | | |'-----'|
* |__|~')_____('
* [ COMPUTER ]
*
*
* North (-1)
* ^
* |
* |
* (1) East <----[ HAPTIC ]----> West (-1)
* |
* |
* v
* South (1)
*
*
* [ USER ]
* \|||/
* (o o)
* ---ooO-(_)-Ooo---
* \endcode
*
* If type is SDL_HAPTIC_POLAR, direction is encoded by hundredths of a
* degree starting north and turning clockwise. The cardinal directions would be:
* - North: 0 (0 degrees)
* - West: 9000 (90 degrees)
* - South: 18000 (180 degrees)
* - East: 27000 (270 degrees)
*
* If type is SDL_HAPTIC_CARTESIAN, direction is encoded by position.
* The cardinal directions would be:
* - North: 0,-1
* - West: -1, 0
* - South: 0, 1
* - East: 1, 0
*
*
* Example:
* \code
* SDL_HapticDirection direction;
*
* direction.type = SDL_HAPTIC_POLAR; // We'll be using polar direction encoding.
* direction.dir = 180000; // Force comes from the south meaning the user will
* // have to pull the stick to counteract.
* \endcode
*
* \sa SDL_HAPTIC_POLAR
* \sa SDL_HAPTIC_CARTESIAN
* \sa SDL_HapticEffect
*/
typedef struct SDL_HapticDirection {
Uint8 type; /**< The type of encoding. */
Uint16 dir[2]; /**< The encoded direction. */
} SDL_HapticDirection;
341
342
/**
* \struct SDL_HapticConstant
343
*
344
* \brief A structure containing a template for a Constant effect.
345
*
346
* The struct is exclusive to the SDL_HAPTIC_CONSTANT effect.
347
*
348
349
* \sa SDL_HAPTIC_CONSTANT
* \sa SDL_HapticEffect
350
*/
351
352
typedef struct SDL_HapticConstant {
/* Header */
353
Uint16 type; /**< SDL_HAPTIC_CONSTANT */
354
SDL_HapticDirection direction; /**< Direction of the effect. */
355
356
/* Replay */
357
358
Uint16 length; /**< Duration of the effect. */
Uint16 delay; /**< Delay before starting the effect. */
359
360
/* Trigger */
361
362
Uint16 button; /**< Button that triggers the effect. */
Uint16 interval; /**< How soon it can be triggered again after button. */
363
364
/* Constant */
365
Sint16 level; /**< Strength of the constant effect. */
366
367
/* Envelope */
368
369
370
371
Uint16 attack_length; /**< Duration of the attack. */
Uint16 attack_level; /**< Level at the start of the attack. */
Uint16 fade_length; /**< Duration of the fade. */
Uint16 fade_level; /**< Level at the end of the fade. */
372
} SDL_HapticConstant;
373
374
375
376
377
378
379
380
381
382
383
384
/**
* \struct SDL_HapticPeriodic
*
* \brief A structure containing a template for a Periodic effect.
*
* The struct handles the following effects:
* - SDL_HAPTIC_SINE
* - SDL_HAPTIC_SQUARE
* - SDL_HAPTIC_TRIANGLE
* - SDL_HAPTIC_SAWTOOTHUP
* - SDL_HAPTIC_SAWTOOTHDOWN
*
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
* Examples:
* \code
* SDL_HAPTIC_SINE
* __ __ __ __
* / \ / \ / \ /
* / \__/ \__/ \__/
*
* SDL_HAPTIC_SQUARE
* __ __ __ __ __
* | | | | | | | | | |
* | |__| |__| |__| |__| |
*
* SDL_HAPTIC_TRIANGLE
* /\ /\ /\ /\ /\
* / \ / \ / \ / \ /
* / \/ \/ \/ \/
*
* SDL_HAPTIC_SAWTOOTHUP
* __ __ __ __ _
* / | / | / | / | /
* / | / | / | / | /
* / |/ |/ |/ |/
*
* SDL_HAPTIC_SAWTOOTHDOWN
* __ __ __ __ __
* \ | \ | \ | \ | \
* \ | \ | \ | \ | \
* \| \| \| \|
* \endcode
*
415
416
417
418
* \sa SDL_HAPTIC_SINE
* \sa SDL_HAPTIC_SQUARE
* \sa SDL_HAPTIC_TRIANGLE
* \sa SDL_HAPTIC_SAWTOOTHUP
419
* \sa SDL_HAPTIC SAWTOOTHDOWN
420
421
* \sa SDL_HapticEffect
*/
422
423
typedef struct SDL_HapticPeriodic {
/* Header */
424
425
Uint16 type; /**< SDL_HAPTIC_{SINE,SQUARE,TRIANGLE,SAWTOOTHUP,SAWTOOTHDOWN} */
SDL_HapticDirection direction; /**< Direction of the effect. */
426
427
/* Replay */
428
429
Uint16 length; /**< Duration of the effect. */
Uint16 delay; /**< Delay before starting the effect. */
430
431
/* Trigger */
432
433
Uint16 button; /**< Button that triggers the effect. */
Uint16 interval; /**< How soon it can be triggered again after button. */
434
435
/* Periodic */
436
437
438
439
Uint16 period; /**< Period of the wave. */
Sint16 magnitude; /**< Peak value. */
Sint16 offset; /**< Mean value of the wave. */
Uint16 phase; /**< Horizontal shift. */
440
441
/* Envelope */
442
443
444
445
Uint16 attack_length; /**< Duration of the attack. */
Uint16 attack_level; /**< Level at the start of the attack. */
Uint16 fade_length; /**< Duration of the fade. */
Uint16 fade_level; /**< Level at the end of the fade. */
446
} SDL_HapticPeriodic;
447
448
449
450
451
/**
* \struct SDL_HapticCondition
*
* \brief A structure containing a template for a Condition effect.
*
452
* Direction is handled by condition internals instead of a direction member.
453
454
455
* Each of right_sat, lefT-sat, right_coeff, left_coeff, deadband and center
* have two parameters, first is for x value, second is for y value following
* the scheme set by SDL_HapticDirection.
456
*
457
* The struct handles the following effects:
458
459
460
461
* - SDL_HAPTIC_SPRING: Effect based on axes position.
* - SDL_HAPTIC_DAMPER: Effect based on axes velocity.
* - SDL_HAPTIC_INERTIA: Effect based on axes acceleration.
* - SDL_HAPTIC_FRICTION: Effect based on axes movement.
462
*
463
* \sa SDL_HapticDirection
464
465
466
467
468
469
* \sa SDL_HAPTIC_SPRING
* \sa SDL_HAPTIC_DAMPER
* \sa SDL_HAPTIC_INERTIA
* \sa SDL_HAPTIC_FRICTION
* \sa SDL_HapticEffect
*/
470
471
typedef struct SDL_HapticCondition {
/* Header */
472
Uint16 type; /**< SDL_HAPTIC_{SPRING,DAMPER,INERTIA,FRICTION} */
473
474
/* Replay */
475
476
Uint16 length; /**< Duration of the effect. */
Uint16 delay; /**< Delay before starting the effect. */
477
478
/* Trigger */
479
480
Uint16 button; /**< Button that triggers the effect. */
Uint16 interval; /**< How soon it can be triggered again after button. */
481
482
/* Condition */
483
484
485
486
487
488
Uint16 right_sat[2]; /**< Level when joystick is to the right. */
Uint16 left_sat[2]; /**< Level when joystick is to the left. */
Sint16 right_coeff[2]; /**< How fast to increase the force towards the right. */
Sint16 left_coeff[2]; /**< How fast to increase the force towards the left. */
Uint16 deadband[2]; /**< Size of the dead zone. */
Sint16 center[2]; /**< Position of the dead zone. */
489
} SDL_HapticCondition;
490
491
492
493
494
495
496
497
498
499
/**
* \struct SDL_HapticRamp
*
* \brief A structure containing a template for a Ramp effect.
*
* This struct is exclusively for the SDL_HAPTIC_RAMP effect.
*
* \sa SDL_HAPTIC_RAMP
* \sa SDL_HapticEffect
*/
500
501
typedef struct SDL_HapticRamp {
/* Header */
502
Uint16 type; /**< SDL_HAPTIC_RAMP */
503
SDL_HapticDirection direction; /**< Direction of the effect. */
504
505
/* Replay */
506
507
Uint16 length; /**< Duration of the effect. */
Uint16 delay; /**< Delay before starting the effect. */
508
509
/* Trigger */
510
511
Uint16 button; /**< Button that triggers the effect. */
Uint16 interval; /**< How soon it can be triggered again after button. */
512
513
/* Ramp */
514
515
Sint16 start; /**< Beginning strength level. */
Sint16 end; /**< Ending strength level. */
516
517
/* Envelope */
518
519
520
521
Uint16 attack_length; /**< Duration of the attack. */
Uint16 attack_level; /**< Level at the start of the attack. */
Uint16 fade_length; /**< Duration of the fade. */
Uint16 fade_level; /**< Level at the end of the fade. */
522
} SDL_HapticRamp;
523
/**
524
525
526
527
* \union SDL_HapticEffect
*
* \brief The generic template for any haptic effect.
*
528
* All values max at 32767 (0x7FFF). Signed values also can be negative.
529
530
531
* Time values unless specified otherwise are in milliseconds.
*
* Common parts:
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
* \code
* // Replay - All effects have this
* Uint16 length; // Duration of effect (ms).
* Uint16 delay; // Delay before starting effect.
*
* // Trigger - All effects have this
* Uint16 button; // Button that triggers effect.
* Uint16 interval; // How soon before effect can be triggered again.
*
* // Envelope - Not all effects have this
* Uint16 attack_length; // Duration of the attack (ms).
* Uint16 attack_level; // Level at the start of the attack.
* Uint16 fade_length; // Duration of the fade out (ms).
* Uint16 fade_level; // Level at the end of the fade.
* \endcode
547
548
*
*
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
* Here we have an example of an effect evolution in time:
*
* \code
* Strength
* ^
* |
* | effect strength --> _________________
* | / \
* | / \
* | / \
* | / \
* | attack_level --> | \
* | | | <--- fade_level
* |
* +--------------------------------------------------> Time
* [--] [---]
* attack_length fade_length
*
* [------------------][-----------------------]
* delay length
* \endcode
570
571
572
573
*
* \sa SDL_HapticConstant
* \sa SDL_HapticPeriodic
* \sa SDL_HapticCondition
574
* \sa SDL_HapticRamp
575
*/
576
577
typedef union SDL_HapticEffect {
/* Common for all force feedback effects */
578
579
580
Uint16 type; /**< Effect type. */
SDL_HapticConstant constant; /**< Constant effect. */
SDL_HapticPeriodic periodic; /**< Periodic effect. */
581
SDL_HapticCondition condition; /**< Condition effect. */
582
SDL_HapticRamp ramp; /**< Ramp effect. */
583
584
} SDL_HapticEffect;
585
586
/* Function prototypes */
587
/**
588
589
590
591
592
* \fn int SDL_NumHaptics(void)
*
* \brief Count the number of joysticks attached to the system.
*
* \return Number of haptic devices detected on the system.
593
594
595
*/
extern DECLSPEC int SDLCALL SDL_NumHaptics(void);
596
/**
597
598
599
* \fn const char * SDL_HapticName(int device_index)
*
* \brief Get the implementation dependent name of a Haptic device.
600
601
* This can be called before any joysticks are opened.
* If no name can be found, this function returns NULL.
602
603
604
605
606
*
* \param device_index Index of the device to get it's name.
* \return Name of the device or NULL on error.
*
* \sa SDL_NumHaptics
607
608
609
*/
extern DECLSPEC const char *SDLCALL SDL_HapticName(int device_index);
610
/**
611
* \fn SDL_Haptic * SDL_HapticOpen(int device_index)
612
613
*
* \brief Opens a Haptic device for usage - the index passed as an
614
615
616
617
* argument refers to the N'th Haptic device on this system.
*
* This function returns a Haptic device identifier, or Null
* if an error occurred.
618
619
620
621
622
623
*
* \param device_index Index of the device to open.
* \return Device identifier or NULL on error.
*
* \sa SDL_HapticOpenFromJoystick
* \sa SDL_HapticClose
624
625
626
*/
extern DECLSPEC SDL_Haptic * SDL_HapticOpen(int device_index);
627
628
/**
* \fn int SDL_JoystickIsHaptic(SDL_Joystick * joystick)
629
630
631
632
633
634
*
* \brief Checks to see if a joystick has haptic features.
*
* \param joystick Joystick to test for haptic capabilities.
* \return SDL_TRUE if the joystick is haptic, SDL_FALSE if it isn't
* or -1 if an error ocurred.
635
*
636
* \sa SDL_HapticOpenFromJoystick
637
638
639
*/
extern DECLSPEC int SDL_JoystickIsHaptic(SDL_Joystick * joystick);
640
/**
641
* \fn SDL_Haptic * SDL_HapticOpenFromJoystick(SDL_Joystick * joystick)
642
*
643
644
645
646
647
648
649
650
* \brief Opens a Haptic device for usage from a Joystick device. Still has
* to be closed seperately to the joystick.
*
* \param joystick Joystick to create a haptic device from.
* \return A valid haptic device identifier on success or NULL on error.
*
* \sa SDL_HapticOpen
* \sa SDL_HapticClose
651
652
653
*/
extern DECLSPEC SDL_Haptic * SDL_HapticOpenFromJoystick(SDL_Joystick * joystick);
654
/**
655
656
657
658
659
* \fn void SDL_HapticClose(SDL_Haptic * haptic)
*
* \brief Closes a Haptic device previously opened with SDL_HapticOpen.
*
* \param haptic Haptic device to close.
660
661
662
*/
extern DECLSPEC void SDL_HapticClose(SDL_Haptic * haptic);
663
/**
664
665
666
667
668
669
670
671
672
* \fn int SDL_HapticNumEffects(SDL_Haptic * haptic)
*
* \brief Returns the number of effects a haptic device can store.
*
* \param haptic The haptic device to query effect max.
* \return The number of effects the haptic device can store or
* -1 on error.
*
* \sa SDL_HapticQuery
673
674
675
*/
extern DECLSPEC int SDL_HapticNumEffects(SDL_Haptic * haptic);
676
/**
677
* \fn unsigned int SDL_HapticQuery(SDL_Haptic * haptic)
678
679
680
681
682
683
684
685
686
687
688
689
690
*
* \brief Gets the haptic devices supported features in bitwise matter.
*
* Example:
* \code
* if (SDL_HapticQueryEffects(haptic) & SDL_HAPTIC_CONSTANT) {
* printf("We have constant haptic effect!");
* }
* \endcode
*
*
* \param haptic The haptic device to query.
* \return Haptic features in bitwise manner (OR'd).
691
*
692
693
* \sa SDL_HapticNumEffects
* \sa SDL_HapticEffectSupported
694
*/
695
extern DECLSPEC unsigned int SDL_HapticQuery(SDL_Haptic * haptic);
696
697
/**
698
* \fn int SDL_HapticEffectSupported(SDL_Haptic * haptic, SDL_HapticEffect * effect)
699
*
700
701
702
703
704
705
706
707
708
* \brief Checks to see if effect is supported by haptic.
*
* \param haptic Haptic device to check on.
* \param effect Effect to check to see if it is supported.
* \return SDL_TRUE if effect is supported, SDL_FALSE if it isn't or
* -1 on error.
*
* \sa SDL_HapticQuery
* \sa SDL_HapticNewEffect
709
710
711
*/
extern DECLSPEC int SDL_HapticEffectSupported(SDL_Haptic * haptic, SDL_HapticEffect * effect);
712
/**
713
714
715
* \fn int SDL_HapticNewEffect(SDL_Haptic * haptic, SDL_HapticEffect * effect)
*
* \brief Creates a new haptic effect on the device.
716
*
717
718
719
720
721
722
723
* \param haptic Haptic device to create the effect on.
* \param effect Properties of the effect to create.
* \return The id of the effect on success or -1 on error.
*
* \sa SDL_HapticUpdateEffect
* \sa SDL_HapticRunEffect
* \sa SDL_HapticDestroyEffect
724
725
726
*/
extern DECLSPEC int SDL_HapticNewEffect(SDL_Haptic * haptic, SDL_HapticEffect * effect);
727
/**
728
729
730
* \fn int SDL_HapticUpdateEffect(SDL_Haptic * haptic, int effect, SDL_HapticEffect * data)
*
* \brief Updates an effect. Can be used dynamically, although behaviour when
731
732
733
734
* dynamically changing direction may be strange. Specifically the effect
* may reupload itself and start playing from the start. You cannot change
* the type either when running UpdateEffect.
*
735
736
737
738
739
740
741
742
* \param haptic Haptic device that has the effect.
* \param effect Effect to update.
* \param data New effect properties to use.
* \return The id of the effect on success or -1 on error.
*
* \sa SDL_HapticNewEffect
* \sa SDL_HapticRunEffect
* \sa SDL_HapticDestroyEffect
743
744
745
*/
extern DECLSPEC int SDL_HapticUpdateEffect(SDL_Haptic * haptic, int effect, SDL_HapticEffect * data);
746
/**
747
* \fn int SDL_HapticRunEffect(SDL_Haptic * haptic, int effect)
748
*
749
750
751
752
753
754
755
756
757
* \brief Runs the haptic effect on it's assosciated haptic device.
*
* \param haptic Haptic device to run the effect on.
* \param effect Identifier of the haptic effect to run.
* \return 0 on success or -1 on error.
*
* \sa SDL_HapticStopEffect
* \sa SDL_HapticDestroyEffect
* \sa SDL_HapticGetEffectStatus
758
759
760
*/
extern DECLSPEC int SDL_HapticRunEffect(SDL_Haptic * haptic, int effect);
761
/**
762
763
764
* \fn int SDL_HapticStopEffect(SDL_Haptic * haptic, int effect)
*
* \brief Stops the haptic effect on it's assosciated haptic device.
765
*
766
* \param haptic Haptic device to stop the effect on.
767
* \param effect Identifier of the effect to stop.
768
769
770
771
* \return 0 on success or -1 on error.
*
* \sa SDL_HapticRunEffect
* \sa SDL_HapticDestroyEffect
772
773
774
*/
extern DECLSPEC int SDL_HapticStopEffect(SDL_Haptic * haptic, int effect);
775
/**
776
777
778
779
780
781
782
783
784
785
* \fn void SDL_HapticDestroyEffect(SDL_Haptic * haptic, int effect)
*
* \brief Destroys a haptic effect on the device. This will stop the effect
* if it's running. Effects are automatically destroyed when the device is
* closed.
*
* \param haptic Device to destroy the effect on.
* \param effect Identifier of the effect to destroy.
*
* \sa SDL_HapticNewEffect
786
787
788
*/
extern DECLSPEC void SDL_HapticDestroyEffect(SDL_Haptic * haptic, int effect);
789
/**
790
791
792
* \fn int SDL_HapticGetEffectStatus(SDL_Haptic *haptic, int effect)
*
* \brief Gets the status of the current effect on the haptic device.
793
*
794
795
796
797
798
799
800
801
802
* Device must support the SDL_HAPTIC_STATUS feature.
*
* \param haptic Haptic device to query the effect status on.
* \param effect Identifier of the effect to query it's status.
* \return 0 if it isn't playing, SDL_HAPTIC_PLAYING if it is playing
* or -1 on error.
*
* \sa SDL_HapticRunEffect
* \sa SDL_HapticStopEffect
803
804
805
*/
extern DECLSPEC int SDL_HapticGetEffectStatus(SDL_Haptic *haptic, int effect);
806
/**
807
808
809
* \fn int SDL_HapticSetGain(SDL_Haptic * haptic, int gain)
*
* \brief Sets the global gain of the device. Gain should be between 0 and 100.
810
*
811
812
813
814
815
816
817
* Device must support the SDL_HAPTIC_GAIN feature.
*
* \param haptic Haptic device to set the gain on.
* \param gain Value to set the gain to, should be between 0 and 100.
* \return 0 on success or -1 on error.
*
* \sa SDL_HapticQuery
818
819
820
*/
extern DECLSPEC int SDL_HapticSetGain(SDL_Haptic * haptic, int gain);
821
/**
822
823
824
* \fn int SDL_HapticSetAutocenter(SDL_Haptic * haptic, int autocenter)
*
* \brief Sets the global autocenter of the device. Autocenter should be between
825
826
* 0 and 100. Setting it to 0 will disable autocentering.
*
827
828
829
830
831
832
833
* Device must support the SDL_HAPTIC_AUTOCENTER feature.
*
* \param haptic Haptic device to set autocentering on.
* \param autocenter Value to set autocenter to, 0 disables autocentering.
* \return 0 on success or -1 on error.
*
* \sa SDL_HapticQuery
834
835
836
*/
extern DECLSPEC int SDL_HapticSetAutocenter(SDL_Haptic * haptic, int autocenter);
837
838
839
840
841
842
843
844
845
846
847
848
/* Ends C function definitions when using C++ */
#ifdef __cplusplus
/* *INDENT-OFF* */
}
/* *INDENT-ON* */
#endif
#include "close_code.h"
#endif /* _SDL_haptic_h */
/* vi: set ts=4 sw=4 expandtab: */