Channels
========

These functions work with sound effect mixer channels.  Music is not affected by these functions.

Mix_AllocateChannels
--------------------

int Mix_AllocateChannels(int NUMCHANS)

numchans
     Number of channels to allocate for mixing.

     A negative number will not do anything, it will tell you how many channels are currently allocated.

Set the number of channels being mixed.  This can be called multiple times, even with sounds playing.  If NUMCHANS is less than the current number of channels, then the higher channels will be stopped, freed, and therefore not mixed any longer.  It's probably not a good idea to change the size 1000 times a second though.

If any channels are deallocated, any callback set by Mix_ChannelFinished will be called when each channel is halted to be freed. Note: passing in zero WILL free all mixing channels, however music will still play.

Returns: The number of channels allocated.  Never fails...but a high number of channels can segfault if you run out of memory.  We're talking REALLY high!

     // allocate 16 mixing channels
     Mix_AllocateChannels(16);

See Also:

Mix_OpenAudio

Mix_Volume
----------

int Mix_Volume(int CHANNEL, int VOLUME)

channel
     Channel to set mix volume for.

     -1 will set the volume for all allocated channels.

volume
     The volume to use from 0 to MIX_MAX_VOLUME(128).

     If greater than MIX_MAX_VOLUME,
      then it will be set to MIX_MAX_VOLUME.

     If less than 0 then the volume will not be set.

Set the volume for any allocated channel.  If CHANNEL is -1 then all channels at are set at once.  The VOLUME is applied during the final mix, along with the sample volume.  So setting this volume to 64 will halve the output of all samples played on the specified channel.  All channels default to a volume of 128, which is the max.  Newly allocated channels will have the max volume set, so setting all channels volumes does not affect subsequent channel allocations.

Returns: current volume of the channel. If channel is -1, the average volume is returned.

     // set channel 1 to half volume
     Mix_Volume(1,MIX_MAX_VOLUME/2);

     // print the average volume
     printf("Average volume is %d\n",Mix_Volume(-1,-1));

See Also:

Mix_VolumeChunk, Mix_VolumeMusic

Mix_PlayChannel
---------------

int Mix_PlayChannel(int CHANNEL, Mix_Chunk *CHUNK, int LOOPS)

channel
     Channel to play on, or -1 for the first free unreserved channel.

chunk
     Sample to play.

loops
     Number of loops, -1 is infinite loops.

     Passing one here plays the sample twice (1 loop).

Play CHUNK on CHANNEL, or if CHANNEL is -1, pick the first free unreserved channel. The sample will play for LOOPS+1 number of times, unless stopped by halt, or fade out, or setting a new expiration time of less time than it would have originally taken to play the loops, or closing the mixer.

Note: this just calls Mix_PlayChannelTimed() with TICKS set to -1.

Returns: the channel the sample is played on.  On any errors, -1 is returned.

     // play sample on first free unreserved channel
     // play it exactly once through
     // Mix_Chunk *sample; //previously loaded
     if(Mix_PlayChannel(-1, sample, 0)==-1) {
         printf("Mix_PlayChannel: %s\n",Mix_GetError());
         // may be critical error, or maybe just no channels were free.
         // you could allocated another channel in that case...
     }

See Also:

Mix_PlayChannelTimed, Mix_PlayChannelVol, Mix_PlayChannelTimedVolume, Mix_FadeInChannel, Mix_FadeInChannelTimed, Mix_FadeInChannelVolume, Mix_FadeInChannelTimedVolume, Mix_HaltChannel, Mix_ExpireChannel, Mix_ReserveChannels

Mix_PlayChannelTimed
--------------------

int Mix_PlayChannelTimed(int CHANNEL, Mix_Chunk *CHUNK, int LOOPS, int TICKS)

channel
     Channel to play on, or -1 for the first free unreserved channel.

chunk
     Sample to play.

loops
     Number of loops, -1 is infinite loops.

     Passing one here plays the sample twice (1 loop).

ticks
     Millisecond limit to play sample, at most.

     If not enough LOOPS or the sample CHUNK is not long enough, then the sample may stop before this timeout occurs.

     -1 means play forever.

If the sample is long enough and has enough loops then the sample will stop after TICKS milliseconds. Otherwise this function is the same as Mix_PlayChannel.

