My Project
SDL_haptic.h
Go to the documentation of this file.
1 /*
2  Simple DirectMedia Layer
3  Copyright (C) 1997-2020 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 
107 #ifndef SDL_haptic_h_
108 #define SDL_haptic_h_
109 
110 #include "SDL_stdinc.h"
111 #include "SDL_error.h"
112 #include "SDL_joystick.h"
113 
114 #include "begin_code.h"
115 /* Set up for C function definitions, even when using C++ */
116 #ifdef __cplusplus
117 extern "C" {
118 #endif /* __cplusplus */
119 
120 /* FIXME: For SDL 2.1, adjust all the magnitude variables to be Uint16 (0xFFFF).
121  *
122  * At the moment the magnitude variables are mixed between signed/unsigned, and
123  * it is also not made clear that ALL of those variables expect a max of 0x7FFF.
124  *
125  * Some platforms may have higher precision than that (Linux FF, Windows XInput)
126  * so we should fix the inconsistency in favor of higher possible precision,
127  * adjusting for platforms that use different scales.
128  * -flibit
129  */
130 
140 struct _SDL_Haptic;
141 typedef struct _SDL_Haptic SDL_Haptic;
142 
143 
149 /* @{ */
150 
154 /* @{ */
155 
163 #define SDL_HAPTIC_CONSTANT (1u<<0)
164 
172 #define SDL_HAPTIC_SINE (1u<<1)
173 
183 #define SDL_HAPTIC_LEFTRIGHT (1u<<2)
184 
185 /* !!! FIXME: put this back when we have more bits in 2.1 */
186 /* #define SDL_HAPTIC_SQUARE (1<<2) */
187 
195 #define SDL_HAPTIC_TRIANGLE (1u<<3)
196 
204 #define SDL_HAPTIC_SAWTOOTHUP (1u<<4)
205 
213 #define SDL_HAPTIC_SAWTOOTHDOWN (1u<<5)
214 
222 #define SDL_HAPTIC_RAMP (1u<<6)
223 
232 #define SDL_HAPTIC_SPRING (1u<<7)
233 
242 #define SDL_HAPTIC_DAMPER (1u<<8)
243 
252 #define SDL_HAPTIC_INERTIA (1u<<9)
253 
262 #define SDL_HAPTIC_FRICTION (1u<<10)
263 
269 #define SDL_HAPTIC_CUSTOM (1u<<11)
270 
271 /* @} *//* Haptic effects */
272 
273 /* These last few are features the device has, not effects */
274 
282 #define SDL_HAPTIC_GAIN (1u<<12)
283 
291 #define SDL_HAPTIC_AUTOCENTER (1u<<13)
292 
300 #define SDL_HAPTIC_STATUS (1u<<14)
301 
310 #define SDL_HAPTIC_PAUSE (1u<<15)
311 
312 
316 /* @{ */
317 
323 #define SDL_HAPTIC_POLAR 0
324 
330 #define SDL_HAPTIC_CARTESIAN 1
331 
337 #define SDL_HAPTIC_SPHERICAL 2
338 
345 #define SDL_HAPTIC_STEERING_AXIS 3
346 
347 /* @} *//* Direction encodings */
348 
349 /* @} *//* Haptic features */
350 
351 /*
352  * Misc defines.
353  */
354 
360 #define SDL_HAPTIC_INFINITY 4294967295U
361 
362 
459 typedef struct SDL_HapticDirection
460 {
461  Uint8 type;
462  Sint32 dir[3];
464 
465 
477 typedef struct SDL_HapticConstant
478 {
479  /* Header */
480  Uint16 type;
483  /* Replay */
484  Uint32 length;
485  Uint16 delay;
487  /* Trigger */
488  Uint16 button;
489  Uint16 interval;
491  /* Constant */
492  Sint16 level;
494  /* Envelope */
495  Uint16 attack_length;
496  Uint16 attack_level;
497  Uint16 fade_length;
498  Uint16 fade_level;
500 
558 typedef struct SDL_HapticPeriodic
559 {
560  /* Header */
561  Uint16 type;
566  /* Replay */
567  Uint32 length;
568  Uint16 delay;
570  /* Trigger */
571  Uint16 button;
572  Uint16 interval;
574  /* Periodic */
575  Uint16 period;
576  Sint16 magnitude;
577  Sint16 offset;
578  Uint16 phase;
580  /* Envelope */
581  Uint16 attack_length;
582  Uint16 attack_level;
583  Uint16 fade_length;
584  Uint16 fade_level;
586 
611 typedef struct SDL_HapticCondition
612 {
613  /* Header */
614  Uint16 type;
618  /* Replay */
619  Uint32 length;
620  Uint16 delay;
622  /* Trigger */
623  Uint16 button;
624  Uint16 interval;
626  /* Condition */
627  Uint16 right_sat[3];
628  Uint16 left_sat[3];
629  Sint16 right_coeff[3];
630  Sint16 left_coeff[3];
631  Uint16 deadband[3];
632  Sint16 center[3];
634 
648 typedef struct SDL_HapticRamp
649 {
650  /* Header */
651  Uint16 type;
654  /* Replay */
655  Uint32 length;
656  Uint16 delay;
658  /* Trigger */
659  Uint16 button;
660  Uint16 interval;
662  /* Ramp */
663  Sint16 start;
664  Sint16 end;
666  /* Envelope */
667  Uint16 attack_length;
668  Uint16 attack_level;
669  Uint16 fade_length;
670  Uint16 fade_level;
672 
685 typedef struct SDL_HapticLeftRight
686 {
687  /* Header */
688  Uint16 type;
690  /* Replay */
691  Uint32 length;
693  /* Rumble */
697 
713 typedef struct SDL_HapticCustom
714 {
715  /* Header */
716  Uint16 type;
719  /* Replay */
720  Uint32 length;
721  Uint16 delay;
723  /* Trigger */
724  Uint16 button;
725  Uint16 interval;
727  /* Custom */
728  Uint8 channels;
729  Uint16 period;
730  Uint16 samples;
731  Uint16 *data;
733  /* Envelope */
734  Uint16 attack_length;
735  Uint16 attack_level;
736  Uint16 fade_length;
737  Uint16 fade_level;
739 
809 typedef union SDL_HapticEffect
810 {
811  /* Common for all force feedback effects */
812  Uint16 type;
820 
821 
822 /* Function prototypes */
828 extern DECLSPEC int SDLCALL SDL_NumHaptics(void);
829 
841 extern DECLSPEC const char *SDLCALL SDL_HapticName(int device_index);
842 
865 extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpen(int device_index);
866 
876 extern DECLSPEC int SDLCALL SDL_HapticOpened(int device_index);
877 
887 extern DECLSPEC int SDLCALL SDL_HapticIndex(SDL_Haptic * haptic);
888 
896 extern DECLSPEC int SDLCALL SDL_MouseIsHaptic(void);
897 
906 extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromMouse(void);
907 
917 extern DECLSPEC int SDLCALL SDL_JoystickIsHaptic(SDL_Joystick * joystick);
918 
936 extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromJoystick(SDL_Joystick *
937  joystick);
938 
944 extern DECLSPEC void SDLCALL SDL_HapticClose(SDL_Haptic * haptic);
945 
960 extern DECLSPEC int SDLCALL SDL_HapticNumEffects(SDL_Haptic * haptic);
961 
976 extern DECLSPEC int SDLCALL SDL_HapticNumEffectsPlaying(SDL_Haptic * haptic);
977 
994 extern DECLSPEC unsigned int SDLCALL SDL_HapticQuery(SDL_Haptic * haptic);
995 
996 
1002 extern DECLSPEC int SDLCALL SDL_HapticNumAxes(SDL_Haptic * haptic);
1003 
1014 extern DECLSPEC int SDLCALL SDL_HapticEffectSupported(SDL_Haptic * haptic,
1016  effect);
1017 
1029 extern DECLSPEC int SDLCALL SDL_HapticNewEffect(SDL_Haptic * haptic,
1030  SDL_HapticEffect * effect);
1031 
1049 extern DECLSPEC int SDLCALL SDL_HapticUpdateEffect(SDL_Haptic * haptic,
1050  int effect,
1051  SDL_HapticEffect * data);
1052 
1071 extern DECLSPEC int SDLCALL SDL_HapticRunEffect(SDL_Haptic * haptic,
1072  int effect,
1073  Uint32 iterations);
1074 
1085 extern DECLSPEC int SDLCALL SDL_HapticStopEffect(SDL_Haptic * haptic,
1086  int effect);
1087 
1099 extern DECLSPEC void SDLCALL SDL_HapticDestroyEffect(SDL_Haptic * haptic,
1100  int effect);
1101 
1114 extern DECLSPEC int SDLCALL SDL_HapticGetEffectStatus(SDL_Haptic * haptic,
1115  int effect);
1116 
1133 extern DECLSPEC int SDLCALL SDL_HapticSetGain(SDL_Haptic * haptic, int gain);
1134 
1149 extern DECLSPEC int SDLCALL SDL_HapticSetAutocenter(SDL_Haptic * haptic,
1150  int autocenter);
1151 
1166 extern DECLSPEC int SDLCALL SDL_HapticPause(SDL_Haptic * haptic);
1167 
1178 extern DECLSPEC int SDLCALL SDL_HapticUnpause(SDL_Haptic * haptic);
1179 
1186 extern DECLSPEC int SDLCALL SDL_HapticStopAll(SDL_Haptic * haptic);
1187 
1198 extern DECLSPEC int SDLCALL SDL_HapticRumbleSupported(SDL_Haptic * haptic);
1199 
1211 extern DECLSPEC int SDLCALL SDL_HapticRumbleInit(SDL_Haptic * haptic);
1212 
1225 extern DECLSPEC int SDLCALL SDL_HapticRumblePlay(SDL_Haptic * haptic, float strength, Uint32 length );
1226 
1237 extern DECLSPEC int SDLCALL SDL_HapticRumbleStop(SDL_Haptic * haptic);
1238 
1239 /* Ends C function definitions when using C++ */
1240 #ifdef __cplusplus
1241 }
1242 #endif
1243 #include "close_code.h"
1244 
1245 #endif /* SDL_haptic_h_ */
1246 
1247 /* vi: set ts=4 sw=4 expandtab: */
DECLSPEC int SDLCALL SDL_HapticSetAutocenter(SDL_Haptic *haptic, int autocenter)
Sets the global autocenter of the device.
DECLSPEC void SDLCALL SDL_HapticDestroyEffect(SDL_Haptic *haptic, int effect)
Destroys a haptic effect on the device.
struct SDL_HapticPeriodic SDL_HapticPeriodic
A structure containing a template for a Periodic effect.
DECLSPEC int SDLCALL SDL_HapticNewEffect(SDL_Haptic *haptic, SDL_HapticEffect *effect)
Creates a new haptic effect on the device.
DECLSPEC int SDLCALL SDL_HapticRunEffect(SDL_Haptic *haptic, int effect, Uint32 iterations)
Runs the haptic effect on its associated haptic device.
DECLSPEC int SDLCALL SDL_HapticOpened(int device_index)
Checks if the haptic device at index has been opened.
DECLSPEC int SDLCALL SDL_HapticNumEffectsPlaying(SDL_Haptic *haptic)
Returns the number of effects a haptic device can play at the same time.
DECLSPEC int SDLCALL SDL_HapticStopEffect(SDL_Haptic *haptic, int effect)
Stops the haptic effect on its associated haptic device.
DECLSPEC int SDLCALL SDL_HapticSetGain(SDL_Haptic *haptic, int gain)
Sets the global gain of the device.
DECLSPEC int SDLCALL SDL_HapticUnpause(SDL_Haptic *haptic)
Unpauses a haptic device.
DECLSPEC int SDLCALL SDL_HapticUpdateEffect(SDL_Haptic *haptic, int effect, SDL_HapticEffect *data)
Updates the properties of an effect.
DECLSPEC void SDLCALL SDL_HapticClose(SDL_Haptic *haptic)
Closes a haptic device previously opened with SDL_HapticOpen().
struct SDL_HapticDirection SDL_HapticDirection
Structure that represents a haptic direction.
DECLSPEC int SDLCALL SDL_NumHaptics(void)
Count the number of haptic devices attached to the system.
struct _SDL_Haptic SDL_Haptic
The haptic structure used to identify an SDL haptic.
Definition: SDL_haptic.h:141
union SDL_HapticEffect SDL_HapticEffect
The generic template for any haptic effect.
DECLSPEC unsigned int SDLCALL SDL_HapticQuery(SDL_Haptic *haptic)
Gets the haptic device's supported features in bitwise manner.
DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromJoystick(SDL_Joystick *joystick)
Opens a haptic device for use from a joystick device.
DECLSPEC const char *SDLCALL SDL_HapticName(int device_index)
Get the implementation dependent name of a haptic device.
DECLSPEC int SDLCALL SDL_JoystickIsHaptic(SDL_Joystick *joystick)
Checks to see if a joystick has haptic features.
DECLSPEC int SDLCALL SDL_MouseIsHaptic(void)
Gets whether or not the current mouse has haptic capabilities.
DECLSPEC int SDLCALL SDL_HapticRumblePlay(SDL_Haptic *haptic, float strength, Uint32 length)
Runs simple rumble on a haptic device.
DECLSPEC int SDLCALL SDL_HapticRumbleStop(SDL_Haptic *haptic)
Stops the simple rumble on a haptic device.
DECLSPEC int SDLCALL SDL_HapticRumbleSupported(SDL_Haptic *haptic)
Checks to see if rumble is supported on a haptic device.
DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromMouse(void)
Tries to open a haptic device from the current mouse.
DECLSPEC int SDLCALL SDL_HapticIndex(SDL_Haptic *haptic)
Gets the index of a haptic device.
DECLSPEC int SDLCALL SDL_HapticStopAll(SDL_Haptic *haptic)
Stops all the currently playing effects on a haptic device.
struct SDL_HapticCustom SDL_HapticCustom
A structure containing a template for the SDL_HAPTIC_CUSTOM effect.
DECLSPEC int SDLCALL SDL_HapticNumAxes(SDL_Haptic *haptic)
Gets the number of haptic axes the device has.
struct SDL_HapticConstant SDL_HapticConstant
A structure containing a template for a Constant effect.
struct SDL_HapticLeftRight SDL_HapticLeftRight
A structure containing a template for a Left/Right effect.
DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpen(int device_index)
Opens a haptic device for use.
DECLSPEC int SDLCALL SDL_HapticGetEffectStatus(SDL_Haptic *haptic, int effect)
Gets the status of the current effect on the haptic device.
DECLSPEC int SDLCALL SDL_HapticEffectSupported(SDL_Haptic *haptic, SDL_HapticEffect *effect)
Checks to see if effect is supported by haptic.
DECLSPEC int SDLCALL SDL_HapticPause(SDL_Haptic *haptic)
Pauses a haptic device.
DECLSPEC int SDLCALL SDL_HapticRumbleInit(SDL_Haptic *haptic)
Initializes the haptic device for simple rumble playback.
struct SDL_HapticCondition SDL_HapticCondition
A structure containing a template for a Condition effect.
struct SDL_HapticRamp SDL_HapticRamp
A structure containing a template for a Ramp effect.
DECLSPEC int SDLCALL SDL_HapticNumEffects(SDL_Haptic *haptic)
Returns the number of effects a haptic device can store.
A structure containing a template for a Condition effect.
Definition: SDL_haptic.h:612
Sint16 left_coeff[3]
Definition: SDL_haptic.h:630
Sint16 right_coeff[3]
Definition: SDL_haptic.h:629
SDL_HapticDirection direction
Definition: SDL_haptic.h:616
Uint16 type
Definition: SDL_haptic.h:614
Sint16 center[3]
Definition: SDL_haptic.h:632
Uint16 right_sat[3]
Definition: SDL_haptic.h:627
Uint16 left_sat[3]
Definition: SDL_haptic.h:628
Uint16 delay
Definition: SDL_haptic.h:620
Uint16 interval
Definition: SDL_haptic.h:624
Uint16 button
Definition: SDL_haptic.h:623
Uint32 length
Definition: SDL_haptic.h:619
Uint16 deadband[3]
Definition: SDL_haptic.h:631
A structure containing a template for a Constant effect.
Definition: SDL_haptic.h:478
Uint16 attack_level
Definition: SDL_haptic.h:496
Uint16 delay
Definition: SDL_haptic.h:485
SDL_HapticDirection direction
Definition: SDL_haptic.h:481
Uint16 fade_level
Definition: SDL_haptic.h:498
Sint16 level
Definition: SDL_haptic.h:492
Uint16 type
Definition: SDL_haptic.h:480
Uint16 fade_length
Definition: SDL_haptic.h:497
Uint16 attack_length
Definition: SDL_haptic.h:495
Uint16 button
Definition: SDL_haptic.h:488
Uint16 interval
Definition: SDL_haptic.h:489
Uint32 length
Definition: SDL_haptic.h:484
A structure containing a template for the SDL_HAPTIC_CUSTOM effect.
Definition: SDL_haptic.h:714
Uint16 attack_length
Definition: SDL_haptic.h:734
Uint16 delay
Definition: SDL_haptic.h:721
Uint8 channels
Definition: SDL_haptic.h:728
Uint16 samples
Definition: SDL_haptic.h:730
Uint16 fade_level
Definition: SDL_haptic.h:737
Uint16 type
Definition: SDL_haptic.h:716
Uint16 button
Definition: SDL_haptic.h:724
Uint16 fade_length
Definition: SDL_haptic.h:736
Uint16 period
Definition: SDL_haptic.h:729
Uint16 * data
Definition: SDL_haptic.h:731
Uint16 attack_level
Definition: SDL_haptic.h:735
Uint32 length
Definition: SDL_haptic.h:720
SDL_HapticDirection direction
Definition: SDL_haptic.h:717
Uint16 interval
Definition: SDL_haptic.h:725
Structure that represents a haptic direction.
Definition: SDL_haptic.h:460
Sint32 dir[3]
Definition: SDL_haptic.h:462
Uint8 type
Definition: SDL_haptic.h:461
A structure containing a template for a Left/Right effect.
Definition: SDL_haptic.h:686
Uint32 length
Definition: SDL_haptic.h:691
Uint16 large_magnitude
Definition: SDL_haptic.h:694
Uint16 small_magnitude
Definition: SDL_haptic.h:695
Uint16 type
Definition: SDL_haptic.h:688
A structure containing a template for a Periodic effect.
Definition: SDL_haptic.h:559
Uint16 interval
Definition: SDL_haptic.h:572
Uint16 period
Definition: SDL_haptic.h:575
Uint32 length
Definition: SDL_haptic.h:567
Uint16 phase
Definition: SDL_haptic.h:578
SDL_HapticDirection direction
Definition: SDL_haptic.h:564
Uint16 attack_level
Definition: SDL_haptic.h:582
Uint16 delay
Definition: SDL_haptic.h:568
Uint16 button
Definition: SDL_haptic.h:571
Sint16 magnitude
Definition: SDL_haptic.h:576
Uint16 attack_length
Definition: SDL_haptic.h:581
Sint16 offset
Definition: SDL_haptic.h:577
Uint16 type
Definition: SDL_haptic.h:561
Uint16 fade_length
Definition: SDL_haptic.h:583
Uint16 fade_level
Definition: SDL_haptic.h:584
A structure containing a template for a Ramp effect.
Definition: SDL_haptic.h:649
Sint16 end
Definition: SDL_haptic.h:664
Uint16 button
Definition: SDL_haptic.h:659
Uint16 interval
Definition: SDL_haptic.h:660
Uint32 length
Definition: SDL_haptic.h:655
Uint16 fade_level
Definition: SDL_haptic.h:670
SDL_HapticDirection direction
Definition: SDL_haptic.h:652
Uint16 attack_level
Definition: SDL_haptic.h:668
Uint16 delay
Definition: SDL_haptic.h:656
Uint16 type
Definition: SDL_haptic.h:651
Sint16 start
Definition: SDL_haptic.h:663
Uint16 fade_length
Definition: SDL_haptic.h:669
Uint16 attack_length
Definition: SDL_haptic.h:667
The generic template for any haptic effect.
Definition: SDL_haptic.h:810
SDL_HapticCustom custom
Definition: SDL_haptic.h:818
SDL_HapticRamp ramp
Definition: SDL_haptic.h:816
SDL_HapticLeftRight leftright
Definition: SDL_haptic.h:817
Uint16 type
Definition: SDL_haptic.h:812
SDL_HapticPeriodic periodic
Definition: SDL_haptic.h:814
SDL_HapticCondition condition
Definition: SDL_haptic.h:815
SDL_HapticConstant constant
Definition: SDL_haptic.h:813