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