AudioEffect Class Reference

#include <audioeffect.h>

Inheritance diagram for AudioEffect:

AudioEffectX List of all members.

Public Member Functions

 AudioEffect (audioMasterCallback audioMaster, VstInt32 numPrograms, VstInt32 numParams)
 Create an AudioEffect object.
virtual ~AudioEffect ()
 Destroy an AudioEffect object.
virtual VstIntPtr dispatcher (VstInt32 opcode, VstInt32 index, VstIntPtr value, void *ptr, float opt)
 Opcodes dispatcher.
State Transitions
virtual void open ()
 Called when plug-in is initialized.
virtual void close ()
 Called when plug-in will be released.
virtual void suspend ()
 Called when plug-in is switched to off.
virtual void resume ()
 Called when plug-in is switched to on.
Processing
virtual void setSampleRate (float sampleRate)
 Called when the sample rate changes (always in a suspend state).
virtual void setBlockSize (VstInt32 blockSize)
 Called when the Maximun block size changes (always in a suspend state). Note that the sampleFrames in Process Calls could be smaller than this block size, but NOT bigger.
virtual void processReplacing (float **inputs, float **outputs, VstInt32 sampleFrames)=0
 Process 32 bit (single precision) floats (always in a resume state).
virtual void processDoubleReplacing (double **inputs, double **outputs, VstInt32 sampleFrames)
 Process 64 bit (double precision) floats (always in a resume state).
Parameters
virtual void setParameter (VstInt32 index, float value)
 Called when a parameter changed.
virtual float getParameter (VstInt32 index)
 Return the value of the parameter with index.
virtual void setParameterAutomated (VstInt32 index, float value)
 Called after a control has changed in the editor and when the associated parameter should be automated.
Programs and Persistence
virtual VstInt32 getProgram ()
 Return the index to the current program.
virtual void setProgram (VstInt32 program)
 Set the current program to program.
virtual void setProgramName (char *name)
 Stuff the name field of the current program with name. Limited to kVstMaxProgNameLen.
virtual void getProgramName (char *name)
 Stuff name with the name of the current program. Limited to kVstMaxProgNameLen.
virtual void getParameterLabel (VstInt32 index, char *label)
 Stuff label with the units in which parameter index is displayed (i.e. "sec", "dB", "type", etc...). Limited to kVstMaxParamStrLen.
virtual void getParameterDisplay (VstInt32 index, char *text)
 Stuff text with a string representation ("0.5", "-3", "PLATE", etc...) of the value of parameter index. Limited to kVstMaxParamStrLen.
virtual void getParameterName (VstInt32 index, char *text)
 Stuff text with the name ("Time", "Gain", "RoomType", etc...) of parameter index. Limited to kVstMaxParamStrLen.
virtual VstInt32 getChunk (void **data, bool isPreset=false)
 Host stores plug-in state. Returns the size in bytes of the chunk (plug-in allocates the data array).
virtual VstInt32 setChunk (void *data, VstInt32 byteSize, bool isPreset=false)
 Host restores plug-in state.
Internal Setup
virtual void setUniqueID (VstInt32 iD)
 Must be called to set the plug-ins unique ID!
virtual void setNumInputs (VstInt32 inputs)
 Set the number of inputs the plug-in will handle. For a plug-in which could change its IO configuration, this number is the maximun available inputs.
virtual void setNumOutputs (VstInt32 outputs)
 Set the number of outputs the plug-in will handle. For a plug-in which could change its IO configuration, this number is the maximun available ouputs.
virtual void canProcessReplacing (bool state=true)
 Tells that processReplacing() could be used. Mandatory in VST 2.4!
virtual void canDoubleReplacing (bool state=true)
 Tells that processDoubleReplacing() is implemented.
virtual void programsAreChunks (bool state=true)
 Program data is handled in formatless chunks (using getChunk-setChunks).
virtual void setInitialDelay (VstInt32 delay)
 Use to report the plug-in's latency (Group Delay).
Editor
void setEditor (AEffEditor *editor)
 Should be called if you want to define your own editor.
virtual AEffEditorgetEditor ()
 Returns the attached editor.
Inquiry
virtual AEffectgetAeffect ()
 Returns the AEffect structure.
virtual float getSampleRate ()
 Returns the current sample rate.
virtual VstInt32 getBlockSize ()
 Returns the current Maximum block size.
Host Communication
virtual VstInt32 getMasterVersion ()
 Returns the Host's version (for example 2400 for VST 2.4).
virtual VstInt32 getCurrentUniqueId ()
 Returns current unique identifier when loading shell plug-ins.
virtual void masterIdle ()
 Give idle time to Host application.
Tools (helpers)
virtual void dB2string (float value, char *text, VstInt32 maxLen)
 Stuffs text with an amplitude on the [0.0, 1.0] scale converted to its value in decibels.
