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       perform state changes on the elements as well as collect and
  23       forward bus messages.
  24     </para>
  25
  26     <figure float="1" id="section-bin-img">
  27       <title>Visualisation of a bin with some elements in it</title>
  28         <mediaobject>
  29           <imageobject>
  30             <imagedata scale="75" fileref="images/bin-element.&image;" format="&IMAGE;"/>
  31           </imageobject>
  32         </mediaobject>
  33     </figure>
  34
  35     <para>
  36       There is one specialized type of bin available to the
  37       &GStreamer; programmer:
  38     </para>
  39     <itemizedlist>
  40       <listitem>
  41         <para>
  42           A pipeline: a generic container that manages the synchronization
  43           and bus messages of the contained elements. The toplevel bin has
  44           to be a pipeline, every application thus needs at least one of
  45           these.
  46         </para>
  47       </listitem>
  48     </itemizedlist>
  49   </sect1>
  50
  51   <sect1 id="section-bin-create">
  52     <title>Creating a bin</title>
  53     <para>
  54       Bins are created in the same way that other elements are created,
  55       i.e. using an element factory. There are also convenience functions
  56       available (<function>gst_bin_new ()</function> and
  57       <function>gst_pipeline_new ()</function>).
  58       To add elements to a bin or remove elements from a
  59       bin, you can use <function>gst_bin_add ()</function> and
  60       <function>gst_bin_remove ()</function>. Note that the bin that you
  61       add an element to will take ownership of that element. If you
  62       destroy the bin, the element will be dereferenced with it. If you
  63       remove an element from a bin, it will be dereferenced automatically.
  64     </para>
  65     <programlisting><!-- example-begin bin.c a -->
  66 #include &lt;gst/gst.h&gt;
  67
  68 int
  69 main (int   argc,
  70       char *argv[])
  71 {
  72   GstElement *bin, *pipeline, *source, *sink;
  73
  74   /* init */
  75   gst_init (&amp;argc, &amp;argv);
  76
  77   /* create */
  78   pipeline = gst_pipeline_new ("my_pipeline");
  79   bin = gst_bin_new ("my_bin");
  80   source = gst_element_factory_make ("fakesrc", "source");
  81   sink = gst_element_factory_make ("fakesink", "sink");
  82
  83   /* First add the elements to the bin */
  84   gst_bin_add_many (GST_BIN (bin), source, sink, NULL);
  85   /* add the bin to the pipeline */
  86   gst_bin_add (GST_BIN (pipeline), bin);
  87
  88   /* link the elements */
  89   gst_element_link (source, sink);
  90 <!-- example-end bin.c a -->
  91 [..]<!-- example-begin bin.c b --><!--
  92   return 0;
  93 --><!-- example-end bin.c b -->
  94 <!-- example-begin bin.c c -->
  95 }
  96     <!-- example-end bin.c c --></programlisting>
  97     <para>
  98       There are various functions to lookup elements in a bin. The most
  99       commonly used are <function>gst_bin_get_by_name ()</function> and
 100       <function>gst_bin_get_by_interface ()</function>. You can also
 101       iterate over all elements that a bin contains using the function
 102       <function>gst_bin_iterate_elements ()</function>. See the API references
 103       of <ulink type="http"
 104       url="&URLAPI;GstBin.html"><classname>GstBin</classname></ulink>
 105       for details.
 106     </para>
 107   </sect1>
 108
 109   <sect1 id="section-bin-custom">
 110     <title>Custom bins</title>
 111     <para>
 112       The application programmer can create custom bins packed with elements
 113       to perform a specific task. This allows you, for example, to write
 114       an Ogg/Vorbis decoder with just the following lines of code:
 115     </para>
 116     <programlisting>
 117 int
 118 main (int   argc,
 119       char *argv[])
 120 {
 121   GstElement *player;
 122
 123   /* init */
 124   gst_init (&amp;argc, &amp;argv);
 125
 126   /* create player */
 127   player = gst_element_factory_make ("oggvorbisplayer", "player");
 128
 129   /* set the source audio file */
 130   g_object_set (player, "location", "helloworld.ogg", NULL);
 131
 132   /* start playback */
 133   gst_element_set_state (GST_ELEMENT (player), GST_STATE_PLAYING);
 134 [..]
 135 }
 136     </programlisting>
 137     <para>
 138       (This is a silly example of course, there already exists a much more
 139       powerful and versatile custom bin like this: the playbin element.)
 140     </para>
 141     <para>
 142       Custom bins can be created with a plugin or from the application. You
 143       will find more information about creating custom bin in the <ulink
 144       type="http"
 145       url="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/pwg/html/index.html">Plugin
 146       Writers Guide</ulink>.
 147     </para>
 148     <para>
 149       Examples of such custom bins are the playbin and uridecodebin elements from<ulink
 150       type="http"
 151       url="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-plugins-base-plugins/html/index.html">
 152       gst-plugins-base</ulink>.
 153     </para>
 154   </sect1>
 155   <sect1 id="section-bin-state-change-handling">
 156     <title>Bins manage states of their children</title>
 157     <para>
 158       Bins manage the state of all elements contained in them. If you set
 159       a bin (or a pipeline, which is a special top-level type of bin) to
 160       a certain target state using <function>gst_element_set_state ()</function>,
 161       it will make sure all elements contained within it will also be set
 162       to this state. This means it's usually only necessary to set the state
 163       of the top-level pipeline to start up the pipeline or shut it down.
 164     </para>
 165     <para>
 166       Note, however, that if elements are added to a bin or pipeline that's
 167       already running, , e.g. from within a "pad-added" or "new-decoded-pad"
 168       signal callback, its state will not automatically be brought in line with
 169       the current state or target state of the bin or pipeline it was added to.
 170       Instead, you have to need to set it to the desired target state yourself
 171       using <function>gst_element_set_state ()</function> or
 172       <function>gst_element_sync_state_with_parent ()</function> when adding
 173       elements to an already-running pipeline.
 174     </para>
 175   </sect1>
 176 </chapter>