AudioProcessorGraph Class Reference

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

Inherits AudioProcessor, and AsyncUpdater.

List of all members.

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...
Public Member Functions
	AudioProcessorGraph ()
	Creates an empty graph.
	~AudioProcessorGraph ()
	Destructor.
void	clear ()
	Deletes all nodes and connections from this graph.
int	getNumNodes () const
	Returns the number of nodes in the graph.
Node *	getNode (const int index) const
	Returns a pointer to one of the nodes in the graph.
Node *	getNodeForId (const uint32 nodeId) const
	Searches the graph for a node with the given ID number and returns it.
Node *	addNode (AudioProcessor *newProcessor, uint32 nodeId=0)
	Adds a node to the graph.
bool	removeNode (uint32 nodeId)
	Deletes a node within the graph which has the specified ID.
int	getNumConnections () const
	Returns the number of connections in the graph.
const Connection *	getConnection (int index) const
	Returns a pointer to one of the connections in the graph.
const Connection *	getConnectionBetween (uint32 sourceNodeId, int sourceChannelIndex, uint32 destNodeId, int destChannelIndex) const
	Searches for a connection between some specified channels.
bool	isConnected (uint32 possibleSourceNodeId, uint32 possibleDestNodeId) const
	Returns true if there is a connection between any of the channels of two specified nodes.
bool	canConnect (uint32 sourceNodeId, int sourceChannelIndex, uint32 destNodeId, int destChannelIndex) const
	Returns true if it would be legal to connect the specified points.
bool	addConnection (uint32 sourceNodeId, int sourceChannelIndex, uint32 destNodeId, int destChannelIndex)
	Attempts to connect two specified channels of two nodes.
void	removeConnection (int index)
	Deletes the connection with the specified index.
bool	removeConnection (uint32 sourceNodeId, int sourceChannelIndex, uint32 destNodeId, int destChannelIndex)
	Deletes any connection between two specified points.
bool	disconnectNode (uint32 nodeId)
	Removes all connections from the specified node.
bool	removeIllegalConnections ()
	Performs a sanity checks of all the connections.
const String	getName () const
	Returns the name of this processor.
void	prepareToPlay (double sampleRate, int estimatedSamplesPerBlock)
	Called before playback starts, to let the filter prepare itself.
void	releaseResources ()
	Called after playback has stopped, to let the filter free up any resources it no longer needs.
void	processBlock (AudioSampleBuffer &buffer, MidiBuffer &midiMessages)
	Renders the next block.
const String	getInputChannelName (int channelIndex) const
	Returns the name of one of the input channels, as returned by the host.
const String	getOutputChannelName (int channelIndex) const
	Returns the name of one of the output channels, as returned by the host.
bool	isInputChannelStereoPair (int index) const
	Returns true if the specified channel is part of a stereo pair with its neighbour.
bool	isOutputChannelStereoPair (int index) const
	Returns true if the specified channel is part of a stereo pair with its neighbour.
bool	acceptsMidi () const
	Returns true if the processor wants midi messages.
bool	producesMidi () const
	Returns true if the processor produces midi messages.
bool	hasEditor () const
	Your filter must override this and return true if it can create an editor component.
AudioProcessorEditor *	createEditor ()
	Creates the filter's UI.
int	getNumParameters ()
	This must return the correct value immediately after the object has been created, and mustn't change the number of parameters later.
const String	getParameterName (int)
	Returns the name of a particular parameter.
float	getParameter (int)
	Called by the host to find out the value of one of the filter's parameters.
const String	getParameterText (int)
	Returns the value of a parameter as a text string.
void	setParameter (int, float)
	The host will call this method to change the value of one of the filter's parameters.
int	getNumPrograms ()
	Returns the number of preset programs the filter supports.
int	getCurrentProgram ()
	Returns the number of the currently active program.
void	setCurrentProgram (int)
	Called by the host to change the current program.
const String	getProgramName (int)
	Must return the name of a given program.
void	changeProgramName (int, const String &)
	Called by the host to rename a program.
