1/* GStreamer
2 * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
3 * 2000 Wim Taymans <wtay@chello.be>
4 *
5 * gstbin.h: Header for GstBin container object
6 *
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Library General Public
9 * License as published by the Free Software Foundation; either
10 * version 2 of the License, or (at your option) any later version.
11 *
12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Library General Public License for more details.
16 *
17 * You should have received a copy of the GNU Library General Public
18 * License along with this library; if not, write to the
19 * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
20 * Boston, MA 02110-1301, USA.
21 */
22
23
24#ifndef __GST_BIN_H__
25#define __GST_BIN_H__
26
27#include <gst/gstelement.h>
28#include <gst/gstiterator.h>
29#include <gst/gstbus.h>
30
31G_BEGIN_DECLS
32
33#define GST_TYPE_BIN (gst_bin_get_type ())
34#define GST_IS_BIN(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GST_TYPE_BIN))
35#define GST_IS_BIN_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), GST_TYPE_BIN))
36#define GST_BIN_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), GST_TYPE_BIN, GstBinClass))
37#define GST_BIN(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), GST_TYPE_BIN, GstBin))
38#define GST_BIN_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), GST_TYPE_BIN, GstBinClass))
39#define GST_BIN_CAST(obj) ((GstBin*)(obj))
40
41/**
42 * GstBinFlags:
43 * @GST_BIN_FLAG_LAST: the last enum in the series of flags for bins.
44 * Derived classes can use this as first value in a list of flags.
45 *
46 * GstBinFlags are a set of flags specific to bins. Most are set/used
47 * internally. They can be checked using the GST_OBJECT_FLAG_IS_SET() macro,
48 * and (un)set using GST_OBJECT_FLAG_SET() and GST_OBJECT_FLAG_UNSET().
49 */
50typedef enum {
51 /**
52 * GST_BIN_FLAG_NO_RESYNC:
53 *
54 * Don't resync a state change when elements are added or linked in the bin
55 *
56 * Since: 1.0.5
57 */
58 GST_BIN_FLAG_NO_RESYNC = (GST_ELEMENT_FLAG_LAST << 0),
59
60 /**
61 * GST_BIN_FLAG_STREAMS_AWARE:
62 *
63 * Indicates whether the bin can handle elements that add/remove source pads
64 * at any point in time without first posting a no-more-pads signal.
65 *
66 * Since: 1.10
67 */
68 GST_BIN_FLAG_STREAMS_AWARE = (GST_ELEMENT_FLAG_LAST << 1),
69
70 /* padding */
71
72 /**
73 * GST_BIN_FLAG_LAST:
74 *
75 * The last enum in the series of flags for bins. Derived classes can use this
76 * as first value in a list of flags.
77 */
78 GST_BIN_FLAG_LAST = (GST_ELEMENT_FLAG_LAST << 5)
79} GstBinFlags;
80
81/**
82 * GST_BIN_IS_NO_RESYNC:
83 * @bin: A #GstBin
84 *
85 * Check if @bin will resync its state change when elements are added and
86 * removed.
87 *
88 * Since: 1.0.5
89 */
90#define GST_BIN_IS_NO_RESYNC(bin) (GST_OBJECT_FLAG_IS_SET(bin,GST_BIN_FLAG_NO_RESYNC))
91
92typedef struct _GstBin GstBin;
93typedef struct _GstBinClass GstBinClass;
94typedef struct _GstBinPrivate GstBinPrivate;
95
96/**
97 * GST_BIN_NUMCHILDREN:
98 * @bin: a #GstBin
99 *
100 * Gets the number of children in a bin.
101 */
102#define GST_BIN_NUMCHILDREN(bin) (GST_BIN_CAST(bin)->numchildren)
103/**
104 * GST_BIN_CHILDREN:
105 * @bin: a #GstBin
106 *
107 * Gets the list of children in a bin.
108 */
109#define GST_BIN_CHILDREN(bin) (GST_BIN_CAST(bin)->children)
110/**
111 * GST_BIN_CHILDREN_COOKIE:
112 * @bin: a #GstBin
113 *
114 * Gets the children cookie that watches the children list.
115 */
116#define GST_BIN_CHILDREN_COOKIE(bin) (GST_BIN_CAST(bin)->children_cookie)
117
118/**
119 * GstBin:
120 * @numchildren: the number of children in this bin
121 * @children: (element-type Gst.Element): the list of children in this bin
122 * @children_cookie: updated whenever @children changes
123 * @child_bus: internal bus for handling child messages
124 * @messages: (element-type Gst.Message): queued and cached messages
125 * @polling: the bin is currently calculating its state
126 * @state_dirty: the bin needs to recalculate its state (deprecated)
127 * @clock_dirty: the bin needs to select a new clock
128 * @provided_clock: the last clock selected
129 * @clock_provider: the element that provided @provided_clock
130 *
131 * The GstBin base class. Subclasses can access these fields provided
132 * the LOCK is taken.
133 */
134struct _GstBin {
135 GstElement element;
136
137 /*< public >*/ /* with LOCK */
138 /* our children, subclass are supposed to update these
139 * fields to reflect their state with _iterate_*() */
140 gint numchildren;
141 GList *children;
142 guint32 children_cookie;
143
144 GstBus *child_bus;
145 GList *messages;
146
147 gboolean polling;
148 gboolean state_dirty;
149
150 gboolean clock_dirty;
151 GstClock *provided_clock;
152 GstElement *clock_provider;
153
154 /*< private >*/
155 GstBinPrivate *priv;
156
157 gpointer _gst_reserved[GST_PADDING];
158};
159
160/**
161 * GstBinClass:
162 * @parent_class: bin parent class
163 *
164 * Subclasses can override #GstBinClass::add_element and #GstBinClass::remove_element
165 * to update the list of children in the bin.
166 *
167 * The #GstBinClass::handle_message method can be overridden to implement custom
168 * message handling.
169 *
170 * #GstBinClass::deep_element_added will be called when a new element has been
171 * added to any bin inside this bin, so it will also be called if a new child
172 * was added to a sub-bin of this bin. #GstBin implementations that override
173 * this message should chain up to the parent class implementation so the
174 * #GstBin::deep-element-added signal is emitted on all parents.
175 */
176struct _GstBinClass {
177 GstElementClass parent_class;
178
179 /*< private >*/
180 GThreadPool *pool; /* deprecated */
181
182 /* signals */
183
184 /**
185 * GstBinClass::element_added:
186 * @bin: the #GstBin
187 * @child: the element that was added
188 *
189 * Method called when an element was added to the bin.
190 */
191 void (*element_added) (GstBin *bin, GstElement *child);
192
193 /**
194 * GstBinClass::element_removed:
195 * @bin: the #GstBin
196 * @child: the element that was removed
197 *
198 * Method called when an element was removed from the bin.
199 */
200 void (*element_removed) (GstBin *bin, GstElement *child);
201
202 /*< public >*/
203 /* virtual methods for subclasses */
204
205 /**
206 * GstBinClass::add_element:
207 * @bin: the #GstBin
208 * @element: the element to be added
209 *
210 * Method to add an element to the bin.
211 *
212 * Returns: %TRUE if the @element was added
213 */
214 gboolean (*add_element) (GstBin *bin, GstElement *element);
215
216 /**
217 * GstBinClass::remove_element:
218 * @bin: the #GstBin
219 * @element: the element to be removed
220 *
221 * Method to remove an element from the bin.
222 *
223 * Returns: %TRUE if the @element was removed
224 */
225 gboolean (*remove_element) (GstBin *bin, GstElement *element);
226
227 /**
228 * GstBinClass::handle_message:
229 * @bin: the #GstBin
230 * @message: (transfer full): the message to be handled
231 *
232 * Method to handle a message from the children.
233 */
234 void (*handle_message) (GstBin *bin, GstMessage *message);
235
236 /*< private >*/
237 /* signal */
238 gboolean (*do_latency) (GstBin *bin);
239
240 /*< public >*/
241 /* signal */
242
243 /**
244 * GstBinClass::deep_element_added:
245 * @bin: the top level #GstBin
246 * @sub_bin: the #GstBin to which the element was added
247 * @child: the element that was added
248 *
249 * Method called when an element was added somewhere in the bin hierarchy.
250 */
251 void (*deep_element_added) (GstBin *bin, GstBin *sub_bin, GstElement *child);
252
253 /**
254 * GstBinClass::deep_element_removed:
255 * @bin: the top level #GstBin
256 * @sub_bin: the #GstBin from which the element was removed
257 * @child: the element that was removed
258 *
259 * Method called when an element was removed somewhere in the bin hierarchy.
260 */
261 void (*deep_element_removed) (GstBin *bin, GstBin *sub_bin, GstElement *child);
262
263 /*< private >*/
264 gpointer _gst_reserved[GST_PADDING-2];
265};
266
267GST_API
268GType gst_bin_get_type (void);
269
270GST_API
271GstElement* gst_bin_new (const gchar *name);
272
273/* add and remove elements from the bin */
274
275GST_API
276gboolean gst_bin_add (GstBin *bin, GstElement *element);
277
278GST_API
279gboolean gst_bin_remove (GstBin *bin, GstElement *element);
280
281/* retrieve a single child */
282
283GST_API
284GstElement* gst_bin_get_by_name (GstBin *bin, const gchar *name);
285
286GST_API
287GstElement* gst_bin_get_by_name_recurse_up (GstBin *bin, const gchar *name);
288
289GST_API
290GstElement* gst_bin_get_by_interface (GstBin *bin, GType iface);
291
292/* retrieve multiple children */
293
294GST_API
295GstIterator* gst_bin_iterate_elements (GstBin *bin);
296
297GST_API
298GstIterator* gst_bin_iterate_sorted (GstBin *bin);
299
300GST_API
301GstIterator* gst_bin_iterate_recurse (GstBin *bin);
302
303GST_API
304GstIterator* gst_bin_iterate_sinks (GstBin *bin);
305
306GST_API
307GstIterator* gst_bin_iterate_sources (GstBin *bin);
308
309GST_API
310GstIterator* gst_bin_iterate_all_by_interface (GstBin *bin, GType iface);
311
312GST_API
313GstIterator* gst_bin_iterate_all_by_element_factory_name (GstBin * bin, const gchar * factory_name);
314
315/* latency */
316
317GST_API
318gboolean gst_bin_recalculate_latency (GstBin * bin);
319
320/* set and get suppressed flags */
321
322GST_API
323void gst_bin_set_suppressed_flags (GstBin * bin, GstElementFlags flags);
324
325GST_API
326GstElementFlags gst_bin_get_suppressed_flags (GstBin * bin);
327
328G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstBin, gst_object_unref)
329
330G_END_DECLS
331
332
333#endif /* __GST_BIN_H__ */
334

source code of include/gstreamer-1.0/gst/gstbin.h