AudioGraph::EffectStage Class Reference

Decorates a source with a non-timewarping effect, which may have latency. More...

#include <EffectStage.h>

Inheritance diagram for AudioGraph::EffectStage:

Collaboration diagram for AudioGraph::EffectStage:

Classes
struct	CreateToken

Public Types
using	Factory = std::function< std::shared_ptr< EffectInstance >()>
Public Types inherited from AudioGraph::Source
using	Buffers = AudioGraph::Buffers

Public Member Functions
	EffectStage (CreateToken, bool multi, Source &upstream, Buffers &inBuffers, const Factory &factory, EffectSettings &settings, double sampleRate, std::optional< sampleCount > genLength, const Track &track)
	Don't call directly but use Create() More...
	EffectStage (const EffectStage &)=delete
EffectStage &	operator= (const EffectStage &)=delete
	~EffectStage () override
	Finalizes the instance. More...
bool	AcceptsBuffers (const Buffers &buffers) const override
bool	AcceptsBlockSize (size_t size) const override
	See postcondition of constructor. More...
std::optional< size_t >	Acquire (Buffers &data, size_t bound) override
	Occupy vacant space in Buffers with some data. More...
sampleCount	Remaining () const override
	Result includes any amount Acquired and not yet Released. More...
bool	Release () override
	Caller is done examining last Acquire()d positions. More...
Public Member Functions inherited from AudioGraph::Source
virtual	~Source ()
virtual bool	AcceptsBuffers (const Buffers &buffers) const =0
virtual bool	AcceptsBlockSize (size_t blockSize) const =0
virtual std::optional< size_t >	Acquire (Buffers &data, size_t bound)=0
	Occupy vacant space in Buffers with some data. More...
virtual sampleCount	Remaining () const =0
	Result includes any amount Acquired and not yet Released. More...
virtual bool	Release ()=0
	Caller is done examining last Acquire()d positions. More...
virtual bool	Terminates () const
	Needed only to make some postconditions assertable; defaults true. More...

Static Public Member Functions
static std::unique_ptr< EffectStage >	Create (bool multi, Source &upstream, Buffers &inBuffers, const Factory &factory, EffectSettings &settings, double sampleRate, std::optional< sampleCount > genLength, const Track &track)
	Satisfies postcondition of constructor or returns null. More...

Private Member Functions
sampleCount	DelayRemaining () const
bool	Process (EffectInstance &instance, size_t channel, const Buffers &data, size_t curBlockSize, size_t outBufferOffset) const
	Produce exactly curBlockSize samples in data More...
std::optional< size_t >	FetchProcessAndAdvance (Buffers &data, size_t bound, bool doZeros, size_t outBufferOffset=0)

Private Attributes
Source &	mUpstream
Buffers &	mInBuffers
const std::vector< std::shared_ptr< EffectInstance > >	mInstances
EffectSettings &	mSettings
const double	mSampleRate
const bool	mIsProcessor
sampleCount	mDelayRemaining
size_t	mLastProduced {}
size_t	mLastZeroes {}
bool	mLatencyDone { false }
bool	mCleared { false }

Detailed Description

Decorates a source with a non-timewarping effect, which may have latency.

Definition at line 28 of file EffectStage.h.

Member Typedef Documentation

Factory

using AudioGraph::EffectStage::Factory = std::function<std::shared_ptr<EffectInstance>()>

Definition at line 32 of file EffectStage.h.

Constructor & Destructor Documentation

EffectStage() [1/2]

AudioGraph::EffectStage::EffectStage	(	CreateToken	,
		bool	multi,
		Source &	upstream,
		Buffers &	inBuffers,
		const Factory &	factory,
		EffectSettings &	settings,
		double	sampleRate,
		std::optional< sampleCount >	genLength,
		const Track &	track
	)

Don't call directly but use Create()

Parameters

factory

used only in construction, will be invoked one or more times

Precondition

upstream.AcceptsBlockSize(inBuffers.BlockSize())

Postcondition

AcceptsBlockSize(inBuffers.BlockSize())

ProcessInitialize() succeeded on each instance that was made by factory

Parameters

map	not required after construction

