1 files changed, 138 insertions, 0 deletions
diff --git a/subprojects/gstreamer/docs/random/wtay/events b/subprojects/gstreamer/docs/random/wtay/events
new file mode 100644
index 0000000000..09e022ee43
--- /dev/null
+++ b/subprojects/gstreamer/docs/random/wtay/events
@@ -0,0 +1,138 @@
+This is a round up from our IRC session on events. It's open for
+discussion of course.
+
+Definition 
+----------
+
+The event system is designed to be a mechanism for _inter_plugin_
+communication. Their scope is therefore limited in a way that they do
+not serve as a way to communicate between plugins and the app (signals
+and properties are still used for plugin-app communication).
+
+Events will be generated by either a plugin or the app. It should be
+possible for a plugin to generate an event on one of its pads and it
+should be possible for an app to insert an event on an arbitrary pad in
+the pipeline.
+
+
+Event handling 
+--------------
+
+Events can both travel upstream or downstream. Some events, by nature,
+only travel in one direction.
+
+* downstream events
+
+  - Travel in the same way buffers do. This includes that they are handled
+    by the scheduler. The rationale is that the events should be kept
+    as close to the buffers are possible.
+
+  - plugins should check the type of the GstData passed in the _chain
+    or _loop function and act appropriately. This can be done by either
+    doing their own stuff or by calling the default handler.
+
+  - are handled on the sink pad.
+
+* upstream events
+
+  - are handled with an event handler attached to the srcpad. A default
+    handler will be implemented for pads that don't implement their own 
+    handler.
+
+  - travel as fast as possible. the rationale is that a seek event should
+    get to the src element ASAP.
+
+
+Possible candidates for events 
+------------------------------
+
+  - QoS
+   quality of service. Plugins can notify other plugins about the quality
+   of the pipeline. A video element can for example say that it receives
+   too much frames and that plugins connected to it need to slow down.
+
+  - EOS
+   A plugin can notify other plugins that it has run out-of-data.
+
+  - Seek
+   Used to notify plugins that they need to seek to a certain byte offset
+   or timestamp.
+
+  - discontinuous
+   A plugin has detected a discontinuity in the stream. Other plugins
+   might need to resync.
+
+  - flush
+   Plugins need to get rid of any buffered data ASAP.
+
+  - caps nego??  
+  - bufferpool get??  
+  - ...
+
+
+application generated events 
+----------------------------
+
+The application can insert events into the pipeline at arbitrary
+places. This will be done by calling gst_pad_event() on a pad.
+
+A first implementation will only cover inserting events on src pads
+since inserting events on sinkpads needs changes to the scheduler.
+
+
+Effects of events on plugins 
+----------------------------
+
+some events are going to change the state of an element. The EOS event
+will for example change the state of an element to the PAUSED state. Not
+sure when or how this will happen.
+
+
+use cases 
+---------
+
+1) filesrc ! fakesink
+
+filesrc will read until it reaches EOF. It will then create a GstEvent
+of type EOS and return it in the _get function. The event will travel
+downstream and will reach the fakesink element. Fakesink will detect
+the event in the _chain function and will call the default handler. The
+default handler will set the element to the paused state. filesrc will
+eventually change its state to PAUSED, probably before sending out the
+event (TBD)
+
+2) filesrc ! fakesink
+
+The app wants to perform a seek on filesrc. It'll call the gst_pad_event()
+on filesrcs src pad with the SEEK event type. The event handler will
+react and change filesrcs internal status. filesrc will return a DISCONT
+event before returning the buffer with the new offset.
+
+3) filesrc ! mpeg2parse video_0! queue ! { mpeg2dec ! xvideosink }
+
+lost of possibilities here: The app can choose to insert a seek event
+on the filesrc element (byte offset), it can insert a byte/time offset
+seek on the video_0 pad of mpeg2parse or it can insert a time seek event
+on mpeg2decs src pad.
+
+the event will travel upstream using the handlers and the intermediate
+elements can convert the event from a time to a byte offset (possibly
+using GstTimeCache to speed up things).
+
+Filesrc will get a byte seek event on its src pad and will proceed as
+in case 2.
+
+As can be seen from this example the app will generate an event in another
+context than those of the plugins, so this will need proper locking.
+
+The app can also choose to insert a flush event on one of the src
+pads. The plugins would clear their cached data and forward the event
+to their upstream peer pad(s).
+
+4)...
+
+Insert impossible case here..
+
+
+
+