General
=======

These functions are useful, as they are the only/best ways to work with SDL_mixer.

Mix_Linked_Version
------------------

const SDL_version *Mix_Linked_Version()

void SDL_MIXER_VERSION(SDL_version *compile_version)

This works similar to SDL_Linked_Version and SDL_VERSION.

Using these you can compare the runtime version to the version that you compiled with.

     SDL_version compile_version;
     const SDL_version *link_version=Mix_Linked_Version();
     SDL_MIXER_VERSION(&compile_version);
     printf("compiled with SDL_mixer version: %d.%d.%d\n",
             compile_version.major,
             compile_version.minor,
             compile_version.patch);
     printf("running with SDL_mixer version: %d.%d.%d\n",
             link_version->major,
             link_version->minor,
             link_version->patch);

See Also:

Mix_OpenAudio, Mix_QuerySpec

Mix_Init
--------

int Mix_Init(int FLAGS)

flags
     bitwise OR'd set of sample/music formats to support by loading a library now.  The values you may OR together to pass in are:

     MIX_INIT_FLAC

     MIX_INIT_MOD

     MIX_INIT_MP3

     MIX_INIT_OGG

     MIX_INIT_MID

     MIX_INIT_OPUS

Initialize by loading support as indicated by the FLAGS, or at least return success if support is already loaded.  You may call this multiple times, which will actually require you to call Mix_Quit just once to clean up.  You may call this function with a 0 to retrieve whether support was built-in or not loaded yet.

Note: you can call Mix_Init with the right MIX_INIT_* flags OR'd together before you program gets busy, to prevent a later hiccup while it loads and unloads the library, and to check that you do have the support that you need before you try and use it.

Note: this function does not always set the error string, so do not depend on Mix_GetError being meaningful all the time.

Returns: a bitmask of all the currently initted sample/music loaders.

     // load support for the OGG and MOD sample/music formats
     int flags=MIX_INIT_OGG|MIX_INIT_MOD;
     int initted=Mix_Init(flags);
     if(initted&flags != flags) {
         printf("Mix_Init: Failed to init required ogg and mod support!\n");
         printf("Mix_Init: %s\n", Mix_GetError());
         // handle error
     }

See Also:

Mix_Quit

Mix_Quit
--------

void Mix_Quit()

This function cleans up all dynamically loaded library handles, freeing memory.  If support is required again it will be initialized again, either by Mix_Init or loading a sample or some music with dynamic support required.  You may call this function when Mix_Load functions are no longer needed for the MIX_INIT_* formats.  You should call this function for each time Mix_Init was called, otherwise it may not free all the dynamic library resources until the program ends.  This is done so that multiple unrelated modules of a program may call Mix_Init and Mix_Quit without affecting the others performance and needs.

     // indicate that we are ready to unload the dynamically loaded libraries
     Mix_Quit();

NOTE: Since each call to Mix_Init may set different flags, there is no way, currently, to request how many times each one was initted.  In other words, the only way to quit for sure is to do a loop like so:

     // force a quit
     while(Mix_Init(0))
         Mix_Quit();

See Also:

Mix_Init

Mix_OpenAudio
-------------

int Mix_OpenAudio(int FREQUENCY, Uint16 FORMAT, int CHANNELS, int CHUNKSIZE)

frequency
     Output sampling frequency in samples per second (Hz).

     you might use MIX_DEFAULT_FREQUENCY(44100) since that is a good value for most games.

format
     Output sample format.

channels
     Number of sound channels in output.

     Set to 2 for stereo, 1 for mono. This has nothing to do with mixing channels.

chunksize
     Bytes used per output sample.

Initialize the mixer API.

This must be called before using other functions in this library.

SDL must be initialized with SDL_INIT_AUDIO before this call. FREQUENCY would be 44100 for 44.1KHz, which is CD audio rate.  Some games use 22050, because 44100 requires too much CPU power on very old computers. CHUNKSIZE is the size of each mixed sample.  The smaller this is the more your hooks will be called.  If make this too small on a slow system, sound may skip.  If made to large, sound effects will lag behind the action more.  You want a happy medium for your target computer.  You also may make this 4096, or larger, if you are just playing music. MIX_CHANNELS(8) mixing channels will be allocated by default. You may call this function multiple times, however you will have to call Mix_CloseAudio just as many times for the device to actually close.  The format will not changed on subsequent calls until fully closed.  So you will have to close all the way before trying to open with different format parameters.

FORMAT is based on SDL audio support, see SDL_audio.h. Here are the values listed there:

AUDIO_U8
     Unsigned 8-bit samples

AUDIO_S8
     Signed 8-bit samples

AUDIO_U16LSB
     Unsigned 16-bit samples, in little-endian byte order

AUDIO_S16LSB
     Signed 16-bit samples, in little-endian byte order

AUDIO_U16MSB
     Unsigned 16-bit samples, in big-endian byte order

AUDIO_S16MSB
     Signed 16-bit samples, in big-endian byte order

AUDIO_U16
     same as AUDIO_U16LSB (for backwards compatability probably)

AUDIO_S16
     same as AUDIO_S16LSB (for backwards compatability probably)

AUDIO_U16SYS
     Unsigned 16-bit samples, in system byte order

AUDIO_S16SYS
     Signed 16-bit samples, in system byte order

AUDIO_S32LSB
     Signed 32-bit samples, in little-endian byte order

AUDIO_S32MSB
     Signed 32-bit samples, in bin-endian byte order

AUDIO_S32
     same as AUDIO_S32LSB (for backwards compatability probably)

AUDIO_S32SYS
     Signed 32-bit samples, in system byte order

AUDIO_F32LSB
     Floating 32-bit samples, in little-endian byte order

AUDIO_F32MSB
     Floating 32-bit samples, in big-endian byte order

AUDIO_F32
     same as AUDIO_F32LSB (for backwards compatability probably)

AUDIO_F32SYS
     Signed 32-bit float samples, in system byte order

MIX_DEFAULT_FORMAT is the same as AUDIO_S16SYS.

Returns: 0 on success, -1 on errors

     // start SDL with audio support
     if(SDL_Init(SDL_INIT_AUDIO)==-1) {
         printf("SDL_Init: %s\n", SDL_GetError());
         exit(1);
     }
     // open 44.1KHz, signed 16bit, system byte order,
     //      stereo audio, using 1024 byte chunks
     if(Mix_OpenAudio(44100, MIX_DEFAULT_FORMAT, 2, 1024)==-1) {
         printf("Mix_OpenAudio: %s\n", Mix_GetError());
         exit(2);
     }

See Also:

Mix_OpenAudioDevice, Mix_CloseAudio, Mix_PauseAudio, Mix_QuerySpec, Mix_AllocateChannels, Mix_OpenAudioDevice

Mix_OpenAudioDevice
-------------------

int Mix_OpenAudioDevice(int FREQUENCY, Uint16 FORMAT, int CHANNELS, int CHUNKSIZE, const char* DEVICE, int ALLOWED_CHANGES)

frequency
     Output sampling frequency in samples per second (Hz).

     you might use MIX_DEFAULT_FREQUENCY(44100) since that is a good value for most games.

format
     Output sample format. See Mix_OpenAudio for the table of available formats.

channels
     Number of sound channels in output.

     Set to 2 for stereo, 1 for mono. This has nothing to do with mixing channels.

chunksize
     Bytes used per output sample.

device
     A UTF-8 string reported by SDL_GetAudioDeviceName() or a driver-specific name as appropriate. NULL requests the most reasonable default device.

allowed_changes
     0, or one or more flags OR'd together.

Initialize the mixer API.

This must be called before using other functions in this library.

SDL must be initialized with SDL_INIT_AUDIO before this call. FREQUENCY would be 44100 for 44.1KHz, which is CD audio rate. Some games use 22050, because 44100 requires too much CPU power on very old computers. CHUNKSIZE is the size of each mixed sample.  The smaller this is the more your hooks will be called.  If make this too small on a slow system, sound may skip.  If made to large, sound effects will lag behind the action more.  You want a happy medium for your target computer.  You also may make this 4096, or larger, if you are just playing music. MIX_CHANNELS(8) mixing channels will be allocated by default. You may call this function multiple times, however you will have to call Mix_CloseAudio just as many times for the device to actually close.  The format will not changed on subsequent calls until fully closed.  So you will have to close all the way before trying to open with different format parameters.

