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