1 <chapter id="cha-bins">
4 A bin is a container element. You can add elements to a bin. Since a bin is
5 an element itself, it can also be added to another bin.
8 Bins allow you to combine a group of 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.
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.
19 <figure float="1" id="sec-bin-img">
20 <title>Visualisation of a bin with some elements in it</title>
23 <imagedata fileref="images/bin-element.ℑ" format="&IMAGE;" />
29 There are two specialized bins available to the GStreamer programmer:
34 a pipeline: a generic container that allows scheduling of the
35 containing elements. The toplevel bin has to be a pipeline.
36 Every application thus needs at least one of these.
41 a thread: a bin that will be run in a separate execution thread.
42 You will have to use this bin if you have to carefully
43 synchronize audio and video, or for buffering. You will learn
44 more about threads in <xref linkend="cha-threads"/>.
50 <sect1 id="sec-bin-create">
51 <title>Creating a bin</title>
53 Bins are created in the same way that other elements are created. ie.
54 using an element factory, or any of the associated convenience functions:
57 GstElement *bin, *thread, *pipeline;
59 /* create a new bin called 'mybin'. this bin will be only for organizational purposes; a normal
60 GstBin doesn't affect plan generation */
61 bin = gst_element_factory_make ("bin", "mybin");
63 /* create a new thread, and give it a unique name */
64 thread = gst_element_factory_make ("thread", NULL);
66 /* the core bins (GstBin, GstThread, GstPipeline) also have convenience APIs,
67 gst_<bintype>_new (). these are equivalent to the gst_element_factory_make () syntax. */
68 pipeline = gst_pipeline_new ("pipeline_name");
72 <sect1 id="sec-bin-adding">
73 <title>Adding elements to a bin</title>
75 Elements are added to a bin with the following code sample:
81 bin = gst_bin_new ("mybin");
83 element = gst_element_factory_make ("mpg123", "decoder");
84 gst_bin_add (GST_BIN (bin), element);
88 Bins and threads can be added to other bins too. This allows you to create nested bins. Pipelines shouldn't be added to any other element, though.
89 They are toplevel bins and they are directly linked to the scheduler.
92 To get an element from the bin you can use:
97 element = gst_bin_get_by_name (GST_BIN (bin), "decoder");
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.
106 To get a list of elements in a bin, use:
111 elements = gst_bin_get_list (GST_BIN (bin));
114 GstElement *element = GST_ELEMENT (elements->data);
116 g_print ("element in bin: %s\n", GST_OBJECT_NAME (GST_OBJECT (element)));
118 elements = g_list_next (elements);
123 To remove an element from a bin, use:
128 gst_bin_remove (GST_BIN (bin), element);
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.
136 GstElement *filesrc, *decoder, *audiosink;
139 /* instantiate the elements and the bins... */
141 gst_bin_add_many (bin, filesrc, decoder, audiosink, NULL);
145 <sect1 id="sec-bin-custom">
146 <title>Custom bins</title>
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:
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);
159 gst_element_set_state (GST_ELEMENT (mp3player), GST_STATE_PLAYING);
162 gst_element_set_state (GST_ELEMENT (mp3player), GST_STATE_PAUSED);
165 gst_element_set_state (GST_ELEMENT (mp3player), GST_STATE_NULL);
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"/>.
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).
180 <sect1 id="sec-bin-ghostpads">
181 <title>Ghost pads</title>
183 You can see from <xref linkend="sec-bin-noghost-img"/> how a bin has no pads of its own.
184 This is where "ghost pads" come into play.
186 <figure float="1" id="sec-bin-noghost-img">
187 <title>Visualisation of a <classname>GstBin</classname> element without ghost pads</title>
190 <imagedata fileref="images/bin-element-noghost.ℑ" format="&IMAGE;" />
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.
201 <figure float="1" id="sec-bin-ghost-img">
202 <title>Visualisation of a <classname>GstBin</classname> element with a ghost pad</title>
205 <imagedata fileref="images/bin-element-ghost.ℑ" format="&IMAGE;" />
210 <xref linkend="sec-bin-ghost-img"/>
211 is a representation of a ghost pad. The sink pad of element one is now also a pad
215 Ghost pads can actually be added to all <classname>GstElement</classname>s and not just
216 <classname>GstBin</classname>s. Use the following code example to add a ghost pad to a bin:
222 element = gst_element_factory_create ("mad", "decoder");
223 bin = gst_bin_new ("mybin");
225 gst_bin_add (GST_BIN (bin), element);
227 gst_element_add_ghost_pad (bin, gst_element_get_pad (element, "sink"), "sink");
231 In the above example, the bin now also has a pad: the pad called 'sink'
232 of the given element.
235 We can now, for example, link the source pad of a filesrc element
241 filesrc = gst_element_factory_create ("filesrc", "disk_reader");
243 gst_element_link_pads (filesrc, "src", bin, "sink");