Returns: 0 on success, -1 on errors

     // start SDL with audio support
     if(SDL_Init(SDL_INIT_AUDIO)==-1) {
         printf("SDL_Init: %s\n", SDL_GetError());
         exit(1);
     }
     // open 44.1KHz, signed 16bit, system byte order,
     //      stereo audio, using 1024 byte chunks
     if(Mix_OpenAudioDevice(44100, MIX_DEFAULT_FORMAT, 2, 1024, NULL,
                             SDL_AUDIO_ALLOW_FREQUENCY_CHANGE |
                             SDL_AUDIO_ALLOW_CHANNELS_CHANGE)==-1) {
         printf("Mix_OpenAudioDevice: %s\n", Mix_GetError());
         exit(2);
     }

See Also:

Mix_OpenAudio, Mix_CloseAudio, Mix_PauseAudio, Mix_QuerySpec, Mix_AllocateChannels, Mix_OpenAudio

Mix_PauseAudio
--------------

void Mix_PauseAudio(int PAUSE_ON)

Pauses or resume the whole audio processing: all playing music and channels will get paused synchroniously.

pause_on
     1 pauses the whole audio processing, 0 resumes the audio processing back.

See Also:

Mix_OpenAudio, Mix_OpenAudioDevice, Mix_CloseAudio, Mix_QuerySpec, Mix_AllocateChannels, Mix_OpenAudio

Mix_CloseAudio
--------------

void Mix_CloseAudio()

Shutdown and cleanup the mixer API.

After calling this all audio is stopped, the device is closed, and the SDL_mixer functions should not be used. You may, of course, use Mix_OpenAudio to start the functionality again.

Note: This function doesn't do anything until you have called it the same number of times that you called Mix_OpenAudio. You may use Mix_QuerySpec to find out how many times Mix_CloseAudio needs to be called before the device is actually closed.

     Mix_CloseAudio();
     // you could SDL_Quit(); here...or not.

See Also:

Mix_OpenAudio, Mix_OpenAudioDevice, Mix_QuerySpec, Mix_PauseAudio,

Mix_InitMixer
-------------

void Mix_InitMixer(const SDL_AudioSpec *SPEC, SDL_bool SKIP_INIT_CHECK)

spec
     The audio spec such as frequency, sample format, number of channels, and desired chunk size, using the SDL_AudioSpec structure.

skip_init_check
     Disable the internal check of the initialization state.

Initialize the mixer API without starting the audio processing. That means, you can make your own audio processing and manually run the mixer API by using callbacks you may retrieve using Mix_GetGeneralMixer, Mix_GetMusicMixer, and Mix_GetMultiMusicMixer calls.

CAUTION: Don't even try to call this function and any of mixer callback if you initialized the mixer using Mix_OpenAudio or Mix_OpenAudioDevice calls.

See Also:

Mix_GetMusicMixer, Mix_GetMultiMusicMixer, Mix_GetGeneralMixer, Mix_FreeMixer

Mix_GetMusicMixer
-----------------

Mix_CommonMixer_t Mix_GetMusicMixer()

Returns: The mixer callback to process the single-stream music.

Get the callback to process the single-stream music out of the main process of mixer API and receive the output of currently playing single-stream music. To receive the multi-stream music output use the Mix_GetMultiMusicMixer callback.

CAUTION: Don't even try to call the returned callback if you initialized the mixer using Mix_OpenAudio or Mix_OpenAudioDevice calls.

See Also:

Mix_InitMixer, Mix_GetMultiMusicMixer, Mix_GetGeneralMixer, Mix_FreeMixer

Mix_GetMultiMusicMixer
----------------------

Mix_CommonMixer_t Mix_GetMultiMusicMixer()

Returns: The mixer callback to process the multi-stream music.

Get the callback to process the single-stream music out of the main process of mixer API and receive the output of all music streams except the single-stream music. To receive the single-stream music output use the Mix_GetMusicMixer callback.

CAUTION: Don't even try to call the returned callback if you initialized the mixer using Mix_OpenAudio or Mix_OpenAudioDevice calls.

See Also:

Mix_InitMixer, Mix_GetMusicMixer, Mix_GetGeneralMixer, Mix_FreeMixer

Mix_GetGeneralMixer
-------------------

Mix_CommonMixer_t Mix_GetMultiMusicMixer()

Returns: The mixer callback to process the general mixer API.

Get the callback to process the general Mixer API out of the main process of mixer API and receive the generated output of all playing music streams and channels.

CAUTION 1: Don't even try to call the returned callback if you initialized the mixer using Mix_OpenAudio or Mix_OpenAudioDevice calls.

CAUTION 2: Once you execute the callback returned by Mix_GetGeneralMixer()), callbacks returned by Mix_GetMusicMixer() and Mix_GetMultiMusicMixer() were already processed internally. You don't need to call them at all.

See Also:

Mix_InitMixer, Mix_GetMusicMixer, Mix_GetMultiMusicMixer, Mix_FreeMixer

Mix_FreeMixer
-------------

void Mix_FreeMixer()

Shutdown and cleanup the mixer API.

Use this call in only condition you initialized the mixer API using the Mix_InitMixer call.

CAUTION: Don't even try to call this function and any of mixer callback if you initialized the mixer using Mix_OpenAudio or Mix_OpenAudioDevice calls.

See Also:

Mix_InitMixer, Mix_GetMusicMixer, Mix_GetMultiMusicMixer, Mix_GetGeneralMixer

Mix_SetError
------------

void Mix_SetError(const char *FMT, ...)

This is the same as SDL_SetError, which sets the error string which may be fetched with Mix_GetError (or SDL_GetError). This functions acts like printf, except that it is limited to SDL_ERRBUFIZE(1024) chars in length.  It only accepts the following format types: %s, %d, %f, %p.  No variations are supported, like %.2f would not work. For any more specifics read the SDL docs.

     int mymixfunc(int i) {
         Mix_SetError("mymixfunc is not implemented! %d was passed in.",i);
         return(-1);
     }

See Also:

Mix_GetError

Mix_GetError
------------

char *Mix_GetError()

This is the same as SDL_GetError, which returns the last error set as a string which you may use to tell the user what happened when an error status has been returned from an SDL_mixer function call.

Returns: a char pointer (string) containing a humam readble version or the reason for the last error that occured.

     printf("Oh My Goodness, an error : %s", Mix_GetError());

See Also:

Mix_SetError

Mix_QuerySpec
-------------

int Mix_QuerySpec(int *FREQUENCY, Uint16 *FORMAT, int *CHANNELS)

frequency
     A pointer to an int where the frequency actually used by the opened audio device will be stored.

format
     A pointer to a Uint16 where the output format actually being used by the audio device will be stored.

channels
     A pointer to an int where the number of audio channels will be stored.

     2 will mean stereo, 1 will mean mono.

Get the actual audio format in use by the opened audio device.  This may or may not match the parameters you passed to Mix_OpenAudio.

Returns: 0 on error. If the device was open the number of times it was opened will be returned.  The values of the arguments variables are not set on an error.

     // get and print the audio format in use
     int numtimesopened, frequency, channels;
     Uint16 format;
     numtimesopened=Mix_QuerySpec(&frequency, &format, &channels);
     if(!numtimesopened) {
         printf("Mix_QuerySpec: %s\n",Mix_GetError());
     }
     else {
         char *format_str="Unknown";
         switch(format) {
             case AUDIO_U8: format_str="U8"; break;
             case AUDIO_S8: format_str="S8"; break;
             case AUDIO_U16LSB: format_str="U16LSB"; break;
             case AUDIO_S16LSB: format_str="S16LSB"; break;
             case AUDIO_U16MSB: format_str="U16MSB"; break;
             case AUDIO_S16MSB: format_str="S16MSB"; break;
             case AUDIO_S32LSB: format_str="S32LSB"; break;
             case AUDIO_S32MSB: format_str="S32MSB"; break;
             case AUDIO_F32LSB: format_str="F32LSB"; break;
             case AUDIO_F32MSB: format_str="F32MSB"; break;
         }
         printf("opened=%d times  frequency=%dHz  format=%s  channels=%d",
                 numtimesopened, frequency, format_str, channels);
     }

See Also:

Mix_OpenAudio