gstreamermm: Gst::Element Class Reference

gstreamermm 1.0.10

- Main Page
- Modules
- Namespaces
- Classes

- Class List
- Class Index
- Class Hierarchy
- Class Members

Public Member Functions | Static Public Member Functions | Protected Member Functions | Related Functions | List of all members
Gst::Element Class Reference
gstreamermm Base Classes

The abstract base class for all pipeline elements. More...

Inheritance diagram for Gst::Element:
[legend]
Collaboration diagram for Gst::Element:
[legend]

## Public Member Functions
virtual | ~Element ()
GstElement* | gobj ()
| Provides access to the underlying C GObject. More...
const GstElement* | gobj () const
| Provides access to the underlying C GObject. More...
GstElement* | gobj_copy ()
| Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs. More...
Glib::RefPtr< Gst::Element > | link (const Glib::RefPtr< Gst::Element >& dest)
| Links this source element to the element. More...
bool | add_pad (const Glib::RefPtr< Gst::Pad >& pad)
| Adds a pad (link point) to element. More...
void | create_all_pads ()
| Creates a pad for each pad template that is always available. More...
Glib::RefPtr< Gst::Pad > | create_compatible_pad (const Glib::RefPtr< const Gst::Pad >& pad, const Glib::RefPtr< const Gst::Caps >& caps)
| Looks for an unlinked pad to which the given pad can link. More...
Glib::RefPtr< Gst::PadTemplate > | get_compatible_pad_template (const Glib::RefPtr< const Gst::PadTemplate >& compattempl)
| Retrieves a pad template from element that is compatible with compattempl. More...
Glib::RefPtr< const Gst::PadTemplate > | get_compatible_pad_template (const Glib::RefPtr< const Gst::PadTemplate >& compattempl) const
| Retrieves a pad template from element that is compatible with compattempl. More...
Glib::RefPtr< Gst::Pad > | get_request_pad (const Glib::ustring& name)
| Retrieves a pad from the element by name (e.g. "src_\\%d"). More...
Glib::RefPtr< Gst::Pad > | request_pad (const Glib::RefPtr< Gst::PadTemplate >& templ, const Glib::ustring& name, const Glib::RefPtr< const Gst::Caps >& caps)
| Retrieves a request pad from the element according to the provided template. More...
Glib::RefPtr< Gst::Pad > | request_pad (const Glib::RefPtr< Gst::PadTemplate >& templ, const Glib::ustring& name)
| A request_pad() convenience overload. More...
Glib::RefPtr< Gst::Pad > | request_pad (const Glib::RefPtr< Gst::PadTemplate >& templ, const Glib::RefPtr< const Gst::Caps >& caps)
| A request_pad() convenience overload. More...
Glib::RefPtr< Gst::Pad > | request_pad (const Glib::RefPtr< Gst::PadTemplate >& templ)
| A request_pad() convenience overload. More...
Glib::RefPtr< Gst::Pad > | get_static_pad (const Glib::ustring& name)
| Retrieves a pad from element by name. More...
Glib::RefPtr< const Gst::Pad > | get_static_pad (const Glib::ustring& name) const
| Retrieves a pad from element by name. More...
void | no_more_pads ()
| Use this function to signal that the element does not expect any more pads to show up in the current pipeline. More...
void | release_request_pad (const Glib::RefPtr< Gst::Pad >& pad)
| Makes the element free the previously requested pad as obtained with get_request_pad(). More...
bool | remove_pad (const Glib::RefPtr< Gst::Pad >& pad)
| Removes pad from element. More...
Gst::Iterator< Gst::Pad > | iterate_pads ()
| Retrieves an iterator of element's pads. More...
Gst::Iterator< const Gst::Pad > | iterate_pads () const
| Retrieves an iterator of element's pads. More...
Gst::Iterator< Gst::Pad > | iterate_sink_pads ()
| Retrieves an iterator of element's sink pads. More...
Gst::Iterator< const Gst::Pad > | iterate_sink_pads () const
| Retrieves an iterator of element's sink pads. More...
Gst::Iterator< Gst::Pad > | iterate_src_pads ()
| Retrieves an iterator of element's source pads. More...
Gst::Iterator< const Gst::Pad > | iterate_src_pads () const
| Retrieves an iterator of element's source pads. More...
void | unlink (const Glib::RefPtr< Gst::Element >& dest)
| Unlinks all source pads of the source element with all sink pads of the sink element to which they are linked. More...
bool | link_pads (const Glib::ustring& srcpadname, const Glib::RefPtr< Gst::Element >& dest, const Glib::ustring& destpadname)
| Links the two named pads of the source and destination elements. More...
void | unlink_pads (const Glib::ustring& srcpadname, const Glib::RefPtr< Gst::Element >& dest, const Glib::ustring& destpadname)
| Unlinks the two named pads of the source and destination elements. More...
bool | link_pads (const Glib::ustring& srcpadname, const Glib::RefPtr< Gst::Element >& dest, const Glib::ustring& destpadname, const Glib::RefPtr< Gst::Caps >& filter)
| Links the two named pads of the source and destination elements. More...
bool | link_pads (const Glib::ustring& srcpadname, const Glib::RefPtr< Gst::Element >& dest, const Glib::ustring& destpadname, PadLinkCheck flags)
| Links the two named pads of the source and destination elements. More...
Glib::RefPtr< Gst::Element > | link (const Glib::RefPtr< Gst::Element >& dest, const Glib::RefPtr< Gst::Caps >& filter)
| Links src to dest using the given caps as filtercaps. More...
void | set_base_time (ClockTime time)
| Set the base time of an element. More...
ClockTime | get_base_time () const
| Returns the base time of the element. More...
void | set_start_time (Gst::ClockTime time)
| Set the start time of an element. More...
Gst::ClockTime | get_start_time () const
| Returns the start time of the element. More...
void | set_bus (const Glib::RefPtr< Gst::Bus >& bus)
| Sets the bus of the element. More...
Glib::RefPtr< Gst::Bus > | get_bus ()
| Returns the bus of the element. More...
Glib::RefPtr< const Gst::Bus > | get_bus () const
| Returns the bus of the element. More...
Glib::RefPtr< Gst::ElementFactory > | get_factory ()
| Retrieves the factory that was used to create this element. More...
Glib::RefPtr< const Gst::ElementFactory > | get_factory () const
| Retrieves the factory that was used to create this element. More...
bool | set_clock (const Glib::RefPtr< Gst::Clock >& clock)
| Sets the clock for the element. More...
Glib::RefPtr< Gst::Clock > | get_clock ()
| Gets the currently configured clock of the element. More...
Glib::RefPtr< const Gst::Clock > | get_clock () const
| Gets the currently configured clock of the element. More...
Glib::RefPtr< Gst::Clock > | provide_clock ()
| Get the clock provided by the given element. More...
Glib::RefPtr< const Gst::Clock > | provide_clock () const
| Get the clock provided by the given element. More...
StateChangeReturn | set_state (State state)
| Sets the state of the element. More...
StateChangeReturn | get_state (State& state, State& pending, ClockTime timeout) const
| Gets the state of the element. More...
bool | set_locked_state (gboolean locked_state)
| Locks the state of an element, so state changes of the parent don't affect this element anymore. More...
bool | is_locked_state () const
| Checks if the state of an element is locked. More...
void | abort_state ()
| Abort the state change of the element. More...
StateChangeReturn | continue_state (StateChangeReturn ret)
| Commit the state change of the element and proceed to the next pending state if any. More...
void | lost_state ()
| Brings the element to the lost state. More...
bool | sync_state_with_parent ()
| Tries to change the state of the element to the same as its parent. More...
StateChangeReturn | change_state (StateChange transition)
| Perform transition on element. More...
void | post_message (int code, int line, MessageType type=Gst::MESSAGE_INFO, const Glib::QueryQuark& domain=get_core_error_quark(), const Glib::ustring& text=Glib::ustring(), const Glib::ustring& debug=Glib::ustring(), const Glib::ustring& file=Glib::ustring(), const Glib::ustring& function=Glib::ustring())
| Post an error, warning or info message on the bus from inside an element. More...
bool | post_message (const Glib::RefPtr< Gst::Message >& message)
| Post a message on the element's Gst::Bus. More...
bool | query (const Glib::RefPtr< Gst::Query >& query) const
| Performs a query on the given element. More...
bool | query_convert (Gst::Format src_format, gint64 src_val, Format dest_format, gint64& dest_val) const
| Queries an element to convert src_val in src_format to dest_format. More...
bool | query_position (Gst::Format format, gint64& cur) const
| Queries an element for the stream position. More...
bool | query_position (Gst::Format format) const
| Queries an element for the stream position. More...
bool | query_duration (Gst::Format format, gint64& duration) const
| Queries an element for the total stream duration. More...
bool | query_duration (Gst::Format format) const
| Queries an element for the total stream duration. More...
bool | seek (Format format, SeekFlags seek_flags, gint64 seek_pos)
| Simple API to perform a seek on the given element, meaning it just seeks to the given position relative to the start of the stream. More...
bool | seek (double rate, Format format, SeekFlags flags, SeekType cur_type, gint64 cur, SeekType stop_type, gint64 stop)
| Sends a seek event to an element. More...
bool | send_event (const Glib::RefPtr< Gst::Event >& event)
| Sends an event to an element. More...
Glib::SignalProxy0< void > | signal_no_more_pads ()
Glib::SignalProxy1< void, const Glib::RefPtr< Gst::Pad >& > | signal_pad_added ()
Glib::SignalProxy1< void, const Glib::RefPtr< Gst::Pad >& > | signal_pad_removed ()
virtual void | release_pad_vfunc (const Glib::RefPtr< Gst::Pad >& pad)
| Called when a request pad is to be released. More...
virtual Glib::RefPtr< Gst::Pad > | request_new_pad_vfunc (Glib::RefPtr< Gst::PadTemplate > templ, const Glib::ustring& name, const Glib::RefPtr< const Gst::Caps >& caps)
| Called when a new pad is requested. More...
virtual StateChangeReturn | get_state_vfunc (State& state, State& pending, ClockTime timeout) const
| Get the state of the element. More...
virtual StateChangeReturn | set_state_vfunc (State state)
| Set a new state on the element. More...
virtual StateChangeReturn | change_state_vfunc (StateChange transition)
| Called by set_state to perform an incremental state change. More...
virtual void | set_bus_vfunc (const Glib::RefPtr< Gst::Bus >& bus)
| Set a Gst::Bus on the element. More...
virtual Glib::RefPtr< Gst::Clock > | provide_clock_vfunc ()
| Gets the Gst::Clock provided by the element. More...
virtual bool | set_clock_vfunc (const Glib::RefPtr< Gst::Clock >& clock)
| Set the Gst::Clock on the element. More...
virtual bool | send_event_vfunc (const Glib::RefPtr< Gst::Event >& event)
| Send a Gst::Event to the element. More...
virtual bool | query_vfunc (const Glib::RefPtr< Gst::Query >&query) const
| Perform a Gst::Query on the element. More...
Glib::RefPtr< Gst::PadTemplate > | get_pad_template (const Glib::ustring& factory_name) const
template<typename T >
Glib::RefPtr< Gst::Element > | property (const Glib::ustring& name, const T& value)
| Sets specified property. More...
Public Member Functions inherited from Gst::Object
virtual | ~Object ()
GstObject* | gobj ()
| Provides access to the underlying C GObject. More...
const GstObject* | gobj () const
| Provides access to the underlying C GObject. More...
GstObject* | gobj_copy ()
| Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs. More...
bool | is_element () const
bool | is_element_factory () const
bool | is_pad () const
bool | is_pad_template () const
bool | is_bin () const
guint32 | get_flags () const
| Returns the entire set of flags for the object. More...
bool | set_name (const Glib::ustring& name)
| Sets the name of object, or gives object a guaranteed unique name (if name is `0`). More...
Glib::ustring | get_name () const
| Returns a copy of the name of object. More...
bool | set_parent (const Glib::RefPtr< Gst::Object >& parent)
| Sets the parent of object to parent. More...
Glib::RefPtr< Gst::Object > | get_parent ()
| Returns the parent of object. More...
Glib::RefPtr< const Gst::Object > | get_parent () const
| Returns the parent of object. More...
void | unparent ()
| Clear the parent of object, removing the associated reference. More...
bool | has_ancestor (const Glib::RefPtr< const Gst::Object >& ancestor) const
| Check if object has an ancestor ancestor somewhere up in the hierarchy. More...
Glib::ustring | get_path_string ()
| Generates a string describing the path of object in the object hierarchy. More...
Glib::PropertyProxy < Glib::ustring > | property_name ()
| The name of the object. More...
Glib::PropertyProxy_ReadOnly < Glib::ustring > | property_name () const
| The name of the object. More...
Glib::SignalProxy2< void, const Glib::RefPtr< Object > &, GParamSpec* > | signal_deep_notify ()

