mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-07-25 15:58:24 +00:00
5b4e6c33c8
Original commit message from CVS: * docs/design/part-TODO.txt: * docs/design/part-clocks.txt: * docs/design/part-events.txt: * docs/design/part-gstbin.txt: * docs/design/part-gstelement.txt: * docs/design/part-gstpipeline.txt: * docs/design/part-live-source.txt: * docs/design/part-messages.txt: * docs/design/part-overview.txt: * docs/design/part-states.txt: Many doc updates.
100 lines
3.2 KiB
Plaintext
100 lines
3.2 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
|
|
|
|
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.
|
|
|
|
STATE_CHANGED 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 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.
|
|
|
|
|
|
SEGMENT_START/DONE
|
|
------------------
|
|
|
|
* not implemented.
|
|
|
|
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.
|
|
|
|
|
|
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.
|
|
|