PlaybackSchedule.h

Go to the documentation of this file.

/**********************************************************************
 
 Audacity: A Digital Audio Editor
 
 @file PlaybackSchedule.h
 
 Paul Licameli split from AudioIOBase.h
 
 **********************************************************************/
 
#ifndef __AUDACITY_PLAYBACK_SCHEDULE__
#define __AUDACITY_PLAYBACK_SCHEDULE__
 
#include "MemoryX.h"
#include "MessageBuffer.h"
#include "Mix.h"
#include "Observer.h"
#include <atomic>
#include <chrono>
#include <vector>
 
class AudacityProject;
struct AudioIOStartStreamOptions;
class BoundedEnvelope;
using PRCrossfadeData = std::vector< std::vector < float > >;
 
constexpr size_t TimeQueueGrainSize = 2000;
 
struct RecordingSchedule {
   double mPreRoll{};
   double mLatencyCorrection{}; // negative value usually
   double mDuration{};
   PRCrossfadeData mCrossfadeData;
 
   // These are initialized by the main thread, then updated
   // only by the thread calling TrackBufferExchange:
   double mPosition{};
   bool mLatencyCorrected{};
 
   double TotalCorrection() const { return mLatencyCorrection - mPreRoll; }
   double ToConsume() const;
   double Consumed() const;
   double ToDiscard() const;
};
 
class Mixer;
struct PlaybackSchedule;
 
struct PlaybackSlice {
   const size_t frames; 
   const size_t toProduce; 
 
 
   PlaybackSlice(
      size_t available, size_t frames_, size_t toProduce_)
      : frames{ std::min(available, frames_) }
      , toProduce{ std::min(toProduce_, frames) }
   {}
};
 
 
class AUDIO_IO_API PlaybackPolicy {
public:
   using Duration = std::chrono::duration<double>;
 
 
   virtual ~PlaybackPolicy() = 0;
 
   virtual void Initialize( PlaybackSchedule &schedule, double rate );
 
   virtual void Finalize( PlaybackSchedule &schedule );
 
   virtual Mixer::WarpOptions MixerWarpOptions(PlaybackSchedule &schedule);
 
   struct BufferTimes {
      Duration batchSize; 
      Duration latency; 
      Duration ringBufferDelay; 
   };
   virtual BufferTimes SuggestedBufferTimes(PlaybackSchedule &schedule);
 
 
   virtual bool AllowSeek( PlaybackSchedule &schedule );
 
   virtual bool Done( PlaybackSchedule &schedule,
      unsigned long outputFrames 
   );
 
 
   virtual double OffsetTrackTime( PlaybackSchedule &schedule, double offset );
 
 
   virtual std::chrono::milliseconds
      SleepInterval( PlaybackSchedule &schedule );
 
   virtual PlaybackSlice GetPlaybackSlice( PlaybackSchedule &schedule,
      size_t available 
   );
 
 
   virtual std::pair<double, double>
      AdvancedTrackTime( PlaybackSchedule &schedule,
         double trackTime, size_t nSamples );
 
   using Mixers = std::vector<std::unique_ptr<Mixer>>;
 
 
   virtual bool RepositionPlayback(
      PlaybackSchedule &schedule, const Mixers &playbackMixers,
      size_t frames, 
      size_t available 
   );
 
 
   virtual bool Looping( const PlaybackSchedule &schedule ) const;
 
protected:
   double mRate = 0;
};
 
 
struct AUDIO_IO_API PlaybackSchedule {
   double              mT0;
   double              mT1;
   std::atomic<double> mTime;
 
   double              mWarpedTime;
 
   double              mWarpedLength;
 
   // mWarpedTime and mWarpedLength are irrelevant when scrubbing,
   // else they are used in updating mTime,
   // and when not scrubbing or playing looped, mTime is also used
   // in the test for termination of playback.
 
   // with ComputeWarpedLength, it is now possible the calculate the warped length with 100% accuracy
   // (ignoring accumulated rounding errors during playback) which fixes the 'missing sound at the end' bug
   
   const BoundedEnvelope *mEnvelope;
 
   /*
    Holds track time values corresponding to every nth sample in the
    playback buffers, for the large n == TimeQueueGrainSize.
 
    The "producer" is the Audio thread that fetches samples from tracks and
    fills the playback RingBuffers.  The "consumer" is the high-latency
    PortAudio thread that drains the RingBuffers.  The atomics in the
    RingBuffer implement lock-free synchronization.
 
    This other structure relies on the RingBuffer's synchronization, and adds
    other information to the stream of samples:  which track times they
    correspond to.
 
    The consumer thread uses that information, and also makes known to the main
    thread, what the last consumed track time is.  The main thread can use that
    for other purposes such as refreshing the display of the play head position.
    */
   class AUDIO_IO_API TimeQueue {
   public:
 
 
      void Clear();
      void Resize(size_t size);
 
 
      void Producer( PlaybackSchedule &schedule, PlaybackSlice slice );
 
      double GetLastTime() const;
 
      void SetLastTime(double time);
 
 
      double Consumer( size_t nSamples, double rate );
 
 
 
      void Prime( double time );
 
   private:
      struct Record {
         double timeValue;
         // More fields to come
      };
      using Records = std::vector<Record>;
      Records mData;
      double mLastTime {};
      struct Cursor {
         size_t mIndex {};
         size_t mRemainder {};
      };
      NonInterfering<Cursor> mHead, mTail;
   } mTimeQueue;
 
   PlaybackPolicy &GetPolicy();
   const PlaybackPolicy &GetPolicy() const;
 
   void Init(
      double t0, double t1,
      const AudioIOStartStreamOptions &options,
      const RecordingSchedule *pRecordingSchedule );
 
   double ComputeWarpedLength(double t0, double t1) const;
 
   double SolveWarpedLength(double t0, double length) const;
 
   bool ReversedTime() const
   {
      return mT1 < mT0;
   }
 
   double GetTrackTime() const
   { return mTime.load(std::memory_order_relaxed); }
 
   void SetTrackTime( double time )
   { mTime.store(time, std::memory_order_relaxed); }
 
   void ResetMode() {
      mPolicyValid.store(false, std::memory_order_release);
   }
 
   // Convert time between mT0 and argument to real duration, according to
   // time track if one is given; result is always nonnegative
   double RealDuration(double trackTime1) const;
 
   // Convert time between mT0 and argument to real duration, according to
   // time track if one is given; may be negative
   double RealDurationSigned(double trackTime1) const;
 
   // How much real time left?
   double RealTimeRemaining() const;
 
   // Advance the real time position
   void RealTimeAdvance( double increment );
 
   // Determine starting duration within the first pass -- sometimes not
   // zero
   void RealTimeInit( double trackTime );
   
   void RealTimeRestart();
 
private:
   std::unique_ptr<PlaybackPolicy> mpPlaybackPolicy;
   std::atomic<bool> mPolicyValid{ false };
};
#endif