Commit 6bd63a32522acc1a30b2e8a2eab50b9b164980a6 - libsdl2-mixer

Update upstream source from tag 'upstream/2.5.3+dfsg' Update to upstream version '2.5.3+dfsg' with Debian dir d22df987d10cfcff7482a3ea632c193856e22d1b Simon McVittie 1 year, 9 months ago

10 changed file(s) with 2440 addition(s) and 368 deletion(s). Raw diff Collapse all Expand all

-0

CHANGES.txt less more

0	0	2.6.0:
	1	* Added support for building with CMake
1	2	* Added support for playing Ogg files using stb_vorbis, which is now the default Vorbis backend.
2	3	To use libvorbis instead, configure using --disable-music-ogg-stb --enable-music-ogg-vorbis
3	4	* Added support for playing FLAC files using dr_flac, which is now the default FLAC music backend.

-1

CMakeLists.txt less more

4	4	# See docs/release_checklist.md
5	5	set(MAJOR_VERSION 2)
6	6	set(MINOR_VERSION 5)
7		set(MICRO_VERSION 2)
	7	set(MICRO_VERSION 3)
8	8	set(SDL_REQUIRED_VERSION 2.0.9)
9	9
10	10	# For historical reasons this is 3.0.0 rather than the expected 1.0.0

-1

Makefile.in less more

24	24	EXTRA_CFLAGS = @EXTRA_CFLAGS@
25	25	LDFLAGS = @BUILD_LDFLAGS@
26	26	EXTRA_LDFLAGS = @EXTRA_LDFLAGS@
	27	MIXER_LIBS = @MIXER_LIBS@
27	28	LIBTOOL = @LIBTOOL@
28	29	INSTALL = @INSTALL@
29	30	AR = @AR@

93	94	.PHONY: all install install-hdrs install-lib install-bin uninstall uninstall-hdrs uninstall-lib uninstall-bin clean distclean dist
94	95
95	96	$(objects)/$(TARGET): $(OBJECTS) $(VERSION_OBJECTS)
96		$(LIBTOOL) --mode=link $(CC) -o $@ $(OBJECTS) $(VERSION_OBJECTS) $(LDFLAGS) $(EXTRA_LDFLAGS) $(LT_LDFLAGS)
	97	$(LIBTOOL) --mode=link $(CC) -o $@ $(OBJECTS) $(VERSION_OBJECTS) $(LDFLAGS) $(EXTRA_LDFLAGS) $(LT_LDFLAGS) $(SDL_LIBS) $(MIXER_LIBS)
97	98
98	99	$(objects)/playwave$(EXE): $(objects)/playwave.lo $(objects)/$(TARGET)
99	100	$(LIBTOOL) --mode=link $(CC) -o $@ $(objects)/playwave.lo $(SDL_CFLAGS) $(objects)/$(TARGET) $(SDL_LIBS) $(LDFLAGS)

-1

Makefile.os2 less more

6	6	LIBNAME = SDL2mix
7	7	MAJOR_VERSION = 2
8	8	MINOR_VERSION = 5
9		MICRO_VERSION = 2
	9	MICRO_VERSION = 3
10	10	VERSION = $(MAJOR_VERSION).$(MINOR_VERSION).$(MICRO_VERSION)
11	11
12	12	TITLENAME = $(LIBNAME) $(VERSION)

-5

README.txt less more

0	0
1	1	SDL_mixer 2.0
2	2
3		The latest version of this library is available from:
4		http://www.libsdl.org/projects/SDL_mixer/
	3	The latest version of this library is available from GitHub:
	4	https://github.com/libsdl-org/SDL_mixer/releases
5	5
6	6	Due to popular demand, here is a simple multi-channel audio mixer.
7	7	It supports 8 channels of 16 bit stereo audio, plus a single channel of music. It can load FLAC, MP3, Ogg, VOC, and WAV format audio. It can also load MIDI, MOD, and Opus audio, depending on build options (see the note below for details.)
8	8
9		See the header file SDL_mixer.h and the examples playwave.c and playmus.c
10		for documentation on this mixer library.
	9	See the header file SDL_mixer.h and the examples playwave.c and playmus.c for documentation on this mixer library. This documentation is also available online at https://wiki.libsdl.org/SDL_mixer
11	10
12	11	The process of mixing MIDI files to wave output is very CPU intensive, so if playing regular WAVE files sound great, but playing MIDI files sound choppy, try using 8-bit audio, mono audio, or lower frequencies.
13	12
14		To play MIDI files using FluidSynth, you'll need to set the SDL_SOUNDFONTS environment variable to a Sound Font 2 (.sf2) file containing the musical instruments you want to use for MIDI playback.
	13	If you have built with FluidSynth support, you'll need to set the SDL_SOUNDFONTS environment variable to a Sound Font 2 (.sf2) file containing the musical instruments you want to use for MIDI playback.
15	14	(On some Linux distributions you can install the fluid-soundfont-gm package)
16	15
17	16	To play MIDI files using Timidity, you'll need to get a complete set of GUS patches from:

+18

-19

configure.ac less more

3	3	# See release_checklist.md
4	4	m4_define([MAJOR_VERSION_MACRO], [2])
5	5	m4_define([MINOR_VERSION_MACRO], [5])
6		m4_define([MICRO_VERSION_MACRO], [2])
	6	m4_define([MICRO_VERSION_MACRO], [3])
7	7
8	8	AC_INIT([SDL2_mixer],
9	9	[MAJOR_VERSION_MACRO.MINOR_VERSION_MACRO.MICRO_VERSION_MACRO],

57	57	AC_SUBST(LT_REVISION)
58	58	AC_SUBST(LT_AGE)
59	59	AC_SUBST(LT_EXTRA)
60
61		dnl For use in static assertions
62		AC_DEFINE_UNQUOTED([SDL_BUILD_MAJOR_VERSION], $MAJOR_VERSION, [ ])
63		AC_DEFINE_UNQUOTED([SDL_BUILD_MINOR_VERSION], $MINOR_VERSION, [ ])
64		AC_DEFINE_UNQUOTED([SDL_BUILD_MICRO_VERSION], $MICRO_VERSION, [ ])
65	60
66	61	dnl Detect the canonical build and host environments
67	62	dnl AC_CANONICAL_HOST

110	105	EXTRA_CFLAGS="$INCLUDE $BASE_CFLAGS"
111	106	BUILD_LDFLAGS="$LDFLAGS"
112	107	EXTRA_LDFLAGS="$BASE_LDFLAGS"
	108	MIXER_LIBS=
113	109	## These are common directories to find software packages
114	110	#for path in /usr/freeware /usr/pkg /usr/local; do
115	111	# if test -d $path/include; then

278	274	AC_MSG_ERROR([*** SDL version $SDL_VERSION not found!])
279	275	)
280	276	EXTRA_CFLAGS="$EXTRA_CFLAGS $SDL_CFLAGS"
281		EXTRA_LDFLAGS="$EXTRA_LDFLAGS $SDL_LIBS"
	277
	278	dnl For use in static assertions
	279	EXTRA_CFLAGS="$EXTRA_CFLAGS -DSDL_BUILD_MAJOR_VERSION=$MAJOR_VERSION -DSDL_BUILD_MINOR_VERSION=$MINOR_VERSION -DSDL_BUILD_MICRO_VERSION=$MICRO_VERSION"
282	280
283	281	dnl check for GCC warning options
284	282	CheckWarnAll

366	364	echo "-- dynamic libmodplug -> $modplug_lib"
367	365	EXTRA_CFLAGS="$EXTRA_CFLAGS -DMODPLUG_DYNAMIC=\\\"$modplug_lib\\\""
368	366	else
369		EXTRA_LDFLAGS="$EXTRA_LDFLAGS $MODPLUG_LIBS"
	367	MIXER_LIBS="$MIXER_LIBS $MODPLUG_LIBS"
370	368	if test x$have_libmodplug_pc = xyes; then
371	369	PC_REQUIRES="$PC_REQUIRES libmodplug"
372	370	else

425	423	echo "-- dynamic libxmp -> $xmp_lib"
426	424	EXTRA_CFLAGS="$EXTRA_CFLAGS -DXMP_DYNAMIC=\\\"$xmp_lib\\\""
427	425	else
428		EXTRA_LDFLAGS="$EXTRA_LDFLAGS $XMP_LIBS"
	426	MIXER_LIBS="$MIXER_LIBS $XMP_LIBS"
429	427	if test x$have_libxmp_pc = xyes; then
430	428	PC_REQUIRES="$PC_REQUIRES lib$xmplib"
431	429	else

475	473	case "$host" in
476	474	--cygwin* \| --mingw*)
477	475	use_music_midi_native=yes
478		EXTRA_LDFLAGS="$EXTRA_LDFLAGS -lwinmm"
	476	MIXER_LIBS="$MIXER_LIBS -lwinmm"
479	477	PC_LIBS="$PC_LIBS -lwinmm"
480	478	;;
481	479	--darwin*)
482	480	use_music_midi_native=yes
483		EXTRA_LDFLAGS="$EXTRA_LDFLAGS -Wl,-framework,AudioToolbox -Wl,-framework,AudioUnit -Wl,-framework,CoreServices"
	481	MIXER_LIBS="$MIXER_LIBS -Wl,-framework,AudioToolbox -Wl,-framework,AudioUnit -Wl,-framework,CoreServices"
484	482	PC_LIBS="$PC_LIBS -Wl,-framework,AudioToolbox -Wl,-framework,AudioUnit -Wl,-framework,CoreServices"
485	483	;;
486	484	--haiku*)
487	485	use_music_midi_native=yes_cpp
488		EXTRA_LDFLAGS="$EXTRA_LDFLAGS -lmidi"
	486	MIXER_LIBS="$MIXER_LIBS -lmidi"
489	487	PC_LIBS="$PC_LIBS -lmidi"
490	488	;;
491	489	esac

539	537	echo "-- dynamic libfluidsynth -> $fluidsynth_lib"
540	538	EXTRA_CFLAGS="$EXTRA_CFLAGS -DFLUIDSYNTH_DYNAMIC=\\\"$fluidsynth_lib\\\""
541	539	else
542		EXTRA_LDFLAGS="$EXTRA_LDFLAGS $FLUIDSYNTH_LIBS"
	540	MIXER_LIBS="$MIXER_LIBS $FLUIDSYNTH_LIBS"
543	541	if test x$have_fluidsynth_pc = xyes; then
544	542	PC_REQUIRES="$PC_REQUIRES fluidsynth"
545	543	else

614	612	echo "-- dynamic libvorbisfile -> $ogg_lib"
615	613	EXTRA_CFLAGS="$EXTRA_CFLAGS -DOGG_DYNAMIC=\\\"$ogg_lib\\\""
616	614	else
617		EXTRA_LDFLAGS="$EXTRA_LDFLAGS $VORBIS_LIBS"
	615	MIXER_LIBS="$MIXER_LIBS $VORBIS_LIBS"
618	616	if test x$have_ogg_pc = xyes; then
619	617	PC_REQUIRES="$PC_REQUIRES vorbisfile"
620	618	else

670	668	echo "-- dynamic libvorbisidec -> $ogg_lib"
671	669	EXTRA_CFLAGS="$EXTRA_CFLAGS -DOGG_DYNAMIC=\\\"$ogg_lib\\\""
672	670	else
673		EXTRA_LDFLAGS="$EXTRA_LDFLAGS $TREMOR_LIBS"
	671	MIXER_LIBS="$MIXER_LIBS $TREMOR_LIBS"
674	672	if test x$have_tremor_pc = xyes; then
675	673	PC_REQUIRES="$PC_REQUIRES vorbisidec"
676	674	else

757	755	echo "-- dynamic libFLAC -> $flac_lib"
758	756	EXTRA_CFLAGS="$EXTRA_CFLAGS -DFLAC_DYNAMIC=\\\"$flac_lib\\\""
759	757	else
760		EXTRA_LDFLAGS="$EXTRA_LDFLAGS $FLAC_LIBS"
	758	MIXER_LIBS="$MIXER_LIBS $FLAC_LIBS"
761	759	if test x$have_flac_pc = xyes; then
762	760	PC_REQUIRES="$PC_REQUIRES flac"
763	761	else

823	821	echo "-- dynamic libmpg123 -> $mpg123_lib"
824	822	EXTRA_CFLAGS="$EXTRA_CFLAGS -DMPG123_DYNAMIC=\\\"$mpg123_lib\\\""
825	823	else
826		EXTRA_LDFLAGS="$EXTRA_LDFLAGS $MPG123_LIBS"
	824	MIXER_LIBS="$MIXER_LIBS $MPG123_LIBS"
827	825	if test x$have_mpg123_pc = xyes; then
828	826	PC_REQUIRES="$PC_REQUIRES libmpg123"
829	827	else

880	878	echo "-- dynamic opusfile -> $opusfile_lib"
881	879	EXTRA_CFLAGS="$EXTRA_CFLAGS -DOPUS_DYNAMIC=\\\"$opusfile_lib\\\""
882	880	else
883		EXTRA_LDFLAGS="$EXTRA_LDFLAGS $OPUSFILE_LIBS"
	881	MIXER_LIBS="$MIXER_LIBS $OPUSFILE_LIBS"
884	882	if test x$have_opusfile_pc = xyes; then
885	883	PC_REQUIRES="$PC_REQUIRES opusfile"
886	884	else

897	895	dnl check for LD --no-undefined option
898	896	CheckNoUndef
899	897
900		EXTRA_LDFLAGS="$EXTRA_LDFLAGS $LIBM"
	898	MIXER_LIBS="$MIXER_LIBS $LIBM"
901	899
902	900	OBJECTS=`echo $SOURCES`
903	901	DEPENDS=`echo $SOURCES`

958	956	AC_SUBST(EXTRA_CFLAGS)
959	957	AC_SUBST(BUILD_LDFLAGS)
960	958	AC_SUBST(EXTRA_LDFLAGS)
	959	AC_SUBST(MIXER_LIBS)
961	960	AC_SUBST(EXE)
962	961	AC_SUBST(SDL_VERSION)
963	962	AC_SUBST(SDL_CFLAGS)

+2385

-335

include/SDL_mixer.h less more

18	18	3. This notice may not be removed or altered from any source distribution.
19	19	*/
20	20
	21	/**
	22	* \file SDL_mixer.h
	23	*
	24	* Header file for SDL_mixer library
	25	*
	26	* A simple library to play and mix sounds and musics
	27	*/
21	28	#ifndef SDL_MIXER_H_
22	29	#define SDL_MIXER_H_
23	30

33	40	extern "C" {
34	41	#endif
35	42
36		/* Printable format: "%d.%d.%d", MAJOR, MINOR, PATCHLEVEL
37		*/
	43	/**
	44	* Printable format: "%d.%d.%d", MAJOR, MINOR, PATCHLEVEL
	45	*/
38	46	#define SDL_MIXER_MAJOR_VERSION 2
39	47	#define SDL_MIXER_MINOR_VERSION 5
40		#define SDL_MIXER_PATCHLEVEL 2
41
42		/* This macro can be used to fill a version structure with the compile-time
	48	#define SDL_MIXER_PATCHLEVEL 3
	49
	50	/**
	51	* This macro can be used to fill a version structure with the compile-time
43	52	* version of the SDL_mixer library.
44	53	*/
45	54	#define SDL_MIXER_VERSION(X) \

77	86	(SDL_MIXER_MAJOR_VERSION > X \|\| SDL_MIXER_MINOR_VERSION >= Y) && \
78	87	(SDL_MIXER_MAJOR_VERSION > X \|\| SDL_MIXER_MINOR_VERSION > Y \|\| SDL_MIXER_PATCHLEVEL >= Z))
79	88
80		/* This function gets the version of the dynamically linked SDL_mixer library.
81		it should NOT be used to fill a version structure, instead you should
82		use the SDL_MIXER_VERSION() macro.
	89	/**
	90	* Query the version of SDL_mixer that the program is linked against.
	91	*
	92	* This function gets the version of the dynamically linked SDL_mixer library.
	93	* This is separate from the SDL_MIXER_VERSION() macro, which tells you what
	94	* version of the SDL_mixer headers you compiled against.
	95	*
	96	* This returns static internal data; do not free or modify it!
	97	*
	98	* \returns a pointer to the version information.
	99	*
	100	* \since This function is available since SDL_mixer 2.0.0.
83	101	*/
84	102	extern DECLSPEC const SDL_version * SDLCALL Mix_Linked_Version(void);
85	103
	104	/**
	105	* Initialization flags
	106	*/
86	107	typedef enum
87	108	{
88	109	MIX_INIT_FLAC = 0x00000001,

93	114	MIX_INIT_OPUS = 0x00000040
94	115	} MIX_InitFlags;
95	116
96		/* Loads dynamic libraries and prepares them for use. Flags should be
97		one or more flags from MIX_InitFlags OR'd together.
98		It returns the flags successfully initialized, or 0 on failure.
	117	/**
	118	* Initialize SDL_mixer.
	119	*
	120	* This function loads dynamic libraries that SDL_mixer needs, and prepares
	121	* them for use. This must be the first function you call in SDL_mixer, and if
	122	* it fails you should not continue with the library.
	123	*
	124	* Flags should be one or more flags from MIX_InitFlags OR'd together. It
	125	* returns the flags successfully initialized, or 0 on failure.
	126	*
	127	* Currently, these flags are:
	128	*
	129	* - `MIX_INIT_FLAC`
	130	* - `MIX_INIT_MOD`
	131	* - `MIX_INIT_MP3`
	132	* - `MIX_INIT_OGG`
	133	* - `MIX_INIT_MID`
	134	* - `MIX_INIT_OPUS`
	135	*
	136	* More flags may be added in a future SDL_mixer release.
	137	*
	138	* This function may need to load external shared libraries to support various
	139	* codecs, which means this function can fail to initialize that support on an
	140	* otherwise-reasonable system if the library isn't available; this is not
	141	* just a question of exceptional circumstances like running out of memory at
	142	* startup!
	143	*
	144	* Note that you may call this function more than once to initialize with
	145	* additional flags. The return value will reflect both new flags that
	146	* successfully initialized, and also include flags that had previously been
	147	* initialized as well.
	148	*
	149	* As this will return previously-initialized flags, it's legal to call this
	150	* with zero (no flags set). This is a safe no-op that can be used to query
	151	* the current initialization state without changing it at all.
	152	*
	153	* Since this returns previously-initialized flags as well as new ones, and
	154	* you can call this with zero, you should not check for a zero return value
	155	* to determine an error condition. Instead, you should check to make sure all
	156	* the flags you require are set in the return value. If you have a game with
	157	* data in a specific format, this might be a fatal error. If you're a generic
	158	* media player, perhaps you are fine with only having WAV and MP3 support and
	159	* can live without Opus playback, even if you request support for everything.
	160	*
	161	* Unlike other SDL satellite libraries, calls to Mix_Init do not stack; a
	162	* single call to Mix_Quit() will deinitialize everything and does not have to
	163	* be paired with a matching Mix_Init call. For that reason, it's considered
	164	* best practices to have a single Mix_Init and Mix_Quit call in your program.
	165	* While this isn't required, be aware of the risks of deviating from that
	166	* behavior.
	167	*
	168	* After initializing SDL_mixer, the next step is to open an audio device to
	169	* prepare to play sound (with Mix_OpenAudio() or Mix_OpenAudioDevice()), and
	170	* load audio data to play with that device.
	171	*
	172	* \param flags initialization flags, OR'd together.
	173	* \returns all currently initialized flags.
	174	*
	175	* \since This function is available since SDL_mixer 2.0.0.
	176	*
	177	* \sa Mix_Quit
99	178	*/
100	179	extern DECLSPEC int SDLCALL Mix_Init(int flags);
101	180
102		/* Unloads libraries loaded with Mix_Init */
	181	/**
	182	* Deinitialize SDL_mixer.
	183	*
	184	* This should be the last function you call in SDL_mixer, after freeing all
	185	* other resources and closing all audio devices. This will unload any shared
	186	* libraries it is using for various codecs.
	187	*
	188	* After this call, a call to Mix_Init(0) will return 0 (no codecs loaded).
	189	*
	190	* You can safely call Mix_Init() to reload various codec support after this
	191	* call.
	192	*
	193	* Unlike other SDL satellite libraries, calls to Mix_Init do not stack; a
	194	* single call to Mix_Quit() will deinitialize everything and does not have to
	195	* be paired with a matching Mix_Init call. For that reason, it's considered
	196	* best practices to have a single Mix_Init and Mix_Quit call in your program.
	197	* While this isn't required, be aware of the risks of deviating from that
	198	* behavior.
	199	*
	200	* \since This function is available since SDL_mixer 2.0.0.
	201	*
	202	* \sa Mix_Init
	203	*/
