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, ChannelGroup *pGroup, const PluginID &id)
	Main thread appends a global or per-group effect. More...
std::shared_ptr< RealtimeEffectState >	ReplaceState (RealtimeEffects::InitializationScope *pScope, ChannelGroup *pGroup, size_t index, const PluginID &id)
	Main thread replaces a global or per-group effect. More...
void	RemoveState (RealtimeEffects::InitializationScope *pScope, ChannelGroup *pGroup, std::shared_ptr< RealtimeEffectState > pState)
	Main thread removes a global or per-group effect. More...
std::optional< size_t >	FindState (ChannelGroup *pGroup, const std::shared_ptr< RealtimeEffectState > &pState) const
	Report the position of a state in the global or a per-group 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, ChannelGroup *pGroup, const PluginID &id)
void	Initialize (RealtimeEffects::InitializationScope &scope, double sampleRate)
	Main thread begins to define a set of groups for playback. More...
void	AddGroup (RealtimeEffects::InitializationScope &scope, const ChannelGroup &group, unsigned chans, float rate)
void	Finalize () noexcept
	Main thread cleans up after playback. More...
void	ProcessStart (bool suspended)
size_t	Process (bool suspended, const ChannelGroup &group, 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 (ChannelGroup &group, const StateVisitor &func)
	Visit the per-project states first, then states for leader if not null. More...
template<typename StateVisitor >
void	VisitGroup (const ChannelGroup &group, const StateVisitor &func)
template<typename StateVisitor >
void	VisitAll (const StateVisitor &func)
	Visit the per-project states first, then all groups from AddGroup. More...

Private Attributes
AudacityProject &	mProject
Latency	mLatency { 0 }
std::atomic< bool >	mSuspended { true }
bool	mActive { false }
std::vector< const ChannelGroup * >	mGroups
	all are non-null More...
std::unordered_map< const ChannelGroup *, 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 48 of file RealtimeEffectManager.h.

Member Typedef Documentation

Latency

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

Definition at line 53 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

AddGroup()

void RealtimeEffectManager::AddGroup ( RealtimeEffects::InitializationScope &  scope, const ChannelGroup &  group, unsigned  chans, float  rate  )

private

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

Precondition

group.IsLeader()

Definition at line 73 of file RealtimeEffectManager.cpp.

{
   assert(group.IsLeader());
   mGroups.push_back(&group);
   mRates.insert({&group, rate});
 
   VisitGroup(group,
      [&](RealtimeEffectState & state, bool) {
         scope.mInstances.push_back(state.AddGroup(group, chans, rate));
      }
   );
}

References RealtimeEffectState::AddGroup(), ChannelGroup::IsLeader(), mGroups, mRates, anonymous_namespace{wxCommandTargets.cpp}::scope, and VisitGroup().

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

Here is the call graph for this function:

Here is the caller graph for this function:

AddState()

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

Main thread appends a global or per-group effect.

Parameters

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

Returns

if null, the given id was not found

Precondition

!pGroup || pGroup->IsLeader()

Postcondition

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

Definition at line 275 of file RealtimeEffectManager.cpp.

{
   assert(!pGroup || pGroup->IsLeader());
   auto &states = FindStates(mProject, pGroup);
   auto pState = MakeNewState(pScope, pGroup, 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,
      pGroup ? pGroup : nullptr
   });
   return pState;
}

References RealtimeEffectManagerMessage::EffectAdded, anonymous_namespace{RealtimeEffectManager.cpp}::FindStates(), ChannelGroup::IsLeader(), 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:

Finalize()

void RealtimeEffectManager::Finalize ( )

privatenoexcept

Main thread cleans up after playback.

Definition at line 88 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
   mGroups.clear();
   mRates.clear();
 
   // No longer active
   mActive = false;
}

References RealtimeEffectState::Finalize(), mActive, mGroups, 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	(	ChannelGroup *	pGroup,
		const std::shared_ptr< RealtimeEffectState > &	pState
	)		const

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

Definition at line 336 of file RealtimeEffectManager.cpp.

