docs/random/wtay/events3 - mtk-gstreamer - Git at Google

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