Base class for all audio plugins in the Tracktion Engine. More...

#include <tracktion_Plugin.h>

Inheritance diagram for engine::Plugin:

Classes
struct	BusLayout
	Describes the full input/output bus topology of a plugin. More...

struct	EditorComponent
	Base class for plugin editor components (custom UIs shown in plugin windows). More...

struct	WindowState
	Persistent state for the plugin's editor window (position, visibility, etc.). More...

struct	Wire
	Represents a single channel-to-channel connection for sidechain routing. More...

Public Types
enum class	Type { allPlugins , folderTrackPlugins , effectPlugins }
	Filter categories used when enumerating plugins. More...

using	Ptr = juce::ReferenceCountedObjectPtr< Plugin >

using	Array = juce::ReferenceCountedArray< Plugin >

Public Types inherited from engine::Selectable
using	WeakRef = juce::WeakReference< Selectable >

Public Member Functions
	Plugin (PluginCreationInfo)

	~Plugin () override

void	selectableAboutToBeDeleted () override
	Called just before the selectable is about to be deleted so any subclasses should still be valid at this point.

void	playStartedOrStopped ()
	called by the system to let the plugin manage its automation stuff

virtual void	initialiseFully ()
	Gives the plugin a chance to do extra initialisation when it's been added to an edit.

virtual void	flushPluginStateToValueTree () override

virtual juce::String	getName () const override=0
	The name of the type, e.g.

virtual juce::String	getPluginType ()=0
	Returns a string identifying the plugin type (used as the XML tag name).

virtual juce::String	getVendor ()
	Returns the plugin vendor/manufacturer name.

virtual juce::String	getShortName (int)
	Returns an abbreviated name, ideally fitting within suggestedLength characters.

juce::String	getDisplayName () const
	Returns the custom name if set, otherwise the built-in getName().

juce::String	getCustomName () const
	Returns the raw custom name (may be empty).

void	setCustomName (const juce::String &)
	Sets a custom display name.

virtual juce::String	getIdentifierString ()
	A unique string to identify a plugin independent of install location.

virtual juce::String	getTooltip ()
	Returns a tooltip string for UI display.

virtual void	setEnabled (bool)
	Enable/disable the plugin.

bool	isEnabled () const noexcept

void	setFrozen (bool shouldBeFrozen)
	Freezing is stronger than disabling – a frozen plugin cannot be interacted with at all.

bool	isFrozen () const noexcept

void	setProcessingEnabled (bool p)
	Enable/disable processing.

bool	isProcessingEnabled () const noexcept

virtual void	initialise (const PluginInitialisationInfo &)=0
	Gives the plugin a chance to set itself up before being played.

virtual void	initialiseWithoutStopping (const PluginInitialisationInfo &)
	Tells the plugin that the audio graph has changed but the plugin isn't being re-initialised - i.e.

virtual void	deinitialise ()=0
	Called after play stops to release resources.

virtual void	reset ()
	Should reset synth voices, tails, clear delay buffers, etc.

virtual void	trackPropertiesChanged ()
	Track name or colour has changed.

virtual void	midiPanic ()
	Tells the plugin to turn off any playing notes, if applicable.

virtual void	applyToBuffer (const PluginRenderContext &)=0
	Process the next block of data.

virtual void	prepareForNextBlock (TimePosition)
	Called between successive rendering blocks.

void	applyToBufferWithAutomation (const PluginRenderContext &)

virtual bool	shouldMeasureCpuUsage () const noexcept
	Plugins can return false if they want to avoid the overhead of measuring the CPU usage.

double	getCpuUsage () const noexcept
	Returns the proportion of the current buffer size spent processing this plugin.

virtual int	getNumOutputChannelsGivenInputs (int numInputChannels)
	Returns the number of output channels this plugin will produce for track routing.