## Static Public Member Functions
static GType | get_type ()
| Get the GType for this class, for use with the underlying GObject type system. More...
Static Public Member Functions inherited from Gst::Object
static GType | get_type ()
| Get the GType for this class, for use with the underlying GObject type system. More...
static bool | check_uniqueness (const Glib::ListHandle< const Gst::Object >& list, const Glib::ustring& name)
| Checks to see if there is any object named name in list. More...

## Protected Member Functions
virtual void | on_no_more_pads ()
| This is a default handler for the signal signal_no_more_pads(). More...
virtual void | on_pad_added (const Glib::RefPtr< Gst::Pad >& new_pad)
| This is a default handler for the signal signal_pad_added(). More...
virtual void | on_pad_removed (const Glib::RefPtr< Gst::Pad >& old_pad)
| This is a default handler for the signal signal_pad_removed(). More...
Protected Member Functions inherited from Gst::Object
virtual void | on_deep_notify (const Glib::RefPtr< Object >& prop_object, GParamSpec* prop)
| This is a default handler for the signal signal_deep_notify(). More...

## Related Functions
(Note that these are not member functions.)
Glib::RefPtr< Gst::Element > | wrap (GstElement* object, bool take_copy=false)
| A Glib::wrap() method for this object. More...
Related Functions inherited from Gst::Object
Glib::RefPtr< Gst::Object > | wrap (GstObject* object, bool take_copy=false)
| A Glib::wrap() method for this object. More...

