Git init
[framework/multimedia/gstreamer0.10.git] / docs / plugins / html / gstreamer-plugins-multiqueue.html
1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2 <html>
3 <head>
4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
5 <title>multiqueue</title>
6 <meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
7 <link rel="home" href="index.html" title="GStreamer Core Plugins 0.10 Plugins Reference Manual">
8 <link rel="up" href="ch01.html" title="gstreamer Elements">
9 <link rel="prev" href="gstreamer-plugins-input-selector.html" title="input-selector">
10 <link rel="next" href="gstreamer-plugins-output-selector.html" title="output-selector">
11 <meta name="generator" content="GTK-Doc V1.17 (XML mode)">
12 <link rel="stylesheet" href="style.css" type="text/css">
13 </head>
14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
16 <tr valign="middle">
17 <td><a accesskey="p" href="gstreamer-plugins-input-selector.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
18 <td><a accesskey="u" href="ch01.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
19 <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
20 <th width="100%" align="center">GStreamer Core Plugins 0.10 Plugins Reference Manual</th>
21 <td><a accesskey="n" href="gstreamer-plugins-output-selector.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
22 </tr>
23 <tr><td colspan="5" class="shortcuts">
24 <a href="#gstreamer-plugins-multiqueue.synopsis" class="shortcut">Top</a>
25                    | 
26                   <a href="#gstreamer-plugins-multiqueue.description" class="shortcut">Description</a>
27                    | 
28                   <a href="#gstreamer-plugins-multiqueue.object-hierarchy" class="shortcut">Object Hierarchy</a>
29                    | 
30                   <a href="#gstreamer-plugins-multiqueue.properties" class="shortcut">Properties</a>
31                    | 
32                   <a href="#gstreamer-plugins-multiqueue.signals" class="shortcut">Signals</a>
33 </td></tr>
34 </table>
35 <div class="refentry">
36 <a name="gstreamer-plugins-multiqueue"></a><div class="titlepage"></div>
37 <div class="refnamediv"><table width="100%"><tr>
38 <td valign="top">
39 <h2><span class="refentrytitle"><a name="gstreamer-plugins-multiqueue.top_of_page"></a>multiqueue</span></h2>
40 <p>multiqueue — Multiple data queue</p>
41 </td>
42 <td valign="top" align="right"></td>
43 </tr></table></div>
44 <div class="refsynopsisdiv">
45 <a name="gstreamer-plugins-multiqueue.synopsis"></a><h2>Synopsis</h2>
46 <a name="GstMultiQueue"></a><pre class="synopsis">struct              <a class="link" href="gstreamer-plugins-multiqueue.html#GstMultiQueue-struct" title="struct GstMultiQueue">GstMultiQueue</a>;
47 </pre>
48 </div>
49 <div class="refsect1">
50 <a name="gstreamer-plugins-multiqueue.object-hierarchy"></a><h2>Object Hierarchy</h2>
51 <pre class="synopsis">
52   <a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#GObject">GObject</a>
53    +----<a href="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gstreamer/html/GstObject.html">GstObject</a>
54          +----<a href="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gstreamer/html/GstElement.html">GstElement</a>
55                +----GstMultiQueue
56 </pre>
57 </div>
58 <div class="refsect1">
59 <a name="gstreamer-plugins-multiqueue.properties"></a><h2>Properties</h2>
60 <pre class="synopsis">
61   "<a class="link" href="gstreamer-plugins-multiqueue.html#GstMultiQueue--extra-size-buffers" title='The "extra-size-buffers" property'>extra-size-buffers</a>"       <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a>                 : Read / Write
62   "<a class="link" href="gstreamer-plugins-multiqueue.html#GstMultiQueue--extra-size-bytes" title='The "extra-size-bytes" property'>extra-size-bytes</a>"         <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a>                 : Read / Write
63   "<a class="link" href="gstreamer-plugins-multiqueue.html#GstMultiQueue--extra-size-time" title='The "extra-size-time" property'>extra-size-time</a>"          <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint64"><span class="type">guint64</span></a>               : Read / Write
64   "<a class="link" href="gstreamer-plugins-multiqueue.html#GstMultiQueue--max-size-buffers" title='The "max-size-buffers" property'>max-size-buffers</a>"         <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a>                 : Read / Write
65   "<a class="link" href="gstreamer-plugins-multiqueue.html#GstMultiQueue--max-size-bytes" title='The "max-size-bytes" property'>max-size-bytes</a>"           <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a>                 : Read / Write
66   "<a class="link" href="gstreamer-plugins-multiqueue.html#GstMultiQueue--max-size-time" title='The "max-size-time" property'>max-size-time</a>"            <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint64"><span class="type">guint64</span></a>               : Read / Write
67   "<a class="link" href="gstreamer-plugins-multiqueue.html#GstMultiQueue--high-percent" title='The "high-percent" property'>high-percent</a>"             <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gint"><span class="type">gint</span></a>                  : Read / Write
68   "<a class="link" href="gstreamer-plugins-multiqueue.html#GstMultiQueue--low-percent" title='The "low-percent" property'>low-percent</a>"              <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gint"><span class="type">gint</span></a>                  : Read / Write
69   "<a class="link" href="gstreamer-plugins-multiqueue.html#GstMultiQueue--use-buffering" title='The "use-buffering" property'>use-buffering</a>"            <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a>              : Read / Write
70 </pre>
71 </div>
72 <div class="refsect1">
73 <a name="gstreamer-plugins-multiqueue.signals"></a><h2>Signals</h2>
74 <pre class="synopsis">
75   "<a class="link" href="gstreamer-plugins-multiqueue.html#GstMultiQueue-overrun" title='The "overrun" signal'>overrun</a>"                                        : <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS"><code class="literal">Run First</code></a>
76   "<a class="link" href="gstreamer-plugins-multiqueue.html#GstMultiQueue-underrun" title='The "underrun" signal'>underrun</a>"                                       : <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS"><code class="literal">Run First</code></a>
77 </pre>
78 </div>
79 <div class="refsect1">
80 <a name="gstreamer-plugins-multiqueue.description"></a><h2>Description</h2>
81 <p>
82 </p>
83 <div class="refsect2">
84 <a name="idp10428752"></a><p>
85 Multiqueue is similar to a normal <a class="link" href="gstreamer-plugins-queue.html#GstQueue"><span class="type">GstQueue</span></a> with the following additional
86 features:
87 </p>
88 <div class="orderedlist"><ol class="orderedlist" type="1">
89 <li class="listitem"><div class="itemizedlist">
90 <p class="title"><b>Multiple streamhandling</b></p>
91 <ul class="itemizedlist" type="disc"><li class="listitem">
92 <p>
93     The element handles queueing data on more than one stream at once. To
94     achieve such a feature it has request sink pads (sink%d) and
95     'sometimes' src pads (src%d).
96   </p>
97 <p>
98     When requesting a given sinkpad with <a href="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gstreamer/html/GstElement.html#gst-element-get-request-pad"><code class="function">gst_element_get_request_pad()</code></a>,
99     the associated srcpad for that stream will be created.
100     Example: requesting sink1 will generate src1.
101   </p>
102 </li></ul>
103 </div></li>
104 <li class="listitem"><div class="itemizedlist">
105 <p class="title"><b>Non-starvation on multiple streams</b></p>
106 <ul class="itemizedlist" type="disc"><li class="listitem">
107 <p>
108     If more than one stream is used with the element, the streams' queues
109     will be dynamically grown (up to a limit), in order to ensure that no
110     stream is risking data starvation. This guarantees that at any given
111     time there are at least N bytes queued and available for each individual
112     stream.
113   </p>
114 <p>
115     If an EOS event comes through a srcpad, the associated queue will be
116     considered as 'not-empty' in the queue-size-growing algorithm.
117   </p>
118 </li></ul>
119 </div></li>
120 <li class="listitem"><div class="itemizedlist">
121 <p class="title"><b>Non-linked srcpads graceful handling</b></p>
122 <ul class="itemizedlist" type="disc"><li class="listitem">
123 <p>
124     In order to better support dynamic switching between streams, the multiqueue
125     (unlike the current GStreamer queue) continues to push buffers on non-linked
126     pads rather than shutting down.
127   </p>
128 <p>
129     In addition, to prevent a non-linked stream from very quickly consuming all
130     available buffers and thus 'racing ahead' of the other streams, the element
131     must ensure that buffers and inlined events for a non-linked stream are pushed
132     in the same order as they were received, relative to the other streams
133     controlled by the element. This means that a buffer cannot be pushed to a
134     non-linked pad any sooner than buffers in any other stream which were received
135     before it.
136   </p>
137 </li></ul>
138 </div></li>
139 </ol></div>
140 <p>
141 </p>
142 <p>
143   Data is queued until one of the limits specified by the
144   <a class="link" href="gstreamer-plugins-multiqueue.html#GstMultiQueue--max-size-buffers" title='The "max-size-buffers" property'><span class="type">"max-size-buffers"</span></a>, <a class="link" href="gstreamer-plugins-multiqueue.html#GstMultiQueue--max-size-bytes" title='The "max-size-bytes" property'><span class="type">"max-size-bytes"</span></a> and/or
145   <a class="link" href="gstreamer-plugins-multiqueue.html#GstMultiQueue--max-size-time" title='The "max-size-time" property'><span class="type">"max-size-time"</span></a> properties has been reached. Any attempt to push
146   more buffers into the queue will block the pushing thread until more space
147   becomes available. <a class="link" href="gstreamer-plugins-multiqueue.html#GstMultiQueue--extra-size-buffers" title='The "extra-size-buffers" property'><span class="type">"extra-size-buffers"</span></a>,
148 </p>
149 <p>
150   <a class="link" href="gstreamer-plugins-multiqueue.html#GstMultiQueue--extra-size-bytes" title='The "extra-size-bytes" property'><span class="type">"extra-size-bytes"</span></a> and <a class="link" href="gstreamer-plugins-multiqueue.html#GstMultiQueue--extra-size-time" title='The "extra-size-time" property'><span class="type">"extra-size-time"</span></a> are
151   currently unused.
152 </p>
153 <p>
154   The default queue size limits are 5 buffers, 10MB of data, or
155   two second worth of data, whichever is reached first. Note that the number
156   of buffers will dynamically grow depending on the fill level of 
157   other queues.
158 </p>
159 <p>
160   The <a class="link" href="gstreamer-plugins-multiqueue.html#GstMultiQueue-underrun" title='The "underrun" signal'><span class="type">"underrun"</span></a> signal is emitted when all of the queues
161   are empty. The <a class="link" href="gstreamer-plugins-multiqueue.html#GstMultiQueue-overrun" title='The "overrun" signal'><span class="type">"overrun"</span></a> signal is emitted when one of the
162   queues is filled.
163   Both signals are emitted from the context of the streaming thread.
164 </p>
165 </div>
166 <p>
167 </p>
168 <p>
169 Last reviewed on 2008-01-25 (0.10.17)
170 </p>
171 <div class="refsynopsisdiv">
172 <h2>Synopsis</h2>
173 <div class="refsect2">
174 <a name="idp10450544"></a><h3>Element Information</h3>
175 <div class="variablelist"><table border="0">
176 <col align="left" valign="top">
177 <tbody>
178 <tr>
179 <td><p><span class="term">plugin</span></p></td>
180 <td>
181             <a class="link" href="gstreamer-plugins-plugin-coreelements.html#plugin-coreelements">coreelements</a>
182           </td>
183 </tr>
184 <tr>
185 <td><p><span class="term">author</span></p></td>
186 <td>Edward Hervey &lt;edward@fluendo.com&gt;</td>
187 </tr>
188 <tr>
189 <td><p><span class="term">class</span></p></td>
190 <td>Generic</td>
191 </tr>
192 </tbody>
193 </table></div>
194 </div>
195 <hr>
196 <div class="refsect2">
197 <a name="idp10458000"></a><h3>Element Pads</h3>
198 <div class="variablelist"><table border="0">
199 <col align="left" valign="top">
200 <tbody>
201 <tr>
202 <td><p><span class="term">name</span></p></td>
203 <td>sink%d</td>
204 </tr>
205 <tr>
206 <td><p><span class="term">direction</span></p></td>
207 <td>sink</td>
208 </tr>
209 <tr>
210 <td><p><span class="term">presence</span></p></td>
211 <td>request</td>
212 </tr>
213 <tr>
214 <td><p><span class="term">details</span></p></td>
215 <td>ANY</td>
216 </tr>
217 </tbody>
218 </table></div>
219 <div class="variablelist"><table border="0">
220 <col align="left" valign="top">
221 <tbody>
222 <tr>
223 <td><p><span class="term">name</span></p></td>
224 <td>src%d</td>
225 </tr>
226 <tr>
227 <td><p><span class="term">direction</span></p></td>
228 <td>source</td>
229 </tr>
230 <tr>
231 <td><p><span class="term">presence</span></p></td>
232 <td>sometimes</td>
233 </tr>
234 <tr>
235 <td><p><span class="term">details</span></p></td>
236 <td>ANY</td>
237 </tr>
238 </tbody>
239 </table></div>
240 </div>
241 </div>
242 <p>
243 </p>
244 </div>
245 <div class="refsect1">
246 <a name="gstreamer-plugins-multiqueue.details"></a><h2>Details</h2>
247 <div class="refsect2">
248 <a name="GstMultiQueue-struct"></a><h3>struct GstMultiQueue</h3>
249 <pre class="programlisting">struct GstMultiQueue;</pre>
250 <p>
251 Opaque <a class="link" href="gstreamer-plugins-multiqueue.html#GstMultiQueue"><span class="type">GstMultiQueue</span></a> structure.
252 </p>
253 </div>
254 </div>
255 <div class="refsect1">
256 <a name="gstreamer-plugins-multiqueue.property-details"></a><h2>Property Details</h2>
257 <div class="refsect2">
258 <a name="GstMultiQueue--extra-size-buffers"></a><h3>The <code class="literal">"extra-size-buffers"</code> property</h3>
259 <pre class="programlisting">  "extra-size-buffers"       <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a>                 : Read / Write</pre>
260 <p>Amount of buffers the queues can grow if one of them is empty (0=disable) (NOT IMPLEMENTED).</p>
261 <p>Default value: 5</p>
262 </div>
263 <hr>
264 <div class="refsect2">
265 <a name="GstMultiQueue--extra-size-bytes"></a><h3>The <code class="literal">"extra-size-bytes"</code> property</h3>
266 <pre class="programlisting">  "extra-size-bytes"         <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a>                 : Read / Write</pre>
267 <p>Amount of data the queues can grow if one of them is empty (bytes, 0=disable) (NOT IMPLEMENTED).</p>
268 <p>Default value: 10485760</p>
269 </div>
270 <hr>
271 <div class="refsect2">
272 <a name="GstMultiQueue--extra-size-time"></a><h3>The <code class="literal">"extra-size-time"</code> property</h3>
273 <pre class="programlisting">  "extra-size-time"          <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint64"><span class="type">guint64</span></a>               : Read / Write</pre>
274 <p>Amount of time the queues can grow if one of them is empty (in ns, 0=disable) (NOT IMPLEMENTED).</p>
275 <p>Default value: 3000000000</p>
276 </div>
277 <hr>
278 <div class="refsect2">
279 <a name="GstMultiQueue--max-size-buffers"></a><h3>The <code class="literal">"max-size-buffers"</code> property</h3>
280 <pre class="programlisting">  "max-size-buffers"         <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a>                 : Read / Write</pre>
281 <p>Max. number of buffers in the queue (0=disable).</p>
282 <p>Default value: 5</p>
283 </div>
284 <hr>
285 <div class="refsect2">
286 <a name="GstMultiQueue--max-size-bytes"></a><h3>The <code class="literal">"max-size-bytes"</code> property</h3>
287 <pre class="programlisting">  "max-size-bytes"           <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint"><span class="type">guint</span></a>                 : Read / Write</pre>
288 <p>Max. amount of data in the queue (bytes, 0=disable).</p>
289 <p>Default value: 10485760</p>
290 </div>
291 <hr>
292 <div class="refsect2">
293 <a name="GstMultiQueue--max-size-time"></a><h3>The <code class="literal">"max-size-time"</code> property</h3>
294 <pre class="programlisting">  "max-size-time"            <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#guint64"><span class="type">guint64</span></a>               : Read / Write</pre>
295 <p>Max. amount of data in the queue (in ns, 0=disable).</p>
296 <p>Default value: 2000000000</p>
297 </div>
298 <hr>
299 <div class="refsect2">
300 <a name="GstMultiQueue--high-percent"></a><h3>The <code class="literal">"high-percent"</code> property</h3>
301 <pre class="programlisting">  "high-percent"             <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gint"><span class="type">gint</span></a>                  : Read / Write</pre>
302 <p>
303 High threshold percent for buffering to finish.
304 </p>
305 <p>Allowed values: [0,100]</p>
306 <p>Default value: 99</p>
307 <p class="since">Since 0.10.26</p>
308 </div>
309 <hr>
310 <div class="refsect2">
311 <a name="GstMultiQueue--low-percent"></a><h3>The <code class="literal">"low-percent"</code> property</h3>
312 <pre class="programlisting">  "low-percent"              <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gint"><span class="type">gint</span></a>                  : Read / Write</pre>
313 <p>
314 Low threshold percent for buffering to start.
315 </p>
316 <p>Allowed values: [0,100]</p>
317 <p>Default value: 10</p>
318 <p class="since">Since 0.10.26</p>
319 </div>
320 <hr>
321 <div class="refsect2">
322 <a name="GstMultiQueue--use-buffering"></a><h3>The <code class="literal">"use-buffering"</code> property</h3>
323 <pre class="programlisting">  "use-buffering"            <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a>              : Read / Write</pre>
324 <p>
325 Enable the buffering option in multiqueue so that BUFFERING messages are
326 emited based on low-/high-percent thresholds.
327 </p>
328 <p>Default value: FALSE</p>
329 <p class="since">Since 0.10.26</p>
330 </div>
331 </div>
332 <div class="refsect1">
333 <a name="gstreamer-plugins-multiqueue.signal-details"></a><h2>Signal Details</h2>
334 <div class="refsect2">
335 <a name="GstMultiQueue-overrun"></a><h3>The <code class="literal">"overrun"</code> signal</h3>
336 <pre class="programlisting"><span class="returnvalue">void</span>                user_function                      (<a class="link" href="gstreamer-plugins-multiqueue.html#GstMultiQueue"><span class="type">GstMultiQueue</span></a> *multiqueue,
337                                                         <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a>       user_data)       : <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS"><code class="literal">Run First</code></a></pre>
338 <p>
339 Reports that one of the queues in the multiqueue is full (overrun).
340 A queue is full if the total amount of data inside it (num-buffers, time,
341 size) is higher than the boundary values which can be set through the
342 GObject properties.
343 </p>
344 <p>
345 This can be used as an indicator of pre-roll.
346 </p>
347 <div class="variablelist"><table border="0">
348 <col align="left" valign="top">
349 <tbody>
350 <tr>
351 <td><p><span class="term"><em class="parameter"><code>multiqueue</code></em> :</span></p></td>
352 <td>the multiqueue instance</td>
353 </tr>
354 <tr>
355 <td><p><span class="term"><em class="parameter"><code>user_data</code></em> :</span></p></td>
356 <td>user data set when the signal handler was connected.</td>
357 </tr>
358 </tbody>
359 </table></div>
360 </div>
361 <hr>
362 <div class="refsect2">
363 <a name="GstMultiQueue-underrun"></a><h3>The <code class="literal">"underrun"</code> signal</h3>
364 <pre class="programlisting"><span class="returnvalue">void</span>                user_function                      (<a class="link" href="gstreamer-plugins-multiqueue.html#GstMultiQueue"><span class="type">GstMultiQueue</span></a> *multiqueue,
365                                                         <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a>       user_data)       : <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#G-SIGNAL-RUN-FIRST:CAPS"><code class="literal">Run First</code></a></pre>
366 <p>
367 This signal is emitted from the streaming thread when there is
368 no data in any of the queues inside the multiqueue instance (underrun).
369 </p>
370 <p>
371 This indicates either starvation or EOS from the upstream data sources.
372 </p>
373 <div class="variablelist"><table border="0">
374 <col align="left" valign="top">
375 <tbody>
376 <tr>
377 <td><p><span class="term"><em class="parameter"><code>multiqueue</code></em> :</span></p></td>
378 <td>the multqueue instance</td>
379 </tr>
380 <tr>
381 <td><p><span class="term"><em class="parameter"><code>user_data</code></em> :</span></p></td>
382 <td>user data set when the signal handler was connected.</td>
383 </tr>
384 </tbody>
385 </table></div>
386 </div>
387 </div>
388 <div class="refsect1">
389 <a name="gstreamer-plugins-multiqueue.see-also"></a><h2>See Also</h2>
390 <a class="link" href="gstreamer-plugins-queue.html#GstQueue"><span class="type">GstQueue</span></a>
391 </div>
392 </div>
393 <div class="footer">
394 <hr>
395           Generated by GTK-Doc V1.17</div>
396 </body>
397 </html>