added and converted comments into a doxygen friendly format

1 files changed, 72 insertions, 41 deletions

diff --git a/dxr3interface.c b/dxr3interface.c
index 23437b1..f32c3cf 100644
--- a/dxr3interface.c
+++ b/dxr3interface.c
@@ -1,3 +1,25 @@
+/*
+ * dxr3interface.h
+ *
+ * Copyright (C) 2002-2004 Kai Möller
+ * Copyright (C) 2004 Christian Gmeiner
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * as published by the Free Software Foundation; either version 2.1
+ * of the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
+ *
+ */
+
 #include <assert.h>
 #include <math.h>
 #include <sys/soundcard.h>
@@ -13,7 +35,7 @@ const int ZEROBUFFER_SIZE = 4096;
 uint8_t zerobuffer[ZEROBUFFER_SIZE] = {0};
 
 // ==================================
-// helper function to generate name
+//! helper function to generate name
 static const char *Dxr3Name(const char *Name, int n)
 {
 	static char buffer[PATH_MAX];
@@ -22,7 +44,7 @@ static const char *Dxr3Name(const char *Name, int n)
 }
 
 // ==================================
-// helper function to open the card #n
+//! helper function to open the card #n
 static int Dxr3Open(const char *Name, int n, int Mode)
 {
 	const char *FileName = Dxr3Name(Name, n);
@@ -36,10 +58,10 @@ static int Dxr3Open(const char *Name, int n, int Mode)
 }
 
 // ==================================