## Detailed Description

The abstract base class for all pipeline elements.

Gst::Element is the abstract base class needed to construct an element that can be used in a GStreamer pipeline. Please refer to the plugin writers guide for more information on creating Gst::Element subclasses.

The name of a Gst::Element can be get with get_name() and set with set_name().

All elements have pads (of the type Gst::Pad). These pads link to pads on other elements. Gst::Buffer flow between these linked pads. An Element has a GList of Gst::Pad structures for all their input (or sink) and output (or source) pads. Core and plug-in writers can add and remove pads with add_pad() and remove_pad().

A pad of an element can be retrieved by name with get_request_pad() or get_static_pad(). An iterator of all pads can be retrieved with iterate_pads().

Gst::Elements can be linked through their pads. Use the link() function to link elements. Use link_filtered() to link two elements constrained by a specified set of Gst::Caps. For finer control, use link_pads() and link_pads_filtered() to specify the pads to link on each element by name.

Each element has a state (see State). You can get and set the state of an element with get_state() and set_state(). To get a string representation of a State, use Gst::Enums::get_name().

Note that clock slection and distribution is normally handled by the toplevel Gst::Pipeline so the clock functions are only to be used in very specific situations.

Last reviewed on 2006-03-12 (0.10.5).

## Constructor & Destructor Documentation

virtual Gst::Element::~Element | ( |  | ) |
| virtual

## Member Function Documentation

void Gst::Element::abort_state | ( |  | ) |

Abort the state change of the element.

This function is used by elements that do asynchronous state changes and find out something is wrong.

This function should be called with the STATE_LOCK held.

MT safe.

bool Gst::Element::add_pad | ( | const Glib::RefPtr< Gst::Pad >& | pad | ) |

Adds a pad (link point) to element.

pad's parent will be set to element; see Gst::Object::set_parent() for refcounting information.

Pads are not automatically activated so elements should perform the needed steps to activate the pad in case this pad is added in the PAUSED or PLAYING state. See Gst::Pad::set_active() for more information about activating pads.

The pad and the element should be unlocked when calling this function.

This function will emit the Gst::Element::signal_pad_added() signal on the element.

Parameters

  pad | The Gst::Pad to add to the element.

Returns
  `true` if the pad could be added. This function can fail when a pad with the same name already existed or the pad already had another parent.

MT safe.

StateChangeReturn Gst::Element::change_state | ( | StateChange | transition | ) |

Perform transition on element.

This function must be called with STATE_LOCK held and is mainly used internally.

Parameters

  transition | The requested transition.

Returns
  The Gst::StateChangeReturn of the state transition.

virtual StateChangeReturn Gst::Element::change_state_vfunc | ( | StateChange | transition | ) |
| virtual

Called by set_state to perform an incremental state change.

StateChangeReturn Gst::Element::continue_state | ( | StateChangeReturn | ret | ) |

Commit the state change of the element and proceed to the next pending state if any.

This function is used by elements that do asynchronous state changes. The core will normally call this method automatically when an element returned Gst::STATE_CHANGE_SUCCESS from the state change function.

If after calling this method the element still has not reached the pending state, the next state change is performed.

This method is used internally and should normally not be called by plugins or applications.

Parameters

  ret | The previous state return value.

Returns
  The result of the commit state change.

MT safe.

void Gst::Element::create_all_pads | ( |  | ) |

Creates a pad for each pad template that is always available.

This function is only useful during object initialization of subclasses of Gst::Element.

Glib::RefPtr<Gst::Pad> Gst::Element::create_compatible_pad | ( | const Glib::RefPtr< const Gst::Pad >& | pad,
|  | const Glib::RefPtr< const Gst::Caps >& | caps
| ) |  |

Looks for an unlinked pad to which the given pad can link.

It is not guaranteed that linking the pads will work, though it should work in most cases.

This function will first attempt to find a compatible unlinked ALWAYS pad, and if none can be found, it will request a compatible REQUEST pad by looking at the templates of element.

