SDL_mixer.h
author Sam Lantinga <slouken@libsdl.org>
Sun, 22 Oct 2017 13:35:44 -0700
changeset 834 4f632d450449
parent 824 dd6b29358ea3
child 835 4285a2d75921
permissions -rw-r--r--
Removed obsolete RCS Id header comment
     1 /*
     2   SDL_mixer:  An audio mixer library based on the SDL library
     3   Copyright (C) 1997-2017 Sam Lantinga <slouken@libsdl.org>
     4 
     5   This software is provided 'as-is', without any express or implied
     6   warranty.  In no event will the authors be held liable for any damages
     7   arising from the use of this software.
     8 
     9   Permission is granted to anyone to use this software for any purpose,
    10   including commercial applications, and to alter it and redistribute it
    11   freely, subject to the following restrictions:
    12 
    13   1. The origin of this software must not be misrepresented; you must not
    14      claim that you wrote the original software. If you use this software
    15      in a product, an acknowledgment in the product documentation would be
    16      appreciated but is not required.
    17   2. Altered source versions must be plainly marked as such, and must not be
    18      misrepresented as being the original software.
    19   3. This notice may not be removed or altered from any source distribution.
    20 */
    21 
    22 #ifndef SDL_MIXER_H_
    23 #define SDL_MIXER_H_
    24 
    25 #include "SDL_stdinc.h"
    26 #include "SDL_rwops.h"
    27 #include "SDL_audio.h"
    28 #include "SDL_endian.h"
    29 #include "SDL_version.h"
    30 #include "begin_code.h"
    31 
    32 /* Set up for C function definitions, even when using C++ */
    33 #ifdef __cplusplus
    34 extern "C" {
    35 #endif
    36 
    37 /* Printable format: "%d.%d.%d", MAJOR, MINOR, PATCHLEVEL
    38 */
    39 #define SDL_MIXER_MAJOR_VERSION 2
    40 #define SDL_MIXER_MINOR_VERSION 0
    41 #define SDL_MIXER_PATCHLEVEL    2
    42 
    43 /* This macro can be used to fill a version structure with the compile-time
    44  * version of the SDL_mixer library.
    45  */
    46 #define SDL_MIXER_VERSION(X)                        \
    47 {                                                   \
    48     (X)->major = SDL_MIXER_MAJOR_VERSION;           \
    49     (X)->minor = SDL_MIXER_MINOR_VERSION;           \
    50     (X)->patch = SDL_MIXER_PATCHLEVEL;              \
    51 }
    52 
    53 /* Backwards compatibility */
    54 #define MIX_MAJOR_VERSION   SDL_MIXER_MAJOR_VERSION
    55 #define MIX_MINOR_VERSION   SDL_MIXER_MINOR_VERSION
    56 #define MIX_PATCHLEVEL      SDL_MIXER_PATCHLEVEL
    57 #define MIX_VERSION(X)      SDL_MIXER_VERSION(X)
    58 
    59 /**
    60  *  This is the version number macro for the current SDL_mixer version.
    61  */
    62 #define SDL_MIXER_COMPILEDVERSION \
    63     SDL_VERSIONNUM(SDL_MIXER_MAJOR_VERSION, SDL_MIXER_MINOR_VERSION, SDL_MIXER_PATCHLEVEL)
    64 
    65 /**
    66  *  This macro will evaluate to true if compiled with SDL_mixer at least X.Y.Z.
    67  */
    68 #define SDL_MIXER_VERSION_ATLEAST(X, Y, Z) \
    69     (SDL_MIXER_COMPILEDVERSION >= SDL_VERSIONNUM(X, Y, Z))
    70 
    71 /* This function gets the version of the dynamically linked SDL_mixer library.
    72    it should NOT be used to fill a version structure, instead you should
    73    use the SDL_MIXER_VERSION() macro.
    74  */
    75 extern DECLSPEC const SDL_version * SDLCALL Mix_Linked_Version(void);
    76 
    77 typedef enum
    78 {
    79     MIX_INIT_FLAC   = 0x00000001,
    80     MIX_INIT_MOD    = 0x00000002,
    81     MIX_INIT_MP3    = 0x00000008,
    82     MIX_INIT_OGG    = 0x00000010,
    83     MIX_INIT_MID    = 0x00000020,
    84 } MIX_InitFlags;
    85 
    86 /* Loads dynamic libraries and prepares them for use.  Flags should be
    87    one or more flags from MIX_InitFlags OR'd together.
    88    It returns the flags successfully initialized, or 0 on failure.
    89  */
    90 extern DECLSPEC int SDLCALL Mix_Init(int flags);
    91 
    92 /* Unloads libraries loaded with Mix_Init */
    93 extern DECLSPEC void SDLCALL Mix_Quit(void);
    94 
    95 
    96 /* The default mixer has 8 simultaneous mixing channels */
    97 #ifndef MIX_CHANNELS
    98 #define MIX_CHANNELS    8
    99 #endif
   100 
   101 /* Good default values for a PC soundcard */
   102 #define MIX_DEFAULT_FREQUENCY   22050
   103 #if SDL_BYTEORDER == SDL_LIL_ENDIAN
   104 #define MIX_DEFAULT_FORMAT  AUDIO_S16LSB
   105 #else
   106 #define MIX_DEFAULT_FORMAT  AUDIO_S16MSB
   107 #endif
   108 #define MIX_DEFAULT_CHANNELS    2
   109 #define MIX_MAX_VOLUME          SDL_MIX_MAXVOLUME /* Volume of a chunk */
   110 
   111 /* The internal format for an audio chunk */
   112 typedef struct Mix_Chunk {
   113     int allocated;
   114     Uint8 *abuf;
   115     Uint32 alen;
   116     Uint8 volume;       /* Per-sample volume, 0-128 */
   117 } Mix_Chunk;
   118 
   119 /* The different fading types supported */
   120 typedef enum {
   121     MIX_NO_FADING,
   122     MIX_FADING_OUT,
   123     MIX_FADING_IN
   124 } Mix_Fading;
   125 
   126 /* These are types of music files (not libraries used to load them) */
   127 typedef enum {
   128     MUS_NONE,
   129     MUS_CMD,
   130     MUS_WAV,
   131     MUS_MOD,
   132     MUS_MID,
   133     MUS_OGG,
   134     MUS_MP3,
   135     MUS_MP3_MAD_UNUSED,
   136     MUS_FLAC,
   137     MUS_MODPLUG_UNUSED
   138 } Mix_MusicType;
   139 
   140 /* The internal format for a music chunk interpreted via mikmod */
   141 typedef struct _Mix_Music Mix_Music;
   142 
   143 /* Open the mixer with a certain audio format */
   144 extern DECLSPEC int SDLCALL Mix_OpenAudio(int frequency, Uint16 format, int channels, int chunksize);
   145 
   146 /* Open the mixer with specific device and certain audio format */
   147 extern DECLSPEC int SDLCALL Mix_OpenAudioDevice(int frequency, Uint16 format, int channels, int chunksize, const char* device, int allowed_changes);
   148 
   149 /* Dynamically change the number of channels managed by the mixer.
   150    If decreasing the number of channels, the upper channels are
   151    stopped.
   152    This function returns the new number of allocated channels.
   153  */
   154 extern DECLSPEC int SDLCALL Mix_AllocateChannels(int numchans);
   155 
   156 /* Find out what the actual audio device parameters are.
   157    This function returns 1 if the audio has been opened, 0 otherwise.
   158  */
   159 extern DECLSPEC int SDLCALL Mix_QuerySpec(int *frequency,Uint16 *format,int *channels);
   160 
   161 /* Load a wave file or a music (.mod .s3m .it .xm) file */
   162 extern DECLSPEC Mix_Chunk * SDLCALL Mix_LoadWAV_RW(SDL_RWops *src, int freesrc);
   163 #define Mix_LoadWAV(file)   Mix_LoadWAV_RW(SDL_RWFromFile(file, "rb"), 1)
   164 extern DECLSPEC Mix_Music * SDLCALL Mix_LoadMUS(const char *file);
   165 
   166 /* Load a music file from an SDL_RWop object (Ogg and MikMod specific currently)
   167    Matt Campbell (matt@campbellhome.dhs.org) April 2000 */
   168 extern DECLSPEC Mix_Music * SDLCALL Mix_LoadMUS_RW(SDL_RWops *src, int freesrc);
   169 
   170 /* Load a music file from an SDL_RWop object assuming a specific format */
   171 extern DECLSPEC Mix_Music * SDLCALL Mix_LoadMUSType_RW(SDL_RWops *src, Mix_MusicType type, int freesrc);
   172 
   173 /* Load a wave file of the mixer format from a memory buffer */
   174 extern DECLSPEC Mix_Chunk * SDLCALL Mix_QuickLoad_WAV(Uint8 *mem);
   175 
   176 /* Load raw audio data of the mixer format from a memory buffer */
   177 extern DECLSPEC Mix_Chunk * SDLCALL Mix_QuickLoad_RAW(Uint8 *mem, Uint32 len);
   178 
   179 /* Free an audio chunk previously loaded */
   180 extern DECLSPEC void SDLCALL Mix_FreeChunk(Mix_Chunk *chunk);
   181 extern DECLSPEC void SDLCALL Mix_FreeMusic(Mix_Music *music);
   182 
   183 /* Get a list of chunk/music decoders that this build of SDL_mixer provides.
   184    This list can change between builds AND runs of the program, if external
   185    libraries that add functionality become available.
   186    You must successfully call Mix_OpenAudio() before calling these functions.
   187    This API is only available in SDL_mixer 1.2.9 and later.
   188 
   189    // usage...
   190    int i;
   191    const int total = Mix_GetNumChunkDecoders();
   192    for (i = 0; i < total; i++)
   193        printf("Supported chunk decoder: [%s]\n", Mix_GetChunkDecoder(i));
   194 
   195    Appearing in this list doesn't promise your specific audio file will
   196    decode...but it's handy to know if you have, say, a functioning Timidity
   197    install.
   198 
   199    These return values are static, read-only data; do not modify or free it.
   200    The pointers remain valid until you call Mix_CloseAudio().
   201 */
   202 extern DECLSPEC int SDLCALL Mix_GetNumChunkDecoders(void);
   203 extern DECLSPEC const char * SDLCALL Mix_GetChunkDecoder(int index);
   204 extern DECLSPEC SDL_bool SDLCALL Mix_HasChunkDecoder(const char *name);
   205 extern DECLSPEC int SDLCALL Mix_GetNumMusicDecoders(void);
   206 extern DECLSPEC const char * SDLCALL Mix_GetMusicDecoder(int index);
   207 extern DECLSPEC SDL_bool SDLCALL Mix_HasMusicDecoder(const char *name);
   208 
   209 /* Find out the music format of a mixer music, or the currently playing
   210    music, if 'music' is NULL.
   211 */
   212 extern DECLSPEC Mix_MusicType SDLCALL Mix_GetMusicType(const Mix_Music *music);
   213 
   214 /* Set a function that is called after all mixing is performed.
   215    This can be used to provide real-time visual display of the audio stream
   216    or add a custom mixer filter for the stream data.
   217 */
   218 extern DECLSPEC void SDLCALL Mix_SetPostMix(void (SDLCALL *mix_func)(void *udata, Uint8 *stream, int len), void *arg);
   219 
   220 /* Add your own music player or additional mixer function.
   221    If 'mix_func' is NULL, the default music player is re-enabled.
   222  */
   223 extern DECLSPEC void SDLCALL Mix_HookMusic(void (SDLCALL *mix_func)(void *udata, Uint8 *stream, int len), void *arg);
   224 
   225 /* Add your own callback for when the music has finished playing or when it is
   226  * stopped from a call to Mix_HaltMusic.
   227  */
   228 extern DECLSPEC void SDLCALL Mix_HookMusicFinished(void (SDLCALL *music_finished)(void));
   229 
   230 /* Get a pointer to the user data for the current music hook */
   231 extern DECLSPEC void * SDLCALL Mix_GetMusicHookData(void);
   232 
   233 /*
   234  * Add your own callback when a channel has finished playing. NULL
   235  *  to disable callback. The callback may be called from the mixer's audio
   236  *  callback or it could be called as a result of Mix_HaltChannel(), etc.
   237  *  do not call SDL_LockAudio() from this callback; you will either be
   238  *  inside the audio callback, or SDL_mixer will explicitly lock the audio
   239  *  before calling your callback.
   240  */
   241 extern DECLSPEC void SDLCALL Mix_ChannelFinished(void (SDLCALL *channel_finished)(int channel));
   242 
   243 
   244 /* Special Effects API by ryan c. gordon. (icculus@icculus.org) */
   245 
   246 #define MIX_CHANNEL_POST  -2
   247 
   248 /* This is the format of a special effect callback:
   249  *
   250  *   myeffect(int chan, void *stream, int len, void *udata);
   251  *
   252  * (chan) is the channel number that your effect is affecting. (stream) is
   253  *  the buffer of data to work upon. (len) is the size of (stream), and
   254  *  (udata) is a user-defined bit of data, which you pass as the last arg of
   255  *  Mix_RegisterEffect(), and is passed back unmolested to your callback.
   256  *  Your effect changes the contents of (stream) based on whatever parameters
   257  *  are significant, or just leaves it be, if you prefer. You can do whatever
   258  *  you like to the buffer, though, and it will continue in its changed state
   259  *  down the mixing pipeline, through any other effect functions, then finally
   260  *  to be mixed with the rest of the channels and music for the final output
   261  *  stream.
   262  *
   263  * DO NOT EVER call SDL_LockAudio() from your callback function!
   264  */
   265 typedef void (SDLCALL *Mix_EffectFunc_t)(int chan, void *stream, int len, void *udata);
   266 
   267 /*
   268  * This is a callback that signifies that a channel has finished all its
   269  *  loops and has completed playback. This gets called if the buffer
   270  *  plays out normally, or if you call Mix_HaltChannel(), implicitly stop
   271  *  a channel via Mix_AllocateChannels(), or unregister a callback while
   272  *  it's still playing.
   273  *
   274  * DO NOT EVER call SDL_LockAudio() from your callback function!
   275  */
   276 typedef void (SDLCALL *Mix_EffectDone_t)(int chan, void *udata);
   277 
   278 
   279 /* Register a special effect function. At mixing time, the channel data is
   280  *  copied into a buffer and passed through each registered effect function.
   281  *  After it passes through all the functions, it is mixed into the final
   282  *  output stream. The copy to buffer is performed once, then each effect
   283  *  function performs on the output of the previous effect. Understand that
   284  *  this extra copy to a buffer is not performed if there are no effects
   285  *  registered for a given chunk, which saves CPU cycles, and any given
   286  *  effect will be extra cycles, too, so it is crucial that your code run
   287  *  fast. Also note that the data that your function is given is in the
   288  *  format of the sound device, and not the format you gave to Mix_OpenAudio(),
   289  *  although they may in reality be the same. This is an unfortunate but
   290  *  necessary speed concern. Use Mix_QuerySpec() to determine if you can
   291  *  handle the data before you register your effect, and take appropriate
   292  *  actions.
   293  * You may also specify a callback (Mix_EffectDone_t) that is called when
   294  *  the channel finishes playing. This gives you a more fine-grained control
   295  *  than Mix_ChannelFinished(), in case you need to free effect-specific
   296  *  resources, etc. If you don't need this, you can specify NULL.
   297  * You may set the callbacks before or after calling Mix_PlayChannel().
   298  * Things like Mix_SetPanning() are just internal special effect functions,
   299  *  so if you are using that, you've already incurred the overhead of a copy
   300  *  to a separate buffer, and that these effects will be in the queue with
   301  *  any functions you've registered. The list of registered effects for a
   302  *  channel is reset when a chunk finishes playing, so you need to explicitly
   303  *  set them with each call to Mix_PlayChannel*().
   304  * You may also register a special effect function that is to be run after
   305  *  final mixing occurs. The rules for these callbacks are identical to those
   306  *  in Mix_RegisterEffect, but they are run after all the channels and the
   307  *  music have been mixed into a single stream, whereas channel-specific
   308  *  effects run on a given channel before any other mixing occurs. These
   309  *  global effect callbacks are call "posteffects". Posteffects only have
   310  *  their Mix_EffectDone_t function called when they are unregistered (since
   311  *  the main output stream is never "done" in the same sense as a channel).
   312  *  You must unregister them manually when you've had enough. Your callback
   313  *  will be told that the channel being mixed is (MIX_CHANNEL_POST) if the
   314  *  processing is considered a posteffect.
   315  *
   316  * After all these effects have finished processing, the callback registered
   317  *  through Mix_SetPostMix() runs, and then the stream goes to the audio
   318  *  device.
   319  *
   320  * DO NOT EVER call SDL_LockAudio() from your callback function!
   321  *
   322  * returns zero if error (no such channel), nonzero if added.
   323  *  Error messages can be retrieved from Mix_GetError().
   324  */
   325 extern DECLSPEC int SDLCALL Mix_RegisterEffect(int chan, Mix_EffectFunc_t f, Mix_EffectDone_t d, void *arg);
   326 
   327 
   328 /* You may not need to call this explicitly, unless you need to stop an
   329  *  effect from processing in the middle of a chunk's playback.
   330  * Posteffects are never implicitly unregistered as they are for channels,
   331  *  but they may be explicitly unregistered through this function by
   332  *  specifying MIX_CHANNEL_POST for a channel.
   333  * returns zero if error (no such channel or effect), nonzero if removed.
   334  *  Error messages can be retrieved from Mix_GetError().
   335  */
   336 extern DECLSPEC int SDLCALL Mix_UnregisterEffect(int channel, Mix_EffectFunc_t f);
   337 
   338 
   339 /* You may not need to call this explicitly, unless you need to stop all
   340  *  effects from processing in the middle of a chunk's playback. Note that
   341  *  this will also shut off some internal effect processing, since
   342  *  Mix_SetPanning() and others may use this API under the hood. This is
   343  *  called internally when a channel completes playback.
   344  * Posteffects are never implicitly unregistered as they are for channels,
   345  *  but they may be explicitly unregistered through this function by
   346  *  specifying MIX_CHANNEL_POST for a channel.
   347  * returns zero if error (no such channel), nonzero if all effects removed.
   348  *  Error messages can be retrieved from Mix_GetError().
   349  */
   350 extern DECLSPEC int SDLCALL Mix_UnregisterAllEffects(int channel);
   351 
   352 
   353 #define MIX_EFFECTSMAXSPEED  "MIX_EFFECTSMAXSPEED"
   354 
   355 /*
   356  * These are the internally-defined mixing effects. They use the same API that
   357  *  effects defined in the application use, but are provided here as a
   358  *  convenience. Some effects can reduce their quality or use more memory in
   359  *  the name of speed; to enable this, make sure the environment variable
   360  *  MIX_EFFECTSMAXSPEED (see above) is defined before you call
   361  *  Mix_OpenAudio().
   362  */
   363 
   364 
   365 /* Set the panning of a channel. The left and right channels are specified
   366  *  as integers between 0 and 255, quietest to loudest, respectively.
   367  *
   368  * Technically, this is just individual volume control for a sample with
   369  *  two (stereo) channels, so it can be used for more than just panning.
   370  *  If you want real panning, call it like this:
   371  *
   372  *   Mix_SetPanning(channel, left, 255 - left);
   373  *
   374  * ...which isn't so hard.
   375  *
   376  * Setting (channel) to MIX_CHANNEL_POST registers this as a posteffect, and
   377  *  the panning will be done to the final mixed stream before passing it on
   378  *  to the audio device.
   379  *
   380  * This uses the Mix_RegisterEffect() API internally, and returns without
   381  *  registering the effect function if the audio device is not configured
   382  *  for stereo output. Setting both (left) and (right) to 255 causes this
   383  *  effect to be unregistered, since that is the data's normal state.
   384  *
   385  * returns zero if error (no such channel or Mix_RegisterEffect() fails),
   386  *  nonzero if panning effect enabled. Note that an audio device in mono
   387  *  mode is a no-op, but this call will return successful in that case.
   388  *  Error messages can be retrieved from Mix_GetError().
   389  */
   390 extern DECLSPEC int SDLCALL Mix_SetPanning(int channel, Uint8 left, Uint8 right);
   391 
   392 
   393 /* Set the position of a channel. (angle) is an integer from 0 to 360, that
   394  *  specifies the location of the sound in relation to the listener. (angle)
   395  *  will be reduced as neccesary (540 becomes 180 degrees, -100 becomes 260).
   396  *  Angle 0 is due north, and rotates clockwise as the value increases.
   397  *  For efficiency, the precision of this effect may be limited (angles 1
   398  *  through 7 might all produce the same effect, 8 through 15 are equal, etc).
   399  *  (distance) is an integer between 0 and 255 that specifies the space
   400  *  between the sound and the listener. The larger the number, the further
   401  *  away the sound is. Using 255 does not guarantee that the channel will be
   402  *  culled from the mixing process or be completely silent. For efficiency,
   403  *  the precision of this effect may be limited (distance 0 through 5 might
   404  *  all produce the same effect, 6 through 10 are equal, etc). Setting (angle)
   405  *  and (distance) to 0 unregisters this effect, since the data would be
   406  *  unchanged.
   407  *
   408  * If you need more precise positional audio, consider using OpenAL for
   409  *  spatialized effects instead of SDL_mixer. This is only meant to be a
   410  *  basic effect for simple "3D" games.
   411  *
   412  * If the audio device is configured for mono output, then you won't get
   413  *  any effectiveness from the angle; however, distance attenuation on the
   414  *  channel will still occur. While this effect will function with stereo
   415  *  voices, it makes more sense to use voices with only one channel of sound,
   416  *  so when they are mixed through this effect, the positioning will sound
   417  *  correct. You can convert them to mono through SDL before giving them to
   418  *  the mixer in the first place if you like.
   419  *
   420  * Setting (channel) to MIX_CHANNEL_POST registers this as a posteffect, and
   421  *  the positioning will be done to the final mixed stream before passing it
   422  *  on to the audio device.
   423  *
   424  * This is a convenience wrapper over Mix_SetDistance() and Mix_SetPanning().
   425  *
   426  * returns zero if error (no such channel or Mix_RegisterEffect() fails),
   427  *  nonzero if position effect is enabled.
   428  *  Error messages can be retrieved from Mix_GetError().
   429  */
   430 extern DECLSPEC int SDLCALL Mix_SetPosition(int channel, Sint16 angle, Uint8 distance);
   431 
   432 
   433 /* Set the "distance" of a channel. (distance) is an integer from 0 to 255
   434  *  that specifies the location of the sound in relation to the listener.
   435  *  Distance 0 is overlapping the listener, and 255 is as far away as possible
   436  *  A distance of 255 does not guarantee silence; in such a case, you might
   437  *  want to try changing the chunk's volume, or just cull the sample from the
   438  *  mixing process with Mix_HaltChannel().
   439  * For efficiency, the precision of this effect may be limited (distances 1
   440  *  through 7 might all produce the same effect, 8 through 15 are equal, etc).
   441  *  (distance) is an integer between 0 and 255 that specifies the space
   442  *  between the sound and the listener. The larger the number, the further
   443  *  away the sound is.
   444  * Setting (distance) to 0 unregisters this effect, since the data would be
   445  *  unchanged.
   446  * If you need more precise positional audio, consider using OpenAL for
   447  *  spatialized effects instead of SDL_mixer. This is only meant to be a
   448  *  basic effect for simple "3D" games.
   449  *
   450  * Setting (channel) to MIX_CHANNEL_POST registers this as a posteffect, and
   451  *  the distance attenuation will be done to the final mixed stream before
   452  *  passing it on to the audio device.
   453  *
   454  * This uses the Mix_RegisterEffect() API internally.
   455  *
   456  * returns zero if error (no such channel or Mix_RegisterEffect() fails),
   457  *  nonzero if position effect is enabled.
   458  *  Error messages can be retrieved from Mix_GetError().
   459  */
   460 extern DECLSPEC int SDLCALL Mix_SetDistance(int channel, Uint8 distance);
   461 
   462 
   463 /*
   464  * !!! FIXME : Haven't implemented, since the effect goes past the
   465  *              end of the sound buffer. Will have to think about this.
   466  *               --ryan.
   467  */
   468 #if 0
   469 /* Causes an echo effect to be mixed into a sound. (echo) is the amount
   470  *  of echo to mix. 0 is no echo, 255 is infinite (and probably not
   471  *  what you want).
   472  *
   473  * Setting (channel) to MIX_CHANNEL_POST registers this as a posteffect, and
   474  *  the reverbing will be done to the final mixed stream before passing it on
   475  *  to the audio device.
   476  *
   477  * This uses the Mix_RegisterEffect() API internally. If you specify an echo
   478  *  of zero, the effect is unregistered, as the data is already in that state.
   479  *
   480  * returns zero if error (no such channel or Mix_RegisterEffect() fails),
   481  *  nonzero if reversing effect is enabled.
   482  *  Error messages can be retrieved from Mix_GetError().
   483  */
   484 extern no_parse_DECLSPEC int SDLCALL Mix_SetReverb(int channel, Uint8 echo);
   485 #endif
   486 
   487 /* Causes a channel to reverse its stereo. This is handy if the user has his
   488  *  speakers hooked up backwards, or you would like to have a minor bit of
   489  *  psychedelia in your sound code.  :)  Calling this function with (flip)
   490  *  set to non-zero reverses the chunks's usual channels. If (flip) is zero,
   491  *  the effect is unregistered.
   492  *
   493  * This uses the Mix_RegisterEffect() API internally, and thus is probably
   494  *  more CPU intensive than having the user just plug in his speakers
   495  *  correctly. Mix_SetReverseStereo() returns without registering the effect
   496  *  function if the audio device is not configured for stereo output.
   497  *
   498  * If you specify MIX_CHANNEL_POST for (channel), then this the effect is used
   499  *  on the final mixed stream before sending it on to the audio device (a
   500  *  posteffect).
   501  *
   502  * returns zero if error (no such channel or Mix_RegisterEffect() fails),
   503  *  nonzero if reversing effect is enabled. Note that an audio device in mono
   504  *  mode is a no-op, but this call will return successful in that case.
   505  *  Error messages can be retrieved from Mix_GetError().
   506  */
   507 extern DECLSPEC int SDLCALL Mix_SetReverseStereo(int channel, int flip);
   508 
   509 /* end of effects API. --ryan. */
   510 
   511 
   512 /* Reserve the first channels (0 -> n-1) for the application, i.e. don't allocate
   513    them dynamically to the next sample if requested with a -1 value below.
   514    Returns the number of reserved channels.
   515  */
   516 extern DECLSPEC int SDLCALL Mix_ReserveChannels(int num);
   517 
   518 /* Channel grouping functions */
   519 
   520 /* Attach a tag to a channel. A tag can be assigned to several mixer
   521    channels, to form groups of channels.
   522    If 'tag' is -1, the tag is removed (actually -1 is the tag used to
   523    represent the group of all the channels).
   524    Returns true if everything was OK.
   525  */
   526 extern DECLSPEC int SDLCALL Mix_GroupChannel(int which, int tag);
   527 /* Assign several consecutive channels to a group */
   528 extern DECLSPEC int SDLCALL Mix_GroupChannels(int from, int to, int tag);
   529 /* Finds the first available channel in a group of channels,
   530    returning -1 if none are available.
   531  */
   532 extern DECLSPEC int SDLCALL Mix_GroupAvailable(int tag);
   533 /* Returns the number of channels in a group. This is also a subtle
   534    way to get the total number of channels when 'tag' is -1
   535  */
   536 extern DECLSPEC int SDLCALL Mix_GroupCount(int tag);
   537 /* Finds the "oldest" sample playing in a group of channels */
   538 extern DECLSPEC int SDLCALL Mix_GroupOldest(int tag);
   539 /* Finds the "most recent" (i.e. last) sample playing in a group of channels */
   540 extern DECLSPEC int SDLCALL Mix_GroupNewer(int tag);
   541 
   542 /* Play an audio chunk on a specific channel.
   543    If the specified channel is -1, play on the first free channel.
   544    If 'loops' is greater than zero, loop the sound that many times.
   545    If 'loops' is -1, loop inifinitely (~65000 times).
   546    Returns which channel was used to play the sound.
   547 */
   548 #define Mix_PlayChannel(channel,chunk,loops) Mix_PlayChannelTimed(channel,chunk,loops,-1)
   549 /* The same as above, but the sound is played at most 'ticks' milliseconds */
   550 extern DECLSPEC int SDLCALL Mix_PlayChannelTimed(int channel, Mix_Chunk *chunk, int loops, int ticks);
   551 extern DECLSPEC int SDLCALL Mix_PlayMusic(Mix_Music *music, int loops);
   552 
   553 /* Fade in music or a channel over "ms" milliseconds, same semantics as the "Play" functions */
   554 extern DECLSPEC int SDLCALL Mix_FadeInMusic(Mix_Music *music, int loops, int ms);
   555 extern DECLSPEC int SDLCALL Mix_FadeInMusicPos(Mix_Music *music, int loops, int ms, double position);
   556 #define Mix_FadeInChannel(channel,chunk,loops,ms) Mix_FadeInChannelTimed(channel,chunk,loops,ms,-1)
   557 extern DECLSPEC int SDLCALL Mix_FadeInChannelTimed(int channel, Mix_Chunk *chunk, int loops, int ms, int ticks);
   558 
   559 /* Set the volume in the range of 0-128 of a specific channel or chunk.
   560    If the specified channel is -1, set volume for all channels.
   561    Returns the original volume.
   562    If the specified volume is -1, just return the current volume.
   563 */
   564 extern DECLSPEC int SDLCALL Mix_Volume(int channel, int volume);
   565 extern DECLSPEC int SDLCALL Mix_VolumeChunk(Mix_Chunk *chunk, int volume);
   566 extern DECLSPEC int SDLCALL Mix_VolumeMusic(int volume);
   567 
   568 /* Halt playing of a particular channel */
   569 extern DECLSPEC int SDLCALL Mix_HaltChannel(int channel);
   570 extern DECLSPEC int SDLCALL Mix_HaltGroup(int tag);
   571 extern DECLSPEC int SDLCALL Mix_HaltMusic(void);
   572 
   573 /* Change the expiration delay for a particular channel.
   574    The sample will stop playing after the 'ticks' milliseconds have elapsed,
   575    or remove the expiration if 'ticks' is -1
   576 */
   577 extern DECLSPEC int SDLCALL Mix_ExpireChannel(int channel, int ticks);
   578 
   579 /* Halt a channel, fading it out progressively till it's silent
   580    The ms parameter indicates the number of milliseconds the fading
   581    will take.
   582  */
   583 extern DECLSPEC int SDLCALL Mix_FadeOutChannel(int which, int ms);
   584 extern DECLSPEC int SDLCALL Mix_FadeOutGroup(int tag, int ms);
   585 extern DECLSPEC int SDLCALL Mix_FadeOutMusic(int ms);
   586 
   587 /* Query the fading status of a channel */
   588 extern DECLSPEC Mix_Fading SDLCALL Mix_FadingMusic(void);
   589 extern DECLSPEC Mix_Fading SDLCALL Mix_FadingChannel(int which);
   590 
   591 /* Pause/Resume a particular channel */
   592 extern DECLSPEC void SDLCALL Mix_Pause(int channel);
   593 extern DECLSPEC void SDLCALL Mix_Resume(int channel);
   594 extern DECLSPEC int SDLCALL Mix_Paused(int channel);
   595 
   596 /* Pause/Resume the music stream */
   597 extern DECLSPEC void SDLCALL Mix_PauseMusic(void);
   598 extern DECLSPEC void SDLCALL Mix_ResumeMusic(void);
   599 extern DECLSPEC void SDLCALL Mix_RewindMusic(void);
   600 extern DECLSPEC int SDLCALL Mix_PausedMusic(void);
   601 
   602 /* Set the current position in the music stream.
   603    This returns 0 if successful, or -1 if it failed or isn't implemented.
   604    This function is only implemented for MOD music formats (set pattern
   605    order number) and for OGG, FLAC, MP3_MAD, MP3_MPG and MODPLUG music
   606    (set position in seconds), at the moment.
   607 */
   608 extern DECLSPEC int SDLCALL Mix_SetMusicPosition(double position);
   609 
   610 /* Check the status of a specific channel.
   611    If the specified channel is -1, check all channels.
   612 */
   613 extern DECLSPEC int SDLCALL Mix_Playing(int channel);
   614 extern DECLSPEC int SDLCALL Mix_PlayingMusic(void);
   615 
   616 /* Stop music and set external music playback command */
   617 extern DECLSPEC int SDLCALL Mix_SetMusicCMD(const char *command);
   618 
   619 /* Synchro value is set by MikMod from modules while playing */
   620 extern DECLSPEC int SDLCALL Mix_SetSynchroValue(int value);
   621 extern DECLSPEC int SDLCALL Mix_GetSynchroValue(void);
   622 
   623 /* Set/Get/Iterate SoundFonts paths to use by supported MIDI backends */
   624 extern DECLSPEC int SDLCALL Mix_SetSoundFonts(const char *paths);
   625 extern DECLSPEC const char* SDLCALL Mix_GetSoundFonts(void);
   626 extern DECLSPEC int SDLCALL Mix_EachSoundFont(int (SDLCALL *function)(const char*, void*), void *data);
   627 
   628 /* Get the Mix_Chunk currently associated with a mixer channel
   629     Returns NULL if it's an invalid channel, or there's no chunk associated.
   630 */
   631 extern DECLSPEC Mix_Chunk * SDLCALL Mix_GetChunk(int channel);
   632 
   633 /* Close the mixer, halting all playing audio */
   634 extern DECLSPEC void SDLCALL Mix_CloseAudio(void);
   635 
   636 /* We'll use SDL for reporting errors */
   637 #define Mix_SetError    SDL_SetError
   638 #define Mix_GetError    SDL_GetError
   639 #define Mix_ClearError  SDL_ClearError
   640 
   641 /* Ends C function definitions when using C++ */
   642 #ifdef __cplusplus
   643 }
   644 #endif
   645 #include "close_code.h"
   646 
   647 #endif /* SDL_MIXER_H_ */
   648 
   649 /* vi: set ts=4 sw=4 expandtab: */