ruby2d 0.11.0 → 0.11.3

Sign up to get free protection for your applications and to get access to all the features.
Files changed (404) hide show
  1. checksums.yaml +4 -4
  2. data/assets/include/SDL2/SDL.h +108 -14
  3. data/assets/include/SDL2/SDL_assert.h +81 -50
  4. data/assets/include/SDL2/SDL_atomic.h +135 -35
  5. data/assets/include/SDL2/SDL_audio.h +960 -355
  6. data/assets/include/SDL2/SDL_bits.h +11 -6
  7. data/assets/include/SDL2/SDL_blendmode.h +91 -14
  8. data/assets/include/SDL2/SDL_clipboard.h +30 -7
  9. data/assets/include/SDL2/SDL_config.h +3 -1
  10. data/assets/include/SDL2/SDL_config_android.h +11 -1
  11. data/assets/include/SDL2/SDL_config_emscripten.h +216 -0
  12. data/assets/include/SDL2/SDL_config_iphoneos.h +9 -1
  13. data/assets/include/SDL2/SDL_config_macosx.h +16 -2
  14. data/assets/include/SDL2/SDL_config_minimal.h +4 -1
  15. data/assets/include/SDL2/SDL_config_os2.h +37 -20
  16. data/assets/include/SDL2/SDL_config_pandora.h +6 -1
  17. data/assets/include/SDL2/SDL_config_psp.h +8 -8
  18. data/assets/include/SDL2/SDL_config_windows.h +39 -22
  19. data/assets/include/SDL2/SDL_config_winrt.h +23 -8
  20. data/assets/include/SDL2/SDL_config_wiz.h +6 -1
  21. data/assets/include/SDL2/SDL_copying.h +1 -1
  22. data/assets/include/SDL2/SDL_cpuinfo.h +331 -71
  23. data/assets/include/SDL2/SDL_egl.h +906 -280
  24. data/assets/include/SDL2/SDL_endian.h +101 -47
  25. data/assets/include/SDL2/SDL_error.h +70 -19
  26. data/assets/include/SDL2/SDL_events.h +387 -79
  27. data/assets/include/SDL2/SDL_filesystem.h +73 -64
  28. data/assets/include/SDL2/SDL_gamecontroller.h +585 -125
  29. data/assets/include/SDL2/SDL_gesture.h +36 -6
  30. data/assets/include/SDL2/SDL_haptic.h +304 -210
  31. data/assets/include/SDL2/SDL_hidapi.h +451 -0
  32. data/assets/include/SDL2/SDL_hints.h +1286 -897
  33. data/assets/include/SDL2/SDL_joystick.h +577 -130
  34. data/assets/include/SDL2/SDL_keyboard.h +162 -63
  35. data/assets/include/SDL2/SDL_keycode.h +7 -5
  36. data/assets/include/SDL2/SDL_loadso.h +42 -8
  37. data/assets/include/SDL2/SDL_locale.h +34 -32
  38. data/assets/include/SDL2/SDL_log.h +212 -19
  39. data/assets/include/SDL2/SDL_main.h +72 -17
  40. data/assets/include/SDL2/SDL_messagebox.h +70 -23
  41. data/assets/include/SDL2/SDL_metal.h +27 -32
  42. data/assets/include/SDL2/SDL_misc.h +19 -15
  43. data/assets/include/SDL2/SDL_mouse.h +262 -110
  44. data/assets/include/SDL2/SDL_mutex.h +286 -66
  45. data/assets/include/SDL2/SDL_name.h +1 -1
  46. data/assets/include/SDL2/SDL_opengl.h +1 -1
  47. data/assets/include/SDL2/SDL_opengles.h +1 -1
  48. data/assets/include/SDL2/SDL_opengles2.h +2 -2
  49. data/assets/include/SDL2/SDL_pixels.h +199 -34
  50. data/assets/include/SDL2/SDL_platform.h +39 -2
  51. data/assets/include/SDL2/SDL_power.h +23 -10
  52. data/assets/include/SDL2/SDL_quit.h +1 -1
  53. data/assets/include/SDL2/SDL_rect.h +78 -28
  54. data/assets/include/SDL2/SDL_render.h +1204 -472
  55. data/assets/include/SDL2/SDL_revision.h +2 -2
  56. data/assets/include/SDL2/SDL_rwops.h +605 -33
  57. data/assets/include/SDL2/SDL_scancode.h +1 -1
  58. data/assets/include/SDL2/SDL_sensor.h +76 -42
  59. data/assets/include/SDL2/SDL_shape.h +38 -27
  60. data/assets/include/SDL2/SDL_stdinc.h +96 -24
  61. data/assets/include/SDL2/SDL_surface.h +571 -139
  62. data/assets/include/SDL2/SDL_system.h +339 -101
  63. data/assets/include/SDL2/SDL_syswm.h +50 -20
  64. data/assets/include/SDL2/SDL_test.h +1 -1
  65. data/assets/include/SDL2/SDL_test_assert.h +2 -2
  66. data/assets/include/SDL2/SDL_test_common.h +23 -6
  67. data/assets/include/SDL2/SDL_test_compare.h +1 -1
  68. data/assets/include/SDL2/SDL_test_crc32.h +1 -1
  69. data/assets/include/SDL2/SDL_test_font.h +3 -3
  70. data/assets/include/SDL2/SDL_test_fuzzer.h +28 -26
  71. data/assets/include/SDL2/SDL_test_harness.h +6 -6
  72. data/assets/include/SDL2/SDL_test_images.h +1 -1
  73. data/assets/include/SDL2/SDL_test_log.h +1 -1
  74. data/assets/include/SDL2/SDL_test_md5.h +1 -1
  75. data/assets/include/SDL2/SDL_test_memory.h +1 -1
  76. data/assets/include/SDL2/SDL_test_random.h +2 -2
  77. data/assets/include/SDL2/SDL_thread.h +226 -128
  78. data/assets/include/SDL2/SDL_timer.h +129 -22
  79. data/assets/include/SDL2/SDL_touch.h +48 -8
  80. data/assets/include/SDL2/SDL_ttf.h +102 -9
  81. data/assets/include/SDL2/SDL_types.h +1 -1
  82. data/assets/include/SDL2/SDL_version.h +72 -46
  83. data/assets/include/SDL2/SDL_video.h +1266 -460
  84. data/assets/include/SDL2/SDL_vulkan.h +100 -161
  85. data/assets/include/SDL2/begin_code.h +22 -1
  86. data/assets/include/SDL2/close_code.h +1 -1
  87. data/assets/include/mrbconf.h +234 -0
  88. data/assets/include/mruby/array.h +317 -0
  89. data/assets/include/mruby/boxing_nan.h +130 -0
  90. data/assets/include/mruby/boxing_no.h +58 -0
  91. data/assets/include/mruby/boxing_word.h +205 -0
  92. data/assets/include/mruby/class.h +108 -0
  93. data/assets/include/mruby/common.h +92 -0
  94. data/assets/include/mruby/compile.h +210 -0
  95. data/assets/include/mruby/data.h +76 -0
  96. data/assets/include/mruby/debug.h +66 -0
  97. data/assets/include/mruby/dump.h +158 -0
  98. data/assets/include/mruby/endian.h +44 -0
  99. data/assets/include/mruby/error.h +137 -0
  100. data/assets/include/mruby/gc.h +92 -0
  101. data/assets/include/mruby/hash.h +242 -0
  102. data/assets/include/mruby/irep.h +147 -0
  103. data/assets/include/mruby/istruct.h +50 -0
  104. data/assets/include/mruby/khash.h +284 -0
  105. data/assets/include/mruby/numeric.h +169 -0
  106. data/assets/include/mruby/object.h +43 -0
  107. data/assets/include/mruby/opcode.h +43 -0
  108. data/assets/include/mruby/ops.h +122 -0
  109. data/assets/include/mruby/presym/disable.h +70 -0
  110. data/assets/include/mruby/presym/enable.h +37 -0
  111. data/assets/include/mruby/presym/scanning.h +73 -0
  112. data/assets/include/mruby/presym.h +40 -0
  113. data/assets/include/mruby/proc.h +209 -0
  114. data/assets/include/mruby/range.h +79 -0
  115. data/assets/include/mruby/re.h +16 -0
  116. data/assets/include/mruby/string.h +469 -0
  117. data/assets/include/mruby/throw.h +66 -0
  118. data/assets/include/mruby/value.h +400 -0
  119. data/assets/include/mruby/variable.h +140 -0
  120. data/assets/include/mruby/version.h +143 -0
  121. data/assets/include/mruby.h +1444 -0
  122. data/assets/macos/universal/bin/mrbc +0 -0
  123. data/assets/macos/universal/lib/libFLAC.a +0 -0
  124. data/assets/macos/universal/lib/libSDL2.a +0 -0
  125. data/assets/macos/universal/lib/libSDL2_image.a +0 -0
  126. data/assets/macos/{lib → universal/lib}/libSDL2_mixer.a +0 -0
  127. data/assets/macos/universal/lib/libSDL2_ttf.a +0 -0
  128. data/assets/macos/universal/lib/libfreetype.a +0 -0
  129. data/assets/macos/universal/lib/libgraphite2.a +0 -0
  130. data/assets/macos/universal/lib/libharfbuzz.a +0 -0
  131. data/assets/macos/universal/lib/libjpeg.a +0 -0
  132. data/assets/macos/universal/lib/libmodplug.a +0 -0
  133. data/assets/macos/{lib → universal/lib}/libmpg123.a +0 -0
  134. data/assets/{mingw/lib/libSDL2.a → macos/universal/lib/libmruby.a} +0 -0
  135. data/assets/macos/{lib → universal/lib}/libogg.a +0 -0
  136. data/assets/macos/universal/lib/libpng16.a +0 -0
  137. data/assets/macos/universal/lib/libtiff.a +0 -0
  138. data/assets/macos/universal/lib/libvorbis.a +0 -0
  139. data/assets/macos/universal/lib/libvorbisfile.a +0 -0
  140. data/assets/macos/universal/lib/libwebp.a +0 -0
  141. data/assets/test_media/README.md +3 -0
  142. data/assets/test_media/bitstream_vera/COPYRIGHT.txt +124 -0
  143. data/assets/test_media/bitstream_vera/vera.ttf +0 -0
  144. data/assets/test_media/boom.png +0 -0
  145. data/assets/test_media/coin.png +0 -0
  146. data/assets/test_media/colors.png +0 -0
  147. data/assets/test_media/controller.png +0 -0
  148. data/assets/test_media/dial.wav +0 -0
  149. data/assets/test_media/hero.png +0 -0
  150. data/assets/test_media/image.bmp +0 -0
  151. data/assets/test_media/image.jpg +0 -0
  152. data/assets/test_media/image.png +0 -0
  153. data/assets/test_media/music.flac +0 -0
  154. data/assets/test_media/music.mp3 +0 -0
  155. data/assets/test_media/music.ogg +0 -0
  156. data/assets/test_media/music.wav +0 -0
  157. data/assets/test_media/originals/boom.pxm +0 -0
  158. data/assets/test_media/originals/coin.pxm +0 -0
  159. data/assets/test_media/originals/controller.sketch +0 -0
  160. data/assets/test_media/originals/hero.pxm +0 -0
  161. data/assets/test_media/originals/image.pxm +0 -0
  162. data/assets/test_media/originals/music.caf +0 -0
  163. data/assets/test_media/originals/texture_atlas.pxm +0 -0
  164. data/assets/test_media/rondo_alla_turka.ogg +0 -0
  165. data/assets/test_media/sound.flac +0 -0
  166. data/assets/test_media/sound.mp3 +0 -0
  167. data/assets/test_media/sound.ogg +0 -0
  168. data/assets/test_media/sound.wav +0 -0
  169. data/assets/test_media/sprite_sheet.png +0 -0
  170. data/assets/test_media/texture_atlas.png +0 -0
  171. data/assets/wasm/libmruby.a +0 -0
  172. data/assets/wasm/template.html +64 -0
  173. data/assets/windows/glew/README.md +10 -0
  174. data/assets/windows/glew/glew.h +23686 -0
  175. data/assets/{mingw/lib → windows/glew}/libglew32.a +0 -0
  176. data/assets/windows/mingw-w64-ucrt-x86_64/bin/mrbc.exe +0 -0
  177. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libFLAC.a +0 -0
  178. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libLerc.a +0 -0
  179. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libSDL2.a +0 -0
  180. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libSDL2_image.a +0 -0
  181. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libSDL2_mixer.a +0 -0
  182. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libSDL2_ttf.a +0 -0
  183. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libbrotlicommon.a +0 -0
  184. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libbrotlidec.a +0 -0
  185. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libbz2.a +0 -0
  186. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libdeflate.a +0 -0
  187. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libfreetype.a +0 -0
  188. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libglew32.a +0 -0
  189. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libgraphite2.a +0 -0
  190. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libharfbuzz.a +0 -0
  191. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libjbig.a +0 -0
  192. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libjpeg.a +0 -0
  193. data/assets/windows/mingw-w64-ucrt-x86_64/lib/liblzma.a +0 -0
  194. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libmodplug.a +0 -0
  195. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libmpg123.a +0 -0
  196. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libmruby.a +0 -0
  197. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libogg.a +0 -0
  198. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libopus.a +0 -0
  199. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libopusfile.a +0 -0
  200. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libpng16.a +0 -0
  201. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libsndfile.a +0 -0
  202. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libssp.a +0 -0
  203. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libstdc++.a +0 -0
  204. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libtiff.a +0 -0
  205. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libvorbis.a +0 -0
  206. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libvorbisfile.a +0 -0
  207. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libwebp.a +0 -0
  208. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libz.a +0 -0
  209. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libzstd.a +0 -0
  210. data/assets/windows/mingw-w64-x86_64/bin/mrbc.exe +0 -0
  211. data/assets/windows/mingw-w64-x86_64/lib/libFLAC.a +0 -0
  212. data/assets/windows/mingw-w64-x86_64/lib/libLerc.a +0 -0
  213. data/assets/windows/mingw-w64-x86_64/lib/libSDL2.a +0 -0
  214. data/assets/windows/mingw-w64-x86_64/lib/libSDL2_image.a +0 -0
  215. data/assets/windows/mingw-w64-x86_64/lib/libSDL2_mixer.a +0 -0
  216. data/assets/windows/mingw-w64-x86_64/lib/libSDL2_ttf.a +0 -0
  217. data/assets/windows/mingw-w64-x86_64/lib/libbrotlicommon.a +0 -0
  218. data/assets/windows/mingw-w64-x86_64/lib/libbrotlidec.a +0 -0
  219. data/assets/windows/mingw-w64-x86_64/lib/libbz2.a +0 -0
  220. data/assets/windows/mingw-w64-x86_64/lib/libdeflate.a +0 -0
  221. data/assets/windows/mingw-w64-x86_64/lib/libfreetype.a +0 -0
  222. data/assets/windows/mingw-w64-x86_64/lib/libglew32.a +0 -0
  223. data/assets/windows/mingw-w64-x86_64/lib/libgraphite2.a +0 -0
  224. data/assets/windows/mingw-w64-x86_64/lib/libharfbuzz.a +0 -0
  225. data/assets/windows/mingw-w64-x86_64/lib/libjbig.a +0 -0
  226. data/assets/windows/mingw-w64-x86_64/lib/libjpeg.a +0 -0
  227. data/assets/windows/mingw-w64-x86_64/lib/liblzma.a +0 -0
  228. data/assets/windows/mingw-w64-x86_64/lib/libmodplug.a +0 -0
  229. data/assets/windows/mingw-w64-x86_64/lib/libmpg123.a +0 -0
  230. data/assets/windows/mingw-w64-x86_64/lib/libmruby.a +0 -0
  231. data/assets/windows/mingw-w64-x86_64/lib/libogg.a +0 -0
  232. data/assets/windows/mingw-w64-x86_64/lib/libopus.a +0 -0
  233. data/assets/windows/mingw-w64-x86_64/lib/libopusfile.a +0 -0
  234. data/assets/windows/mingw-w64-x86_64/lib/libpng16.a +0 -0
  235. data/assets/windows/mingw-w64-x86_64/lib/libsndfile.a +0 -0
  236. data/assets/windows/mingw-w64-x86_64/lib/libssp.a +0 -0
  237. data/assets/windows/mingw-w64-x86_64/lib/libstdc++.a +0 -0
  238. data/assets/windows/mingw-w64-x86_64/lib/libtiff.a +0 -0
  239. data/assets/windows/mingw-w64-x86_64/lib/libvorbis.a +0 -0
  240. data/assets/windows/mingw-w64-x86_64/lib/libvorbisfile.a +0 -0
  241. data/assets/windows/mingw-w64-x86_64/lib/libwebp.a +0 -0
  242. data/assets/windows/mingw-w64-x86_64/lib/libz.a +0 -0
  243. data/assets/windows/mingw-w64-x86_64/lib/libzstd.a +0 -0
  244. data/assets/{ios → xcode/ios}/Assets.xcassets/AppIcon.appiconset/Contents.json +0 -0
  245. data/assets/{ios → xcode/ios}/Assets.xcassets/Contents.json +0 -0
  246. data/assets/{ios → xcode/ios}/Base.lproj/LaunchScreen.storyboard +0 -0
  247. data/assets/{ios → xcode/ios}/Info.plist +0 -0
  248. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mrbconf.h +0 -0
  249. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/array.h +0 -0
  250. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/boxing_nan.h +0 -0
  251. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/boxing_no.h +0 -0
  252. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/boxing_word.h +0 -0
  253. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/class.h +0 -0
  254. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/common.h +0 -0
  255. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/compile.h +0 -0
  256. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/data.h +0 -0
  257. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/debug.h +0 -0
  258. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/dump.h +0 -0
  259. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/error.h +0 -0
  260. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/gc.h +0 -0
  261. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/hash.h +0 -0
  262. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/irep.h +0 -0
  263. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/istruct.h +0 -0
  264. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/khash.h +0 -0
  265. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/numeric.h +0 -0
  266. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/object.h +0 -0
  267. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/opcode.h +0 -0
  268. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/ops.h +0 -0
  269. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/proc.h +0 -0
  270. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/range.h +0 -0
  271. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/re.h +0 -0
  272. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/string.h +0 -0
  273. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/throw.h +0 -0
  274. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/value.h +0 -0
  275. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/variable.h +0 -0
  276. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby/version.h +0 -0
  277. data/assets/{ios → xcode/ios}/MRuby.framework/Headers/mruby.h +0 -0
  278. data/assets/{ios → xcode/ios}/MRuby.framework/Info.plist +0 -0
  279. data/assets/{ios → xcode/ios}/MRuby.framework/MRuby +0 -0
  280. data/assets/{ios → xcode/ios}/MyApp.xcodeproj/project.pbxproj +0 -0
  281. data/assets/{ios → xcode/ios}/MyApp.xcodeproj/project.xcworkspace/contents.xcworkspacedata +0 -0
  282. data/assets/{ios → xcode/ios}/MyApp.xcodeproj/project.xcworkspace/xcshareddata/IDEWorkspaceChecks.plist +0 -0
  283. data/assets/{ios → xcode/ios}/MyApp.xcodeproj/project.xcworkspace/xcshareddata/MyApp.xcscmblueprint +0 -0
  284. data/assets/{ios → xcode/ios}/main.c +0 -0
  285. data/assets/{tvos → xcode/tvos}/Assets.xcassets/App Icon & Top Shelf Image.brandassets/App Icon - Large.imagestack/Back.imagestacklayer/Content.imageset/Contents.json +0 -0
  286. data/assets/{tvos → xcode/tvos}/Assets.xcassets/App Icon & Top Shelf Image.brandassets/App Icon - Large.imagestack/Back.imagestacklayer/Contents.json +0 -0
  287. data/assets/{tvos → xcode/tvos}/Assets.xcassets/App Icon & Top Shelf Image.brandassets/App Icon - Large.imagestack/Contents.json +0 -0
  288. data/assets/{tvos → xcode/tvos}/Assets.xcassets/App Icon & Top Shelf Image.brandassets/App Icon - Large.imagestack/Front.imagestacklayer/Content.imageset/Contents.json +0 -0
  289. data/assets/{tvos → xcode/tvos}/Assets.xcassets/App Icon & Top Shelf Image.brandassets/App Icon - Large.imagestack/Front.imagestacklayer/Contents.json +0 -0
  290. data/assets/{tvos → xcode/tvos}/Assets.xcassets/App Icon & Top Shelf Image.brandassets/App Icon - Large.imagestack/Middle.imagestacklayer/Content.imageset/Contents.json +0 -0
  291. data/assets/{tvos → xcode/tvos}/Assets.xcassets/App Icon & Top Shelf Image.brandassets/App Icon - Large.imagestack/Middle.imagestacklayer/Contents.json +0 -0
  292. data/assets/{tvos → xcode/tvos}/Assets.xcassets/App Icon & Top Shelf Image.brandassets/App Icon - Small.imagestack/Back.imagestacklayer/Content.imageset/Contents.json +0 -0
  293. data/assets/{tvos → xcode/tvos}/Assets.xcassets/App Icon & Top Shelf Image.brandassets/App Icon - Small.imagestack/Back.imagestacklayer/Contents.json +0 -0
  294. data/assets/{tvos → xcode/tvos}/Assets.xcassets/App Icon & Top Shelf Image.brandassets/App Icon - Small.imagestack/Contents.json +0 -0
  295. data/assets/{tvos → xcode/tvos}/Assets.xcassets/App Icon & Top Shelf Image.brandassets/App Icon - Small.imagestack/Front.imagestacklayer/Content.imageset/Contents.json +0 -0
  296. data/assets/{tvos → xcode/tvos}/Assets.xcassets/App Icon & Top Shelf Image.brandassets/App Icon - Small.imagestack/Front.imagestacklayer/Contents.json +0 -0
  297. data/assets/{tvos → xcode/tvos}/Assets.xcassets/App Icon & Top Shelf Image.brandassets/App Icon - Small.imagestack/Middle.imagestacklayer/Content.imageset/Contents.json +0 -0
  298. data/assets/{tvos → xcode/tvos}/Assets.xcassets/App Icon & Top Shelf Image.brandassets/App Icon - Small.imagestack/Middle.imagestacklayer/Contents.json +0 -0
  299. data/assets/{tvos → xcode/tvos}/Assets.xcassets/App Icon & Top Shelf Image.brandassets/Contents.json +0 -0
  300. data/assets/{tvos → xcode/tvos}/Assets.xcassets/App Icon & Top Shelf Image.brandassets/Top Shelf Image Wide.imageset/Contents.json +0 -0
  301. data/assets/{tvos → xcode/tvos}/Assets.xcassets/App Icon & Top Shelf Image.brandassets/Top Shelf Image.imageset/Contents.json +0 -0
  302. data/assets/{tvos → xcode/tvos}/Assets.xcassets/Contents.json +0 -0
  303. data/assets/{tvos → xcode/tvos}/Assets.xcassets/LaunchImage.launchimage/Contents.json +0 -0
  304. data/assets/{tvos → xcode/tvos}/Info.plist +0 -0
  305. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mrbconf.h +0 -0
  306. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/array.h +0 -0
  307. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/boxing_nan.h +0 -0
  308. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/boxing_no.h +0 -0
  309. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/boxing_word.h +0 -0
  310. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/class.h +0 -0
  311. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/common.h +0 -0
  312. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/compile.h +0 -0
  313. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/data.h +0 -0
  314. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/debug.h +0 -0
  315. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/dump.h +0 -0
  316. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/error.h +0 -0
  317. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/gc.h +0 -0
  318. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/hash.h +0 -0
  319. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/irep.h +0 -0
  320. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/istruct.h +0 -0
  321. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/khash.h +0 -0
  322. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/numeric.h +0 -0
  323. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/object.h +0 -0
  324. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/opcode.h +0 -0
  325. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/ops.h +0 -0
  326. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/proc.h +0 -0
  327. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/range.h +0 -0
  328. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/re.h +0 -0
  329. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/string.h +0 -0
  330. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/throw.h +0 -0
  331. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/value.h +0 -0
  332. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/variable.h +0 -0
  333. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby/version.h +0 -0
  334. data/assets/{tvos → xcode/tvos}/MRuby.framework/Headers/mruby.h +0 -0
  335. data/assets/{tvos → xcode/tvos}/MRuby.framework/Info.plist +0 -0
  336. data/assets/{tvos → xcode/tvos}/MRuby.framework/MRuby +0 -0
  337. data/assets/{tvos → xcode/tvos}/MyApp.xcodeproj/project.pbxproj +0 -0
  338. data/assets/{tvos → xcode/tvos}/MyApp.xcodeproj/project.xcworkspace/contents.xcworkspacedata +0 -0
  339. data/assets/{tvos → xcode/tvos}/MyApp.xcodeproj/project.xcworkspace/xcshareddata/IDEWorkspaceChecks.plist +0 -0
  340. data/assets/{tvos → xcode/tvos}/MyApp.xcodeproj/project.xcworkspace/xcshareddata/MyApp.xcscmblueprint +0 -0
  341. data/assets/{tvos → xcode/tvos}/main.c +0 -0
  342. data/bin/ruby2d +3 -4
  343. data/ext/ruby2d/extconf.rb +44 -25
  344. data/ext/ruby2d/gl.c +1 -1
  345. data/ext/ruby2d/gl3.c +0 -1
  346. data/ext/ruby2d/gles.c +137 -84
  347. data/ext/ruby2d/ruby2d.c +126 -32
  348. data/ext/ruby2d/ruby2d.h +53 -6
  349. data/ext/ruby2d/text.c +14 -1
  350. data/ext/ruby2d/window.c +253 -215
  351. data/lib/ruby2d/cli/build.rb +242 -59
  352. data/lib/ruby2d/cli/colorize.rb +5 -4
  353. data/lib/ruby2d/cli/platform.rb +17 -0
  354. data/lib/ruby2d/font.rb +7 -1
  355. data/lib/ruby2d/sprite.rb +7 -2
  356. data/lib/ruby2d/text.rb +1 -3
  357. data/lib/ruby2d/texture.rb +21 -21
  358. data/lib/ruby2d/tileset.rb +34 -33
  359. data/lib/ruby2d/version.rb +1 -1
  360. data/lib/ruby2d/vertices.rb +11 -6
  361. data/lib/ruby2d.rb +14 -20
  362. metadata +279 -151
  363. data/assets/README.md +0 -22
  364. data/assets/Rakefile +0 -85
  365. data/assets/macos/lib/libFLAC.a +0 -0
  366. data/assets/macos/lib/libSDL2.a +0 -0
  367. data/assets/macos/lib/libSDL2_image.a +0 -0
  368. data/assets/macos/lib/libSDL2_ttf.a +0 -0
  369. data/assets/macos/lib/libfreetype.a +0 -0
  370. data/assets/macos/lib/libjpeg.a +0 -0
  371. data/assets/macos/lib/libpng16.a +0 -0
  372. data/assets/macos/lib/libtiff.a +0 -0
  373. data/assets/macos/lib/libvorbis.a +0 -0
  374. data/assets/macos/lib/libvorbisfile.a +0 -0
  375. data/assets/macos/lib/libwebp.a +0 -0
  376. data/assets/mingw/bin/SDL2.dll +0 -0
  377. data/assets/mingw/bin/SDL2_image.dll +0 -0
  378. data/assets/mingw/bin/SDL2_mixer.dll +0 -0
  379. data/assets/mingw/bin/SDL2_ttf.dll +0 -0
  380. data/assets/mingw/bin/glew32.dll +0 -0
  381. data/assets/mingw/bin/libFLAC-8.dll +0 -0
  382. data/assets/mingw/bin/libfreetype-6.dll +0 -0
  383. data/assets/mingw/bin/libjpeg-9.dll +0 -0
  384. data/assets/mingw/bin/libmodplug-1.dll +0 -0
  385. data/assets/mingw/bin/libmpg123-0.dll +0 -0
  386. data/assets/mingw/bin/libogg-0.dll +0 -0
  387. data/assets/mingw/bin/libopus-0.dll +0 -0
  388. data/assets/mingw/bin/libopusfile-0.dll +0 -0
  389. data/assets/mingw/bin/libpng16-16.dll +0 -0
  390. data/assets/mingw/bin/libtiff-5.dll +0 -0
  391. data/assets/mingw/bin/libvorbis-0.dll +0 -0
  392. data/assets/mingw/bin/libvorbisfile-3.dll +0 -0
  393. data/assets/mingw/bin/libwebp-7.dll +0 -0
  394. data/assets/mingw/bin/zlib1.dll +0 -0
  395. data/assets/mingw/lib/libSDL2.dll.a +0 -0
  396. data/assets/mingw/lib/libSDL2_image.a +0 -0
  397. data/assets/mingw/lib/libSDL2_image.dll.a +0 -0
  398. data/assets/mingw/lib/libSDL2_mixer.a +0 -0
  399. data/assets/mingw/lib/libSDL2_mixer.dll.a +0 -0
  400. data/assets/mingw/lib/libSDL2_test.a +0 -0
  401. data/assets/mingw/lib/libSDL2_ttf.a +0 -0
  402. data/assets/mingw/lib/libSDL2_ttf.dll.a +0 -0
  403. data/assets/mingw/lib/libSDL2main.a +0 -0
  404. data/assets/mingw/lib/libglew32.dll.a +0 -0
