From c6767f7099a9633d23f932018ba409618e0f9177 Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Fri, 1 Jul 2022 12:43:55 -0400
Subject: [PATCH] SDL_mixer.h: Rewrote the remaining documentation.
---
include/SDL_mixer.h | 1295 ++++++++++++++++++++++++++++++++++---------
1 file changed, 1039 insertions(+), 256 deletions(-)
diff --git a/include/SDL_mixer.h b/include/SDL_mixer.h
index 2ec65351..795befe0 100644
--- a/include/SDL_mixer.h
+++ b/include/SDL_mixer.h
@@ -704,23 +704,53 @@ extern DECLSPEC Mix_Music * SDLCALL Mix_LoadMUS_RW(SDL_RWops *src, int freesrc);
extern DECLSPEC Mix_Music * SDLCALL Mix_LoadMUSType_RW(SDL_RWops *src, Mix_MusicType type, int freesrc);
/**
- * Load a wave file of the mixer format from a memory buffer
+ * Load a WAV file from memory as quickly as possible.
*
- * \param mem memory buffer
- * \returns Mix Chunk, or NULL on error.
+ * 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 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.
+ *
+ * This function will do NO error checking! Be extremely careful here!
+ *
+ * (Seriously, use Mix_LoadWAV_RW instead.)
+ *
+ * If this function is successful, the provided memory buffer must remain
+ * available until Mix_FreeChunk() is called on the returned chunk.
+ *
+ * \param mem memory buffer containing of a WAV file.
+ * \returns a new chunk, or NULL on error.
*
* \since This function is available since SDL_mixer 2.0.0.
*
+ * \sa Mix_LoadWAV_RW
* \sa Mix_FreeChunk
*/
extern DECLSPEC Mix_Chunk * SDLCALL Mix_QuickLoad_WAV(Uint8 *mem);
/**
- * Load raw audio data of the mixer format from a memory buffer
+ * Load a raw audio data from memory as quickly as possible.
*
- * \param mem memory buffer
- * \param len length
- * \returns Mix Chunk, or NULL on error.
+ * 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.
+ *
+ * \param mem memory buffer containing raw PCM data.
+ * \param len length of buffer pointed to by `mem`, in bytes.
+ * \returns a new chunk, or NULL on error.
*
* \since This function is available since SDL_mixer 2.0.0.
*
@@ -729,13 +759,16 @@ extern DECLSPEC Mix_Chunk * SDLCALL Mix_QuickLoad_WAV(Uint8 *mem);
extern DECLSPEC Mix_Chunk * SDLCALL Mix_QuickLoad_RAW(Uint8 *mem, Uint32 len);
/**
- * Free an audio chunk previously loaded
+ * 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.
*
* SDL_mixer will stop any channels this chunk is currently playing on. This
* will deregister all effects on those channels and call any callback
* specified by Mix_ChannelFinished() for each removed channel.
*
- * \param chunk Mix Chunk
+ * \param chunk the chunk to free.
*
* \since This function is available since SDL_mixer 2.0.0.
*
@@ -747,9 +780,16 @@ extern DECLSPEC Mix_Chunk * SDLCALL Mix_QuickLoad_RAW(Uint8 *mem, Uint32 len);
extern DECLSPEC void SDLCALL Mix_FreeChunk(Mix_Chunk *chunk);
/**
- * Free an audio music previously loaded
+ * Free a music object.
+ *
+ * If this music is currently playing, it will be stopped.
*
- * \param music Mix Music
+ * 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.
+ *
+ * \param music the music object to free.
*
* \since This function is available since SDL_mixer 2.0.0.
*
@@ -760,20 +800,21 @@ extern DECLSPEC void SDLCALL Mix_FreeChunk(Mix_Chunk *chunk);
extern DECLSPEC void SDLCALL Mix_FreeMusic(Mix_Music *music);
/**
- * Get a list of chunk/music decoders that this build of SDL_mixer provides.
+ * Get a list of chunk decoders that this build of SDL_mixer provides.
*
* 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() before calling these functions.
+ * 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 Timidity
- * 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().
*
- * \returns number of chunk decoders
+ * \returns number of chunk decoders available.
*
* \since This function is available since SDL_mixer 2.0.0.
*
@@ -783,10 +824,19 @@ extern DECLSPEC void SDLCALL Mix_FreeMusic(Mix_Music *music);
extern DECLSPEC int SDLCALL Mix_GetNumChunkDecoders(void);
/**
- * Get chunk decoder name
+ * 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.
*
- * \param index index of the chunk decoder
- * \returns chunk decoder 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.
+ *
+ * \param index index of the chunk decoder.
+ * \returns the chunk decoder's name.
*
* \since This function is available since SDL_mixer 2.0.0.
*
@@ -795,19 +845,43 @@ extern DECLSPEC int SDLCALL Mix_GetNumChunkDecoders(void);
extern DECLSPEC const char * SDLCALL Mix_GetChunkDecoder(int index);
/**
- * Check if `name` is a chunk decoder
+ * Check if a chunk decoder is available by name.
+ *
+ * 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.
*
- * \param name name
- * \returns SDL_TRUE or SDL_FALSE
+ * 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.
*
* \since This function is available since SDL_mixer 2.0.2.
+ *
+ * \sa Mix_GetNumChunkDecoders
+ * \sa Mix_GetChunkDecoder
*/
extern DECLSPEC SDL_bool SDLCALL Mix_HasChunkDecoder(const char *name);
/**
- * Get the number of music decoders
+ * Get a list of music decoders that this build of SDL_mixer provides.
*
- * \returns number of music decoders
+ * 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.
+ *
+ * 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.
+ *
+ * These return values are static, read-only data; do not modify or free it.
+ * The pointers remain valid until you call Mix_CloseAudio().
+ *
+ * \returns number of chunk decoders available.
*
* \since This function is available since SDL_mixer 2.0.0.
*
@@ -817,10 +891,19 @@ extern DECLSPEC SDL_bool SDLCALL Mix_HasChunkDecoder(const char *name);
extern DECLSPEC int SDLCALL Mix_GetNumMusicDecoders(void);
/**
- * Get music decoder name
+ * 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.
+ *
+ * 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.
*
- * \param index index of the music decoder
- * \returns music decoder name
+ * \param index index of the music decoder.
+ * \returns the music decoder's name.
*
* \since This function is available since SDL_mixer 2.0.0.
*
@@ -829,69 +912,155 @@ extern DECLSPEC int SDLCALL Mix_GetNumMusicDecoders(void);
extern DECLSPEC const char * SDLCALL Mix_GetMusicDecoder(int index);
/**
- * Check if `name` is a music decoder
+ * Check if a music decoder is available by name.
*
- * \param name name
- * \returns SDL_TRUE or SDL_FALSE
+ * 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.
*
- * \since This function is available since SDL_mixer 2.6.0.
+ * 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.
+ *
+ * \since This function is available since SDL_mixer 2.6.0
+ *
+ * \sa Mix_GetNumMusicDecoders
+ * \sa Mix_GetMusicDecoder
*/
extern DECLSPEC SDL_bool SDLCALL Mix_HasMusicDecoder(const char *name);
-/* Find out the music format of a mixer music, or the currently playing
- music, if 'music' is NULL.
-*/
+/**
+ * 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).
+ *
+ * \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
+ */
extern DECLSPEC Mix_MusicType SDLCALL Mix_GetMusicType(const Mix_Music *music);
/**
- * Get music title from meta-tag if possible.
+ * Get the title for a music object, or its filename.
+ *
+ * This returns format-specific metadata. Not all file formats supply this!
+ *
+ * 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
+ * Mix_GetMusicTitleTag() instead.
*
- * If title tag is empty, filename will be returned
+ * Please note that if the music was loaded from an SDL_RWops instead of a
+ * filename, the filename returned will be an empty string ("").
*
- * \param music Mix Music
- * \returns music title
+ * 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.
+ * \returns the music's title if available, or the filename if not, or "".
*
* \since This function is available since SDL_mixer 2.6.0.
+ *
+ * \sa Mix_GetMusicTitleTag
+ * \sa Mix_GetMusicArtistTag
+ * \sa Mix_GetMusicAlbumTag
+ * \sa Mix_GetMusicCopyrightTag
*/
extern DECLSPEC const char *SDLCALL Mix_GetMusicTitle(const Mix_Music *music);
/**
- * Get music title from meta-tag if possible
+ * Get the title for a music object.
+ *
+ * This returns format-specific metadata. Not all file formats supply this!
+ *
+ * If `music` is NULL, this will query the currently-playing music.
+ *
+ * Unlike this function, Mix_GetMusicTitle() produce a string with the music's
+ * filename if a title isn't available, which might be preferable for some
+ * applications.
*
- * \param music Mix Music
- * \returns music title tag
+ * 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.
+ * \returns the music's title if available, or "".
*
* \since This function is available since SDL_mixer 2.6.0.
+ *
+ * \sa Mix_GetMusicTitle
+ * \sa Mix_GetMusicArtistTag
+ * \sa Mix_GetMusicAlbumTag
+ * \sa Mix_GetMusicCopyrightTag
*/
extern DECLSPEC const char *SDLCALL Mix_GetMusicTitleTag(const Mix_Music *music);
/**
- * Get music artist from meta-tag if possible
+ * Get the artist name for a music object.
+ *
+ * This returns format-specific metadata. Not all file formats supply this!
+ *
+ * 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 ("").
*
- * \param music Mix Music
- * \returns music artist tag
+ * \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.
+ *
+ * \sa Mix_GetMusicTitleTag
+ * \sa Mix_GetMusicAlbumTag
+ * \sa Mix_GetMusicCopyrightTag
*/
extern DECLSPEC const char *SDLCALL Mix_GetMusicArtistTag(const Mix_Music *music);
/**
- * Get music album from meta-tag if possible
+ * Get the album name for a music object.
+ *
+ * This returns format-specific metadata. Not all file formats supply this!
+ *
+ * If `music` is NULL, this will query the currently-playing music.
*
- * \param music Mix Music
- * \returns music album tag
+ * 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.
+ * \returns the music's album name if available, or "".
*
* \since This function is available since SDL_mixer 2.6.0.
+ *
+ * \sa Mix_GetMusicTitleTag
+ * \sa Mix_GetMusicArtistTag
+ * \sa Mix_GetMusicCopyrightTag
*/
extern DECLSPEC const char *SDLCALL Mix_GetMusicAlbumTag(const Mix_Music *music);
/**
- * Get music copyright from meta-tag if possible
+ * Get the copyright text for a music object.
+ *
+ * This returns format-specific metadata. Not all file formats supply this!
*
- * \param music Mix Music
- * \returns music copyright tag
+ * 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 ("").
+ *
+ * \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.
+ *
+ * \sa Mix_GetMusicTitleTag
+ * \sa Mix_GetMusicArtistTag
+ * \sa Mix_GetMusicAlbumTag
*/
extern DECLSPEC const char *SDLCALL Mix_GetMusicCopyrightTag(const Mix_Music *music);
@@ -901,62 +1070,143 @@ 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.
*
- * \param mix_func callback function
- * \param arg callback argument to be passed
+ * 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).
+ *
+ * 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).
+ *
+ * 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.
+ *
+ * \param mix_func the callback function to become the new post-mix callback.
+ * \param arg a pointer that is passed, untouched, to the callback.
*
* \since This function is available since SDL_mixer 2.0.0.
+ *
+ * \sa Mix_HookMusic
*/
extern DECLSPEC void SDLCALL Mix_SetPostMix(void (SDLCALL *mix_func)(void *udata, Uint8 *stream, int len), void *arg);
/**
* Add your own music player or additional mixer function.
*
- * If 'mix_func' is NULL, the default music player is re-enabled.
+ * 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
+ * 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.
+ *
+ * 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.
+ *
+ * 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).
+ *
+ * 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 mixer function callback
- * \param arg callback argument to be passed
+ * \param mix_func the callback function to become the new post-mix callback.
+ * \param arg a pointer that is passed, untouched, to the callback.
*
* \since This function is available since SDL_mixer 2.0.0.
+ *
+ * \sa Mix_SetPostMix
*/
extern DECLSPEC void SDLCALL Mix_HookMusic(void (SDLCALL *mix_func)(void *udata, Uint8 *stream, int len), void *arg);
/**
- * Add your own callback for when the music has finished playing or when it is
- * stopped from a call to Mix_HaltMusic.
+ * 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.
+ *
+ * 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
+ * can be used to loop the music without a gap in the audio playback.
*
- * \param music_finished callback function
+ * 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
+ * calling your callback.
+ *
+ * A NULL pointer will disable the callback.
+ *
+ * \param music_finished the callback function to become the new notification mechanism.
*
* \since This function is available since SDL_mixer 2.0.0.
*/
extern DECLSPEC void SDLCALL Mix_HookMusicFinished(void (SDLCALL *music_finished)(void));
/**
- * Get a pointer to the user data for the current music hook
+ * 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.
*
- * \returns pointer to the user data
+ * \returns pointer to the user data previously passed to Mix_HookMusic.
*
* \since This function is available since SDL_mixer 2.0.0.
*/
extern DECLSPEC void * SDLCALL Mix_GetMusicHookData(void);
/**
- * Add your own callback when a channel has finished playing.
+ * Set a callback that runs when a channel has finished playing.
*
- * NULL to disable callback. The callback may be called from the mixer's audio
- * callback or it could be called as a result of Mix_HaltChannel(), etc. 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 calling
- * your callback.
+ * The callback may be called from the mixer's audio callback or it could be
+ * called as a result of Mix_HaltChannel(), etc.
*
- * \param channel_finished callback function
+ * 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
+ * calling your callback.
+ *
+ * A NULL pointer will disable the callback.
+ *
+ * \param channel_finished the callback function to become the new notification mechanism.
*
* \since This function is available since SDL_mixer 2.0.0.
*/
extern DECLSPEC void SDLCALL Mix_ChannelFinished(void (SDLCALL *channel_finished)(int channel));
-/* Special Effects API by ryan c. gordon. (icculus@icculus.org) */
-
#define MIX_CHANNEL_POST (-2)
/**
@@ -1031,17 +1281,22 @@ typedef void (SDLCALL *Mix_EffectDone_t)(int chan, void *udata);
* Mix_EffectDone_t function called when they are unregistered (since the main
* output stream is never "done" in the same sense as a channel). You must
* unregister them manually when you've had enough. Your callback will be told
- * that the channel being mixed is (MIX_CHANNEL_POST) if the processing is
+ * that the channel being mixed is `MIX_CHANNEL_POST` if the processing is
* considered a posteffect.
*
* After all these effects have finished processing, the callback registered
* through Mix_SetPostMix() runs, and then the stream goes to the audio
* device.
*
- * DO NOT EVER call SDL_LockAudio() from your callback function!
+ * DO NOT EVER call SDL_LockAudio() from your callback function! You are already
+ * running in the audio thread and the lock is already held!
*
- * \param chan channel
- * \param f effect callback
+ * 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 d effect done callback
* \param arg argument
* \returns zero if error (no such channel), nonzero if added. Error messages
@@ -1053,15 +1308,22 @@ extern DECLSPEC int SDLCALL Mix_RegisterEffect(int chan, Mix_EffectFunc_t f, Mix
/**
- * You may not need to call this explicitly, unless you need to stop an effect
+ * Explicitly unregister a special effect function.
+ *
+ * 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, but
- * they may be explicitly unregistered through this function by specifying
- * MIX_CHANNEL_POST for a channel.
+ * 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.
*
- * \param channel channel
- * \param f effect callback
+ * 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 unregister an effect on, or MIX_CHANNEL_POST.
+ * \param f effect the callback stop calling in future mixing iterations.
* \returns zero if error (no such channel or effect), nonzero if removed.
* Error messages can be retrieved from Mix_GetError().
*
@@ -1070,8 +1332,10 @@ extern DECLSPEC int SDLCALL Mix_RegisterEffect(int chan, Mix_EffectFunc_t f, Mix
extern DECLSPEC int SDLCALL Mix_UnregisterEffect(int channel, Mix_EffectFunc_t f);
/**
- * You may not need to call this explicitly, unless you need to stop all
- * effects from processing in the middle of a chunk's playback.
+ * Explicitly unregister all special effect functions.
+ *
+ * You may not need to call this at all, unless you need to stop all effects
+ * from processing in the middle of a chunk's playback.
*
* Note that this will also shut off some internal effect processing, since
* Mix_SetPanning() and others may use this API under the hood. This is called
@@ -1080,7 +1344,11 @@ extern DECLSPEC int SDLCALL Mix_UnregisterEffect(int channel, Mix_EffectFunc_t f
* explicitly unregistered through this function by specifying
* MIX_CHANNEL_POST for a channel.
*
- * \param channel channel
+ * 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 unregister all effects on, or MIX_CHANNEL_POST.
* \returns zero if error (no such channel), nonzero if all effects removed.
* Error messages can be retrieved from Mix_GetError().
*
@@ -1115,8 +1383,6 @@ extern DECLSPEC int SDLCALL Mix_UnregisterAllEffects(int channel);
* Mix_SetPanning(channel, left, 255 - left);
* ```
*
- * ...which isn't so hard.
- *
* Setting `channel` to MIX_CHANNEL_POST registers this as a posteffect, and
* the panning will be done to the final mixed stream before passing it on to
* the audio device.
@@ -1130,6 +1396,10 @@ extern DECLSPEC int SDLCALL Mix_UnregisterAllEffects(int channel);
* return successful in that case. Error messages can be retrieved from
* Mix_GetError().
*
+ * 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 channel The mixer channel to pan or MIX_CHANNEL_POST.
* \param left Volume of stereo left channel, 0 is silence, 255 is full
* volume.
@@ -1149,18 +1419,18 @@ extern DECLSPEC int SDLCALL Mix_SetPanning(int channel, Uint8 left, Uint8 right)
/**
* Set the position of a channel.
*
- * (angle) is an integer from 0 to 360, that specifies the location of the
- * sound in relation to the listener. (angle) will be reduced as neccesary
+ * `angle` is an integer from 0 to 360, that specifies the location of the
+ * sound in relation to the listener. `angle` will be reduced as neccesary
* (540 becomes 180 degrees, -100 becomes 260). Angle 0 is due north, and
* rotates clockwise as the value increases. For efficiency, the precision of
* this effect may be limited (angles 1 through 7 might all produce the same
- * effect, 8 through 15 are equal, etc). (distance) is an integer between 0
+ * effect, 8 through 15 are equal, etc). `distance` is an integer between 0
* and 255 that specifies the space between the sound and the listener. The
* larger the number, the further away the sound is. Using 255 does not
- * guarantee that the channel will be culled from the mixing process or be
+ * guarantee that the channel will be removed from the mixing process or be
* completely silent. For efficiency, the precision of this effect may be
* limited (distance 0 through 5 might all produce the same effect, 6 through
- * 10 are equal, etc). Setting (angle) and (distance) to 0 unregisters this
+ * 10 are equal, etc). Setting `angle` and `distance` to 0 unregisters this
* effect, since the data would be unchanged.
*
* If you need more precise positional audio, consider using OpenAL for
@@ -1175,15 +1445,19 @@ extern DECLSPEC int SDLCALL Mix_SetPanning(int channel, Uint8 left, Uint8 right)
* convert them to mono through SDL before giving them to the mixer in the
* first place if you like.
*
- * Setting (channel) to MIX_CHANNEL_POST registers this as a posteffect, and
+ * Setting the channel to MIX_CHANNEL_POST registers this as a posteffect, and
* the positioning will be done to the final mixed stream before passing it on
* to the audio device.
*
* This is a convenience wrapper over Mix_SetDistance() and Mix_SetPanning().
*
- * \param channel channel
- * \param angle angle
- * \param distance distance
+ * 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 channel The mixer channel to position, or MIX_CHANNEL_POST.
+ * \param angle angle, in degrees. North is 0, and goes clockwise.
+ * \param distance distance; 0 is the listener, 255 is maxiumum distance away.
* \returns zero if error (no such channel or Mix_RegisterEffect() fails),
* nonzero if position effect is enabled. Error messages can be
* retrieved from Mix_GetError().
@@ -1196,28 +1470,32 @@ extern DECLSPEC int SDLCALL Mix_SetPosition(int channel, Sint16 angle, Uint8 dis
/**
* Set the "distance" of a channel.
*
- * (distance) is an integer from 0 to 255 that specifies the location of the
+ * `distance` is an integer from 0 to 255 that specifies the location of the
* sound in relation to the listener. Distance 0 is overlapping the listener,
- * and 255
(Patch may be truncated, please check the link at the top of this post.)