virtual bool	producesAudioWhenNoAudioInput ()
	Returns true if the plugin can produce audio when its input is silent (e.g.

virtual bool	noTail ()
	Returns true if the plugin has no tail (i.e.

virtual void	getChannelNames (juce::StringArray ins, juce::StringArray outs)
	Fills the provided StringArrays with the names of this plugin's input and/or output channels.

virtual BusLayout	getBusses () const =0
	Returns the full input/output bus layout of this plugin.

virtual bool	takesAudioInput ()
	Returns true if this plugin should be fed audio from upstream in the chain.

virtual bool	takesMidiInput ()

virtual bool	isSynth ()

virtual double	getLatencySeconds ()
	Returns the plugin's processing latency in seconds.

virtual double	getTailLength () const
	Returns the length of the plugin's tail in seconds (e.g.

virtual bool	canSidechain ()
	Returns true if this plugin supports sidechain input.

AutomatableParameter *	addParam (const juce::String &paramID, const juce::String &name, juce::NormalisableRange< float > valueRange)
	Registers a new automatable parameter owned by this plugin.

AutomatableParameter *	addParam (const juce::String &paramID, const juce::String &name, juce::NormalisableRange< float > valueRange, std::function< juce::String(float)> valueToStringFunction, std::function< float(const juce::String &)> stringToValueFunction)
	Registers a new automatable parameter with custom string conversion functions.

juce::StringArray	getInputChannelNames ()
	Returns the names of this plugin's input channels (convenience wrapper around getChannelNames).

juce::StringArray	getSidechainSourceNames (bool allowNone)
	Returns the names of available sidechain sources for this plugin.

void	setSidechainSourceByName (const juce::String &name)
	Sets the sidechain source by its display name.

juce::String	getSidechainSourceName ()
	Returns the display name of the current sidechain source.

void	guessSidechainRouting ()
	Attempts to automatically determine a sensible sidechain routing.

int	getNumWires () const

Wire *	getWire (int index) const

void	makeConnection (int srcChannel, int dstChannel, juce::UndoManager *)

void	breakConnection (int srcChannel, int dstChannel)

virtual bool	hasNameForMidiNoteNumber (int note, int midiChannel, juce::String &name)
	If it's a synth that names its notes, this can return the name it uses for this note 0-127.

virtual bool	hasNameForMidiProgram (int programNum, int bank, juce::String &name)
	Returns the name for a midi program, if there is one.

virtual bool	hasNameForMidiBank (int bank, juce::String &name)

virtual bool	canBeAddedToClip ()

virtual bool	canBeAddedToRack ()

virtual bool	canBeAddedToFolderTrack ()

virtual bool	canBeAddedToMaster ()

virtual bool	canBeDisabled ()

virtual bool	canBeMoved ()

virtual bool	needsConstantBufferSize ()
	Returns true if this plugin requires a constant audio buffer size (no variable-size blocks).

virtual bool	isMissing ()
	Returns true if the plugin's backing file/DLL is missing (e.g.

virtual bool	isDisabled ()
	Returns true if the plugin has been forcibly disabled (e.g.

bool	isInRack () const
	Returns true if this plugin lives inside a RackType.

juce::ReferenceCountedObjectPtr< RackType >	getOwnerRackType () const

bool	isClipEffectPlugin () const
	Returns true if this plugin is being used as a clip effect.

virtual juce::AudioProcessor *	getWrappedAudioProcessor () const
	Returns the underlying juce::AudioProcessor, if this plugin wraps one.

AutomatableParameter::Ptr	getQuickControlParameter () const

void	setQuickControlParameter (AutomatableParameter *)

virtual void	deleteFromParent ()
	Attempts to delete this plugin, whether it's a master plugin, track plugin, etc.

void	removeFromParent ()
	Detaches the plugin from any parent it might be in.

Track *	getOwnerTrack () const
	Returns the track if it's a track or clip plugin.

Clip *	getOwnerClip () const
	Returns the clip if that's what it's in.

PluginList *	getOwnerList () const
	Returns the PluginList that contains this plugin.

Ptr	findPluginThatFeedsIntoThis () const
	Returns the previous plugin in the same PluginList, or nullptr.

Ptr	findPluginThatThisFeedsInto () const
	Returns the next plugin in the same PluginList, or nullptr.

void	changed () override
	Marks the plugin as changed and notifies the Edit.

juce::Array< ReferencedItem >	getReferencedItems () override

void	reassignReferencedItem (const ReferencedItem &, ProjectItemRef newRef, double newStartTime) override

virtual void	sourceMediaChanged ()
	Called when ProjectItem sources are re-assigned so you can reload from the new source.

bool	setPluginToMirror (const Plugin::Ptr &)
	Sets a master plugin whose settings this one will mirror.

virtual void	updateFromMirroredPluginIfNeeded (Plugin &)
	Called to pull state from the mirrored master.

Plugin::Ptr	getMirroredPlugin () const
	Returns the plugin this one is mirroring, or nullptr.

bool	baseClassNeedsInitialising () const noexcept
	Returns true if baseClassInitialise() has not yet been called (or has been fully deinitialised).

void	baseClassInitialise (const PluginInitialisationInfo &)
	Prepares the plugin for playback.

void	baseClassDeinitialise ()
	Tears down the plugin after playback.

void	setSidechainSourceID (EditItemID newID)

EditItemID	getSidechainSourceID () const

virtual std::unique_ptr< EditorComponent >	createEditor ()
	Creates a custom editor component for this plugin, or nullptr if none.

void	showWindowExplicitly ()
	Shows the plugin's editor window, creating it if necessary.

void	hideWindowForShutdown ()
	Hides the plugin window during shutdown (avoids dangling references).

juce::UndoManager *	getUndoManager () const noexcept

bool	isInitialising () const

Public Member Functions inherited from engine::Selectable
	Selectable ()

virtual	~Selectable ()

virtual juce::String	getSelectableDescription ()=0
	Subclasses must return a description of what they are.

virtual void	selectionStatusChanged (bool isNowSelected)
	Can be overridden to tell this object that it has just been selected or deselected.

void	addListener (SelectableListener *)

void	removeListener (SelectableListener *)

void	addSelectableListener (SelectableListener *)

void	removeSelectableListener (SelectableListener *)

void	cancelAnyPendingUpdates ()
	If changed() has been called, this will cancel any pending async change notificaions.

void	deselect ()

void	propertiesChanged ()

void	notifyListenersOfDeletion ()

WeakRef	getWeakRef ()

Public Member Functions inherited from engine::Exportable
virtual	~Exportable ()=default

Public Member Functions inherited from engine::AutomatableEditItem
	AutomatableEditItem (Edit &, const juce::ValueTree &)

	~AutomatableEditItem () override

virtual void	restorePluginStateFromValueTree (const juce::ValueTree &)

juce::Array< AutomatableParameter * >	getAutomatableParameters () const

int	getNumAutomatableParameters () const

AutomatableParameter::Ptr	getAutomatableParameter (int index) const

AutomatableParameter::Ptr	getAutomatableParameterByID (const juce::String &paramID) const

void	visitAllAutomatableParams (const std::function< void(AutomatableParameter &)> &visit) const

void	deleteParameter (AutomatableParameter *)

void	deleteAutomatableParameters ()

int	indexOfAutomatableParameter (const AutomatableParameter::Ptr &) const

AutomatableParameterTree &	getParameterTree () const

juce::ReferenceCountedArray< AutomatableParameter >	getFlattenedParameterTree () const

void	addParameterListChangeListener (ParameterListChangeListener *)

void	removeParameterListChangeListener (ParameterListChangeListener *)

bool	isAutomationNeeded () const noexcept

void	setAutomatableParamPosition (TimePosition)

bool	isBeingActivelyPlayed () const

virtual void	updateAutomatableParamPosition (TimePosition)
	Updates all the auto params to their positions at this time.

void	updateParameterStreams (TimePosition)
	Updates all the parameter streams to their positions at this time.

void	resetRecordingStatus ()
	Marks the end of an automation recording stream.

void	updateStreamIterators ()

void	addActiveParameter (const AutomatableParameter &)

void	removeActiveParameter (const AutomatableParameter &)

bool	isActiveParameter (AutomatableParameter &)

Public Member Functions inherited from engine::EditItem
	EditItem (EditItemID, Edit &)

	EditItem (Edit &, const juce::ValueTree &)

virtual	~EditItem ()=default

Public Member Functions inherited from engine::MacroParameterElement
	MacroParameterElement (Edit &, const juce::ValueTree &)
	Constructor.

virtual	~MacroParameterElement ()=default
	Destructor.

MacroParameterList *	getMacroParameterList ()
	If no parameters have been created, this may return nullptr.

MacroParameterList &	getMacroParameterListForWriting ()
	This ensures that the list has been created.

juce::ReferenceCountedArray< MacroParameter >	getMacroParameters () const

Static Public Member Functions
static bool	areSelectedPluginsRackable (SelectionManager &)

static RackInstance *	wrapSelectedPluginsInRack (SelectionManager &)

static void	sortPlugins (Plugin::Array &)

static void	sortPlugins (std::vector< Plugin * > &)

Static Public Member Functions inherited from engine::Selectable
static void	initialise ()

static bool	isSelectableValid (const Selectable *) noexcept
	checks whether this object has been deleted.

Static Public Member Functions inherited from engine::Exportable
static juce::Array< Exportable * >	addAllExportables (Edit &)
	Returns all the Exportables contained in an Edit.

Public Attributes
std::unique_ptr< WindowState >	windowState

Engine &	engine

juce::ValueTree	state
	The ValueTree that stores this plugin's persistent state within the Edit.

Public Attributes inherited from engine::Selectable
WeakRef::Master	masterReference

Public Attributes inherited from engine::AutomatableEditItem
juce::ValueTree	elementState

juce::CachedValue< bool >	remapOnTempoChange

Public Attributes inherited from engine::EditItem
Edit &	edit

const EditItemID	itemID
	Every EditItem has an ID which is unique within the edit.

Public Attributes inherited from engine::MacroParameterElement
Edit &	ownerEdit

juce::ValueTree	parentStateForList

Protected Member Functions
void	valueTreePropertyChanged (juce::ValueTree &, const juce::Identifier &) override

void	valueTreeChanged () override

void	valueTreeChildAdded (juce::ValueTree &, juce::ValueTree &) override

void	valueTreeChildRemoved (juce::ValueTree &, juce::ValueTree &, int) override

void	valueTreeParentChanged (juce::ValueTree &) override

virtual void	processingChanged ()
	Called when the processing enabled state changes.

Protected Member Functions inherited from engine::AutomatableEditItem
virtual void	buildParameterTree () const

void	updateLastPlaybackTime ()

void	clearParameterList ()

void	addAutomatableParameter (const AutomatableParameter::Ptr &)

void	rebuildParameterTree ()

void	saveChangedParametersToState ()
	Saves the explicit value of any parameters that have deviated to the state.

void	restoreChangedParametersFromState ()
	Restores the value of any explicitly set parameters.

Protected Member Functions inherited from engine::ValueTreeAllEventListener
void	valueTreePropertyChanged (juce::ValueTree &, const juce::Identifier &) override

void	valueTreeChildAdded (juce::ValueTree &, juce::ValueTree &) override

void	valueTreeChildRemoved (juce::ValueTree &, juce::ValueTree &, int) override

void	valueTreeChildOrderChanged (juce::ValueTree &, int, int) override

void	valueTreeParentChanged (juce::ValueTree &) override

void	valueTreeRedirected (juce::ValueTree &) override

Static Protected Member Functions
static void	getLeftRightChannelNames (juce::StringArray ins, juce::StringArray outs)
	Helper to populate stereo left/right channel name arrays.

static void	getLeftRightChannelNames (juce::StringArray *chans)

Protected Attributes
juce::CachedValue< AtomicWrapper< bool > >	enabled

juce::CachedValue< bool >	frozen

juce::CachedValue< bool >	processing

juce::CachedValue< juce::String >	quickParamName

juce::CachedValue< juce::String >	customName

juce::CachedValue< EditItemID >	masterPluginID

juce::CachedValue< EditItemID >	sidechainSourceID

double	sampleRate = 44100.0
	Current sample rate and block size, set during baseClassInitialise().

int	blockSizeSamples = 512

Detailed Description

Base class for all audio plugins in the Tracktion Engine.

A Plugin lives inside a PluginList (owned by a Track, Clip, or RackType) and processes audio/MIDI via applyToBuffer(). Its persistent state is stored in a juce::ValueTree, and it supports automation, sidechain routing, and mirroring.

Subclasses include ExternalPlugin (hosted VST/AU/etc.), and the built-in internal plugins (volume/pan, EQ, delay, etc.).

Lifecycle

Plugins are created via PluginCreationInfo, then prepared for playback with initialise() (called indirectly through baseClassInitialise()) and torn down with deinitialise() (via baseClassDeinitialise()). Between those calls the audio graph may call applyToBuffer() on the audio thread.

Threading

applyToBuffer() runs on the audio thread – implementations must not allocate, lock, or perform I/O. Most other methods are message-thread only unless noted otherwise.

Member Typedef Documentation

◆ Ptr

using engine::Plugin::Ptr = juce::ReferenceCountedObjectPtr<Plugin>

◆ Array

using engine::Plugin::Array = juce::ReferenceCountedArray<Plugin>

Member Enumeration Documentation

◆ Type

enum class engine::Plugin::Type

strong

Filter categories used when enumerating plugins.

Enumerator
allPlugins
folderTrackPlugins
effectPlugins

Constructor & Destructor Documentation

◆ Plugin()

engine::Plugin::Plugin ( PluginCreationInfo )

◆ ~Plugin()

engine::Plugin::~Plugin ( )

override

Member Function Documentation

◆ selectableAboutToBeDeleted()

void engine::Plugin::selectableAboutToBeDeleted ( )

overridevirtual

Called just before the selectable is about to be deleted so any subclasses should still be valid at this point.

Reimplemented from engine::Selectable.

◆ playStartedOrStopped()

void engine::Plugin::playStartedOrStopped ( )

called by the system to let the plugin manage its automation stuff

◆ initialiseFully()

virtual void engine::Plugin::initialiseFully ( )

virtual

Gives the plugin a chance to do extra initialisation when it's been added to an edit.

Reimplemented in engine::ExternalPlugin, and engine::FreezePointPlugin.

◆ flushPluginStateToValueTree()

virtual void engine::Plugin::flushPluginStateToValueTree ( )

overridevirtual

Reimplemented from engine::AutomatableEditItem.

Reimplemented in engine::AirWindowsPlugin, and engine::ExternalPlugin.

◆ getName()

virtual juce::String engine::Plugin::getName ( ) const

overridepure virtual

◆ getPluginType()

virtual juce::String engine::Plugin::getPluginType ( )

pure virtual

◆ getVendor()

virtual juce::String engine::Plugin::getVendor ( )

virtual

Returns the plugin vendor/manufacturer name.

Reimplemented in engine::ExternalPlugin.

◆ getShortName()

virtual juce::String engine::Plugin::getShortName ( int )

virtual

Returns an abbreviated name, ideally fitting within suggestedLength characters.

Reimplemented in engine::AuxReturnPlugin, engine::AuxSendPlugin, engine::ChorusPlugin, engine::CompressorPlugin, engine::EqualiserPlugin, engine::FourOscPlugin, engine::ImpulseResponsePlugin, engine::LowPassPlugin, engine::MidiModifierPlugin, engine::MidiPatchBayPlugin, engine::PatchBayPlugin, engine::PitchShiftPlugin, engine::SamplerPlugin, engine::ToneGeneratorPlugin, engine::ChannelMapperPlugin, engine::InsertPlugin, engine::LevelMeterPlugin, and engine::VolumeAndPanPlugin.

References engine::getName().

◆ getDisplayName()

juce::String engine::Plugin::getDisplayName ( ) const

Returns the custom name if set, otherwise the built-in getName().

◆ getCustomName()

juce::String engine::Plugin::getCustomName ( ) const

Returns the raw custom name (may be empty).

◆ setCustomName()

void engine::Plugin::setCustomName ( const juce::String & )

Sets a custom display name.

Trimmed and limited to 64 chars. Empty clears.

◆ getIdentifierString()

virtual juce::String engine::Plugin::getIdentifierString ( )

virtual

A unique string to identify a plugin independent of install location.

Reimplemented in engine::ExternalPlugin.

◆ getTooltip()

virtual juce::String engine::Plugin::getTooltip ( )

virtual

Returns a tooltip string for UI display.

Reimplemented in engine::EqualiserPlugin, engine::ExternalPlugin, engine::FreezePointPlugin, engine::LevelMeterPlugin, and engine::RackInstance.

◆ setEnabled()

virtual void engine::Plugin::setEnabled ( bool )

virtual

Enable/disable the plugin.

Reimplemented in engine::ExternalPlugin.

◆ isEnabled()

bool engine::Plugin::isEnabled ( ) const

noexcept

◆ setFrozen()

void engine::Plugin::setFrozen ( bool shouldBeFrozen )

Freezing is stronger than disabling – a frozen plugin cannot be interacted with at all.

◆ isFrozen()

bool engine::Plugin::isFrozen ( ) const

noexcept

◆ setProcessingEnabled()

void engine::Plugin::setProcessingEnabled ( bool p )

Enable/disable processing.

When processing is disabled, the plugin should minimise memory usage and release any resources possible.

◆ isProcessingEnabled()

bool engine::Plugin::isProcessingEnabled ( ) const

noexcept

◆ initialise()

virtual void engine::Plugin::initialise ( const PluginInitialisationInfo & )

pure virtual

Gives the plugin a chance to set itself up before being played.

This won't be called concurrently with the process thread.

The sample rate and the average block size - although the blocks won't always be the same, and may be bigger.

Don't call this directly or the initialise count will become out of sync.

See also: baseClassInitialise [[ message_thread ]]

Implemented in engine::AirWindowsPlugin, engine::ChorusPlugin, engine::CompressorPlugin, engine::DelayPlugin, engine::EqualiserPlugin, engine::FourOscPlugin, engine::ImpulseResponsePlugin, engine::LatencyPlugin, engine::LowPassPlugin, engine::MidiModifierPlugin, engine::MidiPatchBayPlugin, engine::PatchBayPlugin, engine::PhaserPlugin, engine::PitchShiftPlugin, engine::ReverbPlugin, engine::SamplerPlugin, engine::ToneGeneratorPlugin, engine::ExternalPlugin, engine::AuxReturnPlugin, engine::AuxSendPlugin, engine::ChannelMapperPlugin, engine::FreezePointPlugin, engine::InsertPlugin, engine::LevelMeterPlugin, engine::RackInstance, engine::TextPlugin, engine::VCAPlugin, and engine::VolumeAndPanPlugin.

◆ initialiseWithoutStopping()

virtual void engine::Plugin::initialiseWithoutStopping ( const PluginInitialisationInfo & )

virtual

Tells the plugin that the audio graph has changed but the plugin isn't being re-initialised - i.e.

it's being re-used, maybe by being moved to a different track, etc. This can be called concurrently whilst the plugin is being processed so implementations of it must be thread safe. [[ message_thread ]]

Reimplemented in engine::AuxSendPlugin, engine::InsertPlugin, engine::LevelMeterPlugin, and engine::VolumeAndPanPlugin.

◆ deinitialise()

virtual void engine::Plugin::deinitialise ( )

pure virtual

Called after play stops to release resources.

Don't call this directly or the initialise count will become out of sync.

See also: baseClassDeinitialise

Implemented in engine::AirWindowsPlugin, engine::ChorusPlugin, engine::CompressorPlugin, engine::DelayPlugin, engine::EqualiserPlugin, engine::FourOscPlugin, engine::ImpulseResponsePlugin, engine::LatencyPlugin, engine::LowPassPlugin, engine::MidiModifierPlugin, engine::MidiPatchBayPlugin, engine::PatchBayPlugin, engine::PhaserPlugin, engine::PitchShiftPlugin, engine::ReverbPlugin, engine::SamplerPlugin, engine::ToneGeneratorPlugin, engine::ExternalPlugin, engine::AuxReturnPlugin, engine::AuxSendPlugin, engine::ChannelMapperPlugin, engine::FreezePointPlugin, engine::InsertPlugin, engine::LevelMeterPlugin, engine::RackInstance, engine::TextPlugin, engine::VCAPlugin, and engine::VolumeAndPanPlugin.

◆ reset()

virtual void engine::Plugin::reset ( )

virtual

Should reset synth voices, tails, clear delay buffers, etc.

Reimplemented in engine::DelayPlugin, engine::FourOscPlugin, engine::ImpulseResponsePlugin, engine::ReverbPlugin, and engine::ExternalPlugin.

◆ trackPropertiesChanged()

virtual void engine::Plugin::trackPropertiesChanged ( )

virtual

Track name or colour has changed.

Reimplemented in engine::ExternalPlugin.

◆ midiPanic()

virtual void engine::Plugin::midiPanic ( )

virtual

Tells the plugin to turn off any playing notes, if applicable.

Reimplemented in engine::FourOscPlugin, and engine::ExternalPlugin.

◆ applyToBuffer()

virtual void engine::Plugin::applyToBuffer ( const PluginRenderContext & )

pure virtual

Process the next block of data.

The incoming buffer will have an unknown number of channels, and the plugin has to deal with them however it wants to.

The buffer should be resized to the number of output channels that the plugin wants to return (which should be the same or less than the number of output channel names it returns from getChannelNames() - never more than this).

Implemented in engine::AirWindowsPlugin, engine::ChorusPlugin, engine::CompressorPlugin, engine::DelayPlugin, engine::EqualiserPlugin, engine::FourOscPlugin, engine::ImpulseResponsePlugin, engine::LatencyPlugin, engine::LowPassPlugin, engine::MidiModifierPlugin, engine::MidiPatchBayPlugin, engine::PatchBayPlugin, engine::PhaserPlugin, engine::PitchShiftPlugin, engine::ReverbPlugin, engine::SamplerPlugin, engine::ToneGeneratorPlugin, engine::ExternalPlugin, engine::AuxReturnPlugin, engine::AuxSendPlugin, engine::ChannelMapperPlugin, engine::FreezePointPlugin, engine::InsertPlugin, engine::LevelMeterPlugin, engine::RackInstance, engine::TextPlugin, engine::VCAPlugin, and engine::VolumeAndPanPlugin.

◆ prepareForNextBlock()

virtual void engine::Plugin::prepareForNextBlock ( TimePosition )

virtual

Called between successive rendering blocks.

Reimplemented in engine::RackInstance.

◆ applyToBufferWithAutomation()

void engine::Plugin::applyToBufferWithAutomation ( const PluginRenderContext & )

◆ shouldMeasureCpuUsage()

virtual bool engine::Plugin::shouldMeasureCpuUsage ( ) const

virtualnoexcept

Plugins can return false if they want to avoid the overhead of measuring the CPU usage.

It's a small overhead but with many tracks, the level meters and vol/pan plugins can make a difference.

Reimplemented in engine::LevelMeterPlugin, and engine::VolumeAndPanPlugin.

◆ getCpuUsage()

double engine::Plugin::getCpuUsage ( ) const

noexcept

Returns the proportion of the current buffer size spent processing this plugin.

◆ getNumOutputChannelsGivenInputs()

virtual int engine::Plugin::getNumOutputChannelsGivenInputs ( int numInputChannels )

virtual

Returns the number of output channels this plugin will produce for track routing.

E.g. some might be able to do mono, so will return 1 if the input is 1, 2 if it is 2, etc.

The default impl returns the number of items that getChannelNames() returns. Subclasses with sidechain buses must override this to return only the main bus output count, since sidechain channels are routed separately.

Reimplemented in engine::AirWindowsPlugin, engine::ChorusPlugin, engine::CompressorPlugin, engine::DelayPlugin, engine::EqualiserPlugin, engine::LowPassPlugin, engine::PatchBayPlugin, engine::PhaserPlugin, engine::PitchShiftPlugin, engine::ReverbPlugin, engine::ToneGeneratorPlugin, engine::AuxReturnPlugin, engine::AuxSendPlugin, engine::ChannelMapperPlugin, engine::FreezePointPlugin, engine::LevelMeterPlugin, engine::TextPlugin, engine::ExternalPlugin, engine::RackInstance, engine::VolumeAndPanPlugin, engine::FourOscPlugin, engine::MidiModifierPlugin, engine::MidiPatchBayPlugin, and engine::SamplerPlugin.

◆ producesAudioWhenNoAudioInput()

virtual bool engine::Plugin::producesAudioWhenNoAudioInput ( )

virtual

Returns true if the plugin can produce audio when its input is silent (e.g.

synths, plugins with tails, or plugins driven by automation).

Reimplemented in engine::AirWindowsPlugin, engine::FourOscPlugin, engine::SamplerPlugin, engine::ToneGeneratorPlugin, engine::ExternalPlugin, engine::AuxReturnPlugin, engine::ChannelMapperPlugin, engine::FreezePointPlugin, engine::RackInstance, and engine::TextPlugin.

◆ noTail()

virtual bool engine::Plugin::noTail ( )

virtual

Returns true if the plugin has no tail (i.e.

output is silent once input stops).

Reimplemented in engine::ExternalPlugin.

◆ getChannelNames()

virtual void engine::Plugin::getChannelNames	(	juce::StringArray *	ins,
		juce::StringArray *	outs
	)

virtual

Fills the provided StringArrays with the names of this plugin's input and/or output channels.

Either pointer may be nullptr if not needed.

Reimplemented in engine::CompressorPlugin, engine::MidiModifierPlugin, engine::MidiPatchBayPlugin, engine::PatchBayPlugin, engine::InsertPlugin, and engine::ExternalPlugin.

◆ getBusses()

virtual BusLayout engine::Plugin::getBusses ( ) const

pure virtual

Returns the full input/output bus layout of this plugin.

Every concrete plugin must declare its bus topology here. Multi-out plugins (e.g. ExternalPlugin hosting a VST3 with multiple output buses) report each output bus as a separate entry in the returned layout's outputs list; the first entry is the main bus.

Consumers that only need the main bus can use e.g. getBusses().outputs.front().

Implemented in engine::AirWindowsPlugin, engine::ChorusPlugin, engine::CompressorPlugin, engine::DelayPlugin, engine::EqualiserPlugin, engine::FourOscPlugin, engine::ImpulseResponsePlugin, engine::LatencyPlugin, engine::LowPassPlugin, engine::MidiModifierPlugin, engine::MidiPatchBayPlugin, engine::PatchBayPlugin, engine::PhaserPlugin, engine::PitchShiftPlugin, engine::ReverbPlugin, engine::SamplerPlugin, engine::ToneGeneratorPlugin, engine::ExternalPlugin, engine::AuxReturnPlugin, engine::AuxSendPlugin, engine::ChannelMapperPlugin, engine::FreezePointPlugin, engine::InsertPlugin, engine::LevelMeterPlugin, engine::RackInstance, engine::TextPlugin, engine::VCAPlugin, and engine::VolumeAndPanPlugin.

◆ takesAudioInput()

virtual bool engine::Plugin::takesAudioInput ( )

virtual

Returns true if this plugin should be fed audio from upstream in the chain.

The default derives from the bus layout: a non-synth that declares at least one audio input bus takes audio. Synths that also accept audio input (e.g. for wet/dry mix) should override to return true explicitly.

Reimplemented in engine::SamplerPlugin, engine::ExternalPlugin, and engine::RackInstance.

◆ takesMidiInput()

virtual bool engine::Plugin::takesMidiInput ( )

virtual

Reimplemented in engine::AirWindowsPlugin, engine::FourOscPlugin, engine::SamplerPlugin, engine::ExternalPlugin, engine::AuxReturnPlugin, engine::ChannelMapperPlugin, engine::InsertPlugin, and engine::RackInstance.

◆ isSynth()

virtual bool engine::Plugin::isSynth ( )

virtual

Reimplemented in engine::FourOscPlugin, engine::SamplerPlugin, engine::ToneGeneratorPlugin, engine::ExternalPlugin, and engine::RackInstance.

◆ getLatencySeconds()

virtual double engine::Plugin::getLatencySeconds ( )

virtual

Returns the plugin's processing latency in seconds.

Reimplemented in engine::ImpulseResponsePlugin, engine::LatencyPlugin, engine::MidiModifierPlugin, engine::PitchShiftPlugin, engine::ExternalPlugin, engine::InsertPlugin, and engine::RackInstance.

◆ getTailLength()

virtual double engine::Plugin::getTailLength ( ) const

virtual

Returns the length of the plugin's tail in seconds (e.g.

reverb decay).

Reimplemented in engine::FourOscPlugin, and engine::ExternalPlugin.

◆ canSidechain()

virtual bool engine::Plugin::canSidechain ( )

virtual

Returns true if this plugin supports sidechain input.

Default checks whether getChannelNames() reports more inputs than the main bus.

◆ addParam() [1/2]

AutomatableParameter * engine::Plugin::addParam	(	const juce::String &	paramID,
		const juce::String &	name,
		juce::NormalisableRange< float >	valueRange
	)

Registers a new automatable parameter owned by this plugin.

◆ addParam() [2/2]

AutomatableParameter * engine::Plugin::addParam	(	const juce::String &	paramID,
		const juce::String &	name,
		juce::NormalisableRange< float >	valueRange,
		std::function< juce::String(float)>	valueToStringFunction,
		std::function< float(const juce::String &)>	stringToValueFunction
	)

Registers a new automatable parameter with custom string conversion functions.

◆ getInputChannelNames()

juce::StringArray engine::Plugin::getInputChannelNames ( )

Returns the names of this plugin's input channels (convenience wrapper around getChannelNames).

◆ getSidechainSourceNames()

juce::StringArray engine::Plugin::getSidechainSourceNames ( bool allowNone )

Returns the names of available sidechain sources for this plugin.

If allowNone is true, includes a "none" entry.

◆ setSidechainSourceByName()

void engine::Plugin::setSidechainSourceByName ( const juce::String & name )

Sets the sidechain source by its display name.

◆ getSidechainSourceName()

juce::String engine::Plugin::getSidechainSourceName ( )

Returns the display name of the current sidechain source.

◆ guessSidechainRouting()

void engine::Plugin::guessSidechainRouting ( )

Attempts to automatically determine a sensible sidechain routing.

◆ getNumWires()

int engine::Plugin::getNumWires ( ) const

◆ getWire()

Wire * engine::Plugin::getWire ( int index ) const

◆ makeConnection()

void engine::Plugin::makeConnection	(	int	srcChannel,
		int	dstChannel,
		juce::UndoManager *
	)

◆ breakConnection()

void engine::Plugin::breakConnection	(	int	srcChannel,
		int	dstChannel
	)

◆ hasNameForMidiNoteNumber()

virtual bool engine::Plugin::hasNameForMidiNoteNumber	(	int	note,
		int	midiChannel,
		juce::String &	name
	)

virtual

If it's a synth that names its notes, this can return the name it uses for this note 0-127.

Midi channel is 1-16

Reimplemented in engine::SamplerPlugin, and engine::ExternalPlugin.

◆ hasNameForMidiProgram()

virtual bool engine::Plugin::hasNameForMidiProgram	(	int	programNum,
		int	bank,
		juce::String &	name
	)

virtual

Returns the name for a midi program, if there is one.

programNum = 0 to 127.

Reimplemented in engine::ExternalPlugin.

◆ hasNameForMidiBank()

virtual bool engine::Plugin::hasNameForMidiBank	(	int	bank,
		juce::String &	name
	)

virtual

◆ canBeAddedToClip()

virtual bool engine::Plugin::canBeAddedToClip ( )

virtual

Reimplemented in engine::AirWindowsPlugin, engine::MidiModifierPlugin, engine::MidiPatchBayPlugin, engine::PatchBayPlugin, engine::AuxReturnPlugin, engine::AuxSendPlugin, engine::ChannelMapperPlugin, engine::FreezePointPlugin, engine::InsertPlugin, and engine::VCAPlugin.

◆ canBeAddedToRack()

virtual bool engine::Plugin::canBeAddedToRack ( )

virtual

Reimplemented in engine::AirWindowsPlugin, engine::MidiPatchBayPlugin, engine::PatchBayPlugin, engine::AuxReturnPlugin, engine::AuxSendPlugin, engine::FreezePointPlugin, engine::RackInstance, engine::VCAPlugin, and engine::VolumeAndPanPlugin.

◆ canBeAddedToFolderTrack()

virtual bool engine::Plugin::canBeAddedToFolderTrack ( )

virtual

Reimplemented in engine::TextPlugin, and engine::VCAPlugin.

◆ canBeAddedToMaster()

virtual bool engine::Plugin::canBeAddedToMaster ( )

virtual

Reimplemented in engine::FreezePointPlugin.

◆ canBeDisabled()

virtual bool engine::Plugin::canBeDisabled ( )

virtual

Reimplemented in engine::PatchBayPlugin, engine::FreezePointPlugin, and engine::LevelMeterPlugin.

◆ canBeMoved()

virtual bool engine::Plugin::canBeMoved ( )

virtual

Reimplemented in engine::VCAPlugin, and engine::VolumeAndPanPlugin.

◆ needsConstantBufferSize()

virtual bool engine::Plugin::needsConstantBufferSize ( )

virtual

Returns true if this plugin requires a constant audio buffer size (no variable-size blocks).

Reimplemented in engine::AuxReturnPlugin, engine::AuxSendPlugin, engine::InsertPlugin, and engine::RackInstance.

◆ isMissing()

virtual bool engine::Plugin::isMissing ( )

virtual

Returns true if the plugin's backing file/DLL is missing (e.g.

uninstalled VST).

Reimplemented in engine::ExternalPlugin.

◆ isDisabled()

virtual bool engine::Plugin::isDisabled ( )

virtual

Returns true if the plugin has been forcibly disabled (e.g.

after a crash).

Reimplemented in engine::ExternalPlugin.

◆ isInRack()

bool engine::Plugin::isInRack ( ) const

Returns true if this plugin lives inside a RackType.

◆ getOwnerRackType()

juce::ReferenceCountedObjectPtr< RackType > engine::Plugin::getOwnerRackType ( ) const

◆ isClipEffectPlugin()

bool engine::Plugin::isClipEffectPlugin ( ) const

Returns true if this plugin is being used as a clip effect.

◆ getWrappedAudioProcessor()

virtual juce::AudioProcessor * engine::Plugin::getWrappedAudioProcessor ( ) const

virtual

Returns the underlying juce::AudioProcessor, if this plugin wraps one.

Only ExternalPlugin returns non-null by default.

Reimplemented in engine::ExternalPlugin.

◆ getQuickControlParameter()

AutomatableParameter::Ptr engine::Plugin::getQuickControlParameter ( ) const

◆ setQuickControlParameter()

void engine::Plugin::setQuickControlParameter ( AutomatableParameter * )

◆ deleteFromParent()

virtual void engine::Plugin::deleteFromParent ( )

virtual

Attempts to delete this plugin, whether it's a master plugin, track plugin, etc.

This will call removeFromParent but also hide any automation parameters etc. being shown on tracks and hide plugin windows etc. Use this method if the plugin is being fully deleted from the Edit.

Reimplemented in engine::ExternalPlugin.

◆ removeFromParent()

void engine::Plugin::removeFromParent ( )

Detaches the plugin from any parent it might be in.

This is a little more complicated than just removing its ValueTree from its parent one. Use this method if the plugin is to be inserted somewhere else in the Edit.

◆ getOwnerTrack()

Track * engine::Plugin::getOwnerTrack ( ) const

Returns the track if it's a track or clip plugin.

◆ getOwnerClip()

Clip * engine::Plugin::getOwnerClip ( ) const

Returns the clip if that's what it's in.

◆ getOwnerList()

PluginList * engine::Plugin::getOwnerList ( ) const

Returns the PluginList that contains this plugin.

◆ findPluginThatFeedsIntoThis()

Ptr engine::Plugin::findPluginThatFeedsIntoThis ( ) const

Returns the previous plugin in the same PluginList, or nullptr.

◆ findPluginThatThisFeedsInto()

Ptr engine::Plugin::findPluginThatThisFeedsInto ( ) const

Returns the next plugin in the same PluginList, or nullptr.

◆ changed()

void engine::Plugin::changed ( )

overridevirtual

Marks the plugin as changed and notifies the Edit.

Reimplemented from engine::Selectable.

◆ getReferencedItems()

juce::Array< ReferencedItem > engine::Plugin::getReferencedItems ( )

overridevirtual

Implements engine::Exportable.

Reimplemented in engine::SamplerPlugin.

◆ reassignReferencedItem()

void engine::Plugin::reassignReferencedItem	(	const ReferencedItem &	,
		ProjectItemRef	newRef,
		double	newStartTime
	)

overridevirtual

Implements engine::Exportable.

Reimplemented in engine::SamplerPlugin.

◆ sourceMediaChanged()

virtual void engine::Plugin::sourceMediaChanged ( )

virtual

Called when ProjectItem sources are re-assigned so you can reload from the new source.

Reimplemented in engine::SamplerPlugin.

◆ areSelectedPluginsRackable()

static bool engine::Plugin::areSelectedPluginsRackable ( SelectionManager & )

static

◆ wrapSelectedPluginsInRack()

static RackInstance * engine::Plugin::wrapSelectedPluginsInRack ( SelectionManager & )

static

◆ sortPlugins() [1/2]

static void engine::Plugin::sortPlugins ( Plugin::Array & )

static

◆ sortPlugins() [2/2]

static void engine::Plugin::sortPlugins ( std::vector< Plugin * > & )

static

◆ setPluginToMirror()

bool engine::Plugin::setPluginToMirror ( const Plugin::Ptr & )

Sets a master plugin whose settings this one will mirror.

Returns false if the types don't match.

◆ updateFromMirroredPluginIfNeeded()

virtual void engine::Plugin::updateFromMirroredPluginIfNeeded ( Plugin & )

virtual

Called to pull state from the mirrored master.

Override to apply format-specific state.

Reimplemented in engine::ExternalPlugin.

◆ getMirroredPlugin()

Plugin::Ptr engine::Plugin::getMirroredPlugin ( ) const

Returns the plugin this one is mirroring, or nullptr.

◆ baseClassNeedsInitialising()

bool engine::Plugin::baseClassNeedsInitialising ( ) const

noexcept

Returns true if baseClassInitialise() has not yet been called (or has been fully deinitialised).

◆ baseClassInitialise()

void engine::Plugin::baseClassInitialise ( const PluginInitialisationInfo & )

Prepares the plugin for playback.

Calls initialise() and increments the internal init count.

◆ baseClassDeinitialise()

void engine::Plugin::baseClassDeinitialise ( )

Tears down the plugin after playback.

Calls deinitialise() when the init count reaches zero.

◆ setSidechainSourceID()

void engine::Plugin::setSidechainSourceID ( EditItemID newID )

◆ getSidechainSourceID()

EditItemID engine::Plugin::getSidechainSourceID ( ) const

◆ createEditor()

virtual std::unique_ptr< EditorComponent > engine::Plugin::createEditor ( )

virtual

Creates a custom editor component for this plugin, or nullptr if none.

Reimplemented in engine::ExternalPlugin.

◆ showWindowExplicitly()

void engine::Plugin::showWindowExplicitly ( )

Shows the plugin's editor window, creating it if necessary.

◆ hideWindowForShutdown()

void engine::Plugin::hideWindowForShutdown ( )

Hides the plugin window during shutdown (avoids dangling references).

◆ getUndoManager()

juce::UndoManager * engine::Plugin::getUndoManager ( ) const

noexcept

◆ isInitialising()

bool engine::Plugin::isInitialising ( ) const

◆ valueTreePropertyChanged()

void engine::Plugin::valueTreePropertyChanged	(	juce::ValueTree &	,
		const juce::Identifier &
	)

overrideprotected

◆ valueTreeChanged()

void engine::Plugin::valueTreeChanged ( )

overrideprotectedvirtual

Implements engine::ValueTreeAllEventListener.

◆ valueTreeChildAdded()

void engine::Plugin::valueTreeChildAdded	(	juce::ValueTree &	,
		juce::ValueTree &
	)

overrideprotected

◆ valueTreeChildRemoved()

void engine::Plugin::valueTreeChildRemoved	(	juce::ValueTree &	,
		juce::ValueTree &	,
		int
	)

overrideprotected

◆ valueTreeParentChanged()

void engine::Plugin::valueTreeParentChanged ( juce::ValueTree & )

overrideprotected

◆ processingChanged()

virtual void engine::Plugin::processingChanged ( )

protectedvirtual

Called when the processing enabled state changes.

Reimplemented in engine::ExternalPlugin.

◆ getLeftRightChannelNames() [1/2]

static void engine::Plugin::getLeftRightChannelNames	(	juce::StringArray *	ins,
		juce::StringArray *	outs
	)

staticprotected

Helper to populate stereo left/right channel name arrays.

◆ getLeftRightChannelNames() [2/2]

static void engine::Plugin::getLeftRightChannelNames ( juce::StringArray * chans )

staticprotected

Member Data Documentation

◆ windowState

std::unique_ptr<WindowState> engine::Plugin::windowState

◆ engine

Engine& engine::Plugin::engine

◆ state

juce::ValueTree engine::Plugin::state

The ValueTree that stores this plugin's persistent state within the Edit.

◆ enabled

juce::CachedValue<AtomicWrapper<bool> > engine::Plugin::enabled

protected

◆ frozen

juce::CachedValue<bool> engine::Plugin::frozen

protected

◆ processing

juce::CachedValue<bool> engine::Plugin::processing

protected

◆ quickParamName

juce::CachedValue<juce::String> engine::Plugin::quickParamName

protected

◆ customName

juce::CachedValue<juce::String> engine::Plugin::customName

protected

◆ masterPluginID

juce::CachedValue<EditItemID> engine::Plugin::masterPluginID

protected

◆ sidechainSourceID

juce::CachedValue<EditItemID> engine::Plugin::sidechainSourceID

protected

◆ sampleRate

double engine::Plugin::sampleRate = 44100.0

protected

Current sample rate and block size, set during baseClassInitialise().

◆ blockSizeSamples

int engine::Plugin::blockSizeSamples = 512

protected

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

tracktion_Plugin.h

Classes

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Detailed Description

Member Typedef Documentation

◆ Ptr

◆ Array

Member Enumeration Documentation

◆ Type

Constructor & Destructor Documentation

◆ Plugin()

◆ ~Plugin()

Member Function Documentation

◆ selectableAboutToBeDeleted()

◆ playStartedOrStopped()

◆ initialiseFully()

◆ flushPluginStateToValueTree()

◆ getName()

◆ getPluginType()

◆ getVendor()

◆ getShortName()

◆ getDisplayName()

◆ getCustomName()

◆ setCustomName()

◆ getIdentifierString()

◆ getTooltip()

◆ setEnabled()

◆ isEnabled()

◆ setFrozen()

◆ isFrozen()

◆ setProcessingEnabled()

◆ isProcessingEnabled()

◆ initialise()

◆ initialiseWithoutStopping()

◆ deinitialise()

◆ reset()

◆ trackPropertiesChanged()

◆ midiPanic()

◆ applyToBuffer()

◆ prepareForNextBlock()

◆ applyToBufferWithAutomation()

◆ shouldMeasureCpuUsage()

◆ getCpuUsage()

◆ getNumOutputChannelsGivenInputs()

◆ producesAudioWhenNoAudioInput()

◆ noTail()

◆ getChannelNames()

◆ getBusses()

◆ takesAudioInput()

◆ takesMidiInput()

◆ isSynth()

◆ getLatencySeconds()

◆ getTailLength()

◆ canSidechain()

◆ addParam() [1/2]

◆ addParam() [2/2]

◆ getInputChannelNames()

◆ getSidechainSourceNames()

◆ setSidechainSourceByName()

◆ getSidechainSourceName()

◆ guessSidechainRouting()

◆ getNumWires()

◆ getWire()

◆ makeConnection()

◆ breakConnection()

◆ hasNameForMidiNoteNumber()

◆ hasNameForMidiProgram()

◆ hasNameForMidiBank()

◆ canBeAddedToClip()

◆ canBeAddedToRack()

◆ canBeAddedToFolderTrack()

◆ canBeAddedToMaster()

◆ canBeDisabled()

◆ canBeMoved()

◆ needsConstantBufferSize()