diff --git a/include/QF/sound.h b/include/QF/sound.h index abb7129b7..fcad30bea 100644 --- a/include/QF/sound.h +++ b/include/QF/sound.h @@ -30,6 +30,9 @@ #ifndef _SOUND_H #define _SOUND_H +/** \defgroup sound QuakeForge sound engine +*/ + #include "QF/mathlib.h" #define AMBIENT_WATER 0 @@ -73,58 +76,145 @@ typedef struct dma_s { } dma_t; struct model_s; + +/** \defgroup sound_init Initialization functions + \ingroup sound +*/ +//@{ + +/** Initialize the sound engine. + \param worldmodel pointer to the main engine's world model pointer + \param viewentity pointer to view entity index + \param host_frametime pointer to host frame time difference +*/ void S_Init (struct model_s **worldmodel, int *viewentity, double *host_frametime); + +/** Initialize the Cvars for the sound engine. Call before calling S_Init(). +*/ void S_Init_Cvars (void); -void S_Startup (void); + +/** Shutdown the sound engine. Allows audio output modules to shutdown + gracefully. +*/ void S_Shutdown (void); +//@} + +/** \defgroup sound_stuff Unclassified + \ingroup sound +*/ +//@{ + +/** Start a sound playing. + \param entnum index of entity the sound is associated with. + \param entchannel 0-7 + - 0 auto (never willingly overrides) + - 1 weapon + - 2 voice + - 3 item + - 4 body + \param sfx sound to play + \param origin 3d coords of where the sound originates + \param fvol absolute volume of the sound + \param attenuation rate of volume dropoff vs distance +*/ void S_StartSound (int entnum, int entchannel, sfx_t *sfx, const vec3_t origin, float fvol, float attenuation); + +/** Create a sound generated by the world. + \param sfx sound to play + \param origin 3d coords of where the sound originates + \param vol absolute volume of the sound + \param attenuation rate of volume dropoff vs distance +*/ void S_StaticSound (sfx_t *sfx, const vec3_t origin, float vol, float attenuation); +/** Stop an entity's sound. + \param entnum index of entity the sound is associated with. + \param entchannel channel to silence +*/ void S_StopSound (int entnum, int entchannel); + +/** Stop all sounds from playing. + \param clear if true, the buffer is cleared so sound stops immediately + rather than trailing off +*/ void S_StopAllSounds(qboolean clear); + +/** Update the sound engine with the client's position and orientation and + render some sound. + \param origin 3d coords of the client + \param v_forward 3d vector of the client's facing direction + \param v_right 3d vector of the client's rightward direction + \param v_up 3d vector of the client's upward direction +*/ void S_Update (const vec3_t origin, const vec3_t v_forward, const vec3_t v_right, const vec3_t v_up); + +/** Render some more sound without updating the client's position/orientation. +*/ void S_ExtraUpdate (void); + +/** Pause the sound output. Nested blocking is supported, so calls to + S_BlockSound() and S_UnblockSound() must be balanced. +*/ void S_BlockSound (void); + +/** Unpause the sound output. Nested blocking is supported, so calls to + S_BlockSound() and S_UnblockSound() must be balanced. +*/ void S_UnblockSound (void); +/** Pre-load a sound into the cache. + \param sample name of sound to precache +*/ sfx_t *S_PrecacheSound (const char *sample); + +/** Tag a cached sound to prevent it being flushed unnecessarily. + \param sample name of sound touch + \todo check that Cache_TryGet() does the right thing +*/ void S_TouchSound (const char *sample); + +/** Does nothing. + \todo remove? +*/ void S_ClearPrecache (void); + +/** Does nothing. + \todo remove? +*/ void S_BeginPrecaching (void); + +/** Does nothing. + \todo remove? +*/ void S_EndPrecaching (void); +/** Pre-load a sound. + \param name name of sound to load +*/ sfx_t *S_LoadSound (const char *name); + +/** Allocate a sound channel that can be used for playing sounds. +*/ struct channel_s *S_AllocChannel (void); -// ==================================================================== -// User-setable variables -// ==================================================================== - -#define MAX_CHANNELS 256 -#define MAX_DYNAMIC_CHANNELS 8 - -// -// Fake dma is a synchronous faking of the DMA progress used for -// isolating performance in the renderer. The fakedma_updates is -// number of times S_Update() is called per second. -// - -extern unsigned paintedtime; - -extern struct cvar_s *snd_loadas8bit; -extern struct cvar_s *volume; - -extern struct cvar_s *snd_interp; -extern struct cvar_s *snd_stereo_phase_separation; - +/** Start a sound local to the client view. + \param s name of sound to play +*/ void S_LocalSound (const char *s); +/** Disable ambient sounds. + \todo not used, remove? +*/ void S_AmbientOff (void); + +/** Enable ambient sounds. + \todo not used, remove? +*/ void S_AmbientOn (void); -extern struct model_s **snd_worldmodel; +//@} #endif // _SOUND_H diff --git a/include/snd_render.h b/include/snd_render.h index 402e56b19..b1c66b852 100644 --- a/include/snd_render.h +++ b/include/snd_render.h @@ -133,6 +133,27 @@ void SND_PaintChannelFrom16 (channel_t *ch, sfxbuffer_t *sc, int count); void SND_PaintChannelStereo8 (channel_t *ch, sfxbuffer_t *sc, int count); void SND_PaintChannelStereo16 (channel_t *ch, sfxbuffer_t *sc, int count); +// ==================================================================== +// User-setable variables +// ==================================================================== + +#define MAX_CHANNELS 256 +#define MAX_DYNAMIC_CHANNELS 8 + +// +// Fake dma is a synchronous faking of the DMA progress used for +// isolating performance in the renderer. The fakedma_updates is +// number of times S_Update() is called per second. +// + +extern unsigned paintedtime; + +extern struct cvar_s *snd_loadas8bit; +extern struct cvar_s *volume; + +extern struct cvar_s *snd_interp; +extern struct cvar_s *snd_stereo_phase_separation; + extern volatile dma_t *shm; extern channel_t channels[MAX_CHANNELS]; // 0 to MAX_DYNAMIC_CHANNELS-1 = normal entity sounds