Returns: the channel the sample is played on.  On any errors, -1 is returned.

     // play sample on first free unreserved channel
     // play it for half a second
     // Mix_Chunk *sample; //previously loaded
     if(Mix_PlayChannelTimed(-1, sample, -1 , 500)==-1) {
         printf("Mix_PlayChannel: %s\n",Mix_GetError());
         // may be critical error, or maybe just no channels were free.
         // you could allocated another channel in that case...
     }

See Also:

Mix_PlayChannel, Mix_PlayChannelVol, Mix_PlayChannelTimedVolume, Mix_FadeInChannelTimed, Mix_FadeInChannelVolume, Mix_FadeInChannelTimedVolume, Mix_FadeOutChannel, Mix_ReserveChannels

Mix_PlayChannelVol
------------------

int Mix_PlayChannelVol(int CHANNEL, Mix_Chunk *CHUNK, int LOOPS, int VOL)

channel
     Channel to play on, or -1 for the first free unreserved channel.

chunk
     Sample to play.

loops
     Number of loops, -1 is infinite loops.

     Passing one here plays the sample twice (1 loop).

vol
     Initial volume level between 0 and MIX_MAX_VOLUME

Play CHUNK on CHANNEL, or if CHANNEL is -1, pick the first free unreserved channel. The VOL will set initial channel volume. The sample will play for LOOPS+1 number of times, unless stopped by halt, or fade out, or setting a new expiration time of less time than it would have originally taken to play the loops, or closing the mixer.

Note: this just calls Mix_PlayChannelTimed() with TICKS set to -1.

Returns: the channel the sample is played on.  On any errors, -1 is returned.

     // play sample on first free unreserved channel
     // play it exactly once through
     // Mix_Chunk *sample; //previously loaded
     if(Mix_PlayChannelVol(-1, sample, 0, 56)==-1) {
         printf("Mix_PlayChannelVol: %s\n",Mix_GetError());
         // may be critical error, or maybe just no channels were free.
         // you could allocated another channel in that case...
     }

See Also:

Mix_PlayChannel, Mix_PlayChannelTimed, Mix_PlayChannelTimedVolume, Mix_FadeInChannel, Mix_FadeInChannelTimed, Mix_FadeInChannelVolume, Mix_FadeInChannelTimedVolume, Mix_HaltChannel, Mix_ExpireChannel, Mix_ReserveChannels

Mix_PlayChannelTimedVolume
--------------------------

int Mix_PlayChannelTimedVolume(int CHANNEL, Mix_Chunk *CHUNK, int LOOPS, int TICKS)

channel
     Channel to play on, or -1 for the first free unreserved channel.

chunk
     Sample to play.

loops
     Number of loops, -1 is infinite loops.

     Passing one here plays the sample twice (1 loop).

ticks
     Millisecond limit to play sample, at most.

     If not enough LOOPS or the sample CHUNK is not long enough, then the sample may stop before this timeout occurs.

     -1 means play forever.

vol
     Initial volume level between 0 and MIX_MAX_VOLUME

If the sample is long enough and has enough loops then the sample will stop after TICKS milliseconds. Otherwise this function is the same as Mix_PlayChannelVol.

Returns: the channel the sample is played on.  On any errors, -1 is returned.

     // play sample on first free unreserved channel
     // play it for half a second
     // Mix_Chunk *sample; //previously loaded
     if(Mix_PlayChannelTimedVolume(-1, sample, -1 , 500, 80)==-1) {
         printf("Mix_PlayChannel: %s\n",Mix_GetError());
         // may be critical error, or maybe just no channels were free.
         // you could allocated another channel in that case...
     }

See Also:

Mix_PlayChannel, Mix_PlayChannelVol, Mix_FadeInChannelTimed, Mix_FadeInChannelVolume, Mix_FadeInChannelTimedVolume, Mix_FadeOutChannel, Mix_ReserveChannels

Mix_FadeInChannel
-----------------

int Mix_FadeInChannel(int CHANNEL, Mix_Chunk *CHUNK, int LOOPS, int MS)

channel
     Channel to play on, or -1 for the first free unreserved channel.

chunk
     Sample to play.

loops
     Number of loops, -1 is infinite loops.

     Passing one here plays the sample twice (1 loop).

ms
     Milliseconds of time that the fade-in effect should take to go from silence to full volume.

