geSound
Description: DirectSound wrapper
Source file: …\genesis3d\OpenSource\Source\SOUND.h & SOUND3D.h
Function: CreateSoundSystem, DestroySoundSystem, FreeSoundDef, LoadSoundDef, ModifySound, PlaySoundDef, SetMasterVolume, SoundIsPlaying, StopSound,
geSound3d Functions: GetConfig, GetConfigIgnoreObstructions
Types: geSound_System, geSound_Def, geSound
Addition for Genesis3D v1.6: FreeAllChannels, GetDSound
Types:
typedef struct geSound_System geSound_System;
NOTE: The contents of this structure have been intentionally left out of the interface, by the designers of this module. Think of this as a handle only.
typedef struct geSound_Def geSound_Def;
NOTE: The contents of this structure have been intentionally left out of the interface, by the designers of this module. Think of this as a handle only.
typedef struct geSound geSound;
NOTE: The contents of this structure have been intentionally left out of the interface, by the designers of this module. Think of this as a handle only.
Functions:
GENESISAPI geSound_System* geSound_CreateSoundSystem(HWND hWnd);
This function creates a sound system for the given window handle.
Returns: The geSound_System* .
Notes:
from GENESIS.H: this function is only available if Windows.h is loaded before GENESIS.H
GENESISAPI void geSound_DestroySoundSystem(geSound_System* Sound);
This function shuts down the specified SoundSystem and frees up the resources.
Returns: nothing.
GENESISAPI void geSound_FreeAllChannels(geSound_System* SoundS);
Added for Genesis3D v1.6
GENESISAPI void geSound_FreeSoundDef(geSound_System* SoundS, geSound_Def* SoundDef);
This function removes a sound definition from the sound system and frees up the resources.
Returns: nothing.
GENESISAPI void*
geSound_GetDSound(void);
Added for Genesis3D v1.6
Returns: DSOUND object;
GENESISAPI geSound_Def* geSound_LoadSoundDef(geSound_System* SoundS, geVFile* File);
This function loads a sound definition file for use in the sound system. This call must be matched by a FreeSoundDef to avoid memory leaks. I assume the sound definition must be a valid wave file.
Returns: The geSound_Def* .
Questions:
Is there any required format for the wave file? Are there any restrictions?
GENESISAPI geBoolean geSound_ModifySound(geSound_System* SoundS, geSound* Sound, geFloat Volume, geFloat Pan, geFloat Frequency);
This function provides a facility whereby a playing sound's volume, panning, and the frequency can be changed. The Sound* is that returned by geSound_PlaySoundDef.
Questions:
What does it mean to change a sounds frequency? Does this also change the playback speed?
GENESISAPI geSound* geSound_PlaySoundDef(geSound_System* SoundS, geSound_Def* SoundDef, geFloat Volume, geFloat Pan, geFloat Frequency, geBoolean Loop);
This function plays the previously loaded geSound_Def with the specified volume, pan, frequency, and optional looping. The returned geSound* can be used in calls requiring a reference to the active sound such as geSound_ModifySound.
Returns: The geSound*.
Note: One tutorial states that:
Volume values range 0.0f - 1.0f
Pan can be set to 0.0f to get sound playing to both speakers
Frequency should be set to 1.0f for regular sound.
GENESISAPI geBoolean geSound_SetMasterVolume(geSound_System* SoundS, geFloat Volume );
This function sets the overall SoundSystem volume level.
GENESISAPI geBoolean geSound_SoundIsPlaying(geSound_System* SoundS, geSound* Sound);
This function tests whether the specified Sound is currently playing.
Return: GE_TRUE is the specified sound is playing, GE_FALSE otherwise.
GENESISAPI geBoolean geSound_StopSound(geSound_System* SoundS, geSound* Sound);
This function will halt the currently playing specified sound. This function may fail if the Sound is not currently playing.
I believe this would not only stop a looping sound but would stop a single loop sound at whatever point it is called. I also suspect that replaying the sound would start at the beginning of the sound_def not at the stopped point.
GENESISAPI void geSound3D_GetConfig(const geWorld* World, const geXForm3d* CameraTransform, const geVec3d* SoundPos, geFloat Min, geFloat Ds, geFloat* Volume, geFloat* Pan, geFloat* Frequency);
This function can be used to compute the volume, pan, frequency for a positional sound relative to the player's position to simulate 3D sound.
The goal of this function is to return Volume, Pan, and Frequency. These can then be used to execute geSound_PlaySoundDef, so that the sound appears 3d i.e. far away sounds are soft, etc.
World: the World you are using
CameraTransform: the transform used for rendering (i.e. the camera transform)
SoundPos: The position of the sound in the world
Min: Determines how the sound will decay with distance from camera, as follows:
Sound within Min distance --> full volume
Sound further than Max distance (which is set to Min*10) --> 0 volume (not heard)
In between, volume is graded such that it is at half intensity when twice Min distance
Ds: If modeling sound from a moving object (for example, a missle), then Ds should be the speed of this object towards the camera. This allows for doppler shifts, changing the frequency of the sound based on specified speed. The units are meters-per-second, with 331 mps being the velocity of sound through air in standard conditions.
0 --> no doppler shift (frequency returned will be 1.0f)
331 --> frequency is doubled (frequency returned will be 2.0f).
Volume: the variable that will received the output of this function.
Pan: the variable that will received the output of this function.
Frequency: the variable that will received the output of this function.
Returns: nothing (but does change values of Volume, Pan, Frequency)
GENESISAPI void geSound3D_GetConfigIgnoreObstructions(const geWorld* World, const geXForm3d* MXForm, const geVec3d* SndPos, geFloat Min, geFloat Ds, geFloat* Volume, geFloat* Pan, geFloat* Frequency);
See Notes for GetConfig above. This function differs from GetConfig by allowing sounds to play even if position of sound is not visible. For example, when an explosion occurs around a corner--where you can't see it--do you want the sound to be heard? If yes, use this function. If no, use GetConfig. Note: SoundPos from GetConfig is renamed SndPos here, but it means the same thing.