/****************************************************************************************************

		I3DShSoundtrack.h
		Copyright: (c) 2004 Eovia Corp. All rights reserved.

		Author:	Jeremy
		Date:	6/23/2004

****************************************************************************************************/

#ifndef __I3DShSoundtrack__
#define __I3DShSoundtrack__

#if CP_PRAGMA_ONCE
#pragma once
#endif

#include "ComTypes.h"
#include "APITypes.h"

struct IShSound;
struct I3DShScene;

//****** Globally Unique Ids **************************************************

MCDEFINE_GUID(IID_I3DShSoundtrack,      0x33f45fc7, 0x539b, 0x4fb5, 0xb2, 0x86, 0x64, 0xd4, 0xce, 0x17, 0xa4, 0x40);


/*****************************************************************************\
*                                                                             *
*  I3DShSoundtrack                                                            *
*                                                                             *
*    Interface to the scene Soundtrack object                                 *
*                                                                             *
\*****************************************************************************/


struct I3DShSoundtrack : public IMCUnknown
{
	// ****************************************************************************
	//								
	// 
	// -Description: Creates a new Sound channel in the Soundtrack
	//
	// -Parameters:	 None
	//
	// -Returns:	 The index of the channel just created
	virtual uint32		MCCOMAPI	AddChannel		() =0;

	// ****************************************************************************
	//								
	// 
	// -Description: Creates a new Sound channel in the Soundtrack, moves Sounds "down" to fit
	//
	// -Parameters:
	//		channel	: index of the channel to be inserted
	//
	// -Returns:	 The index of the channel just created
	virtual uint32		MCCOMAPI	AddChannel		(uint32 channel) =0;

	// ****************************************************************************
	//								
	// 
	// -Description: Removes a specified channel from the Soundtrack
	//
	// -Parameters:
	//			channel	:	Channel to be removed
	//
	// -Returns: Nothing
	//
	virtual void		MCCOMAPI	RemoveChannel	(uint32 channel) =0;

	// ****************************************************************************
	//								
	// 
	// -Description: Inserts the sound passed at the given time
	//
	// -Parameters:
	//			inSound		 : The sound object to be added to the Soundtrack
	//			insertTime	 : The time (in MicroTicks) at which to insert the sound
	//			insertChannel: The channel into which to add the sound
	// -Returns:
	//			The index at which the sound has been inserted, or -1 if it was 
	//			passed a NULL inSound
	//
	virtual int32		MCCOMAPI	AddSound		(IShSound* inSound, MicroTick insertTime, uint32 insertChannel) =0;

	// ****************************************************************************
	//								
	// 
	// -Description: Removes the sound passed at the given time
	//
	// -Parameters:
	//			inSound		 : The sound object to be removed from the Soundtrack
	//			insertTime	 : The time (in MicroTicks) from which to remove the sound
	//			insertChannel: The channel from which to remove the sound
	// -Returns:
	//			The index at which the sound has been removed, or -1 if it was 
	//			passed a NULL inSound
	//
	virtual int32		MCCOMAPI	RemoveSound		(IShSound* inSound) =0;


	// ****************************************************************************
	//								
	// 
	// -Description: Moves a sound to a new time/channel
	//
	// -Parameters:
	//			index		: Sound index corresponding to the sound to be moved
	//			newTime		: New time at which to insert the sound
	//			newChannel	: New channel into which to insert the sound
	//
	// -Returns: Nothing.
	//
	virtual void		MCCOMAPI	MoveSound		(uint32 index, MicroTick newTime, uint32 newChannel) =0;

	// ****************************************************************************
	//								
	// 
	// -Description: Moves a sound to a new time/channel
	//
	// -Parameters:
	//			ID			: Selection ID index corresponding to the sound to be moved
	//			newTime		: New time at which to insert the sound
	//			newChannel	: New channel into which to insert the sound
	//
	// -Returns: Nothing.
	//
	virtual void		MCCOMAPI	MoveSoundByID	(uint32 ID, MicroTick newTime, uint32 newChannel) =0;

	// ****************************************************************************
	//								
	// 
	// -Description: Moves a sound to a new time/channel
	//
	// -Parameters:
	//			ID			: Selection ID index corresponding to the sound to be moved
	//			deltaT		: time delta to apply to sound
	//
	// -Returns: Nothing.
	//
	virtual void		MCCOMAPI	MoveSoundByID	(uint32 ID, MicroTick deltaT) =0;


