AudioEffectX

class AudioEffectX : public AudioEffect;

Just as the VST 1.0 specification was built around a class AudioEffect, the VST 2.0 specification is built around a new core class AudioEffectX. We start with a complete discussion of the AudioEffectX class and its methods, which declares all new VST 2.0 (2.1, 2.2 and 2.3) features as seen from plug-in point of view.

General new features of version 2.0 / 2.1 / 2.2 / 2.3

New Universal Basic Methods

There is a basic set of methods that your plug should support (with *), even if you have a 1.0 version working already. These are all found in the new AudioEffectX class.

Version 1.0
11/12/98
Version 2.0
12/07/99
Version 2.1
08/06/00
Version 2.2
08/06/01
Version 2.3
20/05/03
Host -> Plug

setParameter *
getParameter *
process *
processReplacing *
dispatcher
open
close
getProgram *
setProgram *
setProgramName *
getProgramName *
getParameterLabel *
getParameterDisplay *
getParameterName *
getVu
getChunk
setChunk
setSampleRate
setBlockSize
suspend
resume


Internal / Tools

getAeffect
setEditor
setUniqueID
setNumInputs
setNumOutputs
hasVu
hasClip
canMono
canProcessReplacing
setRealtimeQualities
setOfflineQualities
setInitialDelay
programsAreChunks
getSampleRate
getBlockSize
dB2string
Hz2string
ms2string
float2string
long2string


Plug -> Host

setParameterAutomated
getMasterVersion
getCurrentUniqueId
masterIdle
isInputConnected
isOutputConnected

Host -> Plug

canDo *
canParameterBeAutomated
copyProgram
fxIdle
getChannelParameter
getNumCategories
getProgramNameIndexed *
getInputProperties
getOutputProperties
getIcon
getEffectName
getErrorText
getGetTailSize
getParameterProperties
getPlugCategory *
getProductString *
getVendorString *
getVendorVersion
getVstVersion
inputConnected
outputConnected
keysRequired
offlineNotify
offlineGetNumPasses
offlineGetNumMetaPasses
offlinePrepare
offlineRun
processEvents
processVariableIo
reportCurrentPosition
reportDestinationBuffer
setBlockSizeAndSampleRate
setBypass *
setSpeakerArrangement
setViewPosition
string2parameter *
vendorSpecific


Plug -> Host

canHostDo
closeWindow
openWindow
ioChanged
getTimeInfo
sendVstEventsToHost
needIdle
sizeWindow
updateSampleRate
updateBlockSize
getAutomationState
getCurrentProcessLevel
getDirectory
getHostProductString
getHostVendorVersion
getHostVendorString
getHostLanguage
getInputLatency
getOutputLatency
getNextPlug
getPreviousPlug
getNumAutomatableParameters
getParameterQuantization
getSpeakerArrangement
hasExternalBuffer
hostVendorSpecific
isSynth
noTail
offlineGetCurrentMetaPass
offlineGetCurrentPass
offlineRead
offlineStart
offlineWrite
setOutputSamplerate
tempoAt
updateDisplay
wantAsyncOperation
wantEvents
willProcessReplacing

Host -> Plug

getMidiProgramName
getCurrentMidiProgram
getMidiProgramCategory
hasMidiProgramsChanged
getMidiKeyName
beginSetProgram
endSetProgram



Plug -> Host

beginEdit
endEdit
openFileSelector

Plug -> Host

closeFileSelector
getChunkFile

Host -> Plug

setTotalSampleToProcess
getNextShellPlugin
startProcess
stopProcess
setPanLaw
beginLoadBank
beginLoadProgram



Internal / Tools

allocateArrangement
deallocateArrangement
copySpeaker
matchArrangement




Constructor and Destructor


AudioEffectX

AudioEffectX (audioMasterCallback audioMaster, long numPrograms, long numParams);

The constructor method. Same arguments as AudioEffect .


~AudioEffectX

virtual ~AudioEffectX ();

The destructor method. See ~AudioEffect .


'host' are methods which go from plug to host, and are usually not overridden 'plug' are methods which you may override to implement the according functionality (to host) also note that a return value of 0 of either methods almost always indicates 'not implemented'.


Parameters and Programs


getNumAutomatableParameters (->host)

virtual long getNumAutomatableParameters ();

Asks the host application about the maximum number of automatable parameters, which may be limited.

return
0 : Not implemented.
other : The number of automatable parameters.

getParameterQuantization (->host)

virtual long getParameterQuantization ();

Parameter index in <value> (-1: all, any). When the application stores and restores automation data, or when a user control (like a fader or knob) is quantized to integer values, there is some quantization applied related to the floating point value.

