#include <DafPlugin.hpp>

Public Member Functions
	Plugin (uint32_t parameterCount, uint32_t programCount, uint32_t stateCount)
virtual	~Plugin ()
uint32_t	getBufferSize () const noexcept
double	getSampleRate () const noexcept
const char *	getBundlePath () const noexcept
bool	isDummyInstance () const noexcept
bool	isSelfTestInstance () const noexcept
const TimePosition &	getTimePosition () const noexcept
void	setLatency (uint32_t frames) noexcept
bool	writeMidiEvent (const MidiEvent &midiEvent) noexcept
bool	canRequestParameterValueChanges () const noexcept
bool	requestParameterValueChange (uint32_t index, float value) noexcept
bool	updateStateValue (const char key, const char value) noexcept

Protected Member Functions
virtual const char *	getName () const
virtual const char *	getLabel () const =0
virtual const char *	getDescription () const
virtual const char *	getMaker () const =0
virtual const char *	getHomePage () const
virtual const char *	getLicense () const =0
virtual uint32_t	getVersion () const =0
virtual int64_t	getUniqueId () const =0
virtual void	initAudioPort (bool input, uint32_t index, AudioPort &port)
virtual void	initParameter (uint32_t index, Parameter &parameter)
virtual void	initPortGroup (uint32_t groupId, PortGroup &portGroup)
virtual void	initProgramName (uint32_t index, String &programName)=0
virtual void	initState (uint32_t index, State &state)
virtual void	initState (uint32_t, String &, String &)
virtual bool	isStateFile (uint32_t)
virtual float	getParameterValue (uint32_t index) const
virtual bool	hasCustomParameterText (uint32_t) const
virtual bool	getParameterValueText (uint32_t, float, char *, uint32_t) const
virtual bool	getParameterValueFromText (uint32_t, const char *, float &) const
virtual void	setParameterValue (uint32_t index, float value)
virtual void	loadProgram (uint32_t index)
virtual int32_t	getCurrentProgram () const
virtual String	getState (const char *key) const
virtual void	setState (const char key, const char value)
virtual bool	validateStateValue (const char , const char ) const
virtual void	activate ()
virtual void	deactivate ()
virtual void	run (const float inputs, float outputs, uint32_t frames, const MidiEvent *midiEvents, uint32_t midiEventCount)=0
virtual void	bufferSizeChanged (uint32_t newBufferSize)
virtual void	sampleRateChanged (double newSampleRate)
virtual void	ioChanged (uint16_t numInputs, uint16_t numOutputs)

Friends
class	PluginExporter

Detailed Description

DAF Plugin class from where plugin instances are created.

The public methods (Host state) are called from the plugin to get or set host information.
They can be called from a plugin instance at anytime unless stated otherwise.
All other methods are to be implemented by the plugin and will be called by the host.

Shortly after a plugin instance is created, the various init* functions will be called by the host.
Host will call activate() before run(), and deactivate() before the plugin instance is destroyed.
The host may call deactivate right after activate and vice-versa, but never activate/deactivate consecutively.
There is no limit on how many times run() is called, only that activate/deactivate will be called in between.

The buffer size and sample rate values will remain constant between activate and deactivate.
Buffer size is only a hint though, the host might call run() with a higher or lower number of frames.

Some of this class functions are only available according to some macros.

DAF_PLUGIN_WANT_PROGRAMS activates program related features.
When enabled you need to implement initProgramName() and loadProgram().

DAF_PLUGIN_WANT_STATE activates internal state features.
When enabled you need to implement initState() and setState().

The process function run() changes wherever DAF_PLUGIN_WANT_MIDI_INPUT is enabled or not.
When enabled it provides midi input events.

Constructor & Destructor Documentation

◆ Plugin()

Plugin::Plugin	(	uint32_t	parameterCount,
		uint32_t	programCount,
		uint32_t	stateCount )

Plugin class constructor.
You must set all parameter values to their defaults, matching ParameterRanges::def.

◆ ~Plugin()

virtual Plugin::~Plugin ( )

virtual

Destructor.

Member Function Documentation

◆ getBufferSize()

uint32_t Plugin::getBufferSize ( ) const

noexcept

Get the current buffer size that will probably be used during processing, in frames.
This value will remain constant between activate and deactivate.

Note: This value is only a hint!
Hosts might call run() with a higher or lower number of frames.

See also: bufferSizeChanged(uint32_t)

