API overview
frei0r API 1.2 is specified by include/frei0r.h. That header is authoritative. This page is a map for readers; the generated API reference renders the complete declarations and comments.
Design
The interface is a C ABI for simple video sources, filters and mixers controlled by a small set of parameter types. Hosts remain responsible for media decoding, timelines, events, user interfaces and encoding.
Each plugin is a shared library. A host loads the library, checks metadata, constructs an instance for a frame size, sets parameters, calls an update function for each frame, and destroys the instance.
Plugin lifecycle
| Function | Responsibility |
|---|---|
f0r_init | Initialize process-wide plugin state |
f0r_get_plugin_info | Return identity, type, color model, version and parameter count |
f0r_get_param_info | Describe one parameter |
f0r_construct | Create an instance for a width and height |
f0r_set_param_value | Set one instance parameter |
f0r_get_param_value | Read one instance parameter |
f0r_update | Process a one-input API 1.0-compatible filter |
f0r_update2 | Process a source, filter, two-input mixer or three-input mixer |
f0r_destruct | Destroy an instance |
f0r_deinit | Release process-wide plugin state |
Browse the generated function list.
Plugin types
- Source: no input frames; generates an output.
- Filter: one input frame.
- Mixer2: two input frames.
- Mixer3: three input frames.
Generated plugin-type reference
Parameter types
The ABI supports Boolean, double, color, position and string parameters. Parameters must be initialized during construction. Hosts use the metadata name, type and explanation to build controls.
Generated parameter-type reference
Color models
The plugin metadata declares how four bytes in each pixel are interpreted. RGBA8888 is recommended for API 1.2 effects. BGRA8888 and packed 32-bit models remain available for compatibility.
Generated color-model reference
Plugin locations
Unix systems define standard system, local and user library locations under frei0r-1. An optional vendor directory avoids name clashes. FREI0R_PATH supplies a platform-separated search list when a host supports custom locations.
Generated plugin-location reference
Icons
An effect can install a PNG icon with the plugin name. Icon directories mirror the library's vendor layout under the corresponding frei0r data directory.
Concurrency
Hosts may use separate instances concurrently. Plugin authors must follow the header's rules for process-wide and instance state rather than assuming all updates happen on one thread.
Generated concurrency reference
C++ wrapper
include/frei0r.hpp provides base classes and a construct<T> helper. It reduces boilerplate but does not replace the C ABI.
Continue with the plugin development guide.