Looks useful for cheese to switch effects.

(Note: I didn't look at the code yet)

From some discussions about this earlier I think one important thing is still missing here. If you dynamically switch elements (especially sources and sinks) you have to tell the new elements the currently configured segment, the current running time and other things.

But that's true for all elements.. Shouldn't gst_bin_add() or something do it ? Also, if you push a newsegment to a filter element and then it reaches the sink, the sink will be confused.

Yes, you have to catch the event after the new element. I don't think it's gst_bin_adds() job, it has to be done one level higher where you know which elements you're going to replace and how they would be linked.

Currently, this was mostly used (so far) with the fsu{video|audio}{src|sink} elements from farsight-utils. They let you change the source/sink, the device, or set a custom pipeline dynamically, it will automatically change it internally, and it shouldn't have an issue with new segments. For now it's a dirty hack that just sends a flush-stop (that will make elements in the pipeline reset their previous segment setting) before any new-segment is sent in the pipeline. But it's in the TODO to make it more intelligent and less hacky.

How would you suggest telling the elements in the filter manager about the changed source/sink ? The filters (and filter manager) have a _handle_message API method, so maybe sending some kind of message through that ?

Just added a few small commits, added a GstBinFilter to which you can give a 'gst-launch' string description for adding custom pipelines in the middle of filter managers, and also fixed a small typo fix in the gtkdoc.
changes pushed and gtk-doc updated on my page.

Just some high-level comments from looking at the docs

- Why do you have all these volume/audioconvert/etc filters? Isn't this essentially the same as a GstBinFilter with the corresponding description? I'm not sure that these are really needed... of course they don't hurt either :)
- GstResolutionFilter should also have something to specify the PAR/DAR or to force keeping the DAR and things like that. And the name could be improved I guess... but I don't know a good name
- gst_filter_lock/unlock: Everywhere else in GStreamer we use macros for these things, e.g. GST_OBJECT_LOCK(). Would be nice to change that for consistency
- GstFilter::handle_message(): please add to the documentation *which* messages will be passed to this. Is this only for gst_filter_manager_handle_message()? If it is, what exactly is the use case for this? An example in the documentation would help I guess :)
- It might make sense to use GstObject as base class for GstFilter and GstFilterManager. This way you will get a) the mutex, b) parent/childs handling, c) floating refs
- You should add a note to the documentation that dynamic pipeline changes are not handled in all cases yet
- gst_filter_add_standard_element() is badly named. Elements with one pad named "sink" and one pad named "src" are not really "standard elements". More something like filter elements, one-to-one elements, etc.
- Is gst_filter_revert_bin() possible on a filter added by gst_filter_add_element_by_name()? If not, would such a feature be possible?
- GstMultiFilterManager says that you must not do anything with it other than listening to signals. Is this really true? You can't call any of the GstFilterManager interface functions?