103	204	extern DECLSPEC void SDLCALL Mix_Quit(void);
104	205
105	206
106		/* The default mixer has 8 simultaneous mixing channels */
	207	/**
	208	* The default mixer has 8 simultaneous mixing channels
	209	*/
107	210	#ifndef MIX_CHANNELS
108	211	#define MIX_CHANNELS 8
109	212	#endif

118	221	#define MIX_DEFAULT_CHANNELS 2
119	222	#define MIX_MAX_VOLUME SDL_MIX_MAXVOLUME /* Volume of a chunk */
120	223
121		/* The internal format for an audio chunk */
	224	/**
	225	* The internal format for an audio chunk
	226	*/
122	227	typedef struct Mix_Chunk {
123	228	int allocated;
124	229	Uint8 *abuf;

126	231	Uint8 volume; /* Per-sample volume, 0-128 */
127	232	} Mix_Chunk;
128	233
129		/* The different fading types supported */
	234	/**
	235	* The different fading types supported
	236	*/
130	237	typedef enum {
131	238	MIX_NO_FADING,
132	239	MIX_FADING_OUT,
133	240	MIX_FADING_IN
134	241	} Mix_Fading;
135	242
136		/* These are types of music files (not libraries used to load them) */
	243	/**
	244	* These are types of music files (not libraries used to load them)
	245	*/
137	246	typedef enum {
138	247	MUS_NONE,
139	248	MUS_CMD,

148	257	MUS_OPUS
149	258	} Mix_MusicType;
150	259
151		/* The internal format for a music chunk interpreted via codecs */
	260	/**
	261	* The internal format for a music chunk interpreted via codecs
	262	*/
152	263	typedef struct _Mix_Music Mix_Music;
153	264
154		/* Open the mixer with a certain audio format */
	265	/**
	266	* Open the default audio device for playback.
	267	*
	268	* An audio device is what generates sound, so the app must open one to make
	269	* noise.
	270	*
	271	* This function will check if SDL's audio system is initialized, and if not,
	272	* it will initialize it by calling `SDL_Init(SDL_INIT_AUDIO)` on your behalf.
	273	* You are free to (and encouraged to!) initialize it yourself before calling
	274	* this function, as this gives your program more control over the process.
	275	*
	276	* This function might cover all of an application's needs, but for those that
	277	* need more flexibility, the more powerful version of this function is
	278	* Mix_OpenAudioDevice(). This function is equivalent to calling:
	279	*
	280	* ```c
	281	* Mix_OpenAudioDevice(frequency, format, nchannels, chunksize, NULL,
	282	* SDL_AUDIO_ALLOW_FREQUENCY_CHANGE \|
	283	* SDL_AUDIO_ALLOW_CHANNELS_CHANGE);
	284	* ```
	285	*
	286	* If you aren't particularly concerned with the specifics of the audio
	287	* device, and your data isn't in a specific format, the values you use here
	288	* can just be reasonable defaults. SDL_mixer will convert audio data you feed
	289	* it to the correct format on demand.
	290	*
	291	* That being said, if you have control of your audio data and you know its
	292	* format ahead of time, you can save CPU time by opening the audio device in
	293	* that exact format so SDL_mixer does not have to spend time converting
	294	* anything behind the scenes, and can just pass the data straight through to
	295	* the hardware. On some platforms, where the hardware only supports specific
	296	* settings, you might have to be careful to make everything match, but your
	297	* own data is often easier to control, so aim to open the device for what you
	298	* need.
	299	*
	300	* The other reason to care about specific formats: if you plan to touch the
	301	* mix buffer directly (with Mix_SetPostMix, a registered effect, or
	302	* Mix_HookMusic), you might have code that expects it to be in a specific
	303	* format, and you should specify that here.
	304	*
	305	* The audio device frequency is specified in Hz; in modern times, 48000 is
	306	* often a reasonable default.
	307	*
	308	* The audio device format is one of SDL's AUDIO_* constants. AUDIO_S16SYS
	309	* (16-bit audio) is probably a safe default. More modern systems may prefer
	310	* AUDIO_F32SYS (32-bit floating point audio).
	311	*
	312	* The audio device channels are generally 1 for mono output, or 2 for stereo,
	313	* but the brave can try surround sound configs with 4 (quad), 6 (5.1), 7
	314	* (6.1) or 8 (7.1).
	315	*
	316	* The audio device's chunk size is the number of sample frames (one sample
	317	* per frame for mono output, two samples per frame in a stereo setup, etc)
	318	* that are fed to the device at once. The lower the number, the lower the
	319	* latency, but you risk dropouts if it gets too low. 2048 is often a
	320	* reasonable default, but your app might want to experiment with 1024 or
	321	* 4096.
	322	*
	323	* You may only have one audio device open at a time; if you want to change a
	324	* setting, you must close the device and reopen it, which is not something
	325	* you can do seamlessly during playback.
	326	*
	327	* This function does not allow you to select a specific audio device on the
	328	* system, it always chooses the best default it can on your behalf (which, in
	329	* many cases, is exactly what you want anyhow). If you must choose a specific
	330	* device, you can do so with Mix_OpenAudioDevice() instead.
	331	*
	332	* If this function reports success, you are ready to start making noise! Load
	333	* some audio data and start playing!
	334	*
	335	* The app can use Mix_QuerySpec() to determine the final device settings.
	336	*
	337	* When done with an audio device, probably at the end of the program, the app
	338	* should dispose of the device with Mix_CloseDevice().
	339	*
	340	* \param frequency the frequency to playback audio at (in Hz).
	341	* \param format audio format, one of SDL's AUDIO_* values.
	342	* \param channels number of channels (1 is mono, 2 is stereo, etc).
	343	* \param chunksize audio buffer size in sample FRAMES (total samples divided
	344	* by channel count).
	345	* \returns 0 if successful, -1 on error.
	346	*
	347	* \since This function is available since SDL_mixer 2.0.0.
	348	*
	349	* \sa Mix_OpenAudioDevice
	350	* \sa Mix_CloseDevice
	351	*/
155	352	extern DECLSPEC int SDLCALL Mix_OpenAudio(int frequency, Uint16 format, int channels, int chunksize);
156	353
157		/* Open the mixer with specific device and certain audio format */
	354
	355	/**
	356	* Open a specific audio device for playback.
	357	*
	358	* (A slightly simpler version of this function is available in
	359	* Mix_OpenAudio(), which still might meet most applications' needs.)
	360	*
	361	* An audio device is what generates sound, so the app must open one to make
	362	* noise.
	363	*
	364	* This function will check if SDL's audio system is initialized, and if not,
	365	* it will initialize it by calling `SDL_Init(SDL_INIT_AUDIO)` on your behalf.
	366	* You are free to (and encouraged to!) initialize it yourself before calling
	367	* this function, as this gives your program more control over the process.
	368	*
	369	* If you aren't particularly concerned with the specifics of the audio
	370	* device, and your data isn't in a specific format, the values you use here
	371	* can just be reasonable defaults. SDL_mixer will convert audio data you feed
	372	* it to the correct format on demand.
	373	*
	374	* That being said, if you have control of your audio data and you know its
	375	* format ahead of time, you can save CPU time by opening the audio device in
	376	* that exact format so SDL_mixer does not have to spend time converting
	377	* anything behind the scenes, and can just pass the data straight through to
	378	* the hardware. On some platforms, where the hardware only supports specific
	379	* settings, you might have to be careful to make everything match, but your
	380	* own data is often easier to control, so aim to open the device for what you
	381	* need.
	382	*
	383	* The other reason to care about specific formats: if you plan to touch the
	384	* mix buffer directly (with Mix_SetPostMix, a registered effect, or
	385	* Mix_HookMusic), you might have code that expects it to be in a specific
	386	* format, and you should specify that here.
	387	*
	388	* The audio device frequency is specified in Hz; in modern times, 48000 is
	389	* often a reasonable default.
	390	*
	391	* The audio device format is one of SDL's AUDIO_* constants. AUDIO_S16SYS
	392	* (16-bit audio) is probably a safe default. More modern systems may prefer
	393	* AUDIO_F32SYS (32-bit floating point audio).
	394	*
	395	* The audio device channels are generally 1 for mono output, or 2 for stereo,
	396	* but the brave can try surround sound configs with 4 (quad), 6 (5.1), 7
	397	* (6.1) or 8 (7.1).
	398	*
	399	* The audio device's chunk size is the number of sample frames (one sample
	400	* per frame for mono output, two samples per frame in a stereo setup, etc)
	401	* that are fed to the device at once. The lower the number, the lower the
	402	* latency, but you risk dropouts if it gets too low. 2048 is often a
	403	* reasonable default, but your app might want to experiment with 1024 or
	404	* 4096.
	405	*
	406	* You may only have one audio device open at a time; if you want to change a
	407	* setting, you must close the device and reopen it, which is not something
	408	* you can do seamlessly during playback.
	409	*
	410	* This function allows you to select specific audio hardware on the system
	411	* with the `device` parameter. If you specify NULL, SDL_mixer will choose the
	412	* best default it can on your behalf (which, in many cases, is exactly what
	413	* you want anyhow). SDL_mixer does not offer a mechanism to determine device
	414	* names to open, but you can use SDL_GetNumAudioDevices() to get a count of
	415	* available devices and then SDL_GetAudioDeviceName() in a loop to obtain a
	416	* list. If you do this, be sure to call `SDL_Init(SDL_INIT_AUDIO)` first to
	417	* initialize SDL's audio system!
	418	*
	419	* The `allowed_changes` parameter specifies what settings are flexible. These
	420	* are the `SDL_AUDIO_ALLOW_*` flags from SDL. These tell SDL_mixer that the
	421	* app doesn't mind if a specific setting changes. For example, the app might
	422	* need stereo data in Sint16 format, but if the sample rate or chunk size
	423	* changes, the app can handle that. In that case, the app would specify
	424	* `SDL_AUDIO_ALLOW_FORMAT_CHANGE\|SDL_AUDIO_ALLOW_SAMPLES_CHANGE`. In this
	425	* case, if the system's hardware requires something other than the requested
	426	* format, SDL_mixer can select what the hardware demands instead of the app.
	427	* If the `SDL_AUDIO_ALLOW_` flag is not specified, SDL_mixer must convert
	428	* data behind the scenes between what the app demands and what the hardware
	429	* requires. If your app needs precisely what is requested, specify zero for
	430	* `allowed_changes`.
	431	*
	432	* If changes were allowed, the app can use Mix_QuerySpec() to determine the
	433	* final device settings.
	434	*
	435	* If this function reports success, you are ready to start making noise! Load
	436	* some audio data and start playing!
	437	*
	438	* When done with an audio device, probably at the end of the program, the app
	439	* should dispose of the device with Mix_CloseDevice().
	440	*
	441	* \param frequency the frequency to playback audio at (in Hz).
	442	* \param format audio format, one of SDL's AUDIO_* values.
	443	* \param channels number of channels (1 is mono, 2 is stereo, etc).
	444	* \param chunksize audio buffer size in sample FRAMES (total samples divided
	445	* by channel count).
	446	* \param device the device name to open, or NULL to choose a reasonable
	447	* default.
	448	* \param allowed_changes Allow change flags (see SDL_AUDIO_ALLOW_* flags)
	449	* \returns 0 if successful, -1 on error.
	450	*
	451	* \since This function is available since SDL_mixer 2.0.2.
	452	*
	453	* \sa Mix_OpenAudio
	454	* \sa Mix_CloseDevice
	455	* \sa Mix_QuerySpec
	456	*/
158	457	extern DECLSPEC int SDLCALL Mix_OpenAudioDevice(int frequency, Uint16 format, int channels, int chunksize, const char* device, int allowed_changes);
159	458
160		/* Dynamically change the number of channels managed by the mixer.
161		If decreasing the number of channels, the upper channels are
162		stopped.
163		This function returns the new number of allocated channels.
	459	/**
	460	* Find out what the actual audio device parameters are.
	461	*
	462	* If Mix_OpenAudioDevice() was called with `allowed_changes` set to anything
	463	* but zero, or Mix_OpenAudio() was used, some audio device settings may be
	464	* different from the application's request. This function will report what
	465	* the device is actually running at.
	466	*
	467	* Note this is only important if the app intends to touch the audio buffers
	468	* being sent to the hardware directly. If an app just wants to play audio
	469	* files and let SDL_mixer handle the low-level details, this function can
	470	* probably be ignored.
	471	*
	472	* If the audio device is not opened, this function will return 0.
	473	*
	474	* \param frequency On return, will be filled with the audio device's
	475	* frequency in Hz.
	476	* \param format On return, will be filled with the audio device's format.
	477	* \param channels On return, will be filled with the audio device's channel
	478	* count.
	479	* \returns 1 if the audio device has been opened, 0 otherwise.
	480	*
	481	* \since This function is available since SDL_mixer 2.0.0.
	482	*
	483	* \sa Mix_OpenAudio
	484	* \sa Mix_OpenAudioDevice
	485	*/
	486	extern DECLSPEC int SDLCALL Mix_QuerySpec(int frequency, Uint16 format, int *channels);
	487
	488	/**
	489	* Dynamically change the number of channels managed by the mixer.
	490	*
	491	* SDL_mixer deals with "channels," which is not the same thing as the
	492	* mono/stereo channels; they might be better described as "tracks," as each
	493	* one corresponds to a separate source of audio data. Three different WAV
	494	* files playing at the same time would be three separate SDL_mixer channels,
	495	* for example.
	496	*
	497	* An app needs as many channels as it has audio data it wants to play
	498	* simultaneously, mixing them into a single stream to send to the audio
	499	* device.
	500	*
	501	* SDL_mixer allocates `MIX_CHANNELS` (currently 8) channels when you open an
	502	* audio device, which may be more than an app needs, but if the app needs
	503	* more or wants less, this function can change it.
	504	*
	505	* If decreasing the number of channels, any upper channels currently playing
	506	* are stopped. This will deregister all effects on those channels and call
	507	* any callback specified by Mix_ChannelFinished() for each removed channel.
	508	*
	509	* If `numchans` is less than zero, this will return the current number of
	510	* channels without changing anything.
	511	*
	512	* \param numchans the new number of channels, or < 0 to query current channel
	513	* count.
	514	* \returns the new number of allocated channels.
	515	*
	516	* \since This function is available since SDL_mixer 2.0.0.
164	517	*/
165	518	extern DECLSPEC int SDLCALL Mix_AllocateChannels(int numchans);
166	519
167		/* Find out what the actual audio device parameters are.
168		This function returns 1 if the audio has been opened, 0 otherwise.
169		*/
170		extern DECLSPEC int SDLCALL Mix_QuerySpec(int frequency,Uint16 format,int *channels);
171
172		/* Load a wave file or a music (.mod .s3m .it .xm) file */
	520	/**
	521	* Load a supported audio format into a chunk.
	522	*
	523	* SDL_mixer has two separate data structures for audio data. One it calls a
	524	* "chunk," which is meant to be a file completely decoded into memory up
	525	* front, and the other it calls "music" which is a file intended to be
	526	* decoded on demand. Originally, simple formats like uncompressed WAV files
	527	* were meant to be chunks and compressed things, like MP3s, were meant to be
	528	* music, and you would stream one thing for a game's music and make repeating
	529	* sound effects with the chunks.
	530	*
	531	* In modern times, this isn't split by format anymore, and most are
	532	* interchangeable, so the question is what the app thinks is worth
	533	* predecoding or not. Chunks might take more memory, but once they are loaded
	534	* won't need to decode again, whereas music always needs to be decoded on the
	535	* fly. Also, crucially, there are as many channels for chunks as the app can
	536	* allocate, but SDL_mixer only offers a single "music" channel.
	537	*
	538	* If `freesrc` is non-zero, the RWops will be closed before returning,
	539	* whether this function succeeds or not. SDL_mixer reads everything it needs
	540	* from the RWops during this call in any case.
	541	*
	542	* There is a separate function (a macro, before SDL_mixer 2.6.0) to read
	543	* files from disk without having to deal with SDL_RWops:
	544	* `Mix_LoadWAV("filename.wav")` will call this function and manage those
	545	* details for you.
	546	*
	547	* When done with a chunk, the app should dispose of it with a call to
	548	* Mix_FreeChunk().
	549	*
	550	* \param src an SDL_RWops that data will be read from.
	551	* \param freesrc non-zero to close/free the SDL_RWops before returning, zero
	552	* to leave it open.
	553	* \returns a new chunk, or NULL on error.
	554	*
	555	* \since This function is available since SDL_mixer 2.6.0 (and as a macro
	556	* since 2.0.0).
	557	*
	558	* \sa Mix_LoadWAV
	559	* \sa Mix_FreeChunk
	560	*/
