indexing

	description: "[

		Implements channel grouping.
		
		Use this class to group channels.
		
		Note: You should not use this class as grouping is
		available through {EM_CHANNELS}. {EM_CHANNELS}
		will do all the dirty work for you.

	]"
	date: "$Date$"
	revision: "$Revision$"

class EM_AUDIO_GROUP

inherit

	EM_SHARED_ERROR_HANDLER
		export {NONE} all end

	SDL_MIXER_FUNCTIONS_EXTERNAL
		export {NONE} all end

create

	make

feature -- Initialization

	make (a_number: like number) is
			-- Create group with `a_number'.
		do
			internal_number := a_number - 1
			create channels.make
		ensure
			number_set: number = a_number
		end

feature -- Access

	channels: DS_LINKED_LIST [INTEGER]
			-- Hold channel numbers

	number: INTEGER is
			-- Group identifier
		do
			Result := internal_number + 1
		end

	count: INTEGER is
			-- Number of channels in group
		do
			Result := mix_group_count_external (internal_number)
		ensure
			count_positiv: Result >= 0
		end

	has_available_channel: BOOLEAN is
			-- Is there an available channel?
		do
			Result := mix_group_available_external (internal_number) /= -1
		end

	first_available_channel_number: INTEGER is
			-- Returns first available (not playing) channel number in group
			-- or -1 when there is no channel available.
		do
			Result := mix_group_available_external (internal_number)
		end

	oldest_busy_channel_number: INTEGER is
			-- Returns oldest playing channel number in group
			-- or -1 when there is no channel playing.
		do
			Result := mix_group_oldest_external (internal_number)
		end

	newest_busy_channel_number: INTEGER is
			-- Returns newest playing channel number in group
			-- or -1 when there is no channel playing.
		do
			Result := mix_group_newer_external (internal_number)
		end

feature -- Operations

	add_channel (a_channel: EM_CHANNEL) is
			-- Add `a_channel' to group as last element.
		require
			channel_not_void: a_channel /= Void
		local
			i: INTEGER
		do
			channels.put_last (a_channel.number - 1)
			i := mix_group_channel_external (a_channel.number - 1, internal_number)
			if i = 0 then
				error_handler.raise_error (error_handler.Em_error_grouping_channels, [])
			end
		end

	add_channels (from_channel_number: INTEGER; to_channel_number: INTEGER) is
			-- Add channels `from_channel_number' up to and including `to_channel_number'.
		require
			from_channel_greater_or_equal_to_channel: from_channel_number >= to_channel_number
			from_channel_number_positiv: from_channel_number > 0
		local
			i: INTEGER
		do
			from
				i := from_channel_number
			until
				i > to_channel_number
			loop
				channels.put_last (i)
				i := i + 1
			end
			i := mix_group_channels_external (from_channel_number - 1, to_channel_number - 1, internal_number)
			if (to_channel_number - from_channel_number) < i then
				error_handler.raise_error (error_handler.em_error_grouping_channels, [from_channel_number, to_channel_number])
			end
		end

	remove_channel (a_channel: EM_CHANNEL) is
			-- Remove `a_channel' from group.
		require
			a_channel_not_void: a_channel /= Void
		local
			i: INTEGER
		do
			channels.delete (a_channel.number - 1)
			i := mix_group_channel_external (a_channel.number - 1, -1)
			if i = 0 then
				error_handler.raise_error (error_handler.Em_error_grouping_channels, [])
			end
		end

	remove_channels (from_channel_number: INTEGER; to_channel_number: INTEGER) is
			-- Remove channels `from_channel_number' up to and including `to_channel_number'.
		require
			from_channel_greater_or_equal_to_channel: from_channel_number >= to_channel_number
			from_channel_number_positiv: from_channel_number > 0
		local
			i: INTEGER
		do
			from
				i := from_channel_number
			until
				i > to_channel_number
			loop
				channels.delete (i)
				i := i + 1
			end
			i := mix_group_channels_external (from_channel_number - 1, to_channel_number - 1, -1)
			if i = 0 then
				error_handler.raise_error (error_handler.Em_error_grouping_channels, [from_channel_number, to_channel_number])
			end
		end

	wipe_out is
			-- Remove all channels from group.
		local
			i: INTEGER
		do
			from
				i := channels.count
			until
				i < 1
			loop
				remove_channel (create {EM_CHANNEL}.make (0, channels.item (i)))
				i := i - 1
			end
		end

feature -- stopping

	fade_out (a_duration: INTEGER) is
			-- Fade out a group in `a_duration' milliseconds.
			--
			-- Attention: This function is non-blocking.
			--			Please check if the channels are fading before
			--			you quit your application.
		require
			duration_valid: a_duration >= 0
		local
			i: INTEGER
		do
			i := mix_fade_out_group_external (internal_number, a_duration)
		end

	stop is
			-- Stop playing whole group.
		local
			i: INTEGER
		do
			i := mix_halt_group_external (internal_number)
		end

feature {NONE} -- Internal variables

	internal_number: INTEGER
			-- Stores channel number

invariant
	channels_created: channels /= Void
	count_valid: count = channels.count

end