gosu 0.15.0 → 1.0.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (242) hide show
  1. checksums.yaml +4 -4
  2. data/.yardopts +1 -0
  3. data/COPYING +1 -1
  4. data/dependencies/SDL/include/SDL.h +138 -0
  5. data/dependencies/SDL/include/SDL_assert.h +293 -0
  6. data/dependencies/SDL/include/SDL_atomic.h +295 -0
  7. data/dependencies/SDL/include/SDL_audio.h +859 -0
  8. data/dependencies/SDL/include/SDL_bits.h +121 -0
  9. data/dependencies/SDL/include/SDL_blendmode.h +123 -0
  10. data/dependencies/SDL/include/SDL_clipboard.h +71 -0
  11. data/dependencies/SDL/include/SDL_config.h +55 -0
  12. data/dependencies/SDL/include/SDL_config_android.h +182 -0
  13. data/dependencies/SDL/include/SDL_config_iphoneos.h +207 -0
  14. data/dependencies/SDL/include/SDL_config_macosx.h +266 -0
  15. data/dependencies/SDL/include/SDL_config_minimal.h +85 -0
  16. data/dependencies/SDL/include/SDL_config_os2.h +188 -0
  17. data/dependencies/SDL/include/SDL_config_pandora.h +135 -0
  18. data/dependencies/SDL/include/SDL_config_psp.h +165 -0
  19. data/dependencies/SDL/include/SDL_config_windows.h +288 -0
  20. data/dependencies/SDL/include/SDL_config_winrt.h +243 -0
  21. data/dependencies/SDL/include/SDL_config_wiz.h +149 -0
  22. data/dependencies/SDL/include/SDL_copying.h +20 -0
  23. data/dependencies/SDL/include/SDL_cpuinfo.h +299 -0
  24. data/dependencies/SDL/include/SDL_egl.h +1676 -0
  25. data/dependencies/SDL/include/SDL_endian.h +263 -0
  26. data/dependencies/SDL/include/SDL_error.h +112 -0
  27. data/dependencies/SDL/include/SDL_events.h +827 -0
  28. data/dependencies/SDL/include/SDL_filesystem.h +136 -0
  29. data/dependencies/SDL/include/SDL_gamecontroller.h +541 -0
  30. data/dependencies/SDL/include/SDL_gesture.h +87 -0
  31. data/dependencies/SDL/include/SDL_haptic.h +1247 -0
  32. data/dependencies/SDL/include/SDL_hints.h +1578 -0
  33. data/dependencies/SDL/include/SDL_joystick.h +499 -0
  34. data/dependencies/SDL/include/SDL_keyboard.h +217 -0
  35. data/dependencies/SDL/include/SDL_keycode.h +351 -0
  36. data/dependencies/SDL/include/SDL_loadso.h +81 -0
  37. data/dependencies/SDL/include/SDL_locale.h +101 -0
  38. data/dependencies/SDL/include/SDL_log.h +211 -0
  39. data/dependencies/SDL/include/SDL_main.h +180 -0
  40. data/dependencies/SDL/include/SDL_messagebox.h +146 -0
  41. data/dependencies/SDL/include/SDL_metal.h +117 -0
  42. data/dependencies/SDL/include/SDL_misc.h +75 -0
  43. data/dependencies/SDL/include/SDL_mouse.h +302 -0
  44. data/dependencies/SDL/include/SDL_mutex.h +251 -0
  45. data/dependencies/SDL/include/SDL_name.h +33 -0
  46. data/dependencies/SDL/include/SDL_opengl.h +2183 -0
  47. data/dependencies/SDL/include/SDL_opengl_glext.h +11180 -0
  48. data/dependencies/SDL/include/SDL_opengles.h +39 -0
  49. data/dependencies/SDL/include/SDL_opengles2.h +52 -0
  50. data/dependencies/SDL/include/SDL_opengles2_gl2.h +621 -0
  51. data/dependencies/SDL/include/SDL_opengles2_gl2ext.h +2050 -0
  52. data/dependencies/SDL/include/SDL_opengles2_gl2platform.h +30 -0
  53. data/dependencies/SDL/include/SDL_opengles2_khrplatform.h +282 -0
  54. data/dependencies/SDL/include/SDL_pixels.h +479 -0
  55. data/dependencies/SDL/include/SDL_platform.h +198 -0
  56. data/dependencies/SDL/include/SDL_power.h +75 -0
  57. data/dependencies/SDL/include/SDL_quit.h +58 -0
  58. data/dependencies/SDL/include/SDL_rect.h +174 -0
  59. data/dependencies/SDL/include/SDL_render.h +1158 -0
  60. data/dependencies/SDL/include/SDL_revision.h +2 -0
  61. data/dependencies/SDL/include/SDL_rwops.h +283 -0
  62. data/dependencies/SDL/include/SDL_scancode.h +413 -0
  63. data/dependencies/SDL/include/SDL_sensor.h +267 -0
  64. data/dependencies/SDL/include/SDL_shape.h +144 -0
  65. data/dependencies/SDL/include/SDL_stdinc.h +647 -0
  66. data/dependencies/SDL/include/SDL_surface.h +563 -0
  67. data/dependencies/SDL/include/SDL_system.h +325 -0
  68. data/dependencies/SDL/include/SDL_syswm.h +354 -0
  69. data/dependencies/SDL/include/SDL_test.h +69 -0
  70. data/dependencies/SDL/include/SDL_test_assert.h +105 -0
  71. data/dependencies/SDL/include/SDL_test_common.h +218 -0
  72. data/dependencies/SDL/include/SDL_test_compare.h +69 -0
  73. data/dependencies/SDL/include/SDL_test_crc32.h +124 -0
  74. data/dependencies/SDL/include/SDL_test_font.h +81 -0
  75. data/dependencies/SDL/include/SDL_test_fuzzer.h +384 -0
  76. data/dependencies/SDL/include/SDL_test_harness.h +134 -0
  77. data/dependencies/SDL/include/SDL_test_images.h +78 -0
  78. data/dependencies/SDL/include/SDL_test_log.h +67 -0
  79. data/dependencies/SDL/include/SDL_test_md5.h +129 -0
  80. data/dependencies/SDL/include/SDL_test_memory.h +63 -0
  81. data/dependencies/SDL/include/SDL_test_random.h +115 -0
  82. data/dependencies/SDL/include/SDL_thread.h +366 -0
  83. data/dependencies/SDL/include/SDL_timer.h +115 -0
  84. data/dependencies/SDL/include/SDL_touch.h +102 -0
  85. data/dependencies/SDL/include/SDL_types.h +29 -0
  86. data/dependencies/SDL/include/SDL_version.h +162 -0
  87. data/dependencies/SDL/include/SDL_video.h +1282 -0
  88. data/dependencies/SDL/include/SDL_vulkan.h +276 -0
  89. data/dependencies/SDL/include/begin_code.h +166 -0
  90. data/dependencies/SDL/include/close_code.h +40 -0
  91. data/dependencies/SDL/lib/x64/libSDL2.dll.a +0 -0
  92. data/dependencies/SDL/lib/x86/libSDL2.dll.a +0 -0
  93. data/dependencies/SDL_sound/SDL_sound.c +795 -0
  94. data/dependencies/SDL_sound/SDL_sound.h +725 -0
  95. data/dependencies/SDL_sound/SDL_sound_aiff.c +537 -0
  96. data/dependencies/SDL_sound/SDL_sound_au.c +352 -0
  97. data/dependencies/SDL_sound/SDL_sound_coreaudio.c +747 -0
  98. data/dependencies/SDL_sound/SDL_sound_flac.c +182 -0
  99. data/dependencies/SDL_sound/SDL_sound_internal.h +304 -0
  100. data/dependencies/SDL_sound/SDL_sound_modplug.c +228 -0
  101. data/dependencies/SDL_sound/SDL_sound_mp3.c +184 -0
  102. data/dependencies/SDL_sound/SDL_sound_raw.c +164 -0
  103. data/dependencies/SDL_sound/SDL_sound_shn.c +1309 -0
  104. data/dependencies/SDL_sound/SDL_sound_voc.c +550 -0
  105. data/dependencies/SDL_sound/SDL_sound_vorbis.c +223 -0
  106. data/dependencies/SDL_sound/SDL_sound_wav.c +783 -0
  107. data/dependencies/SDL_sound/dr_flac.h +5906 -0
  108. data/dependencies/SDL_sound/dr_mp3.h +2832 -0
  109. data/dependencies/SDL_sound/libmodplug/fastmix.c +1748 -0
  110. data/dependencies/SDL_sound/libmodplug/libmodplug.h +1001 -0
  111. data/dependencies/SDL_sound/libmodplug/load_669.c +188 -0
  112. data/dependencies/SDL_sound/libmodplug/load_abc.c +4725 -0
  113. data/dependencies/SDL_sound/libmodplug/load_amf.c +403 -0
  114. data/dependencies/SDL_sound/libmodplug/load_ams.c +587 -0
  115. data/dependencies/SDL_sound/libmodplug/load_dbm.c +357 -0
  116. data/dependencies/SDL_sound/libmodplug/load_dmf.c +531 -0
  117. data/dependencies/SDL_sound/libmodplug/load_dsm.c +232 -0
  118. data/dependencies/SDL_sound/libmodplug/load_far.c +253 -0
  119. data/dependencies/SDL_sound/libmodplug/load_it.c +796 -0
  120. data/dependencies/SDL_sound/libmodplug/load_mdl.c +488 -0
  121. data/dependencies/SDL_sound/libmodplug/load_med.c +757 -0
  122. data/dependencies/SDL_sound/libmodplug/load_mid.c +1405 -0
  123. data/dependencies/SDL_sound/libmodplug/load_mod.c +269 -0
  124. data/dependencies/SDL_sound/libmodplug/load_mt2.c +546 -0
  125. data/dependencies/SDL_sound/libmodplug/load_mtm.c +142 -0
  126. data/dependencies/SDL_sound/libmodplug/load_okt.c +192 -0
  127. data/dependencies/SDL_sound/libmodplug/load_pat.c +1143 -0
  128. data/dependencies/SDL_sound/libmodplug/load_pat.h +25 -0
  129. data/dependencies/SDL_sound/libmodplug/load_psm.c +350 -0
  130. data/dependencies/SDL_sound/libmodplug/load_ptm.c +204 -0
  131. data/dependencies/SDL_sound/libmodplug/load_s3m.c +325 -0
  132. data/dependencies/SDL_sound/libmodplug/load_stm.c +180 -0
  133. data/dependencies/SDL_sound/libmodplug/load_ult.c +206 -0
  134. data/dependencies/SDL_sound/libmodplug/load_umx.c +51 -0
  135. data/dependencies/SDL_sound/libmodplug/load_xm.c +554 -0
  136. data/dependencies/SDL_sound/libmodplug/mmcmp.c +382 -0
  137. data/dependencies/SDL_sound/libmodplug/modplug.c +170 -0
  138. data/dependencies/SDL_sound/libmodplug/modplug.h +90 -0
  139. data/dependencies/SDL_sound/libmodplug/snd_dsp.c +301 -0
  140. data/dependencies/SDL_sound/libmodplug/snd_flt.c +63 -0
  141. data/dependencies/SDL_sound/libmodplug/snd_fx.c +2350 -0
  142. data/dependencies/SDL_sound/libmodplug/sndfile.c +1169 -0
  143. data/dependencies/SDL_sound/libmodplug/sndmix.c +1034 -0
  144. data/dependencies/SDL_sound/libmodplug/tables.h +371 -0
  145. data/{src/stb_vorbis.c → dependencies/SDL_sound/stb_vorbis.h} +128 -23
  146. data/dependencies/al_soft/AL/al.h +655 -0
  147. data/dependencies/al_soft/AL/alc.h +270 -0
  148. data/dependencies/al_soft/AL/alext.h +585 -0
  149. data/dependencies/al_soft/AL/efx-creative.h +3 -0
  150. data/dependencies/al_soft/AL/efx-presets.h +402 -0
  151. data/dependencies/al_soft/AL/efx.h +762 -0
  152. data/dependencies/al_soft/x64/libOpenAL32.dll.a +0 -0
  153. data/dependencies/al_soft/x86/libOpenAL32.dll.a +0 -0
  154. data/{src → dependencies/stb}/stb_image.h +476 -176
  155. data/{src → dependencies/stb}/stb_image_write.h +253 -131
  156. data/{src → dependencies/stb}/stb_truetype.h +262 -104
  157. data/{src → dependencies/utf8proc}/utf8proc.c +47 -29
  158. data/{src → dependencies/utf8proc}/utf8proc.h +46 -24
  159. data/{src → dependencies/utf8proc}/utf8proc_data.h +10043 -9609
  160. data/ext/gosu/extconf.rb +53 -39
  161. data/{Gosu → include/Gosu}/Audio.hpp +6 -8
  162. data/include/Gosu/Bitmap.hpp +100 -0
  163. data/{Gosu → include/Gosu}/Buttons.hpp +104 -44
  164. data/include/Gosu/Channel.h +25 -0
  165. data/include/Gosu/Color.h +38 -0
  166. data/{Gosu → include/Gosu}/Color.hpp +0 -0
  167. data/{Gosu → include/Gosu}/Directories.hpp +0 -0
  168. data/include/Gosu/Font.h +36 -0
  169. data/{Gosu → include/Gosu}/Font.hpp +1 -1
  170. data/{Gosu → include/Gosu}/Fwd.hpp +0 -5
  171. data/include/Gosu/Gosu.h +82 -0
  172. data/{Gosu → include/Gosu}/Gosu.hpp +0 -0
  173. data/{Gosu → include/Gosu}/Graphics.hpp +0 -0
  174. data/{Gosu → include/Gosu}/GraphicsBase.hpp +0 -0
  175. data/{Gosu → include/Gosu}/IO.hpp +0 -0
  176. data/include/Gosu/Image.h +54 -0
  177. data/{Gosu → include/Gosu}/Image.hpp +7 -6
  178. data/{Gosu → include/Gosu}/ImageData.hpp +0 -0
  179. data/{Gosu → include/Gosu}/Input.hpp +39 -51
  180. data/{Gosu → include/Gosu}/Inspection.hpp +0 -0
  181. data/{Gosu → include/Gosu}/Math.hpp +0 -0
  182. data/{Gosu → include/Gosu}/Platform.hpp +0 -0
  183. data/include/Gosu/Sample.h +19 -0
  184. data/include/Gosu/Song.h +24 -0
  185. data/{Gosu → include/Gosu}/Text.hpp +0 -0
  186. data/include/Gosu/TextInput.h +30 -0
  187. data/{Gosu → include/Gosu}/TextInput.hpp +0 -0
  188. data/{Gosu → include/Gosu}/Timing.hpp +0 -0
  189. data/{Gosu → include/Gosu}/Utility.hpp +15 -4
  190. data/{Gosu → include/Gosu}/Version.hpp +2 -2
  191. data/include/Gosu/Window.h +63 -0
  192. data/{Gosu → include/Gosu}/Window.hpp +23 -25
  193. data/lib/OpenAL32.dll +0 -0
  194. data/lib/SDL2.dll +0 -0
  195. data/lib/gosu.rb +0 -3
  196. data/lib/gosu/patches.rb +0 -23
  197. data/lib/gosu/preview.rb +1 -3
  198. data/lib/gosu/swig_patches.rb +3 -2
  199. data/lib64/OpenAL32.dll +0 -0
  200. data/lib64/SDL2.dll +0 -0
  201. data/rdoc/gosu.rb +98 -22
  202. data/src/Audio.cpp +50 -224
  203. data/src/AudioFile.hpp +20 -37
  204. data/src/AudioFileAudioToolbox.cpp +237 -0
  205. data/src/AudioFileSDLSound.cpp +147 -0
  206. data/src/AudioImpl.cpp +3 -12
  207. data/src/AudioImpl.hpp +3 -1
  208. data/src/Bitmap.cpp +85 -83
  209. data/src/BitmapIO.cpp +52 -58
  210. data/src/ChannelWrapper.cpp +50 -0
  211. data/src/ColorWrapper.cpp +126 -0
  212. data/src/Constants.cpp +338 -0
  213. data/src/Font.cpp +4 -1
  214. data/src/FontWrapper.cpp +74 -0
  215. data/src/GosuWrapper.cpp +251 -0
  216. data/src/Graphics.cpp +7 -4
  217. data/src/Image.cpp +13 -16
  218. data/src/ImageWrapper.cpp +168 -0
  219. data/src/Input.cpp +412 -164
  220. data/src/LargeImageData.cpp +2 -1
  221. data/src/MarkupParser.cpp +2 -1
  222. data/src/RubyGosu.cxx +912 -172
  223. data/src/RubyGosu.h +4 -2
  224. data/src/SampleWrapper.cpp +30 -0
  225. data/src/SongWrapper.cpp +52 -0
  226. data/src/TexChunk.cpp +1 -1
  227. data/src/Text.cpp +1 -0
  228. data/src/TextBuilder.cpp +3 -1
  229. data/src/TextInputWrapper.cpp +101 -0
  230. data/src/Texture.cpp +1 -1
  231. data/src/TrueTypeFont.cpp +2 -1
  232. data/src/Utility.cpp +11 -7
  233. data/src/Window.cpp +30 -39
  234. data/src/WindowWrapper.cpp +317 -0
  235. metadata +212 -43
  236. data/Gosu/AutoLink.hpp +0 -14
  237. data/Gosu/Bitmap.hpp +0 -113
  238. data/lib/gosu/zen.rb +0 -89
  239. data/src/AudioToolboxFile.hpp +0 -210
  240. data/src/OggFile.hpp +0 -92
  241. data/src/SndFile.hpp +0 -174
  242. data/src/WinMain.cpp +0 -64