virtual void Hz2string (float samples, char *text, VstInt32 maxLen)
 Stuffs text with the frequency in Hertz that has a period of samples.
virtual void ms2string (float samples, char *text, VstInt32 maxLen)
 Stuffs text with the duration in milliseconds of samples frames.
virtual void float2string (float value, char *text, VstInt32 maxLen)
 Stuffs text with a string representation on the floating point value.
virtual void int2string (VstInt32 value, char *text, VstInt32 maxLen)
 Stuffs text with a string representation on the integer value.

Protected Attributes

audioMasterCallback audioMaster
 Host callback.
AEffEditoreditor
 Pointer to the plug-in's editor.
float sampleRate
 Current sample rate.
VstInt32 blockSize
 Maximum block size.
VstInt32 numPrograms
 Number of programs.
VstInt32 numParams
 Number of parameters.
VstInt32 curProgram
 Current program.
AEffect cEffect
 AEffect object

Detailed Description

VST Effect Base Class (VST 1.0).


Constructor & Destructor Documentation

AudioEffect::AudioEffect ( audioMasterCallback  audioMaster,
VstInt32  numPrograms,
VstInt32  numParams 
)

Create an AudioEffect object.

The constructor of your class is passed a parameter of the type audioMasterCallback. The actual mechanism in which your class gets constructed is not important right now. Effectively your class is constructed by the hosting application, which passes an object of type audioMasterCallback that handles the interaction with the plug-in. You pass this on to the base class' constructor and then can forget about it.

Parameters:
audioMaster Passed by the Host and handles interaction
numPrograms Pass the number of programs the plug-in provides
numParams Pass the number of parameters the plug-in provides
MyPlug::MyPlug (audioMasterCallback audioMaster)
: AudioEffectX (audioMaster, 1, 1)    // 1 program, 1 parameter only
{
        setNumInputs (2); // stereo in
        setNumOutputs (2); // stereo out
        setUniqueID ('MyPl'); // you must change this for other plug-ins!
        canProcessReplacing (); // supports replacing mode
}

See also:
setNumInputs, setNumOutputs, setUniqueID, canProcessReplacing

AudioEffect::~AudioEffect (  )  [virtual]

Destroy an AudioEffect object.


Member Function Documentation

void AudioEffect::canDoubleReplacing ( bool  state = true  )  [virtual]

Tells that processDoubleReplacing() is implemented.

Parameters:
state Set to true if supported
Note:
Needs to be called in the plug-in's constructor

void AudioEffect::canProcessReplacing ( bool  state = true  )  [virtual]

Tells that processReplacing() could be used. Mandatory in VST 2.4!

Parameters:
state Set to true if supported
Note:
Needs to be called in the plug-in's constructor

virtual void AudioEffect::close (  )  [inline, virtual]

Called when plug-in will be released.

void AudioEffect::dB2string ( float  value,
char *  text,
VstInt32  maxLen 
) [virtual]

Stuffs text with an amplitude on the [0.0, 1.0] scale converted to its value in decibels.

Parameters:
value Value to convert
text String up to length char
maxLen Maximal length of the string

VstIntPtr AudioEffect::dispatcher ( VstInt32  opcode,
VstInt32  index,
VstIntPtr  value,
void *  ptr,
float  opt 
) [virtual]

Opcodes dispatcher.

void AudioEffect::float2string ( float  value,
char *  text,
VstInt32  maxLen 
) [virtual]

Stuffs text with a string representation on the floating point value.

Parameters:
value Value to convert
text String up to length char
maxLen Maximal length of the string

virtual AEffect* AudioEffect::getAeffect (  )  [inline, virtual]

Returns the AEffect structure.

virtual VstInt32 AudioEffect::getBlockSize (  )  [inline, virtual]

Returns the current Maximum block size.

VstInt32 AudioEffect::getChunk ( void **  data,
bool  isPreset = false 
) [inline, virtual]

Host stores plug-in state. Returns the size in bytes of the chunk (plug-in allocates the data array).

Parameters:
data should point to the newly allocated memory block containg state data. You can savely release it in next suspend/resume call.
isPreset true when saving a single program, false for all programs
Note:
If your plug-in is configured to use chunks (see AudioEffect::programsAreChunks), the Host will ask for a block of memory describing the current plug-in state for saving. To restore the state at a later stage, the same data is passed back to AudioEffect::setChunk. Alternatively, when not using chunk, the Host will simply save all parameter values.

VstInt32 AudioEffect::getCurrentUniqueId (  )  [virtual]

Returns current unique identifier when loading shell plug-ins.

See also:
AudioEffectX::getNextShellPlugin

virtual AEffEditor* AudioEffect::getEditor (  )  [inline, virtual]

Returns the attached editor.

