mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-11-03 16:09:39 +00:00
2c202f9120
Original commit message from CVS: * docs/design/part-gstbin.txt: * docs/design/part-gstbus.txt: * gst/gstbus.c: Add blurb about how the bus goes into flushing mode and drops all messages when its bin goes from READY into NULL state.
84 lines
2.7 KiB
Text
84 lines
2.7 KiB
Text
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.
|
|
|
|
When a bin goes from READY into NULL state, it will set its bus to flushing,
|
|
ie. the bus will drop all existing and new messages on the bus. This is
|
|
necessary because bus messages hold references to the bin or its elements,
|
|
so there are circular references that need to be broken if one ever wants
|
|
to be able to destroy the bin properly.
|
|
|
|
|
|
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.
|
|
|