EffectStage Class Reference

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

#include <EffectStage.h>

Inheritance diagram for EffectStage:

Collaboration diagram for 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, int channel, int nInputChannels, Source &upstream, Buffers &inBuffers, const Factory &factory, EffectSettings &settings, double sampleRate, std::optional< sampleCount > genLength)
	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 (int channel, int nInputChannels, Source &upstream, Buffers &inBuffers, const Factory &factory, EffectSettings &settings, double sampleRate, std::optional< sampleCount > genLength)
	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 26 of file EffectStage.h.

Member Typedef Documentation

Factory

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

Definition at line 30 of file EffectStage.h.

Constructor & Destructor Documentation

EffectStage() [1/2]

EffectStage::EffectStage	(	CreateToken	,
		int	channel,
		int	nInputChannels,
		Source &	upstream,
		Buffers &	inBuffers,
		const Factory &	factory,
		EffectSettings &	settings,
		double	sampleRate,
		std::optional< sampleCount >	genLength
	)

Don't call directly but use Create()

Parameters

channel	selects one channel if non-negative; else, all channels
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

Precondition

channel < sequence.NChannels()

Definition at line 59 of file EffectStage.cpp.

    : mUpstream { upstream }
    , mInBuffers { inBuffers }
    , mInstances { MakeInstances(
         factory, settings, sampleRate, genLength, channel, nInputChannels) }
    , 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 AcceptsBlockSize(), AudioGraph::Buffers::BlockSize(), mInBuffers, and AudioGraph::Buffers::Rewind().

Here is the call graph for this function:

EffectStage() [2/2]

EffectStage::EffectStage ( const EffectStage &  )

delete

~EffectStage()

EffectStage::~EffectStage ( )

override

Finalizes the instance.

Definition at line 94 of file EffectStage.cpp.

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

References mInstances.

Member Function Documentation

AcceptsBlockSize()

bool EffectStage::AcceptsBlockSize ( size_t  size ) const

overridevirtual

See postcondition of constructor.

Implements AudioGraph::Source.

Definition at line 107 of file EffectStage.cpp.

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

References AudioGraph::Buffers::BlockSize(), mInBuffers, and size.

Referenced by Acquire(), and EffectStage().

Here is the call graph for this function:

Here is the caller graph for this function:

AcceptsBuffers()

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

overridevirtual

Returns

true

Implements AudioGraph::Source.

Definition at line 102 of file EffectStage.cpp.

{
   return true;
}

Referenced by Acquire().

Here is the caller graph for this function:

Acquire()

std::optional< size_t > 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 113 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 AcceptsBlockSize(), AcceptsBuffers(), AudioGraph::Buffers::BlockSize(), AudioGraph::Buffers::Discard(), FetchProcessAndAdvance(), limitSampleBufferSize(), mDelayRemaining, min(), mInBuffers, mInstances, mIsProcessor, mLastProduced, mLastZeroes, mLatencyDone, mSampleRate, mSettings, mUpstream, AudioGraph::Buffers::Remaining(), and Remaining().

Here is the call graph for this function:

Create()

auto EffectStage::Create ( int  channel, int  nInputChannels, Source &  upstream, Buffers &  inBuffers, const Factory &  factory, EffectSettings &  settings, double  sampleRate, std::optional< sampleCount >  genLength  )

static

Satisfies postcondition of constructor or returns null.

Definition at line 79 of file EffectStage.cpp.

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

References factory, anonymous_namespace{ClipSegmentTest.cpp}::sampleRate, and settings().

Referenced by PerTrackEffect::ProcessTrack(), and Mixer::RegisterEffectStage().

Here is the call graph for this function:

Here is the caller graph for this function:

DelayRemaining()

sampleCount EffectStage::DelayRemaining ( ) const

inlineprivate

Definition at line 72 of file EffectStage.h.

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

Referenced by FetchProcessAndAdvance(), and Remaining().

Here is the caller graph for this function:

FetchProcessAndAdvance()

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

private

Definition at line 225 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 AudioGraph::Buffers::Advance(), AudioGraph::Buffers::BlockSize(), AudioGraph::Buffers::Channels(), DelayRemaining(), AudioGraph::Buffers::GetWritePosition(), limitSampleBufferSize(), mCleared, mDelayRemaining, mInBuffers, mInstances, mIsProcessor, mLastProduced, mLastZeroes, mUpstream, Process(), AudioGraph::Buffers::Remaining(), AudioGraph::Buffers::Rewind(), and AudioGraph::Buffers::Rotate().

Referenced by Acquire().

Here is the call graph for this function:

Here is the caller graph for this function:

operator=()

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

delete

Process()

bool 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 295 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(), mInBuffers, mSettings, AudioGraph::Buffers::Positions(), EffectInstance::ProcessBlock(), and size.

Referenced by FetchProcessAndAdvance().

Here is the call graph for this function:

Here is the caller graph for this function:

Release()

bool 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 359 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;
}

References mDelayRemaining, mLastProduced, and mLastZeroes.

Remaining()

sampleCount 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 347 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();
}

References DelayRemaining(), mIsProcessor, mLastProduced, and mUpstream.

Referenced by Acquire().

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

mCleared

bool EffectStage::mCleared { false }

private

Definition at line 100 of file EffectStage.h.

Referenced by FetchProcessAndAdvance().

mDelayRemaining

sampleCount EffectStage::mDelayRemaining

private

Definition at line 96 of file EffectStage.h.

Referenced by Acquire(), FetchProcessAndAdvance(), and Release().

mInBuffers

Buffers& EffectStage::mInBuffers

private

Invariant

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

Definition at line 90 of file EffectStage.h.

Referenced by AcceptsBlockSize(), Acquire(), EffectStage(), FetchProcessAndAdvance(), and Process().

mInstances

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

private

Definition at line 91 of file EffectStage.h.

Referenced by Acquire(), FetchProcessAndAdvance(), and ~EffectStage().

mIsProcessor

const bool EffectStage::mIsProcessor

private

Definition at line 94 of file EffectStage.h.

Referenced by Acquire(), FetchProcessAndAdvance(), and Remaining().

mLastProduced

size_t EffectStage::mLastProduced {}

private

Definition at line 97 of file EffectStage.h.

Referenced by Acquire(), FetchProcessAndAdvance(), Release(), and Remaining().

mLastZeroes

size_t EffectStage::mLastZeroes {}

private

Definition at line 98 of file EffectStage.h.

Referenced by Acquire(), FetchProcessAndAdvance(), and Release().

mLatencyDone

bool EffectStage::mLatencyDone { false }

private

Definition at line 99 of file EffectStage.h.

Referenced by Acquire().

mSampleRate

const double EffectStage::mSampleRate

private

Definition at line 93 of file EffectStage.h.

Referenced by Acquire().

mSettings

EffectSettings& EffectStage::mSettings

private

Definition at line 92 of file EffectStage.h.

Referenced by Acquire(), and Process().

mUpstream

Source& EffectStage::mUpstream

private

Definition at line 88 of file EffectStage.h.

Referenced by Acquire(), FetchProcessAndAdvance(), and Remaining().

---

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

• EffectStage.h
• EffectStage.cpp