Update docs about buffering.

Original commit message from CVS:
* docs/design/part-buffering.txt:
* gst/gstmessage.c: (gst_message_new_buffering),
(gst_message_parse_buffering):
Update docs about buffering.
* docs/design/part-trickmodes.txt:
Fix typo.

ChangeLog

@@ -1,3 +1,13 @@
+2006-09-22  Wim Taymans  <wim@fluendo.com>
+
+	* docs/design/part-buffering.txt:
+	* gst/gstmessage.c: (gst_message_new_buffering),
+	(gst_message_parse_buffering):
+	Update docs about buffering.
+
+	* docs/design/part-trickmodes.txt:
+	Fix typo.
+
 2006-09-22  Stefan Kost  <ensonic@users.sf.net>
 
 	* libs/gst/controller/gstcontroller.c: (gst_controller_new_valist),

docs/design/part-buffering.txt

@@ -5,16 +5,49 @@ This document outlines the buffering policy used in the GStreamer
 core that can be used by plugins and applications.
 
 The purpose of buffering is to accumulate enough data in a pipeline so that
-playback can occur smoothly and without interruptions. It is typically done when
+playback can occur smoothly and without interruptions. It is typically done
-reading from a (slow) and non-live network source.
+when reading from a (slow) and non-live network source.
 
-While data is buffered, the pipeline should remain in the PAUSED state. It is
+ Some use cases:
-also possible that more data should be buffered while the pipeline is PLAYING,
+
-in which case the pipeline should be PAUSED until the buffering finished.
+   +---------+     +--------+     +-------+
+   | httpsrc |     | buffer |     | demux |
+   |        src - sink     src - sink     ....
+   +---------+     +--------+     +-------+
+
+  In this case we are reading from a slow network source into a buffer element
+  (such as queue). 
+  
+  The buffer element has a low and high watermark expressed in bytes. The
+  buffer uses the watermarks as follows:
+  
+   - The buffer element will not produce data on the src pad until the high
+     watermark is hit. While accumulating data in the buffer, progress is
+     reported by posting BUFFERING messages.
+   - The source will stop to produce data on the src pad when the low watermark
+     is hit.
 
 
 Messages
 --------
 
+A GST_MESSAGE_BUFFERING must be posted on the bus when playback temporarily
+stops to buffer and when buffering finishes. When percentage field in the
+BUFFERING message is 100, buffering is done. Values less than 100 mean that
+buffering is in progress. 
+
+The BUFFERING message should be intercepted and acted upon by the application.
 
 
+Application
+-----------
+
+While data is buffered, the pipeline should remain in the PAUSED state. It is
+also possible that more data should be buffered while the pipeline is PLAYING,
+in which case the pipeline should be PAUSED until the buffering finished.
+
+BUFFERING messages can be posted while the pipeline is prerolling. The
+application should not set the pipeline to PLAYING before a BUFFERING message
+with 100 percent value is received, which might only happen after the pipeline
+prerolled.
+

docs/design/part-trickmodes.txt

@@ -182,5 +182,5 @@ Notes:
 
  - The clock keeps running forward.
  - backwards playback potentially uses a lot of memory as frames and undecoded data
-   get buffered.
+   gets buffered.
 

gst/gstmessage.c

@@ -406,6 +406,13 @@ gst_message_new_tag (GstObject * src, GstTagList * tag_list)
  * needs to buffer data before it can continue processing. @percent should be a
  * value between 0 and 100. A value of 100 means that the buffering completed.
  *
+ * When @percent is < 100 the application should PAUSE a PLAYING pipeline. When
+ * @percent is 100, the application can set the pipeline (back) to PLAYING.
+ * The application must be prepared to receive BUFFERING messages in the
+ * PREROLLING state and may only set the pipeline to PLAYING after receiving a
+ * message with @percent set to 100, which can happen after the pipeline
+ * completed prerolling. 
+ *
  * Returns: The new buffering message.
  *
  * Since: 0.10.11
@@ -734,7 +741,8 @@ gst_message_parse_tag (GstMessage * message, GstTagList ** tag_list)
  * @message: A valid #GstMessage of type GST_MESSAGE_BUFFERING.
  * @percent: Return location for the percent.
  *
- * Extracts the buffering percent from the GstMessage. 
+ * Extracts the buffering percent from the GstMessage. see also
+ * gst_message_new_buffering().
  *
  * Since: 0.10.11
  *