(In reply to comment #5)
> How would you suggest telling the elements in the filter manager about the
> changed source/sink ? The filters (and filter manager) have a _handle_message
> API method, so maybe sending some kind of message through that ?

I think the elements in the filter/filter manager shouldn't even notice that the source/sink was replaced, other than maybe seeing a newsegment event. But now that I looked at the docs of GstFilter it seems that this is only meant for elements between the source and sink and not for the sinks/sources themselves. In that case ignore it for now :)

What remains is that you need to tell newly added elements to a running pipeline about the current running time, otherwise you're going to break QoS and synchronization in some cases.

(In reply to comment #7)
> Just some high-level comments from looking at the docs
> 
> - Why do you have all these volume/audioconvert/etc filters? Isn't this
> essentially the same as a GstBinFilter with the corresponding description? I'm
> not sure that these are really needed... of course they don't hurt either :)
There are a few reasons :
1 - With the filters, you should forget about the elements, the idea is to simplify it by providing a small set of specific filters providing specific 'features', instead of a huge list of elements that may or may not be installed, etc.. It should be 'a filter for everything' and GstBinFilter is only there for 'super advanced users' and should not really be used by anyone
2 - Most people see 'audioconvert' element and they put that in their pipeline to convert their audio format.. then later on, they find bugs and realize they needed to add an audioresample element too.. then they still get some bugs and they don't understand why, only a few people know (and understand why) that you actually need "audioconvert ! audioresample ! audioconvert" to properly convert your audio format. The idea of the filters is to make everything easy and these kind of low-level specific things are hidden by the 'audioconverter' filter, you don't need to be a gstreamer expert in order to properly convert your audio formats anymore
3 - In the case of the volume filter, you have one filter with one volume and you can apply it everywhere, if in the UI, the user selects a volume for that app, then you don't need to keep a list of volume elements, and set the right volume in each one of them, the volume filter does that for you. In the case of VoIP, the UI user only sees one 'volume slider', so the developer should only set the value on only one 'volume filter', and not on every src-pad (from farsight for example) per stream-ssrc-payload_type...
4 - GstBinFilter was added 3 weeks ago, but all these filters were creates months ago. But still, I don't think GstBinFilter should be used for things like that.
5- having them doesn't hurt :)

> - GstResolutionFilter should also have something to specify the PAR/DAR or to
> force keeping the DAR and things like that. And the name could be improved I
> guess... but I don't know a good name
That's a good point, The aspect ratio should be configurable, I'm not sure if it needs to be anything fancy, maybe just 'stretch/keep_aspect_ratio' is enough.
About the name, I don't know, maybe GstVideoSizeFilter ?

> - gst_filter_lock/unlock: Everywhere else in GStreamer we use macros for these
> things, e.g. GST_OBJECT_LOCK(). Would be nice to change that for consistency
Good point, I'll fix that.

> - GstFilter::handle_message(): please add to the documentation *which* messages
> will be passed to this. Is this only for gst_filter_manager_handle_message()?
> If it is, what exactly is the use case for this? An example in the
> documentation would help I guess :)

Well, the documentation says "Try to handle a message originally received on the GstBus to the filter." and really, it's *ANY* and *ALL* messages that goes through the bus.. the filter will return TRUE/FALSE depending on whether or not it recognizes the message. Most filters don't need it and will always return FALSE, others will look for a specific message (like the 'level' filter that takes 'level' messages and transforms them into gobject signals) but you can't know which message since it's filter-dependent.
If you use a GstFilterManager, then the gst_filter_manager_handle_message will call that function for you (for all the filters in the manager), but if you use the filter on its own without a filter manager, then you'd need to call that.
The examples/filters/test-level.c shows how it's used (through the filter manager) : http://git.collabora.co.uk/?p=user/kakaroto/gst-plugins-base.git;a=blob;f=tests/examples/filters/test-level.c;h=b600b68ee303e062e3cdb58371c3a441e9428557;hb=03fba0b1acd6cee1d9117100db4c05051c6d5e02#l47

Does that answer your question or did I misunderstand it ?

> - It might make sense to use GstObject as base class for GstFilter and
> GstFilterManager. This way you will get a) the mutex, b) parent/childs
> handling, c) floating refs
No, I didn't want to do that for multiple reasons, first of all, the purpose of all this is mainly : "Make it easy".
Gstreamer is scary to a lot of people who have never used it, so I wanted to keep this into the realm of what everybody knows by using GObject instead of GstObject. I absolutely do not want floating refs, although I completely agree that they are extremely useful and practical, I think that they add a certain level of complexity to the refcounting system that could easily scare/confuse people. Also there is no parent/child system here, a filter can be added to as many filter managers as you want, so it's more of a "contains" rather than "is a parent of". Finally, adding a mutex is easy, so it doesn't really warrant a move to GstObject.
For all these reasons, I prefer it to be GObject as a base rather than GstObject, I don't see any particularly important advantage in using GstObject
apart from the obvious "This is part of GStreamer so it has to be a GstObject" argument.
What do you think ?

p.s: by the way, GObject also has support for floating refs.

> - You should add a note to the documentation that dynamic pipeline changes are
> not handled in all cases yet
What do you mean? what cases aren't handled for dynamic pipeline changes? It's been a while so maybe it's just that my memory isn't fresh, but as far as I remember, there were no issues with dynamic pipeline changes and all cases were handled correctly.
The only thing I can see from this bug report's comments is about changing the source/sink elements, but wouldn't changing the source only affect the sink synchronization? the filters in between shouldn't really be affected since they only transform data and it's rare for a filter (non-src/non-sink element) to care/modify the timestamps ?
The only filter that has a sink in it is the Preview filter and that one uses sync=false so it shouldn't bother it either.


