EffecTV new plugin API In this page a new plugin API for EffecTV is described. Advantages - Portable DSO loading (capsulated by GLIB) - OO(object oriented)-like design. - Allows multiple instances from a plugin Disadvantages - Single input, single output Plugin ====== Version 0.0 EffecTV loads various plug-in modules at run time. In this docuement we describes the details of the plug-in system. Synopsis -------- The plugin system of EffecTV models after Object-Oriented System. Every plugin defines "class", a definition of plugin's data and behaviour. When EffecTV is trying to use the plugin, EffecTV constructs an instance from the class. Each instance has separated environment (memory space), therefor EffecTV can hold multiple instances of a plugin. Implementation -------------- Each plugins is created as a shared object, relocatable binary. It can be implemented in any language which can output the shared object. (at this time we have written all plugins in C and used GNU libtool utility. See those codes for the details) Essential function ------------------ All of EffecTV plugins have to provide four public function, getType(), getVersion(), loadPlugin() and unloadPlugin(). int getType(); Returns type of this plugin. The result is one of MODULE_EFFECT MODULE_INPUT MODULE_OUTPUT MODULE_COMMAND Those macro values are defined in "src/EffecTV.h". In plugin system version 0.0, command plugin (MODULE_COMMAND) is not implemented yet. unsigned int getVersion(); Returns plugin-API version. Plugin-API version consists of two integer value, major version and minor version. Lower 16 bits of the return value is minor version, and next 16 bits is major version. To calculate the return value, please use a macro function PLUGIN_API_VERSION(major, minor), defined in EffecTV.h. void *loadPlugin(); This function is called at initialization phase. Every plugin has an instance of Plugin class (mentioned below), and this function returns a pointer to it. Additionally the plugin can allocate some resources shared by plugin instances at this time, but it is not recommended. (instead of that, you can allocate them at the first time of creation of the instance.) int unloadPlugin(); This function is called when the plugin modules is unloaded. Releases resources allocated at registration time. After calling this function, this module must be ready to be unloaded. Plugin Class ============ This class is a (virtual) super class of EffectPlugin, OutputPlugin, InputPlugin, and so on. Its internal and behaviour depend on each sub class. See effect.txt, output.txt and input.txt. Its definition is in plugin.h. Effect ====== Each effect is an object. Each effect plugins provides two classes, EffectPlugin and Effect. Additionally it provides three public functions described in plugin.txt. EffectPlugin ============ An instance of EffectPlugin holds informations of the plugin and a constructor method of 'Effect' class, that is a body of the effect. variables --------- char *name; char *description; int apiMajorVersion; int apiMinorVersion; method ------ Effect *construct(System *system); Creats an instance of this effect class. Variables in 'system' are not changed during the lifetime of this object. Creating tables or temporary buffers may be done in this method. Those resources have to be released in 'destruct'. Effect ====== variables --------- char *name; Its name. void *environment; Holds envrionment of the object. It may be a pointer to a structure object defined by each effect. method ------ int destruct(Effect *self); Destructs itself. Usually, objects die when EffecTV dies. Some objects what is created as a second/third instance of effects may be destroyed when it is not to used. int start(Effect *self); int stop(Effect *self); This method is called from EffecTV core when the effect starts/stops. Perhaps most of effects need not to do anything, but some effects using threads may need this method? int effect(Effect *self, Frame *input, Frame *output); int effectToSDLSurface(Effect *self, Frame *input, SDL_Surface *output); int eventHandler(Effect *self, Event *event); int OSDopen(Effect *self);
 |
|||||||||||||
|