Definition at line 69 of file EffectStage.cpp.

   : mUpstream{ upstream }, mInBuffers{ inBuffers }
   , mInstances{ MakeInstances(factory, settings, sampleRate, track,
      genLength, multi) }
   , mSettings{ settings }, mSampleRate{ sampleRate }
   , mIsProcessor{ !genLength.has_value() }
   , mDelayRemaining{ genLength ? *genLength : sampleCount::max() }
{
   assert(upstream.AcceptsBlockSize(inBuffers.BlockSize()));
   assert(this->AcceptsBlockSize(inBuffers.BlockSize()));
 
   // Establish invariant
   mInBuffers.Rewind();
}

References AudioGraph::Source::AcceptsBlockSize(), AcceptsBlockSize(), AudioGraph::Buffers::BlockSize(), mInBuffers, and AudioGraph::Buffers::Rewind().

Here is the call graph for this function:

EffectStage() [2/2]

AudioGraph::EffectStage::EffectStage ( const EffectStage &  )

delete

~EffectStage()

AudioGraph::EffectStage::~EffectStage ( )

override

Finalizes the instance.

Definition at line 102 of file EffectStage.cpp.

{
   // Allow the instances to cleanup
   for (auto &pInstance : mInstances)
      if (pInstance)
         pInstance->ProcessFinalize();
}

Member Function Documentation

AcceptsBlockSize()

bool AudioGraph::EffectStage::AcceptsBlockSize ( size_t  size ) const

overridevirtual

See postcondition of constructor.

Implements AudioGraph::Source.

Definition at line 115 of file EffectStage.cpp.

{
   // Test the equality of input and output block sizes
   return mInBuffers.BlockSize() == size;
}

References size.

Referenced by EffectStage().

Here is the caller graph for this function:

AcceptsBuffers()

bool AudioGraph::EffectStage::AcceptsBuffers ( const Buffers &  buffers ) const

overridevirtual

Returns

true

Implements AudioGraph::Source.

Definition at line 110 of file EffectStage.cpp.

{
   return true;
}

Acquire()

std::optional< size_t > AudioGraph::EffectStage::Acquire ( Buffers &  data, size_t  bound  )

overridevirtual

Occupy vacant space in Buffers with some data.

May exceeed a single block of production Can assume same buffer is passed each time, while the caller advances it over the previous production, or discards it, or rotates the buffer. May rewind or rotate the buffer.

Returns

number of positions available to read from data or nullopt to fail

Precondition

AcceptsBuffers(data)

AcceptsBlockSize(data.BlockSize())

bound <= data.BlockSize()

data.BlockSize() <= data.Remaining()

Postcondition

result: !result || *result <= bound

result: !result || *result <= data.Remaining()

result: !result || *result <= Remaining()

data.Remaining() > 0

result: !result || bound == 0 || Remaining() == 0 || *result > 0 (progress guarantee)

!Terminates() or Remaining() was not previously defined, or is unchanged

Implements AudioGraph::Source.

Definition at line 122 of file EffectStage.cpp.