return
0 : Not implemented.
1 : Full single float precision is maintained in automation.
other : The integer value that represents +1.0.

beginLoadBank  (->host)

virtual long beginLoadBank (VstPatchChunkInfo* ptr);

Called before a bank is loaded.

return
0 : Not implemented.
1 : The bank can be loaded.
-1  : The bank can't be loaded.

beginLoadProgram  (->host)

virtual long beginLoadProgram (VstPatchChunkInfo* ptr);

Called before a Program is loaded. (called before beginSetProgram).

return
0 : Not implemented.
1 : The Program can be loaded.
-1  : The Program cannot be loaded..

canParameterBeAutomated (->plug)

virtual bool canParameterBeAutomated (long index);

Indicates if a parameter can be automated. Obviously only useful when the application supports this.

index An index to the parameter.
return
true : Can be autoimated.
false : Can not.

string2parameter (->plug)

virtual bool string2parameter (long index, char *text);

Convert a string representation to a parameter value. Especially useful for plug-ins without user interface. The application can then implement a text edit field for the user to set a parameter by entering text.

index The index to the parameter.
text A textual description oif the parameter's value. A null pointer is used to check the capability (return true).
return
true : Success.
false : Failure.

Note: implies setParameter .


getChannelParameter (->plug)

virtual float getChannelParameter (long channel, long index);

For internal use of soft synth voices, as a voice may be channel dependant.


getNumCategories (->plug)

virtual long getNumCategories ();

If you support of more than 1 category (i.e. if programs are divided into groups, like in General MIDI), override this.


getProgramNameIndexed (->plug)

virtual bool getProgramNameIndexed (long category, long index, char *text);

Fill text with the name of program <index> in <category>. Allows a host application to list your programs (presets).

category If -1, program indices are enumerated linearily (as usual). Otherwise, each category starts over with index 0.
index The index to the program in a given category, starting with 0.
text A string up to 24 chars.
return
true : Success.
false : Failure.

This should be supported (see the general 2.0 additions ).

Example :

bool MyPlug::getProgramNameIndexed (long category, long index, char *text)
{
	bool returnCode = false;
	
	if (index < kNumPrograms)
	{
		strcpy (text, programs[index].name);
		returnCode = true;
	}
	return (returnCode);
}

copyProgram (->plug)

virtual bool copyProgram (long destination);

Copy currently selected program to program destination.

destination The index of the target program.
return
true : Success.
false : Failure.

This should be supported (see the general 2.0 additions ).

Example :

bool MyPlug::copyProgram (long destination)
{
	bool returnCode = false;
	if (destination < kNumPrograms)
	{
		programs[destination] = programs[curProgram];
		returnCode = true;
	}
	return (returnCode);
}

beginSetProgram (->plug)

virtual bool beginSetProgram ();


Called before a program is loaded.

state
true : The plug took the notification into account.
false : It didn't...


endSetProgram (->plug)

virtual bool endSetProgram ();

Called after a program is loaded.

state
true : The plug took the notification into account.
false : It didn't...


Connections and Configuration


ioChanged (->host)

virtual bool ioChanged ();

Tell host numInputs and/or numOutputs and/or initialDelay has changed. The host could call a suspend (if the plugin was enabled (in resume state)) and then ask for getSpeakerArrangement and/or check the numInputs and numOutputs and initialDelay and then call a resume.

return
true : Success, host supports this feature.
false : Failure.

See also :


needIdle (->host)

virtual bool needIdle ();

Tells host plug needs idle calls (outside its editor window). Some plugs need idle calls even when their editor is closed.

return
true : Success, host supports this feature.
false : Failure.

sizeWindow (->host)

virtual bool sizeWindow (long width, long height);

Requests to resize the editor window.

width The window's width in pixel.
height The window's height in pixel.
return
true : Success.
false : Failure.

updateSampleRate (->host)

virtual double updateSampleRate ();

Returns the sample rate from host.

return The host's sample rate.

Will cause application to call AudioEffect's setSampleRate method to be called (when implemented).


updateBlockSize (->host)

virtual long updateBlockSize ();

Returns the block size from host.

return The host's block size.

Will cause application to call AudioEffect's setBlockSize method to be called (when implemented).


getInputLatency (->host)

virtual long getInputLatency ();

Returns the ASIO input latency values.

return The ASIO input latency.

See also :


getOutputLatency (->host)

virtual long getOutputLatency ();

Returns the ASIO output latency values. while inputLatency is probably not of concern, outputLatency may be used in conjunction with getTimeInfo . samplePos of VstTimeInfo is ahead of the 'visual' sequencer play time by the output latency, such that when outputLatency samples have passed by, our processing result becomes audible.

return The ASIO output latency.

