docs/manual/basics-bins.xml

   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 linked 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 powerful 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       <mediaobject>
  22         <imageobject>
  23           <imagedata fileref="images/bin-element.&image;" format="&IMAGE;" />
  24         </imageobject>
  25       </mediaobject>
  26   </figure>
  27
  28   <para>
  29     There are two standard bins available to the GStreamer programmer:
  30
  31     <itemizedlist>
  32       <listitem>
  33         <para>
  34           A pipeline (<classname>GstPipeline</classname>). Which is a generic container you will
  35           use most of the time. The toplevel bin has to be a pipeline.
  36         </para>
  37       </listitem>
  38       <listitem>
  39         <para>
  40           A thread (<classname>GstThread</classname>). The plan for the
  41           <classname>GstThread</classname> will be run in a separate thread. You will have to use
  42           this bin if you have to carefully synchronize audio and video, for example. You will learn
  43           more about threads in <xref linkend="cha-threads"/>.
  44         </para>
  45       </listitem>
  46     </itemizedlist>
  47   </para>
  48
  49   <sect1 id="sec-bin-create">
  50     <title>Creating a bin</title>
  51     <para>
  52       Bins are created in the same way that other elements are created. ie.
  53       using an element factory, or any of the associated convenience functions:
  54     </para>
  55     <programlisting>
  56   GstElement *bin, *thread, *pipeline;
  57
  58   /* create a new bin called 'mybin'. this bin will be only for organizational purposes; a normal
  59      GstBin doesn't affect plan generation */
  60   bin = gst_element_factory_make ("bin", "mybin");
  61
  62   /* create a new thread, and give it a unique name */
  63   thread = gst_element_factory_make ("thread", NULL);
  64
  65   /* the core bins (GstBin, GstThread, GstPipeline) also have convenience APIs,
  66      gst_&lt;bintype&gt;_new (). these are equivalent to the gst_element_factory_make () syntax. */
  67   pipeline = gst_pipeline_new ("pipeline_name");
  68     </programlisting>
  69   </sect1>
  70
  71   <sect1 id="sec-bin-adding">
  72     <title>Adding elements to a bin</title>
  73     <para>
  74       Elements are added to a bin with the following code sample:
  75     </para>
  76     <programlisting>
  77   GstElement *element;
  78   GstElement *bin;
  79
  80   bin = gst_bin_new ("mybin");
  81
  82   element = gst_element_factory_make ("mpg123", "decoder");
  83   gst_bin_add (GST_BIN (bin), element);
  84    ...
  85     </programlisting>
  86     <para>
  87       Bins and threads can be added to other bins too. This allows you to create nested bins. Note
  88       that it doesn't make very much sense to add a <classname>GstPipeline</classname> to anything,
  89       as it's a toplevel bin that needs to be explicitly iterated.
  90     </para>
  91     <para>
  92       To get an element from the bin you can use:
  93     </para>
  94     <programlisting>
  95   GstElement *element;
  96
  97   element = gst_bin_get_by_name (GST_BIN (bin), "decoder");
  98    ...
  99     </programlisting>
 100     <para>
 101       You can see that the name of the element becomes very handy
 102       for retrieving the element from a bin by using the element's
 103       name. gst_bin_get_by_name () will recursively search nested bins.
 104     </para>
 105     <para>
 106       To get a list of elements in a bin, use:
 107     </para>
 108     <programlisting>
 109   GList *elements;
 110
 111   elements = gst_bin_get_list (GST_BIN (bin));
 112
 113   while (elements) {
 114     GstElement *element = GST_ELEMENT (elements-&gt;data);
 115
 116     g_print ("element in bin: %s\n", GST_OBJECT_NAME (GST_OBJECT (element)));
 117
 118     elements = g_list_next (elements);
 119   }
 120    ...
 121     </programlisting>
 122     <para>
 123       To remove an element from a bin, use:
 124     </para>
 125     <programlisting>
 126   GstElement *element;
 127
 128   gst_bin_remove (GST_BIN (bin), element);
 129    ...
 130     </programlisting>
 131     <para>
 132       To add many elements to a bin at the same time, use the gst_bin_add_many
 133       () function. Remember to pass NULL as the last argument.
 134     </para>
 135     <programlisting>
 136   GstElement *filesrc, *decoder, *audiosink;
 137   GstBin *bin;
 138
 139   /* instantiate the elements and the bins... */
 140
 141   gst_bin_add_many (bin, filesrc, decoder, audiosink, NULL);
 142     </programlisting>
 143   </sect1>
 144
 145   <sect1 id="sec-bin-custom">
 146     <title>Custom bins</title>
 147     <para>
 148       The application programmer can create custom bins packed with elements
 149       to perform a specific task. This allows you to write an MPEG audio
 150       decoder with just the following lines of code:
 151     </para>
 152     <programlisting>
 153
 154   /* create the mp3player element */
 155   GstElement *mp3player = gst_element_factory_make ("mp3player", "mp3player");
 156   /* set the source mp3 audio file */
 157   g_object_set (G_OBJECT (mp3player), "location", "helloworld.mp3", NULL);
 158   /* start playback */
 159   gst_element_set_state (GST_ELEMENT (mp3player), GST_STATE_PLAYING);
 160    ...
 161   /* pause playback */
 162   gst_element_set_state (GST_ELEMENT (mp3player), GST_STATE_PAUSED);
 163    ...
 164   /* stop */
 165   gst_element_set_state (GST_ELEMENT (mp3player), GST_STATE_NULL);
 166     </programlisting>
 167     <para>
 168       Note that the above code assumes that the mp3player bin derives itself
 169       from a <classname>GstThread</classname>, which begins to play as soon
 170       as its state is set to PLAYING.  Other bin types may need explicit
 171       iteration. For more information, see <xref linkend="cha-threads"/>.
 172     </para>
 173     <para>
 174       Custom bins can be created with a plugin or an XML description. You
 175       will find more information about creating custom bin in the Plugin
 176       Writers Guide (FIXME ref).
 177     </para>
 178   </sect1>
 179
 180   <sect1 id="sec-bin-ghostpads">
 181     <title>Ghost pads</title>
 182     <para>
 183       You can see from figure <xref linkend="sec-bin-noghost-img"/> how a bin has no pads of its own.
 184       This is where "ghost pads" come into play.
 185     </para>
 186     <figure float="1" id="sec-bin-noghost-img">
 187       <title>Visualisation of a <classname>GstBin</classname> element without ghost pads</title>
 188       <mediaobject>
 189         <imageobject>
 190           <imagedata fileref="images/bin-element-noghost.&image;" format="&IMAGE;" />
 191         </imageobject>
 192       </mediaobject>
 193     </figure>
 194     <para>
 195       A ghost pad is a pad from some element in the bin that has been promoted to the bin.
 196       This way, the bin also has a pad. The bin becomes just another element with a pad and
 197       you can then use the bin just like any other element. This is a very important feature
 198       for creating custom bins.
 199     </para>
 200
 201     <figure float="1" id="sec-bin-ghost-img">
 202       <title>Visualisation of a <classname>GstBin</classname> element with a ghost pad</title>
 203       <mediaobject>
 204         <imageobject>
 205           <imagedata fileref="images/bin-element-ghost.&image;" format="&IMAGE;" />
 206         </imageobject>
 207       </mediaobject>
 208     </figure>
 209     <para>
 210       Above is a representation of a ghost pad. The sink pad of element one is now also a pad
 211       of the bin.
 212     </para>
 213     <para>
 214       Ghost pads can actually be added to all <classname>GstElement</classname>s and not just
 215       <classname>GstBin</classname>s. Use the following code example to add a ghost pad to a bin:
 216     </para>
 217     <programlisting>
 218   GstElement *bin;
 219   GstElement *element;
 220
 221   element = gst_element_factory_create ("mad", "decoder");
 222   bin = gst_bin_new ("mybin");
 223
 224   gst_bin_add (GST_BIN (bin), element);
 225
 226   gst_element_add_ghost_pad (bin, gst_element_get_pad (element, "sink"), "sink");
 227
 228     </programlisting>
 229     <para>
 230       In the above example, the bin now also has a pad: the pad called 'sink'
 231       of the given element.
 232     </para>
 233     <para>
 234       We can now, for example, link the source pad of a filesrc element
 235       to the bin with:
 236     </para>
 237     <programlisting>
 238   GstElement *filesrc;
 239
 240   filesrc = gst_element_factory_create ("filesrc", "disk_reader");
 241
 242   gst_element_link_pads (filesrc, "src", bin, "sink");
 243     ...
 244     </programlisting>
 245   </sect1>
 246
 247 </chapter>