• Immutable Page
  • Info
  • Attachments

Virtually all plugins need to store some data of some sort, and in most cases it has to be attached to a core structure. An example of this would be storing the progress of an animation when transforming the screen or the opacity of a window in the Fading Windows plugin

To achieve this, we have helper classes to bind plugin screen and window structures to core structures. To do this, we have a template class PluginClassHandler<PluginStructure *, CoreStructrue *> which plugins inherit. This takes a single CoreStructure * as a constructor.

Most plugins set up macros to access these functions, usually called PLUGINNAME_DISPLAY (CompDisplay *d), for instance, which would result in a PluginnameDisplay *pd; variable, where the p is the initial of the plugin. This macro is usually the return value of PluginnameStructure::get (CoreStructure *);

Obtaining the structures of other plugins

By inheriting the PluginClassHandler class, all structures had a static member function ::get (CoreStructure *) which returns a PluginStructure for a given CoreStructure.

If you include the header files that other plugins export, and if they export the definitions of their plugin structures, you can get the instance of the external PluginStructure by calling the ::get function on that structure for a given CoreStructure.

VTable

A plugin has to implement a VTable class that derives from the CompPlugin::VTable, CompPlugin::VTableForScreen <[Plugin screen class name]> or CompPlugin::VTableForScreenAndWindow <[Plugin screen class name],[Plugin window class name]> class. The ForScreen[AndWindow] classes provide automatic initialisation of the plugin classes. A plugin has then also to implement the bool init (); function. A plugin can implement the CompOption::Vector & getOptions (); and bool setOption (const char *name, CompOption::Value &value);  functions or use the  PLUGIN_OPTION_HELPER ([Plugin screen name])  macro if it has implemented the  CompOption::Vector & getOptions ();  and  bool setOption (const char *name, CompOption::Value &value);  functions in its screen class.

A plugin also has to call call the COMPIZ_PLUGIN_20090315 ([plugin name], [plugin vtable name])  macro in its code.

Example:

class FooPluginVTable :
    public CompPlugin::VTableForScreenAndWindow<FooScreen, FooWindow>
{
    public:

        bool init ();

        PLUGIN_OPTION_HELPER (FooScreen);

};

COMPIZ_PLUGIN_20090315 (foo, FooPluginVTable)

This macro will also create a [plugin name]VTable * variable, that allows the access to the plugin metadata class within the plugin.

All plugin vtables must have an a bool init (); function. This runs some initial checks and functions to start enabling the plugin. Usually this involves checking ABI version.

/!\ You must check the ABI version of any plugins you depend on

Since the size of plugin structures can change, the Application Binary Interface (ABI) of each plugin could become out of sync since the code is precompiled and linked at runtime. In order to avoid some nasty crashes, every time the size of a compiled structure changes, the ABI version of either core or the providing plugin is bumped to represent this difference.

Checking the ABI version is fairly simple, most plugins export a #define for their ABI version. Most plugins would check the ABI version of the composite and opengl.

bool
PluginnamePluginVTable::init ()
{
    if (!CompPlugin::checkPluginABI ("core", CORE_ABIVERSION) ||
        !CompPlugin::checkPluginABI ("composite", COMPIZ_COMPOSITE_ABI) ||
        !CompPlugin::checkPluginABI ("opengl", COMPIZ_OPENGL_ABI))
        return false;
    return true;
}

}

PluginScreen

This class is used to store global data about you're plugin's operation. It is attached the CompScreen * that compiz is running on. You should also derive this from your options class if you are using one.

PluginWindow

This is a class used to store data pertaining to specific windows, for example size data for the scale plugin.

Development/zero-nine/PluginStructures (last edited 2010-07-25 11:12:29 by 124-169-107-122)