A type of AudioProcessor which plays back a graph of other AudioProcessors. More...

#include <juce_AudioProcessorGraph.h>

Inheritance diagram for AudioProcessorGraph:

Classes
class	AudioGraphIOProcessor
	A special type of AudioProcessor that can live inside an AudioProcessorGraph in order to use the audio that comes into and out of the graph itself. More...

struct	Connection
	Represents a connection between two channels of two nodes in an AudioProcessorGraph. More...

class	Node
	Represents one of the nodes, or processors, in an AudioProcessorGraph. More...

class	NodeAndChannel
	Represents an input or output channel of a node in an AudioProcessorGraph. More...

struct	NodeID
	Each node in the graph has a UID of this type. More...

Public Types
enum	{ midiChannelIndex = 0x1000 }
	A special index that represents the midi channel of a node. More...

enum class	UpdateKind { sync , async , none }
	Indicates how the graph should be updated after a change. More...

Public Types inherited from AudioProcessor
enum	ProcessingPrecision { singlePrecision , doublePrecision }

enum class	Realtime { no , yes }

enum	WrapperType { wrapperType_Undefined = 0 , wrapperType_VST , wrapperType_VST3 , wrapperType_AudioUnit , wrapperType_AudioUnitv3 , wrapperType_AAX , wrapperType_Standalone , wrapperType_Unity , wrapperType_LV2 }
	Flags to indicate the type of plugin context in which a processor is being used. More...

using	ChangeDetails = AudioProcessorListener::ChangeDetails

Public Member Functions
	AudioProcessorGraph ()
	Creates an empty graph.

	~AudioProcessorGraph () override
	Destructor.

void	clear (UpdateKind=UpdateKind::sync)
	Deletes all nodes and connections from this graph.

const ReferenceCountedArray< Node > &	getNodes () const noexcept
	Returns the array of nodes in the graph.

int	getNumNodes () const noexcept
	Returns the number of nodes in the graph.

Node::Ptr	getNode (int index) const noexcept
	Returns a pointer to one of the nodes in the graph.

Node *	getNodeForId (NodeID) const
	Searches the graph for a node with the given ID number and returns it.

Node::Ptr	addNode (std::unique_ptr< AudioProcessor > newProcessor, std::optional< NodeID > nodeId=std::nullopt, UpdateKind=UpdateKind::sync)
	Adds a node to the graph.

Node::Ptr	removeNode (NodeID, UpdateKind=UpdateKind::sync)
	Deletes a node within the graph which has the specified ID.

Node::Ptr	removeNode (Node *, UpdateKind=UpdateKind::sync)
	Deletes a node within the graph.

std::vector< Connection >	getConnections () const
	Returns the list of connections in the graph.

bool	isConnected (const Connection &) const noexcept
	Returns true if the given connection exists.

bool	isConnected (NodeID possibleSourceNodeID, NodeID possibleDestNodeID) const noexcept
	Returns true if there is a direct connection between any of the channels of two specified nodes.

bool	isAnInputTo (const Node &source, const Node &destination) const noexcept
	Does a recursive check to see if there's a direct or indirect series of connections between these two nodes.

bool	isAnInputTo (NodeID source, NodeID destination) const noexcept
	Does a recursive check to see if there's a direct or indirect series of connections between these two nodes.

bool	canConnect (const Connection &) const
	Returns true if it would be legal to connect the specified points.

bool	addConnection (const Connection &, UpdateKind=UpdateKind::sync)
	Attempts to connect two specified channels of two nodes.

bool	removeConnection (const Connection &, UpdateKind=UpdateKind::sync)
	Deletes the given connection.

bool	disconnectNode (NodeID, UpdateKind=UpdateKind::sync)
	Removes all connections from the specified node.

bool	isConnectionLegal (const Connection &) const
	Returns true if the given connection's channel numbers map on to valid channels at each end.

bool	removeIllegalConnections (UpdateKind=UpdateKind::sync)
	Performs a sanity checks of all the connections.

void	rebuild ()
	Rebuilds the graph if necessary.

const String	getName () const override
	Returns the name of this processor.

void	prepareToPlay (double, int) override
	Called before playback starts, to let the processor prepare itself.

