docs/random/wtay/events

   1 This is a round up from our IRC session on events. It's open for
   2 discussion of course.
   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 in
  15 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 will be 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 Possible candidates for events
  47 ------------------------------
  48
  49   - QoS
  50    quality of service. Plugins can notify other plugins about the quality
  51    of the pipeline. A video element can for example say that it receives
  52    too much frames and that plugins connected to it need to slow down.
  53
  54   - EOS
  55    A plugin can notify other plugins that it has run out-of-data.
  56
  57   - Seek
  58    Used to notify plugins that they need to seek to a certain byte offset
  59    or timestamp.
  60
  61   - discontinuous
  62    A plugin has detected a discontinuity in the stream. Other plugins
  63    might need to resync.
  64
  65   - flush
  66    Plugins need to get rid of any buffered data ASAP.
  67
  68   - caps nego??
  69   - bufferpool get??
  70   - ...
  71
  72
  73 application generated events
  74 ----------------------------
  75
  76 The application can insert events into the pipeline at arbirary
  77 places. This will be done by calling gst_pad_event() on a pad.
  78
  79 A first implementation will only cover inserting events on src pads
  80 since inserting events on sinkpads needs changes to the scheduler.
  81
  82
  83 Effects of events on plugins
  84 ----------------------------
  85
  86 some events are going to change the state of an element. The EOS event
  87 will for example change the state of an element to the PAUSED state. Not
  88 sure when or how this will happen.
  89
  90
  91 use cases
  92 ---------
  93
  94 1) filesrc ! fakesink
  95
  96 filesrc will read until it reaches EOF. It will then create a GstEvent
  97 of type EOS and return it in the _get function. The event will travel
  98 downstream and will reach the fakesink element. Fakesink will detect
  99 the event in the _chain function and will call the default handler. The
 100 default handler will set the element to the paused state. filesrc will
 101 eventually change its state to PAUSED, probably before sending out the
 102 event (TBD)
 103
 104 2) filesrc ! fakesink
 105
 106 The app wants to perform a seek on filesrc. It'll call the gst_pad_event()
 107 on filesrcs src pad with the SEEK event type. The event handler will
 108 react and change filesrcs internal status. filesrc will return a DISCONT
 109 event before returning the buffer with the new offset.
 110
 111 3) filesrc ! mpeg2parse video_0! queue ! { mpeg2dec ! xvideosink }
 112
 113 lost of possibilities here: The app can choose to insert a seek event
 114 on the filesrc element (byte offset), it can insert a byte/time offset
 115 seek on the video_0 pad of mpeg2parse or it can insert a time seek event
 116 on mpeg2decs src pad.
 117
 118 the event will travel upstream using the handlers and the intermediate
 119 elements can convert the event from a time to a byte offset (possibly
 120 using GstTimeCache to speed up things).
 121
 122 Filesrc will get a byte seek event on its src pad and will proceed as
 123 in case 2.
 124
 125 As can be seen from this example the app will generate an event in another
 126 context than those of the plugins, so this will need proper locking.
 127
 128 The app can also choose to insert a flush event on one of the src
 129 pads. The plugins would clear their cached data and forward the event
 130 to their upstream peer pad(s).
 131
 132 4)...
 133
 134 Insert impossible case here..
 135
 136
 137
 138