From ce1ce688ff7a40cbc1bc26b5216c16d4b6277cc2 Mon Sep 17 00:00:00 2001
From: Paul Licameli <paul.licameli@audacityteam.org>
Date: Sat, 11 Aug 2018 15:03:29 -0400
Subject: [PATCH] Try to clarify real time / track time distinction in
 comments...

... Rather than the confusing old terminology of "warped" time, meaning the
real time after accounting for time track, though that persists mostly in the
names of variables now mostly used only within PlaybackSchedule.

"Track" time refers to a position in a wave track, as indexed by the time
ruler.

"Real" time is indexed by the other scale of numbers drawn in the time track,
which is drawn on the screen with nonuniform spacing (so "warped" in that
sense), but it corresponds to uniform actual time.
---
 src/AudioIO.cpp |  9 +++++----
 src/AudioIO.h   | 10 +++++-----
 2 files changed, 10 insertions(+), 9 deletions(-)

diff --git a/src/AudioIO.cpp b/src/AudioIO.cpp
index 85eec3c0e..71888f017 100644
--- a/src/AudioIO.cpp
+++ b/src/AudioIO.cpp
@@ -1988,7 +1988,7 @@ int AudioIO::StartStream(const TransportTracks &tracks,
    // killing performance.
    //
 
-   // (warped) playback time to produce with each filling of the buffers
+   // real playback time to produce with each filling of the buffers
    // by the Audio thread (except at the end of playback):
    // usually, make fillings fewer and longer for less CPU usage.
    // But for useful scrubbing, we can't run too far ahead without checking
@@ -2101,7 +2101,7 @@ int AudioIO::StartStream(const TransportTracks &tracks,
             {
                mPlaybackBuffers[i] = std::make_unique<RingBuffer>(floatSample, playbackBufferSize);
 
-               // MB: use normal time for the end time, not warped time!
+               // use track time for the end time, not real time!
                WaveTrackConstArray mixTracks;
                mixTracks.push_back(mPlaybackTracks[i]);
 
@@ -3874,7 +3874,8 @@ void AudioIO::FillBuffers()
             bool progress = true;
 #ifdef EXPERIMENTAL_SCRUBBING_SUPPORT
             if (mPlaybackSchedule.Interactive())
-               // scrubbing does not use warped time and length
+               // scrubbing and play-at-speed are not limited by the real time
+               // and length accumulators
                frames = limitSampleBufferSize(frames, mScrubDuration);
             else
 #endif
@@ -4430,7 +4431,7 @@ void AudioIO::FillMidiBuffers()
          break;
       }
    SetHasSolo(hasSolo);
-   // If we compute until mNextEventTime > current audio track time,
+   // If we compute until mNextEventTime > current audio time,
    // we would have a built-in compute-ahead of mAudioOutLatency, and
    // it's probably good to compute MIDI when we compute audio (so when
    // we stop, both stop about the same time).
diff --git a/src/AudioIO.h b/src/AudioIO.h
index 00e75cbc2..c14559482 100644
--- a/src/AudioIO.h
+++ b/src/AudioIO.h
@@ -429,7 +429,7 @@ class AUDACITY_DLL_API AudioIO final {
     */
    static int GetOptimalSupportedSampleRate();
 
-   /** \brief During playback, the (unwarped) track time most recently played
+   /** \brief During playback, the track time most recently played
     *
     * When playing looped, this will start from t0 again,
     * too. So the returned time should be always between
@@ -520,7 +520,7 @@ private:
    void PrepareMidiIterator(bool send = true, double offset = 0);
    bool StartPortMidiStream();
 
-   // Compute nondecreasing time stamps, accounting for pauses, but not the
+   // Compute nondecreasing real time stamps, accounting for pauses, but not the
    // synth latency.
    double UncorrectedMidiEventTime();
 
@@ -648,7 +648,7 @@ private:
    std::vector< std::pair< int, int > > mPendingNotesOff;
 #endif
 
-   /// Time at which the next event should be output, measured in seconds.
+   /// Real 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
@@ -840,7 +840,7 @@ private:
       std::atomic<double> mTime;
 
       /// Accumulated real time (not track position), starting at zero (unlike
-      ///  mTime), and wrapping back to zero each time around looping play.
+      /// mTime), and wrapping back to zero each time around looping play.
       /// Thus, it is the length in real seconds between mT0 and mTime.
       double              mWarpedTime;
 
@@ -939,7 +939,7 @@ private:
       // time track if one is given; result is always nonnegative
       double RealDuration(double trackTime1) const;
 
-      // How much real ("warped") time left?
+      // How much real time left?
       double RealTimeRemaining() const;
 
       // Advance the real time position