	// ****************************************************************************
	//								
	// 
	// -Description: Shifts sound to a new time by a delta
	//
	// -Parameters:
	//			index		: Sound index corresponding to the sound to be moved
	//			deltaT		: time delta to apply to sound
	//
	// -Returns: Nothing.
	//
	virtual void		MCCOMAPI	MoveSound		(uint32 index, MicroTick deltaT) =0;

	// ****************************************************************************
	//								
	// 
	// -Description: Returns an IShSound* referenced by internal index
	//
	// -Parameters:
	//			index		: Index of Sound to be returned
	//
	// -Returns: An I3DShSound*, or NULL if the index is out of range
	//
	virtual IShSound*	MCCOMAPI	GetSoundByIndex	(int32 index) =0;
	
	// ****************************************************************************
	//								
	// 
	// -Description: Returns an IShSound* referenced by selection ID
	//
	// -Parameters:
	//			ID			: ID of Sound to be returned
	//
	// -Returns: An I3DShSound*, or NULL if the ID is not found
	//
	virtual IShSound*	MCCOMAPI	GetSoundByID	(uint32 ID) =0;

	// ****************************************************************************
	//								
	// 
	// -Description: Returns the time at which the sound starts in the Soundtrack
	//
	// -Parameters:
	//			index : Index of Sound to be returned
	//
	// -Returns: A MicroTick time reference
	//
	virtual MicroTick	MCCOMAPI	GetSoundStartByIndex (int32 index) =0;

	// ****************************************************************************
	//								
	// 
	// -Description: Returns the time at which the sound starts in the Soundtrack
	//
	// -Parameters:
	//			ID : Selection ID of Sound to be returned
	//
	// -Returns: A MicroTick time reference
	//
	virtual MicroTick	MCCOMAPI	GetSoundStartByID (uint32 ID) =0;

	// ****************************************************************************
	//								
	// 
	// -Description: Returns an IShSound* referenced by Time and Channel
	//
	// -Parameters:
	//			time	: Time at which to look for the Sound
	//			channel	: Channel in which to look for the Sound
	//
	// -Returns: An IShSound*, or NULL if there is no sound at the specified time/channel
	//
	virtual IShSound* MCCOMAPI	GetSoundByTime  (MicroTick time, uint32 channel) =0;

	// ****************************************************************************
	//								
	// 
	// -Description: Returns the total number of sounds in the Soundtrack
	//
	// -Parameters:	None.
	//
	// -Returns: The number of sounds in the Soundtrack
	//
	virtual uint32		MCCOMAPI	GetSoundCount	() =0;

	// ****************************************************************************
	//								
	// 
	// -Description: Returns the total number of channels in the Soundtrack
	//
	// -Parameters: None.
	//
	// -Returns: The number of channels in the Soundtrack
	//
	virtual uint32		MCCOMAPI	GetChannelCount	() const =0;

	// ****************************************************************************
	//								
	// 
	// -Description: Returns the channel of the sound indexed by the parameter
	//
	// -Parameters:
	//			index : Index of sound whose channel we want
	//
	// -Returns: The channel number
	//
	virtual uint32		MCCOMAPI	GetChannelBySoundIndex (int32 index) =0;

	// ****************************************************************************
	//								
	// 
	// -Description: Returns the channel of the sound indexed by the parameter
	//
	// -Parameters:
	//			ID : Selection ID of sound whose channel we want
	//
	// -Returns: The channel number
	//
	virtual uint32		MCCOMAPI	GetChannelByID (uint32 ID) =0;

	// ****************************************************************************
	//								
	// 
	// -Description: Tests to see if a given sound, if moved to a given start time and channel,
	//				 overlaps a sound already there.
	//
	// -Parameters:
	//			ID			:	Selection ID of the sound being tested
	//			channel		:	Hypothetical destination channel
	//			startTime	:	Hypothetical starting time for the sound
	//
	// -Returns:
	//			true	if the sound would overlap another sound at the tested time/channel
	//			false	if the sound would not overlap another
	//
	virtual boolean		MCCOMAPI	IntersectsOtherSound( uint32 ID, uint32 channel, MicroTick startTime ) =0;


