diff options
Diffstat (limited to 'gst/frei0r/frei0r.h')
| -rw-r--r-- | gst/frei0r/frei0r.h | 567 |
1 files changed, 567 insertions, 0 deletions
diff --git a/gst/frei0r/frei0r.h b/gst/frei0r/frei0r.h new file mode 100644 index 00000000..f6b81d2b --- /dev/null +++ b/gst/frei0r/frei0r.h @@ -0,0 +1,567 @@ +/** @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 <a href="frei0r_8h-source.html">frei0r header</a>, + * which is quite simple. + * + * After that, you might want to look at the + * <a href="frei0r_8h.html">frei0r functions</a> 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_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/\<vendor\> + * - (2) /usr/local/lib/frei0r-1/\<vendor\> + * - (3) $HOME/.frei0r-1/lib/\<vendor\> + * + * 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. + * + * @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. + */ + +/** + *\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 \<plugin_path\>/\<plugin\> be a frei0r plugin with name \<effect_name\>. + * Then the corresponding icon (if any) shall be located in + * \<icon_path\>/\<effect_name\>.png. + * \<icon_path\> can be obtained in the following way: + * + * @verbatim + <plugin_path> | <icon_path> + ---------------------------------------------------------------------------- + $HOME/.frei0r-1/lib/<vendor> | $HOME/.frei0r-1/icons/<vendor> + /usr/local/lib/frei0r-1/<vendor> | /usr/local/share/frei0r-1/icons/<vendor> + /usr/lib/frei0r-1/<vendor> | /usr/share/frei0r-1/icons/<vendor> + * | <plugin_path> + @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.1. + * + * 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 <inttypes.h> + +/** + * The frei0r API major version + */ +#define FREI0R_MAJOR_VERSION 1 + +/** + * The frei0r API minor version + */ +#define FREI0R_MINOR_VERSION 1 + +//--------------------------------------------------------------------------- + +/** + * 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.1 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; /**<The (short) name of the param */ + int type; /**<The type (see the F0R_PARAM_* defines) */ + const char* explanation; /**<Optional explanation (can be 0) */ +} f0r_param_info_t; + +/** + * f0r_get_param_info is called by the application to query the type of + * each parameter. + * + * \param info is allocated by the application and filled by the plugin + * \param param_index the index of the parameter to be queried (from 0 to + * num_params-1) + */ +void f0r_get_param_info(f0r_param_info_t* info, int param_index); + +//--------------------------------------------------------------------------- + +/** + * Transparent instance pointer of the frei0r effect. + */ +typedef void* f0r_instance_t; + +/** + * Constructor for effect instances. The plugin returns a pointer to + * its internal instance structure. + * + * The resolution has to be an integer multiple of 8, + * must be greater than 0 and be at most 2048 in both dimensions. + * + * \param width The x-resolution of the processed video frames + * \param height The y-resolution of the processed video frames + * \returns 0 on failure or a pointer != 0 on success + * + * \see f0r_destruct + */ +f0r_instance_t f0r_construct(unsigned int width, unsigned int height); + +/** + * Destroys an effect instance. + * + * \param instance The pointer to the plugins internal instance structure. + * + * \see f0r_construct + */ +void f0r_destruct(f0r_instance_t instance); + +//--------------------------------------------------------------------------- + +/** + * Transparent parameter handle. + */ +typedef void* f0r_param_t; + +/** + * This function allows the application to set the parameter values of an + * effect instance. Validity of the parameter pointer is handled by the + * application thus the data must be copied by the effect. + * + * \param instance the effect instance + * \param param pointer to the parameter value + * \param param_index index of the parameter + * + * \see f0r_get_param_value + */ +void f0r_set_param_value(f0r_instance_t instance, + f0r_param_t param, int param_index); + +/** + * This function allows the application to query the parameter values of an + * effect instance. + * + * \param instance the effect instance + * \param param pointer to the parameter value + * \param param_index index of the parameter + * + * \see f0r_set_param_value + */ +void f0r_get_param_value(f0r_instance_t instance, + f0r_param_t param, int param_index); + +//--------------------------------------------------------------------------- + +/** + * This is where the core effect processing happens. The application calls it + * after it has set the necessary parameter values. + * inframe and outframe must be aligned to an integer multiple of 16 bytes + * in memory. + * + * This funcition should not alter the parameters of the effect in any + * way (\ref f0r_get_param_value should return the same values after a call + * to \ref f0r_update as before the call). + * + * The function is responsible to restore the fpu state (e.g. rounding mode) + * and mmx state if applicable before it returns to the caller. + * + * The host mustn't call \ref f0r_update for effects of type + * \ref F0R_PLUGIN_TYPE_MIXER2 and \ref F0R_PLUGIN_TYPE_MIXER3. + * + * \param instance the effect instance + * \param time the application time in seconds but with subsecond resolution + * (e.g. milli-second resolution). The resolution should be at least + * the inter-frame period of the application. + * \param inframe the incoming video frame (can be zero for sources) + * \param outframe the resulting video frame + * + * \see f0r_update2 + */ +void f0r_update(f0r_instance_t instance, + double time, const uint32_t* inframe, uint32_t* outframe); + +//--------------------------------------------------------------------------- + +/** + * For effects of type \ref F0R_PLUGIN_TYPE_SOURCE or + * \ref F0R_PLUGIN_TYPE_FILTER this method is optional. The \ref f0r_update + * method must still be exported for these two effect types. If both are + * provided the behavior of them must be the same. + * + * Effects of type \ref F0R_PLUGIN_TYPE_MIXER2 or \ref F0R_PLUGIN_TYPE_MIXER3 must provide the new \ref f0r_update2 method. + + * \param instance the effect instance + * \param time the application time in seconds but with subsecond resolution + * (e.g. milli-second resolution). The resolution should be at least + * the inter-frame period of the application. + * \param inframe1 the first incoming video frame (can be zero for sources) + * \param inframe2 the second incoming video frame + (can be zero for sources and filters) + * \param inframe3 the third incoming video frame + (can be zero for sources, filters and mixer3) + * \param outframe the resulting video frame + * + * \see f0r_update + */ +void f0r_update2(f0r_instance_t instance, + double time, + const uint32_t* inframe1, + const uint32_t* inframe2, + const uint32_t* inframe3, + uint32_t* outframe); +//--------------------------------------------------------------------------- + +#endif |