docs/random/wtay/autoplug2

Autoplugger V2
==============

The current autoplugger as described in autoplug1 has some
serious shortcommings:

 - it is embedded in GstPipeline and cannot be used with a 
   generic interface. A lot of complexity is inside the 
   pipeline, more specifically the creation of threads and
   subbins and the pad connections.
 - it is not (easily) pluggable.

 

1) definition
-------------

We want to define a plugable framework for autoplugging this 
includes: 

  - autoplugging algorithms can be added and removed at run time.
  - autoplugging algorithms can be defined by plugins.

The autoplugger is build to handle simple media playback but
could also be used to create more complex pipelines.

The main focus will be on creating an element (can be a bin)
that has *one* input pad and *one or more* output pads.

It must be possible for a user app to insert its own elements in
the autogenerated element.

The autoplugger will be an interface to the low level plugin
system based on the functional requirements of the user app. 
the app will for example request an object that can convert
media type X to media type Y, the user app is not interested in 
any intermediate steps to accomplish this conversion.


2) the API
----------

The API for the user apps should be no more then this:

  GstElement* gst_autoplug_caps_list (GstAutoplug *autoplug, 
                                      GList *incaps, 
			              GList *outcaps, ...);

  autoplug is a reference to the autoplug implementation
  incaps is a GList of GstCaps* for the source pad, the last set
  of arguments is a va_list of destination caps lists.

A handle to the autoplugger implementation can be obtained 
with

  GList* gst_autoplugfactory_get_list (void);
  
which will return a GList* of autopluggers.

  GstAutoplug* gst_autoplugfactory_make ("name");
  
or

  GstAutoplug* gst_autoplugfactory_create (GstAutoplugFactory *autoplug);

is used to get an autoplugger.


3) the plugins API
------------------

plugins can add their own autoplugger implementation by
subclassing an abstract autoplugger class and implementing/
overriding various methods.

the autoplugger can be registered with:

  gst_plugin_add_autoplugger (GstPlugin *plugin,
                              GstAutoplugFactory *autoplug);

This will allow us to only load the autoplugger when needed.



4) implementation
-----------------

We will implement two autopluggers:

 - a static autoplugger. This autoplugger recursively adds
   elements to the target element until all of the possible
   pads are connected to something. The static autoplugger
   only operates on padtemplates and ALWAYS pads. The pipeline
   is not started before all elements are connected, hence 
   the 'static' autoplugger. This autoplugger will be a rework
   of the current autoplugger.

 - a dynamic autoplugger. This autoplugger configures the 
   pipeline at runtime based on the pad capabilities when they
   become available. this allows for more fine grained 
   autoplugging than can be achieved with the static one because
   it can be based on the actual media stream you are handling.

the autopluggers will be implemented in their separate plugins, 
outside of the core libraries and are therefore optional.


5) the autoplugger object
-------------------------

the autoplugger object will be an abstract class with the following
properties:

 - name, description, more text to identify the autoplugger.

 - a class method autoplug_caps_list that has to be implemented by
   the real autoplugger.

optionally, the core autoplugger code can provide convenience 
functions to implement custom autopluggers. The shortest path
algorithm with pluggable weighting and list functions come to 
mind.

signals will be added to the autoplugger so that user apps can
modify the constructed pipeline by adding extra objects. 
A possible use case would be to let gstmediaplay perform an 
autoplug on the media stream and insert a custom sound/video
effect in the pipeline when an appropriate element is created.

the "new_object" signal will be fired by the autoplugger whenever
a new object has been created. This signal can be caught by the
user app to perform an introspection on the newly created object.