Play CHUNK on CHANNEL, or if CHANNEL is -1, pick the first free unreserved channel.

The channel volume starts at 0 and fades up to full volume over MS milliseconds of time.  The sample may end before the fade-in is complete if it is too short or doesn't have enough loops. The sample will play for LOOPS+1 number of times, unless stopped by halt, or fade out, or setting a new expiration time of less time than it would have originally taken to play the loops, or closing the mixer.

Note: this just calls Mix_FadeInChannelTimed() with TICKS set to -1.

Returns: the channel the sample is played on.  On any errors, -1 is returned.

     // play sample on first free unreserved channel
     // play it exactly 3 times through
     // fade in over one second
     // Mix_Chunk *sample; //previously loaded
     if(Mix_FadeInChannel(-1, sample, 2, 1000)==-1) {
         printf("Mix_FadeInChannel: %s\n",Mix_GetError());
         // may be critical error, or maybe just no channels were free.
         // you could allocated another channel in that case...
     }

See Also:

Mix_PlayChannel, Mix_PlayChannelVol, Mix_PlayChannelTimedVolume, Mix_FadeInChannelTimed, Mix_FadeInChannelVolume, Mix_FadeInChannelTimedVolume, Mix_FadingChannel, Mix_FadeOutChannel, Mix_ReserveChannels

Mix_FadeInChannelTimed
----------------------

     int Mix_FadeInChannelTimed(int CHANNEL, Mix_Chunk *CHUNK,
                                int LOOPS, int MS, int TICKS)

channel
     Channel to play on, or -1 for the first free unreserved channel.

chunk
     Sample to play.

loops
     Number of loops, -1 is infinite loops.

     Passing one here plays the sample twice (1 loop).

ms
     Milliseconds of time that the fade-in effect should take to go from silence to full volume.

ticks
     Millisecond limit to play sample, at most.

     If not enough LOOPS or the sample CHUNK is not long enough, then the sample may stop before this timeout occurs.

     -1 means play forever.

If the sample is long enough and has enough loops then the sample will stop after TICKS milliseconds. Otherwise this function is the same as Mix_FadeInChannel.

Returns: the channel the sample is played on.  On any errors, -1 is returned.

     // play sample on first free unreserved channel
     // play it for half a second
     // Mix_Chunk *sample; //previously loaded
     if(Mix_PlayChannelTimed(-1, sample, -1 , 500)==-1) {
         printf("Mix_PlayChannel: %s\n",Mix_GetError());
         // may be critical error, or maybe just no channels were free.
         // you could allocated another channel in that case...
     }

See Also:

Mix_PlayChannelTimed, Mix_PlayChannelVol, Mix_PlayChannelTimedVolume, Mix_FadeInChannel, Mix_FadeInChannelVolume, Mix_FadeInChannelTimedVolume, Mix_FadingChannel, Mix_HaltChannel, Mix_ExpireChannel, Mix_ReserveChannels

Mix_FadeInChannelVolume
-----------------------

int Mix_FadeInChannelVolume(int CHANNEL, Mix_Chunk *CHUNK, int LOOPS, int MS, int VOL)

channel
     Channel to play on, or -1 for the first free unreserved channel.

chunk
     Sample to play.

loops
     Number of loops, -1 is infinite loops.

     Passing one here plays the sample twice (1 loop).

ms
     Milliseconds of time that the fade-in effect should take to go from silence to full volume.

vol
     Initial volume level between 0 and MIX_MAX_VOLUME

Play CHUNK on CHANNEL, or if CHANNEL is -1, pick the first free unreserved channel.

The channel volume starts at 0 and fades up to full volume over MS milliseconds of time.  The sample may end before the fade-in is complete if it is too short or doesn't have enough loops. The sample will play for LOOPS+1 number of times, unless stopped by halt, or fade out, or setting a new expiration time of less time than it would have originally taken to play the loops, or closing the mixer.

The VOL will set initial channel volume. Note: this just calls Mix_FadeInChannelTimed() with TICKS set to -1.

Returns: the channel the sample is played on.  On any errors, -1 is returned.

     // play sample on first free unreserved channel
     // play it exactly 3 times through
     // fade in over one second
     // Mix_Chunk *sample; //previously loaded
     if(Mix_FadeInChannelVolume(-1, sample, 2, 1000, 70)==-1) {
         printf("Mix_FadeInChannel: %s\n",Mix_GetError());
         // may be critical error, or maybe just no channels were free.
         // you could allocated another channel in that case...
     }

