gosu 0.15.2 → 1.0.0.pre1

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