docs/design/part-gstbin.txt

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