Commit 3f2eb6bd authored by Wim Taymans's avatar Wim Taymans

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.
parent 6be1935a
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),
......
......@@ -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.
......@@ -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.
......@@ -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
*
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment