| This is the current implementation of events, based on an earlier | |
| document, in this same directory, called "events". | |
| 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 or | |
| element 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 appropriatly. 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 is 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. | |
| Plugin generated events | |
| ----------------------- | |
| We cover the range of events a plugin can generate and how they | |
| are supposed to handle them. | |
| * EOS | |
| when the plugin has no more data to push, it pushes an EOS | |
| event and calls gst_element_set_eos. | |
| _get based plugins should call gst_element_set_eos() before | |
| returning the EOS event. | |
| gst_element_set_eos() will put an element into the PAUSED state | |
| and will emit the eos signal to the app. | |
| Elements receiving the EOS event on a pad should not pull anymore | |
| data from that pad (in case of a loop based element). | |
| If the plugin cannot operate when it doesn't receive data on that | |
| pad, the element should go to EOS too. It does this by pushing | |
| any data it might still have, to the srcpad after which it | |
| pushes an EOS event on thet pad and calls gst_element_set_eos(). | |
| The EOS event will typically originate from a source element, it | |
| will eventually put all elements into the PAUSED state so that the | |
| pipeline stops. | |
| The EOS event is strictly a downstream event. | |
| * DISCONTINUOUS | |
| The discontinuous event is used to indicate a discontinuity in the | |
| stream to downstream elements. A disctontinuity happens for the | |
| following reasons: | |
| - a source element is sending the first buffers of a stream. | |
| - an element has performed a seek operation resulting in a | |
| discontinuity in the data. | |
| elements that receive a discontinuity event should flush any state | |
| they might have and treat the new data as the start of new data. | |
| Before sending out the new data the element must send a discont event | |
| to the downstream element with at least a GST_FORMAT_TIME or | |
| GST_FORMAT_BYTES as the format/value pair (see below). | |
| a DISCONTINUOUS event has a flush flag. If that flag is set, the | |
| element should also remove any buffered data it might have. | |
| In addition to the flush flag, a DISCONTINUOUS event also caries up | |
| to GST_DISCONTINUOUS_MAX_FORMATS format/value pairs. These values | |
| might be used by the receiver of the event to resynchronize itself. | |
| elements that are using a clock must take special actions upon | |
| receiving the DISCONTINUOUS event: they must call | |
| gst_clock_handle_discont() with the GST_FORMAT_TIME value of | |
| the discont event. | |
| The DISCONTINUOUS event is strictly a downstream event. | |
| * SEEK | |
| The seek event is used to reposition the upstream elements to | |
| a new position in the media stream. | |
| The seek event caries a bitwise-or of a GstFormat and a GstSeekType. | |
| An element receiving the seek event on its srcpad should try to | |
| reposition itself as closely to the requested location as possible. | |
| if the ACCURATE flag is set and it cannot reposition itself with | |
| absolute certainty, it should reposition itself well before the | |
| requested position. If the ACCURATE flag is not set, the element | |
| is free to choose a suitable position in the stream before or after | |
| the requested time. | |
| If the flush flag is set it should make sure that it pushes the | |
| DISCONTINUOUS event the next time it is scheduled, clearing any | |
| data it might have buffered. | |
| The element is free to set the ACCURACY field in the event to notify | |
| the originator of the event of the result. If no accuracy is set, it | |
| defaults to FUZZY. | |
| The SEEK event is stricly an upstream event. | |
| * QOS | |
| QoS is sent to indicate Quality of Service to the upstream element(s). | |
| The QOS event is stricly an upstream event. | |
| * FLUSH | |
| A plugin can send a flush event to its src or sink peer to clear the | |
| buffered contents in the pipeline. | |
| application generated events | |
| ---------------------------- | |
| The application can insert events into the pipeline at arbirary | |
| places. This is done by calling gst_pad_send_event() on a pad. | |
| An application can also insert events on any element. The element | |
| can implement its own handler for these events or it can use | |
| the default handler, which simply forwards the event to the first | |
| connected sinkpad of the element. Events to an element are send using | |
| gst_element_send_event(). | |
| This first implementation only covers inserting events on src pads | |
| since inserting events on sinkpads needs changes to the scheduler. | |
| * FLUSH | |
| A flush event is used to clear any buffered data an element might | |
| have. It is a downstream and upstream event. | |
| Flush events are typically inserted into the pipeline by the app. | |
| Elements that buffer data should implement an event handler on | |
| both the sink and src pads it might have and respond to the flush | |
| event by clearing all data they have buffered. | |
| * SEEK | |
| The application can insert the seek event into the pipeline on | |
| a srcpad with gst_pad_send_event () or on an element with | |
| gst_element_send_event(). | |
| The semantics of the seek parameters are described above. | |
| Thread safety | |
| ------------- | |
| All upstream events can occur outside the element's thread context. | |
| It is not required to protect the element's data structures with | |
| mutexes because in principal we don't support sending events to | |
| a running threaded pipeline. | |
| GstQueue in its current form will refuse to pass events upstream if | |
| it is in the PLAYING state. Future versions might pass the event | |
| on as soon as the element is scheduled again on the sinkpad. | |
| An application cannot insert an event on an element that is PLAYING | |
| in another thread context. It is therefore strongly recommended to | |
| PAUSE the threaded pipeline before inserting an event. | |
| use cases | |
| --------- | |
| 1) filesrc ! fakesink | |
| << explain EOS >> | |
| 2) filesrc ! fakesink | |
| The app wants to perform a seek on filesrc. It'll call the gst_pad_send_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.. | |