audio interface clean-up and Sys_* documentation

code/client/snd_dma.cpp

@@ -476,12 +476,12 @@ static void S_Base_ClearSoundBuffer()
 
 	s_rawend = 0;
 
-	SNDDMA_BeginPainting();
+	Sys_S_BeginPainting();
 	if (dma.buffer) {
 		int clear = (dma.samplebits == 8) ? 0x80 : 0x00;
 		Com_Memset( dma.buffer, clear, dma.samples * dma.samplebits/8 );
 	}
-	SNDDMA_Submit();
+	Sys_S_Submit();
 }
 
 
@@ -844,7 +844,7 @@ static void S_GetSoundtime()
 
 	// it is possible to miscount buffers if it has wrapped twice between
 	// calls to S_Update.  Oh well.
-	int samplepos = SNDDMA_GetDMAPos();
+	int samplepos = Sys_S_GetDMAPos();
 	if (samplepos < oldsamplepos) {
 		buffers++;	// buffer wrapped
 		if (s_paintedtime > 0x40000000) {
@@ -913,11 +913,11 @@ static void S_Update_DMA()
 	if (endtime - s_soundtime > samps)
 		endtime = s_soundtime + samps;
 
-	SNDDMA_BeginPainting();
+	Sys_S_BeginPainting();
 
 	S_PaintChannels( endtime );
 
-	SNDDMA_Submit();
+	Sys_S_Submit();
 }
 
 
@@ -1090,7 +1090,7 @@ static void S_Base_Shutdown()
 		return;
 	}
 
-	SNDDMA_Shutdown();
+	Sys_S_Shutdown();
 
 	s_soundStarted = qfalse;
 
@@ -1113,7 +1113,7 @@ qbool S_Base_Init( soundInterface_t *si )
 
 	Cvar_RegisterArray( cl_cvars, MODULE_SOUND );
 
-	if (!SNDDMA_Init())
+	if (!Sys_S_Init())
 		return qfalse;
 
 	s_soundStarted = qtrue;

code/client/snd_local.h

@@ -119,11 +119,23 @@ typedef struct
 ====================================================================
 */
 
-qbool SNDDMA_Init();
-int SNDDMA_GetDMAPos();
-void SNDDMA_Shutdown();
-void SNDDMA_BeginPainting();
-void SNDDMA_Submit();
+qbool	Sys_S_Init();
+void	Sys_S_Shutdown();
+
+// Returns the current sample position (in mono samples read)
+// inside the DMA ring buffer so the mixing code knows
+// how many sample are required to fill it up.
+int		Sys_S_GetDMAPos();
+
+// Makes sure dma.buffer is valid and accessible.
+// If necessary, acquires a lock.
+void	Sys_S_BeginPainting();
+
+// Sends sound to device if dma.buffer isn't really the DMA buffer.
+// If a lock was acquired by Sys_S_BeginPainting,
+// Sys_S_Submit will release it.
+void	Sys_S_Submit();
+
 
 #define	MAX_CHANNELS			96
 

code/linux/sdl_snd.cpp

@@ -63,7 +63,7 @@ static void FillAudioBufferCallback( void* userData, Uint8* sdlBuffer, int sdlBy
 }
 
 
-qbool SNDDMA_Init()
+qbool Sys_S_Init()
 {
 	if (audio.valid)
 		return qtrue;
@@ -86,7 +86,7 @@ qbool SNDDMA_Init()
 	audio.device = SDL_OpenAudioDevice(NULL, 0, &desired, &obtained, 0);
 	if (audio.device == 0) {
 		Com_Printf("SDL_OpenAudioDevice failed: %s\n", SDL_GetError());
-		SNDDMA_Shutdown();
+		Sys_S_Shutdown();
 		return qfalse;
 	}
 
@@ -109,7 +109,7 @@ qbool SNDDMA_Init()
 }
 
 