173	561	extern DECLSPEC Mix_Chunk * SDLCALL Mix_LoadWAV_RW(SDL_RWops *src, int freesrc);
174		#define Mix_LoadWAV(file) Mix_LoadWAV_RW(SDL_RWFromFile(file, "rb"), 1)
	562
	563	/**
	564	* Load a supported audio format into a chunk.
	565	*
	566	* SDL_mixer has two separate data structures for audio data. One it calls a
	567	* "chunk," which is meant to be a file completely decoded into memory up
	568	* front, and the other it calls "music" which is a file intended to be
	569	* decoded on demand. Originally, simple formats like uncompressed WAV files
	570	* were meant to be chunks and compressed things, like MP3s, were meant to be
	571	* music, and you would stream one thing for a game's music and make repeating
	572	* sound effects with the chunks.
	573	*
	574	* In modern times, this isn't split by format anymore, and most are
	575	* interchangeable, so the question is what the app thinks is worth
	576	* predecoding or not. Chunks might take more memory, but once they are loaded
	577	* won't need to decode again, whereas music always needs to be decoded on the
	578	* fly. Also, crucially, there are as many channels for chunks as the app can
	579	* allocate, but SDL_mixer only offers a single "music" channel.
	580	*
	581	* If you would rather use the abstract SDL_RWops interface to load data from
	582	* somewhere other than the filesystem, you can use Mix_LoadWAV_RW() instead.
	583	*
	584	* When done with a chunk, the app should dispose of it with a call to
	585	* Mix_FreeChunk().
	586	*
	587	* Note that before SDL_mixer 2.6.0, this function was a macro that called
	588	* Mix_LoadWAV_RW(), creating a RWops and setting `freesrc` to 1. This macro
	589	* has since been promoted to a proper API function. Older binaries linked
	590	* against a newer SDL_mixer will still call Mix_LoadWAV_RW directly, as they
	591	* are using the macro, which was available since the dawn of time.
	592	*
	593	* \param file the filesystem path to load data from.
	594	* \returns a new chunk, or NULL on error.
	595	*
	596	* \since This function is available since SDL_mixer 2.6.0 (and as a macro
	597	* since 2.0.0).
	598	*
	599	* \sa Mix_LoadWAV_RW
	600	* \sa Mix_FreeChunk
	601	*/
	602	extern DECLSPEC Mix_Chunk * SDLCALL Mix_LoadWAV(const char *file);
	603
	604
	605	/**
	606	* Load a supported audio format into a music object.
	607	*
	608	* SDL_mixer has two separate data structures for audio data. One it calls a
	609	* "chunk," which is meant to be a file completely decoded into memory up
	610	* front, and the other it calls "music" which is a file intended to be
	611	* decoded on demand. Originally, simple formats like uncompressed WAV files
	612	* were meant to be chunks and compressed things, like MP3s, were meant to be
	613	* music, and you would stream one thing for a game's music and make repeating
	614	* sound effects with the chunks.
	615	*
	616	* In modern times, this isn't split by format anymore, and most are
	617	* interchangeable, so the question is what the app thinks is worth
	618	* predecoding or not. Chunks might take more memory, but once they are loaded
	619	* won't need to decode again, whereas music always needs to be decoded on the
	620	* fly. Also, crucially, there are as many channels for chunks as the app can
	621	* allocate, but SDL_mixer only offers a single "music" channel.
	622	*
	623	* When done with this music, the app should dispose of it with a call to
	624	* Mix_FreeMusic().
	625	*
	626	* \param file a file path from where to load music data.
	627	* \returns a new music object, or NULL on error.
	628	*
	629	* \since This function is available since SDL_mixer 2.0.0.
	630	*
	631	* \sa Mix_FreeMusic
	632	*/
175	633	extern DECLSPEC Mix_Music * SDLCALL Mix_LoadMUS(const char *file);
176	634
177		/* Load a music file from an SDL_RWop object
178		* Matt Campbell (matt@campbellhome.dhs.org) April 2000 */
	635	/**
	636	* Load a supported audio format into a music object.
	637	*
	638	* SDL_mixer has two separate data structures for audio data. One it calls a
	639	* "chunk," which is meant to be a file completely decoded into memory up
	640	* front, and the other it calls "music" which is a file intended to be
	641	* decoded on demand. Originally, simple formats like uncompressed WAV files
	642	* were meant to be chunks and compressed things, like MP3s, were meant to be
	643	* music, and you would stream one thing for a game's music and make repeating
	644	* sound effects with the chunks.
	645	*
	646	* In modern times, this isn't split by format anymore, and most are
	647	* interchangeable, so the question is what the app thinks is worth
	648	* predecoding or not. Chunks might take more memory, but once they are loaded
	649	* won't need to decode again, whereas music always needs to be decoded on the
	650	* fly. Also, crucially, there are as many channels for chunks as the app can
	651	* allocate, but SDL_mixer only offers a single "music" channel.
	652	*
	653	* If `freesrc` is non-zero, the RWops will be closed before returning,
	654	* whether this function succeeds or not. SDL_mixer reads everything it needs
	655	* from the RWops during this call in any case.
	656	*
	657	* As a convenience, there is a function to read files from disk without
	658	* having to deal with SDL_RWops: `Mix_LoadMUS("filename.mp3")` will manage
	659	* those details for you.
	660	*
	661	* This function attempts to guess the file format from incoming data. If the
	662	* caller knows the format, or wants to force it, it should use
	663	* Mix_LoadMUSType_RW() instead.
	664	*
	665	* When done with this music, the app should dispose of it with a call to
	666	* Mix_FreeMusic().
	667	*
	668	* \param src an SDL_RWops that data will be read from.
	669	* \param freesrc non-zero to close/free the SDL_RWops before returning, zero
	670	* to leave it open.
	671	* \returns a new music object, or NULL on error.
	672	*
	673	* \since This function is available since SDL_mixer 2.0.0.
	674	*
	675	* \sa Mix_FreeMusic
	676	*/
179	677	extern DECLSPEC Mix_Music * SDLCALL Mix_LoadMUS_RW(SDL_RWops *src, int freesrc);
180	678
181		/* Load a music file from an SDL_RWop object assuming a specific format */
	679	/**
	680	* Load an audio format into a music object, assuming a specific format.
	681	*
	682	* SDL_mixer has two separate data structures for audio data. One it calls a
	683	* "chunk," which is meant to be a file completely decoded into memory up
	684	* front, and the other it calls "music" which is a file intended to be
	685	* decoded on demand. Originally, simple formats like uncompressed WAV files
	686	* were meant to be chunks and compressed things, like MP3s, were meant to be
	687	* music, and you would stream one thing for a game's music and make repeating
	688	* sound effects with the chunks.
	689	*
	690	* In modern times, this isn't split by format anymore, and most are
	691	* interchangeable, so the question is what the app thinks is worth
	692	* predecoding or not. Chunks might take more memory, but once they are loaded
	693	* won't need to decode again, whereas music always needs to be decoded on the
	694	* fly. Also, crucially, there are as many channels for chunks as the app can
	695	* allocate, but SDL_mixer only offers a single "music" channel.
	696	*
	697	* This function loads music data, and lets the application specify the type
	698	* of music being loaded, which might be useful if SDL_mixer cannot figure it
	699	* out from the data stream itself.
	700	*
	701	* Currently, the following types are supported:
	702	*
	703	* - `MUS_NONE` (SDL_mixer should guess, based on the data)
	704	* - `MUS_WAV` (Microsoft WAV files)
	705	* - `MUS_MOD` (Various tracker formats)
	706	* - `MUS_MID` (MIDI files)
	707	* - `MUS_OGG` (Ogg Vorbis files)
	708	* - `MUS_MP3` (MP3 files)
	709	* - `MUS_FLAC` (FLAC files)
	710	* - `MUS_OPUS` (Opus files)
	711	*
	712	* If `freesrc` is non-zero, the RWops will be closed before returning,
	713	* whether this function succeeds or not. SDL_mixer reads everything it needs
	714	* from the RWops during this call in any case.
	715	*
	716	* As a convenience, there is a function to read files from disk without
	717	* having to deal with SDL_RWops: `Mix_LoadMUS("filename.mp3")` will manage
	718	* those details for you (but not let you specify the music type explicitly)..
	719	*
	720	* When done with this music, the app should dispose of it with a call to
	721	* Mix_FreeMusic().
	722	*
	723	* \param src an SDL_RWops that data will be read from.
	724	* \param type the type of audio data provided by `src`.
	725	* \param freesrc non-zero to close/free the SDL_RWops before returning, zero
	726	* to leave it open.
	727	* \returns a new music object, or NULL on error.
	728	*
	729	* \since This function is available since SDL_mixer 2.0.0.
	730	*
	731	* \sa Mix_FreeMusic
	732	*/
182	733	extern DECLSPEC Mix_Music * SDLCALL Mix_LoadMUSType_RW(SDL_RWops *src, Mix_MusicType type, int freesrc);
183	734
184		/* Load a wave file of the mixer format from a memory buffer */
	735	/**
	736	* Load a WAV file from memory as quickly as possible.
	737	*
	738	* Unlike Mix_LoadWAV_RW, this function has several requirements, and unless
	739	* you control all your audio data and know what you're doing, you should
	740	* consider this function unsafe and not use it.
	741	*
	742	* - The provided audio data MUST be in Microsoft WAV format.
	743	* - The provided audio data shouldn't use any strange WAV extensions.
	744	* - The audio data MUST be in the exact same format as the audio device. This
	745	* function will not attempt to convert it, or even verify it's in the right
	746	* format.
	747	* - The audio data must be valid; this function does not know the size of the
	748	* memory buffer, so if the WAV data is corrupted, it can read past the end
	749	* of the buffer, causing a crash.
	750	* - The audio data must live at least as long as the returned Mix_Chunk,
	751	* because SDL_mixer will use that data directly and not make a copy of it.
	752	*
	753	* This function will do NO error checking! Be extremely careful here!
	754	*
	755	* (Seriously, use Mix_LoadWAV_RW instead.)
	756	*
	757	* If this function is successful, the provided memory buffer must remain
	758	* available until Mix_FreeChunk() is called on the returned chunk.
	759	*
	760	* \param mem memory buffer containing of a WAV file.
	761	* \returns a new chunk, or NULL on error.
	762	*
	763	* \since This function is available since SDL_mixer 2.0.0.
	764	*
	765	* \sa Mix_LoadWAV_RW
	766	* \sa Mix_FreeChunk
	767	*/
185	768	extern DECLSPEC Mix_Chunk * SDLCALL Mix_QuickLoad_WAV(Uint8 *mem);
186	769
187		/* Load raw audio data of the mixer format from a memory buffer */
	770	/**
	771	* Load a raw audio data from memory as quickly as possible.
	772	*
	773	* The audio data MUST be in the exact same format as the audio device. This
	774	* function will not attempt to convert it, or even verify it's in the right
	775	* format.
	776	*
	777	* If this function is successful, the provided memory buffer must remain
	778	* available until Mix_FreeChunk() is called on the returned chunk.
	779	*
	780	* \param mem memory buffer containing raw PCM data.
	781	* \param len length of buffer pointed to by `mem`, in bytes.
	782	* \returns a new chunk, or NULL on error.
	783	*
	784	* \since This function is available since SDL_mixer 2.0.0.
	785	*
	786	* \sa Mix_FreeChunk
	787	*/
188	788	extern DECLSPEC Mix_Chunk * SDLCALL Mix_QuickLoad_RAW(Uint8 *mem, Uint32 len);
189	789
190		/* Free an audio chunk previously loaded */
	790	/**
	791	* Free an audio chunk.
	792	*
	793	* An app should call this function when it is done with a Mix_Chunk and wants
	794	* to dispose of its resources.
	795	*
	796	* SDL_mixer will stop any channels this chunk is currently playing on. This
	797	* will deregister all effects on those channels and call any callback
	798	* specified by Mix_ChannelFinished() for each removed channel.
	799	*
	800	* \param chunk the chunk to free.
	801	*
	802	* \since This function is available since SDL_mixer 2.0.0.
	803	*
	804	* \sa Mix_LoadWAV
	805	* \sa Mix_LoadWAV_RW
	806	* \sa Mix_QuickLoad_WAV
	807	* \sa Mix_QuickLoad_RAW
	808	*/
191	809	extern DECLSPEC void SDLCALL Mix_FreeChunk(Mix_Chunk *chunk);
	810
	811	/**
	812	* Free a music object.
	813	*
	814	* If this music is currently playing, it will be stopped.
	815	*
	816	* If this music is in the process of fading out (via Mix_FadeOutMusic()),
	817	* this function will block until the fade completes. If you need to avoid
	818	* this, be sure to call Mix_HaltMusic() before freeing the music.
	819	*
	820	* \param music the music object to free.
	821	*
	822	* \since This function is available since SDL_mixer 2.0.0.
	823	*
	824	* \sa Mix_LoadMUS
	825	* \sa Mix_LoadMUS_RW
	826	* \sa Mix_LoadMUSType_RW
	827	*/
192	828	extern DECLSPEC void SDLCALL Mix_FreeMusic(Mix_Music *music);
193	829
194		/* Get a list of chunk/music decoders that this build of SDL_mixer provides.
195		This list can change between builds AND runs of the program, if external
196		libraries that add functionality become available.
197		You must successfully call Mix_OpenAudio() before calling these functions.
198		This API is only available in SDL_mixer 1.2.9 and later.
199
200		// usage...
201		int i;
202		const int total = Mix_GetNumChunkDecoders();
203		for (i = 0; i < total; i++)
204		printf("Supported chunk decoder: [%s]\n", Mix_GetChunkDecoder(i));
205
206		Appearing in this list doesn't promise your specific audio file will
207		decode...but it's handy to know if you have, say, a functioning Timidity
208		install.
209
210		These return values are static, read-only data; do not modify or free it.
211		The pointers remain valid until you call Mix_CloseAudio().
212		*/
	830	/**
	831	* Get a list of chunk decoders that this build of SDL_mixer provides.
	832	*
	833	* This list can change between builds AND runs of the program, if external
	834	* libraries that add functionality become available. You must successfully
	835	* call Mix_OpenAudio() or Mix_OpenAudioDevice() before calling this function,
	836	* as decoders are activated at device open time.
	837	*
	838	* Appearing in this list doesn't promise your specific audio file will
	839	* decode...but it's handy to know if you have, say, a functioning Ogg Vorbis
	840	* install.
	841	*
	842	* These return values are static, read-only data; do not modify or free it.
	843	* The pointers remain valid until you call Mix_CloseAudio().
	844	*
	845	* \returns number of chunk decoders available.
	846	*
	847	* \since This function is available since SDL_mixer 2.0.0.
	848	*
	849	* \sa Mix_GetChunkDecoder
	850	* \sa Mix_HasChunkDecoder
	851	*/
213	852	extern DECLSPEC int SDLCALL Mix_GetNumChunkDecoders(void);
	853
	854	/**
	855	* Get a chunk decoder's name.
	856	*
	857	* The requested decoder's index must be between zero and
	858	* Mix_GetNumChunkDecoders()-1. It's safe to call this with an invalid index;
	859	* this function will return NULL in that case.
	860	*
	861	* This list can change between builds AND runs of the program, if external
	862	* libraries that add functionality become available. You must successfully
	863	* call Mix_OpenAudio() or Mix_OpenAudioDevice() before calling this function,
	864	* as decoders are activated at device open time.
	865	*
	866	* \param index index of the chunk decoder.
	867	* \returns the chunk decoder's name.
	868	*
	869	* \since This function is available since SDL_mixer 2.0.0.
	870	*
	871	* \sa Mix_GetNumChunkDecoders
	872	*/
214	873	extern DECLSPEC const char * SDLCALL Mix_GetChunkDecoder(int index);
	874
	875	/**
	876	* Check if a chunk decoder is available by name.
	877	*
	878	* This result can change between builds AND runs of the program, if external
	879	* libraries that add functionality become available. You must successfully
	880	* call Mix_OpenAudio() or Mix_OpenAudioDevice() before calling this function,
	881	* as decoders are activated at device open time.
	882	*
	883	* Decoder names are arbitrary but also obvious, so you have to know what
	884	* you're looking for ahead of time, but usually it's the file extension in
	885	* capital letters (some example names are "AIFF", "VOC", "WAV").
	886	*
	887	* \param name the decoder name to query.
	888	* \returns SDL_TRUE if a decoder by that name is available, SDL_FALSE
	889	* otherwise.
	890	*
	891	* \since This function is available since SDL_mixer 2.0.2.
	892	*
	893	* \sa Mix_GetNumChunkDecoders
	894	* \sa Mix_GetChunkDecoder
	895	*/
215	896	extern DECLSPEC SDL_bool SDLCALL Mix_HasChunkDecoder(const char *name);
	897
	898	/**
	899	* Get a list of music decoders that this build of SDL_mixer provides.
	900	*
	901	* This list can change between builds AND runs of the program, if external
	902	* libraries that add functionality become available. You must successfully
	903	* call Mix_OpenAudio() or Mix_OpenAudioDevice() before calling this function,
	904	* as decoders are activated at device open time.
	905	*
	906	* Appearing in this list doesn't promise your specific audio file will
	907	* decode...but it's handy to know if you have, say, a functioning Ogg Vorbis
	908	* install.
	909	*
	910	* These return values are static, read-only data; do not modify or free it.
	911	* The pointers remain valid until you call Mix_CloseAudio().
	912	*
	913	* \returns number of chunk decoders available.
	914	*
	915	* \since This function is available since SDL_mixer 2.0.0.
	916	*
	917	* \sa Mix_GetMusicDecoder
	918	* \sa Mix_HasMusicDecoder
	919	*/
216	920	extern DECLSPEC int SDLCALL Mix_GetNumMusicDecoders(void);
	921
	922	/**
	923	* Get a music decoder's name.
	924	*
	925	* The requested decoder's index must be between zero and
	926	* Mix_GetNumMusicDecoders()-1. It's safe to call this with an invalid index;
	927	* this function will return NULL in that case.
	928	*
	929	* This list can change between builds AND runs of the program, if external
	930	* libraries that add functionality become available. You must successfully
	931	* call Mix_OpenAudio() or Mix_OpenAudioDevice() before calling this function,
	932	* as decoders are activated at device open time.
	933	*
	934	* \param index index of the music decoder.
	935	* \returns the music decoder's name.
	936	*
	937	* \since This function is available since SDL_mixer 2.0.0.
	938	*
	939	* \sa Mix_GetNumMusicDecoders
	940	*/
217	941	extern DECLSPEC const char * SDLCALL Mix_GetMusicDecoder(int index);
	942
	943	/**
	944	* Check if a music decoder is available by name.
	945	*
	946	* This result can change between builds AND runs of the program, if external
	947	* libraries that add functionality become available. You must successfully
	948	* call Mix_OpenAudio() or Mix_OpenAudioDevice() before calling this function,
	949	* as decoders are activated at device open time.
	950	*
	951	* Decoder names are arbitrary but also obvious, so you have to know what
	952	* you're looking for ahead of time, but usually it's the file extension in
	953	* capital letters (some example names are "MOD", "MP3", "FLAC").
	954	*
	955	* \param name the decoder name to query.
	956	* \returns SDL_TRUE if a decoder by that name is available, SDL_FALSE
	957	* otherwise.
	958	*
	959	* \since This function is available since SDL_mixer 2.6.0
	960	*
	961	* \sa Mix_GetNumMusicDecoders
	962	* \sa Mix_GetMusicDecoder
	963	*/
218	964	extern DECLSPEC SDL_bool SDLCALL Mix_HasMusicDecoder(const char *name);
219	965
220		/* Find out the music format of a mixer music, or the currently playing
221		music, if 'music' is NULL.
222		*/
	966	/**
	967	* Find out the format of a mixer music.
	968	*
	969	* If `music` is NULL, this will query the currently playing music (and return
	970	* MUS_NONE if nothing is currently playing).
	971	*
	972	* \param music the music object to query, or NULL for the currently-playing
	973	* music.
	974	* \returns the Mix_MusicType for the music object.
	975	*
	976	* \since This function is available since SDL_mixer 2.0.0
	977	*/