void	releaseResources () override
	Called after playback has stopped, to let the object free up any resources it no longer needs.

void	processBlock (AudioBuffer< float > &, MidiBuffer &) override
	Renders the next block.

void	processBlock (AudioBuffer< double > &, MidiBuffer &) override
	Renders the next block.

bool	supportsDoublePrecisionProcessing () const override
	Returns true if the Audio processor supports double precision floating point processing.

void	reset () override
	A plugin can override this to be told when it should reset any playing voices.

void	setNonRealtime (bool) noexcept override
	Called by the host to tell this processor whether it's being used in a non-realtime capacity for offline rendering or bouncing.

double	getTailLengthSeconds () const override
	Returns the length of the processor's tail, in seconds.

bool	acceptsMidi () const override
	Returns true if the processor wants MIDI messages.

bool	producesMidi () const override
	Returns true if the processor produces MIDI messages.

bool	hasEditor () const override
	Your processor subclass must override this and return true if it can create an editor component.

AudioProcessorEditor *	createEditor () override
	Creates the processor's GUI.

int	getNumPrograms () override
	Returns the number of preset programs the processor supports.

int	getCurrentProgram () override
	Returns the number of the currently active program.

void	setCurrentProgram (int) override
	Called by the host to change the current program.

const String	getProgramName (int) override
	Must return the name of a given program.

void	changeProgramName (int, const String &) override
	Called by the host to rename a program.

void	getStateInformation (juce::MemoryBlock &) override
	The host will call this method when it wants to save the processor's internal state.

void	setStateInformation (const void *data, int sizeInBytes) override
	This must restore the processor's state from a block of data previously created using getStateInformation().

Public Member Functions inherited from AudioProcessor
virtual	~AudioProcessor ()
	Destructor.

virtual StringArray	getAlternateDisplayNames () const
	Returns a list of alternative names to use for this processor.

virtual void	memoryWarningReceived ()
	Called by the host to indicate that you should reduce your memory footprint.

virtual void	processBlockBypassed (AudioBuffer< float > &buffer, MidiBuffer &midiMessages)
	Renders the next block when the processor is being bypassed.

virtual void	processBlockBypassed (AudioBuffer< double > &buffer, MidiBuffer &midiMessages)
	Renders the next block when the processor is being bypassed.

int	getBusCount (bool isInput) const noexcept
	Returns the number of buses on the input or output side.

Bus *	getBus (bool isInput, int busIndex) noexcept
	Returns the audio bus with a given index and direction.

const Bus *	getBus (bool isInput, int busIndex) const noexcept
	Returns the audio bus with a given index and direction.

virtual bool	canAddBus (bool isInput) const
	Callback to query if a bus can currently be added.

virtual bool	canRemoveBus (bool isInput) const
	Callback to query if the last bus can currently be removed.

bool	addBus (bool isInput)
	Dynamically request an additional bus.

bool	removeBus (bool isInput)
	Dynamically remove the latest added bus.

bool	setBusesLayout (const BusesLayout &)
	Set the channel layouts of this audio processor.

bool	setBusesLayoutWithoutEnabling (const BusesLayout &)
	Set the channel layouts of this audio processor without changing the enablement state of the buses.

BusesLayout	getBusesLayout () const
	Provides the current channel layouts of this audio processor.

AudioChannelSet	getChannelLayoutOfBus (bool isInput, int busIndex) const noexcept
	Provides the channel layout of the bus with a given index and direction.

bool	setChannelLayoutOfBus (bool isInput, int busIndex, const AudioChannelSet &layout)
	Set the channel layout of the bus with a given index and direction.

int	getChannelCountOfBus (bool isInput, int busIndex) const noexcept
	Provides the number of channels of the bus with a given index and direction.

bool	enableAllBuses ()
	Enables all buses.

bool	disableNonMainBuses ()
	Disables all non-main buses (aux and sidechains).

int	getChannelIndexInProcessBlockBuffer (bool isInput, int busIndex, int channelIndex) const noexcept
	Returns the position of a bus's channels within the processBlock buffer.

int	getOffsetInBusBufferForAbsoluteChannelIndex (bool isInput, int absoluteChannelIndex, int &busIndex) const noexcept
	Returns the offset in a bus's buffer from an absolute channel index.

