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 31 G_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 */ 50 typedef 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 92 typedef struct _GstBin GstBin; 93 typedef struct _GstBinClass GstBinClass; 94 typedef 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 */ 134 struct _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 */ 176 struct _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 267 GST_API 268 GType gst_bin_get_type (void); 269 270 GST_API 271 GstElement* gst_bin_new (const gchar *name); 272 273 /* add and remove elements from the bin */ 274 275 GST_API 276 gboolean gst_bin_add (GstBin *bin, GstElement *element); 277 278 GST_API 279 gboolean gst_bin_remove (GstBin *bin, GstElement *element); 280 281 /* retrieve a single child */ 282 283 GST_API 284 GstElement* gst_bin_get_by_name (GstBin *bin, const gchar *name); 285 286 GST_API 287 GstElement* gst_bin_get_by_name_recurse_up (GstBin *bin, const gchar *name); 288 289 GST_API 290 GstElement* gst_bin_get_by_interface (GstBin *bin, GType iface); 291 292 /* retrieve multiple children */ 293 294 GST_API 295 GstIterator* gst_bin_iterate_elements (GstBin *bin); 296 297 GST_API 298 GstIterator* gst_bin_iterate_sorted (GstBin *bin); 299 300 GST_API 301 GstIterator* gst_bin_iterate_recurse (GstBin *bin); 302 303 GST_API 304 GstIterator* gst_bin_iterate_sinks (GstBin *bin); 305 306 GST_API 307 GstIterator* gst_bin_iterate_sources (GstBin *bin); 308 309 GST_API 310 GstIterator* gst_bin_iterate_all_by_interface (GstBin *bin, GType iface); 311 312 GST_API 313 GstIterator* gst_bin_iterate_all_by_element_factory_name (GstBin * bin, const gchar * factory_name); 314 315 /* latency */ 316 317 GST_API 318 gboolean gst_bin_recalculate_latency (GstBin * bin); 319 320 /* set and get suppressed flags */ 321 322 GST_API 323 void gst_bin_set_suppressed_flags (GstBin * bin, GstElementFlags flags); 324 325 GST_API 326 GstElementFlags gst_bin_get_suppressed_flags (GstBin * bin); 327 328 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstBin, gst_object_unref) 329 330 G_END_DECLS 331 332 333 #endif /* __GST_BIN_H__ */ 334