| 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 running_time based on the selected |
| clock (see also clocks.txt and part-synchronisation.txt). |
| |
| The pipeline will calculate a global latency for the elements in the pipeline. |
| (See also part-latency.txt). |
| |
| 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 running_time to 0 |
| |
| - PAUSED -> PLAYING: |
| - Select and a clock. |
| - calculate base_time using the running_time. |
| - calculate and distribute latency. |
| - set clock and base_time on all elements before performing the |
| state change. |
| |
| - PLAYING -> PAUSED: |
| - calculate the running_time when the pipeline was PAUSED. |
| |
| - READY -> NULL: |
| - set the bus to flushing (when auto-flushing is enabled) |
| |
| The running_time represents the total elapsed time, measured in clock units, |
| that the pipeline spent in the PLAYING state (see part-synchronisation.txt). |
| The running_time is set to 0 after a flushing seek. |
| |
| |
| Clock selection |
| ~~~~~~~~~~~~~~~ |
| |
| Since all of the children of a GstPipeline must use the same clock, the |
| pipeline must select a clock. This clock selection happens when the pipeline |
| goes to the PLAYING state. |
| |
| 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 yet |
| 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 |
| usable 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. |
| |
| |
| GstBus |
| ~~~~~~ |
| |
| A GstPipeline provides a GstBus to the application. The bus can be retrieved |
| with gst_pipeline_get_bus() and can then be used to retrieve messages posted by |
| the elements in the pipeline (see part-gstbus.txt). |
| |