Various documentation updates.

Original commit message from CVS:
* docs/design/part-events.txt:
* docs/design/part-gstbus.txt:
* docs/design/part-gstpipeline.txt:
* docs/design/part-messages.txt:
* docs/design/part-overview.txt:
* docs/design/part-segments.txt:
* gst/gstbin.c:
* gst/gstbuffer.c:
* gst/gstclock.c:
* gst/gstelement.c:
* gst/gstevent.c:
* gst/gstfilter.c:
* gst/gstiterator.c:
Various documentation updates.

ChangeLog

@@ -1,3 +1,20 @@
+2005-09-24  Wim Taymans  <wim@fluendo.com>
+
+	* docs/design/part-events.txt:
+	* docs/design/part-gstbus.txt:
+	* docs/design/part-gstpipeline.txt:
+	* docs/design/part-messages.txt:
+	* docs/design/part-overview.txt:
+	* docs/design/part-segments.txt:
+	* gst/gstbin.c:
+	* gst/gstbuffer.c:
+	* gst/gstclock.c:
+	* gst/gstelement.c:
+	* gst/gstevent.c:
+	* gst/gstfilter.c:
+	* gst/gstiterator.c:
+	Various documentation updates.
+
 2005-09-24  Thomas Vander Stichele  <thomas at apestaart dot org>
 
 	* gst/gstclock.h:

docs/design/part-events.txt

@@ -66,6 +66,10 @@ The downstream element should forward the EOS event to its downstream peer
 elements. This way the event will eventually reach the renderers which should
 then post an EOS message on the bus.
 
+An element might want to flush its internally queued data before forwarding
+the EOS event downstream. This flushing can be done in the same thread as
+the one handling the EOS event.
+
 For elements with multiple sink pads it might be possible to wait for EOS on
 all the pads before forwarding the event.
 

docs/design/part-gstbus.txt

@@ -10,7 +10,8 @@ different threads. This is important since the actual streaming of media
 is done in another thread than the application.
 
 The GstBus provides support for GSource based notifications. This makes it
-possible to handle the delivery in the glib mainloop.
+possible to handle the delivery in the glib mainloop. Different GSources 
+can be added to the same bin provided they listen to different message types.
 
 A message is posted on the bus with the gst_bus_post() method. With the
 gst_bus_peek() and _pop() methods one can look at or retrieve a previously
@@ -27,9 +28,11 @@ possible to react to a message in the same thread that posted the
 message on the bus. This should only be used if the application is able
 to deal with messages from different threads.
 
+If no messages are popped from the bus with either a GSource or gst_bus_pop(),
+they remain on the bus.
+
 When a pipeline or bin goes from READY into NULL state, it will set its bus
 to flushing, ie. the bus will drop all existing and new messages on the bus,
 This is necessary because bus messages hold references to the bin/pipeline
 or its elements, so there are circular references that need to be broken if
 one ever wants to be able to destroy a bin or pipeline properly.
-

docs/design/part-gstpipeline.txt

@@ -4,6 +4,8 @@ GstPipeline
 A GstPipeline is usually a toplevel bin an provides all of its 
 children with a clock.
 
+A GstPipeline also provides a toplevel GstBus (see part-gstbus.txt)
+
 The pipeline also calculates the stream time based on the selected
 clock (see part-clocks.txt).
 

docs/design/part-messages.txt

@@ -73,3 +73,14 @@ Message types
 
     An element posted an application specific message.
 
+  GST_MESSAGE_SEGMENT_START:
+
+    An element started playback of a new segment. This message is not forwarded
+    the the application but is used internally to scheduler SEGMENT_DONE messages.
+
+  GST_MESSAGE_SEGMENT_DONE:
+
+    An element or bin completed playback of a segment. This message is only posted
+    on the bus if a SEGMENT seek is performed on a pipeline.
+
+

docs/design/part-overview.txt

@@ -465,7 +465,7 @@ Pipeline seeking
      always stop because of step 1).
   3) perform the seek operation
   4) send a FLUSH done event to all downstream and upstream peer elements.
-  5) send DISCONT event to inform all elements of the new position and to complete
+  5) send NEWSEGMENT event to inform all elements of the new position and to complete
      the seek.
 
  In step 1) all dowstream elements have to return from any blocking operations
@@ -509,7 +509,7 @@ Pipeline seeking
 	      | 2) stop streaming
 	      | 3) perform seek
               --------------------------> 4) FLUSH done event
