gstreamer/docs/design/part-gstpipeline.txt
Wim Taymans b69033434f docs/design/: Documentation updates.
Original commit message from CVS:
* docs/design/draft-klass.txt:
* docs/design/part-clocks.txt:
* docs/design/part-events.txt:
* docs/design/part-gstbin.txt:
* docs/design/part-gstpipeline.txt:
* docs/design/part-messages.txt:
* docs/design/part-negotiation.txt:
* docs/design/part-overview.txt:
* docs/design/part-preroll.txt:
* docs/design/part-seeking.txt:
* docs/design/part-states.txt:
* docs/design/part-streams.txt:
Documentation updates.
2006-03-13 10:32:26 +00:00

90 lines
2.7 KiB
Text

GstPipeline
-----------
A GstPipeline is usually a toplevel bin and provides all of its
children with a clock.
A GstPipeline also provides a toplevel GstBus (see part-gstbus.txt)
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:
- NULL -> READY:
- set the bus to non-flushing
- READY -> PAUSED:
- reset the stream time to 0
- PAUSED -> PLAYING:
- Select and a clock.
- calculate base time using the stream time.
- set clock and base time on all elements before performing the
state change.
- PAUSED -> PLAYING:
- calculate the stream time when the pipeline was stopped.
- READY -> NULL:
- set the bus to flushing (when auto-flushing is enabled)
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 the clock of most upstream element that can provide a clock. This
selection is performed by iterating the element starting from the
sinks going upstream.
* since this selection procedure happens in the PAUSED->PLAYING
state change, all the sinks are prerolled and we can thus be sure
that each sink is linked to some upstream element.
* in the case of a live pipeline (NO_PREROLL), the sink will not
be prerolled and the selection process will select the clock of
a more upstream element.
- use GstSystemClock, this only happens when no element provides a
clock.
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 if a FLUSHING seek is requested
- send the seek event to all sinks
- when a FLUSH seek was performed successfully, the stream_time is set 0 again.
- restore old state of the pipeline.