Known Derived Interfaces

Signals

Description

GstElement 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 GstElement subclasses.

The element must check if the resources it needs are available. Device
sinks and -sources typically try to probe the device to constrain their
caps.

The element opens the device (in case feature need to be probed).

GST_STATE_CHANGE_READY_TO_PAUSED

state change from READY to PAUSED.

The element pads are activated in order to receive data in PAUSED.
Streaming threads are started.

Some elements might need to return GST_STATE_CHANGE_ASYNC and complete
the state change when they have enough information. It is a requirement
for sinks to return GST_STATE_CHANGE_ASYNC and complete the state change
when they receive the first buffer or GST_EVENT_EOS (preroll).
Sinks also block the dataflow when in PAUSED.

GST_ELEMENT_ERROR()

#define GST_ELEMENT_ERROR(el, domain, code, text, debug)

Utility function that elements can use in case they encountered a fatal
data processing error. The pipeline will post an error message and the
application will be requested to stop further media processing.

the message to display (format string and args enclosed in
parentheses)

debug :

debugging information for the message (format string and args
enclosed in parentheses)

GST_ELEMENT_INFO()

#define GST_ELEMENT_INFO(el, domain, code, text, debug)

Utility function that elements can use in case they want to inform
the application of something noteworthy that is not an error.
The pipeline will post a info message and the
application will be informed.

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

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.

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.

gst_element_link ()

Links src to dest. 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.

gst_element_link_pads ()

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.

gst_element_link_pads_full ()

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.

gst_element_link_pads_filtered ()

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 NULL, makes sure that the caps of the link is a subset of caps.

gst_element_link_filtered ()

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.

gst_element_get_base_time ()

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.

gst_element_set_start_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 GstPipeline 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.

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.

gst_element_provides_clock ()

Query if the element provides a clock. A GstClock provided by an
element can be used as the global GstClock for the pipeline.
An element that can provide a clock is only required to do so in the PAUSED
state, this means when it is fully negotiated and has allocated the resources
to operate the clock.

gst_element_set_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 gst_element_get_state() to wait for the completion
of the state change or it can wait for a state change message on the bus.

gst_element_get_state ()

For elements that performed an ASYNC state change, as reported by
gst_element_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.

gst_element_is_locked_state ()

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.

gst_element_continue_state ()

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.

An ASYNC_START message is posted with indication to distribute a new
base_time to the element when new_base_time is TRUE.
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.

gst_element_send_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 so you should
gst_event_ref() it if you want to reuse the event after this call.

gst_element_seek_simple ()

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

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 (the seek might not always be
executed instantly though)

The "pad-added" signal

a new GstPad 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().