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