AudioProcessorGraph::AudioGraphIOProcessor Class Reference

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...

Inherits AudioPluginInstance.

Public Types
enum	IODeviceType { audioInputNode, audioOutputNode, midiInputNode, midiOutputNode }
	Specifies the mode in which this processor will operate. More...

Public Member Functions
IODeviceType	getType () const
	Returns the mode of this processor.
AudioProcessorGraph *	getParentGraph () const
	Returns the parent graph to which this processor belongs, or nullptr if it hasn't yet been added to one.
bool	isInput () const
	True if this is an audio or midi input.
bool	isOutput () const
	True if this is an audio or midi output.
	AudioGraphIOProcessor (const IODeviceType type)
	~AudioGraphIOProcessor ()
const String	getName () const
	Returns the name of this processor.
void	fillInPluginDescription (PluginDescription &) const
	Fills-in the appropriate parts of this plugin description object.
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 &, MidiBuffer &)
	Renders the next block.
const String	getInputChannelName (int channelIndex) const
	Returns the name of one of the processor's input channels.
const String	getOutputChannelName (int channelIndex) const
	Returns the name of one of the processor's output channels.
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	silenceInProducesSilenceOut () const
	Returns true if a silent input always produces a silent output.
double	getTailLengthSeconds () const
	Returns the length of the filter's tail, in seconds.
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::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	setParentGraph (AudioProcessorGraph *)
Public Member Functions inherited from AudioPluginInstance
virtual	~AudioPluginInstance ()
	Destructor.
virtual void *	getPlatformSpecificData ()
	Returns a pointer to some kind of platform-specific data about the plugin.
virtual void	refreshParameterList ()
	For some formats (currently AudioUnit), this forces a reload of the list of available parameters.
Public Member Functions inherited from AudioProcessor
virtual	~AudioProcessor ()
	Destructor.
virtual void	processBlockBypassed (AudioSampleBuffer &buffer, MidiBuffer &midiMessages)
	Renders the next block when the processor is being bypassed.
AudioPlayHead *	getPlayHead () const noexcept
	Returns the current AudioPlayHead object that should be used to find out the state and position of the playhead.
double	getSampleRate () const noexcept
	Returns the current sample rate.
int	getBlockSize () const noexcept
	Returns the current typical block size that is being used.
int	getNumInputChannels () const noexcept
	Returns the number of input channels that the host will be sending the filter.
int	getNumOutputChannels () const noexcept
	Returns the number of output channels that the host will be sending the filter.
const String &	getInputSpeakerArrangement () const noexcept
	Returns a string containing a whitespace-separated list of speaker types corresponding to each input channel.
const String &	getOutputSpeakerArrangement () const noexcept
	Returns a string containing a whitespace-separated list of speaker types corresponding to each output channel.
int	getLatencySamples () const noexcept
	This returns the number of samples delay that the filter imposes on the audio passing through it.
void	setLatencySamples (int newLatency)
	The filter should call this to set the number of samples delay that it introduces.
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 void	reset ()
	A plugin can override this to be told when it should reset any playing voices.
bool	isNonRealtime () const noexcept
	Returns true if the processor is being run in an offline mode for rendering.
void	setNonRealtime (bool isNonRealtime) noexcept
	Called by the host to tell this processor whether it's being used in a non-realtime capacity for offline rendering or bouncing.
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.
virtual String	getParameterLabel (int index) const
	Some plugin types may be able to return a label string for a parameter's units.
void	setParameterNotifyingHost (int parameterIndex, float newValue)
	Your filter can call this when it needs to change one of its parameters.
virtual bool	isParameterAutomatable (int parameterIndex) const
	Returns true if the host can automate this parameter.
virtual bool	isMetaParameter (int parameterIndex) const
	Should return true if this parameter is a "meta" parameter.
void	beginParameterChangeGesture (int parameterIndex)
	Sends a signal to the host to tell it that the user is about to start changing this parameter.
void	endParameterChangeGesture (int parameterIndex)
	Tells the host that the user has finished changing this parameter.
void	updateHostDisplay ()
	The filter can call this when something (apart from a parameter value) has changed.
virtual void	getCurrentProgramStateInformation (juce::MemoryBlock &destData)
	The host will call this method if it wants to save the state of just the filter'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 filter's current program.
virtual void	numChannelsChanged ()
	This method is called when the number of input or output channels is changed.
void	addListener (AudioProcessorListener *newListener)
	Adds a listener that will be called when an aspect of this processor changes.
void	removeListener (AudioProcessorListener *listenerToRemove)
	Removes a previously added listener.
void	setPlayHead (AudioPlayHead *newPlayHead) noexcept
	Tells the processor to use this playhead object.
void	editorBeingDeleted (AudioProcessorEditor *) noexcept
	Not for public use - this is called before deleting an editor component.
void	setPlayConfigDetails (int numIns, int numOuts, double sampleRate, int blockSize) noexcept
	Not for public use - this is called to initialise the processor before playing.
void	setSpeakerArrangement (const String &inputs, const String &outputs)
	Not for public use - this is called to initialise the processor before playing.

Additional Inherited Members
Static Public Member Functions inherited from AudioProcessor
static void JUCE_CALLTYPE	setTypeOfNextNewPlugin (WrapperType)
Public Attributes inherited from AudioProcessor
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 AudioPluginInstance
	AudioPluginInstance ()
Static Protected Member Functions inherited from AudioProcessor
static void	copyXmlToBinary (const XmlElement &xml, juce::MemoryBlock &destData)
	Helper function that just converts an xml element into a binary blob.
static XmlElement *	getXmlFromBinary (const void *data, int sizeInBytes)
	Retrieves an XML element that was stored as binary with the copyXmlToBinary() method.
