docs/design/part-synchronisation.txt: Update some docs.

Original commit message from CVS:
* docs/design/part-synchronisation.txt:
Update some docs.
* docs/plugins/Makefile.am:
* docs/plugins/gstreamer-plugins-docs.sgml:
* docs/plugins/gstreamer-plugins-sections.txt:
* plugins/elements/gstmultiqueue.c:
Add multiqueue to the docs.

diff --git a/ChangeLog b/ChangeLog
index 04bc286f2b322378a7acd3a4cba0f2c58fa069e4..cdb4bbf652e1ad8b37fc4d4cffa3d5160f4193a9 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,14 @@
+2008-02-01  Wim Taymans  <wim.taymans@collabora.co.uk>
+
+       * docs/design/part-synchronisation.txt:
+       Update some docs.
+
+       * docs/plugins/Makefile.am:
+       * docs/plugins/gstreamer-plugins-docs.sgml:
+       * docs/plugins/gstreamer-plugins-sections.txt:
+       * plugins/elements/gstmultiqueue.c:
+       Add multiqueue to the docs.
+
 2008-01-30  Jan Schmidt  <jan.schmidt@sun.com>
 
        * configure.ac:

diff --git a/docs/design/part-synchronisation.txt b/docs/design/part-synchronisation.txt
index c19e6ea2b9a61a820d316171259a40cf139a66ec..54e250508b2840be5acc0e796cb63ee236ee6d76 100644 (file)
--- a/docs/design/part-synchronisation.txt
+++ b/docs/design/part-synchronisation.txt
@@ -190,14 +190,16 @@ allows us to rewrite the above formula for stream_time (and for positive rates).
     B.running_time = (B.timestamp - NS.start) / NS.abs_rate + NS.accum
 
   =>
-    absolute_time - base_time = (B.timestamp - NS.start) / NS.abs_rate + NS.accum
+    (B.timestamp - NS.start) / NS.abs_rate + NS.accum = absolute_time - base_time;
 
   =>
-    absolute_time - base_time = (B.timestamp - NS.start) / NS.abs_rate + NS.accum
+    (B.timestamp - NS.start) / NS.abs_rate = absolute_time - base_time - NS.accum;
 
   =>
     (B.timestamp - NS.start) = (absolute_time - base_time - NS.accum) * NS.abs_rate
 
+  filling (B.timestamp - NS.start) in the above formule for stream time
+
   =>
     stream_time = (absolute_time - base_time - NS.accum) * NS.abs_rate * NS.abs_applied_rate + NS.time
 

diff --git a/docs/plugins/Makefile.am b/docs/plugins/Makefile.am
index 5672c352a4fea9bf04f461ddfa1fae1e895527c5..4ff7372b3ccfc4e6fcf8b4924340abad7b2d04a2 100644 (file)
--- a/docs/plugins/Makefile.am
+++ b/docs/plugins/Makefile.am
@@ -82,6 +82,7 @@ EXTRA_HFILES = \
        $(top_srcdir)/plugins/elements/gstfilesrc.h \
        $(top_srcdir)/plugins/elements/gstfilesink.h \
        $(top_srcdir)/plugins/elements/gstidentity.h \
+       $(top_srcdir)/plugins/elements/gstmultiqueue.h \
        $(top_srcdir)/plugins/elements/gstqueue.h \
        $(top_srcdir)/plugins/elements/gsttypefindelement.h \
        $(top_srcdir)/plugins/elements/gsttee.h

diff --git a/docs/plugins/gstreamer-plugins-docs.sgml b/docs/plugins/gstreamer-plugins-docs.sgml
index faf2501217fd1afc2c378f6c7abd8519b7e311a0..ac652caf4de0ca2297a5e0dfb69610847ccb2799 100644 (file)
--- a/docs/plugins/gstreamer-plugins-docs.sgml
+++ b/docs/plugins/gstreamer-plugins-docs.sgml
@@ -20,6 +20,7 @@
     <xi:include href="xml/element-filesrc.xml" />
     <xi:include href="xml/element-filesink.xml" />
     <xi:include href="xml/element-identity.xml" />
+    <xi:include href="xml/element-multiqueue.xml" />
     <xi:include href="xml/element-queue.xml" />
     <xi:include href="xml/element-tee.xml" />
     <xi:include href="xml/element-typefind.xml" />

diff --git a/docs/plugins/gstreamer-plugins-sections.txt b/docs/plugins/gstreamer-plugins-sections.txt
index 811a8f92070737b17408cbbd7ef29765094c2a2c..ae5cf5aff579121ddb64d2a5419dddfc8ee1c97a 100644 (file)
--- a/docs/plugins/gstreamer-plugins-sections.txt
+++ b/docs/plugins/gstreamer-plugins-sections.txt
@@ -143,6 +143,21 @@ gst_queue_get_type
 GST_QUEUE_CLEAR_LEVEL
 </SECTION>
 
