1 /** @mainpage frei0r - a minimalistic plugin API for video effects 2 * 3 * @section sec_intro Introduction 4 * 5 * This is frei0r - a minimalistic plugin API for video effects. 6 * 7 * The main emphasis is on simplicity - there are many different applications 8 * that use video effects, and they all have different requirements regarding 9 * their internal plugin API. And that's why frei0r does not try to be a 10 * one-in-all general video plugin API, but instead an API for the most 11 * common video effects: simple filters, sources and mixers that can be 12 * controlled by parameters. 13 * 14 * It's our hope that this way these simple effects can be shared between 15 * many applications, avoiding their reimplementation by different 16 * projects. 17 * 18 * On the other hand, this is not meant as a competing standard to 19 * more ambitious efforts that try to satisfy the needs of many different 20 * applications and more complex effects. 21 * 22 * 23 * @section sec_overview Overview 24 * 25 * If you are new to frei0r, the best thing is probably to have 26 * a look at the <a href="frei0r_8h-source.html">frei0r header</a>, 27 * which is quite simple. 28 * 29 * After that, you might want to look at the 30 * <a href="frei0r_8h.html">frei0r functions</a> in more detail. 31 * 32 * When developing a new frei0r effect, you have to choose 33 * - which effect type to use (\ref PLUGIN_TYPE), 34 * - which color model to use (\ref COLOR_MODEL), and 35 * - which parameter types (\ref PARAM_TYPE) your effect will support. 36 * 37 * To round things up, you should decide whether your effect should have 38 * an associated icon (\ref icons), and where it will be installed 39 * (\ref pluglocations). 40 * 41 * @section sec_changes Changes 42 * 43 * @subsection sec_changes_1_1_1_2 From frei0r 1.1 to frei0r 1.2 44 * - make <vendor> in plugin path optional 45 * - added section on FREI0R_PATH environment variable 46 * - added requirement to initialize all parameters in f0r_construct() 47 * 48 * @subsection sec_changes_1_0_1_1 From frei0r 1.0 to frei0r 1.1 49 * 50 * - added specifications for plugin locations 51 * - added specifications for frei0r icons 52 * - added RGBA8888 color model 53 * - added packed32 color model 54 * - added better specification of color models 55 * - added string type 56 * - added bounds to resolution (8 <= width, height <= 2048) 57 * - width and height must be an integer multiple of 8 58 * - frame data must be 16 byte aligned 59 * - improved update specification (must not change parameters, 60 * must restore fpu state) 61 * - added note for applications to ignore effects with unknown fields 62 * - added new plugin types mixer2 and mixer3 63 * - added section about \ref concurrency 64 */ 65 66 67 /** 68 * \addtogroup pluglocations Plugin Locations 69 * @section sec_pluglocations Plugin Locations 70 * 71 * For Unix platforms there are rules for the location of frei0r plugins. 72 * 73 * frei0r 1.x plugin files should be located in 74 * 75 * - (1) /usr/lib/frei0r-1/\<vendor\> 76 * - (2) /usr/local/lib/frei0r-1/\<vendor\> 77 * - (3) $HOME/.frei0r-1/lib/\<vendor\> 78 * 79 * Examples: 80 * 81 * - /usr/lib/frei0r-1/mob/flippo.so 82 * - /usr/lib/frei0r-1/drone/flippo.so 83 * - /usr/local/lib/frei0r-1/gephex/coma/invert0r.so 84 * - /home/martin/.frei0r-1/lib/martin/test.so 85 * 86 * Like in these examples plugins should be placed in "vendor" subdirs 87 * to reduce name clashes. However, <vendor> is optional and may be left blank. 88 * 89 * @subsection sec_order Plugin Loading Order 90 * 91 * The application shall load plugins in the following order: 3, 2, 1. 92 * If a name clash occurs (two or more frei0r plugins with identical 93 * effect name), the plugins in directory 3 have precedence over plugins 94 * in directory 2, and those in directory 2 have precedence over plugins 95 * in directory 1. 96 * 97 * This makes it possible for users to "override" effects that are 98 * installed in system wide directories by placing plugins in their 99 * home directory. 100 * 101 * The order of loading plugins inside each of the directories 102 * 1, 2, and 3 is not defined. 103 * 104 * @subsection sec_path FREI0R_PATH Environment Variable 105 * 106 * If the environment variable FREI0R_PATH is defined, then it shall be 107 * considered a colon separated list of directories which replaces the 108 * default list. 109 * 110 * For example: 111 * 112 * FREI0R_PATH=/home/foo/frei0r-plugins:/usr/lib/frei0r-1:/etc/frei0r 113 */ 114 115 /** 116 *\addtogroup icons Icons for frei0r effects 117 * @section sec_icons Icons for frei0r effects 118 * 119 * Each frei0r effect can have an associated icon. 120 * 121 * @subsection sec_icon_format Icon Format 122 * 123 * The format of frei0r icons must be png. 124 * Recommended resolution is 64x64. 125 * The icon filename of an effect with effect name "frei0r" 126 * must be "frei0r.png". 127 * 128 * @subsection sec_icon_location Icon location 129 * 130 * The exact location where the application should look for the 131 * plugin is platform dependent. 132 * 133 * For Windows platforms, the icon should be at the same place as 134 * the plugin containing the effect. 135 * 136 * For Unix platforms, the following mapping from plugin location 137 * to icon location must be used: 138 * 139 * Let \<plugin_path\>/\<plugin\> be a frei0r plugin with name \<effect_name\>. 140 * Then the corresponding icon (if any) shall be located in 141 * \<icon_path\>/\<effect_name\>.png. 142 * \<icon_path\> can be obtained in the following way: 143 * 144 * @verbatim 145 <plugin_path> | <icon_path> 146 ---------------------------------------------------------------------------- 147 $HOME/.frei0r-1/lib/<vendor> | $HOME/.frei0r-1/icons/<vendor> 148 /usr/local/lib/frei0r-1/<vendor> | /usr/local/share/frei0r-1/icons/<vendor> 149 /usr/lib/frei0r-1/<vendor> | /usr/share/frei0r-1/icons/<vendor> 150 * | <plugin_path> 151 @endverbatim 152 * 153 * (The wildcard '*' stands for any other plugin_path) 154 * 155 * For other platforms, no location is defined. We recommend to use the 156 * plugin path where possible. 157 */ 158 159 /** 160 * \addtogroup concurrency Concurrency 161 * @section sec_concurrency Concurrency 162 * 163 * - \ref f0r_init 164 * - \ref f0r_deinit 165 * 166 * These methods must not be called more than once. It is obvious that no 167 * concurrent calls are allowed. 168 * 169 * 170 * - \ref f0r_get_plugin_info 171 * - \ref f0r_get_param_info 172 * - \ref f0r_construct 173 * - \ref f0r_destruct 174 * 175 * Concurrent calls of these functions are allowed. 176 * 177 * 178 * - \ref f0r_set_param_value 179 * - \ref f0r_get_param_value 180 * - \ref f0r_update 181 * - \ref f0r_update2 182 * 183 * If a thread is in one of these methods its allowed for another thread to 184 * enter one of theses methods for a different effect instance. But for one 185 * effect instance only one thread is allowed to execute any of these methods. 186 */ 187 188 189 190 /** \file 191 * \brief This file defines the frei0r api, version 1.2. 192 * 193 * A conforming plugin must implement and export all functions declared in 194 * this header. 195 * 196 * A conforming application must accept only those plugins which use 197 * allowed values for the described fields. 198 */ 199 200 #ifndef INCLUDED_FREI0R_H 201 #define INCLUDED_FREI0R_H 202 203 #include <glib.h> 204 205 /** 206 * The frei0r API major version 207 */ 208 #define FREI0R_MAJOR_VERSION 1 209 210 /** 211 * The frei0r API minor version 212 */ 213 #define FREI0R_MINOR_VERSION 2 214 215 //--------------------------------------------------------------------------- 216 217 /** 218 * f0r_init() is called once when the plugin is loaded by the application. 219 * \see f0r_deinit 220 */ 221 int f0r_init(); 222 223 /** 224 * f0r_deinit is called once when the plugin is unloaded by the application. 225 * \see f0r_init 226 */ 227 void f0r_deinit(); 228 229 //--------------------------------------------------------------------------- 230 231 /** \addtogroup PLUGIN_TYPE Type of the Plugin 232 * These defines determine whether the plugin is a 233 * source, a filter or one of the two mixer types 234 * @{ 235 */ 236 237 /** one input and one output */ 238 #define F0R_PLUGIN_TYPE_FILTER 0 239 /** just one output */ 240 #define F0R_PLUGIN_TYPE_SOURCE 1 241 /** two inputs and one output */ 242 #define F0R_PLUGIN_TYPE_MIXER2 2 243 /** three inputs and one output */ 244 #define F0R_PLUGIN_TYPE_MIXER3 3 245 246 /** @} */ 247 248 //--------------------------------------------------------------------------- 249 250 /** \addtogroup COLOR_MODEL Color Models 251 * List of supported color models. 252 * 253 * Note: the color models are endian independent, because the 254 * color components are defined by their position in memory, not 255 * by their significance in an uint32_t value. 256 * 257 * For effects that work on the color components, 258 * RGBA8888 is the recommended color model for frei0r-1.2 effects. 259 * For effects that only work on pixels, PACKED32 is the recommended 260 * color model since it helps the application to avoid unnecessary 261 * color conversions. 262 * 263 * Effects can choose an appropriate color model, applications must support 264 * all color models and do conversions if necessary. Source effects 265 * must not use the PACKED32 color model because the application must know 266 * in which color model the created framebuffers are represented. 267 * 268 * For each color model, a frame consists of width*height pixels which 269 * are stored row-wise and consecutively in memory. The size of a pixel is 270 * 4 bytes. There is no extra pitch parameter 271 * (i.e. the pitch is simply width*4). 272 * 273 * The following additional constraints must be honored: 274 * - The top-most line of a frame is stored first in memory. 275 * - A frame must be aligned to a 16 byte border in memory. 276 * - The width and height of a frame must be positive 277 * - The width and height of a frame must be integer multiples of 8 278 * 279 * These constraints make sure that each line is stored at an address aligned 280 * to 16 byte. 281 */ 282 /*@{*/ 283 /** 284 * In BGRA8888, each pixel is represented by 4 consecutive 285 * unsigned bytes, where the first byte value represents 286 * the blue, the second the green, and the third the red color 287 * component of the pixel. The last value represents the 288 * alpha value. 289 */ 290 #define F0R_COLOR_MODEL_BGRA8888 0 291 292 /** 293 * In RGBA8888, each pixel is represented by 4 consecutive 294 * unsigned bytes, where the first byte value represents 295 * the red, the second the green, and the third the blue color 296 * component of the pixel. The last value represents the 297 * alpha value. 298 */ 299 #define F0R_COLOR_MODEL_RGBA8888 1 300 301 /** 302 * In PACKED32, each pixel is represented by 4 consecutive 303 * bytes, but it is not defined how the color components are 304 * stored. The true color format could be RGBA8888, 305 * BGRA8888, a packed 32 bit YUV format, or any other 306 * color format that stores pixels in 32 bit. 307 * 308 * This is useful for effects that don't work on color but 309 * only on pixels (for example a mirror effect). 310 * 311 * Note that source effects must not use this color model. 312 */ 313 #define F0R_COLOR_MODEL_PACKED32 2 314 /*@}*/ 315 316 /** 317 * The f0r_plugin_info_t structure is filled in by the plugin 318 * to tell the application about its name, type, number of parameters, 319 * and version. 320 * 321 * An application should ignore (i.e. not use) frei0r effects that 322 * have unknown values in the plugin_type or color_model field. 323 * It should also ignore effects with a too high frei0r_version. 324 * 325 * This is necessary to be able to extend the frei0r spec (e.g. 326 * by adding new color models or plugin types) in a way that does not 327 * result in crashes when loading effects that make use of these 328 * extensions into an older application. 329 * 330 * All strings are unicode, 0-terminated, and the encoding is utf-8. 331 */ 332 typedef struct f0r_plugin_info 333 { 334 const char* name; /**< The (short) name of the plugin */ 335 const char* author; /**< The plugin author */ 336 /** The plugin type 337 * \see PLUGIN_TYPE 338 */ 339 int plugin_type; 340 int color_model; /**< The color model used */ 341 int frei0r_version; /**< The frei0r major version this plugin is built for*/ 342 int major_version; /**< The major version of the plugin */ 343 int minor_version; /**< The minor version of the plugin */ 344 int num_params; /**< The number of parameters of the plugin */ 345 const char* explanation; /**< An optional explanation string */ 346 } f0r_plugin_info_t; 347 348 349 /** 350 * Is called once after init. The plugin has to fill in the values in info. 351 * 352 * \param info Pointer to an info struct allocated by the application. 353 */ 354 void f0r_get_plugin_info(f0r_plugin_info_t* info); 355 356 //--------------------------------------------------------------------------- 357 358 /** \addtogroup PARAM_TYPE Parameter Types 359 * 360 * @{ 361 */ 362 363 364 /** 365 * Parameter type for boolean values 366 * \see f0r_param_bool 367 */ 368 #define F0R_PARAM_BOOL 0 369 370 /** 371 * Parameter type for doubles 372 * \see f0r_param_double 373 */ 374 #define F0R_PARAM_DOUBLE 1 375 376 /** 377 * Parameter type for color 378 * \see f0r_param_color 379 */ 380 #define F0R_PARAM_COLOR 2 381 /** 382 * Parameter type for position 383 * \see f0r_param_position 384 */ 385 #define F0R_PARAM_POSITION 3 386 387 /** 388 * Parameter type for string 389 * \see f0r_param_string 390 */ 391 #define F0R_PARAM_STRING 4 392 393 /** 394 * The boolean type. The allowed range of values is [0, 1]. 395 * [0, 0.5[ is mapped to false and [0.5, 1] is mapped to true. 396 */ 397 typedef double f0r_param_bool; 398 399 /** 400 * The double type. The allowed range of values is [0, 1]. 401 */ 402 typedef double f0r_param_double; 403 404 /** 405 * The color type. All three color components are in the range [0, 1]. 406 */ 407 typedef struct f0r_param_color 408 { 409 float r; /**< red color component */ 410 float g; /**< green color component */ 411 float b; /**< blue color component */ 412 } f0r_param_color_t; 413 414 /** 415 * The position type. Both position coordinates are in the range [0, 1]. 416 */ 417 typedef struct f0r_param_position 418 { 419 double x; /**< x coordinate */ 420 double y; /**< y coordinate */ 421 } f0r_param_position_t; 422 423 424 /** 425 * The string type. 426 * Zero terminated array of 8-bit values in utf-8 encoding 427 */ 428 typedef char f0r_param_string; 429 430 /** @} */ 431 432 433 /** 434 * Similar to f0r_plugin_info_t, this structure is filled by the plugin 435 * for every parameter. 436 * 437 * All strings are unicode, 0-terminated, and the encoding is utf-8. 438 */ 439 typedef struct f0r_param_info 440 { 441 const char* name; /**<The (short) name of the param */ 442 int type; /**<The type (see the F0R_PARAM_* defines) */ 443 const char* explanation; /**<Optional explanation (can be 0) */ 444 } f0r_param_info_t; 445 446 /** 447 * f0r_get_param_info is called by the application to query the type of 448 * each parameter. 449 * 450 * \param info is allocated by the application and filled by the plugin 451 * \param param_index the index of the parameter to be queried (from 0 to 452 * num_params-1) 453 */ 454 void f0r_get_param_info(f0r_param_info_t* info, int param_index); 455 456 //--------------------------------------------------------------------------- 457 458 /** 459 * Transparent instance pointer of the frei0r effect. 460 */ 461 typedef void* f0r_instance_t; 462 463 /** 464 * Constructor for effect instances. The plugin returns a pointer to 465 * its internal instance structure. 466 * 467 * The resolution must be an integer multiple of 8, 468 * must be greater than 0 and be at most 2048 in both dimensions. 469 * The plugin must set default values for all parameters in this function. 470 * 471 * \param width The x-resolution of the processed video frames 472 * \param height The y-resolution of the processed video frames 473 * \returns 0 on failure or a pointer != 0 on success 474 * 475 * \see f0r_destruct 476 */ 477 f0r_instance_t f0r_construct(unsigned int width, unsigned int height); 478 479 /** 480 * Destroys an effect instance. 481 * 482 * \param instance The pointer to the plugins internal instance structure. 483 * 484 * \see f0r_construct 485 */ 486 void f0r_destruct(f0r_instance_t instance); 487 488 //--------------------------------------------------------------------------- 489 490 /** 491 * Transparent parameter handle. 492 */ 493 typedef void* f0r_param_t; 494 495 /** 496 * This function allows the application to set the parameter values of an 497 * effect instance. Validity of the parameter pointer is handled by the 498 * application thus the data must be copied by the effect. 499 * 500 * Furthermore, if d an update event/signal is needed in a host 501 * application to notice when parameters have changed, this should be 502 * implemented inside its own update() call. The host application 503 * would presumably need to store the current value as well to see if 504 * it changes; to make this thread safe, it should store a copy of the 505 * current value in a struct which uses instance as a key. 506 * 507 * \param instance the effect instance 508 * \param param pointer to the parameter value 509 * \param param_index index of the parameter 510 * 511 * \see f0r_get_param_value 512 */ 513 void f0r_set_param_value(f0r_instance_t instance, 514 f0r_param_t param, int param_index); 515 516 /** 517 * This function allows the application to query the parameter values of an 518 * effect instance. 519 * 520 * \param instance the effect instance 521 * \param param pointer to the parameter value 522 * \param param_index index of the parameter 523 * 524 * \see f0r_set_param_value 525 */ 526 void f0r_get_param_value(f0r_instance_t instance, 527 f0r_param_t param, int param_index); 528 529 //--------------------------------------------------------------------------- 530 531 /** 532 * This is where the core effect processing happens. The application calls it 533 * after it has set the necessary parameter values. 534 * inframe and outframe must be aligned to an integer multiple of 16 bytes 535 * in memory. 536 * 537 * This funcition should not alter the parameters of the effect in any 538 * way (\ref f0r_get_param_value should return the same values after a call 539 * to \ref f0r_update as before the call). 540 * 541 * The function is responsible to restore the fpu state (e.g. rounding mode) 542 * and mmx state if applicable before it returns to the caller. 543 * 544 * The host mustn't call \ref f0r_update for effects of type 545 * \ref F0R_PLUGIN_TYPE_MIXER2 and \ref F0R_PLUGIN_TYPE_MIXER3. 546 * 547 * \param instance the effect instance 548 * \param time the application time in seconds but with subsecond resolution 549 * (e.g. milli-second resolution). The resolution should be at least 550 * the inter-frame period of the application. 551 * \param inframe the incoming video frame (can be zero for sources) 552 * \param outframe the resulting video frame 553 * 554 * \see f0r_update2 555 */ 556 void f0r_update(f0r_instance_t instance, 557 double time, const guint32* inframe, guint32* outframe); 558 559 //--------------------------------------------------------------------------- 560 561 /** 562 * For effects of type \ref F0R_PLUGIN_TYPE_SOURCE or 563 * \ref F0R_PLUGIN_TYPE_FILTER this method is optional. The \ref f0r_update 564 * method must still be exported for these two effect types. If both are 565 * provided the behavior of them must be the same. 566 * 567 * Effects of type \ref F0R_PLUGIN_TYPE_MIXER2 or \ref F0R_PLUGIN_TYPE_MIXER3 must provide the new \ref f0r_update2 method. 568 569 * \param instance the effect instance 570 * \param time the application time in seconds but with subsecond resolution 571 * (e.g. milli-second resolution). The resolution should be at least 572 * the inter-frame period of the application. 573 * \param inframe1 the first incoming video frame (can be zero for sources) 574 * \param inframe2 the second incoming video frame 575 (can be zero for sources and filters) 576 * \param inframe3 the third incoming video frame 577 (can be zero for sources, filters and mixer2) 578 * \param outframe the resulting video frame 579 * 580 * \see f0r_update 581 */ 582 void f0r_update2(f0r_instance_t instance, 583 double time, 584 const guint32* inframe1, 585 const guint32* inframe2, 586 const guint32* inframe3, 587 guint32* outframe); 588 //--------------------------------------------------------------------------- 589 590 #endif 591