gst/playback/gstplaybin.c: Improve docs: add section about BUFFERING messages sent...

Original commit message from CVS:
* gst/playback/gstplaybin.c:
Improve docs: add section about BUFFERING messages sent by playbin.

diff --git a/ChangeLog b/ChangeLog
index 8a9f3c7..e80c453 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2006-08-29  Tim-Philipp Müller  <tim at centricular dot net>
+
+       * gst/playback/gstplaybin.c:
+         Improve docs: add section about BUFFERING messages sent by playbin.
+
 2006-08-29  Michael Smith  <msmith@fluendo.com>
 
        * ext/vorbis/vorbisenc.c: (gst_vorbis_enc_push_buffer),

diff --git a/gst/playback/gstplaybin.c b/gst/playback/gstplaybin.c
index a4af2ad..6e9d241 100644 (file)
--- a/gst/playback/gstplaybin.c
+++ b/gst/playback/gstplaybin.c
@@ -161,6 +161,27 @@
  * new_state=PAUSED), since before that the list might not be complete yet or
  * not contain all available information (like language-codes).
  * </para>
+ * <title>Buffering status</title>
+ * <para>
+ * Playbin handles buffering automatically. When playbin is buffering, it
+ * will post BUFFERING messages on the bus with a percentage value that
+ * shows the progress of the buffering. Applications may want to show this
+ * information to the user in some form or another. Here is how to extract
+ * the percentage information from the message:
+ * </para>
+ * <para>
+ * <programlisting>
+ * switch (GST_MESSAGE_TYPE (msg)) {
+ *   case GST_MESSAGE_BUFFERING: {
+ *     gint percent = 0;
+ *     gst_structure_get_int (msg-&gt;structure, "buffer-percent", &amp;percent);
+ *     g_print ("Buffering (%%u percent done)", percent);
+ *     break;
+ *   }
+ *   ...
+ * }
+ * </programlisting>
+ * </para>
  * <title>Embedding the video window in your application</title>
  * <para>
  * By default, playbin (or rather the video sinks used) will create their own