223	978	extern DECLSPEC Mix_MusicType SDLCALL Mix_GetMusicType(const Mix_Music *music);
224	979
225		/* Get music title from meta-tag if possible. If title tag is empty, filename will be returned */
	980	/**
	981	* Get the title for a music object, or its filename.
	982	*
	983	* This returns format-specific metadata. Not all file formats supply this!
	984	*
	985	* If `music` is NULL, this will query the currently-playing music.
	986	*
	987	* If music's title tag is missing or empty, the filename will be returned. If
	988	* you'd rather have the actual metadata or nothing, use
	989	* Mix_GetMusicTitleTag() instead.
	990	*
	991	* Please note that if the music was loaded from an SDL_RWops instead of a
	992	* filename, the filename returned will be an empty string ("").
	993	*
	994	* This function never returns NULL! If no data is available, it will return
	995	* an empty string ("").
	996	*
	997	* \param music the music object to query, or NULL for the currently-playing
	998	* music.
	999	* \returns the music's title if available, or the filename if not, or "".
	1000	*
	1001	* \since This function is available since SDL_mixer 2.6.0.
	1002	*
	1003	* \sa Mix_GetMusicTitleTag
	1004	* \sa Mix_GetMusicArtistTag
	1005	* \sa Mix_GetMusicAlbumTag
	1006	* \sa Mix_GetMusicCopyrightTag
	1007	*/
226	1008	extern DECLSPEC const char SDLCALL Mix_GetMusicTitle(const Mix_Music music);
227		/* Get music title from meta-tag if possible */
	1009
	1010	/**
	1011	* Get the title for a music object.
	1012	*
	1013	* This returns format-specific metadata. Not all file formats supply this!
	1014	*
	1015	* If `music` is NULL, this will query the currently-playing music.
	1016	*
	1017	* Unlike this function, Mix_GetMusicTitle() produce a string with the music's
	1018	* filename if a title isn't available, which might be preferable for some
	1019	* applications.
	1020	*
	1021	* This function never returns NULL! If no data is available, it will return
	1022	* an empty string ("").
	1023	*
	1024	* \param music the music object to query, or NULL for the currently-playing
	1025	* music.
	1026	* \returns the music's title if available, or "".
	1027	*
	1028	* \since This function is available since SDL_mixer 2.6.0.
	1029	*
	1030	* \sa Mix_GetMusicTitle
	1031	* \sa Mix_GetMusicArtistTag
	1032	* \sa Mix_GetMusicAlbumTag
	1033	* \sa Mix_GetMusicCopyrightTag
	1034	*/
228	1035	extern DECLSPEC const char SDLCALL Mix_GetMusicTitleTag(const Mix_Music music);
229		/* Get music artist from meta-tag if possible */
	1036
	1037	/**
	1038	* Get the artist name for a music object.
	1039	*
	1040	* This returns format-specific metadata. Not all file formats supply this!
	1041	*
	1042	* If `music` is NULL, this will query the currently-playing music.
	1043	*
	1044	* This function never returns NULL! If no data is available, it will return
	1045	* an empty string ("").
	1046	*
	1047	* \param music the music object to query, or NULL for the currently-playing
	1048	* music.
	1049	* \returns the music's artist name if available, or "".
	1050	*
	1051	* \since This function is available since SDL_mixer 2.6.0.
	1052	*
	1053	* \sa Mix_GetMusicTitleTag
	1054	* \sa Mix_GetMusicAlbumTag
	1055	* \sa Mix_GetMusicCopyrightTag
	1056	*/
230	1057	extern DECLSPEC const char SDLCALL Mix_GetMusicArtistTag(const Mix_Music music);
231		/* Get music album from meta-tag if possible */
	1058
	1059	/**
	1060	* Get the album name for a music object.
	1061	*
	1062	* This returns format-specific metadata. Not all file formats supply this!
	1063	*
	1064	* If `music` is NULL, this will query the currently-playing music.
	1065	*
	1066	* This function never returns NULL! If no data is available, it will return
	1067	* an empty string ("").
	1068	*
	1069	* \param music the music object to query, or NULL for the currently-playing
	1070	* music.
	1071	* \returns the music's album name if available, or "".
	1072	*
	1073	* \since This function is available since SDL_mixer 2.6.0.
	1074	*
	1075	* \sa Mix_GetMusicTitleTag
	1076	* \sa Mix_GetMusicArtistTag
	1077	* \sa Mix_GetMusicCopyrightTag
	1078	*/
232	1079	extern DECLSPEC const char SDLCALL Mix_GetMusicAlbumTag(const Mix_Music music);
233		/* Get music copyright from meta-tag if possible */
	1080
	1081	/**
	1082	* Get the copyright text for a music object.
	1083	*
	1084	* This returns format-specific metadata. Not all file formats supply this!
	1085	*
	1086	* If `music` is NULL, this will query the currently-playing music.
	1087	*
	1088	* This function never returns NULL! If no data is available, it will return
	1089	* an empty string ("").
	1090	*
	1091	* \param music the music object to query, or NULL for the currently-playing
	1092	* music.
	1093	* \returns the music's copyright text if available, or "".
	1094	*
	1095	* \since This function is available since SDL_mixer 2.6.0.
	1096	*
	1097	* \sa Mix_GetMusicTitleTag
	1098	* \sa Mix_GetMusicArtistTag
	1099	* \sa Mix_GetMusicAlbumTag
	1100	*/
234	1101	extern DECLSPEC const char SDLCALL Mix_GetMusicCopyrightTag(const Mix_Music music);
235	1102
236		/* Set a function that is called after all mixing is performed.
237		This can be used to provide real-time visual display of the audio stream
238		or add a custom mixer filter for the stream data.
239		*/
	1103	/**
	1104	* Set a function that is called after all mixing is performed.
	1105	*
	1106	* This can be used to provide real-time visual display of the audio stream or
	1107	* add a custom mixer filter for the stream data.
	1108	*
	1109	* The callback will fire every time SDL_mixer is ready to supply more data to
	1110	* the audio device, after it has finished all its mixing work. This runs
	1111	* inside an SDL audio callback, so it's important that the callback return
	1112	* quickly, or there could be problems in the audio playback.
	1113	*
	1114	* The data provided to the callback is in the format that the audio device
	1115	* was opened in, and it represents the exact waveform SDL_mixer has mixed
	1116	* from all playing chunks and music for playback. You are allowed to modify
	1117	* the data, but it cannot be resized (so you can't add a reverb effect that
	1118	* goes past the end of the buffer without saving some state between runs to
	1119	* add it into the next callback, or resample the buffer to a smaller size to
	1120	* speed it up, etc).
	1121	*
	1122	* The `arg` pointer supplied here is passed to the callback as-is, for
	1123	* whatever the callback might want to do with it (keep track of some ongoing
	1124	* state, settings, etc).
	1125	*
	1126	* Passing a NULL callback disables the post-mix callback until such a time as
	1127	* a new one callback is set.
	1128	*
	1129	* There is only one callback available. If you need to mix multiple inputs,
	1130	* be prepared to handle them from a single function.
	1131	*
	1132	* \param mix_func the callback function to become the new post-mix callback.
	1133	* \param arg a pointer that is passed, untouched, to the callback.
	1134	*
	1135	* \since This function is available since SDL_mixer 2.0.0.
	1136	*
	1137	* \sa Mix_HookMusic
	1138	*/
240	1139	extern DECLSPEC void SDLCALL Mix_SetPostMix(void (SDLCALL mix_func)(void udata, Uint8 stream, int len), void arg);
241	1140
242		/* Add your own music player or additional mixer function.
243		If 'mix_func' is NULL, the default music player is re-enabled.
	1141	/**
	1142	* Add your own music player or additional mixer function.
	1143	*
	1144	* This works something like Mix_SetPostMix(), but it has some crucial
	1145	* differences. Note that an app can use this _and_ Mix_SetPostMix() at the
	1146	* same time. This allows an app to replace the built-in music playback,
	1147	* either with it's own music decoder or with some sort of
	1148	* procedurally-generated audio output.
	1149	*
	1150	* The supplied callback will fire every time SDL_mixer is preparing to supply
	1151	* more data to the audio device. This runs inside an SDL audio callback, so
	1152	* it's important that the callback return quickly, or there could be problems
	1153	* in the audio playback.
	1154	*
	1155	* Running this callback is the first thing SDL_mixer will do when starting to
	1156	* mix more audio. The buffer will contain silence upon entry, so the callback
	1157	* does not need to mix into existing data or initialize the buffer.
	1158	*
	1159	* Note that while a callback is set through this function, SDL_mixer will not
	1160	* mix any playing music; this callback is used instead. To disable this
	1161	* callback (and thus reenable built-in music playback) call this function
	1162	* with a NULL callback.
	1163	*
	1164	* The data written to by the callback is in the format that the audio device
	1165	* was opened in, and upon return from the callback, SDL_mixer will mix any
	1166	* playing chunks (but not music!) into the buffer. The callback cannot resize
	1167	* the buffer (so you must be prepared to provide exactly the amount of data
	1168	* demanded or leave it as silence).
	1169	*
	1170	* The `arg` pointer supplied here is passed to the callback as-is, for
	1171	* whatever the callback might want to do with it (keep track of some ongoing
	1172	* state, settings, etc).
	1173	*
	1174	* As there is only one music "channel" mixed, there is only one callback
	1175	* available. If you need to mix multiple inputs, be prepared to handle them
	1176	* from a single function.
	1177	*
	1178	* \param mix_func the callback function to become the new post-mix callback.
	1179	* \param arg a pointer that is passed, untouched, to the callback.
	1180	*
	1181	* \since This function is available since SDL_mixer 2.0.0.
	1182	*
	1183	* \sa Mix_SetPostMix
244	1184	*/
245	1185	extern DECLSPEC void SDLCALL Mix_HookMusic(void (SDLCALL mix_func)(void udata, Uint8 stream, int len), void arg);
246	1186
247		/* Add your own callback for when the music has finished playing or when it is
248		* stopped from a call to Mix_HaltMusic.
	1187	/**
	1188	* Set a callback that runs when a music object has stopped playing.
	1189	*
	1190	* This callback will fire when the currently-playing music has completed, or
	1191	* when it has been explicitly stopped from a call to Mix_HaltMusic. As such,
	1192	* this callback might fire from an arbitrary background thread at almost any
	1193	* time; try to limit what you do here.
	1194	*
	1195	* It is legal to start a new music object playing in this callback (or
	1196	* restart the one that just stopped). If the music finished normally, this
	1197	* can be used to loop the music without a gap in the audio playback.
	1198	*
	1199	* Do not call SDL_LockAudio() from this callback; you will either be inside
	1200	* the audio callback, or SDL_mixer will explicitly lock the audio before
	1201	* calling your callback.
	1202	*
	1203	* A NULL pointer will disable the callback.
	1204	*
	1205	* \param music_finished the callback function to become the new notification
	1206	* mechanism.
	1207	*
	1208	* \since This function is available since SDL_mixer 2.0.0.
249	1209	*/
250	1210	extern DECLSPEC void SDLCALL Mix_HookMusicFinished(void (SDLCALL *music_finished)(void));
251	1211
252		/* Get a pointer to the user data for the current music hook */
	1212	/**
	1213	* Get a pointer to the user data for the current music hook.
	1214	*
	1215	* This returns the `arg` pointer last passed to Mix_HookMusic(), or NULL if
	1216	* that function has never been called.
	1217	*
	1218	* \returns pointer to the user data previously passed to Mix_HookMusic.
	1219	*
	1220	* \since This function is available since SDL_mixer 2.0.0.
	1221	*/
253	1222	extern DECLSPEC void * SDLCALL Mix_GetMusicHookData(void);
254	1223
255		/*
256		* Add your own callback when a channel has finished playing. NULL
257		* to disable callback. The callback may be called from the mixer's audio
258		* callback or it could be called as a result of Mix_HaltChannel(), etc.
259		* do not call SDL_LockAudio() from this callback; you will either be
260		* inside the audio callback, or SDL_mixer will explicitly lock the audio
261		* before calling your callback.
	1224	/**
	1225	* Set a callback that runs when a channel has finished playing.
	1226	*
	1227	* The callback may be called from the mixer's audio callback or it could be
	1228	* called as a result of Mix_HaltChannel(), etc.
	1229	*
	1230	* The callback has a single parameter, `channel`, which says what mixer
	1231	* channel has just stopped.
	1232	*
	1233	* Do not call SDL_LockAudio() from this callback; you will either be inside
	1234	* the audio callback, or SDL_mixer will explicitly lock the audio before
	1235	* calling your callback.
	1236	*
	1237	* A NULL pointer will disable the callback.
	1238	*
	1239	* \param channel_finished the callback function to become the new
	1240	* notification mechanism.
	1241	*
	1242	* \since This function is available since SDL_mixer 2.0.0.
262	1243	*/
263	1244	extern DECLSPEC void SDLCALL Mix_ChannelFinished(void (SDLCALL *channel_finished)(int channel));
264	1245
265	1246
266		/* Special Effects API by ryan c. gordon. (icculus@icculus.org) */
267
268	1247	#define MIX_CHANNEL_POST (-2)
269	1248
270		/* This is the format of a special effect callback:
	1249	/**
	1250	* This is the format of a special effect callback:
271	1251	*
272	1252	* myeffect(int chan, void stream, int len, void udata);
273	1253	*

286	1266	*/
287	1267	typedef void (SDLCALL Mix_EffectFunc_t)(int chan, void stream, int len, void *udata);
288	1268
289		/*
	1269	/**
290	1270	* This is a callback that signifies that a channel has finished all its
291	1271	* loops and has completed playback. This gets called if the buffer
292	1272	* plays out normally, or if you call Mix_HaltChannel(), implicitly stop

298	1278	typedef void (SDLCALL Mix_EffectDone_t)(int chan, void udata);
299	1279
300	1280
301		/* Register a special effect function. At mixing time, the channel data is
302		* copied into a buffer and passed through each registered effect function.
303		* After it passes through all the functions, it is mixed into the final
304		* output stream. The copy to buffer is performed once, then each effect
305		* function performs on the output of the previous effect. Understand that
306		* this extra copy to a buffer is not performed if there are no effects
307		* registered for a given chunk, which saves CPU cycles, and any given
308		* effect will be extra cycles, too, so it is crucial that your code run
309		* fast. Also note that the data that your function is given is in the
310		* format of the sound device, and not the format you gave to Mix_OpenAudio(),
311		* although they may in reality be the same. This is an unfortunate but
312		* necessary speed concern. Use Mix_QuerySpec() to determine if you can
313		* handle the data before you register your effect, and take appropriate
314		* actions.
315		* You may also specify a callback (Mix_EffectDone_t) that is called when
316		* the channel finishes playing. This gives you a more fine-grained control
317		* than Mix_ChannelFinished(), in case you need to free effect-specific
318		* resources, etc. If you don't need this, you can specify NULL.
	1281	/**
	1282	* Register a special effect function.
	1283	*
	1284	* At mixing time, the channel data is copied into a buffer and passed through
	1285	* each registered effect function. After it passes through all the functions,
	1286	* it is mixed into the final output stream. The copy to buffer is performed
	1287	* once, then each effect function performs on the output of the previous
	1288	* effect. Understand that this extra copy to a buffer is not performed if
	1289	* there are no effects registered for a given chunk, which saves CPU cycles,
	1290	* and any given effect will be extra cycles, too, so it is crucial that your
	1291	* code run fast. Also note that the data that your function is given is in
	1292	* the format of the sound device, and not the format you gave to
	1293	* Mix_OpenAudio(), although they may in reality be the same. This is an
	1294	* unfortunate but necessary speed concern. Use Mix_QuerySpec() to determine
	1295	* if you can handle the data before you register your effect, and take
	1296	* appropriate actions.
	1297	*
	1298	* You may also specify a callback (Mix_EffectDone_t) that is called when the
	1299	* channel finishes playing. This gives you a more fine-grained control than
	1300	* Mix_ChannelFinished(), in case you need to free effect-specific resources,
	1301	* etc. If you don't need this, you can specify NULL.
	1302	*
319	1303	* You may set the callbacks before or after calling Mix_PlayChannel().
320		* Things like Mix_SetPanning() are just internal special effect functions,
321		* so if you are using that, you've already incurred the overhead of a copy
322		* to a separate buffer, and that these effects will be in the queue with
323		* any functions you've registered. The list of registered effects for a
324		* channel is reset when a chunk finishes playing, so you need to explicitly
325		* set them with each call to Mix_PlayChannel*().
	1304	*
	1305	* Things like Mix_SetPanning() are just internal special effect functions, so
	1306	* if you are using that, you've already incurred the overhead of a copy to a
	1307	* separate buffer, and that these effects will be in the queue with any
	1308	* functions you've registered. The list of registered effects for a channel
	1309	* is reset when a chunk finishes playing, so you need to explicitly set them
	1310	* with each call to Mix_PlayChannel*().
	1311	*
326	1312	* You may also register a special effect function that is to be run after
327		* final mixing occurs. The rules for these callbacks are identical to those
328		* in Mix_RegisterEffect, but they are run after all the channels and the
329		* music have been mixed into a single stream, whereas channel-specific
330		* effects run on a given channel before any other mixing occurs. These
331		* global effect callbacks are call "posteffects". Posteffects only have
332		* their Mix_EffectDone_t function called when they are unregistered (since
333		* the main output stream is never "done" in the same sense as a channel).
334		* You must unregister them manually when you've had enough. Your callback
335		* will be told that the channel being mixed is (MIX_CHANNEL_POST) if the
336		* processing is considered a posteffect.
	1313	* final mixing occurs. The rules for these callbacks are identical to those
	1314	* in Mix_RegisterEffect, but they are run after all the channels and the
	1315	* music have been mixed into a single stream, whereas channel-specific
	1316	* effects run on a given channel before any other mixing occurs. These global
	1317	* effect callbacks are call "posteffects". Posteffects only have their
	1318	* Mix_EffectDone_t function called when they are unregistered (since the main
	1319	* output stream is never "done" in the same sense as a channel). You must
	1320	* unregister them manually when you've had enough. Your callback will be told
	1321	* that the channel being mixed is `MIX_CHANNEL_POST` if the processing is
	1322	* considered a posteffect.
337	1323	*
338	1324	* After all these effects have finished processing, the callback registered
339		* through Mix_SetPostMix() runs, and then the stream goes to the audio
340		* device.
341		*
342		* DO NOT EVER call SDL_LockAudio() from your callback function!
343		*
344		* returns zero if error (no such channel), nonzero if added.
345		* Error messages can be retrieved from Mix_GetError().
	1325	* through Mix_SetPostMix() runs, and then the stream goes to the audio
	1326	* device.
	1327	*
	1328	* DO NOT EVER call SDL_LockAudio() from your callback function! You are
	1329	* already running in the audio thread and the lock is already held!
	1330	*
	1331	* Note that unlike most SDL and SDL_mixer functions, this function returns
	1332	* zero if there's an error, not on success. We apologize for the API design
	1333	* inconsistency here.
	1334	*
	1335	* \param chan the channel to register an effect to, or MIX_CHANNEL_POST.
	1336	* \param f effect the callback to run when more of this channel is to be
	1337	* mixed.
	1338	* \param d effect done callback
	1339	* \param arg argument
	1340	* \returns zero if error (no such channel), nonzero if added. Error messages
	1341	* can be retrieved from Mix_GetError().
	1342	*
	1343	* \since This function is available since SDL_mixer 2.0.0.
346	1344	*/
347	1345	extern DECLSPEC int SDLCALL Mix_RegisterEffect(int chan, Mix_EffectFunc_t f, Mix_EffectDone_t d, void *arg);
348	1346
349	1347
350		/* You may not need to call this explicitly, unless you need to stop an
351		* effect from processing in the middle of a chunk's playback.
352		* Posteffects are never implicitly unregistered as they are for channels,
353		* but they may be explicitly unregistered through this function by
354		* specifying MIX_CHANNEL_POST for a channel.
355		* returns zero if error (no such channel or effect), nonzero if removed.
356		* Error messages can be retrieved from Mix_GetError().
	1348	/**
	1349	* Explicitly unregister a special effect function.
	1350	*
	1351	* You may not need to call this at all, unless you need to stop an effect
	1352	* from processing in the middle of a chunk's playback.
	1353	*
	1354	* Posteffects are never implicitly unregistered as they are for channels (as
	1355	* the output stream does not have an end), but they may be explicitly
	1356	* unregistered through this function by specifying MIX_CHANNEL_POST for a
	1357	* channel.
	1358	*
	1359	* Note that unlike most SDL and SDL_mixer functions, this function returns
	1360	* zero if there's an error, not on success. We apologize for the API design
	1361	* inconsistency here.
	1362	*
	1363	* \param chan the channel to unregister an effect on, or MIX_CHANNEL_POST.
	1364	* \param f effect the callback stop calling in future mixing iterations.
	1365	* \returns zero if error (no such channel or effect), nonzero if removed.
	1366	* Error messages can be retrieved from Mix_GetError().
	1367	*
	1368	* \since This function is available since SDL_mixer 2.0.0.
357	1369	*/
358	1370	extern DECLSPEC int SDLCALL Mix_UnregisterEffect(int channel, Mix_EffectFunc_t f);
359	1371
360
361		/* You may not need to call this explicitly, unless you need to stop all
362		* effects from processing in the middle of a chunk's playback. Note that
363		* this will also shut off some internal effect processing, since
364		* Mix_SetPanning() and others may use this API under the hood. This is
365		* called internally when a channel completes playback.
366		* Posteffects are never implicitly unregistered as they are for channels,
367		* but they may be explicitly unregistered through this function by
368		* specifying MIX_CHANNEL_POST for a channel.
369		* returns zero if error (no such channel), nonzero if all effects removed.
370		* Error messages can be retrieved from Mix_GetError().
	1372	/**
	1373	* Explicitly unregister all special effect functions.
	1374	*
	1375	* You may not need to call this at all, unless you need to stop all effects
	1376	* from processing in the middle of a chunk's playback.
	1377	*
	1378	* Note that this will also shut off some internal effect processing, since
	1379	* Mix_SetPanning() and others may use this API under the hood. This is called
	1380	* internally when a channel completes playback. Posteffects are never
	1381	* implicitly unregistered as they are for channels, but they may be
	1382	* explicitly unregistered through this function by specifying
	1383	* MIX_CHANNEL_POST for a channel.
	1384	*
	1385	* Note that unlike most SDL and SDL_mixer functions, this function returns
	1386	* zero if there's an error, not on success. We apologize for the API design
	1387	* inconsistency here.
	1388	*
	1389	* \param chan the channel to unregister all effects on, or MIX_CHANNEL_POST.
	1390	* \returns zero if error (no such channel), nonzero if all effects removed.
	1391	* Error messages can be retrieved from Mix_GetError().
	1392	*
	1393	* \since This function is available since SDL_mixer 2.0.0.
371	1394	*/
372	1395	extern DECLSPEC int SDLCALL Mix_UnregisterAllEffects(int channel);
373	1396