Protected Attributes inherited from AudioProcessor
AudioPlayHead *	playHead

Detailed Description

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.

If you create an AudioGraphIOProcessor in "input" mode, it will act as a node in the graph which delivers the audio that is coming into the parent graph. This allows you to stream the data to other nodes and process the incoming audio.

Likewise, one of these in "output" mode can be sent data which it will add to the sum of data being sent to the graph's output.

See Also

AudioProcessorGraph

Member Enumeration Documentation

enum AudioProcessorGraph::AudioGraphIOProcessor::IODeviceType

Specifies the mode in which this processor will operate.

Enumerator:

audioInputNode	In this mode, the processor has output channels representing all the audio input channels that are coming into its parent audio graph.
audioOutputNode	In this mode, the processor has input channels representing all the audio output channels that are going out of its parent audio graph.
midiInputNode	In this mode, the processor has a midi output which delivers the same midi data that is arriving at its parent graph.
midiOutputNode	In this mode, the processor has a midi input and any data sent to it will be passed out of the parent graph.

Constructor & Destructor Documentation

AudioProcessorGraph::AudioGraphIOProcessor::AudioGraphIOProcessor

(

const IODeviceType

type

)

AudioProcessorGraph::AudioGraphIOProcessor::~AudioGraphIOProcessor

(

)

Member Function Documentation

IODeviceType AudioProcessorGraph::AudioGraphIOProcessor::getType

(

)

const

Returns the mode of this processor.

AudioProcessorGraph* AudioProcessorGraph::AudioGraphIOProcessor::getParentGraph

(

)

const

Returns the parent graph to which this processor belongs, or nullptr if it hasn't yet been added to one.

bool AudioProcessorGraph::AudioGraphIOProcessor::isInput

(

)

const

True if this is an audio or midi input.

bool AudioProcessorGraph::AudioGraphIOProcessor::isOutput

(

)

const

True if this is an audio or midi output.

const String AudioProcessorGraph::AudioGraphIOProcessor::getName ( ) const

virtual

Returns the name of this processor.

Implements AudioProcessor.

void AudioProcessorGraph::AudioGraphIOProcessor::fillInPluginDescription ( PluginDescription &  description ) const

virtual

Fills-in the appropriate parts of this plugin description object.

Implements AudioPluginInstance.

void AudioProcessorGraph::AudioGraphIOProcessor::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::AudioGraphIOProcessor::releaseResources ( )

virtual

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

Implements AudioProcessor.

void AudioProcessorGraph::AudioGraphIOProcessor::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 you 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::AudioGraphIOProcessor::getInputChannelName ( int  channelIndex ) const

virtual

Returns the name of one of the processor's input channels.

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

Implements AudioProcessor.

const String AudioProcessorGraph::AudioGraphIOProcessor::getOutputChannelName ( int  channelIndex ) const

virtual

Returns the name of one of the processor's output channels.

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

Implements AudioProcessor.

bool AudioProcessorGraph::AudioGraphIOProcessor::isInputChannelStereoPair ( int  index ) const

virtual

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

Implements AudioProcessor.

bool AudioProcessorGraph::AudioGraphIOProcessor::isOutputChannelStereoPair ( int  index ) const

virtual

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

Implements AudioProcessor.

bool AudioProcessorGraph::AudioGraphIOProcessor::silenceInProducesSilenceOut ( ) const

virtual

Returns true if a silent input always produces a silent output.

Implements AudioProcessor.

double AudioProcessorGraph::AudioGraphIOProcessor::getTailLengthSeconds ( ) const

virtual

Returns the length of the filter's tail, in seconds.

Implements AudioProcessor.

bool AudioProcessorGraph::AudioGraphIOProcessor::acceptsMidi ( ) const

virtual

Returns true if the processor wants midi messages.

Implements AudioProcessor.

bool AudioProcessorGraph::AudioGraphIOProcessor::producesMidi ( ) const

virtual

Returns true if the processor produces midi messages.

Implements AudioProcessor.

bool AudioProcessorGraph::AudioGraphIOProcessor::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::AudioGraphIOProcessor::createEditor ( )

virtual

Creates the filter's UI.

This can return nullptr 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::AudioGraphIOProcessor::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::AudioGraphIOProcessor::getParameterName ( int  parameterIndex )

virtual

Returns the name of a particular parameter.

Implements AudioProcessor.

float AudioProcessorGraph::AudioGraphIOProcessor::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::AudioGraphIOProcessor::getParameterText ( int  parameterIndex )

virtual

Returns the value of a parameter as a text string.

Implements AudioProcessor.

void AudioProcessorGraph::AudioGraphIOProcessor::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::AudioGraphIOProcessor::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::AudioGraphIOProcessor::getCurrentProgram ( )

virtual

Returns the number of the currently active program.

Implements AudioProcessor.

void AudioProcessorGraph::AudioGraphIOProcessor::setCurrentProgram ( int  index )

virtual

Called by the host to change the current program.

Implements AudioProcessor.

const String AudioProcessorGraph::AudioGraphIOProcessor::getProgramName ( int  index )

virtual

Must return the name of a given program.

Implements AudioProcessor.

void AudioProcessorGraph::AudioGraphIOProcessor::changeProgramName ( int  index, const String &  newName  )

virtual

Called by the host to rename a program.

Implements AudioProcessor.

void AudioProcessorGraph::AudioGraphIOProcessor::getStateInformation ( juce::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::AudioGraphIOProcessor::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::AudioGraphIOProcessor::setParentGraph

(

AudioProcessorGraph *

)

---

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

• juce_AudioProcessorGraph.h