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.