From cd8bb7c24146ce616344228f5150ba5d0ff27d9b Mon Sep 17 00:00:00 2001
From: Amar Takhar <verm@aegisub.org>
Date: Thu, 30 Jul 2009 02:51:42 +0000
Subject: [PATCH] Document PortAudio player, this is broken in doxygen at the
moment not sure why..
Originally committed to SVN as r3323.
---
aegisub/src/audio_player_portaudio.cpp | 60 +++++++++------------
aegisub/src/audio_player_portaudio.h | 73 ++++++++++----------------
2 files changed, 54 insertions(+), 79 deletions(-)
diff --git a/aegisub/src/audio_player_portaudio.cpp b/aegisub/src/audio_player_portaudio.cpp
index bd146e93f..b184a763a 100644
--- a/aegisub/src/audio_player_portaudio.cpp
+++ b/aegisub/src/audio_player_portaudio.cpp
@@ -48,17 +48,16 @@
#include "utils.h"
#include "charset_conv.h"
-// Uncomment to enable debug features.
+/// @define PORTAUDIO_DEBUG Enable debugging?
//#define PORTAUDIO_DEBUG
-/// DOCME
+/// Reference counter
int PortAudioPlayer::pa_refcount = 0;
-/// @brief Constructor
-///
+/// @brief Constructor
PortAudioPlayer::PortAudioPlayer() {
// Initialize portaudio
if (!pa_refcount) {
@@ -82,8 +81,7 @@ PortAudioPlayer::PortAudioPlayer() {
-/// @brief Destructor
-///
+/// @brief Destructor
PortAudioPlayer::~PortAudioPlayer() {
// Deinit portaudio
if (!--pa_refcount) Pa_Terminate();
@@ -91,8 +89,7 @@ PortAudioPlayer::~PortAudioPlayer() {
-/// @brief Open stream
-///
+/// @brief Open stream
void PortAudioPlayer::OpenStream() {
// Open stream
PaStreamParameters pa_output_p;
@@ -131,8 +128,7 @@ void PortAudioPlayer::OpenStream() {
-/// @brief Close stream
-///
+/// @brief Close stream
void PortAudioPlayer::CloseStream() {
try {
Stop(false);
@@ -142,8 +138,7 @@ void PortAudioPlayer::CloseStream() {
/// @brief Called when the callback has finished.
-/// @param userData
-///
+/// @param userData Local data to be handed to the callback.
void PortAudioPlayer::paStreamFinishedCallback(void *userData) {
PortAudioPlayer *player = (PortAudioPlayer *) userData;
@@ -158,11 +153,9 @@ void PortAudioPlayer::paStreamFinishedCallback(void *userData) {
-/// @brief Play
-/// @param start
-/// @param count
-/// @return
-///
+/// @brief Play audio.
+/// @param start Start position.
+/// @param count Frame count
void PortAudioPlayer::Play(int64_t start,int64_t count) {
PaError err;
@@ -199,8 +192,8 @@ void PortAudioPlayer::Play(int64_t start,int64_t count) {
-/// @brief Stop
-/// @param timerToo
+/// @brief Stop Playback
+/// @param timerToo Stop display timer?
///
void PortAudioPlayer::Stop(bool timerToo) {
//wxMutexLocker locker(PAMutex);
@@ -218,14 +211,14 @@ void PortAudioPlayer::Stop(bool timerToo) {
-/// @brief PortAudio callback
-/// @param inputBuffer
-/// @param outputBuffer
-/// @param framesPerBuffer
-/// @param timeInfo
-/// @param statusFlags
-/// @param userData
-/// @return
+/// @brief PortAudio callback
+/// @param inputBuffer Input buffer.
+/// @param outputBuffer Output buffer.
+/// @param framesPerBuffer Frames per buffer.
+/// @param timeInfo PortAudio time information.
+/// @param statusFlags Status flags
+/// @param userData Local data to hand callback
+/// @return Whether to stop playback.
///
int PortAudioPlayer::paCallback(const void *inputBuffer, void *outputBuffer, unsigned long framesPerBuffer, const PaStreamCallbackTimeInfo* timeInfo, PaStreamCallbackFlags statusFlags, void *userData) {
@@ -260,9 +253,8 @@ int PortAudioPlayer::paCallback(const void *inputBuffer, void *outputBuffer, uns
-/// @brief Get current stream position.
-/// @return
-///
+/// @brief Get current stream position.
+/// @return Stream position
int64_t PortAudioPlayer::GetCurrentPosition()
{
@@ -285,9 +277,9 @@ int64_t PortAudioPlayer::GetCurrentPosition()
-/// @brief @param Setting from config file. Return a list of available output devices.
-/// @param favorite
-///
+/// @brief @param Setting from config file.
+/// @param favorite Favorite output device
+/// @return List of available output devices.
wxArrayString PortAudioPlayer::GetOutputDevices(wxString favorite) {
wxArrayString list;
int devices = Pa_GetDeviceCount();
@@ -307,5 +299,3 @@ wxArrayString PortAudioPlayer::GetOutputDevices(wxString favorite) {
}
#endif // WITH_PORTAUDIO
-
-
diff --git a/aegisub/src/audio_player_portaudio.h b/aegisub/src/audio_player_portaudio.h
index dd817a91b..9b1cb67c6 100644
--- a/aegisub/src/audio_player_portaudio.h
+++ b/aegisub/src/audio_player_portaudio.h
@@ -50,43 +50,41 @@ extern "C" {
-/// DOCME
/// @class PortAudioPlayer
-/// @brief DOCME
+/// @brief PortAudio Player
///
-/// DOCME
class PortAudioPlayer : public AudioPlayer {
private:
/// DOCME
static int pa_refcount;
- /// DOCME
+ /// PortAudio Mutex
wxMutex PAMutex;
- /// DOCME
+ /// Is playback being stopped?
volatile bool stopping;
- /// DOCME
+ /// Currently Playing?
bool playing;
- /// DOCME
+ /// Current volume level.
float volume;
- /// DOCME
+ /// Playback position.
volatile int64_t playPos;
- /// DOCME
+ /// Playback start position.
volatile int64_t startPos;
- /// DOCME
+ /// Playback end position.
volatile int64_t endPos;
- /// DOCME
+ /// Audio Stream
void *stream;
- /// DOCME
+ /// PortAudio internal start position.
PaTime paStart;
static int paCallback(
@@ -111,68 +109,55 @@ public:
void Play(int64_t start,int64_t count);
void Stop(bool timerToo=true);
- /// @brief DOCME
- /// @return
- ///
+ /// @brief Whether audio is currently being played.
+ /// @return Status
bool IsPlaying() { return playing; }
- /// @brief DOCME
- /// @return
- ///
+ /// @brief Position audio will be played from.
+ /// @return Start position.
int64_t GetStartPosition() { return startPos; }
- /// @brief DOCME
- /// @return
- ///
+ /// @brief End position playback will stop at.
+ /// @return End position.
int64_t GetEndPosition() { return endPos; }
int64_t GetCurrentPosition();
- /// @brief DOCME
- /// @param pos
- ///
+ /// @brief Set end position of playback
+ /// @param pos End position
void SetEndPosition(int64_t pos) { endPos = pos; }
- /// @brief DOCME
- /// @param pos
- ///
+ /// @brief Set current position of playback.
+ /// @param pos Current position
void SetCurrentPosition(int64_t pos) { playPos = pos; }
- /// @brief DOCME
- /// @param vol
- /// @return
- ///
+ /// @brief Set volume level
+ /// @param vol Volume
void SetVolume(double vol) { volume = vol; }
- /// @brief DOCME
- /// @return
- ///
+ /// @brief Get current volume level
+ /// @return Volume level
double GetVolume() { return volume; }
wxArrayString GetOutputDevices(wxString favorite);
- /// @brief DOCME
- /// @return
+ /// @brief Get Mutex
+ /// @return Current Mutex
///
wxMutex *GetMutex() { return &PAMutex; }
};
-/// DOCME
/// @class PortAudioPlayerFactory
-/// @brief DOCME
-///
-/// DOCME
+/// @brief PortAudio Player Factory
class PortAudioPlayerFactory : public AudioPlayerFactory {
public:
- /// @brief DOCME
- ///
+ /// @brief Create player
+ /// @return New PortAudio Player
AudioPlayer *CreatePlayer() { return new PortAudioPlayer(); }
};
#endif //ifdef WITH_PORTAUDIO
-
-
--
GitLab