@@ -0,0 +1,725 @@
1
+ /** \file SDL_sound.h */
2
+
3
+ /*
4
+ * SDL_sound; An abstract sound format decoding API.
5
+ *
6
+ * Please see the file LICENSE.txt in the source's root directory.
7
+ */
8
+
9
+ /**
10
+ * \mainpage SDL_sound
11
+ *
12
+ * The latest version of SDL_sound can be found at:
13
+ * https://icculus.org/SDL_sound/
14
+ *
15
+ * The basic gist of SDL_sound is that you use an SDL_RWops to get sound data
16
+ * into this library, and SDL_sound will take that data, in one of several
17
+ * popular formats, and decode it into raw waveform data in the format of
18
+ * your choice. This gives you a nice abstraction for getting sound into your
19
+ * game or application; just feed it to SDL_sound, and it will handle
20
+ * decoding and converting, so you can just pass it to your SDL audio
21
+ * callback (or whatever). Since it gets data from an SDL_RWops, you can get
22
+ * the initial sound data from any number of sources: file, memory buffer,
23
+ * network connection, etc.
24
+ *
25
+ * As the name implies, this library depends on SDL: Simple Directmedia Layer,
26
+ * which is a powerful, free, and cross-platform multimedia library. It can
27
+ * be found at https://www.libsdl.org/
28
+ *
29
+ * Support is in place or planned for the following sound formats:
30
+ * - .WAV (Microsoft WAVfile RIFF data, internal.)
31
+ * - .VOC (Creative Labs' Voice format, internal.)
32
+ * - .MP3 (MPEG-1 Layer 3 support, via libmpg123.)
33
+ * - .MID (MIDI music converted to Waveform data, internal.)
34
+ * - .MOD (MOD files, via internal copy of libModPlug.)
35
+ * - .OGG (Ogg files, via internal copy of stb_vorbis.)
36
+ * - .SHN (Shorten files, internal.)
37
+ * - .RAW (Raw sound data in any format, internal.)
38
+ * - .AU (Sun's Audio format, internal.)
39
+ * - .AIFF (Audio Interchange format, internal.)
40
+ * - .FLAC (Lossless audio compression, via libFLAC.)
41
+ *
42
+ * (...and more to come...)
43
+ *
44
+ * Please see the file LICENSE.txt in the source's root directory.
45
+ *
46
+ * \author Ryan C. Gordon (icculus@icculus.org)
47
+ * \author many others, please see CREDITS in the source's root directory.
48
+ */
49
+
50
+ #ifndef _INCLUDE_SDL_SOUND_H_
51
+ #define _INCLUDE_SDL_SOUND_H_
52
+
53
+ #include "SDL.h"
54
+
55
+ #if SDL_MAJOR_VERSION < 2
56
+ #error SDL2_sound requires SDL 2.0.0 or later.
57
+ #endif
58
+
59
+ #ifdef __cplusplus
60
+ extern "C" {
61
+ #endif
62
+
63
+ #ifndef DOXYGEN_SHOULD_IGNORE_THIS
64
+
65
+ #ifdef SDL_SOUND_DLL_EXPORTS
66
+ # define SNDDECLSPEC __declspec(dllexport)
67
+ #elif (__GNUC__ >= 3)
68
+ # define SNDDECLSPEC __attribute__((visibility("default")))
69
+ #else
70
+ # define SNDDECLSPEC
71
+ #endif
72
+
73
+ #define SOUND_VER_MAJOR 1
74
+ #define SOUND_VER_MINOR 9
75
+ #define SOUND_VER_PATCH 0
76
+ #endif
77
+
78
+
79
+ /**
80
+ * \enum Sound_SampleFlags
81
+ * \brief Flags that are used in a Sound_Sample to show various states.
82
+ *
83
+ * To use:
84
+ * \code
85
+ * if (sample->flags & SOUND_SAMPLEFLAG_ERROR) { dosomething(); }
86
+ * \endcode
87
+ *
88
+ * \sa Sound_SampleNew
89
+ * \sa Sound_SampleNewFromFile
90
+ * \sa Sound_SampleDecode
91
+ * \sa Sound_SampleDecodeAll
92
+ * \sa Sound_SampleSeek
93
+ */
94
+ typedef enum
95
+ {
96
+ SOUND_SAMPLEFLAG_NONE = 0, /**< No special attributes. */
97
+
98
+ /* these are set at sample creation time... */
99
+ SOUND_SAMPLEFLAG_CANSEEK = 1, /**< Sample can seek to arbitrary points. */
100
+
101
+ /* these are set during decoding... */
102
+ SOUND_SAMPLEFLAG_EOF = 1 << 29, /**< End of input stream. */
103
+ SOUND_SAMPLEFLAG_ERROR = 1 << 30, /**< Unrecoverable error. */
104
+ SOUND_SAMPLEFLAG_EAGAIN = 1 << 31 /**< Function would block, or temp error. */
105
+ } Sound_SampleFlags;
106
+
107
+
108
+ /**
109
+ * \struct Sound_AudioInfo
110
+ * \brief Information about an existing sample's format.
111
+ *
112
+ * These are the basics of a decoded sample's data structure: data format
113
+ * (see AUDIO_U8 and friends in SDL_audio.h), number of channels, and sample
114
+ * rate. If you need more explanation than that, you should stop developing
115
+ * sound code right now.
116
+ *
117
+ * \sa Sound_SampleNew
118
+ * \sa Sound_SampleNewFromFile
119
+ */
120
+ typedef struct
121
+ {
122
+ Uint16 format; /**< Equivalent of SDL_AudioSpec.format. */
123
+ Uint8 channels; /**< Number of sound channels. 1 == mono, 2 == stereo. */
124
+ Uint32 rate; /**< Sample rate; frequency of sample points per second. */
125
+ } Sound_AudioInfo;
126
+
127
+
128
+ /**
129
+ * \struct Sound_DecoderInfo
130
+ * \brief Information about available soudn decoders.
131
+ *
132
+ * Each decoder sets up one of these structs, which can be retrieved via
133
+ * the Sound_AvailableDecoders() function. EVERY FIELD IN THIS IS READ-ONLY.
134
+ *
135
+ * The extensions field is a NULL-terminated list of ASCIZ strings. You
136
+ * should read it like this:
137
+ *
138
+ * \code
139
+ * const char **ext;
140
+ * for (ext = info->extensions; *ext != NULL; ext++) {
141
+ * printf(" File extension \"%s\"\n", *ext);
142
+ * }
143
+ * \endcode
144
+ *
145
+ * \sa Sound_AvailableDecoders
146
+ */
147
+ typedef struct
148
+ {
149
+ const char **extensions; /**< File extensions, list ends with NULL. */
150
+ const char *description; /**< Human readable description of decoder. */
151
+ const char *author; /**< "Name Of Author \<email@emailhost.dom\>" */
152
+ const char *url; /**< URL specific to this decoder. */
153
+ } Sound_DecoderInfo;
154
+
155
+
156
+
157
+ /**
158
+ * \struct Sound_Sample
159
+ * \brief Represents sound data in the process of being decoded.
160
+ *
161
+ * The Sound_Sample structure is the heart of SDL_sound. This holds
162
+ * information about a source of sound data as it is being decoded.
163
+ * EVERY FIELD IN THIS IS READ-ONLY. Please use the API functions to
164
+ * change them.
165
+ */
166
+ typedef struct
167
+ {
168
+ void *opaque; /**< Internal use only. Don't touch. */
169
+ const Sound_DecoderInfo *decoder; /**< Decoder used for this sample. */
170
+ Sound_AudioInfo desired; /**< Desired audio format for conversion. */
171
+ Sound_AudioInfo actual; /**< Actual audio format of sample. */
172
+ void *buffer; /**< Decoded sound data lands in here. */
173
+ Uint32 buffer_size; /**< Current size of (buffer), in bytes (Uint8). */
174
+ Sound_SampleFlags flags; /**< Flags relating to this sample. */
175
+ } Sound_Sample;
176
+
177
+
178
+ /**
179
+ * \struct Sound_Version
180
+ * \brief Information the version of SDL_sound in use.
181
+ *
182
+ * Represents the library's version as three levels: major revision
183
+ * (increments with massive changes, additions, and enhancements),
184
+ * minor revision (increments with backwards-compatible changes to the
185
+ * major revision), and patchlevel (increments with fixes to the minor
186
+ * revision).
187
+ *
188
+ * \sa SOUND_VERSION
189
+ * \sa Sound_GetLinkedVersion
190
+ */
191
+ typedef struct
192
+ {
193
+ int major; /**< major revision */
194
+ int minor; /**< minor revision */
195
+ int patch; /**< patchlevel */
196
+ } Sound_Version;
197
+
198
+
199
+ /* functions and macros... */
200
+
201
+ /**
202
+ * \def SOUND_VERSION(x)
203
+ * \brief Macro to determine SDL_sound version program was compiled against.
204
+ *
205
+ * This macro fills in a Sound_Version structure with the version of the
206
+ * library you compiled against. This is determined by what header the
207
+ * compiler uses. Note that if you dynamically linked the library, you might
208
+ * have a slightly newer or older version at runtime. That version can be
209
+ * determined with Sound_GetLinkedVersion(), which, unlike SOUND_VERSION,
210
+ * is not a macro.
211
+ *
212
+ * \param x A pointer to a Sound_Version struct to initialize.
213
+ *
214
+ * \sa Sound_Version
215
+ * \sa Sound_GetLinkedVersion
216
+ */
217
+ #define SOUND_VERSION(x) \
218
+ { \
219
+ (x)->major = SOUND_VER_MAJOR; \
220
+ (x)->minor = SOUND_VER_MINOR; \
221
+ (x)->patch = SOUND_VER_PATCH; \
222
+ }
223
+
224
+
225
+ /**
226
+ * \fn void Sound_GetLinkedVersion(Sound_Version *ver)
227
+ * \brief Get the version of SDL_sound that is linked against your program.
228
+ *
229
+ * If you are using a shared library (DLL) version of SDL_sound, then it is
230
+ * possible that it will be different than the version you compiled against.
231
+ *
232
+ * This is a real function; the macro SOUND_VERSION tells you what version
233
+ * of SDL_sound you compiled against:
234
+ *
235
+ * \code
236
+ * Sound_Version compiled;
237
+ * Sound_Version linked;
238
+ *
239
+ * SOUND_VERSION(&compiled);
240
+ * Sound_GetLinkedVersion(&linked);
241
+ * printf("We compiled against SDL_sound version %d.%d.%d ...\n",
242
+ * compiled.major, compiled.minor, compiled.patch);
243
+ * printf("But we linked against SDL_sound version %d.%d.%d.\n",
244
+ * linked.major, linked.minor, linked.patch);
245
+ * \endcode
246
+ *
247
+ * This function may be called safely at any time, even before Sound_Init().
248
+ *
249
+ * \param ver Sound_Version structure to fill with shared library's version.
250
+ *
251
+ * \sa Sound_Version
252
+ * \sa SOUND_VERSION
253
+ */
254
+ SNDDECLSPEC void SDLCALL Sound_GetLinkedVersion(Sound_Version *ver);
255
+
256
+
257
+ /**
258
+ * \fn Sound_Init(void)
259
+ * \brief Initialize SDL_sound.
260
+ *
261
+ * This must be called before any other SDL_sound function (except perhaps
262
+ * Sound_GetLinkedVersion()). You should call SDL_Init() before calling this.
263
+ * Sound_Init() will attempt to call SDL_Init(SDL_INIT_AUDIO), just in case.
264
+ * This is a safe behaviour, but it may not configure SDL to your liking by
265
+ * itself.
266
+ *
267
+ * \return nonzero on success, zero on error. Specifics of the
268
+ * error can be gleaned from Sound_GetError().
269
+ *
270
+ * \sa Sound_Quit
271
+ */
272
+ SNDDECLSPEC int SDLCALL Sound_Init(void);
273
+
274
+
275
+ /**
276
+ * \fn Sound_Quit(void)
277
+ * \brief Shutdown SDL_sound.
278
+ *
279
+ * This closes any SDL_RWops that were being used as sound sources, and frees
280
+ * any resources in use by SDL_sound.
281
+ *
282
+ * All Sound_Sample pointers you had prior to this call are INVALIDATED.
283
+ *
284
+ * Once successfully deinitialized, Sound_Init() can be called again to
285
+ * restart the subsystem. All default API states are restored at this
286
+ * point.
287
+ *
288
+ * You should call this BEFORE SDL_Quit(). This will NOT call SDL_Quit()
289
+ * for you!
290
+ *
291
+ * \return nonzero on success, zero on error. Specifics of the error
292
+ * can be gleaned from Sound_GetError(). If failure, state of
293
+ * SDL_sound is undefined, and probably badly screwed up.
294
+ *
295
+ * \sa Sound_Init
296
+ */
297
+ SNDDECLSPEC int SDLCALL Sound_Quit(void);
298
+
299
+
300
+ /**
301
+ * \fn const Sound_DecoderInfo **Sound_AvailableDecoders(void)
302
+ * \brief Get a list of sound formats supported by this version of SDL_sound.
303
+ *
304
+ * This is for informational purposes only. Note that the extension listed is
305
+ * merely convention: if we list "MP3", you can open an MPEG-1 Layer 3 audio
306
+ * file with an extension of "XYZ", if you like. The file extensions are
307
+ * informational, and only required as a hint to choosing the correct
308
+ * decoder, since the sound data may not be coming from a file at all, thanks
309
+ * to the abstraction that an SDL_RWops provides.
310
+ *
311
+ * The returned value is an array of pointers to Sound_DecoderInfo structures,
312
+ * with a NULL entry to signify the end of the list:
313
+ *
314
+ * \code
315
+ * Sound_DecoderInfo **i;
316
+ *
317
+ * for (i = Sound_AvailableDecoders(); *i != NULL; i++)
318
+ * {
319
+ * printf("Supported sound format: [%s], which is [%s].\n",
320
+ * i->extension, i->description);
321
+ * // ...and other fields...
322
+ * }
323
+ * \endcode
324
+ *
325
+ * The return values are pointers to static internal memory, and should
326
+ * be considered READ ONLY, and never freed.
327
+ *
328
+ * \return READ ONLY Null-terminated array of READ ONLY structures.
329
+ *
330
+ * \sa Sound_DecoderInfo
331
+ */
332
+ SNDDECLSPEC const Sound_DecoderInfo ** SDLCALL Sound_AvailableDecoders(void);
333
+
334
+
335
+ /**
336
+ * \fn const char *Sound_GetError(void)
337
+ * \brief Get the last SDL_sound error message as a null-terminated string.
338
+ *
339
+ * This will be NULL if there's been no error since the last call to this
340
+ * function. The pointer returned by this call points to an internal buffer,
341
+ * and should not be deallocated. Each thread has a unique error state
342
+ * associated with it, but each time a new error message is set, it will
343
+ * overwrite the previous one associated with that thread. It is safe to call
344
+ * this function at anytime, even before Sound_Init().
345
+ *
346
+ * \return READ ONLY string of last error message.
347
+ *
348
+ * \sa Sound_ClearError
349
+ */
350
+ SNDDECLSPEC const char * SDLCALL Sound_GetError(void);
351
+
352
+
353
+ /**
354
+ * \fn void Sound_ClearError(void)
355
+ * \brief Clear the current error message.
356
+ *
357
+ * The next call to Sound_GetError() after Sound_ClearError() will return NULL.
358
+ *
359
+ * \sa Sound_GetError
360
+ */
361
+ SNDDECLSPEC void SDLCALL Sound_ClearError(void);
362
+
363
+
364
+ /**
365
+ * \fn Sound_Sample *Sound_NewSample(SDL_RWops *rw, const char *ext, Sound_AudioInfo *desired, Uint32 bufferSize)
366
+ * \brief Start decoding a new sound sample.
367
+ *
368
+ * The data is read via an SDL_RWops structure (see SDL_rwops.h in the SDL
369
+ * include directory), so it may be coming from memory, disk, network stream,
370
+ * etc. The (ext) parameter is merely a hint to determining the correct
371
+ * decoder; if you specify, for example, "mp3" for an extension, and one of
372
+ * the decoders lists that as a handled extension, then that decoder is given
373
+ * first shot at trying to claim the data for decoding. If none of the
374
+ * extensions match (or the extension is NULL), then every decoder examines
375
+ * the data to determine if it can handle it, until one accepts it. In such a
376
+ * case your SDL_RWops will need to be capable of rewinding to the start of
377
+ * the stream.
378
+ *
379
+ * If no decoders can handle the data, a NULL value is returned, and a human
380
+ * readable error message can be fetched from Sound_GetError().
381
+ *
382
+ * Optionally, a desired audio format can be specified. If the incoming data
383
+ * is in a different format, SDL_sound will convert it to the desired format
384
+ * on the fly. Note that this can be an expensive operation, so it may be
385
+ * wise to convert data before you need to play it back, if possible, or
386
+ * make sure your data is initially in the format that you need it in.
387
+ * If you don't want to convert the data, you can specify NULL for a desired
388
+ * format. The incoming format of the data, preconversion, can be found
389
+ * in the Sound_Sample structure.
390
+ *
391
+ * Note that the raw sound data "decoder" needs you to specify both the
392
+ * extension "RAW" and a "desired" format, or it will refuse to handle
393
+ * the data. This is to prevent it from catching all formats unsupported
394
+ * by the other decoders.
395
+ *
396
+ * Finally, specify an initial buffer size; this is the number of bytes that
397
+ * will be allocated to store each read from the sound buffer. The more you
398
+ * can safely allocate, the more decoding can be done in one block, but the
399
+ * more resources you have to use up, and the longer each decoding call will
400
+ * take. Note that different data formats require more or less space to
401
+ * store. This buffer can be resized via Sound_SetBufferSize() ...
402
+ *
403
+ * The buffer size specified must be a multiple of the size of a single
404
+ * sample point. So, if you want 16-bit, stereo samples, then your sample
405
+ * point size is (2 channels * 16 bits), or 32 bits per sample, which is four
406
+ * bytes. In such a case, you could specify 128 or 132 bytes for a buffer,
407
+ * but not 129, 130, or 131 (although in reality, you'll want to specify a
408
+ * MUCH larger buffer).
409
+ *
410
+ * When you are done with this Sound_Sample pointer, you can dispose of it
411
+ * via Sound_FreeSample().
412
+ *
413
+ * You do not have to keep a reference to (rw) around. If this function
414
+ * suceeds, it stores (rw) internally (and disposes of it during the call
415
+ * to Sound_FreeSample()). If this function fails, it will dispose of the
416
+ * SDL_RWops for you.
417
+ *
418
+ * \param rw SDL_RWops with sound data.
419
+ * \param ext File extension normally associated with a data format.
420
+ * Can usually be NULL.
421
+ * \param desired Format to convert sound data into. Can usually be NULL,
422
+ * if you don't need conversion.
423
+ * \param bufferSize Size, in bytes, to allocate for the decoding buffer.
424
+ * \return Sound_Sample pointer, which is used as a handle to several other
425
+ * SDL_sound APIs. NULL on error. If error, use
426
+ * Sound_GetError() to see what went wrong.
427
+ *
428
+ * \sa Sound_NewSampleFromFile
429
+ * \sa Sound_SetBufferSize
430
+ * \sa Sound_Decode
431
+ * \sa Sound_DecodeAll
432
+ * \sa Sound_Seek
433
+ * \sa Sound_Rewind
434
+ * \sa Sound_FreeSample
435
+ */
436
+ SNDDECLSPEC Sound_Sample * SDLCALL Sound_NewSample(SDL_RWops *rw,
437
+ const char *ext,
438
+ Sound_AudioInfo *desired,
439
+ Uint32 bufferSize);
440
+
441
+ /**
442
+ * \fn Sound_Sample *Sound_NewSampleFromMem(const Uint8 *data, Uint32 size, const char *ext, Sound_AudioInfo *desired, Uint32 bufferSize)
443
+ * \brief Start decoding a new sound sample from a file on disk.
444
+ *
445
+ * This is identical to Sound_NewSample(), but it creates an SDL_RWops for you
446
+ * from the (size) bytes of memory referenced by (data).
447
+ *
448
+ * This can pool RWops structures, so it may fragment the heap less over time
449
+ * than using SDL_RWFromMem().
450
+ *
451
+ * \param data Buffer of data holding contents of an audio file to decode.
452
+ * \param size Size, in bytes, of buffer pointed to by (data).
453
+ * \param ext File extension normally associated with a data format.
454
+ * Can usually be NULL.
455
+ * \param desired Format to convert sound data into. Can usually be NULL,
456
+ * if you don't need conversion.
457
+ * \param bufferSize size, in bytes, of initial read buffer.
458
+ * \return Sound_Sample pointer, which is used as a handle to several other
459
+ * SDL_sound APIs. NULL on error. If error, use
460
+ * Sound_GetError() to see what went wrong.
461
+ *
462
+ * \sa Sound_NewSample
463
+ * \sa Sound_SetBufferSize
464
+ * \sa Sound_Decode
465
+ * \sa Sound_DecodeAll
466
+ * \sa Sound_Seek
467
+ * \sa Sound_Rewind
468
+ * \sa Sound_FreeSample
469
+ */
470
+ SNDDECLSPEC Sound_Sample * SDLCALL Sound_NewSampleFromMem(const Uint8 *data,
471
+ Uint32 size,
472
+ const char *ext,
473
+ Sound_AudioInfo *desired,
474
+ Uint32 bufferSize);
475
+
476
+
477
+ /**
478
+ * \fn Sound_Sample *Sound_NewSampleFromFile(const char *filename, Sound_AudioInfo *desired, Uint32 bufferSize)
479
+ * \brief Start decoding a new sound sample from a file on disk.
480
+ *
481
+ * This is identical to Sound_NewSample(), but it creates an SDL_RWops for you
482
+ * from the file located in (filename). Note that (filename) is specified in
483
+ * platform-dependent notation. ("C:\\music\\mysong.mp3" on windows, and
484
+ * "/home/icculus/music/mysong.mp3" or whatever on Unix, etc.)
485
+ * Sound_NewSample()'s "ext" parameter is gleaned from the contents of
486
+ * (filename).
487
+ *
488
+ * This can pool RWops structures, so it may fragment the heap less over time
489
+ * than using SDL_RWFromFile().
490
+ *
491
+ * \param filename file containing sound data.
492
+ * \param desired Format to convert sound data into. Can usually be NULL,
493
+ * if you don't need conversion.
494
+ * \param bufferSize size, in bytes, of initial read buffer.
495
+ * \return Sound_Sample pointer, which is used as a handle to several other
496
+ * SDL_sound APIs. NULL on error. If error, use
497
+ * Sound_GetError() to see what went wrong.
498
+ *
499
+ * \sa Sound_NewSample
500
+ * \sa Sound_SetBufferSize
501
+ * \sa Sound_Decode
502
+ * \sa Sound_DecodeAll
503
+ * \sa Sound_Seek
504
+ * \sa Sound_Rewind
505
+ * \sa Sound_FreeSample
506
+ */
507
+ SNDDECLSPEC Sound_Sample * SDLCALL Sound_NewSampleFromFile(const char *fname,
508
+ Sound_AudioInfo *desired,
509
+ Uint32 bufferSize);
510
+
511
+ /**
512
+ * \fn void Sound_FreeSample(Sound_Sample *sample)
513
+ * \brief Dispose of a Sound_Sample.
514
+ *
515
+ * This will also close/dispose of the SDL_RWops that was used at creation
516
+ * time, so there's no need to keep a reference to that around.
517
+ * The Sound_Sample pointer is invalid after this call, and will almost
518
+ * certainly result in a crash if you attempt to keep using it.
519
+ *
520
+ * \param sample The Sound_Sample to delete.
521
+ *
522
+ * \sa Sound_NewSample
523
+ * \sa Sound_NewSampleFromFile
524
+ */
525
+ SNDDECLSPEC void SDLCALL Sound_FreeSample(Sound_Sample *sample);
526
+
527
+
528
+ /**
529
+ * \fn Sint32 Sound_GetDuration(Sound_Sample *sample)
530
+ * \brief Retrieve total play time of sample, in milliseconds.
531
+ *
532
+ * Report total time length of sample, in milliseconds. This is a fast
533
+ * call. Duration is calculated during Sound_NewSample*, so this is just
534
+ * an accessor into otherwise opaque data.
535
+ *
536
+ * Please note that not all formats can determine a total time, some can't
537
+ * be exact without fully decoding the data, and thus will estimate the
538
+ * duration. Many decoders will require the ability to seek in the data
539
+ * stream to calculate this, so even if we can tell you how long an .ogg
540
+ * file will be, the same data set may fail if it's, say, streamed over an
541
+ * HTTP connection. Plan accordingly.
542
+ *
543
+ * Most people won't need this function to just decode and playback, but it
544
+ * can be useful for informational purposes in, say, a music player's UI.
545
+ *
546
+ * \param sample Sound_Sample from which to retrieve duration information.
547
+ * \return Sample length in milliseconds, or -1 if duration can't be
548
+ * determined for any reason.
549
+ */
550
+ SNDDECLSPEC Sint32 SDLCALL Sound_GetDuration(Sound_Sample *sample);
551
+
552
+
553
+ /**
554
+ * \fn int Sound_SetBufferSize(Sound_Sample *sample, Uint32 new_size)
555
+ * \brief Change the current buffer size for a sample.
556
+ *
557
+ * If the buffer size could be changed, then the sample->buffer and
558
+ * sample->buffer_size fields will reflect that. If they could not be
559
+ * changed, then your original sample state is preserved. If the buffer is
560
+ * shrinking, the data at the end of buffer is truncated. If the buffer is
561
+ * growing, the contents of the new space at the end is undefined until you
562
+ * decode more into it or initialize it yourself.
563
+ *
564
+ * The buffer size specified must be a multiple of the size of a single
565
+ * sample point. So, if you want 16-bit, stereo samples, then your sample
566
+ * point size is (2 channels * 16 bits), or 32 bits per sample, which is four
567
+ * bytes. In such a case, you could specify 128 or 132 bytes for a buffer,
568
+ * but not 129, 130, or 131 (although in reality, you'll want to specify a
569
+ * MUCH larger buffer).
570
+ *
571
+ * \param sample The Sound_Sample whose buffer to modify.
572
+ * \param new_size The desired size, in bytes, of the new buffer.
573
+ * \return non-zero if buffer size changed, zero on failure.
574
+ *
575
+ * \sa Sound_Decode
576
+ * \sa Sound_DecodeAll
577
+ */
578
+ SNDDECLSPEC int SDLCALL Sound_SetBufferSize(Sound_Sample *sample,
579
+ Uint32 new_size);
580
+
581
+
582
+ /**
583
+ * \fn Uint32 Sound_Decode(Sound_Sample *sample)
584
+ * \brief Decode more of the sound data in a Sound_Sample.
585
+ *
586
+ * It will decode at most sample->buffer_size bytes into sample->buffer in the
587
+ * desired format, and return the number of decoded bytes.
588
+ * If sample->buffer_size bytes could not be decoded, then please refer to
589
+ * sample->flags to determine if this was an end-of-stream or error condition.
590
+ *
591
+ * \param sample Do more decoding to this Sound_Sample.
592
+ * \return number of bytes decoded into sample->buffer. If it is less than
593
+ * sample->buffer_size, then you should check sample->flags to see
594
+ * what the current state of the sample is (EOF, error, read again).
595
+ *
596
+ * \sa Sound_DecodeAll
597
+ * \sa Sound_SetBufferSize
598
+ * \sa Sound_Seek
599
+ * \sa Sound_Rewind
600
+ */
601
+ SNDDECLSPEC Uint32 SDLCALL Sound_Decode(Sound_Sample *sample);
602
+
603
+
604
+ /**
605
+ * \fn Uint32 Sound_DecodeAll(Sound_Sample *sample)
606
+ * \brief Decode the remainder of the sound data in a Sound_Sample.
607
+ *
608
+ * This will dynamically allocate memory for the ENTIRE remaining sample.
609
+ * sample->buffer_size and sample->buffer will be updated to reflect the
610
+ * new buffer. Please refer to sample->flags to determine if the decoding
611
+ * finished due to an End-of-stream or error condition.
612
+ *
613
+ * Be aware that sound data can take a large amount of memory, and that
614
+ * this function may block for quite awhile while processing. Also note
615
+ * that a streaming source (for example, from a SDL_RWops that is getting
616
+ * fed from an Internet radio feed that doesn't end) may fill all available
617
+ * memory before giving up...be sure to use this on finite sound sources
618
+ * only!
619
+ *
620
+ * When decoding the sample in its entirety, the work is done one buffer at a
621
+ * time. That is, sound is decoded in sample->buffer_size blocks, and
622
+ * appended to a continually-growing buffer until the decoding completes.
623
+ * That means that this function will need enough RAM to hold approximately
624
+ * sample->buffer_size bytes plus the complete decoded sample at most. The
625
+ * larger your buffer size, the less overhead this function needs, but beware
626
+ * the possibility of paging to disk. Best to make this user-configurable if
627
+ * the sample isn't specific and small.
628
+ *
629
+ * \param sample Do all decoding for this Sound_Sample.
630
+ * \return number of bytes decoded into sample->buffer. You should check
631
+ * sample->flags to see what the current state of the sample is
632
+ * (EOF, error, read again).
633
+ *
634
+ * \sa Sound_Decode
635
+ * \sa Sound_SetBufferSize
636
+ */
637
+ SNDDECLSPEC Uint32 SDLCALL Sound_DecodeAll(Sound_Sample *sample);
638
+
639
+
640
+ /**
641
+ * \fn int Sound_Rewind(Sound_Sample *sample)
642
+ * \brief Rewind a sample to the start.
643
+ *
644
+ * Restart a sample at the start of its waveform data, as if newly
645
+ * created with Sound_NewSample(). If successful, the next call to
646
+ * Sound_Decode[All]() will give audio data from the earliest point
647
+ * in the stream.
648
+ *
649
+ * Beware that this function will fail if the SDL_RWops that feeds the
650
+ * decoder can not be rewound via it's seek method, but this can
651
+ * theoretically be avoided by wrapping it in some sort of buffering
652
+ * SDL_RWops.
653
+ *
654
+ * This function should ONLY fail if the RWops is not seekable, or
655
+ * SDL_sound is not initialized. Both can be controlled by the application,
656
+ * and thus, it is up to the developer's paranoia to dictate whether this
657
+ * function's return value need be checked at all.
658
+ *
659
+ * If this function fails, the state of the sample is undefined, but it
660
+ * is still safe to call Sound_FreeSample() to dispose of it.
661
+ *
662
+ * On success, ERROR, EOF, and EAGAIN are cleared from sample->flags. The
663
+ * ERROR flag is set on error.
664
+ *
665
+ * \param sample The Sound_Sample to rewind.
666
+ * \return nonzero on success, zero on error. Specifics of the
667
+ * error can be gleaned from Sound_GetError().
668
+ *
669
+ * \sa Sound_Seek
670
+ */
671
+ SNDDECLSPEC int SDLCALL Sound_Rewind(Sound_Sample *sample);
672
+
673
+
674
+ /**
675
+ * \fn int Sound_Seek(Sound_Sample *sample, Uint32 ms)
676
+ * \brief Seek to a different point in a sample.
677
+ *
678
+ * Reposition a sample's stream. If successful, the next call to
679
+ * Sound_Decode[All]() will give audio data from the offset you
680
+ * specified.
681
+ *
682
+ * The offset is specified in milliseconds from the start of the
683
+ * sample.
684
+ *
685
+ * Beware that this function can fail for several reasons. If the
686
+ * SDL_RWops that feeds the decoder can not seek, this call will almost
687
+ * certainly fail, but this can theoretically be avoided by wrapping it
688
+ * in some sort of buffering SDL_RWops. Some decoders can never seek,
689
+ * others can only seek with certain files. The decoders will set a flag
690
+ * in the sample at creation time to help you determine this.
691
+ *
692
+ * You should check sample->flags & SOUND_SAMPLEFLAG_CANSEEK
693
+ * before attempting. Sound_Seek() reports failure immediately if this
694
+ * flag isn't set. This function can still fail for other reasons if the
695
+ * flag is set.
696
+ *
697
+ * This function can be emulated in the application with Sound_Rewind()
698
+ * and predecoding a specific amount of the sample, but this can be
699
+ * extremely inefficient. Sound_Seek() accelerates the seek on a
700
+ * with decoder-specific code.
701
+ *
702
+ * If this function fails, the sample should continue to function as if
703
+ * this call was never made. If there was an unrecoverable error,
704
+ * sample->flags & SOUND_SAMPLEFLAG_ERROR will be set, which you regular
705
+ * decoding loop can pick up.
706
+ *
707
+ * On success, ERROR, EOF, and EAGAIN are cleared from sample->flags.
708
+ *
709
+ * \param sample The Sound_Sample to seek.
710
+ * \param ms The new position, in milliseconds from start of sample.
711
+ * \return nonzero on success, zero on error. Specifics of the
712
+ * error can be gleaned from Sound_GetError().
713
+ *
714
+ * \sa Sound_Rewind
715
+ */
716
+ SNDDECLSPEC int SDLCALL Sound_Seek(Sound_Sample *sample, Uint32 ms);
717
+
718
+ #ifdef __cplusplus
719
+ }
720
+ #endif
721
+
722
+ #endif /* !defined _INCLUDE_SDL_SOUND_H_ */
723
+
724
+ /* end of SDL_sound.h ... */
725
+