// Copyright (c) 2008-2010 Raynaldo (Wildicv) Rivera, Joshua (Dark_Kilauea) Jones
// This file is part of the "cAudio Engine"
// For conditions of distribution and use, see copyright notice in cAudio.h

#ifndef IAUDIOSOURCE_H
#define IAUDIOSOURCE_H

#include "cAudioDefines.h"
#include "IRefCounted.h"
#include "IAudioDecoder.h"
#include "cVector3.h"
#include "IEffect.h"
#include "IFilter.h"
#include "ISourceEventHandler.h"

namespace cAudio
{
	//! Interface for a single audio source, which allow you to manipulate sound sources (speakers) in 2D or 3D space.
    class IAudioSource : public IRefCounted
    {
    public:
		IAudioSource() {}
		virtual ~IAudioSource() {}

		//! Plays the source with the last set parameters.
		/**
		\return True if the source is playing, false if not. */
		virtual bool play() = 0;

		//! Plays the source in 2D mode.
		/** No automatic attenuation or panning will take place in this mode, but using setPosition will allow you to manually pan mono audio streams.
		\param toLoop: Whether to loop (restart) the audio when the end is reached.
		\return True if the source is playing, false if not. */
		virtual bool play2d(const bool& toLoop = false) = 0;

		//! Plays the source in 3D mode.
		/**
		\param position: Position to start the sound off at.
		\param soundstr: Affects how the source attenuates due to distance.  Higher values cause the source to stand out more over distance.
		\param toLoop: Whether to loop (restart) the audio when the end is reached.
		\return True if the source is playing, false if not. */
		virtual bool play3d(const cVector3& position, const float& soundstr = 1.0 , const bool& toLoop = false) = 0;
		
		//! Pauses playback of the sound source.
		virtual void pause() = 0;

		//! Stops playback of the sound source.    
		virtual void stop() = 0;

		//! Controls whether the source should loop or not.
		/** \param toLoop: Whether to loop (restart) the audio when the end is reached. */
		virtual void loop(const bool& toLoop) = 0;

		//! Seeks through the audio stream to a specific spot.
		/** Note: May not be supported by all codecs.
		\param seconds: Number of seconds to seek.
		\param relative: Whether to seek from the current position or the start of the stream.
		\return True on success, False if the codec does not support seeking. */
		virtual bool seek(const float& seconds, bool relative = false) = 0;

		//! Returns the total amount of time in the audio stream.  See IAudioDecoder for details.
		virtual float getTotalAudioTime() = 0;

		//! Returns the total decoded size of the audio stream.  See IAudioDecoder for details.
		virtual int getTotalAudioSize() = 0;

		//! Returns the original size of the audio stream.  See IAudioDecoder for details.
		virtual int getCompressedAudioSize() = 0;

		//! Returns the current position in the audio stream in seconds.  See IAudioDecoder for details.
		virtual float getCurrentAudioTime() = 0;

		//! Returns the current position in the decoded audio stream in bytes.  See IAudioDecoder for details.
		virtual int getCurrentAudioPosition() = 0;

		//! Returns the current position in the original audio stream in bytes.  See IAudioDecoder for details.
		virtual int getCurrentCompressedAudioPosition() = 0;

		//! Normally called every frame by the audio manager to update the internal buffers.  Note: For internal use only.
		virtual bool update() = 0;

		//! Releases all resources used by the audio source, normally used to clean up before deletion.  Note: For internal use only.
		virtual void release() = 0;

		//! Returns if the source is ready to be used.
		virtual const bool isValid() const = 0;

		//! Returns if the source is playing.
		virtual const bool isPlaying() const = 0;

		//! Returns if the source is paused.
		virtual const bool isPaused() const = 0;

		//! Returns if the source is stopped.
		virtual const bool isStopped() const = 0;

		//! Returns if the source is looping.
		virtual const bool isLooping() const = 0;

