docs/design/part-gstpipeline.txt

   1 GstPipeline
   2 -----------
   3
   4 A GstPipeline is usually a toplevel bin and provides all of its
   5 children with a clock.
   6
   7 A GstPipeline also provides a toplevel GstBus (see part-gstbus.txt)
   8
   9 The pipeline also calculates the running_time based on the selected
  10 clock (see also clocks.txt and part-synchronisation.txt).
  11
  12 The pipeline will calculate a global latency for the elements in the pipeline.
  13 (See also part-latency.txt).
  14
  15 State changes
  16 ~~~~~~~~~~~~~
  17
  18 In addition to the normal state change procedure of its parent class
  19 GstBin, the pipeline performs the following actions during a state change:
  20
  21  - NULL -> READY:
  22     - set the bus to non-flushing
  23
  24  - READY -> PAUSED:
  25     - reset the running_time to 0
  26
  27  - PAUSED -> PLAYING:
  28     - Select and a clock.
  29     - calculate base_time using the running_time.
  30     - calculate and distribute latency.
  31     - set clock and base_time on all elements before performing the
  32       state change.
  33
  34  - PAUSED -> PLAYING:
  35     - calculate the running_time when the pipeline was PAUSED.
  36
  37  - READY -> NULL:
  38     - set the bus to flushing (when auto-flushing is enabled)
  39
  40 The running_time represents the total elapsed time, measured in clock units,
  41 that the pipeline spent in the PLAYING state (see part-synchronisation.txt).
  42 The running_time is set to 0 after a flushing seek.
  43
  44
  45 Clock selection
  46 ~~~~~~~~~~~~~~~
  47
  48 Since all of the children of a GstPipeline must use the same clock, the
  49 pipeline must select a clock. This clock selection happens when the pipeline
  50 goes to the PLAYING state.
  51
  52 The default clock selection algorithm works as follows:
  53
  54  - If the application selected a clock, use that clock. (see below)
  55
  56  - Use the clock of most upstream element that can provide a clock. This
  57    selection is performed by iterating the element starting from the
  58    sinks going upstream.
  59
  60     * since this selection procedure happens in the PAUSED->PLAYING
  61       state change, all the sinks are prerolled and we can thus be sure
  62       that each sink is linked to some upstream element.
  63     * in the case of a live pipeline (NO_PREROLL), the sink will not yet
  64       be prerolled and the selection process will select the clock of
  65       a more upstream element.
  66
  67  - use GstSystemClock, this only happens when no element provides a
  68    usable clock.
  69
  70 The application can influence this clock selection with two methods:
  71 gst_pipeline_use_clock() and gst_pipeline_auto_clock().
  72
  73 The _use_clock() method forces the use of a specific clock on the pipeline
  74 regardless of what clock providers are children of the pipeline. Setting
  75 NULL disables the clock completely and makes the pipeline run as fast as
  76 possible.
  77
  78 The _auto_clock() method removes the fixed clock and reactivates the auto-
  79 matic clock selection algorithm described above.
  80
  81
  82 GstBus
  83 ~~~~~~
  84
  85 A GstPipeline provides a GstBus to the application. The bus can be retrieved
  86 with gst_pipeline_get_bus() and can then be used to retrieve messages posted by
  87 the elements in the pipeline (see part-gstbus.txt).
  88