4 SDL_mixer: An audio mixer library based on the SDL library
5 Copyright (C) 1997-2013 Sam Lantinga <slouken@libsdl.org>
7 This software is provided 'as-is', without any express or implied
8 warranty. In no event will the authors be held liable for any damages
9 arising from the use of this software.
11 Permission is granted to anyone to use this software for any purpose,
12 including commercial applications, and to alter it and redistribute it
13 freely, subject to the following restrictions:
15 1. The origin of this software must not be misrepresented; you must not
16 claim that you wrote the original software. If you use this software
17 in a product, an acknowledgment in the product documentation would be
18 appreciated but is not required.
19 2. Altered source versions must be plainly marked as such, and must not be
20 misrepresented as being the original software.
21 3. This notice may not be removed or altered from any source distribution.
24 {* ChangeLog: (Header Translation)
27 v.1.74-stable; 16.11.2013: fixed bug, found by Cybermonkey. thx
28 v.1.72-stable; 29.09.2013: fixed bug with procedures without parameters
29 (they must have brackets)
30 v.1.70-stable; 16.09.2013: Initial Commit
43 MIX_LibName = 'SDL2_mixer.dll';
48 MIX_LibName = 'libSDL2_mixer.dylib';
51 MIX_LibName = 'libSDL2_mixer.so';
53 MIX_LibName = 'libSDL2_mixer.so.0';
59 MIX_LibName = 'SDL2_mixer';
61 {$linklib libSDL2_mixer}
65 {* Printable format: "%d.%d.%d", MAJOR, MINOR, PATCHLEVEL *}
67 SDL_MIXER_MAJOR_VERSION = 2;
68 SDL_MIXER_MINOR_VERSION = 0;
69 SDL_MIXER_PATCHLEVEL = 0;
71 {* This macro can be used to fill a version structure with the compile-time
72 * version of the SDL_mixer library.
74 procedure SDL_MIXER_VERSION(X: PSDL_Version);
76 {* Backwards compatibility *}
78 MIX_MAJOR_VERSION = SDL_MIXER_MAJOR_VERSION;
79 MIX_MINOR_VERSION = SDL_MIXER_MINOR_VERSION;
80 MIX_PATCHLEVEL = SDL_MIXER_PATCHLEVEL;
82 procedure MIX_VERSION(X: PSDL_Version);
84 {* This function gets the version of the dynamically linked SDL_mixer library.
85 it should NOT be used to fill a version structure, instead you should
86 use the SDL_MIXER_VERSION() macro.
88 function Mix_Linked_Version: PSDL_Version cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_Linked_Version' {$ENDIF} {$ENDIF};
91 MIX_INIT_FLAC = $00000001;
92 MIX_INIT_MOD = $00000002;
93 MIX_INIT_MODPLUG = $00000004;
94 MIX_INIT_MP3 = $00000008;
95 MIX_INIT_OGG = $00000010;
96 MIX_INIT_FLUIDSYNTH = $00000020;
98 TMIX_InitFlags = Byte;
100 {* Loads dynamic libraries and prepares them for use. Flags should be
101 one or more flags from MIX_InitFlags OR'd together.
102 It returns the flags successfully initialized, or 0 on failure.
104 function Mix_Init(flags: Integer): Integer cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_Init' {$ENDIF} {$ENDIF};
106 {* Unloads libraries loaded with Mix_Init *}
107 procedure Mix_Quit() cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_Quit' {$ENDIF} {$ENDIF};
110 {* The default mixer has 8 simultaneous mixing channels *}
111 {$IFNDEF MIX_CHANNELS}
116 {* Good default values for a PC soundcard *}
118 MIX_DEFAULT_FREQUENCY = 22050;
119 {$IFDEF ENDIAN_LITTLE}
120 MIX_DEFAULT_FORMAT = AUDIO_S16LSB;
122 MIX_DEFAULT_FORMAT = AUDIO_S16MSB;
124 MIX_DEFAULT_CHANNELS = 2;
125 MIX_MAX_VOLUME = 128; {* Volume of a chunk *}
127 {* The internal format for an audio chunk *}
129 PMix_Chunk = ^TMix_Chunk;
134 volume: UInt8; {* Per-sample volume, 0-128 *}
137 {* The different fading types supported *}
139 TMix_Fading = (MIX_NO_FADING, MIX_FADING_OUT, MIX_FADING_IN);
141 TMix_MusicType = (MUS_NONE,
152 {* The internal format for a music chunk interpreted via mikmod *}
153 PMix_Music = ^TMix_Music;
154 TMix_Music = record end;
156 {* Open the mixer with a certain audio format *}
157 function Mix_OpenAudio(frequency: Integer; format: UInt16; channels: Integer; chunksize: Integer): Integer cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_OpenAudio' {$ENDIF} {$ENDIF};
159 {* Dynamically change the number of channels managed by the mixer.
160 If decreasing the number of channels, the upper channels are
162 This function returns the new number of allocated channels.
164 function Mix_AllocateChannels(numchans: Integer): Integer cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_AllocateChannels' {$ENDIF} {$ENDIF};
166 {* Find out what the actual audio device parameters are.
167 This function returns 1 if the audio has been opened, 0 otherwise.
169 function Mix_QuerySpec(frequency: PInt; format: PUInt16; channels: PInt): Integer cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_QuerySpec' {$ENDIF} {$ENDIF};
171 {* Load a wave file or a music (.mod .s3m .it .xm) file *}
172 function Mix_LoadWAV_RW(src: PSDL_RWops; freesrc: Integer): PMix_Chunk cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_LoadWAV_RW' {$ENDIF} {$ENDIF};
173 function Mix_LoadWAV(_file: PAnsiChar): PMix_Chunk;
174 function Mix_LoadMUS(_file: PAnsiChar): PMix_Music cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_LoadMUS' {$ENDIF} {$ENDIF};
176 {* Load a music file from an SDL_RWop object (Ogg and MikMod specific currently)
177 Matt Campbell (matt@campbellhome.dhs.org) April 2000 *}
178 function Mix_LoadMUS_RW(src: PSDL_RWops; freesrc: Integer): PMix_Music cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_LoadMUS_RW' {$ENDIF} {$ENDIF};
180 {* Load a music file from an SDL_RWop object assuming a specific format *}
181 function Mix_LoadMUSType_RW(src: PSDL_RWops; _type: TMix_MusicType; freesrc: Integer): PMix_Music cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_LoadMUSType_RW' {$ENDIF} {$ENDIF};
183 {* Load a wave file of the mixer format from a memory buffer *}
184 function Mix_QuickLoad_WAV(mem: PUInt8): PMix_Chunk cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_QuickLoad_WAV' {$ENDIF} {$ENDIF};
186 {* Load raw audio data of the mixer format from a memory buffer *}
187 function Mix_QuickLoad_RAW(mem: PUInt8; len: UInt32): PMix_Chunk cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_QuickLoad_RAW' {$ENDIF} {$ENDIF};
189 {* Free an audio chunk previously loaded *}
190 procedure Mix_FreeChunk(chunk: PMix_Chunk) cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_FreeChunk' {$ENDIF} {$ENDIF};
191 procedure Mix_FreeMusic(music: PMix_Music) cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_FreeMusic' {$ENDIF} {$ENDIF};
193 {* Get a list of chunk/music decoders that this build of SDL_mixer provides.
194 This list can change between builds AND runs of the program, if external
195 libraries that add functionality become available.
196 You must successfully call Mix_OpenAudio() before calling these functions.
197 This API is only available in SDL_mixer 1.2.9 and later.
201 const int total = Mix_GetNumChunkDecoders();
202 for (i = 0; i < total; i++)
203 printf("Supported chunk decoder: [%s]\n", Mix_GetChunkDecoder(i));
205 Appearing in this list doesn't promise your specific audio file will
206 decode...but it's handy to know if you have, say, a functioning Timidity
209 These return values are static, read-only data; do not modify or free it.
210 The pointers remain valid until you call Mix_CloseAudio().
212 function Mix_GetNumChunkDecoders: Integer cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_GetNumChunkDecoders' {$ENDIF} {$ENDIF};
213 function Mix_GetChunkDecoder(index: Integer): PAnsiChar cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_GetChunkDecoder' {$ENDIF} {$ENDIF};
214 function Mix_GetNumMusicDecoders: Integer cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_GetNumMusicDecoders' {$ENDIF} {$ENDIF};
215 function Mix_GetMusicDecoder(index: Integer): PAnsiChar cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_GetMusicDecoder' {$ENDIF} {$ENDIF};
217 {* Find out the music format of a mixer music, or the currently playing
218 music, if 'music' is NULL.
220 function Mix_GetMusicType(music: TMix_Music): TMix_MusicType cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_GetMusicType' {$ENDIF} {$ENDIF};
222 {* Set a function that is called after all mixing is performed.
223 This can be used to provide real-time visual display of the audio stream
224 or add a custom mixer filter for the stream data.
227 TMix_Func = procedure(udata: Pointer; stream: PUInt8; len: Integer);
229 procedure Mix_SetPostMix(func: TMix_Func; arg: Pointer) cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_SetPostMix' {$ENDIF} {$ENDIF};
231 {* Add your own music player or additional mixer function.
232 If 'mix_func' is NULL, the default music player is re-enabled.
234 procedure Mix_HookMusic(func: TMix_Func; arg: Pointer) cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_HookMusic' {$ENDIF} {$ENDIF};
236 {* Add your own callback when the music has finished playing.
237 This callback is only called if the music finishes naturally.
240 PMix_Music_Finished = ^TMix_Music_Finished;
241 TMix_Music_Finished = procedure();
242 procedure Mix_HookMusicFinished(music_finished: PMix_Music_Finished) cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_HookMusicFinished' {$ENDIF} {$ENDIF};
244 {* Get a pointer to the user data for the current music hook *}
245 function Mix_GetMusicHookData: Pointer cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_GetMusicHookData' {$ENDIF} {$ENDIF};
248 * Add your own callback when a channel has finished playing. NULL
249 * to disable callback. The callback may be called from the mixer's audio
250 * callback or it could be called as a result of Mix_HaltChannel(), etc.
251 * do not call SDL_LockAudio() from this callback; you will either be
252 * inside the audio callback, or SDL_mixer will explicitly lock the audio
253 * before calling your callback.
256 TMix_Channel_Finished = procedure(channel: Integer);
257 procedure Mix_ChannelFinished(channel_finished: TMix_Channel_Finished) cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_ChannelFinished' {$ENDIF} {$ENDIF};
259 {* Special Effects API by ryan c. gordon. (icculus@icculus.org) *}
261 MIX_CHANNEL_POST = -2;
263 {* This is the format of a special effect callback:
265 * myeffect(int chan, void *stream, int len, void *udata);
267 * (chan) is the channel number that your effect is affecting. (stream) is
268 * the buffer of data to work upon. (len) is the size of (stream), and
269 * (udata) is a user-defined bit of data, which you pass as the last arg of
270 * Mix_RegisterEffect(), and is passed back unmolested to your callback.
271 * Your effect changes the contents of (stream) based on whatever parameters
272 * are significant, or just leaves it be, if you prefer. You can do whatever
273 * you like to the buffer, though, and it will continue in its changed state
274 * down the mixing pipeline, through any other effect functions, then finally
275 * to be mixed with the rest of the channels and music for the final output
278 * DO NOT EVER call SDL_LockAudio() from your callback function!
281 TMix_EffectFunc_t = procedure(chan: Integer; stream: Pointer; len: Integer; udata: Pointer);
284 * This is a callback that signifies that a channel has finished all its
285 * loops and has completed playback. This gets called if the buffer
286 * plays out normally, or if you call Mix_HaltChannel(), implicitly stop
287 * a channel via Mix_AllocateChannels(), or unregister a callback while
288 * it's still playing.
290 * DO NOT EVER call SDL_LockAudio() from your callback function!
293 TMix_EffectDone_t = procedure(chan: Integer; udata: Pointer);
295 {* Register a special effect function. At mixing time, the channel data is
296 * copied into a buffer and passed through each registered effect function.
297 * After it passes through all the functions, it is mixed into the final
298 * output stream. The copy to buffer is performed once, then each effect
299 * function performs on the output of the previous effect. Understand that
300 * this extra copy to a buffer is not performed if there are no effects
301 * registered for a given chunk, which saves CPU cycles, and any given
302 * effect will be extra cycles, too, so it is crucial that your code run
303 * fast. Also note that the data that your function is given is in the
304 * format of the sound device, and not the format you gave to Mix_OpenAudio(),
305 * although they may in reality be the same. This is an unfortunate but
306 * necessary speed concern. Use Mix_QuerySpec() to determine if you can
307 * handle the data before you register your effect, and take appropriate
309 * You may also specify a callback (Mix_EffectDone_t) that is called when
310 * the channel finishes playing. This gives you a more fine-grained control
311 * than Mix_ChannelFinished(), in case you need to free effect-specific
312 * resources, etc. If you don't need this, you can specify NULL.
313 * You may set the callbacks before or after calling Mix_PlayChannel().
314 * Things like Mix_SetPanning() are just internal special effect functions,
315 * so if you are using that, you've already incurred the overhead of a copy
316 * to a separate buffer, and that these effects will be in the queue with
317 * any functions you've registered. The list of registered effects for a
318 * channel is reset when a chunk finishes playing, so you need to explicitly
319 * set them with each call to Mix_PlayChannel*().
320 * You may also register a special effect function that is to be run after
321 * final mixing occurs. The rules for these callbacks are identical to those
322 * in Mix_RegisterEffect, but they are run after all the channels and the
323 * music have been mixed into a single stream, whereas channel-specific
324 * effects run on a given channel before any other mixing occurs. These
325 * global effect callbacks are call "posteffects". Posteffects only have
326 * their Mix_EffectDone_t function called when they are unregistered (since
327 * the main output stream is never "done" in the same sense as a channel).
328 * You must unregister them manually when you've had enough. Your callback
329 * will be told that the channel being mixed is (MIX_CHANNEL_POST) if the
330 * processing is considered a posteffect.
332 * After all these effects have finished processing, the callback registered
333 * through Mix_SetPostMix() runs, and then the stream goes to the audio
336 * DO NOT EVER call SDL_LockAudio() from your callback function!
338 * returns zero if error (no such channel), nonzero if added.
339 * Error messages can be retrieved from Mix_GetError().
341 function Mix_RegisterEffect(chan: Integer; f: TMix_EffectFunc_t; d: TMix_EffectDone_t; arg: Pointer): Integer cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_RegisterEffect' {$ENDIF} {$ENDIF};
343 {* You may not need to call this explicitly, unless you need to stop an
344 * effect from processing in the middle of a chunk's playback.
345 * Posteffects are never implicitly unregistered as they are for channels,
346 * but they may be explicitly unregistered through this function by
347 * specifying MIX_CHANNEL_POST for a channel.
348 * returns zero if error (no such channel or effect), nonzero if removed.
349 * Error messages can be retrieved from Mix_GetError().
351 function Mix_UnregisterEffect(channel: Integer; f: TMix_EffectFunc_t): Integer cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_UnregisterEffect' {$ENDIF} {$ENDIF};
353 {* You may not need to call this explicitly, unless you need to stop all
354 * effects from processing in the middle of a chunk's playback. Note that
355 * this will also shut off some internal effect processing, since
356 * Mix_SetPanning() and others may use this API under the hood. This is
357 * called internally when a channel completes playback.
358 * Posteffects are never implicitly unregistered as they are for channels,
359 * but they may be explicitly unregistered through this function by
360 * specifying MIX_CHANNEL_POST for a channel.
361 * returns zero if error (no such channel), nonzero if all effects removed.
362 * Error messages can be retrieved from Mix_GetError().
364 function Mix_UnregisterAllEffects(channel: Integer): Integer cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_UnregisterEffects' {$ENDIF} {$ENDIF};
367 MIX_EFFECTSMAXSPEED = 'MIX_EFFECTSMAXSPEED';
370 * These are the internally-defined mixing effects. They use the same API that
371 * effects defined in the application use, but are provided here as a
372 * convenience. Some effects can reduce their quality or use more memory in
373 * the name of speed; to enable this, make sure the environment variable
374 * MIX_EFFECTSMAXSPEED (see above) is defined before you call
378 {* Set the panning of a channel. The left and right channels are specified
379 * as integers between 0 and 255, quietest to loudest, respectively.
381 * Technically, this is just individual volume control for a sample with
382 * two (stereo) channels, so it can be used for more than just panning.
383 * If you want real panning, call it like this:
385 * Mix_SetPanning(channel, left, 255 - left);
387 * ...which isn't so hard.
389 * Setting (channel) to MIX_CHANNEL_POST registers this as a posteffect, and
390 * the panning will be done to the final mixed stream before passing it on
391 * to the audio device.
393 * This uses the Mix_RegisterEffect() API internally, and returns without
394 * registering the effect function if the audio device is not configured
395 * for stereo output. Setting both (left) and (right) to 255 causes this
396 * effect to be unregistered, since that is the data's normal state.
398 * returns zero if error (no such channel or Mix_RegisterEffect() fails),
399 * nonzero if panning effect enabled. Note that an audio device in mono
400 * mode is a no-op, but this call will return successful in that case.
401 * Error messages can be retrieved from Mix_GetError().
403 function Mix_SetPanning(channel: Integer; left: UInt8; right: UInt8): Integer cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_SetPanning' {$ENDIF} {$ENDIF};
405 {* Set the position of a channel. (angle) is an integer from 0 to 360, that
406 * specifies the location of the sound in relation to the listener. (angle)
407 * will be reduced as neccesary (540 becomes 180 degrees, -100 becomes 260).
408 * Angle 0 is due north, and rotates clockwise as the value increases.
409 * For efficiency, the precision of this effect may be limited (angles 1
410 * through 7 might all produce the same effect, 8 through 15 are equal, etc).
411 * (distance) is an integer between 0 and 255 that specifies the space
412 * between the sound and the listener. The larger the number, the further
413 * away the sound is. Using 255 does not guarantee that the channel will be
414 * culled from the mixing process or be completely silent. For efficiency,
415 * the precision of this effect may be limited (distance 0 through 5 might
416 * all produce the same effect, 6 through 10 are equal, etc). Setting (angle)
417 * and (distance) to 0 unregisters this effect, since the data would be
420 * If you need more precise positional audio, consider using OpenAL for
421 * spatialized effects instead of SDL_mixer. This is only meant to be a
422 * basic effect for simple "3D" games.
424 * If the audio device is configured for mono output, then you won't get
425 * any effectiveness from the angle; however, distance attenuation on the
426 * channel will still occur. While this effect will function with stereo
427 * voices, it makes more sense to use voices with only one channel of sound,
428 * so when they are mixed through this effect, the positioning will sound
429 * correct. You can convert them to mono through SDL before giving them to
430 * the mixer in the first place if you like.
432 * Setting (channel) to MIX_CHANNEL_POST registers this as a posteffect, and
433 * the positioning will be done to the final mixed stream before passing it
434 * on to the audio device.
436 * This is a convenience wrapper over Mix_SetDistance() and Mix_SetPanning().
438 * returns zero if error (no such channel or Mix_RegisterEffect() fails),
439 * nonzero if position effect is enabled.
440 * Error messages can be retrieved from Mix_GetError().
442 function Mix_SetPosition(channel: Integer; angle: SInt16; distance: UInt8): Integer cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_SetPosition' {$ENDIF} {$ENDIF};
444 {* Set the "distance" of a channel. (distance) is an integer from 0 to 255
445 * that specifies the location of the sound in relation to the listener.
446 * Distance 0 is overlapping the listener, and 255 is as far away as possible
447 * A distance of 255 does not guarantee silence; in such a case, you might
448 * want to try changing the chunk's volume, or just cull the sample from the
449 * mixing process with Mix_HaltChannel().
450 * For efficiency, the precision of this effect may be limited (distances 1
451 * through 7 might all produce the same effect, 8 through 15 are equal, etc).
452 * (distance) is an integer between 0 and 255 that specifies the space
453 * between the sound and the listener. The larger the number, the further
455 * Setting (distance) to 0 unregisters this effect, since the data would be
457 * If you need more precise positional audio, consider using OpenAL for
458 * spatialized effects instead of SDL_mixer. This is only meant to be a
459 * basic effect for simple "3D" games.
461 * Setting (channel) to MIX_CHANNEL_POST registers this as a posteffect, and
462 * the distance attenuation will be done to the final mixed stream before
463 * passing it on to the audio device.
465 * This uses the Mix_RegisterEffect() API internally.
467 * returns zero if error (no such channel or Mix_RegisterEffect() fails),
468 * nonzero if position effect is enabled.
469 * Error messages can be retrieved from Mix_GetError().
471 function Mix_SetDistance(channel: Integer; distance: UInt8): Integer cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_SetDistance' {$ENDIF} {$ENDIF};
474 * !!! FIXME : Haven't implemented, since the effect goes past the
475 * end of the sound buffer. Will have to think about this.
479 {* Causes an echo effect to be mixed into a sound. (echo) is the amount
480 * of echo to mix. 0 is no echo, 255 is infinite (and probably not
483 * Setting (channel) to MIX_CHANNEL_POST registers this as a posteffect, and
484 * the reverbing will be done to the final mixed stream before passing it on
485 * to the audio device.
487 * This uses the Mix_RegisterEffect() API internally. If you specify an echo
488 * of zero, the effect is unregistered, as the data is already in that state.
490 * returns zero if error (no such channel or Mix_RegisterEffect() fails),
491 * nonzero if reversing effect is enabled.
492 * Error messages can be retrieved from Mix_GetError().
494 //extern no_parse_DECLSPEC int SDLCALL Mix_SetReverb(int channel, Uint8 echo);
497 {* Causes a channel to reverse its stereo. This is handy if the user has his
498 * speakers hooked up backwards, or you would like to have a minor bit of
499 * psychedelia in your sound code. :) Calling this function with (flip)
500 * set to non-zero reverses the chunks's usual channels. If (flip) is zero,
501 * the effect is unregistered.
503 * This uses the Mix_RegisterEffect() API internally, and thus is probably
504 * more CPU intensive than having the user just plug in his speakers
505 * correctly. Mix_SetReverseStereo() returns without registering the effect
506 * function if the audio device is not configured for stereo output.
508 * If you specify MIX_CHANNEL_POST for (channel), then this the effect is used
509 * on the final mixed stream before sending it on to the audio device (a
512 * returns zero if error (no such channel or Mix_RegisterEffect() fails),
513 * nonzero if reversing effect is enabled. Note that an audio device in mono
514 * mode is a no-op, but this call will return successful in that case.
515 * Error messages can be retrieved from Mix_GetError().
517 function Mix_SetReverseStereo(channel: Integer; flip: Integer): Integer cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_SetReverseStereo' {$ENDIF} {$ENDIF};
519 {* end of effects API. --ryan. *}
521 {* Reserve the first channels (0 -> n-1) for the application, i.e. don't allocate
522 them dynamically to the next sample if requested with a -1 value below.
523 Returns the number of reserved channels.
525 function Mix_ReserveChannels(num: Integer): Integer cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_ReverseChannels' {$ENDIF} {$ENDIF};
527 {* Channel grouping functions *}
529 {* Attach a tag to a channel. A tag can be assigned to several mixer
530 channels, to form groups of channels.
531 If 'tag' is -1, the tag is removed (actually -1 is the tag used to
532 represent the group of all the channels).
533 Returns true if everything was OK.
535 function Mix_GroupChannel(which: Integer; tag: Integer): Integer cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_GroupChannel' {$ENDIF} {$ENDIF};
536 {* Assign several consecutive channels to a group *}
537 function Mix_GroupChannels(from: Integer; _to: Integer; tag: Integer): Integer cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_GroupChannels' {$ENDIF} {$ENDIF};
538 {* Finds the first available channel in a group of channels,
539 returning -1 if none are available.
541 function Mix_GroupAvailable(tag: Integer): Integer cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_GroupAvailable' {$ENDIF} {$ENDIF};
542 {* Returns the number of channels in a group. This is also a subtle
543 way to get the total number of channels when 'tag' is -1
545 function Mix_GroupCount(tag: Integer): Integer cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_GroupCount' {$ENDIF} {$ENDIF};
546 {* Finds the "oldest" sample playing in a group of channels *}
547 function Mix_GroupOldest(tag: Integer): Integer cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_GroupOldest' {$ENDIF} {$ENDIF};
548 {* Finds the "most recent" (i.e. last) sample playing in a group of channels *}
549 function Mix_GroupNewer(tag: Integer): Integer cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_GroupNewer' {$ENDIF} {$ENDIF};
551 {* Play an audio chunk on a specific channel.
552 If the specified channel is -1, play on the first free channel.
553 If 'loops' is greater than zero, loop the sound that many times.
554 If 'loops' is -1, loop inifinitely (~65000 times).
555 Returns which channel was used to play the sound.
557 function Mix_PlayChannel(channel: Integer; chunk: PMix_Chunk; loops: Integer): Integer;
558 {* The same as above, but the sound is played at most 'ticks' milliseconds *}
559 function Mix_PlayChannelTimed(channel: Integer; chunk: PMix_Chunk; loops: Integer; ticks: Integer): Integer cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_PlayChannelTimed' {$ENDIF} {$ENDIF};
560 function Mix_PlayMusic(music: PMix_Music; loops: Integer): Integer cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_PlayMusic' {$ENDIF} {$ENDIF};
562 {* Fade in music or a channel over "ms" milliseconds, same semantics as the "Play" functions *}
563 function Mix_FadeInMusic(music: PMix_Music; loops: Integer; ms: Integer): Integer cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_FadeInMusic' {$ENDIF} {$ENDIF};
564 function Mix_FadeInMusicPos(music: PMix_Music; loops: Integer; ms: Integer; position: Double): Integer cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_FadeInMusicPos' {$ENDIF} {$ENDIF};
565 function Mix_FadeInChannel(channel: Integer; chunk: PMix_Chunk; loops: Integer; ms: Integer): Integer;
566 function Mix_FadeInChannelTimed(channel: Integer; chunk: PMix_Chunk; loops: Integer; ms: Integer; ticks: Integer): Integer cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_FadeInChannelTimed' {$ENDIF} {$ENDIF};
568 {* Set the volume in the range of 0-128 of a specific channel or chunk.
569 If the specified channel is -1, set volume for all channels.
570 Returns the original volume.
571 If the specified volume is -1, just return the current volume.
573 function Mix_Volume(channel: Integer; volume: Integer): Integer cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_Volume' {$ENDIF} {$ENDIF};
574 function Mix_VolumeChunk(chunk: PMix_Chunk; volume: Integer): Integer cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_VolumeChunk' {$ENDIF} {$ENDIF};
575 function Mix_VolumeMusic(volume: Integer): Integer cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_VolumeMusic' {$ENDIF} {$ENDIF};
577 {* Halt playing of a particular channel *}
578 function Mix_HaltChannel(channel: Integer): Integer cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_HaltChannel' {$ENDIF} {$ENDIF};
579 function Mix_HaltGroup(tag: Integer): Integer cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_HaltGroup' {$ENDIF} {$ENDIF};
580 function Mix_HaltMusic: Integer cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_HaltMusic' {$ENDIF} {$ENDIF};
582 {* Change the expiration delay for a particular channel.
583 The sample will stop playing after the 'ticks' milliseconds have elapsed,
584 or remove the expiration if 'ticks' is -1
586 function Mix_ExpireChannel(channel: Integer; ticks: Integer): Integer cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_ExpireChannel' {$ENDIF} {$ENDIF};
588 {* Halt a channel, fading it out progressively till it's silent
589 The ms parameter indicates the number of milliseconds the fading
592 function Mix_FadeOutChannel(which: Integer; ms: Integer): Integer cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_FadeOutChannel' {$ENDIF} {$ENDIF};
593 function Mix_FadeOutGroup(tag: Integer; ms: Integer): Integer cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_FadeOutGroup' {$ENDIF} {$ENDIF};
594 function Mix_FadeOutMusic(ms: Integer): Integer cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_FadeOutMusic' {$ENDIF} {$ENDIF};
596 {* Query the fading status of a channel *}
597 function Mix_FadingMusic: TMix_Fading cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_FadingMusic' {$ENDIF} {$ENDIF};
598 function Mix_FadingChannel(which: Integer): TMix_Fading cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_FadingChannel' {$ENDIF} {$ENDIF};
600 {* Pause/Resume a particular channel *}
601 procedure Mix_Pause(channel: Integer) cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_Pause' {$ENDIF} {$ENDIF};
602 procedure Mix_Resume(channel: Integer) cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_Resume' {$ENDIF} {$ENDIF};
603 function Mix_Paused(channel: Integer): Integer cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_Paused' {$ENDIF} {$ENDIF};
605 {* Pause/Resume the music stream *}
606 procedure Mix_PauseMusic cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_PauseMusic' {$ENDIF} {$ENDIF};
607 procedure Mix_ResumeMusic cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_ResumeMusic' {$ENDIF} {$ENDIF};
608 procedure Mix_RewindMusic cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_RewindMusic' {$ENDIF} {$ENDIF};
609 function Mix_PausedMusic: Integer cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_PausedMusic' {$ENDIF} {$ENDIF};
611 {* Set the current position in the music stream.
612 This returns 0 if successful, or -1 if it failed or isn't implemented.
613 This function is only implemented for MOD music formats (set pattern
614 order number) and for OGG, FLAC, MP3_MAD, and MODPLUG music (set
615 position in seconds), at the moment.
617 function Mix_SetMusicPosition(position: Double): Integer cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_SetMusicPosition' {$ENDIF} {$ENDIF};
619 {* Check the status of a specific channel.
620 If the specified channel is -1, check all channels.
622 function Mix_Playing(channel: Integer): Integer cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_Playing' {$ENDIF} {$ENDIF};
623 function Mix_PlayingMusic: Integer cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_PlayingMusic' {$ENDIF} {$ENDIF};
625 {* Stop music and set external music playback command *}
626 function Mix_SetMusicCMD(command: PAnsiChar): Integer cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_SetMusicCMD' {$ENDIF} {$ENDIF};
628 {* Synchro value is set by MikMod from modules while playing *}
629 function Mix_SetSynchroValue(value: Integer): Integer cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_SetSynchroValue' {$ENDIF} {$ENDIF};
630 function Mix_GetSynchroValue: Integer cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_GetSynchroValue' {$ENDIF} {$ENDIF};
632 {* Set/Get/Iterate SoundFonts paths to use by supported MIDI backends *}
633 function Mix_SetSoundFonts(paths: PAnsiChar): Integer cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_SetSoundFonts' {$ENDIF} {$ENDIF};
634 function Mix_GetSoundFonts: PAnsiChar cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_GetSoundFonts' {$ENDIF} {$ENDIF};
637 TMix_SoundFunc = function(c: PAnsiChar; p: Pointer): Integer;
639 function Mix_EachSoundFont(func: TMix_SoundFunc; data: Pointer): Integer cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_EachSoundFont' {$ENDIF} {$ENDIF};
641 {* Get the Mix_Chunk currently associated with a mixer channel
642 Returns NULL if it's an invalid channel, or there's no chunk associated.
644 function Mix_GetChunk(channel: Integer): PMix_Chunk cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_GetChunk' {$ENDIF} {$ENDIF};
646 {* Close the mixer, halting all playing audio *}
647 procedure Mix_CloseAudio cdecl; external MIX_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_MIX_CloseAudio' {$ENDIF} {$ENDIF};
649 {* We'll use SDL for reporting errors *}
650 function Mix_SetError(const fmt: PAnsiChar): SInt32;
651 function Mix_GetError: PAnsiChar;
655 procedure SDL_MIXER_VERSION(X: PSDL_Version);
657 X.major := SDL_MIXER_MAJOR_VERSION;
658 X.minor := SDL_MIXER_MINOR_VERSION;
659 X.patch := SDL_MIXER_PATCHLEVEL;
662 procedure MIX_VERSION(X: PSDL_Version);
664 SDL_MIXER_VERSION(X);
667 function Mix_FadeInChannel(channel: Integer; chunk: PMix_Chunk; loops: Integer; ms: Integer): Integer;
669 Result := Mix_FadeInChannelTimed(channel, chunk, loops, ms, -1);
672 function Mix_PlayChannel(channel: Integer; chunk: PMix_Chunk; loops: Integer): Integer;
674 Result := Mix_PlayChannelTimed(channel, chunk, loops, -1);
677 function Mix_LoadWAV(_file: PAnsiChar): PMix_Chunk;
679 Result := Mix_LoadWAV_RW(SDL_RWFromFile(_file, 'rb'), 1);
682 function Mix_SetError(const fmt: PAnsiChar): SInt32;
684 Result := SDL_SetError(fmt);
687 function Mix_GetError: PAnsiChar;
689 Result := SDL_GetError;