-// constr.
+//! constr.
 cDxr3Interface::cDxr3Interface()
 {
-	// open control stream
+	///< open control stream
 	m_fdControl = Dxr3Open("", cDxr3ConfigData::Instance().GetDxr3Card(), O_WRONLY | O_SYNC);
 	if (!m_fdControl)
 	{
@@ -47,30 +69,32 @@ cDxr3Interface::cDxr3Interface()
 		cLog::Instance() << "Please check if the dxr3 modules are loaded!\n";
 	}
 
-	// upload microcode to dxr3
+	///< upload microcode to dxr3
 	UploadMicroCode();
 
-	// open 'multimedia' streams
+	///< open 'multimedia' streams
     m_fdVideo = Dxr3Open("_mv", cDxr3ConfigData::Instance().GetDxr3Card(), O_WRONLY | O_SYNC);
     m_fdAudio = Dxr3Open("_ma", cDxr3ConfigData::Instance().GetDxr3Card(), O_WRONLY | O_SYNC);
     m_fdSpu = Dxr3Open("_sp", cDxr3ConfigData::Instance().GetDxr3Card(), O_WRONLY | O_SYNC);
 
-	// everything ok?
+	///< everything ok?
 	if (!m_fdVideo || !m_fdAudio || !m_fdSpu)
 	{
 		cLog::Instance() << "Unable to open one of the 'mulitmedia' streams!\n";
 		exit(1);
 	}
 
+	///< create clock
 	m_pClock = new cDxr3SysClock(m_fdControl, m_fdVideo, m_fdSpu);
 
+	///< everything ok?
 	if (!m_pClock)
 	{
 		cLog::Instance() << "Unable to allocate memory for m_pClock in cDxr3Interface\n";
 		exit(1);
 	}
 
-	// set default values
+	///< set default values
     m_AudioActive = false;
     m_VideoActive = false; 
 	m_OverlayActive = false;
@@ -81,15 +105,15 @@ cDxr3Interface::cDxr3Interface()
     m_audioDataRate = 0;
     m_audioSampleSize = 0;
 
-	// default value 9 = unused value
+	///< default value 9 = unused value
     m_audioMode =  9;
 	m_aspectRatio = UNKNOWN_ASPECT_RATIO;
 	m_spuMode = EM8300_SPUMODE_OFF;
 
-	// configure device based on settings
+	///< configure device based on settings
 	ConfigureDevice();
 
-	// get bcs values from driver
+	///< get bcs values from driver
 	ioctl(m_fdControl, EM8300_IOCTL_GETBCS, &m_bcs);
 
 	if (cDxr3ConfigData::Instance().GetDebug())
@@ -106,7 +130,7 @@ cDxr3Interface::cDxr3Interface()
 // ==================================
 cDxr3Interface::~cDxr3Interface()
 {
-	// close filehandles
+	///< close filehandles
 	if (m_fdControl)
 	{
 		close(m_fdControl);
@@ -124,7 +148,7 @@ cDxr3Interface::~cDxr3Interface()
 		close(m_fdAudio);
 	}
 
-	// free some memory
+	///< free some memory
 	if (m_pClock)
 	{
 		delete m_pClock;
@@ -144,7 +168,7 @@ void cDxr3Interface::Stop()
 
 // audio
 // ==================================
-// set audio-output to analog
+//! set audio-output to analog
 void cDxr3Interface::SetAudioAnalog()
 {
     int ioval = 0;
@@ -168,7 +192,7 @@ void cDxr3Interface::SetAudioAnalog()
 }
 
 // ==================================
-// set audio-output to digital pcm
+//! set audio-output to digital pcm
 void cDxr3Interface::SetAudioDigitalPCM()
 {
     int ioval = 0;
@@ -193,7 +217,7 @@ void cDxr3Interface::SetAudioDigitalPCM()
 }
 
 // ==================================
-// set audio-output to digital ac3
+//! set audio-output to digital ac3
 void cDxr3Interface::SetAudioDigitalAC3()
 {
     if (m_audioMode != EM8300_AUDIOMODE_DIGITALAC3) 
@@ -216,6 +240,7 @@ void cDxr3Interface::SetAudioDigitalAC3()
 }
 
 // ==================================
+//! set audiosepeed
 void cDxr3Interface::SetAudioSpeed(uint32_t speed)
 {
     if (m_audioDataRate != speed && speed != UNKNOWN_DATA_RATE) 
@@ -235,6 +260,7 @@ void cDxr3Interface::SetAudioSpeed(uint32_t speed)
 }
 
 // ==================================
+//! set nummber of channels
 void cDxr3Interface::SetChannelCount(uint32_t count)
 {
     if (m_audioChannelCount != count && count != UNKNOWN_CHANNEL_COUNT) 
@@ -254,6 +280,7 @@ void cDxr3Interface::SetChannelCount(uint32_t count)
 }
 
 // ==================================
+//! set audio sample size
 void cDxr3Interface::SetAudioSampleSize(uint32_t sampleSize) 
 {
     if (!m_ExternalReleased) 
@@ -311,7 +338,7 @@ void cDxr3Interface::SetSpuPts(uint32_t pts)
 
 // state changes
 // ==================================
-// enable subpicture proeccesing of the dxr3
+//! enable subpicture proeccesing of the dxr3
 void cDxr3Interface::EnableSPU()
 {
     int ioval = 0;
@@ -330,7 +357,7 @@ void cDxr3Interface::EnableSPU()
 }
 
 // ==================================
-// disable subpicture proeccesing of the dxr3
+//! disable subpicture proeccesing of the dxr3
 void cDxr3Interface::DisableSPU()
 {
     int ioval = 0;
@@ -349,7 +376,7 @@ void cDxr3Interface::DisableSPU()
 }
 
 // ==================================
-// disable audio output of dxr3
+//! disable audio output of dxr3
 void cDxr3Interface::DisableAudio()
 { 
 	m_AudioActive = false;
@@ -365,7 +392,7 @@ void cDxr3Interface::DisableAudio()
 }
 
 // ==================================
-// enable overlay mode of the dxr3
+//! enable overlay mode of the dxr3
 void cDxr3Interface::EnableOverlay()
 {
 	// first we check, if it is enable yet
@@ -419,7 +446,7 @@ void cDxr3Interface::EnableOverlay()
 }
 
 // ==================================
-// disable overlay mode of the dxr3
+//! disable overlay mode of the dxr3
 void cDxr3Interface::DisanleOverlay()
 {
 	// is it allready disabled
@@ -431,7 +458,7 @@ void cDxr3Interface::DisanleOverlay()
 
 // set/get functions
 // ==================================
-// get aspect ratio
+//! get aspect ratio
 uint32_t cDxr3Interface::GetAspectRatio() const
 {
     int ioval = 0;
@@ -450,6 +477,7 @@ uint32_t cDxr3Interface::GetAspectRatio() const
 }
 
 // ==================================
+//! set aspectratio
 void cDxr3Interface::SetAspectRatio(uint32_t ratio) 
 {
     static int requestCounter = 0;
@@ -491,7 +519,7 @@ void cDxr3Interface::SetAspectRatio(uint32_t ratio)
 
 // play functions
 // ==================================
-// set playing mode and start sync engine
+//! set playing mode and start sync engine
 void cDxr3Interface::SetPlayMode()
 {
     em8300_register_t reg;
@@ -698,8 +726,8 @@ void cDxr3Interface::PlayAudioLpcmFrame(uint8_t* pBuf, int length)
 
 // external device access
 // ==================================
-// release devices, so mplayer-plugin, for instance,
-// can access the dxr3
+//! release devices, so mplayer-plugin, for instance,
+//! can access the dxr3
 void cDxr3Interface::ExternalReleaseDevices()
 {
     Lock();
@@ -722,7 +750,7 @@ void cDxr3Interface::ExternalReleaseDevices()
 }
 
 // ==================================
-// reopen devices for using in the dxr3 plugin
+//! reopen devices for using in the dxr3 plugin
 void cDxr3Interface::ExternalReopenDevices()
 {
     Lock();
@@ -763,7 +791,7 @@ void cDxr3Interface::ExternalReopenDevices()
 
 // tools
 // ==================================
-// play blackframe on tv
+//! play blackframe on tv
 void cDxr3Interface::PlayBlackFrame()
 {
     extern char blackframe[];
@@ -822,7 +850,7 @@ cOsdBase* cDxr3Interface::NewOsd(int x, int y)
 #endif
 
 // ==================================
-// uploadroutine for microcode
+//! uploadroutine for microcode
 void cDxr3Interface::UploadMicroCode()
 {
 	if (cDxr3ConfigData::Instance().GetDebug())
@@ -833,6 +861,8 @@ void cDxr3Interface::UploadMicroCode()
     em8300_microcode_t em8300_microcode;    
     const char* MICRO_CODE_FILE = "/usr/share/misc/em8300.uc";
     struct stat s;
+
+	///< try to open it
     int UCODE = open(MICRO_CODE_FILE, O_RDONLY);
     
     if (UCODE <0) 
@@ -847,7 +877,7 @@ void cDxr3Interface::UploadMicroCode()
         exit(1);
     }
 
-	// read microcode
+	///< read microcode
     em8300_microcode.ucode = new char[s.st_size];
     if (em8300_microcode.ucode == NULL) 
 	{
@@ -858,7 +888,7 @@ void cDxr3Interface::UploadMicroCode()
     if (read(UCODE,em8300_microcode.ucode,s.st_size) < 1) 
 	{
 		cLog::Instance() << "Unable to read data from microcode file\n";
-		// free memory to avoid memory leak
+		///< free memory to avoid memory leak
 		delete [] (char*) em8300_microcode.ucode;
 		exit(1);
     }
@@ -867,11 +897,11 @@ void cDxr3Interface::UploadMicroCode()
 
     em8300_microcode.ucode_size = s.st_size;
 
-	// upload it
+	///< upload it
     if( ioctl(m_fdControl, EM8300_IOCTL_INIT, &em8300_microcode) == -1) 
 	{
 		cLog::Instance() << "Microcode upload to failed!! \n";
-		// free memory to avoid memory leak
+		///< free memory to avoid memory leak
 		delete [] (char*) em8300_microcode.ucode;
         exit(1);
     }
@@ -884,12 +914,12 @@ void cDxr3Interface::UploadMicroCode()
 }
 
 // ==================================
-// config and setup device via ioctl calls
+//! config and setup device via ioctl calls
 void cDxr3Interface::ConfigureDevice()
 {
 	uint32_t videomode = 0;
 
-	// set video mode
+	///< set video mode
 	if (cDxr3ConfigData::Instance().GetVideoMode() == PAL)
 	{
 		videomode = EM8300_VIDEOMODE_PAL;
@@ -915,14 +945,14 @@ void cDxr3Interface::ConfigureDevice()
 		}
 	}
 
-	// make ioctl
+	///< make ioctl
     if (ioctl(m_fdControl, EM8300_IOCTL_SET_VIDEOMODE, &videomode) == -1) 
 	{
 		cLog::Instance() << "Unable to set videomode\n";
         exit(1);
     }
 
-	// set audio mode
+	///< set audio mode
 	if (!cDxr3ConfigData::Instance().GetUseDigitalOut())
 	{
 		SetAudioAnalog();
@@ -934,7 +964,7 @@ void cDxr3Interface::ConfigureDevice()
 }
 
 // ==================================
-// reset whole hardware
+//! reset whole hardware
 void cDxr3Interface::Resuscitation() 
 {
     time_t startt = time(&startt);
@@ -961,6 +991,7 @@ void cDxr3Interface::Resuscitation()
 }
 
 // ==================================
+//! pcm resampling funtcion
 void cDxr3Interface::ResampleVolume(short* pcmbuf, int size)
 {
     if (m_volume == 0) 
@@ -1071,7 +1102,7 @@ void cDxr3Interface::SetPalette(unsigned int *pal)
 
 // helper functions for dxr3 main osd screen
 // ==================================
-// reset dxr3 card
+//! reset dxr3 card
 void cDxr3Interface::ResetHardware()
 {
 	Lock();
@@ -1082,7 +1113,7 @@ void cDxr3Interface::ResetHardware()
 
 // set brightness/contrast/saturation
 // ==================================
-// set brightness
+//! set brightness
 void cDxr3Interface::SetBrightness(int value)
 {
 	m_bcs.brightness = value;
@@ -1094,7 +1125,7 @@ void cDxr3Interface::SetBrightness(int value)
 }
 
 // ==================================
-// set contrast
+//! set contrast
 void cDxr3Interface::SetContrast(int value)
 {
 	m_bcs.contrast = value;
@@ -1106,7 +1137,7 @@ void cDxr3Interface::SetContrast(int value)
 }
 
 // ==================================
-// set saturation
+//! set saturation
 void cDxr3Interface::SetSaturation(int value)
 {
 	m_bcs.saturation = value;