mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-11-26 19:51:11 +00:00
Added first draf of current events code.
Original commit message from CVS: Added first draf of current events code.
This commit is contained in:
Wim Taymans
parent
a599a5b1df
commit
3ac5605ac4
1 changed files with 248 additions and 0 deletions
248
docs/random/wtay/events3
Normal file
248
docs/random/wtay/events3
Normal file
|
|
@ -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..
|
||||
|
||||
|
||||
|
||||
|
||||
Loading…
Reference in a new issue