template<typename FloatType >
AudioBuffer< FloatType >	getBusBuffer (AudioBuffer< FloatType > &processBlockBuffer, bool isInput, int busIndex) const
	Returns an AudioBuffer containing a set of channel pointers for a specific bus.

bool	checkBusesLayoutSupported (const BusesLayout &) const
	Returns true if the Audio processor is likely to support a given layout.

ProcessingPrecision	getProcessingPrecision () const noexcept
	Returns the precision-mode of the processor.

bool	isUsingDoublePrecision () const noexcept
	Returns true if the current precision is set to doublePrecision.

void	setProcessingPrecision (ProcessingPrecision newPrecision) noexcept
	Changes the processing precision of the receiver.

AudioPlayHead *	getPlayHead () const noexcept
	Returns the current AudioPlayHead object that should be used to find out the state and position of the playhead.

int	getTotalNumInputChannels () const noexcept
	Returns the total number of input channels.

int	getTotalNumOutputChannels () const noexcept
	Returns the total number of output channels.

int	getMainBusNumInputChannels () const noexcept
	Returns the number of input channels on the main bus.

int	getMainBusNumOutputChannels () const noexcept
	Returns the number of output channels on the main bus.

template<size_t numLayouts>
BusesLayout	getNextBestLayoutInLayoutList (const BusesLayout &layouts, const short(&channelLayoutList)[numLayouts][2])
	Returns the next best layout which is contained in a channel layout map.

double	getSampleRate () const noexcept
	Returns the current sample rate.

int	getBlockSize () const noexcept
	Returns the current typical block size that is being used.

int	getLatencySamples () const noexcept
	This returns the number of samples delay that the processor imposes on the audio passing through it.

void	setLatencySamples (int newLatency)
	Your processor subclass should call this to set the number of samples delay that it introduces.

virtual bool	supportsMPE () const
	Returns true if the processor supports MPE.

virtual bool	isMidiEffect () const
	Returns true if this is a MIDI effect plug-in and does no audio processing.

const CriticalSection &	getCallbackLock () const noexcept
	This returns a critical section that will automatically be locked while the host is calling the processBlock() method.

void	suspendProcessing (bool shouldBeSuspended)
	Enables and disables the processing callback.

bool	isSuspended () const noexcept
	Returns true if processing is currently suspended.

virtual AudioProcessorParameter *	getBypassParameter () const
	Returns the parameter that controls the AudioProcessor's bypass state.

bool	isNonRealtime () const noexcept
	Returns true if the processor is being run in an offline mode for rendering.

Realtime	isRealtime () const noexcept
	Returns no if the processor is being run in an offline mode for rendering.

AudioProcessorEditor *	getActiveEditor () const noexcept
	Returns the active editor, if there is one.

AudioProcessorEditor *	createEditorIfNeeded ()
	Returns the active editor, or if there isn't one, it will create one.

void	updateHostDisplay (const ChangeDetails &details=ChangeDetails::getDefaultFlags())
	The processor can call this when something (apart from a parameter value) has changed.

void	addParameter (AudioProcessorParameter *)
	Adds a parameter to the AudioProcessor.

void	addParameterGroup (std::unique_ptr< AudioProcessorParameterGroup >)
	Adds a group of parameters to the AudioProcessor.

const AudioProcessorParameterGroup &	getParameterTree () const
	Returns the group of parameters managed by this AudioProcessor.

void	setParameterTree (AudioProcessorParameterGroup &&newTree)
	Sets the group of parameters managed by this AudioProcessor.

virtual void	refreshParameterList ()
	A processor should implement this method so that the host can ask it to rebuild its parameter tree.

const Array< AudioProcessorParameter * > &	getParameters () const
	Returns a flat list of the parameters in the current tree.

virtual void	getCurrentProgramStateInformation (juce::MemoryBlock &destData)
	The host will call this method if it wants to save the state of just the processor's current program.

virtual void	setCurrentProgramStateInformation (const void *data, int sizeInBytes)
	The host will call this method if it wants to restore the state of just the processor's current program.

virtual void	numChannelsChanged ()
	This method is called when the total number of input or output channels is changed.

virtual void	numBusesChanged ()
	This method is called when the number of buses is changed.

