markdown/additional/design/gstbin.md

   1 # GstBin
   2
   3 `GstBin` is a container element for other `GstElements`. It makes
   4 possible to group elements together so that they can be treated as one
   5 single `GstElement`. A `GstBin` provides a `GstBus` for the children and
   6 collates messages from them.
   7
   8 ## Adding/removing elements
   9
  10 The basic functionality of a bin is to add and remove `GstElement`
  11 to/from it. `gst_bin_add()` and `gst_bin_remove()` perform these
  12 operations respectively.
  13
  14 The bin maintains a parent-child relationship with its elements (see
  15 [relations](additional/design/relations.md)).
  16
  17 ## Retrieving elements
  18
  19 `GstBin` provides a number of functions to retrieve one or more children
  20 from itself. A few examples of the provided functions:
  21
  22 * `gst_bin_get_by_name()` retrieves an element by name.
  23 * `gst_bin_iterate_elements()` returns an iterator to all the children.
  24
  25 ## Element management
  26
  27 The most important function of the `GstBin` is to distribute all
  28 `GstElement` operations on itself to all of its children. These
  29 operations include:
  30
  31   - state changes
  32
  33   - index get/set
  34
  35   - clock get/set
  36
  37 The state change distribution is the most complex and is explained in
  38 [states](additional/design/states.md).
  39
  40 ## GstBus
  41
  42 The `GstBin` creates a `GstBus` for its children and distributes it when
  43 child elements are added to the bin. The bin attaches a sync handler to
  44 receive messages from children. The bus for receiving messages from
  45 children is distinct from the bin’s own externally-visible `GstBus`.
  46
  47 Messages received from children are forwarded intact onto the bin’s
  48 external message bus, except for EOS and `SEGMENT_START`/`DONE` which are
  49 handled specially.
  50
  51 `ASYNC_START`/`ASYNC_STOP` messages received from the children are used to
  52 trigger a recalculation of the current state of the bin, as described in
  53 [states](additional/design/states.md).
  54
  55 The application can retrieve the external `GstBus` and integrate it in the
  56 mainloop or it can just `pop()` messages off in its own thread.
  57
  58 When a bin goes to `READY` it will clear all cached messages.
  59
  60 ## EOS
  61
  62 The sink elements will post an `EOS` message on the bus when they reach
  63 `EOS`. This message is only posted to the bus when the sink element is
  64 in `PLAYING`.
  65
  66 The bin collects all `EOS` messages and forwards it to the application as
  67 soon as all the sinks have posted an `EOS`.
  68
  69 The list of queued `EOS` messages is cleared when the bin goes to `PAUSED`
  70 again. This means that all elements should repost the `EOS` message when
  71 going to `PLAYING` again.
  72
  73 ## SEGMENT_START/DONE
  74
  75 A bin collects `SEGMENT_START` messages but does not post them to the
  76 application. It counts the number of `SEGMENT_START` messages and posts a
  77 `SEGMENT_STOP` message to the application when an equal number of
  78 `SEGMENT_STOP` messages were received.
  79
  80 The cached `SEGMENT_START`/`STOP` messages are cleared when going to `READY`.
  81
  82 ## DURATION
  83
  84 When a `DURATION` query is performed on a bin, it will forward the query
  85 to all its sink elements. The bin will calculate the total duration as
  86 the MAX of all returned durations and will then cache the result so that
  87 any further queries can use the cached version. The reason for caching the
  88 result is because the duration of a stream typically does not change
  89 that often.
  90
  91 A `GST_MESSAGE_DURATION_CHANGED` posted by an element will clear the
  92 cached duration value so that the bin will query the sinks again. This
  93 message is typically posted by elements that calculate the duration of
  94 the stream based on some average bitrate, which might change while
  95 playing the stream. The `DURATION_CHANGED` message is posted to the
  96 application, which can then fetch the updated `DURATION`.
  97
  98 ## Subclassing
  99
 100 Subclasses of `GstBin` are free to implement their own add/remove
 101 functions. It is a good idea to update the `GList` of children so
 102 that the `_iterate()` functions can still be used if the custom bin
 103 allows access to its children.
 104
 105 Any bin subclass can also implement a custom message handler by
 106 overriding the default one.