Notes

A GstBin internally intercepts every GstMessage posted by its children and implements the following default behaviour for each of them:

A GstBin implements the following default behaviour for answering to a GstQuery:

A GstBin will by default forward any event sent to it to all sink elements. If all the sinks return TRUE, the bin will also return TRUE, else FALSE is returned. If no sinks are in the bin, the event handler will return TRUE.

struct GstBin

struct GstBin {
  /* our children, subclass are supposed to update these
   * fields to reflect their state with _iterate_*() */
  gint		 numchildren;
  GList		*children;
  guint32	 children_cookie;

  GstBus        *child_bus;
  GList         *messages;

  gboolean	 polling;
  gboolean       state_dirty;

  gboolean       clock_dirty;
  GstClock *provided_clock;
  GstElement    *clock_provider;
};

The GstBin base class. Subclasses can access these fields provided the LOCK is taken.

struct GstBinClass

struct GstBinClass {
  GstElementClass parent_class;

  /* virtual methods for subclasses */
  gboolean (*add_element)		(GstBin *bin, GstElement *element);
  gboolean (*remove_element) (GstBin *bin, GstElement *element);

  void		(*handle_message) (GstBin *bin, GstMessage *message);
};

Subclasses can override the add_element and remove_element to update the list of children in the bin.

The handle_message method can be overridden to implement custom message handling. handle_message takes ownership of the message, just like gst_element_post_message.

gst_bin_new ()

GstElement *        gst_bin_new                         (const gchar *name);

Creates a new bin with the given name.

gst_bin_add ()

gboolean            gst_bin_add                         (GstBin *bin,
                                                         GstElement *element);

Adds the given element to the bin. Sets the element's parent, and thus takes ownership of the element. An element can only be added to one bin.

If the element's pads are linked to other pads, the pads will be unlinked before the element is added to the bin.

MT safe.

gst_bin_remove ()

gboolean            gst_bin_remove                      (GstBin *bin,
                                                         GstElement *element);

Removes the element from the bin, unparenting it as well. Unparenting the element means that the element will be dereferenced, so if the bin holds the only reference to the element, the element will be freed in the process of removing it from the bin. If you want the element to still exist after removing, you need to call gst_object_ref() before removing it from the bin.

If the element's pads are linked to other pads, the pads will be unlinked before the element is removed from the bin.

MT safe.

gst_bin_get_by_name ()

GstElement *        gst_bin_get_by_name                 (GstBin *bin,
                                                         const gchar *name);

Gets the element with the given name from a bin. This function recurses into child bins.

Returns NULL if no element with the given name is found in the bin.

MT safe. Caller owns returned reference.

gst_bin_get_by_name_recurse_up ()

GstElement *        gst_bin_get_by_name_recurse_up      (GstBin *bin,
                                                         const gchar *name);

Gets the element with the given name from this bin. If the element is not found, a recursion is performed on the parent bin.

Returns NULL if:

MT safe. Caller owns returned reference.

gst_bin_get_by_interface ()

GstElement *        gst_bin_get_by_interface            (GstBin *bin,
                                                         GType iface);

Looks for an element inside the bin that implements the given interface. If such an element is found, it returns the element. You can cast this element to the given interface afterwards. If you want all elements that implement the interface, use gst_bin_iterate_all_by_interface(). This function recurses into child bins.

MT safe. Caller owns returned reference.

gst_bin_iterate_elements ()

GstIterator *       gst_bin_iterate_elements            (GstBin *bin);

Gets an iterator for the elements in this bin.

Each element yielded by the iterator will have its refcount increased, so unref after use.

MT safe. Caller owns returned value.

gst_bin_iterate_recurse ()

GstIterator *       gst_bin_iterate_recurse             (GstBin *bin);

Gets an iterator for the elements in this bin. This iterator recurses into GstBin children.

Each element yielded by the iterator will have its refcount increased, so unref after use.

MT safe. Caller owns returned value.

gst_bin_iterate_sinks ()

GstIterator *       gst_bin_iterate_sinks               (GstBin *bin);

Gets an iterator for all elements in the bin that have the GST_ELEMENT_IS_SINK flag set.

Each element yielded by the iterator will have its refcount increased, so unref after use.

MT safe. Caller owns returned value.

gst_bin_iterate_sorted ()

GstIterator *       gst_bin_iterate_sorted              (GstBin *bin);

Gets an iterator for the elements in this bin in topologically sorted order. This means that the elements are returned from the most downstream elements (sinks) to the sources.

This function is used internally to perform the state changes of the bin elements and for clock selection.

Each element yielded by the iterator will have its refcount increased, so unref after use.

MT safe. Caller owns returned value.

gst_bin_iterate_sources ()

GstIterator *       gst_bin_iterate_sources             (GstBin *bin);

Gets an iterator for all elements in the bin that have the GST_ELEMENT_IS_SOURCE flag set.

Each element yielded by the iterator will have its refcount increased, so unref after use.

