mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-07-28 09:15:08 +00:00
6796aaa385
Original commit message from CVS: * docs/design/part-gstbin.txt: * docs/design/part-gstpipeline.txt: Update design notes to reflect the movement of responsibility for bus handling from GstPipeline to GstBin
78 lines
2.3 KiB
Plaintext
78 lines
2.3 KiB
Plaintext
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
|
|
- scheduler set/get
|
|
|
|
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 which is handled specially.
|
|
|
|
The application can retrieve the external GstBus and integrate it in the
|
|
mainloop or it can just _pop() messages off in its own thread.
|
|
|
|
EOS
|
|
---
|
|
|
|
The sink elements will post an EOS event on the bus when they reach EOS. The
|
|
EOS message is only posted to the bus when the 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.
|
|
|
|
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.
|
|
|