{
   assert(AcceptsBuffers(data));
   assert(AcceptsBlockSize(data.BlockSize()));
   // pre, needed for Process() and Discard()
   assert(bound <= std::min(data.BlockSize(), data.Remaining()));
 
   // For each input block of samples, we pass it to the effect along with a
   // variable output location.  This output location is simply a pointer into a
   // much larger buffer.  This reduces the number of calls required to add the
   // samples to the output track.
   //
   // Upon return from the effect, the output samples are "moved to the left" by
   // the number of samples in the current latency setting, effectively removing any
   // delay introduced by the effect.
   //
   // At the same time the total number of delayed samples are gathered and when
   // there is no further input data to process, the loop continues to call the
   // effect with an empty input buffer until the effect has had a chance to
   // return all of the remaining delayed samples.
 
   // Invariant satisfies pre for mUpstream.Acquire() and for Process()
   assert(mInBuffers.BlockSize() <= mInBuffers.Remaining());
 
   size_t curBlockSize = 0;
 
   if (auto oCurBlockSize = FetchProcessAndAdvance(data, bound, false)
      ; !oCurBlockSize
   )
      return {};
   else {
      curBlockSize = *oCurBlockSize;
      if (mIsProcessor && !mLatencyDone) {
         // Come here only in the first call to Acquire()
         // Some effects (like ladspa/lv2 swh plug-ins) don't report latency
         // until at least one block of samples is processed.  Find latency
         // once only for the track and assume it doesn't vary
         auto delay = mDelayRemaining =
            mInstances[0]->GetLatency(mSettings, mSampleRate);
         for (size_t ii = 1, nn = mInstances.size(); ii < nn; ++ii)
            if (mInstances[ii] &&
               mInstances[ii]->GetLatency(mSettings, mSampleRate) != delay)
               // This mismatch is unexpected.  Fail
               return {};
         // Discard all the latency
         while (delay > 0 && curBlockSize > 0) {
            auto discard = limitSampleBufferSize(curBlockSize, delay);
            data.Discard(discard, curBlockSize - discard);
            delay -= discard;
            curBlockSize -= discard;
            if (curBlockSize == 0) {
               if (!(oCurBlockSize = FetchProcessAndAdvance(data, bound, false)
               ))
                  return {};
               else
                  curBlockSize = *oCurBlockSize;
            }
            mLastProduced -= discard;
         }
         if (curBlockSize > 0) {
            assert(delay == 0);
            if (curBlockSize < bound) {
               // Discarded all the latency, while upstream may still be
               // producing.  Try to fill the buffer up to the bound.
               if (!(oCurBlockSize = FetchProcessAndAdvance(
                  data, bound - curBlockSize, false, curBlockSize)
               ))
                  return {};
               else
                  curBlockSize += *oCurBlockSize;
            }
         }
         else while (delay > 0) {
            assert(curBlockSize == 0);
            // Finish one-time delay in case it exceeds entire upstream length
            // Upstream must have been exhausted
            assert(mUpstream.Remaining() == 0);
            // Feed zeroes to the effect
            auto zeroes = limitSampleBufferSize(data.BlockSize(), delay);
            if (!(FetchProcessAndAdvance(data, zeroes, true)))
               return {};
            delay -= zeroes;
            // Debit mDelayRemaining later in Release()
         }
         mLatencyDone = true;
      }
   }
 
   if (mIsProcessor && curBlockSize < bound) {
      // If there is still a short buffer by this point, upstream must have
      // been exhausted
      assert(mUpstream.Remaining() == 0);
 
      // Continue feeding zeroes; this code block will produce as many zeroes
      // at the end as were discarded at the beginning (over one or more visits)
      auto zeroes =
         limitSampleBufferSize(bound - curBlockSize, mDelayRemaining);
      if (!FetchProcessAndAdvance(data, zeroes, true, curBlockSize))
         return {};
      // Debit mDelayRemaining later in Release()
   }
 
   auto result = mLastProduced + mLastZeroes;
   // assert the post
   assert(data.Remaining() > 0);
   assert(result <= bound);
   assert(result <= data.Remaining());
   assert(result <= Remaining());
   assert(bound == 0 || Remaining() == 0 || result > 0);
   return { result };
}

References AudioGraph::Buffers::BlockSize(), AudioGraph::Buffers::Discard(), limitSampleBufferSize(), min(), and AudioGraph::Buffers::Remaining().

Here is the call graph for this function:

Create()

auto AudioGraph::EffectStage::Create ( bool  multi, Source &  upstream, Buffers &  inBuffers, const Factory &  factory, EffectSettings &  settings, double  sampleRate, std::optional< sampleCount >  genLength, const Track &  track  )

static

Satisfies postcondition of constructor or returns null.

Definition at line 87 of file EffectStage.cpp.

{
   try {
      return std::make_unique<EffectStage>(CreateToken{}, multi,
         upstream, inBuffers, factory, settings, sampleRate, genLength, track);
   }
   catch (const std::exception &) {
      return nullptr;
   }
}

References cloud::factory, and settings().

Referenced by PerTrackEffect::ProcessTrack().

Here is the call graph for this function:

Here is the caller graph for this function:

DelayRemaining()

sampleCount AudioGraph::EffectStage::DelayRemaining ( ) const

inlineprivate

Definition at line 72 of file EffectStage.h.

      { return std::max<sampleCount>(0, mDelayRemaining); }

FetchProcessAndAdvance()

std::optional< size_t > AudioGraph::EffectStage::FetchProcessAndAdvance ( Buffers &  data, size_t  bound, bool  doZeros, size_t  outBufferOffset = 0  )