-              --------------------------> 5) DISCONT event
+              --------------------------> 5) NEWSEGMENT event
   
                                       | e) update stream time
 				      | f) PLAY pipeline

docs/design/part-segments.txt

@@ -0,0 +1,61 @@
+Segments
+--------
+
+A segment in GStreamer denotes a set of media samples that must be
+processed. A segment has a start time, a stop time and a processing
+rate. 
+
+A media stream has a start and a stop time. The start time is
+always 0 and the stop time is the duration (or -1 if unknown, for example
+a live stream). We call this the complete media stream.
+
+The segment of the complete media stream can be played by issuing a seek
+on the stream. The seek has a start time, a stop time and a processing rate.
+
+
+               complete stream
+  +------------------------------------------------+
+  0                                              duration
+         segment
+     |--------------------------|
+   start                       stop
+
+
+The playback of a segment starts with a source or demuxer element pushing a
+newsegment event containing the start time, stop time and rate of the segment.
+The purpose of this newsegment is to inform downstream elements of the 
+requested segment positions. Some elements might produce buffers that fall
+outside of the segment and that might therefore be discarded or clipped.
+
+  ex.
+
+    filesrc ! avidemux ! videodecoder ! videosink
+
+    When avidemux starts playback of the segment from second 1 to 5, it pushes
+    out a newsegment with 1 and 5 as start and stop times. 
+
+    The video decoder stores these values internally and forwards them to the
+    next downstream element (videosink, which also stores the values)
+
+    Since second 1 does not contain a keyframe, the avi demuxer starts sending
+    data from the previous keyframe which is at timestamp 0.
+
+    The video decoder decodes the keyframe but knows it should not push the 
+    video frame yet as it falls outside of the configured segment.
+
+    When the video decoder receives the frame with timestamp 1, it is able to
+    decode this frame as it received and decoded the data up to the previous 
+    keyframe. It then continues to decode and push frames with timestamps >= 1.
+    When it reaches timestamp 5, it does not decode and push frames anymore.
+
+    The stop time is important when the video format contains B frames. The
+    video decoder receives a P frame first, which is can decode but not push yet.
+    When it receives a B frame, it can decode the B frame and push the B frame
+    followed by the previously decoded P frame. If the P frame is outside of the
+    segment, the decoder knows it should not send the P frame.
+
+    Avidemux stops sending data after pushing frame with timestamp 5 and pushes
+    an EOS event downstream to finish playback.
+
+
+

gst/gstbin.c

@@ -32,8 +32,8 @@
  * allowing for deep nesting of predefined sub-pipelines.
  *
  * A new GstBin is created with gst_bin_new(). Use a #GstPipeline instead if you
- * want to create a toplevel bin because a normal bin doesn't have a scheduler
- * of its own.
+ * want to create a toplevel bin because a normal bin doesn't have a bus or
+ * handle clock distribution of its own.
  * 
  * After the bin has been created you will typically add elements to it with
  * gst_bin_add(). You can remove elements with gst_bin_remove().
@@ -43,24 +43,15 @@
  * purposes and will query the parent bins when the element is not found in the
  * current bin.
  * 
- * The list of elements in a bin can be retrieved with gst_bin_get_list().
- * 
- * After the bin has been set to the PLAYING state (with gst_element_set_state()), 
- * gst_bin_iterate() is used to process the elements in the bin.
+ * An iterator of elements in a bin can be retrieved with 
+ * gst_bin_iterate_elements(). Various other iterators exist to retrieve the
+ * elements in a bin.
  * 
  * The "element_added" signal is fired whenever a new element is added to the
  * bin. Likewise the "element_removed" signal is fired whenever an element is
  * removed from the bin.
  *
- * gst_bin_destroy() is used to destroy the bin. 
- *
- * To control the selection of the clock in a bin, you can use the following
- * methods:
- * gst_bin_auto_clock() to let the bin select a clock automatically,
- * gst_bin_get_clock() to get the current clock of the bin and
- * gst_bin_use_clock() to specify a clock explicitly.
- * Note that the default behaviour is to automatically select a clock from one
- * of the clock providers in the bin.
+ * gst_bin_unref() is used to destroy the bin. 
  */
 
 #include "gst_private.h"

gst/gstbuffer.c

@@ -58,6 +58,11 @@
  * If an element knows what pad you will push the buffer out on, it should use
  * gst_pad_alloc_buffer() instead to create a buffer.  This allows downstream
  * elements to provide special buffers to write in, like hardware buffers.
