GstElement

Name

GstElement -- Base class for all pipeline elements

Synopsis


#include <gst/gst.h>


enum        GstElementState;
enum        GstElementStateReturn;
#define     GST_NUM_STATES
#define     GST_STATE                       (obj)
#define     GST_STATE_PENDING               (obj)
#define     GST_STATE_TRANSITION            (obj)
#define     GST_STATE_NULL_TO_READY
#define     GST_STATE_READY_TO_PAUSED
#define     GST_STATE_PAUSED_TO_READY
#define     GST_STATE_PLAYING_TO_PAUSED
#define     GST_STATE_PAUSED_TO_PLAYING
#define     GST_STATE_READY_TO_NULL
enum        GstElementFlags;
#define     GST_ELEMENT_IS_THREAD_SUGGESTED (obj)
#define     GST_ELEMENT_IS_DECOUPLED        (obj)
#define     GST_ELEMENT_IS_EOS              (obj)
#define     GST_ELEMENT_IS_EVENT_AWARE      (obj)
#define     GST_ELEMENT_PARENT              (obj)
#define     GST_ELEMENT_NAME                (obj)
#define     GST_ELEMENT_PADS                (obj)
#define     GST_ELEMENT_SCHED               (obj)
#define     GST_ELEMENT_MANAGER             (obj)
struct      GstElement;
void        (*GstElementLoopFunction)       (GstElement *element);
void        gst_element_class_add_padtemplate
                                            (GstElementClass *klass,
                                             GstPadTemplate *templ);
#define     gst_element_destroy             (element)
void        gst_element_set_loop_function   (GstElement *element,
                                             GstElementLoopFunction loop);
void        gst_element_set_name            (GstElement *element,
                                             const gchar *name);
const gchar* gst_element_get_name           (GstElement *element);
GstScheduler* gst_element_get_sched         (GstElement *element);
void        gst_element_set_sched           (GstElement *element,
                                             GstScheduler *sched);
void        gst_element_set_parent          (GstElement *element,
                                             GstObject *parent);
GstObject*  gst_element_get_parent          (GstElement *element);
void        gst_element_add_pad             (GstElement *element,
                                             GstPad *pad);
void        gst_element_remove_pad          (GstElement *element,
                                             GstPad *pad);
GstPad*     gst_element_get_pad             (GstElement *element,
                                             const gchar *name);
GList*      gst_element_get_pad_list        (GstElement *element);
GList*      gst_element_get_padtemplate_list
                                            (GstElement *element);
GstPadTemplate* gst_element_get_padtemplate_by_name
                                            (GstElement *element,
                                             const guchar *name);
GstPad*     gst_element_add_ghost_pad       (GstElement *element,
                                             GstPad *pad,
                                             gchar *name);
void        gst_element_remove_ghost_pad    (GstElement *element,
                                             GstPad *pad);
GstPad*     gst_element_request_compatible_pad
                                            (GstElement *element,
                                             GstPadTemplate *templ);
GstPad*     gst_element_request_pad_by_name (GstElement *element,
                                             const gchar *name);
gboolean    gst_element_connect             (GstElement *src,
                                             const gchar *srcpadname,
                                             GstElement *dest,
                                             const gchar *destpadname);
gboolean    gst_element_connect_filtered    (GstElement *src,
                                             const gchar *srcpadname,
                                             GstElement *dest,
                                             const gchar *destpadname,
                                             GstCaps *filtercaps);
void        gst_element_disconnect          (GstElement *src,
                                             const gchar *srcpadname,
                                             GstElement *dest,
                                             const gchar *destpadname);
gint        gst_element_set_state           (GstElement *element,
                                             GstElementState state);
GstElementState gst_element_get_state       (GstElement *element);
void        gst_element_wait_state_change   (GstElement *element);
const gchar* gst_element_statename          (GstElementState state);
void        gst_element_info                (GstElement *element,
                                             const gchar *info,
                                             ...);
void        gst_element_error               (GstElement *element,
                                             const gchar *error,
                                             ...);
GstElementFactory* gst_element_get_factory  (GstElement *element);
void        gst_element_set_eos             (GstElement *element);
void        gst_element_install_std_props   (GstElementClass *klass,
                                             const char *first_name,
                                             ...);
void        gst_element_send_event          (GstElement *element,
                                             GstEvent *event);
gboolean    gst_element_interrupt           (GstElement *element);
void        gst_element_yield               (GstElement *element);

Object Hierarchy


  GObject
   +----GstObject
         +----GstElement

Signal Prototypes


"eos"       void        user_function      (GstElement *gstelement,
                                            gpointer user_data);
