1 This is a round up from our IRC session on events. It's open for
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).
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 abitrary pad in
21 Events can both travel upstream or downstream. Some events, by nature,
22 only travel in one direction.
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.
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.
34 - are handled on the sink pad.
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
42 - travel as fast as possible. the rationale is that a seek event should
43 get to the src element ASAP.
46 Possible candidates for events
47 ------------------------------
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.
55 A plugin can notify other plugins that it has run out-of-data.
58 Used to notify plugins that they need to seek to a certain byte offset
62 A plugin has detected a discontinuity in the stream. Other plugins
66 Plugins need to get rid of any buffered data ASAP.
73 application generated events
74 ----------------------------
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.
79 A first implementation will only cover inserting events on src pads
80 since inserting events on sinkpads needs changes to the scheduler.
83 Effects of events on plugins
84 ----------------------------
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.
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
104 2) filesrc ! fakesink
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.
111 3) filesrc ! mpeg2parse video_0! queue ! { mpeg2dec ! xvideosink }
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.
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).
122 Filesrc will get a byte seek event on its src pad and will proceed as
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.
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).
134 Insert impossible case here..