First     Previous     Next

Messages from the host

There are four ways the host will inform the plugin of something it has to do or something that has happened. These are Dispatcher, Idle, ProcessEvent and Voice_ProcessEvent. The last one is discussed on the page Working with voices.

Dispatcher
Depending on ID, the plugin needs to do something. ID can be one of the Dispatcher IDs.

When ID is FPD_ShowEditor, the plugin has to either show or hide its editor window. If Value is zero, the editor has to be hidden. Otherwise, the editor has to be shown. In this case, Value is the handle of the parent window, so don't forget to set the parent handle of your window to it. It's best to first set the parent handle and only then show the window. Likewise, hide the editor before you set its parent handle to zero.
In case the editor has to be hidden, the examples set the parent handle of the editor window to zero. Some development systems (such as Delphi 3) might not like this. In this case, it might be a good idea to save the original value of the parent handle and restore that when the editor is hidden.

If ID is FPD_ProcessMode, then Value holds the new processing mode. This ID can be ignored. It's a bitfield that determines the quality of the data that the plugin renders. If the PM_IsRendering flag is set, the host is rendering to a file (.wav, .mp3, ...), which means that the plugin doesn't have to render in real time. You can also check against the PM_IPMask bit mask. This determines the interpolation quality to be used.

FPD_Flush warns the plugin that the next samples do not follow immediately in time to the previous block of samples. In other words, the continuity is broken. You have to make sure that your plugin responds well to a change in continuity. For example, a delay plugin will have to make sure it doesn't use any more old data. The idea is not that you go setting all buffers to zero. It might be enough to set a position variable. This should all be as optimized as possible.

As the name suggests, FPD_SetBlockSize tells the plugin that the maximum block size has changed. This is not relevant to all plugins. Value holds the new maximum blocksize.

FPD_SetSampleRate tells the plugin that the sample rate has been changed. If you're making a plugin that is affected by this, look in Value for the new samplerate.

FPD_WindowMinMax is sent when the host wants information about the resizing of the plugin's editor window. There are two things it wants to know : the minimum and maximum sizes of the window, and the changes in size when the user drags the borders of the window.
Index holds a pointer to a rectangle (TRect / RECT). In this rectangle, you need to specify the minimum and maximum sizes of the editor. For the minimum size, use the Left (width) and Top (height) fields. For the maximum size, use the Right (width) and Bottom (height) fields.
Value holds a pointer to a point structure (TPoint / POINT). In this structure you can specify special values for the steps in resizing the window.
If you don't want the window to be resizeable, then don't respond to this message.

FL Studio will call dispatcher with FPD_KillAVoice when for some reason it thinks the weakest voice should be killed. Maybe the plugin was using too much cpu. Whatever the reason, the plugin should look for the currently active voice that has the lowest volume (on average) and kill it. If it does this, it should return 1 as the functions result.

FPD_UseVoiceLevels
is sent to determine whether or not a full generator will use the CutOff and Resonance per-voice parameters as they are, use them as different (custom) parameters, or not use them at all. In the second case, the plugin will need to implement a response for GetName when it's called with the section FPN_VoiceLevel, so it can provide names for the custom parameters.

FPD_SetPreset
is called when the user selects an internal preset.

FPD_ChanSampleChanged
lets you know that a sample has been loaded into a generator's channel, and now provided to the plugin as a wavetable. This will only be called for a plugin that has specified FPF_GetChanSample as a flag in its info structure.

FPD_SetEnabled
is called when the plugin is either enabled or disabled by the user.

FPD_SetPlaying
informs the plugin that FL Studio has either started or stopped playing.

FPD_SongPosChanged
lets the plugin know that the song position has jumped from one position to another new one, either before or after the previous position. The new position is never just one further than the old position.

FPD_SetTimeSig
is called when the time signature has changed. Check out the time signature structure for more information.

FPD_CollectFile
is used by the host to find out if a plugin has any additional files it would like to see saved, for example when FL Studio exports a project to a zip file. The host keeps calling this until 0 is returned. As long as the plugin has files to save (indicated by the Index parameter), it should pass a pchar / char *, containing the name of the file to be saved, as the result of the function.

FPD_SetNumSends
lets you know how many send tracks there are. This is a fixed number for the time being, but it could be variable in the future.

FPD_LoadFile
is called when a file (not a sound file) is dropped onto a channel's button. The plugin can then load this file if it wants to.The Value parameter should be typecast to a pchar / char * variable and holds the name of the file that was dropped.

FPD_SetFitTime sets fit to a time in beats.

FPD_SetSamplesPerTick lets you know how many samples there are in a "tick" (the basic period of time in FL Studio). This changes when the tempo, PPQ or sample rate have changed. This can be called from the mixing thread.

FPD_SetIdleTime passes the interval at which the Idle function will be called, in milliseconds. You can use this to adjust things like the speed of an animation.

See the Constants page for a complete list of dispatcher codes.


Idle
This function is called continuously. It allows the plugin to perform certain tasks that are not time-critical and which do not take up a lot of time either. For example, TDelphiFruityPlug and TCPPFruityPlug implement this function to show a hint message when the mouse moves over a control in the editor.


ProcessEvent
This is called by the host for special events.

FPE_Tempo means that the tempo has changed. Value holds the new tempo. The tempo is a floating point (single / float), so it needs to be typecast from the integer Value, like this :
    Delphi :  NewTempo := single(Value);
    C++ :  NewTempo = *((float *)&Value);

FPE_MaxPoly is only of intrest to full generators. It tells them that the maximum polyphony (the maximum number of voices playing at once) has been changed. A value of zero (0) means unlimited polyphony.

FPE_MIDI_Pan let's the plugin know that the midi pan has changed.

FPE_MIDI_Vol informs you that the midi volume has changed.

FPE_MIDI_Pitch is used when the midi pitch has changed.

See the Constants page for a complete list of event codes.