VstInt32 AudioEffect::getMasterVersion (  )  [virtual]

Returns the Host's version (for example 2400 for VST 2.4).

Use to ask for the Host's version

Returns:
The Host's version

float AudioEffect::getParameter ( VstInt32  index  )  [inline, virtual]

Return the value of the parameter with index.

Return the value of parameter index

Parameters:
index Index of the parameter
Returns:
A float value between 0.0 and 1.0 inclusive

void AudioEffect::getParameterDisplay ( VstInt32  index,
char *  text 
) [inline, virtual]

Stuff text with a string representation ("0.5", "-3", "PLATE", etc...) of the value of parameter index. Limited to kVstMaxParamStrLen.

Parameters:
index Index of the parameter
text A string up to 8 char

void AudioEffect::getParameterLabel ( VstInt32  index,
char *  label 
) [inline, virtual]

Stuff label with the units in which parameter index is displayed (i.e. "sec", "dB", "type", etc...). Limited to kVstMaxParamStrLen.

Parameters:
index Index of the parameter
label A string up to 8 char

void AudioEffect::getParameterName ( VstInt32  index,
char *  text 
) [inline, virtual]

Stuff text with the name ("Time", "Gain", "RoomType", etc...) of parameter index. Limited to kVstMaxParamStrLen.

Parameters:
index Index of the parameter
text A string up to 8 char

VstInt32 AudioEffect::getProgram (  )  [inline, virtual]

Return the index to the current program.

Returns:
Index of the current program

void AudioEffect::getProgramName ( char *  name  )  [inline, virtual]

Stuff name with the name of the current program. Limited to kVstMaxProgNameLen.

The program name is displayed in the rack, and can be edited by the user.

Parameters:
name A string up to 24 char
Warning:
Please be aware that the string lengths supported by the default VST interface are normally limited to 24 characters. If you copy too much data into the buffers provided, you will break the Host application.

virtual float AudioEffect::getSampleRate (  )  [inline, virtual]

Returns the current sample rate.

void AudioEffect::Hz2string ( float  samples,
char *  text,
VstInt32  maxLen 
) [virtual]

Stuffs text with the frequency in Hertz that has a period of samples.

Parameters:
samples Number of samples
text String up to length char
maxLen Maximal length of the string

void AudioEffect::int2string ( VstInt32  value,
char *  text,
VstInt32  maxLen 
) [virtual]

Stuffs text with a string representation on the integer value.

Parameters:
value Value to convert
text String up to length char
maxLen Maximal length of the string

void AudioEffect::masterIdle (  )  [virtual]

Give idle time to Host application.

Give idle time to Host application, e.g. if plug-in editor is doing mouse tracking in a modal loop.

void AudioEffect::ms2string ( float  samples,
char *  text,
VstInt32  maxLen 
) [virtual]

Stuffs text with the duration in milliseconds of samples frames.

Parameters:
samples Number of samples
text String up to length char
maxLen Maximal length of the string

virtual void AudioEffect::open (  )  [inline, virtual]

Called when plug-in is initialized.

virtual void AudioEffect::processDoubleReplacing ( double **  inputs,
double **  outputs,
VstInt32  sampleFrames 
) [inline, virtual]

Process 64 bit (double precision) floats (always in a resume state).

See also:
processReplacing

void AudioEffect::processReplacing ( float **  inputs,
float **  outputs,
VstInt32  sampleFrames 
) [pure virtual]

Process 32 bit (single precision) floats (always in a resume state).

This process method must be provided. It takes input data, applies its pocessing algorithm, and then puts the result to the output by overwriting the output buffer.

