include/SDL_mixer.h
author Vitaly Novichkov
Sat, 21 Dec 2019 14:55:28 +0300
changeset 1108 22157ac5cd2d
parent 1090 543b77a3c0eb
child 1109 ee22b0e110b3
permissions -rw-r--r--
SDL_mixer.h: Updated a comment for Mix_LoadMUS_RW() call

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