| Newsgroups |
gmane.comp.video.gephex.devel |
| Message-ID |
<[email protected]> |
Archive: [email protected]
New revision: frei0r--main--1.1--patch-1
--
Revision: frei0r--main--1.1--patch-1
Archive: [email protected]
Creator: The Gephex Source Archive <[email protected]>
Date: Sun Mar 13 17:55:28 CET 2005
Standard-date: 2005-03-13 16:55:28 GMT
Modified-files: frei0r.h
New-patches: [email protected]/frei0r--georg--1.1--base-0
[email protected]/frei0r--georg--1.1--patch-1
[email protected]/frei0r--georg--1.1--patch-2
[email protected]/frei0r--georg--1.1--patch-3
[email protected]/frei0r--georg--1.1--patch-4
[email protected]/frei0r--georg--1.1--patch-5
[email protected]/frei0r--georg--1.1--patch-6
[email protected]/frei0r--georg--1.1--patch-7
[email protected]/frei0r--georg--1.1--patch-8
[email protected]/frei0r--main--1.1--patch-1
Summary: [MERGE-REQUEST] First changes towards frei0r-1.1
Keywords:
Patches applied:
* [email protected]/frei0r--georg--1.1--base-0
tag of [email protected]/frei0r--main--1.1--base-0
* [email protected]/frei0r--georg--1.1--patch-1
Set API version to 1.1 and added RGBA8888 color format
* [email protected]/frei0r--georg--1.1--patch-2
Added changes section and string type
* [email protected]/frei0r--georg--1.1--patch-3
Improved specification of update (fpu state, should not change params)
* [email protected]/frei0r--georg--1.1--patch-4
Minor cleanup
* [email protected]/frei0r--georg--1.1--patch-5
More spec...
* [email protected]/frei0r--georg--1.1--patch-6
Added packed32 color format
* [email protected]/frei0r--georg--1.1--patch-7
Added color model restrictions
* [email protected]/frei0r--georg--1.1--patch-8
Some typos, color format -> color model
* added directories
{arch}/frei0r/frei0r--georg/frei0r--georg--1.1
{arch}/frei0r/frei0r--georg/frei0r--georg--1.1/[email protected]
{arch}/frei0r/frei0r--georg/frei0r--georg--1.1/[email protected]/patch-log
* added files
{arch}/frei0r/frei0r--georg/frei0r--georg--1.1/[email protected]/patch-log/base-0
{arch}/frei0r/frei0r--georg/frei0r--georg--1.1/[email protected]/patch-log/patch-1
{arch}/frei0r/frei0r--georg/frei0r--georg--1.1/[email protected]/patch-log/patch-2
{arch}/frei0r/frei0r--georg/frei0r--georg--1.1/[email protected]/patch-log/patch-3
{arch}/frei0r/frei0r--georg/frei0r--georg--1.1/[email protected]/patch-log/patch-4
{arch}/frei0r/frei0r--georg/frei0r--georg--1.1/[email protected]/patch-log/patch-5
{arch}/frei0r/frei0r--georg/frei0r--georg--1.1/[email protected]/patch-log/patch-6
{arch}/frei0r/frei0r--georg/frei0r--georg--1.1/[email protected]/patch-log/patch-7
{arch}/frei0r/frei0r--georg/frei0r--georg--1.1/[email protected]/patch-log/patch-8
{arch}/frei0r/frei0r--main/frei0r--main--1.1/[email protected]/patch-log/patch-1
* modified files
--- orig/frei0r.h
+++ mod/frei0r.h
@@ -20,10 +20,20 @@
*/
/** ile
- * rief This file defines the frei0r api.
+ * rief This file defines the frei0r api, version 1.1.
*
- * A conforming plugin must implement and
- * export all functions declared in this header.
+ * A conforming plugin must implement and export all functions declared in
+ * this header.
+ *
+ * Changes from frei0r-1.0 to frei0r-1.1:
+ * - added RGBA8888 color model
+ * - added better specification of color model
+ * - added string type
+ * - added bounds to resolution (8 <= resx, resy <= 2048)
+ * - improved update specification (must not change parameters,
+ * must restore fpu state)
+ * - added note for applications to ignore effects with unknown fields
+ * - added packed32 color model
*/
#ifndef INCLUDED_FREI0R_H
@@ -39,7 +49,7 @@
/**
* The frei0r API minor version
*/
-#define FREI0R_MINOR_VERSION 0
+#define FREI0R_MINOR_VERSION 1
//---------------------------------------------------------------------------
@@ -66,15 +76,70 @@
/*@}*/
/**
- * List of supported color models - so far only BGRA8888.
+ * @name 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 a uin32_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.
+ */
+/*@{*/
+/**
+ * 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.
*/
typedef struct f0r_plugin_info
{
@@ -86,13 +151,14 @@
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 (can be 0) */
+ const char* explanation; /**< An optional 0-terminated explanation string
+ (can be 0) encoding is utf-8 */
} f0r_plugin_info_t;
/**
- * Is called once after init. The plugin has to fill in the values
- * in info.
+ * 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);
@@ -118,6 +184,10 @@
*/
#define F0R_PARAM_POSITION 3
+/**
+ * Parameter type for string
+ */
+#define F0R_PARAM_STRING 4
/**
* The boolean type. The allowed range of values is [0, 1].
@@ -131,8 +201,7 @@
typedef double f0r_param_double;
/**
- * The color type. All three color components are in the range
- * [0, 1].
+ * The color type. All three color components are in the range [0, 1].
*/
typedef struct f0r_param_color
{
@@ -142,8 +211,7 @@
} f0r_param_color_t;
/**
- * The position type. Both position coordinates are in the range
- * [0, 1].
+ * The position type. Both position coordinates are in the range [0, 1].
*/
typedef struct f0r_param_position
{
@@ -153,6 +221,13 @@
/**
+ * The string type.
+ * Zero terminated array of 8-bit values in utf-8 encoding
+ */
+typedef uint8_t f0r_param_string;
+
+
+/**
* Similar to f0r_plugin_info_t, this structure
* is filled by the plugin for every parameter.
*/
@@ -166,6 +241,7 @@
/**
* 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)
@@ -178,8 +254,11 @@
/**
* Constructor for effect instances. The plugin returns a pointer to
- * its internal instance structure. The resolution has to be
- * a multiple of 8 in both dimension.
+ * its internal instance structure.
+ *
+ * The resolution has to be a 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
*
eturns 0 on failure or a pointer != 0 on success
@@ -188,6 +267,7 @@
/**
* Destroys an effect instance.
+ *
* \param instance The pointer to the plugins internal instance structure.
*/
void f0r_destruct(f0r_instance_t instance);
@@ -199,7 +279,8 @@
/**
* 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.
+ * 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
@@ -210,6 +291,7 @@
/**
* 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
@@ -222,7 +304,14 @@
/**
* This is where the core effect processing happens. The application calls it
* after it has set the necessary parameter values.
- * inframe and outframe data has to be aligned to a multiple of eight.
+ * inframe and outframe data has to be aligned to a multiple of eight bytes.
+ *
+ * This funcition should not alter the parameters of the effect in any
+ * way (f0r_get_param_value should return the same values after a call
+ * to 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.
*
* \param instance the effect instance
* \param time the application time in seconds but with subsecond resolution