"error"     void        user_function      (GstElement *gstelement,
                                            GObject *arg1,
                                            gchar *arg2,
                                            gpointer user_data);
"new-pad"   void        user_function      (GstElement *gstelement,
                                            gpointer arg1,
                                            gpointer user_data);
"pad-removed"
            void        user_function      (GstElement *gstelement,
                                            gpointer arg1,
                                            gpointer user_data);
"state-change"
            void        user_function      (GstElement *gstelement,
                                            gint arg1,
                                            gint arg2,
                                            gpointer user_data);

Description

GstElement is the base class needed to construct an element that can be used in a GST pipeline. As such, it is not a functional entity, and cannot do anything when placed in a pipeline.

All GstElements have a list containing the GstPad structure for all their inputs and outputs. These can be added with gst_element_add_pad() or gst_element_add_ghost_pad(), and retrieved by name with gst_element_get_pad(), or in a list form by gst_element_get_pad_list().

gst_element_connect() is a convenience function provided to make it simpler to connect pads of two elements together.

Details

enum GstElementState

typedef enum {
  GST_STATE_VOID_PENDING        = 0,
  GST_STATE_NULL                = (1 << 0),
  GST_STATE_READY               = (1 << 1),
  GST_STATE_PAUSED              = (1 << 2),
  GST_STATE_PLAYING             = (1 << 3),
} GstElementState;

This enum defines the standard states an element may be in. You will normally use gst_element_set_state() to change the state of an element.

GST_STATE_VOID_PENDING 
GST_STATE_NULLReset the state of an element.
GST_STATE_READYwill make the element ready to start processing data. some elements might have a non trivial way to initialize themselves.
GST_STATE_PAUSEDmeans there really is data flowing temporary stops the data flow.
GST_STATE_PLAYINGmeans there really is data flowing through the graph.


enum GstElementStateReturn

typedef enum {
  GST_STATE_FAILURE             = 0,
  GST_STATE_SUCCESS             = 1,
  GST_STATE_ASYNC               = 2,
} GstElementStateReturn;

This enum defines the standard return values that an element can return after a state change.

GST_STATE_FAILUREthe element could not perform the state change
GST_STATE_SUCCESSthe element successfully changed its state
GST_STATE_ASYNCthe element will asynchronously change its state as soon as possible


GST_NUM_STATES

#define GST_NUM_STATES 4

The maximun number of states.


GST_STATE()

#define GST_STATE(obj)			(GST_ELEMENT(obj)->current_state)

This macro returns the current state of the element.

obj :Element to return state for.


GST_STATE_PENDING()

#define GST_STATE_PENDING(obj)		(GST_ELEMENT(obj)->pending_state)

This macro returns the currently pending state of the element.

obj :Element to return the pending state for.


GST_STATE_TRANSITION()

#define GST_STATE_TRANSITION(obj)	((GST_STATE(obj)<<8) | GST_STATE_PENDING(obj))

Returns the state transition this object is going through.

obj :the Element to return the state transition for


GST_STATE_NULL_TO_READY

#define GST_STATE_NULL_TO_READY		((GST_STATE_NULL<<8) | GST_STATE_READY)

The Element is going from the NULL state to the READY state.


GST_STATE_READY_TO_PAUSED

#define GST_STATE_READY_TO_PAUSED	((GST_STATE_READY<<8) | GST_STATE_PAUSED)

The Element is going from the READY state to the PAUSED state.


GST_STATE_PAUSED_TO_READY

#define GST_STATE_PAUSED_TO_READY	((GST_STATE_PAUSED<<8) | GST_STATE_READY)

The Element is going from the PAUSED state to the READY state.


GST_STATE_PLAYING_TO_PAUSED

#define GST_STATE_PLAYING_TO_PAUSED	((GST_STATE_PLAYING<<8) | GST_STATE_PAUSED)

The Element is going from the PLAYING state to the PAUSED state.


GST_STATE_PAUSED_TO_PLAYING

#define GST_STATE_PAUSED_TO_PLAYING	((GST_STATE_PAUSED<<8) | GST_STATE_PLAYING)

The Element is going from the PAUSED state to the PLAYING state.


GST_STATE_READY_TO_NULL

#define GST_STATE_READY_TO_NULL		((GST_STATE_READY<<8) | GST_STATE_NULL)

The Element is going from the READY state to the NULL state.


enum GstElementFlags