@@ -1,6 +1,6 @@
1
1
  /*
2
2
  Simple DirectMedia Layer
3
- Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
3
+ Copyright (C) 1997-2022 Sam Lantinga <slouken@libsdl.org>
4
4
 
5
5
  This software is provided 'as-is', without any express or implied
6
6
  warranty. In no event will the authors be held liable for any damages
@@ -19,6 +19,8 @@
19
19
  3. This notice may not be removed or altered from any source distribution.
20
20
  */
21
21
 
22
+ /* !!! FIXME: several functions in here need Doxygen comments. */
23
+
22
24
  /**
23
25
  * \file SDL_audio.h
24
26
  *
@@ -212,9 +214,12 @@ typedef void (SDLCALL * SDL_AudioFilter) (struct SDL_AudioCVT * cvt,
212
214
  * set both its (buf) field to a pointer that is aligned to 16 bytes, and its
213
215
  * (len) field to something that's a multiple of 16, if possible.
214
216
  */
215
- #ifdef __GNUC__
217
+ #if defined(__GNUC__) && !defined(__CHERI_PURE_CAPABILITY__)
216
218
  /* This structure is 84 bytes on 32-bit architectures, make sure GCC doesn't
217
219
  pad it out to 88 bytes to guarantee ABI compatibility between compilers.
220
+ This is not a concern on CHERI architectures, where pointers must be stored
221
+ at aligned locations otherwise they will become invalid, and thus structs
222
+ containing pointers cannot be packed without giving a warning or error.
218
223
  vvv
219
224
  The next time we rev the ABI, make sure to size the ints and add padding.
220
225
  */
