--- /dev/null
+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..
+
+
+
+
projects / platform / upstream / gstreamer.git / commitdiff