RealtimeEffectManager Class Reference

#include <RealtimeEffectManager.h>

Inheritance diagram for RealtimeEffectManager:

Collaboration diagram for RealtimeEffectManager:

Classes
struct	AllListsLock

Public Types
using	Latency = std::chrono::microseconds
Public Types inherited from Observer::Publisher< RealtimeEffectManagerMessage >
using	message_type = RealtimeEffectManagerMessage
using	CallbackReturn = std::conditional_t< true, void, bool >
using	Callback = std::function< CallbackReturn(const RealtimeEffectManagerMessage &) >
	Type of functions that can be connected to the Publisher. More...

Public Member Functions
	RealtimeEffectManager (AudacityProject &project)
	~RealtimeEffectManager ()
bool	IsActive () const noexcept
	To be called only from main thread. More...
std::shared_ptr< RealtimeEffectState >	AddState (RealtimeEffects::InitializationScope *pScope, Track *pTrack, const PluginID &id)
	Main thread appends a global or per-track effect. More...
std::shared_ptr< RealtimeEffectState >	ReplaceState (RealtimeEffects::InitializationScope *pScope, Track *pTrack, size_t index, const PluginID &id)
	Main thread replaces a global or per-track effect. More...
void	RemoveState (RealtimeEffects::InitializationScope *pScope, Track *pTrack, std::shared_ptr< RealtimeEffectState > pState)
	Main thread removes a global or per-track effect. More...
std::optional< size_t >	FindState (Track *pTrack, const std::shared_ptr< RealtimeEffectState > &pState) const
	Report the position of a state in the global or a per-track list. More...
bool	GetSuspended () const
void	SetSuspended (bool value)
	To be called only from main thread. More...
Public Member Functions inherited from ClientData::Base
virtual	~Base ()
Public Member Functions inherited from Observer::Publisher< RealtimeEffectManagerMessage >
	Publisher (ExceptionPolicy *pPolicy=nullptr, Alloc a={})
	Constructor supporting type-erased custom allocation/deletion. More...
	Publisher (Publisher &&)=default
Publisher &	operator= (Publisher &&)=default
Subscription	Subscribe (Callback callback)
	Connect a callback to the Publisher; later-connected are called earlier. More...
Subscription	Subscribe (Object &obj, Return(Object::*callback)(Args...))
	Overload of Subscribe takes an object and pointer-to-member-function. More...

Static Public Member Functions
static RealtimeEffectManager &	Get (AudacityProject &project)
static const RealtimeEffectManager &	Get (const AudacityProject &project)

Private Member Functions
std::shared_ptr< RealtimeEffectState >	MakeNewState (RealtimeEffects::InitializationScope *pScope, Track *pLeader, const PluginID &id)
void	Initialize (RealtimeEffects::InitializationScope &scope, double sampleRate)
	Main thread begins to define a set of tracks for playback. More...
void	AddTrack (RealtimeEffects::InitializationScope &scope, const Track &track, unsigned chans, float rate)
void	Finalize () noexcept
	Main thread cleans up after playback. More...
void	ProcessStart (bool suspended)
size_t	Process (bool suspended, const Track &track, float *const *buffers, float *const *scratch, float *dummy, unsigned nBuffers, size_t numSamples)
void	ProcessEnd (bool suspended) noexcept
	RealtimeEffectManager (const RealtimeEffectManager &)=delete
RealtimeEffectManager &	operator= (const RealtimeEffectManager &)=delete
template<typename StateVisitor >
void	VisitGroup (Track &leader, const StateVisitor &func)
	Visit the per-project states first, then states for leader if not null. More...
template<typename StateVisitor >
void	VisitGroup (const Track &leader, const StateVisitor &func)
template<typename StateVisitor >
void	VisitAll (const StateVisitor &func)
	Visit the per-project states first, then all tracks from AddTrack. More...

Private Attributes
AudacityProject &	mProject
Latency	mLatency { 0 }
std::atomic< bool >	mSuspended { true }
bool	mActive { false }
std::vector< const Track * >	mGroupLeaders
	all are non-null More...
