add some documentation to QF/sound.h and move renderer private stuff into snd_render.h

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

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