◆ getSampleRate()

double Plugin::getSampleRate ( ) const

noexcept

Get the current sample rate that will be used during processing.
This value will remain constant between activate and deactivate.

See also: sampleRateChanged(double)

◆ getBundlePath()

const char * Plugin::getBundlePath ( ) const

noexcept

Get the bundle path where the plugin resides. Can return null if the plugin is not available in a bundle (if it is a single binary).

See also: getBinaryFilename; getResourcePath

◆ isDummyInstance()

bool Plugin::isDummyInstance ( ) const

noexcept

Check if this plugin instance is a "dummy" one used for plugin meta-data/information export.
When true no processing will be done, the plugin is created only to extract information.
In DAF, LADSPA/DSSI, VST2 and VST3 formats create one global instance per plugin binary while LV2 creates one when generating turtle meta-data.

◆ isSelfTestInstance()

bool Plugin::isSelfTestInstance ( ) const

noexcept

Check if this plugin instance is a "selftest" one used for automated plugin tests.
To enable this mode build with DAF_RUNTIME_TESTING macro defined (i.e. set as compiler build flag), and run the JACK/Standalone executable with "selftest" as its only and single argument.

A few basic DSP and UI tests will run in self-test mode, with once instance having this function returning true.
You can use this chance to do a few tests of your own as well.

◆ getTimePosition()

const TimePosition & Plugin::getTimePosition ( ) const

noexcept

Get the current host transport time position.
This function should only be called during run().
You can call this during other times, but the returned position is not guaranteed to be in sync.

Note: TimePosition is not supported in LADSPA and DSSI plugin formats.

◆ setLatency()

void Plugin::setLatency ( uint32_t frames )

noexcept

Change the plugin audio output latency to frames.
This function should only be called in the constructor, activate() and run().

Note: This function is only available if DAF_PLUGIN_WANT_LATENCY is enabled.

◆ writeMidiEvent()

bool Plugin::writeMidiEvent ( const MidiEvent & midiEvent )

noexcept

Write a MIDI output event.
This function must only be called during run().
Returns false when the host buffer is full, in which case do not call this again until the next run().

◆ canRequestParameterValueChanges()

bool Plugin::canRequestParameterValueChanges ( ) const

noexcept

Check if parameter value change requests will work with the current plugin host.

Note: This function is only available if DAF_PLUGIN_WANT_PARAMETER_VALUE_CHANGE_REQUEST is enabled.

See also: requestParameterValueChange(uint32_t, float)

◆ requestParameterValueChange()

bool Plugin::requestParameterValueChange	(	uint32_t	index,
		float	value )

noexcept

Request a parameter value change from the host. If successful, this function will automatically trigger a parameter update on the UI side as well. This function can fail, for example if the host is busy with the parameter for read-only automation. Some hosts simply do not have this functionality, which can be verified with canRequestParameterValueChanges().

Note: This function is only available if DAF_PLUGIN_WANT_PARAMETER_VALUE_CHANGE_REQUEST is enabled.

◆ updateStateValue()

bool Plugin::updateStateValue	(	const char *	key,
		const char *	value )

noexcept

Set state value and notify the host about the change.
This function will call setState() and also trigger an update on the UI side as necessary.
It must not be called during run.
The state must be host readable.
Returns false for an unknown key.
On CLAP, VST2, VST3 and JACK it may be called from any thread other than the audio one: setState() is called right away, while the UI and the host's "modified" flag are updated later on the host's main thread. A state the host saves in the meantime has the new value. VST2 and VST3 get there on the editor's idle, so with the editor closed the host is not told before it opens; a VST3 plugin without a UI tells the host on its next setActive instead.
Until the plugin is fully constructed, that is from its constructor and from initState() and the other init functions, there is no host to tell yet: the call does nothing and returns false.

Note: this function does nothing on DSSI plugin format, as DSSI only supports UI->DSP messages.

TODO API under construction

◆ getName()

virtual const char * Plugin::getName ( ) const

inlineprotectedvirtual

Get the plugin name.
Returns DAF_PLUGIN_NAME by default.

◆ getLabel()

virtual const char * Plugin::getLabel ( ) const

protectedpure virtual

Get the plugin label.
This label is a short restricted name consisting of only _, a-z, A-Z and 0-9 characters.

◆ getDescription()

virtual const char * Plugin::getDescription ( ) const

inlineprotectedvirtual

