markdown/manual/building/bins.md

   1 ---
   2 title: Bins
   3 ...
   4
   5 # Bins
   6
   7 A bin is a container element. You can add elements to a bin. Since a bin
   8 is an element itself, a bin can be handled in the same way as any other
   9 element. Therefore, the whole previous chapter
  10 ([Elements](manual/building/elements.md)) applies to bins as well.
  11
  12 ## What are bins
  13
  14 Bins allow you to combine a group of linked elements into one logical
  15 element. You do not deal with the individual elements anymore but with
  16 just one element, the bin. We will see that this is extremely powerful
  17 when you are going to construct complex pipelines since it allows you to
  18 break up the pipeline in smaller chunks.
  19
  20 The bin will also manage the elements contained in it. It will perform
  21 state changes on the elements as well as collect and forward bus
  22 messages.
  23
  24 ![Visualisation of a bin with some elements in
  25 it](images/bin-element.png "fig:")
  26
  27 There is one specialized type of bin available to the GStreamer
  28 programmer:
  29
  30   - A pipeline: a generic container that manages the synchronization and
  31     bus messages of the contained elements. The toplevel bin has to be a
  32     pipeline, every application thus needs at least one of these.
  33
  34 ## Creating a bin
  35
  36 Bins are created in the same way that other elements are created, i.e.
  37 using an element factory. There are also convenience functions available
  38 (`gst_bin_new ()` and `gst_pipeline_new ()`). To add elements to a bin
  39 or remove elements from a bin, you can use `gst_bin_add ()` and
  40 `gst_bin_remove ()`. Note that the bin that you add an element to will
  41 take ownership of that element. If you destroy the bin, the element will
  42 be dereferenced with it. If you remove an element from a bin, it will be
  43 dereferenced automatically.
  44
  45 ```
  46 #include <gst/gst.h>
  47
  48 int
  49 main (int   argc,
  50       char *argv[])
  51 {
  52   GstElement *bin, *pipeline, *source, *sink;
  53
  54   /* init */
  55   gst_init (&argc, &argv);
  56
  57   /* create */
  58   pipeline = gst_pipeline_new ("my_pipeline");
  59   bin = gst_bin_new ("my_bin");
  60   source = gst_element_factory_make ("fakesrc", "source");
  61   sink = gst_element_factory_make ("fakesink", "sink");
  62
  63   /* First add the elements to the bin */
  64   gst_bin_add_many (GST_BIN (bin), source, sink, NULL);
  65   /* add the bin to the pipeline */
  66   gst_bin_add (GST_BIN (pipeline), bin);
  67
  68   /* link the elements */
  69   gst_element_link (source, sink);
  70
  71 [..]
  72
  73 }
  74
  75 ```
  76
  77 There are various functions to lookup elements in a bin. The most
  78 commonly used are `gst_bin_get_by_name ()` and `gst_bin_get_by_interface
  79 ()`. You can also iterate over all elements that a bin contains using
  80 the function `gst_bin_iterate_elements ()`. See the API references of
  81 [`GstBin`](http://gstreamer.freedesktop.org/data/doc/gstreamer/stable/gstreamer/html/GstBin.html)
  82 for details.
  83
  84 ## Custom bins
  85
  86 The application programmer can create custom bins packed with elements
  87 to perform a specific task. This allows you, for example, to write an
  88 Ogg/Vorbis decoder with just the following lines of code:
  89
  90 ```
  91 int
  92 main (int   argc,
  93       char *argv[])
  94 {
  95   GstElement *player;
  96
  97   /* init */
  98   gst_init (&argc, &argv);
  99
 100   /* create player */
 101   player = gst_element_factory_make ("oggvorbisplayer", "player");
 102
 103   /* set the source audio file */
 104   g_object_set (player, "location", "helloworld.ogg", NULL);
 105
 106   /* start playback */
 107   gst_element_set_state (GST_ELEMENT (player), GST_STATE_PLAYING);
 108 [..]
 109 }
 110
 111 ```
 112
 113 (This is a silly example of course, there already exists a much more
 114 powerful and versatile custom bin like this: the playbin element.)
 115
 116 Custom bins can be created with a plugin or from the application. You
 117 will find more information about creating custom bin in the [Plugin
 118 Writers
 119 Guide](http://gstreamer.freedesktop.org/data/doc/gstreamer/head/pwg/html/index.html).
 120
 121 Examples of such custom bins are the playbin and uridecodebin elements
 122 from[gst-plugins-base](http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-plugins-base-plugins/html/index.html).
 123
 124 ## Bins manage states of their children
 125
 126 Bins manage the state of all elements contained in them. If you set a
 127 bin (or a pipeline, which is a special top-level type of bin) to a
 128 certain target state using `gst_element_set_state ()`, it will make sure
 129 all elements contained within it will also be set to this state. This
 130 means it's usually only necessary to set the state of the top-level
 131 pipeline to start up the pipeline or shut it down.
 132
 133 The bin will perform the state changes on all its children from the sink
 134 element to the source element. This ensures that the downstream element
 135 is ready to receive data when the upstream element is brought to PAUSED
 136 or PLAYING. Similarly when shutting down, the sink elements will be set
 137 to READY or NULL first, which will cause the upstream elements to
 138 receive a FLUSHING error and stop the streaming threads before the
 139 elements are set to the READY or NULL state.
 140
 141 Note, however, that if elements are added to a bin or pipeline that's
 142 already running, , e.g. from within a "pad-added" signal callback, its
 143 state will not automatically be brought in line with the current state
 144 or target state of the bin or pipeline it was added to. Instead, you
 145 have to need to set it to the desired target state yourself using
 146 `gst_element_set_state ()` or `gst_element_sync_state_with_parent ()`
 147 when adding elements to an already-running pipeline.