typedef enum {
  /* element is complex (for some def.) and generally require a cothread */
  GST_ELEMENT_COMPLEX		= GST_OBJECT_FLAG_LAST,
  /* input and output pads aren't directly coupled to each other
     examples: queues, multi-output async readers, etc. */
  GST_ELEMENT_DECOUPLED,
  /* this element should be placed in a thread if at all possible */
  GST_ELEMENT_THREAD_SUGGESTED,
  /* this element is incable of seeking (FIXME: does this apply to filters?) */
  GST_ELEMENT_NO_SEEK,

  /* this element, for some reason, has a loop function that performs
   * an infinite loop without calls to gst_element_yield () */
  GST_ELEMENT_INFINITE_LOOP,

  /* private flags that can be used by the scheduler */
  GST_ELEMENT_SCHEDULER_PRIVATE1,
  GST_ELEMENT_SCHEDULER_PRIVATE2,

  /* there is a new loopfunction ready for placement */
  GST_ELEMENT_NEW_LOOPFUNC,

  /* if this element can handle events */
  GST_ELEMENT_EVENT_AWARE,

  /* use some padding for future expansion */
  GST_ELEMENT_FLAG_LAST		= GST_OBJECT_FLAG_LAST + 12,
} GstElementFlags;

This enum defines the standard flags that an element may have.


GST_ELEMENT_IS_THREAD_SUGGESTED()

#define GST_ELEMENT_IS_THREAD_SUGGESTED(obj)	(GST_FLAG_IS_SET(obj,GST_ELEMENT_THREAD_SUGGESTED))

Queries whether the Element should be placed in a thread.

obj :The element to query


GST_ELEMENT_IS_DECOUPLED()

#define GST_ELEMENT_IS_DECOUPLED(obj)		(GST_FLAG_IS_SET(obj,GST_ELEMENT_DECOUPLED))

Queries if the Element is decoupled.

obj :The element to query


GST_ELEMENT_IS_EOS()

#define GST_ELEMENT_IS_EOS(obj)			(GST_FLAG_IS_SET(obj,GST_ELEMENT_EOS))

Query wether this element is in the End Of Stream state.

obj :The element to query


GST_ELEMENT_IS_EVENT_AWARE()

#define GST_ELEMENT_IS_EVENT_AWARE(obj)		(GST_FLAG_IS_SET(obj,GST_ELEMENT_EVENT_AWARE))

Query wether this element can handle events.

obj :The element to query


GST_ELEMENT_PARENT()

#define GST_ELEMENT_PARENT(obj)			(GST_OBJECT_PARENT(obj))

Get the parent object of this element.

obj :The element to query


GST_ELEMENT_NAME()

#define GST_ELEMENT_NAME(obj)			(GST_OBJECT_NAME(obj))

Get the name of this element.

obj :The element to query


GST_ELEMENT_PADS()

#define GST_ELEMENT_PADS(obj)			((obj)->pads)

Get the pads of this elements.

obj :The element to query


GST_ELEMENT_SCHED()

#define GST_ELEMENT_SCHED(obj)			(((GstElement*)(obj))->sched)

Get the scheduler of this element.

obj :The element to query


GST_ELEMENT_MANAGER()

#define GST_ELEMENT_MANAGER(obj)		(((GstElement*)(obj))->manager)

Get the manager of this element.

obj :The element to query


struct GstElement

struct GstElement;


GstElementLoopFunction ()

void        (*GstElementLoopFunction)       (GstElement *element);

This function type is used to specify a loop function for the element. It is passed the element in question, and is expect to return only in error circumstances.

element :The element in question.


gst_element_class_add_padtemplate ()

void        gst_element_class_add_padtemplate
                                            (GstElementClass *klass,
                                             GstPadTemplate *templ);

Add a padtemplate to an element class. This is useful if you have derived a custom bin and wish to provide an on-request pad at runtime. Plugin writers should use gst_elementfactory_add_padtemplate instead.

klass : element class to add padtemplate to
templ : padtemplate to add


gst_element_destroy()

#define			gst_element_destroy(element)	gst_object_destroy (GST_OBJECT (element))

Destroy the element. This is potentially dangerous, use gst_object_unref instead.

element :the element to destroy


gst_element_set_loop_function ()

void        gst_element_set_loop_function   (GstElement *element,
                                             GstElementLoopFunction loop);

This sets the loop function for the element. The function pointed to can deviate from the GstElementLoopFunction definition in type of pointer only.

NOTE: in order for this to take effect, the current loop function *must* exit. Assuming the loop function itself is the only one who will cause a new loopfunc to be assigned, this should be no problem.

element : Element to set loop function of.
loop : Pointer to loop function.


gst_element_set_name ()

void        gst_element_set_name            (GstElement *element,
                                             const gchar *name);

