JUCE  v5.1.1-3-g1a0b28c73
JUCE API
AudioProcessor Class Referenceabstract

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

#include <juce_AudioProcessor.h>

Inheritance diagram for AudioProcessor:
Collaboration diagram for AudioProcessor:

Classes

class  Bus
 Describes the layout and properties of an audio bus. More...
 
struct  BusesLayout
 Represents the bus layout state of a plug-in. More...
 
struct  BusesProperties
 
struct  BusProperties
 Structure used for AudioProcessor Callbacks. More...
 
struct  InOutChannelPair
 

Public Types

enum  ProcessingPrecision {
  singlePrecision,
  doublePrecision
}
 
enum  WrapperType {
  wrapperType_Undefined = 0,
  wrapperType_VST,
  wrapperType_VST3,
  wrapperType_AudioUnit,
  wrapperType_AudioUnitv3,
  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. More...
 
virtual bool acceptsMidi () const =0
 Returns true if the processor wants midi messages. More...
 
bool addBus (bool isInput)
 Dynamically request an additional bus. More...
 
virtual void addListener (AudioProcessorListener *newListener)
 Adds a listener that will be called when an aspect of this processor changes. More...
 
void addParameter (AudioProcessorParameter *)
 Adds a parameter to the list. More...
 
void beginParameterChangeGesture (int parameterIndex)
 Sends a signal to the host to tell it that the user is about to start changing this parameter. More...
 
virtual bool canAddBus (bool isInput) const
 Callback to query if a bus can currently be added. More...
 
virtual bool canRemoveBus (bool isInput) const
 Callback to query if the last bus can currently be removed. More...
 
virtual void changeProgramName (int index, const String &newName)=0
 Called by the host to rename a program. More...
 
bool checkBusesLayoutSupported (const BusesLayout &) const
 Returns true if the Audio processor is likely to support a given layout. More...
 
virtual AudioProcessorEditorcreateEditor ()=0
 Creates the filter's UI. More...
 
AudioProcessorEditorcreateEditorIfNeeded ()
 Returns the active editor, or if there isn't one, it will create one. More...
 
bool disableNonMainBuses ()
 Disables all non-main buses (aux and sidechains). More...
 
void editorBeingDeleted (AudioProcessorEditor *) noexcept
 Not for public use - this is called before deleting an editor component. More...
 
bool enableAllBuses ()
 Enables all buses. More...
 
void endParameterChangeGesture (int parameterIndex)
 Tells the host that the user has finished changing this parameter. More...
 
virtual int32 getAAXPluginIDForMainBusConfig (const AudioChannelSet &mainInputLayout, const AudioChannelSet &mainOutputLayout, bool idForAudioSuite) const
 AAX plug-ins need to report a unique "plug-in id" for every audio layout configuration that your AudioProcessor supports on the main bus. More...
 
AudioProcessorEditorgetActiveEditor () const noexcept
 Returns the active editor, if there is one. More...
 
virtual StringArray getAlternateDisplayNames () const
 Returns a list of alternative names to use for this processor. More...
 
int getBlockSize () const noexcept
 Returns the current typical block size that is being used. More...
 
BusgetBus (bool isInput, int busIdx) noexcept
 Returns the audio bus with a given index and direction. More...
 
const BusgetBus (bool isInput, int busIdx) const noexcept
 Returns the audio bus with a given index and direction. More...
 
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. More...
 
int getBusCount (bool isInput) const noexcept
 Returns the number of buses on the input or output side. More...
 
BusesLayout getBusesLayout () const
 Provides the current channel layouts of this audio processor. More...
 
const CriticalSectiongetCallbackLock () const noexcept
 This returns a critical section that will automatically be locked while the host is calling the processBlock() method. More...
 
int getChannelCountOfBus (bool isInput, int busIdx) const noexcept
 Provides the number of channels of the bus with a given index and direction. More...
 
int getChannelIndexInProcessBlockBuffer (bool isInput, int busIndex, int channelIndex) const noexcept
 Returns the position of a bus's channels within the processBlock buffer. More...
 
AudioChannelSet getChannelLayoutOfBus (bool isInput, int busIndex) const noexcept
 Provides the channel layout of the bus with a given index and direction. More...
 
virtual int getCurrentProgram ()=0
 Returns the number of the currently active program. More...
 
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. More...
 
int getLatencySamples () const noexcept
 This returns the number of samples delay that the filter imposes on the audio passing through it. More...
 
int getMainBusNumInputChannels () const noexcept
 Returns the number of input channels on the main bus. More...
 
int getMainBusNumOutputChannels () const noexcept
 Returns the number of output channels on the main bus. More...
 
virtual const String getName () const =0
 Returns the name of this processor. More...
 
template<int numLayouts>
BusesLayout getNextBestLayoutInLayoutList (const BusesLayout &layouts, const short(&channelLayoutList) [numLayouts][2])
 Returns the next best layout which is contained in a channel layout map. More...
 
virtual int getNumParameters ()
 This must return the correct value immediately after the object has been created, and mustn't change the number of parameters later. More...
 
virtual int getNumPrograms ()=0
 Returns the number of preset programs the filter supports. More...
 
int getOffsetInBusBufferForAbsoluteChannelIndex (bool isInput, int absoluteChannelIndex, int &busIdx) const noexcept
 Returns the offset in a bus's buffer from an absolute channel indes. More...
 
virtual float getParameter (int parameterIndex)
 Called by the host to find out the value of one of the filter's parameters. More...
 
virtual AudioProcessorParameter::Category getParameterCategory (int parameterIndex) const
 Should return the parameter's category. More...
 
virtual float getParameterDefaultValue (int parameterIndex)
 Returns the default value for the parameter. More...
 
virtual String getParameterID (int index)
 Returns the ID of a particular parameter. More...
 
virtual String getParameterLabel (int index) const
 Some plugin types may be able to return a label string for a parameter's units. More...
 
virtual const String getParameterName (int parameterIndex)
 Returns the name of a particular parameter. More...
 
virtual String getParameterName (int parameterIndex, int maximumStringLength)
 Returns the name of a parameter as a text string with a preferred maximum length. More...
 
virtual int getParameterNumSteps (int parameterIndex)
 Returns the number of discrete steps that this parameter can represent. More...
 
const OwnedArray< AudioProcessorParameter > & getParameters () const noexcept
 Returns the current list of parameters. More...
 
virtual const String getParameterText (int parameterIndex)
 Returns the value of a parameter as a text string. More...
 
virtual String getParameterText (int parameterIndex, int maximumStringLength)
 Returns the value of a parameter as a text string with a preferred maximum length. More...
 
AudioPlayHeadgetPlayHead () const noexcept
 Returns the current AudioPlayHead object that should be used to find out the state and position of the playhead. More...
 
ProcessingPrecision getProcessingPrecision () const noexcept
 Returns the precision-mode of the processor. More...
 
virtual const String getProgramName (int index)=0
 Must return the name of a given program. More...
 
double getSampleRate () const noexcept
 Returns the current sample rate. More...
 
virtual void getStateInformation (juce::MemoryBlock &destData)=0
 The host will call this method when it wants to save the filter's internal state. More...
 
virtual double getTailLengthSeconds () const =0
 Returns the length of the filter's tail, in seconds. More...
 
int getTotalNumInputChannels () const noexcept
 Returns the total number of input channels. More...
 
int getTotalNumOutputChannels () const noexcept
 Returns the total number of output channels. More...
 
virtual bool hasEditor () const =0
 Your filter must override this and return true if it can create an editor component. More...
 
virtual bool isMetaParameter (int parameterIndex) const
 Should return true if this parameter is a "meta" parameter. More...
 
virtual bool isMidiEffect () const
 Returns true if this is a midi effect plug-in and does no audio processing. More...
 
bool isNonRealtime () const noexcept
 Returns true if the processor is being run in an offline mode for rendering. More...
 
virtual bool isParameterAutomatable (int parameterIndex) const
 Returns true if the host can automate this parameter. More...
 
virtual bool isParameterOrientationInverted (int index) const
 This can be overridden to tell the host that particular parameters operate in the reverse direction. More...
 
bool isSuspended () const noexcept
 Returns true if processing is currently suspended. More...
 
bool isUsingDoublePrecision () const noexcept
 Returns true if the current precision is set to doublePrecision. More...
 
virtual void numBusesChanged ()
 This method is called when the number of buses is changed. More...
 
virtual void numChannelsChanged ()
 This method is called when the total number of input or output channels is changed. More...
 
virtual void prepareToPlay (double sampleRate, int maximumExpectedSamplesPerBlock)=0
 Called before playback starts, to let the filter prepare itself. More...
 
virtual void processBlock (AudioBuffer< float > &buffer, MidiBuffer &midiMessages)=0
 Renders the next block. More...
 
virtual void processBlock (AudioBuffer< double > &buffer, MidiBuffer &midiMessages)
 Renders the next block. More...
 
virtual void processBlockBypassed (AudioBuffer< float > &buffer, MidiBuffer &midiMessages)
 Renders the next block when the processor is being bypassed. More...
 
virtual void processBlockBypassed (AudioBuffer< double > &buffer, MidiBuffer &midiMessages)
 Renders the next block when the processor is being bypassed. More...
 
virtual void processorLayoutsChanged ()
 This method is called when the layout of the audio processor changes. More...
 
virtual bool producesMidi () const =0
 Returns true if the processor produces midi messages. More...
 
virtual void releaseResources ()=0
 Called after playback has stopped, to let the filter free up any resources it no longer needs. More...
 
bool removeBus (bool isInput)
 Dynamically remove the latest added bus. More...
 
virtual void removeListener (AudioProcessorListener *listenerToRemove)
 Removes a previously added listener. More...
 
virtual void reset ()
 A plugin can override this to be told when it should reset any playing voices. More...
 
bool setBusesLayout (const BusesLayout &)
 Set the channel layouts of this audio processor. More...
 
bool setBusesLayoutWithoutEnabling (const BusesLayout &)
 Set the channel layouts of this audio processor without changing the enablement state of the buses. More...
 
bool setChannelLayoutOfBus (bool isInput, int busIdx, const AudioChannelSet &layout)
 Set the channel layout of the bus with a given index and direction. More...
 
virtual void setCurrentProgram (int index)=0
 Called by the host to change the current program. More...
 
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. More...
 
void setLatencySamples (int newLatency)
 The filter should call this to set the number of samples delay that it introduces. More...
 
virtual 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. More...
 
virtual void setParameter (int parameterIndex, float newValue)
 The host will call this method to change the value of one of the filter's parameters. More...
 
void setParameterNotifyingHost (int parameterIndex, float newValue)
 Your filter can call this when it needs to change one of its parameters. More...
 
void setPlayConfigDetails (int numIns, int numOuts, double sampleRate, int blockSize)
 This is called by the processor to specify its details before being played. More...
 
virtual void setPlayHead (AudioPlayHead *newPlayHead)
 Tells the processor to use this playhead object. More...
 
void setProcessingPrecision (ProcessingPrecision newPrecision) noexcept
 Changes the processing precision of the receiver. More...
 
void setRateAndBufferSizeDetails (double sampleRate, int blockSize) noexcept
 This is called by the processor to specify its details before being played. More...
 
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(). More...
 
virtual bool supportsDoublePrecisionProcessing () const
 Returns true if the Audio processor supports double precision floating point processing. More...
 
virtual bool supportsMPE () const
 Returns true if the processor supports MPE. More...
 
void suspendProcessing (bool shouldBeSuspended)
 Enables and disables the processing callback. More...
 
void updateHostDisplay ()
 The filter can call this when something (apart from a parameter value) has changed. More...
 

Static Public Member Functions

template<int numLayouts>
static bool containsLayout (const BusesLayout &layouts, const short(&channelLayoutList) [numLayouts][2])
 Returns true if the channel layout map contains a certain layout. More...
 
static void copyXmlToBinary (const XmlElement &xml, juce::MemoryBlock &destData)
 Helper function that just converts an xml element into a binary blob. More...
 
static int getDefaultNumParameterSteps () noexcept
 Returns the default number of steps for a parameter. More...
 
static XmlElementgetXmlFromBinary (const void *data, int sizeInBytes)
 Retrieves an XML element that was stored as binary with the copyXmlToBinary() method. More...
 
static void 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. More...
 

Protected Member Functions

