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