gst/playback/: Updated README, added more comments for fixmes etc..

Original commit message from CVS:
* gst/playback/README:
* gst/playback/gstdecodebin.c: (close_pad_link), (try_to_link_1):
* gst/playback/gstplaybasebin.c: (probe_triggered),
(gst_play_base_bin_change_state):
Updated README, added more comments for fixmes etc..

ChangeLog

@@ -1,3 +1,11 @@
+2004-11-08  Wim Taymans  <wim@fluendo.com>
+
+	* gst/playback/README:
+	* gst/playback/gstdecodebin.c: (close_pad_link), (try_to_link_1):
+	* gst/playback/gstplaybasebin.c: (probe_triggered),
+	(gst_play_base_bin_change_state):
+	Updated README, added more comments for fixmes etc..
+
 2004-11-08  Wim Taymans  <wim@fluendo.com>
 
 	* gst/playback/gstplaybasebin.c: (gst_play_base_bin_add_element):

gst/playback/README

@@ -5,10 +5,11 @@ decoderbin:
   from the registry until a raw format is obtained. It will then create a new ghostpad
   on itself to signal the app of the new pad. 
 
+  Decodebin will also remove pads when they are removed from the stream.
+
   TODO
    - reuse of decoderbin, cleanup in READY state
    - threading after demuxing?
-   - error handling
 
 baseplaybin:
 
@@ -19,6 +20,15 @@ baseplaybin:
   assumed that by that time all the streams will be found so that when leaving the
   PAUSED state, one can query the number of streams in the media file with the given
   uri.
+
+  Playbasebin internally groups related streams together in a GstPlayBaseGroup. This
+  is particulary important for chained oggs. Initially, a new group is created in 
+  the 'building' state. All new streams will be added to the building group until
+  no-more-pads is signaled or one of the preroll queues overflows. When this happens,
+  the group is commited to a list of groups ready for playback. PlaybaseBin will then
+  attach a padprobe to each stream to figure out when it finished. It will remove
+  the current group and install the next playable group, then.
+
   Before going to the PLAYING state, it is possible to connect a custom element to
   each of the streams. To do that, you have to add the element to the bin and then
   connect the pad(s) from the stream(s). You do not have to add the elements in
@@ -26,22 +36,24 @@ baseplaybin:
   threads inside the elements, of course.
   The bin tries to be smart and doesn't add a queue when there is only one possible 
   stream.
+
   
   TODO
   - reuse, cleanup in ready state
-  - debugging
   - when the first pad is closed, it's possible that another dynamic element is
     added somewhere so that we need a queue for the first pad as well.
-  - error handling
+  - make sure we get EOS on all pads in a group before commiting the next group.
 
 playbin:
   
    Extends baseplaybin, sets up default audiosink and videosink for first audio/video
    stream detected. implements seeking and querying on the configured sinks.
 
-   TODO
-   - visualisation
-   - reuse, refcounting, cleanup in READY state
-   - debugging
-   - error handling
+   It also waits for new notifications from playbasebin about any new groups that are
+   becomming active. It then disconnects the sinks and reconnects them to the new
+   pads in the group.
+
+   TODO
+   - reuse, refcounting, cleanup in READY state
+   - be smarter about replugging the sinks instead of removing them and readding them.
 

gst/playback/gstdecodebin.c

@@ -404,7 +404,9 @@ close_pad_link (GstElement * element, GstPad * pad, GstCaps * caps,
 
   GST_LOG_OBJECT (element, "trying to close %" GST_PTR_FORMAT, caps);
 
-  /* FIXME, iterate over more structures? */
+  /* FIXME, iterate over more structures? I guess it is possible that
+   * this pad has some encoded and some raw pads. This code will fail
+   * then... */
   structure = gst_caps_get_structure (caps, 0);
   mimetype = gst_structure_get_name (structure);
 
@@ -501,7 +503,10 @@ try_to_link_1 (GstDecodeBin * decode_bin, GstPad * pad, GList * factories)
       /* check if we can use threads */
       if (decode_bin->threaded) {
         if (strstr (klass, "Demux") != NULL) {
-          /* FIXME, do something with threads here */
+          /* FIXME, do something with threads here. Not sure that it 
+           * really matters here but in general it is better to preroll
+           * on encoded data from the muxer than on raw encoded streams
+           * because that would consume less memory. */
         }
       }
       /* make sure we catch unlink signals */

gst/playback/gstplaybasebin.c

@@ -484,6 +484,11 @@ probe_triggered (GstProbe * probe, GstData ** data, gpointer user_data)
 
       GST_DEBUG ("probe got EOS in group %p", group);
 
+      /* FIXME there might be more streams in this group that need
+       * to go to EOS before we can switch to the next group. So
+       * here we should mark the stream as EOSed and decide if all
+       * streams have EOSed before continuing. */
+
       /* see if we have some more groups left to play */
       queued = g_list_length (play_base_bin->queued_groups);
       if (queued > 1) {
@@ -992,7 +997,9 @@ gst_play_base_bin_change_state (GstElement * element)
 
         group = get_active_group (play_base_bin);
 
-        /* FIXME for now... */
+        /* FIXME for now...  The group can be NULL if the setup_source
+         * function somehow returned TRUE but did not commit the group. 
+         * Actually I don't think this can happen but need to recheck. */
         g_assert (group);
 
         /* check if we found any supported stream... if not, then