+<SECTION>
+<FILE>element-multiqueue</FILE>
+<TITLE>multiqueue</TITLE>
+GstMultiQueue
+<SUBSECTION Standard>
+GstMultiQueueClass
+GST_MULTI_QUEUE
+GST_IS_MULTI_QUEUE
+GST_MULTI_QUEUE_CLASS
+GST_IS_MULTI_QUEUE_CLASS
+GST_TYPE_MULTI_QUEUE
+<SUBSECTION Private>
+gst_multi_queue_get_type
+</SECTION>
+
 <SECTION>
 <FILE>element-typefind</FILE>
 <TITLE>typefind</TITLE>

diff --git a/plugins/elements/gstmultiqueue.c b/plugins/elements/gstmultiqueue.c
index 83378e8dabbe31692a55f1276edccffc19668753..9da5374a2ebf94bf478e10e23408868945c371a3 100644 (file)
--- a/plugins/elements/gstmultiqueue.c
+++ b/plugins/elements/gstmultiqueue.c
@@ -21,6 +21,90 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:element-multiqueue
+ * @short_description: Asynchronous data queues
+ * @see_also: #GstQueue
+ *
+ * <refsect2>
+ * <para>
+ * Multiqueue is similar to a normal #GstQueue with the following additional
+ * features:
+ * <orderedlist>
+ * <listitem>
+ *   <itemizedlist><title>Multiple streamhandling</title>
+ *   <listitem><para>
+ *     The element handles queueing data on more than one stream at once. To
+ *     achieve such a feature it has request sink pads (sink_%d) and
+ *     'sometimes' src pads (src_%d).
+ *   </para><para>
+ *     When requesting a given sinkpad with gst_element_get_request_pad(),
+ *     the associated srcpad for that stream will be created.
+ *     Ex: requesting sink_1 will generate src_1.
+ *   </para></listitem>
+ *   </itemizedlist>
+ * </listitem>
+ * <listitem>
+ *   <itemizedlist><title>Non-starvation on multiple streams</title>
+ *   <listitem><para>
+ *     If more than one stream is used with the element, the streams' queues
+ *     will be dynamically grown (up to a limit), in order to ensure that no
+ *     stream is risking data starvation. This guarantees that at any given
+ *     time there are at least N bytes queued and available for each individual
+ *     stream.
+ *   </para><para>
+ *     If an EOS event comes through a srcpad, the associated queue will be
+ *     considered as 'not-empty' in the queue-size-growing algorithm.
+ *   </para></listitem>
+ *   </itemizedlist>
+ * </listitem>
+ * <listitem>
+ *   <itemizedlist><title>Non-linked srcpads graceful handling</title>
+ *   <listitem><para>
+ *     In order to better support dynamic switching between streams, the multiqueue
+ *     (unlike the current GStreamer queue) continues to push buffers on non-linked
+ *     pads rather than shutting down.
+ *   </para><para>
+ *     In addition, to prevent a non-linked stream from very quickly consuming all
+ *     available buffers and thus 'racing ahead' of the other streams, the element
+ *     must ensure that buffers and inlined events for a non-linked stream are pushed
+ *     in the same order as they were received, relative to the other streams
+ *     controlled by the element. This means that a buffer cannot be pushed to a
+ *     non-linked pad any sooner than buffers in any other stream which were received
+ *     before it.
+ *   </para></listitem>
+ *   </itemizedlist>
+ * </listitem>
+ * </orderedlist>
+ * </para>
+ * <para>
+ *   Data is queued until one of the limits specified by the
+ *   #GstMultiQueue:max-size-buffers, #GstMultiQueue:max-size-bytes and/or
+ *   #GstMultiQueue:max-size-time properties has been reached. Any attempt to push
+ *   more buffers into the queue will block the pushing thread until more space
+ *   becomes available. #GstMultiQueue:extra-size-buffers,
+ * </para>
+ * <para>
+ *   #GstMultiQueue:extra-size-bytes and #GstMultiQueue:extra-size-time are
+ *   currently unused.
+ * </para>
+ * <para>
+ *   The default queue size limits are 5 buffers, 10MB of data, or
+ *   two second worth of data, whichever is reached first. Note that the number
+ *   of buffers will dynamically grow depending on the fill level of 
+ *   other queues.
+ * </para>
+ * <para>
+ *   The #GstMultiQueue::underrun signal is emitted when all of the queues
+ *   are empty. The #GstMultiQueue::overrun signal is emitted when one of the
+ *   queues is filled.
+ *   Both signals are emitted from the context of the streaming thread.
+ * </para>
+ * </refsect2>
+ *
+ * Last reviewed on 2008-01-25 (0.10.17)
+ */
+
 #ifdef HAVE_CONFIG_H
 #  include "config.h"
 #endif