> - gst_filter_add_standard_element() is badly named. Elements with one pad named
> "sink" and one pad named "src" are not really "standard elements". More
> something like filter elements, one-to-one elements, etc.
hehe, well, all the elements that get added are basically filters with one-to-one pads, but since this is to be used internally for a filter, it doesn't really make sense to call it gst_filter_add_filter_element. I know there isn't really a 'standard' but it's become a 'kind of standard' for people to name their pads 'src' and 'sink'.. I'm sure if you see an element with a sink pad named "my_sink_pad", you would frown during code review and tell the committer to name it correctly.
If you have a better suggestion for the function name, let me know though, I don't mind changing it.


> - Is gst_filter_revert_bin() possible on a filter added by
> gst_filter_add_element_by_name()? If not, would such a feature be possible?
Good point.. I just checked the code and noticed that the gst_filter_revert_standard_element and gst_filter_revert_bin use the exact same code (apart from the gst_filter_revert_standard_element also unreffing/removing from the 'elements' GList), so I should probably make the revert_bin just call revert_standard_element with the argument GList *elements=NULL.
About the 'add_element_by_name', it's mostly used to specify an element that uses pads named differently from 'src/sink', but I guess it would take 5 minutes to write a 'revert' that takes src_pad_name and sink_pad_name arguments instead of hardcoding "src" and "sink.
Then I could just make the gst_filter_revert_standard_element use that directly giving it "src" and "sink" arguments for the names.


> - GstMultiFilterManager says that you must not do anything with it other than
> listening to signals. Is this really true? You can't call any of the
> GstFilterManager interface functions?
Euhh, no, I think you were mislead by the big green 'Note' in the gtk-doc. The GstMultiFilterManager can be used normally using the same GstFilterManager interface functions.. what you can't play with is the GstSingleFilterManager that is used internally by the MultiFM. The "you must not do anything with it other than listening to signals" is actually a note on the 'applied' signal of the Multi filter manager.
Whenever you 'apply' a MultiFM to a bin+pad, it will create a new SingleFM internally, and append all the filters to it and then 'apply' that SingleFM on that bin+pad. It will make sure all internal SingleFM are synchronized, so if you move/replace/add filters to the MultiFM, all the internal SingleFMs get modified the same way, that's why if you start playing with the internal SingleFM, it will screw it all up.
The SingleFM is accessible because when you apply the MultiFM it will send a 'applied' signal giving you the internal SingleFM it created for this bin+pad :
http://people.collabora.co.uk/~kakaroto/gpb-docs/GstMultiFilterManager.html#GstMultiFilterManager-applied
If for example, you later want to add a new filter to your MultiFM, it will get added in all the internal SingleFMs, and maybe it will fail to apply in one of them, that's why you may want to know about this by listening to signals on the internal SingleFMs.




(In reply to comment #8)
> (In reply to comment #5)
> > How would you suggest telling the elements in the filter manager about the
> > changed source/sink ? The filters (and filter manager) have a _handle_message
> > API method, so maybe sending some kind of message through that ?
> 
> I think the elements in the filter/filter manager shouldn't even notice that
> the source/sink was replaced, other than maybe seeing a newsegment event. But
> now that I looked at the docs of GstFilter it seems that this is only meant for
> elements between the source and sink and not for the sinks/sources themselves.
> In that case ignore it for now :)
> 
Yes, the filters are 'filters' in the gstreamer sense, one input = one output, so you can't really use a GstFilter as a source/sink (but a filter could have an internal src/sink like the Preview filter)

> What remains is that you need to tell newly added elements to a running
> pipeline about the current running time, otherwise you're going to break QoS
> and synchronization in some cases.

Humm, the whole timing/synchronization/segment/latency/QoS stuff in gstreamer is my weak point, I'm having a bit of a hard time getting my mind around it. I'm a bit clueless as to why this is needed, or how to do it properly, could you enlighten me?
If you have a solution that I can just apply, I can fix it, but figuring out what needs to be done is giving me a headache...

Thanks for taking the time to look at this :)

(In reply to comment #9)
> (In reply to comment #7)
> > Just some high-level comments from looking at the docs
> > 
> > - Why do you have all these volume/audioconvert/etc filters? Isn't this
> > essentially the same as a GstBinFilter with the corresponding description? I'm
> > not sure that these are really needed... of course they don't hurt either :)
> [...]
> 5- having them doesn't hurt :)

Ok, fine :)
 
> > - GstResolutionFilter should also have something to specify the PAR/DAR or to
> > force keeping the DAR and things like that. And the name could be improved I
> > guess... but I don't know a good name
> That's a good point, The aspect ratio should be configurable, I'm not sure if
> it needs to be anything fancy, maybe just 'stretch/keep_aspect_ratio' is
> enough.

Maybe just expose the add-black-borders property of videoscale and maybe four ints to give a PAR range

> About the name, I don't know, maybe GstVideoSizeFilter ?

Sounds better :)