void	getStateInformation (JUCE_NAMESPACE::MemoryBlock &destData)
	The host will call this method when it wants to save the filter's internal state.
void	setStateInformation (const void *data, int sizeInBytes)
	This must restore the filter's state from a block of data previously created using getStateInformation().
void	handleAsyncUpdate ()
	Called back to do whatever your class needs to do.
Static Public Attributes
static const int	midiChannelIndex
	A special number that represents the midi channel of a node.

---

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.

---

Constructor & Destructor Documentation

AudioProcessorGraph::AudioProcessorGraph

(

)

Creates an empty graph.

AudioProcessorGraph::~AudioProcessorGraph

(

)

Destructor.

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

---

Member Function Documentation

void AudioProcessorGraph::clear

(

)

Deletes all nodes and connections from this graph.

Any processor objects in the graph will be deleted.

int AudioProcessorGraph::getNumNodes

(

)

const

Returns the number of nodes in the graph.

Node* AudioProcessorGraph::getNode

(

const int

index )

const

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

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

See also:

getNodeForId

Node* AudioProcessorGraph::getNodeForId

(

const uint32

nodeId )

const

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

If no such node was found, this returns 0.

See also:

getNode

Node* AudioProcessorGraph::addNode	(	AudioProcessor *	newProcessor,
		uint32	nodeId = 0
	)

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 an ID to use for the node, but if the value is already in use, this new node will overwrite the old one.

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

bool AudioProcessorGraph::removeNode

(

uint32

nodeId )

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

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

int AudioProcessorGraph::getNumConnections

(

)

const

Returns the number of connections in the graph.

const Connection* AudioProcessorGraph::getConnection

(

int

index )

const

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

const Connection* AudioProcessorGraph::getConnectionBetween	(	uint32	sourceNodeId,
		int	sourceChannelIndex,
		uint32	destNodeId,
		int	destChannelIndex
	)		const

Searches for a connection between some specified channels.

If no such connection is found, this returns 0.

bool AudioProcessorGraph::isConnected	(	uint32	possibleSourceNodeId,
		uint32	possibleDestNodeId
	)		const

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

bool AudioProcessorGraph::canConnect	(	uint32	sourceNodeId,
		int	sourceChannelIndex,
		uint32	destNodeId,
		int	destChannelIndex
	)		const

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

bool AudioProcessorGraph::addConnection	(	uint32	sourceNodeId,
		int	sourceChannelIndex,
		uint32	destNodeId,
		int	destChannelIndex
	)

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.

void AudioProcessorGraph::removeConnection

(

int

index )

Deletes the connection with the specified index.

Returns true if a connection was actually deleted.

bool AudioProcessorGraph::removeConnection	(	uint32	sourceNodeId,
		int	sourceChannelIndex,
		uint32	destNodeId,
		int	destChannelIndex
	)

Deletes any connection between two specified points.

Returns true if a connection was actually deleted.

bool AudioProcessorGraph::disconnectNode

(

uint32

nodeId )

Removes all connections from the specified node.

bool AudioProcessorGraph::removeIllegalConnections

(

)

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.

const String AudioProcessorGraph::getName

(

)

const [virtual]

Returns the name of this processor.

Implements AudioProcessor.

void AudioProcessorGraph::prepareToPlay	(	double	sampleRate,
		int	estimatedSamplesPerBlock
	)		[virtual]

Called before playback starts, to let the filter prepare itself.

The sample rate is the target sample rate, and will remain constant until playback stops.

The estimatedSamplesPerBlock value is a HINT about the typical number of samples that will be processed for each callback, but isn't any kind of guarantee. The actual block sizes that the host uses may be different each time the callback happens, and may be more or less than this value.

Implements AudioProcessor.

void AudioProcessorGraph::releaseResources

(

)

[virtual]

Called after playback has stopped, to let the filter free up any resources it no longer needs.

Implements AudioProcessor.

void AudioProcessorGraph::processBlock	(	AudioSampleBuffer &	buffer,
		MidiBuffer &	midiMessages
	)		[virtual]

Renders the next block.