		//! Sets the position of the source in 3D space.
		/**
		\param position: A 3D vector giving the new location to put this source. */
		virtual void setPosition(const cVector3& position) = 0;

		//! Sets the current velocity of the source for doppler effects.
		/**
		\param velocity: A 3D vector giving the speed and direction that the source is moving. */
		virtual void setVelocity(const cVector3& velocity) = 0;

		//! Sets the direction the source is facing.
		/**
		\param direction: A 3D vector giving the direction that the source is aiming. */
		virtual void setDirection(const cVector3& direction) = 0;

		//! Sets the factor used in attenuating the source over distance.
		/** Larger values make it attenuate faster, smaller values make the source carry better.
		Range: 0.0f to +inf (Default: 1.0f).
		\param rolloff: The rolloff factor to apply to the attenuation calculation. */
		virtual void setRolloffFactor(const float& rolloff) = 0;

		//! Sets how well the source carries over distance.
		/** Same as setRolloffFactor(1.0f/soundstrength).
		Range: 0.0f to +inf (Default: 1.0f).
		\param soundstrength: How well the sound carries over distance. */
		virtual void setStrength(const float& soundstrength) = 0;

		//! Sets the distance from the source where attenuation will begin.
		/** Range: 0.0f to +inf
		\param minDistance: Distance from the source where attenuation begins. */
		virtual void setMinDistance(const float& minDistance) = 0;

		//! Sets the distance from the source where attenuation will stop.
		/** Range: 0.0f to +inf
		\param maxDistance: Distance where attenuation will cease.  Normally the farthest range you can hear the source. */
		virtual void setMaxDistance(const float& maxDistance) = 0;

		//! Sets the pitch of the source.
		/** Range: 0.0f to +inf (Default: 1.0f)
		\param pitch: New pitch level.  Note that higher values will speed up the playback of the sound. */
		virtual void setPitch(const float& pitch) = 0;

		//! Sets the source volume before attenuation and other effects.
		/** Range: 0.0f to +inf (Default: 1.0f).
		\param volume: New volume of the source. */
		virtual void setVolume(const float& volume) = 0;

		//! Sets the minimum volume that the source can be attenuated to.
		/** Range: 0.0f to +inf (Default: 0.0f).
		\param minVolume: New minimum volume of the source. */
		virtual void setMinVolume(const float& minVolume) = 0;

		//! Sets the maximum volume that the source can achieve.
		/** Range: 0.0f to +inf (Default: 1.0f).
		\param maxVolume: New maximum volume of the source. */
		virtual void setMaxVolume(const float& maxVolume) = 0;

		//! Sets the angle of the inner sound cone of the source.  The cone opens up in the direction of the source as set by setDirection(). 
		/** Note: This causes the sound to be loudest only if the listener is inside this cone.
		Range: 0.0f to 360.0f (Default: 360.0f).
		\param innerAngle: Inside angle of the cone. */
		virtual void setInnerConeAngle(const float& innerAngle) = 0;

		//! Sets the angle of the outer sound cone of the source. The cone opens up in the direction of the source as set by setDirection(). 
		/** Note: If the listener is outside of this cone, the sound cannot be heard.  Between the inner cone angle and this angle, the sound volume will fall off.
		Range: 0.0f to 360.0f (Default: 360.0f).
		\param outerAngle: Outside angle of the cone. */
		virtual void setOuterConeAngle(const float& outerAngle) = 0;

		//! Sets how much the volume of the source is scaled in the outer cone.
		/** Range: 0.0f to +inf (Default: 0.0f).
		\param outerVolume: Volume of the source in the outside cone. */
		virtual void setOuterConeVolume(const float& outerVolume) = 0;

		//! Sets the doppler strength, which enhances or diminishes the doppler effect.  Can be used to exaggerate the doppler for a special effect.
		/** Range: 0.0f to +inf (Default: 1.0f).
		\param dstrength: New strength for the doppler effect. */
		virtual void setDopplerStrength(const float& dstrength) = 0; 