See also :


getPreviousPlug (->host)

virtual AEffect *getPreviousPlug (long input);

For future expansion.

input An index to a pin, as several plugs may be connected on several pins. input can be -1 in which case the first found is returned.
return A pointer to an AEffect structure.

getNextPlug (->host)

virtual AEffect *getNextPlug (long output);

For future expansion.

output An index to a pin, as several plugs may be connected on several pins. output can be -1 in which case the first found is returned.
return A pointer to an AEffect structure.

setPanLaw  (->host)

virtual bool setPanLaw (long type, float val);

Set the Panning Law used by the host (in Gain : 0.5 is -6.02dB).

type
The type of the panning law.
Could be (defined via an enum):
kLinearPanLaw = 0 L = pan * M; R = (1 - pan) * M.
kEqualPowerPanLaw L = pow (pan, 0.5) * M;
R = pow ((1 - pan), 0.5) * M;
val
in [0..1]
return true if the host manages to deal with this law.



inputConnected (->plug)

virtual void inputConnected (long index, bool state);

Input index has been (dis-)connected. The application may issue this call when implemented.

index The index to the input.
state
true : Connected.
false : Disconnected.

outputConnected (->plug)

virtual void outputConnected (long index, bool state);

Output index has been (dis-)connected. The application may issue this call when implemented.

index The index to the output.
state
true : Connected.
false : Disconnected.

getInputProperties (->plug)

virtual bool getInputProperties (long index, VstPinProperties *properties);

Stuff the VstPinProperties structure with info about the inputs for the host.

index The index to the input, starting with 0.
properties A pointer to a VstPinProperties structure.
return
true : Success.
false : Failure.

This should be supported (see the general 2.0 additions ).

Example :

bool MyPlug::getInputProperties (long index, VstPinProperties* properties)
{
	bool returnCode = false;
	if (index < kNumInputs)
	{
		sprintf (properties->label, "My %1d In", index + 1);
		properties->flags = kVstPinIsStereo | kVstPinIsActive;
		returnCode = true;
	}
	return returnCode;
}

getOutputProperties (->plug)

virtual bool getOutputProperties (long index, VstPinProperties *properties);

Return the properties of output index.

index The index to the output, starting with 0.
properties A pointer to a VstPinProperties structure.
return
true : Success.
false : Failure.

This should be supported (see the general 2.0 additions ).

Example :

bool MyPlug::getOutputProperties (long index, VstPinProperties* properties)
{
	bool returnCode = false;
	if (index < kNumOutputs)
	{
		sprintf (properties->label, "My %1d Out", index + 1);
		properties->flags = kVstPinIsStereo | kVstPinIsActive;
		returnCode = true;
	}
	return (returnCode);
}
// for plugin with 1 mono, 1 stereo and one 5.1 outputs (kNumOutputs = 9):
bool MyPlug::getOutputProperties (long index, VstPinProperties* properties)
{
	bool returnCode = false;
	if (index >= 0 && index < kNumOutputs)
	{
		properties->flags = kVstPinIsActive;
		if (index == 0) // mono
		{
			strcpy (properties->label, "Mono Out");
			properties->arrangementType = kSpeakerArrMono;
		}
		else if (index == 1) // stereo (1 -> 2)
		{
			strcpy (properties->label, "Stereo Out");
			properties->flags |= kVstPinIsStereo;
			properties->arrangementType = kSpeakerArrStereo;
		}
		else if (index >= 3) // 5.1 (3 -> 8)
		{
			strcpy (properties->label, "5.1 Out");
			properties->flags |= kVstPinUseSpeaker;
			properties->arrangementType = kSpeakerArr51;
			
			// for old VST Host < 2.3, make 5.1 to stereo/mono/mono/stereo (L R C Lfe Ls Rs)
			if (index == 3 || index == 7)
				properties->flags |= kVstPinIsStereo;
			if (index == 5)
				strcpy (properties->label, "Center");	
			else if (index == 6)
				strcpy (properties->label, "Lfe");	
			else if (index == 7) // (7 -> 8)
				strcpy (properties->label, "Stereo Back");
		}
		returnCode = true;
	}
	return returnCode;
}

getPlugCategory (->plug)

virtual VstPlugCategory getPlugCategory ();

Specify a category that fits the plug.

Example :

VstPlugCategory MyPlug::getPlugCategory ()
{
	return kPlugCategEffect;
}


setTotalSampleToProcess (->plug)

virtual long setTotalSampleToProcess (long value);

Called in offline (non RealTime) Process before process is called, indicates how many samples will be processed.
Actually returns value.


getNextSchellPlugin (->plug)

virtual long getNextShellPlugin (char* name);