 AudioProcessor ()
 Constructor. More...
 
 AudioProcessor (const BusesProperties &ioLayouts)
 Constructor for multibus AudioProcessors. More...
 
template<int numLayouts>
 AudioProcessor (const short(&channelLayoutList) [numLayouts][2])
 Constructor for AudioProcessors which use layout maps. More...
 
virtual bool canApplyBusCountChange (bool isInput, bool isAddingBuses, BusProperties &outNewBusProperties)
 Callback to query if adding/removing buses currently possible. More...
 
virtual bool canApplyBusesLayout (const BusesLayout &layouts) const
 Callback to check if a certain bus layout can now be applied. More...
 
virtual bool isBusesLayoutSupported (const BusesLayout &) const
 Callback to query if the AudioProcessor supports a specific layout. More...
 
void sendParamChangeMessageToListeners (int parameterIndex, float newValue)
 

Protected Attributes

AudioPlayHeadplayHead
 

Private Member Functions

bool applyBusLayouts (const BusesLayout &)
 
void audioIOChanged (bool busNumberChanged, bool channelNumChanged)
 
void createBus (bool isInput, const BusProperties &)
 
AudioProcessorListenergetListenerLocked (int) const noexcept
 
void getNextBestLayout (const BusesLayout &, BusesLayout &) const
 
BusesLayout getNextBestLayoutInList (const BusesLayout &, const Array< InOutChannelPair > &) const
 
AudioProcessorParametergetParamChecked (int) const noexcept
 
void initialise (const BusesProperties &)
 
template<typename floatType >
void processBypassed (AudioBuffer< floatType > &, MidiBuffer &)
 
void updateSpeakerFormatStrings ()
 

Static Private Member Functions

static BusesProperties busesPropertiesFromLayoutArray (const Array< InOutChannelPair > &)
 
static bool containsLayout (const BusesLayout &, const Array< InOutChannelPair > &)
 
template<int numLayouts>
static Array< InOutChannelPairlayoutListToArray (const short(&configuration) [numLayouts][2])
 

Private Attributes

Component::SafePointer< AudioProcessorEditoractiveEditor
 
int blockSize
 
String cachedInputSpeakerArrString
 
String cachedOutputSpeakerArrString
 
int cachedTotalIns
 
int cachedTotalOuts
 
CriticalSection callbackLock
 
BigInteger changingParams
 
double currentSampleRate
 
OwnedArray< BusinputBuses
 
int latencySamples
 
CriticalSection listenerLock
 
Array< AudioProcessorListener * > listeners
 
OwnedArray< AudioProcessorParametermanagedParameters
 
bool nonRealtime
 
OwnedArray< BusoutputBuses
 
ProcessingPrecision processingPrecision
 
bool suspended
 
bool textRecursionCheck
 

Friends

class Bus
 
struct PluginBusUtilities
 

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

◆ ProcessingPrecision

Enumerator
singlePrecision 
doublePrecision 

◆ WrapperType

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_AudioUnitv3 
wrapperType_RTAS 
wrapperType_AAX 
wrapperType_Standalone 

Constructor & Destructor Documentation

◆ AudioProcessor() [1/3]

AudioProcessor::AudioProcessor ( )
protected

Constructor.

This constructor will create a main input and output bus which are diabled by default. If you need more fine grain control then use the other constructors.

◆ AudioProcessor() [2/3]

AudioProcessor::AudioProcessor ( const BusesProperties ioLayouts)
protected

Constructor for multibus AudioProcessors.

If your AudioProcessor supports multiple buses than use this constructor to initialise the bus layouts and bus names of your plug-in.

◆ AudioProcessor() [3/3]

template<int numLayouts>
AudioProcessor::AudioProcessor ( const short(&)  channelLayoutList[numLayouts][2])
inlineprotected

Constructor for AudioProcessors which use layout maps.

If your AudioProcessor uses layout maps then use this constructor.

◆ ~AudioProcessor()

virtual AudioProcessor::~AudioProcessor ( )
virtual

Destructor.

Member Function Documentation

◆ acceptsMidi()

virtual bool AudioProcessor::acceptsMidi ( ) const
pure virtual

Returns true if the processor wants midi messages.

Implemented in AudioProcessorGraph, and AudioProcessorGraph::AudioGraphIOProcessor.

Referenced by getLatencySamples(), and AudioProcessorGraph::AudioGraphIOProcessor::getParentGraph().

◆ addBus()

bool AudioProcessor::addBus ( bool  isInput)

Dynamically request an additional bus.

Request an additional bus from the audio processor. If the audio processor does not support adding additional buses then this method will return false.

Most audio processors will not allow you to dynamically add/remove audio buses and will return false.

This method will invoke the canApplyBusCountChange callback to probe if a bus can be added and, if yes, will use the supplied bus properties of the canApplyBusCountChange callback to create a new bus.

See also
canApplyBusCountChange, removeBus

Referenced by canRemoveBus().

◆ addListener()

virtual void AudioProcessor::addListener ( AudioProcessorListener newListener)
virtual

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

Referenced by getActiveEditor().

◆ addParameter()

void AudioProcessor::addParameter ( AudioProcessorParameter )

Adds a parameter to the list.

The parameter object will be managed and deleted automatically by the list when no longer needed.

Referenced by getActiveEditor().

◆ applyBusLayouts()

bool AudioProcessor::applyBusLayouts ( const BusesLayout )
private

◆ audioIOChanged()

void AudioProcessor::audioIOChanged ( bool  busNumberChanged,
bool  channelNumChanged 
)
private

◆ beginParameterChangeGesture()

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

NOTE! This method will eventually be deprecated! It's recommended that you use AudioProcessorParameter::beginChangeGesture() instead.

Referenced by getActiveEditor().

◆ busesPropertiesFromLayoutArray()

static BusesProperties AudioProcessor::busesPropertiesFromLayoutArray ( const Array< InOutChannelPair > &  )
staticprivate

◆ canAddBus()

virtual bool AudioProcessor::canAddBus ( bool  isInput) const
inlinevirtual

Callback to query if a bus can currently be added.

This callback probes if a bus can currently be added. You should override this callback if you want to support dynamically adding/removing buses by the host. This is useful for mixer audio processors.

The default implementation will always return false.

See also
addBus

References juce::ignoreUnused().

◆ canApplyBusCountChange()

virtual bool AudioProcessor::canApplyBusCountChange ( bool  isInput,
bool  isAddingBuses,
BusProperties outNewBusProperties 
)
protectedvirtual

Callback to query if adding/removing buses currently possible.

This callback is called when the host calls addBus or removeBus. Similar to canApplyBusesLayout, this callback is only called while the AudioProcessor is stopped and gives the processor a last chance to reject a requested bus change. It can also be used to apply the bus count change to an underlying wrapped plug-in.

When adding a bus, isAddingBuses will be true and the plug-in is expected to fill out outNewBusProperties with the properties of the bus which will be created just after the succesful return of this callback.

Implementations of AudioProcessor will rarely need to override this method. Only override this method if your processor supports adding and removing buses and if it needs more fine grain control over the naming of new buses or may reject bus number changes although canAddBus or canRemoveBus returned true.

The default implementation will return false if canAddBus/canRemoveBus returns false (the default behavior). Otherwise, this method returns "Input #busIdx" for input buses and "Output #busIdx" for output buses where busIdx is the index for newly created buses. The default layout in this case will be the layout of the previous bus of the same direction.

◆ canApplyBusesLayout()

virtual bool AudioProcessor::canApplyBusesLayout ( const BusesLayout layouts) const
inlineprotectedvirtual

Callback to check if a certain bus layout can now be applied.

Most subclasses will not need to override this method and should instead override the isBusesLayoutSupported callback to reject certain layout changes.

This callback is called when the user requests a layout change. It will only be called if processing of the AudioProcessor has been stopped by a previous call to releaseResources or after the construction of the AudioProcessor. It will be called just before the actual layout change. By returning false you will abort the layout change and setBusesLayout will return false indicating that the layout change was not successful.

The default implementation will simply call isBusesLayoutSupported.

You only need to override this method if there is a chance that your AudioProcessor may not accept a layout although you have previously claimed to support it via the isBusesLayoutSupported callback. This can occur if your AudioProcessor's supported layouts depend on other plug-in parameters which may have changed since the last call to isBusesLayoutSupported, such as the format of an audio file which can be selected by the user in the AudioProcessor's editor. This callback gives the AudioProcessor a last chance to reject a layout if conditions have changed as it is always called just before the actual layout change.

As it is never called while the AudioProcessor is processing audio, it can also be used for AudioProcessors which wrap other plug-in formats to apply the current layout to the underlying plug-in. This callback gives such AudioProcessors a chance to reject the layout change should an error occur with the underlying plug-in during the layout change.

See also
isBusesLayoutSupported, setBusesLayout

References isBusesLayoutSupported().

◆ canRemoveBus()

virtual bool AudioProcessor::canRemoveBus ( bool  isInput) const
inlinevirtual

Callback to query if the last bus can currently be removed.

This callback probes if the last bus can currently be removed. You should override this callback if you want to support dynamically adding/removing buses by the host. This is useful for mixer audio processors.

If you return true in this callback then the AudioProcessor will go ahead and delete the bus.

The default implementation will always return false.

References addBus(), getBusesLayout(), getChannelLayoutOfBus(), juce::ignoreUnused(), removeBus(), setBusesLayout(), setBusesLayoutWithoutEnabling(), and setChannelLayoutOfBus().

◆ changeProgramName()

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

◆ checkBusesLayoutSupported()

bool AudioProcessor::checkBusesLayoutSupported ( const BusesLayout ) const

Returns true if the Audio processor is likely to support a given layout.

This can be called regardless if the processor is currently running.

Referenced by getBusBuffer().

◆ containsLayout() [1/2]

template<int numLayouts>
static bool AudioProcessor::containsLayout ( const BusesLayout layouts,
const short(&)  channelLayoutList[numLayouts][2] 
)
inlinestatic

Returns true if the channel layout map contains a certain layout.

You can use this method to help you implement the checkBusesLayoutSupported method. For example

bool checkBusesLayoutSupported (const BusesLayout& layouts) override
{
return containsLayout (layouts, {{1,1},{2,2}});
}

References layoutListToArray().

Referenced by getMainBusNumOutputChannels().

◆ containsLayout() [2/2]

static bool AudioProcessor::containsLayout ( const BusesLayout ,
const Array< InOutChannelPair > &   
)
staticprivate

◆ copyXmlToBinary()

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.

◆ createBus()

void AudioProcessor::createBus ( bool  isInput,
const BusProperties  
)
private

◆ createEditor()

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.

Referenced by AudioProcessorGraph::AudioGraphIOProcessor::getParentGraph(), and isNonRealtime().

◆ createEditorIfNeeded()

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 getActiveEditor().

◆ disableNonMainBuses()

bool AudioProcessor::disableNonMainBuses ( )

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

Referenced by StandalonePluginHolder::createPlugin(), and getChannelCountOfBus().

◆ editorBeingDeleted()

void AudioProcessor::editorBeingDeleted ( AudioProcessorEditor )
noexcept

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

Referenced by getActiveEditor().

◆ enableAllBuses()

bool AudioProcessor::enableAllBuses ( )

Enables all buses.

Referenced by getChannelCountOfBus().

◆ 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().

NOTE! This method will eventually be deprecated! It's recommended that you use AudioProcessorParameter::endChangeGesture() instead.

Referenced by getActiveEditor().

◆ getAAXPluginIDForMainBusConfig()

virtual int32 AudioProcessor::getAAXPluginIDForMainBusConfig ( const AudioChannelSet mainInputLayout,
const AudioChannelSet mainOutputLayout,
bool  idForAudioSuite 
) const
virtual

AAX plug-ins need to report a unique "plug-in id" for every audio layout configuration that your AudioProcessor supports on the main bus.

Override this function if you want your AudioProcessor to use a custom "plug-in id" (for example to stay backward compatible with older versions of JUCE).

The default implementation will compute a unique integer from the input and output layout and add this value to the 4 character code 'jcaa' (for native AAX) or 'jyaa' (for AudioSuite plug-ins).

Referenced by getActiveEditor().

◆ getActiveEditor()

◆ getAlternateDisplayNames()

virtual StringArray AudioProcessor::getAlternateDisplayNames ( ) const
virtual

Returns a list of alternative names to use for this processor.

Some hosts truncate the name of your AudioProcessor when there isn't enough space in the GUI to show the full name. Overriding this method, allows the host to choose an alternative name (such as an abbreviation) to better fit the available space.

◆ getBlockSize()

int AudioProcessor::getBlockSize ( ) const
inlinenoexcept

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.

References blockSize.

◆ getBus() [1/2]

Bus* AudioProcessor::getBus ( bool  isInput,
int  busIdx 
)
inlinenoexcept

Returns the audio bus with a given index and direction.

If busIdx is invalid then this method will return a nullptr.

References inputBuses, and outputBuses.

Referenced by AudioUnitHelpers::getAUChannelInfo(), getBus(), getChannelCountOfBus(), and AudioUnitHelpers::isLayoutSupported().

◆ getBus() [2/2]

const Bus* AudioProcessor::getBus ( bool  isInput,
int  busIdx 
) const
inlinenoexcept

Returns the audio bus with a given index and direction.

If busIdx is invalid then this method will return a nullptr.

References getBus().

◆ getBusBuffer()

template<typename FloatType >
AudioBuffer<FloatType> AudioProcessor::getBusBuffer ( AudioBuffer< FloatType > &  processBlockBuffer,
bool  isInput,
int  busIndex 
) const
inline

Returns an AudioBuffer containing a set of channel pointers for a specific bus.

This can be called in processBlock to get a buffer containing a sub-group of the master AudioSampleBuffer which contains all the plugin channels.

References checkBusesLayoutSupported(), AudioBuffer< Type >::getArrayOfWritePointers(), getChannelCountOfBus(), getChannelIndexInProcessBlockBuffer(), AudioBuffer< Type >::getNumSamples(), and supportsDoublePrecisionProcessing().

◆ getBusCount()

int AudioProcessor::getBusCount ( bool  isInput) const
inlinenoexcept

Returns the number of buses on the input or output side.

References inputBuses, and outputBuses.

Referenced by AudioUnitHelpers::getBusCount(), AudioUnitHelpers::getBusesLayout(), and AudioUnitHelpers::setBusesLayout().

◆ getBusesLayout()

BusesLayout AudioProcessor::getBusesLayout ( ) const

Provides the current channel layouts of this audio processor.

Referenced by canRemoveBus(), AudioUnitHelpers::getAUChannelInfo(), and AudioUnitHelpers::getBusesLayout().

◆ getCallbackLock()

const CriticalSection& AudioProcessor::getCallbackLock ( ) const
inlinenoexcept

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

References callbackLock, and suspendProcessing().

◆ getChannelCountOfBus()

int AudioProcessor::getChannelCountOfBus ( bool  isInput,
int  busIdx 
) const
inlinenoexcept

Provides the number of channels of the bus with a given index and direction.

If the index, direction combination is invalid then this will return zero.

References disableNonMainBuses(), enableAllBuses(), getBus(), getChannelIndexInProcessBlockBuffer(), and getOffsetInBusBufferForAbsoluteChannelIndex().

Referenced by AudioUnitHelpers::getAUChannelInfo(), getBusBuffer(), getMainBusNumInputChannels(), getMainBusNumOutputChannels(), and AudioUnitHelpers::ChannelRemapper::initializeChannelMapArray().

◆ getChannelIndexInProcessBlockBuffer()

int AudioProcessor::getChannelIndexInProcessBlockBuffer ( bool  isInput,
int  busIndex,
int  channelIndex 
) const
noexcept

Returns the position of a bus's channels within the processBlock buffer.

This can be called in processBlock to figure out which channel of the master AudioSampleBuffer maps onto a specific bus's channel.

Referenced by getBusBuffer(), and getChannelCountOfBus().

◆ getChannelLayoutOfBus()

AudioChannelSet AudioProcessor::getChannelLayoutOfBus ( bool  isInput,
int  busIndex 
) const
noexcept

Provides the channel layout of the bus with a given index and direction.

If the index, direction combination is invalid then this will return an AudioChannelSet with no channels.

Referenced by canRemoveBus(), and AudioUnitHelpers::ChannelRemapper::fillLayoutChannelMaps().

◆ getCurrentProgram()

virtual int AudioProcessor::getCurrentProgram ( )
pure virtual

Returns the number of the currently active program.

Implemented in AudioProcessorGraph, and AudioProcessorGraph::AudioGraphIOProcessor.

Referenced by getActiveEditor(), and AudioProcessorGraph::AudioGraphIOProcessor::getParentGraph().

◆ getCurrentProgramStateInformation()

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

Referenced by getActiveEditor().

◆ getDefaultNumParameterSteps()

static int AudioProcessor::getDefaultNumParameterSteps ( )
staticnoexcept

Returns the default number of steps for a parameter.

NOTE! This method will eventually be deprecated! It's recommended that you use AudioProcessorParameter::getNumSteps() instead.

See also
getParameterNumSteps

Referenced by getActiveEditor().

◆ getLatencySamples()

int AudioProcessor::getLatencySamples ( ) const
inlinenoexcept

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.

References acceptsMidi(), getTailLengthSeconds(), latencySamples, producesMidi(), and setLatencySamples().

◆ getListenerLocked()

AudioProcessorListener* AudioProcessor::getListenerLocked ( int  ) const
privatenoexcept

◆ getMainBusNumInputChannels()

int AudioProcessor::getMainBusNumInputChannels ( ) const
inlinenoexcept

◆ getMainBusNumOutputChannels()

int AudioProcessor::getMainBusNumOutputChannels ( ) const
inlinenoexcept

◆ getName()

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

◆ getNextBestLayout()

void AudioProcessor::getNextBestLayout ( const BusesLayout ,
BusesLayout  
) const
private

◆ getNextBestLayoutInLayoutList()

template<int numLayouts>
BusesLayout AudioProcessor::getNextBestLayoutInLayoutList ( const BusesLayout layouts,
const short(&)  channelLayoutList[numLayouts][2] 
)
inline

Returns the next best layout which is contained in a channel layout map.

You can use this mehtod to help you implement getNextBestLayout. For example:

BusesLayout getNextBestLayout (const BusesLayout& layouts) override
{
return getNextBestLayoutInLayoutList (layouts, {{1,1},{2,2}});
}

References getNextBestLayoutInList(), and layoutListToArray().

◆ getNextBestLayoutInList()

BusesLayout AudioProcessor::getNextBestLayoutInList ( const BusesLayout ,
const Array< InOutChannelPair > &   
) const
private

◆ getNumParameters()

virtual int AudioProcessor::getNumParameters ( )
virtual

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

NOTE! This method will eventually be deprecated! It's recommended that you use the AudioProcessorParameter class instead to manage your parameters.

Referenced by getActiveEditor().

◆ getNumPrograms()

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.

Referenced by getActiveEditor(), and AudioProcessorGraph::AudioGraphIOProcessor::getParentGraph().

◆ getOffsetInBusBufferForAbsoluteChannelIndex()

int AudioProcessor::getOffsetInBusBufferForAbsoluteChannelIndex ( bool  isInput,
int  absoluteChannelIndex,
int busIdx 
) const
noexcept

Returns the offset in a bus's buffer from an absolute channel indes.

This method returns the offset in a bus's buffer given an absolute channel index. It also provides the bus index. For example, this method would return one for a processor with two stereo buses when given the absolute channel index.

Referenced by getChannelCountOfBus().

◆ getParamChecked()

AudioProcessorParameter* AudioProcessor::getParamChecked ( int  ) const
privatenoexcept

◆ getParameter()

virtual float AudioProcessor::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.

NOTE! This method will eventually be deprecated! It's recommended that you use the AudioProcessorParameter class instead to manage your parameters.

Referenced by getActiveEditor().

◆ getParameterCategory()

virtual AudioProcessorParameter::Category AudioProcessor::getParameterCategory ( int  parameterIndex) const
virtual

Should return the parameter's category.

By default, this returns the "generic" category.

NOTE! This method will eventually be deprecated! It's recommended that you use AudioProcessorParameter::isMetaParameter() instead.

Referenced by getActiveEditor().

◆ getParameterDefaultValue()

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.

NOTE! This method will eventually be deprecated! It's recommended that you use AudioProcessorParameter::getDefaultValue() instead.

Referenced by getActiveEditor().

◆ getParameterID()

virtual String AudioProcessor::getParameterID ( int  index)
virtual

Returns the ID of a particular parameter.

The ID is used to communicate the value or mapping of a particular parameter with the host. By default this method will simply return a string representation of index.

NOTE! This method will eventually be deprecated! It's recommended that you use the AudioProcessorParameterWithID class instead to manage your parameters.

Referenced by getActiveEditor().

◆ getParameterLabel()

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

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

NOTE! This method will eventually be deprecated! It's recommended that you use AudioProcessorParameter::getLabel() instead.

Referenced by getActiveEditor().

◆ getParameterName() [1/2]

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

Returns the name of a particular parameter.

NOTE! This method will eventually be deprecated! It's recommended that you use the AudioProcessorParameter class instead to manage your parameters.

Referenced by getActiveEditor().

◆ getParameterName() [2/2]

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 getParameterName(int), and truncate the result.

NOTE! This method will eventually be deprecated! It's recommended that you use AudioProcessorParameter::getName() instead.

◆ getParameterNumSteps()

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 AudioProcessor::getDefaultNumParameterSteps(). 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.

NOTE! This method will eventually be deprecated! It's recommended that you use AudioProcessorParameter::getNumSteps() instead.

Referenced by getActiveEditor().

◆ getParameters()

const OwnedArray<AudioProcessorParameter>& AudioProcessor::getParameters ( ) const
noexcept

Returns the current list of parameters.

Referenced by getActiveEditor().

◆ getParameterText() [1/2]

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

Returns the value of a parameter as a text string.

NOTE! This method will eventually be deprecated! It's recommended that you use AudioProcessorParameter::getText() instead.

Referenced by getActiveEditor().

◆ getParameterText() [2/2]

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.

NOTE! This method will eventually be deprecated! It's recommended that you use AudioProcessorParameter::getText() instead.

◆ getPlayHead()

AudioPlayHead* AudioProcessor::getPlayHead ( ) const
inlinenoexcept

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

You can ONLY call this from your processBlock() method! Calling it at other times will produce undefined behaviour, as the host may not have any context in which a time would make sense, and some hosts will almost certainly have multithreading issues if it's not called on the audio thread.

The AudioPlayHead object that is returned can be used to get the details about the time of the start of the block currently being processed. But do not store this pointer or use it outside of the current audio callback, because the host may delete or re-use it.

If the host can't or won't provide any time info, this will return nullptr.

References playHead.

◆ getProcessingPrecision()

ProcessingPrecision AudioProcessor::getProcessingPrecision ( ) const
inlinenoexcept

Returns the precision-mode of the processor.

Depending on the result of this method you MUST call the corresponding version of processBlock. The default processing precision is single precision.

See also
setProcessingPrecision, supportsDoublePrecisionProcessing

References processingPrecision.

◆ getProgramName()

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

◆ getSampleRate()

double AudioProcessor::getSampleRate ( ) const
inlinenoexcept

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.

References currentSampleRate.

◆ getStateInformation()

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 StandalonePluginHolder::askUserToSaveState(), AudioProcessorGraph::changeProgramName(), getActiveEditor(), AudioProcessorGraph::AudioGraphIOProcessor::getParentGraph(), and StandalonePluginHolder::savePluginState().

◆ getTailLengthSeconds()

virtual double AudioProcessor::getTailLengthSeconds ( ) const
pure virtual

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

Implemented in AudioProcessorGraph, and AudioProcessorGraph::AudioGraphIOProcessor.

Referenced by getLatencySamples(), and AudioProcessorGraph::AudioGraphIOProcessor::getParentGraph().

◆ getTotalNumInputChannels()

int AudioProcessor::getTotalNumInputChannels ( ) const
inlinenoexcept

Returns the total number of input channels.

This method will return the total number of input channels by accumulating the number of channels on each input bus. The number of channels of the buffer passed to your processBlock callback will be equivalent to either getTotalNumInputChannels or getTotalNumOutputChannels - which ever is greater.

Note that getTotalNumInputChannels is equivalent to getMainBusNumInputChannels if your processor does not have any sidechains or aux buses.

References cachedTotalIns.

Referenced by AudioUnitHelpers::ChannelRemapper::initializeChannelMapArray().

◆ getTotalNumOutputChannels()

int AudioProcessor::getTotalNumOutputChannels ( ) const
inlinenoexcept

Returns the total number of output channels.

This method will return the total number of output channels by accumulating the number of channels on each output bus. The number of channels of the buffer passed to your processBlock callback will be equivalent to either getTotalNumInputChannels or getTotalNumOutputChannels - which ever is greater.

Note that getTotalNumOutputChannels is equivalent to getMainBusNumOutputChannels if your processor does not have any sidechains or aux buses.

References cachedTotalOuts.

Referenced by AudioUnitHelpers::ChannelRemapper::initializeChannelMapArray().

◆ getXmlFromBinary()

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.

◆ hasEditor()

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.

Referenced by AudioProcessorGraph::AudioGraphIOProcessor::getParentGraph(), and isNonRealtime().

◆ initialise()

void AudioProcessor::initialise ( const BusesProperties )
private

◆ isBusesLayoutSupported()

virtual bool AudioProcessor::isBusesLayoutSupported ( const BusesLayout ) const
inlineprotectedvirtual

Callback to query if the AudioProcessor supports a specific layout.

This callback is called when the host probes the supported bus layouts via the checkBusesLayoutSupported method. You should override this callback if you would like to limit the layouts that your AudioProcessor supports. The default implementation will accept any layout. JUCE does basic sanity checks so that the provided layouts parameter will have the same number of buses as your AudioProcessor.

See also
checkBusesLayoutSupported

Referenced by canApplyBusesLayout().

◆ isMetaParameter()

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.

NOTE! This method will eventually be deprecated! It's recommended that you use AudioProcessorParameter::isMetaParameter() instead.

Referenced by getActiveEditor().

◆ isMidiEffect()

virtual bool AudioProcessor::isMidiEffect ( ) const
inlinevirtual

Returns true if this is a midi effect plug-in and does no audio processing.

◆ isNonRealtime()

bool AudioProcessor::isNonRealtime ( ) const
inlinenoexcept

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()

References createEditor(), hasEditor(), nonRealtime, and setNonRealtime().

◆ isParameterAutomatable()

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.

NOTE! This method will eventually be deprecated! It's recommended that you use AudioProcessorParameter::isAutomatable() instead.

Referenced by getActiveEditor().

◆ isParameterOrientationInverted()

virtual bool AudioProcessor::isParameterOrientationInverted ( int  index) const
virtual

This can be overridden to tell the host that particular parameters operate in the reverse direction.

(Not all plugin formats or hosts will actually use this information).

NOTE! This method will eventually be deprecated! It's recommended that you use AudioProcessorParameter::isOrientationInverted() instead.

Referenced by getActiveEditor().

◆ isSuspended()

bool AudioProcessor::isSuspended ( ) const
inlinenoexcept

Returns true if processing is currently suspended.

See also
suspendProcessing

References reset(), and suspended.

◆ isUsingDoublePrecision()

bool AudioProcessor::isUsingDoublePrecision ( ) const
inlinenoexcept

Returns true if the current precision is set to doublePrecision.

References doublePrecision, processingPrecision, and setProcessingPrecision().

◆ layoutListToArray()

template<int numLayouts>
static Array<InOutChannelPair> AudioProcessor::layoutListToArray ( const short(&)  configuration[numLayouts][2])
inlinestaticprivate

◆ numBusesChanged()

virtual void AudioProcessor::numBusesChanged ( )
virtual

This method is called when the number of buses is changed.

Referenced by getActiveEditor().

◆ numChannelsChanged()

virtual void AudioProcessor::numChannelsChanged ( )
virtual

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

Referenced by getActiveEditor().

◆ prepareToPlay()

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

You can call getTotalNumInputChannels and getTotalNumOutputChannels or query the busLayout member variable to find out the number of channels your processBlock callback must process.

The maximumExpectedSamplesPerBlock value is a strong hint about the maximum number of samples that will be provided in each block. You may want to use this value to resize internal buffers. You should program defensively in case a buggy host exceeds this value. The actual block sizes that the host uses may be different each time the callback happens: completely variable block sizes can be expected from some hosts.

See also
busLayout, getTotalNumInputChannels, getTotalNumOutputChannels

Implemented in AudioProcessorGraph, and AudioProcessorGraph::AudioGraphIOProcessor.

Referenced by AudioProcessorGraph::AudioGraphIOProcessor::getParentGraph().

◆ processBlock() [1/2]

virtual void AudioProcessor::processBlock ( AudioBuffer< float > &  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 a total of 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 a total of 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!

If your plug-in has more than one input or output buses then the buffer passed to the processBlock methods will contain a bundle of all channels of each bus. Use AudiobusLayout::getBusBuffer to obtain an audio buffer for a particular bus.

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!

Also note that some hosts will occasionally decide to pass a buffer containing zero samples, so make sure that your algorithm can deal with that!

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.

See also
AudiobusLayout::getBusBuffer

Implemented in AudioProcessorGraph, and AudioProcessorGraph::AudioGraphIOProcessor.

Referenced by AudioProcessorGraph::AudioGraphIOProcessor::getParentGraph().

◆ processBlock() [2/2]

virtual void AudioProcessor::processBlock ( AudioBuffer< double > &  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 a combined total of 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!

If your plug-in has more than one input or output buses then the buffer passed to the processBlock methods will contain a bundle of all channels of each bus. Use AudiobusLayout::getBusBuffer to obtain a audio buffer for a particular bus.

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.

If your plugin uses buses, then you should use AudiobusLayout::getBusBuffer() or AudiobusLayout::getChannelIndexInProcessBlockBuffer() to find out which of the input and output channels correspond to which of the buses.

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!

Also note that some hosts will occasionally decide to pass a buffer containing zero samples, so make sure that your algorithm can deal with that!

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.

See also
AudiobusLayout::getBusBuffer

Reimplemented in AudioProcessorGraph, and AudioProcessorGraph::AudioGraphIOProcessor.

◆ processBlockBypassed() [1/2]

virtual void AudioProcessor::processBlockBypassed ( AudioBuffer< float > &  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.

◆ processBlockBypassed() [2/2]

virtual void AudioProcessor::processBlockBypassed ( AudioBuffer< double > &  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.

◆ processBypassed()

template<typename floatType >
void AudioProcessor::processBypassed ( AudioBuffer< floatType > &  ,
MidiBuffer  
)
private

◆ processorLayoutsChanged()

virtual void AudioProcessor::processorLayoutsChanged ( )
virtual

This method is called when the layout of the audio processor changes.

Referenced by getActiveEditor().

◆ producesMidi()

virtual bool AudioProcessor::producesMidi ( ) const
pure virtual

Returns true if the processor produces midi messages.

Implemented in AudioProcessorGraph, and AudioProcessorGraph::AudioGraphIOProcessor.

Referenced by getLatencySamples(), and AudioProcessorGraph::AudioGraphIOProcessor::getParentGraph().

◆ releaseResources()

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.

Referenced by AudioProcessorGraph::AudioGraphIOProcessor::getParentGraph().

◆ removeBus()

bool AudioProcessor::removeBus ( bool  isInput)

Dynamically remove the latest added bus.

Request the removal of the last bus from the audio processor. If the audio processor does not support removing buses then this method will return false.

Most audio processors will not allow you to dynamically add/remove audio buses and will return false.

The default implementation will return false.

This method will invoke the canApplyBusCountChange callback to probe if a bus can currently be removed and, if yes, will go ahead and remove it.

See also
addBus, canRemoveBus

Referenced by canRemoveBus().

◆ removeListener()

virtual void AudioProcessor::removeListener ( AudioProcessorListener listenerToRemove)
virtual

Removes a previously added listener.

Referenced by getActiveEditor().

◆ reset()

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.

Referenced by isSuspended().

◆ sendParamChangeMessageToListeners()

void AudioProcessor::sendParamChangeMessageToListeners ( int  parameterIndex,
float  newValue 
)
protected

◆ setBusesLayout()

bool AudioProcessor::setBusesLayout ( const BusesLayout )

Set the channel layouts of this audio processor.

If the layout is not supported by this audio processor then this method will return false. You can use the checkBusesLayoutSupported and getNextBestLayout methods to probe which layouts this audio processor supports.

Referenced by canRemoveBus(), and AudioUnitHelpers::setBusesLayout().

◆ setBusesLayoutWithoutEnabling()

bool AudioProcessor::setBusesLayoutWithoutEnabling ( const BusesLayout )

Set the channel layouts of this audio processor without changing the enablement state of the buses.

If the layout is not supported by this audio processor then this method will return false. You can use the checkBusesLayoutSupported methods to probe which layouts this audio processor supports.

Referenced by canRemoveBus().

◆ setChannelLayoutOfBus()

bool AudioProcessor::setChannelLayoutOfBus ( bool  isInput,
int  busIdx,
const AudioChannelSet layout 
)

Set the channel layout of the bus with a given index and direction.

If the index, direction combination is invalid or the layout is not supported by the audio processor then this method will return false.

Referenced by canRemoveBus().

◆ setCurrentProgram()

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

Called by the host to change the current program.

Implemented in AudioProcessorGraph, and AudioProcessorGraph::AudioGraphIOProcessor.

Referenced by getActiveEditor(), and AudioProcessorGraph::AudioGraphIOProcessor::getParentGraph().

◆ setCurrentProgramStateInformation()

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

Referenced by getActiveEditor().

◆ setLatencySamples()

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.

Referenced by getLatencySamples().

◆ setNonRealtime()

virtual void AudioProcessor::setNonRealtime ( bool  isNonRealtime)
virtualnoexcept

Called by the host to tell this processor whether it's being used in a non-realtime capacity for offline rendering or bouncing.

Reimplemented in AudioProcessorGraph.

Referenced by isNonRealtime().

◆ setParameter()

virtual void AudioProcessor::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.

NOTE! This method will eventually be deprecated! It's recommended that you use AudioProcessorParameter::setValue() instead.

Referenced by getActiveEditor().

◆ setParameterNotifyingHost()

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.

NOTE! This method will eventually be deprecated! It's recommended that you use AudioProcessorParameter::setValueNotifyingHost() instead.

Referenced by getActiveEditor().

◆ setPlayConfigDetails()

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

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

Use this version of the function if you are not interested in any sidechain and/or aux buses and do not care about the layout of channels. Otherwise use setRateAndBufferSizeDetails.

Referenced by getActiveEditor().

◆ setPlayHead()

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.

Reimplemented in AudioProcessorGraph.

Referenced by getActiveEditor(), and StandalonePluginHolder::startPlaying().

◆ setProcessingPrecision()

void AudioProcessor::setProcessingPrecision ( ProcessingPrecision  newPrecision)
noexcept

Changes the processing precision of the receiver.

A client of the AudioProcessor calls this function to indicate which version of processBlock (single or double precision) it intends to call. The client MUST call this function before calling the prepareToPlay method so that the receiver can do any necessary allocations in the prepareToPlay() method. An implementation of prepareToPlay() should call getProcessingPrecision() to determine with which precision it should allocate it's internal buffers.

Note that setting the processing precision to double floating point precision on a receiver which does not support double precision processing (i.e. supportsDoublePrecisionProcessing() returns false) will result in an assertion.

See also
getProcessingPrecision, supportsDoublePrecisionProcessing

Referenced by isUsingDoublePrecision().

◆ setRateAndBufferSizeDetails()

void AudioProcessor::setRateAndBufferSizeDetails ( double  sampleRate,
int  blockSize 
)
noexcept

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

You should call this function after having informed the processor about the channel and bus layouts via setBusesLayout.

See also
setBusesLayout

Referenced by StandalonePluginHolder::createPlugin(), and getActiveEditor().

◆ setStateInformation()

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 StandalonePluginHolder::askUserToLoadState(), AudioProcessorGraph::changeProgramName(), getActiveEditor(), AudioProcessorGraph::AudioGraphIOProcessor::getParentGraph(), and StandalonePluginHolder::reloadPluginState().

◆ setTypeOfNextNewPlugin()

static void AudioProcessor::setTypeOfNextNewPlugin ( WrapperType  )
static

◆ supportsDoublePrecisionProcessing()

virtual bool AudioProcessor::supportsDoublePrecisionProcessing ( ) const
virtual

Returns true if the Audio processor supports double precision floating point processing.

The default implementation will always return false. If you return true here then you must override the double precision versions of processBlock. Additionally, you must call getProcessingPrecision() in your prepareToPlay method to determine the precision with which you need to allocate your internal buffers.

See also
getProcessingPrecision, setProcessingPrecision

Reimplemented in AudioProcessorGraph, and AudioProcessorGraph::AudioGraphIOProcessor.

Referenced by getBusBuffer(), and AudioProcessorGraph::AudioGraphIOProcessor::getParentGraph().

◆ supportsMPE()

virtual bool AudioProcessor::supportsMPE ( ) const
inlinevirtual

Returns true if the processor supports MPE.

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

Any code that calls processBlock() should call isSuspended() before doing so, and if the processor is suspended, it should avoid the call and emit silence or whatever is appropriate.

See also
getCallbackLock

Referenced by getCallbackLock().

◆ updateHostDisplay()

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.

Referenced by getActiveEditor().

◆ updateSpeakerFormatStrings()

void AudioProcessor::updateSpeakerFormatStrings ( )
private

Friends And Related Function Documentation

◆ Bus

friend class Bus
friend

◆ PluginBusUtilities

friend struct PluginBusUtilities
friend

Member Data Documentation

◆ activeEditor

Component::SafePointer<AudioProcessorEditor> AudioProcessor::activeEditor
private

Referenced by getActiveEditor().

◆ blockSize

int AudioProcessor::blockSize
private

Referenced by getActiveEditor(), and getBlockSize().

◆ cachedInputSpeakerArrString

String AudioProcessor::cachedInputSpeakerArrString
private

◆ cachedOutputSpeakerArrString

String AudioProcessor::cachedOutputSpeakerArrString
private

◆ cachedTotalIns

int AudioProcessor::cachedTotalIns
private

◆ cachedTotalOuts

int AudioProcessor::cachedTotalOuts
private

◆ callbackLock

CriticalSection AudioProcessor::callbackLock
private

Referenced by getCallbackLock().

◆ changingParams

BigInteger AudioProcessor::changingParams
private

◆ currentSampleRate

double AudioProcessor::currentSampleRate
private

Referenced by getSampleRate().

◆ inputBuses

OwnedArray<Bus> AudioProcessor::inputBuses
mutableprivate

Referenced by getBus(), and getBusCount().

◆ latencySamples

int AudioProcessor::latencySamples
private

Referenced by getLatencySamples().

◆ listenerLock

CriticalSection AudioProcessor::listenerLock
private

◆ listeners

Array<AudioProcessorListener*> AudioProcessor::listeners
private

◆ managedParameters

OwnedArray<AudioProcessorParameter> AudioProcessor::managedParameters
private

◆ nonRealtime

bool AudioProcessor::nonRealtime
private

Referenced by isNonRealtime().

◆ outputBuses

OwnedArray<Bus> AudioProcessor::outputBuses
mutableprivate

Referenced by getBus(), and getBusCount().

◆ playHead

AudioPlayHead* AudioProcessor::playHead
protected

Referenced by getPlayHead().

◆ processingPrecision

ProcessingPrecision AudioProcessor::processingPrecision
private

◆ suspended

bool AudioProcessor::suspended
private

Referenced by isSuspended().

◆ textRecursionCheck

bool AudioProcessor::textRecursionCheck
private

◆ wrapperType

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.


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