design: Fix typos, indentions, and assorted improvements. Delete

description of drain event

markdown/additional/design/element-sink.md

@@ -21,7 +21,7 @@ for this is that this way we can detect when the first buffer or event
 arrives in the sink when the state change completes.
 
 A sink should block on the first `EOS` event or buffer received in the
-`READY→PAUSED` state before commiting the state to `PAUSED`.
+`READY→PAUSED` state before committing the state to `PAUSED`.
 
 `FLUSHING` events have to be handled out of sync with the buffer flow and
 take no part in the preroll procedure.
@@ -42,9 +42,9 @@ Events other than `EOS` do not complete the preroll stage.
     switch (pending)
       case PLAYING:
         need_preroll = FALSE
-	break
+        break
       case PAUSED:
-	break
+        break
       case READY:
       case NULL:
         return FALSE
@@ -178,7 +178,7 @@ Events other than `EOS` do not complete the preroll stage.
       break
     SEGMENT:
       # the segment must be used to clip incoming
-      # buffers. Then then go into the queue as non-prerollable
+      # buffers. Then go into the queue as non-prerollable
       # items used for syncing the buffers
       STREAM_LOCK
       PREROLL_LOCK
@@ -234,50 +234,50 @@ Events other than `EOS` do not complete the preroll stage.
       READY_PAUSED:
         # no datapassing is going on so we always return ASYNC
         ret = ASYNC
-	need_commit = TRUE
+        need_commit = TRUE
         eos = FALSE
         flushing = FALSE
-	need_preroll = TRUE
+        need_preroll = TRUE
-	prerolled = FALSE
+        prerolled = FALSE
         break
       PAUSED_PLAYING:
         # we grab the preroll lock. This we can only do if the
-	# chain function is either doing some clock sync, we are
+        # chain function is either doing some clock sync, we are
-	# waiting for preroll or the chain function is not being called.
+        # waiting for preroll or the chain function is not being called.
         PREROLL_LOCK
-	if (prerolled || eos)
+        if (prerolled || eos)
           ret = OK
-	  need_commit = FALSE
+          need_commit = FALSE
-	  need_preroll = FALSE
+          need_preroll = FALSE
-	  if (eos)
+          if (eos)
-	    post_eos
+            post_eos
-	  else
+          else
             PREROLL_SIGNAL
-	else
+        else
-	  need_preroll = TRUE
+          need_preroll = TRUE
-	  need_commit = TRUE
+          need_commit = TRUE
           ret = ASYNC
         PREROLL_UNLOCK
         break
       PLAYING_PAUSED:
                            ---> subclass can interrupt render
         # we grab the preroll lock. This we can only do if the
-	# chain function is either doing some clock sync
+        # chain function is either doing some clock sync
-	# or the chain function is not being called.
+        # or the chain function is not being called.
         PREROLL_LOCK
-	need_preroll = TRUE
+        need_preroll = TRUE
         unlock_clock
-	if (prerolled || eos)
+        if (prerolled || eos)
           ret = OK
-	else
+        else
           ret = ASYNC
         PREROLL_UNLOCK
         break
       PAUSED_READY:
                            ---> subclass can interrupt render
         # we grab the preroll lock. Set to flushing and unlock
-	# everything. This should exit the chain functions and stop
+        # everything. This should exit the chain functions and stop
-	# streaming.
+        # streaming.
         PREROLL_LOCK
         flushing = TRUE
         unlock_clock

markdown/additional/design/events.md

@@ -14,7 +14,7 @@ Different types of events exist to implement various functionalities.
 * `GST_EVENT_CAPS`: Format information about the following buffers
 * `GST_EVENT_SEGMENT`: Timing information for the following buffers
 * `GST_EVENT_TAG`: Stream metadata.
-* `GST_EVENT_BUFFERSIZE`: Buffer size requirements
+* `GST_EVENT_BUFFERSIZE`: Buffer size requirements. Currently not used yet.
 * `GST_EVENT_SINK_MESSAGE`: An event turned into a message by sinks
 * `GST_EVENT_EOS`: no more data is to be expected on a pad.
 * `GST_EVENT_QOS`: A notification of the quality of service of the stream
@@ -24,10 +24,6 @@ Different types of events exist to implement various functionalities.
 * `GST_EVENT_STEP`: Stepping event
 * `GST_EVENT_RECONFIGURE`: stream reconfigure event
 
-- `GST_EVENT_DRAIN`: Play all data downstream before returning.
-  > not yet implemented, under investigation, might be needed to do
-    still frames in DVD.
-
 ## src pads
 
 A `gst_pad_push_event()` on a srcpad will first store the sticky event
@@ -44,7 +40,7 @@ A `gst_pad_send_event()` on a sinkpad will call the event function on
 the pad. If the event function returns success, the sticky event is
 stored in the sticky event array and the event is marked for update.
 
-When the pad is flushing, the `_send_event()` function returns FALSE
+When the pad is flushing, the `gst_pad_send_event()` function returns FALSE
 immediately.
 
 When the next data item is pushed, the pending events are pushed first.
@@ -178,7 +174,6 @@ tagging system. A tag is serialized with buffers.
 ## BUFFERSIZE
 
 > **Note**
->
 > This event is not yet implemented.
 
 An element can suggest a buffersize for downstream elements. This is
@@ -263,20 +258,3 @@ value is calculated by the pipeline and distributed to all sink elements
 before they are set to PLAYING. The sinks will add the configured
 latency value to the timestamps of the buffer in order to delay their
 presentation. (See also [latency](additional/design/latency.md)).
-
-## DRAIN
-
-> **Note**
->
-> This event is not yet implemented.
-
-Drain event indicates that upstream is about to perform a real-time
-event, such as pausing to present an interactive menu or such, and needs
-to wait for all data it has sent to be played-out in the sink.
-
-Drain should only be used by live elements, as it may otherwise occur
-during prerolling.
-
-Usually after draining the pipeline, an element either needs to modify
-timestamps, or FLUSH to prevent subsequent data being discarded at the
-sinks for arriving late (only applies during playback scenarios).