PlaybackPolicy Class Reference

Directs which parts of tracks to fetch for playback. More...

#include <PlaybackSchedule.h>

Inheritance diagram for PlaybackPolicy:

Classes
struct	BufferTimes
	Times are in seconds. More...

Public Types
using	Duration = std::chrono::duration< double >
using	Mixers = std::vector< std::unique_ptr< Mixer > >

Public Member Functions
virtual	~PlaybackPolicy ()=0
virtual void	Initialize (PlaybackSchedule &schedule, double rate)
	Called before starting an audio stream. More...
virtual void	Finalize (PlaybackSchedule &schedule)
	Called after stopping of an audio stream or an unsuccessful start. More...
virtual Mixer::WarpOptions	MixerWarpOptions (PlaybackSchedule &schedule)
	Options to use when constructing mixers for each playback track. More...
virtual BufferTimes	SuggestedBufferTimes (PlaybackSchedule &schedule)
	Provide hints for construction of playback RingBuffer objects. More...
virtual bool	AllowSeek (PlaybackSchedule &schedule)
	Whether repositioning commands are allowed during playback. More...
virtual bool	Done (PlaybackSchedule &schedule, unsigned long outputFrames)
	Returns true if schedule.GetSequenceTime() has reached the end of playback. More...
virtual double	OffsetSequenceTime (PlaybackSchedule &schedule, double offset)
	Called when the play head needs to jump a certain distance. More...
virtual std::chrono::milliseconds	SleepInterval (PlaybackSchedule &schedule)
	How long to wait between calls to AudioIO::SequenceBufferExchange. More...
virtual PlaybackSlice	GetPlaybackSlice (PlaybackSchedule &schedule, size_t available)
	Choose length of one fetch of samples from tracks in a call to AudioIO::FillPlayBuffers. More...
virtual std::pair< double, double >	AdvancedTrackTime (PlaybackSchedule &schedule, double trackTime, size_t nSamples)
	Compute a new point in a track's timeline from an old point and a real duration. More...
virtual bool	RepositionPlayback (PlaybackSchedule &schedule, const Mixers &playbackMixers, size_t frames, size_t available)
	AudioIO::FillPlayBuffers calls this to update its cursors into tracks for changes of position or speed. More...
virtual bool	Looping (const PlaybackSchedule &schedule) const

Protected Attributes
double	mRate = 0

Detailed Description

Directs which parts of tracks to fetch for playback.

A non-default policy object may be created each time playback begins, and if so it is destroyed when playback stops, not reused in the next playback.

Methods of the object are passed a PlaybackSchedule as context.

Definition at line 71 of file PlaybackSchedule.h.

Member Typedef Documentation

Duration

using PlaybackPolicy::Duration = std::chrono::duration<double>

Definition at line 73 of file PlaybackSchedule.h.

Mixers

using PlaybackPolicy::Mixers = std::vector<std::unique_ptr<Mixer> >

Definition at line 139 of file PlaybackSchedule.h.

Constructor & Destructor Documentation

~PlaybackPolicy()

PlaybackPolicy::~PlaybackPolicy ( )

pure virtualdefault

by the main thread

Member Function Documentation

AdvancedTrackTime()

std::pair< double, double > PlaybackPolicy::AdvancedTrackTime ( PlaybackSchedule &  schedule, double  trackTime, size_t  nSamples  )

virtual

Compute a new point in a track's timeline from an old point and a real duration.

Needed because playback might be at non-unit speed.

Called one or more times between GetPlaybackSlice and RepositionPlayback, until the sum of the nSamples values equals the most recent playback slice (including any trailing silence).

Returns

a pair, which indicates a discontinuous jump when its members are not equal, or specially the end of playback when the second member is infinite

Reimplemented in DefaultPlaybackPolicy, anonymous_namespace{ProjectAudioManager.cpp}::CutPreviewPlaybackPolicy, and ScrubbingPlaybackPolicy.

Definition at line 117 of file PlaybackSchedule.cpp.

{
   auto realDuration = nSamples / mRate;
   if (schedule.ReversedTime())
      realDuration *= -1.0;
 
   if (schedule.mEnvelope)
      trackTime =
         schedule.SolveWarpedLength(trackTime, realDuration);
   else
      trackTime += realDuration;
   
   if ( trackTime >= schedule.mT1 )
      return { schedule.mT1, std::numeric_limits<double>::infinity() };
   else
      return { trackTime, trackTime };
}

References PlaybackSchedule::mEnvelope, mRate, PlaybackSchedule::mT1, PlaybackSchedule::ReversedTime(), and PlaybackSchedule::SolveWarpedLength().

Referenced by DefaultPlaybackPolicy::AdvancedTrackTime().

Here is the call graph for this function:

Here is the caller graph for this function:

AllowSeek()

bool PlaybackPolicy::AllowSeek ( PlaybackSchedule &  schedule )

virtual

Whether repositioning commands are allowed during playback.

by the main thread

Reimplemented in ScrubbingPlaybackPolicy.

