My Project
SDL_haptic.h
Go to the documentation of this file.
1 /*
2  Simple DirectMedia Layer
3  Copyright (C) 1997-2018 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 
339 /* @} *//* Direction encodings */
340 
341 /* @} *//* Haptic features */
342 
343 /*
344  * Misc defines.
345  */
346 
352 #define SDL_HAPTIC_INFINITY 4294967295U
353 
354 
450 typedef struct SDL_HapticDirection
451 {
452  Uint8 type;
453  Sint32 dir[3];
455 
456 
468 typedef struct SDL_HapticConstant
469 {
470  /* Header */
471  Uint16 type;
474  /* Replay */
475  Uint32 length;
476  Uint16 delay;
478  /* Trigger */
479  Uint16 button;
480  Uint16 interval;
482  /* Constant */
483  Sint16 level;
485  /* Envelope */
486  Uint16 attack_length;
487  Uint16 attack_level;
488  Uint16 fade_length;
489  Uint16 fade_level;
491 
549 typedef struct SDL_HapticPeriodic
550 {
551  /* Header */
552  Uint16 type;
557  /* Replay */
558  Uint32 length;
559  Uint16 delay;
561  /* Trigger */
562  Uint16 button;
563  Uint16 interval;
565  /* Periodic */
566  Uint16 period;
567  Sint16 magnitude;
568  Sint16 offset;
569  Uint16 phase;
571  /* Envelope */
572  Uint16 attack_length;
573  Uint16 attack_level;
574  Uint16 fade_length;
575  Uint16 fade_level;
577 
602 typedef struct SDL_HapticCondition
603 {
604  /* Header */
605  Uint16 type;
609  /* Replay */
610  Uint32 length;
611  Uint16 delay;
613  /* Trigger */
614  Uint16 button;
615  Uint16 interval;
617  /* Condition */
618  Uint16 right_sat[3];
619  Uint16 left_sat[3];
620  Sint16 right_coeff[3];
621  Sint16 left_coeff[3];
622  Uint16 deadband[3];
623  Sint16 center[3];
625 
639 typedef struct SDL_HapticRamp
640 {
641  /* Header */
642  Uint16 type;
645  /* Replay */
646  Uint32 length;
647  Uint16 delay;
649  /* Trigger */
650  Uint16 button;
651  Uint16 interval;
653  /* Ramp */
654  Sint16 start;
655  Sint16 end;
657  /* Envelope */
658  Uint16 attack_length;
659  Uint16 attack_level;
660  Uint16 fade_length;
661  Uint16 fade_level;
663 
676 typedef struct SDL_HapticLeftRight
677 {
678  /* Header */
679  Uint16 type;
681  /* Replay */
682  Uint32 length;
684  /* Rumble */
688 
704 typedef struct SDL_HapticCustom
705 {
706  /* Header */
707  Uint16 type;
710  /* Replay */
711  Uint32 length;
712  Uint16 delay;
714  /* Trigger */
715  Uint16 button;
716  Uint16 interval;
718  /* Custom */
719  Uint8 channels;
720  Uint16 period;
721  Uint16 samples;
722  Uint16 *data;
724  /* Envelope */
725  Uint16 attack_length;
726  Uint16 attack_level;
727  Uint16 fade_length;
728  Uint16 fade_level;
730 
800 typedef union SDL_HapticEffect
801 {
802  /* Common for all force feedback effects */
803  Uint16 type;
811 
812 
813 /* Function prototypes */
819 extern DECLSPEC int SDLCALL SDL_NumHaptics(void);
820 
832 extern DECLSPEC const char *SDLCALL SDL_HapticName(int device_index);
833 
856 extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpen(int device_index);
857 
867 extern DECLSPEC int SDLCALL SDL_HapticOpened(int device_index);
868 
878 extern DECLSPEC int SDLCALL SDL_HapticIndex(SDL_Haptic * haptic);
879 
887 extern DECLSPEC int SDLCALL SDL_MouseIsHaptic(void);
888 
897 extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromMouse(void);
898 
908 extern DECLSPEC int SDLCALL SDL_JoystickIsHaptic(SDL_Joystick * joystick);
909 
927 extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromJoystick(SDL_Joystick *
928  joystick);
929 
935 extern DECLSPEC void SDLCALL SDL_HapticClose(SDL_Haptic * haptic);
936 
951 extern DECLSPEC int SDLCALL SDL_HapticNumEffects(SDL_Haptic * haptic);
952 
967 extern DECLSPEC int SDLCALL SDL_HapticNumEffectsPlaying(SDL_Haptic * haptic);
968 
985 extern DECLSPEC unsigned int SDLCALL SDL_HapticQuery(SDL_Haptic * haptic);
986 
987 
993 extern DECLSPEC int SDLCALL SDL_HapticNumAxes(SDL_Haptic * haptic);
994 
1005 extern DECLSPEC int SDLCALL SDL_HapticEffectSupported(SDL_Haptic * haptic,
1007  effect);
1008 
1020 extern DECLSPEC int SDLCALL SDL_HapticNewEffect(SDL_Haptic * haptic,
1021  SDL_HapticEffect * effect);
1022 
1040 extern DECLSPEC int SDLCALL SDL_HapticUpdateEffect(SDL_Haptic * haptic,
1041  int effect,
1042  SDL_HapticEffect * data);
1043 
1062 extern DECLSPEC int SDLCALL SDL_HapticRunEffect(SDL_Haptic * haptic,
1063  int effect,
1064  Uint32 iterations);
1065 
1076 extern DECLSPEC int SDLCALL SDL_HapticStopEffect(SDL_Haptic * haptic,
1077  int effect);
1078 
1090 extern DECLSPEC void SDLCALL SDL_HapticDestroyEffect(SDL_Haptic * haptic,
1091  int effect);
1092 
1105 extern DECLSPEC int SDLCALL SDL_HapticGetEffectStatus(SDL_Haptic * haptic,
1106  int effect);
1107 
1124 extern DECLSPEC int SDLCALL SDL_HapticSetGain(SDL_Haptic * haptic, int gain);
1125 
1140 extern DECLSPEC int SDLCALL SDL_HapticSetAutocenter(SDL_Haptic * haptic,
1141  int autocenter);
1142 
1157 extern DECLSPEC int SDLCALL SDL_HapticPause(SDL_Haptic * haptic);
1158 
1169 extern DECLSPEC int SDLCALL SDL_HapticUnpause(SDL_Haptic * haptic);
1170 
1177 extern DECLSPEC int SDLCALL SDL_HapticStopAll(SDL_Haptic * haptic);
1178 
1189 extern DECLSPEC int SDLCALL SDL_HapticRumbleSupported(SDL_Haptic * haptic);
1190 
1202 extern DECLSPEC int SDLCALL SDL_HapticRumbleInit(SDL_Haptic * haptic);
1203 
1216 extern DECLSPEC int SDLCALL SDL_HapticRumblePlay(SDL_Haptic * haptic, float strength, Uint32 length );
1217 
1228 extern DECLSPEC int SDLCALL SDL_HapticRumbleStop(SDL_Haptic * haptic);
1229 
1230 /* Ends C function definitions when using C++ */
1231 #ifdef __cplusplus
1232 }
1233 #endif
1234 #include "close_code.h"
1235 
1236 #endif /* SDL_haptic_h_ */
1237 
1238 /* vi: set ts=4 sw=4 expandtab: */
DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromMouse(void)
Tries to open a haptic device from the current mouse.
DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpen(int device_index)
Opens a haptic device for use.
DECLSPEC void SDLCALL SDL_HapticClose(SDL_Haptic *haptic)
Closes a haptic device previously opened with SDL_HapticOpen().
Uint16 right_sat[3]
Definition: SDL_haptic.h:618
SDL_HapticCustom custom
Definition: SDL_haptic.h:809
Uint16 interval
Definition: SDL_haptic.h:716
A structure containing a template for the SDL_HAPTIC_CUSTOM effect.
Definition: SDL_haptic.h:704
Sint16 level
Definition: SDL_haptic.h:483
Uint16 samples
Definition: SDL_haptic.h:721
Uint16 fade_level
Definition: SDL_haptic.h:661
struct SDL_HapticRamp SDL_HapticRamp
A structure containing a template for a Ramp effect.
DECLSPEC int SDLCALL SDL_HapticIndex(SDL_Haptic *haptic)
Gets the index of a haptic device.
Uint16 attack_length
Definition: SDL_haptic.h:572
Uint16 large_magnitude
Definition: SDL_haptic.h:685
struct _SDL_Haptic SDL_Haptic
The haptic structure used to identify an SDL haptic.
Definition: SDL_haptic.h:141
struct SDL_HapticPeriodic SDL_HapticPeriodic
A structure containing a template for a Periodic effect.
Uint16 fade_level
Definition: SDL_haptic.h:489
DECLSPEC int SDLCALL SDL_HapticStopAll(SDL_Haptic *haptic)
Stops all the currently playing effects on a haptic device.
DECLSPEC int SDLCALL SDL_HapticStopEffect(SDL_Haptic *haptic, int effect)
Stops the haptic effect on its associated haptic device.
Sint16 center[3]
Definition: SDL_haptic.h:623
Uint8 type
Definition: SDL_haptic.h:452
Uint16 button
Definition: SDL_haptic.h:650
Sint32 dir[3]
Definition: SDL_haptic.h:453
Uint16 attack_level
Definition: SDL_haptic.h:573
Uint16 period
Definition: SDL_haptic.h:720
Uint16 small_magnitude
Definition: SDL_haptic.h:686
Uint16 fade_length
Definition: SDL_haptic.h:574
Uint16 attack_length
Definition: SDL_haptic.h:725
Uint16 deadband[3]
Definition: SDL_haptic.h:622
Uint16 attack_level
Definition: SDL_haptic.h:487
Uint16 delay
Definition: SDL_haptic.h:647
Uint16 delay
Definition: SDL_haptic.h:559
SDL_HapticConstant constant
Definition: SDL_haptic.h:804
Uint16 button
Definition: SDL_haptic.h:562
Uint16 type
Definition: SDL_haptic.h:471
SDL_HapticDirection direction
Definition: SDL_haptic.h:607
Uint16 button
Definition: SDL_haptic.h:479
DECLSPEC int SDLCALL SDL_HapticOpened(int device_index)
Checks if the haptic device at index has been opened.
Uint16 * data
Definition: SDL_haptic.h:722
Uint16 period
Definition: SDL_haptic.h:566
Uint32 length
Definition: SDL_haptic.h:475
DECLSPEC int SDLCALL SDL_HapticUpdateEffect(SDL_Haptic *haptic, int effect, SDL_HapticEffect *data)
Updates the properties of an effect.
A structure containing a template for a Constant effect.
Definition: SDL_haptic.h:468
DECLSPEC int SDLCALL SDL_HapticRumbleInit(SDL_Haptic *haptic)
Initializes the haptic device for simple rumble playback.
Uint16 button
Definition: SDL_haptic.h:715
Uint8 channels
Definition: SDL_haptic.h:719
Uint16 fade_length
Definition: SDL_haptic.h:727
DECLSPEC int SDLCALL SDL_HapticNumEffectsPlaying(SDL_Haptic *haptic)
Returns the number of effects a haptic device can play at the same time.
struct SDL_HapticLeftRight SDL_HapticLeftRight
A structure containing a template for a Left/Right effect.
SDL_HapticDirection direction
Definition: SDL_haptic.h:708
DECLSPEC int SDLCALL SDL_HapticNewEffect(SDL_Haptic *haptic, SDL_HapticEffect *effect)
Creates a new haptic effect on the device.
SDL_HapticDirection direction
Definition: SDL_haptic.h:643
DECLSPEC int SDLCALL SDL_HapticRumblePlay(SDL_Haptic *haptic, float strength, Uint32 length)
Runs simple rumble on a haptic device.
Uint32 length
Definition: SDL_haptic.h:711
Uint16 button
Definition: SDL_haptic.h:614
SDL_HapticDirection direction
Definition: SDL_haptic.h:472
DECLSPEC int SDLCALL SDL_HapticGetEffectStatus(SDL_Haptic *haptic, int effect)
Gets the status of the current effect on the haptic device.
Uint32 length
Definition: SDL_haptic.h:558
Uint16 delay
Definition: SDL_haptic.h:611
DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromJoystick(SDL_Joystick *joystick)
Opens a haptic device for use from a joystick device.
SDL_HapticCondition condition
Definition: SDL_haptic.h:806
Uint16 type
Definition: SDL_haptic.h:552
Sint16 end
Definition: SDL_haptic.h:655
DECLSPEC void SDLCALL SDL_HapticDestroyEffect(SDL_Haptic *haptic, int effect)
Destroys a haptic effect on the device.
Uint16 fade_length
Definition: SDL_haptic.h:660
Uint16 type
Definition: SDL_haptic.h:642
Uint16 interval
Definition: SDL_haptic.h:480
A structure containing a template for a Periodic effect.
Definition: SDL_haptic.h:549
DECLSPEC int SDLCALL SDL_HapticEffectSupported(SDL_Haptic *haptic, SDL_HapticEffect *effect)
Checks to see if effect is supported by haptic.
Uint16 type
Definition: SDL_haptic.h:679
Sint16 magnitude
Definition: SDL_haptic.h:567
Sint16 right_coeff[3]
Definition: SDL_haptic.h:620
Uint32 length
Definition: SDL_haptic.h:682
Uint16 fade_length
Definition: SDL_haptic.h:488
Uint16 fade_level
Definition: SDL_haptic.h:728
SDL_HapticDirection direction
Definition: SDL_haptic.h:555
DECLSPEC int SDLCALL SDL_MouseIsHaptic(void)
Gets whether or not the current mouse has haptic capabilities.
DECLSPEC int SDLCALL SDL_HapticRunEffect(SDL_Haptic *haptic, int effect, Uint32 iterations)
Runs the haptic effect on its associated haptic device.
Uint16 interval
Definition: SDL_haptic.h:651
The generic template for any haptic effect.
Definition: SDL_haptic.h:800
Sint16 left_coeff[3]
Definition: SDL_haptic.h:621
Sint16 offset
Definition: SDL_haptic.h:568
DECLSPEC int SDLCALL SDL_HapticSetAutocenter(SDL_Haptic *haptic, int autocenter)
Sets the global autocenter of the device.
A structure containing a template for a Condition effect.
Definition: SDL_haptic.h:602
DECLSPEC const char *SDLCALL SDL_HapticName(int device_index)
Get the implementation dependent name of a haptic device.
DECLSPEC unsigned int SDLCALL SDL_HapticQuery(SDL_Haptic *haptic)
Gets the haptic device&#39;s supported features in bitwise manner.
struct SDL_HapticCondition SDL_HapticCondition
A structure containing a template for a Condition effect.
SDL_HapticLeftRight leftright
Definition: SDL_haptic.h:808
DECLSPEC int SDLCALL SDL_JoystickIsHaptic(SDL_Joystick *joystick)
Checks to see if a joystick has haptic features.
Uint16 delay
Definition: SDL_haptic.h:712
struct SDL_HapticConstant SDL_HapticConstant
A structure containing a template for a Constant effect.
Uint16 delay
Definition: SDL_haptic.h:476
Structure that represents a haptic direction.
Definition: SDL_haptic.h:450
DECLSPEC int SDLCALL SDL_HapticRumbleSupported(SDL_Haptic *haptic)
Checks to see if rumble is supported on a haptic device.
struct SDL_HapticCustom SDL_HapticCustom
A structure containing a template for the SDL_HAPTIC_CUSTOM effect.
SDL_HapticRamp ramp
Definition: SDL_haptic.h:807
Uint16 type
Definition: SDL_haptic.h:803
DECLSPEC int SDLCALL SDL_HapticSetGain(SDL_Haptic *haptic, int gain)
Sets the global gain of the device.
A structure containing a template for a Ramp effect.
Definition: SDL_haptic.h:639
Uint16 fade_level
Definition: SDL_haptic.h:575
Uint16 attack_level
Definition: SDL_haptic.h:659
DECLSPEC int SDLCALL SDL_HapticUnpause(SDL_Haptic *haptic)
Unpauses a haptic device.
SDL_HapticPeriodic periodic
Definition: SDL_haptic.h:805
Uint16 attack_length
Definition: SDL_haptic.h:658
DECLSPEC int SDLCALL SDL_HapticRumbleStop(SDL_Haptic *haptic)
Stops the simple rumble on a haptic device.
Uint32 length
Definition: SDL_haptic.h:646
DECLSPEC int SDLCALL SDL_NumHaptics(void)
Count the number of haptic devices attached to the system.
Uint16 type
Definition: SDL_haptic.h:605
Sint16 start
Definition: SDL_haptic.h:654
Uint16 interval
Definition: SDL_haptic.h:615
DECLSPEC int SDLCALL SDL_HapticNumEffects(SDL_Haptic *haptic)
Returns the number of effects a haptic device can store.
struct SDL_HapticDirection SDL_HapticDirection
Structure that represents a haptic direction.
Uint16 type
Definition: SDL_haptic.h:707
Uint16 attack_length
Definition: SDL_haptic.h:486
Uint32 length
Definition: SDL_haptic.h:610
DECLSPEC int SDLCALL SDL_HapticNumAxes(SDL_Haptic *haptic)
Gets the number of haptic axes the device has.
Uint16 attack_level
Definition: SDL_haptic.h:726
Uint16 phase
Definition: SDL_haptic.h:569
DECLSPEC int SDLCALL SDL_HapticPause(SDL_Haptic *haptic)
Pauses a haptic device.
A structure containing a template for a Left/Right effect.
Definition: SDL_haptic.h:676
union SDL_HapticEffect SDL_HapticEffect
The generic template for any haptic effect.
Uint16 interval
Definition: SDL_haptic.h:563
Uint16 left_sat[3]
Definition: SDL_haptic.h:619