| 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 appropriately. 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 arbitrary |
| 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 |
|