diff --git a/ChangeLog b/ChangeLog index df0e2c0f2e..fef207cd57 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,17 @@ +2004-02-02 Ronald Bultje + + * docs/pwg/advanced-events.xml: + * docs/pwg/advanced-scheduling.xml: + * docs/pwg/intro-basics.xml: + * docs/pwg/other-manager.xml: + * docs/pwg/other-nton.xml: + * docs/pwg/other-ntoone.xml: + * docs/pwg/other-oneton.xml: + * docs/pwg/pwg.xml: + All sort of documentation... Forgot what. Point is that I want this + in before I leave. The 'other-*' will be the last section and will + explain issues specific to these type of elements. + 2004-02-02 Benjamin Otte * gst/elements/gstfilesrc.c: (gst_filesrc_map_region), diff --git a/docs/pwg/advanced-events.xml b/docs/pwg/advanced-events.xml index df7c77e7f4..3a63f20cd7 100644 --- a/docs/pwg/advanced-events.xml +++ b/docs/pwg/advanced-events.xml @@ -21,7 +21,7 @@ gst_pad_event_default. Here is an example for both loop and chain based elements. - /* Chain based element */ static void gst_my_filter_chain (GstPad *pad, @@ -71,7 +71,7 @@ gst_my_filter_loop (GstElement *element) } ... } - ]]> + Upstream events @@ -131,9 +131,10 @@ gst_my_filter_loop (GstElement *element) Here is an example of correct upstream event handling for a plugin that wants to modify navigation events. - static gboolean -gst_my_plugin_handle_src_event (GstPad *pad, GstEvent *event) +gst_my_filter_handle_src_event (GstPad *pad, + GstEvent *event) { GstMyFilter *filter = GST_MY_FILTER (gst_pad_get_parent (pad)); @@ -149,6 +150,265 @@ gst_my_plugin_handle_src_event (GstPad *pad, GstEvent *event) return gst_pad_event_default (pad, event); } } - ]]> + + + + + All Events Together + + In this chapter follows a list of all defined events that are currently + being used, plus how they should be used/interpretted. Events are stored + in a GstEvent structure, which is simply a big + C union with the types for each event in it. For the next development + cycle, we intend to switch events over to GstStructure, + but you don't need to worry about that too much for now. + + + In this chapter, we will discuss the following events: + + + + + + + + + + + + + + End of Stream (EOS) + + End-of-stream events are sent if the stream that an element sends out + is finished. An element receiving this event (from upstream, so it + receives it on its sinkpad) will generally forward the event further + downstream and set itself to EOS (gst_element_set_eos ()). + gst_pad_event_default () takes care of all this, + so most elements do not need to support this event. Exceptions are + elements that explicitely need to close a resource down on EOS, and + N-to-1 elements. Note that the stream itself is not + a resource that should be closed down on EOS! Applications might seek + back to a point before EOS and set the pipeline to PLAYING again. + N-to-1 elements have been discussed previously in + . + + + The EOS event (GST_EVENT_EOS) has no properties, + and that makes it one of the simplest events in &GStreamer;. It is + created using gst_event_new (GST_EVENT_EOS);. + + + Some elements support the EOS event upstream, too. This signals the + element to go into EOS as soon as possible and signal the EOS event + forward downstream. This is useful for elements that have no concept + of end-of-stream themselves. Examples are TV card sources, audio card + sources, etc. This is not (yet) part of the official specifications of + this event, though. + + + + + Flush + + The flush event is being sent downstream if all buffers and caches + in the pipeline should be emptied. Queue elements will + empty their internal list of buffers when they receive this event, for + example. File sink elements (e.g. filesink) will flush + the kernel-to-disk cache (fdatasync () or + fflush ()) when they receive this event. Normally, + elements receiving this event will simply just forward it, since most + filter or filter-like elements don't have an internal cache of data. + gst_pad_event_default () does just that, so for + most elements, it is enough to forward the event using the default + event handler. + + + The flush event is created with gst_event_new (GST_EVENT_FLUSH);. + Like the EOS event, it has no properties. + + + + + Stream Discontinuity + + A discontinuity event is sent downstream to indicate a discontinuity in + the data stream. This can happen because the application used the seek + event to seek to a different position in the stream, but it can also be + because a real-time network source temporarily lost the connection. + After the connection is restored, the data stream will continue, but + not at the same point where it got lost. Therefore, a discontinuity + event is being sent downstream, too. + + + Depending on the element type, the event can simply be forwarded using + gst_pad_event_default (), or it should be parsed + and a modified event should be sent on. The last is true for demuxers, + which generally have a byte-to-time conversion concept. Their input + is usually byte-based, so the incoming event will have an offset in + byte units (GST_FORMAT_BYTES), too. Elements + downstream, however, expect discontinuity events in time units, so that + it can be used to update the pipeline clock. Therefore, demuxers and + similar elements should not forward the event, but parse it, free it + and send a new discontinuity event (in time units, + GST_FORMAT_TIME) further downstream. + + + The discontinuity event is created using the function + gst_event_new_discontinuous (). It should set a + boolean value which indicates if the discontinuity event is sent + because of a new media type (this can happen if - during iteration - + a new location was set on a network source or on a file source). + then, it should give a list of formats and offsets in that format. The + list should be terminated by 0 as format. + + +static void +my_filter_some_function (GstMyFilter *filter) +{ + GstEvent *event; +[..] + event = gst_event_new_discontinuous (FALSE, + GST_FORMAT_BYTES, 0, + GST_FORMAT_TIME, 0, + 0); + gst_pad_push (filter->srcpad, GST_DATA (event)); +[..] +} + + + Elements parsing this event can use macros and functions to access the + various properties. GST_EVENT_DISCONT_NEW_MEDIA (event) + checks the new-media boolean value. + gst_event_discont_get_value (event, format, &value) + gets the offset of the new stream position in the specified format. If + that format was not specified when creating the event, the function + returns FALSE. + + + + + Seek Request + + Seek events are meant to request a new stream position to elements. + This new position can be set in several formats (time, bytes or + units [a term indicating frames for video, samples for + audio, etc.]). Seeking can be done with respect to the end-of-file, + start-of-file or current position, and can happen in both upstream and + downstream direction. Elements receiving seek events should, depending + on the element type, either forward it (filters, decoders), change the + format in which the event is given and forward it (demuxers), handle + the event by changing the file pointer in their internal stream + resource (file sources) or something else. + + + Seek events are, like discontinuity events, built up using positions in + specified formats (time, bytes, units). They are created using the + function gst_event_new_seek (), where the first + argument is the seek type (indicating with respect to which position + [current, end, start] the seek should be applied, and the format in + which the new position is given (time, bytes, units), and an offset + which is the requested position in the specified format. + + +static void +my_filter_some_function (GstMyFilter *filter) +{ + GstEvent *event; +[..] + /* seek to the start of a resource */ + event = gst_event_new_seek (GST_SEEK_SET | GST_FORMAT_BYTES, 0); + gst_pad_push (filter->srcpad, GST_DATA (event)); +[..] +} + + + Elements parsing this event can use macros and functions to access the + properties. The seek type can be retrieved using + GST_EVENT_SEEK_TYPE (event). This seek type + contains both the indicator of with respect to what position the seek + should be applied, and the format in which the seek event is given. + To get either one of these properties separately, use + GST_EVENT_SEEK_FORMAT (event) or + GST_EVENT_SEEK_METHOD (event). The requested + position is available through GST_EVENT_SEEK_OFFSET (event), + and is given in the specified format. + + + + + Stream Filler + + The filler event is, as the name says, a filler of the + stream which has no special meaning associated with itself. It is used + to provide data to downstream elements and should be interpreted as a + way of assuring that the normal data flow will continue further + downstream. The event is especially intended for real-time MIDI source + elements, which only generate data when something changes. + MIDI decoders will therefore stall if nothing changes for several + seconds, and therefore playback will stop. The filler event is sent + downstream to assure the MIDI decoder that nothing changed, so that the + normal decoding process will continue and playback will, too. Unless + you intend to work with MIDI or other control-language-based data + types, you don't need this event. You can mostly simply forward it + with gst_pad_event_default (). + + + The stream filler is created using gst_event_new (GST_EVENT_FILLER);. + It has no properties. + + + + + Interruption + + The interrupt event is generated by queue elements and sent downstream + if a timeout occurs on the stream. The scheduler will use this event to + get back in its own main loop and schedule other elements. This + prevents deadlocks or a stream stall if no data is generated over a + part of the pipeline for a considerable amount of time. The scheduler + will process this event internally, so any normal elements do not need + to generate or handle this event at all. + + + The difference between the filler event and the interrupt event is that + the filler event is a real part of a pipeline, so it will reach fellow + elements, which can use it to "do nothing else than what I used to do". + The interrupt event never reaches fellow elements. + + + The interrupt event (gst_event_new (GST_EVENT_INTERRUPT);) + has no properties. + + + + + Navigation + + WRITEME + + + + + Tag (metadata) + + Tagging events are being sent downstream to indicate the tags as parsed + from the stream data. This is currently used to preserve tags during + stream transcoding from one format to the other. Tags are discussed + extensively in . Most + elements will simply forward the event by calling + gst_pad_event_default (). + + + The tag event is created using the function + gst_event_new_tag (). It requires a filled + taglist as argument. + + + Elements parsing this event can use the function + gst_event_tag_get_list (event) to acquire the + taglist that was parsed. + + diff --git a/docs/pwg/advanced-scheduling.xml b/docs/pwg/advanced-scheduling.xml index a6dafa0951..6cd1593e6f 100644 --- a/docs/pwg/advanced-scheduling.xml +++ b/docs/pwg/advanced-scheduling.xml @@ -365,7 +365,7 @@ gst_my_filter_change_state (GstElement *element) Adding a second output - Identity is now a tee + WRITEME diff --git a/docs/pwg/intro-basics.xml b/docs/pwg/intro-basics.xml index 60277e1f22..df41f790f5 100644 --- a/docs/pwg/intro-basics.xml +++ b/docs/pwg/intro-basics.xml @@ -184,6 +184,11 @@ + + Events will be discussed extensively in . + Until then, the only event that will be used is the EOS + event, which is used to indicate the end-of-stream (usually end-of-file). + See the &GstLibRef; for the current implementation details of a + + + Writing a Manager + + FIXME: write. + + diff --git a/docs/pwg/other-nton.xml b/docs/pwg/other-nton.xml new file mode 100644 index 0000000000..17d2b8d803 --- /dev/null +++ b/docs/pwg/other-nton.xml @@ -0,0 +1,8 @@ + + + + Writing a N-to-N element + + FIXME: write. + + diff --git a/docs/pwg/other-ntoone.xml b/docs/pwg/other-ntoone.xml new file mode 100644 index 0000000000..82f40fe866 --- /dev/null +++ b/docs/pwg/other-ntoone.xml @@ -0,0 +1,16 @@ + + + + + Writing a N-to-1 Element + + FIXME: write. + + + + Writing a Muxer + + WRITEME + + + diff --git a/docs/pwg/other-oneton.xml b/docs/pwg/other-oneton.xml new file mode 100644 index 0000000000..95fa28cb37 --- /dev/null +++ b/docs/pwg/other-oneton.xml @@ -0,0 +1,16 @@ + + + + + Writing a 1-to-N element + + FIXME: write. + + + + Writing a Demuxer + + WRITEME + + + diff --git a/docs/pwg/pwg.xml b/docs/pwg/pwg.xml index 791e76b1f5..1af2efb88d 100644 --- a/docs/pwg/pwg.xml +++ b/docs/pwg/pwg.xml @@ -31,7 +31,11 @@ + + + + @@ -120,6 +124,12 @@ Advanced Filter Concepts + By now, you should be able to create basic filter elements that can + receive and send data. This is the simple model that &GStreamer; stands + for. But &GStreamer; can do much more than only this! In this chapter, + various advanced topics will be discussed, such as scheduling, special + pad types, clocking, events, interfaces, tagging and more. These topics + are the sugar that makes &GStreamer; so easy to use for applications. @@ -140,12 +150,24 @@ Other Element Types + By now, we have looked at pretty much any feature that can be embedded + into a &GStreamer; element. However, we have limited ourselves to the + simple model of a filter element. In this chapter, we will look at the + specific difficulties and things to keep in mind when writing specific + types of elements. We will discuss output elements (sinks), input + elements (sources), 1-to-N elements, N-to-1 elements, N-to-N elements, + autopluggers and managers. Some of these represent elements that don't + actually exist. Rather, they represent a general concept. &OTHER_SOURCE; &OTHER_SINK; + &OTHER_ONETON; + &OTHER_NTOONE; + &OTHER_NTON; &OTHER_AUTOPLUGGER; + &OTHER_MANAGER; @@ -154,6 +176,7 @@ Appendices + This chapter contains things that don't belong anywhere else.