@@ -248,7 +253,48 @@ typedef struct SDL_AudioCVT
248
253
  * order that they are normally initialized by default.
249
254
  */
250
255
  /* @{ */
256
+
257
+ /**
258
+ * Use this function to get the number of built-in audio drivers.
259
+ *
260
+ * This function returns a hardcoded number. This never returns a negative
261
+ * value; if there are no drivers compiled into this build of SDL, this
262
+ * function returns zero. The presence of a driver in this list does not mean
263
+ * it will function, it just means SDL is capable of interacting with that
264
+ * interface. For example, a build of SDL might have esound support, but if
265
+ * there's no esound server available, SDL's esound driver would fail if used.
266
+ *
267
+ * By default, SDL tries all drivers, in its preferred order, until one is
268
+ * found to be usable.
269
+ *
270
+ * \returns the number of built-in audio drivers.
271
+ *
272
+ * \since This function is available since SDL 2.0.0.
273
+ *
274
+ * \sa SDL_GetAudioDriver
275
+ */
251
276
  extern DECLSPEC int SDLCALL SDL_GetNumAudioDrivers(void);
277
+
278
+ /**
279
+ * Use this function to get the name of a built in audio driver.
280
+ *
281
+ * The list of audio drivers is given in the order that they are normally
282
+ * initialized by default; the drivers that seem more reasonable to choose
283
+ * first (as far as the SDL developers believe) are earlier in the list.
284
+ *
285
+ * The names of drivers are all simple, low-ASCII identifiers, like "alsa",
286
+ * "coreaudio" or "xaudio2". These never have Unicode characters, and are not
287
+ * meant to be proper names.
288
+ *
289
+ * \param index the index of the audio driver; the value ranges from 0 to
290
+ * SDL_GetNumAudioDrivers() - 1
291
+ * \returns the name of the audio driver at the requested index, or NULL if an
292
+ * invalid index was specified.
293
+ *
294
+ * \since This function is available since SDL 2.0.0.
295
+ *
296
+ * \sa SDL_GetNumAudioDrivers
297
+ */
252
298
  extern DECLSPEC const char *SDLCALL SDL_GetAudioDriver(int index);
253
299
  /* @} */
254
300
 
@@ -260,60 +306,103 @@ extern DECLSPEC const char *SDLCALL SDL_GetAudioDriver(int index);
260
306
  * use. You should normally use SDL_Init() or SDL_InitSubSystem().
261
307
  */
262
308
  /* @{ */
309
+
310
+ /**
311
+ * Use this function to initialize a particular audio driver.
312
+ *
313
+ * This function is used internally, and should not be used unless you have a
314
+ * specific need to designate the audio driver you want to use. You should
315
+ * normally use SDL_Init() or SDL_InitSubSystem().
316
+ *
317
+ * \param driver_name the name of the desired audio driver
318
+ * \returns 0 on success or a negative error code on failure; call
319
+ * SDL_GetError() for more information.
320
+ *
321
+ * \since This function is available since SDL 2.0.0.
322
+ *
323
+ * \sa SDL_AudioQuit
324
+ */
263
325
  extern DECLSPEC int SDLCALL SDL_AudioInit(const char *driver_name);
326
+
327
+ /**
328
+ * Use this function to shut down audio if you initialized it with
329
+ * SDL_AudioInit().
330
+ *
331
+ * This function is used internally, and should not be used unless you have a
332
+ * specific need to specify the audio driver you want to use. You should
333
+ * normally use SDL_Quit() or SDL_QuitSubSystem().
334
+ *
335
+ * \since This function is available since SDL 2.0.0.
336
+ *
337
+ * \sa SDL_AudioInit
338
+ */
264
339
  extern DECLSPEC void SDLCALL SDL_AudioQuit(void);
265
340
  /* @} */
266
341
 
267
342
  /**
268
- * This function returns the name of the current audio driver, or NULL
269
- * if no driver has been initialized.
343
+ * Get the name of the current audio driver.
344
+ *
345
+ * The returned string points to internal static memory and thus never becomes
346
+ * invalid, even if you quit the audio subsystem and initialize a new driver
347
+ * (although such a case would return a different static string from another
348
+ * call to this function, of course). As such, you should not modify or free
349
+ * the returned string.
350
+ *
351
+ * \returns the name of the current audio driver or NULL if no driver has been
352
+ * initialized.
353
+ *
354
+ * \since This function is available since SDL 2.0.0.
355
+ *
356
+ * \sa SDL_AudioInit
270
357
  */
271
358
  extern DECLSPEC const char *SDLCALL SDL_GetCurrentAudioDriver(void);
272
359
 
273
360
  /**
274
- * This function opens the audio device with the desired parameters, and
275
- * returns 0 if successful, placing the actual hardware parameters in the
276
- * structure pointed to by \c obtained. If \c obtained is NULL, the audio
277
- * data passed to the callback function will be guaranteed to be in the
278
- * requested format, and will be automatically converted to the hardware
279
- * audio format if necessary. This function returns -1 if it failed
280
- * to open the audio device, or couldn't set up the audio thread.
281
- *
282
- * When filling in the desired audio spec structure,
283
- * - \c desired->freq should be the desired audio frequency in samples-per-
284
- * second.
285
- * - \c desired->format should be the desired audio format.
286
- * - \c desired->samples is the desired size of the audio buffer, in
287
- * samples. This number should be a power of two, and may be adjusted by
288
- * the audio driver to a value more suitable for the hardware. Good values
289
- * seem to range between 512 and 8096 inclusive, depending on the
290
- * application and CPU speed. Smaller values yield faster response time,
291
- * but can lead to underflow if the application is doing heavy processing
292
- * and cannot fill the audio buffer in time. A stereo sample consists of
293
- * both right and left channels in LR ordering.
294
- * Note that the number of samples is directly related to time by the
295
- * following formula: \code ms = (samples*1000)/freq \endcode
296
- * - \c desired->size is the size in bytes of the audio buffer, and is
297
- * calculated by SDL_OpenAudio().
298
- * - \c desired->silence is the value used to set the buffer to silence,
299
- * and is calculated by SDL_OpenAudio().
300
- * - \c desired->callback should be set to a function that will be called
301
- * when the audio device is ready for more data. It is passed a pointer
302
- * to the audio buffer, and the length in bytes of the audio buffer.
303
- * This function usually runs in a separate thread, and so you should
304
- * protect data structures that it accesses by calling SDL_LockAudio()
305
- * and SDL_UnlockAudio() in your code. Alternately, you may pass a NULL
306
- * pointer here, and call SDL_QueueAudio() with some frequency, to queue
307
- * more audio samples to be played (or for capture devices, call
308
- * SDL_DequeueAudio() with some frequency, to obtain audio samples).
309
- * - \c desired->userdata is passed as the first parameter to your callback
310
- * function. If you passed a NULL callback, this value is ignored.
311
- *
312
- * The audio device starts out playing silence when it's opened, and should
313
- * be enabled for playing by calling \c SDL_PauseAudio(0) when you are ready
314
- * for your audio callback function to be called. Since the audio driver
315
- * may modify the requested size of the audio buffer, you should allocate
316
- * any local mixing buffers after you open the audio device.
361
+ * This function is a legacy means of opening the audio device.
362
+ *
363
+ * This function remains for compatibility with SDL 1.2, but also because it's
364
+ * slightly easier to use than the new functions in SDL 2.0. The new, more
365
+ * powerful, and preferred way to do this is SDL_OpenAudioDevice().
366
+ *
367
+ * This function is roughly equivalent to:
368
+ *
369
+ * ```c
370
+ * SDL_OpenAudioDevice(NULL, 0, desired, obtained, SDL_AUDIO_ALLOW_ANY_CHANGE);
371
+ * ```
372
+ *
373
+ * With two notable exceptions:
374
+ *
375
+ * - If `obtained` is NULL, we use `desired` (and allow no changes), which
376
+ * means desired will be modified to have the correct values for silence,
377
+ * etc, and SDL will convert any differences between your app's specific
378
+ * request and the hardware behind the scenes.
379
+ * - The return value is always success or failure, and not a device ID, which
380
+ * means you can only have one device open at a time with this function.
381
+ *
382
+ * \param desired an SDL_AudioSpec structure representing the desired output
383
+ * format. Please refer to the SDL_OpenAudioDevice
384
+ * documentation for details on how to prepare this structure.
385
+ * \param obtained an SDL_AudioSpec structure filled in with the actual
386
+ * parameters, or NULL.
387
+ * \returns 0 if successful, placing the actual hardware parameters in the
388
+ * structure pointed to by `obtained`.
389
+ *
390
+ * If `obtained` is NULL, the audio data passed to the callback
391
+ * function will be guaranteed to be in the requested format, and
392
+ * will be automatically converted to the actual hardware audio
393
+ * format if necessary. If `obtained` is NULL, `desired` will have
394
+ * fields modified.
395
+ *
396
+ * This function returns a negative error code on failure to open the
397
+ * audio device or failure to set up the audio thread; call
398
+ * SDL_GetError() for more information.
399
+ *
400
+ * \since This function is available since SDL 2.0.0.
401
+ *
402
+ * \sa SDL_CloseAudio
403
+ * \sa SDL_LockAudio
404
+ * \sa SDL_PauseAudio
405
+ * \sa SDL_UnlockAudio
317
406
  */