> > - GstFilter::handle_message(): please add to the documentation *which* messages
> > will be passed to this. Is this only for gst_filter_manager_handle_message()?
> > If it is, what exactly is the use case for this? An example in the
> > documentation would help I guess :)
> 
> Well, the documentation says "Try to handle a message originally received on
> the GstBus to the filter." and really, it's *ANY* and *ALL* messages that goes
> through the bus.. the filter will return TRUE/FALSE depending on whether or not
> it recognizes the message. Most filters don't need it and will always return
> FALSE, others will look for a specific message (like the 'level' filter that
> takes 'level' messages and transforms them into gobject signals) but you can't
> [...]
>
> Does that answer your question or did I misunderstand it ?

No, makes sense. But maybe multiple filters want to get a single message?
 
> > - It might make sense to use GstObject as base class for GstFilter and
> > GstFilterManager. This way you will get a) the mutex, b) parent/childs
> > handling, c) floating refs
> No, I didn't want to do that for multiple reasons, first of all, the purpose of
> all this is mainly : "Make it easy".
> Gstreamer is scary to a lot of people who have never used it, so I wanted to
> keep this into the realm of what everybody knows by using GObject instead of
> GstObject. I absolutely do not want floating refs, although I completely agree
> that they are extremely useful and practical, I think that they add a certain
> level of complexity to the refcounting system that could easily scare/confuse
> people. Also there is no parent/child system here, a filter can be added to as
> many filter managers as you want, so it's more of a "contains" rather than "is
> a parent of". Finally, adding a mutex is easy, so it doesn't really warrant a
> move to GstObject.
> For all these reasons, I prefer it to be GObject as a base rather than
> GstObject, I don't see any particularly important advantage in using GstObject
> apart from the obvious "This is part of GStreamer so it has to be a GstObject"
> argument.
> What do you think ?
> 
> p.s: by the way, GObject also has support for floating refs.

Makes sense too, especially because it's not really a parent/child relationship here :)

> > - You should add a note to the documentation that dynamic pipeline changes are
> > not handled in all cases yet
> What do you mean? what cases aren't handled for dynamic pipeline changes? It's
> been a while so maybe it's just that my memory isn't fresh, but as far as I
> remember, there were no issues with dynamic pipeline changes and all cases were
> handled correctly.
> The only thing I can see from this bug report's comments is about changing the
> source/sink elements, but wouldn't changing the source only affect the sink
> synchronization? the filters in between shouldn't really be affected since they
> only transform data and it's rare for a filter (non-src/non-sink element) to
> care/modify the timestamps ?
> The only filter that has a sink in it is the Preview filter and that one uses
> sync=false so it shouldn't bother it either.

See at the end of the comment

> > - gst_filter_add_standard_element() is badly named. Elements with one pad named
> > "sink" and one pad named "src" are not really "standard elements". More
> > something like filter elements, one-to-one elements, etc.
> hehe, well, all the elements that get added are basically filters with
> one-to-one pads, but since this is to be used internally for a filter, it
> doesn't really make sense to call it gst_filter_add_filter_element. I know
> there isn't really a 'standard' but it's become a 'kind of standard' for people
> to name their pads 'src' and 'sink'.. I'm sure if you see an element with a
> sink pad named "my_sink_pad", you would frown during code review and tell the
> committer to name it correctly.
> If you have a better suggestion for the function name, let me know though, I
> don't mind changing it.

Unfortunately I don't know a better name, sorry :) Someone else?
  
> (In reply to comment #8)
> > (In reply to comment #5)
> > > How would you suggest telling the elements in the filter manager about the
> > > changed source/sink ? The filters (and filter manager) have a _handle_message
> > > API method, so maybe sending some kind of message through that ?
> > 
> > I think the elements in the filter/filter manager shouldn't even notice that
> > the source/sink was replaced, other than maybe seeing a newsegment event. But
> > now that I looked at the docs of GstFilter it seems that this is only meant for
> > elements between the source and sink and not for the sinks/sources themselves.
> > In that case ignore it for now :)
> > 
> Yes, the filters are 'filters' in the gstreamer sense, one input = one output,
> so you can't really use a GstFilter as a source/sink (but a filter could have
> an internal src/sink like the Preview filter)
> 
> > What remains is that you need to tell newly added elements to a running
> > pipeline about the current running time, otherwise you're going to break QoS
> > and synchronization in some cases.
> 
> Humm, the whole timing/synchronization/segment/latency/QoS stuff in gstreamer
> is my weak point, I'm having a bit of a hard time getting my mind around it.
> I'm a bit clueless as to why this is needed, or how to do it properly, could
> you enlighten me?
> If you have a solution that I can just apply, I can fix it, but figuring out
> what needs to be done is giving me a headache...

