Gst::Bin Class Reference

Gst::Bin — Base class and element that can contain other elements. More...

#include <bin.h>

Inheritance diagram for Gst::Bin:

Gst::Element Gst::ChildProxy Gst::Object Gst::Pipeline GstBase::DecodeBin GstBase::PlayBin2

List of all members.

Public Member Functions

virtual ~Bin ()
GstBin* gobj ()
 Provides access to the underlying C GObject.
const GstBin* gobj () const
 Provides access to the underlying C GObject.
GstBin* gobj_copy ()
 Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.
Glib::RefPtr<Gst::Binadd (const Glib::RefPtr<Gst::Element>& element)
 Adds the given element to the bin.
Glib::RefPtr<Gst::Binremove (const Glib::RefPtr<Gst::Element>& element)
 Removes the element from the bin, unparenting it as well.
Glib::RefPtr<Gst::Elementget_element (const Glib::ustring& name)
 Gets the element with the given name from a bin.
Glib::RefPtr<const Gst::Elementget_element (const Glib::ustring& name) const
 Gets the element with the given name from a bin.
Glib::RefPtr<Gst::Elementget_element_recurse_up (const Glib::ustring& name)
 Gets the element with the given name from this bin.
Glib::RefPtr<const Gst::Elementget_element_recurse_up (const Glib::ustring& name) const
 Gets the element with the given name from this bin.
Glib::RefPtr<Gst::Elementget_element (GType interface)
 Looks for an element inside the bin that implements the given interface.
Glib::RefPtr<const Gst::Elementget_element (GType interface) const
 Looks for an element inside the bin that implements the given interface.
Glib::RefPtr<Gst::Padfind_unlinked_pad (PadDirection dir)
 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 0 otherwise.
Glib::RefPtr<const Gst::Padfind_unlinked_pad (PadDirection dir) const
 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 0 otherwise.
Gst::Iterator<Gst::Elementiterate_elements ()
 Gets an iterator for the elements in this bin.
Gst::Iterator<Gst::Elementiterate_recurse ()
 Gets an iterator for the elements in this bin.
Gst::Iterator<Gst::Elementiterate_sorted ()
 Gets an iterator for the elements in this bin in topologically sorted order.
Gst::Iterator<Gst::Elementiterate_sources ()
 Gets an iterator for all elements in the bin that have no sinkpads and have the Gst::ELEMENT_IS_SINK flag unset.
Gst::Iterator<Gst::Elementiterate_sinks ()
 Gets an iterator for all elements in the bin that have the Gst::ELEMENT_IS_SINK flag set.
Gst::Iterator<Gst::Elementiterate_by_interface (GType iface)
 Looks for all elements inside the bin that implements the given interface.
Glib::ListHandle< Glib::RefPtr
<Gst::Element >> 
get_children () const
 Gets the bin's list of children.
int get_num_children () const
 Gets the number of children in the bin.
Glib::SignalProxy1< void,
const Glib::RefPtr
<Gst::Element >&> 
signal_element_added ()
 Will be emitted after the element was added to the bin.
Glib::SignalProxy1< void,
const Glib::RefPtr
<Gst::Element >&> 
signal_element_removed ()
 Will be emitted after the element was removed from the bin.
Glib::PropertyProxy<bool> property_async_handling ()
 The bin will handle Asynchronous state changes.
Glib::PropertyProxy_ReadOnly
<bool> 
property_async_handling () const
 The bin will handle Asynchronous state changes.
virtual bool add_element_vfunc (const Glib::RefPtr<Gst::Element>& element)
 Method to add an element to a bin.
virtual bool remove_element_vfunc (const Glib::RefPtr<Gst::Element>& element)
 Method to remove an element from a bin.
virtual void handle_message_vfunc (const Glib::RefPtr<Gst::Message>& message)
 Method to handle a message from the children.

Static Public Member Functions

static Glib::RefPtr<Bincreate (const Glib::ustring& name)
 Creates a new bin with the given name.
static Glib::RefPtr<Bincreate ()
 Creates a new bin with a unique generic name.

Protected Member Functions

 Bin (const Glib::ustring& name)
 Bin ()
virtual void on_element_added (const Glib::RefPtr<Gst::Element>& element)
virtual void on_element_removed (const Glib::RefPtr<Gst::Element>& element)

Related Functions

(Note that these are not member functions.)

Glib::RefPtr<Gst::Binwrap (GstBin* object, bool take_copy=false)
 A Glib::wrap() method for this object.


Detailed Description

Gst::Bin — Base class and element that can contain other elements.

Gst::Bin is an element that can contain other Gst::Element, allowing them to be managed as a group. Pads from the child elements can be ghosted to the bin, see Gst::GhostPad. This makes the bin look like any other elements and enables creation of higher-level abstraction elements.

