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

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

		Author:	Jeremy
		Date:	6/15/2004

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

#ifndef __IExSound__
#define __IExSound__

#if CP_PRAGMA_ONCE
#pragma once
#endif


template <class T> class TMCArray;
struct IMCFile;
class TMCDynamicString;

//****** Globally Unique Ids **************************************************
MCDEFINE_GUID2(IID_IExSound, R_IID_IExSound);


/*****************************************************************************\
*                                                                             *
*  I3DExSound                                                                 *
*                                                                             *
*    Interface to Sound objects                                               *
*                                                                             *
\*****************************************************************************/

struct IExSound : public IMCUnknown
{
	
	// ****************************************************************************
	//								
	// 
	// -Description: Sets up the Sound file handler for a specific file.
	//
	// -Parameters:
	//			file	:	Input file
	//			scene	:	pointer to the scene
	//
	// -Returns: true if the file was valid and the Prepare successful, otherwise false
	//
	virtual boolean		 Prepare(IMCFile * file ) = 0;

	// ****************************************************************************
	//								
	// 
	// -Description: Accessor for duration of a Sound
	//
	// -Returns: The duration of a sound in milliseconds
	//
	virtual uint32 GetDuration() const =0;

	// ****************************************************************************
	//								
	// 
	// -Description: Accessor for Sound bit depth
	//
	// -Returns: The sample bit depth of the Sound
	//
	virtual uint32	GetBitDepth() const =0;

	// ****************************************************************************
	//								
	// 
	// -Description: Accessor for Sound number of channels
	//
	// -Returns: Number of channels in the Sound (1 for mono, 2 for stereo, >2 for surround)
	//
	virtual uint32	GetChannelCount() const =0;

	// ****************************************************************************
	//								
	// 
	// -Description: Accessor for sampling rate of a Sound
	//
	// -Returns: The sampling rate in Hz
	//
	virtual uint32	GetSamplingRate() const =0;

	// ****************************************************************************
	//								
	// 
	// -Description: Accessor for sample format of a Sound
	//
	// -Returns:	kTwosComplement for twos-complement format
	//				kOffsetBinary	for offset-binary format
	//
	virtual uint32	GetSampleFormat() const =0;

	// ****************************************************************************
	//								
	// 
	// -Description: Fills an array with values (0..1) corresponding to the Sounds waveform.
	//				 Used for drawing the Sound.  outArray should already be sized
	//				 to the desired number of elements, and GetPreviewData will fill
	//				 it appropriately 
	//
	// -Parameters:  outArray, a TMCArray to fill with values.
	//
	// -Returns:	 nothing
	//
	virtual void	GetPreviewData(TMCArray<real32>* outArray) =0; 

	// ****************************************************************************
	//								
	// 
	// -Description: Accessor for total number of samples in the Sound
	//
	// -Returns:	 The number of samples in the sound
	//
	virtual uint32	 GetSampleCount() const =0;

	// ****************************************************************************
	//								
	// 
	// -Description: Accessor for total data size of the Sound's PCM data
	//
	// -Returns:	 The number of bytes of Sound data
	//
	virtual uint32	 GetDataSize() const =0;

	// ****************************************************************************
	//								
	// 
	// -Description: Accessor for full path name name of the Sound
	//
	// -Parameter:
	//			outName : A TMCString to contain the filename
	//
	virtual void	 GetFullPathName(TMCString& outName) =0;

	// ****************************************************************************
	//								
	// 
	// -Description: Accessor for the offset within the file where the data are stored
	//
	// -Returns:	 The offset
	//
	virtual uint32	GetDataOffset() const =0;

	// ****************************************************************************
	//								
	// 
	// -Description: Accessor for the sound type ID of the sound (eg. 'wave' for .wav files)
	//
	// -Returns: The sound type identifier for this sound instance
	//
	virtual uint32  GetSoundType() const =0;

	// ****************************************************************************
	//								GetSamples
	// 
	/// Reads numBytes of samples into outData.  To maintain alignment, some IExSounds
	/// will only read increments of 4 bytes (ie 1 stereo 16 bit sample).
	/// 
	/// \param outData   pointer into which we're reading the samples
	/// \param offset	 offset in the file's audio data from which to start the read
	/// \param numBytes  number of bytes of sample to read
	/// \return number of bytes actually read.
	virtual MCSize	GetSamples(int8* outData, int32 offset, MCSize numBytes) =0;
	// ****************************************************************************
	//								GetResampledData
	// 
	/// Read and resample the date to desired format.  To maintain alignment, some IExSounds
	/// will only read increments of 4 bytes (ie 1 stereo 16 bit sample).
	/// 
	/// \param outData   pointer into which we're re-sampling
	/// \param[in] offsetInOriginalData	 offset in the file's audio data from which to start the resample
	/// \param[in] channelCount the desired number of channels
	/// \param[in] bitDepth	 the desired bit depth
	/// \param[in] samplingRate the desired sampling rate
	/// \param[in] duration sample data duration in milliseconds
	virtual void   GetResampledData(TMCArray<int8>& outData, int32 offsetInOriginalData, 
									uint32 channelCount, uint32 bitDepth, uint32 samplingRate, uint32 duration) = 0;
};



#endif