See Also:

Mix_PlayChannel, Mix_PlayChannelVol, Mix_PlayChannelTimedVolume, Mix_FadeInChannelTimed, Mix_FadeInChannelTimedVolume, Mix_FadingChannel, Mix_FadeOutChannel, Mix_ReserveChannels

Mix_FadeInChannelTimedVolume
----------------------------

     int Mix_FadeInChannelTimedVolume(int CHANNEL, Mix_Chunk *CHUNK,
                                int LOOPS, int MS, int TICKS, int VOL)

channel
     Channel to play on, or -1 for the first free unreserved channel.

chunk
     Sample to play.

loops
     Number of loops, -1 is infinite loops.

     Passing one here plays the sample twice (1 loop).

ms
     Milliseconds of time that the fade-in effect should take to go from silence to full volume.

ticks
     Millisecond limit to play sample, at most.

     If not enough LOOPS or the sample CHUNK is not long enough, then the sample may stop before this timeout occurs.

     -1 means play forever.

vol
     Initial volume level between 0 and MIX_MAX_VOLUME

If the sample is long enough and has enough loops then the sample will stop after TICKS milliseconds. Otherwise this function is the same as Mix_FadeInChannelVolume.

Returns: the channel the sample is played on.  On any errors, -1 is returned.

     // play sample on first free unreserved channel
     // play it for half a second
     // Mix_Chunk *sample; //previously loaded
     if(Mix_FadeInChannelTimedVolume(-1, sample, -1 , 500, 78)==-1) {
         printf("Mix_PlayChannel: %s\n",Mix_GetError());
         // may be critical error, or maybe just no channels were free.
         // you could allocated another channel in that case...
     }

See Also:

Mix_PlayChannelTimed, Mix_PlayChannelVol, Mix_PlayChannelTimedVolume, Mix_FadeInChannel, Mix_FadeInChannelTimed, Mix_FadeInChannelVolume, Mix_FadingChannel, Mix_HaltChannel, Mix_ExpireChannel, Mix_ReserveChannels

Mix_Pause
---------

void Mix_Pause(int CHANNEL)

channel
     Channel to pause on, or -1 for all channels.

Pause CHANNEL, or all playing channels if -1 is passed in.  You may still halt a paused channel.

Note: Only channels which are actively playing will be paused.

     // pause all sample playback
     Mix_Pause(-1);

See Also:

Mix_Resume, Mix_Paused, Mix_HaltChannel

Mix_Resume
----------

void Mix_Resume(int CHANNEL)

channel
     Channel to resume playing, or -1 for all channels.

Unpause CHANNEL, or all playing and paused channels if -1 is passed in.

     // resume playback on all previously active channels
     Mix_Resume(-1);

See Also:

Mix_Pause, Mix_Paused

Mix_HaltChannel
---------------

int Mix_HaltChannel(int CHANNEL)

channel
     Channel to stop playing, or -1 for all channels.

Halt CHANNEL playback, or all channels if -1 is passed in.

Any callback set by Mix_ChannelFinished will be called.

Returns: always returns zero. (kinda silly)

     // halt playback on all channels
     Mix_HaltChannel(-1);

See Also:

Mix_ExpireChannel, Mix_FadeOutChannel, Mix_ChannelFinished

Mix_ExpireChannel
-----------------

int Mix_ExpireChannel(int CHANNEL, int TICKS)

channel
     Channel to stop playing, or -1 for all channels.

ticks
     Millisecons until channel(s) halt playback.

Halt CHANNEL playback, or all channels if -1 is passed in, after TICKS milliseconds. Any callback set by Mix_ChannelFinished will be called when the channel expires.

Returns: Number of channels set to expire.  Whether or not they are active.

     // halt playback on all channels in 2 seconds
     Mix_ExpireChannel(-1, 2000);

See Also:

Mix_HaltChannel, Mix_FadeOutChannel, Mix_ChannelFinished

Mix_FadeOutChannel
------------------

int Mix_FadeOutChannel(int CHANNEL, int MS)

channel
     Channel to fade out, or -1 to fade all channels out.

