docs/design/part-activation.txt

   1 Pad (de)activation
   2 ------------------
   3
   4 Activation
   5 ~~~~~~~~~~
   6
   7 When changing states, a bin will set the state on all of its children in
   8 sink-to-source order. As elements undergo the READY->PAUSED transition,
   9 their pads are activated so as to prepare for data flow. Some pads will
  10 start tasks to drive the data flow.
  11
  12 An element activates its pads from sourcepads to sinkpads. This to make
  13 sure that when the sinkpads are activated and ready to accept data, the
  14 sourcepads are already active to pass the data downstream.
  15
  16 Pads can be activated in one of two modes, PUSH and PULL. PUSH pads are
  17 the normal case, where the source pad in a link sends data to the sink
  18 pad via gst_pad_push(). PULL pads instead have sink pads request data
  19 from the source pads via gst_pad_pull_range().
  20
  21 To activate a pad, the core will call gst_pad_set_active() with a TRUE
  22 argument, indicating that the pad should be active. If the pad is
  23 already active, be it in a PUSH or PULL mode, gst_pad_set_active() will
  24 return without doing anything. Otherwise it will call the activation
  25 function of the pad.
  26
  27 Because the core does not know in which mode to activate a pad (PUSH or
  28 PULL), it delegates that choice to a method on the pad, activate(). The
  29 activate() function of a pad should choose whether to operate in PUSH or
  30 PULL mode. Once the choice is made, it should call one of the two
  31 mode-specific activation functions, activate_push() or activate_pull().
  32 The default activate() function will call activate_push(), as it is the
  33 default mechanism for data flow. A sink pad that supports either mode of
  34 operation might call activate_pull() if calling check_get_range()
  35 returns TRUE, and activate_push() otherwise.
  36
  37 Consider the case fakesrc ! fakesink, where fakesink is configured to
  38 operate in PULL mode. State changes in the pipeline will start with
  39 fakesink, which is the most downstream element. The core will call
  40 activate() on fakesink's sink pad. For fakesink to go into PULL mode, it
  41 needs to implement a custom activate() function that will call
  42 activate_pull() on its sink pad (because the default is to use PUSH
  43 mode). activate_pull() is then responsible for starting the task that
  44 pulls from fakesrc:src. Clearly, fakesrc needs to be notified that
  45 fakesrc is about to pull on its src pad, even though the pipeline has
  46 not yet changed fakesrc's state. For this reason, activate_pull() must
  47 first call activate_pull() on fakesink:sink's peer before starting
  48 fakesink's task.
  49
  50 In short, upstream elements operating in PULL mode must be ready to
  51 produce data in READY, after having activate_pull() called on their
  52 source pad. Also, a call to activate_pull() needs to propagate through
  53 the pipeline to every pad that a gst_pad_pull() will reach. In the case
  54 fakesrc ! identity ! fakesink, calling activate_pull() on identity's
  55 source pad would need to activate its sink pad in pull mode as well,
  56 which should propagate all the way to fakesrc.
  57
  58 If, on the other hand, fakesrc ! fakesink is operating in PUSH mode, the
  59 activation sequence is different. First, activate() on fakesink:sink
  60 calls activate_push() on fakesink:sink. Then fakesrc's pads are
  61 activated: sources first, then sinks (of which fakesrc has none).
  62 fakesrc:src's activation function is then called.
  63
  64 Note that it does not make sense to set an activation function on a
  65 source pad. The peer of a source pad is downstream, meaning it should
  66 have been activated first. If it was activated in PULL mode, the the
  67 source pad should have already had activate_pull() called on it, and
  68 thus needs no further activation. Otherwise it should be in PUSH mode,
  69 which is the choice of the default activation function.
  70
  71 So, in the PUSH case, the default activation function chooses PUSH mode,
  72 which calls activate_push(), which will then start a task on the source
  73 pad and begin pushing. In this way PUSH scheduling is a bit easier,
  74 because it follows the order of state changes in a pipeline. fakesink is
  75 already in PAUSED with an active sink pad by the time fakesrc starts
  76 pushing data.
  77
  78 Deactivation
  79 ~~~~~~~~~~~~
  80
  81 Pad deactivation occurs when its parent goes into the READY state or when the
  82 pad is deactivated explicitly by the application or element.
  83 gst_pad_set_active() is called with a FALSE argument, which then calls
  84 activate_push() or activate_pull() with a FALSE argument, depending on the
  85 activation mode of the pad.
  86
  87 Mode switching
  88 ~~~~~~~~~~~~~~
  89
  90 Changing from push to pull modes needs a bit of thought. This is actually
  91 possible and implemented but not yet documented here.
  92