A new Gst::Bin is created with create(). Use a Gst::Pipeline instead if you want to create a toplevel bin because a normal bin doesn't have a bus or handle clock distribution of its own.

After the bin has been created you will typically add elements to it with add(). You can remove elements with remove().

An element can be retrieved from a bin with get_element(), using the elements name. get_element_recurse_up() is mainly used for internal purposes and will query the parent bins when the element is not found in the current bin.

An iterator of elements in a bin can be retrieved with iterate_elements(). Various other iterators exist to retrieve the elements in a bin.

The element-added signal is fired whenever a new element is added to the bin. Likewise the element-removed signal is fired whenever an element is removed from the bin.

Notes:

A Gst::Bin internally intercepts every Gst::Message posted by its children and implements the following default behaviour for each of them:

A Gst::Bin implements the following default behaviour for answering to a Gst::Query:

A Gst::Bin 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.

Last reviewed on 2006-04-28 (0.10.6)


Constructor & Destructor Documentation

virtual Gst::Bin::~Bin (  )  [virtual]

Gst::Bin::Bin ( const Glib::ustring &  name  )  [explicit, protected]

Gst::Bin::Bin (  )  [protected]


Member Function Documentation

Glib::RefPtr<Gst::Bin> Gst::Bin::add ( const Glib::RefPtr<Gst::Element>&  element  ) 

Adds the given element to the bin.

This 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 then the pads will be unlinked before the element is added to the bin.

MT safe.

Parameters:
element The Gst::Element to add.
Returns:
This Gst::Bin if successful, for chained calls to add().
Exceptions:
std::runtime_error if the Bin does not want to accept the Element.

virtual bool Gst::Bin::add_element_vfunc ( const Glib::RefPtr<Gst::Element>&  element  )  [virtual]

Method to add an element to a bin.

static Glib::RefPtr<Bin> Gst::Bin::create (  )  [static]

Creates a new bin with a unique generic name.

Returns:
A new Gst::Bin.

Reimplemented in Gst::Pipeline, GstBase::DecodeBin, and GstBase::PlayBin2.

static Glib::RefPtr<Bin> Gst::Bin::create ( const Glib::ustring &  name  )  [static]

Creates a new bin with the given name.

Parameters:
name The name of the new bin.
Returns:
A new Gst::Bin.

Reimplemented in Gst::Pipeline, GstBase::DecodeBin, and GstBase::PlayBin2.

Glib::RefPtr<const Gst::Pad> Gst::Bin::find_unlinked_pad ( PadDirection  dir  )  const

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 0 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.

Parameters:
direction Whether to look for an unlinked source or sink pad.
Returns:
Unlinked pad of the given direction, or 0.
Since: 0.10.20.

Glib::RefPtr<Gst::Pad> Gst::Bin::find_unlinked_pad ( PadDirection  dir  ) 

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 0 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.

Parameters:
direction Whether to look for an unlinked source or sink pad.
Returns:
Unlinked pad of the given direction, or 0.
Since: 0.10.20.

Glib::ListHandle<Glib::RefPtr<Gst::Element>> Gst::Bin::get_children (  )  const

Gets the bin's list of children.

Glib::RefPtr<const Gst::Element> Gst::Bin::get_element ( GType  interface  )  const

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 iterate_all_by_interface(). This function recurses into child bins.

MT safe. Caller owns returned reference.

Parameters:
iface The Type of an interface.
Returns:
A Gst::Element inside the bin implementing the interface.

Glib::RefPtr<Gst::Element> Gst::Bin::get_element ( GType  interface  ) 

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 iterate_all_by_interface(). This function recurses into child bins.

MT safe. Caller owns returned reference.

Parameters:
iface The Type of an interface.
Returns:
A Gst::Element inside the bin implementing the interface.

Glib::RefPtr<const Gst::Element> Gst::Bin::get_element ( const Glib::ustring &  name  )  const

Gets the element with the given name from a bin.

This function recurses into child bins.

Returns: the Gst::Element with the given name, or 0

Parameters:
name The element name to search for.
Returns:
The Gst::Element with the given name, or 0.

Glib::RefPtr<Gst::Element> Gst::Bin::get_element ( const Glib::ustring &  name  ) 

Gets the element with the given name from a bin.

This function recurses into child bins.

Returns: the Gst::Element with the given name, or 0

Parameters:
name The element name to search for.
Returns:
The Gst::Element with the given name, or 0.

Glib::RefPtr<const Gst::Element> Gst::Bin::get_element_recurse_up ( const Glib::ustring &  name  )  const

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: the Gst::Element with the given name, or 0