390	1413	* The left and right channels are specified as integers between 0 and 255,
391	1414	* quietest to loudest, respectively.
392	1415	*
393		* Technically, this is just individual volume control for a sample with
394		* two (stereo) channels, so it can be used for more than just panning.
395		* If you want real panning, call it like this:
	1416	* Technically, this is just individual volume control for a sample with two
	1417	* (stereo) channels, so it can be used for more than just panning. If you
	1418	* want real panning, call it like this:
396	1419	*
397	1420	* ```c
398	1421	* Mix_SetPanning(channel, left, 255 - left);
399	1422	* ```
400	1423	*
401		* ...which isn't so hard.
402		*
403	1424	* Setting `channel` to MIX_CHANNEL_POST registers this as a posteffect, and
404		* the panning will be done to the final mixed stream before passing it on
405		* to the audio device.
	1425	* the panning will be done to the final mixed stream before passing it on to
	1426	* the audio device.
406	1427	*
407	1428	* This uses the Mix_RegisterEffect() API internally, and returns without
408		* registering the effect function if the audio device is not configured
409		* for stereo output. Setting both `left` and `right` to 255 causes this
410		* effect to be unregistered, since that is the data's normal state.
	1429	* registering the effect function if the audio device is not configured for
	1430	* stereo output. Setting both `left` and `right` to 255 causes this effect to
	1431	* be unregistered, since that is the data's normal state.
411	1432	*
412	1433	* Note that an audio device in mono mode is a no-op, but this call will
413		* return successful in that case. Error messages can be retrieved from
414		* Mix_GetError().
	1434	* return successful in that case. Error messages can be retrieved from
	1435	* Mix_GetError().
	1436	*
	1437	* Note that unlike most SDL and SDL_mixer functions, this function returns
	1438	* zero if there's an error, not on success. We apologize for the API design
	1439	* inconsistency here.
415	1440	*
416	1441	* \param channel The mixer channel to pan or MIX_CHANNEL_POST.
417		* \param left Volume of stereo left channel, 0 is silence, 255 is full volume.
418		* \param right Volume of stereo right channel, 0 is silence, 255 is full volume.
	1442	* \param left Volume of stereo left channel, 0 is silence, 255 is full
	1443	* volume.
	1444	* \param right Volume of stereo right channel, 0 is silence, 255 is full
	1445	* volume.
419	1446	* \returns zero if error (no such channel or Mix_RegisterEffect() fails),
420	1447	* nonzero if panning effect enabled.
421	1448	*

427	1454	extern DECLSPEC int SDLCALL Mix_SetPanning(int channel, Uint8 left, Uint8 right);
428	1455
429	1456
430		/* Set the position of a channel. (angle) is an integer from 0 to 360, that
431		* specifies the location of the sound in relation to the listener. (angle)
432		* will be reduced as neccesary (540 becomes 180 degrees, -100 becomes 260).
433		* Angle 0 is due north, and rotates clockwise as the value increases.
434		* For efficiency, the precision of this effect may be limited (angles 1
435		* through 7 might all produce the same effect, 8 through 15 are equal, etc).
436		* (distance) is an integer between 0 and 255 that specifies the space
437		* between the sound and the listener. The larger the number, the further
438		* away the sound is. Using 255 does not guarantee that the channel will be
439		* culled from the mixing process or be completely silent. For efficiency,
440		* the precision of this effect may be limited (distance 0 through 5 might
441		* all produce the same effect, 6 through 10 are equal, etc). Setting (angle)
442		* and (distance) to 0 unregisters this effect, since the data would be
443		* unchanged.
	1457	/**
	1458	* Set the position of a channel.
	1459	*
	1460	* `angle` is an integer from 0 to 360, that specifies the location of the
	1461	* sound in relation to the listener. `angle` will be reduced as neccesary
	1462	* (540 becomes 180 degrees, -100 becomes 260). Angle 0 is due north, and
	1463	* rotates clockwise as the value increases. For efficiency, the precision of
	1464	* this effect may be limited (angles 1 through 7 might all produce the same
	1465	* effect, 8 through 15 are equal, etc). `distance` is an integer between 0
	1466	* and 255 that specifies the space between the sound and the listener. The
	1467	* larger the number, the further away the sound is. Using 255 does not
	1468	* guarantee that the channel will be removed from the mixing process or be
	1469	* completely silent. For efficiency, the precision of this effect may be
	1470	* limited (distance 0 through 5 might all produce the same effect, 6 through
	1471	* 10 are equal, etc). Setting `angle` and `distance` to 0 unregisters this
	1472	* effect, since the data would be unchanged.
444	1473	*
445	1474	* If you need more precise positional audio, consider using OpenAL for
446		* spatialized effects instead of SDL_mixer. This is only meant to be a
447		* basic effect for simple "3D" games.
448		*
449		* If the audio device is configured for mono output, then you won't get
450		* any effectiveness from the angle; however, distance attenuation on the
451		* channel will still occur. While this effect will function with stereo
452		* voices, it makes more sense to use voices with only one channel of sound,
453		* so when they are mixed through this effect, the positioning will sound
454		* correct. You can convert them to mono through SDL before giving them to
455		* the mixer in the first place if you like.
456		*
457		* Setting (channel) to MIX_CHANNEL_POST registers this as a posteffect, and
458		* the positioning will be done to the final mixed stream before passing it
459		* on to the audio device.
	1475	* spatialized effects instead of SDL_mixer. This is only meant to be a basic
	1476	* effect for simple "3D" games.
	1477	*
	1478	* If the audio device is configured for mono output, then you won't get any
	1479	* effectiveness from the angle; however, distance attenuation on the channel
	1480	* will still occur. While this effect will function with stereo voices, it
	1481	* makes more sense to use voices with only one channel of sound, so when they
	1482	* are mixed through this effect, the positioning will sound correct. You can
	1483	* convert them to mono through SDL before giving them to the mixer in the
	1484	* first place if you like.
	1485	*
	1486	* Setting the channel to MIX_CHANNEL_POST registers this as a posteffect, and
	1487	* the positioning will be done to the final mixed stream before passing it on
	1488	* to the audio device.
460	1489	*
461	1490	* This is a convenience wrapper over Mix_SetDistance() and Mix_SetPanning().
462	1491	*
463		* returns zero if error (no such channel or Mix_RegisterEffect() fails),
464		* nonzero if position effect is enabled.
465		* Error messages can be retrieved from Mix_GetError().
	1492	* Note that unlike most SDL and SDL_mixer functions, this function returns
	1493	* zero if there's an error, not on success. We apologize for the API design
	1494	* inconsistency here.
	1495	*
	1496	* \param channel The mixer channel to position, or MIX_CHANNEL_POST.
	1497	* \param angle angle, in degrees. North is 0, and goes clockwise.
	1498	* \param distance distance; 0 is the listener, 255 is maxiumum distance away.
	1499	* \returns zero if error (no such channel or Mix_RegisterEffect() fails),
	1500	* nonzero if position effect is enabled. Error messages can be
	1501	* retrieved from Mix_GetError().
	1502	*
	1503	* \since This function is available since SDL_mixer 2.0.0.
466	1504	*/
467	1505	extern DECLSPEC int SDLCALL Mix_SetPosition(int channel, Sint16 angle, Uint8 distance);
468	1506
469	1507
470		/* Set the "distance" of a channel. (distance) is an integer from 0 to 255
471		* that specifies the location of the sound in relation to the listener.
472		* Distance 0 is overlapping the listener, and 255 is as far away as possible
473		* A distance of 255 does not guarantee silence; in such a case, you might
474		* want to try changing the chunk's volume, or just cull the sample from the
475		* mixing process with Mix_HaltChannel().
476		* For efficiency, the precision of this effect may be limited (distances 1
477		* through 7 might all produce the same effect, 8 through 15 are equal, etc).
478		* (distance) is an integer between 0 and 255 that specifies the space
479		* between the sound and the listener. The larger the number, the further
480		* away the sound is.
481		* Setting (distance) to 0 unregisters this effect, since the data would be
482		* unchanged.
483		* If you need more precise positional audio, consider using OpenAL for
484		* spatialized effects instead of SDL_mixer. This is only meant to be a
485		* basic effect for simple "3D" games.
486		*
487		* Setting (channel) to MIX_CHANNEL_POST registers this as a posteffect, and
488		* the distance attenuation will be done to the final mixed stream before
489		* passing it on to the audio device.
	1508	/**
	1509	* Set the "distance" of a channel.
	1510	*
	1511	* `distance` is an integer from 0 to 255 that specifies the location of the
	1512	* sound in relation to the listener. Distance 0 is overlapping the listener,
	1513	* and 255 is as far away as possible. A distance of 255 does not guarantee
	1514	* silence; in such a case, you might want to try changing the chunk's volume,
	1515	* or just cull the sample from the mixing process with Mix_HaltChannel(). For
	1516	* efficiency, the precision of this effect may be limited (distances 1
	1517	* through 7 might all produce the same effect, 8 through 15 are equal, etc).
	1518	* (distance) is an integer between 0 and 255 that specifies the space between
	1519	* the sound and the listener. The larger the number, the further away the
	1520	* sound is. Setting the distance to 0 unregisters this effect, since the data
	1521	* would be unchanged. If you need more precise positional audio, consider
	1522	* using OpenAL for spatialized effects instead of SDL_mixer. This is only
	1523	* meant to be a basic effect for simple "3D" games.
	1524	*
	1525	* Setting the channel to MIX_CHANNEL_POST registers this as a posteffect, and
	1526	* the distance attenuation will be done to the final mixed stream before
	1527	* passing it on to the audio device.
490	1528	*
491	1529	* This uses the Mix_RegisterEffect() API internally.
492	1530	*
493		* returns zero if error (no such channel or Mix_RegisterEffect() fails),
494		* nonzero if position effect is enabled.
495		* Error messages can be retrieved from Mix_GetError().
	1531	* Note that unlike most SDL and SDL_mixer functions, this function returns
	1532	* zero if there's an error, not on success. We apologize for the API design
	1533	* inconsistency here.
	1534	*
	1535	* \param channel The mixer channel to attenuate, or MIX_CHANNEL_POST.
	1536	* \param distance distance; 0 is the listener, 255 is maxiumum distance away.
	1537	* \returns zero if error (no such channel or Mix_RegisterEffect() fails),
	1538	* nonzero if position effect is enabled. Error messages can be
	1539	* retrieved from Mix_GetError().
	1540	*
	1541	* \since This function is available since SDL_mixer 2.0.0.
496	1542	*/
497	1543	extern DECLSPEC int SDLCALL Mix_SetDistance(int channel, Uint8 distance);
498	1544
499	1545
500		/*
501		* !!! FIXME : Haven't implemented, since the effect goes past the
502		* end of the sound buffer. Will have to think about this.
503		* --ryan.
504		*/
505		#if 0
506		/* Causes an echo effect to be mixed into a sound. (echo) is the amount
507		* of echo to mix. 0 is no echo, 255 is infinite (and probably not
508		* what you want).
509		*
510		* Setting (channel) to MIX_CHANNEL_POST registers this as a posteffect, and
511		* the reverbing will be done to the final mixed stream before passing it on
512		* to the audio device.
513		*
514		* This uses the Mix_RegisterEffect() API internally. If you specify an echo
515		* of zero, the effect is unregistered, as the data is already in that state.
516		*
517		* returns zero if error (no such channel or Mix_RegisterEffect() fails),
518		* nonzero if reversing effect is enabled.
519		* Error messages can be retrieved from Mix_GetError().
520		*/
521		extern no_parse_DECLSPEC int SDLCALL Mix_SetReverb(int channel, Uint8 echo);
522		#endif
523
524		/* Causes a channel to reverse its stereo. This is handy if the user has his
525		* speakers hooked up backwards, or you would like to have a minor bit of
526		* psychedelia in your sound code. :) Calling this function with (flip)
527		* set to non-zero reverses the chunks's usual channels. If (flip) is zero,
528		* the effect is unregistered.
	1546	/**
	1547	* Cause a channel to reverse its stereo.
	1548	*
	1549	* This is handy if the user has his speakers hooked up backwards, or you
	1550	* would like to have a trippy sound effect.
	1551	*
	1552	* Calling this function with `flip` set to non-zero reverses the chunks's
	1553	* usual channels. If `flip` is zero, the effect is unregistered.
529	1554	*
530	1555	* This uses the Mix_RegisterEffect() API internally, and thus is probably
531		* more CPU intensive than having the user just plug in his speakers
532		* correctly. Mix_SetReverseStereo() returns without registering the effect
533		* function if the audio device is not configured for stereo output.
534		*
535		* If you specify MIX_CHANNEL_POST for (channel), then this the effect is used
536		* on the final mixed stream before sending it on to the audio device (a
537		* posteffect).
538		*
539		* returns zero if error (no such channel or Mix_RegisterEffect() fails),
540		* nonzero if reversing effect is enabled. Note that an audio device in mono
541		* mode is a no-op, but this call will return successful in that case.
542		* Error messages can be retrieved from Mix_GetError().
	1556	* more CPU intensive than having the user just plug in his speakers
	1557	* correctly. Mix_SetReverseStereo() returns without registering the effect
	1558	* function if the audio device is not configured for stereo output.
	1559	*
	1560	* If you specify MIX_CHANNEL_POST for `channel`, then this effect is used on
	1561	* the final mixed stream before sending it on to the audio device (a
	1562	* posteffect).
	1563	*
	1564	* Note that unlike most SDL and SDL_mixer functions, this function returns
	1565	* zero if there's an error, not on success. We apologize for the API design
	1566	* inconsistency here.
	1567	*
	1568	* \param channel The mixer channel to reverse, or MIX_CHANNEL_POST.
	1569	* \param flip non-zero to reverse stereo, zero to disable this effect.
	1570	* \returns zero if error (no such channel or Mix_RegisterEffect() fails),
	1571	* nonzero if reversing effect is enabled. Note that an audio device
	1572	* in mono mode is a no-op, but this call will return successful in
	1573	* that case. Error messages can be retrieved from Mix_GetError().
	1574	*
	1575	* \since This function is available since SDL_mixer 2.0.0.
543	1576	*/
544	1577	extern DECLSPEC int SDLCALL Mix_SetReverseStereo(int channel, int flip);
545	1578
546		/* end of effects API. --ryan. */
547
548
549		/* Reserve the first channels (0 -> n-1) for the application, i.e. don't allocate
550		them dynamically to the next sample if requested with a -1 value below.
551		Returns the number of reserved channels.
	1579	/* end of effects API. */
	1580
	1581
	1582
	1583	/**
	1584	* Reserve the first channels for the application.
	1585	*
	1586	* While SDL_mixer will use up to the number of channels allocated by
	1587	* Mix_AllocateChannels(), this sets channels aside that will not be available
	1588	* when calling Mix_PlayChannel with a channel of -1 (play on the first unused
	1589	* channel). In this case, SDL_mixer will treat reserved channels as "used"
	1590	* whether anything is playing on them at the moment or not.
	1591	*
	1592	* This is useful if you've budgeted some channels for dedicated audio and the
	1593	* rest are just used as they are available.
	1594	*
	1595	* Calling this function will set channels 0 to `n - 1` to be reserved. This
	1596	* will not change channel allocations. The number of reserved channels will
	1597	* be clamped to the current number allocated.
	1598	*
	1599	* By default, no channels are reserved.
	1600	*
	1601	* \param num number of channels to reserve, starting at index zero.
	1602	* \returns the number of reserved channels.
	1603	*
	1604	* \since This function is available since SDL_mixer 2.0.0.
552	1605	*/
553	1606	extern DECLSPEC int SDLCALL Mix_ReserveChannels(int num);
554	1607
	1608