virtual void	processorLayoutsChanged ()
	This method is called when the layout of the audio processor changes.

virtual void	addListener (AudioProcessorListener *newListener)
	Adds a listener that will be called when an aspect of this processor changes.

virtual void	removeListener (AudioProcessorListener *listenerToRemove)
	Removes a previously added listener.

virtual void	setPlayHead (AudioPlayHead *newPlayHead)
	Tells the processor to use this playhead object.

void	setPlayConfigDetails (int numIns, int numOuts, double sampleRate, int blockSize)
	This is called by the processor to specify its details before being played.

void	setRateAndBufferSizeDetails (double sampleRate, int blockSize) noexcept
	This is called by the processor to specify its details before being played.

virtual void	audioWorkgroupContextChanged (const AudioWorkgroup &workgroup)
	This is called by the host when the thread workgroup context has changed.

virtual AAXClientExtensions &	getAAXClientExtensions ()
	Returns a reference to an object that implements AAX specific information regarding this AudioProcessor.

virtual VST2ClientExtensions *	getVST2ClientExtensions ()
	Returns a non-owning pointer to an object that implements VST2 specific information regarding this AudioProcessor.

virtual VST3ClientExtensions *	getVST3ClientExtensions ()
	Returns a non-owning pointer to an object that implements VST3 specific information regarding this AudioProcessor.

virtual CurveData	getResponseCurve (CurveData::Type) const

void	editorBeingDeleted (AudioProcessorEditor *) noexcept
	Not for public use - this is called before deleting an editor component.

virtual void	updateTrackProperties (const TrackProperties &properties)
	Informs the AudioProcessor that track properties such as the track's name or colour has been changed.

Public Member Functions inherited from ChangeBroadcaster
	ChangeBroadcaster () noexcept
	Creates an ChangeBroadcaster.

virtual	~ChangeBroadcaster ()
	Destructor.

void	addChangeListener (ChangeListener *listener)
	Registers a listener to receive change callbacks from this broadcaster.

void	removeChangeListener (ChangeListener *listener)
	Unregisters a listener from the list.

void	removeAllChangeListeners ()
	Removes all listeners from the list.

void	sendChangeMessage ()
	Causes an asynchronous change message to be sent to all the registered listeners.

void	sendSynchronousChangeMessage ()
	Sends a synchronous change message to all the registered listeners.

void	dispatchPendingMessages ()
	If a change message has been sent but not yet dispatched, this will call sendSynchronousChangeMessage() to make the callback immediately.

Additional Inherited Members
Static Public Member Functions inherited from AudioProcessor
static bool	containsLayout (const BusesLayout &layouts, const std::initializer_list< const short[2]> &channelLayoutList)
	Returns true if the channel layout map contains a certain layout.

template<size_t numLayouts>
static bool	containsLayout (const BusesLayout &layouts, const short(&channelLayoutList)[numLayouts][2])

static int	getDefaultNumParameterSteps () noexcept
	Returns the default number of steps for a parameter.

static const char *	getWrapperTypeDescription (AudioProcessor::WrapperType) noexcept
	Returns a textual description of a WrapperType value.

static void	copyXmlToBinary (const XmlElement &xml, juce::MemoryBlock &destData)
	Helper function that just converts an xml element into a binary blob.

static std::unique_ptr< XmlElement >	getXmlFromBinary (const void *data, int sizeInBytes)
	Retrieves an XML element that was stored as binary with the copyXmlToBinary() method.

static void JUCE_CALLTYPE	setTypeOfNextNewPlugin (WrapperType)

Public Attributes inherited from AudioProcessor
const WrapperType	wrapperType
	When loaded by a plugin wrapper, this flag will be set to indicate the type of plugin within which the processor is running.

Protected Member Functions inherited from AudioProcessor
	AudioProcessor ()
	Constructor.

	AudioProcessor (const BusesProperties &ioLayouts)
	Constructor for multi-bus AudioProcessors.

	AudioProcessor (const std::initializer_list< const short[2]> &channelLayoutList)
	Constructor for AudioProcessors which use layout maps If your AudioProcessor uses layout maps then use this constructor.

