Update some docs regarding reverse playback.

Original commit message from CVS:
* docs/design/part-trickmodes.txt:
* gst/gstevent.c:
Update some docs regarding reverse playback.

ChangeLog

@@ -1,3 +1,9 @@
+2006-10-16  Wim Taymans  <wim@fluendo.com>
+
+	* docs/design/part-trickmodes.txt:
+	* gst/gstevent.c:
+	Update some docs regarding reverse playback.
+
 2006-10-15  Tim-Philipp Müller  <tim at centricular dot net>
 
 	Patch by: Marcus Granado  <mrc dot gran at gmail com>

docs/design/part-trickmodes.txt

@@ -160,27 +160,42 @@ For backwards playback the following rules apply:
 
 For plugins the following rules apply:
    
- - A source plugin sends data in chunks starting from the last chunk of the file. 
+ - A source plugin sends data in chunks starting from the last chunk of the
-   The actual bytes are not reversed.
+   file. The actual bytes are not reversed. Each chunk that is not forward
+   continuous with the previous chunk is marked with a DISCONT flag.
 
  - A demuxer accumulates the chunks. As soon as a keyframe is found, everything
    starting from the keyframe up to the accumulated data is sent downstream.
    Timestamps on the buffers are set starting from the stop position to start,
-   effectively going backwards.
+   effectively going backwards. Chunks are marked with DISCONT when they are not
+   forward continuous with the previous buffer.
 
- - A decoder decodes and accumulates all frames. If a new keyframe or EOS is received, 
+ - A video decoder decodes and accumulates all decoded frames. If a buffer with
-   all accumulated frames are sent downsteam in reverse. 
+   a DISCONT, accumulate NEWSEGMENT or EOS is received, all accumulated frames
+   are sent downsteam in reverse.
 
- - A sink reverses (for audio) and retimestamps (audio, video) the buffers before
+ - An audio decoder decodes and accumulates all decoded audio. If a buffer with
-   playing them back. Retimestamping occurs relative to the stop position, making
+   a DISCONT, accumulate NEWSEGMENT or EOS is received, all accumulated audio
-   the timestamps increase again and suitable for synchronizing against the clock.
+   is sent downstream in reverse order. Some audio codecs need the previous
+   data buffer to decode the current one, in that case, the previous DISCONT
+   buffer needs to be combined with the last non-DISCONT buffer to generate the
+   last bit of output.
 
- - for transcoding, audio and video resamplers can be used to reverse, resample and
+ - A sink reverses (for audio) and retimestamps (audio, video) the buffers
-   retimestamp the buffers.
+   before playing them back. Retimestamping occurs relative to the stop
+   position, making the timestamps increase again and suitable for synchronizing
+   against the clock.
+   Audio sinks also have to perform simple resampling before playing the
+   samples.
+
+ - for transcoding, audio and video resamplers can be used to reverse, resample
+   and retimestamp the buffers. Any rate adjustments performed on the media must
+   be added to the applied_rate and subtracted from the rate members in the
+   NEWSEGMENT event.
 
 Notes:
 
- - The clock keeps running forward.
+ - The clock/stream_time keeps running forward.
- - backwards playback potentially uses a lot of memory as frames and undecoded data
+ - backwards playback potentially uses a lot of memory as frames and undecoded
-   gets buffered.
+   data gets buffered.
 

gst/gstevent.c

@@ -811,8 +811,11 @@ gst_event_parse_qos (GstEvent * event, gdouble * proportion,
  * that the position should not be updated.
  *
  * When the rate is positive and @start has been updated, playback will start
- * from the newly configured start position. For negative rates, playback will
+ * from the newly configured start position. 
- * start from the newly configured stop position.
+ *
+ * For negative rates, playback will start from the newly configured stop
+ * position (if any). If the stop position if updated, it must be different from
+ * -1 for negative rates.
  *
  * It is not possible to seek relative to the current playback position, to do
  * this, PAUSE the pipeline, query the current playback position with