JUCE
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros
Public Types | Public Member Functions | Static Public Member Functions | Public Attributes | Protected Member Functions | Protected Attributes | List of all members
AudioProcessor Class Referenceabstract

Base class for audio processing filters or plugins. More...

Inherited by AudioPluginInstance, and AudioProcessorGraph.

Public Types

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

Public Member Functions

virtual ~AudioProcessor ()
 Destructor.
 
virtual const String getName () const =0
 Returns the name of this processor.
 
virtual void prepareToPlay (double sampleRate, int estimatedSamplesPerBlock)=0
 Called before playback starts, to let the filter prepare itself.
 
virtual void releaseResources ()=0
 Called after playback has stopped, to let the filter free up any resources it no longer needs.
 
virtual void processBlock (AudioSampleBuffer &buffer, MidiBuffer &midiMessages)=0
 Renders the next block.
 
virtual void processBlockBypassed (AudioSampleBuffer &buffer, MidiBuffer &midiMessages)
 Renders the next block when the processor is being bypassed.
 
AudioPlayHeadgetPlayHead () 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 StringgetInputSpeakerArrangement () const noexcept
 Returns a string containing a whitespace-separated list of speaker types corresponding to each input channel.
 
const StringgetOutputSpeakerArrangement () const noexcept
 Returns a string containing a whitespace-separated list of speaker types corresponding to each output channel.
 
virtual const String getInputChannelName (int channelIndex) const =0
 Returns the name of one of the processor's input channels.
 
virtual const String getOutputChannelName (int channelIndex) const =0
 Returns the name of one of the processor's output channels.
 
virtual bool isInputChannelStereoPair (int index) const =0
 Returns true if the specified channel is part of a stereo pair with its neighbour.
 
virtual bool isOutputChannelStereoPair (int index) const =0
 Returns true if the specified channel is part of a stereo pair with its neighbour.
 
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.
 
virtual bool silenceInProducesSilenceOut () const =0
 Returns true if a silent input always produces a silent output.
 
virtual double getTailLengthSeconds () const =0
 Returns the length of the filter's tail, in seconds.
 
virtual bool acceptsMidi () const =0
 Returns true if the processor wants midi messages.
 
virtual bool producesMidi () const =0
 Returns true if the processor produces midi messages.
 
const CriticalSectiongetCallbackLock () 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.
 
virtual AudioProcessorEditorcreateEditor ()=0
 Creates the filter's UI.
 
virtual bool hasEditor () const =0
 Your filter must override this and return true if it can create an editor component.
 
AudioProcessorEditorgetActiveEditor () const noexcept
 Returns the active editor, if there is one.
 
AudioProcessorEditorcreateEditorIfNeeded ()
 Returns the active editor, or if there isn't one, it will create one.
 
virtual int getNumParameters ()=0
 This must return the correct value immediately after the object has been created, and mustn't change the number of parameters later.
 
virtual const String getParameterName (int parameterIndex)=0
 Returns the name of a particular parameter.
 
virtual float getParameter (int parameterIndex)=0
 Called by the host to find out the value of one of the filter's parameters.
 
virtual const String getParameterText (int parameterIndex)=0
 Returns the value of a parameter as a text string.
 
virtual String getParameterName (int parameterIndex, int maximumStringLength)
 Returns the name of a parameter as a text string with a preferred maximum length.
 
virtual String getParameterText (int parameterIndex, int maximumStringLength)
 Returns the value of a parameter as a text string with a preferred maximum length.
 
virtual int getParameterNumSteps (int parameterIndex)
 Returns the number of discrete steps that this parameter can represent.
 
virtual float getParameterDefaultValue (int parameterIndex)
 Returns the default value for the parameter.
 
virtual String getParameterLabel (int index) const
 Some plugin types may be able to return a label string for a parameter's units.
 
virtual void setParameter (int parameterIndex, float newValue)=0
 The host will call this method to change the value of one of the filter's parameters.
 
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 int getNumPrograms ()=0
 Returns the number of preset programs the filter supports.
 
