caps: avoid using in-place oprations

[platform/upstream/gstreamer.git] / docs / manual / advanced-clocks.xml

diff --git a/docs/manual/advanced-clocks.xml b/docs/manual/advanced-clocks.xml
index 4781155..c23cf3c 100644 (file)
--- a/docs/manual/advanced-clocks.xml
+++ b/docs/manual/advanced-clocks.xml
@@ -1,7 +1,91 @@
 <chapter id="chapter-clocks">
   <title>Clocks in GStreamer</title>
 
-  <para> 
-    WRITEME
+  <para>
+    To maintain sync in pipeline playback (which is the only case where this
+    really matters), &GStreamer; uses <emphasis>clocks</emphasis>. Clocks
+    are exposed by some elements, whereas other elements are merely clock
+    slaves. The primary task of a clock is to represent the time progress
+    according to the element exposing the clock, based on its own playback
+    rate. If no clock provider is available in a pipeline, the system clock
+    is used instead.
   </para>
+  
+  <para>
+    &GStreamer; derives several <emphasis>time value</emphasis> from the clock
+    and the playback state.
+    It is important to note, that a  <emphasis>clock-time</emphasis> is
+    monotonically rising, but the value itself is not meaningful.
+    Subtracting the <emphasis>base-time</emphasis> yields the
+    <emphasis>running-time</emphasis>. It is the same as the
+    <emphasis>stream-time</emphasis> if one plays from start to end at original
+    rate. The <emphasis>stream-time</emphasis> indicates the position in the
+    media. The <emphasis>running-time</emphasis> is (re-)set to 0 when the 
+    pipeline starts to play and also after <emphasis>flushing</emphasis> seeks.
+  </para>
+
+  <figure float="1" id="chapter-clock-img">
+    <title>&GStreamer; clock and various times</title>
+    <mediaobject>
+      <imageobject>
+        <imagedata scale="75" fileref="images/clocks.&image;" format="&IMAGE;" />
+      </imageobject>
+    </mediaobject>  
+  </figure>
+
+  <sect1 id="section-clocks-providers">
+    <title>Clock providers</title>
+
+    <para>
+      Clock providers exist because they play back media at some rate, and
+      this rate is not necessarily the same as the system clock rate. For
+      example, a soundcard may playback at 44,1 kHz, but that doesn't mean
+      that after <emphasis>exactly</emphasis> 1 second <emphasis>according
+      to the system clock</emphasis>, the soundcard has played back 44.100
+      samples. This is only true by approximation. Therefore, generally,
+      pipelines with an audio output use the audiosink as clock provider.
+      This ensures that one second of video will be played back at the same
+      rate as that the soundcard plays back 1 second of audio.
+    </para>
+    <para>
+      Whenever some part of the pipeline requires to know the current clock
+      time, it will be requested from the clock through
+      <function>gst_clock_get_time ()</function>. The clock-time does not
+      need to start at 0. The pipeline, which contains the global clock that
+      all elements in the pipeline will use, in addition has a <quote>base
+      time</quote>, which is the clock time at the point where the
+      pipeline went to the PLAYING state. Each element can subtract the
+      <quote>base time</quote> from the clock-time to know the current
+      running time.
+    </para>
+    <para>
+      The clock provider is responsible for making sure that the clock time
+      always represents the current media time as closely as possible; it
+      has to take care of things such as playback latencies, buffering in
+      audio-kernel modules, and so on, since all those could affect a/v sync
+      and thus decrease the user experience.
+    </para>
+  </sect1>
+
+  <sect1 id="section-clocks-slaves">
+    <title>Clock slaves</title>
+    <para>
+      Clock slaves get assigned a clock by their containing pipeline. Their
+      task is to make sure that media playback follows the time progress as
+      represented by this clock as closely as possible. For most elements,
+      that will simply mean to wait until the buffer running-time is reached
+      before playing back their current sample.
+    </para>
+    <para>
+      The buffer running-time is derived from the buffer timestamp and the
+      newsegment event preceeding the buffer. A buffer is played synchronized
+      with the clock when the clock's running-time has reached exactly the
+      buffer running-time; this can be done with the function
+      <function>gst_clock_id_wait ()</function>.
+    </para>
+    <para>
+      For more information on how to write elements that conform to this
+      required behaviour, see the Plugin Writer's Guide.
+    </para>
+  </sect1>
 </chapter>