include/SDL_mixer.h
changeset 999 1a87fe70802d
child 1086 89f446aae9b5
     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/include/SDL_mixer.h	Tue Nov 19 12:36:40 2019 +0300
     1.3 @@ -0,0 +1,651 @@
     1.4 +/*
     1.5 +  SDL_mixer:  An audio mixer library based on the SDL library
     1.6 +  Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
     1.7 +
     1.8 +  This software is provided 'as-is', without any express or implied
     1.9 +  warranty.  In no event will the authors be held liable for any damages
    1.10 +  arising from the use of this software.
    1.11 +
    1.12 +  Permission is granted to anyone to use this software for any purpose,
    1.13 +  including commercial applications, and to alter it and redistribute it
    1.14 +  freely, subject to the following restrictions:
    1.15 +
    1.16 +  1. The origin of this software must not be misrepresented; you must not
    1.17 +     claim that you wrote the original software. If you use this software
    1.18 +     in a product, an acknowledgment in the product documentation would be
    1.19 +     appreciated but is not required.
    1.20 +  2. Altered source versions must be plainly marked as such, and must not be
    1.21 +     misrepresented as being the original software.
    1.22 +  3. This notice may not be removed or altered from any source distribution.
    1.23 +*/
    1.24 +
    1.25 +#ifndef SDL_MIXER_H_
    1.26 +#define SDL_MIXER_H_
    1.27 +
    1.28 +#include "SDL_stdinc.h"
    1.29 +#include "SDL_rwops.h"
    1.30 +#include "SDL_audio.h"
    1.31 +#include "SDL_endian.h"
    1.32 +#include "SDL_version.h"
    1.33 +#include "begin_code.h"
    1.34 +
    1.35 +/* Set up for C function definitions, even when using C++ */
    1.36 +#ifdef __cplusplus
    1.37 +extern "C" {
    1.38 +#endif
    1.39 +
    1.40 +/* Printable format: "%d.%d.%d", MAJOR, MINOR, PATCHLEVEL
    1.41 +*/
    1.42 +#define SDL_MIXER_MAJOR_VERSION 2
    1.43 +#define SDL_MIXER_MINOR_VERSION 0
    1.44 +#define SDL_MIXER_PATCHLEVEL    4
    1.45 +
    1.46 +/* This macro can be used to fill a version structure with the compile-time
    1.47 + * version of the SDL_mixer library.
    1.48 + */
    1.49 +#define SDL_MIXER_VERSION(X)                        \
    1.50 +{                                                   \
    1.51 +    (X)->major = SDL_MIXER_MAJOR_VERSION;           \
    1.52 +    (X)->minor = SDL_MIXER_MINOR_VERSION;           \
    1.53 +    (X)->patch = SDL_MIXER_PATCHLEVEL;              \
    1.54 +}
    1.55 +
    1.56 +/* Backwards compatibility */
    1.57 +#define MIX_MAJOR_VERSION   SDL_MIXER_MAJOR_VERSION
    1.58 +#define MIX_MINOR_VERSION   SDL_MIXER_MINOR_VERSION
    1.59 +#define MIX_PATCHLEVEL      SDL_MIXER_PATCHLEVEL
    1.60 +#define MIX_VERSION(X)      SDL_MIXER_VERSION(X)
    1.61 +
    1.62 +/**
    1.63 + *  This is the version number macro for the current SDL_mixer version.
    1.64 + */
    1.65 +#define SDL_MIXER_COMPILEDVERSION \
    1.66 +    SDL_VERSIONNUM(SDL_MIXER_MAJOR_VERSION, SDL_MIXER_MINOR_VERSION, SDL_MIXER_PATCHLEVEL)
    1.67 +
    1.68 +/**
    1.69 + *  This macro will evaluate to true if compiled with SDL_mixer at least X.Y.Z.
    1.70 + */
    1.71 +#define SDL_MIXER_VERSION_ATLEAST(X, Y, Z) \
    1.72 +    (SDL_MIXER_COMPILEDVERSION >= SDL_VERSIONNUM(X, Y, Z))
    1.73 +
    1.74 +/* This function gets the version of the dynamically linked SDL_mixer library.
    1.75 +   it should NOT be used to fill a version structure, instead you should
    1.76 +   use the SDL_MIXER_VERSION() macro.
    1.77 + */
    1.78 +extern DECLSPEC const SDL_version * SDLCALL Mix_Linked_Version(void);
    1.79 +
    1.80 +typedef enum
    1.81 +{
    1.82 +    MIX_INIT_FLAC   = 0x00000001,
    1.83 +    MIX_INIT_MOD    = 0x00000002,
    1.84 +    MIX_INIT_MP3    = 0x00000008,
    1.85 +    MIX_INIT_OGG    = 0x00000010,
    1.86 +    MIX_INIT_MID    = 0x00000020,
    1.87 +    MIX_INIT_OPUS   = 0x00000040
    1.88 +} MIX_InitFlags;
    1.89 +
    1.90 +/* Loads dynamic libraries and prepares them for use.  Flags should be
    1.91 +   one or more flags from MIX_InitFlags OR'd together.
    1.92 +   It returns the flags successfully initialized, or 0 on failure.
    1.93 + */
    1.94 +extern DECLSPEC int SDLCALL Mix_Init(int flags);
    1.95 +
    1.96 +/* Unloads libraries loaded with Mix_Init */
    1.97 +extern DECLSPEC void SDLCALL Mix_Quit(void);
    1.98 +
    1.99 +
   1.100 +/* The default mixer has 8 simultaneous mixing channels */
   1.101 +#ifndef MIX_CHANNELS
   1.102 +#define MIX_CHANNELS    8
   1.103 +#endif
   1.104 +
   1.105 +/* Good default values for a PC soundcard */
   1.106 +#define MIX_DEFAULT_FREQUENCY   22050
   1.107 +#if SDL_BYTEORDER == SDL_LIL_ENDIAN
   1.108 +#define MIX_DEFAULT_FORMAT  AUDIO_S16LSB
   1.109 +#else
   1.110 +#define MIX_DEFAULT_FORMAT  AUDIO_S16MSB
   1.111 +#endif
   1.112 +#define MIX_DEFAULT_CHANNELS    2
   1.113 +#define MIX_MAX_VOLUME          SDL_MIX_MAXVOLUME /* Volume of a chunk */
   1.114 +
   1.115 +/* The internal format for an audio chunk */
   1.116 +typedef struct Mix_Chunk {
   1.117 +    int allocated;
   1.118 +    Uint8 *abuf;
   1.119 +    Uint32 alen;
   1.120 +    Uint8 volume;       /* Per-sample volume, 0-128 */
   1.121 +} Mix_Chunk;
   1.122 +
   1.123 +/* The different fading types supported */
   1.124 +typedef enum {
   1.125 +    MIX_NO_FADING,
   1.126 +    MIX_FADING_OUT,
   1.127 +    MIX_FADING_IN
   1.128 +} Mix_Fading;
   1.129 +
   1.130 +/* These are types of music files (not libraries used to load them) */
   1.131 +typedef enum {
   1.132 +    MUS_NONE,
   1.133 +    MUS_CMD,
   1.134 +    MUS_WAV,
   1.135 +    MUS_MOD,
   1.136 +    MUS_MID,
   1.137 +    MUS_OGG,
   1.138 +    MUS_MP3,
   1.139 +    MUS_MP3_MAD_UNUSED,
   1.140 +    MUS_FLAC,
   1.141 +    MUS_MODPLUG_UNUSED,
   1.142 +    MUS_OPUS
   1.143 +} Mix_MusicType;
   1.144 +
   1.145 +/* The internal format for a music chunk interpreted via mikmod */
   1.146 +typedef struct _Mix_Music Mix_Music;
   1.147 +
   1.148 +/* Open the mixer with a certain audio format */
   1.149 +extern DECLSPEC int SDLCALL Mix_OpenAudio(int frequency, Uint16 format, int channels, int chunksize);
   1.150 +
   1.151 +/* Open the mixer with specific device and certain audio format */
   1.152 +extern DECLSPEC int SDLCALL Mix_OpenAudioDevice(int frequency, Uint16 format, int channels, int chunksize, const char* device, int allowed_changes);
   1.153 +
   1.154 +/* Dynamically change the number of channels managed by the mixer.
   1.155 +   If decreasing the number of channels, the upper channels are
   1.156 +   stopped.
   1.157 +   This function returns the new number of allocated channels.
   1.158 + */
   1.159 +extern DECLSPEC int SDLCALL Mix_AllocateChannels(int numchans);
   1.160 +
   1.161 +/* Find out what the actual audio device parameters are.
   1.162 +   This function returns 1 if the audio has been opened, 0 otherwise.
   1.163 + */
   1.164 +extern DECLSPEC int SDLCALL Mix_QuerySpec(int *frequency,Uint16 *format,int *channels);
   1.165 +
   1.166 +/* Load a wave file or a music (.mod .s3m .it .xm) file */
   1.167 +extern DECLSPEC Mix_Chunk * SDLCALL Mix_LoadWAV_RW(SDL_RWops *src, int freesrc);
   1.168 +#define Mix_LoadWAV(file)   Mix_LoadWAV_RW(SDL_RWFromFile(file, "rb"), 1)
   1.169 +extern DECLSPEC Mix_Music * SDLCALL Mix_LoadMUS(const char *file);
   1.170 +
   1.171 +/* Load a music file from an SDL_RWop object (Ogg and MikMod specific currently)
   1.172 +   Matt Campbell (matt@campbellhome.dhs.org) April 2000 */
   1.173 +extern DECLSPEC Mix_Music * SDLCALL Mix_LoadMUS_RW(SDL_RWops *src, int freesrc);
   1.174 +
   1.175 +/* Load a music file from an SDL_RWop object assuming a specific format */
   1.176 +extern DECLSPEC Mix_Music * SDLCALL Mix_LoadMUSType_RW(SDL_RWops *src, Mix_MusicType type, int freesrc);
   1.177 +
   1.178 +/* Load a wave file of the mixer format from a memory buffer */
   1.179 +extern DECLSPEC Mix_Chunk * SDLCALL Mix_QuickLoad_WAV(Uint8 *mem);
   1.180 +
   1.181 +/* Load raw audio data of the mixer format from a memory buffer */
   1.182 +extern DECLSPEC Mix_Chunk * SDLCALL Mix_QuickLoad_RAW(Uint8 *mem, Uint32 len);
   1.183 +
   1.184 +/* Free an audio chunk previously loaded */
   1.185 +extern DECLSPEC void SDLCALL Mix_FreeChunk(Mix_Chunk *chunk);
   1.186 +extern DECLSPEC void SDLCALL Mix_FreeMusic(Mix_Music *music);
   1.187 +
   1.188 +/* Get a list of chunk/music decoders that this build of SDL_mixer provides.
   1.189 +   This list can change between builds AND runs of the program, if external
   1.190 +   libraries that add functionality become available.
   1.191 +   You must successfully call Mix_OpenAudio() before calling these functions.
   1.192 +   This API is only available in SDL_mixer 1.2.9 and later.
   1.193 +
   1.194 +   // usage...
   1.195 +   int i;
   1.196 +   const int total = Mix_GetNumChunkDecoders();
   1.197 +   for (i = 0; i < total; i++)
   1.198 +       printf("Supported chunk decoder: [%s]\n", Mix_GetChunkDecoder(i));
   1.199 +
   1.200 +   Appearing in this list doesn't promise your specific audio file will
   1.201 +   decode...but it's handy to know if you have, say, a functioning Timidity
   1.202 +   install.
   1.203 +
   1.204 +   These return values are static, read-only data; do not modify or free it.
   1.205 +   The pointers remain valid until you call Mix_CloseAudio().
   1.206 +*/
   1.207 +extern DECLSPEC int SDLCALL Mix_GetNumChunkDecoders(void);
   1.208 +extern DECLSPEC const char * SDLCALL Mix_GetChunkDecoder(int index);
   1.209 +extern DECLSPEC SDL_bool SDLCALL Mix_HasChunkDecoder(const char *name);
   1.210 +extern DECLSPEC int SDLCALL Mix_GetNumMusicDecoders(void);
   1.211 +extern DECLSPEC const char * SDLCALL Mix_GetMusicDecoder(int index);
   1.212 +extern DECLSPEC SDL_bool SDLCALL Mix_HasMusicDecoder(const char *name);
   1.213 +
   1.214 +/* Find out the music format of a mixer music, or the currently playing
   1.215 +   music, if 'music' is NULL.
   1.216 +*/
   1.217 +extern DECLSPEC Mix_MusicType SDLCALL Mix_GetMusicType(const Mix_Music *music);
   1.218 +
   1.219 +/* Set a function that is called after all mixing is performed.
   1.220 +   This can be used to provide real-time visual display of the audio stream
   1.221 +   or add a custom mixer filter for the stream data.
   1.222 +*/
   1.223 +extern DECLSPEC void SDLCALL Mix_SetPostMix(void (SDLCALL *mix_func)(void *udata, Uint8 *stream, int len), void *arg);
   1.224 +
   1.225 +/* Add your own music player or additional mixer function.
   1.226 +   If 'mix_func' is NULL, the default music player is re-enabled.
   1.227 + */
   1.228 +extern DECLSPEC void SDLCALL Mix_HookMusic(void (SDLCALL *mix_func)(void *udata, Uint8 *stream, int len), void *arg);
   1.229 +
   1.230 +/* Add your own callback for when the music has finished playing or when it is
   1.231 + * stopped from a call to Mix_HaltMusic.
   1.232 + */
   1.233 +extern DECLSPEC void SDLCALL Mix_HookMusicFinished(void (SDLCALL *music_finished)(void));
   1.234 +
   1.235 +/* Get a pointer to the user data for the current music hook */
   1.236 +extern DECLSPEC void * SDLCALL Mix_GetMusicHookData(void);
   1.237 +
   1.238 +/*
   1.239 + * Add your own callback when a channel has finished playing. NULL
   1.240 + *  to disable callback. The callback may be called from the mixer's audio
   1.241 + *  callback or it could be called as a result of Mix_HaltChannel(), etc.
   1.242 + *  do not call SDL_LockAudio() from this callback; you will either be
   1.243 + *  inside the audio callback, or SDL_mixer will explicitly lock the audio
   1.244 + *  before calling your callback.
   1.245 + */
   1.246 +extern DECLSPEC void SDLCALL Mix_ChannelFinished(void (SDLCALL *channel_finished)(int channel));
   1.247 +
   1.248 +
   1.249 +/* Special Effects API by ryan c. gordon. (icculus@icculus.org) */
   1.250 +
   1.251 +#define MIX_CHANNEL_POST  -2
   1.252 +
   1.253 +/* This is the format of a special effect callback:
   1.254 + *
   1.255 + *   myeffect(int chan, void *stream, int len, void *udata);
   1.256 + *
   1.257 + * (chan) is the channel number that your effect is affecting. (stream) is
   1.258 + *  the buffer of data to work upon. (len) is the size of (stream), and
   1.259 + *  (udata) is a user-defined bit of data, which you pass as the last arg of
   1.260 + *  Mix_RegisterEffect(), and is passed back unmolested to your callback.
   1.261 + *  Your effect changes the contents of (stream) based on whatever parameters
   1.262 + *  are significant, or just leaves it be, if you prefer. You can do whatever
   1.263 + *  you like to the buffer, though, and it will continue in its changed state
   1.264 + *  down the mixing pipeline, through any other effect functions, then finally
   1.265 + *  to be mixed with the rest of the channels and music for the final output
   1.266 + *  stream.
   1.267 + *
   1.268 + * DO NOT EVER call SDL_LockAudio() from your callback function!
   1.269 + */
   1.270 +typedef void (SDLCALL *Mix_EffectFunc_t)(int chan, void *stream, int len, void *udata);
   1.271 +
   1.272 +/*
   1.273 + * This is a callback that signifies that a channel has finished all its
   1.274 + *  loops and has completed playback. This gets called if the buffer
   1.275 + *  plays out normally, or if you call Mix_HaltChannel(), implicitly stop
   1.276 + *  a channel via Mix_AllocateChannels(), or unregister a callback while
   1.277 + *  it's still playing.
   1.278 + *
   1.279 + * DO NOT EVER call SDL_LockAudio() from your callback function!
   1.280 + */
   1.281 +typedef void (SDLCALL *Mix_EffectDone_t)(int chan, void *udata);
   1.282 +
   1.283 +
   1.284 +/* Register a special effect function. At mixing time, the channel data is
   1.285 + *  copied into a buffer and passed through each registered effect function.
   1.286 + *  After it passes through all the functions, it is mixed into the final
   1.287 + *  output stream. The copy to buffer is performed once, then each effect
   1.288 + *  function performs on the output of the previous effect. Understand that
   1.289 + *  this extra copy to a buffer is not performed if there are no effects
   1.290 + *  registered for a given chunk, which saves CPU cycles, and any given
   1.291 + *  effect will be extra cycles, too, so it is crucial that your code run
   1.292 + *  fast. Also note that the data that your function is given is in the
   1.293 + *  format of the sound device, and not the format you gave to Mix_OpenAudio(),
   1.294 + *  although they may in reality be the same. This is an unfortunate but
   1.295 + *  necessary speed concern. Use Mix_QuerySpec() to determine if you can
   1.296 + *  handle the data before you register your effect, and take appropriate
   1.297 + *  actions.
   1.298 + * You may also specify a callback (Mix_EffectDone_t) that is called when
   1.299 + *  the channel finishes playing. This gives you a more fine-grained control
   1.300 + *  than Mix_ChannelFinished(), in case you need to free effect-specific
   1.301 + *  resources, etc. If you don't need this, you can specify NULL.
   1.302 + * You may set the callbacks before or after calling Mix_PlayChannel().
   1.303 + * Things like Mix_SetPanning() are just internal special effect functions,
   1.304 + *  so if you are using that, you've already incurred the overhead of a copy
   1.305 + *  to a separate buffer, and that these effects will be in the queue with
   1.306 + *  any functions you've registered. The list of registered effects for a
   1.307 + *  channel is reset when a chunk finishes playing, so you need to explicitly
   1.308 + *  set them with each call to Mix_PlayChannel*().
   1.309 + * You may also register a special effect function that is to be run after
   1.310 + *  final mixing occurs. The rules for these callbacks are identical to those
   1.311 + *  in Mix_RegisterEffect, but they are run after all the channels and the
   1.312 + *  music have been mixed into a single stream, whereas channel-specific
   1.313 + *  effects run on a given channel before any other mixing occurs. These
   1.314 + *  global effect callbacks are call "posteffects". Posteffects only have
   1.315 + *  their Mix_EffectDone_t function called when they are unregistered (since
   1.316 + *  the main output stream is never "done" in the same sense as a channel).
   1.317 + *  You must unregister them manually when you've had enough. Your callback
   1.318 + *  will be told that the channel being mixed is (MIX_CHANNEL_POST) if the
   1.319 + *  processing is considered a posteffect.
   1.320 + *
   1.321 + * After all these effects have finished processing, the callback registered
   1.322 + *  through Mix_SetPostMix() runs, and then the stream goes to the audio
   1.323 + *  device.
   1.324 + *
   1.325 + * DO NOT EVER call SDL_LockAudio() from your callback function!
   1.326 + *
   1.327 + * returns zero if error (no such channel), nonzero if added.
   1.328 + *  Error messages can be retrieved from Mix_GetError().
   1.329 + */
   1.330 +extern DECLSPEC int SDLCALL Mix_RegisterEffect(int chan, Mix_EffectFunc_t f, Mix_EffectDone_t d, void *arg);
   1.331 +
   1.332 +
   1.333 +/* You may not need to call this explicitly, unless you need to stop an
   1.334 + *  effect from processing in the middle of a chunk's playback.
   1.335 + * Posteffects are never implicitly unregistered as they are for channels,
   1.336 + *  but they may be explicitly unregistered through this function by
   1.337 + *  specifying MIX_CHANNEL_POST for a channel.
   1.338 + * returns zero if error (no such channel or effect), nonzero if removed.
   1.339 + *  Error messages can be retrieved from Mix_GetError().
   1.340 + */
   1.341 +extern DECLSPEC int SDLCALL Mix_UnregisterEffect(int channel, Mix_EffectFunc_t f);
   1.342 +
   1.343 +
   1.344 +/* You may not need to call this explicitly, unless you need to stop all
   1.345 + *  effects from processing in the middle of a chunk's playback. Note that
   1.346 + *  this will also shut off some internal effect processing, since
   1.347 + *  Mix_SetPanning() and others may use this API under the hood. This is
   1.348 + *  called internally when a channel completes playback.
   1.349 + * Posteffects are never implicitly unregistered as they are for channels,
   1.350 + *  but they may be explicitly unregistered through this function by
   1.351 + *  specifying MIX_CHANNEL_POST for a channel.
   1.352 + * returns zero if error (no such channel), nonzero if all effects removed.
   1.353 + *  Error messages can be retrieved from Mix_GetError().
   1.354 + */
   1.355 +extern DECLSPEC int SDLCALL Mix_UnregisterAllEffects(int channel);
   1.356 +
   1.357 +
   1.358 +#define MIX_EFFECTSMAXSPEED  "MIX_EFFECTSMAXSPEED"
   1.359 +
   1.360 +/*
   1.361 + * These are the internally-defined mixing effects. They use the same API that
   1.362 + *  effects defined in the application use, but are provided here as a
   1.363 + *  convenience. Some effects can reduce their quality or use more memory in
   1.364 + *  the name of speed; to enable this, make sure the environment variable
   1.365 + *  MIX_EFFECTSMAXSPEED (see above) is defined before you call
   1.366 + *  Mix_OpenAudio().
   1.367 + */
   1.368 +
   1.369 +
   1.370 +/* Set the panning of a channel. The left and right channels are specified
   1.371 + *  as integers between 0 and 255, quietest to loudest, respectively.
   1.372 + *
   1.373 + * Technically, this is just individual volume control for a sample with
   1.374 + *  two (stereo) channels, so it can be used for more than just panning.
   1.375 + *  If you want real panning, call it like this:
   1.376 + *
   1.377 + *   Mix_SetPanning(channel, left, 255 - left);
   1.378 + *
   1.379 + * ...which isn't so hard.
   1.380 + *
   1.381 + * Setting (channel) to MIX_CHANNEL_POST registers this as a posteffect, and
   1.382 + *  the panning will be done to the final mixed stream before passing it on
   1.383 + *  to the audio device.
   1.384 + *
   1.385 + * This uses the Mix_RegisterEffect() API internally, and returns without
   1.386 + *  registering the effect function if the audio device is not configured
   1.387 + *  for stereo output. Setting both (left) and (right) to 255 causes this
   1.388 + *  effect to be unregistered, since that is the data's normal state.
   1.389 + *
   1.390 + * returns zero if error (no such channel or Mix_RegisterEffect() fails),
   1.391 + *  nonzero if panning effect enabled. Note that an audio device in mono
   1.392 + *  mode is a no-op, but this call will return successful in that case.
   1.393 + *  Error messages can be retrieved from Mix_GetError().
   1.394 + */
   1.395 +extern DECLSPEC int SDLCALL Mix_SetPanning(int channel, Uint8 left, Uint8 right);
   1.396 +
   1.397 +
   1.398 +/* Set the position of a channel. (angle) is an integer from 0 to 360, that
   1.399 + *  specifies the location of the sound in relation to the listener. (angle)
   1.400 + *  will be reduced as neccesary (540 becomes 180 degrees, -100 becomes 260).
   1.401 + *  Angle 0 is due north, and rotates clockwise as the value increases.
   1.402 + *  For efficiency, the precision of this effect may be limited (angles 1
   1.403 + *  through 7 might all produce the same effect, 8 through 15 are equal, etc).
   1.404 + *  (distance) is an integer between 0 and 255 that specifies the space
   1.405 + *  between the sound and the listener. The larger the number, the further
   1.406 + *  away the sound is. Using 255 does not guarantee that the channel will be
   1.407 + *  culled from the mixing process or be completely silent. For efficiency,
   1.408 + *  the precision of this effect may be limited (distance 0 through 5 might
   1.409 + *  all produce the same effect, 6 through 10 are equal, etc). Setting (angle)
   1.410 + *  and (distance) to 0 unregisters this effect, since the data would be
   1.411 + *  unchanged.
   1.412 + *
   1.413 + * If you need more precise positional audio, consider using OpenAL for
   1.414 + *  spatialized effects instead of SDL_mixer. This is only meant to be a
   1.415 + *  basic effect for simple "3D" games.
   1.416 + *
   1.417 + * If the audio device is configured for mono output, then you won't get
   1.418 + *  any effectiveness from the angle; however, distance attenuation on the
   1.419 + *  channel will still occur. While this effect will function with stereo
   1.420 + *  voices, it makes more sense to use voices with only one channel of sound,
   1.421 + *  so when they are mixed through this effect, the positioning will sound
   1.422 + *  correct. You can convert them to mono through SDL before giving them to
   1.423 + *  the mixer in the first place if you like.
   1.424 + *
   1.425 + * Setting (channel) to MIX_CHANNEL_POST registers this as a posteffect, and
   1.426 + *  the positioning will be done to the final mixed stream before passing it
   1.427 + *  on to the audio device.
   1.428 + *
   1.429 + * This is a convenience wrapper over Mix_SetDistance() and Mix_SetPanning().
   1.430 + *
   1.431 + * returns zero if error (no such channel or Mix_RegisterEffect() fails),
   1.432 + *  nonzero if position effect is enabled.
   1.433 + *  Error messages can be retrieved from Mix_GetError().
   1.434 + */
   1.435 +extern DECLSPEC int SDLCALL Mix_SetPosition(int channel, Sint16 angle, Uint8 distance);
   1.436 +
   1.437 +
   1.438 +/* Set the "distance" of a channel. (distance) is an integer from 0 to 255
   1.439 + *  that specifies the location of the sound in relation to the listener.
   1.440 + *  Distance 0 is overlapping the listener, and 255 is as far away as possible
   1.441 + *  A distance of 255 does not guarantee silence; in such a case, you might
   1.442 + *  want to try changing the chunk's volume, or just cull the sample from the
   1.443 + *  mixing process with Mix_HaltChannel().
   1.444 + * For efficiency, the precision of this effect may be limited (distances 1
   1.445 + *  through 7 might all produce the same effect, 8 through 15 are equal, etc).
   1.446 + *  (distance) is an integer between 0 and 255 that specifies the space
   1.447 + *  between the sound and the listener. The larger the number, the further
   1.448 + *  away the sound is.
   1.449 + * Setting (distance) to 0 unregisters this effect, since the data would be
   1.450 + *  unchanged.
   1.451 + * If you need more precise positional audio, consider using OpenAL for
   1.452 + *  spatialized effects instead of SDL_mixer. This is only meant to be a
   1.453 + *  basic effect for simple "3D" games.
   1.454 + *
   1.455 + * Setting (channel) to MIX_CHANNEL_POST registers this as a posteffect, and
   1.456 + *  the distance attenuation will be done to the final mixed stream before
   1.457 + *  passing it on to the audio device.
   1.458 + *
   1.459 + * This uses the Mix_RegisterEffect() API internally.
   1.460 + *
   1.461 + * returns zero if error (no such channel or Mix_RegisterEffect() fails),
   1.462 + *  nonzero if position effect is enabled.
   1.463 + *  Error messages can be retrieved from Mix_GetError().
   1.464 + */
   1.465 +extern DECLSPEC int SDLCALL Mix_SetDistance(int channel, Uint8 distance);
   1.466 +
   1.467 +
   1.468 +/*
   1.469 + * !!! FIXME : Haven't implemented, since the effect goes past the
   1.470 + *              end of the sound buffer. Will have to think about this.
   1.471 + *               --ryan.
   1.472 + */
   1.473 +#if 0
   1.474 +/* Causes an echo effect to be mixed into a sound. (echo) is the amount
   1.475 + *  of echo to mix. 0 is no echo, 255 is infinite (and probably not
   1.476 + *  what you want).
   1.477 + *
   1.478 + * Setting (channel) to MIX_CHANNEL_POST registers this as a posteffect, and
   1.479 + *  the reverbing will be done to the final mixed stream before passing it on
   1.480 + *  to the audio device.
   1.481 + *
   1.482 + * This uses the Mix_RegisterEffect() API internally. If you specify an echo
   1.483 + *  of zero, the effect is unregistered, as the data is already in that state.
   1.484 + *
   1.485 + * returns zero if error (no such channel or Mix_RegisterEffect() fails),
   1.486 + *  nonzero if reversing effect is enabled.
   1.487 + *  Error messages can be retrieved from Mix_GetError().
   1.488 + */
   1.489 +extern no_parse_DECLSPEC int SDLCALL Mix_SetReverb(int channel, Uint8 echo);
   1.490 +#endif
   1.491 +
   1.492 +/* Causes a channel to reverse its stereo. This is handy if the user has his
   1.493 + *  speakers hooked up backwards, or you would like to have a minor bit of
   1.494 + *  psychedelia in your sound code.  :)  Calling this function with (flip)
   1.495 + *  set to non-zero reverses the chunks's usual channels. If (flip) is zero,
   1.496 + *  the effect is unregistered.
   1.497 + *
   1.498 + * This uses the Mix_RegisterEffect() API internally, and thus is probably
   1.499 + *  more CPU intensive than having the user just plug in his speakers
   1.500 + *  correctly. Mix_SetReverseStereo() returns without registering the effect
   1.501 + *  function if the audio device is not configured for stereo output.
   1.502 + *
   1.503 + * If you specify MIX_CHANNEL_POST for (channel), then this the effect is used
   1.504 + *  on the final mixed stream before sending it on to the audio device (a
   1.505 + *  posteffect).
   1.506 + *
   1.507 + * returns zero if error (no such channel or Mix_RegisterEffect() fails),
   1.508 + *  nonzero if reversing effect is enabled. Note that an audio device in mono
   1.509 + *  mode is a no-op, but this call will return successful in that case.
   1.510 + *  Error messages can be retrieved from Mix_GetError().
   1.511 + */
   1.512 +extern DECLSPEC int SDLCALL Mix_SetReverseStereo(int channel, int flip);
   1.513 +
   1.514 +/* end of effects API. --ryan. */
   1.515 +
   1.516 +
   1.517 +/* Reserve the first channels (0 -> n-1) for the application, i.e. don't allocate
   1.518 +   them dynamically to the next sample if requested with a -1 value below.
   1.519 +   Returns the number of reserved channels.
   1.520 + */
   1.521 +extern DECLSPEC int SDLCALL Mix_ReserveChannels(int num);
   1.522 +
   1.523 +/* Channel grouping functions */
   1.524 +
   1.525 +/* Attach a tag to a channel. A tag can be assigned to several mixer
   1.526 +   channels, to form groups of channels.
   1.527 +   If 'tag' is -1, the tag is removed (actually -1 is the tag used to
   1.528 +   represent the group of all the channels).
   1.529 +   Returns true if everything was OK.
   1.530 + */
   1.531 +extern DECLSPEC int SDLCALL Mix_GroupChannel(int which, int tag);
   1.532 +/* Assign several consecutive channels to a group */
   1.533 +extern DECLSPEC int SDLCALL Mix_GroupChannels(int from, int to, int tag);
   1.534 +/* Finds the first available channel in a group of channels,
   1.535 +   returning -1 if none are available.
   1.536 + */
   1.537 +extern DECLSPEC int SDLCALL Mix_GroupAvailable(int tag);
   1.538 +/* Returns the number of channels in a group. This is also a subtle
   1.539 +   way to get the total number of channels when 'tag' is -1
   1.540 + */
   1.541 +extern DECLSPEC int SDLCALL Mix_GroupCount(int tag);
   1.542 +/* Finds the "oldest" sample playing in a group of channels */
   1.543 +extern DECLSPEC int SDLCALL Mix_GroupOldest(int tag);
   1.544 +/* Finds the "most recent" (i.e. last) sample playing in a group of channels */
   1.545 +extern DECLSPEC int SDLCALL Mix_GroupNewer(int tag);
   1.546 +
   1.547 +/* Play an audio chunk on a specific channel.
   1.548 +   If the specified channel is -1, play on the first free channel.
   1.549 +   If 'loops' is greater than zero, loop the sound that many times.
   1.550 +   If 'loops' is -1, loop inifinitely (~65000 times).
   1.551 +   Returns which channel was used to play the sound.
   1.552 +*/
   1.553 +#define Mix_PlayChannel(channel,chunk,loops) Mix_PlayChannelTimed(channel,chunk,loops,-1)
   1.554 +/* The same as above, but the sound is played at most 'ticks' milliseconds */
   1.555 +extern DECLSPEC int SDLCALL Mix_PlayChannelTimed(int channel, Mix_Chunk *chunk, int loops, int ticks);
   1.556 +extern DECLSPEC int SDLCALL Mix_PlayMusic(Mix_Music *music, int loops);
   1.557 +
   1.558 +/* Fade in music or a channel over "ms" milliseconds, same semantics as the "Play" functions */
   1.559 +extern DECLSPEC int SDLCALL Mix_FadeInMusic(Mix_Music *music, int loops, int ms);
   1.560 +extern DECLSPEC int SDLCALL Mix_FadeInMusicPos(Mix_Music *music, int loops, int ms, double position);
   1.561 +#define Mix_FadeInChannel(channel,chunk,loops,ms) Mix_FadeInChannelTimed(channel,chunk,loops,ms,-1)
   1.562 +extern DECLSPEC int SDLCALL Mix_FadeInChannelTimed(int channel, Mix_Chunk *chunk, int loops, int ms, int ticks);
   1.563 +
   1.564 +/* Set the volume in the range of 0-128 of a specific channel or chunk.
   1.565 +   If the specified channel is -1, set volume for all channels.
   1.566 +   Returns the original volume.
   1.567 +   If the specified volume is -1, just return the current volume.
   1.568 +*/
   1.569 +extern DECLSPEC int SDLCALL Mix_Volume(int channel, int volume);
   1.570 +extern DECLSPEC int SDLCALL Mix_VolumeChunk(Mix_Chunk *chunk, int volume);
   1.571 +extern DECLSPEC int SDLCALL Mix_VolumeMusic(int volume);
   1.572 +
   1.573 +/* Halt playing of a particular channel */
   1.574 +extern DECLSPEC int SDLCALL Mix_HaltChannel(int channel);
   1.575 +extern DECLSPEC int SDLCALL Mix_HaltGroup(int tag);
   1.576 +extern DECLSPEC int SDLCALL Mix_HaltMusic(void);
   1.577 +
   1.578 +/* Change the expiration delay for a particular channel.
   1.579 +   The sample will stop playing after the 'ticks' milliseconds have elapsed,
   1.580 +   or remove the expiration if 'ticks' is -1
   1.581 +*/
   1.582 +extern DECLSPEC int SDLCALL Mix_ExpireChannel(int channel, int ticks);
   1.583 +
   1.584 +/* Halt a channel, fading it out progressively till it's silent
   1.585 +   The ms parameter indicates the number of milliseconds the fading
   1.586 +   will take.
   1.587 + */
   1.588 +extern DECLSPEC int SDLCALL Mix_FadeOutChannel(int which, int ms);
   1.589 +extern DECLSPEC int SDLCALL Mix_FadeOutGroup(int tag, int ms);
   1.590 +extern DECLSPEC int SDLCALL Mix_FadeOutMusic(int ms);
   1.591 +
   1.592 +/* Query the fading status of a channel */
   1.593 +extern DECLSPEC Mix_Fading SDLCALL Mix_FadingMusic(void);
   1.594 +extern DECLSPEC Mix_Fading SDLCALL Mix_FadingChannel(int which);
   1.595 +
   1.596 +/* Pause/Resume a particular channel */
   1.597 +extern DECLSPEC void SDLCALL Mix_Pause(int channel);
   1.598 +extern DECLSPEC void SDLCALL Mix_Resume(int channel);
   1.599 +extern DECLSPEC int SDLCALL Mix_Paused(int channel);
   1.600 +
   1.601 +/* Pause/Resume the music stream */
   1.602 +extern DECLSPEC void SDLCALL Mix_PauseMusic(void);
   1.603 +extern DECLSPEC void SDLCALL Mix_ResumeMusic(void);
   1.604 +extern DECLSPEC void SDLCALL Mix_RewindMusic(void);
   1.605 +extern DECLSPEC int SDLCALL Mix_PausedMusic(void);
   1.606 +
   1.607 +/* Set the current position in the music stream.
   1.608 +   This returns 0 if successful, or -1 if it failed or isn't implemented.
   1.609 +   This function is only implemented for MOD music formats (set pattern
   1.610 +   order number) and for OGG, FLAC, MP3_MAD, MP3_MPG and MODPLUG music
   1.611 +   (set position in seconds), at the moment.
   1.612 +*/
   1.613 +extern DECLSPEC int SDLCALL Mix_SetMusicPosition(double position);
   1.614 +
   1.615 +/* Check the status of a specific channel.
   1.616 +   If the specified channel is -1, check all channels.
   1.617 +*/
   1.618 +extern DECLSPEC int SDLCALL Mix_Playing(int channel);
   1.619 +extern DECLSPEC int SDLCALL Mix_PlayingMusic(void);
   1.620 +
   1.621 +/* Stop music and set external music playback command */
   1.622 +extern DECLSPEC int SDLCALL Mix_SetMusicCMD(const char *command);
   1.623 +
   1.624 +/* Synchro value is set by MikMod from modules while playing */
   1.625 +extern DECLSPEC int SDLCALL Mix_SetSynchroValue(int value);
   1.626 +extern DECLSPEC int SDLCALL Mix_GetSynchroValue(void);
   1.627 +
   1.628 +/* Set/Get/Iterate SoundFonts paths to use by supported MIDI backends */
   1.629 +extern DECLSPEC int SDLCALL Mix_SetSoundFonts(const char *paths);
   1.630 +extern DECLSPEC const char* SDLCALL Mix_GetSoundFonts(void);
   1.631 +extern DECLSPEC int SDLCALL Mix_EachSoundFont(int (SDLCALL *function)(const char*, void*), void *data);
   1.632 +
   1.633 +/* Get the Mix_Chunk currently associated with a mixer channel
   1.634 +    Returns NULL if it's an invalid channel, or there's no chunk associated.
   1.635 +*/
   1.636 +extern DECLSPEC Mix_Chunk * SDLCALL Mix_GetChunk(int channel);
   1.637 +
   1.638 +/* Close the mixer, halting all playing audio */
   1.639 +extern DECLSPEC void SDLCALL Mix_CloseAudio(void);
   1.640 +
   1.641 +/* We'll use SDL for reporting errors */
   1.642 +#define Mix_SetError    SDL_SetError
   1.643 +#define Mix_GetError    SDL_GetError
   1.644 +#define Mix_ClearError  SDL_ClearError
   1.645 +
   1.646 +/* Ends C function definitions when using C++ */
   1.647 +#ifdef __cplusplus
   1.648 +}
   1.649 +#endif
   1.650 +#include "close_code.h"
   1.651 +
   1.652 +#endif /* SDL_MIXER_H_ */
   1.653 +
   1.654 +/* vi: set ts=4 sw=4 expandtab: */