Set the name of the element, getting rid of the old name if there was one.

element : GstElement to set name of
name : new name of element


gst_element_get_name ()

const gchar* gst_element_get_name           (GstElement *element);

Get the name of the element.

element : GstElement to get name of
Returns : name of the element


gst_element_get_sched ()

GstScheduler* gst_element_get_sched         (GstElement *element);

Returns the scheduler of the element.

element : Element to get manager of.
Returns : Element's scheduler


gst_element_set_sched ()

void        gst_element_set_sched           (GstElement *element,
                                             GstScheduler *sched);

Sets the scheduler of the element. For internal use only, unless you're writing a new bin subclass.

element : Element to set manager of.
sched : GstScheduler to set.


gst_element_set_parent ()

void        gst_element_set_parent          (GstElement *element,
                                             GstObject *parent);

Set the parent of the element.

element : GstElement to set parent of
parent : new parent of the object


gst_element_get_parent ()

GstObject*  gst_element_get_parent          (GstElement *element);

Get the parent of the element.

element : GstElement to get the parent of
Returns : parent of the element


gst_element_add_pad ()

void        gst_element_add_pad             (GstElement *element,
                                             GstPad *pad);

Add a pad (connection point) to the element, setting the parent of the pad to the element (and thus adding a reference).

element : element to add pad to
pad : pad to add


gst_element_remove_pad ()

void        gst_element_remove_pad          (GstElement *element,
                                             GstPad *pad);

Remove a pad (connection point) from the element,

element : element to remove pad from
pad : pad to remove


gst_element_get_pad ()

GstPad*     gst_element_get_pad             (GstElement *element,
                                             const gchar *name);

Retrieve a pad from the element by name.

element : element to find pad of
name : name of pad to retrieve
Returns : requested pad if found, otherwise NULL.


gst_element_get_pad_list ()

GList*      gst_element_get_pad_list        (GstElement *element);

Retrieve a list of the pads associated with the element.

element : element to get pads of
Returns : GList of pads


gst_element_get_padtemplate_list ()

GList*      gst_element_get_padtemplate_list
                                            (GstElement *element);

Retrieve a list of the padtemplates associated with the element.

element : element to get padtemplates of
Returns : GList of padtemplates


gst_element_get_padtemplate_by_name ()

GstPadTemplate* gst_element_get_padtemplate_by_name
                                            (GstElement *element,
                                             const guchar *name);

Retrieve a padtemplate from this element with the given name.

element : element to get padtemplate of
name : the name of the padtemplate to get.
Returns : the padtemplate with the given name


gst_element_add_ghost_pad ()

GstPad*     gst_element_add_ghost_pad       (GstElement *element,
                                             GstPad *pad,
                                             gchar *name);

Create a ghost pad from the given pad, and add it to the list of pads for this element.

element : element to add ghost pad to
pad : pad from which the new ghost pad will be created
name : name of the new ghost pad
Returns : the added ghost pad or NULL, if no ghost pad was created.


gst_element_remove_ghost_pad ()

void        gst_element_remove_ghost_pad    (GstElement *element,
                                             GstPad *pad);

removes a ghost pad from an element

element : element to remove the ghost pad from
pad : ghost pad to remove


gst_element_request_compatible_pad ()

GstPad*     gst_element_request_compatible_pad
                                            (GstElement *element,
                                             GstPadTemplate *templ);

Request a new pad from the element. The template will be used to decide what type of pad to create. This function is typically used for elements with a padtemplate with presence GST_PAD_REQUEST.

element : element to request a new pad from
templ : a pad template to which the new pad should be able to connect
Returns : the new pad that was created.


gst_element_request_pad_by_name ()

GstPad*     gst_element_request_pad_by_name (GstElement *element,
                                             const gchar *name);

Request a new pad from the element. The name argument will be used to decide what padtemplate to use. This function is typically used for elements with a padtemplate with presence GST_PAD_REQUEST.

element : element to request a new pad from
name : the name of the padtemplate to use.
Returns : the new pad that was created.


gst_element_connect ()

gboolean    gst_element_connect             (GstElement *src,
                                             const gchar *srcpadname,
                                             GstElement *dest,
                                             const gchar *destpadname);

Connect 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 connection fails.

Return: TRUE if the pads could be connected.

src : element containing source pad
srcpadname : name of pad in source element
dest : element containing destination pad
destpadname : name of pad in destination element
Returns : 


gst_element_connect_filtered ()

gboolean    gst_element_connect_filtered    (GstElement *src,
                                             const gchar *srcpadname,
                                             GstElement *dest,
                                             const gchar *destpadname,
                                             GstCaps *filtercaps);