		//! Overrides the doppler velocity vector.  It is usually better to let the engine take care of it automatically.
		/** Note: must be set every time you set the position, velocity, or direction.
		\param dvelocity: New doppler vector for the source. */
		virtual void setDopplerVelocity(const cVector3& dvelocity) = 0;

		//! Convenience function to automatically set the velocity and position for you in a single call.
		/** Velocity will be set to new position - last position.
		\param position: Position to move the source to. */
		virtual void move(const cVector3& position) = 0;

		//! Returns the audio objects position
		virtual const cVector3 getPosition() const = 0;

		//! Returns the audio objects velocity
		virtual const cVector3 getVelocity() const = 0;

		//! Returns the audio objects direction
		virtual const cVector3 getDirection() const = 0;

		//! Returns the factor used in attenuating the source over distance
		virtual const float getRolloffFactor() const = 0;

		//! Returns the strength of the source
		virtual const float getStrength() const = 0;

		//! Returns the distance from the source where attenuation will begin
		virtual const float getMinDistance() const = 0;

		//! Returns the distance from the source where attenuation will stop
		virtual const float getMaxDistance() const = 0;

		//! Returns the pitch of the source
		virtual const float getPitch() const = 0;

		//! Returns the source volume before attenuation and other effects
		virtual const float getVolume() const = 0;

		//! Returns the minimum volume that the source can be attenuated to
		virtual const float getMinVolume() const = 0;

		//! Returns the maximum volume that the source can achieve
		virtual const float getMaxVolume() const = 0;

		//! Returns the angle of the inner sound cone of the source
		virtual const float getInnerConeAngle() const = 0;

		//! Returns the angle of the outer sound cone of the source
		virtual const float getOuterConeAngle() const = 0;

		//! Returns how much the volume of the source is scaled in the outer cone
		virtual const float getOuterConeVolume() const = 0;

		//! Returns the doppler strength, which enhances or diminishes the doppler effect 
		virtual const float getDopplerStrength() const = 0;

		//! Returns the override for the doppler velocity vector
		virtual const cVector3 getDopplerVelocity() const = 0;

		//! Registers a new event handler to this source
		/**
		\param handler: Pointer to the event handler to register. */
		virtual void registerEventHandler(ISourceEventHandler* handler) = 0;

		//! Removes a specified event handler from this source
		/**
		\param handler: Pointer to the event handler to remove. */
		virtual void unRegisterEventHandler(ISourceEventHandler* handler) = 0;

		//! Removes all event handlers attached to this source
		virtual void unRegisterAllEventHandlers() = 0;

#ifdef CAUDIO_EFX_ENABLED
		//! Returns the number of effects at one time this source can support.
		virtual unsigned int getNumEffectSlotsAvailable() const = 0;

		//! Attaches an EFX audio effect to this sound source to a specific slot.
		/** 
		\param slot: Slot to attach this effect to. Range: 0 to getNumEffectSlotsAvailable().
		\param effect: Pointer to an effect object to attach. 
		\return Whether the effect was successfully attached. */
		virtual bool attachEffect(unsigned int slot, IEffect* effect) = 0;

		//! Removes an EFX audio effect from this sound source.
		/** 
		\param slot: Slot of the effect to remove. Range: 0 to getNumEffectSlotsAvailable().*/
		virtual void removeEffect(unsigned int slot) = 0;

		//! Attaches an audio filter to this sound source that will operate on the direct feed, separate from any effects.
		/**
		\param filter: Pointer to the filter to attach.  Any previous filter will be dropped. 
		\return Whether the filter was successfully attached. */
		virtual bool attachFilter(IFilter* filter) = 0;

		//! Removes a previously attached filter.
		virtual void removeFilter() = 0;
#endif

    protected:
    private:
    };
};
#endif //! IAUDIO_H