Parameters

  pad | The Gst::Pad to find a compatible one for.
  caps | The Gst::Caps to use as a filter.

Returns
  The Gst::Pad to which a link can be made, or `0` if one cannot be found. Gst::Object::unref() after usage.

ClockTime Gst::Element::get_base_time | ( |  | ) | const

Returns the base time of the element.

The base time is the absolute time of the clock when this element was last put to PLAYING. Subtracting the base time from the clock time gives the running time of the element.

Returns
  The base time of the element.

MT safe.

Glib::RefPtr<Gst::Bus> Gst::Element::get_bus | ( |  | ) |

Returns the bus of the element.

Note that only a Gst::Pipeline will provide a bus for the application.

Returns
  The element's Gst::Bus. unref after usage.

MT safe.

Glib::RefPtr<const Gst::Bus> Gst::Element::get_bus | ( |  | ) | const

Returns the bus of the element.

Note that only a Gst::Pipeline will provide a bus for the application.

Returns
  The element's Gst::Bus. unref after usage.

MT safe.

Glib::RefPtr<Gst::Clock> Gst::Element::get_clock | ( |  | ) |

Gets the currently configured clock of the element.

This is the clock as was last set with set_clock().

Returns
  The Gst::Clock of the element. unref after usage.

MT safe.

Glib::RefPtr<const Gst::Clock> Gst::Element::get_clock | ( |  | ) | const

Gets the currently configured clock of the element.

This is the clock as was last set with set_clock().

Returns
  The Gst::Clock of the element. unref after usage.

MT safe.

Glib::RefPtr<Gst::PadTemplate> Gst::Element::get_compatible_pad_template | ( | const Glib::RefPtr< const Gst::PadTemplate >& | compattempl | ) |

Retrieves a pad template from element that is compatible with compattempl.

Pads from compatible templates can be linked together.

Parameters

  compattempl | The Gst::PadTemplate to find a compatible template for.

Returns
  A compatible Gst::PadTemplate, or `0` if none was found. No unreferencing is necessary.

Glib::RefPtr<const Gst::PadTemplate> Gst::Element::get_compatible_pad_template | ( | const Glib::RefPtr< const Gst::PadTemplate >& | compattempl | ) | const

Retrieves a pad template from element that is compatible with compattempl.

Pads from compatible templates can be linked together.

Parameters

  compattempl | The Gst::PadTemplate to find a compatible template for.

Returns
  A compatible Gst::PadTemplate, or `0` if none was found. No unreferencing is necessary.

Glib::RefPtr<Gst::ElementFactory> Gst::Element::get_factory | ( |  | ) |

Retrieves the factory that was used to create this element.

Returns
  The Gst::ElementFactory used for creating this element. no refcounting is needed.

Glib::RefPtr<const Gst::ElementFactory> Gst::Element::get_factory | ( |  | ) | const

Retrieves the factory that was used to create this element.

Returns
  The Gst::ElementFactory used for creating this element. no refcounting is needed.

Glib::RefPtr<Gst::PadTemplate> Gst::Element::get_pad_template | ( | const Glib::ustring & | factory_name | ) | const

Glib::RefPtr<Gst::Pad> Gst::Element::get_request_pad | ( | const Glib::ustring & | name | ) |

Retrieves a pad from the element by name (e.g. "src_\\%d").

This version only retrieves request pads. The pad should be released with release_request_pad().

This method is slow and will be deprecated in the future. New code should use request_pad() with the requested template.

Parameters

  name | The name of the request Gst::Pad to retrieve.

Returns
  Requested Gst::Pad if found, otherwise `0`. Release after usage.

Gst::ClockTime Gst::Element::get_start_time | ( |  | ) | const

Returns the start time of the element.

The start time is the running time of the clock when this element was last put to PAUSED.

Usually the start_time is managed by a toplevel element such as Gst::Pipeline.

MT safe.

Returns
  The start time of the element.

StateChangeReturn Gst::Element::get_state | ( | State& | state,
|  | State& | pending,
|  | ClockTime | timeout
| ) |  | const

Gets the state of the element.

For elements that performed an ASYNC state change, as reported by set_state(), this function will block up to the specified timeout value for the state change to complete. If the element completes the state change or goes into an error, this function returns immediately with a return value of Gst::STATE_CHANGE_SUCCESS or Gst::STATE_CHANGE_FAILURE respectively.

For elements that did not return Gst::STATE_CHANGE_ASYNC, this function returns the current and pending state immediately.

This function returns Gst::STATE_CHANGE_NO_PREROLL if the element successfully changed its state but is not able to provide data yet. This mostly happens for live sources that only produce data in Gst::STATE_PLAYING. While the state change return is equivalent to Gst::STATE_CHANGE_SUCCESS, it is returned to the application to signal that some sink elements might not be able to complete their state change because an element is not producing data to complete the preroll. When setting the element to playing, the preroll will complete and playback will start.

Parameters

  state | A pointer to Gst::State to hold the state. Can be `0`.
  pending | A pointer to Gst::State to hold the pending state. Can be `0`.
  timeout | A Gst::ClockTime to specify the timeout for an async state change or Gst::CLOCK_TIME_NONE for infinite timeout.

Returns
  Gst::STATE_CHANGE_SUCCESS if the element has no more pending state and the last state change succeeded, Gst::STATE_CHANGE_ASYNC if the element is still performing a state change or Gst::STATE_CHANGE_FAILURE if the last state change failed.

MT safe.

virtual StateChangeReturn Gst::Element::get_state_vfunc | ( | State& | state,
|  | State& | pending,
|  | ClockTime | timeout
| ) |  | const
| virtual

Get the state of the element.

Glib::RefPtr<Gst::Pad> Gst::Element::get_static_pad | ( | const Glib::ustring & | name | ) |

Retrieves a pad from element by name.

This version only retrieves already-existing (i.e. 'static') pads.

Parameters

  name | The name of the static Gst::Pad to retrieve.

Returns
  The requested Gst::Pad if found, otherwise `0`. unref after usage.

MT safe.

Glib::RefPtr<const Gst::Pad> Gst::Element::get_static_pad | ( | const Glib::ustring & | name | ) | const

