markdown/additional/design/push-pull.md

   1 # push-pull
   2
   3 Normally a source element will push data to the downstream element using
   4 the `gst_pad_push()` method. The downstream peer pad will receive the
   5 buffer in the Chain function. In the push mode, the source element is
   6 the driving force in the pipeline as it initiates data transport.
   7
   8 It is also possible for an element to pull data from an upstream
   9 element. The downstream element does this by calling
  10 `gst_pad_pull_range()` on one of its sinkpads. In this mode, the
  11 downstream element is the driving force in the pipeline as it initiates
  12 data transfer.
  13
  14 It is important that the elements are in the correct state to handle a
  15 `push()` or a `pull_range()` from the peer element. For `push()` based
  16 elements this means that all downstream elements should be in the
  17 correct state and for `pull_range()` based elements this means the
  18 upstream elements should be in the correct state.
  19
  20 Most sinkpads implement a chain function. This is the most common case.
  21 sinkpads implementing a loop function will be the exception. Likewise,
  22 srcpads implementing a getrange function will be the exception.
  23
  24 ## State changes
  25
  26 The `GstBin` sets the state of all the sink elements. These are the
  27 elements without source pads.
  28
  29 Setting the state on an element will first activate all the srcpads and
  30 then the sinkpads. For each of the sinkpads,
  31 `gst_pad_check_pull_range()` is performed. If the sinkpad supports a
  32 loopfunction and the peer pad returns TRUE from the `GstPadCheckPullRange`
  33 function, then the peer pad is activated first as it must be in the
  34 right state to handle a `_pull_range()`. Note that the state change of
  35 the element is not yet performed, just the activate function is called
  36 on the source pad. This means that elements that implement a getrange
  37 function must be prepared to get their activate function called before
  38 their state change function.
  39
  40 Elements that have multiple sinkpads that require all of them to operate
  41 in the same mode (push/pull) can use the `_check_pull_range()` on all
  42 their pads and can then remove the loop functions if one of the pads
  43 does not support pull based mode.