1 /** @mainpage frei0r - a minimalistic plugin API for video effects
3 * @section sec_intro Introduction
5 * This is frei0r - a minimalistic plugin API for video effects.
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.
14 * It's our hope that this way these simple effects can be shared between
15 * many applications, avoiding their reimplementation by different
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.
23 * @section sec_overview Overview
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.
29 * After that, you might want to look at the
30 * <a href="frei0r_8h.html">frei0r functions</a> in more detail.
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.
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).
41 * @section sec_changes Changes
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()
48 * @subsection sec_changes_1_0_1_1 From frei0r 1.0 to frei0r 1.1
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
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
68 * \addtogroup pluglocations Plugin Locations
69 * @section sec_pluglocations Plugin Locations
71 * For Unix platforms there are rules for the location of frei0r plugins.
73 * frei0r 1.x plugin files should be located in
75 * - (1) /usr/lib/frei0r-1/\<vendor\>
76 * - (2) /usr/local/lib/frei0r-1/\<vendor\>
77 * - (3) $HOME/.frei0r-1/lib/\<vendor\>
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
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.
89 * @subsection sec_order Plugin Loading Order
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
97 * This makes it possible for users to "override" effects that are
98 * installed in system wide directories by placing plugins in their
101 * The order of loading plugins inside each of the directories
102 * 1, 2, and 3 is not defined.
104 * @subsection sec_path FREI0R_PATH Environment Variable
106 * If the environment variable FREI0R_PATH is defined, then it shall be
107 * considered a colon separated list of directories which replaces the
112 * FREI0R_PATH=/home/foo/frei0r-plugins:/usr/lib/frei0r-1:/etc/frei0r
116 *\addtogroup icons Icons for frei0r effects
117 * @section sec_icons Icons for frei0r effects
119 * Each frei0r effect can have an associated icon.
121 * @subsection sec_icon_format Icon Format
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".
128 * @subsection sec_icon_location Icon location
130 * The exact location where the application should look for the
131 * plugin is platform dependent.
133 * For Windows platforms, the icon should be at the same place as
134 * the plugin containing the effect.
136 * For Unix platforms, the following mapping from plugin location
137 * to icon location must be used:
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:
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>
153 * (The wildcard '*' stands for any other plugin_path)
155 * For other platforms, no location is defined. We recommend to use the
156 * plugin path where possible.
160 * \addtogroup concurrency Concurrency
161 * @section sec_concurrency Concurrency
166 * These methods must not be called more than once. It is obvious that no
167 * concurrent calls are allowed.
170 * - \ref f0r_get_plugin_info
171 * - \ref f0r_get_param_info
172 * - \ref f0r_construct
173 * - \ref f0r_destruct
175 * Concurrent calls of these functions are allowed.
178 * - \ref f0r_set_param_value
179 * - \ref f0r_get_param_value
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.
191 * \brief This file defines the frei0r api, version 1.2.
193 * A conforming plugin must implement and export all functions declared in
196 * A conforming application must accept only those plugins which use
197 * allowed values for the described fields.
200 #ifndef INCLUDED_FREI0R_H
201 #define INCLUDED_FREI0R_H
206 * The frei0r API major version
208 #define FREI0R_MAJOR_VERSION 1
211 * The frei0r API minor version
213 #define FREI0R_MINOR_VERSION 2
215 //---------------------------------------------------------------------------
218 * f0r_init() is called once when the plugin is loaded by the application.
224 * f0r_deinit is called once when the plugin is unloaded by the application.
229 //---------------------------------------------------------------------------
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
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
248 //---------------------------------------------------------------------------
250 /** \addtogroup COLOR_MODEL Color Models
251 * List of supported color models.
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.
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
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.
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).
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
279 * These constraints make sure that each line is stored at an address aligned
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
290 #define F0R_COLOR_MODEL_BGRA8888 0
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
299 #define F0R_COLOR_MODEL_RGBA8888 1
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.
308 * This is useful for effects that don't work on color but
309 * only on pixels (for example a mirror effect).
311 * Note that source effects must not use this color model.
313 #define F0R_COLOR_MODEL_PACKED32 2
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,
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.
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.
330 * All strings are unicode, 0-terminated, and the encoding is utf-8.
332 typedef struct f0r_plugin_info
334 const char* name; /**< The (short) name of the plugin */
335 const char* author; /**< The plugin author */
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 */
350 * Is called once after init. The plugin has to fill in the values in info.
352 * \param info Pointer to an info struct allocated by the application.
354 void f0r_get_plugin_info(f0r_plugin_info_t* info);
356 //---------------------------------------------------------------------------
358 /** \addtogroup PARAM_TYPE Parameter Types
365 * Parameter type for boolean values
366 * \see f0r_param_bool
368 #define F0R_PARAM_BOOL 0
371 * Parameter type for doubles
372 * \see f0r_param_double
374 #define F0R_PARAM_DOUBLE 1
377 * Parameter type for color
378 * \see f0r_param_color
380 #define F0R_PARAM_COLOR 2
382 * Parameter type for position
383 * \see f0r_param_position
385 #define F0R_PARAM_POSITION 3
388 * Parameter type for string
389 * \see f0r_param_string
391 #define F0R_PARAM_STRING 4
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.
397 typedef double f0r_param_bool;
400 * The double type. The allowed range of values is [0, 1].
402 typedef double f0r_param_double;
405 * The color type. All three color components are in the range [0, 1].
407 typedef struct f0r_param_color
409 float r; /**< red color component */
410 float g; /**< green color component */
411 float b; /**< blue color component */
415 * The position type. Both position coordinates are in the range [0, 1].
417 typedef struct f0r_param_position
419 double x; /**< x coordinate */
420 double y; /**< y coordinate */
421 } f0r_param_position_t;
426 * Zero terminated array of 8-bit values in utf-8 encoding
428 typedef char f0r_param_string;
434 * Similar to f0r_plugin_info_t, this structure is filled by the plugin
435 * for every parameter.
437 * All strings are unicode, 0-terminated, and the encoding is utf-8.
439 typedef struct f0r_param_info
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) */
447 * f0r_get_param_info is called by the application to query the type of
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
454 void f0r_get_param_info(f0r_param_info_t* info, int param_index);
456 //---------------------------------------------------------------------------
459 * Transparent instance pointer of the frei0r effect.
461 typedef void* f0r_instance_t;
464 * Constructor for effect instances. The plugin returns a pointer to
465 * its internal instance structure.
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.
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
477 f0r_instance_t f0r_construct(unsigned int width, unsigned int height);
480 * Destroys an effect instance.
482 * \param instance The pointer to the plugins internal instance structure.
486 void f0r_destruct(f0r_instance_t instance);
488 //---------------------------------------------------------------------------
491 * Transparent parameter handle.
493 typedef void* f0r_param_t;
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.
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.
507 * \param instance the effect instance
508 * \param param pointer to the parameter value
509 * \param param_index index of the parameter
511 * \see f0r_get_param_value
513 void f0r_set_param_value(f0r_instance_t instance,
514 f0r_param_t param, int param_index);
517 * This function allows the application to query the parameter values of an
520 * \param instance the effect instance
521 * \param param pointer to the parameter value
522 * \param param_index index of the parameter
524 * \see f0r_set_param_value
526 void f0r_get_param_value(f0r_instance_t instance,
527 f0r_param_t param, int param_index);
529 //---------------------------------------------------------------------------
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
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).
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.
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.
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
556 void f0r_update(f0r_instance_t instance,
557 double time, const guint32* inframe, guint32* outframe);
559 //---------------------------------------------------------------------------
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.
567 * Effects of type \ref F0R_PLUGIN_TYPE_MIXER2 or \ref F0R_PLUGIN_TYPE_MIXER3 must provide the new \ref f0r_update2 method.
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
582 void f0r_update2(f0r_instance_t instance,
584 const guint32* inframe1,
585 const guint32* inframe2,
586 const guint32* inframe3,
588 //---------------------------------------------------------------------------