When this method is called, the buffer contains a number of channels which is at least as great as the maximum number of input and output channels that this filter is using. It will be filled with the filter's input data and should be replaced with the filter's output.

So for example if your filter has 2 input channels and 4 output channels, then the buffer will contain 4 channels, the first two being filled with the input data. Your filter should read these, do its processing, and replace the contents of all 4 channels with its output.

Or if your filter has 5 inputs and 2 outputs, the buffer will have 5 channels, all filled with data, and your filter should overwrite the first 2 of these with its output. But be VERY careful not to write anything to the last 3 channels, as these might be mapped to memory that the host assumes is read-only!

Note that if you have more outputs than inputs, then only those channels that correspond to an input channel are guaranteed to contain sensible data - e.g. in the case of 2 inputs and 4 outputs, the first two channels contain the input, but the last two channels may contain garbage, so you should be careful not to let this pass through without being overwritten or cleared.

Also note that the buffer may have more channels than are strictly necessary, but your should only read/write from the ones that your filter is supposed to be using.

The number of samples in these buffers is NOT guaranteed to be the same for every callback, and may be more or less than the estimated value given to prepareToPlay(). Your code must be able to cope with variable-sized blocks, or you're going to get clicks and crashes!

If the filter is receiving a midi input, then the midiMessages array will be filled with the midi messages for this block. Each message's timestamp will indicate the message's time, as a number of samples from the start of the block.

Any messages left in the midi buffer when this method has finished are assumed to be the filter's midi output. This means that your filter should be careful to clear any incoming messages from the array if it doesn't want them to be passed-on.

Be very careful about what you do in this callback - it's going to be called by the audio thread, so any kind of interaction with the UI is absolutely out of the question. If you change a parameter in here and need to tell your UI to update itself, the best way is probably to inherit from a ChangeBroadcaster, let the UI components register as listeners, and then call sendChangeMessage() inside the processBlock() method to send out an asynchronous message. You could also use the AsyncUpdater class in a similar way.

Implements AudioProcessor.

const String AudioProcessorGraph::getInputChannelName

(

int

channelIndex )

const [virtual]

Returns the name of one of the input channels, as returned by the host.

The host might not supply very useful names for channels, and this might be something like "1", "2", "left", "right", etc.

Implements AudioProcessor.

const String AudioProcessorGraph::getOutputChannelName

(

int

channelIndex )

const [virtual]

Returns the name of one of the output channels, as returned by the host.

The host might not supply very useful names for channels, and this might be something like "1", "2", "left", "right", etc.

Implements AudioProcessor.

bool AudioProcessorGraph::isInputChannelStereoPair

(

int

index )

const [virtual]

Returns true if the specified channel is part of a stereo pair with its neighbour.

Implements AudioProcessor.

bool AudioProcessorGraph::isOutputChannelStereoPair

(

int

index )

const [virtual]

Returns true if the specified channel is part of a stereo pair with its neighbour.

Implements AudioProcessor.

bool AudioProcessorGraph::acceptsMidi

(

)

const [virtual]

Returns true if the processor wants midi messages.

Implements AudioProcessor.

bool AudioProcessorGraph::producesMidi

(

)

const [virtual]

Returns true if the processor produces midi messages.

Implements AudioProcessor.

bool AudioProcessorGraph::hasEditor

(

)

const [virtual]

Your filter must override this and return true if it can create an editor component.

See also:

createEditor

Implements AudioProcessor.

AudioProcessorEditor* AudioProcessorGraph::createEditor

(

)

[virtual]

Creates the filter's UI.

This can return 0 if you want a UI-less filter, in which case the host may create a generic UI that lets the user twiddle the parameters directly.

If you do want to pass back a component, the component should be created and set to the correct size before returning it. If you implement this method, you must also implement the hasEditor() method and make it return true.

Remember not to do anything silly like allowing your filter to keep a pointer to the component that gets created - it could be deleted later without any warning, which would make your pointer into a dangler. Use the getActiveEditor() method instead.

The correct way to handle the connection between an editor component and its filter is to use something like a ChangeBroadcaster so that the editor can register itself as a listener, and be told when a change occurs. This lets them safely unregister themselves when they are deleted.