	// ****************************************************************************
	//								
	// 
	// -Description: Tells the Soundtrack to begin playback of the sounds
	//
	// -Parameters:
	//			inTime	:	Time at which to start playing
	//			rate	:	Playback rate (1.0 for normal speed, forwards playback)
	//
	virtual void		MCCOMAPI	BeginPlayback(MicroTick inTime, real32 rate) = 0;

	// ****************************************************************************
	//								
	// 
	// -Description: Tells the Soundtrack to stop playback of the sounds
	//
	//
	virtual void		MCCOMAPI	EndPlayback() = 0;

	// ****************************************************************************
	//								
	// 
	// -Description: Tells the Soundtrack to adjust the sound playback time and rate
	//
	// -Parameters:
	//			inTime	:	Time at which to play
	//			rate	:	Playback rate (1.0 for normal speed, forwards playback)
	//
	virtual void		MCCOMAPI	AdjustPlayback(MicroTick inTime, real32 rate) = 0;

	// ****************************************************************************
	//								GetSoundCursorByIndex
	// 
	/// Gets the time of the sound's playback cursor.
	/// 
	/// \param index  Index of the sound whose playback cursor we want.
	/// 
	virtual MicroTick	MCCOMAPI	GetSoundCursorByIndex(int32 index) = 0;

	// ****************************************************************************
	//								SetSoundCursorByIndex
	// 
	/// Sets the time of the indexed sound's playback cursor
	/// 
	/// \param index     Index of the sound whose playback cursor we want to set
	/// \param inCursor  Time to set the cursor
	/// 
	virtual void		MCCOMAPI	SetSoundCursorByIndex(int32 index, MicroTick inCursor) = 0;

	// ****************************************************************************
	//								
	// 
	// -Description: Returns the duration of the sound in the Soundtrack
	//
	// -Parameters:
	//			index : index of Sound to be returned
	//
	// -Returns: A MicroTick time reference
	//
	virtual MicroTick	MCCOMAPI	GetSoundDurationByIndex (int32 index) =0;

	virtual void		MCCOMAPI	PlaySounds() = 0;
	virtual void		MCCOMAPI	StopSounds() = 0;

    // ****************************************************************************
	//								SetChannelStared
	// 
	/// Sets a sound channel as either stared or not stared
	/// 
	/// \param channel   The ID of the channel to be modified
	/// \param isStared  should the specified channel be stared
	/// 
    virtual void       MCCOMAPI     SetChannelStared(uint32 channel, boolean isStared) = 0;
    virtual uint32     MCCOMAPI     GetStaredChannelsCount() const = 0;
    virtual boolean    MCCOMAPI     IsChannelStared(uint32 channel) const = 0;
    // ****************************************************************************
	//								GetStaredChannelIDAtIndex
    //
    /// Get the stared channel ID at specific index (the i th stared channel)
    /// \param index The index of the stared channel
    /// \return the stared channel ID at specific index (the i th stared channel) or -1 if such a channel does not exist
    virtual int32      MCCOMAPI     GetStaredChannelIDAtIndex(uint32 index) const = 0;
    // Text associeted with sound support
    virtual boolean    MCCOMAPI     GetHasSoundWithText() const = 0;
    virtual boolean    MCCOMAPI     GetHasStaredSoundWithText() const = 0;

	virtual void		MCCOMAPI	SetScene(I3DShScene* scene) =0;


    // ****************************************************************************
	//								GetSoundIndexByTime
    //
    /// Returns the index of the sound in a given time for a given channel
	///
    /// \param time		Time at which to look for the Sound
    /// \param channel	The index of the stared channel
    ///
    /// \return The index of the sound if there is one, -1 if not
	///
	virtual int32 MCCOMAPI	GetSoundIndexByTime(MicroTick time,int32 channel) =0;

	virtual void		MCCOMAPI	SetChannelMuted(uint32 channelID, boolean isMuted) =0;
	virtual boolean    MCCOMAPI		IsChannelMuted(uint32 channelID) const =0;

    virtual const TMCArray<uint32>& MCCOMAPI GetMutedChannelList() const = 0;
    virtual void MCCOMAPI	SetMutedChannelList(const TMCArray<uint32>& newList) = 0;

	virtual boolean		MCCOMAPI	GetLoop() =0;
	virtual void		MCCOMAPI	SetLoop(boolean isLoop) =0;
	virtual void		MCCOMAPI	Reset() =0;

};




#endif
