docs/random/wtay/autoplug2

   1 Autoplugger V2
   2 ==============
   3
   4 The current autoplugger as described in autoplug1 has some
   5 serious shortcomings:
   6
   7  - it is embedded in GstPipeline and cannot be used with a
   8    generic interface. A lot of complexity is inside the
   9    pipeline, more specifically the creation of threads and
  10    subbins and the pad connections.
  11  - it is not (easily) pluggable.
  12
  13
  14
  15 1) definition
  16 -------------
  17
  18 We want to define a pluggable framework for autoplugging this
  19 includes:
  20
  21   - autoplugging algorithms can be added and removed at run time.
  22   - autoplugging algorithms can be defined by plugins.
  23
  24 The autoplugger is build to handle simple media playback but
  25 could also be used to create more complex pipelines.
  26
  27 The main focus will be on creating an element (can be a bin)
  28 that has *one* input pad and *one or more* output pads.
  29
  30 It must be possible for a user app to insert its own elements in
  31 the autogenerated element.
  32
  33 The autoplugger will be an interface to the low level plugin
  34 system based on the functional requirements of the user app.
  35 the app will for example request an object that can convert
  36 media type X to media type Y, the user app is not interested in
  37 any intermediate steps to accomplish this conversion.
  38
  39
  40 2) the API
  41 ----------
  42
  43 The API for the user apps should be no more then this:
  44
  45   GstElement* gst_autoplug_caps_list (GstAutoplug *autoplug,
  46                                       GList *incaps,
  47                                       GList *outcaps, ...);
  48
  49   autoplug is a reference to the autoplug implementation
  50   incaps is a GList of GstCaps* for the source pad, the last set
  51   of arguments is a va_list of destination caps lists.
  52
  53 A handle to the autoplugger implementation can be obtained
  54 with
  55
  56   GList* gst_autoplugfactory_get_list (void);
  57
  58 which will return a GList* of autopluggers.
  59
  60   GstAutoplug* gst_autoplugfactory_make ("name");
  61
  62 or
  63
  64   GstAutoplug* gst_autoplugfactory_create (GstAutoplugFactory *autoplug);
  65
  66 is used to get an autoplugger.
  67
  68
  69 3) the plugins API
  70 ------------------
  71
  72 plugins can add their own autoplugger implementation by
  73 subclassing an abstract autoplugger class and implementing/
  74 overriding various methods.
  75
  76 the autoplugger can be registered with:
  77
  78   gst_plugin_add_autoplugger (GstPlugin *plugin,
  79                               GstAutoplugFactory *autoplug);
  80
  81 This will allow us to only load the autoplugger when needed.
  82
  83
  84
  85 4) implementation
  86 -----------------
  87
  88 We will implement two autopluggers:
  89
  90  - a static autoplugger. This autoplugger recursively adds
  91    elements to the target element until all of the possible
  92    pads are connected to something. The static autoplugger
  93    only operates on padtemplates and ALWAYS pads. The pipeline
  94    is not started before all elements are connected, hence
  95    the 'static' autoplugger. This autoplugger will be a rework
  96    of the current autoplugger.
  97
  98  - a dynamic autoplugger. This autoplugger configures the
  99    pipeline at runtime based on the pad capabilities when they
 100    become available. this allows for more fine grained
 101    autoplugging than can be achieved with the static one because
 102    it can be based on the actual media stream you are handling.
 103
 104 the autopluggers will be implemented in their separate plugins,
 105 outside of the core libraries and are therefore optional.
 106
 107
 108 5) the autoplugger object
 109 -------------------------
 110
 111 the autoplugger object will be an abstract class with the following
 112 properties:
 113
 114  - name, description, more text to identify the autoplugger.
 115
 116  - a class method autoplug_caps_list that has to be implemented by
 117    the real autoplugger.
 118
 119 optionally, the core autoplugger code can provide convenience
 120 functions to implement custom autopluggers. The shortest path
 121 algorithm with pluggable weighting and list functions come to
 122 mind.
 123
 124 signals will be added to the autoplugger so that user apps can
 125 modify the constructed pipeline by adding extra objects.
 126 A possible use case would be to let gstmediaplay perform an
 127 autoplug on the media stream and insert a custom sound/video
 128 effect in the pipeline when an appropriate element is created.
 129
 130 the "new_object" signal will be fired by the autoplugger whenever
 131 a new object has been created. This signal can be caught by the
 132 user app to perform an introspection on the newly created object.
 133
 134
 135