Connect 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 connection fails.

Return: TRUE if the pads could be connected.

src : element containing source pad
srcpadname : name of pad in source element
dest : element containing destination pad
destpadname : name of pad in destination element
filtercaps : the caps to use as a filter
Returns : 


gst_element_disconnect ()

void        gst_element_disconnect          (GstElement *src,
                                             const gchar *srcpadname,
                                             GstElement *dest,
                                             const gchar *destpadname);

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

src : element containing source pad
srcpadname : name of pad in source element
dest : element containing destination pad
destpadname : name of pad in destination element


gst_element_set_state ()

gint        gst_element_set_state           (GstElement *element,
                                             GstElementState state);

Sets the state of the element. This function will only set the elements pending state.

element : element to change state of
state : new element state
Returns : whether or not the state was successfully set.


gst_element_get_state ()

GstElementState gst_element_get_state       (GstElement *element);

Gets the state of the element.

element : element to get state of
Returns : The element state


gst_element_wait_state_change ()

void        gst_element_wait_state_change   (GstElement *element);

Wait and block until the element changed its state.

element : element wait for


gst_element_statename ()

const gchar* gst_element_statename          (GstElementState state);

Gets a string representing the given state.

state : The state to get the name of
Returns : a string with the statename.


gst_element_info ()

void        gst_element_info                (GstElement *element,
                                             const gchar *info,
                                             ...);

This function is used internally by elements to signal an info condition. It results in the "info" signal.

element : Element with the info
info : String describing the info
... : arguments for the string.


gst_element_error ()

void        gst_element_error               (GstElement *element,
                                             const gchar *error,
                                             ...);

This function is used internally by elements to signal an error condition. It results in the "error" signal.

element : Element with the error
error : A printf-like string describing the error
... : optional arguments for the string


gst_element_get_factory ()

GstElementFactory* gst_element_get_factory  (GstElement *element);

Retrieves the factory that was used to create this element

element : element to request the factory
Returns : the factory used for creating this element


gst_element_set_eos ()

void        gst_element_set_eos             (GstElement *element);

Perform the actions needed to bring the element in the EOS state.

element : element to set to the EOS state


gst_element_install_std_props ()

void        gst_element_install_std_props   (GstElementClass *klass,
                                             const char *first_name,
                                             ...);

Add a list of standardized properties with types to the klass. the id is for the property switch in your get_prop method, and the flags determine readability / writeability.

klass : the class to add the properties to
first_name : the first in a NULL terminated 'name', 'id', 'flags' triplet list.
... : the triplet list


gst_element_send_event ()

void        gst_element_send_event          (GstElement *element,
                                             GstEvent *event);

This function is deprecated and doesn't work anymore.

element : Element generating the event
event : the event to send


gst_element_interrupt ()

gboolean    gst_element_interrupt           (GstElement *element);

Request the scheduler of this element to interrupt the execution of this element and scheduler another one.

element : Element to interrupt
Returns : a boolean indicating that the child should exit its chain/loop/get function ASAP, depending on the scheduler implementation.


gst_element_yield ()

void        gst_element_yield               (GstElement *element);

Request a yield operation for the child. The scheduler will typically give control to another element.

element : Element to yield

Signals

The "eos" signal

void        user_function                  (GstElement *gstelement,
                                            gpointer user_data);

gstelement :the object which received the signal.
user_data :user data set when the signal handler was connected.


The "error" signal

void        user_function                  (GstElement *gstelement,
                                            GObject *arg1,
                                            gchar *arg2,
                                            gpointer user_data);

Is trigered whenever an error occured

gstelement :the object which received the signal.
arg1 :the error message
arg2 : 
user_data :user data set when the signal handler was connected.


The "new-pad" signal

void        user_function                  (GstElement *gstelement,
                                            gpointer arg1,
                                            gpointer user_data);

Is trigered whenever a new pad is added to an element

gstelement :the object which received the signal.
arg1 :the new pad that was added
user_data :user data set when the signal handler was connected.


The "pad-removed" signal

void        user_function                  (GstElement *gstelement,
                                            gpointer arg1,
                                            gpointer user_data);

gstelement :the object which received the signal.
arg1 :The pad that was removed.
user_data :user data set when the signal handler was connected.


The "state-change" signal

void        user_function                  (GstElement *gstelement,
                                            gint arg1,
                                            gint arg2,
                                            gpointer user_data);

Is trigered whenever the state of an element changes

gstelement :the object which received the signal.
arg1 :the new state of the object
arg2 : 
user_data :user data set when the signal handler was connected.

See Also

GstElementFactory