From 7b4d06b03a367f50b1ea8756183db68fbfe7251a Mon Sep 17 00:00:00 2001
From: SDL Wiki Bot <[EMAIL REDACTED]>
Date: Fri, 1 Jul 2022 16:46:11 +0000
Subject: [PATCH] Sync SDL_mixer wiki -> header
---
include/SDL_mixer.h | 851 ++++++++++++++++++++++----------------------
1 file changed, 426 insertions(+), 425 deletions(-)
diff --git a/include/SDL_mixer.h b/include/SDL_mixer.h
index 795befe0..2ae73e3d 100644
--- a/include/SDL_mixer.h
+++ b/include/SDL_mixer.h
@@ -706,18 +706,18 @@ extern DECLSPEC Mix_Music * SDLCALL Mix_LoadMUSType_RW(SDL_RWops *src, Mix_Music
/**
* Load a WAV file from memory as quickly as possible.
*
- * Unlike Mix_LoadWAV_RW, this function has several requirements, and
- * unless you control all your audio data and know what you're doing, you
- * should consider this function unsafe and not use it.
+ * Unlike Mix_LoadWAV_RW, this function has several requirements, and unless
+ * you control all your audio data and know what you're doing, you should
+ * consider this function unsafe and not use it.
*
* - The provided audio data MUST be in Microsoft WAV format.
* - The provided audio data shouldn't use any strange WAV extensions.
- * - The audio data MUST be in the exact same format as the audio device.
- * This function will not attempt to convert it, or even verify it's
- * in the right format.
- * - The audio data must be valid; this function does not know the size of
- * the memory buffer, so if the WAV data is corrupted, it can read past
- * the end of the buffer, causing a crash.
+ * - The audio data MUST be in the exact same format as the audio device. This
+ * function will not attempt to convert it, or even verify it's in the right
+ * format.
+ * - The audio data must be valid; this function does not know the size of the
+ * memory buffer, so if the WAV data is corrupted, it can read past the end
+ * of the buffer, causing a crash.
* - The audio data must live at least as long as the returned Mix_Chunk,
* because SDL_mixer will use that data directly and not make a copy of it.
*
@@ -741,9 +741,9 @@ extern DECLSPEC Mix_Chunk * SDLCALL Mix_QuickLoad_WAV(Uint8 *mem);
/**
* Load a raw audio data from memory as quickly as possible.
*
- * The audio data MUST be in the exact same format as the audio device.
- * This function will not attempt to convert it, or even verify it's
- * in the right format.
+ * The audio data MUST be in the exact same format as the audio device. This
+ * function will not attempt to convert it, or even verify it's in the right
+ * format.
*
* If this function is successful, the provided memory buffer must remain
* available until Mix_FreeChunk() is called on the returned chunk.
@@ -761,8 +761,8 @@ extern DECLSPEC Mix_Chunk * SDLCALL Mix_QuickLoad_RAW(Uint8 *mem, Uint32 len);
/**
* Free an audio chunk.
*
- * An app should call this function when it is done with a Mix_Chunk
- * and wants to dispose of its resources.
+ * An app should call this function when it is done with a Mix_Chunk and wants
+ * to dispose of its resources.
*
* SDL_mixer will stop any channels this chunk is currently playing on. This
* will deregister all effects on those channels and call any callback
@@ -785,9 +785,8 @@ extern DECLSPEC void SDLCALL Mix_FreeChunk(Mix_Chunk *chunk);
* If this music is currently playing, it will be stopped.
*
* If this music is in the process of fading out (via Mix_FadeOutMusic()),
- * this function will *block* until the fade completes. If you need
- * to avoid this, be sure to call Mix_HaltMusic() before freeing
- * the music.
+ * this function will *block* until the fade completes. If you need to avoid
+ * this, be sure to call Mix_HaltMusic() before freeing the music.
*
* \param music the music object to free.
*
@@ -804,12 +803,12 @@ extern DECLSPEC void SDLCALL Mix_FreeMusic(Mix_Music *music);
*
* This list can change between builds AND runs of the program, if external
* libraries that add functionality become available. You must successfully
- * call Mix_OpenAudio() or Mix_OpenAudioDevice() before calling this
- * function, as decoders are activated at device open time.
+ * call Mix_OpenAudio() or Mix_OpenAudioDevice() before calling this function,
+ * as decoders are activated at device open time.
*
* Appearing in this list doesn't promise your specific audio file will
- * decode...but it's handy to know if you have, say, a functioning
- * Ogg Vorbis install.
+ * decode...but it's handy to know if you have, say, a functioning Ogg Vorbis
+ * install.
*
* These return values are static, read-only data; do not modify or free it.
* The pointers remain valid until you call Mix_CloseAudio().
@@ -827,13 +826,13 @@ extern DECLSPEC int SDLCALL Mix_GetNumChunkDecoders(void);
* Get a chunk decoder's name.
*
* The requested decoder's index must be between zero and
- * Mix_GetNumChunkDecoders()-1. It's safe to call this with an
- * invalid index; this function will return NULL in that case.
+ * Mix_GetNumChunkDecoders()-1. It's safe to call this with an invalid index;
+ * this function will return NULL in that case.
*
* This list can change between builds AND runs of the program, if external
* libraries that add functionality become available. You must successfully
- * call Mix_OpenAudio() or Mix_OpenAudioDevice() before calling this
- * function, as decoders are activated at device open time.
+ * call Mix_OpenAudio() or Mix_OpenAudioDevice() before calling this function,
+ * as decoders are activated at device open time.
*
* \param index index of the chunk decoder.
* \returns the chunk decoder's name.
@@ -849,15 +848,16 @@ extern DECLSPEC const char * SDLCALL Mix_GetChunkDecoder(int index);
*
* This result can change between builds AND runs of the program, if external
* libraries that add functionality become available. You must successfully
- * call Mix_OpenAudio() or Mix_OpenAudioDevice() before calling this
- * function, as decoders are activated at device open time.
+ * call Mix_OpenAudio() or Mix_OpenAudioDevice() before calling this function,
+ * as decoders are activated at device open time.
*
* Decoder names are arbitrary but also obvious, so you have to know what
* you're looking for ahead of time, but usually it's the file extension in
* capital letters (some example names are "AIFF", "VOC", "WAV").
*
* \param name the decoder name to query.
- * \returns SDL_TRUE if a decoder by that name is available, SDL_FALSE otherwise.
+ * \returns SDL_TRUE if a decoder by that name is available, SDL_FALSE
+ * otherwise.
*
* \since This function is available since SDL_mixer 2.0.2.
*
@@ -871,12 +871,12 @@ extern DECLSPEC SDL_bool SDLCALL Mix_HasChunkDecoder(const char *name);
*
* This list can change between builds AND runs of the program, if external
* libraries that add functionality become available. You must successfully
- * call Mix_OpenAudio() or Mix_OpenAudioDevice() before calling this
- * function, as decoders are activated at device open time.
+ * call Mix_OpenAudio() or Mix_OpenAudioDevice() before calling this function,
+ * as decoders are activated at device open time.
*
* Appearing in this list doesn't promise your specific audio file will
- * decode...but it's handy to know if you have, say, a functioning
- * Ogg Vorbis install.
+ * decode...but it's handy to know if you have, say, a functioning Ogg Vorbis
+ * install.
*
* These return values are static, read-only data; do not modify or free it.
* The pointers remain valid until you call Mix_CloseAudio().
@@ -894,13 +894,13 @@ extern DECLSPEC int SDLCALL Mix_GetNumMusicDecoders(void);
* Get a music decoder's name.
*
* The requested decoder's index must be between zero and
- * Mix_GetNumMusicDecoders()-1. It's safe to call this with an
- * invalid index; this function will return NULL in that case.
+ * Mix_GetNumMusicDecoders()-1. It's safe to call this with an invalid index;
+ * this function will return NULL in that case.
*
* This list can change between builds AND runs of the program, if external
* libraries that add functionality become available. You must successfully
- * call Mix_OpenAudio() or Mix_OpenAudioDevice() before calling this
- * function, as decoders are activated at device open time.
+ * call Mix_OpenAudio() or Mix_OpenAudioDevice() before calling this function,
+ * as decoders are activated at device open time.
*
* \param index index of the music decoder.
* \returns the music decoder's name.
@@ -916,15 +916,16 @@ extern DECLSPEC const char * SDLCALL Mix_GetMusicDecoder(int index);
*
* This result can change between builds AND runs of the program, if external
* libraries that add functionality become available. You must successfully
- * call Mix_OpenAudio() or Mix_OpenAudioDevice() before calling this
- * function, as decoders are activated at device open time.
+ * call Mix_OpenAudio() or Mix_OpenAudioDevice() before calling this function,
+ * as decoders are activated at device open time.
*
* Decoder names are arbitrary but also obvious, so you have to know what
* you're looking for ahead of time, but usually it's the file extension in
* capital letters (some example names are "MOD", "MP3", "FLAC").
*
* \param name the decoder name to query.
- * \returns SDL_TRUE if a decoder by that name is available, SDL_FALSE otherwise.
+ * \returns SDL_TRUE if a decoder by that name is available, SDL_FALSE
+ * otherwise.
*
* \since This function is available since SDL_mixer 2.6.0
*
@@ -936,10 +937,11 @@ extern DECLSPEC SDL_bool SDLCALL Mix_HasMusicDecoder(const char *name);
/**
* Find out the format of a mixer music.
*
- * If `music` is NULL, this will query the currently playing music (and
- * return MUS_NONE if nothing is currently playing).
+ * If `music` is NULL, this will query the currently playing music (and return
+ * MUS_NONE if nothing is currently playing).
*
- * \param music the music object to query, or NULL for the currently-playing music.
+ * \param music the music object to query, or NULL for the currently-playing
+ * music.
* \returns the Mix_MusicType for the music object.
*
* \since This function is available since SDL_mixer 2.0.0
@@ -953,17 +955,18 @@ extern DECLSPEC Mix_MusicType SDLCALL Mix_GetMusicType(const Mix_Music *music);
*
* If `music` is NULL, this will query the currently-playing music.
*
- * If music's title tag is missing or empty, the filename will be returned.
- * If you'd rather have the actual metadata or nothing, use
+ * If music's title tag is missing or empty, the filename will be returned. If
+ * you'd rather have the actual metadata or nothing, use
* Mix_GetMusicTitleTag() instead.
*
* Please note that if the music was loaded from an SDL_RWops instead of a
* filename, the filename returned will be an empty string ("").
*
- * This function never returns NULL! If no data is available, it will return an
- * empty string ("").
+ * This function never returns NULL! If no data is available, it will return
+ * an empty string ("").
*
- * \param music the music object to query, or NULL for the currently-playing music.
+ * \param music the music object to query, or NULL for the currently-playing
+ * music.
* \returns the music's title if available, or the filename if not, or "".
*
* \since This function is available since SDL_mixer 2.6.0.
@@ -986,10 +989,11 @@ extern DECLSPEC const char *SDLCALL Mix_GetMusicTitle(const Mix_Music *music);
* filename if a title isn't available, which might be preferable for some
* applications.
*
- * This function never returns NULL! If no data is available, it will return an
- * empty string ("").
+ * This function never returns NULL! If no data is available, it will return
+ * an empty string ("").
*
- * \param music the music object to query, or NULL for the currently-playing music.
+ * \param music the music object to query, or NULL for the currently-playing
+ * music.
* \returns the music's title if available, or "".
*
* \since This function is available since SDL_mixer 2.6.0.
@@ -1008,10 +1012,11 @@ extern DECLSPEC const char *SDLCALL Mix_GetMusicTitleTag(const Mix_Music *music)
*
* If `music` is NULL, this will query the currently-playing music.
*
- * This function never returns NULL! If no data is available, it will return an
- * empty string ("").
+ * This function never returns NULL! If no data is available, it will return
+ * an empty string ("").
*
- * \param music the music object to query, or NULL for the currently-playing music.
+ * \param music the music object to query, or NULL for the currently-playing
+ * music.
* \returns the music's artist name if available, or "".
*
* \since This function is available since SDL_mixer 2.6.0.
@@ -1029,10 +1034,11 @@ extern DECLSPEC const char *SDLCALL Mix_GetMusicArtistTag(const Mix_Music *music
*
* If `music` is NULL, this will query the currently-playing music.
*
- * This function never returns NULL! If no data is available, it will return an
- * empty string ("").
+ * This function never returns NULL! If no data is available, it will return
+ * an empty string ("").
*
- * \param music the music object to query, or NULL for the currently-playing music.
+ * \param music the music object to query, or NULL for the currently-playing
+ * music.
* \returns the music's album name if available, or "".
*
* \since This function is available since SDL_mixer 2.6.0.
@@ -1050,10 +1056,11 @@ extern DECLSPEC const char *SDLCALL Mix_GetMusicAlbumTag(const Mix_Music *music)
*
* If `music` is NULL, this will query the currently-playing music.
*
- * This function never returns NULL! If no data is available, it will return an
- * empty string ("").
+ * This function never returns NULL! If no data is available, it will return
+ * an empty string ("").
*
- * \param music the music object to query, or NULL for the currently-playing music.
+ * \param music the music object to query, or NULL for the currently-playing
+ * music.
* \returns the music's copyright text if available, or "".
*
* \since This function is available since SDL_mixer 2.6.0.
@@ -1070,25 +1077,25 @@ extern DECLSPEC const char *SDLCALL Mix_GetMusicCopyrightTag(const Mix_Music *mu
* This can be used to provide real-time visual display of the audio stream or
* add a custom mixer filter for the stream data.
*
- * The callback will fire every time SDL_mixer is ready to supply more data
- * to the audio device, after it has finished all its mixing work. This runs
+ * The callback will fire every time SDL_mixer is ready to supply more data to
+ * the audio device, after it has finished all its mixing work. This runs
* inside an SDL audio callback, so it's important that the callback return
* quickly, or there could be problems in the audio playback.
*
* The data provided to the callback is in the format that the audio device
* was opened in, and it represents the exact waveform SDL_mixer has mixed
- * from all playing chunks and music for playback. You are allowed to
- * modify the data, but it cannot be resized (so you can't add a reverb
- * effect that goes past the end of the buffer without saving some state
- * between runs to add it into the next callback, or resample the buffer
- * to a smaller size to speed it up, etc).
+ * from all playing chunks and music for playback. You are allowed to modify
+ * the data, but it cannot be resized (so you can't add a reverb effect that
+ * goes past the end of the buffer without saving some state between runs to
+ * add it into the next callback, or resample the buffer to a smaller size to
+ * speed it up, etc).
*
* The `arg` pointer supplied here is passed to the callback as-is, for
- * whatever the callback might want to do with it (keep track of some
- * ongoing state, settings, etc).
+ * whatever the callback might want to do with it (keep track of some ongoing
+ * state, settings, etc).
*
- * Passing a NULL callback disables the post-mix callback until such a time
- * as a new one callback is set.
+ * Passing a NULL callback disables the post-mix callback until such a time as
+ * a new one callback is set.
*
* There is only one callback available. If you need to mix multiple inputs,
* be prepared to handle them from a single function.
@@ -1106,39 +1113,38 @@ extern DECLSPEC void SDLCALL Mix_SetPostMix(void (SDLCALL *mix_func)(void *udata
* Add your own music player or additional mixer function.
*
* This works something like Mix_SetPostMix(), but it has some crucial
- * differences. Note that an app can use this _and_ Mix_SetPostMix() at
- * the same time. This allows an app to replace the built-in music
- * playback, either with it's own music decoder or with some sort of
+ * differences. Note that an app can use this _and_ Mix_SetPostMix() at the
+ * same time. This allows an app to replace the built-in music playback,
+ * either with it's own music decoder or with some sort of
* procedurally-generated audio output.
*
- * The supplied callback will fire every time SDL_mixer is preparing to
- * supply more data to the audio device. This runs inside an SDL audio
- * callback, so it's important that the callback return quickly, or there
- * could be problems in the audio playback.
+ * The supplied callback will fire every time SDL_mixer is preparing to supply
+ * more data to the audio device. This runs inside an SDL audio callback, so
+ * it's important that the callback return quickly, or there could be problems
+ * in the audio playback.
*
- * Running this callback is the first thing SDL_mixer will do when
- * starting to mix more audio. The buffer will contain silence upon
- * entry, so the callback does not need to mix into existing data or
- * initialize the buffer.
+ * Running this callback is the first thing SDL_mixer will do when starting to
+ * mix more audio. The buffer will contain silence upon entry, so the callback
+ * does not need to mix into existing data or initialize the buffer.
*
- * Note that while a callback is set through this function, SDL_mixer
- * will not mix any playing music; this callback is used instead. To
- * disable this callback (and thus reenable built-in music playback)
- * call this function with a NULL callback.
+ * Note that while a callback is set through this function, SDL_mixer will not
+ * mix any playing music; this callback is used instead. To disable this
+ * callback (and thus reenable built-in music playback) call this function
+ * with a NULL callback.
*
- * The data written to by the callback is in the format that the audio
- * device was opened in, and upon return from the callback, SDL_mixer
- * will mix any playing chunks (but not music!) into the buffer. The
- * callback cannot resize the buffer (so you must be prepared to provide
- * exactly the amount of data demanded or leave it as silence).
+ * The data written to by the callback is in the format that the audio device
+ * was opened in, and upon return from the callback, SDL_mixer will mix any
+ * playing chunks (but not music!) into the buffer. The callback cannot resize
+ * the buffer (so you must be prepared to provide exactly the amount of data
+ * demanded or leave it as silence).
*
* The `arg` pointer supplied here is passed to the callback as-is, for
- * whatever the callback might want to do with it (keep track of some
- * ongoing state, settings, etc).
+ * whatever the callback might want to do with it (keep track of some ongoing
+ * state, settings, etc).
*
- * As there is only one music "channel" mixed, there is only one
- * callback available. If you need to mix multiple inputs,
- * be prepared to handle them from a single function.
+ * As there is only one music "channel" mixed, there is only one callback
+ * available. If you need to mix multiple inputs, be prepared to handle them
+ * from a single function.
*
* \param mix_func the callback function to become the new post-mix callback.
* \param arg a pointer that is passed, untouched, to the callback.
@@ -1152,10 +1158,10 @@ extern DECLSPEC void SDLCALL Mix_HookMusic(void (SDLCALL *mix_func)(void *udata,
/**
* Set a callback that runs when a music object has stopped playing.
*
- * This callback will fire when the currently-playing music has completed,
- * or when it has been explicitly stopped from a call to Mix_HaltMusic. As
- * such, this callback might fire from an arbitrary background thread at
- * almost any time; try to limit what you do here.
+ * This callback will fire when the currently-playing music has completed, or
+ * when it has been explicitly stopped from a call to Mix_HaltMusic. As such,
+ * this callback might fire from an arbitrary background thread at almost any
+ * time; try to limit what you do here.
*
* It is legal to start a new music object playing in this callback (or
* restart the one that just stopped). If the music finished normally, this
@@ -1167,7 +1173,8 @@ extern DECLSPEC void SDLCALL Mix_HookMusic(void (SDLCALL *mix_func)(void *udata,
*
* A NULL pointer will disable the callback.
*
- * \param music_finished the callback function to become the new notification mechanism.
+ * \param music_finished the callback function to become the new notification
+ * mechanism.
*
* \since This function is available since SDL_mixer 2.0.0.
*/
@@ -1176,8 +1183,8 @@ extern DECLSPEC void SDLCALL Mix_HookMusicFinished(void (SDLCALL *music_finished
/**
* Get a pointer to the user data for the current music hook.
*
- * This returns the `arg` pointer last passed to Mix_HookMusic(), or
- * NULL if that function has never been called.
+ * This returns the `arg` pointer last passed to Mix_HookMusic(), or NULL if
+ * that function has never been called.
*
* \returns pointer to the user data previously passed to Mix_HookMusic.
*
@@ -1191,8 +1198,8 @@ extern DECLSPEC void * SDLCALL Mix_GetMusicHookData(void);
* The callback may be called from the mixer's audio callback or it could be
* called as a result of Mix_HaltChannel(), etc.
*
- * The callback has a single parameter, `channel`, which says what
- * mixer channel has just stopped.
+ * The callback has a single parameter, `channel`, which says what mixer
+ * channel has just stopped.
*
* Do not call SDL_LockAudio() from this callback; you will either be inside
* the audio callback, or SDL_mixer will explicitly lock the audio before
@@ -1200,7 +1207,8 @@ extern DECLSPEC void * SDLCALL Mix_GetMusicHookData(void);
*
* A NULL pointer will disable the callback.
*
- * \param channel_finished the callback function to become the new notification mechanism.
+ * \param channel_finished the callback function to become the new
+ * notification mechanism.
*
* \since This function is available since SDL_mixer 2.0.0.
*/
@@ -1288,15 +1296,16 @@ typedef void (SDLCALL *Mix_EffectDone_t)(int chan, void *udata);
* through Mix_SetPostMix() runs, and then the stream goes to the audio
* device.
*
- * DO NOT EVER call SDL_LockAudio() from your callback function! You are already
- * running in the audio thread and the lock is already held!
+ * DO NOT EVER call SDL_LockAudio() from your callback function! You are
+ * already running in the audio thread and the lock is already held!
*
* Note that unlike most SDL and SDL_mixer functions, this function returns
* zero if there's an error, not on success. We apologize for the API design
* inconsistency here.
*
* \param chan the channel to register an effect to, or MIX_CHANNEL_POST.
- * \param f effect the callback to run when more of this channel is to be mixed.
+ * \param f effect the callback to run when more of this channel is to be
+ * mixed.
* \param d effect done callback
* \param arg argument
* \returns zero if error (no such channel), nonzero if added. Error messages
@@ -1313,8 +1322,8 @@ extern DECLSPEC int SDLCALL Mix_RegisterEffect(int chan, Mix_EffectFunc_t f, Mix
* You may not need to call this at all, unless you need to stop an effect
* from processing in the middle of a chunk's playback.
*
- * Posteffects are never implicitly unregistered as they are for channels
- * (as the output stream does not have an end), but they may be explicitly
+ * Posteffects are never implicitly unregistered as they are for channels (as
+ * the output stream does not have an end), but they may be explicitly
* unregistered through this function by specifying MIX_CHANNEL_POST for a
* channel.
*
@@ -1519,8 +1528,8 @@ extern DECLSPEC int SDLCALL Mix_SetDistance(int channel, Uint8 distance);
* correctly. Mix_SetReverseStereo() returns without registering the effect
* function if the audio device is not configured for stereo output.
*
- * If you specify MIX_CHANNEL_POST for `channel`, then this effect is used
- * on the final mixed stream before sending it on to the audio device (a
+ * If you specify MIX_CHANNEL_POST for `channel`, then this effect is used on
+ * the final mixed stream before sending it on to the audio device (a
* posteffect).
*
* Note that unlike most SDL and SDL_mixer functions, this function returns
@@ -1546,18 +1555,17 @@ extern DECLSPEC int SDLCALL Mix_SetReverseStereo(int channel, int flip);
* Reserve the first channels for the application.
*
* While SDL_mixer will use up to the number of channels allocated by
- * Mix_AllocateChannels(), this sets channels aside that will not be
- * available when calling Mix_PlayChannel with a channel of -1 (play
- * on the first unused channel). In this case, SDL_mixer will treat
- * reserved channels as "used" whether anything is playing on them
- * at the moment or not.
+ * Mix_AllocateChannels(), this sets channels aside that will not be available
+ * when calling Mix_PlayChannel with a channel of -1 (play on the first unused
+ * channel). In this case, SDL_mixer will treat reserved channels as "used"
+ * whether anything is playing on them at the moment or not.
*
- * This is useful if you've budgeted some channels for dedicated
- * audio and the rest are just used as they are available.
+ * This is useful if you've budgeted some channels for dedicated audio and the
+ * rest are just used as they are available.
*
- * Calling this function will set channels 0 to `n - 1` to be reserved.
- * This will not change channel allocations. The number of reserved
- * channels will be clamped to the current number allocated.
+ * Calling this function will set channels 0 to `n - 1` to be reserved. This
+ * will not change channel allocations. The number of reserved channels will
+ * be clamped to the current number allocated.
*
* By default, no channels are reserved.
*
@@ -1574,20 +1582,19 @@ extern DECLSPEC int SDLCALL Mix_ReserveChannels(int num);
/**
* Assign a tag to a channel.
*
- * A tag is an arbitary number that can be assigned to several mixer
- * channels, to form groups of channels.
+ * A tag is an arbitary number that can be assigned to several mixer channels,
+ * to form groups of channels.
*
* If 'tag' is -1, the tag is removed (actually -1 is the tag used to
* represent the group of all the channels).
*
- * This function replaces the requested channel's current tag; you
- * may only have one tag per channel.
+ * This function replaces the requested channel's current tag; you may only
+ * have one tag per channel.
*
* You may not specify MAX_CHANNEL_POST for a channel.
*
* \param which the channel to set the tag on.
* \param tag an arbitrary value to assign a channel.
- *
* \returns non-zero on success, zero on error (no such channel).
*
* \since This function is available since SDL_mixer 2.0.0.
@@ -1597,19 +1604,19 @@ extern DECLSPEC int SDLCALL Mix_GroupChannel(int which, int tag);
/**
* Assign several consecutive channels to the same tag.
*
- * A tag is an arbitary number that can be assigned to several mixer
- * channels, to form groups of channels.
+ * A tag is an arbitary number that can be assigned to several mixer channels,
+ * to form groups of channels.
*
* If 'tag' is -1, the tag is removed (actually -1 is the tag used to
* represent the group of all the channels).
*
- * This function replaces the requested channels' current tags; you
- * may only have one tag per channel.
+ * This function replaces the requested channels' current tags; you may only
+ * have one tag per channel.
*
* You may not specify MAX_CHANNEL_POST for a channel.
*
- * Note that this returns success and failure in the _opposite_ way
- * from Mix_GroupChannel(). We regret the API design mistake.
+ * Note that this returns success and failure in the _opposite_ way from
+ * Mix_GroupChannel(). We regret the API design mistake.
*
* \param from the first channel to set the tag on.
* \param to the last channel to set the tag on, inclusive.
@@ -1623,15 +1630,13 @@ extern DECLSPEC int SDLCALL Mix_GroupChannels(int from, int to, int tag);
/**
* Finds the first available channel in a group of channels.
*
- * A tag is an arbitary number that can be assigned to several mixer
- * channels, to form groups of channels.
+ * A tag is an arbitary number that can be assigned to several mixer channels,
+ * to form groups of channels.
*
- * This function searches all channels with a specified tag, and
- * returns the channel number of the first one it finds that is
- * currently unused.
+ * This function searches all channels with a specified tag, and returns the
+ * channel number of the first one it finds that is currently unused.
*
- * If no channels with the specified tag are unused, this function
- * returns -1.
+ * If no channels with the specified tag are unused, this function returns -1.
*
* \param tag an arbitrary value, assigned to channels, to search for.
* \returns first available channel, or -1 if none are available.
@@ -1643,8 +1648,8 @@ extern DECLSPEC int SDLCALL Mix_GroupAvailable(int tag);
/**
* Returns the number of channels in a group.
*
- * If tag is -1, this will return the total number of
- * channels allocated, regardless of what their tag might be.
+ * If tag is -1, this will return the total number of channels allocated,
+ * regardless of what their tag might be.
*
* \param tag an arbitrary value, assigned to channels, to search for.
* \returns the number of channels assigned the specified tag.
@@ -1656,13 +1661,11 @@ extern DECLSPEC int SDLCALL Mix_GroupCount(int tag);
/**
* Find the "oldest" sample playing in a group of channels.
*
- * Specifically, this function returns the channel number that
- * is assigned the specified tag, is currently playing, and
- * has the lowest start time, based on the value of SDL_GetTicks()
- * when the channel started playing.
+ * Specifically, this function returns the channel number that is assigned the
+ * specified tag, is currently playing, and has the lowest start time, based
+ * on the value of SDL_GetTicks() when the channel started playing.
*
- * If no channel with this tag is currently playing, this function
- * returns -1.
+ * If no channel with this tag is currently playing, this function returns -1.
*
* \param tag an arbitrary value, assigned to channels, to search through.
* \returns the "oldest" sample playing in a group of channels
@@ -1676,13 +1679,11 @@ extern DECLSPEC int SDLCALL Mix_GroupOldest(int tag);
/**
* Find the "most recent" sample playing in a group of channels.
*
- * Specifically, this function returns the channel number that
- * is assigned the specified tag, is cur
(Patch may be truncated, please check the link at the top of this post.)