/*! *	This library is dependant on libfmod, liblua, liblualib & libLuaBinder.  *	If you do not want lua function bindings within your code, add the option  *	-DNO_LUA in the COMPILER options for the library makefile. This will remove  *	the dependancies with the lua scripting language. * *	I made lots of changes to the way in which this works on Sunday 18-1-04.  *	Basically made the code deterministic (ie, I can now predict when the sound *	will finish as apposed to being told at an unknown time).  * *	I've also added some 3D sound functions to the end of the code which is nice. * *	(c) Rob Bateman	2004 */#ifndef __SOUND_PLAYBACK__H__#define __SOUND_PLAYBACK__H__#ifdef __cplusplusextern "C" {#endif	/*--------------------------------------------------------------------------------*	 *	 *	 *					---===###	SIMPLE(ish) SOUND FX		###===---	 *	 *	 *	Sound FX gets a little bit more complex than the simple mp3 playback routines.	 *	I've tried to keep it as simple as possible but due to the nature of sound a bit	 *	of explaination may come in handy:	 *	 *	1. You must use the SoundLoad function to load the sound effects that you will	 *	   be using in your game. You can load as many sounds up as you wish, but bear	 *	   in mind that more sounds = more memory usage. Each sound loaded will return	 *	   a unique integer ID (SoundInstance typedef below).	 *	 *	2. At any one time, the engine is set up to allow playback of up to 64 sounds.	 *	   (one of these will be the mp3 stream). When a sound is requested to begin	 *	   playback, it will be set to play in a spare channel.... This is to allow for	 *	   the same sound to played a number of times simultaneously...	 *	 *	3. The SoundPlay() function takes a SoundInstance ID and returns the channel id	 *	   of where this has been set to play. This is only really of use if you want to	 *	   set the volume etc of the sound, or if you have set the sound to be looping	 *	   in which case you'll probably want to store this number so you can stop it	 *	   again (alternatively you can call SoundStopAll() to stop all sounds from	 *	   playing back).	 *	 *	4. If you have finished with a sound you can un-load them with the SoundDelete()	 *	   or SoundDeleteAll functions.	 *	 *	One thing I have not really taken account for is what happens when all the	 *	channels are currently playing something back. If that does happen then I ignore	 *	the request (I'll leave that for you to sort out if you face the problem)	 *	\*--------------------------------------------------------------------------------*/	/*!	 *	A typedef for a Loaded Sound File	 */	typedef unsigned short SoundInstance;	/*!	 *	A typedef for a Sound Channel in which the sound has been set to play	 */	typedef int SoundChannel;	/*!	 *	\brief	This function was added for a number of reasons. Primarily if I left	 *			The code using FSOUND_IsPlaying() we would have a problem in that 	 *			the game engine I'm writing would become non deterministic, ie I 	 *			cannot predict when the sound will finish playing. This has a drastic 	 *			knock on effect for anycode using the SoundIsPlaying function. To	 *			avoid this hassle I've altered the code to approximate the length of	 *			The sound when playback starts. This means I have no now update the sound	 *			system so I know when the sounds have actually finished. Bit of a pain, 	 *			but it IS WORTH THE EFFORT!	 *	\param	dt	-	the time since last called.	 */	void SoundUpdate(float dt);	/*!	 *	\brief	This function loads a sound file into memory. Note that there is no point	 *			loading the same sound more than once!	 *	\param	filename	-	the name of the sound to load	 *	\return	a unique ID of the sound	 */	SoundInstance SoundLoad(char filename[]);	/*!	 *	\brief	This function un-loads the specified sound file.	 *	\param	Sound	-	the sound instance to unload	 */	void SoundDelete(SoundInstance Sound);	/*!	 *	\brief	This function deletes all currently loaded sounds.	 */	void SoundDeleteAll();	/*!	 *	\brief	This function plays the sound in the first available free channel.	 *	\param	Sound	-	the sound to play	 *	\return	The channel in which it is playing.	 */	SoundChannel SoundPlay(SoundInstance Sound);	/*!	 *	\brief	This function plays the sound in the first available free channel.	 *	\param	Sound	-	the sound to play	 *	\return	The channel in which it is playing.	 */	SoundChannel SoundPlayLooping(SoundInstance Sound);	/*!	 *	\brief	This function allows you to query whether a specific sound channel is playing	 *	\param	Channel	-	the ID of the sound channel	 *	\return	1 if true, 0 if no sound playing	 */	int SoundIsPlaying(SoundChannel Channel);	/*!	 *	\brief	This function pauses the specified sound channel	 *	\param	Channel	-	the ID of the sound channel	 */	void SoundPause(SoundChannel Channel);	/*!	 *	\brief	This function un-pauses the specified sound channel	 *	\param	Channel	-	the ID of the sound channel	 */	void SoundUnPause(SoundChannel Channel);	/*!	 *	\brief	This function pauses all sounds (useful for pause etc..)	 */	void SoundPauseAll();	/*!	 *	\brief	This function un-pauses all sounds	 */	void SoundUnPauseAll();	/*!	 *	\brief	This function stops playback of the specified channel	 *	\param	Channel	-	the ID of the sound channel	 */	void SoundStop(SoundChannel Channel);	/*!	 *	\brief	This function stops playback of all loaded sounds	 */	void SoundStopAll();	/*!	 *	\brief	This function allows you to set the volume level of a specific sound channel	 *	\param	Channel	-	the ID of the sound channel	 *	\param	Volume	-	the new volume level between 0 and 1	 */	void SoundSetVolume(SoundChannel Channel,float Volume);	/*!	 *	\brief	This function allows you to get the volume level of a specific sound channel	 *	\param	Channel	-	the ID of the sound channel	 *	\return	The volume level from 0 to 1	 */	float SoundGetVolume(SoundChannel Channel);	/*!	 *	\brief	This function allows you to set the panning amount of a specific sound channel	 *	\param	Channel	-	the ID of the sound channel	 *	\param	Pan		-	the panning amount from -1 to 1	 */	void SoundSetPan(SoundChannel Channel,float Pan);	/*!	 *	\brief	This function allows you to get the panning amount of a specific sound channel	 *	\param	Channel	-	the ID of the sound channel	 *	\return	the panning amount from -1 to 1	 */	float SoundGetPan(SoundChannel Channel);	/*!	 *	\brief	This function allows you to set the frequency amount of a specific sound channel	 *	\param	Channel	-	the ID of the sound channel	 *	\aparam	Freq	-	The new frequency - should be in the range 100->705600	 */	void SoundSetFrequency(SoundChannel Channel,int Freq);	/*!	 *	\brief	This function allows you to get the frequency amount of a specific sound channel	 *	\param	Channel	-	the ID of the sound channel	 *	\return The frequency of the channel	 */	int SoundGetFrequency(SoundChannel Channel);	/*	 *###########################################################################################	 *	 *									3D Sound Functions	 *	 *	There are 3 main setting functions for the 3D sound engine, basically specify the doppler,	 *	shift, distance factor and rolloff factor. I very much doubt you will ever need to change	 *	these. 	 *	 *	On a per frame basis you will have to calculate the position of the listener and the 	 *	positions of the sounds. The functions SoundSetListener and SoundSetPosition should 	 *	do this quite nicely for you. 	 *	 *	Once you have updated all of the sounds' positions etc, call SoundUpdate() which will	 *	do all of the 3D processing for you. Ideally then you will need to calculate the changes	 *	In sound speeds and positions in your idle and call SoundUpdate there also. Thats basically 	 *	all you need for 3D sound, Nice. Have fun coding! 	 *	 *###########################################################################################	 */	/*!	 *	\brief	This function sets the number of units per meter. The default is 1. If your	 *			world units were feet, then this value should be 3.48. If each of your world	 *			units were centimeters then this value should be 100. 	 *	\param	The distance factor for the world units	 */	void SoundSetDistanceFactor(float Distance);	/*! 	 *	\brief	This function sets the effect of the doppler shift. To emulate real world,	 *			A value of 1 should do it. A higher value will make this more pronounced. 	 *			fyi - a doppler shift is the change in pitch of a sound when it moves at speed;	 *			for example when a police car speeds past you (just in case you didn't know...)	 *	\param	The doppler shift factor	 */	void SoundSetDopplerFactor(float dopplershift);	/*! 	 *	\brief	Normally a sound's volume will dropoff at the rate of 1/distance. To make this 	 *			drop off faster, increase the factor's value. 	 *	\param	The rolloff factor	 */	void SoundSetRollOffFactor(float dopplershift);	/*!	 *	\brief	This function sets the listener speed, direction & orientation. Basically the 	 *			listener is your ears in the world, normall the same movement as the camera.	 *	\param	pos	-	the world space position of the listener	 *	\param	vel	-	the velocity of the listener, measured in units per second	 *	\param	dir	-	the forward direction of the listener as unit length vector	 *	\param	up	-	a unit length vector descrbing up.	 *	\note	The velocity of the listener can change from the direction simply because you 	 *			may be strafing.	 */	void SoundSetListener(float pos[],float vel[],float dir[],float up[]);	/*!	 *	\brief	This function sets the position and speed of the specified sound.	 *	\param	ch	-	the sound channel to affect	 *	\param	pos	-	the world space position of the listener	 *	\param	vel	-	the velocity of the listener, measured in units per second	 */	void SoundSetPosition(SoundChannel ch,float pos[],float vel[]);	#ifdef __cplusplus}#endif#endif