docs/random/autoplug1

   1 COMPLETELY OUTDATED
   2 -------------------
   3
   4
   5 A little explanation of the first autoplugger in GStreamer:
   6
   7 Autoplugging is implemented in the following places:
   8
   9  gstpipeline.c : construction of the pipeline
  10  gstautoplug.c : selection of the elementfactories needed for autoplugging
  11
  12 1) pipeline setup
  13 -----------------
  14
  15 before any autoplugging will take place, a new GstPipeline has to be created.
  16 The autoplugger needs to have a src element and one or more sink elements. the
  17 autoplugger will try to find the elements needed to connect the src element
  18 to the sinks.
  19
  20 using:
  21
  22   gst_pipeline_add_src (GstPipeline *pipeline, GstElement *element);
  23
  24 a source element is added to the pipeline. only one src element can be added
  25 for now.
  26
  27 using:
  28
  29   gst_pipeline_add_sink (GstPipeline *pipeline, GstElement *element);
  30
  31 a sink element can be added to the pipeline.
  32
  33 2) starting autoplug
  34 --------------------
  35
  36 when the pipeline has been set up as above, you will call
  37
  38   gst_pipeline_autoplug (GstPipeline *pipeline);
  39
  40 to start the autoplugger. this will be done in four phases
  41
  42 ex. we are going to autoplug an mpeg1 system stream.
  43
  44 2a) phase1: figure out the type (GstCaps) of the src element.
  45 -------------------------------------------------------------
  46
  47 the gsttypefind element is connected to the "src" pad of the source
  48 element. gst_bin_iterate is called in a loop until gsttypefind
  49 signals "have_type". the gst_bin_iterate is stopped and the GstCaps
  50 is retrieved from the gsttypefind element.
  51
  52 gsttypefind is disconnected from the src element and removed from the
  53 bin.
  54
  55 the GstCaps of the source element is called src_caps later on.
  56
  57 ex. all typefind functions are tried and the one in mpeg1types will
  58      return a GstCaps:
  59
  60         video/mpeg,
  61         "systemstream", GST_PROPS_BOOLEAN (TRUE),
  62         "mpegversion",  GST_PROPS_INT (1),
  63         NULL
  64
  65
  66 2b) phase2: create lists of factories.
  67 ---------------------------------------
  68
  69 for each sink:
  70 {
  71    sinkpad = take the first sinkpad of the sink (HACK)
  72    call
  73
  74    list[i] = gst_autoplug_caps (src_caps, sinkpad->caps);
  75
  76    I++;
  77 }
  78
  79 gst_autoplug_caps will figure out (based on the padtemplates)
  80 which elementfactories are needed to connect src_caps to sinkpad->caps
  81 and will return them in a list.
  82
  83 ex. we have two sinks with following caps:
  84
  85         video/raw                    audio/raw
  86         "...."                       "...."
  87
  88  gst_autoplug_caps will figure out that for the first sink the following
  89  elements are needed:
  90
  91    mpeg1parse, mp1videoparse, mpeg_play
  92
  93  for the second sink the following is needed:
  94
  95    mpeg1parse, mp3parse, mpg123
  96
  97  We now have two lists of elementfactories.
  98
  99 2c) phase3: collect common elements from the lists.
 100 ---------------------------------------------------
 101
 102 the rationale is that from the lists we have created in phase2, there
 103 must be some element that is a splitter and that it has to come first (HACK)
 104 We try to find that element by comparing the lists until an element differs.
 105
 106 we add the common elements to the bin and run gst_pipeline_pads_autoplug. this
 107 function will loop over the pads of the previous element and the one we
 108 just added, and tries to connect src to sink if possible.
 109
 110 If a connection between the two elements could not be made, a signal "new_pad"
 111 is connected to the element so that pad connection can occur later on when
 112 the pad is actually created.
 113
 114 ex. when we compare the two lists we see that we have common element: mpeg1parse.
 115
 116  we add this element to the bin and try to connect it to the previous element in
 117  the bin, the disksrc.
 118
 119  we see that the src pad of the disksrc and the sinkpad of the mpeg1parse element
 120  can be connected because they are compatible. We have a pipeline like:
 121
 122   ---------)         (--------
 123    disksrc !         ! mpeg1parse
 124            src --- sink
 125   ---------)         (--------
 126
 127
 128 2d) phase4: add remaining elements
 129 ----------------------------------
 130
 131 now we loop over all the list and try to add the remaining elements
 132
 133 (HACK) we always use a new thread for the elements when there is a common
 134 element found.
 135
 136 if a new thread is needed (either bacuase the previous element is a common
 137 element or the object flag of the next element is set to GST_SUGGEST_THREAD)
 138 we add a queue to the bin and we add a new thread. We add the elements to
 139 the bin and connect them using gst_pipeline_pads_autoplug.
 140
 141 If we add a queue, we have to copy the caps of the sink element of the queue
 142 to the src pad of the queue (else they won't connect)
 143
 144 we finally arrive at the sink element and we're done.
 145
 146 ex.
 147
 148      we have just found our mpeg1parse common element, so we start a thread.
 149      We add a queue to the bin and a new thread, we add the elements
 150      mp1videoparse and mpeg_play to the thread. We arrive at the videosink, we
 151      see that the SUGGEST_THREAD flag is set, we add a queue and a thread and
 152      add the videosink in the thread.
 153
 154      the same procedure happens for the audio part. We are now left with the
 155      following pipeline:
 156
 157      We will also have set a signal "new_pad" on the mpeg1parse element bacause
 158      the element mp1videoparse could not be connected to the element just yet.
 159
 160                                                  (------------------------------------)         (----------
 161                                                  !thread                              !         ! thread
 162                                                  ! (-------------)       (---------)  !         ! (---------)
 163                                                  ! !mp1videoparse!       !mpeg_play!  !         ! !videosink!
 164                                    videoqueue--sink             src -- sink      src -- queue --- sink     !
 165   ---------)         (-----------)               ! (-------------)       (---------)  !         ! (---------)
 166    disksrc !         ! mpeg1parse!               (------------------------------------)         (-------------
 167            src --- sink          !
 168   ---------)         (-----------)
 169                                       queue-----  same for audio
 170
 171
 172    then we play, create_plan happens, data is flowing and the "new_pad" signal is called
 173    from mpeg1parse, gst_pipeline_pad_autoplug is called and the connection between
 174    mpeg1parse and the videoqueue is made. same for audio.
 175
 176    voila. smame procedure for mp3/vorbis/avi/qt/mpeg2 etc...
 177
 178
 179 Problems:
 180 ---------
 181
 182 this is obviously a very naive solution. the creation of the elements actually happens
 183 beforehand. MPEG2, for one, fails bacause there are multiple possibilities to go
 184 from the mpeg demuxer to audio/raw (ac3, mp3)
 185
 186 Also any intermedia elements like mixers (subtitles) are not possible because we
 187 assume that after the common elements, the streams to not converge anymore.
 188
 189
 190
 191
 192
 193
 194
 195
 196
 197
 198
 199
 200
 201
 202
 203
 204
 205
 206