<HTML>
	<HEAD>
		<TITLE>Reference manual for David Piuva's graphics engine</TITLE>
	</HEAD>
	<BODY>
		<link rel="stylesheet" type="text/css" href="PageStyle.css">
		<A href="../Manual.html">Back to main page</A>
<P>		<b>Sound</b>
<P>		The sound engine is using my high quality lossy sound format with the extension *.dsf that can be converted to and from using the sound converter tool.
<P>		Clean and smooth high quality sounds gives a compression ratio of around 13%.
		Noisy low quality sounds from a cheap microphone gives a compression ratio of around 36%.
		The worst case compression ratio for white noise is around 50%.
<P>		You can use a free sound application called Audacity for creating your sound and save them as raw 16 bit PCM wave files.
		When your game is finished, you can use the sound converter tool to compress your sound files before releasing the game.
<P>	<IMG SRC="Images/Border.png">
<P>		<IMG SRC="Images/RightArrow.png"> void Sound_PlaceGlobalListener(float Pos_X, float Pos_Y, float Pos_Z, float Front_X, float Front_Y, float Front_Z, float Up_X, float Up_Y, float Up_Z);
<P>			The default listener is placed at (0,0,0) with the front facing (0,0,1) and the top facing (0,1,0).
<P>			<IMG SRC="Images/SideEffect.png"> Places the listener at (Pos_X,Pos_Y,Pos_Z) facing the direction (Front_X,Front_Y,Front_Z) with (Up_X,Up_Y,Up_Z) for orthogonalizing the top vector.
<P>	<IMG SRC="Images/Border.png">
<P>		<IMG SRC="Images/RightArrow.png"> void Sound_SetMetersPerDistanceUnit(float Meters);
<P>			By default, the meters per distance unit value equals 1.0.
<P>			Doubling the value will make the same difference as placing the sounds twice as far away from the listener.
<P>			Setting the value to 0 will make it sound as if all sounds are placed on the listener.
<P>			<IMG SRC="Images/PreCondition.png"> Meters >= 0
<P>			<IMG SRC="Images/SideEffect.png"> Sets the meters in the sound engine per distance units in the sound engine to Meters.
<P>	<IMG SRC="Images/LightBorder.png">
<P>		<IMG SRC="Images/LeftArrow.png"> float Sound_GetMetersPerDistanceUnit(void);
<P>			<IMG SRC="Images/PostCondition.png"> Returns the meters per distance unit value that you gave the engine the last time or the default value 1.0.
<P>	<IMG SRC="Images/Border.png">
<P>		<IMG SRC="Images/Star.png"> int Sound_Buffer_LoadFromFile_InSB(int NumberOfCopies, bool LoadAs3DSound, bool LoadAsEditable);
<P>			Both full and extensionless filenames are allowed. Use full names if you want to load the wave file and make a new compressed version. Use extensionless filenames for loading sound to your game so that you can compress the sound later without recompiling.
<P>			Choosing LoadAs3DSound will give each copy of the sound buffer a 3D position in the world so that you will hear them relative to the global listener.
<P>			Choosing LoadAsEditable will allow the sound buffer to be used by methods starting with "Sound_Buffer_Editable_".
<P>			<IMG SRC="Images/Warning.png"> NumberOfCopies will not save sound memory since modern soundcards and DirectSound does not have hardware instancing. It only save loading time and disk space. You might as well record multiple versions of each sound and play them in a random order to get more variation using the same amount of sound memory.
<P>			<IMG SRC="Images/PreCondition.png"> NumberOfCopies > 0. You may not load a multi channel sound as a 3D sound. The string buffer must contain a full or extensionless filename with less than 256 characters refering to a 16 bit PCM (Standard HiFi quality) wave sound (*.wav) or a compressed sound using David's Sound Format (*.dsf).
<P>			<IMG SRC="Images/SideEffect.png"> Create a new sound buffer from the loaded file.
<P>			<IMG SRC="Images/PostCondition.png"> Returns the ID to the new sound buffer loaded with the string buffer's content as the filename. If loading fails, -1 is returned.
<P>	<IMG SRC="Images/Border.png">
<P>		<IMG SRC="Images/Star.png"> int Sound_Buffer_CreateEmpty(int NumberOfCopies, int NumberOfChannels, int NumberOfSamplesPerChannel, int SamplesPerSecond, bool CreateAs3DSound);
<P>			<IMG SRC="Images/Warning.png"> Having more than 2 channels can make it difficult to play the sound without that number of speakers.
<P>			<IMG SRC="Images/PreCondition.png"> NumberOfCopies > 0, NumberOfChannels > 0, NumberOfSamplesPerChannel > 1 and (NumberOfChannels = 1 or CreateAs3DSound = false).
<P>			<IMG SRC="Images/SideEffect.png"> Create an empty sound buffer with the given properties.
<P>			<IMG SRC="Images/PostCondition.png"> Returns the ID to the new sound buffer.
<P>	<IMG SRC="Images/Border.png">
<P>		<IMG SRC="Images/RightArrow.png"> void Sound_Buffer_Editable_SaveToFile_InSB(int SoundBuffer);
<P>			This method does not allow extensionless filenames because you much choose between the *.wav and *.dsf formats. Saving a sound as "MySound.wav" will choose the 16 bit PCM wave format and "MySound.dsf" will compress the sound and save it in David's Sound Format.
<P>			<IMG SRC="Images/Warning.png"> Any existing file with the same name and extension will be overwritten. You can make an interface that ask the user about overwriting by checking if the file exist before saving.
<P>			<IMG SRC="Images/PreCondition.png"> The string buffer must contain a full filename to an existing or non existing file. The filename must have less than 260 characters and end with ".wav" or ".dsf" with lower or upper case letters.
<P>			<IMG SRC="Images/SideEffect.png"> Saves the sound data in SoundBuffer to the filename specified in the string buffer.
<P>	<IMG SRC="Images/Border.png">
<P>		<IMG SRC="Images/Trashcan.png"> void Sound_Buffer_Delete(int SoundBuffer);
<P>			<IMG SRC="Images/PreCondition.png"> SoundBuffer is a valid sound buffer reference.
<P>			<IMG SRC="Images/SideEffect.png"> Delete SoundBuffer.
<P>	<IMG SRC="Images/Border.png">
<P>		<IMG SRC="Images/RightArrow.png"> void Sound_Buffer_Play(int SoundBuffer, int Index, bool FromBeginning, bool Looping);
<P>			<IMG SRC="Images/PreCondition.png"> SoundBuffer is a valid sound buffer reference and 0 <= Index < number of copies.
<P>			<IMG SRC="Images/SideEffect.png"> If FromBeginning is true, start playing the sound from the beginning. Otherwise resume playing from the same place.
<P>	<IMG SRC="Images/LightBorder.png">
<P>		<IMG SRC="Images/LeftArrow.png"> int Sound_Buffer_IsPlaying(int SoundBuffer, int Index);
<P>			<IMG SRC="Images/PreCondition.png"> SoundBuffer is a valid sound buffer reference and 0 <= Index < number of copies.
<P>			<IMG SRC="Images/PostCondition.png"> Returns 1 if the sound is playing and 0 otherwise.
<P>	<IMG SRC="Images/LightBorder.png">
<P>		<IMG SRC="Images/LeftArrow.png"> int Sound_Buffer_GetLastPlayedIndex(int SoundBuffer);
<P>			<IMG SRC="Images/PreCondition.png"> SoundBuffer is a valid sound buffer reference.
<P>			<IMG SRC="Images/PostCondition.png"> Returns the index of the last copy that started to play in SoundBuffer.
<P>	<IMG SRC="Images/LightBorder.png">
<P>		<IMG SRC="Images/RightArrow.png"> void Sound_Buffer_Stop(int SoundBuffer, int Index);
<P>			<IMG SRC="Images/PreCondition.png"> SoundBuffer is a valid sound buffer reference and 0 <= Index < number of copies.
<P>			<IMG SRC="Images/SideEffect.png"> Stop copy number Index in SoundBuffer from playing.
<P>	<IMG SRC="Images/Border.png">
<P>		<IMG SRC="Images/LeftArrow.png"> int Sound_Buffer_GetNumberOfCopies(int SoundBuffer);
<P>			<IMG SRC="Images/PreCondition.png"> SoundBuffer is a valid sound buffer reference.
<P>			<IMG SRC="Images/PostCondition.png"> Returns the number of copies in SoundBuffer.
<P>	<IMG SRC="Images/LightBorder.png">
<P>		<IMG SRC="Images/LeftArrow.png"> int Sound_Buffer_GetNumberOfChannels(int SoundBuffer);
<P>			<IMG SRC="Images/PreCondition.png"> SoundBuffer is a valid sound buffer reference.
<P>			<IMG SRC="Images/PostCondition.png"> Returns the number of channels in SoundBuffer.
<P>	<IMG SRC="Images/LightBorder.png">
<P>		<IMG SRC="Images/LeftArrow.png"> int Sound_Buffer_GetNumberOfSamplesPerChannel(int SoundBuffer);
<P>			<IMG SRC="Images/PreCondition.png"> SoundBuffer is a valid sound buffer reference.
<P>			<IMG SRC="Images/PostCondition.png"> Returns the number of samples per channel in SoundBuffer.
<P>	<IMG SRC="Images/LightBorder.png">
<P>		<IMG SRC="Images/LeftArrow.png"> int Sound_Buffer_GetSamplesPerSecond(int SoundBuffer);
<P>			<IMG SRC="Images/PreCondition.png"> SoundBuffer is a valid sound buffer reference.
<P>			<IMG SRC="Images/PostCondition.png"> Returns the original number of samples per second in SoundBuffer before the speed multiplier is applied in each played copy.
<P>	<IMG SRC="Images/Border.png">
<P>		<IMG SRC="Images/RightArrow.png"> void Sound_Buffer_SetSpeed(int SoundBuffer, int Index, float Speed);
<P>			<IMG SRC="Images/PreCondition.png"> SoundBuffer is a valid sound buffer reference and 0 <= Index < number of copies.
<P>			<IMG SRC="Images/SideEffect.png"> Sets the speed of copy number Index in SoundBuffer to Speed. The final sampling rate equals Speed times the sound's original sampling rate clamped to what can be played.
<P>	<IMG SRC="Images/LightBorder.png">
<P>		<IMG SRC="Images/LeftArrow.png"> float Sound_Buffer_GetSpeed(int SoundBuffer, int Index);
<P>			<IMG SRC="Images/PreCondition.png"> SoundBuffer is a valid sound buffer reference and 0 <= Index < number of copies.
<P>			<IMG SRC="Images/PostCondition.png"> Returns the speed of copy number Index in SoundBuffer that you assigned. This might not be the real speed that you hear because the final sampling rate will be clamped to sampling rates that can be played.
<P>	<IMG SRC="Images/Border.png">
<P>		<IMG SRC="Images/RightArrow.png"> void Sound_Buffer_SetVolume(int SoundBuffer, int Index, float Volume);
<P>			If you can't get your sound to play fast enough on your computer, try reducing the original sampling rate of the sound to get a lower sound quality but less restriction on the maximum speed.
<P>			<IMG SRC="Images/PreCondition.png"> SoundBuffer is a valid sound buffer reference, 0 <= Index < number of copies and 0 <= Volume <= 1. Values outside are clamped to the nearest value.
<P>			<IMG SRC="Images/SideEffect.png"> Sets the volume of copy number Index in SoundBuffer to Volume in a linear scale where 0 is muted and 1 is full volume.
<P>	<IMG SRC="Images/LightBorder.png">
<P>		<IMG SRC="Images/LeftArrow.png"> float Sound_Buffer_GetVolume(int SoundBuffer, int Index);
<P>			<IMG SRC="Images/PreCondition.png"> SoundBuffer is a valid sound buffer reference and 0 <= Index < number of copies.
<P>			<IMG SRC="Images/PostCondition.png"> Returns the volume of copy number Index in SoundBuffer that you assigned. This might not be the real volume that you hear because of clamping to the range [0..1].
<P>	<IMG SRC="Images/Border.png">
<P>		<IMG SRC="Images/LeftArrow.png"> int Sound_Buffer_Is3DSound(int SoundBuffer);
<P>			<IMG SRC="Images/PreCondition.png"> SoundBuffer is a valid sound buffer reference.
<P>			<IMG SRC="Images/PostCondition.png"> Returns 1 if the sound have a 3D position and 0 otherwise.
<P>	<IMG SRC="Images/Border.png">
<P>		<IMG SRC="Images/RightArrow.png"> void Sound_Buffer_3D_SetPosition(int SoundBuffer, int Index, float X, float Y, float Z);
<P>			<IMG SRC="Images/PreCondition.png"> SoundBuffer is a valid sound buffer reference and 0 <= Index < number of copies.
<P>			<IMG SRC="Images/SideEffect.png"> Sets the 3D position of copy number Index in SoundBuffer to (X,Y,Z).
<P>	<IMG SRC="Images/LightBorder.png">
<P>		<IMG SRC="Images/LeftArrow.png"> void Sound_Buffer_3D_GetPosition_OutV3(int SoundBuffer, int Index);
<P>			<IMG SRC="Images/PreCondition.png"> SoundBuffer is a valid sound buffer reference and 0 <= Index < number of copies.
<P>			<IMG SRC="Images/SideEffect.png"> Writes the 3D position of copy number Index in SoundBuffer to (X1,Y1,Z1) in the matrix buffer.
<P>	<IMG SRC="Images/Border.png">
<P>		<IMG SRC="Images/LeftArrow.png"> int Sound_Buffer_IsEditable(int SoundBuffer);
<P>			<IMG SRC="Images/PreCondition.png"> SoundBuffer is a valid sound buffer reference.
<P>			<IMG SRC="Images/PostCondition.png"> Returns 1 if the sound is editable and 0 otherwise.
<P>	<IMG SRC="Images/Border.png">
<P>		<IMG SRC="Images/LeftArrow.png"> float Sound_Buffer_Editable_GetSample(int SoundBuffer, int Time, int Channel);
<P>			<IMG SRC="Images/PreCondition.png"> SoundBuffer is a valid sound buffer reference, 0 <= Time < number of sampler per channel and 0 <= Channel < number of channels.
<P>			<IMG SRC="Images/PostCondition.png"> Returns the sample at Time and Channel in SoundBuffer converted to a floatingpoint value in the range [-1..1]
<P>	<IMG SRC="Images/LightBorder.png">
<P>		<IMG SRC="Images/RightArrow.png"> void Sound_Buffer_Editable_SetSample(int SoundBuffer, int Time, int Channel, float NewValue);
<P>			<IMG SRC="Images/Warning.png"> You will not hear any change before calling Sound_Buffer_Editable_Update and Sound_Buffer_Play.
<P>			<IMG SRC="Images/PreCondition.png"> SoundBuffer is a valid sound buffer reference, 0 <= Time < number of sampler per channel, 0 <= Channel < number of channels and -1 <= NewValue <= 1.
<P>			<IMG SRC="Images/SideEffect.png"> Sets the sample at Time and Channel in SoundBuffer to NewValue converted to the internal integer representation.
<P>	<IMG SRC="Images/Border.png">
<P>		<IMG SRC="Images/RightArrow.png"> void Sound_Buffer_Editable_Update(int SoundBuffer);
<P>			<IMG SRC="Images/PreCondition.png"> SoundBuffer is a valid sound buffer reference.
<P>			<IMG SRC="Images/SideEffect.png"> Stop playing all copies in SoundBuffer and upload the changes that you did with Sound_Buffer_Editable_SetSample so that you will hear it the next time you play a copy.
<P>	<IMG SRC="Images/Border.png">
	</BODY>
</HTML>