private

Definition at line 234 of file EffectStage.cpp.

{
   std::optional<size_t> oCurBlockSize;
   // Generator always supplies zeroes in
   doZeroes = doZeroes || !mIsProcessor;
   if (!doZeroes)
      oCurBlockSize = mUpstream.Acquire(mInBuffers, bound);
   else {
      if (!mCleared) {
         // Need to do this the first time, only, that we begin to give zeroes
         // to the processor
         mInBuffers.Rewind();
         const auto blockSize = mInBuffers.BlockSize();
         for (size_t ii = 0; ii < mInBuffers.Channels(); ++ii) {
            auto p = &mInBuffers.GetWritePosition(ii);
            std::fill(p, p + blockSize, 0);
         }
         mCleared = true;
      }
      oCurBlockSize = {
         mIsProcessor ? bound : limitSampleBufferSize(bound, mDelayRemaining) };
      if (!mIsProcessor)
         // Do this (ignoring result) so we can correctly Release() upstream
         mUpstream.Acquire(mInBuffers, bound);
   }
   if (!oCurBlockSize)
      return {};
 
   const auto curBlockSize = *oCurBlockSize;
   if (curBlockSize == 0)
      assert(doZeroes || mUpstream.Remaining() == 0); // post of Acquire()
   else {
      // Called only in Acquire()
      // invariant or post of mUpstream.Acquire() satisfies pre of Process()
      // because curBlockSize <= bound <= mInBuffers.blockSize()
      //    == data.BlockSize()
      // and mInBuffers.BlockSize() <= mInBuffers.Remaining() by invariant
      // and data.BlockSize() <= data.Remaining() by pre of Acquire()
      for (size_t ii = 0, nn = mInstances.size(); ii < nn; ++ii) {
         auto &pInstance = mInstances[ii];
         if (!pInstance)
            continue;
         if (!Process(*pInstance, ii, data, curBlockSize, outBufferOffset))
            return {};
      }
 
      if (doZeroes) {
         // Either a generator or doing the tail; will count down delay
         mLastZeroes = limitSampleBufferSize(curBlockSize, DelayRemaining());
         if (!mIsProcessor) {
            // This allows polling the progress meter for a generator
            if (!mUpstream.Release())
               return {};
         }
      }
      else {
         // Will count down the upstream
         mLastProduced += curBlockSize;
         if (!mUpstream.Release())
            return {};
         mInBuffers.Advance(curBlockSize);
         if (mInBuffers.Remaining() < mInBuffers.BlockSize())
            // Maintain invariant minimum availability
            mInBuffers.Rotate();
      }
   }
   return oCurBlockSize;
}

References limitSampleBufferSize().

Here is the call graph for this function:

operator=()

EffectStage & AudioGraph::EffectStage::operator= ( const EffectStage &  )

delete

Process()

bool AudioGraph::EffectStage::Process ( EffectInstance &  instance, size_t  channel, const Buffers &  data, size_t  curBlockSize, size_t  outBufferOffset  ) const

private

Produce exactly curBlockSize samples in data

Precondition

curBlockSize <= data.BlockSize() - outBufferOffset

curBlockSize <= data.Remaining() - outBufferOffset

curBlockSize <= mInBuffers.Remaining()

Returns

success

Definition at line 304 of file EffectStage.cpp.

