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_NO_RESYNC: don't resync a state change when elements are 44 * added or linked in the bin (Since: 1.0.5) 45 * @GST_BIN_FLAG_STREAMS_AWARE: Indicates whether the bin can handle elements 46 * that add/remove source pads at any point in time without 47 * first posting a no-more-pads signal (Since: 1.10) 48 * @GST_BIN_FLAG_LAST: the last enum in the series of flags for bins. 49 * Derived classes can use this as first value in a list of flags. 50 * 51 * GstBinFlags are a set of flags specific to bins. Most are set/used 52 * internally. They can be checked using the GST_OBJECT_FLAG_IS_SET () macro, 53 * and (un)set using GST_OBJECT_FLAG_SET () and GST_OBJECT_FLAG_UNSET (). 54 */ 55 typedef enum { 56 GST_BIN_FLAG_NO_RESYNC = (GST_ELEMENT_FLAG_LAST << 0), 57 GST_BIN_FLAG_STREAMS_AWARE = (GST_ELEMENT_FLAG_LAST << 1), 58 /* padding */ 59 GST_BIN_FLAG_LAST = (GST_ELEMENT_FLAG_LAST << 5) 60 } GstBinFlags; 61 62 /** 63 * GST_BIN_IS_NO_RESYNC: 64 * @bin: A #GstBin 65 * 66 * Check if @bin will resync its state change when elements are added and 67 * removed. 68 * 69 * Since: 1.0.5 70 */ 71 #define GST_BIN_IS_NO_RESYNC(bin) (GST_OBJECT_FLAG_IS_SET(bin,GST_BIN_FLAG_NO_RESYNC)) 72 73 typedef struct _GstBin GstBin; 74 typedef struct _GstBinClass GstBinClass; 75 typedef struct _GstBinPrivate GstBinPrivate; 76 77 /** 78 * GST_BIN_NUMCHILDREN: 79 * @bin: a #GstBin 80 * 81 * Gets the number of children in a bin. 82 */ 83 #define GST_BIN_NUMCHILDREN(bin) (GST_BIN_CAST(bin)->numchildren) 84 /** 85 * GST_BIN_CHILDREN: 86 * @bin: a #GstBin 87 * 88 * Gets the list with children in a bin. 89 */ 90 #define GST_BIN_CHILDREN(bin) (GST_BIN_CAST(bin)->children) 91 /** 92 * GST_BIN_CHILDREN_COOKIE: 93 * @bin: a #GstBin 94 * 95 * Gets the children cookie that watches the children list. 96 */ 97 #define GST_BIN_CHILDREN_COOKIE(bin) (GST_BIN_CAST(bin)->children_cookie) 98 99 /** 100 * GstBin: 101 * @numchildren: the number of children in this bin 102 * @children: (element-type Gst.Element): the list of children in this bin 103 * @children_cookie: updated whenever @children changes 104 * @child_bus: internal bus for handling child messages 105 * @messages: (element-type Gst.Message): queued and cached messages 106 * @polling: the bin is currently calculating its state 107 * @state_dirty: the bin needs to recalculate its state (deprecated) 108 * @clock_dirty: the bin needs to select a new clock 109 * @provided_clock: the last clock selected 110 * @clock_provider: the element that provided @provided_clock 111 * 112 * The GstBin base class. Subclasses can access these fields provided 113 * the LOCK is taken. 114 */ 115 struct _GstBin { 116 GstElement element; 117 118 /*< public >*/ /* with LOCK */ 119 /* our children, subclass are supposed to update these 120 * fields to reflect their state with _iterate_*() */ 121 gint numchildren; 122 GList *children; 123 guint32 children_cookie; 124 125 GstBus *child_bus; 126 GList *messages; 127 128 gboolean polling; 129 gboolean state_dirty; 130 131 gboolean clock_dirty; 132 GstClock *provided_clock; 133 GstElement *clock_provider; 134 135 /*< private >*/ 136 GstBinPrivate *priv; 137 138 gpointer _gst_reserved[GST_PADDING]; 139 }; 140 141 /** 142 * GstBinClass: 143 * @parent_class: bin parent class 144 * @add_element: method to add an element to a bin 145 * @remove_element: method to remove an element from a bin 146 * @handle_message: method to handle a message from the children 147 * @deep_element_added: method called when an element was added somewhere 148 * in the bin hierarchy 149 * @deep_element_removed: method called when an element was removed somewhere 150 * in the bin hierarchy 151 * 152 * Subclasses can override the @add_element and @remove_element to 153 * update the list of children in the bin. 154 * 155 * The @handle_message method can be overridden to implement custom 156 * message handling. @handle_message takes ownership of the message, just like 157 * #gst_element_post_message. 158 * 159 * The @deep_element_added vfunc will be called when a new element has been 160 * added to any bin inside this bin, so it will also be called if a new child 161 * was added to a sub-bin of this bin. #GstBin implementations that override 162 * this message should chain up to the parent class implementation so the 163 * element-added-deep signal is emitted on all parents. 164 */ 165 struct _GstBinClass { 166 GstElementClass parent_class; 167 168 /*< private >*/ 169 GThreadPool *pool; /* deprecated */ 170 171 /* signals */ 172 void (*element_added) (GstBin *bin, GstElement *child); 173 void (*element_removed) (GstBin *bin, GstElement *child); 174 175 /*< public >*/ 176 /* virtual methods for subclasses */ 177 gboolean (*add_element) (GstBin *bin, GstElement *element); 178 gboolean (*remove_element) (GstBin *bin, GstElement *element); 179 180 void (*handle_message) (GstBin *bin, GstMessage *message); 181 182 /*< private >*/ 183 /* signal */ 184 gboolean (*do_latency) (GstBin *bin); 185 186 /*< public >*/ 187 /* signal */ 188 void (*deep_element_added) (GstBin *bin, GstBin *sub_bin, GstElement *child); 189 void (*deep_element_removed) (GstBin *bin, GstBin *sub_bin, GstElement *child); 190 191 /*< private >*/ 192 gpointer _gst_reserved[GST_PADDING-2]; 193 }; 194 195 GST_API 196 GType gst_bin_get_type (void); 197 198 GST_API 199 GstElement* gst_bin_new (const gchar *name); 200 201 /* add and remove elements from the bin */ 202 203 GST_API 204 gboolean gst_bin_add (GstBin *bin, GstElement *element); 205 206 GST_API 207 gboolean gst_bin_remove (GstBin *bin, GstElement *element); 208 209 /* retrieve a single child */ 210 211 GST_API 212 GstElement* gst_bin_get_by_name (GstBin *bin, const gchar *name); 213 214 GST_API 215 GstElement* gst_bin_get_by_name_recurse_up (GstBin *bin, const gchar *name); 216 217 GST_API 218 GstElement* gst_bin_get_by_interface (GstBin *bin, GType iface); 219 220 /* retrieve multiple children */ 221 222 GST_API 223 GstIterator* gst_bin_iterate_elements (GstBin *bin); 224 225 GST_API 226 GstIterator* gst_bin_iterate_sorted (GstBin *bin); 227 228 GST_API 229 GstIterator* gst_bin_iterate_recurse (GstBin *bin); 230 231 GST_API 232 GstIterator* gst_bin_iterate_sinks (GstBin *bin); 233 234 GST_API 235 GstIterator* gst_bin_iterate_sources (GstBin *bin); 236 237 GST_API 238 GstIterator* gst_bin_iterate_all_by_interface (GstBin *bin, GType iface); 239 240 /* latency */ 241 242 GST_API 243 gboolean gst_bin_recalculate_latency (GstBin * bin); 244 245 /* set and get suppressed flags */ 246 247 GST_API 248 void gst_bin_set_suppressed_flags (GstBin * bin, GstElementFlags flags); 249 250 GST_API 251 GstElementFlags gst_bin_get_suppressed_flags (GstBin * bin); 252 253 #ifdef G_DEFINE_AUTOPTR_CLEANUP_FUNC 254 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstBin, gst_object_unref) 255 #endif 256 257 G_END_DECLS 258 259 260 #endif /* __GST_BIN_H__ */ 261