docs/design/: Updated docs, mostly DISCONT related.

Original commit message from CVS:
* docs/design/part-TODO.txt:
* docs/design/part-clocks.txt:
* docs/design/part-element-sink.txt:
* docs/design/part-events.txt:
* docs/design/part-gstpipeline.txt:
Updated docs, mostly DISCONT related.

ChangeLog

@@ -1,3 +1,12 @@
+2005-07-15  Wim Taymans  <wim@fluendo.com>
+
+	* docs/design/part-TODO.txt:
+	* docs/design/part-clocks.txt:
+	* docs/design/part-element-sink.txt:
+	* docs/design/part-events.txt:
+	* docs/design/part-gstpipeline.txt:
+	Updated docs, mostly DISCONT related.
+
 2005-07-15  Tim-Philipp Müller  <tim at centricular dot net>
 
 	* docs/pwg/building-pads.xml:

docs/design/part-TODO.txt

@@ -4,9 +4,6 @@
   to a duplicate name after adding it is therefore allowed and voids internal
   consistency.
 
-- only emit EOS in PLAYING. Make sure elements reemit the EOS message when going to
-  PLAYING again.
-
 - implement return values from events in addition to the gboolean. This should be
   done by making the event contain a GstStructure with input/output values, similar
   to GstMessage.
@@ -19,3 +16,6 @@
 
 - implement clock selection as explained in part-gstpipeline.txt
 
+- when a pipeline with a live source goes to PAUSED again, a sample is prerolled
+  in the sinks. This sample should be discarded, possibly with a flush event
+  started from the source.

docs/design/part-clocks.txt

@@ -39,9 +39,29 @@ GstClock absolute time.
 Timestamps
 ----------
 
-Timestamps on buffers are always expressed in stream time. This means that
-all elements that require synchronizing to the clock need to be aware of
-the clock base time in order to know the absolute time of the timestamp.
+The combination of the last DISCONT event and the buffer timestamps 
+express the presentation stream time of the buffer. The stream time
+of a buffer is calculated as follows:
+
+ ST = TS - DT        where: TS = buffer timestamp
+                            DT = DISCONT timestamp
+			    ST = buffer stream time
+
+The reason for not making the buffer times express the stream time directly
+is for the following reasons:
+
+ - demuxers are easier if they can just copy the timestamps as encoded in
+   the file. The initial discont event would contain the lowest timestamp in
+   the stream which makes the stream time start from 0.
+ - pipelines requiring retimestamping of buffers can efficiently adjust
+   the timestamp in the discont events and have all buffers retimestamped
+   automatically.
+ - resync after different kinds of seeks is easier.
+
+If an element wants to synchronize a buffer to the clock it needs to first
+calculate the buffer stream time and then bring the stream time to the
+absolute clock time.
+
 Converting a timestamp (in stream time) to absolute time is performed using
 the following formula:
 

docs/design/part-element-sink.txt

@@ -26,6 +26,7 @@ PAUSED state before commiting the state to PAUSED.
 FLUSHING events have to be handled out of sync with the buffer flow
 and take no part in the preroll procedure.
 
+Events other than EOS do not complete the preroll stage.
 
 
 

docs/design/part-events.txt

@@ -100,7 +100,7 @@ pipeline using the DISCONT event.
 
 Elements that sync to the clock should store the DISCONT start and end values
 and substract the start value from the buffer timestamp before comparing
-it against the stream time.
+it against the stream time (see part-clocks.txt).
 
 An element is allowed to send out buffers with the DISCONT start time already
 substracted from the timestamp. If it does so, it needs to send a corrected
@@ -111,7 +111,7 @@ is usually generated by a demuxer. The event is generated before pushing the
 first buffer and after a seek, right before pushing the new buffer.
 
 The DISCONT event can be send from both the application and the streaming
-thread.
+thread and should be serialized with the buffers.
 
 
 
@@ -126,7 +126,8 @@ The seek event contains the new start and end position of playback
 after the seek is performed. Optionally the end position can be left
 at -1 to continue playback to the end of the stream.
 
-A seek usually flushes the graph to minimize latency after the seek. 
+A seek usually flushes the graph to minimize latency after the seek this
+behaviour is triggered by using the SEEK_FLUSH flag. 
 
 The seek event is passed along from element to element until it reaches
 an element that can perform the seek. No intermediate element is allowed
@@ -139,7 +140,7 @@ or failure can be reported as a return value of the seek event. It is
 therefore important that before executing the seek, the element acquires
 the STREAM_LOCK so that the streaming thread and the seek gets serialized.
 
-The general flow of executing the seek is as follows:
+The general flow of executing the seek with FLUSH is as follows:
 
  1) unblock the streaming threads, they could be blocked in a chain 
     function. This is done by sending a flush on all srcpads.

docs/design/part-gstpipeline.txt

@@ -65,7 +65,7 @@ the pipeline performs the following actions:
  - record the current state of the pipeline.
  - set the pipeline to paused
  - send the seek event to all sinks
- - update the stream time with the time of the seek
+ - when a FLUSH seek is done, the stream_time is set 0 again.
  - restore old state of the pipeline.