From ad4a44a22bdc0813c62361df23ac86efae07c259 Mon Sep 17 00:00:00 2001 From: Karl Blomster Date: Wed, 5 Aug 2009 11:21:00 +0000 Subject: [PATCH] Document ffmpegsource_common.cpp/h. Originally committed to SVN as r3363. --- aegisub/src/ffmpegsource_common.cpp | 61 ++++++++++++----------------- aegisub/src/ffmpegsource_common.h | 57 ++++----------------------- 2 files changed, 34 insertions(+), 84 deletions(-) diff --git a/aegisub/src/ffmpegsource_common.cpp b/aegisub/src/ffmpegsource_common.cpp index d860c5519..df4b3454f 100644 --- a/aegisub/src/ffmpegsource_common.cpp +++ b/aegisub/src/ffmpegsource_common.cpp @@ -51,17 +51,14 @@ #include - -/// DOCME wxMutex FFmpegSourceProvider::CleaningInProgress; - -/// @brief Update indexing progress -/// @param Current -/// @param Total -/// @param Private -/// @return +/// @brief Callback function that updates the indexing progress dialog +/// @param Current The current file positition in bytes +/// @param Total The total file size in bytes +/// @param Private A pointer to the progress dialog box to update +/// @return Returns non-0 if indexing is cancelled, 0 otherwise. /// int FFMS_CC FFmpegSourceProvider::UpdateIndexingProgress(int64_t Current, int64_t Total, void *Private) { IndexingProgressDialog *Progress = (IndexingProgressDialog *)Private; @@ -77,12 +74,12 @@ int FFMS_CC FFmpegSourceProvider::UpdateIndexingProgress(int64_t Current, int64_ -/// @brief Do indexing -/// @param Indexer -/// @param CacheName -/// @param Trackmask -/// @param IgnoreDecodeErrors -/// @return +/// @brief Does indexing of a source file +/// @param Indexer A pointer to the indexer object representing the file to be indexed +/// @param CacheName The filename of the output index file +/// @param Trackmask A binary mask of the track numbers to index +/// @param IgnoreDecodeErrors True if audio decoding errors will be tolerated, false otherwise +/// @return Returns the index object on success, NULL otherwise /// FFIndex *FFmpegSourceProvider::DoIndexing(FFIndexer *Indexer, const wxString &CacheName, int Trackmask, bool IgnoreDecodeErrors) { char FFMSErrMsg[1024]; @@ -121,11 +118,10 @@ FFIndex *FFmpegSourceProvider::DoIndexing(FFIndexer *Indexer, const wxString &Ca -/// @brief Find all tracks of the given typo and return their track numbers and respective codec names -/// @param Indexer -/// @param Type -/// @return -/// +/// @brief Finds all tracks of the given type and return their track numbers and respective codec names +/// @param Indexer The indexer object representing the source file +/// @param Type The track type to look for +/// @return Returns a std::map with the track numbers as keys and the codec names as values. std::map FFmpegSourceProvider::GetTracksOfType(FFIndexer *Indexer, FFMS_TrackType Type) { std::map TrackList; int NumTracks = FFMS_GetNumTracksI(Indexer); @@ -143,10 +139,9 @@ std::map FFmpegSourceProvider::GetTracksOfType(FFIndexer *Indexer, /// @brief Ask user for which track he wants to load -/// @param TrackList -/// @param Type -/// @return -/// +/// @param TrackList A std::map with the track numbers as keys and codec names as values +/// @param Type The track type to ask about +/// @return Returns the track number chosen (an integer >= 0) on success, or a negative integer if the user cancelled. int FFmpegSourceProvider::AskForTrackSelection(const std::map &TrackList, FFMS_TrackType Type) { std::vector TrackNumbers; wxArrayString Choices; @@ -173,7 +168,6 @@ int FFmpegSourceProvider::AskForTrackSelection(const std::map &Tra /// @brief Set ffms2 log level according to setting in config.dat -/// void FFmpegSourceProvider::SetLogLevel() { wxString LogLevel = Options.AsText(_T("FFmpegSource log level")); @@ -197,10 +191,9 @@ void FFmpegSourceProvider::SetLogLevel() { -/// @brief method by amz Creates a name for the ffmpegsource2 index and prepares the folder if it doesn't exist -/// @param filename -/// @return -/// +/// @brief Generates an unique name for the ffms2 index file and prepares the cache folder if it doesn't exist +/// @param filename The name of the source file +/// @return Returns the generated filename. wxString FFmpegSourceProvider::GetCacheFilename(const wxString& filename) { // Get the size of the file to be hashed @@ -238,9 +231,8 @@ wxString FFmpegSourceProvider::GetCacheFilename(const wxString& filename) } -/// @brief fire and forget cleaning thread (well, almost) -/// @return -/// +/// @brief Starts the cache cleaner thread +/// @return True on success, false if the thread could not be started. bool FFmpegSourceProvider::CleanCache() { wxLogDebug(_T("FFmpegSourceCacheCleaner: attempting to start thread")); @@ -266,15 +258,14 @@ bool FFmpegSourceProvider::CleanCache() { /// @brief constructor -/// @param par -/// +/// @param par the parent provider FFmpegSourceCacheCleaner::FFmpegSourceCacheCleaner(FFmpegSourceProvider *par) : wxThread(wxTHREAD_DETACHED) { parent = par; } -/// @brief all actual work happens here because I was too lazy to write more functions -/// +/// @brief Cleans the ffms2 index cache folder +/// @return Returns non-0 on error, 0 otherwise. wxThread::ExitCode FFmpegSourceCacheCleaner::Entry() { wxMutexLocker lock(FFmpegSourceProvider::CleaningInProgress); if (!lock.IsOk()) { diff --git a/aegisub/src/ffmpegsource_common.h b/aegisub/src/ffmpegsource_common.h index 58c6cd3bb..0803b8dd0 100644 --- a/aegisub/src/ffmpegsource_common.h +++ b/aegisub/src/ffmpegsource_common.h @@ -42,72 +42,41 @@ #include #include #include "include/aegisub/aegisub.h" - -/// DOCME -#define FFMS_BETA_10_COMPAT #include #include "dialog_progress.h" - -/// DOCME +/// Index all tracks #define FFMS_TRACKMASK_ALL -1 - -/// DOCME +/// Index no tracks #define FFMS_TRACKMASK_NONE 0 - -/// DOCME /// @class FFmpegSourceProvider -/// @brief DOCME -/// -/// DOCME +/// @brief Base class for FFMS2 source providers; contains common functions etc class FFmpegSourceProvider { friend class FFmpegSourceCacheCleaner; public: - - /// DOCME + /// Logging level constants from avutil/log.h enum FFMS_LogLevel { - - /// DOCME + /// nothing printed FFMS_LOG_QUIET = -8, - - /// DOCME FFMS_LOG_PANIC = 0, - - /// DOCME FFMS_LOG_FATAL = 8, - - /// DOCME FFMS_LOG_ERROR = 16, - - /// DOCME FFMS_LOG_WARNING = 24, - - /// DOCME FFMS_LOG_INFO = 32, - - /// DOCME FFMS_LOG_VERBOSE = 40, - - /// DOCME FFMS_LOG_DEBUG = 48, }; - - /// DOCME + /// Indexing progress report dialog struct IndexingProgressDialog { - - /// DOCME volatile bool IndexingCanceled; - - /// DOCME DialogProgress *ProgressDialog; }; - - /// DOCME + /// Mutex preventing two cache cleaner threads from running at the same time static wxMutex CleaningInProgress; bool CleanCache(); @@ -119,30 +88,20 @@ public: wxString GetCacheFilename(const wxString& filename); void SetLogLevel(); - - /// @brief DOCME - /// virtual ~FFmpegSourceProvider() {} }; -/// DOCME /// @class FFmpegSourceCacheCleaner -/// @brief DOCME -/// -/// DOCME +/// @brief Implements index cache cleaning functionality for the FFMS2 providers class FFmpegSourceCacheCleaner : public wxThread { private: - - /// DOCME FFmpegSourceProvider *parent; public: FFmpegSourceCacheCleaner(FFmpegSourceProvider *par); - /// @brief DOCME - /// ~FFmpegSourceCacheCleaner() {}; wxThread::ExitCode Entry(); };