std::unordered_map< const Track *, double >	mRates

Additional Inherited Members
Static Public Attributes inherited from Observer::Publisher< RealtimeEffectManagerMessage >
static constexpr bool	notifies_all
Protected Member Functions inherited from Observer::Publisher< RealtimeEffectManagerMessage >
CallbackReturn	Publish (const RealtimeEffectManagerMessage &message)
	Send a message to connected callbacks. More...

Detailed Description

Definition at line 47 of file RealtimeEffectManager.h.

Member Typedef Documentation

Latency

using RealtimeEffectManager::Latency = std::chrono::microseconds

Definition at line 52 of file RealtimeEffectManager.h.

Constructor & Destructor Documentation

RealtimeEffectManager() [1/2]

RealtimeEffectManager::RealtimeEffectManager

(

AudacityProject &

project

)

Definition at line 39 of file RealtimeEffectManager.cpp.

   : mProject(project)
{
}

~RealtimeEffectManager()

RealtimeEffectManager::~RealtimeEffectManager

(

)

Definition at line 44 of file RealtimeEffectManager.cpp.

{
}

RealtimeEffectManager() [2/2]

RealtimeEffectManager::RealtimeEffectManager ( const RealtimeEffectManager &  )

privatedelete

Member Function Documentation

AddState()

std::shared_ptr< RealtimeEffectState > RealtimeEffectManager::AddState	(	RealtimeEffects::InitializationScope *	pScope,
		Track *	pTrack,
		const PluginID &	id
	)

Main thread appends a global or per-track effect.

Parameters

pScope	if realtime is active but scope is absent, there is no effect
pTrack	if null, then state is added to the global list
id	identifies the effect

Returns

if null, the given id was not found

Postcondition

result: !result || result->GetEffect() != nullptr

Definition at line 278 of file RealtimeEffectManager.cpp.

{
   auto [pLeader, states] = FindStates(mProject, pTrack);
   auto pState = MakeNewState(pScope, pTrack, id);
   if (!pState)
      return nullptr;
 
   // Only now add the completed state to the list, under a lock guard
   if (!states.AddState(pState))
      return nullptr;
   Publish({
      RealtimeEffectManagerMessage::Type::EffectAdded,
      pLeader ? pLeader->shared_from_this() : nullptr
   });
   return pState;
}

References RealtimeEffectManagerMessage::EffectAdded, anonymous_namespace{RealtimeEffectManager.cpp}::FindStates(), MakeNewState(), mProject, and Observer::Publisher< RealtimeEffectManagerMessage >::Publish().

Referenced by AudioIO::AddState().

Here is the call graph for this function:

Here is the caller graph for this function:

AddTrack()

void RealtimeEffectManager::AddTrack ( RealtimeEffects::InitializationScope &  scope, const Track &  track, unsigned  chans, float  rate  )

private

Main thread adds one track (passing the first of one or more channels), still before playback

Definition at line 73 of file RealtimeEffectManager.cpp.

{
   auto leader = *track.GetOwner()->FindLeader(&track);
   // This should never return a null
   wxASSERT(leader);
   mGroupLeaders.push_back(leader);
   mRates.insert({leader, rate});
 
   VisitGroup(*leader,
      [&](RealtimeEffectState & state, bool) {
         scope.mInstances.push_back(state.AddTrack(*leader, chans, rate));
      }
   );
}

References RealtimeEffectState::AddTrack(), Track::GetOwner(), mGroupLeaders, mRates, scope, and VisitGroup().

Referenced by RealtimeEffects::InitializationScope::AddTrack().

Here is the call graph for this function:

Here is the caller graph for this function:

Finalize()

void RealtimeEffectManager::Finalize ( )

privatenoexcept

Main thread cleans up after playback.

Definition at line 90 of file RealtimeEffectManager.cpp.

{
   // Reenter suspended state
   SetSuspended(true);
 
   // Assume it is now safe to clean up
   mLatency = std::chrono::microseconds(0);
 
   VisitAll([](RealtimeEffectState &state, bool){ state.Finalize(); });
 
   // Reset processor parameters
   mGroupLeaders.clear();
   mRates.clear();
 
   // No longer active
   mActive = false;
}

References RealtimeEffectState::Finalize(), mActive, mGroupLeaders, mLatency, mRates, SetSuspended(), and VisitAll().

Referenced by RealtimeEffects::InitializationScope::~InitializationScope().

Here is the call graph for this function:

Here is the caller graph for this function:

FindState()

std::optional< size_t > RealtimeEffectManager::FindState	(	Track *	pTrack,
		const std::shared_ptr< RealtimeEffectState > &	pState
	)		const

Report the position of a state in the global or a per-track list.

Definition at line 337 of file RealtimeEffectManager.cpp.

{
   auto [_, states] = FindStates(mProject, pTrack);
   return states.FindState(pState);
}

References _, anonymous_namespace{RealtimeEffectManager.cpp}::FindStates(), and mProject.

Here is the call graph for this function:

Get() [1/2]

RealtimeEffectManager & RealtimeEffectManager::Get ( AudacityProject &  project )

static

Definition at line 29 of file RealtimeEffectManager.cpp.

{
   return project.AttachedObjects::Get<RealtimeEffectManager&>(manager);
}

References manager.

Referenced by AudioIO::AddState(), RealtimeEffects::InitializationScope::AddTrack(), Get(), RealtimeEffects::InitializationScope::InitializationScope(), anonymous_namespace{PluginMenus.cpp}::IsRealtimeNotActiveFlag(), anonymous_namespace{RealtimeEffectPanel.cpp}::RealtimeEffectControl::OnChangeButtonClicked(), RealtimeEffects::ProcessingScope::Process(), RealtimeEffects::ProcessingScope::ProcessingScope(), AudioIO::RemoveState(), AudioIO::ReplaceState(), AudioIO::SetPaused(), TrackPanel::TrackPanel(), RealtimeEffects::InitializationScope::~InitializationScope(), and RealtimeEffects::ProcessingScope::~ProcessingScope().

Here is the caller graph for this function:

Get() [2/2]

const RealtimeEffectManager & RealtimeEffectManager::Get ( const AudacityProject &  project )

static

Definition at line 34 of file RealtimeEffectManager.cpp.

{
   return Get(const_cast<AudacityProject &>(project));
}

References Get().

Here is the call graph for this function:

GetSuspended()

bool RealtimeEffectManager::GetSuspended ( ) const

inline

Definition at line 107 of file RealtimeEffectManager.h.

      { return mSuspended.load(std::memory_order_relaxed); }

Initialize()

void RealtimeEffectManager::Initialize ( RealtimeEffects::InitializationScope &  scope, double  sampleRate  )

private

Main thread begins to define a set of tracks for playback.

Definition at line 53 of file RealtimeEffectManager.cpp.

{
   // (Re)Set processor parameters
   mRates.clear();
   mGroupLeaders.clear();
 
   // RealtimeAdd/RemoveEffect() needs to know when we're active so it can
   // initialize newly added effects
   mActive = true;
 
   // Tell each state to get ready for action
   VisitAll([&scope, sampleRate](RealtimeEffectState &state, bool) {
      scope.mInstances.push_back(state.Initialize(sampleRate));
   });
 
   // Leave suspended state
   SetSuspended(false);
}

References RealtimeEffectState::Initialize(), mActive, mGroupLeaders, mRates, scope, SetSuspended(), and VisitAll().

Referenced by RealtimeEffects::InitializationScope::InitializationScope().

Here is the call graph for this function:

Here is the caller graph for this function:

IsActive()

bool RealtimeEffectManager::IsActive ( ) const

noexcept

To be called only from main thread.

Definition at line 48 of file RealtimeEffectManager.cpp.

{
   return mActive;
}

References mActive.

Referenced by anonymous_namespace{PluginMenus.cpp}::IsRealtimeNotActiveFlag().

Here is the caller graph for this function:

MakeNewState()

