ruby2d 0.11.3 → 0.12.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (221) hide show
  1. checksums.yaml +4 -4
  2. data/assets/include/GLES2/gl2.h +656 -0
  3. data/assets/include/GLES2/gl2ext.h +3949 -0
  4. data/assets/include/GLES2/gl2ext_angle.h +701 -0
  5. data/assets/include/GLES2/gl2platform.h +27 -0
  6. data/assets/include/GLES3/gl3.h +1192 -0
  7. data/assets/include/GLES3/gl31.h +1507 -0
  8. data/assets/include/GLES3/gl32.h +1808 -0
  9. data/assets/include/GLES3/gl3platform.h +27 -0
  10. data/assets/include/KHR/khrplatform.h +290 -0
  11. data/assets/include/SDL2/SDL.h +1 -0
  12. data/assets/include/SDL2/SDL_assert.h +4 -2
  13. data/assets/include/SDL2/SDL_atomic.h +20 -0
  14. data/assets/include/SDL2/SDL_audio.h +40 -4
  15. data/assets/include/SDL2/SDL_blendmode.h +4 -6
  16. data/assets/include/SDL2/SDL_clipboard.h +47 -0
  17. data/assets/include/SDL2/SDL_config.h +6 -2
  18. data/assets/include/SDL2/SDL_config_android.h +2 -0
  19. data/assets/include/SDL2/SDL_config_emscripten.h +2 -0
  20. data/assets/include/SDL2/SDL_config_iphoneos.h +3 -1
  21. data/assets/include/SDL2/SDL_config_macosx.h +3 -6
  22. data/assets/include/SDL2/SDL_config_minimal.h +18 -11
  23. data/assets/include/SDL2/SDL_config_ngage.h +89 -0
  24. data/assets/include/SDL2/SDL_config_os2.h +5 -3
  25. data/assets/include/SDL2/SDL_config_pandora.h +1 -0
  26. data/assets/include/SDL2/SDL_config_windows.h +71 -45
  27. data/assets/include/SDL2/SDL_config_wingdk.h +253 -0
  28. data/assets/include/SDL2/SDL_config_winrt.h +11 -49
  29. data/assets/include/SDL2/SDL_config_xbox.h +235 -0
  30. data/assets/include/SDL2/SDL_cpuinfo.h +39 -4
  31. data/assets/include/SDL2/SDL_egl.h +59 -9
  32. data/assets/include/SDL2/SDL_endian.h +34 -3
  33. data/assets/include/SDL2/SDL_events.h +32 -1
  34. data/assets/include/SDL2/SDL_filesystem.h +5 -1
  35. data/assets/include/SDL2/SDL_gamecontroller.h +78 -5
  36. data/assets/include/SDL2/SDL_guid.h +100 -0
  37. data/assets/include/SDL2/SDL_hints.h +645 -43
  38. data/assets/include/SDL2/SDL_image.h +2045 -33
  39. data/assets/include/SDL2/SDL_joystick.h +127 -7
  40. data/assets/include/SDL2/SDL_keyboard.h +38 -1
  41. data/assets/include/SDL2/SDL_keycode.h +6 -1
  42. data/assets/include/SDL2/SDL_log.h +2 -2
  43. data/assets/include/SDL2/SDL_main.h +42 -2
  44. data/assets/include/SDL2/SDL_metal.h +2 -1
  45. data/assets/include/SDL2/SDL_mixer.h +2529 -396
  46. data/assets/include/SDL2/SDL_mouse.h +12 -1
  47. data/assets/include/SDL2/SDL_opengl.h +0 -51
  48. data/assets/include/SDL2/SDL_opengl_glext.h +2260 -231
  49. data/assets/include/SDL2/SDL_opengles2_gl2.h +374 -339
  50. data/assets/include/SDL2/SDL_opengles2_gl2ext.h +3479 -1496
  51. data/assets/include/SDL2/SDL_opengles2_gl2platform.h +6 -9
  52. data/assets/include/SDL2/SDL_opengles2_khrplatform.h +43 -14
  53. data/assets/include/SDL2/SDL_platform.h +32 -6
  54. data/assets/include/SDL2/SDL_rect.h +154 -2
  55. data/assets/include/SDL2/SDL_render.h +46 -17
  56. data/assets/include/SDL2/SDL_revision.h +4 -0
  57. data/assets/include/SDL2/SDL_rwops.h +1 -15
  58. data/assets/include/SDL2/SDL_scancode.h +46 -21
  59. data/assets/include/SDL2/SDL_sensor.h +24 -3
  60. data/assets/include/SDL2/SDL_stdinc.h +119 -8
  61. data/assets/include/SDL2/SDL_surface.h +3 -1
  62. data/assets/include/SDL2/SDL_system.h +66 -6
  63. data/assets/include/SDL2/SDL_syswm.h +2 -0
  64. data/assets/include/SDL2/SDL_test_common.h +1 -0
  65. data/assets/include/SDL2/SDL_test_font.h +90 -3
  66. data/assets/include/SDL2/SDL_thread.h +3 -3
  67. data/assets/include/SDL2/SDL_touch.h +8 -0
  68. data/assets/include/SDL2/SDL_ttf.h +2084 -155
  69. data/assets/include/SDL2/SDL_version.h +19 -3
  70. data/assets/include/SDL2/SDL_video.h +71 -9
  71. data/assets/include/SDL2/begin_code.h +4 -4
  72. data/assets/include/mrbconf.h +15 -17
  73. data/assets/include/mruby/array.h +8 -21
  74. data/assets/include/mruby/boxing_nan.h +115 -86
  75. data/assets/include/mruby/boxing_word.h +104 -78
  76. data/assets/include/mruby/common.h +6 -0
  77. data/assets/include/mruby/compile.h +3 -4
  78. data/assets/include/mruby/debug.h +4 -2
  79. data/assets/include/mruby/dump.h +5 -2
  80. data/assets/include/mruby/error.h +12 -2
  81. data/assets/include/mruby/gc.h +2 -0
  82. data/assets/include/mruby/hash.h +1 -3
  83. data/assets/include/mruby/irep.h +4 -4
  84. data/assets/include/mruby/numeric.h +21 -13
  85. data/assets/include/mruby/opcode.h +30 -0
  86. data/assets/include/mruby/ops.h +99 -101
  87. data/assets/include/mruby/presym/scanning.h +15 -9
  88. data/assets/include/mruby/proc.h +4 -2
  89. data/assets/include/mruby/string.h +3 -24
  90. data/assets/include/mruby/value.h +80 -40
  91. data/assets/include/mruby/variable.h +0 -15
  92. data/assets/include/mruby/version.h +5 -5
  93. data/assets/include/mruby.h +86 -16
  94. data/assets/macos/universal/bin/mrbc +0 -0
  95. data/assets/macos/universal/lib/libFLAC.a +0 -0
  96. data/assets/macos/universal/lib/libSDL2.a +0 -0
  97. data/assets/macos/universal/lib/libSDL2_image.a +0 -0
  98. data/assets/macos/universal/lib/libSDL2_mixer.a +0 -0
  99. data/assets/macos/universal/lib/libSDL2_ttf.a +0 -0
  100. data/assets/macos/universal/lib/libavif.a +0 -0
  101. data/assets/macos/universal/lib/libbrotlicommon-static.a +0 -0
  102. data/assets/macos/universal/lib/libbrotlidec-static.a +0 -0
  103. data/assets/macos/universal/lib/libfreetype.a +0 -0
  104. data/assets/macos/universal/lib/libgraphite2.a +0 -0
  105. data/assets/macos/universal/lib/libharfbuzz.a +0 -0
  106. data/assets/macos/universal/lib/libhwy.a +0 -0
  107. data/assets/macos/universal/lib/libjpeg.a +0 -0
  108. data/assets/macos/universal/lib/libjxl.a +0 -0
  109. data/assets/macos/universal/lib/libmodplug.a +0 -0
  110. data/assets/macos/universal/lib/libmpg123.a +0 -0
  111. data/assets/macos/universal/lib/libmruby.a +0 -0
  112. data/assets/macos/universal/lib/libogg.a +0 -0
  113. data/assets/macos/universal/lib/libpng.a +0 -0
  114. data/assets/macos/universal/lib/libtiff.a +0 -0
  115. data/assets/macos/universal/lib/libvorbis.a +0 -0
  116. data/assets/macos/universal/lib/libvorbisfile.a +0 -0
  117. data/assets/macos/universal/lib/libwebp.a +0 -0
  118. data/assets/macos/universal/lib/libzstd.a +0 -0
  119. data/assets/wasm/template.html +2 -1
  120. data/assets/windows/mingw-w64-ucrt-x86_64/bin/mrbc.exe +0 -0
  121. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libFLAC.a +0 -0
  122. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libLerc.a +0 -0
  123. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libSDL2.a +0 -0
  124. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libSDL2_image.a +0 -0
  125. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libSDL2_mixer.a +0 -0
  126. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libSDL2_ttf.a +0 -0
  127. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libbrotlicommon.a +0 -0
  128. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libbrotlidec.a +0 -0
  129. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libdeflate.a +0 -0
  130. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libfreetype.a +0 -0
  131. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libglew32.a +0 -0
  132. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libharfbuzz.a +0 -0
  133. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libhwy.a +0 -0
  134. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libjpeg.a +0 -0
  135. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libjxl.a +0 -0
  136. data/assets/windows/mingw-w64-ucrt-x86_64/lib/liblzma.a +0 -0
  137. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libmpg123.a +0 -0
  138. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libmruby.a +0 -0
  139. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libopus.a +0 -0
  140. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libpng.a +0 -0
  141. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libsndfile.a +0 -0
  142. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libssp.a +0 -0
  143. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libstdc++.a +0 -0
  144. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libtiff.a +0 -0
  145. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libwebp.a +0 -0
  146. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libz.a +0 -0
  147. data/assets/windows/mingw-w64-x86_64/bin/mrbc.exe +0 -0
  148. data/assets/windows/mingw-w64-x86_64/lib/libFLAC.a +0 -0
  149. data/assets/windows/mingw-w64-x86_64/lib/libLerc.a +0 -0
  150. data/assets/windows/mingw-w64-x86_64/lib/libSDL2.a +0 -0
  151. data/assets/windows/mingw-w64-x86_64/lib/libSDL2_image.a +0 -0
  152. data/assets/windows/mingw-w64-x86_64/lib/libSDL2_mixer.a +0 -0
  153. data/assets/windows/mingw-w64-x86_64/lib/libSDL2_ttf.a +0 -0
  154. data/assets/windows/mingw-w64-x86_64/lib/libbrotlicommon.a +0 -0
  155. data/assets/windows/mingw-w64-x86_64/lib/libbrotlidec.a +0 -0
  156. data/assets/windows/mingw-w64-x86_64/lib/libdeflate.a +0 -0
  157. data/assets/windows/mingw-w64-x86_64/lib/libfreetype.a +0 -0
  158. data/assets/windows/mingw-w64-x86_64/lib/libglew32.a +0 -0
  159. data/assets/windows/mingw-w64-x86_64/lib/libharfbuzz.a +0 -0
  160. data/assets/windows/mingw-w64-x86_64/lib/libhwy.a +0 -0
  161. data/assets/windows/mingw-w64-x86_64/lib/libjpeg.a +0 -0
  162. data/assets/windows/mingw-w64-x86_64/lib/libjxl.a +0 -0
  163. data/assets/windows/mingw-w64-x86_64/lib/liblzma.a +0 -0
  164. data/assets/windows/mingw-w64-x86_64/lib/libmpg123.a +0 -0
  165. data/assets/windows/mingw-w64-x86_64/lib/libmruby.a +0 -0
  166. data/assets/windows/mingw-w64-x86_64/lib/libopus.a +0 -0
  167. data/assets/windows/mingw-w64-x86_64/lib/libpng.a +0 -0
  168. data/assets/windows/mingw-w64-x86_64/lib/libsndfile.a +0 -0
  169. data/assets/windows/mingw-w64-x86_64/lib/libssp.a +0 -0
  170. data/assets/windows/mingw-w64-x86_64/lib/libstdc++.a +0 -0
  171. data/assets/windows/mingw-w64-x86_64/lib/libtiff.a +0 -0
  172. data/assets/windows/mingw-w64-x86_64/lib/libwebp.a +0 -0
  173. data/assets/windows/mingw-w64-x86_64/lib/libz.a +0 -0
  174. data/assets/windows/mingw-w64-x86_64/lib/libzstd.a +0 -0
  175. data/ext/ruby2d/canvas.c +540 -0
  176. data/ext/ruby2d/extconf.rb +33 -20
  177. data/ext/ruby2d/gl.c +3 -3
  178. data/ext/ruby2d/image.c +7 -7
  179. data/ext/ruby2d/ruby2d.c +741 -24
  180. data/ext/ruby2d/ruby2d.h +66 -3
  181. data/ext/ruby2d/sound.c +16 -2
  182. data/lib/ruby2d/canvas.rb +315 -0
  183. data/lib/ruby2d/circle.rb +30 -15
  184. data/lib/ruby2d/cli/build.rb +5 -3
  185. data/lib/ruby2d/cli/enable_console.rb +3 -1
  186. data/lib/ruby2d/color.rb +133 -77
  187. data/lib/ruby2d/core.rb +32 -0
  188. data/lib/ruby2d/dsl.rb +38 -32
  189. data/lib/ruby2d/exceptions.rb +2 -1
  190. data/lib/ruby2d/font.rb +97 -62
  191. data/lib/ruby2d/image.rb +48 -27
  192. data/lib/ruby2d/line.rb +84 -45
  193. data/lib/ruby2d/music.rb +33 -23
  194. data/lib/ruby2d/pixel.rb +10 -9
  195. data/lib/ruby2d/pixmap.rb +39 -0
  196. data/lib/ruby2d/pixmap_atlas.rb +56 -0
  197. data/lib/ruby2d/quad.rb +98 -49
  198. data/lib/ruby2d/rectangle.rb +35 -36
  199. data/lib/ruby2d/renderable.rb +7 -6
  200. data/lib/ruby2d/sound.rb +23 -17
  201. data/lib/ruby2d/sprite.rb +181 -140
  202. data/lib/ruby2d/square.rb +21 -20
  203. data/lib/ruby2d/text.rb +47 -19
  204. data/lib/ruby2d/texture.rb +13 -3
  205. data/lib/ruby2d/tileset.rb +97 -44
  206. data/lib/ruby2d/triangle.rb +91 -42
  207. data/lib/ruby2d/version.rb +3 -1
  208. data/lib/ruby2d/vertices.rb +81 -45
  209. data/lib/ruby2d/window.rb +508 -371
  210. data/lib/ruby2d.rb +11 -29
  211. metadata +51 -16
  212. data/assets/include/SDL2/SDL_config_psp.h +0 -165
  213. data/assets/include/SDL2/SDL_config_wiz.h +0 -154
  214. data/assets/include/glew.h +0 -23686
  215. data/assets/macos/universal/lib/libpng16.a +0 -0
  216. data/assets/windows/glew/README.md +0 -10
  217. data/assets/windows/glew/glew.h +0 -23686
  218. data/assets/windows/glew/libglew32.a +0 -0
  219. data/assets/windows/mingw-w64-ucrt-x86_64/lib/libpng16.a +0 -0
  220. data/assets/windows/mingw-w64-x86_64/lib/libpng16.a +0 -0
  221. data/lib/ruby2d/entity.rb +0 -17
@@ -1,6 +1,6 @@
1
1
  /*
2
2
  SDL_mixer: An audio mixer library based on the SDL library
3
- Copyright (C) 1997-2018 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,13 @@
19
19
  3. This notice may not be removed or altered from any source distribution.
20
20
  */
21
21
 
22
+ /**
23
+ * \file SDL_mixer.h
24
+ *
25
+ * Header file for SDL_mixer library
26
+ *
27
+ * A simple library to play and mix sounds and musics
28
+ */
22
29
  #ifndef SDL_MIXER_H_
23
30
  #define SDL_MIXER_H_
24
31
 
