/** @mainpage frei0r - a minimalistic plugin API for video effects * * @section sec_intro Introduction * * This is frei0r - a minimalistic plugin API for video effects. * * The main emphasis is on simplicity - there are many different applications * that use video effects, and they all have different requirements regarding * their internal plugin API. And that's why frei0r does not try to be a * one-in-all general video plugin API, but instead an API for the most * common video effects: simple filters, sources and mixers that can be * controlled by parameters. * * It's our hope that this way these simple effects can be shared between * many applications, avoiding their reimplementation by different * projects. * * On the other hand, this is not meant as a competing standard to * more ambitious efforts that try to satisfy the needs of many different * applications and more complex effects. * * * @section sec_overview Overview * * If you are new to frei0r, the best thing is probably to have * a look at the frei0r header, * which is quite simple. * * After that, you might want to look at the * frei0r functions in more detail. * * When developing a new frei0r effect, you have to choose * - which effect type to use (\ref PLUGIN_TYPE), * - which color model to use (\ref COLOR_MODEL), and * - which parameter types (\ref PARAM_TYPE) your effect will support. * * To round things up, you should decide whether your effect should have * an associated icon (\ref icons), and where it will be installed * (\ref pluglocations). * * @section sec_changes Changes * * @subsection sec_changes_1_1_1_2 From frei0r 1.1 to frei0r 1.2 * - make in plugin path optional * - added section on FREI0R_PATH environment variable * - added requirement to initialize all parameters in f0r_construct() * * @subsection sec_changes_1_0_1_1 From frei0r 1.0 to frei0r 1.1 * * - added specifications for plugin locations * - added specifications for frei0r icons * - added RGBA8888 color model * - added packed32 color model * - added better specification of color models * - added string type * - added bounds to resolution (8 <= width, height <= 2048) * - width and height must be an integer multiple of 8 * - frame data must be 16 byte aligned * - improved update specification (must not change parameters, * must restore fpu state) * - added note for applications to ignore effects with unknown fields * - added new plugin types mixer2 and mixer3 * - added section about \ref concurrency */ /** * \addtogroup pluglocations Plugin Locations * @section sec_pluglocations Plugin Locations * * For Unix platforms there are rules for the location of frei0r plugins. * * frei0r 1.x plugin files should be located in * * - (1) /usr/lib/frei0r-1/\ * - (2) /usr/local/lib/frei0r-1/\ * - (3) $HOME/.frei0r-1/lib/\ * * Examples: * * - /usr/lib/frei0r-1/mob/flippo.so * - /usr/lib/frei0r-1/drone/flippo.so * - /usr/local/lib/frei0r-1/gephex/coma/invert0r.so * - /home/martin/.frei0r-1/lib/martin/test.so * * Like in these examples plugins should be placed in "vendor" subdirs * to reduce name clashes. However, is optional and may be left blank. * * @subsection sec_order Plugin Loading Order * * The application shall load plugins in the following order: 3, 2, 1. * If a name clash occurs (two or more frei0r plugins with identical * effect name), the plugins in directory 3 have precedence over plugins * in directory 2, and those in directory 2 have precedence over plugins * in directory 1. * * This makes it possible for users to "override" effects that are * installed in system wide directories by placing plugins in their * home directory. * * The order of loading plugins inside each of the directories * 1, 2, and 3 is not defined. * * @subsection sec_path FREI0R_PATH Environment Variable * * If the environment variable FREI0R_PATH is defined, then it shall be * considered a colon separated list of directories which replaces the * default list. * * For example: * * FREI0R_PATH=/home/foo/frei0r-plugins:/usr/lib/frei0r-1:/etc/frei0r */ /** *\addtogroup icons Icons for frei0r effects * @section sec_icons Icons for frei0r effects * * Each frei0r effect can have an associated icon. * * @subsection sec_icon_format Icon Format * * The format of frei0r icons must be png. * Recommended resolution is 64x64. * The icon filename of an effect with effect name "frei0r" * must be "frei0r.png". * * @subsection sec_icon_location Icon location * * The exact location where the application should look for the * plugin is platform dependant. * * For Windows platforms, the icon should be at the same place as * the plugin containing the effect. * * For Unix platforms, the following mapping from plugin location * to icon location must be used: * * Let \/\ be a frei0r plugin with name \. * Then the corresponding icon (if any) shall be located in * \/\.png. * \ can be obtained in the following way: * * @verbatim | ----------------------------------------------------------------------------$HOME/.frei0r-1/lib/ | \$HOME/.frei0r-1/icons/ /usr/local/lib/frei0r-1/ | /usr/local/share/frei0r-1/icons/ /usr/lib/frei0r-1/ | /usr/share/frei0r-1/icons/ * | @endverbatim * * (The wildcard '*' stands for any other plugin_path) * * For other platforms, no location is defined. We recommend to use the * plugin path where possible. */ /** * \addtogroup concurrency Concurrency * @section sec_concurrency Concurrency * * - \ref f0r_init * - \ref f0r_deinit * * These methods must not be called more than once. It is obvious that no * concurrent calls are allowed. * * * - \ref f0r_get_plugin_info * - \ref f0r_get_param_info * - \ref f0r_construct * - \ref f0r_destruct * * Concurrent calls of these functions are allowed. * * * - \ref f0r_set_param_value * - \ref f0r_get_param_value * - \ref f0r_update * - \ref f0r_update2 * * If a thread is in one of these methods its allowed for another thread to * enter one of theses methods for a different effect instance. But for one * effect instance only one thread is allowed to execute any of these methods. */ /** \file * \brief This file defines the frei0r api, version 1.2. * * A conforming plugin must implement and export all functions declared in * this header. * * A conforming application must accept only those plugins which use * allowed values for the described fields. */ #ifndef INCLUDED_FREI0R_H #define INCLUDED_FREI0R_H #include /** * The frei0r API major version */ #define FREI0R_MAJOR_VERSION 1 /** * The frei0r API minor version */ #define FREI0R_MINOR_VERSION 2 //--------------------------------------------------------------------------- /** * f0r_init() is called once when the plugin is loaded by the application. * \see f0r_deinit */ int f0r_init(); /** * f0r_deinit is called once when the plugin is unloaded by the application. * \see f0r_init */ void f0r_deinit(); //--------------------------------------------------------------------------- /** \addtogroup PLUGIN_TYPE Type of the Plugin * These defines determine whether the plugin is a * source, a filter or one of the two mixer types * @{ */ /** one input and one output */ #define F0R_PLUGIN_TYPE_FILTER 0 /** just one output */ #define F0R_PLUGIN_TYPE_SOURCE 1 /** two inputs and one output */ #define F0R_PLUGIN_TYPE_MIXER2 2 /** three inputs and one output */ #define F0R_PLUGIN_TYPE_MIXER3 3 /** @} */ //--------------------------------------------------------------------------- /** \addtogroup COLOR_MODEL Color Models * List of supported color models. * * Note: the color models are endian independent, because the * color components are defined by their positon in memory, not * by their significance in an uint32_t value. * * For effects that work on the color components, * RGBA8888 is the recommended color model for frei0r-1.2 effects. * For effects that only work on pixels, PACKED32 is the recommended * color model since it helps the application to avoid unnecessary * color conversions. * * Effects can choose an appropriate color model, applications must support * all color models and do conversions if necessary. Source effects * must not use the PACKED32 color model because the application must know * in which color model the created framebuffers are represented. * * For each color model, a frame consists of width*height pixels which * are stored row-wise and consecutively in memory. The size of a pixel is * 4 bytes. There is no extra pitch parameter * (i.e. the pitch is simply width*4). * * The following additional constraints must be honored: * - The top-most line of a frame is stored first in memory. * - A frame must be aligned to a 16 byte border in memory. * - The width and height of a frame must be positive * - The width and height of a frame must be integer multiples of 8 * * These constraints make sure that each line is stored at an address aligned * to 16 byte. */ /*@{*/ /** * In BGRA8888, each pixel is represented by 4 consecutive * unsigned bytes, where the first byte value represents * the blue, the second the green, and the third the red color * component of the pixel. The last value represents the * alpha value. */ #define F0R_COLOR_MODEL_BGRA8888 0 /** * In RGBA8888, each pixel is represented by 4 consecutive * unsigned bytes, where the first byte value represents * the red, the second the green, and the third the blue color * component of the pixel. The last value represents the * alpha value. */ #define F0R_COLOR_MODEL_RGBA8888 1 /** * In PACKED32, each pixel is represented by 4 consecutive * bytes, but it is not defined how the color componets are * stored. The true color format could be RGBA8888, * BGRA8888, a packed 32 bit YUV format, or any other * color format that stores pixels in 32 bit. * * This is useful for effects that don't work on color but * only on pixels (for example a mirror effect). * * Note that source effects must not use this color model. */ #define F0R_COLOR_MODEL_PACKED32 2 /*@}*/ /** * The f0r_plugin_info_t structure is filled in by the plugin * to tell the application about its name, type, number of parameters, * and version. * * An application should ignore (i.e. not use) frei0r effects that * have unknown values in the plugin_type or color_model field. * It should also ignore effects with a too high frei0r_version. * * This is necessary to be able to extend the frei0r spec (e.g. * by adding new color models or plugin types) in a way that does not * result in crashes when loading effects that make use of these * extensions into an older application. * * All strings are unicode, 0-terminated, and the encoding is utf-8. */ typedef struct f0r_plugin_info { const char* name; /**< The (short) name of the plugin */ const char* author; /**< The plugin author */ /** The plugin type * \see PLUGIN_TYPE */ int plugin_type; int color_model; /**< The color model used */ int frei0r_version; /**< The frei0r major version this plugin is built for*/ int major_version; /**< The major version of the plugin */ int minor_version; /**< The minor version of the plugin */ int num_params; /**< The number of parameters of the plugin */ const char* explanation; /**< An optional explanation string */ } f0r_plugin_info_t; /** * Is called once after init. The plugin has to fill in the values in info. * * \param info Pointer to an info struct allocated by the application. */ void f0r_get_plugin_info(f0r_plugin_info_t* info); //--------------------------------------------------------------------------- /** \addtogroup PARAM_TYPE Parameter Types * * @{ */ /** * Parameter type for boolean values * \see f0r_param_bool */ #define F0R_PARAM_BOOL 0 /** * Parameter type for doubles * \see f0r_param_double */ #define F0R_PARAM_DOUBLE 1 /** * Parameter type for color * \see f0r_param_color */ #define F0R_PARAM_COLOR 2 /** * Parameter type for position * \see f0r_param_position */ #define F0R_PARAM_POSITION 3 /** * Parameter type for string * \see f0r_param_string */ #define F0R_PARAM_STRING 4 /** * The boolean type. The allowed range of values is [0, 1]. * [0, 0.5[ is mapped to false and [0.5, 1] is mapped to true. */ typedef double f0r_param_bool; /** * The double type. The allowed range of values is [0, 1]. */ typedef double f0r_param_double; /** * The color type. All three color components are in the range [0, 1]. */ typedef struct f0r_param_color { float r; /**< red color component */ float g; /**< green color component */ float b; /**< blue color component */ } f0r_param_color_t; /** * The position type. Both position coordinates are in the range [0, 1]. */ typedef struct f0r_param_position { double x; /**< x coordinate */ double y; /**< y coordinate */ } f0r_param_position_t; /** * The string type. * Zero terminated array of 8-bit values in utf-8 encoding */ typedef char f0r_param_string; /** @} */ /** * Similar to f0r_plugin_info_t, this structure is filled by the plugin * for every parameter. * * All strings are unicode, 0-terminated, and the encoding is utf-8. */ typedef struct f0r_param_info { const char* name; /**