1/*
2 SDL_mixer: An audio mixer library based on the SDL library
3 Copyright (C) 1997-2024 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/**
23 * \file SDL_mixer.h
24 *
25 * Header file for SDL_mixer library
26 *
27 * A simple library to play and mix sounds and musics
28 */
29#ifndef SDL_MIXER_H_
30#define SDL_MIXER_H_
31
32#include "SDL_stdinc.h"
33#include "SDL_rwops.h"
34#include "SDL_audio.h"
35#include "SDL_endian.h"
36#include "SDL_version.h"
37#include "begin_code.h"
38
39/* Set up for C function definitions, even when using C++ */
40#ifdef __cplusplus
41extern "C" {
42#endif
43
44/**
45 * Printable format: "%d.%d.%d", MAJOR, MINOR, PATCHLEVEL
46 */
47#define SDL_MIXER_MAJOR_VERSION 2
48#define SDL_MIXER_MINOR_VERSION 8
49#define SDL_MIXER_PATCHLEVEL 0
50
51/**
52 * This macro can be used to fill a version structure with the compile-time
53 * version of the SDL_mixer library.
54 */
55#define SDL_MIXER_VERSION(X) \
56{ \
57 (X)->major = SDL_MIXER_MAJOR_VERSION; \
58 (X)->minor = SDL_MIXER_MINOR_VERSION; \
59 (X)->patch = SDL_MIXER_PATCHLEVEL; \
60}
61
62/* Backwards compatibility */
63#define MIX_MAJOR_VERSION SDL_MIXER_MAJOR_VERSION
64#define MIX_MINOR_VERSION SDL_MIXER_MINOR_VERSION
65#define MIX_PATCHLEVEL SDL_MIXER_PATCHLEVEL
66#define MIX_VERSION(X) SDL_MIXER_VERSION(X)
67
68#if SDL_MIXER_MAJOR_VERSION < 3 && SDL_MAJOR_VERSION < 3
69/**
70 * This is the version number macro for the current SDL_mixer version.
71 *
72 * In versions higher than 2.9.0, the minor version overflows into
73 * the thousands digit: for example, 2.23.0 is encoded as 4300.
74 * This macro will not be available in SDL 3.x or SDL_mixer 3.x.
75 *
76 * Deprecated, use SDL_MIXER_VERSION_ATLEAST or SDL_MIXER_VERSION instead.
77 */
78#define SDL_MIXER_COMPILEDVERSION \
79 SDL_VERSIONNUM(SDL_MIXER_MAJOR_VERSION, SDL_MIXER_MINOR_VERSION, SDL_MIXER_PATCHLEVEL)
80#endif /* SDL_MIXER_MAJOR_VERSION < 3 && SDL_MAJOR_VERSION < 3 */
81
82/**
83 * This macro will evaluate to true if compiled with SDL_mixer at least X.Y.Z.
84 */
85#define SDL_MIXER_VERSION_ATLEAST(X, Y, Z) \
86 ((SDL_MIXER_MAJOR_VERSION >= X) && \
87 (SDL_MIXER_MAJOR_VERSION > X || SDL_MIXER_MINOR_VERSION >= Y) && \
88 (SDL_MIXER_MAJOR_VERSION > X || SDL_MIXER_MINOR_VERSION > Y || SDL_MIXER_PATCHLEVEL >= Z))
89
90/**
91 * Query the version of SDL_mixer that the program is linked against.
92 *
93 * This function gets the version of the dynamically linked SDL_mixer library.
94 * This is separate from the SDL_MIXER_VERSION() macro, which tells you what
95 * version of the SDL_mixer headers you compiled against.
96 *
97 * This returns static internal data; do not free or modify it!
98 *
99 * \returns a pointer to the version information.
100 *
101 * \since This function is available since SDL_mixer 2.0.0.
102 */
103extern DECLSPEC const SDL_version * SDLCALL Mix_Linked_Version(void);
104
105/**
106 * Initialization flags
107 */
108typedef enum
109{
110 MIX_INIT_FLAC = 0x00000001,
111 MIX_INIT_MOD = 0x00000002,
112 MIX_INIT_MP3 = 0x00000008,
113 MIX_INIT_OGG = 0x00000010,
114 MIX_INIT_MID = 0x00000020,
115 MIX_INIT_OPUS = 0x00000040,
116 MIX_INIT_WAVPACK= 0x00000080
117} MIX_InitFlags;
118
119/**
120 * Initialize SDL_mixer.
121 *
122 * This function loads dynamic libraries that SDL_mixer needs, and prepares
123 * them for use.
124 *
125 * Note that, unlike other SDL libraries, this call is optional! If you load a
126 * music file, SDL_mixer will handle initialization on the fly. This function
127 * will let you know, up front, whether a specific format will be available
128 * for use.
129 *
130 * Flags should be one or more flags from MIX_InitFlags OR'd together. It
131 * returns the flags successfully initialized, or 0 on failure.
132 *
133 * Currently, these flags are:
134 *
135 * - `MIX_INIT_FLAC`
136 * - `MIX_INIT_MOD`
137 * - `MIX_INIT_MP3`
138 * - `MIX_INIT_OGG`
139 * - `MIX_INIT_MID`
140 * - `MIX_INIT_OPUS`
141 * - `MIX_INIT_WAVPACK`
142 *
143 * More flags may be added in a future SDL_mixer release.
144 *
145 * This function may need to load external shared libraries to support various
146 * codecs, which means this function can fail to initialize that support on an
147 * otherwise-reasonable system if the library isn't available; this is not
148 * just a question of exceptional circumstances like running out of memory at
149 * startup!
150 *
151 * Note that you may call this function more than once to initialize with
152 * additional flags. The return value will reflect both new flags that
153 * successfully initialized, and also include flags that had previously been
154 * initialized as well.
155 *
156 * As this will return previously-initialized flags, it's legal to call this
157 * with zero (no flags set). This is a safe no-op that can be used to query
158 * the current initialization state without changing it at all.
159 *
160 * Since this returns previously-initialized flags as well as new ones, and
161 * you can call this with zero, you should not check for a zero return value
162 * to determine an error condition. Instead, you should check to make sure all
163 * the flags you require are set in the return value. If you have a game with
164 * data in a specific format, this might be a fatal error. If you're a generic
165 * media player, perhaps you are fine with only having WAV and MP3 support and
166 * can live without Opus playback, even if you request support for everything.
167 *
168 * Unlike other SDL satellite libraries, calls to Mix_Init do not stack; a
169 * single call to Mix_Quit() will deinitialize everything and does not have to
170 * be paired with a matching Mix_Init call. For that reason, it's considered
171 * best practices to have a single Mix_Init and Mix_Quit call in your program.
172 * While this isn't required, be aware of the risks of deviating from that
173 * behavior.
174 *
175 * After initializing SDL_mixer, the next step is to open an audio device to
176 * prepare to play sound (with Mix_OpenAudio() or Mix_OpenAudioDevice()), and
177 * load audio data to play with that device.
178 *
179 * \param flags initialization flags, OR'd together.
180 * \returns all currently initialized flags.
181 *
182 * \since This function is available since SDL_mixer 2.0.0.
183 *
184 * \sa Mix_Quit
185 */
186extern DECLSPEC int SDLCALL Mix_Init(int flags);
187
188/**
189 * Deinitialize SDL_mixer.
190 *
191 * This should be the last function you call in SDL_mixer, after freeing all
192 * other resources and closing all audio devices. This will unload any shared
193 * libraries it is using for various codecs.
194 *
195 * After this call, a call to Mix_Init(0) will return 0 (no codecs loaded).
196 *
197 * You can safely call Mix_Init() to reload various codec support after this
198 * call.
199 *
200 * Unlike other SDL satellite libraries, calls to Mix_Init do not stack; a
201 * single call to Mix_Quit() will deinitialize everything and does not have to
202 * be paired with a matching Mix_Init call. For that reason, it's considered
203 * best practices to have a single Mix_Init and Mix_Quit call in your program.
204 * While this isn't required, be aware of the risks of deviating from that
205 * behavior.
206 *
207 * \since This function is available since SDL_mixer 2.0.0.
208 *
209 * \sa Mix_Init
210 */
211extern DECLSPEC void SDLCALL Mix_Quit(void);
212
213
214/**
215 * The default mixer has 8 simultaneous mixing channels
216 */
217#ifndef MIX_CHANNELS
218#define MIX_CHANNELS 8
219#endif
220
221/* Good default values for a PC soundcard */
222#define MIX_DEFAULT_FREQUENCY 44100
223#define MIX_DEFAULT_FORMAT AUDIO_S16SYS
224#define MIX_DEFAULT_CHANNELS 2
225#define MIX_MAX_VOLUME SDL_MIX_MAXVOLUME /* Volume of a chunk */
226
227/**
228 * The internal format for an audio chunk
229 */
230typedef struct Mix_Chunk {
231 int allocated;
232 Uint8 *abuf;
233 Uint32 alen;
234 Uint8 volume; /* Per-sample volume, 0-128 */
235} Mix_Chunk;
236
237/**
238 * The different fading types supported
239 */
240typedef enum {
241 MIX_NO_FADING,
242 MIX_FADING_OUT,
243 MIX_FADING_IN
244} Mix_Fading;
245
246/**
247 * These are types of music files (not libraries used to load them)
248 */
249typedef enum {
250 MUS_NONE,
251 MUS_CMD,
252 MUS_WAV,
253 MUS_MOD,
254 MUS_MID,
255 MUS_OGG,
256 MUS_MP3,
257 MUS_MP3_MAD_UNUSED,
258 MUS_FLAC,
259 MUS_MODPLUG_UNUSED,
260 MUS_OPUS,
261 MUS_WAVPACK,
262 MUS_GME
263} Mix_MusicType;
264
265/**
266 * The internal format for a music chunk interpreted via codecs
267 */
268typedef struct _Mix_Music Mix_Music;
269
270/**
271 * Open the default audio device for playback.
272 *
273 * An audio device is what generates sound, so the app must open one to make
274 * noise.
275 *
276 * This function will check if SDL's audio system is initialized, and if not,
277 * it will initialize it by calling `SDL_Init(SDL_INIT_AUDIO)` on your behalf.
278 * You are free to (and encouraged to!) initialize it yourself before calling
279 * this function, as this gives your program more control over the process.
280 *
281 * This function might cover all of an application's needs, but for those that
282 * need more flexibility, the more powerful version of this function is
283 * Mix_OpenAudioDevice(). This function is equivalent to calling:
284 *
285 * ```c
286 * Mix_OpenAudioDevice(frequency, format, nchannels, chunksize, NULL,
287 * SDL_AUDIO_ALLOW_FREQUENCY_CHANGE |
288 * SDL_AUDIO_ALLOW_CHANNELS_CHANGE);
289 * ```
290 *
291 * If you aren't particularly concerned with the specifics of the audio
292 * device, and your data isn't in a specific format, the values you use here
293 * can just be reasonable defaults. SDL_mixer will convert audio data you feed
294 * it to the correct format on demand.
295 *
296 * That being said, if you have control of your audio data and you know its
297 * format ahead of time, you may save CPU time by opening the audio device in
298 * that exact format so SDL_mixer does not have to spend time converting
299 * anything behind the scenes, and can just pass the data straight through to
300 * the hardware. On some platforms, where the hardware only supports specific
301 * settings, you might have to be careful to make everything match, but your
302 * own data is often easier to control, so aim to open the device for what you
303 * need.
304 *
305 * The other reason to care about specific formats: if you plan to touch the
306 * mix buffer directly (with Mix_SetPostMix, a registered effect, or
307 * Mix_HookMusic), you might have code that expects it to be in a specific
308 * format, and you should specify that here.
309 *
310 * The audio device frequency is specified in Hz; in modern times, 48000 is
311 * often a reasonable default.
312 *
313 * The audio device format is one of SDL's AUDIO_* constants. AUDIO_S16SYS
314 * (16-bit audio) is probably a safe default. More modern systems may prefer
315 * AUDIO_F32SYS (32-bit floating point audio).
316 *
317 * The audio device channels are generally 1 for mono output, or 2 for stereo,
318 * but the brave can try surround sound configs with 4 (quad), 6 (5.1), 7
319 * (6.1) or 8 (7.1).
320 *
321 * The audio device's chunk size is the number of sample frames (one sample
322 * per frame for mono output, two samples per frame in a stereo setup, etc)
323 * that are fed to the device at once. The lower the number, the lower the
324 * latency, but you risk dropouts if it gets too low. 2048 is often a
325 * reasonable default, but your app might want to experiment with 1024 or
326 * 4096.
327 *
328 * You may only have one audio device open at a time; if you want to change a
329 * setting, you must close the device and reopen it, which is not something
330 * you can do seamlessly during playback.
331 *
332 * This function does not allow you to select a specific audio device on the
333 * system, it always chooses the best default it can on your behalf (which, in
334 * many cases, is exactly what you want anyhow). If you must choose a specific
335 * device, you can do so with Mix_OpenAudioDevice() instead.
336 *
337 * If this function reports success, you are ready to start making noise! Load
338 * some audio data and start playing!
339 *
340 * The app can use Mix_QuerySpec() to determine the final device settings.
341 *
342 * When done with an audio device, probably at the end of the program, the app
343 * should dispose of the device with Mix_CloseAudio().
344 *
345 * \param frequency the frequency to playback audio at (in Hz).
346 * \param format audio format, one of SDL's AUDIO_* values.
347 * \param channels number of channels (1 is mono, 2 is stereo, etc).
348 * \param chunksize audio buffer size in sample FRAMES (total samples divided
349 * by channel count).
350 * \returns 0 if successful, -1 on error.
351 *
352 * \since This function is available since SDL_mixer 2.0.0.
353 *
354 * \sa Mix_OpenAudioDevice
355 * \sa Mix_CloseAudio
356 */
357extern DECLSPEC int SDLCALL Mix_OpenAudio(int frequency, Uint16 format, int channels, int chunksize);
358
359
360/**
361 * Open a specific audio device for playback.
362 *
363 * (A slightly simpler version of this function is available in
364 * Mix_OpenAudio(), which still might meet most applications' needs.)
365 *
366 * An audio device is what generates sound, so the app must open one to make
367 * noise.
368 *
369 * This function will check if SDL's audio system is initialized, and if not,
370 * it will initialize it by calling `SDL_Init(SDL_INIT_AUDIO)` on your behalf.
371 * You are free to (and encouraged to!) initialize it yourself before calling
372 * this function, as this gives your program more control over the process.
373 *
374 * If you aren't particularly concerned with the specifics of the audio
375 * device, and your data isn't in a specific format, the values you use here
376 * can just be reasonable defaults. SDL_mixer will convert audio data you feed
377 * it to the correct format on demand.
378 *
379 * That being said, if you have control of your audio data and you know its
380 * format ahead of time, you can save CPU time by opening the audio device in
381 * that exact format so SDL_mixer does not have to spend time converting
382 * anything behind the scenes, and can just pass the data straight through to
383 * the hardware. On some platforms, where the hardware only supports specific
384 * settings, you might have to be careful to make everything match, but your
385 * own data is often easier to control, so aim to open the device for what you
386 * need.
387 *
388 * The other reason to care about specific formats: if you plan to touch the
389 * mix buffer directly (with Mix_SetPostMix, a registered effect, or
390 * Mix_HookMusic), you might have code that expects it to be in a specific
391 * format, and you should specify that here.
392 *
393 * The audio device frequency is specified in Hz; in modern times, 48000 is
394 * often a reasonable default.
395 *
396 * The audio device format is one of SDL's AUDIO_* constants. AUDIO_S16SYS
397 * (16-bit audio) is probably a safe default. More modern systems may prefer
398 * AUDIO_F32SYS (32-bit floating point audio).
399 *
400 * The audio device channels are generally 1 for mono output, or 2 for stereo,
401 * but the brave can try surround sound configs with 4 (quad), 6 (5.1), 7
402 * (6.1) or 8 (7.1).
403 *
404 * The audio device's chunk size is the number of sample frames (one sample
405 * per frame for mono output, two samples per frame in a stereo setup, etc)
406 * that are fed to the device at once. The lower the number, the lower the
407 * latency, but you risk dropouts if it gets too low. 2048 is often a
408 * reasonable default, but your app might want to experiment with 1024 or
409 * 4096.
410 *
411 * You may only have one audio device open at a time; if you want to change a
412 * setting, you must close the device and reopen it, which is not something
413 * you can do seamlessly during playback.
414 *
415 * This function allows you to select specific audio hardware on the system
416 * with the `device` parameter. If you specify NULL, SDL_mixer will choose the
417 * best default it can on your behalf (which, in many cases, is exactly what
418 * you want anyhow). SDL_mixer does not offer a mechanism to determine device
419 * names to open, but you can use SDL_GetNumAudioDevices() to get a count of
420 * available devices and then SDL_GetAudioDeviceName() in a loop to obtain a
421 * list. If you do this, be sure to call `SDL_Init(SDL_INIT_AUDIO)` first to
422 * initialize SDL's audio system!
423 *
424 * The `allowed_changes` parameter specifies what settings are flexible. These
425 * are the `SDL_AUDIO_ALLOW_*` flags from SDL. These tell SDL_mixer that the
426 * app doesn't mind if a specific setting changes. For example, the app might
427 * need stereo data in Sint16 format, but if the sample rate or chunk size
428 * changes, the app can handle that. In that case, the app would specify
429 * `SDL_AUDIO_ALLOW_FORMAT_CHANGE|SDL_AUDIO_ALLOW_SAMPLES_CHANGE`. In this
430 * case, if the system's hardware requires something other than the requested
431 * format, SDL_mixer can select what the hardware demands instead of the app.
432 * If the `SDL_AUDIO_ALLOW_` flag is not specified, SDL_mixer must convert
433 * data behind the scenes between what the app demands and what the hardware
434 * requires. If your app needs precisely what is requested, specify zero for
435 * `allowed_changes`.
436 *
437 * If changes were allowed, the app can use Mix_QuerySpec() to determine the
438 * final device settings.
439 *
440 * If this function reports success, you are ready to start making noise! Load
441 * some audio data and start playing!
442 *
443 * When done with an audio device, probably at the end of the program, the app
444 * should dispose of the device with Mix_CloseDevice().
445 *
446 * \param frequency the frequency to playback audio at (in Hz).
447 * \param format audio format, one of SDL's AUDIO_* values.
448 * \param channels number of channels (1 is mono, 2 is stereo, etc).
449 * \param chunksize audio buffer size in sample FRAMES (total samples divided
450 * by channel count).
451 * \param device the device name to open, or NULL to choose a reasonable
452 * default.
453 * \param allowed_changes Allow change flags (see SDL_AUDIO_ALLOW_* flags)
454 * \returns 0 if successful, -1 on error.
455 *
456 * \since This function is available since SDL_mixer 2.0.2.
457 *
458 * \sa Mix_OpenAudio
459 * \sa Mix_CloseDevice
460 * \sa Mix_QuerySpec
461 */
462extern DECLSPEC int SDLCALL Mix_OpenAudioDevice(int frequency, Uint16 format, int channels, int chunksize, const char* device, int allowed_changes);
463
464/**
465 * Suspend or resume the whole audio output.
466 *
467 * \param pause_on 1 to pause audio output, or 0 to resume.
468 *
469 * \since This function is available since SDL_mixer 2.8.0.
470 */
471extern DECLSPEC void SDLCALL Mix_PauseAudio(int pause_on);
472
473/**
474 * Find out what the actual audio device parameters are.
475 *
476 * If Mix_OpenAudioDevice() was called with `allowed_changes` set to anything
477 * but zero, or Mix_OpenAudio() was used, some audio device settings may be
478 * different from the application's request. This function will report what
479 * the device is actually running at.
480 *
481 * Note this is only important if the app intends to touch the audio buffers
482 * being sent to the hardware directly. If an app just wants to play audio
483 * files and let SDL_mixer handle the low-level details, this function can
484 * probably be ignored.
485 *
486 * If the audio device is not opened, this function will return 0.
487 *
488 * \param frequency On return, will be filled with the audio device's
489 * frequency in Hz.
490 * \param format On return, will be filled with the audio device's format.
491 * \param channels On return, will be filled with the audio device's channel
492 * count.
493 * \returns 1 if the audio device has been opened, 0 otherwise.
494 *
495 * \since This function is available since SDL_mixer 2.0.0.
496 *
497 * \sa Mix_OpenAudio
498 * \sa Mix_OpenAudioDevice
499 */
500extern DECLSPEC int SDLCALL Mix_QuerySpec(int *frequency, Uint16 *format, int *channels);
501
502/**
503 * Dynamically change the number of channels managed by the mixer.
504 *
505 * SDL_mixer deals with "channels," which is not the same thing as the
506 * mono/stereo channels; they might be better described as "tracks," as each
507 * one corresponds to a separate source of audio data. Three different WAV
508 * files playing at the same time would be three separate SDL_mixer channels,
509 * for example.
510 *
511 * An app needs as many channels as it has audio data it wants to play
512 * simultaneously, mixing them into a single stream to send to the audio
513 * device.
514 *
515 * SDL_mixer allocates `MIX_CHANNELS` (currently 8) channels when you open an
516 * audio device, which may be more than an app needs, but if the app needs
517 * more or wants less, this function can change it.
518 *
519 * If decreasing the number of channels, any upper channels currently playing
520 * are stopped. This will deregister all effects on those channels and call
521 * any callback specified by Mix_ChannelFinished() for each removed channel.
522 *
523 * If `numchans` is less than zero, this will return the current number of
524 * channels without changing anything.
525 *
526 * \param numchans the new number of channels, or < 0 to query current channel
527 * count.
528 * \returns the new number of allocated channels.
529 *
530 * \since This function is available since SDL_mixer 2.0.0.
531 */
532extern DECLSPEC int SDLCALL Mix_AllocateChannels(int numchans);
533
534/**
535 * Load a supported audio format into a chunk.
536 *
537 * SDL_mixer has two separate data structures for audio data. One it calls a
538 * "chunk," which is meant to be a file completely decoded into memory up
539 * front, and the other it calls "music" which is a file intended to be
540 * decoded on demand. Originally, simple formats like uncompressed WAV files
541 * were meant to be chunks and compressed things, like MP3s, were meant to be
542 * music, and you would stream one thing for a game's music and make repeating
543 * sound effects with the chunks.
544 *
545 * In modern times, this isn't split by format anymore, and most are
546 * interchangeable, so the question is what the app thinks is worth
547 * predecoding or not. Chunks might take more memory, but once they are loaded
548 * won't need to decode again, whereas music always needs to be decoded on the
549 * fly. Also, crucially, there are as many channels for chunks as the app can
550 * allocate, but SDL_mixer only offers a single "music" channel.
551 *
552 * If `freesrc` is non-zero, the RWops will be closed before returning,
553 * whether this function succeeds or not. SDL_mixer reads everything it needs
554 * from the RWops during this call in any case.
555 *
556 * There is a separate function (a macro, before SDL_mixer 2.6.0) to read
557 * files from disk without having to deal with SDL_RWops:
558 * `Mix_LoadWAV("filename.wav")` will call this function and manage those
559 * details for you.
560 *
561 * When done with a chunk, the app should dispose of it with a call to
562 * Mix_FreeChunk().
563 *
564 * \param src an SDL_RWops that data will be read from.
565 * \param freesrc non-zero to close/free the SDL_RWops before returning, zero
566 * to leave it open.
567 * \returns a new chunk, or NULL on error.
568 *
569 * \since This function is available since SDL_mixer 2.6.0 (and as a macro
570 * since 2.0.0).
571 *
572 * \sa Mix_LoadWAV
573 * \sa Mix_FreeChunk
574 */
575extern DECLSPEC Mix_Chunk * SDLCALL Mix_LoadWAV_RW(SDL_RWops *src, int freesrc);
576
577/**
578 * Load a supported audio format into a chunk.
579 *
580 * SDL_mixer has two separate data structures for audio data. One it calls a
581 * "chunk," which is meant to be a file completely decoded into memory up
582 * front, and the other it calls "music" which is a file intended to be
583 * decoded on demand. Originally, simple formats like uncompressed WAV files
584 * were meant to be chunks and compressed things, like MP3s, were meant to be
585 * music, and you would stream one thing for a game's music and make repeating
586 * sound effects with the chunks.
587 *
588 * In modern times, this isn't split by format anymore, and most are
589 * interchangeable, so the question is what the app thinks is worth
590 * predecoding or not. Chunks might take more memory, but once they are loaded
591 * won't need to decode again, whereas music always needs to be decoded on the
592 * fly. Also, crucially, there are as many channels for chunks as the app can
593 * allocate, but SDL_mixer only offers a single "music" channel.
594 *
595 * If you would rather use the abstract SDL_RWops interface to load data from
596 * somewhere other than the filesystem, you can use Mix_LoadWAV_RW() instead.
597 *
598 * When done with a chunk, the app should dispose of it with a call to
599 * Mix_FreeChunk().
600 *
601 * Note that before SDL_mixer 2.6.0, this function was a macro that called
602 * Mix_LoadWAV_RW(), creating a RWops and setting `freesrc` to 1. This macro
603 * has since been promoted to a proper API function. Older binaries linked
604 * against a newer SDL_mixer will still call Mix_LoadWAV_RW directly, as they
605 * are using the macro, which was available since the dawn of time.
606 *
607 * \param file the filesystem path to load data from.
608 * \returns a new chunk, or NULL on error.
609 *
610 * \since This function is available since SDL_mixer 2.6.0 (and as a macro
611 * since 2.0.0).
612 *
613 * \sa Mix_LoadWAV_RW
614 * \sa Mix_FreeChunk
615 */
616extern DECLSPEC Mix_Chunk * SDLCALL Mix_LoadWAV(const char *file);
617
618
619/**
620 * Load a supported audio format into a music object.
621 *
622 * SDL_mixer has two separate data structures for audio data. One it calls a
623 * "chunk," which is meant to be a file completely decoded into memory up
624 * front, and the other it calls "music" which is a file intended to be
625 * decoded on demand. Originally, simple formats like uncompressed WAV files
626 * were meant to be chunks and compressed things, like MP3s, were meant to be
627 * music, and you would stream one thing for a game's music and make repeating
628 * sound effects with the chunks.
629 *
630 * In modern times, this isn't split by format anymore, and most are
631 * interchangeable, so the question is what the app thinks is worth
632 * predecoding or not. Chunks might take more memory, but once they are loaded
633 * won't need to decode again, whereas music always needs to be decoded on the
634 * fly. Also, crucially, there are as many channels for chunks as the app can
635 * allocate, but SDL_mixer only offers a single "music" channel.
636 *
637 * When done with this music, the app should dispose of it with a call to
638 * Mix_FreeMusic().
639 *
640 * \param file a file path from where to load music data.
641 * \returns a new music object, or NULL on error.
642 *
643 * \since This function is available since SDL_mixer 2.0.0.
644 *
645 * \sa Mix_FreeMusic
646 */
647extern DECLSPEC Mix_Music * SDLCALL Mix_LoadMUS(const char *file);
648
649/**
650 * Load a supported audio format into a music object.
651 *
652 * SDL_mixer has two separate data structures for audio data. One it calls a
653 * "chunk," which is meant to be a file completely decoded into memory up
654 * front, and the other it calls "music" which is a file intended to be
655 * decoded on demand. Originally, simple formats like uncompressed WAV files
656 * were meant to be chunks and compressed things, like MP3s, were meant to be
657 * music, and you would stream one thing for a game's music and make repeating
658 * sound effects with the chunks.
659 *
660 * In modern times, this isn't split by format anymore, and most are
661 * interchangeable, so the question is what the app thinks is worth
662 * predecoding or not. Chunks might take more memory, but once they are loaded
663 * won't need to decode again, whereas music always needs to be decoded on the
664 * fly. Also, crucially, there are as many channels for chunks as the app can
665 * allocate, but SDL_mixer only offers a single "music" channel.
666 *
667 * If `freesrc` is non-zero, the RWops will be closed before returning,
668 * whether this function succeeds or not. SDL_mixer reads everything it needs
669 * from the RWops during this call in any case.
670 *
671 * As a convenience, there is a function to read files from disk without
672 * having to deal with SDL_RWops: `Mix_LoadMUS("filename.mp3")` will manage
673 * those details for you.
674 *
675 * This function attempts to guess the file format from incoming data. If the
676 * caller knows the format, or wants to force it, it should use
677 * Mix_LoadMUSType_RW() instead.
678 *
679 * When done with this music, the app should dispose of it with a call to
680 * Mix_FreeMusic().
681 *
682 * \param src an SDL_RWops that data will be read from.
683 * \param freesrc non-zero to close/free the SDL_RWops before returning, zero
684 * to leave it open.
685 * \returns a new music object, or NULL on error.
686 *
687 * \since This function is available since SDL_mixer 2.0.0.
688 *
689 * \sa Mix_FreeMusic
690 */
691extern DECLSPEC Mix_Music * SDLCALL Mix_LoadMUS_RW(SDL_RWops *src, int freesrc);
692
693/**
694 * Load an audio format into a music object, assuming a specific format.
695 *
696 * SDL_mixer has two separate data structures for audio data. One it calls a
697 * "chunk," which is meant to be a file completely decoded into memory up
698 * front, and the other it calls "music" which is a file intended to be
699 * decoded on demand. Originally, simple formats like uncompressed WAV files
700 * were meant to be chunks and compressed things, like MP3s, were meant to be
701 * music, and you would stream one thing for a game's music and make repeating
702 * sound effects with the chunks.
703 *
704 * In modern times, this isn't split by format anymore, and most are
705 * interchangeable, so the question is what the app thinks is worth
706 * predecoding or not. Chunks might take more memory, but once they are loaded
707 * won't need to decode again, whereas music always needs to be decoded on the
708 * fly. Also, crucially, there are as many channels for chunks as the app can
709 * allocate, but SDL_mixer only offers a single "music" channel.
710 *
711 * This function loads music data, and lets the application specify the type
712 * of music being loaded, which might be useful if SDL_mixer cannot figure it
713 * out from the data stream itself.
714 *
715 * Currently, the following types are supported:
716 *
717 * - `MUS_NONE` (SDL_mixer should guess, based on the data)
718 * - `MUS_WAV` (Microsoft WAV files)
719 * - `MUS_MOD` (Various tracker formats)
720 * - `MUS_MID` (MIDI files)
721 * - `MUS_OGG` (Ogg Vorbis files)
722 * - `MUS_MP3` (MP3 files)
723 * - `MUS_FLAC` (FLAC files)
724 * - `MUS_OPUS` (Opus files)
725 * - `MUS_WAVPACK` (WavPack files)
726 *
727 * If `freesrc` is non-zero, the RWops will be closed before returning,
728 * whether this function succeeds or not. SDL_mixer reads everything it needs
729 * from the RWops during this call in any case.
730 *
731 * As a convenience, there is a function to read files from disk without
732 * having to deal with SDL_RWops: `Mix_LoadMUS("filename.mp3")` will manage
733 * those details for you (but not let you specify the music type explicitly)..
734 *
735 * When done with this music, the app should dispose of it with a call to
736 * Mix_FreeMusic().
737 *
738 * \param src an SDL_RWops that data will be read from.
739 * \param type the type of audio data provided by `src`.
740 * \param freesrc non-zero to close/free the SDL_RWops before returning, zero
741 * to leave it open.
742 * \returns a new music object, or NULL on error.
743 *
744 * \since This function is available since SDL_mixer 2.0.0.
745 *
746 * \sa Mix_FreeMusic
747 */
748extern DECLSPEC Mix_Music * SDLCALL Mix_LoadMUSType_RW(SDL_RWops *src, Mix_MusicType type, int freesrc);
749
750/**
751 * Load a WAV file from memory as quickly as possible.
752 *
753 * Unlike Mix_LoadWAV_RW, this function has several requirements, and unless
754 * you control all your audio data and know what you're doing, you should
755 * consider this function unsafe and not use it.
756 *
757 * - The provided audio data MUST be in Microsoft WAV format.
758 * - The provided audio data shouldn't use any strange WAV extensions.
759 * - The audio data MUST be in the exact same format as the audio device. This
760 * function will not attempt to convert it, or even verify it's in the right
761 * format.
762 * - The audio data must be valid; this function does not know the size of the
763 * memory buffer, so if the WAV data is corrupted, it can read past the end
764 * of the buffer, causing a crash.
765 * - The audio data must live at least as long as the returned Mix_Chunk,
766 * because SDL_mixer will use that data directly and not make a copy of it.
767 *
768 * This function will do NO error checking! Be extremely careful here!
769 *
770 * (Seriously, use Mix_LoadWAV_RW instead.)
771 *
772 * If this function is successful, the provided memory buffer must remain
773 * available until Mix_FreeChunk() is called on the returned chunk.
774 *
775 * \param mem memory buffer containing of a WAV file.
776 * \returns a new chunk, or NULL on error.
777 *
778 * \since This function is available since SDL_mixer 2.0.0.
779 *
780 * \sa Mix_LoadWAV_RW
781 * \sa Mix_FreeChunk
782 */
783extern DECLSPEC Mix_Chunk * SDLCALL Mix_QuickLoad_WAV(Uint8 *mem);
784
785/**
786 * Load a raw audio data from memory as quickly as possible.
787 *
788 * The audio data MUST be in the exact same format as the audio device. This
789 * function will not attempt to convert it, or even verify it's in the right
790 * format.
791 *
792 * If this function is successful, the provided memory buffer must remain
793 * available until Mix_FreeChunk() is called on the returned chunk.
794 *
795 * \param mem memory buffer containing raw PCM data.
796 * \param len length of buffer pointed to by `mem`, in bytes.
797 * \returns a new chunk, or NULL on error.
798 *
799 * \since This function is available since SDL_mixer 2.0.0.
800 *
801 * \sa Mix_FreeChunk
802 */
803extern DECLSPEC Mix_Chunk * SDLCALL Mix_QuickLoad_RAW(Uint8 *mem, Uint32 len);
804
805/**
806 * Free an audio chunk.
807 *
808 * An app should call this function when it is done with a Mix_Chunk and wants
809 * to dispose of its resources.
810 *
811 * SDL_mixer will stop any channels this chunk is currently playing on. This
812 * will deregister all effects on those channels and call any callback
813 * specified by Mix_ChannelFinished() for each removed channel.
814 *
815 * \param chunk the chunk to free.
816 *
817 * \since This function is available since SDL_mixer 2.0.0.
818 *
819 * \sa Mix_LoadWAV
820 * \sa Mix_LoadWAV_RW
821 * \sa Mix_QuickLoad_WAV
822 * \sa Mix_QuickLoad_RAW
823 */
824extern DECLSPEC void SDLCALL Mix_FreeChunk(Mix_Chunk *chunk);
825
826/**
827 * Free a music object.
828 *
829 * If this music is currently playing, it will be stopped.
830 *
831 * If this music is in the process of fading out (via Mix_FadeOutMusic()),
832 * this function will *block* until the fade completes. If you need to avoid
833 * this, be sure to call Mix_HaltMusic() before freeing the music.
834 *
835 * \param music the music object to free.
836 *
837 * \since This function is available since SDL_mixer 2.0.0.
838 *
839 * \sa Mix_LoadMUS
840 * \sa Mix_LoadMUS_RW
841 * \sa Mix_LoadMUSType_RW
842 */
843extern DECLSPEC void SDLCALL Mix_FreeMusic(Mix_Music *music);
844
845/**
846 * Get a list of chunk decoders that this build of SDL_mixer provides.
847 *
848 * This list can change between builds AND runs of the program, if external
849 * libraries that add functionality become available. You must successfully
850 * call Mix_OpenAudio() or Mix_OpenAudioDevice() before calling this function,
851 * as decoders are activated at device open time.
852 *
853 * Appearing in this list doesn't promise your specific audio file will
854 * decode...but it's handy to know if you have, say, a functioning Ogg Vorbis
855 * install.
856 *
857 * These return values are static, read-only data; do not modify or free it.
858 * The pointers remain valid until you call Mix_CloseAudio().
859 *
860 * \returns number of chunk decoders available.
861 *
862 * \since This function is available since SDL_mixer 2.0.0.
863 *
864 * \sa Mix_GetChunkDecoder
865 * \sa Mix_HasChunkDecoder
866 */
867extern DECLSPEC int SDLCALL Mix_GetNumChunkDecoders(void);
868
869/**
870 * Get a chunk decoder's name.
871 *
872 * The requested decoder's index must be between zero and
873 * Mix_GetNumChunkDecoders()-1. It's safe to call this with an invalid index;
874 * this function will return NULL in that case.
875 *
876 * This list can change between builds AND runs of the program, if external
877 * libraries that add functionality become available. You must successfully
878 * call Mix_OpenAudio() or Mix_OpenAudioDevice() before calling this function,
879 * as decoders are activated at device open time.
880 *
881 * \param index index of the chunk decoder.
882 * \returns the chunk decoder's name.
883 *
884 * \since This function is available since SDL_mixer 2.0.0.
885 *
886 * \sa Mix_GetNumChunkDecoders
887 */
888extern DECLSPEC const char * SDLCALL Mix_GetChunkDecoder(int index);
889
890/**
891 * Check if a chunk decoder is available by name.
892 *
893 * This result can change between builds AND runs of the program, if external
894 * libraries that add functionality become available. You must successfully
895 * call Mix_OpenAudio() or Mix_OpenAudioDevice() before calling this function,
896 * as decoders are activated at device open time.
897 *
898 * Decoder names are arbitrary but also obvious, so you have to know what
899 * you're looking for ahead of time, but usually it's the file extension in
900 * capital letters (some example names are "AIFF", "VOC", "WAV").
901 *
902 * \param name the decoder name to query.
903 * \returns SDL_TRUE if a decoder by that name is available, SDL_FALSE
904 * otherwise.
905 *
906 * \since This function is available since SDL_mixer 2.0.2.
907 *
908 * \sa Mix_GetNumChunkDecoders
909 * \sa Mix_GetChunkDecoder
910 */
911extern DECLSPEC SDL_bool SDLCALL Mix_HasChunkDecoder(const char *name);
912
913/**
914 * Get a list of music decoders that this build of SDL_mixer provides.
915 *
916 * This list can change between builds AND runs of the program, if external
917 * libraries that add functionality become available. You must successfully
918 * call Mix_OpenAudio() or Mix_OpenAudioDevice() before calling this function,
919 * as decoders are activated at device open time.
920 *
921 * Appearing in this list doesn't promise your specific audio file will
922 * decode...but it's handy to know if you have, say, a functioning Ogg Vorbis
923 * install.
924 *
925 * These return values are static, read-only data; do not modify or free it.
926 * The pointers remain valid until you call Mix_CloseAudio().
927 *
928 * \returns number of music decoders available.
929 *
930 * \since This function is available since SDL_mixer 2.0.0.
931 *
932 * \sa Mix_GetMusicDecoder
933 * \sa Mix_HasMusicDecoder
934 */
935extern DECLSPEC int SDLCALL Mix_GetNumMusicDecoders(void);
936
937/**
938 * Get a music decoder's name.
939 *
940 * The requested decoder's index must be between zero and
941 * Mix_GetNumMusicDecoders()-1. It's safe to call this with an invalid index;
942 * this function will return NULL in that case.
943 *
944 * This list can change between builds AND runs of the program, if external
945 * libraries that add functionality become available. You must successfully
946 * call Mix_OpenAudio() or Mix_OpenAudioDevice() before calling this function,
947 * as decoders are activated at device open time.
948 *
949 * \param index index of the music decoder.
950 * \returns the music decoder's name.
951 *
952 * \since This function is available since SDL_mixer 2.0.0.
953 *
954 * \sa Mix_GetNumMusicDecoders
955 */
956extern DECLSPEC const char * SDLCALL Mix_GetMusicDecoder(int index);
957
958/**
959 * Check if a music decoder is available by name.
960 *
961 * This result can change between builds AND runs of the program, if external
962 * libraries that add functionality become available. You must successfully
963 * call Mix_OpenAudio() or Mix_OpenAudioDevice() before calling this function,
964 * as decoders are activated at device open time.
965 *
966 * Decoder names are arbitrary but also obvious, so you have to know what
967 * you're looking for ahead of time, but usually it's the file extension in
968 * capital letters (some example names are "MOD", "MP3", "FLAC").
969 *
970 * \param name the decoder name to query.
971 * \returns SDL_TRUE if a decoder by that name is available, SDL_FALSE
972 * otherwise.
973 *
974 * \since This function is available since SDL_mixer 2.6.0
975 *
976 * \sa Mix_GetNumMusicDecoders
977 * \sa Mix_GetMusicDecoder
978 */
979extern DECLSPEC SDL_bool SDLCALL Mix_HasMusicDecoder(const char *name);
980
981/**
982 * Find out the format of a mixer music.
983 *
984 * If `music` is NULL, this will query the currently playing music (and return
985 * MUS_NONE if nothing is currently playing).
986 *
987 * \param music the music object to query, or NULL for the currently-playing
988 * music.
989 * \returns the Mix_MusicType for the music object.
990 *
991 * \since This function is available since SDL_mixer 2.0.0
992 */
993extern DECLSPEC Mix_MusicType SDLCALL Mix_GetMusicType(const Mix_Music *music);
994
995/**
996 * Get the title for a music object, or its filename.
997 *
998 * This returns format-specific metadata. Not all file formats supply this!
999 *
1000 * If `music` is NULL, this will query the currently-playing music.
1001 *
1002 * If music's title tag is missing or empty, the filename will be returned. If
1003 * you'd rather have the actual metadata or nothing, use
1004 * Mix_GetMusicTitleTag() instead.
1005 *
1006 * Please note that if the music was loaded from an SDL_RWops instead of a
1007 * filename, the filename returned will be an empty string ("").
1008 *
1009 * This function never returns NULL! If no data is available, it will return
1010 * an empty string ("").
1011 *
1012 * \param music the music object to query, or NULL for the currently-playing
1013 * music.
1014 * \returns the music's title if available, or the filename if not, or "".
1015 *
1016 * \since This function is available since SDL_mixer 2.6.0.
1017 *
1018 * \sa Mix_GetMusicTitleTag
1019 * \sa Mix_GetMusicArtistTag
1020 * \sa Mix_GetMusicAlbumTag
1021 * \sa Mix_GetMusicCopyrightTag
1022 */
1023extern DECLSPEC const char *SDLCALL Mix_GetMusicTitle(const Mix_Music *music);
1024
1025/**
1026 * Get the title for a music object.
1027 *
1028 * This returns format-specific metadata. Not all file formats supply this!
1029 *
1030 * If `music` is NULL, this will query the currently-playing music.
1031 *
1032 * Unlike this function, Mix_GetMusicTitle() produce a string with the music's
1033 * filename if a title isn't available, which might be preferable for some
1034 * applications.
1035 *
1036 * This function never returns NULL! If no data is available, it will return
1037 * an empty string ("").
1038 *
1039 * \param music the music object to query, or NULL for the currently-playing
1040 * music.
1041 * \returns the music's title if available, or "".
1042 *
1043 * \since This function is available since SDL_mixer 2.6.0.
1044 *
1045 * \sa Mix_GetMusicTitle
1046 * \sa Mix_GetMusicArtistTag
1047 * \sa Mix_GetMusicAlbumTag
1048 * \sa Mix_GetMusicCopyrightTag
1049 */
1050extern DECLSPEC const char *SDLCALL Mix_GetMusicTitleTag(const Mix_Music *music);
1051
1052/**
1053 * Get the artist name for a music object.
1054 *
1055 * This returns format-specific metadata. Not all file formats supply this!
1056 *
1057 * If `music` is NULL, this will query the currently-playing music.
1058 *
1059 * This function never returns NULL! If no data is available, it will return
1060 * an empty string ("").
1061 *
1062 * \param music the music object to query, or NULL for the currently-playing
1063 * music.
1064 * \returns the music's artist name if available, or "".
1065 *
1066 * \since This function is available since SDL_mixer 2.6.0.
1067 *
1068 * \sa Mix_GetMusicTitleTag
1069 * \sa Mix_GetMusicAlbumTag
1070 * \sa Mix_GetMusicCopyrightTag
1071 */
1072extern DECLSPEC const char *SDLCALL Mix_GetMusicArtistTag(const Mix_Music *music);
1073
1074/**
1075 * Get the album name for a music object.
1076 *
1077 * This returns format-specific metadata. Not all file formats supply this!
1078 *
1079 * If `music` is NULL, this will query the currently-playing music.
1080 *
1081 * This function never returns NULL! If no data is available, it will return
1082 * an empty string ("").
1083 *
1084 * \param music the music object to query, or NULL for the currently-playing
1085 * music.
1086 * \returns the music's album name if available, or "".
1087 *
1088 * \since This function is available since SDL_mixer 2.6.0.
1089 *
1090 * \sa Mix_GetMusicTitleTag
1091 * \sa Mix_GetMusicArtistTag
1092 * \sa Mix_GetMusicCopyrightTag
1093 */
1094extern DECLSPEC const char *SDLCALL Mix_GetMusicAlbumTag(const Mix_Music *music);
1095
1096/**
1097 * Get the copyright text for a music object.
1098 *
1099 * This returns format-specific metadata. Not all file formats supply this!
1100 *
1101 * If `music` is NULL, this will query the currently-playing music.
1102 *
1103 * This function never returns NULL! If no data is available, it will return
1104 * an empty string ("").
1105 *
1106 * \param music the music object to query, or NULL for the currently-playing
1107 * music.
1108 * \returns the music's copyright text if available, or "".
1109 *
1110 * \since This function is available since SDL_mixer 2.6.0.
1111 *
1112 * \sa Mix_GetMusicTitleTag
1113 * \sa Mix_GetMusicArtistTag
1114 * \sa Mix_GetMusicAlbumTag
1115 */
1116extern DECLSPEC const char *SDLCALL Mix_GetMusicCopyrightTag(const Mix_Music *music);
1117
1118/**
1119 * Set a function that is called after all mixing is performed.
1120 *
1121 * This can be used to provide real-time visual display of the audio stream or
1122 * add a custom mixer filter for the stream data.
1123 *
1124 * The callback will fire every time SDL_mixer is ready to supply more data to
1125 * the audio device, after it has finished all its mixing work. This runs
1126 * inside an SDL audio callback, so it's important that the callback return
1127 * quickly, or there could be problems in the audio playback.
1128 *
1129 * The data provided to the callback is in the format that the audio device
1130 * was opened in, and it represents the exact waveform SDL_mixer has mixed
1131 * from all playing chunks and music for playback. You are allowed to modify
1132 * the data, but it cannot be resized (so you can't add a reverb effect that
1133 * goes past the end of the buffer without saving some state between runs to
1134 * add it into the next callback, or resample the buffer to a smaller size to
1135 * speed it up, etc).
1136 *
1137 * The `arg` pointer supplied here is passed to the callback as-is, for
1138 * whatever the callback might want to do with it (keep track of some ongoing
1139 * state, settings, etc).
1140 *
1141 * Passing a NULL callback disables the post-mix callback until such a time as
1142 * a new one callback is set.
1143 *
1144 * There is only one callback available. If you need to mix multiple inputs,
1145 * be prepared to handle them from a single function.
1146 *
1147 * \param mix_func the callback function to become the new post-mix callback.
1148 * \param arg a pointer that is passed, untouched, to the callback.
1149 *
1150 * \since This function is available since SDL_mixer 2.0.0.
1151 *
1152 * \sa Mix_HookMusic
1153 */
1154extern DECLSPEC void SDLCALL Mix_SetPostMix(void (SDLCALL *mix_func)(void *udata, Uint8 *stream, int len), void *arg);
1155
1156/**
1157 * Add your own music player or additional mixer function.
1158 *
1159 * This works something like Mix_SetPostMix(), but it has some crucial
1160 * differences. Note that an app can use this _and_ Mix_SetPostMix() at the
1161 * same time. This allows an app to replace the built-in music playback,
1162 * either with it's own music decoder or with some sort of
1163 * procedurally-generated audio output.
1164 *
1165 * The supplied callback will fire every time SDL_mixer is preparing to supply
1166 * more data to the audio device. This runs inside an SDL audio callback, so
1167 * it's important that the callback return quickly, or there could be problems
1168 * in the audio playback.
1169 *
1170 * Running this callback is the first thing SDL_mixer will do when starting to
1171 * mix more audio. The buffer will contain silence upon entry, so the callback
1172 * does not need to mix into existing data or initialize the buffer.
1173 *
1174 * Note that while a callback is set through this function, SDL_mixer will not
1175 * mix any playing music; this callback is used instead. To disable this
1176 * callback (and thus reenable built-in music playback) call this function
1177 * with a NULL callback.
1178 *
1179 * The data written to by the callback is in the format that the audio device
1180 * was opened in, and upon return from the callback, SDL_mixer will mix any
1181 * playing chunks (but not music!) into the buffer. The callback cannot resize
1182 * the buffer (so you must be prepared to provide exactly the amount of data
1183 * demanded or leave it as silence).
1184 *
1185 * The `arg` pointer supplied here is passed to the callback as-is, for
1186 * whatever the callback might want to do with it (keep track of some ongoing
1187 * state, settings, etc).
1188 *
1189 * As there is only one music "channel" mixed, there is only one callback
1190 * available. If you need to mix multiple inputs, be prepared to handle them
1191 * from a single function.
1192 *
1193 * \param mix_func the callback function to become the new post-mix callback.
1194 * \param arg a pointer that is passed, untouched, to the callback.
1195 *
1196 * \since This function is available since SDL_mixer 2.0.0.
1197 *
1198 * \sa Mix_SetPostMix
1199 */
1200extern DECLSPEC void SDLCALL Mix_HookMusic(void (SDLCALL *mix_func)(void *udata, Uint8 *stream, int len), void *arg);
1201
1202/**
1203 * Set a callback that runs when a music object has stopped playing.
1204 *
1205 * This callback will fire when the currently-playing music has completed, or
1206 * when it has been explicitly stopped from a call to Mix_HaltMusic. As such,
1207 * this callback might fire from an arbitrary background thread at almost any
1208 * time; try to limit what you do here.
1209 *
1210 * It is legal to start a new music object playing in this callback (or
1211 * restart the one that just stopped). If the music finished normally, this
1212 * can be used to loop the music without a gap in the audio playback.
1213 *
1214 * Do not call SDL_LockAudio() from this callback; you will either be inside
1215 * the audio callback, or SDL_mixer will explicitly lock the audio before
1216 * calling your callback.
1217 *
1218 * A NULL pointer will disable the callback.
1219 *
1220 * \param music_finished the callback function to become the new notification
1221 * mechanism.
1222 *
1223 * \since This function is available since SDL_mixer 2.0.0.
1224 */
1225extern DECLSPEC void SDLCALL Mix_HookMusicFinished(void (SDLCALL *music_finished)(void));
1226
1227/**
1228 * Get a pointer to the user data for the current music hook.
1229 *
1230 * This returns the `arg` pointer last passed to Mix_HookMusic(), or NULL if
1231 * that function has never been called.
1232 *
1233 * \returns pointer to the user data previously passed to Mix_HookMusic.
1234 *
1235 * \since This function is available since SDL_mixer 2.0.0.
1236 */
1237extern DECLSPEC void * SDLCALL Mix_GetMusicHookData(void);
1238
1239/**
1240 * Set a callback that runs when a channel has finished playing.
1241 *
1242 * The callback may be called from the mixer's audio callback or it could be
1243 * called as a result of Mix_HaltChannel(), etc.
1244 *
1245 * The callback has a single parameter, `channel`, which says what mixer
1246 * channel has just stopped.
1247 *
1248 * Do not call SDL_LockAudio() from this callback; you will either be inside
1249 * the audio callback, or SDL_mixer will explicitly lock the audio before
1250 * calling your callback.
1251 *
1252 * A NULL pointer will disable the callback.
1253 *
1254 * \param channel_finished the callback function to become the new
1255 * notification mechanism.
1256 *
1257 * \since This function is available since SDL_mixer 2.0.0.
1258 */
1259extern DECLSPEC void SDLCALL Mix_ChannelFinished(void (SDLCALL *channel_finished)(int channel));
1260
1261
1262#define MIX_CHANNEL_POST (-2)
1263
1264/**
1265 * This is the format of a special effect callback:
1266 *
1267 * myeffect(int chan, void *stream, int len, void *udata);
1268 *
1269 * (chan) is the channel number that your effect is affecting. (stream) is
1270 * the buffer of data to work upon. (len) is the size of (stream), and
1271 * (udata) is a user-defined bit of data, which you pass as the last arg of
1272 * Mix_RegisterEffect(), and is passed back unmolested to your callback.
1273 * Your effect changes the contents of (stream) based on whatever parameters
1274 * are significant, or just leaves it be, if you prefer. You can do whatever
1275 * you like to the buffer, though, and it will continue in its changed state
1276 * down the mixing pipeline, through any other effect functions, then finally
1277 * to be mixed with the rest of the channels and music for the final output
1278 * stream.
1279 *
1280 * DO NOT EVER call SDL_LockAudio() from your callback function!
1281 */
1282typedef void (SDLCALL *Mix_EffectFunc_t)(int chan, void *stream, int len, void *udata);
1283
1284/**
1285 * This is a callback that signifies that a channel has finished all its
1286 * loops and has completed playback. This gets called if the buffer
1287 * plays out normally, or if you call Mix_HaltChannel(), implicitly stop
1288 * a channel via Mix_AllocateChannels(), or unregister a callback while
1289 * it's still playing.
1290 *
1291 * DO NOT EVER call SDL_LockAudio() from your callback function!
1292 */
1293typedef void (SDLCALL *Mix_EffectDone_t)(int chan, void *udata);
1294
1295
1296/**
1297 * Register a special effect function.
1298 *
1299 * At mixing time, the channel data is copied into a buffer and passed through
1300 * each registered effect function. After it passes through all the functions,
1301 * it is mixed into the final output stream. The copy to buffer is performed
1302 * once, then each effect function performs on the output of the previous
1303 * effect. Understand that this extra copy to a buffer is not performed if
1304 * there are no effects registered for a given chunk, which saves CPU cycles,
1305 * and any given effect will be extra cycles, too, so it is crucial that your
1306 * code run fast. Also note that the data that your function is given is in
1307 * the format of the sound device, and not the format you gave to
1308 * Mix_OpenAudio(), although they may in reality be the same. This is an
1309 * unfortunate but necessary speed concern. Use Mix_QuerySpec() to determine
1310 * if you can handle the data before you register your effect, and take
1311 * appropriate actions.
1312 *
1313 * You may also specify a callback (Mix_EffectDone_t) that is called when the
1314 * channel finishes playing. This gives you a more fine-grained control than
1315 * Mix_ChannelFinished(), in case you need to free effect-specific resources,
1316 * etc. If you don't need this, you can specify NULL.
1317 *
1318 * You may set the callbacks before or after calling Mix_PlayChannel().
1319 *
1320 * Things like Mix_SetPanning() are just internal special effect functions, so
1321 * if you are using that, you've already incurred the overhead of a copy to a
1322 * separate buffer, and that these effects will be in the queue with any
1323 * functions you've registered. The list of registered effects for a channel
1324 * is reset when a chunk finishes playing, so you need to explicitly set them
1325 * with each call to Mix_PlayChannel*().
1326 *
1327 * You may also register a special effect function that is to be run after
1328 * final mixing occurs. The rules for these callbacks are identical to those
1329 * in Mix_RegisterEffect, but they are run after all the channels and the
1330 * music have been mixed into a single stream, whereas channel-specific
1331 * effects run on a given channel before any other mixing occurs. These global
1332 * effect callbacks are call "posteffects". Posteffects only have their
1333 * Mix_EffectDone_t function called when they are unregistered (since the main
1334 * output stream is never "done" in the same sense as a channel). You must
1335 * unregister them manually when you've had enough. Your callback will be told
1336 * that the channel being mixed is `MIX_CHANNEL_POST` if the processing is
1337 * considered a posteffect.
1338 *
1339 * After all these effects have finished processing, the callback registered
1340 * through Mix_SetPostMix() runs, and then the stream goes to the audio
1341 * device.
1342 *
1343 * DO NOT EVER call SDL_LockAudio() from your callback function! You are
1344 * already running in the audio thread and the lock is already held!
1345 *
1346 * Note that unlike most SDL and SDL_mixer functions, this function returns
1347 * zero if there's an error, not on success. We apologize for the API design
1348 * inconsistency here.
1349 *
1350 * \param chan the channel to register an effect to, or MIX_CHANNEL_POST.
1351 * \param f effect the callback to run when more of this channel is to be
1352 * mixed.
1353 * \param d effect done callback
1354 * \param arg argument
1355 * \returns zero if error (no such channel), nonzero if added. Error messages
1356 * can be retrieved from Mix_GetError().
1357 *
1358 * \since This function is available since SDL_mixer 2.0.0.
1359 */
1360extern DECLSPEC int SDLCALL Mix_RegisterEffect(int chan, Mix_EffectFunc_t f, Mix_EffectDone_t d, void *arg);
1361
1362
1363/**
1364 * Explicitly unregister a special effect function.
1365 *
1366 * You may not need to call this at all, unless you need to stop an effect
1367 * from processing in the middle of a chunk's playback.
1368 *
1369 * Posteffects are never implicitly unregistered as they are for channels (as
1370 * the output stream does not have an end), but they may be explicitly
1371 * unregistered through this function by specifying MIX_CHANNEL_POST for a
1372 * channel.
1373 *
1374 * Note that unlike most SDL and SDL_mixer functions, this function returns
1375 * zero if there's an error, not on success. We apologize for the API design
1376 * inconsistency here.
1377 *
1378 * \param channel the channel to unregister an effect on, or MIX_CHANNEL_POST.
1379 * \param f effect the callback stop calling in future mixing iterations.
1380 * \returns zero if error (no such channel or effect), nonzero if removed.
1381 * Error messages can be retrieved from Mix_GetError().
1382 *
1383 * \since This function is available since SDL_mixer 2.0.0.
1384 */
1385extern DECLSPEC int SDLCALL Mix_UnregisterEffect(int channel, Mix_EffectFunc_t f);
1386
1387/**
1388 * Explicitly unregister all special effect functions.
1389 *
1390 * You may not need to call this at all, unless you need to stop all effects
1391 * from processing in the middle of a chunk's playback.
1392 *
1393 * Note that this will also shut off some internal effect processing, since
1394 * Mix_SetPanning() and others may use this API under the hood. This is called
1395 * internally when a channel completes playback. Posteffects are never
1396 * implicitly unregistered as they are for channels, but they may be
1397 * explicitly unregistered through this function by specifying
1398 * MIX_CHANNEL_POST for a channel.
1399 *
1400 * Note that unlike most SDL and SDL_mixer functions, this function returns
1401 * zero if there's an error, not on success. We apologize for the API design
1402 * inconsistency here.
1403 *
1404 * \param channel the channel to unregister all effects on, or
1405 * MIX_CHANNEL_POST.
1406 * \returns zero if error (no such channel), nonzero if all effects removed.
1407 * Error messages can be retrieved from Mix_GetError().
1408 *
1409 * \since This function is available since SDL_mixer 2.0.0.
1410 */
1411extern DECLSPEC int SDLCALL Mix_UnregisterAllEffects(int channel);
1412
1413
1414#define MIX_EFFECTSMAXSPEED "MIX_EFFECTSMAXSPEED"
1415
1416/*
1417 * These are the internally-defined mixing effects. They use the same API that
1418 * effects defined in the application use, but are provided here as a
1419 * convenience. Some effects can reduce their quality or use more memory in
1420 * the name of speed; to enable this, make sure the environment variable
1421 * MIX_EFFECTSMAXSPEED (see above) is defined before you call
1422 * Mix_OpenAudio().
1423 */
1424
1425
1426/**
1427 * Set the panning of a channel.
1428 *
1429 * The left and right channels are specified as integers between 0 and 255,
1430 * quietest to loudest, respectively.
1431 *
1432 * Technically, this is just individual volume control for a sample with two
1433 * (stereo) channels, so it can be used for more than just panning. If you
1434 * want real panning, call it like this:
1435 *
1436 * ```c
1437 * Mix_SetPanning(channel, left, 255 - left);
1438 * ```
1439 *
1440 * Setting `channel` to MIX_CHANNEL_POST registers this as a posteffect, and
1441 * the panning will be done to the final mixed stream before passing it on to
1442 * the audio device.
1443 *
1444 * This uses the Mix_RegisterEffect() API internally, and returns without
1445 * registering the effect function if the audio device is not configured for
1446 * stereo output. Setting both `left` and `right` to 255 causes this effect to
1447 * be unregistered, since that is the data's normal state.
1448 *
1449 * Note that an audio device in mono mode is a no-op, but this call will
1450 * return successful in that case. Error messages can be retrieved from
1451 * Mix_GetError().
1452 *
1453 * Note that unlike most SDL and SDL_mixer functions, this function returns
1454 * zero if there's an error, not on success. We apologize for the API design
1455 * inconsistency here.
1456 *
1457 * \param channel The mixer channel to pan or MIX_CHANNEL_POST.
1458 * \param left Volume of stereo left channel, 0 is silence, 255 is full
1459 * volume.
1460 * \param right Volume of stereo right channel, 0 is silence, 255 is full
1461 * volume.
1462 * \returns zero if error (no such channel or Mix_RegisterEffect() fails),
1463 * nonzero if panning effect enabled.
1464 *
1465 * \since This function is available since SDL_mixer 2.0.0.
1466 *
1467 * \sa Mix_SetPosition
1468 * \sa Mix_SetDistance
1469 */
1470extern DECLSPEC int SDLCALL Mix_SetPanning(int channel, Uint8 left, Uint8 right);
1471
1472
1473/**
1474 * Set the position of a channel.
1475 *
1476 * `angle` is an integer from 0 to 360, that specifies the location of the
1477 * sound in relation to the listener. `angle` will be reduced as necessary
1478 * (540 becomes 180 degrees, -100 becomes 260). Angle 0 is due north, and
1479 * rotates clockwise as the value increases. For efficiency, the precision of
1480 * this effect may be limited (angles 1 through 7 might all produce the same
1481 * effect, 8 through 15 are equal, etc). `distance` is an integer between 0
1482 * and 255 that specifies the space between the sound and the listener. The
1483 * larger the number, the further away the sound is. Using 255 does not
1484 * guarantee that the channel will be removed from the mixing process or be
1485 * completely silent. For efficiency, the precision of this effect may be
1486 * limited (distance 0 through 5 might all produce the same effect, 6 through
1487 * 10 are equal, etc). Setting `angle` and `distance` to 0 unregisters this
1488 * effect, since the data would be unchanged.
1489 *
1490 * If you need more precise positional audio, consider using OpenAL for
1491 * spatialized effects instead of SDL_mixer. This is only meant to be a basic
1492 * effect for simple "3D" games.
1493 *
1494 * If the audio device is configured for mono output, then you won't get any
1495 * effectiveness from the angle; however, distance attenuation on the channel
1496 * will still occur. While this effect will function with stereo voices, it
1497 * makes more sense to use voices with only one channel of sound, so when they
1498 * are mixed through this effect, the positioning will sound correct. You can
1499 * convert them to mono through SDL before giving them to the mixer in the
1500 * first place if you like.
1501 *
1502 * Setting the channel to MIX_CHANNEL_POST registers this as a posteffect, and
1503 * the positioning will be done to the final mixed stream before passing it on
1504 * to the audio device.
1505 *
1506 * This is a convenience wrapper over Mix_SetDistance() and Mix_SetPanning().
1507 *
1508 * Note that unlike most SDL and SDL_mixer functions, this function returns
1509 * zero if there's an error, not on success. We apologize for the API design
1510 * inconsistency here.
1511 *
1512 * \param channel The mixer channel to position, or MIX_CHANNEL_POST.
1513 * \param angle angle, in degrees. North is 0, and goes clockwise.
1514 * \param distance distance; 0 is the listener, 255 is maxiumum distance away.
1515 * \returns zero if error (no such channel or Mix_RegisterEffect() fails),
1516 * nonzero if position effect is enabled. Error messages can be
1517 * retrieved from Mix_GetError().
1518 *
1519 * \since This function is available since SDL_mixer 2.0.0.
1520 */
1521extern DECLSPEC int SDLCALL Mix_SetPosition(int channel, Sint16 angle, Uint8 distance);
1522
1523
1524/**
1525 * Set the "distance" of a channel.
1526 *
1527 * `distance` is an integer from 0 to 255 that specifies the location of the
1528 * sound in relation to the listener. Distance 0 is overlapping the listener,
1529 * and 255 is as far away as possible. A distance of 255 does not guarantee
1530 * silence; in such a case, you might want to try changing the chunk's volume,
1531 * or just cull the sample from the mixing process with Mix_HaltChannel(). For
1532 * efficiency, the precision of this effect may be limited (distances 1
1533 * through 7 might all produce the same effect, 8 through 15 are equal, etc).
1534 * (distance) is an integer between 0 and 255 that specifies the space between
1535 * the sound and the listener. The larger the number, the further away the
1536 * sound is. Setting the distance to 0 unregisters this effect, since the data
1537 * would be unchanged. If you need more precise positional audio, consider
1538 * using OpenAL for spatialized effects instead of SDL_mixer. This is only
1539 * meant to be a basic effect for simple "3D" games.
1540 *
1541 * Setting the channel to MIX_CHANNEL_POST registers this as a posteffect, and
1542 * the distance attenuation will be done to the final mixed stream before
1543 * passing it on to the audio device.
1544 *
1545 * This uses the Mix_RegisterEffect() API internally.
1546 *
1547 * Note that unlike most SDL and SDL_mixer functions, this function returns
1548 * zero if there's an error, not on success. We apologize for the API design
1549 * inconsistency here.
1550 *
1551 * \param channel The mixer channel to attenuate, or MIX_CHANNEL_POST.
1552 * \param distance distance; 0 is the listener, 255 is maxiumum distance away.
1553 * \returns zero if error (no such channel or Mix_RegisterEffect() fails),
1554 * nonzero if position effect is enabled. Error messages can be
1555 * retrieved from Mix_GetError().
1556 *
1557 * \since This function is available since SDL_mixer 2.0.0.
1558 */
1559extern DECLSPEC int SDLCALL Mix_SetDistance(int channel, Uint8 distance);
1560
1561
1562/**
1563 * Cause a channel to reverse its stereo.
1564 *
1565 * This is handy if the user has his speakers hooked up backwards, or you
1566 * would like to have a trippy sound effect.
1567 *
1568 * Calling this function with `flip` set to non-zero reverses the chunks's
1569 * usual channels. If `flip` is zero, the effect is unregistered.
1570 *
1571 * This uses the Mix_RegisterEffect() API internally, and thus is probably
1572 * more CPU intensive than having the user just plug in his speakers
1573 * correctly. Mix_SetReverseStereo() returns without registering the effect
1574 * function if the audio device is not configured for stereo output.
1575 *
1576 * If you specify MIX_CHANNEL_POST for `channel`, then this effect is used on
1577 * the final mixed stream before sending it on to the audio device (a
1578 * posteffect).
1579 *
1580 * Note that unlike most SDL and SDL_mixer functions, this function returns
1581 * zero if there's an error, not on success. We apologize for the API design
1582 * inconsistency here.
1583 *
1584 * \param channel The mixer channel to reverse, or MIX_CHANNEL_POST.
1585 * \param flip non-zero to reverse stereo, zero to disable this effect.
1586 * \returns zero if error (no such channel or Mix_RegisterEffect() fails),
1587 * nonzero if reversing effect is enabled. Note that an audio device
1588 * in mono mode is a no-op, but this call will return successful in
1589 * that case. Error messages can be retrieved from Mix_GetError().
1590 *
1591 * \since This function is available since SDL_mixer 2.0.0.
1592 */
1593extern DECLSPEC int SDLCALL Mix_SetReverseStereo(int channel, int flip);
1594
1595/* end of effects API. */
1596
1597
1598
1599/**
1600 * Reserve the first channels for the application.
1601 *
1602 * While SDL_mixer will use up to the number of channels allocated by
1603 * Mix_AllocateChannels(), this sets channels aside that will not be available
1604 * when calling Mix_PlayChannel with a channel of -1 (play on the first unused
1605 * channel). In this case, SDL_mixer will treat reserved channels as "used"
1606 * whether anything is playing on them at the moment or not.
1607 *
1608 * This is useful if you've budgeted some channels for dedicated audio and the
1609 * rest are just used as they are available.
1610 *
1611 * Calling this function will set channels 0 to `n - 1` to be reserved. This
1612 * will not change channel allocations. The number of reserved channels will
1613 * be clamped to the current number allocated.
1614 *
1615 * By default, no channels are reserved.
1616 *
1617 * \param num number of channels to reserve, starting at index zero.
1618 * \returns the number of reserved channels.
1619 *
1620 * \since This function is available since SDL_mixer 2.0.0.
1621 */
1622extern DECLSPEC int SDLCALL Mix_ReserveChannels(int num);
1623
1624
1625/* Channel grouping functions */
1626
1627/**
1628 * Assign a tag to a channel.
1629 *
1630 * A tag is an arbitary number that can be assigned to several mixer channels,
1631 * to form groups of channels.
1632 *
1633 * If 'tag' is -1, the tag is removed (actually -1 is the tag used to
1634 * represent the group of all the channels).
1635 *
1636 * This function replaces the requested channel's current tag; you may only
1637 * have one tag per channel.
1638 *
1639 * You may not specify MAX_CHANNEL_POST for a channel.
1640 *
1641 * \param which the channel to set the tag on.
1642 * \param tag an arbitrary value to assign a channel.
1643 * \returns non-zero on success, zero on error (no such channel).
1644 *
1645 * \since This function is available since SDL_mixer 2.0.0.
1646 */
1647extern DECLSPEC int SDLCALL Mix_GroupChannel(int which, int tag);
1648
1649/**
1650 * Assign several consecutive channels to the same tag.
1651 *
1652 * A tag is an arbitary number that can be assigned to several mixer channels,
1653 * to form groups of channels.
1654 *
1655 * If 'tag' is -1, the tag is removed (actually -1 is the tag used to
1656 * represent the group of all the channels).
1657 *
1658 * This function replaces the requested channels' current tags; you may only
1659 * have one tag per channel.
1660 *
1661 * You may not specify MAX_CHANNEL_POST for a channel.
1662 *
1663 * Note that this returns success and failure in the _opposite_ way from
1664 * Mix_GroupChannel(). We regret the API design mistake.
1665 *
1666 * \param from the first channel to set the tag on.
1667 * \param to the last channel to set the tag on, inclusive.
1668 * \param tag an arbitrary value to assign a channel.
1669 * \returns 0 if successful, negative on error
1670 *
1671 * \since This function is available since SDL_mixer 2.0.0.
1672 */
1673extern DECLSPEC int SDLCALL Mix_GroupChannels(int from, int to, int tag);
1674
1675/**
1676 * Finds the first available channel in a group of channels.
1677 *
1678 * A tag is an arbitary number that can be assigned to several mixer channels,
1679 * to form groups of channels.
1680 *
1681 * This function searches all channels with a specified tag, and returns the
1682 * channel number of the first one it finds that is currently unused.
1683 *
1684 * If no channels with the specified tag are unused, this function returns -1.
1685 *
1686 * \param tag an arbitrary value, assigned to channels, to search for.
1687 * \returns first available channel, or -1 if none are available.
1688 *
1689 * \since This function is available since SDL_mixer 2.0.0.
1690 */
1691extern DECLSPEC int SDLCALL Mix_GroupAvailable(int tag);
1692
1693/**
1694 * Returns the number of channels in a group.
1695 *
1696 * If tag is -1, this will return the total number of channels allocated,
1697 * regardless of what their tag might be.
1698 *
1699 * \param tag an arbitrary value, assigned to channels, to search for.
1700 * \returns the number of channels assigned the specified tag.
1701 *
1702 * \since This function is available since SDL_mixer 2.0.0.
1703 */
1704extern DECLSPEC int SDLCALL Mix_GroupCount(int tag);
1705
1706/**
1707 * Find the "oldest" sample playing in a group of channels.
1708 *
1709 * Specifically, this function returns the channel number that is assigned the
1710 * specified tag, is currently playing, and has the lowest start time, based
1711 * on the value of SDL_GetTicks() when the channel started playing.
1712 *
1713 * If no channel with this tag is currently playing, this function returns -1.
1714 *
1715 * \param tag an arbitrary value, assigned to channels, to search through.
1716 * \returns the "oldest" sample playing in a group of channels
1717 *
1718 * \since This function is available since SDL_mixer 2.0.0.
1719 *
1720 * \sa Mix_GroupNewer
1721 */
1722extern DECLSPEC int SDLCALL Mix_GroupOldest(int tag);
1723
1724/**
1725 * Find the "most recent" sample playing in a group of channels.
1726 *
1727 * Specifically, this function returns the channel number that is assigned the
1728 * specified tag, is currently playing, and has the highest start time, based
1729 * on the value of SDL_GetTicks() when the channel started playing.
1730 *
1731 * If no channel with this tag is currently playing, this function returns -1.
1732 *
1733 * \param tag an arbitrary value, assigned to channels, to search through.
1734 * \returns the "most recent" sample playing in a group of channels
1735 *
1736 * \since This function is available since SDL_mixer 2.0.0.
1737 *
1738 * \sa Mix_GroupOldest
1739 */
1740extern DECLSPEC int SDLCALL Mix_GroupNewer(int tag);
1741
1742/**
1743 * Play an audio chunk on a specific channel.
1744 *
1745 * If the specified channel is -1, play on the first free channel (and return
1746 * -1 without playing anything new if no free channel was available).
1747 *
1748 * If a specific channel was requested, and there is a chunk already playing
1749 * there, that chunk will be halted and the new chunk will take its place.
1750 *
1751 * If `loops` is greater than zero, loop the sound that many times. If `loops`
1752 * is -1, loop "infinitely" (~65000 times).
1753 *
1754 * Note that before SDL_mixer 2.6.0, this function was a macro that called
1755 * Mix_PlayChannelTimed() with a fourth parameter ("ticks") of -1. This
1756 * function still does the same thing, but promotes it to a proper API
1757 * function. Older binaries linked against a newer SDL_mixer will still call
1758 * Mix_PlayChannelTimed directly, as they are using the macro, which was
1759 * available since the dawn of time.
1760 *
1761 * \param channel the channel on which to play the new chunk.
1762 * \param chunk the new chunk to play.
1763 * \param loops the number of times the chunk should loop, -1 to loop (not
1764 * actually) infinitely.
1765 * \returns which channel was used to play the sound, or -1 if sound could not
1766 * be played.
1767 *
1768 * \since This function is available since SDL_mixer 2.6.0 (and as a macro
1769 * since 2.0.0).
1770 */
1771extern DECLSPEC int SDLCALL Mix_PlayChannel(int channel, Mix_Chunk *chunk, int loops);
1772
1773/**
1774 * Play an audio chunk on a specific channel for a maximum time.
1775 *
1776 * If the specified channel is -1, play on the first free channel (and return
1777 * -1 without playing anything new if no free channel was available).
1778 *
1779 * If a specific channel was requested, and there is a chunk already playing
1780 * there, that chunk will be halted and the new chunk will take its place.
1781 *
1782 * If `loops` is greater than zero, loop the sound that many times. If `loops`
1783 * is -1, loop "infinitely" (~65000 times).
1784 *
1785 * `ticks` specifies the maximum number of milliseconds to play this chunk
1786 * before halting it. If you want the chunk to play until all data has been
1787 * mixed, specify -1.
1788 *
1789 * Note that this function does not block for the number of ticks requested;
1790 * it just schedules the chunk to play and notes the maximum for the mixer to
1791 * manage later, and returns immediately.
1792 *
1793 * \param channel the channel on which to play the new chunk.
1794 * \param chunk the new chunk to play.
1795 * \param loops the number of times the chunk should loop, -1 to loop (not
1796 * actually) infinitely.
1797 * \param ticks the maximum number of milliseconds of this chunk to mix for
1798 * playback.
1799 * \returns which channel was used to play the sound, or -1 if sound could not
1800 * be played.
1801 *
1802 * \since This function is available since SDL_mixer 2.0.0.
1803 */
1804extern DECLSPEC int SDLCALL Mix_PlayChannelTimed(int channel, Mix_Chunk *chunk, int loops, int ticks);
1805
1806/**
1807 * Play a new music object.
1808 *
1809 * This will schedule the music object to begin mixing for playback.
1810 *
1811 * There is only ever one music object playing at a time; if this is called
1812 * when another music object is playing, the currently-playing music is halted
1813 * and the new music will replace it.
1814 *
1815 * Please note that if the currently-playing music is in the process of fading
1816 * out (via Mix_FadeOutMusic()), this function will *block* until the fade
1817 * completes. If you need to avoid this, be sure to call Mix_HaltMusic()
1818 * before starting new music.
1819 *
1820 * \param music the new music object to schedule for mixing.
1821 * \param loops the number of loops to play the music for (0 means "play once
1822 * and stop").
1823 * \returns zero on success, -1 on error.
1824 *
1825 * \since This function is available since SDL_mixer 2.0.0.
1826 */
1827extern DECLSPEC int SDLCALL Mix_PlayMusic(Mix_Music *music, int loops);
1828
1829/**
1830 * Play a new music object, fading in the audio.
1831 *
1832 * This will start the new music playing, much like Mix_PlayMusic() will, but
1833 * will start the music playing at silence and fade in to its normal volume
1834 * over the specified number of milliseconds.
1835 *
1836 * If there is already music playing, that music will be halted and the new
1837 * music object will take its place.
1838 *
1839 * If `loops` is greater than zero, loop the music that many times. If `loops`
1840 * is -1, loop "infinitely" (~65000 times).
1841 *
1842 * Fading music will change it's volume progressively, as if Mix_VolumeMusic()
1843 * was called on it (which is to say: you probably shouldn't call
1844 * Mix_VolumeMusic() on fading music).
1845 *
1846 * \param music the new music object to play.
1847 * \param loops the number of times the chunk should loop, -1 to loop (not
1848 * actually) infinitely.
1849 * \param ms the number of milliseconds to spend fading in.
1850 * \returns zero on success, -1 on error.
1851 *
1852 * \since This function is available since SDL_mixer 2.0.0.
1853 */
1854extern DECLSPEC int SDLCALL Mix_FadeInMusic(Mix_Music *music, int loops, int ms);
1855
1856/**
1857 * Play a new music object, fading in the audio, from a starting position.
1858 *
1859 * This will start the new music playing, much like Mix_PlayMusic() will, but
1860 * will start the music playing at silence and fade in to its normal volume
1861 * over the specified number of milliseconds.
1862 *
1863 * If there is already music playing, that music will be halted and the new
1864 * music object will take its place.
1865 *
1866 * If `loops` is greater than zero, loop the music that many times. If `loops`
1867 * is -1, loop "infinitely" (~65000 times).
1868 *
1869 * Fading music will change it's volume progressively, as if Mix_VolumeMusic()
1870 * was called on it (which is to say: you probably shouldn't call
1871 * Mix_VolumeMusic() on fading music).
1872 *
1873 * This function allows the caller to start the music playback past the
1874 * beginning of its audio data. You may specify a start position, in seconds,
1875 * and the playback and fade-in will start there instead of with the first
1876 * samples of the music.
1877 *
1878 * An app can specify a `position` of 0.0 to start at the beginning of the
1879 * music (or just call Mix_FadeInMusic() instead).
1880 *
1881 * To convert from milliseconds, divide by 1000.0.
1882 *
1883 * \param music the new music object to play.
1884 * \param loops the number of times the chunk should loop, -1 to loop (not
1885 * actually) infinitely.
1886 * \param ms the number of milliseconds to spend fading in.
1887 * \param position the start position within the music, in seconds, where
1888 * playback should start.
1889 * \returns zero on success, -1 on error.
1890 *
1891 * \since This function is available since SDL_mixer 2.0.0.
1892 */
1893extern DECLSPEC int SDLCALL Mix_FadeInMusicPos(Mix_Music *music, int loops, int ms, double position);
1894
1895/**
1896 * Play an audio chunk on a specific channel, fading in the audio.
1897 *
1898 * This will start the new sound playing, much like Mix_PlayChannel() will,
1899 * but will start the sound playing at silence and fade in to its normal
1900 * volume over the specified number of milliseconds.
1901 *
1902 * If the specified channel is -1, play on the first free channel (and return
1903 * -1 without playing anything new if no free channel was available).
1904 *
1905 * If a specific channel was requested, and there is a chunk already playing
1906 * there, that chunk will be halted and the new chunk will take its place.
1907 *
1908 * If `loops` is greater than zero, loop the sound that many times. If `loops`
1909 * is -1, loop "infinitely" (~65000 times).
1910 *
1911 * A fading channel will change it's volume progressively, as if Mix_Volume()
1912 * was called on it (which is to say: you probably shouldn't call Mix_Volume()
1913 * on a fading channel).
1914 *
1915 * Note that before SDL_mixer 2.6.0, this function was a macro that called
1916 * Mix_FadeInChannelTimed() with a fourth parameter ("ticks") of -1. This
1917 * function still does the same thing, but promotes it to a proper API
1918 * function. Older binaries linked against a newer SDL_mixer will still call
1919 * Mix_FadeInChannelTimed directly, as they are using the macro, which was
1920 * available since the dawn of time.
1921 *
1922 * \param channel the channel on which to play the new chunk, or -1 to find
1923 * any available.
1924 * \param chunk the new chunk to play.
1925 * \param loops the number of times the chunk should loop, -1 to loop (not
1926 * actually) infinitely.
1927 * \param ms the number of milliseconds to spend fading in.
1928 * \returns which channel was used to play the sound, or -1 if sound could not
1929 * be played.
1930 *
1931 * \since This function is available since SDL_mixer 2.6.0 (and as a macro
1932 * since 2.0.0).
1933 */
1934extern DECLSPEC int SDLCALL Mix_FadeInChannel(int channel, Mix_Chunk *chunk, int loops, int ms);
1935
1936/**
1937 * Play an audio chunk on a specific channel, fading in the audio, for a
1938 * maximum time.
1939 *
1940 * This will start the new sound playing, much like Mix_PlayChannel() will,
1941 * but will start the sound playing at silence and fade in to its normal
1942 * volume over the specified number of milliseconds.
1943 *
1944 * If the specified channel is -1, play on the first free channel (and return
1945 * -1 without playing anything new if no free channel was available).
1946 *
1947 * If a specific channel was requested, and there is a chunk already playing
1948 * there, that chunk will be halted and the new chunk will take its place.
1949 *
1950 * If `loops` is greater than zero, loop the sound that many times. If `loops`
1951 * is -1, loop "infinitely" (~65000 times).
1952 *
1953 * `ticks` specifies the maximum number of milliseconds to play this chunk
1954 * before halting it. If you want the chunk to play until all data has been
1955 * mixed, specify -1.
1956 *
1957 * Note that this function does not block for the number of ticks requested;
1958 * it just schedules the chunk to play and notes the maximum for the mixer to
1959 * manage later, and returns immediately.
1960 *
1961 * A fading channel will change it's volume progressively, as if Mix_Volume()
1962 * was called on it (which is to say: you probably shouldn't call Mix_Volume()
1963 * on a fading channel).
1964 *
1965 * \param channel the channel on which to play the new chunk, or -1 to find
1966 * any available.
1967 * \param chunk the new chunk to play.
1968 * \param loops the number of times the chunk should loop, -1 to loop (not
1969 * actually) infinitely.
1970 * \param ms the number of milliseconds to spend fading in.
1971 * \param ticks the maximum number of milliseconds of this chunk to mix for
1972 * playback.
1973 * \returns which channel was used to play the sound, or -1 if sound could not
1974 * be played.
1975 *
1976 * \since This function is available since SDL_mixer 2.0.0.
1977 */
1978extern DECLSPEC int SDLCALL Mix_FadeInChannelTimed(int channel, Mix_Chunk *chunk, int loops, int ms, int ticks);
1979
1980/**
1981 * Set the volume for a specific channel.
1982 *
1983 * The volume must be between 0 (silence) and MIX_MAX_VOLUME (full volume).
1984 * Note that MIX_MAX_VOLUME is 128. Values greater than MIX_MAX_VOLUME are
1985 * clamped to MIX_MAX_VOLUME.
1986 *
1987 * Specifying a negative volume will not change the current volume; as such,
1988 * this can be used to query the current volume without making changes, as
1989 * this function returns the previous (in this case, still-current) value.
1990 *
1991 * If the specified channel is -1, this function sets the volume for all
1992 * channels, and returns _the average_ of all channels' volumes prior to this
1993 * call.
1994 *
1995 * The default volume for a channel is MIX_MAX_VOLUME (no attenuation).
1996 *
1997 * \param channel the channel on set/query the volume on, or -1 for all
1998 * channels.
1999 * \param volume the new volume, between 0 and MIX_MAX_VOLUME, or -1 to query.
2000 * \returns the previous volume. If the specified volume is -1, this returns
2001 * the current volume. If `channel` is -1, this returns the average
2002 * of all channels.
2003 *
2004 * \since This function is available since SDL_mixer 2.0.0.
2005 */
2006extern DECLSPEC int SDLCALL Mix_Volume(int channel, int volume);
2007
2008/**
2009 * Set the volume for a specific chunk.
2010 *
2011 * In addition to channels having a volume setting, individual chunks also
2012 * maintain a separate volume. Both values are considered when mixing, so both
2013 * affect the final attenuation of the sound. This lets an app adjust the
2014 * volume for all instances of a sound in addition to specific instances of
2015 * that sound.
2016 *
2017 * The volume must be between 0 (silence) and MIX_MAX_VOLUME (full volume).
2018 * Note that MIX_MAX_VOLUME is 128. Values greater than MIX_MAX_VOLUME are
2019 * clamped to MIX_MAX_VOLUME.
2020 *
2021 * Specifying a negative volume will not change the current volume; as such,
2022 * this can be used to query the current volume without making changes, as
2023 * this function returns the previous (in this case, still-current) value.
2024 *
2025 * The default volume for a chunk is MIX_MAX_VOLUME (no attenuation).
2026 *
2027 * \param chunk the chunk whose volume to adjust.
2028 * \param volume the new volume, between 0 and MIX_MAX_VOLUME, or -1 to query.
2029 * \returns the previous volume. If the specified volume is -1, this returns
2030 * the current volume. If `chunk` is NULL, this returns -1.
2031 *
2032 * \since This function is available since SDL_mixer 2.0.0.
2033 */
2034extern DECLSPEC int SDLCALL Mix_VolumeChunk(Mix_Chunk *chunk, int volume);
2035
2036/**
2037 * Set the volume for the music channel.
2038 *
2039 * The volume must be between 0 (silence) and MIX_MAX_VOLUME (full volume).
2040 * Note that MIX_MAX_VOLUME is 128. Values greater than MIX_MAX_VOLUME are
2041 * clamped to MIX_MAX_VOLUME.
2042 *
2043 * Specifying a negative volume will not change the current volume; as such,
2044 * this can be used to query the current volume without making changes, as
2045 * this function returns the previous (in this case, still-current) value.
2046 *
2047 * The default volume for music is MIX_MAX_VOLUME (no attenuation).
2048 *
2049 * \param volume the new volume, between 0 and MIX_MAX_VOLUME, or -1 to query.
2050 * \returns the previous volume. If the specified volume is -1, this returns
2051 * the current volume.
2052 *
2053 * \since This function is available since SDL_mixer 2.0.0.
2054 */
2055extern DECLSPEC int SDLCALL Mix_VolumeMusic(int volume);
2056
2057/**
2058 * Query the current volume value for a music object.
2059 *
2060 * \param music the music object to query.
2061 * \returns the music's current volume, between 0 and MIX_MAX_VOLUME (128).
2062 *
2063 * \since This function is available since SDL_mixer 2.6.0.
2064 */
2065extern DECLSPEC int SDLCALL Mix_GetMusicVolume(Mix_Music *music);
2066
2067/**
2068 * Set the master volume for all channels.
2069 *
2070 * SDL_mixer keeps a per-channel volume, a per-chunk volume, and a master
2071 * volume, and considers all three when mixing audio. This function sets the
2072 * master volume, which is applied to all playing channels when mixing.
2073 *
2074 * The volume must be between 0 (silence) and MIX_MAX_VOLUME (full volume).
2075 * Note that MIX_MAX_VOLUME is 128. Values greater than MIX_MAX_VOLUME are
2076 * clamped to MIX_MAX_VOLUME.
2077 *
2078 * Specifying a negative volume will not change the current volume; as such,
2079 * this can be used to query the current volume without making changes, as
2080 * this function returns the previous (in this case, still-current) value.
2081 *
2082 * Note that the master volume does not affect any playing music; it is only
2083 * applied when mixing chunks. Use Mix_MusicVolume() for that.\
2084 *
2085 * \param volume the new volume, between 0 and MIX_MAX_VOLUME, or -1 to query.
2086 * \returns the previous volume. If the specified volume is -1, this returns
2087 * the current volume.
2088 *
2089 * \since This function is available since SDL_mixer 2.6.0.
2090 */
2091extern DECLSPEC int SDLCALL Mix_MasterVolume(int volume);
2092
2093/**
2094 * Halt playing of a particular channel.
2095 *
2096 * This will stop further playback on that channel until a new chunk is
2097 * started there.
2098 *
2099 * Specifying a channel of -1 will halt _all_ channels, except for any playing
2100 * music.
2101 *
2102 * Any halted channels will have any currently-registered effects
2103 * deregistered, and will call any callback specified by Mix_ChannelFinished()
2104 * before this function returns.
2105 *
2106 * You may not specify MAX_CHANNEL_POST for a channel.
2107 *
2108 * \param channel channel to halt, or -1 to halt all channels.
2109 * \returns 0 on success, or -1 on error.
2110 *
2111 * \since This function is available since SDL_mixer 2.0.0.
2112 */
2113extern DECLSPEC int SDLCALL Mix_HaltChannel(int channel);
2114
2115/**
2116 * Halt playing of a group of channels by arbitrary tag.
2117 *
2118 * This will stop further playback on all channels with a specific tag, until
2119 * a new chunk is started there.
2120 *
2121 * A tag is an arbitrary number that can be assigned to several mixer
2122 * channels, to form groups of channels.
2123 *
2124 * The default tag for a channel is -1.
2125 *
2126 * Any halted channels will have any currently-registered effects
2127 * deregistered, and will call any callback specified by Mix_ChannelFinished()
2128 * before this function returns.
2129 *
2130 * \param tag an arbitrary value, assigned to channels, to search for.
2131 * \returns zero, whether any channels were halted or not.
2132 *
2133 * \since This function is available since SDL_mixer 2.0.0.
2134 */
2135extern DECLSPEC int SDLCALL Mix_HaltGroup(int tag);
2136
2137/**
2138 * Halt playing of the music stream.
2139 *
2140 * This will stop further playback of music until a new music object is
2141 * started there.
2142 *
2143 * Any halted music will call any callback specified by
2144 * Mix_HookMusicFinished() before this function returns.
2145 *
2146 * \returns zero, regardless of whether any music was halted.
2147 *
2148 * \since This function is available since SDL_mixer 2.0.0.
2149 */
2150extern DECLSPEC int SDLCALL Mix_HaltMusic(void);
2151
2152/**
2153 * Change the expiration delay for a particular channel.
2154 *
2155 * The channel will halt after the 'ticks' milliseconds have elapsed, or
2156 * remove the expiration if 'ticks' is -1.
2157 *
2158 * This overrides the value passed to the fourth parameter of
2159 * Mix_PlayChannelTimed().
2160 *
2161 * Specifying a channel of -1 will set an expiration for _all_ channels.
2162 *
2163 * Any halted channels will have any currently-registered effects
2164 * deregistered, and will call any callback specified by Mix_ChannelFinished()
2165 * once the halt occurs.
2166 *
2167 * Note that this function does not block for the number of ticks requested;
2168 * it just schedules the chunk to expire and notes the time for the mixer to
2169 * manage later, and returns immediately.
2170 *
2171 * \param channel the channel to change the expiration time on.
2172 * \param ticks number of milliseconds from now to let channel play before
2173 * halting, -1 to not halt.
2174 * \returns the number of channels that changed expirations.
2175 *
2176 * \since This function is available since SDL_mixer 2.0.0.
2177 */
2178extern DECLSPEC int SDLCALL Mix_ExpireChannel(int channel, int ticks);
2179
2180/**
2181 * Halt a channel after fading it out for a specified time.
2182 *
2183 * This will begin a channel fading from its current volume to silence over
2184 * `ms` milliseconds. After that time, the channel is halted.
2185 *
2186 * Any halted channels will have any currently-registered effects
2187 * deregistered, and will call any callback specified by Mix_ChannelFinished()
2188 * once the halt occurs.
2189 *
2190 * A fading channel will change it's volume progressively, as if Mix_Volume()
2191 * was called on it (which is to say: you probably shouldn't call Mix_Volume()
2192 * on a fading channel).
2193 *
2194 * Note that this function does not block for the number of milliseconds
2195 * requested; it just schedules the chunk to fade and notes the time for the
2196 * mixer to manage later, and returns immediately.
2197 *
2198 * \param which the channel to fade out.
2199 * \param ms number of milliseconds to fade before halting the channel.
2200 * \returns the number of channels scheduled to fade.
2201 *
2202 * \since This function is available since SDL_mixer 2.0.0.
2203 */
2204extern DECLSPEC int SDLCALL Mix_FadeOutChannel(int which, int ms);
2205
2206/**
2207 * Halt a playing group of channels by arbitrary tag, after fading them out
2208 * for a specified time.
2209 *
2210 * This will begin fading a group of channels with a specific tag from their
2211 * current volumes to silence over `ms` milliseconds. After that time, those
2212 * channels are halted.
2213 *
2214 * A tag is an arbitrary number that can be assigned to several mixer
2215 * channels, to form groups of channels.
2216 *
2217 * The default tag for a channel is -1.
2218 *
2219 * Any halted channels will have any currently-registered effects
2220 * deregistered, and will call any callback specified by Mix_ChannelFinished()
2221 * once the halt occurs.
2222 *
2223 * A fading channel will change it's volume progressively, as if Mix_Volume()
2224 * was called on it (which is to say: you probably shouldn't call Mix_Volume()
2225 * on a fading channel).
2226 *
2227 * Note that this function does not block for the number of milliseconds
2228 * requested; it just schedules the group to fade and notes the time for the
2229 * mixer to manage later, and returns immediately.
2230 *
2231 * \param tag an arbitrary value, assigned to channels, to search for.
2232 * \param ms number of milliseconds to fade before halting the group.
2233 * \returns the number of channels that were scheduled for fading.
2234 *
2235 * \since This function is available since SDL_mixer 2.0.0.
2236 */
2237extern DECLSPEC int SDLCALL Mix_FadeOutGroup(int tag, int ms);
2238
2239/**
2240 * Halt the music stream after fading it out for a specified time.
2241 *
2242 * This will begin the music fading from its current volume to silence over
2243 * `ms` milliseconds. After that time, the music is halted.
2244 *
2245 * Any halted music will call any callback specified by
2246 * Mix_HookMusicFinished() once the halt occurs.
2247 *
2248 * Fading music will change it's volume progressively, as if Mix_VolumeMusic()
2249 * was called on it (which is to say: you probably shouldn't call
2250 * Mix_VolumeMusic() on a fading channel).
2251 *
2252 * Note that this function does not block for the number of milliseconds
2253 * requested; it just schedules the music to fade and notes the time for the
2254 * mixer to manage later, and returns immediately.
2255 *
2256 * \param ms number of milliseconds to fade before halting the channel.
2257 * \returns non-zero if music was scheduled to fade, zero otherwise. If no
2258 * music is currently playing, this returns zero.
2259 *
2260 * \since This function is available since SDL_mixer 2.0.0.
2261 */
2262extern DECLSPEC int SDLCALL Mix_FadeOutMusic(int ms);
2263
2264/**
2265 * Query the fading status of the music stream.
2266 *
2267 * This reports one of three values:
2268 *
2269 * - `MIX_NO_FADING`
2270 * - `MIX_FADING_OUT`
2271 * - `MIX_FADING_IN`
2272 *
2273 * If music is not currently playing, this returns `MIX_NO_FADING`.
2274 *
2275 * \returns the current fading status of the music stream.
2276 *
2277 * \since This function is available since SDL_mixer 2.0.0.
2278 */
2279extern DECLSPEC Mix_Fading SDLCALL Mix_FadingMusic(void);
2280
2281/**
2282 * Query the fading status of a channel.
2283 *
2284 * This reports one of three values:
2285 *
2286 * - `MIX_NO_FADING`
2287 * - `MIX_FADING_OUT`
2288 * - `MIX_FADING_IN`
2289 *
2290 * If nothing is currently playing on the channel, or an invalid channel is
2291 * specified, this returns `MIX_NO_FADING`.
2292 *
2293 * You may not specify MAX_CHANNEL_POST for a channel.
2294 *
2295 * You may not specify -1 for all channels; only individual channels may be
2296 * queried.
2297 *
2298 * \param which the channel to query.
2299 * \returns the current fading status of the channel.
2300 *
2301 * \since This function is available since SDL_mixer 2.0.0.
2302 */
2303extern DECLSPEC Mix_Fading SDLCALL Mix_FadingChannel(int which);
2304
2305/**
2306 * Pause a particular channel.
2307 *
2308 * Pausing a channel will prevent further playback of the assigned chunk but
2309 * will maintain the chunk's current mixing position. When resumed, this
2310 * channel will continue to mix the chunk where it left off.
2311 *
2312 * A paused channel can be resumed by calling Mix_Resume().
2313 *
2314 * A paused channel with an expiration will not expire while paused (the
2315 * expiration countdown will be adjusted once resumed).
2316 *
2317 * It is legal to halt a paused channel. Playing a new chunk on a paused
2318 * channel will replace the current chunk and unpause the channel.
2319 *
2320 * Specifying a channel of -1 will pause _all_ channels. Any music is
2321 * unaffected.
2322 *
2323 * You may not specify MAX_CHANNEL_POST for a channel.
2324 *
2325 * \param channel the channel to pause, or -1 to pause all channels.
2326 *
2327 * \since This function is available since SDL_mixer 2.0.0.
2328 */
2329extern DECLSPEC void SDLCALL Mix_Pause(int channel);
2330
2331/**
2332 * Resume a particular channel.
2333 *
2334 * It is legal to resume an unpaused or invalid channel; it causes no effect
2335 * and reports no error.
2336 *
2337 * If the paused channel has an expiration, its expiration countdown resumes
2338 * now, as well.
2339 *
2340 * Specifying a channel of -1 will resume _all_ paused channels. Any music is
2341 * unaffected.
2342 *
2343 * \param channel the channel to resume, or -1 to resume all paused channels.
2344 *
2345 * \since This function is available since SDL_mixer 2.0.0.
2346 */
2347extern DECLSPEC void SDLCALL Mix_Resume(int channel);
2348
2349/**
2350 * Query whether a particular channel is paused.
2351 *
2352 * If an invalid channel is specified, this function returns zero.
2353 *
2354 * \param channel the channel to query, or -1 to query all channels.
2355 * \return 1 if channel paused, 0 otherwise. If `channel` is -1, returns the
2356 * number of paused channels.
2357 *
2358 * \since This function is available since SDL_mixer 2.0.0.
2359 */
2360extern DECLSPEC int SDLCALL Mix_Paused(int channel);
2361
2362/**
2363 * Pause the music stream.
2364 *
2365 * Pausing the music stream will prevent further playback of the assigned
2366 * music object, but will maintain the object's current mixing position. When
2367 * resumed, this channel will continue to mix the music where it left off.
2368 *
2369 * Paused music can be resumed by calling Mix_ResumeMusic().
2370 *
2371 * It is legal to halt paused music. Playing a new music object when music is
2372 * paused will replace the current music and unpause the music stream.
2373 *
2374 * \since This function is available since SDL_mixer 2.0.0.
2375 */
2376extern DECLSPEC void SDLCALL Mix_PauseMusic(void);
2377
2378/**
2379 * Resume the music stream.
2380 *
2381 * It is legal to resume an unpaused music stream; it causes no effect and
2382 * reports no error.
2383 *
2384 * \since This function is available since SDL_mixer 2.0.0.
2385 */
2386extern DECLSPEC void SDLCALL Mix_ResumeMusic(void);
2387
2388/**
2389 * Rewind the music stream.
2390 *
2391 * This causes the currently-playing music to start mixing from the beginning
2392 * of the music, as if it were just started.
2393 *
2394 * It's a legal no-op to rewind the music stream when not playing.
2395 *
2396 * \since This function is available since SDL_mixer 2.0.0.
2397 */
2398extern DECLSPEC void SDLCALL Mix_RewindMusic(void);
2399
2400/**
2401 * Query whether the music stream is paused.
2402 *
2403 * \return 1 if music is paused, 0 otherwise.
2404 *
2405 * \since This function is available since SDL_mixer 2.0.0.
2406 *
2407 * \sa Mix_PauseMusic
2408 * \sa Mix_ResumeMusic
2409 */
2410extern DECLSPEC int SDLCALL Mix_PausedMusic(void);
2411
2412/**
2413 * Jump to a given order in mod music.
2414 *
2415 * This only applies to MOD music formats.
2416 *
2417 * \param order order
2418 * \returns 0 if successful, or -1 if failed or isn't implemented.
2419 *
2420 * \since This function is available since SDL_mixer 2.6.0.
2421 */
2422extern DECLSPEC int SDLCALL Mix_ModMusicJumpToOrder(int order);
2423
2424/**
2425 * Start a track in music object.
2426 *
2427 * This only applies to GME music formats.
2428 *
2429 * \param music the music object.
2430 * \param track the track number to play. 0 is the first track.
2431 * \returns 0 if successful, or -1 if failed or isn't implemented.
2432 *
2433 * \since This function is available since SDL_mixer 2.8.0.
2434 */
2435extern DECLSPEC int SDLCALL Mix_StartTrack(Mix_Music *music, int track);
2436
2437/**
2438 * Get number of tracks in music object.
2439 *
2440 * This only applies to GME music formats.
2441 *
2442 * \param music the music object.
2443 * \returns number of tracks if successful, or -1 if failed or isn't
2444 * implemented.
2445 *
2446 * \since This function is available since SDL_mixer 2.8.0.
2447 */
2448extern DECLSPEC int SDLCALL Mix_GetNumTracks(Mix_Music *music);
2449
2450/**
2451 * Set the current position in the music stream, in seconds.
2452 *
2453 * To convert from milliseconds, divide by 1000.0.
2454 *
2455 * This function is only implemented for MOD music formats (set pattern order
2456 * number) and for WAV, OGG, FLAC, MP3, and MODPLUG music at the moment.
2457 *
2458 * \param position the new position, in seconds (as a double).
2459 * \returns 0 if successful, or -1 if it failed or not implemented.
2460 *
2461 * \since This function is available since SDL_mixer 2.0.0.
2462 */
2463extern DECLSPEC int SDLCALL Mix_SetMusicPosition(double position);
2464
2465/**
2466 * Get the time current position of music stream, in seconds.
2467 *
2468 * To convert to milliseconds, multiply by 1000.0.
2469 *
2470 * \param music the music object to query.
2471 * \returns -1.0 if this feature is not supported for some codec.
2472 *
2473 * \since This function is available since SDL_mixer 2.6.0.
2474 */
2475extern DECLSPEC double SDLCALL Mix_GetMusicPosition(Mix_Music *music);
2476
2477/**
2478 * Get a music object's duration, in seconds.
2479 *
2480 * To convert to milliseconds, multiply by 1000.0.
2481 *
2482 * If NULL is passed, returns duration of current playing music.
2483 *
2484 * \param music the music object to query.
2485 * \returns music duration in seconds, or -1.0 on error.
2486 *
2487 * \since This function is available since SDL_mixer 2.6.0.
2488 */
2489extern DECLSPEC double SDLCALL Mix_MusicDuration(Mix_Music *music);
2490
2491/**
2492 * Get the loop start time position of music stream, in seconds.
2493 *
2494 * To convert to milliseconds, multiply by 1000.0.
2495 *
2496 * If NULL is passed, returns duration of current playing music.
2497 *
2498 * \param music the music object to query.
2499 * \returns -1.0 if this feature is not used for this music or not supported
2500 * for some codec
2501 *
2502 * \since This function is available since SDL_mixer 2.6.0.
2503 */
2504extern DECLSPEC double SDLCALL Mix_GetMusicLoopStartTime(Mix_Music *music);
2505
2506/**
2507 * Get the loop end time position of music stream, in seconds.
2508 *
2509 * To convert to milliseconds, multiply by 1000.0.
2510 *
2511 * If NULL is passed, returns duration of current playing music.
2512 *
2513 * \param music the music object to query.
2514 * \returns -1.0 if this feature is not used for this music or not supported
2515 * for some codec
2516 *
2517 * \since This function is available since SDL_mixer 2.6.0.
2518 */
2519extern DECLSPEC double SDLCALL Mix_GetMusicLoopEndTime(Mix_Music *music);
2520
2521/**
2522 * Get the loop time length of music stream, in seconds.
2523 *
2524 * To convert to milliseconds, multiply by 1000.0.
2525 *
2526 * If NULL is passed, returns duration of current playing music.
2527 *
2528 * \param music the music object to query.
2529 * \returns -1.0 if this feature is not used for this music or not supported
2530 * for some codec
2531 *
2532 * \since This function is available since SDL_mixer 2.6.0.
2533 */
2534extern DECLSPEC double SDLCALL Mix_GetMusicLoopLengthTime(Mix_Music *music);
2535
2536/**
2537 * Check the playing status of a specific channel.
2538 *
2539 * If the channel is currently playing, this function returns 1. Otherwise it
2540 * returns 0.
2541 *
2542 * If the specified channel is -1, all channels are checked, and this function
2543 * returns the number of channels currently playing.
2544 *
2545 * You may not specify MAX_CHANNEL_POST for a channel.
2546 *
2547 * Paused channels are treated as playing, even though they are not currently
2548 * making forward progress in mixing.
2549 *
2550 * \param channel channel
2551 * \returns non-zero if channel is playing, zero otherwise. If `channel` is
2552 * -1, return the total number of channel playings.
2553 *
2554 * \since This function is available since SDL_mixer 2.0.0.
2555 */
2556extern DECLSPEC int SDLCALL Mix_Playing(int channel);
2557
2558/**
2559 * Check the playing status of the music stream.
2560 *
2561 * If music is currently playing, this function returns 1. Otherwise it
2562 * returns 0.
2563 *
2564 * Paused music is treated as playing, even though it is not currently making
2565 * forward progress in mixing.
2566 *
2567 * \returns non-zero if music is playing, zero otherwise.
2568 *
2569 * \since This function is available since SDL_mixer 2.0.0.
2570 */
2571extern DECLSPEC int SDLCALL Mix_PlayingMusic(void);
2572
2573/**
2574 * Run an external command as the music stream.
2575 *
2576 * This halts any currently-playing music, and next time the music stream is
2577 * played, SDL_mixer will spawn a process using the command line specified in
2578 * `command`. This command is not subject to shell expansion, and beyond some
2579 * basic splitting up of arguments, is passed to execvp() on most platforms,
2580 * not system().
2581 *
2582 * The command is responsible for generating sound; it is NOT mixed by
2583 * SDL_mixer! SDL_mixer will kill the child process if asked to halt the
2584 * music, but otherwise does not have any control over what the process does.
2585 *
2586 * You are strongly encouraged not to use this function without an extremely
2587 * good reason.
2588 *
2589 * \param command command
2590 * \returns 0 if successful, -1 on error
2591 *
2592 * \since This function is available since SDL_mixer 2.0.0.
2593 */
2594extern DECLSPEC int SDLCALL Mix_SetMusicCMD(const char *command);
2595
2596/**
2597 * This function does nothing, do not use.
2598 *
2599 * This was probably meant to expose a feature, but no codecs support it, so
2600 * it only remains for binary compatibility.
2601 *
2602 * Calling this function is a legal no-op that returns -1.
2603 *
2604 * \param value this parameter is ignored.
2605 * \returns -1.
2606 *
2607 * \since This function is available since SDL_mixer 2.0.0.
2608 */
2609extern DECLSPEC int SDLCALL Mix_SetSynchroValue(int value);
2610
2611/**
2612 * This function does nothing, do not use.
2613 *
2614 * This was probably meant to expose a feature, but no codecs support it, so
2615 * it only remains for binary compatibility.
2616 *
2617 * Calling this function is a legal no-op that returns -1.
2618 *
2619 * \returns -1.
2620 *
2621 * \since This function is available since SDL_mixer 2.0.0.
2622 */
2623extern DECLSPEC int SDLCALL Mix_GetSynchroValue(void);
2624
2625/**
2626 * Set SoundFonts paths to use by supported MIDI backends.
2627 *
2628 * You may specify multiple paths in a single string by separating them with
2629 * semicolons; they will be searched in the order listed.
2630 *
2631 * This function replaces any previously-specified paths.
2632 *
2633 * Passing a NULL path will remove any previously-specified paths.
2634 *
2635 * Note that unlike most SDL and SDL_mixer functions, this function returns
2636 * zero if there's an error, not on success. We apologize for the API design
2637 * inconsistency here.
2638 *
2639 * \param paths Paths on the filesystem where SoundFonts are available,
2640 * separated by semicolons.
2641 * \returns 1 if successful, 0 on error (out of memory).
2642 *
2643 * \since This function is available since SDL_mixer 2.0.0.
2644 */
2645extern DECLSPEC int SDLCALL Mix_SetSoundFonts(const char *paths);
2646
2647/**
2648 * Get SoundFonts paths to use by supported MIDI backends.
2649 *
2650 * There are several factors that determine what will be reported by this
2651 * function:
2652 *
2653 * - If the boolean _SDL hint_ `"SDL_FORCE_SOUNDFONTS"` is set, AND the
2654 * `"SDL_SOUNDFONTS"` _environment variable_ is also set, this function will
2655 * return that environment variable regardless of whether
2656 * Mix_SetSoundFounts() was ever called.
2657 * - Otherwise, if Mix_SetSoundFonts() was successfully called with a non-NULL
2658 * path, this function will return the string passed to that function.
2659 * - Otherwise, if the `"SDL_SOUNDFONTS"` variable is set, this function will
2660 * return that environment variable.
2661 * - Otherwise, this function will search some common locations on the
2662 * filesystem, and if it finds a SoundFont there, it will return that.
2663 * - Failing everything else, this function returns NULL.
2664 *
2665 * This returns a pointer to internal (possibly read-only) memory, and it
2666 * should not be modified or free'd by the caller.
2667 *
2668 * \returns semicolon-separated list of sound font paths.
2669 *
2670 * \since This function is available since SDL_mixer 2.0.0.
2671 */
2672extern DECLSPEC const char* SDLCALL Mix_GetSoundFonts(void);
2673
2674/**
2675 * Iterate SoundFonts paths to use by supported MIDI backends.
2676 *
2677 * This function will take the string reported by Mix_GetSoundFonts(), split
2678 * it up into separate paths, as delimited by semicolons in the string, and
2679 * call a callback function for each separate path.
2680 *
2681 * If there are no paths available, this returns 0 without calling the
2682 * callback at all.
2683 *
2684 * If the callback returns non-zero, this function stops iterating and returns
2685 * non-zero. If the callback returns 0, this function will continue iterating,
2686 * calling the callback again for further paths. If the callback never returns
2687 * 1, this function returns 0, so this can be used to decide if an available
2688 * soundfont is acceptable for use.
2689 *
2690 * \param function the callback function to call once per path.
2691 * \param data a pointer to pass to the callback for its own personal use.
2692 * \returns non-zero if callback ever returned non-zero, 0 on error or the
2693 * callback never returned non-zero.
2694 *
2695 * \since This function is available since SDL_mixer 2.0.0.
2696 *
2697 * \sa Mix_GetSoundFonts
2698 */
2699extern DECLSPEC int SDLCALL Mix_EachSoundFont(int (SDLCALL *function)(const char*, void*), void *data);
2700
2701/**
2702 * Set full path of the Timidity config file.
2703 *
2704 * For example, "/etc/timidity.cfg"
2705 *
2706 * This is obviously only useful if SDL_mixer is using Timidity internally to
2707 * play MIDI files.
2708 *
2709 * \param path path to a Timidity config file.
2710 * \returns 1 if successful, 0 on error
2711 *
2712 * \since This function is available since SDL_mixer 2.6.0.
2713 */
2714extern DECLSPEC int SDLCALL Mix_SetTimidityCfg(const char *path);
2715
2716/**
2717 * Get full path of a previously-specified Timidity config file.
2718 *
2719 * For example, "/etc/timidity.cfg"
2720 *
2721 * If a path has never been specified, this returns NULL.
2722 *
2723 * This returns a pointer to internal memory, and it should not be modified or
2724 * free'd by the caller.
2725 *
2726 * \returns the previously-specified path, or NULL if not set.
2727 *
2728 * \since This function is available since SDL_mixer 2.6.0.
2729 *
2730 * \sa Mix_SetTimidityCfg
2731 */
2732extern DECLSPEC const char* SDLCALL Mix_GetTimidityCfg(void);
2733
2734/**
2735 * Get the Mix_Chunk currently associated with a mixer channel.
2736 *
2737 * You may not specify MAX_CHANNEL_POST or -1 for a channel.
2738 *
2739 * \param channel the channel to query.
2740 * \returns the associated chunk, if any, or NULL if it's an invalid channel.
2741 *
2742 * \since This function is available since SDL_mixer 2.0.0.
2743 */
2744extern DECLSPEC Mix_Chunk * SDLCALL Mix_GetChunk(int channel);
2745
2746/**
2747 * Close the mixer, halting all playing audio.
2748 *
2749 * Any halted channels will have any currently-registered effects
2750 * deregistered, and will call any callback specified by Mix_ChannelFinished()
2751 * before this function returns.
2752 *
2753 * Any halted music will call any callback specified by
2754 * Mix_HookMusicFinished() before this function returns.
2755 *
2756 * Do not start any new audio playing during callbacks in this function.
2757 *
2758 * This will close the audio device. Attempting to play new audio after this
2759 * function returns will fail, until another successful call to
2760 * Mix_OpenAudio() or Mix_OpenAudioDevice().
2761 *
2762 * Note that (unlike Mix_OpenAudio optionally calling SDL_Init(SDL_INIT_AUDIO)
2763 * on the app's behalf), this will _not_ deinitialize the SDL audio subsystem
2764 * in any case. At some point after calling this function and Mix_Quit(), some
2765 * part of the application should be responsible for calling SDL_Quit() to
2766 * deinitialize all of SDL, including its audio subsystem.
2767 *
2768 * This function should be the last thing you call in SDL_mixer before
2769 * Mix_Quit(). However, the following notes apply if you don't follow this
2770 * advice:
2771 *
2772 * Note that this will not free any loaded chunks or music; you should dispose
2773 * of those resources separately. It is probably poor form to dispose of them
2774 * _after_ this function, but it is safe to call Mix_FreeChunk() and
2775 * Mix_FreeMusic() after closing the device.
2776 *
2777 * Note that any chunks or music you don't free may or may not work if you
2778 * call Mix_OpenAudio again, as the audio device may be in a new format and
2779 * the existing chunks will not be converted to match.
2780 *
2781 * \since This function is available since SDL_mixer 2.0.0.
2782 *
2783 * \sa Mix_Quit
2784 */
2785extern DECLSPEC void SDLCALL Mix_CloseAudio(void);
2786
2787/* We'll use SDL for reporting errors */
2788
2789/**
2790 * Report SDL_mixer errors
2791 *
2792 * \sa Mix_GetError
2793 */
2794#define Mix_SetError SDL_SetError
2795
2796/**
2797 * Get last SDL_mixer error
2798 *
2799 * \sa Mix_SetError
2800 */
2801#define Mix_GetError SDL_GetError
2802
2803/**
2804 * Clear last SDL_mixer error
2805 *
2806 * \sa Mix_SetError
2807 */
2808#define Mix_ClearError SDL_ClearError
2809
2810/**
2811 * Set OutOfMemory error
2812 */
2813#define Mix_OutOfMemory SDL_OutOfMemory
2814
2815/* Ends C function definitions when using C++ */
2816#ifdef __cplusplus
2817}
2818#endif
2819
2820#include "close_code.h"
2821
2822#endif /* SDL_MIXER_H_ */
2823