README

   ___________              ._________
   \_   _____/______   ____ |__\   _  \_______
    |    __) \_  __ \_/ __ \|  /  /_\  \_  __ \
    |     \   |  | \/\  ___/|  \  \_/   \  | \/
    \___  /   |__|    \___  >__|\_____  /__|
        \/                \/          \/

  Minimalistic plugin API for video effects  v.1.2.1

  	       	      by the Piksel Developers Union


Table of Contents
=================
Introduction 
    What Frei0r is 
    What Frei0r is not 
    Current status 
    Code gallery 
    History 
Download 
    Source code 
        Build dependencies 
    Debian / Ubuntu 
    Apple / OSX 
Documentation 
    API explanation 
    C++ Filter example 
Communication 
Acknowledgments 


Introduction 
~~~~~~~~~~~~~


What Frei0r is 
===============

Frei0r is a minimalistic plugin API for video effects.

The main emphasis  is on simplicity for an API that  will round up the
most common video effects into 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.

What Frei0r is not 
===================

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

It is not meant as a generic API for all kinds of video applications,
as it doesn't provides things like an extensive parameter mechanism or
event handling.

Eventually the frei0r API can be wrapped by higher level APIs
expanding its functionalities (for instance as GStreamer, MLT, FFmpeg
and others do).

Current status 
===============


If you like to  peek in what's boiling in the pot,  have a look at our
[TODO]

Developers  are sporadically  contributing and  we are  happy  if more
people like to get involved, so let us know about your creations! Code
and  patches  are  well  accepted,   get  in  touch  with  us  on  the
mailinglist.


[TODO]: file:TODO

Code gallery 
=============
 
You might  want to  look at the  code in  frei0r more in  detail, then
browse the existing effects by visiting the [Frei0r plugin gallery].


[Frei0r plugin gallery]: /gallery

History 
========

Frei0r  has been around  since 2004,  born from  yearly brainstormings
held at the  [Piksel] conference with the participation  of various free
and open source video software developers.

It is mostly adopted on  GNU/Linux and OSX platforms, counts more than
80  effects implemented  and is  used  by free  video applications  as
[PureData],  [Open  Movie  Editor],  [DVEdit], [Gephex],  [LiVES],  [FreeJ],  [MøB],
[VeeJay], [MLT] and [KDEnLive] among the others.

Find our more on the [Wikipedia page about Frei0r].



[Piksel]: http://www.piksel.no
[PureData]: http://www.artefacte.org/pd/
[Open  Movie  Editor]: http://openmovieeditor.sourceforge.net/
[DVEdit]: http://www.freenet.org.nz/dvedit
[Gephex]: http://www.gephex.org/
[LiVES]: http://lives.sf.net
[FreeJ]: http://freej.dyne.org
[MøB]: http://mob.bek.no/
[VeeJay]: http://veejayhq.net
[MLT]: http://www.mltframework.org/
[KDEnLive]: http://www.kdenlive.org/
[Wikipedia page about Frei0r]: http://en.wikipedia.org/wiki/Frei0r

Download 
~~~~~~~~~

Source code 
============

