Groups
======

These functions work with groupings of mixer channels.

The default group tag number of -1, which refers to ALL channels.

Mix_ReserveChannels
-------------------

int Mix_ReserveChannels(int NUM)

num
     Number of channels to reserve from default mixing.

     Zero removes all reservations.

Reserve NUM channels from being used when playing samples when passing in -1 as a channel number to playback functions. The channels are reserved starting from channel 0 to NUM-1. Passing in zero will unreserve all channels. Normally SDL_mixer starts without any channels reserved.

The following functions are affected by this setting:

Mix_PlayChannel

Mix_PlayChannelTimed

Mix_FadeInChannel

Mix_FadeInChannelTimed

Returns: The number of channels reserved.  Never fails, but may return less channels than you ask for, depending on the number of channels previously allocated.

     // reserve the first 8 mixing channels
     int reserved_count;
     reserved_count=Mix_ReserveChannels(8);
     if(reserved_count!=8) {
         printf("reserved %d channels from default mixing.\n",reserved_count);
         printf("8 channels were not reserved!\n");
         // this might be a critical error...
     }

See Also:

Mix_AllocateChannels

Mix_GroupChannel
----------------

int Mix_GroupChannel(int WHICH, int TAG)

which
     Channel number of channels to assign TAG to.

tag
     A group number Any positive numbers (including zero).

     -1 is the default group.  Use -1 to remove a group tag essentially.

Add WHICH channel to group TAG, or reset it's group to the default group tag (-1).

Returns: True(1) on success. False(0) is returned when the channel specified is invalid.

     // add channel 0 to group 1
     if(!Mix_GroupChannel(0,1)) {
         // bad channel, apparently channel 1 isn't allocated
     }

See Also:

Mix_GroupChannels, Mix_AllocateChannels

Mix_GroupChannels
-----------------

int Mix_GroupChannels(int FROM, int TO, int TAG)

from
     First Channel number of channels to assign TAG to.  Must be less or equal to TO.

to
     Last Channel number of channels to assign TAG to.  Must be greater or equal to FROM.

tag
     A group number.  Any positive numbers (including zero).

     -1 is the default group.  Use -1 to remove a group tag essentially.

Add channels starting at FROM up through TO to group TAG, or reset it's group to the default group tag (-1).

Returns: The number of tagged channels on success. If that number is less than TO-FROM+1 then some channels were no tagged because they didn't exist.

     // add channels 0 through 7 to group 1
     if(Mix_GroupChannels(0,7,1)!=8) {
         // some bad channels, apparently some channels aren't allocated
     }

See Also:

Mix_GroupChannel, Mix_AllocateChannels

Mix_GroupCount
--------------

int Mix_GroupCount(int TAG)

tag
     A group number Any positive numbers (including zero).

     -1 will count ALL channels.

Count the number of channels in group TAG.

Returns: The number of channels found in the group.  This function never fails.

     // count the number of channels in group 1
     printf("There are %d channels in group 1\n", Mix_GroupCount(1));

See Also:

Mix_GroupChannel, Mix_GroupChannels

Mix_GroupAvailable
------------------

int Mix_GroupAvailable(int TAG)

tag
     A group number Any positive numbers (including zero).

     -1 will search ALL channels.

Find the first available (not playing) channel in group TAG.

Returns: The channel found on success. -1 is returned when no channels in the group are available.

     // find the first available channel in group 1
     int channel;
     channel=Mix_GroupAvailable(1);
     if (channel==-1) {
         // no channel available...
         // perhaps search for oldest or newest channel in use...
     }

See Also:

Mix_GroupOldest, Mix_GroupNewer, Mix_GroupChannel, Mix_GroupChannels

Mix_GroupOldest
---------------

int Mix_GroupOldest(int TAG)

tag
     A group number Any positive numbers (including zero).

     -1 will search ALL channels.

Find the oldest actively playing channel in group TAG.

Returns: The channel found on success. -1 is returned when no channels in the group are playing or the group is empty.

     // find the oldest playing channel in group 1
     int channel;
     channel=Mix_GroupOldest(1);
     if (channel==-1) {
         // no channel playing or allocated...
         // perhaps just search for an available channel...
     }

See Also:

Mix_GroupNewer, Mix_GroupAvailable, Mix_GroupChannel, Mix_GroupChannels

Mix_GroupNewer
--------------

int Mix_GroupNewer(int TAG)

tag
     A group number Any positive numbers (including zero).

     -1 will search ALL channels.

Find the newest, most recently started, actively playing channel in group TAG.

Returns: The channel found on success. -1 is returned when no channels in the group are playing or the group is empty.

     // find the newest playing channel in group 1
     int channel;
     channel=Mix_GroupNewer(1);
     if (channel==-1) {
         // no channel playing or allocated...
         // perhaps just search for an available channel...
     }

See Also:

Mix_GroupOldest, Mix_GroupAvailable, Mix_GroupChannel, Mix_GroupChannels

Mix_FadeOutGroup
----------------

int Mix_FadeOutGroup(int TAG, int MS)

tag
     Group to fade out.

     NOTE: -1 will NOT fade all channels out.  Use Mix_FadeOutChannel(-1) for that instead.

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

Gradually fade out channels in group TAG over MS milliseconds starting from now. The channels 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 each channel finishes fading out.

Returns: The number of channels set to fade out.

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

See Also:

Mix_HaltGroup, Mix_FadeOutChannel, Mix_FadingChannel, Mix_ChannelFinished

Mix_HaltGroup
-------------

int Mix_HaltGroup(int TAG)

tag
     Group to fade out.

     NOTE: -1 will NOT halt all channels.  Use Mix_HaltChannel(-1) for that instead.

Halt playback on all channels in group TAG.

Any callback set by Mix_ChannelFinished will be called once for each channel that stops.

Returns: always returns zero. (more silly than MIX_HALTCHANNEL)

     // halt playback on all channels in group 1
     Mix_HaltGroup(1);

See Also:

Mix_FadeOutGroup, Mix_HaltChannel, Mix_ChannelFinished