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