Talking to the host |
The host is represented by an object, just as the plugin. This makes it possible to ask the host to do some things. See TFruityPlugHost for more information.
Members
First of all, TFruityPlugHost has some member variables that can be useful to
a plugin. Apart from the ones mentioned here, there are also MixingTick and
Flags, but they're not used yet.
HostVersion holds the version of FL Studio. All
the version number is included in one integer. So if the version number of FL
Studio would be 1.2.3, HostVersion would have a value of 01002003. Certain features
in the sdk require a minimum version of FL Studio to be installed.
AppHandle could be more important. It is the handle
of the application that has loaded the plugin (so it's the handle of FL Studio).
This could be needed for creating windows, depending on your development system.
WaveTables can be very handy, especially for generator
plugins. It's an array of maximum ten pointers to an array of samples. They
contain precalculated sine, triangle etc. waves. Each array has 16384 samples,
in floating point format (-1.0 .. +1.0). So far, only 5 wavetables are defined.
These are : sine (index = 0), triangle (index = 1), square (index = 2), saw
(index = 3), analog saw (index = 4).
TempBuffers holds a few buffers that you can use
when processing. They're guaranteed to hold at least Length samples (where Length
is the value passed to Eff_Render, Gen_Render or Voice_Render). For hybrid generators,
some of these buffers may be in use by FL Studio.
Dispatcher
This method sends a message to the host. You use the plugin's HostTag as the
Sender parameter. Check here
for a complete list of messages that you can send.
First, there are two messages that are related to parameter popup menus. FL
Studio fills the parameter popup menu for you, but you can also add items of
your own if you want to. You don't necessarily have to provide a popup menu
for this. Anything that allows the user to choose to edit the events or link
to a midi controller or another of these options would do. But a popup menu
is more in line with other plugins in FL Studio.
First you use FHD_GetParamMenuEntry to ask the
host for popup menu items. The plugin then has to add these to its popup menu
(or whatever it chooses). Note that TDelphiFruityPlugin and TCPPFruityPlugin
have a function that can do this automatically, called AdjustParamPopup.
FHD_ParamMenu then informs the host that the user
has clicked on a parameter popup menu item. The host then reacts to this the
same as it does in other cases. Like this, uniformity within the program is
maintained. This message has two parameters. The first is the index of the parameter
and is passed in Index. The second is the index of the menu item that has been
clicked, passed in Value. This last index is counted from 0, meaning the first
item that was added after a call to FHD_GetParamMenyEntry.
Note that the FL Studio popup menus also have a menu item called "Reset".
It would be best if you also implement such an item. Since the host has nothing
to do with it, it won't be added by using FHD_GetParamMenuEntry.
FHP_EditorResized is the next host message. Call
this when you have resized the plugin's editor window and you want to let the
host know.
Next is FHD_NoteNamesChanged. It's all in the name.
Call this when the name of a note was changed and FL Studio will call the GetName
function to get the new name.
FHD_ActivateMidi is used to make the host enable
it's midi output (which can be disabled in FL Studio).
Call FHD_WantMIDIInput when you want your plugin
to receive midi messages, or to stop receiving them.
FHD_WantMIDITick means the plugin wants to receive
midi tick messages.
FHD_KillAutomation is called when you want the
host to get rid of all automation (parameter change) information that it's currently
holding. You want to do this when that information is no longer accurate (for
example the meaning of a parameter has changed) or to make a demo version (as
a limitation).
If your plugin has internal presets, you have to call Dispatcher with FHD_SetNumPresets
to let the host know how many presets there are. You can do this at any time
(which means you can also change the number of presets).
FHD_SetNewName can be used to change the short
name of the plugin while it's loaded.
Call FHD_SelectChanSample to get a selector for
a parent channel sample.
FHD_WantIdle lets the host know whether or not
the plugin wants the Idle method to be called by the host. By default this behaviour
is on. If you don't do anything in Idle (including showing the parameter name
when the mouse moves over a control), you can call this and in that way save
a bit of cpu power.
Use FHD_LocateDataFile when you want to find the
exact location for a certain file. You pass the filename without a path and
FL Studio will search for it in all of its search paths.
FHD_TicksToTime asks the host to translate a tick
time into a bar:step:tick time.
With FHD_AddNotesToPR a plugin can ask the host
to add one or more notes to the piano roll for the plugin's channel.
FHD_ShowMsg allows you to ask FL Studio to show
a message box with a certain text. This way the messagebox will look as the
ones FL Studio shows itself.
FHD_NoteOn and FHD_NoteOff
allow the plugin to play a preview note on an internal piano keyboard (like
the Fruity DX10 does). While the plugin doesn't really need to tell the host
about this, it's better if it does (so the host can for example also show that
note playing on its preview keyboard).
FHD_OnHint_Direct is the same as OnHint, but it
shows the text immediately (to show a progress while you're doing something).
FHD_SetNewColor sets a new color for the parent.
This color is used for the sample button in FL Studio's step sequencer.
FHD_GetInstance returns the module instance of
the host. This could be an exe or a dll, so it might not be the process itself.
Use FHD_KillIntCtrl to ask the host to kill anything
linked to an internal controller, for controllers between Index & Value
(included). This is used when getting rid of internal controllers. For example,
Dashboard calls this when a control is deleted.
Call FHD_SetNumParams to override the number of
parameters. This is useful for plugins that have a different set of parameters
per instance.
FHD_PackDataFile asks the host to pack an absolute
filename into a local filemane. When you pass the simple filename in Value the
packed path is returned as Result. Note that the result pointer won't be valid
for long, so you should copy the string right away!
FHD_GetProgPath asks the host where the FL Studio
engine dll is, which might NOT be where the executable is, but where the data
path will be. The value is returned as result of the function. Note that the
result pointer won't be valid for long, so you should copy the string right
away!
FHD_SetLatency sets the plugin latency, if any.
Call FHD_CallDownloader to show the preset downloader/selector.
This is for use by some specific plugins only.
OnParamChanged
In order to make your parameters recordable in FL Studio, you have to call this
function whenever a parameter is changed from within your plugin (probably because
the user turned a wheel or something). You need to pass HostTag in the Sender
parameter. To let the host know which parameter has just been changed, pass
the parameter index in Index. Finally, pass the new value (as an integer) in
Value.
OnHint
Fruity plugins can also show hints (or rather tell FL Studio to show a hint).
Note that TDelphiFruityPlug and TCPPFruityPlug
implement functions that make it a bit easier to show a hint. It's really a
simple function. You pass HostTag for the Sender parameter. Text is a pointer
to a string that contains the hint message. Note that the plugin is responsible
for making sure that Text points to a valid string !
There is one extra feature of parameter hints. It is possible to tell FL Studio
to show little icons next to the hint, that have a special meaning. For the
moment there are three of those. Note that these have to be inserted at the
BEGINNING of the string.
"^a" shows a little icon that informs
the user that the parameter that the hint is about can be linked to a MIDI controller.
"^b" informs the user that the parameter
is recordable.
"^c" shows a little smiley. No real use,
just for fun.
"^d" shows a mouse with the right button
clicked, to denote a control that has a popup menu.
"^e" shows an unhappy smiley, to use
when something went wrong.
"^f" shows a left-pointing arrow
"^g" shows a double right-pointing arrow,
for fast forward
"^h" is an exclamation mark, for a warning
to the user
"^i" is an hourglass
"^j" shows a double left-pointing arrow,
for fast reverse
So to show both the "midi linkable" and "recordable" icons,
you might have a hint like this : "^b^aThis is my hint". Note that
in FL Studio the order is reversed (not ^a^b, but ^b^a). You might want to do
this too in order to fit in better.
LockMix / UnlockMix
These two functions work together. They are here to let you control the different
threads within FL Studio in case they would get in your way. Working with threads
is not a very easy subject and can cause many problems.
FL Studio has a seperate thread for the mixer. So functions inside the plugin
could be called from the main thread or from the mix thread. Multiple functions
within your plugin could be executing at the same time! Therefore if you have
to do something that could be disturbed by this, first call Lockmix. After this,
you can do whatever it is you want to do. When you're done, DON'T FORGET
to call UnlockMix. This let's the mixer thread go about its business again.
It's also essential to implement as little code as possible between the calls
to LockMix and UnlockMix. When the locking lasts too long a time, this will
disrupt the playing in FL Studio, ranging from clicks to delays (zipper noise).
Note that there are two other pairs of locking functions: LockPlugin/UnlockPlugin (won't freeze audio) and LockMix_Shared/UnlockMix_Shared (multithread-safe processing).