docs/manual/queues.xml

   1 <chapter id="cha-queues">
   2   <title>Queues</title>
   3   <para>
   4     A <classname>GstQueue</classname> is a filter element.
   5     Queues can be used to link two elements in such way that the data can
   6     be buffered.
   7   </para>
   8   <para>
   9     A buffer that is sinked to a Queue will not automatically be pushed to the
  10     next linked element but will be buffered. It will be pushed to the next
  11     element as soon as a gst_pad_pull () is called on the queue's source pad.
  12   </para>
  13   <para>
  14     Queues are mostly used in conjunction with a <classname>GstThread</classname> to
  15     provide an external link for the thread elements. You could have one
  16     thread feeding buffers into a <classname>GstQueue</classname> and another
  17     thread repeadedly calling gst_pad_pull () on the queue to feed its
  18     internal elements.
  19   </para>
  20
  21   <para>
  22     Below is a figure of a two-threaded decoder. We have one thread (the main execution
  23     thread) reading the data from a file, and another thread decoding the data.
  24   </para>
  25   <figure float="1" id="sec-queues-img">
  26     <title>a two-threaded decoder with a queue</title>
  27     <mediaobject>
  28       <imageobject>
  29         <imagedata fileref="images/queue.&magic;" format="&MAGIC;" />
  30       </imageobject>
  31     </mediaobject>
  32   </figure>
  33
  34   <para>
  35     The standard <application>GStreamer</application> queue implementation has some
  36     properties that can be changed using the g_objet_set () method. To set the
  37     maximum number of buffers that can be queued to 30, do:
  38   </para>
  39   <programlisting>
  40   g_object_set (G_OBJECT (queue), "max_level", 30, NULL);
  41   </programlisting>
  42
  43   <para>
  44     The following MP3 player shows you how to create the above pipeline
  45     using a thread and a queue.
  46   </para>
  47
  48   <programlisting>
  49 /* example-begin queue.c */
  50 #include &lt;stdlib.h&gt;
  51 #include &lt;gst/gst.h&gt;
  52
  53 gboolean playing;
  54
  55 /* eos will be called when the src element has an end of stream */
  56 void
  57 eos (GstElement *element, gpointer data)
  58 {
  59   g_print ("have eos, quitting\n");
  60
  61   playing = FALSE;
  62 }
  63
  64 int
  65 main (int argc, char *argv[])
  66 {
  67   GstElement *filesrc, *audiosink, *queue, *decode;
  68   GstElement *bin;
  69   GstElement *thread;
  70
  71   gst_init (&amp;argc,&amp;argv);
  72
  73   if (argc != 2) {
  74     g_print ("usage: %s &lt;mp3 filename&gt;\n", argv[0]);
  75     exit (-1);
  76   }
  77
  78   /* create a new thread to hold the elements */
  79   thread = gst_thread_new ("thread");
  80   g_assert (thread != NULL);
  81
  82   /* create a new bin to hold the elements */
  83   bin = gst_bin_new ("bin");
  84   g_assert (bin != NULL);
  85
  86   /* create a disk reader */
  87   filesrc = gst_element_factory_make ("filesrc", "disk_source");
  88   g_assert (filesrc != NULL);
  89   g_object_set (G_OBJECT (filesrc), "location", argv[1], NULL);
  90   g_signal_connect (G_OBJECT (filesrc), "eos",
  91                     G_CALLBACK (eos), thread);
  92
  93   queue = gst_element_factory_make ("queue", "queue");
  94   g_assert (queue != NULL);
  95
  96   /* and an audio sink */
  97   audiosink = gst_element_factory_make ("osssink", "play_audio");
  98   g_assert (audiosink != NULL);
  99
 100   decode = gst_element_factory_make ("mad", "decode");
 101
 102   /* add objects to the main bin */
 103   gst_bin_add_many (GST_BIN (thread), decode, audiosink, NULL);
 104
 105   gst_bin_add_many (GST_BIN (bin), filesrc, queue, thread, NULL);
 106
 107
 108   gst_element_link (filesrc, queue);
 109   gst_element_link_many (queue, decode, audiosink, NULL);
 110
 111   /* start playing */
 112   gst_element_set_state (GST_ELEMENT (bin), GST_STATE_PLAYING);
 113
 114   playing = TRUE;
 115
 116   while (playing) {
 117     gst_bin_iterate (GST_BIN (bin));
 118   }
 119
 120   gst_element_set_state (GST_ELEMENT (bin), GST_STATE_NULL);
 121
 122   return 0;
 123 }
 124 /* example-end queue.c */
 125   </programlisting>
 126
 127
 128
 129 </chapter>