std::shared_ptr< RealtimeEffectState > RealtimeEffectManager::MakeNewState ( RealtimeEffects::InitializationScope *  pScope, Track *  pLeader, const PluginID &  id  )

private

Definition at line 239 of file RealtimeEffectManager.cpp.

{
   if (!pScope && mActive)
      return nullptr;
   auto pNewState = RealtimeEffectState::make_shared(id);
   auto &state = *pNewState;
   if (pScope && mActive) {
      // Adding a state while playback is in-flight
      auto pInstance = state.Initialize(pScope->mSampleRate);
      pScope->mInstances.push_back(pInstance);
      for (auto &leader : mGroupLeaders) {
         // Add all tracks to a per-project state, but add only the same track
         // to a state in the per-track list
         if (pLeader && pLeader != leader)
            continue;
         auto rate = mRates[leader];
         auto pInstance2 =
            state.AddTrack(*leader, pScope->mNumPlaybackChannels, rate);
         if (pInstance2 != pInstance)
            pScope->mInstances.push_back(pInstance2);
      }
   }
   return pNewState;
}

References mActive, SharedNonInterfering< RealtimeEffectState >::make_shared(), mGroupLeaders, RealtimeEffects::InitializationScope::mInstances, RealtimeEffects::InitializationScope::mNumPlaybackChannels, mRates, and RealtimeEffects::InitializationScope::mSampleRate.

Referenced by AddState(), and ReplaceState().

Here is the call graph for this function:

Here is the caller graph for this function:

operator=()

RealtimeEffectManager & RealtimeEffectManager::operator= ( const RealtimeEffectManager &  )

privatedelete

Process()

size_t RealtimeEffectManager::Process ( bool  suspended, const Track &  track, float *const *  buffers, float *const *  scratch, float *  dummy, unsigned  nBuffers, size_t  numSamples  )

private

Definition at line 124 of file RealtimeEffectManager.cpp.

{
   // Can be suspended because of the audio stream being paused or because effects
   // have been suspended, so allow the samples to pass as-is.
   if (suspended)
      return 0;
 
   // Remember when we started so we can calculate the amount of latency we
   // are introducing
   auto start = std::chrono::steady_clock::now();
 
   // Allocate the in and out buffer arrays
   const auto ibuf =
      static_cast<float **>(alloca(nBuffers * sizeof(float *)));
   const auto obuf =
      static_cast<float **>(alloca(nBuffers * sizeof(float *)));
 
   // And populate the input with the buffers we've been given while allocating
   // NEW output buffers
   for (unsigned int i = 0; i < nBuffers; i++) {
      ibuf[i] = buffers[i];
      obuf[i] = scratch[i];
   }
 
   // Now call each effect in the chain while swapping buffer pointers to feed the
   // output of one effect as the input to the next effect
   // Tracks how many processors were called
   size_t called = 0;
   size_t discardable = 0;
   VisitGroup(track,
      [&](RealtimeEffectState &state, bool)
      {
         discardable +=
            state.Process(track, nBuffers, ibuf, obuf, dummy, numSamples);
         for (auto i = 0; i < nBuffers; ++i)
            std::swap(ibuf[i], obuf[i]);
         called++;
      }
   );
 
   // Once we're done, we might wind up with the last effect storing its results
   // in the temporary buffers.  If that's the case, we need to copy it over to
   // the caller's buffers.  This happens when the number of effects processed
   // is odd.
   if (called & 1)
      for (unsigned int i = 0; i < nBuffers; i++)
         memcpy(buffers[i], ibuf[i], numSamples * sizeof(float));
 
   // Remember the latency
   auto end = std::chrono::steady_clock::now();
   mLatency = std::chrono::duration_cast<std::chrono::microseconds>(end - start);
 
   //
   // This is wrong...needs to handle tails
   //
   return discardable;
}

References PackedArray::end(), mLatency, RealtimeEffectState::Process(), anonymous_namespace{NoteTrack.cpp}::swap(), and VisitGroup().

Referenced by RealtimeEffects::ProcessingScope::Process().

Here is the call graph for this function:

