From 3f2eb6bdffe088fea3f2961244bfa09f238efd0a Mon Sep 17 00:00:00 2001 From: Wim Taymans Date: Fri, 22 Sep 2006 15:29:23 +0000 Subject: [PATCH] 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 | 10 ++++++++ docs/design/part-buffering.txt | 43 +++++++++++++++++++++++++++++---- docs/design/part-trickmodes.txt | 2 +- gst/gstmessage.c | 10 +++++++- 4 files changed, 58 insertions(+), 7 deletions(-) diff --git a/ChangeLog b/ChangeLog index 273d21ad63..2a20ac4da5 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,13 @@ +2006-09-22 Wim Taymans + + * 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 * libs/gst/controller/gstcontroller.c: (gst_controller_new_valist), diff --git a/docs/design/part-buffering.txt b/docs/design/part-buffering.txt index adf4503720..622d2113d2 100644 --- a/docs/design/part-buffering.txt +++ b/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 -reading from a (slow) and non-live network source. +playback can occur smoothly and without interruptions. It is typically done +when reading from a (slow) and non-live network source. -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. + Some use cases: + + +---------+ +--------+ +-------+ + | 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. + diff --git a/docs/design/part-trickmodes.txt b/docs/design/part-trickmodes.txt index 321487fa46..d318a8cac4 100644 --- a/docs/design/part-trickmodes.txt +++ b/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. diff --git a/gst/gstmessage.c b/gst/gstmessage.c index 8a6dd9a236..ba3f86cba6 100644 --- a/gst/gstmessage.c +++ b/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 *