Definition at line 58 of file PlaybackSchedule.cpp.

{
   return true;
}

Referenced by AudioIoCallback::FillOutputBuffers().

Here is the caller graph for this function:

Done()

bool PlaybackPolicy::Done ( PlaybackSchedule &  schedule, unsigned long  outputFrames  )

virtual

Returns true if schedule.GetSequenceTime() has reached the end of playback.

Parameters

outputFrames

how many playback frames were taken from RingBuffers

Reimplemented in DefaultPlaybackPolicy, anonymous_namespace{ProjectAudioManager.cpp}::CutPreviewPlaybackPolicy, and ScrubbingPlaybackPolicy.

Definition at line 63 of file PlaybackSchedule.cpp.

{
   // Called from portAudio thread, use GetSequenceTime()
   auto diff = schedule.GetSequenceTime() - schedule.mT1;
   if (schedule.ReversedTime())
      diff *= -1;
   return sampleCount(floor(diff * mRate + 0.5)) >= 0 &&
      // Require also that output frames are all consumed from ring buffer
      outputFrames == 0;
}

References PlaybackSchedule::GetSequenceTime(), mRate, PlaybackSchedule::mT1, and PlaybackSchedule::ReversedTime().

Referenced by AudioIoCallback::CallbackCheckCompletion(), and AudioIoCallback::DrainInputBuffers().

Here is the call graph for this function:

Here is the caller graph for this function:

Finalize()

void PlaybackPolicy::Finalize ( PlaybackSchedule &  schedule )

virtual

Called after stopping of an audio stream or an unsuccessful start.

Reimplemented in ScrubbingPlaybackPolicy.

Definition at line 28 of file PlaybackSchedule.cpp.

{}

Referenced by AudioIO::StartStreamCleanup(), and AudioIO::StopStream().

Here is the caller graph for this function:

GetPlaybackSlice()

PlaybackSlice PlaybackPolicy::GetPlaybackSlice ( PlaybackSchedule &  schedule, size_t  available  )

virtual

Choose length of one fetch of samples from tracks in a call to AudioIO::FillPlayBuffers.

Parameters

available

upper bound for the length of the fetch

Reimplemented in DefaultPlaybackPolicy, anonymous_namespace{ProjectAudioManager.cpp}::CutPreviewPlaybackPolicy, and ScrubbingPlaybackPolicy.

Definition at line 91 of file PlaybackSchedule.cpp.

{
   // How many samples to produce for each channel.
   const auto realTimeRemaining = schedule.RealTimeRemaining();
   auto frames = available;
   auto toProduce = frames;
   double deltat = frames / mRate;
 
   if (deltat > realTimeRemaining)
   {
      // Produce some extra silence so that the time queue consumer can
      // satisfy its end condition
      const double extraRealTime = (TimeQueueGrainSize + 1) / mRate;
      auto extra = std::min( extraRealTime, deltat - realTimeRemaining );
      auto realTime = realTimeRemaining + extra;
      frames = realTime * mRate + 0.5;
      toProduce = realTimeRemaining * mRate + 0.5;
      schedule.RealTimeAdvance( realTime );
   }
   else
      schedule.RealTimeAdvance( deltat );
 
   return { available, frames, toProduce };
}

References min(), mRate, PlaybackSchedule::RealTimeAdvance(), PlaybackSchedule::RealTimeRemaining(), and TimeQueueGrainSize.

Here is the call graph for this function:

Initialize()

void PlaybackPolicy::Initialize ( PlaybackSchedule &  schedule, double  rate  )

virtual

Called before starting an audio stream.

Reimplemented in DefaultPlaybackPolicy, anonymous_namespace{ProjectAudioManager.cpp}::CutPreviewPlaybackPolicy, and ScrubbingPlaybackPolicy.

Definition at line 23 of file PlaybackSchedule.cpp.

{
   mRate = rate;
}

References mRate.

Referenced by DefaultPlaybackPolicy::Initialize(), anonymous_namespace{ProjectAudioManager.cpp}::CutPreviewPlaybackPolicy::Initialize(), ScrubbingPlaybackPolicy::Initialize(), and AudioIO::StartStream().

Here is the caller graph for this function:

Looping()

bool PlaybackPolicy::Looping ( const PlaybackSchedule &  schedule ) const

virtual

be removed

Reimplemented in DefaultPlaybackPolicy.

Definition at line 142 of file PlaybackSchedule.cpp.

{
   return false;
}

Referenced by anonymous_namespace{MIDIPlay.h}::MIDIPlay::FillOtherBuffers(), and anonymous_namespace{MIDIPlay.h}::Iterator::OutputEvent().

Here is the caller graph for this function:

MixerWarpOptions()

Mixer::WarpOptions PlaybackPolicy::MixerWarpOptions ( PlaybackSchedule &  schedule )

virtual

Options to use when constructing mixers for each playback track.

Reimplemented in DefaultPlaybackPolicy, and ScrubbingPlaybackPolicy.

Definition at line 30 of file PlaybackSchedule.cpp.

