gstreamer/docs/manual/advanced-clocks.xml

64 lines
3 KiB
XML
Raw Normal View History

<chapter id="chapter-clocks">
<title>Clocks in GStreamer</title>
docs/manual/: Try 2. This time, include a short preface as a "general introduction", also add code blocks around all ... Original commit message from CVS: * docs/manual/advanced-autoplugging.xml: * docs/manual/advanced-clocks.xml: * docs/manual/advanced-interfaces.xml: * docs/manual/advanced-metadata.xml: * docs/manual/advanced-position.xml: * docs/manual/advanced-schedulers.xml: * docs/manual/advanced-threads.xml: * docs/manual/appendix-gnome.xml: * docs/manual/appendix-programs.xml: * docs/manual/appendix-quotes.xml: * docs/manual/autoplugging.xml: * docs/manual/basics-bins.xml: * docs/manual/basics-data.xml: * docs/manual/basics-elements.xml: * docs/manual/basics-helloworld.xml: * docs/manual/basics-init.xml: * docs/manual/basics-pads.xml: * docs/manual/basics-plugins.xml: * docs/manual/bins-api.xml: * docs/manual/bins.xml: * docs/manual/buffers-api.xml: * docs/manual/buffers.xml: * docs/manual/clocks.xml: * docs/manual/components.xml: * docs/manual/cothreads.xml: * docs/manual/debugging.xml: * docs/manual/dparams-app.xml: * docs/manual/dynamic.xml: * docs/manual/elements-api.xml: * docs/manual/elements.xml: * docs/manual/factories.xml: * docs/manual/gnome.xml: * docs/manual/goals.xml: * docs/manual/helloworld.xml: * docs/manual/helloworld2.xml: * docs/manual/highlevel-components.xml: * docs/manual/highlevel-xml.xml: * docs/manual/init-api.xml: * docs/manual/intro-basics.xml: * docs/manual/intro-motivation.xml: * docs/manual/intro-preface.xml: * docs/manual/intro.xml: * docs/manual/links-api.xml: * docs/manual/links.xml: * docs/manual/manual.xml: * docs/manual/motivation.xml: * docs/manual/pads-api.xml: * docs/manual/pads.xml: * docs/manual/plugins-api.xml: * docs/manual/plugins.xml: * docs/manual/programs.xml: * docs/manual/queues.xml: * docs/manual/quotes.xml: * docs/manual/schedulers.xml: * docs/manual/states-api.xml: * docs/manual/states.xml: * docs/manual/threads.xml: * docs/manual/typedetection.xml: * docs/manual/win32.xml: * docs/manual/xml.xml: Try 2. This time, include a short preface as a "general introduction", also add code blocks around all code samples so they get compiled. We still need a way to tell readers the filename of the code sample. In some cases, don't show all code in the documentation, but do include it in the generated code. This allows for focussing on specific bits in the docs, while still having a full test application available. * examples/manual/Makefile.am: Fix up examples for new ADM. Add several of the new examples that were either added or were missing from the build system. * examples/manual/extract.pl: Allow nameless blocks.
2004-12-15 17:32:49 +00:00
<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>
<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 the point where media time
is starting from zero. This timestamp is subctracted from the clock
time, and that value is returned by <function>_get_time ()</function>.
</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 a certain time is reached before
playing back their current sample; this can be done with the function
<function>gst_clock_id_wait ()</function>. Some elements may need to
support dropping samples too, however.
</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>