318
407
  extern DECLSPEC int SDLCALL SDL_OpenAudio(SDL_AudioSpec * desired,
319
408
  SDL_AudioSpec * obtained);
@@ -330,59 +419,223 @@ extern DECLSPEC int SDLCALL SDL_OpenAudio(SDL_AudioSpec * desired,
330
419
  typedef Uint32 SDL_AudioDeviceID;
331
420
 
332
421
  /**
333
- * Get the number of available devices exposed by the current driver.
334
- * Only valid after a successfully initializing the audio subsystem.
335
- * Returns -1 if an explicit list of devices can't be determined; this is
336
- * not an error. For example, if SDL is set up to talk to a remote audio
337
- * server, it can't list every one available on the Internet, but it will
338
- * still allow a specific host to be specified to SDL_OpenAudioDevice().
422
+ * Get the number of built-in audio devices.
423
+ *
424
+ * This function is only valid after successfully initializing the audio
425
+ * subsystem.
426
+ *
427
+ * Note that audio capture support is not implemented as of SDL 2.0.4, so the
428
+ * `iscapture` parameter is for future expansion and should always be zero for
429
+ * now.
430
+ *
431
+ * This function will return -1 if an explicit list of devices can't be
432
+ * determined. Returning -1 is not an error. For example, if SDL is set up to
433
+ * talk to a remote audio server, it can't list every one available on the
434
+ * Internet, but it will still allow a specific host to be specified in
435
+ * SDL_OpenAudioDevice().
436
+ *
437
+ * In many common cases, when this function returns a value <= 0, it can still
438
+ * successfully open the default device (NULL for first argument of
439
+ * SDL_OpenAudioDevice()).
440
+ *
441
+ * This function may trigger a complete redetect of available hardware. It
442
+ * should not be called for each iteration of a loop, but rather once at the
443
+ * start of a loop:
444
+ *
445
+ * ```c
446
+ * // Don't do this:
447
+ * for (int i = 0; i < SDL_GetNumAudioDevices(0); i++)
448
+ *
449
+ * // do this instead:
450
+ * const int count = SDL_GetNumAudioDevices(0);
451
+ * for (int i = 0; i < count; ++i) { do_something_here(); }
452
+ * ```
453
+ *
454
+ * \param iscapture zero to request playback devices, non-zero to request
455
+ * recording devices
456
+ * \returns the number of available devices exposed by the current driver or
457
+ * -1 if an explicit list of devices can't be determined. A return
458
+ * value of -1 does not necessarily mean an error condition.
459
+ *
460
+ * \since This function is available since SDL 2.0.0.
339
461
  *
340
- * In many common cases, when this function returns a value <= 0, it can still
341
- * successfully open the default device (NULL for first argument of
342
- * SDL_OpenAudioDevice()).
462
+ * \sa SDL_GetAudioDeviceName
463
+ * \sa SDL_OpenAudioDevice
343
464
  */
344
465
  extern DECLSPEC int SDLCALL SDL_GetNumAudioDevices(int iscapture);
345
466
 
346
467
  /**
347
- * Get the human-readable name of a specific audio device.
348
- * Must be a value between 0 and (number of audio devices-1).
349
- * Only valid after a successfully initializing the audio subsystem.
350
- * The values returned by this function reflect the latest call to
351
- * SDL_GetNumAudioDevices(); recall that function to redetect available
352
- * hardware.
468
+ * Get the human-readable name of a specific audio device.
353
469
  *
354
- * The string returned by this function is UTF-8 encoded, read-only, and
355
- * managed internally. You are not to free it. If you need to keep the
356
- * string for any length of time, you should make your own copy of it, as it
357
- * will be invalid next time any of several other SDL functions is called.
470
+ * This function is only valid after successfully initializing the audio
471
+ * subsystem. The values returned by this function reflect the latest call to
472
+ * SDL_GetNumAudioDevices(); re-call that function to redetect available
473
+ * hardware.
474
+ *
475
+ * The string returned by this function is UTF-8 encoded, read-only, and
476
+ * managed internally. You are not to free it. If you need to keep the string
477
+ * for any length of time, you should make your own copy of it, as it will be
478
+ * invalid next time any of several other SDL functions are called.
479
+ *
480
+ * \param index the index of the audio device; valid values range from 0 to
481
+ * SDL_GetNumAudioDevices() - 1
482
+ * \param iscapture non-zero to query the list of recording devices, zero to
483
+ * query the list of output devices.
484
+ * \returns the name of the audio device at the requested index, or NULL on
485
+ * error.
486
+ *
487
+ * \since This function is available since SDL 2.0.0.
488
+ *
489
+ * \sa SDL_GetNumAudioDevices
358
490
  */
359
491
  extern DECLSPEC const char *SDLCALL SDL_GetAudioDeviceName(int index,
360
492
  int iscapture);
361
493
 
362
-
363
494
  /**
364
- * Open a specific audio device. Passing in a device name of NULL requests
365
- * the most reasonable default (and is equivalent to calling SDL_OpenAudio()).
495
+ * Get the preferred audio format of a specific audio device.
496
+ *
497
+ * This function is only valid after a successfully initializing the audio
498
+ * subsystem. The values returned by this function reflect the latest call to
499
+ * SDL_GetNumAudioDevices(); re-call that function to redetect available
500
+ * hardware.
366
501
  *
367
- * The device name is a UTF-8 string reported by SDL_GetAudioDeviceName(), but
368
- * some drivers allow arbitrary and driver-specific strings, such as a
369
- * hostname/IP address for a remote audio server, or a filename in the
370
- * diskaudio driver.
502
+ * `spec` will be filled with the sample rate, sample format, and channel
503
+ * count. All other values in the structure are filled with 0. When the
504
+ * supported struct members are 0, SDL was unable to get the property from the
505
+ * backend.
371
506
  *
372
- * \return 0 on error, a valid device ID that is >= 2 on success.
507
+ * \param index the index of the audio device; valid values range from 0 to
508
+ * SDL_GetNumAudioDevices() - 1
509
+ * \param iscapture non-zero to query the list of recording devices, zero to
510
+ * query the list of output devices.
511
+ * \param spec The SDL_AudioSpec to be initialized by this function.
512
+ * \returns 0 on success, nonzero on error
373
513
  *
374
- * SDL_OpenAudio(), unlike this function, always acts on device ID 1.
514
+ * \since This function is available since SDL 2.0.16.
515
+ *
516
+ * \sa SDL_GetNumAudioDevices
517
+ */
518
+ extern DECLSPEC int SDLCALL SDL_GetAudioDeviceSpec(int index,
519
+ int iscapture,
520
+ SDL_AudioSpec *spec);
521
+
522
+
523
+ /**
524
+ * Open a specific audio device.
525
+ *
526
+ * SDL_OpenAudio(), unlike this function, always acts on device ID 1. As such,
527
+ * this function will never return a 1 so as not to conflict with the legacy
528
+ * function.
529
+ *
530
+ * Please note that SDL 2.0 before 2.0.5 did not support recording; as such,
531
+ * this function would fail if `iscapture` was not zero. Starting with SDL
532
+ * 2.0.5, recording is implemented and this value can be non-zero.
533
+ *
534
+ * Passing in a `device` name of NULL requests the most reasonable default
535
+ * (and is equivalent to what SDL_OpenAudio() does to choose a device). The
536
+ * `device` name is a UTF-8 string reported by SDL_GetAudioDeviceName(), but
537
+ * some drivers allow arbitrary and driver-specific strings, such as a
538
+ * hostname/IP address for a remote audio server, or a filename in the
539
+ * diskaudio driver.
540
+ *
541
+ * An opened audio device starts out paused, and should be enabled for playing
542
+ * by calling SDL_PauseAudioDevice(devid, 0) when you are ready for your audio
543
+ * callback function to be called. Since the audio driver may modify the
544
+ * requested size of the audio buffer, you should allocate any local mixing
545
+ * buffers after you open the audio device.
546
+ *
547
+ * The audio callback runs in a separate thread in most cases; you can prevent
548
+ * race conditions between your callback and other threads without fully
549
+ * pausing playback with SDL_LockAudioDevice(). For more information about the
550
+ * callback, see SDL_AudioSpec.
551
+ *
552
+ * Managing the audio spec via 'desired' and 'obtained':
553
+ *
554
+ * When filling in the desired audio spec structure:
555
+ *
556
+ * - `desired->freq` should be the frequency in sample-frames-per-second (Hz).
557
+ * - `desired->format` should be the audio format (`AUDIO_S16SYS`, etc).
558
+ * - `desired->samples` is the desired size of the audio buffer, in _sample
559
+ * frames_ (with stereo output, two samples--left and right--would make a
560
+ * single sample frame). This number should be a power of two, and may be
561
+ * adjusted by the audio driver to a value more suitable for the hardware.
562
+ * Good values seem to range between 512 and 8096 inclusive, depending on
563
+ * the application and CPU speed. Smaller values reduce latency, but can
564
+ * lead to underflow if the application is doing heavy processing and cannot
565
+ * fill the audio buffer in time. Note that the number of sample frames is
566
+ * directly related to time by the following formula: `ms =
567
+ * (sampleframes*1000)/freq`
568
+ * - `desired->size` is the size in _bytes_ of the audio buffer, and is
569
+ * calculated by SDL_OpenAudioDevice(). You don't initialize this.
570
+ * - `desired->silence` is the value used to set the buffer to silence, and is
571
+ * calculated by SDL_OpenAudioDevice(). You don't initialize this.
572
+ * - `desired->callback` should be set to a function that will be called when
573
+ * the audio device is ready for more data. It is passed a pointer to the
574
+ * audio buffer, and the length in bytes of the audio buffer. This function
575
+ * usually runs in a separate thread, and so you should protect data
576
+ * structures that it accesses by calling SDL_LockAudioDevice() and
577
+ * SDL_UnlockAudioDevice() in your code. Alternately, you may pass a NULL
578
+ * pointer here, and call SDL_QueueAudio() with some frequency, to queue
579
+ * more audio samples to be played (or for capture devices, call
580
+ * SDL_DequeueAudio() with some frequency, to obtain audio samples).
581
+ * - `desired->userdata` is passed as the first parameter to your callback
582
+ * function. If you passed a NULL callback, this value is ignored.
583
+ *
584
+ * `allowed_changes` can have the following flags OR'd together:
585
+ *
586
+ * - `SDL_AUDIO_ALLOW_FREQUENCY_CHANGE`
587
+ * - `SDL_AUDIO_ALLOW_FORMAT_CHANGE`
588
+ * - `SDL_AUDIO_ALLOW_CHANNELS_CHANGE`
589
+ * - `SDL_AUDIO_ALLOW_ANY_CHANGE`
590
+ *
591
+ * These flags specify how SDL should behave when a device cannot offer a
592
+ * specific feature. If the application requests a feature that the hardware
593
+ * doesn't offer, SDL will always try to get the closest equivalent.
594
+ *
595
+ * For example, if you ask for float32 audio format, but the sound card only
596
+ * supports int16, SDL will set the hardware to int16. If you had set
597
+ * SDL_AUDIO_ALLOW_FORMAT_CHANGE, SDL will change the format in the `obtained`
598
+ * structure. If that flag was *not* set, SDL will prepare to convert your
599
+ * callback's float32 audio to int16 before feeding it to the hardware and
600
+ * will keep the originally requested format in the `obtained` structure.
601
+ *
602
+ * The resulting audio specs, varying depending on hardware and on what
603
+ * changes were allowed, will then be written back to `obtained`.
604
+ *
605
+ * If your application can only handle one specific data format, pass a zero
606
+ * for `allowed_changes` and let SDL transparently handle any differences.
607
+ *
608
+ * \param device a UTF-8 string reported by SDL_GetAudioDeviceName() or a
609
+ * driver-specific name as appropriate. NULL requests the most
610
+ * reasonable default device.
611
+ * \param iscapture non-zero to specify a device should be opened for
612
+ * recording, not playback
613
+ * \param desired an SDL_AudioSpec structure representing the desired output
614
+ * format; see SDL_OpenAudio() for more information
615
+ * \param obtained an SDL_AudioSpec structure filled in with the actual output
616
+ * format; see SDL_OpenAudio() for more information
617
+ * \param allowed_changes 0, or one or more flags OR'd together
618
+ * \returns a valid device ID that is > 0 on success or 0 on failure; call
619
+ * SDL_GetError() for more information.
620
+ *
621
+ * For compatibility with SDL 1.2, this will never return 1, since
622
+ * SDL reserves that ID for the legacy SDL_OpenAudio() function.
623
+ *
624
+ * \since This function is available since SDL 2.0.0.
625
+ *
626
+ * \sa SDL_CloseAudioDevice
627
+ * \sa SDL_GetAudioDeviceName
628
+ * \sa SDL_LockAudioDevice
629
+ * \sa SDL_OpenAudio
630
+ * \sa SDL_PauseAudioDevice
631
+ * \sa SDL_UnlockAudioDevice
375
632
  */
376
- extern DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(const char
377
- *device,
378
- int iscapture,
379
- const
380
- SDL_AudioSpec *
381
- desired,
382
- SDL_AudioSpec *
383
- obtained,
384
- int
385
- allowed_changes);
633
+ extern DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(
634
+ const char *device,
635
+ int iscapture,
636
+ const SDL_AudioSpec *desired,
637
+ SDL_AudioSpec *obtained,
638
+ int allowed_changes);
386
639
 
387
640
 
388
641
 
@@ -398,10 +651,39 @@ typedef enum
398
651
  SDL_AUDIO_PLAYING,
399
652
  SDL_AUDIO_PAUSED
400
653
  } SDL_AudioStatus;
654
+
655
+ /**
656
+ * This function is a legacy means of querying the audio device.
657
+ *
658
+ * New programs might want to use SDL_GetAudioDeviceStatus() instead. This
659
+ * function is equivalent to calling...
660
+ *
661
+ * ```c
662
+ * SDL_GetAudioDeviceStatus(1);
663
+ * ```
664
+ *
665
+ * ...and is only useful if you used the legacy SDL_OpenAudio() function.
666
+ *
667
+ * \returns the SDL_AudioStatus of the audio device opened by SDL_OpenAudio().
668
+ *
669
+ * \since This function is available since SDL 2.0.0.
670
+ *
671
+ * \sa SDL_GetAudioDeviceStatus
672
+ */
401
673
  extern DECLSPEC SDL_AudioStatus SDLCALL SDL_GetAudioStatus(void);
402
674
 
403
- extern DECLSPEC SDL_AudioStatus SDLCALL
404
- SDL_GetAudioDeviceStatus(SDL_AudioDeviceID dev);
675
+ /**
676
+ * Use this function to get the current audio state of an audio device.
677
+ *
678
+ * \param dev the ID of an audio device previously opened with
679
+ * SDL_OpenAudioDevice()
680
+ * \returns the SDL_AudioStatus of the specified audio device.
681
+ *
682
+ * \since This function is available since SDL 2.0.0.
683
+ *
684
+ * \sa SDL_PauseAudioDevice
685
+ */
686
+ extern DECLSPEC SDL_AudioStatus SDLCALL SDL_GetAudioDeviceStatus(SDL_AudioDeviceID dev);
405
687
  /* @} *//* Audio State */
406
688
 
407
689
  /**
@@ -414,62 +696,140 @@ SDL_GetAudioDeviceStatus(SDL_AudioDeviceID dev);
414
696
  * Silence will be written to the audio device during the pause.
415
697
  */
416
698
  /* @{ */
417
- extern DECLSPEC void SDLCALL SDL_PauseAudio(int pause_on);
418
- extern DECLSPEC void SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev,
419
- int pause_on);
420
- /* @} *//* Pause audio functions */
421
699
 
422
700
  /**
423
- * \brief Load the audio data of a WAVE file into memory
701
+ * This function is a legacy means of pausing the audio device.
424
702
  *
425
- * Loading a WAVE file requires \c src, \c spec, \c audio_buf and \c audio_len
426
- * to be valid pointers. The entire data portion of the file is then loaded
427
- * into memory and decoded if necessary.
703
+ * New programs might want to use SDL_PauseAudioDevice() instead. This
704
+ * function is equivalent to calling...
428
705
  *
429
- * If \c freesrc is non-zero, the data source gets automatically closed and
430
- * freed before the function returns.
706
+ * ```c
707
+ * SDL_PauseAudioDevice(1, pause_on);
708
+ * ```
431
709
  *
432
- * Supported are RIFF WAVE files with the formats PCM (8, 16, 24, and 32 bits),
433
- * IEEE Float (32 bits), Microsoft ADPCM and IMA ADPCM (4 bits), and A-law and
434
- * µ-law (8 bits). Other formats are currently unsupported and cause an error.
710
+ * ...and is only useful if you used the legacy SDL_OpenAudio() function.
435
711
  *
436
- * If this function succeeds, the pointer returned by it is equal to \c spec
437
- * and the pointer to the audio data allocated by the function is written to
438
- * \c audio_buf and its length in bytes to \c audio_len. The \ref SDL_AudioSpec
439
- * members \c freq, \c channels, and \c format are set to the values of the
440
- * audio data in the buffer. The \c samples member is set to a sane default and
441
- * all others are set to zero.
712
+ * \param pause_on non-zero to pause, 0 to unpause
442
713
  *
443
- * It's necessary to use SDL_FreeWAV() to free the audio data returned in
444
- * \c audio_buf when it is no longer used.
714
+ * \since This function is available since SDL 2.0.0.
445
715
  *
446
- * Because of the underspecification of the Waveform format, there are many
447
- * problematic files in the wild that cause issues with strict decoders. To
448
- * provide compatibility with these files, this decoder is lenient in regards
449
- * to the truncation of the file, the fact chunk, and the size of the RIFF
450
- * chunk. The hints SDL_HINT_WAVE_RIFF_CHUNK_SIZE, SDL_HINT_WAVE_TRUNCATION,
451
- * and SDL_HINT_WAVE_FACT_CHUNK can be used to tune the behavior of the
452
- * loading process.
716
+ * \sa SDL_GetAudioStatus
717
+ * \sa SDL_PauseAudioDevice
718
+ */
719
+ extern DECLSPEC void SDLCALL SDL_PauseAudio(int pause_on);
720
+
721
+ /**
722
+ * Use this function to pause and unpause audio playback on a specified
723
+ * device.
724
+ *
725
+ * This function pauses and unpauses the audio callback processing for a given
726
+ * device. Newly-opened audio devices start in the paused state, so you must
727
+ * call this function with **pause_on**=0 after opening the specified audio
728
+ * device to start playing sound. This allows you to safely initialize data
729
+ * for your callback function after opening the audio device. Silence will be
730
+ * written to the audio device while paused, and the audio callback is
731
+ * guaranteed to not be called. Pausing one device does not prevent other
732
+ * unpaused devices from running their callbacks.
733
+ *
734
+ * Pausing state does not stack; even if you pause a device several times, a
735
+ * single unpause will start the device playing again, and vice versa. This is
736
+ * different from how SDL_LockAudioDevice() works.
453
737
  *
454
- * Any file that is invalid (due to truncation, corruption, or wrong values in
455
- * the headers), too big, or unsupported causes an error. Additionally, any
456
- * critical I/O error from the data source will terminate the loading process
457
- * with an error. The function returns NULL on error and in all cases (with the
458
- * exception of \c src being NULL), an appropriate error message will be set.
738
+ * If you just need to protect a few variables from race conditions vs your
739
+ * callback, you shouldn't pause the audio device, as it will lead to dropouts
740
+ * in the audio playback. Instead, you should use SDL_LockAudioDevice().
459
741
  *
460
- * It is required that the data source supports seeking.
742
+ * \param dev a device opened by SDL_OpenAudioDevice()
743
+ * \param pause_on non-zero to pause, 0 to unpause
461
744
  *
462
- * Example:
463
- * \code
464
- * SDL_LoadWAV_RW(SDL_RWFromFile("sample.wav", "rb"), 1, ...);
465
- * \endcode
745
+ * \since This function is available since SDL 2.0.0.
466
746
  *
467
- * \param src The data source with the WAVE data
468
- * \param freesrc A integer value that makes the function close the data source if non-zero
469
- * \param spec A pointer filled with the audio format of the audio data
470
- * \param audio_buf A pointer filled with the audio data allocated by the function
471
- * \param audio_len A pointer filled with the length of the audio data buffer in bytes
472
- * \return NULL on error, or non-NULL on success.
747
+ * \sa SDL_LockAudioDevice
748
+ */
749
+ extern DECLSPEC void SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev,
750
+ int pause_on);
751
+ /* @} *//* Pause audio functions */
752
+
753
+ /**
754
+ * Load the audio data of a WAVE file into memory.
755
+ *
756
+ * Loading a WAVE file requires `src`, `spec`, `audio_buf` and `audio_len` to
757
+ * be valid pointers. The entire data portion of the file is then loaded into
758
+ * memory and decoded if necessary.
759
+ *
760
+ * If `freesrc` is non-zero, the data source gets automatically closed and
761
+ * freed before the function returns.
762
+ *
763
+ * Supported formats are RIFF WAVE files with the formats PCM (8, 16, 24, and
764
+ * 32 bits), IEEE Float (32 bits), Microsoft ADPCM and IMA ADPCM (4 bits), and
765
+ * A-law and mu-law (8 bits). Other formats are currently unsupported and
766
+ * cause an error.
767
+ *
768
+ * If this function succeeds, the pointer returned by it is equal to `spec`
769
+ * and the pointer to the audio data allocated by the function is written to
770
+ * `audio_buf` and its length in bytes to `audio_len`. The SDL_AudioSpec
771
+ * members `freq`, `channels`, and `format` are set to the values of the audio
772
+ * data in the buffer. The `samples` member is set to a sane default and all
773
+ * others are set to zero.
774
+ *
775
+ * It's necessary to use SDL_FreeWAV() to free the audio data returned in
776
+ * `audio_buf` when it is no longer used.
777
+ *
778
+ * Because of the underspecification of the .WAV format, there are many
779
+ * problematic files in the wild that cause issues with strict decoders. To
780
+ * provide compatibility with these files, this decoder is lenient in regards
781
+ * to the truncation of the file, the fact chunk, and the size of the RIFF
782
+ * chunk. The hints `SDL_HINT_WAVE_RIFF_CHUNK_SIZE`,
783
+ * `SDL_HINT_WAVE_TRUNCATION`, and `SDL_HINT_WAVE_FACT_CHUNK` can be used to
784
+ * tune the behavior of the loading process.
785
+ *
786
+ * Any file that is invalid (due to truncation, corruption, or wrong values in
787
+ * the headers), too big, or unsupported causes an error. Additionally, any
788
+ * critical I/O error from the data source will terminate the loading process
789
+ * with an error. The function returns NULL on error and in all cases (with
790
+ * the exception of `src` being NULL), an appropriate error message will be
791
+ * set.
792
+ *
793
+ * It is required that the data source supports seeking.
794
+ *
795
+ * Example:
796
+ *
797
+ * ```c
798
+ * SDL_LoadWAV_RW(SDL_RWFromFile("sample.wav", "rb"), 1, &spec, &buf, &len);
799
+ * ```
800
+ *
801
+ * Note that the SDL_LoadWAV macro does this same thing for you, but in a less
802
+ * messy way:
803
+ *
804
+ * ```c
805
+ * SDL_LoadWAV("sample.wav", &spec, &buf, &len);
806
+ * ```
807
+ *
808
+ * \param src The data source for the WAVE data
809
+ * \param freesrc If non-zero, SDL will _always_ free the data source
810
+ * \param spec An SDL_AudioSpec that will be filled in with the wave file's
811
+ * format details
812
+ * \param audio_buf A pointer filled with the audio data, allocated by the
813
+ * function.
814
+ * \param audio_len A pointer filled with the length of the audio data buffer
815
+ * in bytes
816
+ * \returns This function, if successfully called, returns `spec`, which will
817
+ * be filled with the audio data format of the wave source data.
818
+ * `audio_buf` will be filled with a pointer to an allocated buffer
819
+ * containing the audio data, and `audio_len` is filled with the
820
+ * length of that audio buffer in bytes.
821
+ *
822
+ * This function returns NULL if the .WAV file cannot be opened, uses
823
+ * an unknown data format, or is corrupt; call SDL_GetError() for
824
+ * more information.
825
+ *
826
+ * When the application is done with the data returned in
827
+ * `audio_buf`, it should call SDL_FreeWAV() to dispose of it.
828
+ *
829
+ * \since This function is available since SDL 2.0.0.
830
+ *
831
+ * \sa SDL_FreeWAV
832
+ * \sa SDL_LoadWAV
473
833
  */