Retrieves a pad from element by name.

This version only retrieves already-existing (i.e. 'static') pads.

Parameters

  name | The name of the static Gst::Pad to retrieve.

Returns
  The requested Gst::Pad if found, otherwise `0`. unref after usage.

MT safe.

static GType Gst::Element::get_type | ( |  | ) |
| static

Get the GType for this class, for use with the underlying GObject type system.

GstElement* Gst::Element::gobj | ( |  | ) |
| inline

Provides access to the underlying C GObject.

const GstElement* Gst::Element::gobj | ( |  | ) | const
| inline

Provides access to the underlying C GObject.

GstElement* Gst::Element::gobj_copy | ( |  | ) |

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

bool Gst::Element::is_locked_state | ( |  | ) | const

Checks if the state of an element is locked.

If the state of an element is locked, state changes of the parent don't affect the element. This way you can leave currently unused elements inside bins. Just lock their state before changing the state from Gst::STATE_NULL.

MT safe.

Returns
  `true`, if the element's state is locked.

Gst::Iterator<Gst::Pad> Gst::Element::iterate_pads | ( |  | ) |

Retrieves an iterator of element's pads.

The iterator should be freed after usage. Also more specialized iterators exists such as iterate_src_pads() or iterate_sink_pads().

The order of pads returned by the iterator will be the order in which the pads were added to the element.

Returns
  The Gst::Iterator of Gst::Pad.

MT safe.

Gst::Iterator<const Gst::Pad> Gst::Element::iterate_pads | ( |  | ) | const

Retrieves an iterator of element's pads.

The iterator should be freed after usage. Also more specialized iterators exists such as iterate_src_pads() or iterate_sink_pads().

The order of pads returned by the iterator will be the order in which the pads were added to the element.

Returns
  The Gst::Iterator of Gst::Pad.

MT safe.

Gst::Iterator<Gst::Pad> Gst::Element::iterate_sink_pads | ( |  | ) |

Retrieves an iterator of element's sink pads.

The order of pads returned by the iterator will be the order in which the pads were added to the element.

Returns
  The Gst::Iterator of Gst::Pad.

MT safe.

Gst::Iterator<const Gst::Pad> Gst::Element::iterate_sink_pads | ( |  | ) | const

Retrieves an iterator of element's sink pads.

The order of pads returned by the iterator will be the order in which the pads were added to the element.

Returns
  The Gst::Iterator of Gst::Pad.

MT safe.

Gst::Iterator<Gst::Pad> Gst::Element::iterate_src_pads | ( |  | ) |

Retrieves an iterator of element's source pads.

The order of pads returned by the iterator will be the order in which the pads were added to the element.

Returns
  The Gst::Iterator of Gst::Pad.

MT safe.

Gst::Iterator<const Gst::Pad> Gst::Element::iterate_src_pads | ( |  | ) | const

Retrieves an iterator of element's source pads.

The order of pads returned by the iterator will be the order in which the pads were added to the element.

Returns
  The Gst::Iterator of Gst::Pad.

MT safe.

Glib::RefPtr<Gst::Element> Gst::Element::link | ( | const Glib::RefPtr< Gst::Element >& | dest | ) |

Links this source element to the element.

The link must be from source to destination - the other direction will not be tried. The function looks for existing pads that aren't linked yet. It will request new pads if necessary. Such pads need to be released manually when unlinking. If multiple links are possible, only one is established.

Make sure you have added your elements to a bin or pipeline with Gst::Bin::add() before trying to link them.

Parameters

  dest | the Gst::Element containing the destination pad.

Returns
  the destination element for further linking if desired.

Exceptions

  std::runtime_error | If the elements could not be linked.

Glib::RefPtr<Gst::Element> Gst::Element::link | ( | const Glib::RefPtr< Gst::Element >& | dest,
|  | const Glib::RefPtr< Gst::Caps >& | filter
| ) |  |

Links src to dest using the given caps as filtercaps.

The link must be from source to destination; the other direction will not be tried. The function looks for existing pads that aren't linked yet. It will request new pads if necessary. If multiple links are possible, only one is established.

Make sure you have added your elements to a bin or pipeline with Gst::Bin::add() before trying to link them.

Parameters

  dest | The Gst::Element containing the destination pad.
  filter | The Gst::Caps to filter the link.

Returns
  the destination element for further linking if desired.

Exceptions

  std::runtime_error | If the elements could not be linked.

bool Gst::Element::link_pads | ( | const Glib::ustring & | srcpadname,
|  | const Glib::RefPtr< Gst::Element >& | dest,
|  | const Glib::ustring & | destpadname
| ) |  |

Links the two named pads of the source and destination elements.

Side effect is that if one of the pads has no parent, it becomes a child of the parent of the other element. If they have different parents, the link fails.

Parameters

  srcpadname | The name of the Gst::Pad in source element or `0` for any pad.
  dest | The Gst::Element containing the destination pad.
  destpadname | The name of the Gst::Pad in destination element, or `0` for any pad.

Returns
  `true` if the pads could be linked, `false` otherwise.

bool Gst::Element::link_pads | ( | const Glib::ustring & | srcpadname,
|  | const Glib::RefPtr< Gst::Element >& | dest,
|  | const Glib::ustring & | destpadname,
|  | const Glib::RefPtr< Gst::Caps >& | filter
| ) |  |

Links the two named pads of the source and destination elements.

Side effect is that if one of the pads has no parent, it becomes a child of the parent of the other element. If they have different parents, the link fails. If caps is not #`0`, makes sure that the caps of the link is a subset of caps.

Parameters

  srcpadname | The name of the Gst::Pad in source element or `0` for any pad.
  dest | The Gst::Element containing the destination pad.
  destpadname | The name of the Gst::Pad in destination element or `0` for any pad.
  filter | The Gst::Caps to filter the link, or #`0` for no filter.

Returns
  `true` if the pads could be linked, `false` otherwise.

bool Gst::Element::link_pads | ( | const Glib::ustring & | srcpadname,
|  | const Glib::RefPtr< Gst::Element >& | dest,
|  | const Glib::ustring & | destpadname,
|  | PadLinkCheck | flags
| ) |  |

