AudioEffectX
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
-
Plug-ins that can receive MIDI events from the host application and then
"render" audio however they please.
-
A protocol defining how a plug-in can obtain time & tempo information from
the host application in a variety of formats.
-
A complete interface definition between host and plug-in defining off-line audio
processes. Apart from these new capabilities, there is a whole batch of new
methods on both the plug-in and application side of the VST Plug-in interface.
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.
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'.
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. |
|
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)
Called before a bank is loaded.
return |
0 : |
Not implemented. |
1 : |
The bank can be loaded. |
-1 : |
The bank can't be loaded . |
|
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.. |
|
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. |
|
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
.
virtual float getChannelParameter (long channel, long index);
For internal use of soft synth voices, as a voice may be channel dependant.
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.
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);
}
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);
}
virtual bool beginSetProgram ();
Called before a program is loaded.
state |
true : |
The plug took the notification into account.
|
false : |
It didn't...
|
|
virtual bool endSetProgram ();
Called after a program is loaded.
state |
true : |
The plug took the notification into account.
|
false : |
It didn't...
|
|
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 :
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. |
|
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. |
|
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).
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).
virtual long getInputLatency ();
Returns the ASIO input latency values.
return |
The ASIO input latency. |
See also :
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 :
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. |
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. |
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.
|
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. |
|
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. |
|
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;
}
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;
}
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
.
virtual long getNextShellPlugin (char* name);
This opcode is only called if plugin is of type kPlugCategShell.
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.
|
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 :
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. |
|
virtual long getAutomationState ();
Returns the host's automation state.
return |
0 : |
Not supported. |
1 : |
Off. |
2 : |
Read. |
3 : |
Write. |
4 : |
Read/write. |
|
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.
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. |
|
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 :
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.
stopProcess (->plug)
virtual long stopProcess ();
Called after the stop of process call.
virtual void setOutputSamplerate (float samplerate);
Used for variable I/O processing.
samplerate : |
The new sample rate. |
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. |
|
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. |
|
virtual long getHostVendorVersion ();
Returns the host's vendor-specific version.
return |
The host's version. |
virtual long hostVendorSpecific (long lArg1, long lArg2, void* ptrArg, float floatArg);
No definition.
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. |
|
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 :
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 :
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 :
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 :
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 :
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 :
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 :
virtual long getHostLanguage ();
Returns the host's language.
return |
Any constant in VstHostLanguage :
kVstLangEnglish |
kVstLangGerman |
kVstLangFrench |
kVstLangItalian |
kVstLangSpanish |
kVstLangJapanese |
|
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 :
virtual bool closeWindow (
VstWindow* vstWindow);
Closes a newly created window.
vstWindow |
A pointer to a VstWindow structure. |
return |
true : |
Success. |
false : |
Failure. |
|
See also :
virtual void* getDirectory ();
Returns the plug's containing directory.
return
|
FSSpec on mac, else char * . |
virtual bool updateDisplay();
Something has changed, update 'multi-fx' display.
return |
true : |
Success. |
false : |
Failure. |
|
Used for variableIo processing.
varIo : |
A pointer to a VstVariableIo
structure. |
return |
true : |
Success. |
false : |
Failure. |
|
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.
See also :
Gets the speaker arrangement of the Plugin.
See also :
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 :
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 |
|
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 :
virtual bool getEffectName (char* name)
Fill text
with a string identifying the effect.
This should be supported.
name |
A string up to 32char s. |
return |
true |
Success. |
false |
Failure. |
|
See also :
Example :
bool MyPlug::getEffectName (char* name)
{
strcpy (name, "MyPlug");
return true;
}
virtual bool getErrorText (char* text)
Fill text
with an error string.
text |
A string up to 256char s. |
return |
true |
Success. |
false |
Failure. |
|
virtual bool getVendorString (char* text)
Fill text
with a string identifying the vendor.
This should be supported.
text |
A string up to 64char s. |
return
|
true |
Success. |
false |
Failure. |
|
See also :
Example :
bool MyPlug::getVendorString (char* text)
{
strcpy (text, "My Company");
return (true);
}
virtual bool getProductString (char* text)
Fill text with a string identifying the product name.
This should be supported.
text |
A string up to 64char s. |
return
|
true |
Success. |
false |
Failure. |
|
See also :
Example :
bool MyPlug::getProductString (char* text)
{
strcpy (text, "My Plug Soft Synth");
return (true);
}
virtual long getVendorVersion ();
Return vendor-specific version.
This should be supported.
return |
The version of the plug. |
See also :
Example :
bool MyPlug::getVendorVersion ()
{
return (1);
}
virtual long vendorSpecific (long lArg, long lArg2, void* ptrArg, float floatArg);
No definition, vendor specific handling.
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.
virtual void* getIcon ()
Not yet defined. Could be a CBitmap
.
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. |
|
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 :
virtual long fxIdle ();
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. |
|
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.
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.
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. |
|
virtual long getVstVersion ();
Return the VST-specification the plug is derived from.
return |
2 : |
By default for VST-2.0 plugs. |
0 : |
Older versions. |
|
Open a host File selector (see VstFileSelect).
Close the file selector.
bool getChunkFile (void* nativePath);
nativePath will point (if true is returned) to the path of the chunk file.
Allocate memory for a VstSpeakerArrangement containing the given number of
channels.
delete/free memory for a speaker arrangement
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...)
"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.