name
 Points to a char buffer of size 64, which is to be filled with the name of the plugin including the terminating 0.
return
 Returns the next plugin's uniqueID.

This opcode is only called if plugin is of type kPlugCategShell. Note that each of the SubPlugins included in this shell must not be of the type kPlugCategShell.

Example:

//---From the Host side : if found plugin is a Shell category-----------
if (effect->getCategory () == kPlugCategShell)
{ 
	// scan shell for subplugins
	char tempName[64] = {0}; 
	long plugUniqueID = 0;
	while ((plugUniqueID = effect->dispatchEffect (effShellGetNextPlugin, 0, 0, tempName)) != 0)
	{ 
		// subplug needs a name 
		if (tempName[0] != 0)
		{
			...do what you want with this tempName and plugUniqueID
		}
	}
}


//---From the Host side : Intanciate a subplugin of a shell plugin---
// retreive the uniqueID of this subplugin the host wants to load
// set it to the host currentID
currentID = subplugInfo->uniqueID;

// call the its shell plugin (main function)
main ();

// the shell plugin will ask for the currentUniqueID
// and should return the chosen subplugin
...


//---From the plugin-Shell Side: for enumeration of subplugins---------

category = kPlugCategShell;
->can ask the host if "shellCategory" is supported

// at start (instanciation) reset the index for the getNextShellPlugin call.
myPluginShell::index = 0;

// implementation of getNextShellPlugin (char* name);
long myPluginShell::getNextShellPlugin (char* name)
{
	strcpy (name, MyNameTable[index]);
	return MyUniqueIDTable[index++];
}
....

//---From the plugin-Shell Side: when instanciation-----
long uniqueID = host->getCurrentUniqueID ();
if (uniqueID == 0) // the host instanciates the shell
{}
else // host try to instanciate one of my subplugin...identified by the uniqueID
{}

Realtime


willProcessReplacing (->host)

virtual long willProcessReplacing ();

Asks host if it will call the plug's processReplacing method. Remember all plugs should really support both methods, it's a matter of copy and paste but may significantly enhance audio performance.

return
0 : Not implemented. we don't know whether process or is called.
1 : Indicates that host will call processReplacing .
other : process (accumulating) will be used.

See also :


getCurrentProcessLevel (->host)

virtual long getCurrentProcessLevel ();

Returns the hosts's process level. A plug is like a black box processing some audio coming in on some inputs (if any) and going out of some outputs (if any). This may be used to do offline or real-time processing, and sometimes it may be desirable to know the current context.

return
0 : Not supported.
1 : Currently in user thread (gui).
2 : Currently in audio thread or irq (where process is called).
3 : Currently in 'sequencer' thread or irq (midi, timer etc).
4 : Currently offline processing and thus in user thread.
other : Not defined, but probably pre-empting user thread.

getAutomationState (->host)

virtual long getAutomationState ();

Returns the host's automation state.

return
0 : Not supported.
1 : Off.
2 : Read.
3 : Write.
4 : Read/write.

wantAsyncOperation (->host)

virtual void wantAsyncOperation (bool state = true);

Notify host that we want to operate asynchronously. process will return immedeately; host will poll reportCurrentPosition to see if data are available in time.

Support for plug-ins whose processing is actually carried out on external resources (dsp). The idea is to use asynchronous processing here. The host will call the process method as always, but the plug will only pass input data to its dsp, and return immediately. Now while the external processor does its work, the host may call other (native) audio processes which are not depending on the output of this plug. When the host is done, it will poll the plug's reportCurrentPosition method to learn if the external dsp is done, and then take the data from the plugs output buffer (reportDestinationBuffer ), or the 'regular' output buffers if none is provided.

state
true : Operate asynchronously.
false : Operate synchronously.

Use canHostDo ("asyncProcessing") to find out if this functionality is supported by the host.


hasExternalBuffer (->host)

virtual void hasExternalBuffer (bool state = true);

Notifies the host that the plug uses an external buffer, as external dsp, may have their own output buffer (32 bit float). The host then requests this via effGetDestinationBuffer. For dma access it may be more efficient for a plug with external dsp to provide its own buffers.

state
true : Plug provides its own output buffers.
false : Host expects output data in the output buffers passed to process as usual.

reportCurrentPosition (->plug)

virtual long reportCurrentPosition ();

Return how much data has been processed in external buffer. The host will poll reportCurrentPosition to see if data is available in time.

return The position in external buffer.

See also :


reportDestinationBuffer (->plug)

virtual float* reportDestinationBuffer ();

Return an external buffer. The host will take the data from the plugs output buffer once it nows from reportCurrentPosition that the external dsp has finished.

