First     Previous     Next

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).