Get an extensive comment/description about the plugin.
Optional, returns nothing by default.

◆ getMaker()

virtual const char * Plugin::getMaker ( ) const

protectedpure virtual

Get the plugin author/maker.

◆ getHomePage()

virtual const char * Plugin::getHomePage ( ) const

inlineprotectedvirtual

Get the plugin homepage.
Optional, returns nothing by default.

◆ getLicense()

virtual const char * Plugin::getLicense ( ) const

protectedpure virtual

Get the plugin license (a single line of text or a URL).
For commercial plugins this should return some short copyright information.

◆ getVersion()

virtual uint32_t Plugin::getVersion ( ) const

protectedpure virtual

Get the plugin version, in hexadecimal.

See also: d_version()

◆ getUniqueId()

virtual int64_t Plugin::getUniqueId ( ) const

protectedpure virtual

Get the plugin unique Id.
This value is used by LADSPA, DSSI, VST2, VST3 and AUv2 plugin formats.

Note: It is preferred that you set DAF_PLUGIN_UNIQUE_ID macro instead of overriding this call, as that is required for AUv2 plugins anyhow.

See also: d_cconst()

◆ initAudioPort()

virtual void Plugin::initAudioPort	(	bool	input,
		uint32_t	index,
		AudioPort &	port )

protectedvirtual

Initialize the audio port index.
This function will be called once, shortly after the plugin is created.

◆ initParameter()

virtual void Plugin::initParameter	(	uint32_t	index,
		Parameter &	parameter )

protectedvirtual

Initialize the parameter index.
This function will be called once, shortly after the plugin is created.

◆ initPortGroup()

virtual void Plugin::initPortGroup	(	uint32_t	groupId,
		PortGroup &	portGroup )

protectedvirtual

Initialize the port group groupId.
This function will be called once, shortly after the plugin is created and all audio ports and parameters have been enumerated.

◆ initProgramName()

virtual void Plugin::initProgramName	(	uint32_t	index,
		String &	programName )

protectedpure virtual

Set the name of the program index.
This function will be called once, shortly after the plugin is created.
Must be implemented by your plugin class only if DAF_PLUGIN_WANT_PROGRAMS is enabled.

◆ initState()

virtual void Plugin::initState	(	uint32_t	index,
		State &	state )

protectedvirtual

Initialize the state index.
This function will be called once, shortly after the plugin is created.
Must be implemented by your plugin class only if DAF_PLUGIN_WANT_STATE is enabled.

◆ getParameterValue()

virtual float Plugin::getParameterValue ( uint32_t index ) const

protectedvirtual

Get the current value of a parameter.
The host may call this function from any context, including realtime processing.

◆ hasCustomParameterText()

virtual bool Plugin::hasCustomParameterText ( uint32_t ) const

inlineprotectedvirtual

Whether this parameter supplies custom text conversion callbacks. Custom conversion callbacks must be nonallocating and safe to call concurrently. When true, a callback returning false reports invalid conversion; adapters must not fall back to generic numeric parsing or formatting.

◆ getParameterValueText()

virtual bool Plugin::getParameterValueText	(	uint32_t	,
		float	,
		char *	,
		uint32_t	) const

inlineprotectedvirtual

Format a parameter-domain value into text without allocating. Null text or zero capacity must be handled safely by the override. Returns false when conversion is unavailable or the buffer is insufficient.

◆ getParameterValueFromText()

virtual bool Plugin::getParameterValueFromText	(	uint32_t	,
		const char *	,
		float &	) const

inlineprotectedvirtual

Parse text into a parameter-domain value without allocating. Null text must be handled safely by the override. Returns false when conversion is unavailable or invalid.

◆ setParameterValue()

virtual void Plugin::setParameterValue	(	uint32_t	index,
		float	value )

protectedvirtual

Change a parameter value.
The host may call this function from any context, including realtime processing.
When a parameter is marked as automatable, you must ensure no non-realtime operations are performed.

Note: This function will only be called for parameter inputs.

◆ loadProgram()

virtual void Plugin::loadProgram ( uint32_t index )

protectedvirtual

Load a program.
The host may call this function from any context, including realtime processing.
Must be implemented by your plugin class only if DAF_PLUGIN_WANT_PROGRAMS is enabled.

◆ getCurrentProgram()

virtual int32_t Plugin::getCurrentProgram ( ) const

inlineprotectedvirtual

