documentation updates

1 files changed, 304 insertions, 15 deletions

diff --git a/README b/README
index 9baec9f..9b24d7a 100644
--- a/README
+++ b/README
@@ -1,24 +1,313 @@
-frei0r - a minimalistic plugin API for video effects
 
-It is a minimalistic plugin API for video sources and filters. The behaviour of
-the effects can be controlled from the host by simple parameters. The intent is
-to solve the recurring reimplementation or adaptation issue of standard effects.
+ ___________ ._________
+ \_ _____/______ ____ |__\ _ \_______
+ | __) \_ __ \_/ __ \| / /_\ \_ __ \
+ | \ | | \/\ ___/| \ \_/ \ | \/
+ \___ / |__| \___ >__|\_____ /__|
+ \/ \/ \/
 
-It is not meant as a generic API for all kinds of video applications.
+ Minimalistic plugin API for video effects v.1.2
 
-There is no support for the requirements of special application areas like non
-linear editors, hardware accelerated shader effects, and high precision video
-processing. These advanced issues are not even solved satisfactory for non cross
-application plugin apis and are still an evolving field.
+ by the Piksel Developers Union
 
-The frei0r API is not meant to be a competing standard to more ambitious
-efforts.
 
-http://www.piksel.org/frei0r/
+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 
+~~~~~~~~~~~~~
 
-Optional Dependencies:
-gavl, required for scale0tilt and vectorscope plugin, available at http://gmerlin.sourceforge.net/
 
-OpenCV, required for facedetect plugin, available at http://opencvlibrary.sourceforge.net/
+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 2006, 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/
+