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