frei0r.h File Reference

This file defines the frei0r api, version 1.1. More...

#include <inttypes.h>

Go to the source code of this file.

Data Structures

struct  f0r_plugin_info
struct  f0r_param_color
struct  f0r_param_position
struct  f0r_param_info

Defines

#define FREI0R_MAJOR_VERSION   1
#define FREI0R_MINOR_VERSION   1
#define F0R_PLUGIN_TYPE_FILTER   0
#define F0R_PLUGIN_TYPE_SOURCE   1
#define F0R_PLUGIN_TYPE_MIXER2   2
#define F0R_PLUGIN_TYPE_MIXER3   3
#define F0R_COLOR_MODEL_BGRA8888   0
#define F0R_COLOR_MODEL_RGBA8888   1
#define F0R_COLOR_MODEL_PACKED32   2
#define F0R_PARAM_BOOL   0
#define F0R_PARAM_DOUBLE   1
#define F0R_PARAM_COLOR   2
#define F0R_PARAM_POSITION   3
#define F0R_PARAM_STRING   4

Typedefs

typedef f0r_plugin_info f0r_plugin_info_t
typedef double f0r_param_bool
typedef double f0r_param_double
typedef f0r_param_color f0r_param_color_t
typedef f0r_param_position f0r_param_position_t
typedef char f0r_param_string
typedef f0r_param_info f0r_param_info_t
typedef void * f0r_instance_t
typedef void * f0r_param_t

Functions

int f0r_init ()
void f0r_deinit ()
void f0r_get_plugin_info (f0r_plugin_info_t *info)
void f0r_get_param_info (f0r_param_info_t *info, int param_index)
f0r_instance_t f0r_construct (unsigned int width, unsigned int height)
void f0r_destruct (f0r_instance_t instance)
void f0r_set_param_value (f0r_instance_t instance, f0r_param_t param, int param_index)
void f0r_get_param_value (f0r_instance_t instance, f0r_param_t param, int param_index)
void f0r_update (f0r_instance_t instance, double time, const uint32_t *inframe, uint32_t *outframe)
void f0r_update2 (f0r_instance_t instance, double time, const uint32_t *inframe1, const uint32_t *inframe2, const uint32_t *inframe3, uint32_t *outframe)


Detailed Description

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.


Define Documentation

#define FREI0R_MAJOR_VERSION   1

The frei0r API major version

#define FREI0R_MINOR_VERSION   1

The frei0r API minor version


Typedef Documentation

typedef void* f0r_instance_t

Transparent instance pointer of the frei0r effect.

typedef struct f0r_param_info f0r_param_info_t

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 void* f0r_param_t

Transparent parameter handle.

typedef struct f0r_plugin_info f0r_plugin_info_t

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.


Function Documentation

f0r_instance_t f0r_construct ( unsigned int  width,
unsigned int  height 
)

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.

Parameters:
width The x-resolution of the processed video frames
height The y-resolution of the processed video frames
Returns:
0 on failure or a pointer != 0 on success
See also:
f0r_destruct

void f0r_deinit (  ) 

f0r_deinit is called once when the plugin is unloaded by the application.

See also:
f0r_init

void f0r_destruct ( f0r_instance_t  instance  ) 

Destroys an effect instance.

Parameters:
instance The pointer to the plugins internal instance structure.
See also:
f0r_construct

void f0r_get_param_info ( f0r_param_info_t info,
int  param_index 
)

f0r_get_param_info is called by the application to query the type of each parameter.

Parameters:
info is allocated by the application and filled by the plugin
param_index the index of the parameter to be queried (from 0 to num_params-1)

void f0r_get_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.

Parameters:
instance the effect instance
param pointer to the parameter value
param_index index of the parameter
See also:
f0r_set_param_value

void f0r_get_plugin_info ( f0r_plugin_info_t info  ) 

Is called once after init. The plugin has to fill in the values in info.

Parameters:
info Pointer to an info struct allocated by the application.

int f0r_init (  ) 

f0r_init() is called once when the plugin is loaded by the application.

See also:
f0r_deinit

void f0r_set_param_value ( f0r_instance_t  instance,
f0r_param_t  param,
int  param_index 
)

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.

Parameters:
instance the effect instance
param pointer to the parameter value
param_index index of the parameter
See also:
f0r_get_param_value

void f0r_update ( f0r_instance_t  instance,
double  time,
const uint32_t *  inframe,
uint32_t *  outframe 
)

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 (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.

The host mustn't call f0r_update for effects of type F0R_PLUGIN_TYPE_MIXER2 and F0R_PLUGIN_TYPE_MIXER3.

Parameters:
instance the effect instance
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.
inframe the incoming video frame (can be zero for sources)
outframe the resulting video frame
See also:
f0r_update2

void f0r_update2 ( f0r_instance_t  instance,
double  time,
const uint32_t *  inframe1,
const uint32_t *  inframe2,
const uint32_t *  inframe3,
uint32_t *  outframe 
)

For effects of type F0R_PLUGIN_TYPE_SOURCE or F0R_PLUGIN_TYPE_FILTER this method is optional. The 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 F0R_PLUGIN_TYPE_MIXER2 or F0R_PLUGIN_TYPE_MIXER3 must provide the new f0r_update2 method.

Parameters:
instance the effect instance
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.
inframe1 the first incoming video frame (can be zero for sources)
inframe2 the second incoming video frame (can be zero for sources and filters)
inframe3 the third incoming video frame (can be zero for sources, filters and mixer3)
outframe the resulting video frame
See also:
f0r_update


Generated on Thu May 31 17:38:09 2007 for frei0r by  doxygen 1.5.1