virtual bool	isBusesLayoutSupported (const BusesLayout &) const
	Callback to query if the AudioProcessor supports a specific layout.

virtual bool	canApplyBusesLayout (const BusesLayout &layouts) const
	Callback to check if a certain bus layout can now be applied.

virtual bool	applyBusLayouts (const BusesLayout &layouts)
	This method will be called when a new bus layout needs to be applied.

virtual bool	canApplyBusCountChange (bool isInput, bool isAddingBuses, BusProperties &outNewBusProperties)
	Callback to query if adding/removing buses currently possible.

void	sendParamChangeMessageToListeners (int parameterIndex, float newValue)

Protected Attributes inherited from AudioProcessor
std::atomic< AudioPlayHead * >	playHead { nullptr }

Detailed Description

A type of AudioProcessor which plays back a graph of other AudioProcessors.

Use one of these objects if you want to wire-up a set of AudioProcessors and play back the result.

Processors can be added to the graph as "nodes" using addNode(), and once added, you can connect any of their input or output channels to other nodes using addConnection().

To play back a graph through an audio device, you might want to use an AudioProcessorPlayer object.

Member Enumeration Documentation

◆ anonymous enum

anonymous enum

A special index that represents the midi channel of a node.

This is used as a channel index value if you want to refer to the midi input or output instead of an audio channel.

Enumerator
midiChannelIndex

◆ UpdateKind

enum class AudioProcessorGraph::UpdateKind

strong

Indicates how the graph should be updated after a change.

If you need to make lots of changes to a graph (e.g. lots of separate calls to addNode, addConnection etc.) you can avoid rebuilding the graph on each change by using the async update kind.

Enumerator

sync

Graph should be rebuilt immediately after modification.

async

Graph rebuild should be delayed.

If you make several changes to the graph inside the same call stack, these changes will be applied in one go.

none

Graph should not be rebuilt automatically.

Use rebuild() to trigger a graph rebuild.

Constructor & Destructor Documentation

◆ AudioProcessorGraph()

AudioProcessorGraph::AudioProcessorGraph ( )

Creates an empty graph.

◆ ~AudioProcessorGraph()

AudioProcessorGraph::~AudioProcessorGraph ( )

override

Destructor.

Any processor objects that have been added to the graph will also be deleted.

Member Function Documentation

◆ clear()

void AudioProcessorGraph::clear ( UpdateKind = UpdateKind::sync )

Deletes all nodes and connections from this graph.

Any processor objects in the graph will be deleted.

◆ getNodes()

const ReferenceCountedArray< Node > & AudioProcessorGraph::getNodes ( ) const

noexcept

Returns the array of nodes in the graph.

◆ getNumNodes()

int AudioProcessorGraph::getNumNodes ( ) const

noexcept

Returns the number of nodes in the graph.

◆ getNode()

Node::Ptr AudioProcessorGraph::getNode ( int index ) const

noexcept

Returns a pointer to one of the nodes in the graph.

This will return nullptr if the index is out of range.

See also: getNodeForId

◆ getNodeForId()

Node * AudioProcessorGraph::getNodeForId ( NodeID ) const

Searches the graph for a node with the given ID number and returns it.

If no such node was found, this returns nullptr.

See also: getNode

◆ addNode()

Node::Ptr AudioProcessorGraph::addNode	(	std::unique_ptr< AudioProcessor >	newProcessor,
		std::optional< NodeID >	nodeId = std::nullopt,
		UpdateKind	= UpdateKind::sync )

Adds a node to the graph.

This creates a new node in the graph, for the specified processor. Once you have added a processor to the graph, the graph owns it and will delete it later when it is no longer needed.

The optional nodeId parameter lets you specify a unique ID to use for the node. If the value is already in use, this method will fail and return an empty node.

If this succeeds, it returns a pointer to the newly-created node.

◆ removeNode() [1/2]

Node::Ptr AudioProcessorGraph::removeNode	(	NodeID	,
		UpdateKind	= UpdateKind::sync )

Deletes a node within the graph which has the specified ID.

This will also delete any connections that are attached to this node.

◆ removeNode() [2/2]

Node::Ptr AudioProcessorGraph::removeNode	(	Node *	,
		UpdateKind	= UpdateKind::sync )

Deletes a node within the graph.