+ *
+ * A buffer has a pointer to a #GstCaps describing the media type of the data
+ * in the buffer. Attach caps to the buffer with gst_buffer_set_caps(); this
+ * is typically done before pushing out a buffer using gst_pad_push() so that
+ * the downstream element knows the type of the buffer.
  * 
  * gst_buffer_ref() is used to increase the refcount of a buffer. This must be
  * done when you want to keep a handle to the buffer after pushing it to the
@@ -80,12 +85,10 @@
  * An element should either unref the buffer or push it out on a src pad
  * using gst_pad_push() (see #GstPad).
  * 
- * Buffers usually are freed by unreffing them with gst_buffer_unref().
- * Do not use gst_buffer_free() : this function effectively frees the buffer
- * regardless of the refcount, which is dangerous.
- *
- * Last reviewed on August 12th, 2004 (0.8.5)
+ * Buffers usually are freed by unreffing them with gst_buffer_unref(). When
+ * the refcount drops to 0, the buffer memory will be freed again.
  *
+ * Last reviewed on September 24th, 2005 (0.9.0)
  */
 #include "gst_private.h"
 

gst/gstclock.c

@@ -31,8 +31,10 @@
  *
  * The clock time is always measured in nanoseconds and always increases. The
  * pipeline uses the clock to calculate the stream time.
- * Usually all renderers sync to the global clock so that the clock is always 
- * a good measure of the current playback time in the pipeline.
+ * Usually all renderers sync to the global clock using the buffer timestamps
+ * and the segment events.
+ *
+ * The time of the clock in itself is not very usefull for an application.
  */
 #include <time.h>
 

gst/gstelement.c

@@ -39,10 +39,9 @@
  * and output (or source) pads.  
  * Core and plug-in writers can add and remove pads with gst_element_add_pad()
  * and gst_element_remove_pad().
- * Application writers can manipulate ghost pads (copies of real pads inside a bin)
- * with gst_element_add_ghost_pad() and gst_element_remove_ghost_pad().
+ *
  * A pad of an element can be retrieved by name with gst_element_get_pad().
- * A GList of all pads can be retrieved with gst_element_get_pad_list().
+ * An iterator of all pads can be retrieved with gst_element_iterate_pads().
  * 
  * Elements can be linked through their pads.
  * If the link is straightforward, use the gst_element_link() 
@@ -61,9 +60,7 @@
  * gst_element_state_get_name().
  * 
  * You can get and set a #GstClock on an element using gst_element_get_clock()
- * and gst_element_set_clock().  You can wait for the clock to reach a given
- * #GstClockTime using gst_element_clock_wait().
- * 
+ * and gst_element_set_clock().  
  */
 #include "gst_private.h"
 #include <glib.h>

gst/gstevent.c

@@ -26,9 +26,10 @@
  *
  * The event classes are used to construct and query events.
  *
- * Events are usually created with gst_event_new() which takes the event type as
- * an argument. Properties specific to the event can be set afterwards with the
- * provided macros. The event should be unreferenced with gst_event_unref().
+ * Events are usually created with gst_event_new_*() which takes the extra event 
+ * paramters as arguments. 
+ * Events can be parsed with their respective gst_event_parse_*() functions.
+ * The event should be unreferenced with gst_event_unref().
  *
  * gst_event_new_seek() is a usually used to create a seek event and it takes
  * the needed parameters for a seek event.

gst/gstfilter.c

@@ -18,13 +18,8 @@
  */
 /**
  * SECTION:gstfilter
- * @short_description: Take data in and spit data out
+ * @short_description: A utility function to filter GLists.
  *
- * Filters take data in and spit data out. They are the main elements in a
- * filter graph.
- * Filters have zero or more inputs and zero or more outputs. Filters are
- * linked together to form filter graphs. A #GstFilter is the base class and is
- * not very useful on its own.
  */
 #include "gst_private.h"
 #include <gst/gstfilter.h>

gst/gstiterator.c

@@ -18,6 +18,18 @@
  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  * Boston, MA 02111-1307, USA.
  */
+/**
+ * SECTION:gstiterator
+ * @short_description: Object to retrieve multiple elements in a threadsafe
+ * way.
+ * @see_also: #GstElement, #GstBin
+ *
+ * A GstIterator is used to retrieve multiple objects from another object in
+ * a threadsafe way.
+ *
+ * Various GStreamer objects provide access to their internal structures using
+ * an iterator.
+ */
 
 #include "gst_private.h"
 #include <gst/gstiterator.h>