Working with voices |
If you're going to make a generator plugin, you need to know about the voice
functions.
FL Studio uses the TVoiceParams
structure to tell the plugin the settings for a certain voice. This consists
of two fields, InitLevels and FinalLevels, both of type TLevelParams.
It holds information about the channel panning, volume, pitch and filter cutoff
and Q. Note that the Q value (FRes) has a range of 0 to 80/128. That means that
each value for FRes is an integer value between 0 and 80, but that needs to
be divided by 128 before it's assigned to FRes.
NOTE:
In version 1.4 of the sdk, TLevelParams has been
changed to have floating point fields for Pan and Pitch. The old version
of TLevelParams has been renamed to TLevelParams_Old. Always use the new
version for new plugins. For old projects, you can leave the FPF_NewVoiceParams
out of the plugin flags (it's in the combo's by default). |
There are four functions in TFruityPlug that
deal with managing voices. These are TriggerVoice, Voice_Release, Voice_Kill
and Voice_ProcessEvent.
TriggerVoice
This is the first voice function that will get called by FL Studio. The plugin
has to create a new voice (allocate memory) when this is called. FL Studio provides
a pointer to a TVoiceParams structure. You have to keep this structure around
for future reference.
The result of this function is going to be used in the other functions as the
identifier of the voice. It's the plugin's task to choose a unique identifier.
An easy way of doing this is to create a structure to hold (private) information
about the voice, which also holds the pointer to the TVoiceParams structure.
Then you can use a pointer to your own structure as the result of TriggerVoice,
as the pointer should be unique within a process. You can take a look at the
implementation of TriggerVoice in the Osc3 example for this.
Don't forget to save the SetTag parameter. It's needed when you want to call
voice functions in the host class (see TFruityPlugHost).
Check out the voice information codes to retrieve any relevant info about the
newly triggered voice. These include FPV_GetLength,
FPV_GetColor, FPV_GetVelocity and FPV_SetLinkVelocity.
Voice_Release
This function signals that a specified voice (identified by the Handle parameter,
which is the value that was returned by the TriggerVoice function) should enter
the releasing state. This is a note off in midi terms. You can call Voice_Kill
in PlugHost if your generator doesn't support releasing voices. Otherwise you'll
probably set a flag in your voice structure and let it die out.
The codes FPV_GetRelVelocity and FPV_GetRelTime
can be used to retrieve more information about the released voice.
Voice_Kill
When FL Studio has no more need for a voice (identified by the Handle parameter),
it will call this function. You need to free all memory that you allocated for
this voice in the TriggerVoice function.
The plugin can tell FL Studio that it wants to kill a voice. In that case, the
plugin shouldn't call Voice_Kill (or free any memory) itself for that voice
if it has called Voice_Kill in PlugHost with the KillHandle parameter set to
true. FL Studio will take care of calling Voice_Kill on the plugin.
Also, make sure you kill all voices that are left when the plugin is destroyed.
Voice_ProcessEvent
This function will get called when a voice event occurs. The only voice
event at the moment is FPV_Retrigger.