docs/random/wtay/events3

   1 This is the current implementation of events, based on an earlier
   2 document, in this same directory, called "events".
   3
   4 Definition
   5 ----------
   6
   7 The event system is designed to be a mechanism for _inter_plugin_
   8 communication. Their scope is therefore limited in a way that they do
   9 not serve as a way to communicate between plugins and the app (signals
  10 and properties are still used for plugin-app communication).
  11
  12 Events will be generated by either a plugin or the app. It should be
  13 possible for a plugin to generate an event on one of its pads and it
  14 should be possible for an app to insert an event on an arbitrary pad or
  15 element in the pipeline.
  16
  17
  18 Event handling
  19 --------------
  20
  21 Events can both travel upstream or downstream. Some events, by nature,
  22 only travel in one direction.
  23
  24 * downstream events
  25
  26   - Travel in the same way buffers do. This includes that they are handled
  27     by the scheduler. The rationale is that the events should be kept
  28     as close to the buffers are possible.
  29
  30   - plugins should check the type of the GstData passed in the _chain
  31     or _loop function and act appropriatly. This can be done by either
  32     doing their own stuff or by calling the default handler.
  33
  34   - are handled on the sink pad.
  35
  36 * upstream events
  37
  38   - are handled with an event handler attached to the srcpad. A default
  39     handler is implemented for pads that don't implement their own
  40     handler.
  41
  42   - travel as fast as possible. the rationale is that a seek event should
  43     get to the src element ASAP.
  44
  45
  46
  47 Plugin generated events
  48 -----------------------
  49
  50 We cover the range of events a plugin can generate and how they
  51 are supposed to handle them.
  52
  53 * EOS
  54
  55   when the plugin has no more data to push, it pushes an EOS
  56   event and calls gst_element_set_eos.
  57
  58   _get based plugins should call gst_element_set_eos() before
  59   returning the EOS event.
  60
  61   gst_element_set_eos() will put an element into the PAUSED state
  62   and will emit the eos signal to the app.
  63
  64   Elements receiving the EOS event on a pad should not pull anymore
  65   data from that pad (in case of a loop based element).
  66   If the plugin cannot operate when it doesn't receive data on that
  67   pad, the element should go to EOS too. It does this by pushing
  68   any data it might still have, to the srcpad after which it
  69   pushes an EOS event on thet pad and calls gst_element_set_eos().
  70
  71   The EOS event will typically originate from a source element, it
  72   will eventually put all elements into the PAUSED state so that the
  73   pipeline stops.
  74
  75   The EOS event is strictly a downstream event.
  76
  77 * DISCONTINUOUS
  78
  79   The discontinuous event is used to indicate a discontinuity in the
  80   stream to downstream elements.  A disctontinuity happens for the
  81   following reasons:
  82
  83    - a source element is sending the first buffers of a stream.
  84    - an element has performed a seek operation resulting in a
  85      discontinuity in the data.
  86
  87   elements that receive a discontinuity event should flush any state
  88   they might have and treat the new data as the start of new data.
  89   Before sending out the new data the element must send a discont event
  90   to the downstream element with at least a GST_FORMAT_TIME or
  91   GST_FORMAT_BYTES as the format/value pair (see below).
  92
  93   a DISCONTINUOUS event has a flush flag. If that flag is set, the
  94   element should also remove any buffered data it might have.
  95
  96   In addition to the flush flag, a DISCONTINUOUS event also caries up
  97   to GST_DISCONTINUOUS_MAX_FORMATS format/value pairs. These values
  98   might be used by the receiver of the event to resynchronize itself.
  99
 100   elements that are using a clock must take special actions upon
 101   receiving the DISCONTINUOUS event: they must call
 102   gst_clock_handle_discont() with the GST_FORMAT_TIME value of
 103   the discont event.
 104
 105   The DISCONTINUOUS event is strictly a downstream event.
 106
 107
 108 * SEEK
 109
 110   The seek event is used to reposition  the upstream elements to
 111   a new position in the media stream.
 112
 113   The seek event caries a bitwise-or of a GstFormat and a GstSeekType.
 114
 115   An element receiving the seek event on its srcpad should try to
 116   reposition itself as closely to the requested location as possible.
 117   if the ACCURATE flag is set and it cannot reposition itself with
 118   absolute certainty, it should reposition itself well before the
 119   requested position. If the ACCURATE flag is not set, the element
 120   is free to choose a suitable position in the stream before or after
 121   the requested time.
 122
 123   If the flush flag is set it should make sure that it pushes the
 124   DISCONTINUOUS event the next time it is scheduled, clearing any
 125   data it might have buffered.
 126
 127   The element is free to set the ACCURACY field in the event to notify
 128   the originator of the event of the result. If no accuracy is set, it
 129   defaults to FUZZY.
 130
 131   The SEEK event is stricly an upstream event.
 132
 133 * QOS
 134
 135   QoS is sent to indicate Quality of Service to the upstream element(s).
 136
 137   The QOS event is stricly an upstream event.
 138
 139 * FLUSH
 140
 141   A plugin can send a flush event to its src or sink peer to clear the
 142   buffered contents in the pipeline.
 143
 144
 145 application generated events
 146 ----------------------------
 147
 148 The application can insert events into the pipeline at arbirary
 149 places. This is done by calling gst_pad_send_event() on a pad.
 150
 151 An application can also insert events on any element. The element
 152 can implement its own handler for these events or it can use
 153 the default handler, which simply forwards the event to the first
 154 connected sinkpad of the element. Events to an element are send using
 155 gst_element_send_event().
 156
 157 This first implementation only covers inserting events on src pads
 158 since inserting events on sinkpads needs changes to the scheduler.
 159
 160
 161 * FLUSH
 162
 163   A flush event is used to clear any buffered data an element might
 164   have. It is a downstream and upstream event.
 165
 166   Flush events are typically inserted into the pipeline by the app.
 167   Elements that buffer data should implement an event handler on
 168   both the sink and src pads it might have and respond to the flush
 169   event by clearing all data they have buffered.
 170
 171 * SEEK
 172
 173   The application can insert the seek event into the pipeline on
 174   a srcpad with gst_pad_send_event () or on an element with
 175   gst_element_send_event().
 176
 177   The semantics of the seek parameters are described above.
 178
 179
 180 Thread safety
 181 -------------
 182
 183 All upstream events can occur outside the element's thread context.
 184 It is not required to protect the element's data structures with
 185 mutexes because in principal we don't support sending events to
 186 a running threaded pipeline.
 187
 188 GstQueue in its current form will refuse to pass events upstream if
 189 it is in the PLAYING state. Future versions might pass the event
 190 on as soon as the element is scheduled again on the sinkpad.
 191
 192 An application cannot insert an event on an element that is PLAYING
 193 in another thread context. It is therefore strongly recommended to
 194 PAUSE the threaded pipeline before inserting an event.
 195
 196
 197 use cases
 198 ---------
 199
 200 1) filesrc ! fakesink
 201
 202 << explain EOS >>
 203
 204
 205 2) filesrc ! fakesink
 206
 207 The app wants to perform a seek on filesrc. It'll call the gst_pad_send_event()
 208 on filesrcs src pad with the SEEK event type. The event handler will
 209 react and change filesrcs internal status. filesrc will return a DISCONT
 210 event before returning the buffer with the new offset.
 211
 212 3) filesrc ! mpeg2parse video_0! queue ! { mpeg2dec ! xvideosink }
 213
 214 lost of possibilities here: The app can choose to insert a seek event
 215 on the filesrc element (byte offset), it can insert a byte/time offset
 216 seek on the video_0 pad of mpeg2parse or it can insert a time seek event
 217 on mpeg2decs src pad.
 218
 219 the event will travel upstream using the handlers and the intermediate
 220 elements can convert the event from a time to a byte offset (possibly
 221 using GstTimeCache to speed up things).
 222
 223 Filesrc will get a byte seek event on its src pad and will proceed as
 224 in case 2.
 225
 226 As can be seen from this example the app will generate an event in another
 227 context than those of the plugins, so this will need proper locking.
 228
 229 The app can also choose to insert a flush event on one of the src
 230 pads. The plugins would clear their cached data and forward the event
 231 to their upstream peer pad(s).
 232
 233 4)...
 234
 235 Insert impossible case here..
 236
 237
 238
 239