GstPipeline
-----------

A GstPipeline is usually a toplevel bin an provides all of its 
children with a clock.

The pipeline also calculates the stream time based on the selected
clock (see part-clocks.txt).

The pipeline manages the seek operation for the application.


State changes
-------------

In addition to the normal state change procedure of its parent class
GstBin, the pipeline performs the following actions during a state change:

 - READY -> PAUSED:
    - Select and set a clock.

 - PAUSED -> PLAYING:
    - calculate the stream time.

The GstPipeline will also wait for any async state change to complete before
proceeding to the next state change. This is usefull for the application because
it does not have to deal with ASYNC state changes then.


Clock selection
---------------

Since all of the children of a GstPipeline must use the same clock, the
pipeline must select a clock.

The default clock selection algorithm works as follows:

 - If the application selected a clock, use that clock. (see below)
 - use clock of source elements (*)
 - use clock of other element, starting from the sinks going upstream. 
   (+)
 - use GstSystemClock.

(*) currently not implemented.
(+) traversing the graph upstream to find the best clock is not implemented,
    currently the first element found that provides a clock is used.

The application can influence this clock selection with two methods:
gst_pipeline_use_clock() and gst_pipeline_auto_clock(). 

The _use_clock() method forces the use of a specific clock on the pipeline 
regardless of what clock providers are children of the pipeline. Setting 
NULL disables the clock completely and makes the pipeline run as fast as 
possible.

The _auto_clock() method removes the fixed clock and reactivates the auto-
matic clock selection algorithm described above.

Seeking
-------

When performing a seek on the pipeline element using gst_element_send_event(),
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
 - when a FLUSH seek is done, the stream_time is set 0 again.
 - restore old state of the pipeline.