555	1609	/* Channel grouping functions */
556	1610
557		/* Attach a tag to a channel. A tag can be assigned to several mixer
558		channels, to form groups of channels.
559		If 'tag' is -1, the tag is removed (actually -1 is the tag used to
560		represent the group of all the channels).
561		Returns true if everything was OK.
	1611	/**
	1612	* Assign a tag to a channel.
	1613	*
	1614	* A tag is an arbitary number that can be assigned to several mixer channels,
	1615	* to form groups of channels.
	1616	*
	1617	* If 'tag' is -1, the tag is removed (actually -1 is the tag used to
	1618	* represent the group of all the channels).
	1619	*
	1620	* This function replaces the requested channel's current tag; you may only
	1621	* have one tag per channel.
	1622	*
	1623	* You may not specify MAX_CHANNEL_POST for a channel.
	1624	*
	1625	* \param which the channel to set the tag on.
	1626	* \param tag an arbitrary value to assign a channel.
	1627	* \returns non-zero on success, zero on error (no such channel).
	1628	*
	1629	* \since This function is available since SDL_mixer 2.0.0.
562	1630	*/
563	1631	extern DECLSPEC int SDLCALL Mix_GroupChannel(int which, int tag);
564		/* Assign several consecutive channels to a group */
	1632
	1633	/**
	1634	* Assign several consecutive channels to the same tag.
	1635	*
	1636	* A tag is an arbitary number that can be assigned to several mixer channels,
	1637	* to form groups of channels.
	1638	*
	1639	* If 'tag' is -1, the tag is removed (actually -1 is the tag used to
	1640	* represent the group of all the channels).
	1641	*
	1642	* This function replaces the requested channels' current tags; you may only
	1643	* have one tag per channel.
	1644	*
	1645	* You may not specify MAX_CHANNEL_POST for a channel.
	1646	*
	1647	* Note that this returns success and failure in the _opposite_ way from
	1648	* Mix_GroupChannel(). We regret the API design mistake.
	1649	*
	1650	* \param from the first channel to set the tag on.
	1651	* \param to the last channel to set the tag on, inclusive.
	1652	* \param tag an arbitrary value to assign a channel.
	1653	* \returns 0 if successful, negative on error
	1654	*
	1655	* \since This function is available since SDL_mixer 2.0.0.
	1656	*/
565	1657	extern DECLSPEC int SDLCALL Mix_GroupChannels(int from, int to, int tag);
566		/* Finds the first available channel in a group of channels,
567		returning -1 if none are available.
	1658
	1659	/**
	1660	* Finds the first available channel in a group of channels.
	1661	*
	1662	* A tag is an arbitary number that can be assigned to several mixer channels,
	1663	* to form groups of channels.
	1664	*
	1665	* This function searches all channels with a specified tag, and returns the
	1666	* channel number of the first one it finds that is currently unused.
	1667	*
	1668	* If no channels with the specified tag are unused, this function returns -1.
	1669	*
	1670	* \param tag an arbitrary value, assigned to channels, to search for.
	1671	* \returns first available channel, or -1 if none are available.
	1672	*
	1673	* \since This function is available since SDL_mixer 2.0.0.
568	1674	*/
569	1675	extern DECLSPEC int SDLCALL Mix_GroupAvailable(int tag);
570		/* Returns the number of channels in a group. This is also a subtle
571		way to get the total number of channels when 'tag' is -1
	1676
	1677	/**
	1678	* Returns the number of channels in a group.
	1679	*
	1680	* If tag is -1, this will return the total number of channels allocated,
	1681	* regardless of what their tag might be.
	1682	*
	1683	* \param tag an arbitrary value, assigned to channels, to search for.
	1684	* \returns the number of channels assigned the specified tag.
	1685	*
	1686	* \since This function is available since SDL_mixer 2.0.0.
572	1687	*/
573	1688	extern DECLSPEC int SDLCALL Mix_GroupCount(int tag);
574		/* Finds the "oldest" sample playing in a group of channels */
	1689
	1690	/**
	1691	* Find the "oldest" sample playing in a group of channels.
	1692	*
	1693	* Specifically, this function returns the channel number that is assigned the
	1694	* specified tag, is currently playing, and has the lowest start time, based
	1695	* on the value of SDL_GetTicks() when the channel started playing.
	1696	*
	1697	* If no channel with this tag is currently playing, this function returns -1.
	1698	*
	1699	* \param tag an arbitrary value, assigned to channels, to search through.
	1700	* \returns the "oldest" sample playing in a group of channels
	1701	*
	1702	* \since This function is available since SDL_mixer 2.0.0.
	1703	*
	1704	* \sa Mix_GroupNewer
	1705	*/
575	1706	extern DECLSPEC int SDLCALL Mix_GroupOldest(int tag);
576		/* Finds the "most recent" (i.e. last) sample playing in a group of channels */
	1707
	1708	/**
	1709	* Find the "most recent" sample playing in a group of channels.
	1710	*
	1711	* Specifically, this function returns the channel number that is assigned the
	1712	* specified tag, is currently playing, and has the highest start time, based
	1713	* on the value of SDL_GetTicks() when the channel started playing.
	1714	*
	1715	* If no channel with this tag is currently playing, this function returns -1.
	1716	*
	1717	* \param tag an arbitrary value, assigned to channels, to search through.
	1718	* \returns the "most recent" sample playing in a group of channels
	1719	*
	1720	* \since This function is available since SDL_mixer 2.0.0.
	1721	*
	1722	* \sa Mix_GroupOldest
	1723	*/
577	1724	extern DECLSPEC int SDLCALL Mix_GroupNewer(int tag);
578	1725
579		/* Play an audio chunk on a specific channel.
580		If the specified channel is -1, play on the first free channel.
581		If 'loops' is greater than zero, loop the sound that many times.
582		If 'loops' is -1, loop inifinitely (~65000 times).
583		Returns which channel was used to play the sound.
584		*/
585		#define Mix_PlayChannel(channel,chunk,loops) Mix_PlayChannelTimed(channel,chunk,loops,-1)
586		/* The same as above, but the sound is played at most 'ticks' milliseconds */
	1726	/**
	1727	* Play an audio chunk on a specific channel.
	1728	*
	1729	* If the specified channel is -1, play on the first free channel (and return
	1730	* -1 without playing anything new if no free channel was available).
	1731	*
	1732	* If a specific channel was requested, and there is a chunk already playing
	1733	* there, that chunk will be halted and the new chunk will take its place.
	1734	*
	1735	* If `loops` is greater than zero, loop the sound that many times. If `loops`
	1736	* is -1, loop "infinitely" (~65000 times).
	1737	*
	1738	* Note that before SDL_mixer 2.6.0, this function was a macro that called
	1739	* Mix_PlayChannelTimed() with a fourth parameter ("ticks") of -1. This
	1740	* function still does the same thing, but promotes it to a proper API
	1741	* function. Older binaries linked against a newer SDL_mixer will still call
	1742	* Mix_PlayChannelTimed directly, as they are using the macro, which was
	1743	* available since the dawn of time.
	1744	*
	1745	* \param channel the channel on which to play the new chunk.
	1746	* \param chunk the new chunk to play.
	1747	* \param loop the number of times the chunk should loop, -1 to loop (not
	1748	* actually) infinitely.
	1749	* \returns which channel was used to play the sound, or -1 if sound could not
	1750	* be played.
	1751	*
	1752	* \since This function is available since SDL_mixer 2.6.0 (and as a macro
	1753	* since 2.0.0).
	1754	*/
	1755	extern DECLSPEC int SDLCALL Mix_PlayChannel(int channel, Mix_Chunk *chunk, int loops);
	1756
	1757	/**
	1758	* Play an audio chunk on a specific channel for a maximum time.
	1759	*
	1760	* If the specified channel is -1, play on the first free channel (and return
	1761	* -1 without playing anything new if no free channel was available).
	1762	*
	1763	* If a specific channel was requested, and there is a chunk already playing
	1764	* there, that chunk will be halted and the new chunk will take its place.
	1765	*
	1766	* If `loops` is greater than zero, loop the sound that many times. If `loops`
	1767	* is -1, loop "infinitely" (~65000 times).
	1768	*
	1769	* `ticks` specifies the maximum number of milliseconds to play this chunk
	1770	* before halting it. If you want the chunk to play until all data has been
	1771	* mixed, specify -1.
	1772	*
	1773	* Note that this function does not block for the number of ticks requested;
	1774	* it just schedules the chunk to play and notes the maximum for the mixer to
	1775	* manage later, and returns immediately.
	1776	*
	1777	* \param channel the channel on which to play the new chunk.
	1778	* \param chunk the new chunk to play.
	1779	* \param loop the number of times the chunk should loop, -1 to loop (not
	1780	* actually) infinitely.
	1781	* \param ticks the maximum number of milliseconds of this chunk to mix for
	1782	* playback.
	1783	* \returns which channel was used to play the sound, or -1 if sound could not
	1784	* be played.
	1785	*
	1786	* \since This function is available since SDL_mixer 2.0.0.
	1787	*/
587	1788	extern DECLSPEC int SDLCALL Mix_PlayChannelTimed(int channel, Mix_Chunk *chunk, int loops, int ticks);
	1789
	1790	/**
	1791	* Play a new music object.
	1792	*
	1793	* This will schedule the music object to begin mixing for playback.
	1794	*
	1795	* There is only ever one music object playing at a time; if this is called
	1796	* when another music object is playing, the currently-playing music is halted
	1797	* and the new music will replace it.
	1798	*
	1799	* Please note that if the currently-playing music is in the process of fading
	1800	* out (via Mix_FadeOutMusic()), this function will block until the fade
	1801	* completes. If you need to avoid this, be sure to call Mix_HaltMusic()
	1802	* before starting new music.
	1803	*
	1804	* \param music the new music object to schedule for mixing.
	1805	* \param loops the number of loops to play the music for (0 means "play once
	1806	* and stop").
	1807	* \returns zero on success, -1 on error.
	1808	*
	1809	* \since This function is available since SDL_mixer 2.0.0.
	1810	*/
588	1811	extern DECLSPEC int SDLCALL Mix_PlayMusic(Mix_Music *music, int loops);
589	1812
590		/* Fade in music or a channel over "ms" milliseconds, same semantics as the "Play" functions */
	1813	/**
	1814	* Play a new music object, fading in the audio.
	1815	*
	1816	* This will start the new music playing, much like Mix_PlayMusic() will, but
	1817	* will start the music playing at silence and fade in to its normal volume
	1818	* over the specified number of milliseconds.
	1819	*
	1820	* If there is already music playing, that music will be halted and the new
	1821	* music object will take its place.
	1822	*
	1823	* If `loops` is greater than zero, loop the music that many times. If `loops`
	1824	* is -1, loop "infinitely" (~65000 times).
	1825	*
	1826	* Fading music will change it's volume progressively, as if Mix_VolumeMusic()
	1827	* was called on it (which is to say: you probably shouldn't call
	1828	* Mix_VolumeMusic() on fading music).
	1829	*
	1830	* \param music the new music object to play.
	1831	* \param loop the number of times the chunk should loop, -1 to loop (not
	1832	* actually) infinitely.
	1833	* \param ms the number of milliseconds to spend fading in.
	1834	* \returns zero on success, -1 on error.
	1835	*
	1836	* \since This function is available since SDL_mixer 2.0.0.
	1837	*/
591	1838	extern DECLSPEC int SDLCALL Mix_FadeInMusic(Mix_Music *music, int loops, int ms);
	1839
	1840	/**
	1841	* Play a new music object, fading in the audio, from a starting position.
	1842	*
	1843	* This will start the new music playing, much like Mix_PlayMusic() will, but
	1844	* will start the music playing at silence and fade in to its normal volume
	1845	* over the specified number of milliseconds.
	1846	*
	1847	* If there is already music playing, that music will be halted and the new
	1848	* music object will take its place.
	1849	*
	1850	* If `loops` is greater than zero, loop the music that many times. If `loops`
	1851	* is -1, loop "infinitely" (~65000 times).
	1852	*
	1853	* Fading music will change it's volume progressively, as if Mix_VolumeMusic()
	1854	* was called on it (which is to say: you probably shouldn't call
	1855	* Mix_VolumeMusic() on fading music).
	1856	*
	1857	* This function allows the caller to start the music playback past the
	1858	* beginning of its audio data. You may specify a start position, in seconds,
	1859	* and the playback and fade-in will start there instead of with the first
	1860	* samples of the music.
	1861	*
	1862	* An app can specify a `position` of 0.0 to start at the beginning of the
	1863	* music (or just call Mix_FadeInMusic() instead).
	1864	*
	1865	* To convert from milliseconds, divide by 1000.0.
	1866	*
	1867	* \param music the new music object to play.
	1868	* \param loop the number of times the chunk should loop, -1 to loop (not
	1869	* actually) infinitely.
	1870	* \param ms the number of milliseconds to spend fading in.
	1871	* \param position the start position within the music, in seconds, where
	1872	* playback should start.
	1873	* \returns zero on success, -1 on error.
	1874	*
	1875	* \since This function is available since SDL_mixer 2.0.0.
	1876	*/
592	1877	extern DECLSPEC int SDLCALL Mix_FadeInMusicPos(Mix_Music *music, int loops, int ms, double position);
593		#define Mix_FadeInChannel(channel,chunk,loops,ms) Mix_FadeInChannelTimed(channel,chunk,loops,ms,-1)
	1878
	1879	/**
	1880	* Play an audio chunk on a specific channel, fading in the audio.
	1881	*
	1882	* This will start the new sound playing, much like Mix_PlayChannel() will,
	1883	* but will start the sound playing at silence and fade in to its normal
	1884	* volume over the specified number of milliseconds.
	1885	*
	1886	* If the specified channel is -1, play on the first free channel (and return
	1887	* -1 without playing anything new if no free channel was available).
	1888	*
	1889	* If a specific channel was requested, and there is a chunk already playing
	1890	* there, that chunk will be halted and the new chunk will take its place.
	1891	*
	1892	* If `loops` is greater than zero, loop the sound that many times. If `loops`
	1893	* is -1, loop "infinitely" (~65000 times).
	1894	*
	1895	* A fading channel will change it's volume progressively, as if Mix_Volume()
	1896	* was called on it (which is to say: you probably shouldn't call Mix_Volume()
	1897	* on a fading channel).
	1898	*
	1899	* Note that before SDL_mixer 2.6.0, this function was a macro that called
	1900	* Mix_FadeInChannelTimed() with a fourth parameter ("ticks") of -1. This
	1901	* function still does the same thing, but promotes it to a proper API
	1902	* function. Older binaries linked against a newer SDL_mixer will still call
	1903	* Mix_FadeInChannelTimed directly, as they are using the macro, which was
	1904	* available since the dawn of time.
	1905	*
	1906	* \param channel the channel on which to play the new chunk, or -1 to find
	1907	* any available.
	1908	* \param chunk the new chunk to play.
	1909	* \param loop the number of times the chunk should loop, -1 to loop (not
	1910	* actually) infinitely.
	1911	* \param ms the number of milliseconds to spend fading in.
	1912	* \returns which channel was used to play the sound, or -1 if sound could not
	1913	* be played.
	1914	*
	1915	* \since This function is available since SDL_mixer 2.6.0 (and as a macro
	1916	* since 2.0.0).
	1917	*/
	1918	extern DECLSPEC int SDLCALL Mix_FadeInChannel(int channel, Mix_Chunk *chunk, int loops, int ms);
	1919
	1920	/**
	1921	* Play an audio chunk on a specific channel, fading in the audio, for a
	1922	* maximum time.
	1923	*
	1924	* This will start the new sound playing, much like Mix_PlayChannel() will,
	1925	* but will start the sound playing at silence and fade in to its normal
	1926	* volume over the specified number of milliseconds.
	1927	*
	1928	* If the specified channel is -1, play on the first free channel (and return
	1929	* -1 without playing anything new if no free channel was available).
	1930	*
	1931	* If a specific channel was requested, and there is a chunk already playing
	1932	* there, that chunk will be halted and the new chunk will take its place.
	1933	*
	1934	* If `loops` is greater than zero, loop the sound that many times. If `loops`
	1935	* is -1, loop "infinitely" (~65000 times).
	1936	*
	1937	* `ticks` specifies the maximum number of milliseconds to play this chunk
	1938	* before halting it. If you want the chunk to play until all data has been
	1939	* mixed, specify -1.
	1940	*
	1941	* Note that this function does not block for the number of ticks requested;
	1942	* it just schedules the chunk to play and notes the maximum for the mixer to
	1943	* manage later, and returns immediately.
	1944	*
	1945	* A fading channel will change it's volume progressively, as if Mix_Volume()
	1946	* was called on it (which is to say: you probably shouldn't call Mix_Volume()
	1947	* on a fading channel).
	1948	*
	1949	* \param channel the channel on which to play the new chunk, or -1 to find
	1950	* any available.
	1951	* \param chunk the new chunk to play.
	1952	* \param loop the number of times the chunk should loop, -1 to loop (not
	1953	* actually) infinitely.
	1954	* \param ms the number of milliseconds to spend fading in.
	1955	* \param ticks the maximum number of milliseconds of this chunk to mix for
	1956	* playback.
	1957	* \returns which channel was used to play the sound, or -1 if sound could not
	1958	* be played.
	1959	*
	1960	* \since This function is available since SDL_mixer 2.0.0.
	1961	*/
594	1962	extern DECLSPEC int SDLCALL Mix_FadeInChannelTimed(int channel, Mix_Chunk *chunk, int loops, int ms, int ticks);
595	1963
596		/* Set the volume in the range of 0-128 of a specific channel or chunk.
597		If the specified channel is -1, set volume for all channels.
598		Returns the original volume.
599		If the specified volume is -1, just return the current volume.
600		*/
	1964	/**
	1965	* Set the volume for a specific channel.
	1966	*
	1967	* The volume must be between 0 (silence) and MIX_MAX_VOLUME (full volume).
	1968	* Note that MIX_MAX_VOLUME is 128. Values greater than MIX_MAX_VOLUME are
	1969	* clamped to MIX_MAX_VOLUME.
	1970	*
	1971	* Specifying a negative volume will not change the current volume; as such,
	1972	* this can be used to query the current volume without making changes, as
	1973	* this function returns the previous (in this case, still-current) value.
	1974	*
	1975	* If the specified channel is -1, this function sets the volume for all
	1976	* channels, and returns _the average_ of all channels' volumes prior to this
	1977	* call.
	1978	*
	1979	* The default volume for a channel is MIX_MAX_VOLUME (no attenuation).
	1980	*
	1981	* \param channel the channel on set/query the volume on, or -1 for all
	1982	* channels.
	1983	* \param volume the new volume, between 0 and MIX_MAX_VOLUME, or -1 to query.
	1984	* \returns the previous volume. If the specified volume is -1, this returns
	1985	* the current volume. If `channel` is -1, this returns the average
	1986	* of all channels.
	1987	*
	1988	* \since This function is available since SDL_mixer 2.0.0.
	1989	*/
601	1990	extern DECLSPEC int SDLCALL Mix_Volume(int channel, int volume);
	1991
	1992	/**
	1993	* Set the volume for a specific chunk.
	1994	*
	1995	* In addition to channels having a volume setting, individual chunks also
	1996	* maintain a seperate volume. Both values are considered when mixing, so both
	1997	* affect the final attenuation of the sound. This lets an app adjust the
	1998	* volume for all instances of a sound in addition to specific instances of
	1999	* that sound.
	2000	*
	2001	* The volume must be between 0 (silence) and MIX_MAX_VOLUME (full volume).
	2002	* Note that MIX_MAX_VOLUME is 128. Values greater than MIX_MAX_VOLUME are
	2003	* clamped to MIX_MAX_VOLUME.
	2004	*
	2005	* Specifying a negative volume will not change the current volume; as such,
	2006	* this can be used to query the current volume without making changes, as
	2007	* this function returns the previous (in this case, still-current) value.
	2008	*
	2009	* The default volume for a chunk is MIX_MAX_VOLUME (no attenuation).
	2010	*
	2011	* \param channel the channel on set/query the volume on, or -1 for all
	2012	* channels.
	2013	* \param volume the new volume, between 0 and MIX_MAX_VOLUME, or -1 to query.
	2014	* \returns the previous volume. If the specified volume is -1, this returns
	2015	* the current volume. If `chunk` is NULL, this returns -1.
	2016	*
	2017	* \since This function is available since SDL_mixer 2.0.0.
	2018	*/
602	2019	extern DECLSPEC int SDLCALL Mix_VolumeChunk(Mix_Chunk *chunk, int volume);
	2020
	2021	/**
	2022	* Set the volume for the music channel.
	2023	*
	2024	* The volume must be between 0 (silence) and MIX_MAX_VOLUME (full volume).
	2025	* Note that MIX_MAX_VOLUME is 128. Values greater than MIX_MAX_VOLUME are
	2026	* clamped to MIX_MAX_VOLUME.
	2027	*
	2028	* Specifying a negative volume will not change the current volume; as such,
	2029	* this can be used to query the current volume without making changes, as
	2030	* this function returns the previous (in this case, still-current) value.
	2031	*
	2032	* The default volume for music is MIX_MAX_VOLUME (no attenuation).
	2033	*
	2034	* \param volume the new volume, between 0 and MIX_MAX_VOLUME, or -1 to query.
	2035	* \returns the previous volume. If the specified volume is -1, this returns
	2036	* the current volume.
	2037	*
	2038	* \since This function is available since SDL_mixer 2.0.0.
	2039	*/
603	2040	extern DECLSPEC int SDLCALL Mix_VolumeMusic(int volume);
604		/* Get the current volume value in the range of 0-128 of a music stream */
	2041
	2042	/**
	2043	* Query the current volume value for a music object.
	2044	*
	2045	* \param music the music object to query.
	2046	* \returns the music's current volume, between 0 and MIX_MAX_VOLUME (128).
	2047	*
	2048	* \since This function is available since SDL_mixer 2.6.0.
	2049	*/
605	2050	extern DECLSPEC int SDLCALL Mix_GetMusicVolume(Mix_Music *music);
606	2051
607		/* Set the master volume for all channels.
608		This did not affect the member variables of channel or chunk volume.
609		If the specified volume is -1, just return the current master volume.
610		*/
	2052	/**
	2053	* Set the master volume for all channels.
	2054	*
	2055	* SDL_mixer keeps a per-channel volume, a per-chunk volume, and a master
	2056	* volume, and considers all three when mixing audio. This function sets the
	2057	* master volume, which is applied to all playing channels when mixing.
	2058	*
	2059	* The volume must be between 0 (silence) and MIX_MAX_VOLUME (full volume).
	2060	* Note that MIX_MAX_VOLUME is 128. Values greater than MIX_MAX_VOLUME are
	2061	* clamped to MIX_MAX_VOLUME.
	2062	*
	2063	* Specifying a negative volume will not change the current volume; as such,
	2064	* this can be used to query the current volume without making changes, as
	2065	* this function returns the previous (in this case, still-current) value.
	2066	*
	2067	* Note that the master volume does not affect any playing music; it is only
	2068	* applied when mixing chunks. Use Mix_MusicVolume() for that.\
	2069	*
	2070	* \param volume the new volume, between 0 and MIX_MAX_VOLUME, or -1 to query.
	2071	* \returns the previous volume. If the specified volume is -1, this returns
	2072	* the current volume.
	2073	*
	2074	* \since This function is available since SDL_mixer 2.6.0.
	2075	*/
611	2076	extern DECLSPEC int SDLCALL Mix_MasterVolume(int volume);
612	2077
613		/* Halt playing of a particular channel */
	2078	/**
	2079	* Halt playing of a particular channel.
	2080	*
	2081	* This will stop further playback on that channel until a new chunk is
	2082	* started there.
	2083	*
	2084	* Specifying a channel of -1 will halt _all_ channels, except for any playing
	2085	* music.
	2086	*
	2087	* Any halted channels will have any currently-registered effects
	2088	* deregistered, and will call any callback specified by Mix_ChannelFinished()
	2089	* before this function returns.
	2090	*
	2091	* You may not specify MAX_CHANNEL_POST for a channel.
	2092	*
	2093	* \param channel channel to halt, or -1 to halt all channels.
	2094	* \returns 0 on success, or -1 on error.
	2095	*
	2096	* \since This function is available since SDL_mixer 2.0.0.
	2097	*/
614	2098	extern DECLSPEC int SDLCALL Mix_HaltChannel(int channel);
	2099
	2100	/**
	2101	* Halt playing of a group of channels by arbitrary tag.
	2102	*
	2103	* This will stop further playback on all channels with a specific tag, until
	2104	* a new chunk is started there.
	2105	*
	2106	* A tag is an arbitary number that can be assigned to several mixer channels,
	2107	* to form groups of channels.
	2108	*
	2109	* The default tag for a channel is -1.
	2110	*
	2111	* Any halted channels will have any currently-registered effects
	2112	* deregistered, and will call any callback specified by Mix_ChannelFinished()
	2113	* before this function returns.
	2114	*
	2115	* \param tag an arbitrary value, assigned to channels, to search for.
	2116	* \returns zero, whether any channels were halted or not.
	2117	*
	2118	* \since This function is available since SDL_mixer 2.0.0.
	2119	*/
615	2120	extern DECLSPEC int SDLCALL Mix_HaltGroup(int tag);
	2121
	2122	/**
	2123	* Halt playing of the music stream.
	2124	*
	2125	* This will stop further playback of music until a new music object is
	2126	* started there.
	2127	*
	2128	* Any halted music will call any callback specified by
	2129	* Mix_HookMusicFinished() before this function returns.
	2130	*
	2131	* \returns zero, regardless of whether any music was halted.
	2132	*
	2133	* \since This function is available since SDL_mixer 2.0.0.
	2134	*/
616	2135	extern DECLSPEC int SDLCALL Mix_HaltMusic(void);
617	2136
618		/* Change the expiration delay for a particular channel.
619		The sample will stop playing after the 'ticks' milliseconds have elapsed,
620		or remove the expiration if 'ticks' is -1
621		*/
	2137	/**
	2138	* Change the expiration delay for a particular channel.
	2139	*
	2140	* The channel will halt after the 'ticks' milliseconds have elapsed, or
	2141	* remove the expiration if 'ticks' is -1.
	2142	*
	2143	* This overrides the value passed to the fourth parameter of
	2144	* Mix_PlayChannelTimed().
	2145	*
	2146	* Specifying a channel of -1 will set an expiration for _all_ channels.
	2147	*
	2148	* Any halted channels will have any currently-registered effects
	2149	* deregistered, and will call any callback specified by Mix_ChannelFinished()
	2150	* once the halt occurs.
	2151	*
	2152	* Note that this function does not block for the number of ticks requested;
	2153	* it just schedules the chunk to expire and notes the time for the mixer to
	2154	* manage later, and returns immediately.
	2155	*
	2156	* \param channel the channel to change the expiration time on.
	2157	* \param ticks number of milliseconds from now to let channel play before
	2158	* halting, -1 to not halt.
	2159	* \returns the number of channels that changed expirations.
	2160	*
	2161	* \since This function is available since SDL_mixer 2.0.0.
	2162	*/
622	2163	extern DECLSPEC int SDLCALL Mix_ExpireChannel(int channel, int ticks);
623	2164
624		/* Halt a channel, fading it out progressively till it's silent
625		The ms parameter indicates the number of milliseconds the fading
626		will take.
	2165	/**
	2166	* Halt a channel after fading it out for a specified time.
	2167	*
	2168	* This will begin a channel fading from its current volume to silence over
	2169	* `ms` milliseconds. After that time, the channel is halted.
	2170	*
	2171	* Any halted channels will have any currently-registered effects
	2172	* deregistered, and will call any callback specified by Mix_ChannelFinished()
	2173	* once the halt occurs.
	2174	*
	2175	* A fading channel will change it's volume progressively, as if Mix_Volume()
	2176	* was called on it (which is to say: you probably shouldn't call Mix_Volume()
	2177	* on a fading channel).
	2178	*
	2179	* Note that this function does not block for the number of milliseconds
	2180	* requested; it just schedules the chunk to fade and notes the time for the
	2181	* mixer to manage later, and returns immediately.
	2182	*
	2183	* \param which the channel to fade out.
	2184	* \param ms number of milliseconds to fade before halting the channel.
	2185	* \returns 0 on success, or -1 on error.
	2186	*
	2187	* \since This function is available since SDL_mixer 2.0.0.
627	2188	*/
628	2189	extern DECLSPEC int SDLCALL Mix_FadeOutChannel(int which, int ms);
	2190
	2191	/**
	2192	* Halt a playing group of channels by arbitrary tag, after fading them out
	2193	* for a specified time.
	2194	*
	2195	* This will begin fading a group of channels with a specific tag from their
	2196	* current volumes to silence over `ms` milliseconds. After that time, those
	2197	* channels are halted.
	2198	*
	2199	* A tag is an arbitary number that can be assigned to several mixer channels,
	2200	* to form groups of channels.
	2201	*
	2202	* The default tag for a channel is -1.
	2203	*
	2204	* Any halted channels will have any currently-registered effects
	2205	* deregistered, and will call any callback specified by Mix_ChannelFinished()
	2206	* once the halt occurs.
	2207	*
	2208	* A fading channel will change it's volume progressively, as if Mix_Volume()
	2209	* was called on it (which is to say: you probably shouldn't call Mix_Volume()
	2210	* on a fading channel).
	2211	*
	2212	* Note that this function does not block for the number of milliseconds
	2213	* requested; it just schedules the group to fade and notes the time for the
	2214	* mixer to manage later, and returns immediately.
	2215	*
	2216	* \param tag an arbitrary value, assigned to channels, to search for.
	2217	* \param ms number of milliseconds to fade before halting the group.
	2218	* \returns the number of channels that were scheduled for fading.
	2219	*
	2220	* \since This function is available since SDL_mixer 2.0.0.
	2221	*/
629	2222	extern DECLSPEC int SDLCALL Mix_FadeOutGroup(int tag, int ms);
	2223
	2224	/**
	2225	* Halt the music stream after fading it out for a specified time.
	2226	*
	2227	* This will begin the music fading from its current volume to silence over
	2228	* `ms` milliseconds. After that time, the music is halted.
	2229	*
	2230	* Any halted music will call any callback specified by
	2231	* Mix_HookMusicFinished() once the halt occurs.
	2232	*
	2233	* Fading music will change it's volume progressively, as if Mix_VolumeMusic()
	2234	* was called on it (which is to say: you probably shouldn't call
	2235	* Mix_VolumeMusic() on a fading channel).
	2236	*
	2237	* Note that this function does not block for the number of milliseconds
	2238	* requested; it just schedules the music to fade and notes the time for the
	2239	* mixer to manage later, and returns immediately.
	2240	*
	2241	* \param which the channel to fade out.
	2242	* \param ms number of milliseconds to fade before halting the channel.
	2243	* \returns non-zero if music was scheduled to fade, zero otherwise. If no
	2244	* music is currently playing, this returns zero.
	2245	*
	2246	* \since This function is available since SDL_mixer 2.0.0.
	2247	*/
630	2248	extern DECLSPEC int SDLCALL Mix_FadeOutMusic(int ms);
631	2249
632		/* Query the fading status of a channel */
	2250	/**
	2251	* Query the fading status of the music stream.
	2252	*
	2253	* This reports one of three values:
	2254	*
	2255	* - `MIX_NO_FADING`
	2256	* - `MIX_FADING_OUT`
	2257	* - `MIX_FADING_IN`
	2258	*
	2259	* If music is not currently playing, this returns `MIX_NO_FADING`.
	2260	*
	2261	* \returns the current fading status of the music stream.
	2262	*
	2263	* \since This function is available since SDL_mixer 2.0.0.
	2264	*/
633	2265	extern DECLSPEC Mix_Fading SDLCALL Mix_FadingMusic(void);
	2266
	2267	/**
	2268	* Query the fading status of a channel.
	2269	*
	2270	* This reports one of three values:
	2271	*
	2272	* - `MIX_NO_FADING`
	2273	* - `MIX_FADING_OUT`
	2274	* - `MIX_FADING_IN`
	2275	*
	2276	* If nothing is currently playing on the channel, or an invalid channel is
	2277	* specified, this returns `MIX_NO_FADING`.
	2278	*
	2279	* You may not specify MAX_CHANNEL_POST for a channel.
	2280	*
	2281	* You may not specify -1 for all channels; only individual channels may be
	2282	* queried.
	2283	*
	2284	* \param which the channel to query.
	2285	* \returns the current fading status of the channel.
	2286	*
	2287	* \since This function is available since SDL_mixer 2.0.0.
	2288	*/
634	2289	extern DECLSPEC Mix_Fading SDLCALL Mix_FadingChannel(int which);
635	2290
636		/* Pause/Resume a particular channel */
	2291	/**
	2292	* Pause a particular channel.
	2293	*
	2294	* Pausing a channel will prevent further playback of the assigned chunk but
	2295	* will maintain the chunk's current mixing position. When resumed, this
	2296	* channel will continue to mix the chunk where it left off.
	2297	*
	2298	* A paused channel can be resumed by calling Mix_Resume().
	2299	*
	2300	* A paused channel with an expiration will not expire while paused (the
	2301	* expiration countdown will be adjusted once resumed).
	2302	*
	2303	* It is legal to halt a paused channel. Playing a new chunk on a paused
	2304	* channel will replace the current chunk and unpause the channel.
	2305	*
	2306	* Specifying a channel of -1 will pause _all_ channels. Any music is
	2307	* unaffected.
	2308	*
	2309	* You may not specify MAX_CHANNEL_POST for a channel.
	2310	*
	2311	* \param channel the channel to pause, or -1 to pause all channels.
	2312	*
	2313	* \since This function is available since SDL_mixer 2.0.0.
	2314	*/
637	2315	extern DECLSPEC void SDLCALL Mix_Pause(int channel);
	2316
	2317	/**
	2318	* Resume a particular channel.
	2319	*
	2320	* It is legal to resume an unpaused or invalid channel; it causes no effect
	2321	* and reports no error.
	2322	*
	2323	* If the paused channel has an expiration, its expiration countdown resumes
	2324	* now, as well.
	2325	*
	2326	* Specifying a channel of -1 will resume _all_ paused channels. Any music is
	2327	* unaffected.
	2328	*
	2329	* \param channel the channel to resume, or -1 to resume all paused channels.
	2330	*
	2331	* \since This function is available since SDL_mixer 2.0.0.
	2332	*/
638	2333	extern DECLSPEC void SDLCALL Mix_Resume(int channel);
	2334
	2335	/**
	2336	* Query whether a particular channel is paused.
	2337	*
	2338	* If an invalid channel is specified, this function returns zero.
	2339	*
	2340	* \param channel the channel to query, or -1 to query all channels.
	2341	* \return 1 if channel paused, 0 otherwise. If `channel` is -1, returns the
	2342	* number of paused channels.
	2343	*
	2344	* \since This function is available since SDL_mixer 2.0.0.
	2345	*/
639	2346	extern DECLSPEC int SDLCALL Mix_Paused(int channel);
640	2347
641		/* Pause/Resume the music stream */
	2348	/**
	2349	* Pause the music stream.
	2350	*
	2351	* Pausing the music stream will prevent further playback of the assigned
	2352	* music object, but will maintain the object's current mixing position. When
	2353	* resumed, this channel will continue to mix the music where it left off.
	2354	*
	2355	* Paused music can be resumed by calling Mix_ResumeMusic().
	2356	*
	2357	* It is legal to halt paused music. Playing a new music object when music is
	2358	* paused will replace the current music and unpause the music stream.
	2359	*
	2360	* \since This function is available since SDL_mixer 2.0.0.
	2361	*/
642	2362	extern DECLSPEC void SDLCALL Mix_PauseMusic(void);
	2363
	2364	/**
	2365	* Resume the music stream.
	2366	*
	2367	* It is legal to resume an unpaused music stream; it causes no effect and
	2368	* reports no error.
	2369	*
	2370	* \since This function is available since SDL_mixer 2.0.0.
	2371	*/
643	2372	extern DECLSPEC void SDLCALL Mix_ResumeMusic(void);
	2373
	2374	/**
	2375	* Rewind the music stream.
	2376	*
	2377	* This causes the currently-playing music to start mixing from the beginning
	2378	* of the music, as if it were just started.
	2379	*
	2380	* It's a legal no-op to rewind the music stream when not playing.
	2381	*
	2382	* \since This function is available since SDL_mixer 2.0.0.
	2383	*/
644	2384	extern DECLSPEC void SDLCALL Mix_RewindMusic(void);
	2385
	2386	/**
	2387	* Query whether the music stream is paused.
	2388	*
	2389	* \return 1 if music is paused, 0 otherwise.
	2390	*
	2391	* \since This function is available since SDL_mixer 2.0.0.
	2392	*
	2393	* \sa Mix_PauseMusic
	2394	* \sa Mix_ResumeMusic
	2395	*/
645	2396	extern DECLSPEC int SDLCALL Mix_PausedMusic(void);
646	2397
647		/* Jump to a given order in mod music.
648		Returns 0 if successful, or -1 if failed or isn't implemented.
649		Only for MOD music formats.
	2398	/**
	2399	* Jump to a given order in mod music.
	2400	*
	2401	* This only applies to MOD music formats.
	2402	*
	2403	* \param order order
	2404	* \returns 0 if successful, or -1 if failed or isn't implemented.
	2405	*
	2406	* \since This function is available since SDL_mixer 2.6.0.
650	2407	*/
651	2408	extern DECLSPEC int SDLCALL Mix_ModMusicJumpToOrder(int order);
652	2409
653		/* Set the current position in the music stream (in seconds).
654		This returns 0 if successful, or -1 if it failed or not implemented.
655		This function is only implemented for MOD music formats (set pattern
656		order number) and for WAV, OGG, FLAC, MP3, and MODPLUG music at the
657		moment.
658		*/
	2410	/**
	2411	* Set the current position in the music stream, in seconds.
	2412	*
	2413	* To convert from milliseconds, divide by 1000.0.
	2414	*
	2415	* This function is only implemented for MOD music formats (set pattern order
	2416	* number) and for WAV, OGG, FLAC, MP3, and MODPLUG music at the moment.
	2417	*
	2418	* \param position the new position, in seconds (as a double).
	2419	* \returns 0 if successful, or -1 if it failed or not implemented.
	2420	*
	2421	* \since This function is available since SDL_mixer 2.0.0.
	2422	*/
659	2423	extern DECLSPEC int SDLCALL Mix_SetMusicPosition(double position);
660	2424
661		/*
662		Get the time current position of music stream
663		returns -1.0 if this feature is not supported for some codec
	2425	/**
	2426	* Get the time current position of music stream, in seconds.
	2427	*
	2428	* To convert to milliseconds, multiply by 1000.0.
	2429	*
	2430	* \param music the music object to query.
	2431	* \returns -1.0 if this feature is not supported for some codec.
	2432	*
	2433	* \since This function is available since SDL_mixer 2.6.0.
664	2434	*/
665	2435	extern DECLSPEC double SDLCALL Mix_GetMusicPosition(Mix_Music *music);
666	2436
667		/* Return music duration in seconds.
668		If NULL is passed, returns duration of current playing music.
669		Returns -1 on error.
	2437	/**
	2438	* Get a music object's duration, in seconds.
	2439	*
	2440	* To convert to milliseconds, multiply by 1000.0.
	2441	*
	2442	* If NULL is passed, returns duration of current playing music.
	2443	*
	2444	* \param music the music object to query.
	2445	* \returns music duration in seconds, or -1.0 on error.
	2446	*
	2447	* \since This function is available since SDL_mixer 2.6.0.
670	2448	*/
671	2449	extern DECLSPEC double SDLCALL Mix_MusicDuration(Mix_Music *music);
672	2450
673		/*
674		Get the loop start time position of music stream
675		returns -1.0 if this feature is not used for this music or not supported for some codec
	2451	/**
	2452	* Get the loop start time position of music stream, in seconds.
	2453	*
	2454	* To convert to milliseconds, multiply by 1000.0.
	2455	*
	2456	* If NULL is passed, returns duration of current playing music.
	2457	*
	2458	* \param music the music object to query.
	2459	* \returns -1.0 if this feature is not used for this music or not supported
	2460	* for some codec
	2461	*
	2462	* \since This function is available since SDL_mixer 2.6.0.
676	2463	*/
677	2464	extern DECLSPEC double SDLCALL Mix_GetMusicLoopStartTime(Mix_Music *music);
678		/*
679		Get the loop end time position of music stream
680		returns -1.0 if this feature is not used for this music or not supported for some codec
	2465
	2466	/**
	2467	* Get the loop end time position of music stream, in seconds.
	2468	*
	2469	* To convert to milliseconds, multiply by 1000.0.
	2470	*
	2471	* If NULL is passed, returns duration of current playing music.
	2472	*
	2473	* \param music the music object to query.
	2474	* \returns -1.0 if this feature is not used for this music or not supported
	2475	* for some codec
	2476	*
	2477	* \since This function is available since SDL_mixer 2.6.0.
681	2478	*/
682	2479	extern DECLSPEC double SDLCALL Mix_GetMusicLoopEndTime(Mix_Music *music);
683		/*
684		Get the loop time length of music stream
685		returns -1.0 if this feature is not used for this music or not supported for some codec
	2480
	2481	/**
	2482	* Get the loop time length of music stream, in seconds.
	2483	*
	2484	* To convert to milliseconds, multiply by 1000.0.
	2485	*
	2486	* If NULL is passed, returns duration of current playing music.
	2487	*
	2488	* \param music the music object to query.
	2489	* \returns -1.0 if this feature is not used for this music or not supported
	2490	* for some codec
	2491	*
	2492	* \since This function is available since SDL_mixer 2.6.0.
686	2493	*/
687	2494	extern DECLSPEC double SDLCALL Mix_GetMusicLoopLengthTime(Mix_Music *music);
688	2495
689		/* Check the status of a specific channel.
690		If the specified channel is -1, check all channels.
691		*/
	2496	/**
	2497	* Check the playing status of a specific channel.
	2498	*
	2499	* If the channel is currently playing, this function returns 1. Otherwise it
	2500	* returns 0.
	2501	*
	2502	* If the specified channel is -1, all channels are checked, and this function
	2503	* returns the number of channels currently playing.
	2504	*
	2505	* You may not specify MAX_CHANNEL_POST for a channel.
	2506	*
	2507	* Paused channels are treated as playing, even though they are not currently
	2508	* making forward progress in mixing.
	2509	*
	2510	* \param channel channel
	2511	* \returns non-zero if channel is playing, zero otherwise. If `channel` is
	2512	* -1, return the total number of channel playings.
	2513	*
	2514	* \since This function is available since SDL_mixer 2.0.0.
	2515	*/
692	2516	extern DECLSPEC int SDLCALL Mix_Playing(int channel);
	2517
	2518	/**
	2519	* Check the playing status of the music stream.
	2520	*
	2521	* If music is currently playing, this function returns 1. Otherwise it
	2522	* returns 0.
	2523	*
	2524	* Paused music is treated as playing, even though it is not currently making
	2525	* forward progress in mixing.
	2526	*
	2527	* \returns non-zero if music is playing, zero otherwise.
	2528	*
	2529	* \since This function is available since SDL_mixer 2.0.0.
	2530	*/
693	2531	extern DECLSPEC int SDLCALL Mix_PlayingMusic(void);
694	2532
695		/* Stop music and set external music playback command */
	2533	/**
	2534	* Run an external command as the music stream.
	2535	*
	2536	* This halts any currently-playing music, and next time the music stream is
	2537	* played, SDL_mixer will spawn a process using the command line specified in
	2538	* `command`. This command is not subject to shell expansion, and beyond some
	2539	* basic splitting up of arguments, is passed to execvp() on most platforms,
	2540	* not system().
	2541	*
	2542	* The command is responsible for generating sound; it is NOT mixed by
	2543	* SDL_mixer! SDL_mixer will kill the child process if asked to halt the
	2544	* music, but otherwise does not have any control over what the process does.
	2545	*
	2546	* You are strongly encouraged not to use this function without an extremely
	2547	* good reason.
	2548	*
	2549	* \param command command
	2550	* \returns 0 if successful, -1 on error
	2551	*
	2552	* \since This function is available since SDL_mixer 2.0.0.
	2553	*/
696	2554	extern DECLSPEC int SDLCALL Mix_SetMusicCMD(const char *command);
697	2555
698		/* Synchro value is set from modules while playing */
	2556	/**
	2557	* This function does nothing, do not use.
	2558	*
	2559	* This was probably meant to expose a feature, but no codecs support it, so
	2560	* it only remains for binary compatibility.
	2561	*
	2562	* Calling this function is a legal no-op that returns -1.
	2563	*
	2564	* \param value this parameter is ignored.
	2565	* \returns -1.
	2566	*
	2567	* \since This function is available since SDL_mixer 2.0.0.
	2568	*/
699	2569	extern DECLSPEC int SDLCALL Mix_SetSynchroValue(int value);
	2570
	2571	/**
	2572	* This function does nothing, do not use.
	2573	*
	2574	* This was probably meant to expose a feature, but no codecs support it, so
	2575	* it only remains for binary compatibility.
	2576	*
	2577	* Calling this function is a legal no-op that returns -1.
	2578	*
	2579	* \returns -1.
	2580	*
	2581	* \since This function is available since SDL_mixer 2.0.0.
	2582	*/
700	2583	extern DECLSPEC int SDLCALL Mix_GetSynchroValue(void);
701	2584
702		/* Set/Get/Iterate SoundFonts paths to use by supported MIDI backends */
	2585	/**
	2586	* Set SoundFonts paths to use by supported MIDI backends.
	2587	*
	2588	* You may specify multiple paths in a single string by separating them with
	2589	* semicolons; they will be searched in the order listed.
	2590	*
	2591	* This function replaces any previously-specified paths.
	2592	*
	2593	* Passing a NULL path will remove any previously-specified paths.
	2594	*
	2595	* Note that unlike most SDL and SDL_mixer functions, this function returns
	2596	* zero if there's an error, not on success. We apologize for the API design
	2597	* inconsistency here.
	2598	*
	2599	* \param paths Paths on the filesystem where SoundFonts are available,
	2600	* separated by semicolons.
	2601	* \returns 1 if successful, 0 on error (out of memory).
	2602	*
	2603	* \since This function is available since SDL_mixer 2.0.0.
	2604	*/
703	2605	extern DECLSPEC int SDLCALL Mix_SetSoundFonts(const char *paths);
	2606
	2607	/**
	2608	* Get SoundFonts paths to use by supported MIDI backends.
	2609	*
	2610	* There are several factors that determine what will be reported by this
	2611	* function:
	2612	*
	2613	* - If the boolean _SDL hint_ `"SDL_FORCE_SOUNDFONTS"` is set, AND the
	2614	* `"SDL_SOUNDFONTS"` _environment variable_ is also set, this function will
	2615	* return that environment variable regardless of whether
	2616	* Mix_SetSoundFounts() was ever called.
	2617	* - Otherwise, if Mix_SetSoundFonts() was successfully called with a non-NULL
	2618	* path, this function will return the string passed to that function.
	2619	* - Otherwise, if the `"SDL_SOUNDFONTS"` variable is set, this function will
	2620	* return that environment variable.
	2621	* - Otherwise, this function will search some common locations on the
	2622	* filesystem, and if it finds a SoundFont there, it will return that.
	2623	* - Failing everything else, this function returns NULL.
	2624	*
	2625	* This returns a pointer to internal (possibly read-only) memory, and it
	2626	* should not be modified or free'd by the caller.
	2627	*
	2628	* \returns semicolon-separated list of sound font paths.
	2629	*
	2630	* \since This function is available since SDL_mixer 2.0.0.
	2631	*/
704	2632	extern DECLSPEC const char* SDLCALL Mix_GetSoundFonts(void);
	2633
	2634	/**
	2635	* Iterate SoundFonts paths to use by supported MIDI backends.
	2636	*
	2637	* This function will take the string reported by Mix_GetSoundFonts(), split
	2638	* it up into separate paths, as delimited by semicolons in the string, and
	2639	* call a callback function for each separate path.
	2640	*
	2641	* If there are no paths available, this returns 0 without calling the
	2642	* callback at all.
	2643	*
	2644	* If the callback returns non-zero, this function stops iterating and returns
	2645	* non-zero. If the callback returns 0, this function will continue iterating,
	2646	* calling the callback again for further paths. If the callback never returns
	2647	* 1, this function returns 0, so this can be used to decide if an available
	2648	* soundfont is acceptable for use.
	2649	*
	2650	* \param function the callback function to call once per path.
	2651	* \param data a pointer to pass to the callback for its own personal use.
	2652	* \returns non-zero if callback ever returned non-zero, 0 on error or the
	2653	* callback never returned non-zero.
	2654	*
	2655	* \since This function is available since SDL_mixer 2.0.0.
	2656	*
	2657	* \sa Mix_GetSoundFonts
	2658	*/
705	2659	extern DECLSPEC int SDLCALL Mix_EachSoundFont(int (SDLCALL function)(const char, void), void data);
706	2660
707		/* Set/Get full path of Timidity config file (e.g. /etc/timidity.cfg) */
	2661	/**
	2662	* Set full path of the Timidity config file.
	2663	*
	2664	* For example, "/etc/timidity.cfg"
	2665	*
	2666	* This is obviously only useful if SDL_mixer is using Timidity internally to
	2667	* play MIDI files.
	2668	*
	2669	* \param path path to a Timidity config file.
	2670	* \returns 1 if successful, 0 on error
	2671	*
	2672	* \since This function is available since SDL_mixer 2.6.0.
	2673	*/
708	2674	extern DECLSPEC int SDLCALL Mix_SetTimidityCfg(const char *path);
	2675
	2676	/**
	2677	* Get full path of a previously-specified Timidity config file.
	2678	*
	2679	* For example, "/etc/timidity.cfg"
	2680	*
	2681	* If a path has never been specified, this returns NULL.
	2682	*
	2683	* This returns a pointer to internal memory, and it should not be modified or
	2684	* free'd by the caller.
	2685	*
	2686	* \returns the previously-specified path, or NULL if not set.
	2687	*
	2688	* \since This function is available since SDL_mixer 2.6.0.
	2689	*
	2690	* \sa Mix_SetTimidityCfg
	2691	*/
709	2692	extern DECLSPEC const char* SDLCALL Mix_GetTimidityCfg(void);
710	2693
711		/* Get the Mix_Chunk currently associated with a mixer channel
712		Returns NULL if it's an invalid channel, or there's no chunk associated.
713		*/
	2694	/**
	2695	* Get the Mix_Chunk currently associated with a mixer channel.
	2696	*
	2697	* You may not specify MAX_CHANNEL_POST or -1 for a channel.
	2698	*
	2699	* \param channel the channel to query.
	2700	* \returns the associated chunk, if any, or NULL if it's an invalid channel.
	2701	*
	2702	* \since This function is available since SDL_mixer 2.0.0.
	2703	*/
714	2704	extern DECLSPEC Mix_Chunk * SDLCALL Mix_GetChunk(int channel);
715	2705
716		/* Close the mixer, halting all playing audio */
	2706	/**
	2707	* Close the mixer, halting all playing audio.
	2708	*
	2709	* Any halted channels will have any currently-registered effects
	2710	* deregistered, and will call any callback specified by Mix_ChannelFinished()
	2711	* before this function returns.
	2712	*
	2713	* Any halted music will call any callback specified by
	2714	* Mix_HookMusicFinished() before this function returns.
	2715	*
	2716	* Do not start any new audio playing during callbacks in this function.
	2717	*
	2718	* This will close the audio device. Attempting to play new audio after this
	2719	* function returns will fail, until another successful call to
	2720	* Mix_OpenAudio() or Mix_OpenAudioDevice().
	2721	*
	2722	* Note that (unlike Mix_OpenAudio optionally calling SDL_Init(SDL_INIT_AUDIO)
	2723	* on the app's behalf), this will _not_ deinitialize the SDL audio subsystem
	2724	* in any case. At some point after calling this function and Mix_Quit(), some
	2725	* part of the application should be responsible for calling SDL_Quit() to
	2726	* deinitialize all of SDL, including its audio subsystem.
	2727	*
	2728	* This function should be the last thing you call in SDL_mixer before
	2729	* Mix_Quit(). However, the following notes apply if you don't follow this
	2730	* advice:
	2731	*
	2732	* Note that this will not free any loaded chunks or music; you should dispose
	2733	* of those resources separately. It is probably poor form to dispose of them
	2734	* _after_ this function, but it is safe to call Mix_FreeChunk() and
	2735	* Mix_FreeMusic() after closing the device.
	2736	*
	2737	* Note that any chunks or music you don't free may or may not work if you
	2738	* call Mix_OpenAudio again, as the audio device may be in a new format and
	2739	* the existing chunks will not be converted to match.
	2740	*
	2741	* \since This function is available since SDL_mixer 2.0.0.
	2742	*
	2743	* \sa Mix_Quit
	2744	*/
717	2745	extern DECLSPEC void SDLCALL Mix_CloseAudio(void);
718	2746
719	2747	/* We'll use SDL for reporting errors */
	2748
	2749	/**
	2750	* Report SDL_mixer errors
	2751	*
	2752	* \sa Mix_GetError
	2753	*/
720	2754	#define Mix_SetError SDL_SetError
	2755
	2756	/**
	2757	* Get last SDL_mixer error
	2758	*
	2759	* \sa Mix_SetError
	2760	*/
721	2761	#define Mix_GetError SDL_GetError
	2762
	2763	/**
	2764	* Clear last SDL_mixer error
	2765	*
	2766	* \sa Mix_SetError
	2767	*/
722	2768	#define Mix_ClearError SDL_ClearError
	2769
	2770	/**
	2771	* Set OutOfMemory error
	2772	*/
723	2773	#define Mix_OutOfMemory SDL_OutOfMemory
724	2774
725	2775	/* Ends C function definitions when using C++ */

-1

sdl2_mixer-config.cmake.in less more

70	70	set(bindir "@bindir@")
71	71	set(includedir "@includedir@")
72	72	set(libdir "@libdir@")
73		set(_sdl2mixer_extra_static_libraries "@PC_LIBS@")
	73	set(_sdl2mixer_extra_static_libraries "@MIXER_LIBS@ @PC_LIBS@")
74	74	string(STRIP "${_sdl2mixer_extra_static_libraries}" _sdl2mixer_extra_static_libraries)
75	75
76	76	set(_sdl2mixer_bindir "${bindir}")

+23

-1

src/mixer.c less more

845	845	return(chunk);
846	846	}
847	847
	848	Mix_Chunk Mix_LoadWAV(const char file)
	849	{
	850	return Mix_LoadWAV_RW(SDL_RWFromFile(file, "rb"), 1);
	851	}
	852
	853
848	854	/* Load a wave file of the mixer format from a memory buffer */
849	855	Mix_Chunk Mix_QuickLoad_WAV(Uint8 mem)
850	856	{

1070	1076	return(which);
1071	1077	}
1072	1078
	1079	int Mix_PlayChannel(int channel, Mix_Chunk *chunk, int loops)
	1080	{
	1081	return Mix_PlayChannelTimed(channel, chunk, loops, -1);
	1082	}
	1083
1073	1084	/* Change the expiration delay for a channel */
1074	1085	int Mix_ExpireChannel(int which, int ticks)
1075	1086	{

1147	1158	return(which);
1148	1159	}
1149	1160
	1161	int Mix_FadeInChannel(int channel, Mix_Chunk *chunk, int loops, int ms)
	1162	{
	1163	return Mix_FadeInChannelTimed(channel, chunk, loops, ms, -1);
	1164	}
	1165
	1166
1150	1167	/* Set volume of a particular channel */
1151	1168	int Mix_Volume(int which, int volume)
1152	1169	{

1445	1462	{
1446	1463	int count = 0;
1447	1464	int i;
	1465
	1466	if (tag == -1) {
	1467	return num_channels; /* minor optimization; no need to go through the loop. */
	1468	}
	1469
1448	1470	for(i=0; i < num_channels; i ++) {
1449		if (mix_channel[i].tag==tag \|\| tag==-1)
	1471	if (mix_channel[i].tag == tag)
1450	1472	++ count;
1451	1473	}
1452	1474	return(count);

-4

version.rc less more

8	8	//
9	9
10	10	VS_VERSION_INFO VERSIONINFO
11		FILEVERSION 2,5,2,0
12		PRODUCTVERSION 2,5,2,0
	11	FILEVERSION 2,5,3,0
	12	PRODUCTVERSION 2,5,3,0
13	13	FILEFLAGSMASK 0x3fL
14	14	FILEFLAGS 0x0L
15	15	FILEOS 0x40004L

22	22	BEGIN
23	23	VALUE "CompanyName", "\0"
24	24	VALUE "FileDescription", "SDL_mixer\0"
25		VALUE "FileVersion", "2, 5, 2, 0\0"
	25	VALUE "FileVersion", "2, 5, 3, 0\0"
26	26	VALUE "InternalName", "SDL_mixer\0"
27	27	VALUE "LegalCopyright", "Copyright © 2022 Sam Lantinga\0"
28	28	VALUE "OriginalFilename", "SDL_mixer.dll\0"
29	29	VALUE "ProductName", "Simple DirectMedia Layer\0"
30		VALUE "ProductVersion", "2, 5, 2, 0\0"
	30	VALUE "ProductVersion", "2, 5, 3, 0\0"
31	31	END
32	32	END
33	33	BLOCK "VarFileInfo"