From 437de150980162d11f8d9c7c0e66bec05ad1bdf0 Mon Sep 17 00:00:00 2001 From: Pokechu22 Date: Wed, 31 May 2017 08:04:59 -0700 Subject: [PATCH] Add more method and field documentation Mostly for MIDI-specific areas, and general AudioIO fields. --- src/AColor.cpp | 6 ++-- src/AColor.h | 4 +++ src/AudioIO.h | 94 +++++++++++++++++++++++++++++++++++--------------- 3 files changed, 74 insertions(+), 30 deletions(-) diff --git a/src/AColor.cpp b/src/AColor.cpp index ec88e9f55..91c982002 100644 --- a/src/AColor.cpp +++ b/src/AColor.cpp @@ -558,8 +558,8 @@ const int AColor_midicolors[16][3] = { {153, 255, 255}, // 13=lt turquoise {153, 153, 255}, // 14=lt blue {204, 102, 255}, // 15=lt blue-violet - {255, 51, 204} -}; // 16=lt red-violet + {255, 51, 204} // 16=lt red-violet +}; void AColor::MIDIChannel(wxDC * dc, int channel /* 1 - 16 */ ) { @@ -571,7 +571,7 @@ void AColor::MIDIChannel(wxDC * dc, int channel /* 1 - 16 */ ) dc->SetBrush(wxBrush(wxColour(colors[0], colors[1], colors[2]), wxSOLID)); } else { - dc->SetPen(wxPen(wxColour(153, 153, 153), 1, wxSOLID));// DONT-THEME Midi, unused. + dc->SetPen(wxPen(wxColour(153, 153, 153), 1, wxSOLID)); dc->SetBrush(wxBrush(wxColour(153, 153, 153), wxSOLID)); } diff --git a/src/AColor.h b/src/AColor.h index c4c6a5a94..fcc0a17c6 100644 --- a/src/AColor.h +++ b/src/AColor.h @@ -86,6 +86,10 @@ class AColor { static void Mute(wxDC * dc, bool on, bool selected, bool soloing); static void Solo(wxDC * dc, bool on, bool selected); + // In all of these, channel is 1-indexed (1 through 16); if out of bounds + // (either due to being explicitly set to 0 or due to an allegro file with + // more than 16 channels) a gray color is returned. + static void MIDIChannel(wxDC * dc, int channel /* 1 - 16 */ ); static void LightMIDIChannel(wxDC * dc, int channel /* 1 - 16 */ ); static void DarkMIDIChannel(wxDC * dc, int channel /* 1 - 16 */ ); diff --git a/src/AudioIO.h b/src/AudioIO.h index b48306fac..c7c517511 100644 --- a/src/AudioIO.h +++ b/src/AudioIO.h @@ -227,6 +227,8 @@ class AUDACITY_DLL_API AudioIO final { public: bool SetHasSolo(bool hasSolo); bool GetHasSolo() { return mHasSolo; } + /// Sets the speed for midi playback, based off of the transcription speed. + /// This takes a percentage, so passing 100 will play at normal speed. void SetMidiPlaySpeed(double s) { mMidiPlaySpeed = s * 0.01; } #endif @@ -494,12 +496,25 @@ private: /** \brief How many sample rates to try */ static const int NumRatesToTry; + /** \brief True if the end time is before the start time */ bool ReversedTime() const { return mT1 < mT0; } + /** \brief Clamps the given time to be between mT0 and mT1 + * + * Returns the bound if the value is out of bounds; does not wrap. + * Returns a time in seconds. + * @param absoluteTime A time in seconds, usually mTime + */ double LimitStreamTime(double absoluteTime) const; + /** \brief Normalizes the given time, clamping it and handling gaps from cut preview. + * + * Clamps the time (unless scrubbing), and skips over the cut section. + * Returns a time in seconds. + * @param absoluteTime A time in seconds, usually mTime + */ double NormalizeStreamTime(double absoluteTime) const; /** \brief Clean up after StartStream if it fails. @@ -511,35 +526,50 @@ private: // MIDI_PLAYBACK: PmStream *mMidiStream; PmError mLastPmError; - long mMidiLatency; // latency value for PortMidi - long mSynthLatency; // latency of MIDI synthesizer - double mMidiPlaySpeed; // a copy of TranscriptionToolBar::mPlaySpeed + /// Latency value for PortMidi + long mMidiLatency; + /// Latency of MIDI synthesizer + long mSynthLatency; + /// A copy of TranscriptionToolBar::mPlaySpeed - a linear speed offset. + /// Should be replaced with use of mTimeTrack + double mMidiPlaySpeed; - // These fields are used to synchronize MIDI with audio - volatile double mAudioCallbackOutputTime; // PortAudio's outTime - volatile long mNumFrames; // includes pauses - volatile long mNumPauseFrames; // how many frames of zeros inserted? - volatile long mPauseTime; // pause in ms if no audio playback - volatile double mMidiLoopOffset; // total of backward jumps + // These fields are used to synchronize MIDI with audio: + + /// PortAudio's outTime + volatile double mAudioCallbackOutputTime; + /// Number of frames output, including pauses + volatile long mNumFrames; + /// How many frames of zeros were output due to pauses? + volatile long mNumPauseFrames; + /// pause in ms if no audio playback + volatile long mPauseTime; + /// total of backward jumps + volatile double mMidiLoopOffset; volatile long mAudioFramesPerBuffer; - volatile bool mMidiPaused; // used by Midi process to record - // that pause has begun. Pause time is accumulated in mPauseTime. - // This variable is shared so that it can be cleared when playback - // begins. + /// Used by Midi process to record that pause has begun. + /// Pause time is accumulated in mPauseTime. This variable is shared + /// so that it can be cleared when playback begins. + volatile bool mMidiPaused; Alg_seq_ptr mSeq; std::unique_ptr mIterator; - Alg_event_ptr mNextEvent; // the next event to play (or null) - double mNextEventTime; // the time of the next event - // (note that this could be a note's time+duration) - NoteTrack *mNextEventTrack; // track of next event - bool mMidiOutputComplete; // true when output reaches mT1 - bool mNextIsNoteOn; // is the next event a note-off? + /// The next event to play (or null) + Alg_event_ptr mNextEvent; + /// Time at which the next event should be output, measured in seconds. + /// Note that this could be a note's time+duration for note offs. + double mNextEventTime; + /// Track of next event + NoteTrack *mNextEventTrack; + /// True when output reaches mT1 + bool mMidiOutputComplete; + /// Is the next event a note-on? + bool mNextIsNoteOn; // int mCnt; - // mMidiStreamActive tells when mMidiStream is open for output + /// mMidiStreamActive tells when mMidiStream is open for output bool mMidiStreamActive; - // when true, mSendMidiState means send only updates, not note-on's, - // used to send state changes that precede the selected notes + /// when true, mSendMidiState means send only updates, not note-on's, + /// used to send state changes that precede the selected notes bool mSendMidiState; NoteTrackArray mMidiPlaybackTracks; #endif @@ -575,20 +605,30 @@ private: volatile int mStreamToken; static int mNextStreamToken; double mFactor; + /// Audio playback rate in samples per second double mRate; - double mT0; // playback starts at offset of mT0 - double mT1; // and ends at offset of mT1 - double mTime; // current time position during playback - double mWarpedTime; // current time after warping, starting at zero (unlike mTime) - double mWarpedLength; // total length after warping + /// Playback starts at offset of mT0, which is measured in seconds. + double mT0; + /// Playback ends at offset of mT1, which is measured in seconds. Note that mT1 may be less than mT0 during scrubbing. + double mT1; + /// Current time position during playback, in seconds. Between mT0 and mT1. + double mTime; + /// Current time after warping, starting at zero (unlike mTime). + /// Length in real seconds between mT0 and mTime. + double mWarpedTime; + /// Total length after warping via a time track. + /// Length in real seconds between mT0 and mT1. Always positive. + double mWarpedLength; double mSeek; double mPlaybackRingBufferSecs; double mCaptureRingBufferSecs; size_t mPlaybackSamplesToCopy; double mMinCaptureSecsToCopy; + /// True if audio playback is paused bool mPaused; PaStream *mPortStreamV19; bool mSoftwarePlaythrough; + /// True if Sound Activated Recording is enabled bool mPauseRec; float mSilenceLevel; unsigned int mNumCaptureChannels;