From 5e29690ad65393e4d6af01e5cef129ea855ce89e Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Sun, 19 Jun 2022 21:57:23 -0400
Subject: [PATCH] Prepare headers to bridge to the wiki.
---
.wikiheaders-options | 1 +
include/SDL_mixer.h | 485 +++++++++++++++++++++----------------------
2 files changed, 232 insertions(+), 254 deletions(-)
diff --git a/.wikiheaders-options b/.wikiheaders-options
index b23a3fea..53058b1d 100644
--- a/.wikiheaders-options
+++ b/.wikiheaders-options
@@ -13,3 +13,4 @@ projecturl = https://libsdl.org/projects/SDL_mixer
wikiurl = https://wiki.libsdl.org/SDL_mixer
bugreporturl = https://github.com/libsdl-org/sdlwiki/issues/new
warn_about_missing = 1
+wikipreamble = (This function is part of SDL_mixer, a separate library from SDL.)
diff --git a/include/SDL_mixer.h b/include/SDL_mixer.h
index dc9c96ef..19f91e87 100644
--- a/include/SDL_mixer.h
+++ b/include/SDL_mixer.h
@@ -89,10 +89,11 @@ extern "C" {
/**
* This function gets the version of the dynamically linked SDL_mixer library.
- * it should NOT be used to fill a version structure, instead you should
- * use the SDL_MIXER_VERSION() macro.
*
- * \returns SDL_mixer version
+ * it should NOT be used to fill a version structure, instead you should use
+ * the SDL_MIXER_VERSION() macro.
+ *
+ * \returns SDL_mixer version
*/
extern DECLSPEC const SDL_version * SDLCALL Mix_Linked_Version(void);
@@ -110,15 +111,16 @@ typedef enum
} MIX_InitFlags;
/**
- * Loads dynamic libraries and prepares them for use. Flags should be
- * one or more flags from MIX_InitFlags OR'd together.
- * It returns the flags successfully initialized, or 0 on failure.
+ * Loads dynamic libraries and prepares them for use.
+ *
+ * Flags should be one or more flags from MIX_InitFlags OR'd together. It
+ * returns the flags successfully initialized, or 0 on failure.
*
* \param flags initialization flags
* \returns flags successfully initialized, or 0 on failure.
*
- * \sa Mix_Quit
- * \sa MIX_InitFlags
+ * \sa Mix_Quit
+ * \sa MIX_InitFlags
*/
extern DECLSPEC int SDLCALL Mix_Init(int flags);
@@ -192,11 +194,9 @@ typedef struct _Mix_Music Mix_Music;
* Open the mixer with a certain audio format
*
* \param frequency frequency
- * \param format audio format
- * \param channels number of channels
+ * \param format audio format
+ * \param channels number of channels
* \param chunksize chunk size
- *
- *
* \returns 0 if successful, -1 on error
*/
extern DECLSPEC int SDLCALL Mix_OpenAudio(int frequency, Uint16 format, int channels, int chunksize);
@@ -204,25 +204,22 @@ extern DECLSPEC int SDLCALL Mix_OpenAudio(int frequency, Uint16 format, int chan
/**
* Open the mixer with specific device and certain audio format
*
- *
* \param frequency frequency
- * \param format audio format
- * \param channels number of channels
+ * \param format audio format
+ * \param channels number of channels
* \param chunksize chunk size
- * \param device audio device (can be NULL)
+ * \param device audio device (can be NULL)
* \param allowed_changes Allow change flags (see SDL_AUDIO_ALLOW_* flags)
- *
* \returns 0 if successful, -1 on error
*/
extern DECLSPEC int SDLCALL Mix_OpenAudioDevice(int frequency, Uint16 format, int channels, int chunksize, const char* device, int allowed_changes);
/**
* Dynamically change the number of channels managed by the mixer.
- * If decreasing the number of channels, the upper channels are
- * stopped.
*
- * \param numchans number of channels
+ * If decreasing the number of channels, the upper channels are stopped.
*
+ * \param numchans number of channels
* \returns the new number of allocated channels.
*/
extern DECLSPEC int SDLCALL Mix_AllocateChannels(int numchans);
@@ -233,7 +230,6 @@ extern DECLSPEC int SDLCALL Mix_AllocateChannels(int numchans);
* \param frequency frequency
* \param format audio format
* \param channels number of channels
- *
* \returns 1 if the audio has been opened, 0 otherwise.
*/
extern DECLSPEC int SDLCALL Mix_QuerySpec(int *frequency, Uint16 *format, int *channels);
@@ -244,7 +240,6 @@ extern DECLSPEC int SDLCALL Mix_QuerySpec(int *frequency, Uint16 *format, int *c
* \param src RWops
* \param freesrc can be set so that the RWops is freed after this function is
* called
- *
* \returns Mix Chunk, or NULL on error.
*
* \sa Mix_FreeChunk
@@ -267,7 +262,6 @@ extern DECLSPEC Mix_Chunk * SDLCALL Mix_LoadWAV_RW(SDL_RWops *src, int freesrc);
* Load a music file
*
* \param file file name
- *
* \returns Mix Music, or NULL on error.
*
* \sa Mix_FreeMusic
@@ -280,7 +274,6 @@ extern DECLSPEC Mix_Music * SDLCALL Mix_LoadMUS(const char *file);
* \param src RWops
* \param freesrc can be set so that the RWops is freed after this function is
* called
- *
* \returns Mix Music, or NULL on error.
*
* \sa Mix_FreeMusic
@@ -294,7 +287,6 @@ extern DECLSPEC Mix_Music * SDLCALL Mix_LoadMUS_RW(SDL_RWops *src, int freesrc);
* \param type music type
* \param freesrc can be set so that the RWops is freed after this function is
* called
- *
* \returns Mix Music, or NULL on error.
*
* \sa Mix_MusicType
@@ -306,7 +298,6 @@ extern DECLSPEC Mix_Music * SDLCALL Mix_LoadMUSType_RW(SDL_RWops *src, Mix_Music
* Load a wave file of the mixer format from a memory buffer
*
* \param mem memory buffer
- *
* \returns Mix Chunk, or NULL on error.
*
* \sa Mix_FreeChunk
@@ -318,7 +309,6 @@ extern DECLSPEC Mix_Chunk * SDLCALL Mix_QuickLoad_WAV(Uint8 *mem);
*
* \param mem memory buffer
* \param len length
- *
* \returns Mix Chunk, or NULL on error.
*
* \sa Mix_FreeChunk
@@ -342,7 +332,6 @@ extern DECLSPEC void SDLCALL Mix_FreeChunk(Mix_Chunk *chunk);
*
* \param music Mix Music
*
- *
* \sa Mix_LoadMUS
* \sa Mix_LoadMUS_RW
* \sa Mix_LoadMUSType_RW
@@ -351,23 +340,27 @@ extern DECLSPEC void SDLCALL Mix_FreeMusic(Mix_Music *music);
/**
* Get a list of chunk/music 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.
- * This API is only available in SDL_mixer 1.2.9 and later.
+ * libraries that add functionality become available. You must successfully
+ * call Mix_OpenAudio() before calling these functions. This API is only
+ * available in SDL_mixer 1.2.9 and later.
*
+ * ```c
* // usage...
* int i;
* const int total = Mix_GetNumChunkDecoders();
- * for (i = 0; i < total; i++)
+ * for (i = 0; i < total; i++) {
* printf("Supported chunk decoder: [%s]\n", Mix_GetChunkDecoder(i));
+ * }
+ * ```
*
* 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.
*
* These return values are static, read-only data; do not modify or free it.
- * The pointers remain valid until you call Mix_CloseAudio().a
+ * The pointers remain valid until you call Mix_CloseAudio().
*
* \returns number of chunk decoders
*
@@ -380,7 +373,6 @@ extern DECLSPEC int SDLCALL Mix_GetNumChunkDecoders(void);
* Get chunk decoder name
*
* \param index index of the chunk decoder
- *
* \returns chunk decoder name
*
* \sa Mix_GetNumChunkDecoders
@@ -391,7 +383,6 @@ extern DECLSPEC const char * SDLCALL Mix_GetChunkDecoder(int index);
* Check if `name` is a chunk decoder
*
* \param name name
- *
* \returns SDL_TRUE or SDL_FALSE
*/
extern DECLSPEC SDL_bool SDLCALL Mix_HasChunkDecoder(const char *name);
@@ -410,7 +401,6 @@ extern DECLSPEC int SDLCALL Mix_GetNumMusicDecoders(void);
* Get music decoder name
*
* \param index index of the music decoder
- *
* \returns music decoder name
*
* \sa Mix_GetNumMusicDecoders
@@ -421,7 +411,6 @@ extern DECLSPEC const char * SDLCALL Mix_GetMusicDecoder(int index);
* Check if `name` is a music decoder
*
* \param name name
- *
* \returns SDL_TRUE or SDL_FALSE
*/
extern DECLSPEC SDL_bool SDLCALL Mix_HasMusicDecoder(const char *name);
@@ -432,10 +421,11 @@ extern DECLSPEC SDL_bool SDLCALL Mix_HasMusicDecoder(const char *name);
extern DECLSPEC Mix_MusicType SDLCALL Mix_GetMusicType(const Mix_Music *music);
/**
- * Get music title from meta-tag if possible. If title tag is empty, filename will be returned
+ * Get music title from meta-tag if possible.
*
- * \param music Mix Music
+ * If title tag is empty, filename will be returned
*
+ * \param music Mix Music
* \returns music title
*/
extern DECLSPEC const char *SDLCALL Mix_GetMusicTitle(const Mix_Music *music);
@@ -444,7 +434,6 @@ extern DECLSPEC const char *SDLCALL Mix_GetMusicTitle(const Mix_Music *music);
* Get music title from meta-tag if possible
*
* \param music Mix Music
- *
* \returns music title tag
*/
extern DECLSPEC const char *SDLCALL Mix_GetMusicTitleTag(const Mix_Music *music);
@@ -453,7 +442,6 @@ extern DECLSPEC const char *SDLCALL Mix_GetMusicTitleTag(const Mix_Music *music)
* Get music artist from meta-tag if possible
*
* \param music Mix Music
- *
* \returns music artist tag
*/
extern DECLSPEC const char *SDLCALL Mix_GetMusicArtistTag(const Mix_Music *music);
@@ -462,7 +450,6 @@ extern DECLSPEC const char *SDLCALL Mix_GetMusicArtistTag(const Mix_Music *music
* Get music album from meta-tag if possible
*
* \param music Mix Music
- *
* \returns music album tag
*/
extern DECLSPEC const char *SDLCALL Mix_GetMusicAlbumTag(const Mix_Music *music);
@@ -471,15 +458,15 @@ extern DECLSPEC const char *SDLCALL Mix_GetMusicAlbumTag(const Mix_Music *music)
* Get music copyright from meta-tag if possible
*
* \param music Mix Music
- *
* \returns music copyright tag
*/
extern DECLSPEC const char *SDLCALL Mix_GetMusicCopyrightTag(const Mix_Music *music);
/**
* Set a function that is called after all mixing is performed.
- * This can be used to provide real-time visual display of the audio stream
- * or add a custom mixer filter for the stream data.
+ *
+ * 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
@@ -488,6 +475,7 @@ extern DECLSPEC void SDLCALL Mix_SetPostMix(void (SDLCALL *mix_func)(void *udata
/**
* Add your own music player or additional mixer function.
+ *
* If 'mix_func' is NULL, the default music player is re-enabled.
*
* \param mix_func mixer function callback
@@ -511,14 +499,15 @@ extern DECLSPEC void SDLCALL Mix_HookMusicFinished(void (SDLCALL *music_finished
extern DECLSPEC void * SDLCALL Mix_GetMusicHookData(void);
/**
- * Add your own callback 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.
+ * Add your own callback when a channel has finished playing.
*
- * \param channel_finished callback function
+ * 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.
+ *
+ * \param channel_finished callback function
*/
extern DECLSPEC void SDLCALL Mix_ChannelFinished(void (SDLCALL *channel_finished)(int channel));
@@ -560,46 +549,51 @@ typedef void (SDLCALL *Mix_EffectDone_t)(int chan, void *udata);
/**
- * Register a special effect function. At mixing time, the channel data is
- * copied into a buffer and passed through each registered effect function.
- * After it passes through all the functions, it is mixed into the final
- * output stream. The copy to buffer is performed once, then each effect
- * function performs on the output of the previous effect. Understand that
- * this extra copy to a buffer is not performed if there are no effects
- * registered for a given chunk, which saves CPU cycles, and any given
- * effect will be extra cycles, too, so it is crucial that your code run
- * fast. Also note that the data that your function is given is in the
- * format of the sound device, and not the format you gave to Mix_OpenAudio(),
- * although they may in reality be the same. This is an unfortunate but
- * necessary speed concern. Use Mix_QuerySpec() to determine if you can
- * handle the data before you register your effect, and take appropriate
- * actions.
- * You may also specify a callback (Mix_EffectDone_t) that is called when
- * the channel finishes playing. This gives you a more fine-grained control
- * than Mix_ChannelFinished(), in case you need to free effect-specific
- * resources, etc. If you don't need this, you can specify NULL.
+ * Register a special effect function.
+ *
+ * At mixing time, the channel data is copied into a buffer and passed through
+ * each registered effect function. After it passes through all the functions,
+ * it is mixed into the final output stream. The copy to buffer is performed
+ * once, then each effect function performs on the output of the previous
+ * effect. Understand that this extra copy to a buffer is not performed if
+ * there are no effects registered for a given chunk, which saves CPU cycles,
+ * and any given effect will be extra cycles, too, so it is crucial that your
+ * code run fast. Also note that the data that your function is given is in
+ * the format of the sound device, and not the format you gave to
+ * Mix_OpenAudio(), although they may in reality be the same. This is an
+ * unfortunate but necessary speed concern. Use Mix_QuerySpec() to determine
+ * if you can handle the data before you register your effect, and take
+ * appropriate actions.
+ *
+ * You may also specify a callback (Mix_EffectDone_t) that is called when the
+ * channel finishes playing. This gives you a more fine-grained control than
+ * Mix_ChannelFinished(), in case you need to free effect-specific resources,
+ * etc. If you don't need this, you can specify NULL.
+ *
* You may set the callbacks before or after calling Mix_PlayChannel().
- * Things like Mix_SetPanning() are just internal special effect functions,
- * so if you are using that, you've already incurred the overhead of a copy
- * to a separate buffer, and that these effects will be in the queue with
- * any functions you've registered. The list of registered effects for a
- * channel is reset when a chunk finishes playing, so you need to explicitly
- * set them with each call to Mix_PlayChannel*().
+ *
+ * Things like Mix_SetPanning() are just internal special effect functions, so
+ * if you are using that, you've already incurred the overhead of a copy to a
+ * separate buffer, and that these effects will be in the queue with any
+ * functions you've registered. The list of registered effects for a channel
+ * is reset when a chunk finishes playing, so you need to explicitly set them
+ * with each call to Mix_PlayChannel*().
+ *
* You may also register a special effect function that is to be run after
- * final mixing occurs. The rules for these callbacks are identical to those
- * in Mix_RegisterEffect, but they are run after all the channels and the
- * music have been mixed into a single stream, whereas channel-specific
- * effects run on a given channel before any other mixing occurs. These
- * global effect callbacks are call "posteffects". Posteffects only have
- * their 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 considered a posteffect.
+ * final mixing occurs. The rules for these callbacks are identical to those
+ * in Mix_RegisterEffect, but they are run after all the channels and the
+ * music have been mixed into a single stream, whereas channel-specific
+ * effects run on a given channel before any other mixing occurs. These global
+ * effect callbacks are call "posteffects". Posteffects only have their
+ * 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
+ * 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.
+ * through Mix_SetPostMix() runs, and then the stream goes to the audio
+ * device.
*
* DO NOT EVER call SDL_LockAudio() from your callback function!
*
@@ -607,42 +601,41 @@ typedef void (SDLCALL *Mix_EffectDone_t)(int chan, void *udata);
* \param f effect callback
* \param d effect done callback
* \param arg argument
- *
- * \returns zero if error (no such channel), nonzero if added.
- * Error messages can be retrieved from Mix_GetError().
+ * \returns zero if error (no such channel), nonzero if added. Error messages
+ * can be retrieved from Mix_GetError().
*/
extern DECLSPEC int SDLCALL Mix_RegisterEffect(int chan, Mix_EffectFunc_t f, Mix_EffectDone_t d, void *arg);
/**
- * You may not need to call this explicitly, 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.
+ * You may not need to call this explicitly, 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.
*
* \param channel channel
* \param f effect callback
- *
* \returns zero if error (no such channel or effect), nonzero if removed.
- * Error messages can be retrieved from Mix_GetError().
+ * Error messages can be retrieved from Mix_GetError().
*/
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. 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 internally when a channel completes 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.
+ * effects from processing in the middle of a chunk's playback.
*
- * \param channel channel
+ * 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
+ * internally when a channel completes 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.
*
+ * \param channel channel
* \returns zero if error (no such channel), nonzero if all effects removed.
- * Error messages can be retrieved from Mix_GetError().
+ * Error messages can be retrieved from Mix_GetError().
*/
extern DECLSPEC int SDLCALL Mix_UnregisterAllEffects(int channel);
@@ -665,9 +658,9 @@ extern DECLSPEC int SDLCALL Mix_UnregisterAllEffects(int channel);
* The left and right channels are specified as integers between 0 and 255,
* quietest to loudest, respectively.
*
- * Technically, this is just individual volume control for a sample with
- * two (stereo) channels, so it can be used for more than just panning.
- * If you want real panning, call it like this:
+ * Technically, this is just individual volume control for a sample with two
+ * (stereo) channels, so it can be used for more than just panning. If you
+ * want real panning, call it like this:
*
* ```c
* Mix_SetPanning(channel, left, 255 - left);
@@ -676,21 +669,23 @@ extern DECLSPEC int SDLCALL Mix_UnregisterAllEffects(int channel);
* ...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.
+ * the panning will be done to the final mixed stream before passing it on to
+ * the audio device.
*
* This uses the Mix_RegisterEffect() API internally, and returns without
- * registering the effect function if the audio device is not configured
- * for stereo output. Setting both `left` and `right` to 255 causes this
- * effect to be unregistered, since that is the data's normal state.
+ * registering the effect function if the audio device is not configured for
+ * stereo output. Setting both `left` and `right` to 255 causes this effect to
+ * be unregistered, since that is the data's normal state.
*
* Note that an audio device in mono mode is a no-op, but this call will
- * return successful in that case. Error messages can be retrieved from
- * Mix_GetError().
+ * return successful in that case. Error messages can be retrieved from
+ * Mix_GetError().
*
* \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.
- * \param right Volume of stereo right channel, 0 is silence, 255 is full volume.
+ * \param left Volume of stereo left channel, 0 is silence, 255 is full
+ * volume.
+ * \param right Volume of stereo right channel, 0 is silence, 255 is full
+ * volume.
* \returns zero if error (no such channel or Mix_RegisterEffect() fails),
* nonzero if panning effect enabled.
*
@@ -703,80 +698,78 @@ 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 (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 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 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 effect, since the data would be
- * unchanged.
+ * 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
+ * (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
+ * 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
+ * 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
+ * effect, since the data would be unchanged.
*
* If you need more precise positional audio, consider using OpenAL for
- * spatialized effects instead of SDL_mixer. This is only meant to be a
- * basic effect for simple "3D" games.
+ * spatialized effects instead of SDL_mixer. This is only meant to be a basic
+ * effect for simple "3D" games.
*
- * If the audio device is configured for mono output, then you won't get
- * any effectiveness from the angle; however, distance attenuation on the
- * channel will still occur. While this effect will function with stereo
- * voices, it makes more sense to use voices with only one channel of sound,
- * so when they are mixed through this effect, the positioning will sound
- * correct. You can convert them to mono through SDL before giving them to
- * the mixer in the first place if you like.
+ * If the audio device is configured for mono output, then you won't get any
+ * effectiveness from the angle; however, distance attenuation on the channel
+ * will still occur. While this effect will function with stereo voices, it
+ * makes more sense to use voices with only one channel of sound, so when they
+ * are mixed through this effect, the positioning will sound correct. You can
+ * 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
- * the positioning will be done to the final mixed stream before passing it
- * on to the audio device.
+ * 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
- *
* \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().
+ * nonzero if position effect is enabled. Error messages can be
+ * retrieved from Mix_GetError().
*/
extern DECLSPEC int SDLCALL Mix_SetPosition(int channel, Sint16 angle, Uint8 distance);
/**
- * Set the "distance" of a channel. (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 is as far away as possible
- * A distance of 255 does not guarantee silence; in such a case, you might
- * want to try changing the chunk's volume, or just cull the sample from the
- * mixing process with Mix_HaltChannel().
- * For efficiency, the precision of this effect may be limited (distances 1
- * through 7 might all produce the same 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.
- * Setting (distance) to 0 unregisters this effect, since the data would be
- * unchanged.
- * If you need more precise positional audio, consider using OpenAL for
- * spatialized effects instead of SDL_mixer. This is only meant to be a
- * basic effect for simple "3D" games.
+ * Set the "distance" of a channel.
+ *
+ * (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 is as far away as possible A distance of 255 does not guarantee
+ * silence; in such a case, you might want to try changing the chunk's volume,
+ * or just cull the sample from the mixing process with Mix_HaltChannel(). For
+ * efficiency, the precision of this effect may be limited (distances 1
+ * through 7 might all produce the same 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. Setting (distance) to 0 unregisters this effect, since the data
+ * would be unchanged. If you need more precise positional audio, consider
+ * using OpenAL for spatialized effects instead of SDL_mixer. This is only
+ * meant to be a basic effect for simple "3D" games.
*
* Setting (channel) to MIX_CHANNEL_POST registers this as a posteffect, and
- * the distance attenuation will be done to the final mixed stream before
- * passing it on to the audio device.
+ * the distance attenuation will be done to the final mixed stream before
+ * passing it on to the audio device.
*
* This uses the Mix_RegisterEffect() API internally.
*
* \param channel channel
* \param distance distance
- *
* \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().
+ * nonzero if position effect is enabled. Error messages can be
+ * retrieved from Mix_GetError().
*/
extern DECLSPEC int SDLCALL Mix_SetDistance(int channel, Uint8 distance);
@@ -806,28 +799,28 @@ extern no_parse_DECLSPEC int SDLCALL Mix_SetReverb(int channel, Uint8 echo);
#endif
/**
- * Causes a channel to reverse its stereo. This is handy if the user has his
- * speakers hooked up backwards, or you would like to have a minor bit of
- * psychedelia in your sound code. :) Calling this function with (flip)
- * set to non-zero reverses the chunks's usual channels. If (flip) is zero,
- * the effect is unregistered.
+ * Causes a channel to reverse its stereo.
+ *
+ * This is handy if the user has his speakers hooked up backwards, or you
+ * would like to have a minor bit of psychedelia in your sound code. :)
+ * Calling this function with (flip) set to non-zero reverses the chunks's
+ * usual channels. If (flip) is zero, the effect is unregistered.
*
* This uses the Mix_RegisterEffect() API internally, and thus is probably
- * more CPU intensive than having the user just plug in his speakers
- * correctly. Mix_SetReverseStereo() returns without registering the effect
- * function if the audio device is not configured for stereo output.
+ * more CPU intensive than having the user just plug in his speakers
+ * 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 the effect is used
- * on the final mixed stream before sending it on to the audio device (a
- * posteffect).
+ * on the final mixed stream before sending it on to the audio device (a
+ * posteffect).
*
* \param channel channel
* \param flip flip
- *
* \returns zero if error (no such channel or Mix_RegisterEffect() fails),
- * nonzero if reversing effect is enabled. Note that an audio device in mono
- * mode is a no-op, but this call will return successful in that case.
- * Err
(Patch may be truncated, please check the link at the top of this post.)