@@ -34,13 +41,15 @@
34
41
  extern "C" {
35
42
  #endif
36
43
 
37
- /* Printable format: "%d.%d.%d", MAJOR, MINOR, PATCHLEVEL
38
- */
44
+ /**
45
+ * Printable format: "%d.%d.%d", MAJOR, MINOR, PATCHLEVEL
46
+ */
39
47
  #define SDL_MIXER_MAJOR_VERSION 2
40
- #define SDL_MIXER_MINOR_VERSION 0
41
- #define SDL_MIXER_PATCHLEVEL 4
48
+ #define SDL_MIXER_MINOR_VERSION 6
49
+ #define SDL_MIXER_PATCHLEVEL 2
42
50
 
43
- /* This macro can be used to fill a version structure with the compile-time
51
+ /**
52
+ * This macro can be used to fill a version structure with the compile-time
44
53
  * version of the SDL_mixer library.
45
54
  */
46
55
  #define SDL_MIXER_VERSION(X) \
@@ -56,24 +65,46 @@ extern "C" {
56
65
  #define MIX_PATCHLEVEL SDL_MIXER_PATCHLEVEL
57
66
  #define MIX_VERSION(X) SDL_MIXER_VERSION(X)
58
67
 
68
+ #if SDL_MIXER_MAJOR_VERSION < 3 && SDL_MAJOR_VERSION < 3
59
69
  /**
60
70
  * This is the version number macro for the current SDL_mixer version.
71
+ *
72
+ * In versions higher than 2.9.0, the minor version overflows into
73
+ * the thousands digit: for example, 2.23.0 is encoded as 4300.
74
+ * This macro will not be available in SDL 3.x or SDL_mixer 3.x.
75
+ *
76
+ * Deprecated, use SDL_MIXER_VERSION_ATLEAST or SDL_MIXER_VERSION instead.
61
77
  */
62
78
  #define SDL_MIXER_COMPILEDVERSION \
63
79
  SDL_VERSIONNUM(SDL_MIXER_MAJOR_VERSION, SDL_MIXER_MINOR_VERSION, SDL_MIXER_PATCHLEVEL)
80
+ #endif /* SDL_MIXER_MAJOR_VERSION < 3 && SDL_MAJOR_VERSION < 3 */
64
81
 
65
82
  /**
66
83
  * This macro will evaluate to true if compiled with SDL_mixer at least X.Y.Z.
67
84
  */
68
85
  #define SDL_MIXER_VERSION_ATLEAST(X, Y, Z) \
69
- (SDL_MIXER_COMPILEDVERSION >= SDL_VERSIONNUM(X, Y, Z))
86
+ ((SDL_MIXER_MAJOR_VERSION >= X) && \
87
+ (SDL_MIXER_MAJOR_VERSION > X || SDL_MIXER_MINOR_VERSION >= Y) && \
88
+ (SDL_MIXER_MAJOR_VERSION > X || SDL_MIXER_MINOR_VERSION > Y || SDL_MIXER_PATCHLEVEL >= Z))
70
89
 
71
- /* This function gets the version of the dynamically linked SDL_mixer library.
72
- it should NOT be used to fill a version structure, instead you should
73
- use the SDL_MIXER_VERSION() macro.
90
+ /**
91
+ * Query the version of SDL_mixer that the program is linked against.
92
+ *
93
+ * This function gets the version of the dynamically linked SDL_mixer library.
94
+ * This is separate from the SDL_MIXER_VERSION() macro, which tells you what
95
+ * version of the SDL_mixer headers you compiled against.
96
+ *
97
+ * This returns static internal data; do not free or modify it!
98
+ *
99
+ * \returns a pointer to the version information.
100
+ *
101
+ * \since This function is available since SDL_mixer 2.0.0.
74
102
  */
75
103
  extern DECLSPEC const SDL_version * SDLCALL Mix_Linked_Version(void);
76
104
 
105
+ /**
106
+ * Initialization flags
107
+ */
77
108
  typedef enum
78
109
  {
79
110
  MIX_INIT_FLAC = 0x00000001,
@@ -84,23 +115,105 @@ typedef enum
84
115
  MIX_INIT_OPUS = 0x00000040
85
116
  } MIX_InitFlags;
86
117
 
87
- /* Loads dynamic libraries and prepares them for use. Flags should be
88
- one or more flags from MIX_InitFlags OR'd together.
89
- It returns the flags successfully initialized, or 0 on failure.
118
+ /**
119
+ * Initialize SDL_mixer.
120
+ *
121
+ * This function loads dynamic libraries that SDL_mixer needs, and prepares
122
+ * them for use. This must be the first function you call in SDL_mixer, and if
123
+ * it fails you should not continue with the library.
124
+ *
125
+ * Flags should be one or more flags from MIX_InitFlags OR'd together. It
126
+ * returns the flags successfully initialized, or 0 on failure.
127
+ *
128
+ * Currently, these flags are:
129
+ *
130
+ * - `MIX_INIT_FLAC`
131
+ * - `MIX_INIT_MOD`
132
+ * - `MIX_INIT_MP3`
133
+ * - `MIX_INIT_OGG`
134
+ * - `MIX_INIT_MID`
135
+ * - `MIX_INIT_OPUS`
136
+ *
137
+ * More flags may be added in a future SDL_mixer release.
138
+ *
139
+ * This function may need to load external shared libraries to support various
140
+ * codecs, which means this function can fail to initialize that support on an
141
+ * otherwise-reasonable system if the library isn't available; this is not
142
+ * just a question of exceptional circumstances like running out of memory at
143
+ * startup!
144
+ *
145
+ * Note that you may call this function more than once to initialize with
146
+ * additional flags. The return value will reflect both new flags that
147
+ * successfully initialized, and also include flags that had previously been
148
+ * initialized as well.
149
+ *
150
+ * As this will return previously-initialized flags, it's legal to call this
151
+ * with zero (no flags set). This is a safe no-op that can be used to query
152
+ * the current initialization state without changing it at all.
153
+ *
154
+ * Since this returns previously-initialized flags as well as new ones, and
155
+ * you can call this with zero, you should not check for a zero return value
156
+ * to determine an error condition. Instead, you should check to make sure all
157
+ * the flags you require are set in the return value. If you have a game with
158
+ * data in a specific format, this might be a fatal error. If you're a generic
159
+ * media player, perhaps you are fine with only having WAV and MP3 support and
160
+ * can live without Opus playback, even if you request support for everything.
161
+ *
162
+ * Unlike other SDL satellite libraries, calls to Mix_Init do not stack; a
163
+ * single call to Mix_Quit() will deinitialize everything and does not have to
164
+ * be paired with a matching Mix_Init call. For that reason, it's considered
165
+ * best practices to have a single Mix_Init and Mix_Quit call in your program.
166
+ * While this isn't required, be aware of the risks of deviating from that
167
+ * behavior.
168
+ *
169
+ * After initializing SDL_mixer, the next step is to open an audio device to
170
+ * prepare to play sound (with Mix_OpenAudio() or Mix_OpenAudioDevice()), and
171
+ * load audio data to play with that device.
172
+ *
173
+ * \param flags initialization flags, OR'd together.
174
+ * \returns all currently initialized flags.
175
+ *
176
+ * \since This function is available since SDL_mixer 2.0.0.
177
+ *
178
+ * \sa Mix_Quit
90
179
  */
91
180
  extern DECLSPEC int SDLCALL Mix_Init(int flags);
92
181
 
93
- /* Unloads libraries loaded with Mix_Init */
182
+ /**
183
+ * Deinitialize SDL_mixer.
184
+ *
185
+ * This should be the last function you call in SDL_mixer, after freeing all
186
+ * other resources and closing all audio devices. This will unload any shared
187
+ * libraries it is using for various codecs.
188
+ *
189
+ * After this call, a call to Mix_Init(0) will return 0 (no codecs loaded).
190
+ *
191
+ * You can safely call Mix_Init() to reload various codec support after this
192
+ * call.
193
+ *
194
+ * Unlike other SDL satellite libraries, calls to Mix_Init do not stack; a
195
+ * single call to Mix_Quit() will deinitialize everything and does not have to
196
+ * be paired with a matching Mix_Init call. For that reason, it's considered
197
+ * best practices to have a single Mix_Init and Mix_Quit call in your program.
198
+ * While this isn't required, be aware of the risks of deviating from that
199
+ * behavior.
200
+ *
201
+ * \since This function is available since SDL_mixer 2.0.0.
202
+ *
203
+ * \sa Mix_Init
204
+ */
94
205
  extern DECLSPEC void SDLCALL Mix_Quit(void);
95
206
 
96
207
 
97
- /* The default mixer has 8 simultaneous mixing channels */
208
+ /**
209
+ * The default mixer has 8 simultaneous mixing channels
210
+ */
98
211
  #ifndef MIX_CHANNELS
99
212
  #define MIX_CHANNELS 8
100
213
  #endif
101
214
 
102
215
  /* Good default values for a PC soundcard */
103
- #define MIX_DEFAULT_FREQUENCY 22050
216
+ #define MIX_DEFAULT_FREQUENCY 44100
104
217
  #if SDL_BYTEORDER == SDL_LIL_ENDIAN
105
218
  #define MIX_DEFAULT_FORMAT AUDIO_S16LSB
106
219
  #else
@@ -109,7 +222,9 @@ extern DECLSPEC void SDLCALL Mix_Quit(void);
109
222
  #define MIX_DEFAULT_CHANNELS 2
110
223
  #define MIX_MAX_VOLUME SDL_MIX_MAXVOLUME /* Volume of a chunk */
111
224
 
112
- /* The internal format for an audio chunk */
225
+ /**
226
+ * The internal format for an audio chunk
227
+ */
113
228
  typedef struct Mix_Chunk {
114
229
  int allocated;
115
230
  Uint8 *abuf;
@@ -117,14 +232,18 @@ typedef struct Mix_Chunk {
117
232
  Uint8 volume; /* Per-sample volume, 0-128 */
118
233
  } Mix_Chunk;
119
234
 
120
- /* The different fading types supported */
235
+ /**
236
+ * The different fading types supported
237
+ */
121
238
  typedef enum {
122
239
  MIX_NO_FADING,
123
240
  MIX_FADING_OUT,
124
241
  MIX_FADING_IN
125
242
  } Mix_Fading;
126
243
 
127
- /* These are types of music files (not libraries used to load them) */
244
+ /**
245
+ * These are types of music files (not libraries used to load them)
246
+ */
128
247
  typedef enum {
129
248
  MUS_NONE,
130
249
  MUS_CMD,
@@ -139,507 +258,2521 @@ typedef enum {
139
258
  MUS_OPUS
140
259
  } Mix_MusicType;
141
260
 
142
- /* The internal format for a music chunk interpreted via mikmod */
143
- typedef struct _Mix_Music Mix_Music;
144
-
145
- /* Open the mixer with a certain audio format */
146
- extern DECLSPEC int SDLCALL Mix_OpenAudio(int frequency, Uint16 format, int channels, int chunksize);
147
-
148
- /* Open the mixer with specific device and certain audio format */
149
- extern DECLSPEC int SDLCALL Mix_OpenAudioDevice(int frequency, Uint16 format, int channels, int chunksize, const char* device, int allowed_changes);
150
-
151
- /* Dynamically change the number of channels managed by the mixer.
152
- If decreasing the number of channels, the upper channels are
153
- stopped.
154
- This function returns the new number of allocated channels.
155
- */
156
- extern DECLSPEC int SDLCALL Mix_AllocateChannels(int numchans);
157
-
158
- /* Find out what the actual audio device parameters are.
159
- This function returns 1 if the audio has been opened, 0 otherwise.
160
- */
161
- extern DECLSPEC int SDLCALL Mix_QuerySpec(int *frequency,Uint16 *format,int *channels);
162
-
163
- /* Load a wave file or a music (.mod .s3m .it .xm) file */
164
- extern DECLSPEC Mix_Chunk * SDLCALL Mix_LoadWAV_RW(SDL_RWops *src, int freesrc);
165
- #define Mix_LoadWAV(file) Mix_LoadWAV_RW(SDL_RWFromFile(file, "rb"), 1)
166
- extern DECLSPEC Mix_Music * SDLCALL Mix_LoadMUS(const char *file);
167
-
168
- /* Load a music file from an SDL_RWop object (Ogg and MikMod specific currently)
169
- Matt Campbell (matt@campbellhome.dhs.org) April 2000 */
170
- extern DECLSPEC Mix_Music * SDLCALL Mix_LoadMUS_RW(SDL_RWops *src, int freesrc);
171
-
172
- /* Load a music file from an SDL_RWop object assuming a specific format */
173
- extern DECLSPEC Mix_Music * SDLCALL Mix_LoadMUSType_RW(SDL_RWops *src, Mix_MusicType type, int freesrc);
174
-
175
- /* Load a wave file of the mixer format from a memory buffer */
176
- extern DECLSPEC Mix_Chunk * SDLCALL Mix_QuickLoad_WAV(Uint8 *mem);
177
-
178
- /* Load raw audio data of the mixer format from a memory buffer */
179
- extern DECLSPEC Mix_Chunk * SDLCALL Mix_QuickLoad_RAW(Uint8 *mem, Uint32 len);
180
-
181
- /* Free an audio chunk previously loaded */
182
- extern DECLSPEC void SDLCALL Mix_FreeChunk(Mix_Chunk *chunk);
183
- extern DECLSPEC void SDLCALL Mix_FreeMusic(Mix_Music *music);
184
-
185
- /* Get a list of chunk/music decoders that this build of SDL_mixer provides.
186
- This list can change between builds AND runs of the program, if external
187
- libraries that add functionality become available.
188
- You must successfully call Mix_OpenAudio() before calling these functions.
189
- This API is only available in SDL_mixer 1.2.9 and later.
190
-
191
- // usage...
192
- int i;
193
- const int total = Mix_GetNumChunkDecoders();
194
- for (i = 0; i < total; i++)
195
- printf("Supported chunk decoder: [%s]\n", Mix_GetChunkDecoder(i));
196
-
197
- Appearing in this list doesn't promise your specific audio file will
198
- decode...but it's handy to know if you have, say, a functioning Timidity
199
- install.
200
-
201
- These return values are static, read-only data; do not modify or free it.
202
- The pointers remain valid until you call Mix_CloseAudio().
203
- */
204
- extern DECLSPEC int SDLCALL Mix_GetNumChunkDecoders(void);
205
- extern DECLSPEC const char * SDLCALL Mix_GetChunkDecoder(int index);
206
- extern DECLSPEC SDL_bool SDLCALL Mix_HasChunkDecoder(const char *name);
207
- extern DECLSPEC int SDLCALL Mix_GetNumMusicDecoders(void);
208
- extern DECLSPEC const char * SDLCALL Mix_GetMusicDecoder(int index);
209
- extern DECLSPEC SDL_bool SDLCALL Mix_HasMusicDecoder(const char *name);
210
-
211
- /* Find out the music format of a mixer music, or the currently playing
212
- music, if 'music' is NULL.
213
- */
214
- extern DECLSPEC Mix_MusicType SDLCALL Mix_GetMusicType(const Mix_Music *music);
215
-
216
- /* Set a function that is called after all mixing is performed.
217
- This can be used to provide real-time visual display of the audio stream
218
- or add a custom mixer filter for the stream data.
219
- */
220
- extern DECLSPEC void SDLCALL Mix_SetPostMix(void (SDLCALL *mix_func)(void *udata, Uint8 *stream, int len), void *arg);
221
-
222
- /* Add your own music player or additional mixer function.
223
- If 'mix_func' is NULL, the default music player is re-enabled.
224
- */
225
- extern DECLSPEC void SDLCALL Mix_HookMusic(void (SDLCALL *mix_func)(void *udata, Uint8 *stream, int len), void *arg);
226
-
227
- /* Add your own callback for when the music has finished playing or when it is
228
- * stopped from a call to Mix_HaltMusic.
229
- */
230
- extern DECLSPEC void SDLCALL Mix_HookMusicFinished(void (SDLCALL *music_finished)(void));
231
-
232
- /* Get a pointer to the user data for the current music hook */
233
- extern DECLSPEC void * SDLCALL Mix_GetMusicHookData(void);
234
-
235
- /*
236
- * Add your own callback when a channel has finished playing. NULL
237
- * to disable callback. The callback may be called from the mixer's audio
238
- * callback or it could be called as a result of Mix_HaltChannel(), etc.
239
- * do not call SDL_LockAudio() from this callback; you will either be
240
- * inside the audio callback, or SDL_mixer will explicitly lock the audio
241
- * before calling your callback.
261
+ /**
262
+ * The internal format for a music chunk interpreted via codecs
242
263
  */
243
- extern DECLSPEC void SDLCALL Mix_ChannelFinished(void (SDLCALL *channel_finished)(int channel));
244
-
245
-
246
- /* Special Effects API by ryan c. gordon. (icculus@icculus.org) */
247
-
248
- #define MIX_CHANNEL_POST -2
264
+ typedef struct _Mix_Music Mix_Music;
249
265
 
250
- /* This is the format of a special effect callback:
266
+ /**
267
+ * Open the default audio device for playback.
251
268
  *
252
- * myeffect(int chan, void *stream, int len, void *udata);
269
+ * An audio device is what generates sound, so the app must open one to make
270
+ * noise.
253
271
  *
254
- * (chan) is the channel number that your effect is affecting. (stream) is
255
- * the buffer of data to work upon. (len) is the size of (stream), and
256
- * (udata) is a user-defined bit of data, which you pass as the last arg of
257
- * Mix_RegisterEffect(), and is passed back unmolested to your callback.
258
- * Your effect changes the contents of (stream) based on whatever parameters
259
- * are significant, or just leaves it be, if you prefer. You can do whatever
260
- * you like to the buffer, though, and it will continue in its changed state
261
- * down the mixing pipeline, through any other effect functions, then finally
262
- * to be mixed with the rest of the channels and music for the final output
263
- * stream.
272
+ * This function will check if SDL's audio system is initialized, and if not,
273
+ * it will initialize it by calling `SDL_Init(SDL_INIT_AUDIO)` on your behalf.
274
+ * You are free to (and encouraged to!) initialize it yourself before calling
275
+ * this function, as this gives your program more control over the process.
264
276
  *
265
- * DO NOT EVER call SDL_LockAudio() from your callback function!
266
- */
267
- typedef void (SDLCALL *Mix_EffectFunc_t)(int chan, void *stream, int len, void *udata);
268
-
269
- /*
270
- * This is a callback that signifies that a channel has finished all its
271
- * loops and has completed playback. This gets called if the buffer
272
- * plays out normally, or if you call Mix_HaltChannel(), implicitly stop
273
- * a channel via Mix_AllocateChannels(), or unregister a callback while
274
- * it's still playing.
277
+ * This function might cover all of an application's needs, but for those that
278
+ * need more flexibility, the more powerful version of this function is
279
+ * Mix_OpenAudioDevice(). This function is equivalent to calling:
275
280
  *
276
- * DO NOT EVER call SDL_LockAudio() from your callback function!
281
+ * ```c
282
+ * Mix_OpenAudioDevice(frequency, format, nchannels, chunksize, NULL,
283
+ * SDL_AUDIO_ALLOW_FREQUENCY_CHANGE |
284
+ * SDL_AUDIO_ALLOW_CHANNELS_CHANGE);
285
+ * ```
286
+ *
287
+ * If you aren't particularly concerned with the specifics of the audio
288
+ * device, and your data isn't in a specific format, the values you use here
289
+ * can just be reasonable defaults. SDL_mixer will convert audio data you feed
290
+ * it to the correct format on demand.
291
+ *
292
+ * That being said, if you have control of your audio data and you know its
293
+ * format ahead of time, you can save CPU time by opening the audio device in
294
+ * that exact format so SDL_mixer does not have to spend time converting
295
+ * anything behind the scenes, and can just pass the data straight through to
296
+ * the hardware. On some platforms, where the hardware only supports specific
297
+ * settings, you might have to be careful to make everything match, but your
298
+ * own data is often easier to control, so aim to open the device for what you
299
+ * need.
300
+ *
301
+ * The other reason to care about specific formats: if you plan to touch the
302
+ * mix buffer directly (with Mix_SetPostMix, a registered effect, or
303
+ * Mix_HookMusic), you might have code that expects it to be in a specific
304
+ * format, and you should specify that here.
305
+ *
306
+ * The audio device frequency is specified in Hz; in modern times, 48000 is
307
+ * often a reasonable default.
308
+ *
309
+ * The audio device format is one of SDL's AUDIO_* constants. AUDIO_S16SYS
310
+ * (16-bit audio) is probably a safe default. More modern systems may prefer
311
+ * AUDIO_F32SYS (32-bit floating point audio).
312
+ *
313
+ * The audio device channels are generally 1 for mono output, or 2 for stereo,
314
+ * but the brave can try surround sound configs with 4 (quad), 6 (5.1), 7
315
+ * (6.1) or 8 (7.1).
316
+ *
317
+ * The audio device's chunk size is the number of sample frames (one sample
318
+ * per frame for mono output, two samples per frame in a stereo setup, etc)
319
+ * that are fed to the device at once. The lower the number, the lower the
320
+ * latency, but you risk dropouts if it gets too low. 2048 is often a
321
+ * reasonable default, but your app might want to experiment with 1024 or
322
+ * 4096.
323
+ *
324
+ * You may only have one audio device open at a time; if you want to change a
325
+ * setting, you must close the device and reopen it, which is not something
326
+ * you can do seamlessly during playback.
327
+ *
328
+ * This function does not allow you to select a specific audio device on the
329
+ * system, it always chooses the best default it can on your behalf (which, in
330
+ * many cases, is exactly what you want anyhow). If you must choose a specific
331
+ * device, you can do so with Mix_OpenAudioDevice() instead.
332
+ *
333
+ * If this function reports success, you are ready to start making noise! Load
334
+ * some audio data and start playing!
335
+ *
336
+ * The app can use Mix_QuerySpec() to determine the final device settings.
337
+ *
338
+ * When done with an audio device, probably at the end of the program, the app
339
+ * should dispose of the device with Mix_CloseDevice().
340
+ *
341
+ * \param frequency the frequency to playback audio at (in Hz).
342
+ * \param format audio format, one of SDL's AUDIO_* values.
343
+ * \param channels number of channels (1 is mono, 2 is stereo, etc).
344
+ * \param chunksize audio buffer size in sample FRAMES (total samples divided
345
+ * by channel count).
346
+ * \returns 0 if successful, -1 on error.
347
+ *
348
+ * \since This function is available since SDL_mixer 2.0.0.
349
+ *
350
+ * \sa Mix_OpenAudioDevice
351
+ * \sa Mix_CloseDevice
277
352
  */
278
- typedef void (SDLCALL *Mix_EffectDone_t)(int chan, void *udata);
353
+ extern DECLSPEC int SDLCALL Mix_OpenAudio(int frequency, Uint16 format, int channels, int chunksize);
279
354
 
280
355
 
281
- /* Register a special effect function. At mixing time, the channel data is
282
- * copied into a buffer and passed through each registered effect function.
283
- * After it passes through all the functions, it is mixed into the final
284
- * output stream. The copy to buffer is performed once, then each effect
285
- * function performs on the output of the previous effect. Understand that
286
- * this extra copy to a buffer is not performed if there are no effects
287
- * registered for a given chunk, which saves CPU cycles, and any given
288
- * effect will be extra cycles, too, so it is crucial that your code run
289
- * fast. Also note that the data that your function is given is in the
290
- * format of the sound device, and not the format you gave to Mix_OpenAudio(),
291
- * although they may in reality be the same. This is an unfortunate but
292
- * necessary speed concern. Use Mix_QuerySpec() to determine if you can
293
- * handle the data before you register your effect, and take appropriate
294
- * actions.
295
- * You may also specify a callback (Mix_EffectDone_t) that is called when
296
- * the channel finishes playing. This gives you a more fine-grained control
297
- * than Mix_ChannelFinished(), in case you need to free effect-specific
298
- * resources, etc. If you don't need this, you can specify NULL.
299
- * You may set the callbacks before or after calling Mix_PlayChannel().
300
- * Things like Mix_SetPanning() are just internal special effect functions,
301
- * so if you are using that, you've already incurred the overhead of a copy
302
- * to a separate buffer, and that these effects will be in the queue with
303
- * any functions you've registered. The list of registered effects for a
304
- * channel is reset when a chunk finishes playing, so you need to explicitly
305
- * set them with each call to Mix_PlayChannel*().
306
- * You may also register a special effect function that is to be run after
307
- * final mixing occurs. The rules for these callbacks are identical to those
308
- * in Mix_RegisterEffect, but they are run after all the channels and the
309
- * music have been mixed into a single stream, whereas channel-specific
310
- * effects run on a given channel before any other mixing occurs. These
311
- * global effect callbacks are call "posteffects". Posteffects only have
312
- * their Mix_EffectDone_t function called when they are unregistered (since
313
- * the main output stream is never "done" in the same sense as a channel).
314
- * You must unregister them manually when you've had enough. Your callback
315
- * will be told that the channel being mixed is (MIX_CHANNEL_POST) if the
316
- * processing is considered a posteffect.
356
+ /**
357
+ * Open a specific audio device for playback.
317
358
  *
318
- * After all these effects have finished processing, the callback registered
319
- * through Mix_SetPostMix() runs, and then the stream goes to the audio
320
- * device.
359
+ * (A slightly simpler version of this function is available in
360
+ * Mix_OpenAudio(), which still might meet most applications' needs.)
321
361
  *
322
- * DO NOT EVER call SDL_LockAudio() from your callback function!
362
+ * An audio device is what generates sound, so the app must open one to make
363
+ * noise.
364
+ *
365
+ * This function will check if SDL's audio system is initialized, and if not,
366
+ * it will initialize it by calling `SDL_Init(SDL_INIT_AUDIO)` on your behalf.
367
+ * You are free to (and encouraged to!) initialize it yourself before calling
368
+ * this function, as this gives your program more control over the process.
369
+ *
370
+ * If you aren't particularly concerned with the specifics of the audio
371
+ * device, and your data isn't in a specific format, the values you use here
372
+ * can just be reasonable defaults. SDL_mixer will convert audio data you feed
373
+ * it to the correct format on demand.
374
+ *
375
+ * That being said, if you have control of your audio data and you know its
376
+ * format ahead of time, you can save CPU time by opening the audio device in
377
+ * that exact format so SDL_mixer does not have to spend time converting
378
+ * anything behind the scenes, and can just pass the data straight through to
379
+ * the hardware. On some platforms, where the hardware only supports specific
380
+ * settings, you might have to be careful to make everything match, but your
381
+ * own data is often easier to control, so aim to open the device for what you
382
+ * need.
383
+ *
384
+ * The other reason to care about specific formats: if you plan to touch the
385
+ * mix buffer directly (with Mix_SetPostMix, a registered effect, or
386
+ * Mix_HookMusic), you might have code that expects it to be in a specific
387
+ * format, and you should specify that here.
388
+ *
389
+ * The audio device frequency is specified in Hz; in modern times, 48000 is
390
+ * often a reasonable default.
391
+ *
392
+ * The audio device format is one of SDL's AUDIO_* constants. AUDIO_S16SYS
393
+ * (16-bit audio) is probably a safe default. More modern systems may prefer
394
+ * AUDIO_F32SYS (32-bit floating point audio).
395
+ *
396
+ * The audio device channels are generally 1 for mono output, or 2 for stereo,
397
+ * but the brave can try surround sound configs with 4 (quad), 6 (5.1), 7
398
+ * (6.1) or 8 (7.1).
399
+ *
400
+ * The audio device's chunk size is the number of sample frames (one sample
401
+ * per frame for mono output, two samples per frame in a stereo setup, etc)
402
+ * that are fed to the device at once. The lower the number, the lower the
403
+ * latency, but you risk dropouts if it gets too low. 2048 is often a
404
+ * reasonable default, but your app might want to experiment with 1024 or
405
+ * 4096.
406
+ *
407
+ * You may only have one audio device open at a time; if you want to change a
408
+ * setting, you must close the device and reopen it, which is not something
409
+ * you can do seamlessly during playback.
410
+ *
411
+ * This function allows you to select specific audio hardware on the system
412
+ * with the `device` parameter. If you specify NULL, SDL_mixer will choose the
413
+ * best default it can on your behalf (which, in many cases, is exactly what
414
+ * you want anyhow). SDL_mixer does not offer a mechanism to determine device
415
+ * names to open, but you can use SDL_GetNumAudioDevices() to get a count of
416
+ * available devices and then SDL_GetAudioDeviceName() in a loop to obtain a
417
+ * list. If you do this, be sure to call `SDL_Init(SDL_INIT_AUDIO)` first to
418
+ * initialize SDL's audio system!
323
419
  *
324
- * returns zero if error (no such channel), nonzero if added.
325
- * Error messages can be retrieved from Mix_GetError().
420
+ * The `allowed_changes` parameter specifies what settings are flexible. These
421
+ * are the `SDL_AUDIO_ALLOW_*` flags from SDL. These tell SDL_mixer that the
422
+ * app doesn't mind if a specific setting changes. For example, the app might
423
+ * need stereo data in Sint16 format, but if the sample rate or chunk size
424
+ * changes, the app can handle that. In that case, the app would specify
425
+ * `SDL_AUDIO_ALLOW_FORMAT_CHANGE|SDL_AUDIO_ALLOW_SAMPLES_CHANGE`. In this
426
+ * case, if the system's hardware requires something other than the requested
427
+ * format, SDL_mixer can select what the hardware demands instead of the app.
428
+ * If the `SDL_AUDIO_ALLOW_` flag is not specified, SDL_mixer must convert
429
+ * data behind the scenes between what the app demands and what the hardware
430
+ * requires. If your app needs precisely what is requested, specify zero for
431
+ * `allowed_changes`.
432
+ *
433
+ * If changes were allowed, the app can use Mix_QuerySpec() to determine the
434
+ * final device settings.
435
+ *
436
+ * If this function reports success, you are ready to start making noise! Load
437
+ * some audio data and start playing!
438
+ *
439
+ * When done with an audio device, probably at the end of the program, the app
440
+ * should dispose of the device with Mix_CloseDevice().
441
+ *
442
+ * \param frequency the frequency to playback audio at (in Hz).
443
+ * \param format audio format, one of SDL's AUDIO_* values.
444
+ * \param channels number of channels (1 is mono, 2 is stereo, etc).
445
+ * \param chunksize audio buffer size in sample FRAMES (total samples divided
446
+ * by channel count).
447
+ * \param device the device name to open, or NULL to choose a reasonable
448
+ * default.
449
+ * \param allowed_changes Allow change flags (see SDL_AUDIO_ALLOW_* flags)
450
+ * \returns 0 if successful, -1 on error.
451
+ *
452
+ * \since This function is available since SDL_mixer 2.0.2.
453
+ *
454
+ * \sa Mix_OpenAudio
455
+ * \sa Mix_CloseDevice
456
+ * \sa Mix_QuerySpec
326
457
  */
327
- extern DECLSPEC int SDLCALL Mix_RegisterEffect(int chan, Mix_EffectFunc_t f, Mix_EffectDone_t d, void *arg);
328
-
458
+ extern DECLSPEC int SDLCALL Mix_OpenAudioDevice(int frequency, Uint16 format, int channels, int chunksize, const char* device, int allowed_changes);
329
459
 
330
- /* You may not need to call this explicitly, unless you need to stop an
331
- * effect from processing in the middle of a chunk's playback.
332
- * Posteffects are never implicitly unregistered as they are for channels,
333
- * but they may be explicitly unregistered through this function by
334
- * specifying MIX_CHANNEL_POST for a channel.
335
- * returns zero if error (no such channel or effect), nonzero if removed.
336
- * Error messages can be retrieved from Mix_GetError().
460
+ /**
461
+ * Find out what the actual audio device parameters are.
462
+ *
463
+ * If Mix_OpenAudioDevice() was called with `allowed_changes` set to anything
464
+ * but zero, or Mix_OpenAudio() was used, some audio device settings may be
465
+ * different from the application's request. This function will report what
466
+ * the device is actually running at.
467
+ *
468
+ * Note this is only important if the app intends to touch the audio buffers
469
+ * being sent to the hardware directly. If an app just wants to play audio
470
+ * files and let SDL_mixer handle the low-level details, this function can
471
+ * probably be ignored.
472
+ *
473
+ * If the audio device is not opened, this function will return 0.
474
+ *
475
+ * \param frequency On return, will be filled with the audio device's
476
+ * frequency in Hz.
477
+ * \param format On return, will be filled with the audio device's format.
478
+ * \param channels On return, will be filled with the audio device's channel
479
+ * count.
480
+ * \returns 1 if the audio device has been opened, 0 otherwise.
481
+ *
482
+ * \since This function is available since SDL_mixer 2.0.0.
483
+ *
484
+ * \sa Mix_OpenAudio
485
+ * \sa Mix_OpenAudioDevice
337
486
  */
338
- extern DECLSPEC int SDLCALL Mix_UnregisterEffect(int channel, Mix_EffectFunc_t f);
339
-
487
+ extern DECLSPEC int SDLCALL Mix_QuerySpec(int *frequency, Uint16 *format, int *channels);
340
488
 
341
- /* You may not need to call this explicitly, unless you need to stop all
342
- * effects from processing in the middle of a chunk's playback. Note that
343
- * this will also shut off some internal effect processing, since
344
- * Mix_SetPanning() and others may use this API under the hood. This is
345
- * called internally when a channel completes playback.
346
- * Posteffects are never implicitly unregistered as they are for channels,
347
- * but they may be explicitly unregistered through this function by
348
- * specifying MIX_CHANNEL_POST for a channel.
349
- * returns zero if error (no such channel), nonzero if all effects removed.
350
- * Error messages can be retrieved from Mix_GetError().
489
+ /**
490
+ * Dynamically change the number of channels managed by the mixer.
491
+ *
492
+ * SDL_mixer deals with "channels," which is not the same thing as the
493
+ * mono/stereo channels; they might be better described as "tracks," as each
494
+ * one corresponds to a separate source of audio data. Three different WAV
495
+ * files playing at the same time would be three separate SDL_mixer channels,
496
+ * for example.
497
+ *
498
+ * An app needs as many channels as it has audio data it wants to play
499
+ * simultaneously, mixing them into a single stream to send to the audio
500
+ * device.
501
+ *
502
+ * SDL_mixer allocates `MIX_CHANNELS` (currently 8) channels when you open an
503
+ * audio device, which may be more than an app needs, but if the app needs
504
+ * more or wants less, this function can change it.
505
+ *
506
+ * If decreasing the number of channels, any upper channels currently playing
507
+ * are stopped. This will deregister all effects on those channels and call
508
+ * any callback specified by Mix_ChannelFinished() for each removed channel.
509
+ *
510
+ * If `numchans` is less than zero, this will return the current number of
511
+ * channels without changing anything.
512
+ *
513
+ * \param numchans the new number of channels, or < 0 to query current channel
514
+ * count.
515
+ * \returns the new number of allocated channels.
516
+ *
517
+ * \since This function is available since SDL_mixer 2.0.0.
351
518
  */
352
- extern DECLSPEC int SDLCALL Mix_UnregisterAllEffects(int channel);
353
-
354
-
355
- #define MIX_EFFECTSMAXSPEED "MIX_EFFECTSMAXSPEED"
519
+ extern DECLSPEC int SDLCALL Mix_AllocateChannels(int numchans);
356
520
 
357
- /*
358
- * These are the internally-defined mixing effects. They use the same API that
359
- * effects defined in the application use, but are provided here as a
360
- * convenience. Some effects can reduce their quality or use more memory in
361
- * the name of speed; to enable this, make sure the environment variable
362
- * MIX_EFFECTSMAXSPEED (see above) is defined before you call
363
- * Mix_OpenAudio().
521
+ /**
522
+ * Load a supported audio format into a chunk.
523
+ *
524
+ * SDL_mixer has two separate data structures for audio data. One it calls a
525
+ * "chunk," which is meant to be a file completely decoded into memory up
526
+ * front, and the other it calls "music" which is a file intended to be
527
+ * decoded on demand. Originally, simple formats like uncompressed WAV files
528
+ * were meant to be chunks and compressed things, like MP3s, were meant to be
529
+ * music, and you would stream one thing for a game's music and make repeating
530
+ * sound effects with the chunks.
531
+ *
532
+ * In modern times, this isn't split by format anymore, and most are
533
+ * interchangeable, so the question is what the app thinks is worth
534
+ * predecoding or not. Chunks might take more memory, but once they are loaded
535
+ * won't need to decode again, whereas music always needs to be decoded on the
536
+ * fly. Also, crucially, there are as many channels for chunks as the app can
537
+ * allocate, but SDL_mixer only offers a single "music" channel.
538
+ *
539
+ * If `freesrc` is non-zero, the RWops will be closed before returning,
540
+ * whether this function succeeds or not. SDL_mixer reads everything it needs
541
+ * from the RWops during this call in any case.
542
+ *
543
+ * There is a separate function (a macro, before SDL_mixer 2.6.0) to read
544
+ * files from disk without having to deal with SDL_RWops:
545
+ * `Mix_LoadWAV("filename.wav")` will call this function and manage those
546
+ * details for you.
547
+ *
548
+ * When done with a chunk, the app should dispose of it with a call to
549
+ * Mix_FreeChunk().
550
+ *
551
+ * \param src an SDL_RWops that data will be read from.
552
+ * \param freesrc non-zero to close/free the SDL_RWops before returning, zero
553
+ * to leave it open.
554
+ * \returns a new chunk, or NULL on error.
555
+ *
556
+ * \since This function is available since SDL_mixer 2.6.0 (and as a macro
557
+ * since 2.0.0).
558
+ *
559
+ * \sa Mix_LoadWAV
560
+ * \sa Mix_FreeChunk
364
561
  */
562
+ extern DECLSPEC Mix_Chunk * SDLCALL Mix_LoadWAV_RW(SDL_RWops *src, int freesrc);
365
563
 
366
-
367
- /* Set the panning of a channel. The left and right channels are specified
368
- * as integers between 0 and 255, quietest to loudest, respectively.
564
+ /**
565
+ * Load a supported audio format into a chunk.
369
566
  *
370
- * Technically, this is just individual volume control for a sample with
371
- * two (stereo) channels, so it can be used for more than just panning.
372
- * If you want real panning, call it like this:
567
+ * SDL_mixer has two separate data structures for audio data. One it calls a
568
+ * "chunk," which is meant to be a file completely decoded into memory up
569
+ * front, and the other it calls "music" which is a file intended to be
570
+ * decoded on demand. Originally, simple formats like uncompressed WAV files
571
+ * were meant to be chunks and compressed things, like MP3s, were meant to be
572
+ * music, and you would stream one thing for a game's music and make repeating
573
+ * sound effects with the chunks.
373
574
  *
374
- * Mix_SetPanning(channel, left, 255 - left);
575
+ * In modern times, this isn't split by format anymore, and most are
576
+ * interchangeable, so the question is what the app thinks is worth
577
+ * predecoding or not. Chunks might take more memory, but once they are loaded
578
+ * won't need to decode again, whereas music always needs to be decoded on the
579
+ * fly. Also, crucially, there are as many channels for chunks as the app can
580
+ * allocate, but SDL_mixer only offers a single "music" channel.
375
581
  *
376
- * ...which isn't so hard.
582
+ * If you would rather use the abstract SDL_RWops interface to load data from
583
+ * somewhere other than the filesystem, you can use Mix_LoadWAV_RW() instead.
377
584
  *
378
- * Setting (channel) to MIX_CHANNEL_POST registers this as a posteffect, and
379
- * the panning will be done to the final mixed stream before passing it on
380
- * to the audio device.
585
+ * When done with a chunk, the app should dispose of it with a call to
586
+ * Mix_FreeChunk().
381
587
  *
382
- * This uses the Mix_RegisterEffect() API internally, and returns without
383
- * registering the effect function if the audio device is not configured
384
- * for stereo output. Setting both (left) and (right) to 255 causes this
385
- * effect to be unregistered, since that is the data's normal state.
588
+ * Note that before SDL_mixer 2.6.0, this function was a macro that called
589
+ * Mix_LoadWAV_RW(), creating a RWops and setting `freesrc` to 1. This macro
590
+ * has since been promoted to a proper API function. Older binaries linked
591
+ * against a newer SDL_mixer will still call Mix_LoadWAV_RW directly, as they
592
+ * are using the macro, which was available since the dawn of time.
593
+ *
594
+ * \param file the filesystem path to load data from.
595
+ * \returns a new chunk, or NULL on error.
386
596
  *
387
- * returns zero if error (no such channel or Mix_RegisterEffect() fails),
388
- * nonzero if panning effect enabled. Note that an audio device in mono
389
- * mode is a no-op, but this call will return successful in that case.
390
- * Error messages can be retrieved from Mix_GetError().
597
+ * \since This function is available since SDL_mixer 2.6.0 (and as a macro
598
+ * since 2.0.0).
599
+ *
600
+ * \sa Mix_LoadWAV_RW
601
+ * \sa Mix_FreeChunk
391
602
  */
392
- extern DECLSPEC int SDLCALL Mix_SetPanning(int channel, Uint8 left, Uint8 right);
603
+ extern DECLSPEC Mix_Chunk * SDLCALL Mix_LoadWAV(const char *file);
393
604
 
394
605
 
395
- /* Set the position of a channel. (angle) is an integer from 0 to 360, that
396
- * specifies the location of the sound in relation to the listener. (angle)
397
- * will be reduced as neccesary (540 becomes 180 degrees, -100 becomes 260).
398
- * Angle 0 is due north, and rotates clockwise as the value increases.
399
- * For efficiency, the precision of this effect may be limited (angles 1
400
- * through 7 might all produce the same effect, 8 through 15 are equal, etc).
401
- * (distance) is an integer between 0 and 255 that specifies the space
402
- * between the sound and the listener. The larger the number, the further
403
- * away the sound is. Using 255 does not guarantee that the channel will be
404
- * culled from the mixing process or be completely silent. For efficiency,
405
- * the precision of this effect may be limited (distance 0 through 5 might
406
- * all produce the same effect, 6 through 10 are equal, etc). Setting (angle)
407
- * and (distance) to 0 unregisters this effect, since the data would be
408
- * unchanged.
606
+ /**
607
+ * Load a supported audio format into a music object.
409
608
  *
410
- * If you need more precise positional audio, consider using OpenAL for
411
- * spatialized effects instead of SDL_mixer. This is only meant to be a
412
- * basic effect for simple "3D" games.
609
+ * SDL_mixer has two separate data structures for audio data. One it calls a
610
+ * "chunk," which is meant to be a file completely decoded into memory up
611
+ * front, and the other it calls "music" which is a file intended to be
612
+ * decoded on demand. Originally, simple formats like uncompressed WAV files
613
+ * were meant to be chunks and compressed things, like MP3s, were meant to be
614
+ * music, and you would stream one thing for a game's music and make repeating
615
+ * sound effects with the chunks.
413
616
  *
414
- * If the audio device is configured for mono output, then you won't get
415
- * any effectiveness from the angle; however, distance attenuation on the
416
- * channel will still occur. While this effect will function with stereo
417
- * voices, it makes more sense to use voices with only one channel of sound,
418
- * so when they are mixed through this effect, the positioning will sound
419
- * correct. You can convert them to mono through SDL before giving them to
420
- * the mixer in the first place if you like.
617
+ * In modern times, this isn't split by format anymore, and most are
618
+ * interchangeable, so the question is what the app thinks is worth
619
+ * predecoding or not. Chunks might take more memory, but once they are loaded
620
+ * won't need to decode again, whereas music always needs to be decoded on the
621
+ * fly. Also, crucially, there are as many channels for chunks as the app can
622
+ * allocate, but SDL_mixer only offers a single "music" channel.
421
623
  *
422
- * Setting (channel) to MIX_CHANNEL_POST registers this as a posteffect, and
423
- * the positioning will be done to the final mixed stream before passing it
424
- * on to the audio device.
624
+ * When done with this music, the app should dispose of it with a call to
625
+ * Mix_FreeMusic().
425
626
  *
426
- * This is a convenience wrapper over Mix_SetDistance() and Mix_SetPanning().
627
+ * \param file a file path from where to load music data.
628
+ * \returns a new music object, or NULL on error.
629
+ *
630
+ * \since This function is available since SDL_mixer 2.0.0.
427
631
  *
428
- * returns zero if error (no such channel or Mix_RegisterEffect() fails),
429
- * nonzero if position effect is enabled.
430
- * Error messages can be retrieved from Mix_GetError().
632
+ * \sa Mix_FreeMusic
431
633
  */
432
- extern DECLSPEC int SDLCALL Mix_SetPosition(int channel, Sint16 angle, Uint8 distance);
433
-
634
+ extern DECLSPEC Mix_Music * SDLCALL Mix_LoadMUS(const char *file);
434
635
 
435
- /* Set the "distance" of a channel. (distance) is an integer from 0 to 255
436
- * that specifies the location of the sound in relation to the listener.
437
- * Distance 0 is overlapping the listener, and 255 is as far away as possible
438
- * A distance of 255 does not guarantee silence; in such a case, you might
439
- * want to try changing the chunk's volume, or just cull the sample from the
440
- * mixing process with Mix_HaltChannel().
441
- * For efficiency, the precision of this effect may be limited (distances 1
442
- * through 7 might all produce the same effect, 8 through 15 are equal, etc).
443
- * (distance) is an integer between 0 and 255 that specifies the space
444
- * between the sound and the listener. The larger the number, the further
445
- * away the sound is.
446
- * Setting (distance) to 0 unregisters this effect, since the data would be
447
- * unchanged.
448
- * If you need more precise positional audio, consider using OpenAL for
449
- * spatialized effects instead of SDL_mixer. This is only meant to be a
450
- * basic effect for simple "3D" games.
636
+ /**
637
+ * Load a supported audio format into a music object.
451
638
  *
452
- * Setting (channel) to MIX_CHANNEL_POST registers this as a posteffect, and
453
- * the distance attenuation will be done to the final mixed stream before
454
- * passing it on to the audio device.
639
+ * SDL_mixer has two separate data structures for audio data. One it calls a
640
+ * "chunk," which is meant to be a file completely decoded into memory up
641
+ * front, and the other it calls "music" which is a file intended to be
642
+ * decoded on demand. Originally, simple formats like uncompressed WAV files
643
+ * were meant to be chunks and compressed things, like MP3s, were meant to be
644
+ * music, and you would stream one thing for a game's music and make repeating
645
+ * sound effects with the chunks.
455
646
  *
456
- * This uses the Mix_RegisterEffect() API internally.
647
+ * In modern times, this isn't split by format anymore, and most are
648
+ * interchangeable, so the question is what the app thinks is worth
649
+ * predecoding or not. Chunks might take more memory, but once they are loaded
650
+ * won't need to decode again, whereas music always needs to be decoded on the
651
+ * fly. Also, crucially, there are as many channels for chunks as the app can
652
+ * allocate, but SDL_mixer only offers a single "music" channel.
457
653
  *
458
- * returns zero if error (no such channel or Mix_RegisterEffect() fails),
459
- * nonzero if position effect is enabled.
460
- * Error messages can be retrieved from Mix_GetError().
654
+ * If `freesrc` is non-zero, the RWops will be closed before returning,
655
+ * whether this function succeeds or not. SDL_mixer reads everything it needs
656
+ * from the RWops during this call in any case.
657
+ *
658
+ * As a convenience, there is a function to read files from disk without
659
+ * having to deal with SDL_RWops: `Mix_LoadMUS("filename.mp3")` will manage
660
+ * those details for you.
661
+ *
662
+ * This function attempts to guess the file format from incoming data. If the
663
+ * caller knows the format, or wants to force it, it should use
664
+ * Mix_LoadMUSType_RW() instead.
665
+ *
666
+ * When done with this music, the app should dispose of it with a call to
667
+ * Mix_FreeMusic().
668
+ *
669
+ * \param src an SDL_RWops that data will be read from.
670
+ * \param freesrc non-zero to close/free the SDL_RWops before returning, zero
671
+ * to leave it open.
672
+ * \returns a new music object, or NULL on error.
673
+ *
674
+ * \since This function is available since SDL_mixer 2.0.0.
675
+ *
676
+ * \sa Mix_FreeMusic
461
677
  */
462
- extern DECLSPEC int SDLCALL Mix_SetDistance(int channel, Uint8 distance);
463
-
678
+ extern DECLSPEC Mix_Music * SDLCALL Mix_LoadMUS_RW(SDL_RWops *src, int freesrc);
464
679
 
465
- /*
466
- * !!! FIXME : Haven't implemented, since the effect goes past the
467
- * end of the sound buffer. Will have to think about this.
468
- * --ryan.
469
- */
470
- #if 0
471
- /* Causes an echo effect to be mixed into a sound. (echo) is the amount
472
- * of echo to mix. 0 is no echo, 255 is infinite (and probably not
473
- * what you want).
680
+ /**
681
+ * Load an audio format into a music object, assuming a specific format.
682
+ *
683
+ * SDL_mixer has two separate data structures for audio data. One it calls a
684
+ * "chunk," which is meant to be a file completely decoded into memory up
685
+ * front, and the other it calls "music" which is a file intended to be
686
+ * decoded on demand. Originally, simple formats like uncompressed WAV files
687
+ * were meant to be chunks and compressed things, like MP3s, were meant to be
688
+ * music, and you would stream one thing for a game's music and make repeating
689
+ * sound effects with the chunks.
690
+ *
691
+ * In modern times, this isn't split by format anymore, and most are
692
+ * interchangeable, so the question is what the app thinks is worth
693
+ * predecoding or not. Chunks might take more memory, but once they are loaded
694
+ * won't need to decode again, whereas music always needs to be decoded on the
695
+ * fly. Also, crucially, there are as many channels for chunks as the app can
696
+ * allocate, but SDL_mixer only offers a single "music" channel.
697
+ *
698
+ * This function loads music data, and lets the application specify the type
699
+ * of music being loaded, which might be useful if SDL_mixer cannot figure it
700
+ * out from the data stream itself.
701
+ *
702
+ * Currently, the following types are supported:
474
703
  *
475
- * Setting (channel) to MIX_CHANNEL_POST registers this as a posteffect, and
476
- * the reverbing will be done to the final mixed stream before passing it on
477
- * to the audio device.
704
+ * - `MUS_NONE` (SDL_mixer should guess, based on the data)
705
+ * - `MUS_WAV` (Microsoft WAV files)
706
+ * - `MUS_MOD` (Various tracker formats)
707
+ * - `MUS_MID` (MIDI files)
708
+ * - `MUS_OGG` (Ogg Vorbis files)
709
+ * - `MUS_MP3` (MP3 files)
710
+ * - `MUS_FLAC` (FLAC files)
711
+ * - `MUS_OPUS` (Opus files)
478
712
  *
479
- * This uses the Mix_RegisterEffect() API internally. If you specify an echo
480
- * of zero, the effect is unregistered, as the data is already in that state.
713
+ * If `freesrc` is non-zero, the RWops will be closed before returning,
714
+ * whether this function succeeds or not. SDL_mixer reads everything it needs
715
+ * from the RWops during this call in any case.
481
716
  *
482
- * returns zero if error (no such channel or Mix_RegisterEffect() fails),
483
- * nonzero if reversing effect is enabled.
484
- * Error messages can be retrieved from Mix_GetError().
717
+ * As a convenience, there is a function to read files from disk without
718
+ * having to deal with SDL_RWops: `Mix_LoadMUS("filename.mp3")` will manage
719
+ * those details for you (but not let you specify the music type explicitly)..
720
+ *
721
+ * When done with this music, the app should dispose of it with a call to
722
+ * Mix_FreeMusic().
723
+ *
724
+ * \param src an SDL_RWops that data will be read from.
725
+ * \param type the type of audio data provided by `src`.
726
+ * \param freesrc non-zero to close/free the SDL_RWops before returning, zero
727
+ * to leave it open.
728
+ * \returns a new music object, or NULL on error.
729
+ *
730
+ * \since This function is available since SDL_mixer 2.0.0.
731
+ *
732
+ * \sa Mix_FreeMusic
485
733
  */
486
- extern no_parse_DECLSPEC int SDLCALL Mix_SetReverb(int channel, Uint8 echo);
487
- #endif
734
+ extern DECLSPEC Mix_Music * SDLCALL Mix_LoadMUSType_RW(SDL_RWops *src, Mix_MusicType type, int freesrc);
488
735
 
489
- /* Causes a channel to reverse its stereo. This is handy if the user has his
490
- * speakers hooked up backwards, or you would like to have a minor bit of
491
- * psychedelia in your sound code. :) Calling this function with (flip)
492
- * set to non-zero reverses the chunks's usual channels. If (flip) is zero,
493
- * the effect is unregistered.
736
+ /**
737
+ * Load a WAV file from memory as quickly as possible.
494
738
  *
495
- * This uses the Mix_RegisterEffect() API internally, and thus is probably
496
- * more CPU intensive than having the user just plug in his speakers
497
- * correctly. Mix_SetReverseStereo() returns without registering the effect
498
- * function if the audio device is not configured for stereo output.
739
+ * Unlike Mix_LoadWAV_RW, this function has several requirements, and unless
740
+ * you control all your audio data and know what you're doing, you should
741
+ * consider this function unsafe and not use it.
499
742
  *
500
- * If you specify MIX_CHANNEL_POST for (channel), then this the effect is used
501
- * on the final mixed stream before sending it on to the audio device (a
502
- * posteffect).
743
+ * - The provided audio data MUST be in Microsoft WAV format.
744
+ * - The provided audio data shouldn't use any strange WAV extensions.
745
+ * - The audio data MUST be in the exact same format as the audio device. This
746
+ * function will not attempt to convert it, or even verify it's in the right
747
+ * format.
748
+ * - The audio data must be valid; this function does not know the size of the
749
+ * memory buffer, so if the WAV data is corrupted, it can read past the end
750
+ * of the buffer, causing a crash.
751
+ * - The audio data must live at least as long as the returned Mix_Chunk,
752
+ * because SDL_mixer will use that data directly and not make a copy of it.
503
753
  *
504
- * returns zero if error (no such channel or Mix_RegisterEffect() fails),
505
- * nonzero if reversing effect is enabled. Note that an audio device in mono
506
- * mode is a no-op, but this call will return successful in that case.
507
- * Error messages can be retrieved from Mix_GetError().
754
+ * This function will do NO error checking! Be extremely careful here!
755
+ *
756
+ * (Seriously, use Mix_LoadWAV_RW instead.)
757
+ *
758
+ * If this function is successful, the provided memory buffer must remain
759
+ * available until Mix_FreeChunk() is called on the returned chunk.
760
+ *
761
+ * \param mem memory buffer containing of a WAV file.
762
+ * \returns a new chunk, or NULL on error.
763
+ *
764
+ * \since This function is available since SDL_mixer 2.0.0.
765
+ *
766
+ * \sa Mix_LoadWAV_RW
767
+ * \sa Mix_FreeChunk
508
768
  */
509
- extern DECLSPEC int SDLCALL Mix_SetReverseStereo(int channel, int flip);
510
-
511
- /* end of effects API. --ryan. */
769
+ extern DECLSPEC Mix_Chunk * SDLCALL Mix_QuickLoad_WAV(Uint8 *mem);
512
770
 
771
+ /**
772
+ * Load a raw audio data from memory as quickly as possible.
773
+ *
774
+ * The audio data MUST be in the exact same format as the audio device. This
775
+ * function will not attempt to convert it, or even verify it's in the right
776
+ * format.
777
+ *
778
+ * If this function is successful, the provided memory buffer must remain
779
+ * available until Mix_FreeChunk() is called on the returned chunk.
780
+ *
781
+ * \param mem memory buffer containing raw PCM data.
782
+ * \param len length of buffer pointed to by `mem`, in bytes.
783
+ * \returns a new chunk, or NULL on error.
784
+ *
785
+ * \since This function is available since SDL_mixer 2.0.0.
786
+ *
787
+ * \sa Mix_FreeChunk
788
+ */
789
+ extern DECLSPEC Mix_Chunk * SDLCALL Mix_QuickLoad_RAW(Uint8 *mem, Uint32 len);
790
+
791
+ /**
792
+ * Free an audio chunk.
793
+ *
794
+ * An app should call this function when it is done with a Mix_Chunk and wants
795
+ * to dispose of its resources.
796
+ *
797
+ * SDL_mixer will stop any channels this chunk is currently playing on. This
798
+ * will deregister all effects on those channels and call any callback
799
+ * specified by Mix_ChannelFinished() for each removed channel.
800
+ *
801
+ * \param chunk the chunk to free.
802
+ *
803
+ * \since This function is available since SDL_mixer 2.0.0.
804
+ *
805
+ * \sa Mix_LoadWAV
806
+ * \sa Mix_LoadWAV_RW
807
+ * \sa Mix_QuickLoad_WAV
808
+ * \sa Mix_QuickLoad_RAW
809
+ */
810
+ extern DECLSPEC void SDLCALL Mix_FreeChunk(Mix_Chunk *chunk);
811
+
812
+ /**
813
+ * Free a music object.
814
+ *
815
+ * If this music is currently playing, it will be stopped.
816
+ *
817
+ * If this music is in the process of fading out (via Mix_FadeOutMusic()),
818
+ * this function will *block* until the fade completes. If you need to avoid
819
+ * this, be sure to call Mix_HaltMusic() before freeing the music.
820
+ *
821
+ * \param music the music object to free.
822
+ *
823
+ * \since This function is available since SDL_mixer 2.0.0.
824
+ *
825
+ * \sa Mix_LoadMUS
826
+ * \sa Mix_LoadMUS_RW
827
+ * \sa Mix_LoadMUSType_RW
828
+ */
829
+ extern DECLSPEC void SDLCALL Mix_FreeMusic(Mix_Music *music);
830
+
831
+ /**
832
+ * Get a list of chunk decoders that this build of SDL_mixer provides.
833
+ *
834
+ * This list can change between builds AND runs of the program, if external
835
+ * libraries that add functionality become available. You must successfully
836
+ * call Mix_OpenAudio() or Mix_OpenAudioDevice() before calling this function,
837
+ * as decoders are activated at device open time.
838
+ *
839
+ * Appearing in this list doesn't promise your specific audio file will
840
+ * decode...but it's handy to know if you have, say, a functioning Ogg Vorbis
841
+ * install.
842
+ *
843
+ * These return values are static, read-only data; do not modify or free it.
844
+ * The pointers remain valid until you call Mix_CloseAudio().
845
+ *
846
+ * \returns number of chunk decoders available.
847
+ *
848
+ * \since This function is available since SDL_mixer 2.0.0.
849
+ *
850
+ * \sa Mix_GetChunkDecoder
851
+ * \sa Mix_HasChunkDecoder
852
+ */
853
+ extern DECLSPEC int SDLCALL Mix_GetNumChunkDecoders(void);
854
+
855
+ /**
856
+ * Get a chunk decoder's name.
857
+ *
858
+ * The requested decoder's index must be between zero and
859
+ * Mix_GetNumChunkDecoders()-1. It's safe to call this with an invalid index;
860
+ * this function will return NULL in that case.
861
+ *
862
+ * This list can change between builds AND runs of the program, if external
863
+ * libraries that add functionality become available. You must successfully
864
+ * call Mix_OpenAudio() or Mix_OpenAudioDevice() before calling this function,
865
+ * as decoders are activated at device open time.
866
+ *
867
+ * \param index index of the chunk decoder.
868
+ * \returns the chunk decoder's name.
869
+ *
870
+ * \since This function is available since SDL_mixer 2.0.0.
871
+ *
872
+ * \sa Mix_GetNumChunkDecoders
873
+ */
874
+ extern DECLSPEC const char * SDLCALL Mix_GetChunkDecoder(int index);
875
+
876
+ /**
877
+ * Check if a chunk decoder is available by name.
878
+ *
879
+ * This result can change between builds AND runs of the program, if external
880
+ * libraries that add functionality become available. You must successfully
881
+ * call Mix_OpenAudio() or Mix_OpenAudioDevice() before calling this function,
882
+ * as decoders are activated at device open time.
883
+ *
884
+ * Decoder names are arbitrary but also obvious, so you have to know what
885
+ * you're looking for ahead of time, but usually it's the file extension in
886
+ * capital letters (some example names are "AIFF", "VOC", "WAV").
887
+ *
888
+ * \param name the decoder name to query.
889
+ * \returns SDL_TRUE if a decoder by that name is available, SDL_FALSE
890
+ * otherwise.
891
+ *
892
+ * \since This function is available since SDL_mixer 2.0.2.
893
+ *
894
+ * \sa Mix_GetNumChunkDecoders
895
+ * \sa Mix_GetChunkDecoder
896
+ */
897
+ extern DECLSPEC SDL_bool SDLCALL Mix_HasChunkDecoder(const char *name);
898
+
899
+ /**
900
+ * Get a list of music decoders that this build of SDL_mixer provides.
901
+ *
902
+ * This list can change between builds AND runs of the program, if external
903
+ * libraries that add functionality become available. You must successfully
904
+ * call Mix_OpenAudio() or Mix_OpenAudioDevice() before calling this function,
905
+ * as decoders are activated at device open time.
906
+ *
907
+ * Appearing in this list doesn't promise your specific audio file will
908
+ * decode...but it's handy to know if you have, say, a functioning Ogg Vorbis
909
+ * install.
910
+ *
911
+ * These return values are static, read-only data; do not modify or free it.
912
+ * The pointers remain valid until you call Mix_CloseAudio().
913
+ *
914
+ * \returns number of chunk decoders available.
915
+ *
916
+ * \since This function is available since SDL_mixer 2.0.0.
917
+ *
918
+ * \sa Mix_GetMusicDecoder
919
+ * \sa Mix_HasMusicDecoder
920
+ */
921
+ extern DECLSPEC int SDLCALL Mix_GetNumMusicDecoders(void);
922
+
923
+ /**
924
+ * Get a music decoder's name.
925
+ *
926
+ * The requested decoder's index must be between zero and
927
+ * Mix_GetNumMusicDecoders()-1. It's safe to call this with an invalid index;
928
+ * this function will return NULL in that case.
929
+ *
930
+ * This list can change between builds AND runs of the program, if external
931
+ * libraries that add functionality become available. You must successfully
932
+ * call Mix_OpenAudio() or Mix_OpenAudioDevice() before calling this function,
933
+ * as decoders are activated at device open time.
934
+ *
935
+ * \param index index of the music decoder.
936
+ * \returns the music decoder's name.
937
+ *
938
+ * \since This function is available since SDL_mixer 2.0.0.
939
+ *
940
+ * \sa Mix_GetNumMusicDecoders
941
+ */
942
+ extern DECLSPEC const char * SDLCALL Mix_GetMusicDecoder(int index);
943
+
944
+ /**
945
+ * Check if a music decoder is available by name.
946
+ *
947
+ * This result can change between builds AND runs of the program, if external
948
+ * libraries that add functionality become available. You must successfully
949
+ * call Mix_OpenAudio() or Mix_OpenAudioDevice() before calling this function,
950
+ * as decoders are activated at device open time.
951
+ *
952
+ * Decoder names are arbitrary but also obvious, so you have to know what
953
+ * you're looking for ahead of time, but usually it's the file extension in
954
+ * capital letters (some example names are "MOD", "MP3", "FLAC").
955
+ *
956
+ * \param name the decoder name to query.
957
+ * \returns SDL_TRUE if a decoder by that name is available, SDL_FALSE
958
+ * otherwise.
959
+ *
960
+ * \since This function is available since SDL_mixer 2.6.0
961
+ *
962
+ * \sa Mix_GetNumMusicDecoders
963
+ * \sa Mix_GetMusicDecoder
964
+ */
965
+ extern DECLSPEC SDL_bool SDLCALL Mix_HasMusicDecoder(const char *name);
966
+
967
+ /**
968
+ * Find out the format of a mixer music.
969
+ *
970
+ * If `music` is NULL, this will query the currently playing music (and return
971
+ * MUS_NONE if nothing is currently playing).
972
+ *
973
+ * \param music the music object to query, or NULL for the currently-playing
974
+ * music.
975
+ * \returns the Mix_MusicType for the music object.
976
+ *
977
+ * \since This function is available since SDL_mixer 2.0.0
978
+ */
979
+ extern DECLSPEC Mix_MusicType SDLCALL Mix_GetMusicType(const Mix_Music *music);
980
+
981
+ /**
982
+ * Get the title for a music object, or its filename.
983
+ *
984
+ * This returns format-specific metadata. Not all file formats supply this!
985
+ *
986
+ * If `music` is NULL, this will query the currently-playing music.
987
+ *
988
+ * If music's title tag is missing or empty, the filename will be returned. If
989
+ * you'd rather have the actual metadata or nothing, use
990
+ * Mix_GetMusicTitleTag() instead.
991
+ *
992
+ * Please note that if the music was loaded from an SDL_RWops instead of a
993
+ * filename, the filename returned will be an empty string ("").
994
+ *
995
+ * This function never returns NULL! If no data is available, it will return
996
+ * an empty string ("").
997
+ *
998
+ * \param music the music object to query, or NULL for the currently-playing
999
+ * music.
1000
+ * \returns the music's title if available, or the filename if not, or "".
1001
+ *
1002
+ * \since This function is available since SDL_mixer 2.6.0.
1003
+ *
1004
+ * \sa Mix_GetMusicTitleTag
1005
+ * \sa Mix_GetMusicArtistTag
1006
+ * \sa Mix_GetMusicAlbumTag
1007
+ * \sa Mix_GetMusicCopyrightTag
1008
+ */
1009
+ extern DECLSPEC const char *SDLCALL Mix_GetMusicTitle(const Mix_Music *music);
1010
+
1011
+ /**
1012
+ * Get the title for a music object.
1013
+ *
1014
+ * This returns format-specific metadata. Not all file formats supply this!
1015
+ *
1016
+ * If `music` is NULL, this will query the currently-playing music.
1017
+ *
1018
+ * Unlike this function, Mix_GetMusicTitle() produce a string with the music's
1019
+ * filename if a title isn't available, which might be preferable for some
1020
+ * applications.
1021
+ *
1022
+ * This function never returns NULL! If no data is available, it will return
1023
+ * an empty string ("").
1024
+ *
1025
+ * \param music the music object to query, or NULL for the currently-playing
1026
+ * music.
1027
+ * \returns the music's title if available, or "".
1028
+ *
1029
+ * \since This function is available since SDL_mixer 2.6.0.
1030
+ *
1031
+ * \sa Mix_GetMusicTitle
1032
+ * \sa Mix_GetMusicArtistTag
1033
+ * \sa Mix_GetMusicAlbumTag
1034
+ * \sa Mix_GetMusicCopyrightTag
1035
+ */
1036
+ extern DECLSPEC const char *SDLCALL Mix_GetMusicTitleTag(const Mix_Music *music);
1037
+
1038
+ /**
1039
+ * Get the artist name for a music object.
1040
+ *
1041
+ * This returns format-specific metadata. Not all file formats supply this!
1042
+ *
1043
+ * If `music` is NULL, this will query the currently-playing music.
1044
+ *
1045
+ * This function never returns NULL! If no data is available, it will return
1046
+ * an empty string ("").
1047
+ *
1048
+ * \param music the music object to query, or NULL for the currently-playing
1049
+ * music.
1050
+ * \returns the music's artist name if available, or "".
1051
+ *
1052
+ * \since This function is available since SDL_mixer 2.6.0.
1053
+ *
1054
+ * \sa Mix_GetMusicTitleTag
1055
+ * \sa Mix_GetMusicAlbumTag
1056
+ * \sa Mix_GetMusicCopyrightTag
1057
+ */
1058
+ extern DECLSPEC const char *SDLCALL Mix_GetMusicArtistTag(const Mix_Music *music);
1059
+
1060
+ /**
1061
+ * Get the album name for a music object.
1062
+ *
1063
+ * This returns format-specific metadata. Not all file formats supply this!
1064
+ *
1065
+ * If `music` is NULL, this will query the currently-playing music.
1066
+ *
1067
+ * This function never returns NULL! If no data is available, it will return
1068
+ * an empty string ("").
1069
+ *
1070
+ * \param music the music object to query, or NULL for the currently-playing
1071
+ * music.
1072
+ * \returns the music's album name if available, or "".
1073
+ *
1074
+ * \since This function is available since SDL_mixer 2.6.0.
1075
+ *
1076
+ * \sa Mix_GetMusicTitleTag
1077
+ * \sa Mix_GetMusicArtistTag
1078
+ * \sa Mix_GetMusicCopyrightTag
1079
+ */
1080
+ extern DECLSPEC const char *SDLCALL Mix_GetMusicAlbumTag(const Mix_Music *music);
1081
+
1082
+ /**
1083
+ * Get the copyright text for a music object.
1084
+ *
1085
+ * This returns format-specific metadata. Not all file formats supply this!
1086
+ *
1087
+ * If `music` is NULL, this will query the currently-playing music.
1088
+ *
1089
+ * This function never returns NULL! If no data is available, it will return
1090
+ * an empty string ("").
1091
+ *
1092
+ * \param music the music object to query, or NULL for the currently-playing
1093
+ * music.
1094
+ * \returns the music's copyright text if available, or "".
1095
+ *
1096
+ * \since This function is available since SDL_mixer 2.6.0.
1097
+ *
1098
+ * \sa Mix_GetMusicTitleTag
1099
+ * \sa Mix_GetMusicArtistTag
1100
+ * \sa Mix_GetMusicAlbumTag
1101
+ */
1102
+ extern DECLSPEC const char *SDLCALL Mix_GetMusicCopyrightTag(const Mix_Music *music);
1103
+
1104
+ /**
1105
+ * Set a function that is called after all mixing is performed.
1106
+ *
1107
+ * This can be used to provide real-time visual display of the audio stream or
1108
+ * add a custom mixer filter for the stream data.
1109
+ *
1110
+ * The callback will fire every time SDL_mixer is ready to supply more data to
1111
+ * the audio device, after it has finished all its mixing work. This runs
1112
+ * inside an SDL audio callback, so it's important that the callback return
1113
+ * quickly, or there could be problems in the audio playback.
1114
+ *
1115
+ * The data provided to the callback is in the format that the audio device
1116
+ * was opened in, and it represents the exact waveform SDL_mixer has mixed
1117
+ * from all playing chunks and music for playback. You are allowed to modify
1118
+ * the data, but it cannot be resized (so you can't add a reverb effect that
1119
+ * goes past the end of the buffer without saving some state between runs to
1120
+ * add it into the next callback, or resample the buffer to a smaller size to
1121
+ * speed it up, etc).
1122
+ *
1123
+ * The `arg` pointer supplied here is passed to the callback as-is, for
1124
+ * whatever the callback might want to do with it (keep track of some ongoing
1125
+ * state, settings, etc).
1126
+ *
1127
+ * Passing a NULL callback disables the post-mix callback until such a time as
1128
+ * a new one callback is set.
1129
+ *
1130
+ * There is only one callback available. If you need to mix multiple inputs,
1131
+ * be prepared to handle them from a single function.
1132
+ *
1133
+ * \param mix_func the callback function to become the new post-mix callback.
1134
+ * \param arg a pointer that is passed, untouched, to the callback.
1135
+ *
1136
+ * \since This function is available since SDL_mixer 2.0.0.
1137
+ *
1138
+ * \sa Mix_HookMusic
1139
+ */
1140
+ extern DECLSPEC void SDLCALL Mix_SetPostMix(void (SDLCALL *mix_func)(void *udata, Uint8 *stream, int len), void *arg);
1141
+
1142
+ /**
1143
+ * Add your own music player or additional mixer function.
1144
+ *
1145
+ * This works something like Mix_SetPostMix(), but it has some crucial
1146
+ * differences. Note that an app can use this _and_ Mix_SetPostMix() at the
1147
+ * same time. This allows an app to replace the built-in music playback,
1148
+ * either with it's own music decoder or with some sort of
1149
+ * procedurally-generated audio output.
1150
+ *
1151
+ * The supplied callback will fire every time SDL_mixer is preparing to supply
1152
+ * more data to the audio device. This runs inside an SDL audio callback, so
1153
+ * it's important that the callback return quickly, or there could be problems
1154
+ * in the audio playback.
1155
+ *
1156
+ * Running this callback is the first thing SDL_mixer will do when starting to
1157
+ * mix more audio. The buffer will contain silence upon entry, so the callback
1158
+ * does not need to mix into existing data or initialize the buffer.
1159
+ *
1160
+ * Note that while a callback is set through this function, SDL_mixer will not
1161
+ * mix any playing music; this callback is used instead. To disable this
1162
+ * callback (and thus reenable built-in music playback) call this function
1163
+ * with a NULL callback.
1164
+ *
1165
+ * The data written to by the callback is in the format that the audio device
1166
+ * was opened in, and upon return from the callback, SDL_mixer will mix any
1167
+ * playing chunks (but not music!) into the buffer. The callback cannot resize
1168
+ * the buffer (so you must be prepared to provide exactly the amount of data
1169
+ * demanded or leave it as silence).
1170
+ *
1171
+ * The `arg` pointer supplied here is passed to the callback as-is, for
1172
+ * whatever the callback might want to do with it (keep track of some ongoing
1173
+ * state, settings, etc).
1174
+ *
1175
+ * As there is only one music "channel" mixed, there is only one callback
1176
+ * available. If you need to mix multiple inputs, be prepared to handle them
1177
+ * from a single function.
1178
+ *
1179
+ * \param mix_func the callback function to become the new post-mix callback.
1180
+ * \param arg a pointer that is passed, untouched, to the callback.
1181
+ *
1182
+ * \since This function is available since SDL_mixer 2.0.0.
1183
+ *
1184
+ * \sa Mix_SetPostMix
1185
+ */
1186
+ extern DECLSPEC void SDLCALL Mix_HookMusic(void (SDLCALL *mix_func)(void *udata, Uint8 *stream, int len), void *arg);
1187
+
1188
+ /**
1189
+ * Set a callback that runs when a music object has stopped playing.
1190
+ *
1191
+ * This callback will fire when the currently-playing music has completed, or
1192
+ * when it has been explicitly stopped from a call to Mix_HaltMusic. As such,
1193
+ * this callback might fire from an arbitrary background thread at almost any
1194
+ * time; try to limit what you do here.
1195
+ *
1196
+ * It is legal to start a new music object playing in this callback (or
1197
+ * restart the one that just stopped). If the music finished normally, this
1198
+ * can be used to loop the music without a gap in the audio playback.
1199
+ *
1200
+ * Do not call SDL_LockAudio() from this callback; you will either be inside
1201
+ * the audio callback, or SDL_mixer will explicitly lock the audio before
1202
+ * calling your callback.
1203
+ *
1204
+ * A NULL pointer will disable the callback.
1205
+ *
1206
+ * \param music_finished the callback function to become the new notification
1207
+ * mechanism.
1208
+ *
1209
+ * \since This function is available since SDL_mixer 2.0.0.
1210
+ */
1211
+ extern DECLSPEC void SDLCALL Mix_HookMusicFinished(void (SDLCALL *music_finished)(void));
1212
+
1213
+ /**
1214
+ * Get a pointer to the user data for the current music hook.
1215
+ *
1216
+ * This returns the `arg` pointer last passed to Mix_HookMusic(), or NULL if
1217
+ * that function has never been called.
1218
+ *
1219
+ * \returns pointer to the user data previously passed to Mix_HookMusic.
1220
+ *
1221
+ * \since This function is available since SDL_mixer 2.0.0.
1222
+ */
1223
+ extern DECLSPEC void * SDLCALL Mix_GetMusicHookData(void);
1224
+
1225
+ /**
1226
+ * Set a callback that runs when a channel has finished playing.
1227
+ *
1228
+ * The callback may be called from the mixer's audio callback or it could be
1229
+ * called as a result of Mix_HaltChannel(), etc.
1230
+ *
1231
+ * The callback has a single parameter, `channel`, which says what mixer
1232
+ * channel has just stopped.
1233
+ *
1234
+ * Do not call SDL_LockAudio() from this callback; you will either be inside
1235
+ * the audio callback, or SDL_mixer will explicitly lock the audio before
1236
+ * calling your callback.
1237
+ *
1238
+ * A NULL pointer will disable the callback.
1239
+ *
1240
+ * \param channel_finished the callback function to become the new
1241
+ * notification mechanism.
1242
+ *
1243
+ * \since This function is available since SDL_mixer 2.0.0.
1244
+ */
1245
+ extern DECLSPEC void SDLCALL Mix_ChannelFinished(void (SDLCALL *channel_finished)(int channel));
1246
+
1247
+
1248
+ #define MIX_CHANNEL_POST (-2)
1249
+
1250
+ /**
1251
+ * This is the format of a special effect callback:
1252
+ *
1253
+ * myeffect(int chan, void *stream, int len, void *udata);
1254
+ *
1255
+ * (chan) is the channel number that your effect is affecting. (stream) is
1256
+ * the buffer of data to work upon. (len) is the size of (stream), and
1257
+ * (udata) is a user-defined bit of data, which you pass as the last arg of
1258
+ * Mix_RegisterEffect(), and is passed back unmolested to your callback.
1259
+ * Your effect changes the contents of (stream) based on whatever parameters
1260
+ * are significant, or just leaves it be, if you prefer. You can do whatever
1261
+ * you like to the buffer, though, and it will continue in its changed state
1262
+ * down the mixing pipeline, through any other effect functions, then finally
1263
+ * to be mixed with the rest of the channels and music for the final output
1264
+ * stream.
1265
+ *
1266
+ * DO NOT EVER call SDL_LockAudio() from your callback function!
1267
+ */
1268
+ typedef void (SDLCALL *Mix_EffectFunc_t)(int chan, void *stream, int len, void *udata);
1269
+
1270
+ /**
1271
+ * This is a callback that signifies that a channel has finished all its
1272
+ * loops and has completed playback. This gets called if the buffer
1273
+ * plays out normally, or if you call Mix_HaltChannel(), implicitly stop
1274
+ * a channel via Mix_AllocateChannels(), or unregister a callback while
1275
+ * it's still playing.
1276
+ *
1277
+ * DO NOT EVER call SDL_LockAudio() from your callback function!
1278
+ */
1279
+ typedef void (SDLCALL *Mix_EffectDone_t)(int chan, void *udata);
1280
+
1281
+
1282
+ /**
1283
+ * Register a special effect function.
1284
+ *
1285
+ * At mixing time, the channel data is copied into a buffer and passed through
1286
+ * each registered effect function. After it passes through all the functions,
1287
+ * it is mixed into the final output stream. The copy to buffer is performed
1288
+ * once, then each effect function performs on the output of the previous
1289
+ * effect. Understand that this extra copy to a buffer is not performed if
1290
+ * there are no effects registered for a given chunk, which saves CPU cycles,
1291
+ * and any given effect will be extra cycles, too, so it is crucial that your
1292
+ * code run fast. Also note that the data that your function is given is in
1293
+ * the format of the sound device, and not the format you gave to
1294
+ * Mix_OpenAudio(), although they may in reality be the same. This is an
1295
+ * unfortunate but necessary speed concern. Use Mix_QuerySpec() to determine
1296
+ * if you can handle the data before you register your effect, and take
1297
+ * appropriate actions.
1298
+ *
1299
+ * You may also specify a callback (Mix_EffectDone_t) that is called when the
1300
+ * channel finishes playing. This gives you a more fine-grained control than
1301
+ * Mix_ChannelFinished(), in case you need to free effect-specific resources,
1302
+ * etc. If you don't need this, you can specify NULL.
1303
+ *
1304
+ * You may set the callbacks before or after calling Mix_PlayChannel().
1305
+ *
1306
+ * Things like Mix_SetPanning() are just internal special effect functions, so
1307
+ * if you are using that, you've already incurred the overhead of a copy to a
1308
+ * separate buffer, and that these effects will be in the queue with any
1309
+ * functions you've registered. The list of registered effects for a channel
1310
+ * is reset when a chunk finishes playing, so you need to explicitly set them
1311
+ * with each call to Mix_PlayChannel*().
1312
+ *
1313
+ * You may also register a special effect function that is to be run after
1314
+ * final mixing occurs. The rules for these callbacks are identical to those
1315
+ * in Mix_RegisterEffect, but they are run after all the channels and the
1316
+ * music have been mixed into a single stream, whereas channel-specific
1317
+ * effects run on a given channel before any other mixing occurs. These global
1318
+ * effect callbacks are call "posteffects". Posteffects only have their
1319
+ * Mix_EffectDone_t function called when they are unregistered (since the main
1320
+ * output stream is never "done" in the same sense as a channel). You must
1321
+ * unregister them manually when you've had enough. Your callback will be told
1322
+ * that the channel being mixed is `MIX_CHANNEL_POST` if the processing is
1323
+ * considered a posteffect.
1324
+ *
1325
+ * After all these effects have finished processing, the callback registered
1326
+ * through Mix_SetPostMix() runs, and then the stream goes to the audio
1327
+ * device.
1328
+ *
1329
+ * DO NOT EVER call SDL_LockAudio() from your callback function! You are
1330
+ * already running in the audio thread and the lock is already held!
1331
+ *
1332
+ * Note that unlike most SDL and SDL_mixer functions, this function returns
1333
+ * zero if there's an error, not on success. We apologize for the API design
1334
+ * inconsistency here.
1335
+ *
1336
+ * \param chan the channel to register an effect to, or MIX_CHANNEL_POST.
1337
+ * \param f effect the callback to run when more of this channel is to be
1338
+ * mixed.
1339
+ * \param d effect done callback
1340
+ * \param arg argument
1341
+ * \returns zero if error (no such channel), nonzero if added. Error messages
1342
+ * can be retrieved from Mix_GetError().
1343
+ *
1344
+ * \since This function is available since SDL_mixer 2.0.0.
1345
+ */
1346
+ extern DECLSPEC int SDLCALL Mix_RegisterEffect(int chan, Mix_EffectFunc_t f, Mix_EffectDone_t d, void *arg);
1347
+
1348
+
1349
+ /**
1350
+ * Explicitly unregister a special effect function.
1351
+ *
1352
+ * You may not need to call this at all, unless you need to stop an effect
1353
+ * from processing in the middle of a chunk's playback.
1354
+ *
1355
+ * Posteffects are never implicitly unregistered as they are for channels (as
1356
+ * the output stream does not have an end), but they may be explicitly
1357
+ * unregistered through this function by specifying MIX_CHANNEL_POST for a
1358
+ * channel.
1359
+ *
1360
+ * Note that unlike most SDL and SDL_mixer functions, this function returns
1361
+ * zero if there's an error, not on success. We apologize for the API design
1362
+ * inconsistency here.
1363
+ *
1364
+ * \param chan the channel to unregister an effect on, or MIX_CHANNEL_POST.
1365
+ * \param f effect the callback stop calling in future mixing iterations.
1366
+ * \returns zero if error (no such channel or effect), nonzero if removed.
1367
+ * Error messages can be retrieved from Mix_GetError().
1368
+ *
1369
+ * \since This function is available since SDL_mixer 2.0.0.
1370
+ */
1371
+ extern DECLSPEC int SDLCALL Mix_UnregisterEffect(int channel, Mix_EffectFunc_t f);
1372
+
1373
+ /**
1374
+ * Explicitly unregister all special effect functions.
1375
+ *
1376
+ * You may not need to call this at all, unless you need to stop all effects
1377
+ * from processing in the middle of a chunk's playback.
1378
+ *
1379
+ * Note that this will also shut off some internal effect processing, since
1380
+ * Mix_SetPanning() and others may use this API under the hood. This is called
1381
+ * internally when a channel completes playback. Posteffects are never
1382
+ * implicitly unregistered as they are for channels, but they may be
1383
+ * explicitly unregistered through this function by specifying
1384
+ * MIX_CHANNEL_POST for a channel.
1385
+ *
1386
+ * Note that unlike most SDL and SDL_mixer functions, this function returns
1387
+ * zero if there's an error, not on success. We apologize for the API design
1388
+ * inconsistency here.
1389
+ *
1390
+ * \param chan the channel to unregister all effects on, or MIX_CHANNEL_POST.
1391
+ * \returns zero if error (no such channel), nonzero if all effects removed.
1392
+ * Error messages can be retrieved from Mix_GetError().
1393
+ *
1394
+ * \since This function is available since SDL_mixer 2.0.0.
1395
+ */
1396
+ extern DECLSPEC int SDLCALL Mix_UnregisterAllEffects(int channel);
1397
+
1398
+
1399
+ #define MIX_EFFECTSMAXSPEED "MIX_EFFECTSMAXSPEED"
1400
+
1401
+ /*
1402
+ * These are the internally-defined mixing effects. They use the same API that
1403
+ * effects defined in the application use, but are provided here as a
1404
+ * convenience. Some effects can reduce their quality or use more memory in
1405
+ * the name of speed; to enable this, make sure the environment variable
1406
+ * MIX_EFFECTSMAXSPEED (see above) is defined before you call
1407
+ * Mix_OpenAudio().
1408
+ */
1409
+
1410
+
1411
+ /**
1412
+ * Set the panning of a channel.
1413
+ *
1414
+ * The left and right channels are specified as integers between 0 and 255,
1415
+ * quietest to loudest, respectively.
1416
+ *
1417
+ * Technically, this is just individual volume control for a sample with two
1418
+ * (stereo) channels, so it can be used for more than just panning. If you
1419
+ * want real panning, call it like this:
1420
+ *
1421
+ * ```c
1422
+ * Mix_SetPanning(channel, left, 255 - left);
1423
+ * ```
1424
+ *
1425
+ * Setting `channel` to MIX_CHANNEL_POST registers this as a posteffect, and
1426
+ * the panning will be done to the final mixed stream before passing it on to
1427
+ * the audio device.
1428
+ *
1429
+ * This uses the Mix_RegisterEffect() API internally, and returns without
1430
+ * registering the effect function if the audio device is not configured for
1431
+ * stereo output. Setting both `left` and `right` to 255 causes this effect to
1432
+ * be unregistered, since that is the data's normal state.
1433
+ *
1434
+ * Note that an audio device in mono mode is a no-op, but this call will
1435
+ * return successful in that case. Error messages can be retrieved from
1436
+ * Mix_GetError().
1437
+ *
1438
+ * Note that unlike most SDL and SDL_mixer functions, this function returns
1439
+ * zero if there's an error, not on success. We apologize for the API design
1440
+ * inconsistency here.
1441
+ *
1442
+ * \param channel The mixer channel to pan or MIX_CHANNEL_POST.
1443
+ * \param left Volume of stereo left channel, 0 is silence, 255 is full
1444
+ * volume.
1445
+ * \param right Volume of stereo right channel, 0 is silence, 255 is full
1446
+ * volume.
1447
+ * \returns zero if error (no such channel or Mix_RegisterEffect() fails),
1448
+ * nonzero if panning effect enabled.
1449
+ *
1450
+ * \since This function is available since SDL_mixer 2.0.0.
1451
+ *
1452
+ * \sa Mix_SetPosition
1453
+ * \sa Mix_SetDistance
1454
+ */
1455
+ extern DECLSPEC int SDLCALL Mix_SetPanning(int channel, Uint8 left, Uint8 right);
1456
+
1457
+
1458
+ /**
1459
+ * Set the position of a channel.
1460
+ *
1461
+ * `angle` is an integer from 0 to 360, that specifies the location of the
1462
+ * sound in relation to the listener. `angle` will be reduced as neccesary
1463
+ * (540 becomes 180 degrees, -100 becomes 260). Angle 0 is due north, and
1464
+ * rotates clockwise as the value increases. For efficiency, the precision of
1465
+ * this effect may be limited (angles 1 through 7 might all produce the same
1466
+ * effect, 8 through 15 are equal, etc). `distance` is an integer between 0
1467
+ * and 255 that specifies the space between the sound and the listener. The
1468
+ * larger the number, the further away the sound is. Using 255 does not
1469
+ * guarantee that the channel will be removed from the mixing process or be
1470
+ * completely silent. For efficiency, the precision of this effect may be
1471
+ * limited (distance 0 through 5 might all produce the same effect, 6 through
1472
+ * 10 are equal, etc). Setting `angle` and `distance` to 0 unregisters this
1473
+ * effect, since the data would be unchanged.
1474
+ *
1475
+ * If you need more precise positional audio, consider using OpenAL for
1476
+ * spatialized effects instead of SDL_mixer. This is only meant to be a basic
1477
+ * effect for simple "3D" games.
1478
+ *
1479
+ * If the audio device is configured for mono output, then you won't get any
1480
+ * effectiveness from the angle; however, distance attenuation on the channel
1481
+ * will still occur. While this effect will function with stereo voices, it
1482
+ * makes more sense to use voices with only one channel of sound, so when they
1483
+ * are mixed through this effect, the positioning will sound correct. You can
1484
+ * convert them to mono through SDL before giving them to the mixer in the
1485
+ * first place if you like.
1486
+ *
1487
+ * Setting the channel to MIX_CHANNEL_POST registers this as a posteffect, and
1488
+ * the positioning will be done to the final mixed stream before passing it on
1489
+ * to the audio device.
1490
+ *
1491
+ * This is a convenience wrapper over Mix_SetDistance() and Mix_SetPanning().
1492
+ *
1493
+ * Note that unlike most SDL and SDL_mixer functions, this function returns
1494
+ * zero if there's an error, not on success. We apologize for the API design
1495
+ * inconsistency here.
1496
+ *
1497
+ * \param channel The mixer channel to position, or MIX_CHANNEL_POST.
1498
+ * \param angle angle, in degrees. North is 0, and goes clockwise.
1499
+ * \param distance distance; 0 is the listener, 255 is maxiumum distance away.
1500
+ * \returns zero if error (no such channel or Mix_RegisterEffect() fails),
1501
+ * nonzero if position effect is enabled. Error messages can be
1502
+ * retrieved from Mix_GetError().
1503
+ *
1504
+ * \since This function is available since SDL_mixer 2.0.0.
1505
+ */
1506
+ extern DECLSPEC int SDLCALL Mix_SetPosition(int channel, Sint16 angle, Uint8 distance);
1507
+
1508
+
1509
+ /**
1510
+ * Set the "distance" of a channel.
1511
+ *
1512
+ * `distance` is an integer from 0 to 255 that specifies the location of the
1513
+ * sound in relation to the listener. Distance 0 is overlapping the listener,
1514
+ * and 255 is as far away as possible. A distance of 255 does not guarantee
1515
+ * silence; in such a case, you might want to try changing the chunk's volume,
1516
+ * or just cull the sample from the mixing process with Mix_HaltChannel(). For
1517
+ * efficiency, the precision of this effect may be limited (distances 1
1518
+ * through 7 might all produce the same effect, 8 through 15 are equal, etc).
1519
+ * (distance) is an integer between 0 and 255 that specifies the space between
1520
+ * the sound and the listener. The larger the number, the further away the
1521
+ * sound is. Setting the distance to 0 unregisters this effect, since the data
1522
+ * would be unchanged. If you need more precise positional audio, consider
1523
+ * using OpenAL for spatialized effects instead of SDL_mixer. This is only
1524
+ * meant to be a basic effect for simple "3D" games.
1525
+ *
1526
+ * Setting the channel to MIX_CHANNEL_POST registers this as a posteffect, and
1527
+ * the distance attenuation will be done to the final mixed stream before
1528
+ * passing it on to the audio device.
1529
+ *
1530
+ * This uses the Mix_RegisterEffect() API internally.
1531
+ *
1532
+ * Note that unlike most SDL and SDL_mixer functions, this function returns
1533
+ * zero if there's an error, not on success. We apologize for the API design
1534
+ * inconsistency here.
1535
+ *
1536
+ * \param channel The mixer channel to attenuate, or MIX_CHANNEL_POST.
1537
+ * \param distance distance; 0 is the listener, 255 is maxiumum distance away.
1538
+ * \returns zero if error (no such channel or Mix_RegisterEffect() fails),
1539
+ * nonzero if position effect is enabled. Error messages can be
1540
+ * retrieved from Mix_GetError().
1541
+ *
1542
+ * \since This function is available since SDL_mixer 2.0.0.
1543
+ */
1544
+ extern DECLSPEC int SDLCALL Mix_SetDistance(int channel, Uint8 distance);
1545
+
1546
+
1547
+ /**
1548
+ * Cause a channel to reverse its stereo.
1549
+ *
1550
+ * This is handy if the user has his speakers hooked up backwards, or you
1551
+ * would like to have a trippy sound effect.
1552
+ *
1553
+ * Calling this function with `flip` set to non-zero reverses the chunks's
1554
+ * usual channels. If `flip` is zero, the effect is unregistered.
1555
+ *
1556
+ * This uses the Mix_RegisterEffect() API internally, and thus is probably
1557
+ * more CPU intensive than having the user just plug in his speakers
1558
+ * correctly. Mix_SetReverseStereo() returns without registering the effect
1559
+ * function if the audio device is not configured for stereo output.
1560
+ *
1561
+ * If you specify MIX_CHANNEL_POST for `channel`, then this effect is used on
1562
+ * the final mixed stream before sending it on to the audio device (a
1563
+ * posteffect).
1564
+ *
1565
+ * Note that unlike most SDL and SDL_mixer functions, this function returns
1566
+ * zero if there's an error, not on success. We apologize for the API design
1567
+ * inconsistency here.
1568
+ *
1569
+ * \param channel The mixer channel to reverse, or MIX_CHANNEL_POST.
1570
+ * \param flip non-zero to reverse stereo, zero to disable this effect.
1571
+ * \returns zero if error (no such channel or Mix_RegisterEffect() fails),
1572
+ * nonzero if reversing effect is enabled. Note that an audio device
1573
+ * in mono mode is a no-op, but this call will return successful in
1574
+ * that case. Error messages can be retrieved from Mix_GetError().
1575
+ *
1576
+ * \since This function is available since SDL_mixer 2.0.0.
1577
+ */
1578
+ extern DECLSPEC int SDLCALL Mix_SetReverseStereo(int channel, int flip);
513
1579
 
514
- /* Reserve the first channels (0 -> n-1) for the application, i.e. don't allocate
515
- them dynamically to the next sample if requested with a -1 value below.
516
- Returns the number of reserved channels.
1580
+ /* end of effects API. */
1581
+
1582
+
1583
+
1584
+ /**
1585
+ * Reserve the first channels for the application.
1586
+ *
1587
+ * While SDL_mixer will use up to the number of channels allocated by
1588
+ * Mix_AllocateChannels(), this sets channels aside that will not be available
1589
+ * when calling Mix_PlayChannel with a channel of -1 (play on the first unused
1590
+ * channel). In this case, SDL_mixer will treat reserved channels as "used"
1591
+ * whether anything is playing on them at the moment or not.
1592
+ *
1593
+ * This is useful if you've budgeted some channels for dedicated audio and the
1594
+ * rest are just used as they are available.
1595
+ *
1596
+ * Calling this function will set channels 0 to `n - 1` to be reserved. This
1597
+ * will not change channel allocations. The number of reserved channels will
1598
+ * be clamped to the current number allocated.
1599
+ *
1600
+ * By default, no channels are reserved.
1601
+ *
1602
+ * \param num number of channels to reserve, starting at index zero.
1603
+ * \returns the number of reserved channels.
1604
+ *
1605
+ * \since This function is available since SDL_mixer 2.0.0.
517
1606
  */
518
1607
  extern DECLSPEC int SDLCALL Mix_ReserveChannels(int num);
519
1608
 
1609
+
520
1610
  /* Channel grouping functions */
521
1611
 
522
- /* Attach a tag to a channel. A tag can be assigned to several mixer
523
- channels, to form groups of channels.
524
- If 'tag' is -1, the tag is removed (actually -1 is the tag used to
525
- represent the group of all the channels).
526
- Returns true if everything was OK.
1612
+ /**
1613
+ * Assign a tag to a channel.
1614
+ *
1615
+ * A tag is an arbitary number that can be assigned to several mixer channels,
1616
+ * to form groups of channels.
1617
+ *
1618
+ * If 'tag' is -1, the tag is removed (actually -1 is the tag used to
1619
+ * represent the group of all the channels).
1620
+ *
1621
+ * This function replaces the requested channel's current tag; you may only
1622
+ * have one tag per channel.
1623
+ *
1624
+ * You may not specify MAX_CHANNEL_POST for a channel.
1625
+ *
1626
+ * \param which the channel to set the tag on.
1627
+ * \param tag an arbitrary value to assign a channel.
1628
+ * \returns non-zero on success, zero on error (no such channel).
1629
+ *
1630
+ * \since This function is available since SDL_mixer 2.0.0.
527
1631
  */
528
1632
  extern DECLSPEC int SDLCALL Mix_GroupChannel(int which, int tag);
529
- /* Assign several consecutive channels to a group */
1633
+
1634
+ /**
1635
+ * Assign several consecutive channels to the same tag.
1636
+ *
1637
+ * A tag is an arbitary number that can be assigned to several mixer channels,
1638
+ * to form groups of channels.
1639
+ *
1640
+ * If 'tag' is -1, the tag is removed (actually -1 is the tag used to
1641
+ * represent the group of all the channels).
1642
+ *
1643
+ * This function replaces the requested channels' current tags; you may only
1644
+ * have one tag per channel.
1645
+ *
1646
+ * You may not specify MAX_CHANNEL_POST for a channel.
1647
+ *
1648
+ * Note that this returns success and failure in the _opposite_ way from
1649
+ * Mix_GroupChannel(). We regret the API design mistake.
1650
+ *
1651
+ * \param from the first channel to set the tag on.
1652
+ * \param to the last channel to set the tag on, inclusive.
1653
+ * \param tag an arbitrary value to assign a channel.
1654
+ * \returns 0 if successful, negative on error
1655
+ *
1656
+ * \since This function is available since SDL_mixer 2.0.0.
1657
+ */
530
1658
  extern DECLSPEC int SDLCALL Mix_GroupChannels(int from, int to, int tag);
531
- /* Finds the first available channel in a group of channels,
532
- returning -1 if none are available.
1659
+
1660
+ /**
1661
+ * Finds the first available channel in a group of channels.
1662
+ *
1663
+ * A tag is an arbitary number that can be assigned to several mixer channels,
1664
+ * to form groups of channels.
1665
+ *
1666
+ * This function searches all channels with a specified tag, and returns the
1667
+ * channel number of the first one it finds that is currently unused.
1668
+ *
1669
+ * If no channels with the specified tag are unused, this function returns -1.
1670
+ *
1671
+ * \param tag an arbitrary value, assigned to channels, to search for.
1672
+ * \returns first available channel, or -1 if none are available.
1673
+ *
1674
+ * \since This function is available since SDL_mixer 2.0.0.
533
1675
  */
534
1676
  extern DECLSPEC int SDLCALL Mix_GroupAvailable(int tag);
535
- /* Returns the number of channels in a group. This is also a subtle
536
- way to get the total number of channels when 'tag' is -1
1677
+
1678
+ /**
1679
+ * Returns the number of channels in a group.
1680
+ *
1681
+ * If tag is -1, this will return the total number of channels allocated,
1682
+ * regardless of what their tag might be.
1683
+ *
1684
+ * \param tag an arbitrary value, assigned to channels, to search for.
1685
+ * \returns the number of channels assigned the specified tag.
1686
+ *
1687
+ * \since This function is available since SDL_mixer 2.0.0.
537
1688
  */
538
1689
  extern DECLSPEC int SDLCALL Mix_GroupCount(int tag);
539
- /* Finds the "oldest" sample playing in a group of channels */
1690
+
1691
+ /**
1692
+ * Find the "oldest" sample playing in a group of channels.
1693
+ *
1694
+ * Specifically, this function returns the channel number that is assigned the
1695
+ * specified tag, is currently playing, and has the lowest start time, based
1696
+ * on the value of SDL_GetTicks() when the channel started playing.
1697
+ *
1698
+ * If no channel with this tag is currently playing, this function returns -1.
1699
+ *
1700
+ * \param tag an arbitrary value, assigned to channels, to search through.
1701
+ * \returns the "oldest" sample playing in a group of channels
1702
+ *
1703
+ * \since This function is available since SDL_mixer 2.0.0.
1704
+ *
1705
+ * \sa Mix_GroupNewer
1706
+ */
540
1707
  extern DECLSPEC int SDLCALL Mix_GroupOldest(int tag);
541
- /* Finds the "most recent" (i.e. last) sample playing in a group of channels */
1708
+
1709
+ /**
1710
+ * Find the "most recent" sample playing in a group of channels.
1711
+ *
1712
+ * Specifically, this function returns the channel number that is assigned the
1713
+ * specified tag, is currently playing, and has the highest start time, based
1714
+ * on the value of SDL_GetTicks() when the channel started playing.
1715
+ *
1716
+ * If no channel with this tag is currently playing, this function returns -1.
1717
+ *
1718
+ * \param tag an arbitrary value, assigned to channels, to search through.
1719
+ * \returns the "most recent" sample playing in a group of channels
1720
+ *
1721
+ * \since This function is available since SDL_mixer 2.0.0.
1722
+ *
1723
+ * \sa Mix_GroupOldest
1724
+ */
542
1725
  extern DECLSPEC int SDLCALL Mix_GroupNewer(int tag);
543
1726
 
544
- /* Play an audio chunk on a specific channel.
545
- If the specified channel is -1, play on the first free channel.
546
- If 'loops' is greater than zero, loop the sound that many times.
547
- If 'loops' is -1, loop inifinitely (~65000 times).
548
- Returns which channel was used to play the sound.
549
- */
550
- #define Mix_PlayChannel(channel,chunk,loops) Mix_PlayChannelTimed(channel,chunk,loops,-1)
551
- /* The same as above, but the sound is played at most 'ticks' milliseconds */
1727
+ /**
1728
+ * Play an audio chunk on a specific channel.
1729
+ *
1730
+ * If the specified channel is -1, play on the first free channel (and return
1731
+ * -1 without playing anything new if no free channel was available).
1732
+ *
1733
+ * If a specific channel was requested, and there is a chunk already playing
1734
+ * there, that chunk will be halted and the new chunk will take its place.
1735
+ *
1736
+ * If `loops` is greater than zero, loop the sound that many times. If `loops`
1737
+ * is -1, loop "infinitely" (~65000 times).
1738
+ *
1739
+ * Note that before SDL_mixer 2.6.0, this function was a macro that called
1740
+ * Mix_PlayChannelTimed() with a fourth parameter ("ticks") of -1. This
1741
+ * function still does the same thing, but promotes it to a proper API
1742
+ * function. Older binaries linked against a newer SDL_mixer will still call
1743
+ * Mix_PlayChannelTimed directly, as they are using the macro, which was
1744
+ * available since the dawn of time.
1745
+ *
1746
+ * \param channel the channel on which to play the new chunk.
1747
+ * \param chunk the new chunk to play.
1748
+ * \param loop the number of times the chunk should loop, -1 to loop (not
1749
+ * actually) infinitely.
1750
+ * \returns which channel was used to play the sound, or -1 if sound could not
1751
+ * be played.
1752
+ *
1753
+ * \since This function is available since SDL_mixer 2.6.0 (and as a macro
1754
+ * since 2.0.0).
1755
+ */
1756
+ extern DECLSPEC int SDLCALL Mix_PlayChannel(int channel, Mix_Chunk *chunk, int loops);
1757
+
1758
+ /**
1759
+ * Play an audio chunk on a specific channel for a maximum time.
1760
+ *
1761
+ * If the specified channel is -1, play on the first free channel (and return
1762
+ * -1 without playing anything new if no free channel was available).
1763
+ *
1764
+ * If a specific channel was requested, and there is a chunk already playing
1765
+ * there, that chunk will be halted and the new chunk will take its place.
1766
+ *
1767
+ * If `loops` is greater than zero, loop the sound that many times. If `loops`
1768
+ * is -1, loop "infinitely" (~65000 times).
1769
+ *
1770
+ * `ticks` specifies the maximum number of milliseconds to play this chunk
1771
+ * before halting it. If you want the chunk to play until all data has been
1772
+ * mixed, specify -1.
1773
+ *
1774
+ * Note that this function does not block for the number of ticks requested;
1775
+ * it just schedules the chunk to play and notes the maximum for the mixer to
1776
+ * manage later, and returns immediately.
1777
+ *
1778
+ * \param channel the channel on which to play the new chunk.
1779
+ * \param chunk the new chunk to play.
1780
+ * \param loop the number of times the chunk should loop, -1 to loop (not
1781
+ * actually) infinitely.
1782
+ * \param ticks the maximum number of milliseconds of this chunk to mix for
1783
+ * playback.
1784
+ * \returns which channel was used to play the sound, or -1 if sound could not
1785
+ * be played.
1786
+ *
1787
+ * \since This function is available since SDL_mixer 2.0.0.
1788
+ */
552
1789
  extern DECLSPEC int SDLCALL Mix_PlayChannelTimed(int channel, Mix_Chunk *chunk, int loops, int ticks);
1790
+
1791
+ /**
1792
+ * Play a new music object.
1793
+ *
1794
+ * This will schedule the music object to begin mixing for playback.
1795
+ *
1796
+ * There is only ever one music object playing at a time; if this is called
1797
+ * when another music object is playing, the currently-playing music is halted
1798
+ * and the new music will replace it.
1799
+ *
1800
+ * Please note that if the currently-playing music is in the process of fading
1801
+ * out (via Mix_FadeOutMusic()), this function will *block* until the fade
1802
+ * completes. If you need to avoid this, be sure to call Mix_HaltMusic()
1803
+ * before starting new music.
1804
+ *
1805
+ * \param music the new music object to schedule for mixing.
1806
+ * \param loops the number of loops to play the music for (0 means "play once
1807
+ * and stop").
1808
+ * \returns zero on success, -1 on error.
1809
+ *
1810
+ * \since This function is available since SDL_mixer 2.0.0.
1811
+ */
553
1812
  extern DECLSPEC int SDLCALL Mix_PlayMusic(Mix_Music *music, int loops);
554
1813
 
555
- /* Fade in music or a channel over "ms" milliseconds, same semantics as the "Play" functions */
1814
+ /**
1815
+ * Play a new music object, fading in the audio.
1816
+ *
1817
+ * This will start the new music playing, much like Mix_PlayMusic() will, but
1818
+ * will start the music playing at silence and fade in to its normal volume
1819
+ * over the specified number of milliseconds.
1820
+ *
1821
+ * If there is already music playing, that music will be halted and the new
1822
+ * music object will take its place.
1823
+ *
1824
+ * If `loops` is greater than zero, loop the music that many times. If `loops`
1825
+ * is -1, loop "infinitely" (~65000 times).
1826
+ *
1827
+ * Fading music will change it's volume progressively, as if Mix_VolumeMusic()
1828
+ * was called on it (which is to say: you probably shouldn't call
1829
+ * Mix_VolumeMusic() on fading music).
1830
+ *
1831
+ * \param music the new music object to play.
1832
+ * \param loop the number of times the chunk should loop, -1 to loop (not
1833
+ * actually) infinitely.
1834
+ * \param ms the number of milliseconds to spend fading in.
1835
+ * \returns zero on success, -1 on error.
1836
+ *
1837
+ * \since This function is available since SDL_mixer 2.0.0.
1838
+ */
556
1839
  extern DECLSPEC int SDLCALL Mix_FadeInMusic(Mix_Music *music, int loops, int ms);
1840
+
1841
+ /**
1842
+ * Play a new music object, fading in the audio, from a starting position.
1843
+ *
1844
+ * This will start the new music playing, much like Mix_PlayMusic() will, but
1845
+ * will start the music playing at silence and fade in to its normal volume
1846
+ * over the specified number of milliseconds.
1847
+ *
1848
+ * If there is already music playing, that music will be halted and the new
1849
+ * music object will take its place.
1850
+ *
1851
+ * If `loops` is greater than zero, loop the music that many times. If `loops`
1852
+ * is -1, loop "infinitely" (~65000 times).
1853
+ *
1854
+ * Fading music will change it's volume progressively, as if Mix_VolumeMusic()
1855
+ * was called on it (which is to say: you probably shouldn't call
1856
+ * Mix_VolumeMusic() on fading music).
1857
+ *
1858
+ * This function allows the caller to start the music playback past the
1859
+ * beginning of its audio data. You may specify a start position, in seconds,
1860
+ * and the playback and fade-in will start there instead of with the first
1861
+ * samples of the music.
1862
+ *
1863
+ * An app can specify a `position` of 0.0 to start at the beginning of the
1864
+ * music (or just call Mix_FadeInMusic() instead).
1865
+ *
1866
+ * To convert from milliseconds, divide by 1000.0.
1867
+ *
1868
+ * \param music the new music object to play.
1869
+ * \param loop the number of times the chunk should loop, -1 to loop (not
1870
+ * actually) infinitely.
1871
+ * \param ms the number of milliseconds to spend fading in.
1872
+ * \param position the start position within the music, in seconds, where
1873
+ * playback should start.
1874
+ * \returns zero on success, -1 on error.
1875
+ *
1876
+ * \since This function is available since SDL_mixer 2.0.0.
1877
+ */
557
1878
  extern DECLSPEC int SDLCALL Mix_FadeInMusicPos(Mix_Music *music, int loops, int ms, double position);
558
- #define Mix_FadeInChannel(channel,chunk,loops,ms) Mix_FadeInChannelTimed(channel,chunk,loops,ms,-1)
1879
+
1880
+ /**
1881
+ * Play an audio chunk on a specific channel, fading in the audio.
1882
+ *
1883
+ * This will start the new sound playing, much like Mix_PlayChannel() will,
1884
+ * but will start the sound playing at silence and fade in to its normal
1885
+ * volume over the specified number of milliseconds.
1886
+ *
1887
+ * If the specified channel is -1, play on the first free channel (and return
1888
+ * -1 without playing anything new if no free channel was available).
1889
+ *
1890
+ * If a specific channel was requested, and there is a chunk already playing
1891
+ * there, that chunk will be halted and the new chunk will take its place.
1892
+ *
1893
+ * If `loops` is greater than zero, loop the sound that many times. If `loops`
1894
+ * is -1, loop "infinitely" (~65000 times).
1895
+ *
1896
+ * A fading channel will change it's volume progressively, as if Mix_Volume()
1897
+ * was called on it (which is to say: you probably shouldn't call Mix_Volume()
1898
+ * on a fading channel).
1899
+ *
1900
+ * Note that before SDL_mixer 2.6.0, this function was a macro that called
1901
+ * Mix_FadeInChannelTimed() with a fourth parameter ("ticks") of -1. This
1902
+ * function still does the same thing, but promotes it to a proper API
1903
+ * function. Older binaries linked against a newer SDL_mixer will still call
1904
+ * Mix_FadeInChannelTimed directly, as they are using the macro, which was
1905
+ * available since the dawn of time.
1906
+ *
1907
+ * \param channel the channel on which to play the new chunk, or -1 to find
1908
+ * any available.
1909
+ * \param chunk the new chunk to play.
1910
+ * \param loop the number of times the chunk should loop, -1 to loop (not
1911
+ * actually) infinitely.
1912
+ * \param ms the number of milliseconds to spend fading in.
1913
+ * \returns which channel was used to play the sound, or -1 if sound could not
1914
+ * be played.
1915
+ *
1916
+ * \since This function is available since SDL_mixer 2.6.0 (and as a macro
1917
+ * since 2.0.0).
1918
+ */
1919
+ extern DECLSPEC int SDLCALL Mix_FadeInChannel(int channel, Mix_Chunk *chunk, int loops, int ms);
1920
+
1921
+ /**
1922
+ * Play an audio chunk on a specific channel, fading in the audio, for a
1923
+ * maximum time.
1924
+ *
1925
+ * This will start the new sound playing, much like Mix_PlayChannel() will,
1926
+ * but will start the sound playing at silence and fade in to its normal
1927
+ * volume over the specified number of milliseconds.
1928
+ *
1929
+ * If the specified channel is -1, play on the first free channel (and return
1930
+ * -1 without playing anything new if no free channel was available).
1931
+ *
1932
+ * If a specific channel was requested, and there is a chunk already playing
1933
+ * there, that chunk will be halted and the new chunk will take its place.
1934
+ *
1935
+ * If `loops` is greater than zero, loop the sound that many times. If `loops`
1936
+ * is -1, loop "infinitely" (~65000 times).
1937
+ *
1938
+ * `ticks` specifies the maximum number of milliseconds to play this chunk
1939
+ * before halting it. If you want the chunk to play until all data has been
1940
+ * mixed, specify -1.
1941
+ *
1942
+ * Note that this function does not block for the number of ticks requested;
1943
+ * it just schedules the chunk to play and notes the maximum for the mixer to
1944
+ * manage later, and returns immediately.
1945
+ *
1946
+ * A fading channel will change it's volume progressively, as if Mix_Volume()
1947
+ * was called on it (which is to say: you probably shouldn't call Mix_Volume()
1948
+ * on a fading channel).
1949
+ *
1950
+ * \param channel the channel on which to play the new chunk, or -1 to find
1951
+ * any available.
1952
+ * \param chunk the new chunk to play.
1953
+ * \param loop the number of times the chunk should loop, -1 to loop (not
1954
+ * actually) infinitely.
1955
+ * \param ms the number of milliseconds to spend fading in.
1956
+ * \param ticks the maximum number of milliseconds of this chunk to mix for
1957
+ * playback.
1958
+ * \returns which channel was used to play the sound, or -1 if sound could not
1959
+ * be played.
1960
+ *
1961
+ * \since This function is available since SDL_mixer 2.0.0.
1962
+ */
559
1963
  extern DECLSPEC int SDLCALL Mix_FadeInChannelTimed(int channel, Mix_Chunk *chunk, int loops, int ms, int ticks);
560
1964
 
561
- /* Set the volume in the range of 0-128 of a specific channel or chunk.
562
- If the specified channel is -1, set volume for all channels.
563
- Returns the original volume.
564
- If the specified volume is -1, just return the current volume.
565
- */
1965
+ /**
1966
+ * Set the volume for a specific channel.
1967
+ *
1968
+ * The volume must be between 0 (silence) and MIX_MAX_VOLUME (full volume).
1969
+ * Note that MIX_MAX_VOLUME is 128. Values greater than MIX_MAX_VOLUME are
1970
+ * clamped to MIX_MAX_VOLUME.
1971
+ *
1972
+ * Specifying a negative volume will not change the current volume; as such,
1973
+ * this can be used to query the current volume without making changes, as
1974
+ * this function returns the previous (in this case, still-current) value.
1975
+ *
1976
+ * If the specified channel is -1, this function sets the volume for all
1977
+ * channels, and returns _the average_ of all channels' volumes prior to this
1978
+ * call.
1979
+ *
1980
+ * The default volume for a channel is MIX_MAX_VOLUME (no attenuation).
1981
+ *
1982
+ * \param channel the channel on set/query the volume on, or -1 for all
1983
+ * channels.
1984
+ * \param volume the new volume, between 0 and MIX_MAX_VOLUME, or -1 to query.
1985
+ * \returns the previous volume. If the specified volume is -1, this returns
1986
+ * the current volume. If `channel` is -1, this returns the average
1987
+ * of all channels.
1988
+ *
1989
+ * \since This function is available since SDL_mixer 2.0.0.
1990
+ */
566
1991
  extern DECLSPEC int SDLCALL Mix_Volume(int channel, int volume);
1992
+
1993
+ /**
1994
+ * Set the volume for a specific chunk.
1995
+ *
1996
+ * In addition to channels having a volume setting, individual chunks also
1997
+ * maintain a seperate volume. Both values are considered when mixing, so both
1998
+ * affect the final attenuation of the sound. This lets an app adjust the
1999
+ * volume for all instances of a sound in addition to specific instances of
2000
+ * that sound.
2001
+ *
2002
+ * The volume must be between 0 (silence) and MIX_MAX_VOLUME (full volume).
2003
+ * Note that MIX_MAX_VOLUME is 128. Values greater than MIX_MAX_VOLUME are
2004
+ * clamped to MIX_MAX_VOLUME.
2005
+ *
2006
+ * Specifying a negative volume will not change the current volume; as such,
2007
+ * this can be used to query the current volume without making changes, as
2008
+ * this function returns the previous (in this case, still-current) value.
2009
+ *
2010
+ * The default volume for a chunk is MIX_MAX_VOLUME (no attenuation).
2011
+ *
2012
+ * \param channel the channel on set/query the volume on, or -1 for all
2013
+ * channels.
2014
+ * \param volume the new volume, between 0 and MIX_MAX_VOLUME, or -1 to query.
2015
+ * \returns the previous volume. If the specified volume is -1, this returns
2016
+ * the current volume. If `chunk` is NULL, this returns -1.
2017
+ *
2018
+ * \since This function is available since SDL_mixer 2.0.0.
2019
+ */
567
2020
  extern DECLSPEC int SDLCALL Mix_VolumeChunk(Mix_Chunk *chunk, int volume);
2021
+
2022
+ /**
2023
+ * Set the volume for the music channel.
2024
+ *
2025
+ * The volume must be between 0 (silence) and MIX_MAX_VOLUME (full volume).
2026
+ * Note that MIX_MAX_VOLUME is 128. Values greater than MIX_MAX_VOLUME are
2027
+ * clamped to MIX_MAX_VOLUME.
2028
+ *
2029
+ * Specifying a negative volume will not change the current volume; as such,
2030
+ * this can be used to query the current volume without making changes, as
2031
+ * this function returns the previous (in this case, still-current) value.
2032
+ *
2033
+ * The default volume for music is MIX_MAX_VOLUME (no attenuation).
2034
+ *
2035
+ * \param volume the new volume, between 0 and MIX_MAX_VOLUME, or -1 to query.
2036
+ * \returns the previous volume. If the specified volume is -1, this returns
2037
+ * the current volume.
2038
+ *
2039
+ * \since This function is available since SDL_mixer 2.0.0.
2040
+ */
568
2041
  extern DECLSPEC int SDLCALL Mix_VolumeMusic(int volume);
569
2042
 
570
- /* Halt playing of a particular channel */
2043
+ /**
2044
+ * Query the current volume value for a music object.
2045
+ *
2046
+ * \param music the music object to query.
2047
+ * \returns the music's current volume, between 0 and MIX_MAX_VOLUME (128).
2048
+ *
2049
+ * \since This function is available since SDL_mixer 2.6.0.
2050
+ */
2051
+ extern DECLSPEC int SDLCALL Mix_GetMusicVolume(Mix_Music *music);
2052
+
2053
+ /**
2054
+ * Set the master volume for all channels.
2055
+ *
2056
+ * SDL_mixer keeps a per-channel volume, a per-chunk volume, and a master
2057
+ * volume, and considers all three when mixing audio. This function sets the
2058
+ * master volume, which is applied to all playing channels when mixing.
2059
+ *
2060
+ * The volume must be between 0 (silence) and MIX_MAX_VOLUME (full volume).
2061
+ * Note that MIX_MAX_VOLUME is 128. Values greater than MIX_MAX_VOLUME are
2062
+ * clamped to MIX_MAX_VOLUME.
2063
+ *
2064
+ * Specifying a negative volume will not change the current volume; as such,
2065
+ * this can be used to query the current volume without making changes, as
2066
+ * this function returns the previous (in this case, still-current) value.
2067
+ *
2068
+ * Note that the master volume does not affect any playing music; it is only
2069
+ * applied when mixing chunks. Use Mix_MusicVolume() for that.\
2070
+ *
2071
+ * \param volume the new volume, between 0 and MIX_MAX_VOLUME, or -1 to query.
2072
+ * \returns the previous volume. If the specified volume is -1, this returns
2073
+ * the current volume.
2074
+ *
2075
+ * \since This function is available since SDL_mixer 2.6.0.
2076
+ */
2077
+ extern DECLSPEC int SDLCALL Mix_MasterVolume(int volume);
2078
+
2079
+ /**
2080
+ * Halt playing of a particular channel.
2081
+ *
2082
+ * This will stop further playback on that channel until a new chunk is
2083
+ * started there.
2084
+ *
2085
+ * Specifying a channel of -1 will halt _all_ channels, except for any playing
2086
+ * music.
2087
+ *
2088
+ * Any halted channels will have any currently-registered effects
2089
+ * deregistered, and will call any callback specified by Mix_ChannelFinished()
2090
+ * before this function returns.
2091
+ *
2092
+ * You may not specify MAX_CHANNEL_POST for a channel.
2093
+ *
2094
+ * \param channel channel to halt, or -1 to halt all channels.
2095
+ * \returns 0 on success, or -1 on error.
2096
+ *
2097
+ * \since This function is available since SDL_mixer 2.0.0.
2098
+ */
571
2099
  extern DECLSPEC int SDLCALL Mix_HaltChannel(int channel);
2100
+
2101
+ /**
2102
+ * Halt playing of a group of channels by arbitrary tag.
2103
+ *
2104
+ * This will stop further playback on all channels with a specific tag, until
2105
+ * a new chunk is started there.
2106
+ *
2107
+ * A tag is an arbitary number that can be assigned to several mixer channels,
2108
+ * to form groups of channels.
2109
+ *
2110
+ * The default tag for a channel is -1.
2111
+ *
2112
+ * Any halted channels will have any currently-registered effects
2113
+ * deregistered, and will call any callback specified by Mix_ChannelFinished()
2114
+ * before this function returns.
2115
+ *
2116
+ * \param tag an arbitrary value, assigned to channels, to search for.
2117
+ * \returns zero, whether any channels were halted or not.
2118
+ *
2119
+ * \since This function is available since SDL_mixer 2.0.0.
2120
+ */
572
2121
  extern DECLSPEC int SDLCALL Mix_HaltGroup(int tag);
2122
+
2123
+ /**
2124
+ * Halt playing of the music stream.
2125
+ *
2126
+ * This will stop further playback of music until a new music object is
2127
+ * started there.
2128
+ *
2129
+ * Any halted music will call any callback specified by
2130
+ * Mix_HookMusicFinished() before this function returns.
2131
+ *
2132
+ * \returns zero, regardless of whether any music was halted.
2133
+ *
2134
+ * \since This function is available since SDL_mixer 2.0.0.
2135
+ */
573
2136
  extern DECLSPEC int SDLCALL Mix_HaltMusic(void);
574
2137
 
575
- /* Change the expiration delay for a particular channel.
576
- The sample will stop playing after the 'ticks' milliseconds have elapsed,
577
- or remove the expiration if 'ticks' is -1
578
- */
2138
+ /**
2139
+ * Change the expiration delay for a particular channel.
2140
+ *
2141
+ * The channel will halt after the 'ticks' milliseconds have elapsed, or
2142
+ * remove the expiration if 'ticks' is -1.
2143
+ *
2144
+ * This overrides the value passed to the fourth parameter of
2145
+ * Mix_PlayChannelTimed().
2146
+ *
2147
+ * Specifying a channel of -1 will set an expiration for _all_ channels.
2148
+ *
2149
+ * Any halted channels will have any currently-registered effects
2150
+ * deregistered, and will call any callback specified by Mix_ChannelFinished()
2151
+ * once the halt occurs.
2152
+ *
2153
+ * Note that this function does not block for the number of ticks requested;
2154
+ * it just schedules the chunk to expire and notes the time for the mixer to
2155
+ * manage later, and returns immediately.
2156
+ *
2157
+ * \param channel the channel to change the expiration time on.
2158
+ * \param ticks number of milliseconds from now to let channel play before
2159
+ * halting, -1 to not halt.
2160
+ * \returns the number of channels that changed expirations.
2161
+ *
2162
+ * \since This function is available since SDL_mixer 2.0.0.
2163
+ */
579
2164
  extern DECLSPEC int SDLCALL Mix_ExpireChannel(int channel, int ticks);
580
2165
 
581
- /* Halt a channel, fading it out progressively till it's silent
582
- The ms parameter indicates the number of milliseconds the fading
583
- will take.
2166
+ /**
2167
+ * Halt a channel after fading it out for a specified time.
2168
+ *
2169
+ * This will begin a channel fading from its current volume to silence over
2170
+ * `ms` milliseconds. After that time, the channel is halted.
2171
+ *
2172
+ * Any halted channels will have any currently-registered effects
2173
+ * deregistered, and will call any callback specified by Mix_ChannelFinished()
2174
+ * once the halt occurs.
2175
+ *
2176
+ * A fading channel will change it's volume progressively, as if Mix_Volume()
2177
+ * was called on it (which is to say: you probably shouldn't call Mix_Volume()
2178
+ * on a fading channel).
2179
+ *
2180
+ * Note that this function does not block for the number of milliseconds
2181
+ * requested; it just schedules the chunk to fade and notes the time for the
2182
+ * mixer to manage later, and returns immediately.
2183
+ *
2184
+ * \param which the channel to fade out.
2185
+ * \param ms number of milliseconds to fade before halting the channel.
2186
+ * \returns 0 on success, or -1 on error.
2187
+ *
2188
+ * \since This function is available since SDL_mixer 2.0.0.
584
2189
  */
585
2190
  extern DECLSPEC int SDLCALL Mix_FadeOutChannel(int which, int ms);
2191
+
2192
+ /**
2193
+ * Halt a playing group of channels by arbitrary tag, after fading them out
2194
+ * for a specified time.
2195
+ *
2196
+ * This will begin fading a group of channels with a specific tag from their
2197
+ * current volumes to silence over `ms` milliseconds. After that time, those
2198
+ * channels are halted.
2199
+ *
2200
+ * A tag is an arbitary number that can be assigned to several mixer channels,
2201
+ * to form groups of channels.
2202
+ *
2203
+ * The default tag for a channel is -1.
2204
+ *
2205
+ * Any halted channels will have any currently-registered effects
2206
+ * deregistered, and will call any callback specified by Mix_ChannelFinished()
2207
+ * once the halt occurs.
2208
+ *
2209
+ * A fading channel will change it's volume progressively, as if Mix_Volume()
2210
+ * was called on it (which is to say: you probably shouldn't call Mix_Volume()
2211
+ * on a fading channel).
2212
+ *
2213
+ * Note that this function does not block for the number of milliseconds
2214
+ * requested; it just schedules the group to fade and notes the time for the
2215
+ * mixer to manage later, and returns immediately.
2216
+ *
2217
+ * \param tag an arbitrary value, assigned to channels, to search for.
2218
+ * \param ms number of milliseconds to fade before halting the group.
2219
+ * \returns the number of channels that were scheduled for fading.
2220
+ *
2221
+ * \since This function is available since SDL_mixer 2.0.0.
2222
+ */
586
2223
  extern DECLSPEC int SDLCALL Mix_FadeOutGroup(int tag, int ms);
2224
+
2225
+ /**
2226
+ * Halt the music stream after fading it out for a specified time.
2227
+ *
2228
+ * This will begin the music fading from its current volume to silence over
2229
+ * `ms` milliseconds. After that time, the music is halted.
2230
+ *
2231
+ * Any halted music will call any callback specified by
2232
+ * Mix_HookMusicFinished() once the halt occurs.
2233
+ *
2234
+ * Fading music will change it's volume progressively, as if Mix_VolumeMusic()
2235
+ * was called on it (which is to say: you probably shouldn't call
2236
+ * Mix_VolumeMusic() on a fading channel).
2237
+ *
2238
+ * Note that this function does not block for the number of milliseconds
2239
+ * requested; it just schedules the music to fade and notes the time for the
2240
+ * mixer to manage later, and returns immediately.
2241
+ *
2242
+ * \param which the channel to fade out.
2243
+ * \param ms number of milliseconds to fade before halting the channel.
2244
+ * \returns non-zero if music was scheduled to fade, zero otherwise. If no
2245
+ * music is currently playing, this returns zero.
2246
+ *
2247
+ * \since This function is available since SDL_mixer 2.0.0.
2248
+ */
587
2249
  extern DECLSPEC int SDLCALL Mix_FadeOutMusic(int ms);
588
2250
 
589
- /* Query the fading status of a channel */
2251
+ /**
2252
+ * Query the fading status of the music stream.
2253
+ *
2254
+ * This reports one of three values:
2255
+ *
2256
+ * - `MIX_NO_FADING`
2257
+ * - `MIX_FADING_OUT`
2258
+ * - `MIX_FADING_IN`
2259
+ *
2260
+ * If music is not currently playing, this returns `MIX_NO_FADING`.
2261
+ *
2262
+ * \returns the current fading status of the music stream.
2263
+ *
2264
+ * \since This function is available since SDL_mixer 2.0.0.
2265
+ */
590
2266
  extern DECLSPEC Mix_Fading SDLCALL Mix_FadingMusic(void);
2267
+
2268
+ /**
2269
+ * Query the fading status of a channel.
2270
+ *
2271
+ * This reports one of three values:
2272
+ *
2273
+ * - `MIX_NO_FADING`
2274
+ * - `MIX_FADING_OUT`
2275
+ * - `MIX_FADING_IN`
2276
+ *
2277
+ * If nothing is currently playing on the channel, or an invalid channel is
2278
+ * specified, this returns `MIX_NO_FADING`.
2279
+ *
2280
+ * You may not specify MAX_CHANNEL_POST for a channel.
2281
+ *
2282
+ * You may not specify -1 for all channels; only individual channels may be
2283
+ * queried.
2284
+ *
2285
+ * \param which the channel to query.
2286
+ * \returns the current fading status of the channel.
2287
+ *
2288
+ * \since This function is available since SDL_mixer 2.0.0.
2289
+ */
591
2290
  extern DECLSPEC Mix_Fading SDLCALL Mix_FadingChannel(int which);
592
2291
 
593
- /* Pause/Resume a particular channel */
2292
+ /**
2293
+ * Pause a particular channel.
2294
+ *
2295
+ * Pausing a channel will prevent further playback of the assigned chunk but
2296
+ * will maintain the chunk's current mixing position. When resumed, this
2297
+ * channel will continue to mix the chunk where it left off.
2298
+ *
2299
+ * A paused channel can be resumed by calling Mix_Resume().
2300
+ *
2301
+ * A paused channel with an expiration will not expire while paused (the
2302
+ * expiration countdown will be adjusted once resumed).
2303
+ *
2304
+ * It is legal to halt a paused channel. Playing a new chunk on a paused
2305
+ * channel will replace the current chunk and unpause the channel.
2306
+ *
2307
+ * Specifying a channel of -1 will pause _all_ channels. Any music is
2308
+ * unaffected.
2309
+ *
2310
+ * You may not specify MAX_CHANNEL_POST for a channel.
2311
+ *
2312
+ * \param channel the channel to pause, or -1 to pause all channels.
2313
+ *
2314
+ * \since This function is available since SDL_mixer 2.0.0.
2315
+ */
594
2316
  extern DECLSPEC void SDLCALL Mix_Pause(int channel);
2317
+
2318
+ /**
2319
+ * Resume a particular channel.
2320
+ *
2321
+ * It is legal to resume an unpaused or invalid channel; it causes no effect
2322
+ * and reports no error.
2323
+ *
2324
+ * If the paused channel has an expiration, its expiration countdown resumes
2325
+ * now, as well.
2326
+ *
2327
+ * Specifying a channel of -1 will resume _all_ paused channels. Any music is
2328
+ * unaffected.
2329
+ *
2330
+ * \param channel the channel to resume, or -1 to resume all paused channels.
2331
+ *
2332
+ * \since This function is available since SDL_mixer 2.0.0.
2333
+ */
595
2334
  extern DECLSPEC void SDLCALL Mix_Resume(int channel);
2335
+
2336
+ /**
2337
+ * Query whether a particular channel is paused.
2338
+ *
2339
+ * If an invalid channel is specified, this function returns zero.
2340
+ *
2341
+ * \param channel the channel to query, or -1 to query all channels.
2342
+ * \return 1 if channel paused, 0 otherwise. If `channel` is -1, returns the
2343
+ * number of paused channels.
2344
+ *
2345
+ * \since This function is available since SDL_mixer 2.0.0.
2346
+ */
596
2347
  extern DECLSPEC int SDLCALL Mix_Paused(int channel);
597
2348
 
598
- /* Pause/Resume the music stream */
2349
+ /**
2350
+ * Pause the music stream.
2351
+ *
2352
+ * Pausing the music stream will prevent further playback of the assigned
2353
+ * music object, but will maintain the object's current mixing position. When
2354
+ * resumed, this channel will continue to mix the music where it left off.
2355
+ *
2356
+ * Paused music can be resumed by calling Mix_ResumeMusic().
2357
+ *
2358
+ * It is legal to halt paused music. Playing a new music object when music is
2359
+ * paused will replace the current music and unpause the music stream.
2360
+ *
2361
+ * \since This function is available since SDL_mixer 2.0.0.
2362
+ */
599
2363
  extern DECLSPEC void SDLCALL Mix_PauseMusic(void);
2364
+
2365
+ /**
2366
+ * Resume the music stream.
2367
+ *
2368
+ * It is legal to resume an unpaused music stream; it causes no effect and
2369
+ * reports no error.
2370
+ *
2371
+ * \since This function is available since SDL_mixer 2.0.0.
2372
+ */
600
2373
  extern DECLSPEC void SDLCALL Mix_ResumeMusic(void);
2374
+
2375
+ /**
2376
+ * Rewind the music stream.
2377
+ *
2378
+ * This causes the currently-playing music to start mixing from the beginning
2379
+ * of the music, as if it were just started.
2380
+ *
2381
+ * It's a legal no-op to rewind the music stream when not playing.
2382
+ *
2383
+ * \since This function is available since SDL_mixer 2.0.0.
2384
+ */
601
2385
  extern DECLSPEC void SDLCALL Mix_RewindMusic(void);
2386
+
2387
+ /**
2388
+ * Query whether the music stream is paused.
2389
+ *
2390
+ * \return 1 if music is paused, 0 otherwise.
2391
+ *
2392
+ * \since This function is available since SDL_mixer 2.0.0.
2393
+ *
2394
+ * \sa Mix_PauseMusic
2395
+ * \sa Mix_ResumeMusic
2396
+ */
602
2397
  extern DECLSPEC int SDLCALL Mix_PausedMusic(void);
603
2398
 
604
- /* Set the current position in the music stream.
605
- This returns 0 if successful, or -1 if it failed or isn't implemented.
606
- This function is only implemented for MOD music formats (set pattern
607
- order number) and for OGG, FLAC, MP3_MAD, MP3_MPG and MODPLUG music
608
- (set position in seconds), at the moment.
609
- */
2399
+ /**
2400
+ * Jump to a given order in mod music.
2401
+ *
2402
+ * This only applies to MOD music formats.
2403
+ *
2404
+ * \param order order
2405
+ * \returns 0 if successful, or -1 if failed or isn't implemented.
2406
+ *
2407
+ * \since This function is available since SDL_mixer 2.6.0.
2408
+ */
2409
+ extern DECLSPEC int SDLCALL Mix_ModMusicJumpToOrder(int order);
2410
+
2411
+ /**
2412
+ * Set the current position in the music stream, in seconds.
2413
+ *
2414
+ * To convert from milliseconds, divide by 1000.0.
2415
+ *
2416
+ * This function is only implemented for MOD music formats (set pattern order
2417
+ * number) and for WAV, OGG, FLAC, MP3, and MODPLUG music at the moment.
2418
+ *
2419
+ * \param position the new position, in seconds (as a double).
2420
+ * \returns 0 if successful, or -1 if it failed or not implemented.
2421
+ *
2422
+ * \since This function is available since SDL_mixer 2.0.0.
2423
+ */
610
2424
  extern DECLSPEC int SDLCALL Mix_SetMusicPosition(double position);
611
2425
 
612
- /* Check the status of a specific channel.
613
- If the specified channel is -1, check all channels.
614
- */
2426
+ /**
2427
+ * Get the time current position of music stream, in seconds.
2428
+ *
2429
+ * To convert to milliseconds, multiply by 1000.0.
2430
+ *
2431
+ * \param music the music object to query.
2432
+ * \returns -1.0 if this feature is not supported for some codec.
2433
+ *
2434
+ * \since This function is available since SDL_mixer 2.6.0.
2435
+ */
2436
+ extern DECLSPEC double SDLCALL Mix_GetMusicPosition(Mix_Music *music);
2437
+
2438
+ /**
2439
+ * Get a music object's duration, in seconds.
2440
+ *
2441
+ * To convert to milliseconds, multiply by 1000.0.
2442
+ *
2443
+ * If NULL is passed, returns duration of current playing music.
2444
+ *
2445
+ * \param music the music object to query.
2446
+ * \returns music duration in seconds, or -1.0 on error.
2447
+ *
2448
+ * \since This function is available since SDL_mixer 2.6.0.
2449
+ */
2450
+ extern DECLSPEC double SDLCALL Mix_MusicDuration(Mix_Music *music);
2451
+
2452
+ /**
2453
+ * Get the loop start time position of music stream, in seconds.
2454
+ *
2455
+ * To convert to milliseconds, multiply by 1000.0.
2456
+ *
2457
+ * If NULL is passed, returns duration of current playing music.
2458
+ *
2459
+ * \param music the music object to query.
2460
+ * \returns -1.0 if this feature is not used for this music or not supported
2461
+ * for some codec
2462
+ *
2463
+ * \since This function is available since SDL_mixer 2.6.0.
2464
+ */
2465
+ extern DECLSPEC double SDLCALL Mix_GetMusicLoopStartTime(Mix_Music *music);
2466
+
2467
+ /**
2468
+ * Get the loop end time position of music stream, in seconds.
2469
+ *
2470
+ * To convert to milliseconds, multiply by 1000.0.
2471
+ *
2472
+ * If NULL is passed, returns duration of current playing music.
2473
+ *
2474
+ * \param music the music object to query.
2475
+ * \returns -1.0 if this feature is not used for this music or not supported
2476
+ * for some codec
2477
+ *
2478
+ * \since This function is available since SDL_mixer 2.6.0.
2479
+ */
2480
+ extern DECLSPEC double SDLCALL Mix_GetMusicLoopEndTime(Mix_Music *music);
2481
+
2482
+ /**
2483
+ * Get the loop time length of music stream, in seconds.
2484
+ *
2485
+ * To convert to milliseconds, multiply by 1000.0.
2486
+ *
2487
+ * If NULL is passed, returns duration of current playing music.
2488
+ *
2489
+ * \param music the music object to query.
2490
+ * \returns -1.0 if this feature is not used for this music or not supported
2491
+ * for some codec
2492
+ *
2493
+ * \since This function is available since SDL_mixer 2.6.0.
2494
+ */
2495
+ extern DECLSPEC double SDLCALL Mix_GetMusicLoopLengthTime(Mix_Music *music);
2496
+
2497
+ /**
2498
+ * Check the playing status of a specific channel.
2499
+ *
2500
+ * If the channel is currently playing, this function returns 1. Otherwise it
2501
+ * returns 0.
2502
+ *
2503
+ * If the specified channel is -1, all channels are checked, and this function
2504
+ * returns the number of channels currently playing.
2505
+ *
2506
+ * You may not specify MAX_CHANNEL_POST for a channel.
2507
+ *
2508
+ * Paused channels are treated as playing, even though they are not currently
2509
+ * making forward progress in mixing.
2510
+ *
2511
+ * \param channel channel
2512
+ * \returns non-zero if channel is playing, zero otherwise. If `channel` is
2513
+ * -1, return the total number of channel playings.
2514
+ *
2515
+ * \since This function is available since SDL_mixer 2.0.0.
2516
+ */
615
2517
  extern DECLSPEC int SDLCALL Mix_Playing(int channel);
2518
+
2519
+ /**
2520
+ * Check the playing status of the music stream.
2521
+ *
2522
+ * If music is currently playing, this function returns 1. Otherwise it
2523
+ * returns 0.
2524
+ *
2525
+ * Paused music is treated as playing, even though it is not currently making
2526
+ * forward progress in mixing.
2527
+ *
2528
+ * \returns non-zero if music is playing, zero otherwise.
2529
+ *
2530
+ * \since This function is available since SDL_mixer 2.0.0.
2531
+ */
616
2532
  extern DECLSPEC int SDLCALL Mix_PlayingMusic(void);
617
2533
 
618
- /* Stop music and set external music playback command */
2534
+ /**
2535
+ * Run an external command as the music stream.
2536
+ *
2537
+ * This halts any currently-playing music, and next time the music stream is
2538
+ * played, SDL_mixer will spawn a process using the command line specified in
2539
+ * `command`. This command is not subject to shell expansion, and beyond some
2540
+ * basic splitting up of arguments, is passed to execvp() on most platforms,
2541
+ * not system().
2542
+ *
2543
+ * The command is responsible for generating sound; it is NOT mixed by
2544
+ * SDL_mixer! SDL_mixer will kill the child process if asked to halt the
2545
+ * music, but otherwise does not have any control over what the process does.
2546
+ *
2547
+ * You are strongly encouraged not to use this function without an extremely
2548
+ * good reason.
2549
+ *
2550
+ * \param command command
2551
+ * \returns 0 if successful, -1 on error
2552
+ *
2553
+ * \since This function is available since SDL_mixer 2.0.0.
2554
+ */
619
2555
  extern DECLSPEC int SDLCALL Mix_SetMusicCMD(const char *command);
620
2556
 
621
- /* Synchro value is set by MikMod from modules while playing */
2557
+ /**
2558
+ * This function does nothing, do not use.
2559
+ *
2560
+ * This was probably meant to expose a feature, but no codecs support it, so
2561
+ * it only remains for binary compatibility.
2562
+ *
2563
+ * Calling this function is a legal no-op that returns -1.
2564
+ *
2565
+ * \param value this parameter is ignored.
2566
+ * \returns -1.
2567
+ *
2568
+ * \since This function is available since SDL_mixer 2.0.0.
2569
+ */
622
2570
  extern DECLSPEC int SDLCALL Mix_SetSynchroValue(int value);
2571
+
2572
+ /**
2573
+ * This function does nothing, do not use.
2574
+ *
2575
+ * This was probably meant to expose a feature, but no codecs support it, so
2576
+ * it only remains for binary compatibility.
2577
+ *
2578
+ * Calling this function is a legal no-op that returns -1.
2579
+ *
2580
+ * \returns -1.
2581
+ *
2582
+ * \since This function is available since SDL_mixer 2.0.0.
2583
+ */
623
2584
  extern DECLSPEC int SDLCALL Mix_GetSynchroValue(void);
624
2585
 
625
- /* Set/Get/Iterate SoundFonts paths to use by supported MIDI backends */
2586
+ /**
2587
+ * Set SoundFonts paths to use by supported MIDI backends.
2588
+ *
2589
+ * You may specify multiple paths in a single string by separating them with
2590
+ * semicolons; they will be searched in the order listed.
2591
+ *
2592
+ * This function replaces any previously-specified paths.
2593
+ *
2594
+ * Passing a NULL path will remove any previously-specified paths.
2595
+ *
2596
+ * Note that unlike most SDL and SDL_mixer functions, this function returns
2597
+ * zero if there's an error, not on success. We apologize for the API design
2598
+ * inconsistency here.
2599
+ *
2600
+ * \param paths Paths on the filesystem where SoundFonts are available,
2601
+ * separated by semicolons.
2602
+ * \returns 1 if successful, 0 on error (out of memory).
2603
+ *
2604
+ * \since This function is available since SDL_mixer 2.0.0.
2605
+ */
626
2606
  extern DECLSPEC int SDLCALL Mix_SetSoundFonts(const char *paths);
2607
+
2608
+ /**
2609
+ * Get SoundFonts paths to use by supported MIDI backends.
2610
+ *
2611
+ * There are several factors that determine what will be reported by this
2612
+ * function:
2613
+ *
2614
+ * - If the boolean _SDL hint_ `"SDL_FORCE_SOUNDFONTS"` is set, AND the
2615
+ * `"SDL_SOUNDFONTS"` _environment variable_ is also set, this function will
2616
+ * return that environment variable regardless of whether
2617
+ * Mix_SetSoundFounts() was ever called.
2618
+ * - Otherwise, if Mix_SetSoundFonts() was successfully called with a non-NULL
2619
+ * path, this function will return the string passed to that function.
2620
+ * - Otherwise, if the `"SDL_SOUNDFONTS"` variable is set, this function will
2621
+ * return that environment variable.
2622
+ * - Otherwise, this function will search some common locations on the
2623
+ * filesystem, and if it finds a SoundFont there, it will return that.
2624
+ * - Failing everything else, this function returns NULL.
2625
+ *
2626
+ * This returns a pointer to internal (possibly read-only) memory, and it
2627
+ * should not be modified or free'd by the caller.
2628
+ *
2629
+ * \returns semicolon-separated list of sound font paths.
2630
+ *
2631
+ * \since This function is available since SDL_mixer 2.0.0.
2632
+ */
627
2633
  extern DECLSPEC const char* SDLCALL Mix_GetSoundFonts(void);
2634
+
2635
+ /**
2636
+ * Iterate SoundFonts paths to use by supported MIDI backends.
2637
+ *
2638
+ * This function will take the string reported by Mix_GetSoundFonts(), split
2639
+ * it up into separate paths, as delimited by semicolons in the string, and
2640
+ * call a callback function for each separate path.
2641
+ *
2642
+ * If there are no paths available, this returns 0 without calling the
2643
+ * callback at all.
2644
+ *
2645
+ * If the callback returns non-zero, this function stops iterating and returns
2646
+ * non-zero. If the callback returns 0, this function will continue iterating,
2647
+ * calling the callback again for further paths. If the callback never returns
2648
+ * 1, this function returns 0, so this can be used to decide if an available
2649
+ * soundfont is acceptable for use.
2650
+ *
2651
+ * \param function the callback function to call once per path.
2652
+ * \param data a pointer to pass to the callback for its own personal use.
2653
+ * \returns non-zero if callback ever returned non-zero, 0 on error or the
2654
+ * callback never returned non-zero.
2655
+ *
2656
+ * \since This function is available since SDL_mixer 2.0.0.
2657
+ *
2658
+ * \sa Mix_GetSoundFonts
2659
+ */
628
2660
  extern DECLSPEC int SDLCALL Mix_EachSoundFont(int (SDLCALL *function)(const char*, void*), void *data);
629
2661
 
630
- /* Get the Mix_Chunk currently associated with a mixer channel
631
- Returns NULL if it's an invalid channel, or there's no chunk associated.
632
- */
2662
+ /**
2663
+ * Set full path of the Timidity config file.
2664
+ *
2665
+ * For example, "/etc/timidity.cfg"
2666
+ *
2667
+ * This is obviously only useful if SDL_mixer is using Timidity internally to
2668
+ * play MIDI files.
2669
+ *
2670
+ * \param path path to a Timidity config file.
2671
+ * \returns 1 if successful, 0 on error
2672
+ *
2673
+ * \since This function is available since SDL_mixer 2.6.0.
2674
+ */
2675
+ extern DECLSPEC int SDLCALL Mix_SetTimidityCfg(const char *path);
2676
+
2677
+ /**
2678
+ * Get full path of a previously-specified Timidity config file.
2679
+ *
2680
+ * For example, "/etc/timidity.cfg"
2681
+ *
2682
+ * If a path has never been specified, this returns NULL.
2683
+ *
2684
+ * This returns a pointer to internal memory, and it should not be modified or
2685
+ * free'd by the caller.
2686
+ *
2687
+ * \returns the previously-specified path, or NULL if not set.
2688
+ *
2689
+ * \since This function is available since SDL_mixer 2.6.0.
2690
+ *
2691
+ * \sa Mix_SetTimidityCfg
2692
+ */
2693
+ extern DECLSPEC const char* SDLCALL Mix_GetTimidityCfg(void);
2694
+
2695
+ /**
2696
+ * Get the Mix_Chunk currently associated with a mixer channel.
2697
+ *
2698
+ * You may not specify MAX_CHANNEL_POST or -1 for a channel.
2699
+ *
2700
+ * \param channel the channel to query.
2701
+ * \returns the associated chunk, if any, or NULL if it's an invalid channel.
2702
+ *
2703
+ * \since This function is available since SDL_mixer 2.0.0.
2704
+ */
633
2705
  extern DECLSPEC Mix_Chunk * SDLCALL Mix_GetChunk(int channel);
634
2706
 
635
- /* Close the mixer, halting all playing audio */
2707
+ /**
2708
+ * Close the mixer, halting all playing audio.
2709
+ *
2710
+ * Any halted channels will have any currently-registered effects
2711
+ * deregistered, and will call any callback specified by Mix_ChannelFinished()
2712
+ * before this function returns.
2713
+ *
2714
+ * Any halted music will call any callback specified by
2715
+ * Mix_HookMusicFinished() before this function returns.
2716
+ *
2717
+ * Do not start any new audio playing during callbacks in this function.
2718
+ *
2719
+ * This will close the audio device. Attempting to play new audio after this
2720
+ * function returns will fail, until another successful call to
2721
+ * Mix_OpenAudio() or Mix_OpenAudioDevice().
2722
+ *
2723
+ * Note that (unlike Mix_OpenAudio optionally calling SDL_Init(SDL_INIT_AUDIO)
2724
+ * on the app's behalf), this will _not_ deinitialize the SDL audio subsystem
2725
+ * in any case. At some point after calling this function and Mix_Quit(), some
2726
+ * part of the application should be responsible for calling SDL_Quit() to
2727
+ * deinitialize all of SDL, including its audio subsystem.
2728
+ *
2729
+ * This function should be the last thing you call in SDL_mixer before
2730
+ * Mix_Quit(). However, the following notes apply if you don't follow this
2731
+ * advice:
2732
+ *
2733
+ * Note that this will not free any loaded chunks or music; you should dispose
2734
+ * of those resources separately. It is probably poor form to dispose of them
2735
+ * _after_ this function, but it is safe to call Mix_FreeChunk() and
2736
+ * Mix_FreeMusic() after closing the device.
2737
+ *
2738
+ * Note that any chunks or music you don't free may or may not work if you
2739
+ * call Mix_OpenAudio again, as the audio device may be in a new format and
2740
+ * the existing chunks will not be converted to match.
2741
+ *
2742
+ * \since This function is available since SDL_mixer 2.0.0.
2743
+ *
2744
+ * \sa Mix_Quit
2745
+ */
636
2746
  extern DECLSPEC void SDLCALL Mix_CloseAudio(void);
637
2747
 
638
2748
  /* We'll use SDL for reporting errors */
2749
+
2750
+ /**
2751
+ * Report SDL_mixer errors
2752
+ *
2753
+ * \sa Mix_GetError
2754
+ */
639
2755
  #define Mix_SetError SDL_SetError
2756
+
2757
+ /**
2758
+ * Get last SDL_mixer error
2759
+ *
2760
+ * \sa Mix_SetError
2761
+ */
640
2762
  #define Mix_GetError SDL_GetError
2763
+
2764
+ /**
2765
+ * Clear last SDL_mixer error
2766
+ *
2767
+ * \sa Mix_SetError
2768
+ */
641
2769
  #define Mix_ClearError SDL_ClearError
642
2770
 
2771
+ /**
2772
+ * Set OutOfMemory error
2773
+ */
2774
+ #define Mix_OutOfMemory SDL_OutOfMemory
2775
+
643
2776
  /* Ends C function definitions when using C++ */
644
2777
  #ifdef __cplusplus
645
2778
  }