virtual int getCurrentProgram ()=0
 Returns the number of the currently active program.
 
virtual void setCurrentProgram (int index)=0
 Called by the host to change the current program.
 
virtual const String getProgramName (int index)=0
 Must return the name of a given program.
 
virtual void changeProgramName (int index, const String &newName)=0
 Called by the host to rename a program.
 
virtual void getStateInformation (juce::MemoryBlock &destData)=0
 The host will call this method when it wants to save the filter's internal state.
 
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 setStateInformation (const void *data, int sizeInBytes)=0
 This must restore the filter's state from a block of data previously created using getStateInformation().
 
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.
 
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) noexcept
 This is called by the processor to specify its details before being played.
 
void editorBeingDeleted (AudioProcessorEditor *) noexcept
 Not for public use - this is called before deleting an editor component.
 
void setSpeakerArrangement (const String &inputs, const String &outputs)
 Not for public use - this is called to initialise the processor before playing.
 

Static Public Member Functions

static void copyXmlToBinary (const XmlElement &xml, juce::MemoryBlock &destData)
 Helper function that just converts an xml element into a binary blob.
 
static XmlElementgetXmlFromBinary (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

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

 AudioProcessor ()
 Constructor.
 
void sendParamChangeMessageToListeners (int parameterIndex, float newValue)
 

Protected Attributes

AudioPlayHeadplayHead
 

Detailed Description

Base class for audio processing filters or plugins.

This is intended to act as a base class of audio filter that is general enough to be wrapped as a VST, AU, RTAS, etc, or used internally.

It is also used by the plugin hosting code as the wrapper around an instance of a loaded plugin.

Derive your filter class from this base class, and if you're building a plugin, you should implement a global function called createPluginFilter() which creates and returns a new instance of your subclass.

Member Enumeration Documentation

Flags to indicate the type of plugin context in which a processor is being used.

Enumerator:
wrapperType_Undefined 
wrapperType_VST 
wrapperType_VST3 
wrapperType_AudioUnit 
wrapperType_RTAS 
wrapperType_AAX 
wrapperType_Standalone 

Constructor & Destructor Documentation

AudioProcessor::AudioProcessor ( )
protected

Constructor.

You can also do your initialisation tasks in the initialiseFilterInfo() call, which will be made after this object has been created.

virtual AudioProcessor::~AudioProcessor ( )
virtual

Destructor.

Member Function Documentation

virtual const String AudioProcessor::getName ( ) const
pure virtual

Returns the name of this processor.

Implemented in AudioProcessorGraph, and AudioProcessorGraph::AudioGraphIOProcessor.

virtual void AudioProcessor::prepareToPlay ( double  sampleRate,
int  estimatedSamplesPerBlock 
)
pure 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.

Implemented in AudioProcessorGraph, and AudioProcessorGraph::AudioGraphIOProcessor.

virtual void AudioProcessor::releaseResources ( )
pure virtual

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

Implemented in AudioProcessorGraph, and AudioProcessorGraph::AudioGraphIOProcessor.

virtual void AudioProcessor::processBlock ( AudioSampleBuffer buffer,
MidiBuffer midiMessages 
)
pure 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.

Implemented in AudioProcessorGraph, and AudioProcessorGraph::AudioGraphIOProcessor.

virtual void AudioProcessor::processBlockBypassed ( AudioSampleBuffer buffer,
MidiBuffer midiMessages 
)
virtual

Renders the next block when the processor is being bypassed.

The default implementation of this method will pass-through any incoming audio, but you may override this method e.g. to add latency compensation to the data to match the processor's latency characteristics. This will avoid situations where bypassing will shift the signal forward in time, possibly creating pre-echo effects and odd timings. Another use for this method would be to cross-fade or morph between the wet (not bypassed) and dry (bypassed) signals.

AudioPlayHead* AudioProcessor::getPlayHead ( ) const
noexcept

Returns the current AudioPlayHead object that should be used to find out the state and position of the playhead.

You can call this from your processBlock() method, and use the AudioPlayHead object to get the details about the time of the start of the block currently being processed.

If the host hasn't supplied a playhead object, this will return nullptr.

double AudioProcessor::getSampleRate ( ) const
noexcept

Returns the current sample rate.

This can be called from your processBlock() method - it's not guaranteed to be valid at any other time, and may return 0 if it's unknown.

int AudioProcessor::getBlockSize ( ) const
noexcept

Returns the current typical block size that is being used.

This can be called from your processBlock() method - it's not guaranteed to be valid at any other time.

Remember it's not the ONLY block size that may be used when calling processBlock, it's just the normal one. The actual block sizes used may be larger or smaller than this, and will vary between successive calls.

int AudioProcessor::getNumInputChannels ( ) const
noexcept

Returns the number of input channels that the host will be sending the filter.

If writing a plugin, your configuration macros should specify the number of channels that your filter would prefer to have, and this method lets you know how many the host is actually using.

Note that this method is only valid during or after the prepareToPlay() method call. Until that point, the number of channels will be unknown.

Referenced by StandaloneFilterWindow::showAudioSettingsDialog(), and StandaloneFilterWindow::StandaloneFilterWindow().

int AudioProcessor::getNumOutputChannels ( ) const
noexcept

Returns the number of output channels that the host will be sending the filter.

If writing a plugin, your configuration macros should specify the number of channels that your filter would prefer to have, and this method lets you know how many the host is actually using.

Note that this method is only valid during or after the prepareToPlay() method call. Until that point, the number of channels will be unknown.

Referenced by StandaloneFilterWindow::showAudioSettingsDialog(), and StandaloneFilterWindow::StandaloneFilterWindow().

const String& AudioProcessor::getInputSpeakerArrangement ( ) const
noexcept

Returns a string containing a whitespace-separated list of speaker types corresponding to each input channel.

For example in a 5.1 arrangement, the string may be "L R C Lfe Ls Rs" If the speaker arrangement is unknown, the returned string will be empty.

const String& AudioProcessor::getOutputSpeakerArrangement ( ) const
noexcept

Returns a string containing a whitespace-separated list of speaker types corresponding to each output channel.

For example in a 5.1 arrangement, the string may be "L R C Lfe Ls Rs" If the speaker arrangement is unknown, the returned string will be empty.

virtual const String AudioProcessor::getInputChannelName ( int  channelIndex) const
pure 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.

Implemented in AudioProcessorGraph, and AudioProcessorGraph::AudioGraphIOProcessor.

virtual const String AudioProcessor::getOutputChannelName ( int  channelIndex) const
pure 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.

Implemented in AudioProcessorGraph, and AudioProcessorGraph::AudioGraphIOProcessor.

virtual bool AudioProcessor::isInputChannelStereoPair ( int  index) const
pure virtual

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

Implemented in AudioProcessorGraph, and AudioProcessorGraph::AudioGraphIOProcessor.

virtual bool AudioProcessor::isOutputChannelStereoPair ( int  index) const
pure virtual

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

Implemented in AudioProcessorGraph, and AudioProcessorGraph::AudioGraphIOProcessor.

int AudioProcessor::getLatencySamples ( ) const
noexcept

This returns the number of samples delay that the filter imposes on the audio passing through it.

The host will call this to find the latency - the filter itself should set this value by calling setLatencySamples() as soon as it can during its initialisation.

void AudioProcessor::setLatencySamples ( int  newLatency)

The filter should call this to set the number of samples delay that it introduces.

The filter should call this as soon as it can during initialisation, and can call it later if the value changes.

virtual bool AudioProcessor::silenceInProducesSilenceOut ( ) const
pure virtual

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

Implemented in AudioProcessorGraph, and AudioProcessorGraph::AudioGraphIOProcessor.

virtual double AudioProcessor::getTailLengthSeconds ( ) const
pure virtual

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

Implemented in AudioProcessorGraph, and AudioProcessorGraph::AudioGraphIOProcessor.

virtual bool AudioProcessor::acceptsMidi ( ) const
pure virtual

Returns true if the processor wants midi messages.

Implemented in AudioProcessorGraph, and AudioProcessorGraph::AudioGraphIOProcessor.

virtual bool AudioProcessor::producesMidi ( ) const
pure virtual

Returns true if the processor produces midi messages.

Implemented in AudioProcessorGraph, and AudioProcessorGraph::AudioGraphIOProcessor.

const CriticalSection& AudioProcessor::getCallbackLock ( ) const
noexcept

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

Use it from your UI or other threads to lock access to variables that are used by the process callback, but obviously be careful not to keep it locked for too long, because that could cause stuttering playback. If you need to do something that'll take a long time and need the processing to stop while it happens, use the suspendProcessing() method instead.

See Also
suspendProcessing
void AudioProcessor::suspendProcessing ( bool  shouldBeSuspended)

Enables and disables the processing callback.

If you need to do something time-consuming on a thread and would like to make sure the audio processing callback doesn't happen until you've finished, use this to disable the callback and re-enable it again afterwards.

E.g.

void loadNewPatch()
{
..do something that takes ages..
}

If the host tries to make an audio callback while processing is suspended, the filter will return an empty buffer, but won't block the audio thread like it would do if you use the getCallbackLock() critical section to synchronise access.

If you're going to use this, your processBlock() method must call isSuspended() and check whether it's suspended or not. If it is, then it should skip doing any real processing, either emitting silence or passing the input through unchanged.

See Also
getCallbackLock
bool AudioProcessor::isSuspended ( ) const
noexcept

Returns true if processing is currently suspended.

See Also
suspendProcessing
virtual void AudioProcessor::reset ( )
virtual

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

The default implementation does nothing, but a host may call this to tell the plugin that it should stop any tails or sounds that have been left running.

Reimplemented in AudioProcessorGraph.

bool AudioProcessor::isNonRealtime ( ) const
noexcept

Returns true if the processor is being run in an offline mode for rendering.

If the processor is being run live on realtime signals, this returns false. If the mode is unknown, this will assume it's realtime and return false.

This value may be unreliable until the prepareToPlay() method has been called, and could change each time prepareToPlay() is called.

See Also
setNonRealtime()
void AudioProcessor::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.

virtual AudioProcessorEditor* AudioProcessor::createEditor ( )
pure 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

Implemented in AudioProcessorGraph, and AudioProcessorGraph::AudioGraphIOProcessor.

virtual bool AudioProcessor::hasEditor ( ) const
pure virtual

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

See Also
createEditor

Implemented in AudioProcessorGraph, and AudioProcessorGraph::AudioGraphIOProcessor.

AudioProcessorEditor* AudioProcessor::getActiveEditor ( ) const
noexcept

Returns the active editor, if there is one.

Bear in mind this can return nullptr, even if an editor has previously been opened.

AudioProcessorEditor* AudioProcessor::createEditorIfNeeded ( )

Returns the active editor, or if there isn't one, it will create one.

This may call createEditor() internally to create the component.

Referenced by StandaloneFilterWindow::resetFilter(), and StandaloneFilterWindow::StandaloneFilterWindow().

virtual int AudioProcessor::getNumParameters ( )
pure virtual

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

Implemented in AudioProcessorGraph, and AudioProcessorGraph::AudioGraphIOProcessor.

virtual const String AudioProcessor::getParameterName ( int  parameterIndex)
pure virtual

Returns the name of a particular parameter.

Implemented in AudioProcessorGraph, and AudioProcessorGraph::AudioGraphIOProcessor.

virtual float AudioProcessor::getParameter ( int  parameterIndex)
pure 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.

Implemented in AudioProcessorGraph, and AudioProcessorGraph::AudioGraphIOProcessor.

virtual const String AudioProcessor::getParameterText ( int  parameterIndex)
pure virtual

Returns the value of a parameter as a text string.

Implemented in AudioProcessorGraph, and AudioProcessorGraph::AudioGraphIOProcessor.

virtual String AudioProcessor::getParameterName ( int  parameterIndex,
int  maximumStringLength 
)
virtual

Returns the name of a parameter as a text string with a preferred maximum length.

If you want to provide customised short versions of your parameter names that will look better in constrained spaces (e.g. the displays on hardware controller devices or mixing desks) then you should implement this method. If you don't override it, the default implementation will call getParameterText(int), and truncate the result.

virtual String AudioProcessor::getParameterText ( int  parameterIndex,
int  maximumStringLength 
)
virtual

Returns the value of a parameter as a text string with a preferred maximum length.

If you want to provide customised short versions of your parameter values that will look better in constrained spaces (e.g. the displays on hardware controller devices or mixing desks) then you should implement this method. If you don't override it, the default implementation will call getParameterText(int), and truncate the result.

virtual int AudioProcessor::getParameterNumSteps ( int  parameterIndex)
virtual

Returns the number of discrete steps that this parameter can represent.

The default return value if you don't implement this method is 0x7fffffff. If your parameter is boolean, then you may want to make this return 2. The value that is returned may or may not be used, depending on the host.

virtual float AudioProcessor::getParameterDefaultValue ( int  parameterIndex)
virtual

Returns the default value for the parameter.

By default, this just returns 0. The value that is returned may or may not be used, depending on the host.

virtual String AudioProcessor::getParameterLabel ( int  index) const
virtual

Some plugin types may be able to return a label string for a parameter's units.

virtual void AudioProcessor::setParameter ( int  parameterIndex,
float  newValue 
)
pure 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.

Implemented in AudioProcessorGraph, and AudioProcessorGraph::AudioGraphIOProcessor.

void AudioProcessor::setParameterNotifyingHost ( int  parameterIndex,
float  newValue 
)

Your filter can call this when it needs to change one of its parameters.

This could happen when the editor or some other internal operation changes a parameter. This method will call the setParameter() method to change the value, and will then send a message to the host telling it about the change.

Note that to make sure the host correctly handles automation, you should call the beginParameterChangeGesture() and endParameterChangeGesture() methods to tell the host when the user has started and stopped changing the parameter.

virtual bool AudioProcessor::isParameterAutomatable ( int  parameterIndex) const
virtual

Returns true if the host can automate this parameter.

By default, this returns true for all parameters.

virtual bool AudioProcessor::isMetaParameter ( int  parameterIndex) const
virtual

Should return true if this parameter is a "meta" parameter.

A meta-parameter is a parameter that changes other params. It is used by some hosts (e.g. AudioUnit hosts).

By default this returns false.

void AudioProcessor::beginParameterChangeGesture ( int  parameterIndex)

Sends a signal to the host to tell it that the user is about to start changing this parameter.

This allows the host to know when a parameter is actively being held by the user, and it may use this information to help it record automation.

If you call this, it must be matched by a later call to endParameterChangeGesture().

void AudioProcessor::endParameterChangeGesture ( int  parameterIndex)

Tells the host that the user has finished changing this parameter.

This allows the host to know when a parameter is actively being held by the user, and it may use this information to help it record automation.

A call to this method must follow a call to beginParameterChangeGesture().

void AudioProcessor::updateHostDisplay ( )

The filter can call this when something (apart from a parameter value) has changed.

It sends a hint to the host that something like the program, number of parameters, etc, has changed, and that it should update itself.

virtual int AudioProcessor::getNumPrograms ( )
pure 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.

Implemented in AudioProcessorGraph, and AudioProcessorGraph::AudioGraphIOProcessor.

virtual int AudioProcessor::getCurrentProgram ( )
pure virtual

Returns the number of the currently active program.

Implemented in AudioProcessorGraph, and AudioProcessorGraph::AudioGraphIOProcessor.

virtual void AudioProcessor::setCurrentProgram ( int  index)
pure virtual

Called by the host to change the current program.

Implemented in AudioProcessorGraph, and AudioProcessorGraph::AudioGraphIOProcessor.

virtual const String AudioProcessor::getProgramName ( int  index)
pure virtual

Must return the name of a given program.

Implemented in AudioProcessorGraph, and AudioProcessorGraph::AudioGraphIOProcessor.

virtual void AudioProcessor::changeProgramName ( int  index,
const String newName 
)
pure virtual

Called by the host to rename a program.

Implemented in AudioProcessorGraph, and AudioProcessorGraph::AudioGraphIOProcessor.

virtual void AudioProcessor::getStateInformation ( juce::MemoryBlock &  destData)
pure 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

Implemented in AudioProcessorGraph, and AudioProcessorGraph::AudioGraphIOProcessor.

Referenced by StandaloneFilterWindow::saveState(), and StandaloneFilterWindow::~StandaloneFilterWindow().

virtual void AudioProcessor::getCurrentProgramStateInformation ( juce::MemoryBlock &  destData)
virtual

The host will call this method if it wants to save the state of just the filter's current program.

Unlike getStateInformation, this should only return the current program's state.

Not all hosts support this, and if you don't implement it, the base class method just calls getStateInformation() instead. If you do implement it, be sure to also implement getCurrentProgramStateInformation.

See Also
getStateInformation, setCurrentProgramStateInformation
virtual void AudioProcessor::setStateInformation ( const void *  data,
int  sizeInBytes 
)
pure 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

Implemented in AudioProcessorGraph, and AudioProcessorGraph::AudioGraphIOProcessor.

Referenced by StandaloneFilterWindow::loadState(), and StandaloneFilterWindow::StandaloneFilterWindow().

virtual void AudioProcessor::setCurrentProgramStateInformation ( const void *  data,
int  sizeInBytes 
)
virtual

The host will call this method if it wants to restore the state of just the filter's current program.

Not all hosts support this, and if you don't implement it, the base class method just calls setStateInformation() instead. If you do implement it, be sure to also implement getCurrentProgramStateInformation.

See Also
setStateInformation, getCurrentProgramStateInformation
virtual void AudioProcessor::numChannelsChanged ( )
virtual

This method is called when the number of input or output channels is changed.

virtual void AudioProcessor::addListener ( AudioProcessorListener newListener)
virtual

Adds a listener that will be called when an aspect of this processor changes.

virtual void AudioProcessor::removeListener ( AudioProcessorListener listenerToRemove)
virtual

Removes a previously added listener.

virtual void AudioProcessor::setPlayHead ( AudioPlayHead newPlayHead)
virtual

Tells the processor to use this playhead object.

The processor will not take ownership of the object, so the caller must delete it when it is no longer being used.

void AudioProcessor::setPlayConfigDetails ( int  numIns,
int  numOuts,
double  sampleRate,
int  blockSize 
)
noexcept

This is called by the processor to specify its details before being played.

Referenced by StandaloneFilterWindow::StandaloneFilterWindow().

void AudioProcessor::editorBeingDeleted ( AudioProcessorEditor )
noexcept

Not for public use - this is called before deleting an editor component.

void AudioProcessor::setSpeakerArrangement ( const String inputs,
const String outputs 
)

Not for public use - this is called to initialise the processor before playing.

static void AudioProcessor::copyXmlToBinary ( const XmlElement xml,
juce::MemoryBlock &  destData 
)
static

Helper function that just converts an xml element into a binary blob.

Use this in your filter's getStateInformation() method if you want to store its state as xml.

Then use getXmlFromBinary() to reverse this operation and retrieve the XML from a binary blob.

static XmlElement* AudioProcessor::getXmlFromBinary ( const void *  data,
int  sizeInBytes 
)
static

Retrieves an XML element that was stored as binary with the copyXmlToBinary() method.

This might return nullptr if the data's unsuitable or corrupted. Otherwise it will return an XmlElement object that the caller must delete when no longer needed.

static void JUCE_CALLTYPE AudioProcessor::setTypeOfNextNewPlugin ( WrapperType  )
static
void AudioProcessor::sendParamChangeMessageToListeners ( int  parameterIndex,
float  newValue 
)
protected

Member Data Documentation

WrapperType AudioProcessor::wrapperType

When loaded by a plugin wrapper, this flag will be set to indicate the type of plugin within which the processor is running.

AudioPlayHead* AudioProcessor::playHead
protected

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