Parameters:
name The element name to search for.
Returns:
The Gst::Element with the given name, or 0.

Glib::RefPtr<Gst::Element> Gst::Bin::get_element_recurse_up ( const Glib::ustring &  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: the Gst::Element with the given name, or 0

Parameters:
name The element name to search for.
Returns:
The Gst::Element with the given name, or 0.

int Gst::Bin::get_num_children (  )  const

Gets the number of children in the bin.

const GstBin* Gst::Bin::gobj (  )  const [inline]

Provides access to the underlying C GObject.

Reimplemented from Gst::ChildProxy.

Reimplemented in Gst::Pipeline, GstBase::DecodeBin, and GstBase::PlayBin2.

GstBin* Gst::Bin::gobj (  )  [inline]

Provides access to the underlying C GObject.

Reimplemented from Gst::ChildProxy.

Reimplemented in Gst::Pipeline, GstBase::DecodeBin, and GstBase::PlayBin2.

GstBin* Gst::Bin::gobj_copy (  ) 

Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.

Reimplemented from Gst::Element.

Reimplemented in Gst::Pipeline, GstBase::DecodeBin, and GstBase::PlayBin2.

virtual void Gst::Bin::handle_message_vfunc ( const Glib::RefPtr<Gst::Message>&  message  )  [virtual]

Method to handle a message from the children.

Gst::Iterator<Gst::Element> Gst::Bin::iterate_by_interface ( 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 Gst::Element 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.

Parameters:
iface The Type of an interface.
Returns:
A Gst::Iterator of Gst::Element for all elements in the bin implementing the given interface, or 0.

Gst::Iterator<Gst::Element> Gst::Bin::iterate_elements (  ) 

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.

Returns:
A Gst::Iterator of Gst::Element, or 0.

Gst::Iterator<Gst::Element> Gst::Bin::iterate_recurse (  ) 

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.

Returns:
A Gst::Iterator of Gst::Element, or 0.

Gst::Iterator<Gst::Element> Gst::Bin::iterate_sinks (  ) 

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.

Returns:
A Gst::Iterator of Gst::Element, or 0.

Gst::Iterator<Gst::Element> Gst::Bin::iterate_sorted (  ) 

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.

Returns:
A Gst::Iterator of Gst::Element, or 0.

Gst::Iterator<Gst::Element> Gst::Bin::iterate_sources (  ) 

Gets an iterator for all elements in the bin that have no sinkpads and have the Gst::ELEMENT_IS_SINK flag unset.

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

MT safe. Caller owns returned value.

Returns:
A Gst::Iterator of Gst::Element, or 0.

virtual void Gst::Bin::on_element_added ( const Glib::RefPtr<Gst::Element>&  element  )  [protected, virtual]

virtual void Gst::Bin::on_element_removed ( const Glib::RefPtr<Gst::Element>&  element  )  [protected, virtual]

Glib::PropertyProxy_ReadOnly<bool> Gst::Bin::property_async_handling (  )  const

The bin will handle Asynchronous state changes.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Glib::PropertyProxy<bool> Gst::Bin::property_async_handling (  ) 

The bin will handle Asynchronous state changes.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Glib::RefPtr<Gst::Bin> Gst::Bin::remove ( const Glib::RefPtr<Gst::Element>&  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 the element's pads are linked to other pads, the pads will be unlinked before the element is removed from the bin.

MT safe.

element the Gst::Element to remove Returns this Gst::Bin if successful (for further removing if wanted), NULL otherwise

virtual bool Gst::Bin::remove_element_vfunc ( const Glib::RefPtr<Gst::Element>&  element  )  [virtual]

Method to remove an element from a bin.

Glib::SignalProxy1<void,const Glib::RefPtr<Gst::Element>&> Gst::Bin::signal_element_added (  ) 

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

Prototype:
void on_my_element_added(const Glib::RefPtr<Gst::Element>& element)

Glib::SignalProxy1<void,const Glib::RefPtr<Gst::Element>&> Gst::Bin::signal_element_removed (  ) 

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

Prototype:
void on_my_element_removed(const Glib::RefPtr<Gst::Element>& element)


Friends And Related Function Documentation

Glib::RefPtr<Gst::Bin> wrap ( GstBin *  object,
bool  take_copy = false 
) [related]

A Glib::wrap() method for this object.

Parameters:
object The C instance.
take_copy False if the result should take ownership of the C instance. True if it should take a new copy or ref.
Returns:
A C++ instance that wraps this C instance.


The documentation for this class was generated from the following file:

Generated on Thu Jan 15 09:33:12 2009 for gstreamermm by  doxygen 1.5.7.1