474
834
  extern DECLSPEC SDL_AudioSpec *SDLCALL SDL_LoadWAV_RW(SDL_RWops * src,
475
835
  int freesrc,
@@ -485,18 +845,53 @@ extern DECLSPEC SDL_AudioSpec *SDLCALL SDL_LoadWAV_RW(SDL_RWops * src,
485
845
  SDL_LoadWAV_RW(SDL_RWFromFile(file, "rb"),1, spec,audio_buf,audio_len)
486
846
 
487
847
  /**
488
- * This function frees data previously allocated with SDL_LoadWAV_RW()
848
+ * Free data previously allocated with SDL_LoadWAV() or SDL_LoadWAV_RW().
849
+ *
850
+ * After a WAVE file has been opened with SDL_LoadWAV() or SDL_LoadWAV_RW()
851
+ * its data can eventually be freed with SDL_FreeWAV(). It is safe to call
852
+ * this function with a NULL pointer.
853
+ *
854
+ * \param audio_buf a pointer to the buffer created by SDL_LoadWAV() or
855
+ * SDL_LoadWAV_RW()
856
+ *
857
+ * \since This function is available since SDL 2.0.0.
858
+ *
859
+ * \sa SDL_LoadWAV
860
+ * \sa SDL_LoadWAV_RW
489
861
  */
490
862
  extern DECLSPEC void SDLCALL SDL_FreeWAV(Uint8 * audio_buf);
491
863
 
492
864
  /**
493
- * This function takes a source format and rate and a destination format
494
- * and rate, and initializes the \c cvt structure with information needed
495
- * by SDL_ConvertAudio() to convert a buffer of audio data from one format
496
- * to the other. An unsupported format causes an error and -1 will be returned.
497
- *
498
- * \return 0 if no conversion is needed, 1 if the audio filter is set up,
499
- * or -1 on error.
865
+ * Initialize an SDL_AudioCVT structure for conversion.
866
+ *
867
+ * Before an SDL_AudioCVT structure can be used to convert audio data it must
868
+ * be initialized with source and destination information.
869
+ *
870
+ * This function will zero out every field of the SDL_AudioCVT, so it must be
871
+ * called before the application fills in the final buffer information.
872
+ *
873
+ * Once this function has returned successfully, and reported that a
874
+ * conversion is necessary, the application fills in the rest of the fields in
875
+ * SDL_AudioCVT, now that it knows how large a buffer it needs to allocate,
876
+ * and then can call SDL_ConvertAudio() to complete the conversion.
877
+ *
878
+ * \param cvt an SDL_AudioCVT structure filled in with audio conversion
879
+ * information
880
+ * \param src_format the source format of the audio data; for more info see
881
+ * SDL_AudioFormat
882
+ * \param src_channels the number of channels in the source
883
+ * \param src_rate the frequency (sample-frames-per-second) of the source
884
+ * \param dst_format the destination format of the audio data; for more info
885
+ * see SDL_AudioFormat
886
+ * \param dst_channels the number of channels in the destination
887
+ * \param dst_rate the frequency (sample-frames-per-second) of the destination
888
+ * \returns 1 if the audio filter is prepared, 0 if no conversion is needed,
889
+ * or a negative error code on failure; call SDL_GetError() for more
890
+ * information.
891
+ *
892
+ * \since This function is available since SDL 2.0.0.
893
+ *
894
+ * \sa SDL_ConvertAudio
500
895
  */
501
896
  extern DECLSPEC int SDLCALL SDL_BuildAudioCVT(SDL_AudioCVT * cvt,
502
897
  SDL_AudioFormat src_format,
@@ -507,16 +902,42 @@ extern DECLSPEC int SDLCALL SDL_BuildAudioCVT(SDL_AudioCVT * cvt,
507
902
  int dst_rate);
508
903
 
509
904
  /**
510
- * Once you have initialized the \c cvt structure using SDL_BuildAudioCVT(),
511
- * created an audio buffer \c cvt->buf, and filled it with \c cvt->len bytes of
512
- * audio data in the source format, this function will convert it in-place
513
- * to the desired format.
514
- *
515
- * The data conversion may expand the size of the audio data, so the buffer
516
- * \c cvt->buf should be allocated after the \c cvt structure is initialized by
517
- * SDL_BuildAudioCVT(), and should be \c cvt->len*cvt->len_mult bytes long.
518
- *
519
- * \return 0 on success or -1 if \c cvt->buf is NULL.
905
+ * Convert audio data to a desired audio format.
906
+ *
907
+ * This function does the actual audio data conversion, after the application
908
+ * has called SDL_BuildAudioCVT() to prepare the conversion information and
909
+ * then filled in the buffer details.
910
+ *
911
+ * Once the application has initialized the `cvt` structure using
912
+ * SDL_BuildAudioCVT(), allocated an audio buffer and filled it with audio
913
+ * data in the source format, this function will convert the buffer, in-place,
914
+ * to the desired format.
915
+ *
916
+ * The data conversion may go through several passes; any given pass may
917
+ * possibly temporarily increase the size of the data. For example, SDL might
918
+ * expand 16-bit data to 32 bits before resampling to a lower frequency,
919
+ * shrinking the data size after having grown it briefly. Since the supplied
920
+ * buffer will be both the source and destination, converting as necessary
921
+ * in-place, the application must allocate a buffer that will fully contain
922
+ * the data during its largest conversion pass. After SDL_BuildAudioCVT()
923
+ * returns, the application should set the `cvt->len` field to the size, in
924
+ * bytes, of the source data, and allocate a buffer that is `cvt->len *
925
+ * cvt->len_mult` bytes long for the `buf` field.
926
+ *
927
+ * The source data should be copied into this buffer before the call to
928
+ * SDL_ConvertAudio(). Upon successful return, this buffer will contain the
929
+ * converted audio, and `cvt->len_cvt` will be the size of the converted data,
930
+ * in bytes. Any bytes in the buffer past `cvt->len_cvt` are undefined once
931
+ * this function returns.
932
+ *
933
+ * \param cvt an SDL_AudioCVT structure that was previously set up by
934
+ * SDL_BuildAudioCVT().
935
+ * \returns 0 if the conversion was completed successfully or a negative error
936
+ * code on failure; call SDL_GetError() for more information.
937
+ *
938
+ * \since This function is available since SDL 2.0.0.
939
+ *
940
+ * \sa SDL_BuildAudioCVT
520
941
  */
521
942
  extern DECLSPEC int SDLCALL SDL_ConvertAudio(SDL_AudioCVT * cvt);
522
943
 
@@ -532,22 +953,24 @@ struct _SDL_AudioStream;
532
953
  typedef struct _SDL_AudioStream SDL_AudioStream;
533
954
 
534
955
  /**
535
- * Create a new audio stream
536
- *
537
- * \param src_format The format of the source audio
538
- * \param src_channels The number of channels of the source audio
539
- * \param src_rate The sampling rate of the source audio
540
- * \param dst_format The format of the desired audio output
541
- * \param dst_channels The number of channels of the desired audio output
542
- * \param dst_rate The sampling rate of the desired audio output
543
- * \return 0 on success, or -1 on error.
544
- *
545
- * \sa SDL_AudioStreamPut
546
- * \sa SDL_AudioStreamGet
547
- * \sa SDL_AudioStreamAvailable
548
- * \sa SDL_AudioStreamFlush
549
- * \sa SDL_AudioStreamClear
550
- * \sa SDL_FreeAudioStream
956
+ * Create a new audio stream.
957
+ *
958
+ * \param src_format The format of the source audio
959
+ * \param src_channels The number of channels of the source audio
960
+ * \param src_rate The sampling rate of the source audio
961
+ * \param dst_format The format of the desired audio output
962
+ * \param dst_channels The number of channels of the desired audio output
963
+ * \param dst_rate The sampling rate of the desired audio output
964
+ * \returns 0 on success, or -1 on error.
965
+ *
966
+ * \since This function is available since SDL 2.0.7.
967
+ *
968
+ * \sa SDL_AudioStreamPut
969
+ * \sa SDL_AudioStreamGet
970
+ * \sa SDL_AudioStreamAvailable
971
+ * \sa SDL_AudioStreamFlush
972
+ * \sa SDL_AudioStreamClear
973
+ * \sa SDL_FreeAudioStream
551
974
  */
552
975
  extern DECLSPEC SDL_AudioStream * SDLCALL SDL_NewAudioStream(const SDL_AudioFormat src_format,
553
976
  const Uint8 src_channels,
@@ -557,110 +980,164 @@ extern DECLSPEC SDL_AudioStream * SDLCALL SDL_NewAudioStream(const SDL_AudioForm
557
980
  const int dst_rate);
558
981
 
559
982
  /**
560
- * Add data to be converted/resampled to the stream
983
+ * Add data to be converted/resampled to the stream.
984
+ *
985
+ * \param stream The stream the audio data is being added to
986
+ * \param buf A pointer to the audio data to add
987
+ * \param len The number of bytes to write to the stream
988
+ * \returns 0 on success, or -1 on error.
561
989
  *
562
- * \param stream The stream the audio data is being added to
563
- * \param buf A pointer to the audio data to add
564
- * \param len The number of bytes to write to the stream
565
- * \return 0 on success, or -1 on error.
990
+ * \since This function is available since SDL 2.0.7.
566
991
  *
567
- * \sa SDL_NewAudioStream
568
- * \sa SDL_AudioStreamGet
569
- * \sa SDL_AudioStreamAvailable
570
- * \sa SDL_AudioStreamFlush
571
- * \sa SDL_AudioStreamClear
572
- * \sa SDL_FreeAudioStream
992
+ * \sa SDL_NewAudioStream
993
+ * \sa SDL_AudioStreamGet
994
+ * \sa SDL_AudioStreamAvailable
995
+ * \sa SDL_AudioStreamFlush
996
+ * \sa SDL_AudioStreamClear
997
+ * \sa SDL_FreeAudioStream
573
998
  */
574
999
  extern DECLSPEC int SDLCALL SDL_AudioStreamPut(SDL_AudioStream *stream, const void *buf, int len);
575
1000
 
576
1001
  /**
577
- * Get converted/resampled data from the stream
1002
+ * Get converted/resampled data from the stream
578
1003
  *
579
- * \param stream The stream the audio is being requested from
580
- * \param buf A buffer to fill with audio data
581
- * \param len The maximum number of bytes to fill
582
- * \return The number of bytes read from the stream, or -1 on error
1004
+ * \param stream The stream the audio is being requested from
1005
+ * \param buf A buffer to fill with audio data
1006
+ * \param len The maximum number of bytes to fill
1007
+ * \returns the number of bytes read from the stream, or -1 on error
583
1008
  *
584
- * \sa SDL_NewAudioStream
585
- * \sa SDL_AudioStreamPut
586
- * \sa SDL_AudioStreamAvailable
587
- * \sa SDL_AudioStreamFlush
588
- * \sa SDL_AudioStreamClear
589
- * \sa SDL_FreeAudioStream
1009
+ * \since This function is available since SDL 2.0.7.
1010
+ *
1011
+ * \sa SDL_NewAudioStream
1012
+ * \sa SDL_AudioStreamPut
1013
+ * \sa SDL_AudioStreamAvailable
1014
+ * \sa SDL_AudioStreamFlush
1015
+ * \sa SDL_AudioStreamClear
1016
+ * \sa SDL_FreeAudioStream
590
1017
  */
591
1018
  extern DECLSPEC int SDLCALL SDL_AudioStreamGet(SDL_AudioStream *stream, void *buf, int len);
592
1019
 
593
1020
  /**
594
- * Get the number of converted/resampled bytes available. The stream may be
595
- * buffering data behind the scenes until it has enough to resample
596
- * correctly, so this number might be lower than what you expect, or even
597
- * be zero. Add more data or flush the stream if you need the data now.
1021
+ * Get the number of converted/resampled bytes available.
1022
+ *
1023
+ * The stream may be buffering data behind the scenes until it has enough to
1024
+ * resample correctly, so this number might be lower than what you expect, or
1025
+ * even be zero. Add more data or flush the stream if you need the data now.
598
1026
  *
599
- * \sa SDL_NewAudioStream
600
- * \sa SDL_AudioStreamPut
601
- * \sa SDL_AudioStreamGet
602
- * \sa SDL_AudioStreamFlush
603
- * \sa SDL_AudioStreamClear
604
- * \sa SDL_FreeAudioStream
1027
+ * \since This function is available since SDL 2.0.7.
1028
+ *
1029
+ * \sa SDL_NewAudioStream
1030
+ * \sa SDL_AudioStreamPut
1031
+ * \sa SDL_AudioStreamGet
1032
+ * \sa SDL_AudioStreamFlush
1033
+ * \sa SDL_AudioStreamClear
1034
+ * \sa SDL_FreeAudioStream
605
1035
  */
606
1036
  extern DECLSPEC int SDLCALL SDL_AudioStreamAvailable(SDL_AudioStream *stream);
607
1037
 
608
1038
  /**
609
1039
  * Tell the stream that you're done sending data, and anything being buffered
610
- * should be converted/resampled and made available immediately.
1040
+ * should be converted/resampled and made available immediately.
1041
+ *
1042
+ * It is legal to add more data to a stream after flushing, but there will be
1043
+ * audio gaps in the output. Generally this is intended to signal the end of
1044
+ * input, so the complete output becomes available.
611
1045
  *
612
- * It is legal to add more data to a stream after flushing, but there will
613
- * be audio gaps in the output. Generally this is intended to signal the
614
- * end of input, so the complete output becomes available.
1046
+ * \since This function is available since SDL 2.0.7.
615
1047
  *
616
- * \sa SDL_NewAudioStream
617
- * \sa SDL_AudioStreamPut
618
- * \sa SDL_AudioStreamGet
619
- * \sa SDL_AudioStreamAvailable
620
- * \sa SDL_AudioStreamClear
621
- * \sa SDL_FreeAudioStream
1048
+ * \sa SDL_NewAudioStream
1049
+ * \sa SDL_AudioStreamPut
1050
+ * \sa SDL_AudioStreamGet
1051
+ * \sa SDL_AudioStreamAvailable
1052
+ * \sa SDL_AudioStreamClear
1053
+ * \sa SDL_FreeAudioStream
622
1054
  */
623
1055
  extern DECLSPEC int SDLCALL SDL_AudioStreamFlush(SDL_AudioStream *stream);
624
1056
 
625
1057
  /**
626
- * Clear any pending data in the stream without converting it
1058
+ * Clear any pending data in the stream without converting it
1059
+ *
1060
+ * \since This function is available since SDL 2.0.7.
627
1061
  *
628
- * \sa SDL_NewAudioStream
629
- * \sa SDL_AudioStreamPut
630
- * \sa SDL_AudioStreamGet
631
- * \sa SDL_AudioStreamAvailable
632
- * \sa SDL_AudioStreamFlush
633
- * \sa SDL_FreeAudioStream
1062
+ * \sa SDL_NewAudioStream
1063
+ * \sa SDL_AudioStreamPut
1064
+ * \sa SDL_AudioStreamGet
1065
+ * \sa SDL_AudioStreamAvailable
1066
+ * \sa SDL_AudioStreamFlush
1067
+ * \sa SDL_FreeAudioStream
634
1068
  */
635
1069
  extern DECLSPEC void SDLCALL SDL_AudioStreamClear(SDL_AudioStream *stream);
636
1070
 
637
1071
  /**
638
1072
  * Free an audio stream
639
1073
  *
640
- * \sa SDL_NewAudioStream
641
- * \sa SDL_AudioStreamPut
642
- * \sa SDL_AudioStreamGet
643
- * \sa SDL_AudioStreamAvailable
644
- * \sa SDL_AudioStreamFlush
645
- * \sa SDL_AudioStreamClear
1074
+ * \since This function is available since SDL 2.0.7.
1075
+ *
1076
+ * \sa SDL_NewAudioStream
1077
+ * \sa SDL_AudioStreamPut
1078
+ * \sa SDL_AudioStreamGet
1079
+ * \sa SDL_AudioStreamAvailable
1080
+ * \sa SDL_AudioStreamFlush
1081
+ * \sa SDL_AudioStreamClear
646
1082
  */
647
1083
  extern DECLSPEC void SDLCALL SDL_FreeAudioStream(SDL_AudioStream *stream);
648
1084
 
649
1085
  #define SDL_MIX_MAXVOLUME 128
1086
+
650
1087
  /**
651
- * This takes two audio buffers of the playing audio format and mixes
652
- * them, performing addition, volume adjustment, and overflow clipping.
653
- * The volume ranges from 0 - 128, and should be set to ::SDL_MIX_MAXVOLUME
654
- * for full audio volume. Note this does not change hardware volume.
655
- * This is provided for convenience -- you can mix your own audio data.
1088
+ * This function is a legacy means of mixing audio.
1089
+ *
1090
+ * This function is equivalent to calling...
1091
+ *
1092
+ * ```c
1093
+ * SDL_MixAudioFormat(dst, src, format, len, volume);
1094
+ * ```
1095
+ *
1096
+ * ...where `format` is the obtained format of the audio device from the
1097
+ * legacy SDL_OpenAudio() function.
1098
+ *
1099
+ * \param dst the destination for the mixed audio
1100
+ * \param src the source audio buffer to be mixed
1101
+ * \param len the length of the audio buffer in bytes
1102
+ * \param volume ranges from 0 - 128, and should be set to SDL_MIX_MAXVOLUME
1103
+ * for full audio volume
1104
+ *
1105
+ * \since This function is available since SDL 2.0.0.
1106
+ *
1107
+ * \sa SDL_MixAudioFormat
656
1108
  */
657
1109
  extern DECLSPEC void SDLCALL SDL_MixAudio(Uint8 * dst, const Uint8 * src,
658
1110
  Uint32 len, int volume);
659
1111
 
660
1112
  /**
661
- * This works like SDL_MixAudio(), but you specify the audio format instead of
662
- * using the format of audio device 1. Thus it can be used when no audio
663
- * device is open at all.
1113
+ * Mix audio data in a specified format.
1114
+ *
1115
+ * This takes an audio buffer `src` of `len` bytes of `format` data and mixes
1116
+ * it into `dst`, performing addition, volume adjustment, and overflow
1117
+ * clipping. The buffer pointed to by `dst` must also be `len` bytes of
1118
+ * `format` data.
1119
+ *
1120
+ * This is provided for convenience -- you can mix your own audio data.
1121
+ *
1122
+ * Do not use this function for mixing together more than two streams of
1123
+ * sample data. The output from repeated application of this function may be
1124
+ * distorted by clipping, because there is no accumulator with greater range
1125
+ * than the input (not to mention this being an inefficient way of doing it).
1126
+ *
1127
+ * It is a common misconception that this function is required to write audio
1128
+ * data to an output stream in an audio callback. While you can do that,
1129
+ * SDL_MixAudioFormat() is really only needed when you're mixing a single
1130
+ * audio stream with a volume adjustment.
1131
+ *
1132
+ * \param dst the destination for the mixed audio
1133
+ * \param src the source audio buffer to be mixed
1134
+ * \param format the SDL_AudioFormat structure representing the desired audio
1135
+ * format
1136
+ * \param len the length of the audio buffer in bytes
1137
+ * \param volume ranges from 0 - 128, and should be set to SDL_MIX_MAXVOLUME
1138
+ * for full audio volume
1139
+ *
1140
+ * \since This function is available since SDL 2.0.0.
664
1141
  */
665
1142
  extern DECLSPEC void SDLCALL SDL_MixAudioFormat(Uint8 * dst,
666
1143
  const Uint8 * src,
@@ -668,184 +1145,312 @@ extern DECLSPEC void SDLCALL SDL_MixAudioFormat(Uint8 * dst,
668
1145
  Uint32 len, int volume);
669
1146
 
670
1147
  /**
671
- * Queue more audio on non-callback devices.
1148
+ * Queue more audio on non-callback devices.
1149
+ *
1150
+ * If you are looking to retrieve queued audio from a non-callback capture
1151
+ * device, you want SDL_DequeueAudio() instead. SDL_QueueAudio() will return
1152
+ * -1 to signify an error if you use it with capture devices.
1153
+ *
1154
+ * SDL offers two ways to feed audio to the device: you can either supply a
1155
+ * callback that SDL triggers with some frequency to obtain more audio (pull
1156
+ * method), or you can supply no callback, and then SDL will expect you to
1157
+ * supply data at regular intervals (push method) with this function.
1158
+ *
1159
+ * There are no limits on the amount of data you can queue, short of
1160
+ * exhaustion of address space. Queued data will drain to the device as
1161
+ * necessary without further intervention from you. If the device needs audio
1162
+ * but there is not enough queued, it will play silence to make up the
1163
+ * difference. This means you will have skips in your audio playback if you
1164
+ * aren't routinely queueing sufficient data.
1165
+ *
1166
+ * This function copies the supplied data, so you are safe to free it when the
1167
+ * function returns. This function is thread-safe, but queueing to the same
1168
+ * device from two threads at once does not promise which buffer will be
1169
+ * queued first.
1170
+ *
1171
+ * You may not queue audio on a device that is using an application-supplied
1172
+ * callback; doing so returns an error. You have to use the audio callback or
1173
+ * queue audio with this function, but not both.
1174
+ *
1175
+ * You should not call SDL_LockAudio() on the device before queueing; SDL
1176
+ * handles locking internally for this function.
1177
+ *
1178
+ * Note that SDL2 does not support planar audio. You will need to resample
1179
+ * from planar audio formats into a non-planar one (see SDL_AudioFormat)
1180
+ * before queuing audio.
1181
+ *
1182
+ * \param dev the device ID to which we will queue audio
1183
+ * \param data the data to queue to the device for later playback
1184
+ * \param len the number of bytes (not samples!) to which `data` points
1185
+ * \returns 0 on success or a negative error code on failure; call
1186
+ * SDL_GetError() for more information.
1187
+ *
1188
+ * \since This function is available since SDL 2.0.4.
1189
+ *
1190
+ * \sa SDL_ClearQueuedAudio
1191
+ * \sa SDL_GetQueuedAudioSize
1192
+ */
1193
+ extern DECLSPEC int SDLCALL SDL_QueueAudio(SDL_AudioDeviceID dev, const void *data, Uint32 len);
1194
+
1195
+ /**
1196
+ * Dequeue more audio on non-callback devices.
1197
+ *
1198
+ * If you are looking to queue audio for output on a non-callback playback
1199
+ * device, you want SDL_QueueAudio() instead. SDL_DequeueAudio() will always
1200
+ * return 0 if you use it with playback devices.
1201
+ *
1202
+ * SDL offers two ways to retrieve audio from a capture device: you can either
1203
+ * supply a callback that SDL triggers with some frequency as the device
1204
+ * records more audio data, (push method), or you can supply no callback, and
1205
+ * then SDL will expect you to retrieve data at regular intervals (pull
1206
+ * method) with this function.
1207
+ *
1208
+ * There are no limits on the amount of data you can queue, short of
1209
+ * exhaustion of address space. Data from the device will keep queuing as
1210
+ * necessary without further intervention from you. This means you will
1211
+ * eventually run out of memory if you aren't routinely dequeueing data.
1212
+ *
1213
+ * Capture devices will not queue data when paused; if you are expecting to
1214
+ * not need captured audio for some length of time, use SDL_PauseAudioDevice()
1215
+ * to stop the capture device from queueing more data. This can be useful
1216
+ * during, say, level loading times. When unpaused, capture devices will start
1217
+ * queueing data from that point, having flushed any capturable data available
1218
+ * while paused.
1219
+ *
1220
+ * This function is thread-safe, but dequeueing from the same device from two
1221
+ * threads at once does not promise which thread will dequeue data first.
1222
+ *
1223
+ * You may not dequeue audio from a device that is using an
1224
+ * application-supplied callback; doing so returns an error. You have to use
1225
+ * the audio callback, or dequeue audio with this function, but not both.
1226
+ *
1227
+ * You should not call SDL_LockAudio() on the device before dequeueing; SDL
1228
+ * handles locking internally for this function.
1229
+ *
1230
+ * \param dev the device ID from which we will dequeue audio
1231
+ * \param data a pointer into where audio data should be copied
1232
+ * \param len the number of bytes (not samples!) to which (data) points
1233
+ * \returns the number of bytes dequeued, which could be less than requested;
1234
+ * call SDL_GetError() for more information.
1235
+ *
1236
+ * \since This function is available since SDL 2.0.5.
1237
+ *
1238
+ * \sa SDL_ClearQueuedAudio
1239
+ * \sa SDL_GetQueuedAudioSize
1240
+ */
1241
+ extern DECLSPEC Uint32 SDLCALL SDL_DequeueAudio(SDL_AudioDeviceID dev, void *data, Uint32 len);
1242
+
1243
+ /**
1244
+ * Get the number of bytes of still-queued audio.
672
1245
  *
673
- * (If you are looking to retrieve queued audio from a non-callback capture
674
- * device, you want SDL_DequeueAudio() instead. This will return -1 to
675
- * signify an error if you use it with capture devices.)
1246
+ * For playback devices: this is the number of bytes that have been queued for
1247
+ * playback with SDL_QueueAudio(), but have not yet been sent to the hardware.
676
1248
  *
677
- * SDL offers two ways to feed audio to the device: you can either supply a
678
- * callback that SDL triggers with some frequency to obtain more audio
679
- * (pull method), or you can supply no callback, and then SDL will expect
680
- * you to supply data at regular intervals (push method) with this function.
1249
+ * Once we've sent it to the hardware, this function can not decide the exact
1250
+ * byte boundary of what has been played. It's possible that we just gave the
1251
+ * hardware several kilobytes right before you called this function, but it
1252
+ * hasn't played any of it yet, or maybe half of it, etc.
681
1253
  *
682
- * There are no limits on the amount of data you can queue, short of
683
- * exhaustion of address space. Queued data will drain to the device as
684
- * necessary without further intervention from you. If the device needs
685
- * audio but there is not enough queued, it will play silence to make up
686
- * the difference. This means you will have skips in your audio playback
687
- * if you aren't routinely queueing sufficient data.
1254
+ * For capture devices, this is the number of bytes that have been captured by
1255
+ * the device and are waiting for you to dequeue. This number may grow at any
1256
+ * time, so this only informs of the lower-bound of available data.
688
1257
  *
689
- * This function copies the supplied data, so you are safe to free it when
690
- * the function returns. This function is thread-safe, but queueing to the
691
- * same device from two threads at once does not promise which buffer will
692
- * be queued first.
1258
+ * You may not queue or dequeue audio on a device that is using an
1259
+ * application-supplied callback; calling this function on such a device
1260
+ * always returns 0. You have to use the audio callback or queue audio, but
1261
+ * not both.
693
1262
  *
694
- * You may not queue audio on a device that is using an application-supplied
695
- * callback; doing so returns an error. You have to use the audio callback
696
- * or queue audio with this function, but not both.
1263
+ * You should not call SDL_LockAudio() on the device before querying; SDL
1264
+ * handles locking internally for this function.
697
1265
  *
698
- * You should not call SDL_LockAudio() on the device before queueing; SDL
699
- * handles locking internally for this function.
1266
+ * \param dev the device ID of which we will query queued audio size
1267
+ * \returns the number of bytes (not samples!) of queued audio.
700
1268
  *
701
- * \param dev The device ID to which we will queue audio.
702
- * \param data The data to queue to the device for later playback.
703
- * \param len The number of bytes (not samples!) to which (data) points.
704
- * \return 0 on success, or -1 on error.
1269
+ * \since This function is available since SDL 2.0.4.
705
1270
  *
706
- * \sa SDL_GetQueuedAudioSize
707
- * \sa SDL_ClearQueuedAudio
1271
+ * \sa SDL_ClearQueuedAudio
1272
+ * \sa SDL_QueueAudio
1273
+ * \sa SDL_DequeueAudio
708
1274
  */
709
- extern DECLSPEC int SDLCALL SDL_QueueAudio(SDL_AudioDeviceID dev, const void *data, Uint32 len);
1275
+ extern DECLSPEC Uint32 SDLCALL SDL_GetQueuedAudioSize(SDL_AudioDeviceID dev);
710
1276
 
711
1277
  /**
712
- * Dequeue more audio on non-callback devices.
1278
+ * Drop any queued audio data waiting to be sent to the hardware.
713
1279
  *
714
- * (If you are looking to queue audio for output on a non-callback playback
715
- * device, you want SDL_QueueAudio() instead. This will always return 0
716
- * if you use it with playback devices.)
1280
+ * Immediately after this call, SDL_GetQueuedAudioSize() will return 0. For
1281
+ * output devices, the hardware will start playing silence if more audio isn't
1282
+ * queued. For capture devices, the hardware will start filling the empty
1283
+ * queue with new data if the capture device isn't paused.
717
1284
  *
718
- * SDL offers two ways to retrieve audio from a capture device: you can
719
- * either supply a callback that SDL triggers with some frequency as the
720
- * device records more audio data, (push method), or you can supply no
721
- * callback, and then SDL will expect you to retrieve data at regular
722
- * intervals (pull method) with this function.
1285
+ * This will not prevent playback of queued audio that's already been sent to
1286
+ * the hardware, as we can not undo that, so expect there to be some fraction
1287
+ * of a second of audio that might still be heard. This can be useful if you
1288
+ * want to, say, drop any pending music or any unprocessed microphone input
1289
+ * during a level change in your game.
723
1290
  *
724
- * There are no limits on the amount of data you can queue, short of
725
- * exhaustion of address space. Data from the device will keep queuing as
726
- * necessary without further intervention from you. This means you will
727
- * eventually run out of memory if you aren't routinely dequeueing data.
1291
+ * You may not queue or dequeue audio on a device that is using an
1292
+ * application-supplied callback; calling this function on such a device
1293
+ * always returns 0. You have to use the audio callback or queue audio, but
1294
+ * not both.
728
1295
  *
729
- * Capture devices will not queue data when paused; if you are expecting
730
- * to not need captured audio for some length of time, use
731
- * SDL_PauseAudioDevice() to stop the capture device from queueing more
732
- * data. This can be useful during, say, level loading times. When
733
- * unpaused, capture devices will start queueing data from that point,
734
- * having flushed any capturable data available while paused.
1296
+ * You should not call SDL_LockAudio() on the device before clearing the
1297
+ * queue; SDL handles locking internally for this function.
735
1298
  *
736
- * This function is thread-safe, but dequeueing from the same device from
737
- * two threads at once does not promise which thread will dequeued data
738
- * first.
1299
+ * This function always succeeds and thus returns void.
739
1300
  *
740
- * You may not dequeue audio from a device that is using an
741
- * application-supplied callback; doing so returns an error. You have to use
742
- * the audio callback, or dequeue audio with this function, but not both.
1301
+ * \param dev the device ID of which to clear the audio queue
743
1302
  *
744
- * You should not call SDL_LockAudio() on the device before queueing; SDL
745
- * handles locking internally for this function.
1303
+ * \since This function is available since SDL 2.0.4.
746
1304
  *
747
- * \param dev The device ID from which we will dequeue audio.
748
- * \param data A pointer into where audio data should be copied.
749
- * \param len The number of bytes (not samples!) to which (data) points.
750
- * \return number of bytes dequeued, which could be less than requested.
1305
+ * \sa SDL_GetQueuedAudioSize
1306
+ * \sa SDL_QueueAudio
1307
+ * \sa SDL_DequeueAudio
1308
+ */
1309
+ extern DECLSPEC void SDLCALL SDL_ClearQueuedAudio(SDL_AudioDeviceID dev);
1310
+
1311
+
1312
+ /**
1313
+ * \name Audio lock functions
751
1314
  *
752
- * \sa SDL_GetQueuedAudioSize
753
- * \sa SDL_ClearQueuedAudio
1315
+ * The lock manipulated by these functions protects the callback function.
1316
+ * During a SDL_LockAudio()/SDL_UnlockAudio() pair, you can be guaranteed that
1317
+ * the callback function is not running. Do not call these from the callback
1318
+ * function or you will cause deadlock.
754
1319
  */
755
- extern DECLSPEC Uint32 SDLCALL SDL_DequeueAudio(SDL_AudioDeviceID dev, void *data, Uint32 len);
1320
+ /* @{ */
756
1321
 
757
1322
  /**
758
- * Get the number of bytes of still-queued audio.
1323
+ * This function is a legacy means of locking the audio device.
1324
+ *
1325
+ * New programs might want to use SDL_LockAudioDevice() instead. This function
1326
+ * is equivalent to calling...
759
1327
  *
760
- * For playback device:
1328
+ * ```c
1329
+ * SDL_LockAudioDevice(1);
1330
+ * ```
761
1331
  *
762
- * This is the number of bytes that have been queued for playback with
763
- * SDL_QueueAudio(), but have not yet been sent to the hardware. This
764
- * number may shrink at any time, so this only informs of pending data.
1332
+ * ...and is only useful if you used the legacy SDL_OpenAudio() function.
765
1333
  *
766
- * Once we've sent it to the hardware, this function can not decide the
767
- * exact byte boundary of what has been played. It's possible that we just
768
- * gave the hardware several kilobytes right before you called this
769
- * function, but it hasn't played any of it yet, or maybe half of it, etc.
1334
+ * \since This function is available since SDL 2.0.0.
770
1335
  *
771
- * For capture devices:
1336
+ * \sa SDL_LockAudioDevice
1337
+ * \sa SDL_UnlockAudio
1338
+ * \sa SDL_UnlockAudioDevice
1339
+ */
1340
+ extern DECLSPEC void SDLCALL SDL_LockAudio(void);
1341
+
1342
+ /**
1343
+ * Use this function to lock out the audio callback function for a specified
1344
+ * device.
772
1345
  *
773
- * This is the number of bytes that have been captured by the device and
774
- * are waiting for you to dequeue. This number may grow at any time, so
775
- * this only informs of the lower-bound of available data.
1346
+ * The lock manipulated by these functions protects the audio callback
1347
+ * function specified in SDL_OpenAudioDevice(). During a
1348
+ * SDL_LockAudioDevice()/SDL_UnlockAudioDevice() pair, you can be guaranteed
1349
+ * that the callback function for that device is not running, even if the
1350
+ * device is not paused. While a device is locked, any other unpaused,
1351
+ * unlocked devices may still run their callbacks.
776
1352
  *
777
- * You may not queue audio on a device that is using an application-supplied
778
- * callback; calling this function on such a device always returns 0.
779
- * You have to queue audio with SDL_QueueAudio()/SDL_DequeueAudio(), or use
780
- * the audio callback, but not both.
1353
+ * Calling this function from inside your audio callback is unnecessary. SDL
1354
+ * obtains this lock before calling your function, and releases it when the
1355
+ * function returns.
781
1356
  *
782
- * You should not call SDL_LockAudio() on the device before querying; SDL
783
- * handles locking internally for this function.
1357
+ * You should not hold the lock longer than absolutely necessary. If you hold
1358
+ * it too long, you'll experience dropouts in your audio playback. Ideally,
1359
+ * your application locks the device, sets a few variables and unlocks again.
1360
+ * Do not do heavy work while holding the lock for a device.
784
1361
  *
785
- * \param dev The device ID of which we will query queued audio size.
786
- * \return Number of bytes (not samples!) of queued audio.
1362
+ * It is safe to lock the audio device multiple times, as long as you unlock
1363
+ * it an equivalent number of times. The callback will not run until the
1364
+ * device has been unlocked completely in this way. If your application fails
1365
+ * to unlock the device appropriately, your callback will never run, you might
1366
+ * hear repeating bursts of audio, and SDL_CloseAudioDevice() will probably
1367
+ * deadlock.
787
1368
  *
788
- * \sa SDL_QueueAudio
789
- * \sa SDL_ClearQueuedAudio
1369
+ * Internally, the audio device lock is a mutex; if you lock from two threads
1370
+ * at once, not only will you block the audio callback, you'll block the other
1371
+ * thread.
1372
+ *
1373
+ * \param dev the ID of the device to be locked
1374
+ *
1375
+ * \since This function is available since SDL 2.0.0.
1376
+ *
1377
+ * \sa SDL_UnlockAudioDevice
790
1378
  */
791
- extern DECLSPEC Uint32 SDLCALL SDL_GetQueuedAudioSize(SDL_AudioDeviceID dev);
1379
+ extern DECLSPEC void SDLCALL SDL_LockAudioDevice(SDL_AudioDeviceID dev);
792
1380
 
793
1381
  /**
794
- * Drop any queued audio data. For playback devices, this is any queued data
795
- * still waiting to be submitted to the hardware. For capture devices, this
796
- * is any data that was queued by the device that hasn't yet been dequeued by
797
- * the application.
1382
+ * This function is a legacy means of unlocking the audio device.
798
1383
  *
799
- * Immediately after this call, SDL_GetQueuedAudioSize() will return 0. For
800
- * playback devices, the hardware will start playing silence if more audio
801
- * isn't queued. Unpaused capture devices will start filling the queue again
802
- * as soon as they have more data available (which, depending on the state
803
- * of the hardware and the thread, could be before this function call
804
- * returns!).
1384
+ * New programs might want to use SDL_UnlockAudioDevice() instead. This
1385
+ * function is equivalent to calling...
805
1386
  *
806
- * This will not prevent playback of queued audio that's already been sent
807
- * to the hardware, as we can not undo that, so expect there to be some
808
- * fraction of a second of audio that might still be heard. This can be
809
- * useful if you want to, say, drop any pending music during a level change
810
- * in your game.
1387
+ * ```c
1388
+ * SDL_UnlockAudioDevice(1);
1389
+ * ```
811
1390
  *
812
- * You may not queue audio on a device that is using an application-supplied
813
- * callback; calling this function on such a device is always a no-op.
814
- * You have to queue audio with SDL_QueueAudio()/SDL_DequeueAudio(), or use
815
- * the audio callback, but not both.
1391
+ * ...and is only useful if you used the legacy SDL_OpenAudio() function.
816
1392
  *
817
- * You should not call SDL_LockAudio() on the device before clearing the
818
- * queue; SDL handles locking internally for this function.
1393
+ * \since This function is available since SDL 2.0.0.
819
1394
  *
820
- * This function always succeeds and thus returns void.
821
- *
822
- * \param dev The device ID of which to clear the audio queue.
823
- *
824
- * \sa SDL_QueueAudio
825
- * \sa SDL_GetQueuedAudioSize
1395
+ * \sa SDL_LockAudio
1396
+ * \sa SDL_UnlockAudioDevice
826
1397
  */
827
- extern DECLSPEC void SDLCALL SDL_ClearQueuedAudio(SDL_AudioDeviceID dev);
828
-
1398
+ extern DECLSPEC void SDLCALL SDL_UnlockAudio(void);
829
1399
 
830
1400
  /**
831
- * \name Audio lock functions
1401
+ * Use this function to unlock the audio callback function for a specified
1402
+ * device.
832
1403
  *
833
- * The lock manipulated by these functions protects the callback function.
834
- * During a SDL_LockAudio()/SDL_UnlockAudio() pair, you can be guaranteed that
835
- * the callback function is not running. Do not call these from the callback
836
- * function or you will cause deadlock.
1404
+ * This function should be paired with a previous SDL_LockAudioDevice() call.
1405
+ *
1406
+ * \param dev the ID of the device to be unlocked
1407
+ *
1408
+ * \since This function is available since SDL 2.0.0.
1409
+ *
1410
+ * \sa SDL_LockAudioDevice
837
1411
  */
838
- /* @{ */
839
- extern DECLSPEC void SDLCALL SDL_LockAudio(void);
840
- extern DECLSPEC void SDLCALL SDL_LockAudioDevice(SDL_AudioDeviceID dev);
841
- extern DECLSPEC void SDLCALL SDL_UnlockAudio(void);
842
1412
  extern DECLSPEC void SDLCALL SDL_UnlockAudioDevice(SDL_AudioDeviceID dev);
843
1413
  /* @} *//* Audio lock functions */
844
1414
 
845
1415
  /**
846
- * This function shuts down audio processing and closes the audio device.
1416
+ * This function is a legacy means of closing the audio device.
1417
+ *
1418
+ * This function is equivalent to calling...
1419
+ *
1420
+ * ```c
1421
+ * SDL_CloseAudioDevice(1);
1422
+ * ```
1423
+ *
1424
+ * ...and is only useful if you used the legacy SDL_OpenAudio() function.
1425
+ *
1426
+ * \since This function is available since SDL 2.0.0.
1427
+ *
1428
+ * \sa SDL_OpenAudio
847
1429
  */
848
1430
  extern DECLSPEC void SDLCALL SDL_CloseAudio(void);
1431
+
1432
+ /**
1433
+ * Use this function to shut down audio processing and close the audio device.
1434
+ *
1435
+ * The application should close open audio devices once they are no longer
1436
+ * needed. Calling this function will wait until the device's audio callback
1437
+ * is not running, release the audio hardware and then clean up internal
1438
+ * state. No further audio will play from this device once this function
1439
+ * returns.
1440
+ *
1441
+ * This function may block briefly while pending audio data is played by the
1442
+ * hardware, so that applications don't drop the last buffer of data they
1443
+ * supplied.
1444
+ *
1445
+ * The device ID is invalid as soon as the device is closed, and is eligible
1446
+ * for reuse in a new SDL_OpenAudioDevice() call immediately.
1447
+ *
1448
+ * \param dev an audio device previously opened with SDL_OpenAudioDevice()
1449
+ *
1450
+ * \since This function is available since SDL 2.0.0.
1451
+ *
1452
+ * \sa SDL_OpenAudioDevice
1453
+ */
849
1454
  extern DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID dev);
850
1455
 
851
1456
  /* Ends C function definitions when using C++ */