MT safe. Caller owns returned value.

gst_bin_iterate_all_by_interface ()

GstIterator *       gst_bin_iterate_all_by_interface    (GstBin *bin,
                                                         GType iface);

Looks for all elements inside the bin that implements the given interface. You can safely cast all returned elements to the given interface. The function recurses inside child bins. The iterator will yield a series of GstElement that should be unreffed after use.

Each element yielded by the iterator will have its refcount increased, so unref after use.

MT safe. Caller owns returned value.

gst_bin_recalculate_latency ()

gboolean            gst_bin_recalculate_latency         (GstBin *bin);

Query bin for the current latency using and reconfigures this latency to all the elements with a LATENCY event.

This method is typically called on the pipeline when a GST_MESSAGE_LATENCY is posted on the bus.

This function simply emits the 'do-latency' signal so any custom latency calculations will be performed.

Since 0.10.22.

gst_bin_add_many ()

void                gst_bin_add_many                    (GstBin *bin,
                                                         GstElement *element_1,
                                                         ...);

Adds a NULL-terminated list of elements to a bin. This function is equivalent to calling gst_bin_add() for each member of the list. The return value of each gst_bin_add() is ignored.

gst_bin_remove_many ()

void                gst_bin_remove_many                 (GstBin *bin,
                                                         GstElement *element_1,
                                                         ...);

Remove a list of elements from a bin. This function is equivalent to calling gst_bin_remove() with each member of the list.

gst_bin_find_unlinked_pad ()

GstPad *            gst_bin_find_unlinked_pad           (GstBin *bin,
                                                         GstPadDirection direction);

Recursively looks for elements with an unlinked pad of the given direction within the specified bin and returns an unlinked pad if one is found, or NULL otherwise. If a pad is found, the caller owns a reference to it and should use gst_object_unref() on the pad when it is not needed any longer.

Since 0.10.20

gst_bin_find_unconnected_pad ()

GstPad *            gst_bin_find_unconnected_pad        (GstBin *bin,
                                                         GstPadDirection direction);

Recursively looks for elements with an unlinked pad of the given direction within the specified bin and returns an unlinked pad if one is found, or NULL otherwise. If a pad is found, the caller owns a reference to it and should use gst_object_unref() on the pad when it is not needed any longer.

Since 0.10.3

enum GstBinFlags

typedef enum {
  /* padding */
  GST_BIN_FLAG_LAST		= (GST_ELEMENT_FLAG_LAST << 5)
} GstBinFlags;

GstBinFlags are a set of flags specific to bins. Most are set/used internally. They can be checked using the GST_OBJECT_FLAG_IS_SET() macro, and (un)set using GST_OBJECT_FLAG_SET() and GST_OBJECT_FLAG_UNSET().

GST_BIN_CHILDREN()

#define GST_BIN_CHILDREN(bin)		(GST_BIN_CAST(bin)->children)

Gets the list with children in a bin.

GST_BIN_CHILDREN_COOKIE()

#define GST_BIN_CHILDREN_COOKIE(bin) (GST_BIN_CAST(bin)->children_cookie)

Gets the children cookie that watches the children list.

GST_BIN_NUMCHILDREN()

#define GST_BIN_NUMCHILDREN(bin) (GST_BIN_CAST(bin)->numchildren)

Gets the number of children in a bin.

The "async-handling" property

  "async-handling"           gboolean              : Read / Write

If set to TRUE, the bin will handle asynchronous state changes. This should be used only if the bin subclass is modifying the state of its children on its own.

Default value: FALSE

Since 0.10.13

The "message-forward" property

  "message-forward"          gboolean              : Read / Write

Forward all children messages, even those that would normally be filtered by the bin. This can be interesting when one wants to be notified of the EOS state of individual elements, for example.

The messages are converted to an ELEMENT message with the bin as the source. The structure of the message is named 'GstBinForwarded' and contains a field named 'message' of type GST_TYPE_MESSAGE that contains the original forwarded message.

Default value: FALSE

Since 0.10.31

The "do-latency" signal

gboolean            user_function                      (GstBin  *bin,
                                                        gpointer user_data)      : Run Last

Will be emitted when the bin needs to perform latency calculations. This signal is only emited for toplevel bins or when async-handling is enabled.

Only one signal handler is invoked. If no signals are connected, the default handler is invoked, which will query and distribute the lowest possible latency to all sinks.

Connect to this signal if the default latency calculations are not sufficient, like when you need different latencies for different sinks in the same pipeline.

Since 0.10.22

The "element-added" signal

void                user_function                      (GstBin     *bin,
                                                        GstElement *element,
                                                        gpointer    user_data)      : Run First

Will be emitted after the element was added to the bin.

The "element-removed" signal

void                user_function                      (GstBin     *bin,
                                                        GstElement *element,
                                                        gpointer    user_data)      : Run First

Will be emitted after the element was removed from the bin.