return A pointer to an external output buffer, or the 'regular' output buffers if none is provided.

See also :


startProcess (->plug)

virtual long startProcess ();

Called one time before the start of process call.

Example

resume () // the user activates the plugin (User Interface Thread)
startProcess () // Audio Thread
process () // or ProcessReplacing ()
process ()
process ()
process ()
stopProcess () // something has stopped the engine...or delayed the call
startProcess ()
process ()
process ()
process ()
process ()
stopProcess () // yet the user has really stopped the plugin (Off)
suspend ()

stopProcess (->plug)

virtual long stopProcess ();

Called after the stop of process call.


Other


setOutputSamplerate (->host)

virtual void setOutputSamplerate (float samplerate);

Used for variable I/O processing.

samplerate : The new sample rate.

getHostVendorString (->host)

virtual bool getHostVendorString (char* text);

Fills text with a string identifying the host's vendor.

text A string up to 64 chars.
return
true : Success.
false : Failure.

getHostProductString (->host)

virtual bool getHostProductString (char* text);

Fills text with a string identifying the host's name.

text A string up to 64 chars.
return
true : Success.
false : Failure.

getHostVendorVersion (->host)

virtual long getHostVendorVersion ();

Returns the host's vendor-specific version.

return The host's version.

hostVendorSpecific (->host)

virtual long hostVendorSpecific (long lArg1, long lArg2, void* ptrArg, float floatArg);

No definition.


canHostDo (->host)

virtual long canHostDo (char* text);

Asks host if it implements the feature text.

A plug-in cannot assume a 2.0 feature is available from the host. Use this method to ascertain the environment in which the plug finds itself. Ignoring this inquiry methods and trying to access a 2.0 feature in a 1.0 host will mean your plug-in or host application will break.

It is not the end-users job to pick and choose which plug-ins can be supported by which host.

text A string from hostCanDos .
return
0 : Don't know (default).
1 : Yes.
-1 : No.

isSynth (->host)

virtual void isSynth (bool state = true);

Tells the host that the plug is an instrument, i.e. that it will call the wantEvents method.

state
true : Is an instrument, the default.
false : A simple audio effect.

See also :


getMidiProgramName (->plug)

Purpose:

ask plugin if MidiPrograms are used and if so, query for names, numbers (ProgramChange-Number + BankSelect-Number), categories and keynames of each MidiProgram, on each Midi-channel.

Condition:

Plug canDo "midiProgramNames". No effect, if 0 is returned.

Caution:

don't mix concepts: the MidiPrograms are totally independent from all other programs present in VST. The main difference is, that there are upto 16 simultaneous active MidiPrograms (one per channel), while there can be only one active "VST"-Program. (You should see the "VST"-Program as the one single main global program, which contains the entire current state of the plugin.) This function can be called in any sequence.

Usage:

if that function is called, your plug has to read MidiProgramName::thisProgramIndex, fill out the other fields with the information assigned to a certain MidiProgram and return the number of available MidiPrograms on that MidiChannel.

Example:

your plug has 3 MidiPrograms on MidiChannel 0.

