docs/manual/basics-bins.xml

   1 <chapter id="chapter-bins">
   2   <title>Bins</title>
   3   <para>
   4     A bin is a container element. You can add elements to a bin. Since a
   5     bin is an element itself, a bin can be handled in the same way as any
   6     other element. Therefore, the whole previous chapter (<xref
   7     linkend="chapter-elements"/>) applies to bins as well.
   8   </para>
   9
  10   <sect1 id="section-bins">
  11     <title>What are bins</title>
  12     <para>
  13       Bins allow you to combine a group of linked elements into one
  14       logical element. You do not deal with the individual elements
  15       anymore but with just one element, the bin. We will see that
  16       this is extremely powerful when you are going to construct
  17       complex pipelines since it allows you to break up the pipeline
  18       in smaller chunks.
  19     </para>
  20     <para>
  21       The bin will also manage the elements contained in it. It will
  22       figure out how the data will flow in the bin and generate an
  23       optimal plan for that data flow. Plan generation is one of the
  24       most complicated procedures in &GStreamer;. You will learn more
  25       about this process, called scheduling, in <xref
  26       linkend="chapter-scheduler"/>.
  27     </para>
  28
  29     <figure float="1" id="section-bin-img">
  30       <title>Visualisation of a bin with some elements in it</title>
  31         <mediaobject>
  32           <imageobject>
  33             <imagedata fileref="images/bin-element.&image;" format="&IMAGE;"/>
  34           </imageobject>
  35         </mediaobject>
  36     </figure>
  37
  38     <para>
  39       There are two specialized types of bins available to the
  40       &GStreamer; programmer:
  41     </para>
  42     <itemizedlist>
  43       <listitem>
  44         <para>
  45           A pipeline: a generic container that allows scheduling of the
  46           containing elements.  The toplevel bin has to be a pipeline.
  47           Every application thus needs at least one of these. Applications
  48           can iterate pipelines using <function>gst_bin_iterate
  49           ()</function> to make it process data while in the playing state.
  50         </para>
  51       </listitem>
  52       <listitem>
  53         <para>
  54           A thread: a bin that will be run in a separate execution thread.
  55           You will have to use this bin if you have to carefully
  56           synchronize audio and video, or for buffering. You will learn
  57           more about threads in <xref linkend="chapter-threads"/>.
  58         </para>
  59       </listitem>
  60     </itemizedlist>
  61   </sect1>
  62
  63   <sect1 id="section-bin-create">
  64     <title>Creating a bin</title>
  65     <para>
  66       Bins are created in the same way that other elements are created,
  67       i.e. using an element factory. There are also convenience functions
  68       available (<function>gst_bin_new ()</function>,
  69       <function>gst_thread_new ()</function> and <function>gst_pipeline_new
  70       ()</function>). To add elements to a bin or remove elements from a
  71       bin, you can use <function>gst_bin_add ()</function> and
  72       <function>gst_bin_remove ()</function>. Note that the bin that you
  73       add an element to will take ownership of that element. If you
  74       destroy the bin, the element will be dereferenced with it. If you
  75       remove an element from a bin, it will be dereferenced automatically.
  76     </para>
  77     <programlisting>
  78 int
  79 main (int   argc,
  80       char *argv[])
  81 {
  82   GstElement *bin, *pipeline, *source, *sink;
  83
  84   /* init */
  85   gst_init (&amp;argc, &amp;argv);
  86
  87   /* create */
  88   pipeline = gst_pipeline_new ("my_pipeline");
  89   bin = gst_pipeline_new ("my_bin");
  90   source = gst_element_factory_make ("fakesrc", "source");
  91   sink = gst_element_factory_make ("fakesink", "sink");
  92
  93   /* set up pipeline */
  94   gst_bin_add_many (GST_BIN (bin), source, sink, NULL);
  95   gst_bin_add (GST_BIN (pipeline), bin);
  96   gst_element_link (source, sink);
  97
  98 [..]
  99 }
 100     </programlisting>
 101     <para>
 102       There are various functions to lookup elements in a bin. You can
 103       also get a list of all elements that a bin contains using the function
 104       <function>gst_bin_get_list ()</function>. See the API references of
 105       <ulink type="http"
 106       url="../../GStreamer/html/GstBin.html"><classname>GstBin</classname></ulink>
 107       for details.
 108     </para>
 109   </sect1>
 110
 111   <sect1 id="section-bin-custom">
 112     <title>Custom bins</title>
 113     <para>
 114       The application programmer can create custom bins packed with elements
 115       to perform a specific task. This allows you, for example, to write
 116       an Ogg/Vorbis decoder with just the following lines of code:
 117     </para>
 118     <programlisting>
 119 int
 120 main (int   argc
 121       char *argv[])
 122 {
 123   GstElement *player;
 124
 125   /* init */
 126   gst_init (&amp;argc, &amp;argv);
 127
 128   /* create player */
 129   player = gst_element_factory_make ("oggvorbisplayer", "player");
 130
 131   /* set the source audio file */
 132   g_object_set (G_OBJECT (player), "location", "helloworld.ogg", NULL);
 133
 134   /* start playback */
 135   gst_element_set_state (GST_ELEMENT (mp3player), GST_STATE_PLAYING);
 136 [..]
 137 }
 138     </programlisting>
 139     <para>
 140       Custom bins can be created with a plugin or an XML description. You
 141       will find more information about creating custom bin in the <ulink
 142       type="http"
 143       url="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/pwg/html/index.html">Plugin
 144       Writers Guide</ulink>.
 145     </para>
 146   </sect1>
 147 </chapter>