diff --git a/ChangeLog b/ChangeLog index 04bc286f2b..cdb4bbf652 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,14 @@ +2008-02-01 Wim Taymans + + * 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 * configure.ac: diff --git a/docs/design/part-synchronisation.txt b/docs/design/part-synchronisation.txt index c19e6ea2b9..54e250508b 100644 --- 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 5672c352a4..4ff7372b3c 100644 --- 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 faf2501217..ac652caf4d 100644 --- a/docs/plugins/gstreamer-plugins-docs.sgml +++ b/docs/plugins/gstreamer-plugins-docs.sgml @@ -20,6 +20,7 @@ + diff --git a/docs/plugins/gstreamer-plugins-sections.txt b/docs/plugins/gstreamer-plugins-sections.txt index 811a8f9207..ae5cf5aff5 100644 --- 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 +
+element-multiqueue +multiqueue +GstMultiQueue + +GstMultiQueueClass +GST_MULTI_QUEUE +GST_IS_MULTI_QUEUE +GST_MULTI_QUEUE_CLASS +GST_IS_MULTI_QUEUE_CLASS +GST_TYPE_MULTI_QUEUE + +gst_multi_queue_get_type +
+
element-typefind typefind diff --git a/plugins/elements/gstmultiqueue.c b/plugins/elements/gstmultiqueue.c index 83378e8dab..9da5374a2e 100644 --- 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 + * + * + * + * Multiqueue is similar to a normal #GstQueue with the following additional + * features: + * + * + * Multiple streamhandling + * + * 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). + * + * 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. + * + * + * + * + * Non-starvation on multiple streams + * + * 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. + * + * If an EOS event comes through a srcpad, the associated queue will be + * considered as 'not-empty' in the queue-size-growing algorithm. + * + * + * + * + * Non-linked srcpads graceful handling + * + * 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. + * + * 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. + * + * + * + * + * + * + * 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, + * + * + * #GstMultiQueue:extra-size-bytes and #GstMultiQueue:extra-size-time are + * currently unused. + * + * + * 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. + * + * + * 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. + * + * + * + * Last reviewed on 2008-01-25 (0.10.17) + */ + #ifdef HAVE_CONFIG_H # include "config.h" #endif