Back to main page

Sound

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.

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%.

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.

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);

The default listener is placed at (0,0,0) with the front facing (0,0,1) and the top facing (0,1,0).

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.

void Sound_SetMetersPerDistanceUnit(float Meters);

By default, the meters per distance unit value equals 1.0.

Doubling the value will make the same difference as placing the sounds twice as far away from the listener.

Setting the value to 0 will make it sound as if all sounds are placed on the listener.

Meters >= 0

Sets the meters in the sound engine per distance units in the sound engine to Meters.

float Sound_GetMetersPerDistanceUnit(void);

Returns the meters per distance unit value that you gave the engine the last time or the default value 1.0.

int Sound_Buffer_LoadFromFile_InSB(int NumberOfCopies, bool LoadAs3DSound, bool LoadAsEditable);

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.

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.

Choosing LoadAsEditable will allow the sound buffer to be used by methods starting with "Sound_Buffer_Editable_".

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.

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).

Create a new sound buffer from the loaded file.

Returns the ID to the new sound buffer loaded with the string buffer's content as the filename. If loading fails, -1 is returned.

int Sound_Buffer_CreateEmpty(int NumberOfCopies, int NumberOfChannels, int NumberOfSamplesPerChannel, int SamplesPerSecond, bool CreateAs3DSound);

Having more than 2 channels can make it difficult to play the sound without that number of speakers.

NumberOfCopies > 0, NumberOfChannels > 0, NumberOfSamplesPerChannel > 1 and (NumberOfChannels = 1 or CreateAs3DSound = false).

Create an empty sound buffer with the given properties.

Returns the ID to the new sound buffer.

void Sound_Buffer_Editable_SaveToFile_InSB(int SoundBuffer);

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.

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.

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.

Saves the sound data in SoundBuffer to the filename specified in the string buffer.

void Sound_Buffer_Delete(int SoundBuffer);

SoundBuffer is a valid sound buffer reference.

Delete SoundBuffer.

void Sound_Buffer_Play(int SoundBuffer, int Index, bool FromBeginning, bool Looping);

SoundBuffer is a valid sound buffer reference and 0 <= Index < number of copies.

If FromBeginning is true, start playing the sound from the beginning. Otherwise resume playing from the same place.

int Sound_Buffer_IsPlaying(int SoundBuffer, int Index);

SoundBuffer is a valid sound buffer reference and 0 <= Index < number of copies.

Returns 1 if the sound is playing and 0 otherwise.

int Sound_Buffer_GetLastPlayedIndex(int SoundBuffer);

SoundBuffer is a valid sound buffer reference.

Returns the index of the last copy that started to play in SoundBuffer.

void Sound_Buffer_Stop(int SoundBuffer, int Index);

SoundBuffer is a valid sound buffer reference and 0 <= Index < number of copies.

Stop copy number Index in SoundBuffer from playing.

int Sound_Buffer_GetNumberOfCopies(int SoundBuffer);

SoundBuffer is a valid sound buffer reference.

Returns the number of copies in SoundBuffer.

int Sound_Buffer_GetNumberOfChannels(int SoundBuffer);

SoundBuffer is a valid sound buffer reference.

Returns the number of channels in SoundBuffer.

int Sound_Buffer_GetNumberOfSamplesPerChannel(int SoundBuffer);

SoundBuffer is a valid sound buffer reference.

Returns the number of samples per channel in SoundBuffer.

int Sound_Buffer_GetSamplesPerSecond(int SoundBuffer);

SoundBuffer is a valid sound buffer reference.

Returns the original number of samples per second in SoundBuffer before the speed multiplier is applied in each played copy.

void Sound_Buffer_SetSpeed(int SoundBuffer, int Index, float Speed);

SoundBuffer is a valid sound buffer reference and 0 <= Index < number of copies.

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.

float Sound_Buffer_GetSpeed(int SoundBuffer, int Index);

SoundBuffer is a valid sound buffer reference and 0 <= Index < number of copies.

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.

void Sound_Buffer_SetVolume(int SoundBuffer, int Index, float Volume);

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.

SoundBuffer is a valid sound buffer reference, 0 <= Index < number of copies and 0 <= Volume <= 1. Values outside are clamped to the nearest value.

Sets the volume of copy number Index in SoundBuffer to Volume in a linear scale where 0 is muted and 1 is full volume.

float Sound_Buffer_GetVolume(int SoundBuffer, int Index);

SoundBuffer is a valid sound buffer reference and 0 <= Index < number of copies.

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].

int Sound_Buffer_Is3DSound(int SoundBuffer);

SoundBuffer is a valid sound buffer reference.

Returns 1 if the sound have a 3D position and 0 otherwise.

void Sound_Buffer_3D_SetPosition(int SoundBuffer, int Index, float X, float Y, float Z);

SoundBuffer is a valid sound buffer reference and 0 <= Index < number of copies.

Sets the 3D position of copy number Index in SoundBuffer to (X,Y,Z).

void Sound_Buffer_3D_GetPosition_OutV3(int SoundBuffer, int Index);

SoundBuffer is a valid sound buffer reference and 0 <= Index < number of copies.

Writes the 3D position of copy number Index in SoundBuffer to (X1,Y1,Z1) in the matrix buffer.

int Sound_Buffer_IsEditable(int SoundBuffer);

SoundBuffer is a valid sound buffer reference.

Returns 1 if the sound is editable and 0 otherwise.

float Sound_Buffer_Editable_GetSample(int SoundBuffer, int Time, int Channel);

SoundBuffer is a valid sound buffer reference, 0 <= Time < number of sampler per channel and 0 <= Channel < number of channels.

Returns the sample at Time and Channel in SoundBuffer converted to a floatingpoint value in the range [-1..1]

void Sound_Buffer_Editable_SetSample(int SoundBuffer, int Time, int Channel, float NewValue);

You will not hear any change before calling Sound_Buffer_Editable_Update and Sound_Buffer_Play.

SoundBuffer is a valid sound buffer reference, 0 <= Time < number of sampler per channel, 0 <= Channel < number of channels and -1 <= NewValue <= 1.

Sets the sample at Time and Channel in SoundBuffer to NewValue converted to the internal integer representation.

void Sound_Buffer_Editable_Update(int SoundBuffer);

SoundBuffer is a valid sound buffer reference.

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.