Commit 84770e84 authored by Wim Taymans's avatar Wim Taymans

Various documentation updates.

Original commit message from CVS:
* docs/design/part-events.txt:
* docs/design/part-gstbus.txt:
* docs/design/part-gstpipeline.txt:
* docs/design/part-messages.txt:
* docs/design/part-overview.txt:
* docs/design/part-segments.txt:
* gst/gstbin.c:
* gst/gstbuffer.c:
* gst/gstclock.c:
* gst/gstelement.c:
* gst/gstevent.c:
* gst/gstfilter.c:
* gst/gstiterator.c:
Various documentation updates.
parent be19f39e
2005-09-24 Wim Taymans <wim@fluendo.com>
* docs/design/part-events.txt:
* docs/design/part-gstbus.txt:
* docs/design/part-gstpipeline.txt:
* docs/design/part-messages.txt:
* docs/design/part-overview.txt:
* docs/design/part-segments.txt:
* gst/gstbin.c:
* gst/gstbuffer.c:
* gst/gstclock.c:
* gst/gstelement.c:
* gst/gstevent.c:
* gst/gstfilter.c:
* gst/gstiterator.c:
Various documentation updates.
2005-09-24 Thomas Vander Stichele <thomas at apestaart dot org>
* gst/gstclock.h:
......
......@@ -66,6 +66,10 @@ The downstream element should forward the EOS event to its downstream peer
elements. This way the event will eventually reach the renderers which should
then post an EOS message on the bus.
An element might want to flush its internally queued data before forwarding
the EOS event downstream. This flushing can be done in the same thread as
the one handling the EOS event.
For elements with multiple sink pads it might be possible to wait for EOS on
all the pads before forwarding the event.
......
......@@ -10,7 +10,8 @@ different threads. This is important since the actual streaming of media
is done in another thread than the application.
The GstBus provides support for GSource based notifications. This makes it
possible to handle the delivery in the glib mainloop.
possible to handle the delivery in the glib mainloop. Different GSources
can be added to the same bin provided they listen to different message types.
A message is posted on the bus with the gst_bus_post() method. With the
gst_bus_peek() and _pop() methods one can look at or retrieve a previously
......@@ -27,9 +28,11 @@ possible to react to a message in the same thread that posted the
message on the bus. This should only be used if the application is able
to deal with messages from different threads.
If no messages are popped from the bus with either a GSource or gst_bus_pop(),
they remain on the bus.
When a pipeline or bin goes from READY into NULL state, it will set its bus
to flushing, ie. the bus will drop all existing and new messages on the bus,
This is necessary because bus messages hold references to the bin/pipeline
or its elements, so there are circular references that need to be broken if
one ever wants to be able to destroy a bin or pipeline properly.
......@@ -4,6 +4,8 @@ GstPipeline
A GstPipeline is usually a toplevel bin an provides all of its
children with a clock.
A GstPipeline also provides a toplevel GstBus (see part-gstbus.txt)
The pipeline also calculates the stream time based on the selected
clock (see part-clocks.txt).
......
......@@ -73,3 +73,14 @@ Message types
An element posted an application specific message.
GST_MESSAGE_SEGMENT_START:
An element started playback of a new segment. This message is not forwarded
the the application but is used internally to scheduler SEGMENT_DONE messages.
GST_MESSAGE_SEGMENT_DONE:
An element or bin completed playback of a segment. This message is only posted
on the bus if a SEGMENT seek is performed on a pipeline.
......@@ -465,7 +465,7 @@ Pipeline seeking
always stop because of step 1).
3) perform the seek operation
4) send a FLUSH done event to all downstream and upstream peer elements.
5) send DISCONT event to inform all elements of the new position and to complete
5) send NEWSEGMENT event to inform all elements of the new position and to complete
the seek.
In step 1) all dowstream elements have to return from any blocking operations
......@@ -509,7 +509,7 @@ Pipeline seeking
| 2) stop streaming
| 3) perform seek
--------------------------> 4) FLUSH done event
--------------------------> 5) DISCONT event
--------------------------> 5) NEWSEGMENT event
| e) update stream time
| f) PLAY pipeline
......
Segments
--------
A segment in GStreamer denotes a set of media samples that must be
processed. A segment has a start time, a stop time and a processing
rate.
A media stream has a start and a stop time. The start time is
always 0 and the stop time is the duration (or -1 if unknown, for example
a live stream). We call this the complete media stream.
The segment of the complete media stream can be played by issuing a seek
on the stream. The seek has a start time, a stop time and a processing rate.
complete stream
+------------------------------------------------+
0 duration
segment
|--------------------------|
start stop
The playback of a segment starts with a source or demuxer element pushing a
newsegment event containing the start time, stop time and rate of the segment.
The purpose of this newsegment is to inform downstream elements of the
requested segment positions. Some elements might produce buffers that fall
outside of the segment and that might therefore be discarded or clipped.
ex.
filesrc ! avidemux ! videodecoder ! videosink
When avidemux starts playback of the segment from second 1 to 5, it pushes
out a newsegment with 1 and 5 as start and stop times.
The video decoder stores these values internally and forwards them to the
next downstream element (videosink, which also stores the values)
Since second 1 does not contain a keyframe, the avi demuxer starts sending
data from the previous keyframe which is at timestamp 0.
The video decoder decodes the keyframe but knows it should not push the
video frame yet as it falls outside of the configured segment.
When the video decoder receives the frame with timestamp 1, it is able to
decode this frame as it received and decoded the data up to the previous
keyframe. It then continues to decode and push frames with timestamps >= 1.
When it reaches timestamp 5, it does not decode and push frames anymore.
The stop time is important when the video format contains B frames. The
video decoder receives a P frame first, which is can decode but not push yet.
When it receives a B frame, it can decode the B frame and push the B frame
followed by the previously decoded P frame. If the P frame is outside of the
segment, the decoder knows it should not send the P frame.
Avidemux stops sending data after pushing frame with timestamp 5 and pushes
an EOS event downstream to finish playback.
......@@ -32,8 +32,8 @@
* allowing for deep nesting of predefined sub-pipelines.
*
* A new GstBin is created with gst_bin_new(). Use a #GstPipeline instead if you
* want to create a toplevel bin because a normal bin doesn't have a scheduler
* of its own.
* want to create a toplevel bin because a normal bin doesn't have a bus or
* handle clock distribution of its own.
*
* After the bin has been created you will typically add elements to it with
* gst_bin_add(). You can remove elements with gst_bin_remove().
......@@ -43,24 +43,15 @@
* purposes and will query the parent bins when the element is not found in the
* current bin.
*
* The list of elements in a bin can be retrieved with gst_bin_get_list().
*
* After the bin has been set to the PLAYING state (with gst_element_set_state()),
* gst_bin_iterate() is used to process the elements in the bin.
* An iterator of elements in a bin can be retrieved with
* gst_bin_iterate_elements(). Various other iterators exist to retrieve the
* elements in a bin.
*
* The "element_added" signal is fired whenever a new element is added to the
* bin. Likewise the "element_removed" signal is fired whenever an element is
* removed from the bin.
*
* gst_bin_destroy() is used to destroy the bin.
*
* To control the selection of the clock in a bin, you can use the following
* methods:
* gst_bin_auto_clock() to let the bin select a clock automatically,
* gst_bin_get_clock() to get the current clock of the bin and
* gst_bin_use_clock() to specify a clock explicitly.
* Note that the default behaviour is to automatically select a clock from one
* of the clock providers in the bin.
* gst_bin_unref() is used to destroy the bin.
*/
#include "gst_private.h"
......
......@@ -58,6 +58,11 @@
* If an element knows what pad you will push the buffer out on, it should use
* gst_pad_alloc_buffer() instead to create a buffer. This allows downstream
* elements to provide special buffers to write in, like hardware buffers.
*
* A buffer has a pointer to a #GstCaps describing the media type of the data
* in the buffer. Attach caps to the buffer with gst_buffer_set_caps(); this
* is typically done before pushing out a buffer using gst_pad_push() so that
* the downstream element knows the type of the buffer.
*
* gst_buffer_ref() is used to increase the refcount of a buffer. This must be
* done when you want to keep a handle to the buffer after pushing it to the
......@@ -80,12 +85,10 @@
* An element should either unref the buffer or push it out on a src pad
* using gst_pad_push() (see #GstPad).
*
* Buffers usually are freed by unreffing them with gst_buffer_unref().
* Do not use gst_buffer_free() : this function effectively frees the buffer
* regardless of the refcount, which is dangerous.
*
* Last reviewed on August 12th, 2004 (0.8.5)
* Buffers usually are freed by unreffing them with gst_buffer_unref(). When
* the refcount drops to 0, the buffer memory will be freed again.
*
* Last reviewed on September 24th, 2005 (0.9.0)
*/
#include "gst_private.h"
......
......@@ -31,8 +31,10 @@
*
* The clock time is always measured in nanoseconds and always increases. The
* pipeline uses the clock to calculate the stream time.
* Usually all renderers sync to the global clock so that the clock is always
* a good measure of the current playback time in the pipeline.
* Usually all renderers sync to the global clock using the buffer timestamps
* and the segment events.
*
* The time of the clock in itself is not very usefull for an application.
*/
#include <time.h>
......
......@@ -39,10 +39,9 @@
* and output (or source) pads.
* Core and plug-in writers can add and remove pads with gst_element_add_pad()
* and gst_element_remove_pad().
* Application writers can manipulate ghost pads (copies of real pads inside a bin)
* with gst_element_add_ghost_pad() and gst_element_remove_ghost_pad().
*
* A pad of an element can be retrieved by name with gst_element_get_pad().
* A GList of all pads can be retrieved with gst_element_get_pad_list().
* An iterator of all pads can be retrieved with gst_element_iterate_pads().
*
* Elements can be linked through their pads.
* If the link is straightforward, use the gst_element_link()
......@@ -61,9 +60,7 @@
* gst_element_state_get_name().
*
* You can get and set a #GstClock on an element using gst_element_get_clock()
* and gst_element_set_clock(). You can wait for the clock to reach a given
* #GstClockTime using gst_element_clock_wait().
*
* and gst_element_set_clock().
*/
#include "gst_private.h"
#include <glib.h>
......
......@@ -26,9 +26,10 @@
*
* The event classes are used to construct and query events.
*
* Events are usually created with gst_event_new() which takes the event type as
* an argument. Properties specific to the event can be set afterwards with the
* provided macros. The event should be unreferenced with gst_event_unref().
* Events are usually created with gst_event_new_*() which takes the extra event
* paramters as arguments.
* Events can be parsed with their respective gst_event_parse_*() functions.
* The event should be unreferenced with gst_event_unref().
*
* gst_event_new_seek() is a usually used to create a seek event and it takes
* the needed parameters for a seek event.
......
......@@ -18,13 +18,8 @@
*/
/**
* SECTION:gstfilter
* @short_description: Take data in and spit data out
* @short_description: A utility function to filter GLists.
*
* Filters take data in and spit data out. They are the main elements in a
* filter graph.
* Filters have zero or more inputs and zero or more outputs. Filters are
* linked together to form filter graphs. A #GstFilter is the base class and is
* not very useful on its own.
*/
#include "gst_private.h"
#include <gst/gstfilter.h>
......
......@@ -18,6 +18,18 @@
* Free Software Foundation, Inc., 59 Temple Place - Suite 330,
* Boston, MA 02111-1307, USA.
*/
/**
* SECTION:gstiterator
* @short_description: Object to retrieve multiple elements in a threadsafe
* way.
* @see_also: #GstElement, #GstBin
*
* A GstIterator is used to retrieve multiple objects from another object in
* a threadsafe way.
*
* Various GStreamer objects provide access to their internal structures using
* an iterator.
*/
#include "gst_private.h"
#include <gst/gstiterator.h>
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment