docs/gst/tmpl/gstbin.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 GstBin
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 Base container element
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 GstBin is the simplest of the container elements, allowing elements to
  10 become children of itself.  Pads from the child elements can be ghosted to
  11 the bin, making the bin itself look transparently like any other element,
  12 allowing for deep nesting of predefined sub-pipelines.
  13 </para>
  14 <para>
  15 A new GstBin is created with gst_bin_new(). Use a #GstPipeline instead if you want
  16 to create a toplevel bin because a normal bin doesn't have a scheduler of its
  17 own.
  18 </para>
  19 <para>
  20 After the bin has been created you will typically add elements to it with
  21 gst_bin_add(). You can remove elements with gst_bin_remove().
  22 </para>
  23 <para>
  24 An element can be retrieved from a bin with gst_bin_get_by_name(), using the
  25 elements name. gst_bin_get_by_name_recurse_up() is mainly used for internal
  26 purposes and will query the parent bins when the element is not found in the
  27 current bin.
  28 </para>
  29 <para>
  30 The list of elements in a bin can be retrieved with gst_bin_get_list().
  31 </para>
  32 <para>
  33 After the bin has been set to the PLAYING state (with gst_element_set_state()),
  34 gst_bin_iterate() is used to process the elements in the bin.
  35 </para>
  36 <para>
  37 The "element_added" signal is fired whenever a new element is added to the bin.
  38 </para>
  39 <para>
  40 The "element_removed" signal is fired whenever an element is removed from the bin.
  41 </para>
  42 <para>
  43 gst_bin_destroy() is used to destroy the bin.
  44 </para>
  45 <para>
  46 To control the selection of the clock in a bin, you can use the following methods:
  47 gst_bin_auto_clock() to let the bin select a clock automatically, gst_bin_get_clock() to
  48 get the current clock of the bin and gst_bin_use_clock() to specify a clock explicitly.
  49 Note that the default behaviour is to automatically select a clock from one of the
  50 clock providers in the bin.
  51 </para>
  52
  53 <!-- ##### SECTION See_Also ##### -->
  54 <para>
  55
  56 </para>
  57
  58 <!-- ##### ENUM GstBinFlags ##### -->
  59 <para>
  60 Flags for a bin.
  61 </para>
  62
  63 @GST_BIN_FLAG_MANAGER: This bin has a scheduler and can be used as a toplevel bin.
  64 @GST_BIN_SELF_SCHEDULABLE: This bin iterates itself, so no calls to gst_bin_iterate() should be made.
  65 @GST_BIN_FLAG_PREFER_COTHREADS: This bin preferes to have its elements scheduled with cothreads
  66 @GST_BIN_FLAG_FIXED_CLOCK: This bin uses a fixed clock, possibly the one set with gst_bin_use_clock().
  67 @GST_BIN_FLAG_LAST:
  68
  69 <!-- ##### STRUCT GstBin ##### -->
  70 <para>
  71 The GstBin object
  72 </para>
  73
  74
  75 <!-- ##### SIGNAL GstBin::element-added ##### -->
  76 <para>
  77
  78 </para>
  79
  80 @gstbin: the object which received the signal.
  81 @arg1: the element that was added to the bin
  82
  83 <!-- ##### SIGNAL GstBin::element-removed ##### -->
  84 <para>
  85
  86 </para>
  87
  88 @gstbin: the object which received the signal.
  89 @arg1: the element that was removed from the bin
  90
  91 <!-- ##### SIGNAL GstBin::iterate ##### -->
  92 <para>
  93 This signal is emitted when a bin iterates, either automatically or
  94 due to a #gst_bin_iterate() call.  The return value is used to
  95 determine if the object method handler processed any data.
  96 In most normal cases, a user-provided signal handler should return
  97 FALSE.
  98 </para>
  99
 100 @gstbin: the object which received the signal.
 101 @Returns: TRUE if the state of the bin was advanced.
 102
 103 <!-- ##### USER_FUNCTION GstBinPrePostIterateFunction ##### -->
 104 <para>
 105 The signature of the callback for the post and pre iterate function as set with
 106 gst_bin_set_pre_iterate_function() and gst_bin_set_post_iterate_function().
 107 </para>
 108
 109 @bin: The bin that performed the callback
 110 @user_data: user data
 111
 112
 113 <!-- ##### FUNCTION gst_bin_new ##### -->
 114 <para>
 115
 116 </para>
 117
 118 @name:
 119 @Returns:
 120
 121
 122 <!-- ##### FUNCTION gst_bin_add ##### -->
 123 <para>
 124
 125 </para>
 126
 127 @bin:
 128 @element:
 129
 130
 131 <!-- ##### FUNCTION gst_bin_add_many ##### -->
 132 <para>
 133
 134 </para>
 135
 136 @bin:
 137 @element_1:
 138 @Varargs:
 139
 140
 141 <!-- ##### FUNCTION gst_bin_remove ##### -->
 142 <para>
 143
 144 </para>
 145
 146 @bin:
 147 @element:
 148
 149
 150 <!-- ##### FUNCTION gst_bin_remove_many ##### -->
 151 <para>
 152
 153 </para>
 154
 155 @bin:
 156 @element_1:
 157 @Varargs:
 158
 159
 160 <!-- ##### FUNCTION gst_bin_get_by_name ##### -->
 161 <para>
 162
 163 </para>
 164
 165 @bin:
 166 @name:
 167 @Returns:
 168
 169
 170 <!-- ##### FUNCTION gst_bin_get_by_name_recurse_up ##### -->
 171 <para>
 172
 173 </para>
 174
 175 @bin:
 176 @name:
 177 @Returns:
 178
 179
 180 <!-- ##### FUNCTION gst_bin_get_list ##### -->
 181 <para>
 182
 183 </para>
 184
 185 @bin:
 186 @Returns:
 187
 188
 189 <!-- ##### FUNCTION gst_bin_iterate ##### -->
 190 <para>
 191
 192 </para>
 193
 194 @bin:
 195 @Returns:
 196
 197
 198 <!-- ##### FUNCTION gst_bin_set_post_iterate_function ##### -->
 199 <para>
 200
 201 </para>
 202
 203 @bin:
 204 @func:
 205 @user_data:
 206
 207
 208 <!-- ##### FUNCTION gst_bin_set_pre_iterate_function ##### -->
 209 <para>
 210
 211 </para>
 212
 213 @bin:
 214 @func:
 215 @user_data:
 216
 217
 218 <!-- ##### FUNCTION gst_bin_child_state_change ##### -->
 219 <para>
 220
 221 </para>
 222
 223 @bin:
 224 @oldstate:
 225 @newstate:
 226 @child:
 227
 228
 229 <!-- ##### FUNCTION gst_bin_auto_clock ##### -->
 230 <para>
 231
 232 </para>
 233
 234 @bin:
 235
 236
 237 <!-- ##### FUNCTION gst_bin_get_clock ##### -->
 238 <para>
 239
 240 </para>
 241
 242 @bin:
 243 @Returns:
 244
 245
 246 <!-- ##### FUNCTION gst_bin_use_clock ##### -->
 247 <para>
 248
 249 </para>
 250
 251 @bin:
 252 @clock:
 253
 254