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 <!-- ##### USER_FUNCTION GstBinPrePostIterateFunction ##### -->
  76 <para>
  77 The signature of the callback for the post and pre iterate function as set with
  78 gst_bin_set_pre_iterate_function() and gst_bin_set_post_iterate_function().
  79 </para>
  80
  81 @bin: The bin that performed the callback
  82 @user_data: user data
  83
  84
  85 <!-- ##### FUNCTION gst_bin_new ##### -->
  86 <para>
  87
  88 </para>
  89
  90 @name:
  91 @Returns:
  92
  93
  94 <!-- ##### FUNCTION gst_bin_add ##### -->
  95 <para>
  96
  97 </para>
  98
  99 @bin:
 100 @element:
 101
 102
 103 <!-- ##### FUNCTION gst_bin_add_many ##### -->
 104 <para>
 105
 106 </para>
 107
 108 @bin:
 109 @element_1:
 110 @Varargs:
 111
 112
 113 <!-- ##### FUNCTION gst_bin_remove ##### -->
 114 <para>
 115
 116 </para>
 117
 118 @bin:
 119 @element:
 120
 121
 122 <!-- ##### FUNCTION gst_bin_remove_many ##### -->
 123 <para>
 124
 125 </para>
 126
 127 @bin:
 128 @element_1:
 129 @Varargs:
 130
 131
 132 <!-- ##### FUNCTION gst_bin_get_by_name ##### -->
 133 <para>
 134
 135 </para>
 136
 137 @bin:
 138 @name:
 139 @Returns:
 140
 141
 142 <!-- ##### FUNCTION gst_bin_get_by_name_recurse_up ##### -->
 143 <para>
 144
 145 </para>
 146
 147 @bin:
 148 @name:
 149 @Returns:
 150
 151
 152 <!-- ##### FUNCTION gst_bin_get_list ##### -->
 153 <para>
 154
 155 </para>
 156
 157 @bin:
 158 @Returns:
 159
 160
 161 <!-- ##### FUNCTION gst_bin_iterate ##### -->
 162 <para>
 163
 164 </para>
 165
 166 @bin:
 167 @Returns:
 168
 169
 170 <!-- ##### FUNCTION gst_bin_set_post_iterate_function ##### -->
 171 <para>
 172
 173 </para>
 174
 175 @bin:
 176 @func:
 177 @user_data:
 178
 179
 180 <!-- ##### FUNCTION gst_bin_set_pre_iterate_function ##### -->
 181 <para>
 182
 183 </para>
 184
 185 @bin:
 186 @func:
 187 @user_data:
 188
 189
 190 <!-- ##### FUNCTION gst_bin_child_state_change ##### -->
 191 <para>
 192
 193 </para>
 194
 195 @bin:
 196 @oldstate:
 197 @newstate:
 198 @child:
 199
 200
 201 <!-- ##### FUNCTION gst_bin_auto_clock ##### -->
 202 <para>
 203
 204 </para>
 205
 206 @bin:
 207
 208
 209 <!-- ##### FUNCTION gst_bin_get_clock ##### -->
 210 <para>
 211
 212 </para>
 213
 214 @bin:
 215 @Returns:
 216
 217
 218 <!-- ##### FUNCTION gst_bin_use_clock ##### -->
 219 <para>
 220
 221 </para>
 222
 223 @bin:
 224 @clock:
 225
 226
 227 <!-- ##### SIGNAL GstBin::element-added ##### -->
 228 <para>
 229
 230 </para>
 231
 232 @gstbin: the object which received the signal.
 233 @arg1: the element that was added to the bin
 234
 235 <!-- ##### SIGNAL GstBin::element-removed ##### -->
 236 <para>
 237
 238 </para>
 239
 240 @gstbin: the object which received the signal.
 241 @arg1: the element that was removed from the bin
 242
 243 <!-- ##### SIGNAL GstBin::iterate ##### -->
 244 <para>
 245 This signal is emitted when a bin iterates, either automatically or
 246 due to a #gst_bin_iterate() call.  The return value is used to
 247 determine if the object method handler processed any data.
 248 In most normal cases, a user-provided signal handler should return
 249 FALSE.
 250 </para>
 251
 252 @gstbin: the object which received the signal.
 253 @Returns: TRUE if the state of the bin was advanced.
 254