docs: update activation design docs

docs/design/part-activation.txt

@@ -27,49 +27,50 @@ 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
+PULL mode. Once the choice is made, it should call activate_mode()
-mode-specific activation functions, activate_push() or activate_pull().
+with the selected activation mode.
-The default activate() function will call activate_push(), as it is the
+The default activate() function will call activate_mode() with
-default mechanism for data flow. A sink pad that supports either mode of
+#GST_PAD_MODE_PUSH, as it is the default mechanism for data flow.
-operation might call activate_pull() if calling check_get_range()
+A sink pad that supports either mode of operation might call
-returns TRUE, and activate_push() otherwise.
+activate_mode(PULL) if the SCHEDULING query upstream contains the
+#GST_PAD_MODE_PULL scheduling mode, and activate_mode(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
+activate_mode(PULL) on its sink pad (because the default is to
-mode). activate_pull() is then responsible for starting the task that
+use PUSH mode). activate_mode(PULL) is then responsible for starting
-pulls from fakesrc:src. Clearly, fakesrc needs to be notified that
+the task that pulls from fakesrc:src. Clearly, fakesrc needs to be
-fakesrc is about to pull on its src pad, even though the pipeline has
+notified that fakesrc is about to pull on its src pad, even though the
-not yet changed fakesrc's state. For this reason, activate_pull() must
+pipeline has not yet changed fakesrc's state. For this reason,
-first call activate_pull() on fakesink:sink's peer before starting
+GStreamer will first call call activate_mode(PULL) on fakesink:sink's
-fakesink's task.
+peer before calling activate_mode(PULL) on fakesink:sinks.
 
 In short, upstream elements operating in PULL mode must be ready to
-produce data in READY, after having activate_pull() called on their
+produce data in READY, after having activate_mode(PULL) called on their
-source pad. Also, a call to activate_pull() needs to propagate through
+source pad. Also, a call to activate_mode(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
+fakesrc ! identity ! fakesink, calling activate_mode(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
+calls activate_mode(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
-source pad should have already had activate_pull() called on it, and
+source pad should have already had activate_mode(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
+which calls activate_mode(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
@@ -81,8 +82,8 @@ 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
+activate_mode(PUSH) or activate_mode(PULL) with a FALSE argument, depending
-activation mode of the pad.
+on the current activation mode of the pad.
 
 Mode switching
 ~~~~~~~~~~~~~~