-int SNDDMA_GetDMAPos()
+int Sys_S_GetDMAPos()
 {
 	if (!audio.valid)
 		return 0;
@@ -118,7 +118,7 @@ int SNDDMA_GetDMAPos()
 }
 
 
-void SNDDMA_Shutdown()
+void Sys_S_Shutdown()
 {
 	if (audio.device != 0) {
 		SDL_PauseAudioDevice(audio.device, 1);
@@ -135,7 +135,7 @@ void SNDDMA_Shutdown()
 }
 
 
-void SNDDMA_Submit()
+void Sys_S_Submit()
 {
 	if (!audio.valid)
 		return;
@@ -145,7 +145,7 @@ void SNDDMA_Submit()
 }
 
 
-void SNDDMA_BeginPainting()
+void Sys_S_BeginPainting()
 {
 	if (!audio.valid)
 		return;

code/qcommon/qcommon.h

@@ -1066,6 +1066,7 @@ void Sys_Init();
 void	Sys_Quit( int status ); // status is the engine's exit code
 
 // both of these must handle duplicate calls correctly
+// and are only called in a full input subsystem restart (i.e. in_restart)
 void	Sys_InitInput();
 void	Sys_ShutdownInput();
 
@@ -1074,7 +1075,11 @@ void* QDECL Sys_LoadDll( const char* name, dllSyscall_t *entryPoint, dllSyscall_
 void		Sys_UnloadDll( void* dllHandle );
 
 void QDECL	Sys_Error( const char *error, ...);
-char	*Sys_GetClipboardData( void );	// note that this isn't journaled...
+
+// allowed to fail and return NULL
+// if it succeeds, returns memory allocated by Z_Malloc
+// note that this isn't journaled
+char	*Sys_GetClipboardData( void );
 
 void	Sys_Print( const char *msg );
 
@@ -1083,17 +1088,15 @@ void	Sys_Print( const char *msg );
 int		Sys_Milliseconds();
 
 // the system console is shown when a dedicated server is running
-void	Sys_DisplaySystemConsole( qbool show );
-
 void	Sys_ShowConsole( int level, qbool quitOnClose );
+
 void	Sys_SetErrorText( const char *text );
 
+// net_ip.cpp
+// system-specific but not implemented in the platform layer
 qbool	Sys_GetPacket( netadr_t* net_from, msg_t* net_message );
 void	Sys_SendPacket( int length, const void *data, netadr_t to );
-
-qbool	Sys_StringToAdr( const char *s, netadr_t *a );
-//Does NOT parse port numbers, only base addresses.
-
+qbool	Sys_StringToAdr( const char *s, netadr_t *a );	// does NOT parse port numbers, only base addresses
 qbool	Sys_IsLANAddress( const netadr_t& adr );
 void	Sys_ShowIP();
 

code/win32/win_snd.cpp

@@ -55,12 +55,8 @@ static const char *DSoundError( int error ) {
 	return "unknown";
 }
 
-/*
-==================
-SNDDMA_Shutdown
-==================
-*/
-void SNDDMA_Shutdown( void ) {
+
+void Sys_S_Shutdown( void ) {
 	Com_DPrintf( "Shutting down sound system\n" );
 
 	if ( pDS ) {
@@ -124,7 +120,7 @@ static qbool SNDDMA_InitDS()
 	}
 	else {
 		Com_Printf("failed\n");
-		SNDDMA_Shutdown();
+		Sys_S_Shutdown();
 		return qfalse;
 	}
 
@@ -134,7 +130,7 @@ static qbool SNDDMA_InitDS()
 
 	if ( DS_OK != pDS->SetCooperativeLevel( g_wv.hWnd, DSSCL_PRIORITY ) ) {
 		Com_Printf ("failed\n");
-		SNDDMA_Shutdown();
+		Sys_S_Shutdown();
 		return qfalse;
 	}
 	Com_DPrintf("ok\n" );
@@ -173,7 +169,7 @@ static qbool SNDDMA_InitDS()
 		dsbuf.dwFlags = DSBCAPS_LOCSOFTWARE | DSBCAPS_GETCURRENTPOSITION2;
 		if (DS_OK != pDS->CreateSoundBuffer( &dsbuf, &pDSBuf, NULL )) {
 			Com_Printf( "failed\n" );
-			SNDDMA_Shutdown();
+			Sys_S_Shutdown();
 			return qfalse;
 		}
 		Com_DPrintf( "forced to software.  ok\n" );
@@ -182,14 +178,14 @@ static qbool SNDDMA_InitDS()
 	// Make sure mixer is active
 	if ( DS_OK != pDSBuf->Play( 0, 0, DSBPLAY_LOOPING ) ) {
 		Com_Printf ("*** Looped sound play failed ***\n");
-		SNDDMA_Shutdown ();
+		Sys_S_Shutdown ();
 		return qfalse;
 	}
 
 	// get the returned buffer size
 	if ( DS_OK != pDSBuf->GetCaps(&dsbcaps) ) {
 		Com_Printf ("*** GetCaps failed ***\n");
-		SNDDMA_Shutdown ();
+		Sys_S_Shutdown ();
 		return qfalse;
 	}
 
@@ -204,16 +200,16 @@ static qbool SNDDMA_InitDS()
 
 	sample16 = (dma.samplebits/8) - 1;
 
-	SNDDMA_BeginPainting();
+	Sys_S_BeginPainting();
 	if (dma.buffer)
 		memset(dma.buffer, 0, dma.samples * dma.samplebits/8);
-	SNDDMA_Submit();
+	Sys_S_Submit();
 
 	return qtrue;
 }
 
 
-qbool SNDDMA_Init(void)
+qbool Sys_S_Init(void)
 {
 	CoInitialize(NULL);
 
@@ -230,16 +226,7 @@ qbool SNDDMA_Init(void)
 }
 
 
-/*
-==============
-SNDDMA_GetDMAPos
-
-return the current sample position (in mono samples read)
-inside the recirculating dma buffer, so the mixing code will know
-how many sample are required to fill it up.
-===============
-*/
-int SNDDMA_GetDMAPos( void ) {
+int Sys_S_GetDMAPos( void ) {
 	MMTIME	mmtime;
 	int		s;
 	DWORD	dwWrite;
@@ -256,14 +243,8 @@ int SNDDMA_GetDMAPos( void ) {
 	return s;
 }
 
-/*
-==============
-SNDDMA_BeginPainting
 
-Makes sure dma.buffer is valid
-===============
-*/
-void SNDDMA_BeginPainting( void ) {
+void Sys_S_BeginPainting( void ) {
 	int		reps;
 	DWORD	dwSize2;
 	DWORD	*pbuf, *pbuf2;
@@ -309,15 +290,8 @@ void SNDDMA_BeginPainting( void ) {
 	dma.buffer = (unsigned char *)pbuf;
 }
 
-/*
-==============
-SNDDMA_Submit
 
-Send sound to device if buffer isn't really the dma buffer
-Also unlocks the dsound buffer
-===============
-*/
-void SNDDMA_Submit( void )
+void Sys_S_Submit( void )
 {
 	if ( pDSBuf ) {
 		pDSBuf->Unlock( dma.buffer, locksize, NULL, 0 );
@@ -325,13 +299,7 @@ void SNDDMA_Submit( void )
 }
 
 
-/*
-=================
-WIN_S_WindowActivate
-
-Called in reaction to WM_ACTIVATE
-=================
-*/
+// Called in reaction to WM_ACTIVATE
 void WIN_S_WindowActivate()
 {
 	if ( !pDS ) {
@@ -340,7 +308,6 @@ void WIN_S_WindowActivate()
 
 	if ( DS_OK != pDS->SetCooperativeLevel( g_wv.hWnd, DSSCL_PRIORITY ) ) {
 		Com_Printf ("sound SetCooperativeLevel failed\n");
-		SNDDMA_Shutdown();
+		Sys_S_Shutdown();
 	}
 }
-