{
   size_t processed{};
   try {
      const auto positions = mInBuffers.Positions();
      const auto nPositions = mInBuffers.Channels();
      // channel may be nonzero in the case of a plug-in that only reads
      // one channel at a time, so multiple instances are made to mix stereo
      assert(channel <= nPositions);
      std::vector<float *> inPositions(
         positions + channel, positions + nPositions - channel);
      // When the plug-in expects many input channels, replicate the last
      // buffer (assumed to be zero-filled) as dummy input
      inPositions.resize(
         instance.GetAudioInCount() - channel, inPositions.back());
 
      std::vector<float *> advancedOutPositions;
      const auto size = instance.GetAudioOutCount() - channel;
      advancedOutPositions.reserve(size);
 
      auto outPositions = data.Positions();
      // It is assumed that data has at least one dummy buffer last
      auto channels = data.Channels();
      // channel may be nonzero in the case of a plug-in that only writes
      // one channel at a time, so multiple instances are made to mix stereo
      for (size_t ii = channel; ii < channels; ++ii)
         advancedOutPositions.push_back(outPositions[ii] + outBufferOffset);
      // When the plug-in expects many output channels, replicate the last
      // as dummy output
      advancedOutPositions.resize(size, advancedOutPositions.back());
 
      processed = instance.ProcessBlock(mSettings,
         inPositions.data(), advancedOutPositions.data(), curBlockSize);
   }
   catch (const AudacityException &) {
      // PRL: Bug 437:
      // Pass this along to our application-level handler
      throw;
   }
   catch (...) {
      // PRL:
      // Exceptions for other reasons, maybe in third-party code...
      // Continue treating them as we used to, but I wonder if these
      // should now be treated the same way.
      return false;
   }
 
   return (processed == curBlockSize);
}

References AudioGraph::Buffers::Channels(), EffectInstance::GetAudioInCount(), EffectInstance::GetAudioOutCount(), AudioGraph::Buffers::Positions(), EffectInstance::ProcessBlock(), and size.

Here is the call graph for this function:

Release()

bool AudioGraph::EffectStage::Release ( )

overridevirtual

Caller is done examining last Acquire()d positions.

May be called only after at least one successful call to Acquire()

Returns

success

Postcondition

!Terminates() or Remaining() reduced by what was last returned by Acquire()

Implements AudioGraph::Source.

Definition at line 368 of file EffectStage.cpp.

{
   // Progress toward termination (Remaining() == 0),
   // if mLastProduced + mLastZeroes > 0,
   // which is what Acquire() last returned
   mDelayRemaining -= mLastZeroes;
   assert(mDelayRemaining >= 0);
   mLastProduced = mLastZeroes = 0;
   return true;
}

Remaining()

sampleCount AudioGraph::EffectStage::Remaining ( ) const

overridevirtual

Result includes any amount Acquired and not yet Released.

May be undefined before the first successful call to Acquire()

Postcondition

result: result >= 0

Implements AudioGraph::Source.

Definition at line 356 of file EffectStage.cpp.

{
   // Not correct until at least one call to Acquire() so that mDelayRemaining
   // is assigned.
   // mLastProduced will have the up-front latency discarding deducted.
   // mDelayRemaining later decreases to 0 as zeroes are supplied to the
   // processor at the end, compensating for the discarding.
   return mLastProduced
      + (mIsProcessor ? mUpstream.Remaining() : 0)
      + DelayRemaining();
}

Member Data Documentation

mCleared

bool AudioGraph::EffectStage::mCleared { false }

private

Definition at line 100 of file EffectStage.h.

mDelayRemaining

sampleCount AudioGraph::EffectStage::mDelayRemaining

private

Definition at line 96 of file EffectStage.h.

mInBuffers

Buffers& AudioGraph::EffectStage::mInBuffers

private

Invariant

mInBuffers.BlockSize() <= mInBuffers.Remaining()

Definition at line 90 of file EffectStage.h.

Referenced by EffectStage().

mInstances

const std::vector<std::shared_ptr<EffectInstance> > AudioGraph::EffectStage::mInstances

private

Definition at line 91 of file EffectStage.h.

mIsProcessor

const bool AudioGraph::EffectStage::mIsProcessor

private

Definition at line 94 of file EffectStage.h.

mLastProduced

size_t AudioGraph::EffectStage::mLastProduced {}

private

Definition at line 97 of file EffectStage.h.

mLastZeroes

size_t AudioGraph::EffectStage::mLastZeroes {}

private

Definition at line 98 of file EffectStage.h.

mLatencyDone

bool AudioGraph::EffectStage::mLatencyDone { false }

private

Definition at line 99 of file EffectStage.h.

mSampleRate

const double AudioGraph::EffectStage::mSampleRate

private

Definition at line 93 of file EffectStage.h.

mSettings

EffectSettings& AudioGraph::EffectStage::mSettings

private

Definition at line 92 of file EffectStage.h.

mUpstream

Source& AudioGraph::EffectStage::mUpstream

private

Definition at line 88 of file EffectStage.h.

---

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

• EffectStage.h
• EffectStage.cpp