Links the two named pads of the source and destination elements.

Side effect is that if one of the pads has no parent, it becomes a child of the parent of the other element. If they have different parents, the link fails.

Calling link_pads_full() with flags == Gst::PAD_LINK_CHECK_DEFAULT is the same as calling link_pads() and the recommended way of linking pads with safety checks applied.

This is a convenience function for Gst::Pad::link_full().

Parameters

  srcpadname | The name of the Gst::Pad in source element or `0` for any pad.
  dest | The Gst::Element containing the destination pad.
  destpadname | The name of the Gst::Pad in destination element, or `0` for any pad.
  flags | The Gst::PadLinkCheck to be performed when linking pads.

Returns
  `true` if the pads could be linked, `false` otherwise.

void Gst::Element::lost_state | ( |  | ) |

Brings the element to the lost state.

The current state of the element is copied to the pending state so that any call to get_state() will return Gst::STATE_CHANGE_ASYNC.

An ASYNC_START message is posted. If the element was PLAYING, it will go to PAUSED. The element will be restored to its PLAYING state by the parent pipeline when it prerolls again.

This is mostly used for elements that lost their preroll buffer in the Gst::STATE_PAUSED or Gst::STATE_PLAYING state after a flush, they will go to their pending state again when a new preroll buffer is queued. This function can only be called when the element is currently not in error or an async state change.

This function is used internally and should normally not be called from plugins or applications.

void Gst::Element::no_more_pads | ( |  | ) |

Use this function to signal that the element does not expect any more pads to show up in the current pipeline.

This function should be called whenever pads have been added by the element itself. Elements with Gst::PAD_SOMETIMES pad templates use this in combination with autopluggers to figure out that the element is done initializing its pads.

This function emits the Gst::Element::signal_no_more_pads() signal.

MT safe.

virtual void Gst::Element::on_no_more_pads | ( |  | ) |
| protectedvirtual

This is a default handler for the signal signal_no_more_pads().

virtual void Gst::Element::on_pad_added | ( | const Glib::RefPtr< Gst::Pad >& | new_pad | ) |
| protectedvirtual

This is a default handler for the signal signal_pad_added().

virtual void Gst::Element::on_pad_removed | ( | const Glib::RefPtr< Gst::Pad >& | old_pad | ) |
| protectedvirtual

This is a default handler for the signal signal_pad_removed().

void Gst::Element::post_message | ( | int | code,
|  | int | line,
|  | MessageType | type = `Gst::MESSAGE_INFO`,
|  | const Glib::QueryQuark & | domain = `get_core_error_quark()`,
|  | const Glib::ustring & | text = `Glib::ustring()`,
|  | const Glib::ustring & | debug = `Glib::ustring()`,
|  | const Glib::ustring & | file = `Glib::ustring()`,
|  | const Glib::ustring & | function = `Glib::ustring()`
| ) |  |

Post an error, warning or info message on the bus from inside an element.

type must be of Gst::MESSAGE_ERROR, Gst::MESSAGE_WARNING or Gst::MESSAGE_INFO.

MT safe.

Parameters

  code | The GError code belonging to the domain.
  line | The source code line where the error was generated.
  type | The GstMessageType.
  domain | The GStreamer GError domain this message belongs to.
  text | A text string to be used as a replacement for the default message connected to code.
  debug | A debug message to be used as a replacement for the default debugging information.
  file | The source code file where the error was generated.
  function | The source code function where the error was generated.

bool Gst::Element::post_message | ( | const Glib::RefPtr< Gst::Message >& | message | ) |

Post a message on the element's Gst::Bus.

This function takes ownership of the message; if you want to access the message after this call, you should add an additional reference before calling.

Parameters

  message | A Gst::Message to post.

Returns
  `true` if the message was successfully posted. The function returns `false` if the element did not have a bus.

MT safe.

template <typename T >

Glib::RefPtr<Gst::Element> Gst::Element::property | ( | const Glib::ustring & | name,
|  | const T & | value
| ) |  |
| inline

Sets specified property.