Here is the caller graph for this function:

ProcessEnd()

void RealtimeEffectManager::ProcessEnd ( bool  suspended )

privatenoexcept

Definition at line 187 of file RealtimeEffectManager.cpp.

{
   // Can be suspended because of the audio stream being paused or because effects
   // have been suspended.
   VisitAll([suspended](RealtimeEffectState &state, bool){
      state.ProcessEnd();
   });
}

References RealtimeEffectState::ProcessEnd().

Referenced by RealtimeEffects::ProcessingScope::~ProcessingScope().

Here is the call graph for this function:

Here is the caller graph for this function:

ProcessStart()

void RealtimeEffectManager::ProcessStart ( bool  suspended )

private

Definition at line 111 of file RealtimeEffectManager.cpp.

{
   // Can be suspended because of the audio stream being paused or because effects
   // have been suspended.
   VisitAll([suspended](RealtimeEffectState &state, bool listIsActive){
      state.ProcessStart(!suspended && listIsActive);
   });
}

References RealtimeEffectState::ProcessStart(), and VisitAll().

Referenced by RealtimeEffects::ProcessingScope::ProcessingScope().

Here is the call graph for this function:

Here is the caller graph for this function:

RemoveState()

void RealtimeEffectManager::RemoveState	(	RealtimeEffects::InitializationScope *	pScope,
		Track *	pTrack,
		std::shared_ptr< RealtimeEffectState >	pState
	)

Main thread removes a global or per-track effect.

Parameters

pScope	if realtime is active but scope is absent, there is no effect
pTrack	if null, then state is added to the global list
state	the state to be removed

No effect if realtime is active but scope is not supplied

Definition at line 321 of file RealtimeEffectManager.cpp.

{
   auto [pLeader, states] = FindStates(mProject, pTrack);
 
   // Remove the state from processing (under the lock guard) before finalizing
   states.RemoveState(pState);
   if (mActive)
      pState->Finalize();
   Publish({
      RealtimeEffectManagerMessage::Type::EffectRemoved,
      pLeader ? pLeader->shared_from_this() : nullptr
   });
}

References RealtimeEffectManagerMessage::EffectRemoved, anonymous_namespace{RealtimeEffectManager.cpp}::FindStates(), mActive, mProject, and Observer::Publisher< RealtimeEffectManagerMessage >::Publish().

Referenced by AudioIO::RemoveState().

Here is the call graph for this function:

Here is the caller graph for this function:

ReplaceState()

std::shared_ptr< RealtimeEffectState > RealtimeEffectManager::ReplaceState	(	RealtimeEffects::InitializationScope *	pScope,
		Track *	pTrack,
		size_t	index,
		const PluginID &	id
	)

Main thread replaces a global or per-track effect.

Parameters

pScope	if realtime is active but scope is absent, there is no effect
pTrack	if null, then state is added to the global list
index	position in the list to replace; no effect if out of range
id	identifies the effect

Returns

if null, the given id was not found and the old state remains

Postcondition

result: !result || result->GetEffect() != nullptr

Definition at line 297 of file RealtimeEffectManager.cpp.

{
   auto [pLeader, states] = FindStates(mProject, pTrack);
   auto pOldState = states.GetStateAt(index);
   if (!pOldState)
      return nullptr;
   auto pNewState = MakeNewState(pScope, pTrack, id);
   if (!pNewState)
      return nullptr;
 
   // Only now swap the completed state into the list, under a lock guard
   if (!states.ReplaceState(index, pNewState))
      return nullptr;
   if (mActive)
      pOldState->Finalize();
   Publish({
      RealtimeEffectManagerMessage::Type::EffectReplaced,
      pLeader ? pLeader->shared_from_this() : nullptr
   });
   return pNewState;
}

References RealtimeEffectManagerMessage::EffectReplaced, anonymous_namespace{RealtimeEffectManager.cpp}::FindStates(), mActive, MakeNewState(), mProject, and Observer::Publisher< RealtimeEffectManagerMessage >::Publish().

Referenced by AudioIO::ReplaceState().

