From 3ac5605ac470573eb9fb1b700a3e7a567c967de3 Mon Sep 17 00:00:00 2001 From: Wim Taymans Date: Thu, 30 May 2002 19:05:05 +0000 Subject: [PATCH] Added first draf of current events code. Original commit message from CVS: Added first draf of current events code. --- docs/random/wtay/events3 | 248 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 248 insertions(+) create mode 100644 docs/random/wtay/events3 diff --git a/docs/random/wtay/events3 b/docs/random/wtay/events3 new file mode 100644 index 0000000000..a6773fa1f3 --- /dev/null +++ b/docs/random/wtay/events3 @@ -0,0 +1,248 @@ +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 abitrary 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. + +* NEW_MEDIA + + The new media event is typically generated by source elements when + they provide data of a new type. + <<< define me >>> + + The NEW_MEDIA 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 DISCONTINOUS 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.. + + + +