Parameters:
inputs An array of pointers to the data
outputs An array of pointers to where the data can be written to
sampleFrames Number of sample frames to process
Warning:
Never call any Mac OS 9 functions (or other functions which call into the OS) inside your audio process function! This will crash the system when your plug-in is run in MP (multiprocessor) mode. If you must call into the OS, you must use MPRemoteCall () (see Apples' documentation), or explicitly use functions which are documented by Apple to be MP safe. On Mac OS X read the system header files to be sure that you only call thread safe functions.

void AudioEffect::programsAreChunks ( bool  state = true  )  [virtual]

Program data is handled in formatless chunks (using getChunk-setChunks).

Parameters:
state Set true if programs are chunks
Note:
Needs to be called in the plug-in's constructor

virtual void AudioEffect::resume (  )  [inline, virtual]

Called when plug-in is switched to on.

void AudioEffect::setBlockSize ( VstInt32  blockSize  )  [inline, virtual]

Called when the Maximun block size changes (always in a suspend state). Note that the sampleFrames in Process Calls could be smaller than this block size, but NOT bigger.

This is called by the Host, and tells the plug-in that the maximum block size passed to processReplacing() will be blockSize.

Parameters:
blockSize Maximum number of sample frames
Warning:
You must process exactly sampleFrames number of samples in inside processReplacing, not more!

VstInt32 AudioEffect::setChunk ( void *  data,
VstInt32  byteSize,
bool  isPreset = false 
) [inline, virtual]

Host restores plug-in state.

Parameters:
data pointer to state data (owned by Host)
byteSize size of state data
isPreset true when restoring a single program, false for all programs
See also:
getChunk

void AudioEffect::setEditor ( AEffEditor editor  ) 

Should be called if you want to define your own editor.

void AudioEffect::setInitialDelay ( VstInt32  delay  )  [virtual]

Use to report the plug-in's latency (Group Delay).

Use to report the Plug-in's latency (Group Delay)

Parameters:
delay Plug-ins delay in samples

void AudioEffect::setNumInputs ( VstInt32  inputs  )  [inline, virtual]

Set the number of inputs the plug-in will handle. For a plug-in which could change its IO configuration, this number is the maximun available inputs.

This number is fixed at construction time and can't change until the plug-in is destroyed.

Parameters:
inputs The number of inputs
See also:
isInputConnected()
Note:
Needs to be called in the plug-in's constructor

void AudioEffect::setNumOutputs ( VstInt32  outputs  )  [inline, virtual]

Set the number of outputs the plug-in will handle. For a plug-in which could change its IO configuration, this number is the maximun available ouputs.

This number is fixed at construction time and can't change until the plug-in is destroyed.

Parameters:
outputs The number of outputs
See also:
isOutputConnected()
Note:
Needs to be called in the plug-in's constructor

void AudioEffect::setParameter ( VstInt32  index,
float  value 
) [inline, virtual]

Called when a parameter changed.

Parameters are the individual parameter settings the user can adjust. A VST Host can automate these parameters. Set parameter index to value.

Parameters:
index Index of the parameter to change
value A float value between 0.0 and 1.0 inclusive
Note:
Parameter values, like all VST parameters, are declared as floats with an inclusive range of 0.0 to 1.0. How data is presented to the user is merely in the user-interface handling. This is a convention, but still worth regarding. Maybe the VST-Host's automation system depends on this range.

void AudioEffect::setParameterAutomated ( VstInt32  index,
float  value 
) [virtual]

Called after a control has changed in the editor and when the associated parameter should be automated.

Parameters:
index parameter index
float parameter value
Note:
An important thing to notice is that if the user changes a parameter in your editor, which is out of the Host's control if you are not using the default string based interface, you should call setParameterAutomated (). This ensures that the Host is notified of the parameter change, which allows it to record these changes for automation.
See also:
setParameter

void AudioEffect::setProgram ( VstInt32  program  )  [inline, virtual]

Set the current program to program.

Parameters:
Program of the current program

void AudioEffect::setProgramName ( char *  name  )  [inline, virtual]

Stuff the name field of the current program with name. Limited to kVstMaxProgNameLen.

The program name is displayed in the rack, and can be edited by the user.

Parameters:
name A string up to 24 char
Warning:
Please be aware that the string lengths supported by the default VST interface are normally limited to 24 characters. If you copy too much data into the buffers provided, you will break the Host application.

virtual void AudioEffect::setSampleRate ( float  sampleRate  )  [inline, virtual]

Called when the sample rate changes (always in a suspend state).

void AudioEffect::setUniqueID ( VstInt32  iD  )  [inline, virtual]

Must be called to set the plug-ins unique ID!

Must call this! Set the plug-in's unique identifier. The Host uses this to identify the plug-in, for instance when it is loading effect programs and banks. On Steinberg Web Page you can find an UniqueID Database where you can record your UniqueID, it will check if the ID is already used by an another vendor. You can use CCONST('a','b','c','d') (defined in VST 2.0) to be platform independent to initialize an UniqueID.

Parameters:
iD Plug-in's unique ID
Note:
Needs to be called in the plug-in's constructor

virtual void AudioEffect::suspend (  )  [inline, virtual]

Called when plug-in is switched to off.


Member Data Documentation

audioMasterCallback AudioEffect::audioMaster [protected]

Host callback.

VstInt32 AudioEffect::blockSize [protected]

Maximum block size.

AEffect AudioEffect::cEffect [protected]

AEffect object

VstInt32 AudioEffect::curProgram [protected]

Current program.

AEffEditor* AudioEffect::editor [protected]

Pointer to the plug-in's editor.

VstInt32 AudioEffect::numParams [protected]

Number of parameters.

VstInt32 AudioEffect::numPrograms [protected]

Number of programs.

float AudioEffect::sampleRate [protected]

Current sample rate.


The documentation for this class was generated from the following files: Empty

Copyright ©2006 Steinberg Media Technologies. All Rights Reserved.