ms
     Milliseconds of time that the fade-out effect should take to go to silence, starting now.

Gradually fade out WHICH channel over MS milliseconds starting from now. The channel will be halted after the fade out is completed.  Only channels that are playing are set to fade out, including paused channels. Any callback set by Mix_ChannelFinished will be called when the channel finishes fading out.

Returns: The number of channels set to fade out.

     // fade out all channels to finish 3 seconds from now
     printf("starting fade out of %d channels\n", Mix_FadeOutChannel(-1, 3000));

See Also:

Mix_FadeInChannel, Mix_FadeInChannelTimed, Mix_FadingChannel, Mix_ChannelFinished

Mix_ChannelFinished
-------------------

void Mix_ChannelFinished(void (*CHANNEL_FINISHED)(int channel))

channel_finished
     Function to call when any channel finishes playback.

When CHANNEL playback is halted, then the specified CHANNEL_FINISHED function is called.  The channel parameter will contain the channel number that has finished.

NOTE: NEVER call SDL_Mixer functions, nor SDL_LockAudio, from a callback function.

     // a simple channel_finished function
     void channelDone(int channel) {
         printf("channel %d finished playback.\n",channel);
     }

     // make a channelDone function
     void channelDone(int channel)
     {
         printf("channel %d finished playing.\n", channel);
     }
     ...
     // set the callback for when a channel stops playing
     Mix_ChannelFinished(channelDone);

See Also:

Mix_HaltChannel, Mix_ExpireChannel

Mix_Playing
-----------

int Mix_Playing(int CHANNEL)

channel
     Channel to test whether it is playing or not.

     -1 will tell you how many channels are playing.

Tells you if CHANNEL is playing, or not.

Note: Does not check if the channel has been paused.

Returns: Zero if the channel is not playing.  Otherwise if you passed in -1, the number of channels playing is returned.  If you passed in a specific channel, then 1 is returned if it is playing.

     // check how many channels are playing samples
     printf("%d channels are playing\n", Mix_Playing(-1));

See Also:

Mix_Paused, Mix_Fading, Mix_PlayChannel, Mix_Pause,

Mix_Paused
----------

int Mix_Paused(int CHANNEL)

channel
     Channel to test whether it is paused or not.

     -1 will tell you how many channels are paused.

Tells you if CHANNEL is paused, or not.

Note: Does not check if the channel has been halted after it was paused, which may seem a little weird.

Returns: Zero if the channel is not paused.  Otherwise if you passed in -1, the number of paused channels is returned.  If you passed in a specific channel, then 1 is returned if it is paused.

     // check the pause status on all channels
     printf("%d channels are paused\n", Mix_Paused(-1));

See Also:

Mix_Playing, Mix_Pause, Mix_Resume

Mix_FadingChannel
-----------------

Mix_Fading Mix_FadingChannel(int WHICH)

which
     Channel to get the fade activity status from.

     -1 is not valid, and will probably crash the program.

Tells you if WHICH channel is fading in, out, or not.  Does not tell you if the channel is playing anything, or paused, so you'd need to test that separately.

Returns: the fading status.  Never returns an error.

     // check the fade status on channel 0
     switch(Mix_FadingChannel(0)) {
         case MIX_NO_FADING:
             printf("Not fading.\n");
             break;
         case MIX_FADING_OUT:
             printf("Fading out.\n");
             break;
         case MIX_FADING_IN:
             printf("Fading in.\n");
             break;
     }

See Also:

Mix_Fading, Mix_Playing, Mix_Paused, Mix_FadeInChannel, Mix_FadeInChannelTimed, Mix_FadeOutChannel

Mix_GetChunk
------------

Mix_Chunk *Mix_GetChunk(int CHANNEL)

channel
     Channel to get the current Mix_Chunk playing.

     -1 is not valid, but will not crash the program.

Get the most recent sample chunk pointer played on CHANNEL.  This pointer may be currently playing, or just the last used.

Note: The actual chunk may have been freed, so this pointer may not be valid anymore.

Returns: Pointer to the Mix_Chunk.  NULL is returned if the channel is not allocated, or if the channel has not played any samples yet.

     // get the last chunk used by channel 0
     printf("Mix_Chunk* last in use on channel 0 was: %08p\n", Mix_GetChunk(0));

See Also:

Mix_Chunk, Mix_Playing