{
   return Mixer::WarpOptions{ schedule.mEnvelope };
}

References PlaybackSchedule::mEnvelope.

Referenced by DefaultPlaybackPolicy::MixerWarpOptions().

Here is the caller graph for this function:

OffsetSequenceTime()

double PlaybackPolicy::OffsetSequenceTime ( PlaybackSchedule &  schedule, double  offset  )

virtual

Called when the play head needs to jump a certain distance.

Parameters

offset

signed amount requested to be added to schedule::GetSequenceTime()

Returns

the new value that will be set as the schedule's track time

Reimplemented in DefaultPlaybackPolicy, and anonymous_namespace{ProjectAudioManager.cpp}::CutPreviewPlaybackPolicy.

Definition at line 75 of file PlaybackSchedule.cpp.

{
   auto time = schedule.GetSequenceTime() + offset;
   time = std::clamp(time, schedule.mT0, schedule.mT1);
   schedule.RealTimeInit( time );
   return time;
}

References PlaybackSchedule::GetSequenceTime(), PlaybackSchedule::mT0, PlaybackSchedule::mT1, and PlaybackSchedule::RealTimeInit().

Referenced by AudioIoCallback::CallbackDoSeek(), and AudioIO::StartStream().

Here is the call graph for this function:

Here is the caller graph for this function:

RepositionPlayback()

bool PlaybackPolicy::RepositionPlayback ( PlaybackSchedule &  schedule, const Mixers &  playbackMixers, size_t  frames, size_t  available  )

virtual

AudioIO::FillPlayBuffers calls this to update its cursors into tracks for changes of position or speed.

Returns

if true, AudioIO::FillPlayBuffers stops producing samples even if space remains

Parameters

frames	how many samples were just now buffered for play
available	how many more samples may be buffered

Reimplemented in DefaultPlaybackPolicy, anonymous_namespace{ProjectAudioManager.cpp}::CutPreviewPlaybackPolicy, and ScrubbingPlaybackPolicy.

Definition at line 136 of file PlaybackSchedule.cpp.

{
   return true;
}

Referenced by DefaultPlaybackPolicy::RepositionPlayback().

Here is the caller graph for this function:

SleepInterval()

std::chrono::milliseconds PlaybackPolicy::SleepInterval ( PlaybackSchedule &  schedule )

virtual

How long to wait between calls to AudioIO::SequenceBufferExchange.

by the main thread

Reimplemented in ScrubbingPlaybackPolicy.

Definition at line 84 of file PlaybackSchedule.cpp.

{
   using namespace std::chrono;
   return 10ms;
}

Referenced by AudioIO::AudioThread().

Here is the caller graph for this function:

SuggestedBufferTimes()

PlaybackPolicy::BufferTimes PlaybackPolicy::SuggestedBufferTimes ( PlaybackSchedule &  schedule )

virtual

Provide hints for construction of playback RingBuffer objects.

Reimplemented in DefaultPlaybackPolicy, and ScrubbingPlaybackPolicy.

Definition at line 36 of file PlaybackSchedule.cpp.

{
   using namespace std::chrono;
#if 1
   // Shorter times than in the default policy so that responses, to changes of
   // loop region or speed slider or other such controls, don't lag too much
   return { 0.05s, 0.05s, 0.25s };
#else
/*
The old values, going very far back.
 
There are old comments in the code about larger batches of work filling the
queue with samples, to reduce CPU usage.  Maybe this doesn't matter with most
modern machines, or maybe there will prove to be a need to choose the numbers
more smartly than these hardcoded values.  Maybe we will need to figure out
adaptiveness of the buffer size by detecting how long the work takes.  Maybe
we can afford even smaller times.
*/
   return { 4.0s, 4.0s, 10.0s };
#endif
}

Referenced by AudioIO::AllocateBuffers().

Here is the caller graph for this function:

Member Data Documentation

mRate

double PlaybackPolicy::mRate = 0

protected

Definition at line 156 of file PlaybackSchedule.h.

Referenced by AdvancedTrackTime(), DefaultPlaybackPolicy::AdvancedTrackTime(), anonymous_namespace{ProjectAudioManager.cpp}::CutPreviewPlaybackPolicy::AdvancedTrackTime(), ScrubbingPlaybackPolicy::AdvancedTrackTime(), Done(), DefaultPlaybackPolicy::Done(), anonymous_namespace{ProjectAudioManager.cpp}::CutPreviewPlaybackPolicy::Done(), GetPlaybackSlice(), DefaultPlaybackPolicy::GetPlaybackSlice(), anonymous_namespace{ProjectAudioManager.cpp}::CutPreviewPlaybackPolicy::GetPlaybackSlice(), ScrubbingPlaybackPolicy::GetPlaybackSlice(), Initialize(), DefaultPlaybackPolicy::RepositionPlayback(), and ScrubbingPlaybackPolicy::RepositionPlayback().

---

The documentation for this class was generated from the following files:

• PlaybackSchedule.h
• PlaybackSchedule.cpp