Here is the call graph for this function:

Here is the caller graph for this function:

SetSuspended()

void RealtimeEffectManager::SetSuspended ( bool  value )

inline

To be called only from main thread.

Each time a processing scope starts in the audio thread, suspension state is tested, and plug-in instances may need to do things in response to the transitions. Playback of samples may continue but with effects switched off in suspended state.

Definition at line 117 of file RealtimeEffectManager.h.

      { mSuspended.store(value, std::memory_order_relaxed); }

Referenced by Finalize(), and Initialize().

Here is the caller graph for this function:

VisitAll()

template<typename StateVisitor >

void RealtimeEffectManager::VisitAll ( const StateVisitor &  func )

inlineprivate

Visit the per-project states first, then all tracks from AddTrack.

Tracks are visited in unspecified order

Definition at line 186 of file RealtimeEffectManager.h.

   {
      // Call the function for each effect on the master list
      RealtimeEffectList::Get(mProject).Visit(func);
 
      // And all track lists
      for (auto leader : mGroupLeaders)
         RealtimeEffectList::Get(*leader).Visit(func);
   }

References RealtimeEffectList::Get(), and RealtimeEffectList::Visit().

Referenced by Finalize(), Initialize(), and ProcessStart().

Here is the call graph for this function:

Here is the caller graph for this function:

VisitGroup() [1/2]

template<typename StateVisitor >

void RealtimeEffectManager::VisitGroup ( const Track &  leader, const StateVisitor &  func  )

inlineprivate

Definition at line 174 of file RealtimeEffectManager.h.

   {
      // Call the function for each effect on the master list
      RealtimeEffectList::Get(mProject).Visit(func);
 
      // Call the function for each effect on the track list
      RealtimeEffectList::Get(leader).Visit(func);
   }

References RealtimeEffectList::Get(), and RealtimeEffectList::Visit().

Here is the call graph for this function:

VisitGroup() [2/2]

template<typename StateVisitor >

void RealtimeEffectManager::VisitGroup ( Track &  leader, const StateVisitor &  func  )

inlineprivate

Visit the per-project states first, then states for leader if not null.

Definition at line 164 of file RealtimeEffectManager.h.

   {
      // Call the function for each effect on the master list
      RealtimeEffectList::Get(mProject).Visit(func);
 
      // Call the function for each effect on the track list
      RealtimeEffectList::Get(leader).Visit(func);
   }

References RealtimeEffectList::Get(), and RealtimeEffectList::Visit().

Referenced by AddTrack(), and Process().

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

mActive

bool RealtimeEffectManager::mActive { false }

private

Definition at line 201 of file RealtimeEffectManager.h.

Referenced by Finalize(), Initialize(), IsActive(), MakeNewState(), RemoveState(), and ReplaceState().

mGroupLeaders

std::vector<const Track *> RealtimeEffectManager::mGroupLeaders

private

all are non-null

Definition at line 205 of file RealtimeEffectManager.h.

Referenced by AddTrack(), RealtimeEffectManager::AllListsLock::AllListsLock(), Finalize(), Initialize(), and MakeNewState().

mLatency

Latency RealtimeEffectManager::mLatency { 0 }

private

Definition at line 197 of file RealtimeEffectManager.h.

Referenced by Finalize(), and Process().

mProject

AudacityProject& RealtimeEffectManager::mProject

private

Definition at line 196 of file RealtimeEffectManager.h.

Referenced by AddState(), RealtimeEffectManager::AllListsLock::AllListsLock(), FindState(), RemoveState(), and ReplaceState().

mRates

std::unordered_map<const Track *, double> RealtimeEffectManager::mRates

private

Definition at line 207 of file RealtimeEffectManager.h.

Referenced by AddTrack(), Finalize(), Initialize(), and MakeNewState().

mSuspended

std::atomic<bool> RealtimeEffectManager::mSuspended { true }

private

Definition at line 199 of file RealtimeEffectManager.h.

---

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

• RealtimeEffectManager.h
• RealtimeEffectManager.cpp