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

#include <inttypes.h>

Include dependency graph for frei0r.h:

Data Structures
struct	f0r_plugin_info

struct	f0r_param_color

struct	f0r_param_position

struct	f0r_param_info

Macros
#define	FREI0R_MAJOR_VERSION 1

#define	FREI0R_MINOR_VERSION 2

#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 struct f0r_plugin_info	f0r_plugin_info_t

typedef double	f0r_param_bool

typedef double	f0r_param_double

typedef struct f0r_param_color	f0r_param_color_t

typedef struct f0r_param_position	f0r_param_position_t

typedef char *	f0r_param_string

typedef struct f0r_param_info	f0r_param_info_t

typedef void *	f0r_instance_t

typedef void *	f0r_param_t

Functions
int	f0r_init (void)

void	f0r_deinit (void)

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

Definition in file frei0r.h.

Macro Definition Documentation

◆ F0R_COLOR_MODEL_BGRA8888

#define F0R_COLOR_MODEL_BGRA8888 0

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.

Definition at line 299 of file frei0r.h.

◆ F0R_COLOR_MODEL_PACKED32

#define F0R_COLOR_MODEL_PACKED32 2

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.

Definition at line 322 of file frei0r.h.

◆ F0R_COLOR_MODEL_RGBA8888

#define F0R_COLOR_MODEL_RGBA8888 1

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.

Definition at line 308 of file frei0r.h.

◆ FREI0R_MAJOR_VERSION

#define FREI0R_MAJOR_VERSION 1

The frei0r API major version

Definition at line 217 of file frei0r.h.

◆ FREI0R_MINOR_VERSION

#define FREI0R_MINOR_VERSION 2

The frei0r API minor version

Definition at line 222 of file frei0r.h.

Typedef Documentation

◆ f0r_instance_t

typedef void* f0r_instance_t

Transparent instance pointer of the frei0r effect.

Definition at line 470 of file frei0r.h.

◆ f0r_param_info_t

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.

◆ f0r_param_t

typedef void* f0r_param_t

Transparent parameter handle.

Definition at line 502 of file frei0r.h.

◆ f0r_plugin_info_t

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_construct()

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 must be an integer multiple of 8, must be greater than 0 and be at most 2048 in both dimensions. The plugin must set default values for all parameters in this function.

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

◆ f0r_deinit()

void f0r_deinit ( void )

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

See also: f0r_init

◆ f0r_destruct()

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

◆ f0r_get_param_info()

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)

◆ f0r_get_param_value()

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.

If the parameter type is of F0R_PARAM_STRING, then the caller should supply a pointer to f0r_param_string (char**). The plugin sets the pointer to the address of its copy of the parameter value. Therefore, the caller should not free the result. If the caller needs to modify the value, it should make a copy of it and modify before calling f0r_set_param_value().

Parameters

instance	the effect instance
param	pointer to the parameter value
param_index	index of the parameter

See also: f0r_set_param_value

◆ f0r_get_plugin_info()

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.

◆ f0r_init()

int f0r_init ( void )

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

See also: f0r_deinit

◆ f0r_set_param_value()

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.

If the parameter type is of F0R_PARAM_STRING, then the caller should supply a pointer to f0r_param_string (char**). The plugin must copy copy the string and not assume it exists beyond the lifetime of the call. The reason a double pointer is requested when only a single is really needed is simply for API consistency.

Furthermore, if an update event/signal is needed in a host application to notice when parameters have changed, this should be implemented inside its own update() call. The host application would presumably need to store the current value as well to see if it changes; to make this thread safe, it should store a copy of the current value in a struct which uses instance as a key.

Parameters

instance	the effect instance
param	pointer to the parameter value
param_index	index of the parameter

See also: f0r_get_param_value

◆ f0r_update()

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 function 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

◆ 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 mixer2)
outframe	the resulting video frame

See also: f0r_update

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ F0R_COLOR_MODEL_BGRA8888

◆ F0R_COLOR_MODEL_PACKED32

◆ F0R_COLOR_MODEL_RGBA8888

◆ FREI0R_MAJOR_VERSION

◆ FREI0R_MINOR_VERSION

Typedef Documentation

◆ f0r_instance_t

◆ f0r_param_info_t

◆ f0r_param_t

◆ f0r_plugin_info_t

Function Documentation

◆ f0r_construct()

◆ f0r_deinit()

◆ f0r_destruct()

◆ f0r_get_param_info()

◆ f0r_get_param_value()

◆ f0r_get_plugin_info()

◆ f0r_init()

◆ f0r_set_param_value()

◆ f0r_update()

◆ f0r_update2()