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