docs/manual/bins.sgml

   1 <chapter id="cha-bins">
   2   <title>Bins</title>
   3   <para>
   4     A Bin is a container element. You can add elements to a bin. Since a bin is
   5     an <classname>GstElement</classname> itself, it can also be added to another bin.
   6   </para>
   7   <para>
   8     Bins allow you to combine connected elements into one logical element. You do
   9     not deal with the individual elements anymore but with just one element, the bin.
  10     We will see that this is extremely powerfull when you are going to construct
  11     complex pipelines since it allows you to break up the pipeline in smaller chunks.
  12   </para>
  13   <para>
  14     The bin will also manage the elements contained in it. It will figure out how
  15     the data will flow in the bin and generate an optimal plan for that data flow. Plan
  16     generation is one of the most complicated procedures in GStreamer.
  17   </para>
  18
  19   <figure float="1" id="sec-bin-img">
  20     <title>Visualisation of a <classname>GstBin</classname> element with some elements in it</title>
  21     <graphic fileref="images/bin-element" format="png"></graphic>
  22   </figure>
  23
  24   <para>
  25     There are two standard bins available to the GStreamer programmer:
  26
  27     <itemizedlist>
  28       <listitem>
  29         <para>
  30           A pipeline (<classname>GstPipeline</classname>). Which is a generic container you will
  31           use most of the time.
  32         </para>
  33       </listitem>
  34       <listitem>
  35         <para>
  36           A thread (<classname>GstThread</classname>). All the elements in the thread bin will
  37           run in a separate thread. You will haver to use this bin if you carfully have to
  38           synchronize audio and video for example. You will learn more about threads in.. <!-- FIXME -->
  39         </para>
  40       </listitem>
  41     </itemizedlist>
  42   </para>
  43
  44   <sect1 id="sec-bin-create">
  45     <title>Creating a bin</title>
  46     <para>
  47       You create a bin with  a specified name 'mybin' with:
  48     </para>
  49     <programlisting>
  50   GstElement *bin;
  51
  52   gst_bin_new ("mybin");
  53    ...
  54     </programlisting>
  55     <para>
  56       A thread can be created with:
  57     </para>
  58     <programlisting>
  59   GstElement *thread;
  60
  61   gst_thread_new ("mythread");
  62    ...
  63     </programlisting>
  64     <para>
  65       Pipelines are created with gst_pipeline_new ("name");
  66     </para>
  67   </sect1>
  68
  69   <sect1 id="sec-bin-adding">
  70     <title>Adding elements to a bin</title>
  71     <para>
  72       Elements are added to a bin with the following code sample:
  73     </para>
  74     <programlisting>
  75   GstElement *element;
  76   GstElement *bin;
  77
  78   bin = gst_bin_new ("mybin");
  79
  80   element = gst_elementfactory_make ("mpg123", "decoder");
  81   gst_bin_add (GST_BIN (bin), element);
  82    ...
  83     </programlisting>
  84     <para>
  85       Bins and threads can be added to other bins too. This allows you to create nested
  86       bins.
  87     </para>
  88     <para>
  89       To get an element from the bin you can use:
  90     </para>
  91     <programlisting>
  92   GstElement *element;
  93
  94   element = gst_bin_get_by_name (GST_BIN (bin), "decoder");
  95    ...
  96     </programlisting>
  97     <para>
  98       You can see that the name of the element becomes very handy for retrieving the
  99       element from an bin by using the elements name. gst_bin_get_by_name () will
 100       recursively search nested bins.
 101     </para>
 102     <para>
 103       To get a list of elements in a bin, use:
 104     </para>
 105     <programlisting>
 106   GList *elements;
 107
 108   elements = gst_bin_get_list (GST_BIN (bin));
 109
 110   while (elements) {
 111     GstElement *element = GST_ELEMENT (elements-&gt;data);
 112
 113     g_print ("element in bin: %s\n", gst_element_get_name (element));
 114
 115     elements = g_list_next (elements);
 116   }
 117    ...
 118     </programlisting>
 119     <para>
 120       To remove an element from a bin use:
 121     </para>
 122     <programlisting>
 123   GstElement *element;
 124
 125   gst_bin_remove (GST_BIN (bin), element);
 126    ...
 127     </programlisting>
 128   </sect1>
 129
 130   <sect1 id="sec-bin-custom">
 131     <title>Custom bins</title>
 132     <para>
 133       The application programmer can create custom bins packed with elements to perform a
 134       specific task. This allow you to write an MPEG audio decoder with just the follwing lines
 135       of code:
 136
 137       <programlisting>
 138
 139   // create the mp3player element
 140   GstElement *mp3player = gst_elementfactory_make("mp3player","mp3player");
 141   // set the source mp3 audio file
 142   gtk_object_set(GTK_OBJECT(mp3player), "location", "helloworld.mp3", NULL);
 143   // start playback
 144   gst_element_set_state(GST_ELEMENT(mp3player),GST_STATE_PLAYING);
 145    ...
 146   // pause playback
 147   gst_element_set_state(GST_ELEMENT(mp3player),GST_STATE_PAUSED);
 148    ...
 149   // stop
 150   gst_element_set_state(GST_ELEMENT(mp3player),GST_STATE_NULL);
 151       </programlisting>
 152
 153       Custom bins can be created with a plugin or an XML description. You will find more
 154       information about creating custom bin in the Filter-Writers-Guide.
 155     </para>
 156   </sect1>
 157
 158   <sect1 id="sec-bin-ghostpads">
 159     <title>Ghostpads</title>
 160     <para>
 161       You can see from figure ... how a bin has no pads of its own. This is where Ghostpads
 162       come into play.
 163     </para>
 164     <para>
 165       A ghostpad is a pad from some element in the bin that has been promoted to the bin.
 166       This way, the bin also has a pad. The bin becomes just another element with a pad and
 167       you can then use the bin just like any other element. This is a very important feature
 168       for creating custom bins.
 169     </para>
 170
 171     <figure float="1" id="sec-bin-ghost-img">
 172       <title>Visualisation of a <classname>GstBin</classname> element with a ghostpad</title>
 173       <graphic fileref="images/bin-element-ghost" format="png"></graphic>
 174     </figure>
 175     <para>
 176       Above is a representation of a ghostpad. the sinkpad of element one is now also a pad
 177       of the bin.
 178     </para>
 179     <para>
 180       Ghostpads can actually be added to all <classname>GstElement</classname>s and not just
 181       <classname>GstBin</classname>s. Use the following code example to add a ghostpad to a bin:
 182     </para>
 183     <programlisting>
 184   GstElement *bin;
 185   GstElement *element;
 186
 187   element = gst_elementfactory_create ("mpg123", "decoder");
 188   bin = gst_bin_new ("mybin");
 189
 190   gst_bin_add (GST_BIN (bin), element);
 191
 192   gst_element_add_ghost_pad (bin, gst_element_get_pad (element, "sink"));
 193
 194     </programlisting>
 195     <para>
 196       In the above example, the bin now also has a pad: the pad called 'sink' of the
 197       given element. We can now, for example, connect the srcpad of a disksrc to the
 198       bin with:
 199     </para>
 200     <programlisting>
 201   GstElement *disksrc;
 202
 203   disksrc = gst_elementfactory_create ("disksrc", "disk_reader");
 204
 205   gst_element_connect (disksrc, "src", bin, "sink");
 206     ...
 207     </programlisting>
 208   </sect1>
 209
 210 </chapter>