This will also delete any connections that are attached to this node.

◆ getConnections()

std::vector< Connection > AudioProcessorGraph::getConnections ( ) const

Returns the list of connections in the graph.

◆ isConnected() [1/2]

bool AudioProcessorGraph::isConnected ( const Connection & ) const

noexcept

Returns true if the given connection exists.

◆ isConnected() [2/2]

bool AudioProcessorGraph::isConnected	(	NodeID	possibleSourceNodeID,
		NodeID	possibleDestNodeID ) const

noexcept

Returns true if there is a direct connection between any of the channels of two specified nodes.

◆ isAnInputTo() [1/2]

bool AudioProcessorGraph::isAnInputTo	(	const Node &	source,
		const Node &	destination ) const

noexcept

Does a recursive check to see if there's a direct or indirect series of connections between these two nodes.

◆ isAnInputTo() [2/2]

bool AudioProcessorGraph::isAnInputTo	(	NodeID	source,
		NodeID	destination ) const

noexcept

Does a recursive check to see if there's a direct or indirect series of connections between these two nodes.

◆ canConnect()

bool AudioProcessorGraph::canConnect ( const Connection & ) const

Returns true if it would be legal to connect the specified points.

◆ addConnection()

bool AudioProcessorGraph::addConnection	(	const Connection &	,
		UpdateKind	= UpdateKind::sync )

Attempts to connect two specified channels of two nodes.

If this isn't allowed (e.g. because you're trying to connect a midi channel to an audio one or other such nonsense), then it'll return false.

◆ removeConnection()

bool AudioProcessorGraph::removeConnection	(	const Connection &	,
		UpdateKind	= UpdateKind::sync )

Deletes the given connection.

◆ disconnectNode()

bool AudioProcessorGraph::disconnectNode	(	NodeID	,
		UpdateKind	= UpdateKind::sync )

Removes all connections from the specified node.

◆ isConnectionLegal()

bool AudioProcessorGraph::isConnectionLegal ( const Connection & ) const

Returns true if the given connection's channel numbers map on to valid channels at each end.

Even if a connection is valid when created, its status could change if a node changes its channel config.

◆ removeIllegalConnections()

bool AudioProcessorGraph::removeIllegalConnections ( UpdateKind = UpdateKind::sync )

Performs a sanity checks of all the connections.

This might be useful if some of the processors are doing things like changing their channel counts, which could render some connections obsolete.

◆ rebuild()

void AudioProcessorGraph::rebuild ( )

Rebuilds the graph if necessary.

This function will only ever rebuild the graph on the main thread. If this function is called from another thread, the rebuild request will be dispatched asynchronously to the main thread.

◆ getName()

const String AudioProcessorGraph::getName ( ) const

overridevirtual

Returns the name of this processor.

Classes

Public Types

Public Member Functions

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ anonymous enum

◆ UpdateKind

Constructor & Destructor Documentation

◆ AudioProcessorGraph()

◆ ~AudioProcessorGraph()

Member Function Documentation

◆ clear()

◆ getNodes()

◆ getNumNodes()

◆ getNode()

◆ getNodeForId()

◆ addNode()

◆ removeNode() [1/2]

◆ removeNode() [2/2]

◆ getConnections()

◆ isConnected() [1/2]

◆ isConnected() [2/2]

◆ isAnInputTo() [1/2]

◆ isAnInputTo() [2/2]

◆ canConnect()

◆ addConnection()

◆ removeConnection()

◆ disconnectNode()

◆ isConnectionLegal()

◆ removeIllegalConnections()

◆ rebuild()

◆ getName()

◆ prepareToPlay()

◆ releaseResources()

◆ processBlock() [1/2]

◆ processBlock() [2/2]

◆ supportsDoublePrecisionProcessing()

◆ reset()

◆ setNonRealtime()

◆ getTailLengthSeconds()

◆ acceptsMidi()

◆ producesMidi()

◆ hasEditor()

◆ createEditor()

◆ getNumPrograms()

◆ getCurrentProgram()

◆ setCurrentProgram()

◆ getProgramName()

◆ changeProgramName()

◆ getStateInformation()

◆ setStateInformation()

Purchase

Discover

Learn

Support

About

Events