mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-11-19 08:11:16 +00:00
16ce2d4ea4
Unify the ad-hoc markup to be asciidoc style in many places. Add a "html" target to Makefile to generate the output.
92 lines
4.4 KiB
Text
92 lines
4.4 KiB
Text
Pad (de)activation
|
|
------------------
|
|
|
|
Activation
|
|
~~~~~~~~~~
|
|
|
|
When changing states, a bin will set the state on all of its children in
|
|
sink-to-source order. As elements undergo the READY->PAUSED transition,
|
|
their pads are activated so as to prepare for data flow. Some pads will
|
|
start tasks to drive the data flow.
|
|
|
|
An element activates its pads from sourcepads to sinkpads. This to make
|
|
sure that when the sinkpads are activated and ready to accept data, the
|
|
sourcepads are already active to pass the data downstream.
|
|
|
|
Pads can be activated in one of two modes, PUSH and PULL. PUSH pads are
|
|
the normal case, where the source pad in a link sends data to the sink
|
|
pad via gst_pad_push(). PULL pads instead have sink pads request data
|
|
from the source pads via gst_pad_pull_range().
|
|
|
|
To activate a pad, the core will call gst_pad_set_active() with a TRUE
|
|
argument, indicating that the pad should be active. If the pad is
|
|
already active, be it in a PUSH or PULL mode, gst_pad_set_active() will
|
|
return without doing anything. Otherwise it will call the activation
|
|
function of the pad.
|
|
|
|
Because the core does not know in which mode to activate a pad (PUSH or
|
|
PULL), it delegates that choice to a method on the pad, activate(). The
|
|
activate() function of a pad should choose whether to operate in PUSH or
|
|
PULL mode. Once the choice is made, it should call one of the two
|
|
mode-specific activation functions, activate_push() or activate_pull().
|
|
The default activate() function will call activate_push(), as it is the
|
|
default mechanism for data flow. A sink pad that supports either mode of
|
|
operation might call activate_pull() if calling check_get_range()
|
|
returns TRUE, and activate_push() otherwise.
|
|
|
|
Consider the case fakesrc ! fakesink, where fakesink is configured to
|
|
operate in PULL mode. State changes in the pipeline will start with
|
|
fakesink, which is the most downstream element. The core will call
|
|
activate() on fakesink's sink pad. For fakesink to go into PULL mode, it
|
|
needs to implement a custom activate() function that will call
|
|
activate_pull() on its sink pad (because the default is to use PUSH
|
|
mode). activate_pull() is then responsible for starting the task that
|
|
pulls from fakesrc:src. Clearly, fakesrc needs to be notified that
|
|
fakesrc is about to pull on its src pad, even though the pipeline has
|
|
not yet changed fakesrc's state. For this reason, activate_pull() must
|
|
first call activate_pull() on fakesink:sink's peer before starting
|
|
fakesink's task.
|
|
|
|
In short, upstream elements operating in PULL mode must be ready to
|
|
produce data in READY, after having activate_pull() called on their
|
|
source pad. Also, a call to activate_pull() needs to propagate through
|
|
the pipeline to every pad that a gst_pad_pull() will reach. In the case
|
|
fakesrc ! identity ! fakesink, calling activate_pull() on identity's
|
|
source pad would need to activate its sink pad in pull mode as well,
|
|
which should propagate all the way to fakesrc.
|
|
|
|
If, on the other hand, fakesrc ! fakesink is operating in PUSH mode, the
|
|
activation sequence is different. First, activate() on fakesink:sink
|
|
calls activate_push() on fakesink:sink. Then fakesrc's pads are
|
|
activated: sources first, then sinks (of which fakesrc has none).
|
|
fakesrc:src's activation function is then called.
|
|
|
|
Note that it does not make sense to set an activation function on a
|
|
source pad. The peer of a source pad is downstream, meaning it should
|
|
have been activated first. If it was activated in PULL mode, the the
|
|
source pad should have already had activate_pull() called on it, and
|
|
thus needs no further activation. Otherwise it should be in PUSH mode,
|
|
which is the choice of the default activation function.
|
|
|
|
So, in the PUSH case, the default activation function chooses PUSH mode,
|
|
which calls activate_push(), which will then start a task on the source
|
|
pad and begin pushing. In this way PUSH scheduling is a bit easier,
|
|
because it follows the order of state changes in a pipeline. fakesink is
|
|
already in PAUSED with an active sink pad by the time fakesrc starts
|
|
pushing data.
|
|
|
|
Deactivation
|
|
~~~~~~~~~~~~
|
|
|
|
Pad deactivation occurs when its parent goes into the READY state or when the
|
|
pad is deactivated explicitly by the application or element.
|
|
gst_pad_set_active() is called with a FALSE argument, which then calls
|
|
activate_push() or activate_pull() with a FALSE argument, depending on the
|
|
activation mode of the pad.
|
|
|
|
Mode switching
|
|
~~~~~~~~~~~~~~
|
|
|
|
Changing from push to pull modes needs a bit of thought. This is actually
|
|
possible and implemented but not yet documented here.
|
|
|