Commit 429ebfff authored by Wim Taymans's avatar Wim Taymans

Documentation updates.

Original commit message from CVS:
* docs/gst/gstreamer-sections.txt:
* gst/gstbin.c: (bin_bus_handler), (gst_bin_handle_message_func):
* gst/gstbin.h:
* gst/gstbus.c: (gst_bus_class_init):
* gst/gstbus.h:
* gst/gstclock.c:
* gst/gstelement.c: (gst_element_set_locked_state):
* gst/gstsegment.c:
Documentation updates.
* gst/gstpipeline.c: (gst_pipeline_get_type),
(gst_pipeline_class_init), (gst_pipeline_init),
(gst_pipeline_dispose), (gst_pipeline_set_property),
(gst_pipeline_get_property), (do_pipeline_seek),
(gst_pipeline_send_event), (gst_pipeline_change_state),
(gst_pipeline_provide_clock_func), (gst_pipeline_set_delay),
(gst_pipeline_get_delay):
* gst/gstpipeline.h:
Added methods for setting the delay.
API: gst_pipeline_set_delay
API: gst_pipeline_get_delay
Add pipeline debug category
Various cleanups.
Updated docs.
Don't reset stream time when seek failed.
parent b6903343
2006-03-13 Wim Taymans <wim@fluendo.com>
* docs/gst/gstreamer-sections.txt:
* gst/gstbin.c: (bin_bus_handler), (gst_bin_handle_message_func):
* gst/gstbin.h:
* gst/gstbus.c: (gst_bus_class_init):
* gst/gstbus.h:
* gst/gstclock.c:
* gst/gstelement.c: (gst_element_set_locked_state):
* gst/gstsegment.c:
Documentation updates.
* gst/gstpipeline.c: (gst_pipeline_get_type),
(gst_pipeline_class_init), (gst_pipeline_init),
(gst_pipeline_dispose), (gst_pipeline_set_property),
(gst_pipeline_get_property), (do_pipeline_seek),
(gst_pipeline_send_event), (gst_pipeline_change_state),
(gst_pipeline_provide_clock_func), (gst_pipeline_set_delay),
(gst_pipeline_get_delay):
* gst/gstpipeline.h:
Added methods for setting the delay.
API: gst_pipeline_set_delay
API: gst_pipeline_get_delay
Add pipeline debug category
Various cleanups.
Updated docs.
Don't reset stream time when seek failed.
2006-03-13 Wim Taymans <wim@fluendo.com>
* docs/design/draft-klass.txt:
......
......@@ -1404,16 +1404,23 @@ GstPipelineFlags
gst_pipeline_new
gst_pipeline_auto_clock
gst_pipeline_get_bus
gst_pipeline_get_clock
gst_pipeline_get_last_stream_time
gst_pipeline_set_clock
gst_pipeline_set_new_stream_time
gst_pipeline_get_clock
gst_pipeline_use_clock
gst_pipeline_auto_clock
gst_pipeline_set_new_stream_time
gst_pipeline_get_last_stream_time
gst_pipeline_get_auto_flush_bus
gst_pipeline_set_auto_flush_bus
gst_pipeline_get_auto_flush_bus
gst_pipeline_set_delay
gst_pipeline_get_delay
<SUBSECTION Standard>
GstPipelineClass
GST_PIPELINE
......
......@@ -79,21 +79,58 @@
* a SEGMENT_START have posted a SEGMENT_DONE.</para></listitem>
* </varlistentry>
* <varlistentry>
* <term>GST_MESSAGE_DURATION</term>
* <listitem><para> Is posted by an element that detected a change
* in the stream duration. The default bin behaviour is to clear any
* cached duration values so that the next duration query will perform
* a full duration recalculation. The duration change is posted to the
* application so that it can refetch the new duration with a duration
* query.
* </para></listitem>
* </varlistentry>
* <varlistentry>
* <term>GST_MESSAGE_CLOCK_LOST</term>
* <listitem><para> This message is posted by an element when it
* can no longer provide a clock. The default bin behaviour is to
* check if the lost clock was the one provided by the bin. If so and
* the bin is currently in the PLAYING state, the message is forwarded to
* the bin parent.
* This message is also generated when a clock provider is removed from
* the bin. If this message is received by the application, it should
* PAUSE the pipeline and set it back to PLAYING to force a new clock
* distribution.
* </para></listitem>
* </varlistentry>
* <varlistentry>
* <term>GST_MESSAGE_CLOCK_PROVIDE</term>
* <listitem><para> This message is generated when an element
* can provide a clock. This mostly happens when a new clock
* provider is added to the bin. The default behaviour of the bin is to
* mark the currently selected clock as dirty, which will perform a clock
* recalculation the next time the bin is asked to provide a clock.
* This message is never sent tot the application but is forwarded to
* the parent of the bin.
* </para></listitem>
* </varlistentry>
* <varlistentry>
* <term>OTHERS</term>
* <listitem><para> posted upwards.</para></listitem>
* </varlistentry>
* </variablelist>
*
*
* A #GstBin implements the following default behaviour for answering to a
* #GstQuery:
* <variablelist>
* <varlistentry>
* <term>GST_QUERY_DURATION</term>
* <listitem><para>If the query has been asked before with the same format,
* <listitem><para>If the query has been asked before with the same format
* and the bin is a toplevel bin (ie. has no parent),
* use the cached previous value. If no previous value was cached, the
* query is sent to all sink elements in the bin and the MAXIMUM of all
* values is returned and cached. If no sinks are available in the bin, the
* query fails.</para></listitem>
* values is returned. If the bin is a toplevel bin the value is cached.
* If no sinks are available in the bin, the query fails.
* </para></listitem>
* </varlistentry>
* <varlistentry>
* <term>OTHERS</term>
......@@ -110,7 +147,7 @@
* </para>
* </refsect2>
*
* Last reviewed on 2005-12-16 (0.10.0)
* Last reviewed on 2006-03-12 (0.10.5)
*/
#include "gst_private.h"
......@@ -1918,6 +1955,21 @@ gst_bin_recalc_func (GstBin * bin, gpointer data)
gst_object_unref (bin);
}
static GstBusSyncReply
bin_bus_handler (GstBus * bus, GstMessage * message, GstBin * bin)
{
GstBinClass *bclass;
bclass = GST_BIN_GET_CLASS (bin);
if (bclass->handle_message)
bclass->handle_message (bin, message);
else
gst_message_unref (message);
return GST_BUS_DROP;
}
/* handle child messages:
*
* GST_MESSAGE_EOS: This message is only posted by sinks
......@@ -1941,23 +1993,26 @@ gst_bin_recalc_func (GstBin * bin, gpointer data)
* changes its duration marks our cached values invalid.
* This message is also posted upwards.
*
* GST_MESSAGE_CLOCK_LOST: This message is posted by an element when it
* can no longer provide a clock. The default bin behaviour is to
* check if the lost clock was the one provided by the bin. If so and
* we are currently in the PLAYING state, we forward the message to
* our parent.
* This message is also generated when we remove a clock provider from
* a bin. If this message is received by the application, it should
* PAUSE the pipeline and set it back to PLAYING to force a new clock
* distribution.
*
* GST_MESSAGE_CLOCK_PROVIDE: This message is generated when an element
* can provide a clock. This mostly happens when we add a new clock
* provider to the bin. The default behaviour of the bin is to mark the
* currently selected clock as dirty, which will perform a clock
* recalculation the next time we are asked to provide a clock.
* This message is never sent tot the application but is forwarded to
* the parent.
*
* OTHER: post upwards.
*/
static GstBusSyncReply
bin_bus_handler (GstBus * bus, GstMessage * message, GstBin * bin)
{
GstBinClass *bclass;
bclass = GST_BIN_GET_CLASS (bin);
if (bclass->handle_message)
bclass->handle_message (bin, message);
else
gst_message_unref (message);
return GST_BUS_DROP;
}
static void
gst_bin_handle_message_func (GstBin * bin, GstMessage * message)
{
......
......@@ -83,7 +83,7 @@ typedef struct _GstBinClass GstBinClass;
* @children: the list of children in this bin
* @children_cookie: updated whenever @children changes
* @child_bus: internal bus for handling child messages
* @messages: queued messages
* @messages: queued and cached messages
* @polling: the bin is currently calculating its state
* @state_dirty: the bin needs to recalculate its state
* @clock_dirty: the bin needs to select a new clock
......
......@@ -48,7 +48,9 @@
* bus to handle them.
* Alternatively the application can register an asynchronous bus function
* using gst_bus_add_watch_full() or gst_bus_add_watch(). This function will
* receive messages a short while after they have been posted.
* install a #GSource in the default glib main loop and will deliver messages
* a short while after they have been posted. Note that the main loop should
* be running for the asynchronous callbacks.
*
* It is also possible to get messages from the bus without any thread
* marshalling with the gst_bus_set_sync_handler() method. This makes it
......@@ -61,7 +63,7 @@
* Note that a #GstPipeline will set its bus into flushing state when changing
* from READY to NULL state.
*
* Last reviewed on 2005-10-28 (0.9.4)
* Last reviewed on 2006-03-12 (0.10.5)
*/
#include <errno.h>
......@@ -195,7 +197,8 @@ gst_bus_class_init (GstBusClass * klass)
* @message: the message that has been posted asynchronously
*
* A message has been posted on the bus. This signal is emitted from a
* GSource added to the mainloop.
* GSource added to the mainloop. this signal will only be emited when
* there is a mainloop running.
*/
gst_bus_signals[ASYNC_MESSAGE] =
g_signal_new ("message", G_TYPE_FROM_CLASS (klass),
......@@ -684,13 +687,13 @@ gst_bus_create_watch (GstBus * bus)
* @user_data: user data passed to @func.
* @notify: the function to call when the source is removed.
*
* Adds a bus watch to the default main context with the given priority.
* If the func returns FALSE, the source will be removed.
* Adds a bus watch to the default main context with the given @priority.
*
* When the func is called, the message belongs to the caller; if you want to
* keep a copy of it, call gst_message_ref() before leaving the func.
* When @func is called, the message belongs to the caller; if you want to
* keep a copy of it, call gst_message_ref() before leaving @func.
*
* The watch can be removed using #g_source_remove().
* The watch can be removed using g_source_remove() or by returning FALSE
* from @func.
*
* Returns: The event source id.
*
......@@ -727,7 +730,8 @@ gst_bus_add_watch_full (GstBus * bus, gint priority,
*
* Adds a bus watch to the default main context with the default priority.
*
* The watch can be removed using #g_source_remove().
* The watch can be removed using g_source_remove() or by returning FALSE
* from @func.
*
* Returns: The event source id.
*
......@@ -874,7 +878,7 @@ gst_bus_poll (GstBus * bus, GstMessageType events, GstClockTimeDiff timeout)
* @message: the #GstMessage received
* @data: user data
*
* A helper GstBusFunc that can be used to convert all asynchronous messages
* A helper #GstBusFunc that can be used to convert all asynchronous messages
* into signals.
*
* Returns: TRUE
......@@ -925,7 +929,7 @@ gst_bus_sync_signal_handler (GstBus * bus, GstMessage * message, gpointer data)
* gst_bus_enable_sync_message_emission:
* @bus: a #GstBus on which you want to receive the "sync-message" signal
*
* Instructs GStreamer to emit the sync-message signal after running the bus's
* Instructs GStreamer to emit the "sync-message" signal after running the bus's
* sync handler. This function is here so that code can ensure that they can
* synchronously receive messages without having to affect what the bin's sync
* handler is.
......@@ -936,9 +940,9 @@ gst_bus_sync_signal_handler (GstBus * bus, GstMessage * message, gpointer data)
*
* While this function looks similar to gst_bus_add_signal_watch(), it is not
* exactly the same -- this function enables <emphasis>synchronous</emphasis> emission of
* signals when messages arrive; gst_bus_add_signal_watch adds an idle callback
* signals when messages arrive; gst_bus_add_signal_watch() adds an idle callback
* to pop messages off the bus <emphasis>asynchronously</emphasis>. The sync-message signal
* comes from the thread of whatever object posted the message; the message
* comes from the thread of whatever object posted the message; the "message"
* signal is marshalled to the main thread via the main loop.
*
* MT safe.
......@@ -960,14 +964,14 @@ gst_bus_enable_sync_message_emission (GstBus * bus)
* @bus: a #GstBus on which you previously called
* gst_bus_enable_sync_message_emission()
*
* Instructs GStreamer to stop emitting the sync-message signal for this bus.
* Instructs GStreamer to stop emitting the "sync-message" signal for this bus.
* See gst_bus_enable_sync_message_emission() for more information.
*
* In the event that multiple pieces of code have called
* gst_bus_enable_sync_message_emission(), the sync-message emissions will only
* be stopped after all calls to gst_bus_enable_sync_message_emission() were
* "cancelled" by calling this function. In this way the semantics are exactly
* the same as gst_object_ref(); that which calls enable should also call
* the same as gst_object_ref() that which calls enable should also call
* disable.
*
* MT safe.
......@@ -992,8 +996,8 @@ gst_bus_disable_sync_message_emission (GstBus * bus)
* @priority: The priority of the watch.
*
* Adds a bus signal watch to the default main context with the given priority.
* After calling this statement, the bus will emit the message signal for each
* message posted on the bus.
* After calling this statement, the bus will emit the "message" signal for each
* message posted on the bus when the main loop is running.
*
* This function may be called multiple times. To clean up, the caller is
* responsible for calling gst_bus_remove_signal_watch() as many times as this
......@@ -1031,7 +1035,7 @@ done:
*
* Adds a bus signal watch to the default main context with the default
* priority.
* After calling this statement, the bus will emit the message signal for each
* After calling this statement, the bus will emit the "message" signal for each
* message posted on the bus.
*
* This function may be called multiple times. To clean up, the caller is
......
......@@ -98,6 +98,9 @@ typedef GstBusSyncReply (*GstBusSyncHandler) (GstBus * bus, GstMessage * messag
* The message passed to the function will be unreffed after execution of this
* function so it should not be freed in the function.
*
* Note that this function is used as a GSourceFunc which means that returning
* FALSE will remove the GSource from the mainloop.
*
* Returns: %FALSE if the event source should be removed.
*/
typedef gboolean (*GstBusFunc) (GstBus * bus, GstMessage * message, gpointer data);
......
......@@ -24,7 +24,7 @@
/**
* SECTION:gstclock
* @short_description: Abstract class for global clocks
* @see_also: #GstSystemClock
* @see_also: #GstSystemClock, #GstPipeline
*
* GStreamer uses a global clock to synchronize the plugins in a pipeline.
* Different clock implementations are possible by implementing this abstract
......@@ -35,10 +35,11 @@
* clock implementation but time is always expressed in nanoseconds. Since the
* baseline of the clock is undefined, the clock time returned is not
* meaningful in itself, what matters are the deltas between two clock times.
* The time returned by a clock is called the absolute time.
*
* The pipeline uses the clock to calculate the stream time. Usually all
* renderers synchronize to the global clock using the buffer timestamps, the
* newsegment events and the element's base time.
* newsegment events and the element's base time, see #GstPipeline.
*
* A clock implementation can support periodic and single shot clock
* notifications both synchronous and asynchronous.
......
......@@ -25,9 +25,9 @@
* @short_description: Abstract base class for all pipeline elements
* @see_also: #GstElementFactory, #GstPad
*
* GstElement is the base class needed to construct an element that can be
* used in a GStreamer pipeline. As such, it is not a functional entity, and
* cannot do anything when placed in a pipeline.
* GstElement is the abstract base class needed to construct an element that
* can be used in a GStreamer pipeline. Please refer to the plugin writers
* guide for more information on creating #GstElement subclasses.
*
* The name of a #GstElement can be get with gst_element_get_name() and set with
* gst_element_set_name(). For speed, GST_ELEMENT_NAME() can be used in the
......@@ -73,7 +73,7 @@
* toplevel #GstPipeline so the clock functions are only to be used in very
* specific situations.
*
* Last reviewed on 2005-11-23 (0.9.5)
* Last reviewed on 2006-03-12 (0.10.5)
*/
#include "gst_private.h"
......
This diff is collapsed.
......@@ -72,6 +72,7 @@ struct _GstPipeline {
/*< private >*/
GstPipelinePrivate *priv;
gpointer _gst_reserved[GST_PADDING-1];
};
......@@ -95,6 +96,9 @@ gboolean gst_pipeline_set_clock (GstPipeline *pipeline, GstClock
GstClock* gst_pipeline_get_clock (GstPipeline *pipeline);
void gst_pipeline_auto_clock (GstPipeline *pipeline);
void gst_pipeline_set_delay (GstPipeline *pipeline, GstClockTime delay);
GstClockTime gst_pipeline_get_delay (GstPipeline *pipeline);
void gst_pipeline_set_auto_flush_bus (GstPipeline *pipeline, gboolean auto_flush);
gboolean gst_pipeline_get_auto_flush_bus (GstPipeline *pipeline);
......
......@@ -64,7 +64,7 @@
* If the cur_type was different from GST_SEEK_TYPE_NONE, playback continues from
* the last_pos position, possibly with updated flags or rate.
*
* For elements that want to us #GstSegment to track the playback region, use
* For elements that want to use #GstSegment to track the playback region, use
* gst_segment_set_newsegment() to update the segment fields with the information from
* the newsegment event. The gst_segment_clip() method can be used to check and clip
* the media data to the segment boundaries.
......@@ -77,7 +77,7 @@
* gst_segment_to_stream_time() can be used to convert a timestamp and the segment
* info to stream time (which is always between 0 and the duration of the stream).
*
* Last reviewed on 2005-12-12 (0.10.0)
* Last reviewed on 2006-03-12 (0.10.5)
*/
static GstSegment *
......@@ -174,7 +174,7 @@ gst_segment_init (GstSegment * segment, GstFormat format)
* used by elements that perform seeking and know the total duration of the
* segment.
*
* This field should be set to allow seeking request relative to the
* This field should be set to allow seeking requests relative to the
* duration.
*/
void
......@@ -198,6 +198,9 @@ gst_segment_set_duration (GstSegment * segment, GstFormat format,
* @position: the position
*
* Set the last observed stop position in the segment to @position.
*
* This field should be set to allow seeking requests relative to the
* current playing position.
*/
void
gst_segment_set_last_stop (GstSegment * segment, GstFormat format,
......@@ -223,8 +226,7 @@ gst_segment_set_last_stop (GstSegment * segment, GstFormat format,
* @cur: the seek start value
* @stop_type: the seek method
* @stop: the seek stop value
* @update: boolean holding whether an update the current segment is
* needed.
* @update: boolean holding whether start or stop were updated.
*
* Update the segment structure with the field values of a seek event.
*
......@@ -450,11 +452,12 @@ gst_segment_to_stream_time (GstSegment * segment, GstFormat format,
* @position: the position in the segment
*
* Translate @position to the total running time using the currently configured
* segment.
* and previously accumulated segments.
*
* This function is typically used by elements that need to synchronize to the
* global clock in a pipeline. The runnning time is a constantly increasing value
* starting from 0.
* starting from 0. When gst_segment_init() is called, this value will reset to
* 0.
*
* Returns: the position as the total running time.
*/
......@@ -491,8 +494,16 @@ gst_segment_to_running_time (GstSegment * segment, GstFormat format,
* Clip the given @start and @stop values to the segment boundaries given
* in @segment.
*
* Returns: TRUE if the given @start and @stop times fall partially in
* @segment, FALSE if the values are completely outside of the segment.
* If the function returns FALSE, @start and @stop are known to fall
* outside of @segment and @clip_start and @clip_stop are not updated.
*
* When the function returns TRUE, @clip_start and @clip_stop will be
* updated. If @clip_start or @clip_stop are different from @start or @stop
* respectively, the region fell partially in the segment.
*
* Returns: TRUE if the given @start and @stop times fall partially or
* completely in @segment, FALSE if the values are completely outside
* of the segment.
*/
gboolean
gst_segment_clip (GstSegment * segment, GstFormat format, gint64 start,
......
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