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_COTHREAD_STOPPING(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);
void        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);
void        gst_element_connect             (GstElement *src,
                                             const gchar *srcpadname,
                                             GstElement *dest,
                                             const gchar *destpadname);
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_error               (GstElement *element,
                                             const gchar *error);
GstElementFactory* gst_element_get_factory  (GstElement *element);
void        gst_element_signal_eos          (GstElement *element);
GstElement* gst_element_restore_thyself     (xmlNodePtr self,
                                             GstObject *parent);

Object Hierarchy


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

Signal Prototypes


"state-change"
            void        user_function      (GstElement *gstelement,
                                            gint arg1,
                                            gint arg2,
                                            gpointer user_data);
"new-pad"   void        user_function      (GstElement *gstelement,
                                            GstPad *arg1,
                                            gpointer user_data);
"pad-removed"
            void        user_function      (GstElement *gstelement,
                                            GstPad *arg1,
                                            gpointer user_data);
"error"     void        user_function      (GstElement *gstelement,
                                            gchar *arg1,
                                            gpointer user_data);
"eos"       void        user_function      (GstElement *gstelement,
                                            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,

  /***** !!!!! need to have a flag that says that an element must
    *not* be an entry into a scheduling chain !!!!! *****/
  /* this element for some reason doesn't obey COTHREAD_STOPPING, or
     has some other reason why it can't be the entry */
  GST_ELEMENT_NO_ENTRY,

  /* there is a new loopfunction ready for placement */
  GST_ELEMENT_NEW_LOOPFUNC,
  /* the cothread holding this element needs to be stopped */
  GST_ELEMENT_COTHREAD_STOPPING,
  /* the element has to be scheduled as a cothread for any sanity */
  GST_ELEMENT_USE_COTHREAD,

  /* 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_COTHREAD_STOPPING()

#define GST_ELEMENT_IS_COTHREAD_STOPPING(obj)	(GST_FLAG_IS_SET(obj,GST_ELEMENT_COTHREAD_STOPPING))

Queries whether the cothread holding this element needs to be stopped.

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 ()

void        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


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 ()

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

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_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_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 : String describing the error


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_signal_eos ()

void        gst_element_signal_eos          (GstElement *element);

Throws the eos signal to indicate that the end of the stream is reached.

element : element to trigger the eos signal of


gst_element_restore_thyself ()

GstElement* gst_element_restore_thyself     (xmlNodePtr self,
                                             GstObject *parent);

Load the element from the XML description

self : the xml node
parent : the parent of this object when it's loaded
Returns : the new element

Signals

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.


The "new-pad" signal

void        user_function                  (GstElement *gstelement,
                                            GstPad *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,
                                            GstPad *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 "error" signal

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

Is trigered whenever an error occured

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


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.

See Also

GstElementFactory