Optional identity readback after a complete state recall.
Return the current factory program, or -1 when no program is known. This getter must be safe to call concurrently with processing.

◆ getState()

virtual String Plugin::getState ( const char * key ) const

protectedvirtual

Get the value of an internal state.
The host may call this function from any non-realtime context.
Must be implemented by your plugin class if DAF_PLUGIN_WANT_FULL_STATE is enabled.

Note: The use of this function breaks compatibility with the DSSI format.

◆ setState()

virtual void Plugin::setState	(	const char *	key,
		const char *	value )

protectedvirtual

Change an internal state key to value.
Must be implemented by your plugin class only if DAF_PLUGIN_WANT_STATE is enabled.

◆ validateStateValue()

virtual bool Plugin::validateStateValue	(	const char *	,
		const char *	) const

inlineprotectedvirtual

Validate a state value without changing the plugin. Called outside the audio callback. Override for complete sound snapshots so wrappers can reject a malformed recall before applying its program or parameters. The default preserves existing plugin behavior.

◆ activate()

virtual void Plugin::activate ( )

inlineprotectedvirtual

Activate this plugin.

◆ deactivate()

virtual void Plugin::deactivate ( )

inlineprotectedvirtual

Deactivate this plugin.

◆ run()

virtual void Plugin::run	(	const float **	inputs,
		float **	outputs,
		uint32_t	frames,
		const MidiEvent *	midiEvents,
		uint32_t	midiEventCount )

protectedpure virtual

Run/process function for plugins with MIDI input.

Note: Some parameters might be null if there are no audio inputs/outputs or MIDI events.

◆ bufferSizeChanged()

virtual void Plugin::bufferSizeChanged ( uint32_t newBufferSize )

protectedvirtual

Optional callback to inform the plugin about a buffer size change.
This function will only be called when the plugin is deactivated.

Note: This value is only a hint!
Hosts might call run() with a higher or lower number of frames.

See also: getBufferSize()

◆ sampleRateChanged()

virtual void Plugin::sampleRateChanged ( double newSampleRate )

protectedvirtual

Optional callback to inform the plugin about a sample rate change.
This function will only be called when the plugin is deactivated.

See also: getSampleRate()

◆ ioChanged()

virtual void Plugin::ioChanged	(	uint16_t	numInputs,
		uint16_t	numOutputs )

protectedvirtual

Optional callback to inform the plugin about audio port IO changes.
This function will only be called when the plugin is deactivated.
Used by AU, and by CLAP/VST3 for supported main-bus configurations declared with DAF_PLUGIN_EXTRA_IO.
With DAF_PLUGIN_SIDECHAIN_ON_EXTRA_IO (AU), numInputs can also be the declared main-bus layout for numOutputs plus a connected sidechain at its declared width or narrower (e.g. 1 + 1 = 2 with 1 output on a Logic mono track, 1 + 2 = 3 for a mono track keyed by a stereo sidechain). This applies only to a plugin with one sidechain bus, and to output counts whose declared combinations all put the same width on the main bus, so the main width follows from numOutputs. The input ports keep their declared positions: the sidechain stays on its own ports, and the channels a connected bus does not carry read silence.

See also: DAF_PLUGIN_EXTRA_IO

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

daf/DafPlugin.hpp

Public Member Functions

Protected Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ Plugin()

◆ ~Plugin()

Member Function Documentation

◆ getBufferSize()

◆ getSampleRate()

◆ getBundlePath()

◆ isDummyInstance()

◆ isSelfTestInstance()

◆ getTimePosition()

◆ setLatency()

◆ writeMidiEvent()

◆ canRequestParameterValueChanges()

◆ requestParameterValueChange()

◆ updateStateValue()

◆ getName()

◆ getLabel()

◆ getDescription()

◆ getMaker()

◆ getHomePage()

◆ getLicense()

◆ getVersion()

◆ getUniqueId()

◆ initAudioPort()

◆ initParameter()

◆ initPortGroup()

◆ initProgramName()

◆ initState()

◆ getParameterValue()

◆ hasCustomParameterText()

◆ getParameterValueText()

◆ getParameterValueFromText()

◆ setParameterValue()

◆ loadProgram()

◆ getCurrentProgram()

◆ getState()

◆ setState()

◆ validateStateValue()

◆ activate()

◆ deactivate()

◆ run()

◆ bufferSizeChanged()

◆ sampleRateChanged()

◆ ioChanged()