Here are a few things to bear in mind when writing an editor:

• Initially there won't be an editor, until the user opens one, or they might not open one at all. Your filter mustn't rely on it being there.
• An editor object may be deleted and a replacement one created again at any time.
• It's safe to assume that an editor will be deleted before its filter.

See also:

hasEditor

Implements AudioProcessor.

int AudioProcessorGraph::getNumParameters

(

)

[virtual]

This must return the correct value immediately after the object has been created, and mustn't change the number of parameters later.

Implements AudioProcessor.

const String AudioProcessorGraph::getParameterName

(

int

parameterIndex )

[virtual]

Returns the name of a particular parameter.

Implements AudioProcessor.

float AudioProcessorGraph::getParameter

(

int

parameterIndex )

[virtual]

Called by the host to find out the value of one of the filter's parameters.

The host will expect the value returned to be between 0 and 1.0.

This could be called quite frequently, so try to make your code efficient. It's also likely to be called by non-UI threads, so the code in here should be thread-aware.

Implements AudioProcessor.

const String AudioProcessorGraph::getParameterText

(

int

parameterIndex )

[virtual]

Returns the value of a parameter as a text string.

Implements AudioProcessor.

void AudioProcessorGraph::setParameter	(	int	parameterIndex,
		float	newValue
	)		[virtual]

The host will call this method to change the value of one of the filter's parameters.

The host may call this at any time, including during the audio processing callback, so the filter has to process this very fast and avoid blocking.

If you want to set the value of a parameter internally, e.g. from your editor component, then don't call this directly - instead, use the setParameterNotifyingHost() method, which will also send a message to the host telling it about the change. If the message isn't sent, the host won't be able to automate your parameters properly.

The value passed will be between 0 and 1.0.

Implements AudioProcessor.

int AudioProcessorGraph::getNumPrograms

(

)

[virtual]

Returns the number of preset programs the filter supports.

The value returned must be valid as soon as this object is created, and must not change over its lifetime.

This value shouldn't be less than 1.

Implements AudioProcessor.

int AudioProcessorGraph::getCurrentProgram

(

)

[virtual]

Returns the number of the currently active program.

Implements AudioProcessor.

void AudioProcessorGraph::setCurrentProgram

(

int

index )

[virtual]

Called by the host to change the current program.

Implements AudioProcessor.

const String AudioProcessorGraph::getProgramName

(

int

index )

[virtual]

Must return the name of a given program.

Implements AudioProcessor.

void AudioProcessorGraph::changeProgramName	(	int	index,
		const String &	newName
	)		[virtual]

Called by the host to rename a program.

Implements AudioProcessor.

void AudioProcessorGraph::getStateInformation

(

JUCE_NAMESPACE::MemoryBlock &

destData )

[virtual]

The host will call this method when it wants to save the filter's internal state.

This must copy any info about the filter's state into the block of memory provided, so that the host can store this and later restore it using setStateInformation().

Note that there's also a getCurrentProgramStateInformation() method, which only stores the current program, not the state of the entire filter.

See also the helper function copyXmlToBinary() for storing settings as XML.

See also:

getCurrentProgramStateInformation

Implements AudioProcessor.

void AudioProcessorGraph::setStateInformation	(	const void *	data,
		int	sizeInBytes
	)		[virtual]

This must restore the filter's state from a block of data previously created using getStateInformation().

Note that there's also a setCurrentProgramStateInformation() method, which tries to restore just the current program, not the state of the entire filter.

See also the helper function getXmlFromBinary() for loading settings as XML.

See also:

setCurrentProgramStateInformation

Implements AudioProcessor.

void AudioProcessorGraph::handleAsyncUpdate

(

)

[virtual]

Called back to do whatever your class needs to do.

This method is called by the message thread at the next convenient time after the triggerAsyncUpdate() method has been called.

Implements AsyncUpdater.

---

Member Data Documentation

const int AudioProcessorGraph::midiChannelIndex [static]

A special number 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.

---

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

• juce_AudioProcessorGraph.h