indexing

	description: "[

		Implements a music file.
		
		This file can be either WAVE, MOD, MIDI, OGG or MP3.
		
		Note: You need to have special compiled version of SDL_mixer
		to be able to play MP3-files. Please check documentation
		for further details.

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

class EM_MUSIC

inherit

	EM_SHARED_ERROR_HANDLER
		export {NONE} all end

	EM_AUDIO

	EM_AUDIO_CONSTANTS
		export
			{NONE} all
			{ANY} Em_max_volume
		end

	SDL_MIXER_FUNCTIONS_EXTERNAL
		export {NONE} all end

create

	{EM_AUDIO_FACTORY} make_from_pointer

feature -- Playing

	play (a_loop_count: INTEGER) is
			-- Play music with `a_loop_count' loops.
			--
			-- Special values for `a_loop_count' are:
			--	-1: Plays forever
			--	0: Plays this music zero times
		local
			i: INTEGER
		do
			i := mix_play_music_external (item, a_loop_count)
			if i = -1 then
				error_handler.raise_error (error_handler.Em_error_playing_music, [a_loop_count])
			end
		ensure
			playing: is_playing
		end

	fade_in (a_loop_count: INTEGER; a_duration: INTEGER) is
			-- Play music with `a_loop_count' loops and a fade in of `a_duration' millseconds.
			--
			-- Special values for `a_loop_count' are:
			--	-1: Plays forever
			--	0: Plays this music zero times
			--
			-- Attention: This function is non-blocking.
			--			Please check if music is fading before
			--			you quit your application.
		local
			i: INTEGER
		do
			i := mix_fade_in_music_external (item, a_loop_count, a_duration)
			if i = -1 then
				error_handler.raise_error (error_handler.Em_error_fading_music_in, [a_loop_count, a_duration])
			end
		ensure
			playing: is_playing
		end

	fade_in_positioned (a_loop_count: INTEGER; a_duration: INTEGER; a_position: DOUBLE) is
			-- Play music with `a_loop_count' loops and a fade in of `a_duration' millseconds
			-- from `a_position' in track.
			--
			-- Special values for `a_loop_count' are:
			--	-1: Plays forever
			--	0: Plays this music zero times
			--
			-- Note: Please check documentation for explanation of track position
			--		 for different file formats.
			--
			-- Attention: This function is non-blocking.
			--			Please check if music is fading before
			--			you quit your application.
		local
			i: INTEGER
		do
			i := mix_fade_in_music_pos_external (item, a_loop_count, a_duration, a_position)
			if i = -1 then
				error_handler.raise_error (error_handler.Em_error_fading_music_in_positioned, [a_loop_count, a_duration, a_position])
			end
		ensure
			playing: is_playing
		end

feature -- Pausing

	pause is
			-- Pause music.
		require
			playing: is_playing
		do
			mix_pause_music_external
		ensure
			paused: is_paused
		end

	resume is
			-- Resume music playback.
		do
			mix_resume_music_external
		ensure
			playing: is_playing
		end

feature -- Stopping

	stop is
			-- Stop playing music.
			--
			-- Any callback set by mix_hook_music_finished won't be called
			-- when music stops by user interaction.
		local
			i: INTEGER
		do
			i := mix_halt_music_external
		ensure
			not_playing: not is_playing
		end

	fade_out (a_duration: INTEGER) is
			-- Stop playing music with a fade out of `a_duration' millseconds.
			--
			-- Any callback set by mix_hook_music_finished won't be called
			-- when music stops by user interaction.
			--
			-- Attention: This function is non-blocking.
			--			Please check if music is fading before
			--			you quit your application.
		require
			playing: is_playing
		local
			i: INTEGER
		do
			i := mix_fade_out_music_external (a_duration)
			if i = 0 then
				error_handler.raise_error (error_handler.Em_error_fading_music_out, [a_duration])
			end
		end

feature -- Manipulation

	rewind is
			-- Rewinds this music to start.
			--
			-- Note: This function only works for these formats
			--		MOD, OGG, MP3, Native MIDI
		do
			mix_rewind_music_external
		end

	set_position (a_position: DOUBLE) is
			-- Set track position to `a_position'
			--
			-- Note: This function only works for these formats
			--		MOD, OGG, MP3
			--
			--		 Please check documentation for explanation of track position
			--		 for different file formats.
		require
			position_positiv: a_position >= 0
		local
			i: INTEGER
		do
			i := mix_set_music_position_external (a_position)
			if i = -1 then
				error_handler.raise_error (error_handler.Em_error_setting_music_position, [a_position])
			end
		end

	set_volume (a_volume: INTEGER) is
			-- Set volume to `a_volume'.
			-- `a_volume' is in range of [0..Em_max_volume].
			--
			-- If track is fading or you're using an external player,
			-- set_volume has no effect.
		require
			a_volume_in_range: a_volume >= 0 and then a_volume <= Em_max_volume
		local
			i: INTEGER
		do
			i := mix_volume_music_external (a_volume)
		ensure
			volume_set: (volume = a_volume) or else (a_volume > Em_max_volume implies volume = Em_max_volume)
		end

feature -- Informations

	volume: INTEGER is
			-- Volume in range [0..Em_max_volume]
		do
			Result := mix_volume_music_external (-1)
		end

	music_type: INTEGER is
			-- Type of music
			--
			-- 	`Em_music_none':	No music
			-- 	`Em_music_command':	Music using external command
			-- 	`Em_music_wave':	WAVE/RIFF music
			-- 	`Em_music_mod':		MOD music
			-- 	`Em_music_midi':	MIDI music
			-- 	`Em_music_ogg':		OGG music
			-- 	`Em_music_mp3':		MP3 music
			--
			-- Note: These constants have been defined in {EM_AUDIO_CONSTANTS}
		do
			Result := mix_get_music_type_external (item)
		end

	is_playing: BOOLEAN is
			-- Is track playing?
		do
			Result := (1 = mix_playing_music_external)
		end

	is_paused: BOOLEAN is
			-- Is track paused?
		do
			Result := (1 = mix_paused_music_external)
		end

	is_fading: BOOLEAN is
			-- Is track fading in or out?
		do
			Result := is_fading_in or else is_fading_out
		end

	is_fading_in: BOOLEAN is
			-- Is track fading in?
		do
			Result := (Em_fading_in = mix_fading_music_external)
		end

	is_fading_out: BOOLEAN is
			-- Is track fading out?
		do
			Result := (Em_fading_out = mix_fading_music_external)
		end

end