Merge remote-tracking branch 'origin/0.10'

[platform/upstream/gstreamer.git] / docs / design / part-latency.txt

diff --git a/docs/design/part-latency.txt b/docs/design/part-latency.txt
index 637d584..315c756 100644 (file)
--- a/docs/design/part-latency.txt
+++ b/docs/design/part-latency.txt
@@ -95,7 +95,7 @@ capture pipelines.
   * the sink will receive the buffer with timestamp 0 at time >= D. At this
     point the buffer is too late already and might be dropped. This state of
     constantly dropping data will not change unless a constant latency
-    correction is added to the incomming buffer timestamps.
+    correction is added to the incoming buffer timestamps.
 
   The problem is due to the fact that the sink is set to (pending) PLAYING
   without being prerolled, which only happens in live pipelines. 
@@ -195,13 +195,11 @@ capture pipelines.
   prerolled.
 
 
-State Changes revised
-~~~~~~~~~~~~~~~~~~~~~
+State Changes
+~~~~~~~~~~~~~
 
-As a first step in a generic solution we propose to modify the state changes so
-that no sink is set to PLAYING before it is prerolled.
-
-In order to do this, the pipeline (at the GstBin level) keeps track of all
+A Sink is never set to PLAYING before it is prerolled. In order to do this, the
+pipeline (at the GstBin level) keeps track of all
 elements that require preroll (the ones that return ASYNC from the state
 change). These elements posted a ASYNC_START message without a matching
 ASYNC_DONE message.
@@ -221,18 +219,37 @@ NO_PREROLL element to PLAYING. This operation has to be performed in the
 separate async state change thread (like the one currently used for going from
 PAUSED->PLAYING in a non-live pipeline).
 
-implications:
 
- - the current async_play vmethod in basesink can be deprecated since we now
-   always call the state change function when going from PAUSED->PLAYING. We
-   keep this method however to remain backward compatible.
+Query
+~~~~~
+
+The pipeline latency is queried with the LATENCY query.
+
+ (out) "live", G_TYPE_BOOLEAN (default FALSE)
+        - if a live element is found upstream
+
+ (out) "min-latency", G_TYPE_UINT64 (default 0)
+        - the minimum latency in the pipeline
+
+ (out) "max-latency", G_TYPE_UINT64 (default 0)
+        - the maximum latency in the pipeline
+
+
+Event
+~~~~~
+
+The latency in the pipeline is configured with the LATENCY event, which contains
+the following fields:
+
+      "latency", G_TYPE_UINT64
+        - the configured latency in the pipeline
 
 
 Latency compensation
 ~~~~~~~~~~~~~~~~~~~~
 
-As an extension to the revised state changes we can perform latency calculation
-and compensation before we proceed to the PLAYING state. 
+Latency calculation and compensation is performed before the pipeline proceeds to
+the PLAYING state. 
 
 When the pipeline collected all ASYNC_DONE messages it can calculate the global
 latency as follows:
@@ -279,8 +296,8 @@ the same for all sinks, all sinks will render data relatively synchronised.
 Flushing a playing pipeline
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Using the new state change mechanism we can implement resynchronisation after an
-uncontrolled FLUSH in (part of) a pipeline. Indeed, when a flush is performed on
+We can implement resynchronisation after an uncontrolled FLUSH in (part of) a
+pipeline in the same way. Indeed, when a flush is performed on
 a PLAYING live element, a new base time must be distributed to this element.
 
 A flush in a pipeline can happen in the following cases: