1 /* Libvisual - The audio visualisation framework. 2 * 3 * Copyright (C) 2004, 2005 Dennis Smit <ds@nerds-incorporated.org> 4 * 5 * Authors: Dennis Smit <ds@nerds-incorporated.org> 6 * 7 * $Id: 8 * 9 * This program is free software; you can redistribute it and/or modify 10 * it under the terms of the GNU Lesser General Public License as 11 * published by the Free Software Foundation; either version 2.1 12 * of the License, or (at your option) any later version. 13 * 14 * This program is distributed in the hope that it will be useful, 15 * but WITHOUT ANY WARRANTY; without even the implied warranty of 16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 17 * GNU Lesser General Public License for more details. 18 * 19 * You should have received a copy of the GNU Lesser General Public License 20 * along with this program; if not, write to the Free Software 21 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 22 */ 23 24 #ifndef _LV_PLUGIN_H 25 #define _LV_PLUGIN_H 26 27 #include <libvisual/lv_video.h> 28 #include <libvisual/lv_audio.h> 29 #include <libvisual/lv_palette.h> 30 #include <libvisual/lv_list.h> 31 #include <libvisual/lv_songinfo.h> 32 #include <libvisual/lv_event.h> 33 #include <libvisual/lv_param.h> 34 #include <libvisual/lv_ui.h> 35 #include <libvisual/lv_random.h> 36 #include <libvisual/lv_types.h> 37 38 #ifdef __cplusplus 39 extern "C" { 40 #endif /* __cplusplus */ 41 42 #define VISUAL_PLUGINREF(obj) (VISUAL_CHECK_CAST ((obj), 0, VisPluginRef)) 43 #define VISUAL_PLUGININFO(obj) (VISUAL_CHECK_CAST ((obj), 0, VisPluginInfo)) 44 #define VISUAL_PLUGINDATA(obj) (VISUAL_CHECK_CAST ((obj), 0, VisPluginData)) 45 #define VISUAL_PLUGINENVIRON(obj) (VISUAL_CHECK_CAST ((obj), 0, VisPluginEnviron)) 46 47 #define VISUAL_PLUGIN_ACTOR(obj) (VISUAL_CHECK_CAST ((obj), VISUAL_PLUGIN_TYPE_ACTOR_ENUM, VisActorPlugin)) 48 #define VISUAL_PLUGIN_INPUT(obj) (VISUAL_CHECK_CAST ((obj), VISUAL_PLUGIN_TYPE_INPUT_ENUM, VisInputPlugin)) 49 #define VISUAL_PLUGIN_MORPH(obj) (VISUAL_CHECK_CAST ((obj), VISUAL_PLUGIN_TYPE_MORPH_ENUM, VisMorphPlugin)) 50 #define VISUAL_PLUGIN_TRANSFORM(obj) (VISUAL_CHECK_CAST ((obj), VISUAL_PLUGIN_TYPE_TRANSFORM_ENUM, VisTransformPlugin)) 51 52 /** 53 * Indicates at which version the plugin API is. 54 */ 55 #define VISUAL_PLUGIN_API_VERSION 2 56 57 /** 58 * Type defination that should be used in plugins to set the plugin type for a NULL plugin. 59 */ 60 #define VISUAL_PLUGIN_TYPE_NULL "Libvisual:core:null" 61 /** 62 * Type defination that should be used in plugins to set the plugin type for an actor plugin. 63 */ 64 #define VISUAL_PLUGIN_TYPE_ACTOR "Libvisual:core:actor" 65 /** 66 * Type defination that should be used in plugins to set the plugin type for an input plugin. 67 */ 68 #define VISUAL_PLUGIN_TYPE_INPUT "Libvisual:core:input" 69 /** 70 * Type defination that should be used in plugins to set the plugin type for a morph plugin. 71 */ 72 #define VISUAL_PLUGIN_TYPE_MORPH "Libvisual:core:morph" 73 /** 74 * Type defination that should be used in plugins to set the plugin type for a transform plugin. 75 */ 76 #define VISUAL_PLUGIN_TYPE_TRANSFORM "Libvisual:core:transform" 77 78 /** 79 * Enumerate to define the plugin type. Especially used 80 * within the VisPlugin system and for type checking within the core library itself. 81 * 82 * For plugin type defination use the VISUAL_PLUGIN_TYPE_NULL, VISUAL_PLUGIN_TYPE_ACTOR 83 * VISUAL_PLUGIN_TYPE_INPUT or VISUAL_PLUGIN_TYPE_MORPH defines that contain the domain string. 84 * 85 * There are three different plugins being: 86 * -# Actor plugins: These are the actual 87 * visualisation plugins. 88 * -# Input plugins: These can be used to obtain 89 * PCM data through, for example different sound servers. 90 * -# Morph plugins: These are capable of morphing 91 * between different plugins. 92 * -# Transform plugins: These are capable of transforming a video or palette 93 * into something new. 94 */ 95 typedef enum { 96 VISUAL_PLUGIN_TYPE_NULL_ENUM, /**< Used when there is no plugin. */ 97 VISUAL_PLUGIN_TYPE_ACTOR_ENUM, /**< Used when the plugin is an actor plugin. */ 98 VISUAL_PLUGIN_TYPE_INPUT_ENUM, /**< Used when the plugin is an input plugin. */ 99 VISUAL_PLUGIN_TYPE_MORPH_ENUM, /**< Used when the plugin is a morph plugin. */ 100 VISUAL_PLUGIN_TYPE_TRANSFORM_ENUM /**< Used when the plugin is a transform plugin. */ 101 } VisPluginType; 102 103 /** 104 * Enumerate to define the plugin flags. Plugin flags can be used to 105 * define some of the plugin it's behavior. 106 */ 107 typedef enum { 108 VISUAL_PLUGIN_FLAG_NONE = 0, /**< Used to set no flags. */ 109 VISUAL_PLUGIN_FLAG_NOT_REENTRANT = 1, /**< Used to tell the plugin loader that this plugin 110 * is not reentrant, and can be loaded only once. */ 111 VISUAL_PLUGIN_FLAG_SPECIAL = 2 /**< Used to tell the plugin loader that this plugin has 112 * special purpose, like the GdkPixbuf plugin, or a webcam 113 * plugin. */ 114 } VisPluginFlags; 115 116 /** 117 * Enumerate to check the depth of the type wildcard/defination used, used together with the visual_plugin_type functions. 118 */ 119 typedef enum { 120 VISUAL_PLUGIN_TYPE_DEPTH_NONE = 0, /**< No type found.*/ 121 VISUAL_PLUGIN_TYPE_DEPTH_DOMAIN = 1, /**< Only domain in type. */ 122 VISUAL_PLUGIN_TYPE_DEPTH_PACKAGE = 2, /**< Domain and package in type. */ 123 VISUAL_PLUGIN_TYPE_DEPTH_TYPE = 3, /**< Domain, package and type found in type. */ 124 } VisPluginTypeDepth; 125 126 typedef struct _VisPluginRef VisPluginRef; 127 typedef struct _VisPluginInfo VisPluginInfo; 128 typedef struct _VisPluginData VisPluginData; 129 typedef struct _VisPluginEnviron VisPluginEnviron; 130 131 typedef struct _VisActorPlugin VisActorPlugin; 132 typedef struct _VisInputPlugin VisInputPlugin; 133 typedef struct _VisMorphPlugin VisMorphPlugin; 134 typedef struct _VisTransformPlugin VisTransformPlugin; 135 136 /* Actor plugin methods */ 137 138 /** 139 * An actor plugin needs this signature for the requisition function. The requisition function 140 * is used to determine the size required by the plugin for a given width/height value. 141 * 142 * @arg plugin Pointer to the VisPluginData instance structure. 143 * @arg width Pointer to an int containing the width requested, will be altered to the nearest 144 * supported width. 145 * @arg height Pointer to an int containing the height requested, will be altered to the nearest 146 * supported height. 147 * 148 * @return 0 on succes -1 on error. 149 */ 150 typedef int (*VisPluginActorRequisitionFunc)(VisPluginData *plugin, int *width, int *height); 151 152 /** 153 * An actor plugin needs this signature for the palette function. The palette function 154 * is used to retrieve the desired palette from the plugin. 155 * 156 * @arg plugin Pointer to the VisPluginData instance structure. 157 * 158 * @return Pointer to the VisPalette used by the plugin, this should be a VisPalette with 256 159 * VisColor entries, NULL is also allowed to be returned. 160 */ 161 typedef VisPalette *(*VisPluginActorPaletteFunc)(VisPluginData *plugin); 162 163 /** 164 * An actor plugin needs this signature for the render function. The render function 165 * is used to render the frame for the visualisation. 166 * 167 * @arg plugin Pointer to the VisPluginData instance structure. 168 * @arg video Pointer to the VisVideo containing all information about the display surface. 169 * Params like height and width won't suddenly change, this is always notified as an event 170 * so the plugin can adjust to the new dimension. 171 * @arg audio Pointer to the VisAudio containing all the data regarding the current audio sample. 172 * 173 * @return 0 on succes -1 on error. 174 */ 175 typedef int (*VisPluginActorRenderFunc)(VisPluginData *plugin, VisVideo *video, VisAudio *audio); 176 177 /* Input plugin methods */ 178 179 /** 180 * An input plugin needs this signature for the sample upload function. The sample upload function 181 * is used to retrieve sample information when a input is being used to retrieve the 182 * audio sample. 183 * 184 * @arg plugin Pointer to the VisPluginData instance structure. 185 * @arg audio Pointer to the VisAudio in which the new sample data is set. 186 * 187 * @return 0 on succes -1 on error. 188 */ 189 typedef int (*VisPluginInputUploadFunc)(VisPluginData *plugin, VisAudio *audio); 190 191 /* Morph plugin methods */ 192 193 /** 194 * A morph plugin needs this signature for the palette function. The palette function 195 * is used to give a palette for the morph. The palette function isn't mandatory and the 196 * VisMorph system will interpolate between the two palettes in VISUAL_VIDEO_DEPTH_8BIT when 197 * a palette function isn't set. 198 * 199 * @arg plugin Pointer to the VisPluginData instance structure. 200 * @arg rate A float between 0.0 and 1.0 that tells how far the morph has proceeded. 201 * @arg audio Pointer to the VisAudio containing all the data regarding the current audio sample. 202 * @arg pal A pointer to the target VisPalette in which the morph between the two palettes is saved. Should have 203 * 256 VisColor entries. 204 * @arg src1 A pointer to the first VisVideo source. 205 * @arg src2 A pointer to the second VisVideo source. 206 * 207 * @return 0 on succes -1 on error. 208 */ 209 typedef int (*VisPluginMorphPaletteFunc)(VisPluginData *plugin, float rate, VisAudio *audio, VisPalette *pal, 210 VisVideo *src1, VisVideo *src2); 211 212 /** 213 * A morph plugin needs this signature for the apply function. The apply function 214 * is used to execute a morph between two VisVideo sources. It's the 'render' function of 215 * the morph plugin and here is the morphing done. 216 * 217 * @arg plugin Pointer to the VisPluginData instance structure. 218 * @arg rate A float between 0.0 and 1.0 that tells how far the morph has proceeded. 219 * @arg audio Pointer to the VisAudio containing all the data regarding the current audio sample. 220 * @arg src1 A pointer to the first VisVideo source. 221 * @arg src2 A pointer to the second VisVideo source. 222 * 223 * @return 0 on succes -1 on error. 224 */ 225 typedef int (*VisPluginMorphApplyFunc)(VisPluginData *plugin, float rate, VisAudio *audio, VisVideo *dest, 226 VisVideo *src1, VisVideo *src2); 227 228 /* Transform plugin methodes */ 229 230 /** 231 * A transform plugin needs this signature to transform VisPalettes. 232 * 233 * @arg plugin Pointer to the VisPluginData instance structure. 234 * @arg pal Pointer to the VisPalette that is to be morphed. 235 * Only 256 entry VisPalettes have to be supported. 236 * @arg audio Optionally a pointer to the VisAudio, when requested. 237 * 238 * @return 0 on succes -1 on error. 239 */ 240 typedef int (*VisPluginTransformPaletteFunc)(VisPluginData *plugin, VisPalette *pal, VisAudio *audio); 241 242 /** 243 * A transform plugin needs this signature to transform VisVideos. 244 * 245 * @arg plugin Pointer to the VisPluginData instance structure. 246 * @arg video Pointer to the VisVideo that needs to be transformed. 247 * @arg audio Optionally a pointer to the VisAudio, when requested. 248 * 249 * @return 0 on succes -1 on error. 250 */ 251 typedef int (*VisPluginTransformVideoFunc)(VisPluginData *plugin, VisVideo *video, VisAudio *audio); 252 253 /* Plugin standard get_plugin_info method */ 254 /** 255 * This is the signature for the 'get_plugin_info' function every libvisual plugin needs to have. The 256 * 'get_plugin_info' function provides libvisual plugin data and all the detailed information regarding 257 * the plugin. This function is compulsory without it libvisual won't load the plugin. 258 * 259 * @arg count An int pointer in which the number of VisPluginData entries within the plugin. Plugins can have 260 * multiple 'features' and thus the count is needed. 261 * 262 * @return Pointer to the VisPluginInfo array which contains information about the plugin. 263 */ 264 typedef const VisPluginInfo *(*VisPluginGetInfoFunc)(int *count); 265 266 /* Standard plugin methods */ 267 268 /** 269 * Every libvisual plugin that is loaded by the libvisual plugin loader needs this signature for it's 270 * intialize function. 271 * 272 * @arg plugin Pointer to the VisPluginData instance structure. 273 * 274 * @return 0 on succes -1 on error. 275 */ 276 typedef int (*VisPluginInitFunc)(VisPluginData *plugin); 277 278 /** 279 * Every libvisual plugin that is loaded by the libvisual plugin loader needs this signature for it's 280 * cleanup function. 281 * 282 * @arg plugin Pointer to the VisPluginData instance structure. 283 * 284 * @return 0 on succes -1 on error. 285 */ 286 typedef int (*VisPluginCleanupFunc)(VisPluginData *plugin); 287 288 /** 289 * This is the signature for the event handler within libvisual plugins. An event handler is not mandatory because 290 * it has no use in some plugin classes but some plugin types require it nonetheless. 291 * 292 * @arg plugin Pointer to the VisPluginData instance structure. 293 * @arg events Pointer to the VisEventQueue that might contain events that need to be handled. 294 * 295 * @return 0 on succes -1 on error. 296 */ 297 typedef int (*VisPluginEventsFunc)(VisPluginData *plugin, VisEventQueue *events); 298 299 /** 300 * The VisPluginRef data structure contains information about the plugins 301 * and does refcounting. It is also used as entries in the plugin registry. 302 */ 303 struct _VisPluginRef { 304 VisObject object; /**< The VisObject data. */ 305 306 char *file; /**< The file location of the plugin. */ 307 int index; /**< Contains the index number for the entry in the VisPluginInfo table. */ 308 int usecount; /**< The use count, this indicates how many instances are loaded. */ 309 VisPluginInfo *info; /**< A copy of the VisPluginInfo structure. */ 310 }; 311 312 /** 313 * The VisPluginInfo data structure contains information about a plugin 314 * and is filled within the plugin itself. 315 */ 316 struct _VisPluginInfo { 317 VisObject object; /**< The VisObject data. */ 318 319 uint32_t struct_size; /**< Struct size, should always be set for compatability checks. */ 320 uint32_t api_version; /**< API version, compile plugins always with .api_version = VISUAL_PLUGIN_API_VERSION. */ 321 char *type; /**< Plugin type, in the format of "domain:package:type", as example, 322 * this could be "Libvisual:core:actor". It's adviced to use the defination macros here 323 * instead of filling in the string yourself. */ 324 char *plugname; /**< The plugin name as it's saved in the registry. */ 325 326 char *name; /**< Long name */ 327 char *author; /**< Author */ 328 char *version; /**< Version */ 329 char *about; /**< About */ 330 char *help; /**< Help */ 331 332 VisPluginInitFunc init; /**< The standard init function, every plugin has to implement this. */ 333 VisPluginCleanupFunc cleanup; /**< The standard cleanup function, every plugin has to implement this. */ 334 VisPluginEventsFunc events; /**< The standard event function, implementation is optional. */ 335 336 int flags; /**< Plugin flags from the VisPluginFlags enumerate. */ 337 338 VisObject *plugin; /**< Pointer to the plugin specific data structures. */ 339 }; 340 341 /** 342 * The VisPluginData structure is the main plugin structure, every plugin 343 * is encapsulated in this. 344 */ 345 struct _VisPluginData { 346 VisObject object; /**< The VisObject data. */ 347 348 VisPluginRef *ref; /**< Pointer to the plugin references corresponding to this VisPluginData. */ 349 350 VisPluginInfo *info; /**< Pointer to the VisPluginInfo that is obtained from the plugin. */ 351 352 VisEventQueue eventqueue; /**< The plugin it's VisEventQueue for queueing events. */ 353 VisParamContainer *params; /**< The plugin it's VisParamContainer in which VisParamEntries can be placed. */ 354 VisUIWidget *userinterface; /**< The plugin it's top level VisUIWidget, this acts as the container for the 355 * rest of the user interface. */ 356 357 int plugflags; /**< Plugin flags, currently unused but will be used in the future. */ 358 359 VisRandomContext random; /**< Pointer to the plugin it's private random context. It's highly adviced to use 360 * the plugin it's randomize functions. The reason is so more advanced apps can 361 * semi reproduce visuals. */ 362 363 int realized; /**< Flag that indicates if the plugin is realized. */ 364 void *handle; /**< The dlopen handle */ 365 VisList environ; /**< Misc environment specific data. */ 366 }; 367 368 /** 369 * The VisPluginEnviron is used to setup a pre realize/init environment for plugins. 370 * Some types of plugins might need this internally and thus this system provides this function. 371 */ 372 struct _VisPluginEnviron { 373 VisObject object; /**< The VisObject data. */ 374 const char *type; /**< Almost the same as _VisPluginInfo.type. */ 375 VisObject *environ; /**< VisObject that contains environ specific data. */ 376 }; 377 378 /** 379 * The VisActorPlugin structure is the main data structure 380 * for the actor (visualisation) plugin. 381 * 382 * The actor plugin is the visualisation plugin. 383 */ 384 struct _VisActorPlugin { 385 VisObject object; /**< The VisObject data. */ 386 VisPluginActorRequisitionFunc requisition; /**< The requisition function. This is used to 387 * get the desired VisVideo surface size of the plugin. */ 388 VisPluginActorPaletteFunc palette; /**< Used to retrieve the desired palette from the plugin. */ 389 VisPluginActorRenderFunc render; /**< The main render loop. This is called to draw a frame. */ 390 391 VisSongInfo songinfo; /**< Pointer to VisSongInfo that contains information about 392 *the current playing song. This can be NULL. */ 393 394 int depth; /**< The depth flag for the VisActorPlugin. This contains an ORred 395 * value of depths that are supported by the plugin. */ 396 }; 397 398 /** 399 * The VisInputPlugin structure is the main data structure 400 * for the input plugin. 401 * 402 * The input plugin is used to retrieve PCM samples from 403 * certain sources. 404 */ 405 struct _VisInputPlugin { 406 VisObject object; /**< The VisObject data. */ 407 VisPluginInputUploadFunc upload; /**< The sample upload function. This is the main function 408 * of the plugin which uploads sample data into 409 * libvisual. */ 410 }; 411 412 /** 413 * The VisMorphPlugin structure is the main data structure 414 * for the morph plugin. 415 * 416 * The morph plugin is capable of morphing between two VisVideo 417 * sources, and thus is capable of morphing between two 418 * VisActors. 419 */ 420 struct _VisMorphPlugin { 421 VisObject object; /**< The VisObject data. */ 422 VisPluginMorphPaletteFunc palette; /**< The plugin's palette function. This can be used 423 * to obtain a palette for VISUAL_VIDEO_DEPTH_8BIT surfaces. 424 * However the function may be set to NULL. In this case the 425 * VisMorph system morphs between palettes itself. */ 426 VisPluginMorphApplyFunc apply; /**< The plugin it's main function. This is used to morph 427 * between two VisVideo sources. */ 428 int depth; /**< The depth flag for the VisMorphPlugin. This contains an ORred 429 * value of depths that are supported by the plugin. */ 430 int requests_audio;/**< When set on TRUE this will indicate that the Morph plugin 431 * requires an VisAudio context in order to render properly. */ 432 }; 433 434 /** 435 * The VisTransformPlugin structure is the main data structure 436 * for the transform plugin. 437 * 438 * The transform plugin is used to transform videos and palettes 439 * and can be used in visualisation pipelines. 440 */ 441 struct _VisTransformPlugin { 442 VisObject object; /**< The VisObject data. */ 443 VisPluginTransformPaletteFunc palette; /**< Used to transform a VisPalette. Writes directly into the source. */ 444 VisPluginTransformVideoFunc video; /**< Used to transform a VisVideo. Writes directly into the source. */ 445 446 int depth; /**< The depth flag for the VisActorPlugin. This contains an ORred 447 * value of depths that are supported by the plugin. */ 448 int requests_audio;/**< When set on TRUE this will indicate that the Morph plugin 449 * requires an VisAudio context in order to render properly. */ 450 }; 451 452 453 /* prototypes */ 454 VisPluginInfo *visual_plugin_info_new (void); 455 int visual_plugin_info_copy (VisPluginInfo *dest, VisPluginInfo *src); 456 457 int visual_plugin_events_pump (VisPluginData *plugin); 458 VisEventQueue *visual_plugin_get_eventqueue (VisPluginData *plugin); 459 int visual_plugin_set_userinterface (VisPluginData *plugin, VisUIWidget *widget); 460 VisUIWidget *visual_plugin_get_userinterface (VisPluginData *plugin); 461 462 VisPluginInfo *visual_plugin_get_info (VisPluginData *plugin); 463 464 VisParamContainer *visual_plugin_get_params (VisPluginData *plugin); 465 466 VisRandomContext *visual_plugin_get_random_context (VisPluginData *plugin); 467 468 void *visual_plugin_get_specific (VisPluginData *plugin); 469 470 VisPluginRef *visual_plugin_ref_new (void); 471 472 VisPluginData *visual_plugin_new (void); 473 474 VisList *visual_plugin_get_registry (void); 475 VisList *visual_plugin_registry_filter (VisList *pluglist, const char *domain); 476 477 const char *visual_plugin_get_next_by_name (VisList *list, const char *name); 478 const char *visual_plugin_get_prev_by_name (VisList *list, const char *name); 479 480 int visual_plugin_unload (VisPluginData *plugin); 481 VisPluginData *visual_plugin_load (VisPluginRef *ref); 482 int visual_plugin_realize (VisPluginData *plugin); 483 484 VisPluginRef **visual_plugin_get_references (const char *pluginpath, int *count); 485 VisList *visual_plugin_get_list (const char **paths); 486 487 VisPluginRef *visual_plugin_find (VisList *list, const char *name); 488 489 int visual_plugin_get_api_version (void); 490 491 VisSongInfo *visual_plugin_actor_get_songinfo (VisActorPlugin *actplugin); 492 493 const char *visual_plugin_type_get_domain (const char *type); 494 const char *visual_plugin_type_get_package (const char *type); 495 const char *visual_plugin_type_get_type (const char *type); 496 VisPluginTypeDepth visual_plugin_type_get_depth (const char *type); 497 int visual_plugin_type_member_of (const char *domain, const char *type); 498 499 VisPluginEnviron *visual_plugin_environ_new (const char *type, VisObject *environ); 500 int visual_plugin_environ_add (VisPluginData *plugin, VisPluginEnviron *penve); 501 int visual_plugin_environ_remove (VisPluginData *plugin, const char *type); 502 VisObject *visual_plugin_environ_get (VisPluginData *plugin, const char *type); 503 504 505 #ifdef __cplusplus 506 } 507 #endif /* __cplusplus */ 508 509 #endif /* _LV_PLUGIN_H */ 510