{
   auto &states = FindStates(mProject, pGroup);
   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 28 of file RealtimeEffectManager.cpp.

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

References manager, and project.

Referenced by RealtimeEffects::InitializationScope::AddGroup(), AudioIO::AddState(), 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(), and project.

Here is the call graph for this function:

GetSuspended()

bool RealtimeEffectManager::GetSuspended ( ) const

inline

Definition at line 113 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 groups for playback.

Definition at line 53 of file RealtimeEffectManager.cpp.

{
   // (Re)Set processor parameters
   mRates.clear();
   mGroups.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, mGroups, mRates, anonymous_namespace{ClipSegmentTest.cpp}::sampleRate, anonymous_namespace{wxCommandTargets.cpp}::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, ChannelGroup *  pGroup, const PluginID &  id  )

private

Precondition

!pGroup || pGroup->IsLeader()

Definition at line 238 of file RealtimeEffectManager.cpp.

{
   assert(!pGroup || pGroup->IsLeader());
   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 (const auto group : mGroups) {
         // Add all groups to a per-project state, but add only the same
         // group to a state in the per-group list
         if (pGroup && pGroup != group)
            continue;
         auto rate = mRates[group];
         auto pInstance2 =
            state.AddGroup(*group, pScope->mNumPlaybackChannels, rate);
         if (pInstance2 != pInstance)
            pScope->mInstances.push_back(pInstance2);
      }
   }
   return pNewState;
}

References ChannelGroup::IsLeader(), mActive, SharedNonInterfering< RealtimeEffectState >::make_shared(), mGroups, 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 ChannelGroup &  group, float *const *  buffers, float *const *  scratch, float *  dummy, unsigned  nBuffers, size_t  numSamples  )

private

Definition at line 122 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(group,
      [&](RealtimeEffectState &state, bool)
      {
         discardable +=
            state.Process(group, 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 186 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 109 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,
		ChannelGroup *	pGroup,
		std::shared_ptr< RealtimeEffectState >	pState
	)

Main thread removes a global or per-group effect.

Parameters

pScope	if realtime is active but scope is absent, there is no effect
pGroup	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 319 of file RealtimeEffectManager.cpp.

{
   auto &states = FindStates(mProject, pGroup);
 
   // Remove the state from processing (under the lock guard) before finalizing
   states.RemoveState(pState);
   if (mActive)
      pState->Finalize();
   Publish({
      RealtimeEffectManagerMessage::Type::EffectRemoved,
      pGroup ? pGroup : 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,
		ChannelGroup *	pGroup,
		size_t	index,
		const PluginID &	id
	)

Main thread replaces a global or per-group effect.

Parameters

pScope	if realtime is active but scope is absent, there is no effect
pGroup	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 295 of file RealtimeEffectManager.cpp.

{
   assert(!pGroup || pGroup->IsLeader());
   auto &states = FindStates(mProject, pGroup);
   auto pOldState = states.GetStateAt(index);
   if (!pOldState)
      return nullptr;
   auto pNewState = MakeNewState(pScope, pGroup, 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, pGroup
   });
   return pNewState;
}

References RealtimeEffectManagerMessage::EffectReplaced, anonymous_namespace{RealtimeEffectManager.cpp}::FindStates(), ChannelGroup::IsLeader(), 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 123 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 groups from AddGroup.

Groups are visited in unspecified order

Definition at line 201 of file RealtimeEffectManager.h.

   {
      // Call the function for each effect on the master list
      RealtimeEffectList::Get(mProject).Visit(func);
 
      // And all group lists
      for (auto group : mGroups)
         RealtimeEffectList::Get(*group).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 ( ChannelGroup &  group, const StateVisitor &  func  )

inlineprivate

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

Definition at line 178 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 group list
      RealtimeEffectList::Get(group).Visit(func);
   }

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

Referenced by AddGroup(), and Process().

Here is the call graph for this function:

Here is the caller graph for this function:

VisitGroup() [2/2]

template<typename StateVisitor >

void RealtimeEffectManager::VisitGroup ( const ChannelGroup &  group, const StateVisitor &  func  )

inlineprivate

Definition at line 188 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 group list
      RealtimeEffectList::Get(group).Visit(func);
   }

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

Here is the call graph for this function:

Member Data Documentation

mActive

bool RealtimeEffectManager::mActive { false }

private

Definition at line 216 of file RealtimeEffectManager.h.

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

mGroups

std::vector<const ChannelGroup *> RealtimeEffectManager::mGroups

private

all are non-null

Definition at line 220 of file RealtimeEffectManager.h.

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

mLatency

Latency RealtimeEffectManager::mLatency { 0 }

private

Definition at line 212 of file RealtimeEffectManager.h.

Referenced by Finalize(), and Process().

mProject

AudacityProject& RealtimeEffectManager::mProject

private

Definition at line 211 of file RealtimeEffectManager.h.

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

mRates

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

private

Definition at line 222 of file RealtimeEffectManager.h.

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

mSuspended

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

private

Definition at line 214 of file RealtimeEffectManager.h.

---

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

• RealtimeEffectManager.h
• RealtimeEffectManager.cpp