Essentially you need to install buffer and event probes on sinkpad, catch newsegment events and buffer timestamps/durations. And then you'll be able to calculate the current running time when changing elements during playback. And to tell a new element about the old running time you have to send a newsegment event to it before anything else happens (and important: drop it on the other side of the element).

(In reply to comment #10)
> (In reply to comment #9)
> > (In reply to comment #7)
> > > - gst_filter_add_standard_element() is badly named. Elements with one pad named
> > > "sink" and one pad named "src" are not really "standard elements". More
> > > something like filter elements, one-to-one elements, etc.
> > hehe, well, all the elements that get added are basically filters with
> > one-to-one pads, but since this is to be used internally for a filter, it
> > doesn't really make sense to call it gst_filter_add_filter_element. I know
> > there isn't really a 'standard' but it's become a 'kind of standard' for people
> > to name their pads 'src' and 'sink'.. I'm sure if you see an element with a
> > sink pad named "my_sink_pad", you would frown during code review and tell the
> > committer to name it correctly.
> > If you have a better suggestion for the function name, let me know though, I
> > don't mind changing it.
> 
> Unfortunately I don't know a better name, sorry :) Someone else?

why not just gst_filter_add_element () or gst_filter_add_element_default (). Imho describing the difference in the API docs is enough.

It would be nice to have a small example in the section docs for the helpers. The purpose of the _revert_ functions is not totally clear to me (or the naming is a bit unlucky).

(In reply to comment #10)
> > > - GstResolutionFilter should also have something to specify the PAR/DAR or to
> > > force keeping the DAR and things like that. And the name could be improved I
> > > guess... but I don't know a good name
> > That's a good point, The aspect ratio should be configurable, I'm not sure if
> > it needs to be anything fancy, maybe just 'stretch/keep_aspect_ratio' is
> > enough.
> 
> Maybe just expose the add-black-borders property of videoscale and maybe four
> ints to give a PAR range
Humm... I tried the add-borders property, it doesn't work when using v4l2src because it seems the pixel-aspect-ratio is set to 1/2147483647 from the output of v4l2src :
DEBUG             videoscale gstvideoscale.c:437:gst_video_scale_set_caps:<videoscale0> from=1280x960 (par=1/2147483647 dar=-1/-1), size 2457600 -> to=270x821 (par=1/1 dar=270/821 borders=0:0), size 443340

I made it work by adding a capsfilter before the videoscale forcing the pixel-aspect-ratio to 3/4 but I don't think I should hardcode the aspect ratio in the filter.
Any suggestions? Maybe videoscale should fallback to an aspect ratio of height/width when it can't compute the DAR ?

> 
> > About the name, I don't know, maybe GstVideoSizeFilter ?
> 
> Sounds better :)
ok cool, I'll change it to VideoSizeFilter then :)

> 
> > > - GstFilter::handle_message(): please add to the documentation *which* messages
> > > will be passed to this. Is this only for gst_filter_manager_handle_message()?
> > > If it is, what exactly is the use case for this? An example in the
> > > documentation would help I guess :)
> > 
> > Well, the documentation says "Try to handle a message originally received on
> > the GstBus to the filter." and really, it's *ANY* and *ALL* messages that goes
> > through the bus.. the filter will return TRUE/FALSE depending on whether or not
> > it recognizes the message. Most filters don't need it and will always return
> > FALSE, others will look for a specific message (like the 'level' filter that
> > takes 'level' messages and transforms them into gobject signals) but you can't
> > [...]
> >
> > Does that answer your question or did I misunderstand it ?
> 
> No, makes sense. But maybe multiple filters want to get a single message?
Usually filters will only handle messages coming from the elements they added themselves, so I don't think two filters would want to handle the same message.. if a filter handles a message it doesn't "own", then it shouldn't return TRUE, since the return value isn't whether or not it handled it, it's whether or not it should be dropped.

> 
> > (In reply to comment #8)
> > 
> > Humm, the whole timing/synchronization/segment/latency/QoS stuff in gstreamer
> > is my weak point, I'm having a bit of a hard time getting my mind around it.
> > I'm a bit clueless as to why this is needed, or how to do it properly, could
> > you enlighten me?
> > If you have a solution that I can just apply, I can fix it, but figuring out
> > what needs to be done is giving me a headache...
> 
> Essentially you need to install buffer and event probes on sinkpad, catch
> newsegment events and buffer timestamps/durations. And then you'll be able to
> calculate the current running time when changing elements during playback. And
> to tell a new element about the old running time you have to send a newsegment
> event to it before anything else happens (and important: drop it on the other
> side of the element).

ok, so keep track of the new segments with the running time, then inject it when applying new filters, then drop it at the src side of the filter. I'll try to do that.


(In reply to comment #11)
> (In reply to comment #10)
> > 
> > Unfortunately I don't know a better name, sorry :) Someone else?
> 
> why not just gst_filter_add_element () or gst_filter_add_element_default ().
> Imho describing the difference in the API docs is enough.
> 
gst_filter_add_element_default makes more sense, but somehow, I don't feel like it's good enough.. 
Maybe I could change the way we do it, and do the invert... make add_element_by_name use "src"/"sink" and have a add_element_by_name_custom_pads (or whatever better name) for the one where you specify the pad names?

> It would be nice to have a small example in the section docs for the helpers.
> The purpose of the _revert_ functions is not totally clear to me (or the naming
> is a bit unlucky).

yes, the gtk-doc definitely needs a more 'gstreamer documentation quality' to it, as in, more text, a long descriptive/narrative documentation with examples.
The "revert" is the opposite of 'apply', it reverts the filter application from a bin+pad. I think Olivier and I spent some time trying to find the right name for this, and revert was the best we could find.

I've now committed fixes to some of the things discussed here. I've also rebased on the latest origin/master.

Here are the main issues raised, with their resolution :

> - GstResolutionFilter should also have something to specify the PAR/DAR or to
> force keeping the DAR and things like that. And the name could be improved I
> guess... but I don't know a good name
I've renamed the filter int GstVideoSizeFilter but see comment #12 with regards to why I still couldn't add a ratio option

> - gst_filter_lock/unlock: Everywhere else in GStreamer we use macros for these
> things, e.g. GST_OBJECT_LOCK(). Would be nice to change that for consistency
I've replaced gst_filter_lock/unlock with GST_FILTER_LOCK/TRYLOCK/UNLOCK/GET_LOCK macros and made the mutex public.
However, I'm still using g_mutex_lock directly without any macros *inside* the filter managers's code to lock/unlock a private mutex inside the class, that's fine, right ?


> - gst_filter_add_standard_element() is badly named. Elements with one pad named
> "sink" and one pad named "src" are not really "standard elements". More
> something like filter elements, one-to-one elements, etc.
I've revamped that API entirely, I used the '_default' for the apis that use "src/sink" for pad names, I also made it more consistent, I noticed that there was an add_element that returned a GstElement and another variant that returned a GstPad, so I changed the API to have add_element_* return GstElement, apply_element_* return the GstPad, and revert_element_* return the GstPad.

> - Is gst_filter_revert_bin() possible on a filter added by
> gst_filter_add_element_by_name()? If not, would such a feature be possible?
I removed gst_filter_revert_bin, and made a gst_filter_revert_element which takes a pad name and gst_filter_revert_element_default that would work on a bin or on an element added by gst_filter_add_element_by_name

> - It would be nice to have a small example in the section docs for the helpers.
> The purpose of the _revert_ functions is not totally clear to me (or the naming
> is a bit unlucky).

This is one of the big missing points.. I noticed many comments about the documentation that needs to be clearer or more fleshed out, I haven't done that yet, as it takes time to properly write documentation and I'm hoping someone else might do it :p 
Let's concentrate on the API, and on the code review first, then I'll make sure the documentation as on the same level (or close) to the other gstreamer docs.

Thanks.

Following discussions at the GStreamer Conference, we have come to the conclusion that the GStreamer team does not want to integrate GstFilters into gst-plugins-base. I have then decided to release it as a standalone project.
For this reason, I am now closing this bug as WONTFIX.

The 0.1 version has been released and it is available from the new website: 
http://www.freedesktop.org/wiki/Software/GstFilters

Thanks for the comments I've received.