Allows to create property-chain (e.g. element->property("location", "test.ogg")->property("num_buffers", 20);

Glib::RefPtr<Gst::Clock> Gst::Element::provide_clock | ( |  | ) |

Get the clock provided by the given element.

<note>An element is only required to provide a clock in the PAUSED state. Some elements can provide a clock in other states.</note>

Returns
  The GstClock provided by the element or `0` if no clock could be provided. Unref after usage.

MT safe.

Glib::RefPtr<const Gst::Clock> Gst::Element::provide_clock | ( |  | ) | const

Get the clock provided by the given element.

<note>An element is only required to provide a clock in the PAUSED state. Some elements can provide a clock in other states.</note>

Returns
  The GstClock provided by the element or `0` if no clock could be provided. Unref after usage.

MT safe.

virtual Glib::RefPtr<Gst::Clock> Gst::Element::provide_clock_vfunc | ( |  | ) |
| virtual

Gets the Gst::Clock provided by the element.

bool Gst::Element::query | ( | const Glib::RefPtr< Gst::Query >& | query | ) | const

Performs a query on the given element.

For elements that don't implement a query handler, this function forwards the query to a random srcpad or to the peer of a random linked sinkpad of this element.

Please note that some queries might need a running pipeline to work.

Parameters

  query | The Gst::Query.

Returns
  `true` if the query could be performed.

MT safe.

bool Gst::Element::query_convert | ( | Gst::Format | src_format,
|  | gint64 | src_val,
|  | Format | dest_format,
|  | gint64 & | dest_val
| ) |  | const

Queries an element to convert src_val in src_format to dest_format.

Parameters

  src_format | A Gst::Format to convert from.
  src_val | A value to convert.
  dest_format | The Gst::Format to convert to.
  dest_val | A pointer to the result.

Returns
  `true` if the query could be performed.

bool Gst::Element::query_duration | ( | Gst::Format | format,
|  | gint64 & | duration
| ) |  | const

Queries an element for the total stream duration.

Parameters

  format | The Gst::Format requested.
  duration | A location in which to store the total duration, or `0`.

Returns
  `true` if the query could be performed.

bool Gst::Element::query_duration | ( | Gst::Format | format | ) | const

Queries an element for the total stream duration.

Parameters

  format | On return contains the Gst::Format used.

Returns
  true if the query could be performed.

bool Gst::Element::query_position | ( | Gst::Format | format,
|  | gint64 & | cur
| ) |  | const

Queries an element for the stream position.

If one repeatedly calls this function one can also create and reuse it in query().

Parameters

  format | The Gst::Format requested.
  cur | A location in which to store the current position, or `0`.

Returns
  `true` if the query could be performed.

bool Gst::Element::query_position | ( | Gst::Format | format | ) | const

Queries an element for the stream position.

Parameters

  format | On return will contain the Gst::Format used.

Returns
  true if the query could be performed.

virtual bool Gst::Element::query_vfunc | ( | const Glib::RefPtr< Gst::Query >& | query | ) | const
| virtual

Perform a Gst::Query on the element.

virtual void Gst::Element::release_pad_vfunc | ( | const Glib::RefPtr< Gst::Pad >& | pad | ) |
| virtual

Called when a request pad is to be released.

void Gst::Element::release_request_pad | ( | const Glib::RefPtr< Gst::Pad >& | pad | ) |

Makes the element free the previously requested pad as obtained with get_request_pad().

MT safe.

Parameters

  pad | The Gst::Pad to release.

bool Gst::Element::remove_pad | ( | const Glib::RefPtr< Gst::Pad >& | pad | ) |

Removes pad from element.

pad will be destroyed if it has not been referenced elsewhere using Gst::Object::unparent().

This function is used by plugin developers and should not be used by applications. Pads that were dynamically requested from elements with get_request_pad() should be released with the release_request_pad() function instead.

Pads are not automatically deactivated so elements should perform the needed steps to deactivate the pad in case this pad is removed in the PAUSED or PLAYING state. See Gst::Pad::set_active() for more information about deactivating pads.

The pad and the element should be unlocked when calling this function.

This function will emit the Gst::Element::signal_pad_removed() signal on the element.

Parameters

  pad | The Gst::Pad to remove from the element.

Returns
  `true` if the pad could be removed. Can return `false` if the pad does not belong to the provided element.

MT safe.

virtual Glib::RefPtr<Gst::Pad> Gst::Element::request_new_pad_vfunc | ( | Glib::RefPtr< Gst::PadTemplate > | templ,
|  | const Glib::ustring & | name,
|  | const Glib::RefPtr< const Gst::Caps >& | caps
| ) |  |
| virtual

Called when a new pad is requested.

Glib::RefPtr<Gst::Pad> Gst::Element::request_pad | ( | const Glib::RefPtr< Gst::PadTemplate >& | templ,
|  | const Glib::ustring & | name,
|  | const Glib::RefPtr< const Gst::Caps >& | caps
| ) |  |

Retrieves a request pad from the element according to the provided template.

Pad templates can be looked up using Gst::ElementFactory::get_static_pad_templates().

The pad should be released with release_request_pad().

Parameters

  templ | A Gst::PadTemplate of which we want a pad of.
  name | The name of the request Gst::Pad to retrieve. Can be `0`.
  caps | The caps of the pad we want to request. Can be `0`.

Returns
  Requested Gst::Pad if found, otherwise `0`. Release after usage.

Glib::RefPtr<Gst::Pad> Gst::Element::request_pad | ( | const Glib::RefPtr< Gst::PadTemplate >& | templ,
|  | const Glib::ustring & | name
| ) |  |

A request_pad() convenience overload.

Glib::RefPtr<Gst::Pad> Gst::Element::request_pad | ( | const Glib::RefPtr< Gst::PadTemplate >& | templ,
|  | const Glib::RefPtr< const Gst::Caps >& | caps
| ) |  |

A request_pad() convenience overload.

Glib::RefPtr<Gst::Pad> Gst::Element::request_pad | ( | const Glib::RefPtr< Gst::PadTemplate >& | templ | ) |

A request_pad() convenience overload.

bool Gst::Element::seek | ( | Format | format,
|  | SeekFlags | seek_flags,
|  | gint64 | seek_pos
| ) |  |

Simple API to perform a seek on the given element, meaning it just seeks to the given position relative to the start of the stream.

For more complex operations like segment seeks (e.g. for looping) or changing the playback rate or seeking relative to the last configured playback segment you should use seek().

In a completely prerolled PAUSED or PLAYING pipeline, seeking is always guaranteed to return `true` on a seekable media type or `false` when the media type is certainly not seekable (such as a live stream).

Some elements allow for seeking in the READY state, in this case they will store the seek event and execute it when they are put to PAUSED. If the element supports seek in READY, it will always return `true` when it receives the event in the READY state.

Parameters

  format | A Gst::Format to execute the seek in, such as Gst::FORMAT_TIME.
  seek_flags | Seek options; playback applications will usually want to use GST_SEEK_FLAG_FLUSH | GST_SEEK_FLAG_KEY_UNIT here.
  seek_pos | Position to seek to (relative to the start); if you are doing a seek in Gst::FORMAT_TIME this value is in nanoseconds - multiply with Gst::SECOND to convert seconds to nanoseconds or with Gst::MSECOND to convert milliseconds to nanoseconds.

Returns
  `true` if the seek operation succeeded. Flushing seeks will trigger a preroll, which will emit Gst::MESSAGE_ASYNC_DONE.

bool Gst::Element::seek | ( | double | rate,
|  | Format | format,
|  | SeekFlags | flags,
|  | SeekType | cur_type,
|  | gint64 | cur,
|  | SeekType | stop_type,
|  | gint64 | stop
| ) |  |

Sends a seek event to an element.

See gst_event_new_seek() for the details of the parameters. The seek event is sent to the element using send_event().

MT safe.

Parameters

  rate | The new playback rate.
  format | The format of the seek values.
  flags | The optional seek flags.
  start_type | The type and flags for the new start position.
  start | The value of the new start position.
  stop_type | The type and flags for the new stop position.
  stop | The value of the new stop position.

Returns
  `true` if the event was handled. Flushing seeks will trigger a preroll, which will emit Gst::MESSAGE_ASYNC_DONE.

bool Gst::Element::send_event | ( | const Glib::RefPtr< Gst::Event >& | event | ) |

Sends an event to an element.

If the element doesn't implement an event handler, the event will be pushed on a random linked sink pad for upstream events or a random linked source pad for downstream events.

This function takes owership of the provided event.

Parameters

  event | The Gst::Event to send to the element.

Returns
  true if the event was handled. MT safe.

virtual bool Gst::Element::send_event_vfunc | ( | const Glib::RefPtr< Gst::Event >& | event | ) |
| virtual

Send a Gst::Event to the element.

void Gst::Element::set_base_time | ( | ClockTime | time | ) |

Set the base time of an element.

See get_base_time().

MT safe.

Parameters

  time | The base time to set.

void Gst::Element::set_bus | ( | const Glib::RefPtr< Gst::Bus >& | bus | ) |

Sets the bus of the element.

Increases the refcount on the bus. For internal use only, unless you're testing elements.

MT safe.

Parameters

  bus | The Gst::Bus to set.

virtual void Gst::Element::set_bus_vfunc | ( | const Glib::RefPtr< Gst::Bus >& | bus | ) |
| virtual

Set a Gst::Bus on the element.

bool Gst::Element::set_clock | ( | const Glib::RefPtr< Gst::Clock >& | clock | ) |

Sets the clock for the element.

This function increases the refcount on the clock. Any previously set clock on the object is unreffed.

Parameters

  clock | The Gst::Clock to set for the element.

Returns
  `true` if the element accepted the clock. An element can refuse a clock when it, for example, is not able to slave its internal clock to the clock or when it requires a specific clock to operate.

MT safe.

virtual bool Gst::Element::set_clock_vfunc | ( | const Glib::RefPtr< Gst::Clock >& | clock | ) |
| virtual

Set the Gst::Clock on the element.

bool Gst::Element::set_locked_state | ( | gboolean | locked_state | ) |

Locks the state of an element, so state changes of the parent don't affect this element anymore.

MT safe.

Parameters

  locked_state | `true` to lock the element's state.

Returns
  `true` if the state was changed, `false` if bad parameters were given or the elements state-locking needed no change.

void Gst::Element::set_start_time | ( | Gst::ClockTime | time | ) |

Set the start time of an element.

The start time of the element is the running time of the element when it last went to the PAUSED state. In READY or after a flushing seek, it is set to 0.

Toplevel elements like Gst::Pipeline will manage the start_time and base_time on its children. Setting the start_time to Gst::CLOCK_TIME_NONE on such a toplevel element will disable the distribution of the base_time to the children and can be useful if the application manages the base_time itself, for example if you want to synchronize capture from multiple pipelines, and you can also ensure that the pipelines have the same clock.

MT safe.

Parameters

  time | The base time to set.

StateChangeReturn Gst::Element::set_state | ( | State | state | ) |

Sets the state of the element.

This function will try to set the requested state by going through all the intermediary states and calling the class's state change function for each.

This function can return Gst::STATE_CHANGE_ASYNC, in which case the element will perform the remainder of the state change asynchronously in another thread. An application can use get_state() to wait for the completion of the state change or it can wait for a Gst::MESSAGE_ASYNC_DONE or Gst::MESSAGE_STATE_CHANGED on the bus.

State changes to Gst::STATE_READY or Gst::STATE_NULL never return Gst::STATE_CHANGE_ASYNC.

Parameters

  state | The element's new Gst::State.

Returns
  Result of the state change using Gst::StateChangeReturn.

MT safe.

virtual StateChangeReturn Gst::Element::set_state_vfunc | ( | State | state | ) |
| virtual

Set a new state on the element.

Glib::SignalProxy0< void > Gst::Element::signal_no_more_pads | ( |  | ) |

Slot Prototype:
  `void on_my_no_more_pads()`

This signals that the element will not generate more dynamic pads. Note that this signal will usually be emitted from the context of the streaming thread.

Glib::SignalProxy1< void,const Glib::RefPtr<Gst::Pad>& > Gst::Element::signal_pad_added | ( |  | ) |

Slot Prototype:
  `void on_my_pad_added(const Glib::RefPtr<Gst::Pad>& new_pad)`

a new Gst::Pad has been added to the element. Note that this signal will usually be emitted from the context of the streaming thread. Also keep in mind that if you add new elements to the pipeline in the signal handler you will need to set them to the desired target state with Gst::Element::set_state() or Gst::Element::sync_state_with_parent().

Parameters

  new_pad | The pad that has been added.

Glib::SignalProxy1< void,const Glib::RefPtr<Gst::Pad>& > Gst::Element::signal_pad_removed | ( |  | ) |

Slot Prototype:
  `void on_my_pad_removed(const Glib::RefPtr<Gst::Pad>& old_pad)`

a Gst::Pad has been removed from the element

Parameters

  old_pad | The pad that has been removed.

bool Gst::Element::sync_state_with_parent | ( |  | ) |

Tries to change the state of the element to the same as its parent.

If this function returns `false`, the state of element is undefined.

Returns
  `true`, if the element's state could be synced to the parent's state.

MT safe.

void Gst::Element::unlink | ( | const Glib::RefPtr< Gst::Element >& | dest | ) |

Unlinks all source pads of the source element with all sink pads of the sink element to which they are linked.

If the link has been made using link(), it could have created an requestpad, which has to be released using release_request_pad().

Parameters

  dest | The sink Gst::Element to unlink.

void Gst::Element::unlink_pads | ( | const Glib::ustring & | srcpadname,
|  | const Glib::RefPtr< Gst::Element >& | dest,
|  | const Glib::ustring & | destpadname
| ) |  |

Unlinks the two named pads of the source and destination elements.

This is a convenience function for Gst::Pad::unlink().

Parameters

  srcpadname | The name of the Gst::Pad in source element.
  dest | A Gst::Element containing the destination pad.
  destpadname | The name of the Gst::Pad in destination element.

## Friends And Related Function Documentation

Glib::RefPtr< Gst::Element > wrap | ( | GstElement * | 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:

- gstreamermm/element.h