SDL_mixer.h
author Sam Lantinga <slouken@libsdl.org>
Mon, 12 Nov 2018 16:54:24 -0800
changeset 925 5945988b4a41
parent 915 2e274cefe1db
child 926 d6c9518fb5ee
permissions -rw-r--r--
Fixed bug 4371 - tvOS Simulator devices not listed

Caleb Cornett

In the Xcode-iOS project, when selecting the libSDL_mixer-tvOS target, no tvOS simulators appear in the available device dropdown.

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