Stable frei0r releases are packaged periodically and distributed on

 [ftp://ftp.dyne.org/frei0r]

We encourage the unauthorized mirroring of this source repository by
all those interested, using the command

 rsync -Pr rsync.dyne.org::frei0r .

Frei0r sourcecode is released under the terms of the GNU General
Public License and, eventually other compatible Free Software
licenses.

The latest source for frei0r plugins can be attained using our
revisioning system *GIT*

 git clone git://code.dyne.org/frei0r.git

Daily snapshots are on the FTP and on [www.piksel.no/frei0r/snapshot]


[www.piksel.no/frei0r/snapshot]: http://www.piksel.no/frei0r/snapshot/

Build dependencies 
-------------------

 + GNU autotools ( ./configure && make )
   or
 + CMake ( cmake . && make )

Frei0r can be built on GNU/Linux, M$/Windows and Apple/OSX platforms,
possibly in even more environments.

* Optional Dependencies 
  
  + [Gavl] ( required for scale0tilt and vectorscope filters )
  + [OpenCV] (required for facebl0r filter )
  
  

  [Gavl]: http://gmerlin.sourceforge.net/
  [OpenCV]: http://opencvlibrary.sourceforge.net/

Debian / Ubuntu 
================

Binary packages  are mantained  for Debian ([QA])  and Ubuntu  ([pkg]), to
install the stable version distributed use *apt-get* or *synaptic*:

 sudo apt-get install frei0r-plugins


 [QA]: http://packages.qa.debian.org/f/frei0r.html
 [pkg]: http://packages.ubuntu.com/search?searchon=names&keywords=frei0r

Apple / OSX 
============

[MacPorts] provide ready  to install packages for OSX:  in case you have
this packaging system installed, you  just need to open a terminal and
give the following command:

sudo port install frei0r-plugins


[MacPorts]: http://www.macports.org

Documentation 
~~~~~~~~~~~~~~

If you  are new to frei0r (but  not to programming) the  best thing is
probably to  have a look at  the [frei0r header], which  is quite simple
and well documented


[frei0r header]: /codedoc/html/frei0r_8h-source.html

API explanation 
================

While  the main  source of  documentation for  the Frei0r  API  is the
header, the  sourcecode is  well commented so  you can study  its full
[doxyfied documentation] online.


[doxyfied documentation]: http://frei0r.dyne.org/codedoc/html

C++ Filter example 
===================

A simple skeleton for a frei0r video filter looks like this:


  #include <frei0r.hpp>
  
  typedef struct {
    int16_t w, h;
    uint8_t bpp;
    uint32_t size;
  } ScreenGeometry;
  
  class MyExample: public frei0r::filter {
  public:
    MyExample(int wdt, int hgt);
    ~MyExample();
    virtual void update();
  private:
    ScreenGeometry geo;
    void _init(int wdt, int hgt);
  }
  
  MyExample::MyExample() { /* constructor */ }
  MyExample::~MyExample() { /* destructor */ }
  
  void MyExample::_init(int wdt, int hgt) {
    geo.w = wdt;
    geo.h = hgt;
    geo.bpp = 32; // this filter works only in RGBA 32bit
    geo.size = geo.w*geo.h*(geo.bpp/8); // calculate the size in bytes
  }
  
  void MyExample::update() {
    // we get video input via buffer pointer (void*)in 
    uint32_t *src = (uint32_t*)in;
    // and we give video output via buffer pointer (void*)out
    uint32_t *dst = (uint32_t*)out;
    // this example here does just a copy of input to output
    memcpy(dst, src, geo.size);
  }
    
  frei0r::construct<MyExample>
          plugin("MyExample", "short and simple description for my example",
                 "Who did it", 1, 0);

Communication 
~~~~~~~~~~~~~~

You  can get  in touch  with our  developer community,  send  your new
effects and share your intentions with us.

We have a  free mailinglist open to subscription  on [frei0r-devel] with
[public archives] that are also [searchable and indexed] online.

For   effective   and   indexed   bug   reporting   regarding   plugin
implementations  and platform  builds,  here is  a publicly  available
[issue tracker].


[frei0r-devel]: https://piksel.no/mailman/listinfo/frei0r-devel
[public archives]: http://piksel.no/pipermail/frei0r-devel/
[searchable and indexed]: http://blog.gmane.org/gmane.comp.video.frei0r.devel
[issue tracker]: http://www.piksel.no/projects/frei0r/report

Acknowledgments 
~~~~~~~~~~~~~~~~


Frei0r  is the  result of  a  collective effort  in coordination  with
several software developers meeting at [Piksel] between 2003 and 2005 to
find a common standard for video effect plugins to be used among their
applications:    Andraz   Tori    (Cinelerra/CVS),    Daniel   Fischer
(Pakt/GStreamet), Denis Jaromil  Rojo (FreeJ/Dyne), Gabriel "Salsaman"
Finch  (LiVES),  Kentaro  Fukuchi  (EffecTV), Niels  Elburg  (VeeJay),
Øyvind  Kolås  (Gegl/Babl/Gimp),  Tom Schouten  (PDP/PureData),  Georg
Seidel, Martin Bayer and Phillip Promesberger (Gephex).


We first aimed at the realisation of a comprehensive specification for
dynamically  loaded  plugins  named  [LiViDO], which  then  spawned  two
implementations:  one  being  Frei0r,  a  minimalistic  implementation
contributed  by the  Gephex  team and  the  other one  being the  [WEED]
implementation by LiVES developer Salsaman, sporting more features for
GUI integration and scriptability.


Within the span of a  few years, the minimalistic approach of *frei0r*
has been widely adopted among more applications and became a *de-facto
standard*.   Maintenance and further  refinements were  contributed by
Carlo Prelz  (MøB/BEK), Richard Spindler  (Open Movie Editor)  and Dan
Dennedy (MLT/KDEnLive), while Debian/Ubuntu packaging and build system
standardization  were taken  care  of by  dyne.org developers  Filippo
Giunchedi and Luca Bigliardi.

---------------------------------------------------------------------

[Piksel]: http://www.piksel.no
[LiViDO]: http://livido.dyne.org/codedoc/
[WEED]: http://lives.cvs.sourceforge.net/lives/lives/weed-docs/