Host calls getMidiProgramName with idx = 0 and MidiProgramName::thisProgramIndex = 0.
Plug fills out:
MidiProgramName::name[64] = "Program A"
MidiProgramName::midiProgram = 0
MidiProgramName::midiBankMsb = -1
MidiProgramName::midiBankLsb = -1
MidiProgramName::parentCategoryIndex = -1
MidiProgramName::flags = 0 (if plug isn't "Omni").
Plug returns 3.
Host calls getMidiProgramName with idx = 0 and MidiProgramName::thisProgramIndex = 1.
Plug fills out:
MidiProgramName::name[64] = "Program B"
MidiProgramName::midiProgram = 1
MidiProgramName::midiBankMsb = -1
MidiProgramName::midiBankLsb = -1
MidiProgramName::parentCategoryIndex = -1
MidiProgramName::flags = 0 (if plug isn't "Omni").
Plug returns 3.
Host calls getMidiProgramName with idx = 0 and MidiProgramName::thisProgramIndex = 2.
Plug fills out:
MidiProgramName::name[64] = "Program C"
MidiProgramName::midiProgram = 2
MidiProgramName::midiBankMsb = -1
MidiProgramName::midiBankLsb = -1
MidiProgramName::parentCategoryIndex = -1
MidiProgramName::flags = 0 (if plug isn't "Omni").
Plug returns 3.

channel IN: MidiChannel. 0-15.
midiProgramName IN: points to MidiProgramName struct.
MidiProgramName::thisProgramIndex : IN: >= 0. fill struct for this program index.
MidiProgramName::name[64] : OUT: fill in the name of the program.
MidiProgramName::midiProgram : OUT: -1:off, 0-127.
MidiProgramName::midiBankMsb : OUT: -1:off, 0-127.
MidiProgramName::midiBankLsb : OUT: -1:off, 0-127.
MidiProgramName::parentCategoryIndex : OUT: -1: no parent category, >= 0: Categ.Index.
MidiProgramName::flags : OUT: Set to "kMidiIsOmni", when MidiChannel is ignored.
MidiProgramName::reserved : IGNORE: Undefined, don't touch.
return number of available MidiPrograms on that channel

See also :


getCurrentMidiProgram (->plug)

Purpose:

ask plugin for the currently active program on a certain MidiChannel.

Condition:

Plug canDo "midiProgramNames" and initial getMidiProgramName-call did not return 0.

Usage:

just like getMidiProgramName, but MidiProgramName::thisProgramIndex has to be filled out with the currently active MidiProgram-index, which also has to be returned.
channel IN: MidiChannel. 0-15.
currentProgram IN: points to MidiProgramName struct.
MidiProgramName::thisProgramIndex : OUT: >= 0. currently active MidiProgram-index.
MidiProgramName::name[64] : OUT: fill in the name of the program.
MidiProgramName::midiProgram : OUT: -1:off, 0-127.
MidiProgramName::midiBankMsb : OUT: -1:off, 0-127.
MidiProgramName::midiBankLsb : OUT: -1:off, 0-127.
MidiProgramName::parentCategoryIndex : OUT: -1: no parent category, >= 0: Categ.Index.
MidiProgramName::flags : OUT: Set to "kMidiIsOmni", when MidiChannel is ignored.
MidiProgramName::reserved : IGNORE: Undefined, don't touch.
return currently active MidiProgram-index

See also :


getMidiProgramCategory (->plug)

Purpose:

MidiPrograms can be grouped in a category-tree (eg. Instrument-Type, Bank).

Condition:

Plug canDo "midiProgramNames", initial getMidiProgramName-call did not return 0 and an earlier call to "getMidiProgramName", "getCurrentMidiProgram" or "getMidiProgramCategory" returned a value >= 0 in the field MidiProgramName::parentCategoryIndex / MidiProgramCategory::parentCategoryIndex.

Usage:

similar to getMidiProgramName, but is recursive: you can have categories in categories in ..., when you return a number >= 0 in MidiProgramCategory::parentCategoryIndex.
channel IN: MidiChannel. 0-15.
category IN: points to MidiProgramCategory struct.
MidiProgramCategory::thisCategoryIndex : IN: >= 0. fill struct for this category index.
MidiProgramCategory::name[64] : OUT: fill in the name of the category.
MidiProgramCategory::parentCategoryIndex : OUT: -1: no parent category, >= 0: Categ.Index.
MidiProgramCategory::flags : IGNORE: Undefined, don't touch.
return number of available categories on that channel. If 0, no categories supported.

See also :


hasMidiProgramsChanged (->plug)

Purpose:

the host asks the plug (whenever he wants), if anything (except currentMidiProgram) in the MidiProgramNames has changed (since the last scan) on a specific MidiChannel. If the plugin returns true, the host will rescan the entire MidiProgramNames, MidiProgramCategories and MidiKeyNames.

Condition:

Plug canDo "midiProgramNames" and initial getMidiProgramName-call did not return 0.

Usage:

you should only return true, if the user loaded another soundbank or renamed a MidiProgram / MidiProgramCategory / MidiKeyName. When returning true, you should immediatly reset this flag to false, otherwise the host might think, that the new scan is invalid again. Initially you should return false (because there was no previous scan).
channel IN: MidiChannel. 0-15.
state
true : Names have changed since last scan.
false : Names haven't changed.

See also :


getMidiKeyName (->plug)

Purpose:

each MidiProgram can have a set of keynames, that defines which SoundName is triggered by which MidiNoteNumber. Usefull for drumsets, samplers and split-zones.

Condition:

Plug canDo "midiProgramNames" and initial getMidiProgramName-call did not return 0.
channel IN: MidiChannel. 0-15.
keyName IN: points to MidiKeyName struct.
MidiKeyName::thisProgramIndex : IN: >= 0. fill struct for this program index.
MidiKeyName::thisKeyNumber : IN: 0 - 127. fill struct for this key number.
MidiKeyName::keyName[64] : OUT: fill in the name of the NoteNumber.
MidiKeyName::reserved : IGNORE: Undefined, don't touch.
MidiKeyName::flags : IGNORE: Undefined, don't touch.
state
true : MidiProgram has keynames.
false : MidiProgram has no keynames.

See also :


noTail (->host)

virtual void noTail (bool state = true);

Tells the host that no data will be produced when silence comes in.

state
true : Host can omit to call process when no data is present on any input.
false : Host should allways call process.

See also :


getHostLanguage (->host)

virtual long getHostLanguage ();

Returns the host's language.

return Any constant in VstHostLanguage :
kVstLangEnglish
kVstLangGerman
kVstLangFrench
kVstLangItalian
kVstLangSpanish
kVstLangJapanese

openWindow (->host)

virtual void* openWindow (VstWindow* vstWindow);

Creates a new window.

vstWindow A pointer to a VstWindow structure.
return A pointer to the newly created window (WindowPtr on mac.

See also :


closeWindow (->host)

virtual bool closeWindow (VstWindow* vstWindow);

Closes a newly created window.

vstWindow A pointer to a VstWindow structure.
return
true : Success.
false : Failure.

See also :


getDirectory (->host)

virtual void* getDirectory ();

Returns the plug's containing directory.

return FSSpec on mac, else char *.

updateDisplay (->host)

virtual bool updateDisplay();

Something has changed, update 'multi-fx' display.

return
true : Success.
false : Failure.

processVariableIo (->plug)

virtual bool processVariableIo ( VstVariableIo* varIo);

Used for variableIo processing.

varIo : A pointer to a VstVariableIo structure.
return
true : Success.
false : Failure.

setSpeakerArrangement (->plug)

virtual bool setSpeakerArrangement (VstSpeakerArrangement* pluginInput, VstSpeakerArrangement *pluginOutput);

Set the plug's speaker arrangements. With a VST 2.3 Plugin if it returns true, it means that the plugin accepts this IO arrangement. The host doesn't need to ask for getSpeakerArrangement. If the plugin returns false, it means that it doesn't accept this arrangement, the host should then ask for getSpeakerArrangement and then can (optional) recall setSpeakerArrangement.

pluginInput A pointer to the input's VstSpeakerArrangement structure.
pluginOutput A pointer to the output's VstSpeakerArrangement structure.
return
true : Success.
false : Failure.

See also :


getSpeakerArrangement (->plug)

virtual bool getSpeakerArrangement (VstSpeakerArrangement** pluginInput, VstSpeakerArrangement** pluginOutput);

Gets the speaker arrangement of the Plugin.

pluginInput A pointer to the input's VstSpeakerArrangement structure.
pluginOutput A pointer to the output's VstSpeakerArrangement structure.
return
true : Success.
false : Failure.

See also :


setBlockSizeAndSampleRate (->plug)

virtual void setBlockSizeAndSampleRate (long blockSize, float sampleRate)

Set the sample rate and block size.

More handy than the seperate methods setBlockSize and setSampleRate.
blockSize A pointer to the input's The plug's new block size.
sampleRate The plug's new sample rate.

See also :


setBypass (->plug)

virtual bool setBypass (bool onOff);

For 'soft-bypass'; process still called (if Supported). Some plugs need to stay 'alive' even when bypassed. An example is a surround decoder which has more inputs than outputs and must maintain some reasonable signal distribution even when being bypassed. A CanDo 'bypass' allows to ask the plugin if it supports softbayppas or not.

onOff
true :
false :
return
true : Supports SoftBypass, process will be called, the plug should compensate its delay, and copy inputs to outputs.
false : doesnt support SoftBypass, process will not be called, the host should bypass the process call.

See also :


getEffectName (->plug)

virtual bool getEffectName (char* name)

Fill text with a string identifying the effect.

This should be supported.

name A string up to 32chars.
return
true Success.
false Failure.

See also :

Example :

bool MyPlug::getEffectName (char* name)
{
	strcpy (name, "MyPlug");
	return true;
}

getErrorText (->plug)

virtual bool getErrorText (char* text)

Fill text with an error string.

text A string up to 256chars.
return
true Success.
false Failure.

getVendorString (->plug)

virtual bool getVendorString (char* text)

Fill text with a string identifying the vendor.

This should be supported.

text A string up to 64chars.
return
true Success.
false Failure.

See also :

Example :

bool MyPlug::getVendorString (char* text)
{
	strcpy (text, "My Company");
	return (true);
}

getProductString (->plug)

virtual bool getProductString (char* text)

Fill text with a string identifying the product name.

This should be supported.

text A string up to 64chars.
return
true Success.
false Failure.

See also :

Example :

bool MyPlug::getProductString (char* text)
{
	strcpy (text, "My Plug Soft Synth");
	return (true);
}

getVendorVersion (->plug)

virtual long getVendorVersion ();

Return vendor-specific version.

This should be supported.

return The version of the plug.

See also :

Example :

bool MyPlug::getVendorVersion ()
{
	return 1000; // for 1.0.0.0
}

vendorSpecific (->plug)

virtual long vendorSpecific (long lArg, long lArg2, void* ptrArg, float floatArg);

No definition, vendor specific handling.


canDo (->plug)

virtual long canDo (char* text)

Report what the plug is able to do. In general you can but don't have to report whatever you support or not support via canDo. Some application functionality may require some specific reply, but in that case you will probably know. Best is to report whatever you know for sure.

A host application cannot make assumptions about the presence of the new 2.0 features of a plug-in. Ignoring this inquiry methods and trying to access a 2.0 feature from a 1.0 plug, or vice versa, will mean the plug-in or host application will break. It is not the end-users job to pick and choose which plug-ins can be supported by which host.

This should be supported.

text A string from plugCanDos .
return
0 Don't know (default).
1 Yes.
-1 No.

See also :

Example :

long MyPlug::canDo (char* text)
{
long returnCode = 0L;

if (!strcmp (text, "receiveVstEvents"))
returnCode = 1L;
else if (!strcmp (text, "receiveVstMidiEvent"))
returnCode = 1L;

return (returnCode);
}

This set of canDo's (receiveVstEvents and receiveVstMidiEvent) is how Virtual Instruments (synths based on VST2.0) declare to Cubase VST what they are capable of, and what events they need to be notified of.


getIcon (->plug)

virtual void* getIcon ()

Not yet defined. Could be a CBitmap .


setViewPosition (->plug)

virtual bool setViewPosition (long x, long y)

Set view position (in window) to (x, y).

x The horizontal position.
y The vertical position.
return
true : Success.
false : Failure, by default.

getGetTailSize (->plug)

virtual long getGetTailSize ();

Return after what time the response to an input sample will have die to zero. For instance, a reverb will have a tail somewhat similar to its reverbaration time, an IIR will 'never' die, and an FIR will usually die after a short amount of samples, but many plugs will have no tail at all. The application may decide to not call the plug's process method after it sounded out, and no input data will be applied (silence).

return
0 : Not supported, continuous calls to the process methods are required.
1 : No tail at all.
other : The duration, in samples, the plug needs to 'sound out'.

See also :


fxIdle (->plug)

virtual long fxIdle ();

return 0 by default.

getParameterProperties (->plug)

virtual bool getParameterProperties (long index, VstParameterProperties *p);

Stuff p with information about the parameter index .

index An index to the parameter.
p A pointer to a VstParameterProperties structure.
return
true : Success.
false : Failure.

beginEdit (->host)

virtual bool beginEdit (long index);


To be called before a setParameterAutomated with mouse move (one per Mouse Down). It tells the host that if it needs to, it has to record automation data for this control.

endEdit (->host)

virtual bool endEdit (long index);


To be called after a setParameterAutomated (on Mouse Up). It notifies the host that this control is no more moved by the mouse.


keysRequired (->plug)

virtual bool keysRequired ();

Return if keys are needed or not.

return
true : Keys are needed, the default for VST-1.0 plugs.
false : Keys are not needed.

getVstVersion (->plug)

virtual long getVstVersion ();

Return the VST-specification the plug is derived from.

return
2 : By default for VST-2.0 plugs.
0 : Older versions.


openFileSelector (->plug)

virtual bool openFileSelector (VstFileSelect *ptr);

Open a host File selector (see VstFileSelect).



closeFileSelector (->plug)

bool closeFileSelector (VstFileSelect *ptr);

Close the file selector.



getChunkFile (->plug)

bool getChunkFile (void* nativePath);

nativePath will point (if true is returned) to the path of the chunk file.



allocateArrangement (tool)

virtual bool allocateArrangement (VstSpeakerArrangement** arrangement, long nbChannels);

Allocate memory for a VstSpeakerArrangement containing the given number of channels.



deallocateArrangement (tool)

virtual bool deallocateArrangement (VstSpeakerArrangement* arrangement);

delete/free memory for a speaker arrangement



copySpeaker (tool)

virtual bool copySpeaker (VstSpeakerProperties* to, VstSpeakerProperties* from);

feed the "to" speaker properties with the same values than "from"'s ones. It is assumed here that "to" exists yet, ie this function won't allocate memory for the speaker (this will prevent from having a difference between an Arrangement's number of channels and its actual speakers...)



matchArrangement (tool)

virtual bool matchArrangement (VstSpeakerArrangement** to, VstSpeakerArrangement* from);

"to" is deleted, then created and initialized with the same values as "from" ones ("from" must exist).
It's notably useful when setSpeakerArrangement is called by the host.




Copyright 2003 Steinberg Media Technologies GmbH. All Rights Reserved.

Last Modified: