First     Previous     Next

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.