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