| GstBin |
| ------ |
| |
| GstBin is a container element for other GstElements. This makes it possible |
| to group elements together so that they can be treated as one single |
| GstElement. A GstBin provides a GstBus for the children and collates messages |
| from them. |
| |
| Add/removing elements |
| --------------------- |
| |
| The basic functionality of a bin is to add and remove GstElements to/from it. |
| gst_bin_add() and gst_bin_remove() perform these operations respectively. |
| |
| The bin maintains a parent-child relationship with its elements (see part- |
| relations.txt). |
| |
| |
| Retrieving elements |
| ------------------- |
| |
| GstBin provides a number of functions to retrieve one or more children from |
| itself. A few examples of the provided functions: |
| |
| gst_bin_get_by_name() retrieves an element by name. |
| |
| gst_bin_iterate_elements() returns an iterator to all the children. |
| |
| |
| element management |
| ------------------ |
| |
| The most important function of the GstBin is to distribute all GstElement |
| operations on itself to all of its children. This includes: |
| |
| - state changes |
| - index get/set |
| - clock gst/set |
| |
| The state change distribution is the most complex and is explained in |
| part-states.txt. |
| |
| GstBus |
| ------ |
| |
| The GstBin creates a GstBus for its children and distributes it when child |
| elements are added to the bin. The bin attaches a sync handler to receive |
| messages from children. The bus for receiving messages from children is |
| distinct from the bin's own externally-visible GstBus. |
| |
| Messages received from children are forwarded intact onto the bin's |
| external message bus, except for EOS and SEGMENT_START/DONE which are |
| handled specially. |
| |
| ASYNC_START/ASYNC_STOP messages received from the children are used to |
| trigger a recalculation of the current state of the bin, as described in |
| part-states.txt. |
| |
| The application can retrieve the external GstBus and integrate it in the |
| mainloop or it can just _pop() messages off in its own thread. |
| |
| When a bin goes to READY it will clear all cached messages. |
| |
| |
| EOS |
| --- |
| |
| The sink elements will post an EOS message on the bus when they reach EOS. The |
| EOS message is only posted to the bus when the sink element is in PLAYING. |
| |
| The bin collects all EOS messages and forwards it to the application as |
| soon as all the sinks have posted an EOS. |
| |
| The list of queued EOS messages is cleared when the bin goes to PAUSED |
| again. This means that all elements should repost the EOS message when going |
| to PLAYING again. |
| |
| |
| SEGMENT_START/DONE |
| ------------------ |
| |
| A bin collects SEGMENT_START messages but does not post them to the application. |
| It counts the number of SEGMENT_START messages and posts a SEGMENT_STOP message |
| to the application when an equal number of SEGMENT_STOP messages where received. |
| |
| The cached SEGMENT_START/STOP messages are cleared when going to READY. |
| |
| |
| DURATION |
| -------- |
| |
| When a DURATION query is performed on a bin, it will forward the query to all |
| its sink elements. The bin will calculate the total duration as the MAX of all |
| returned durations and will then cache the result so that any further query can |
| use the cached version. The reason for caching the result is because the |
| duration of a stream typically does not change that often. |
| |
| A GST_MESSAGE_DURATION posted by an element will clear the cached duration value |
| so that the bin will query the sinks again. This message is typically posted by |
| elements that calculate the duration of the stream based on some average |
| bitrate, which might change while playing the stream. The DURATION message is |
| posted to the application, which can then fetch the updated DURATION. |
| |
| |
| Subclassing |
| ----------- |
| |
| Subclasses of GstBin are free to implement their own add/remove implementations. |
| It is a good idea to update the GList of children so that the _iterate() functions |
| can still be used if the custom bin allows acces to its children. |
| |
| Any bin subclass can also implement a custom message handler by overriding the |
| default message handler. |
| |