GstElement

Name

GstElement -- Base class for all pipeline elements

Synopsis


#include <gst/gst.h>


enum        GstElementState;
enum        GstElementStateReturn;
#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_PLAYING
#define     GST_STATE_PLAYING_TO_PAUSED
#define     GST_STATE_PAUSED_TO_PLAYING
#define     GST_STATE_PLAYING_TO_READY
#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_PARENT              (obj)
#define     GST_ELEMENT_NAME                (obj)
struct      GstElement;
struct      GstElementDetails;
struct      GstElementFactory;
void        (*GstElementLoopFunction)       (GstElement *element);
GstElement* gst_element_new                 (void);
#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);
void        gst_element_set_manager         (GstElement *element,
                                             GstElement *manager);
GstElement* gst_element_get_manager         (GstElement *element);
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);
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);
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_load_thyself        (xmlNodePtr self,
                                             GstObject *parent);
GstElementFactory* gst_elementfactory_new   (const gchar *name,
                                             GtkType type,
                                             GstElementDetails *details);
void        gst_elementfactory_destroy      (GstElementFactory *elementfactory);
void        gst_elementfactory_add_padtemplate
                                            (GstElementFactory *elementfactory,
                                             GstPadTemplate *templ);
GstElementFactory* gst_elementfactory_find  (const gchar *name);
GList*      gst_elementfactory_get_list     (void);
gboolean    gst_elementfactory_can_src_caps (GstElementFactory *factory,
                                             GstCaps *caps);
gboolean    gst_elementfactory_can_sink_caps
                                            (GstElementFactory *factory,
                                             GstCaps *caps);
gboolean    gst_elementfactory_can_src_caps_list
                                            (GstElementFactory *factory,
                                             GList *caps);
gboolean    gst_elementfactory_can_sink_caps_list
                                            (GstElementFactory *factory,
                                             GList *caps);
GstElement* gst_elementfactory_create       (GstElementFactory *factory,
                                             const gchar *name);
GstElement* gst_elementfactory_make         (const gchar *factoryname,
                                             const gchar *name);
xmlNodePtr  gst_elementfactory_save_thyself (GstElementFactory *factory,
                                             xmlNodePtr parent);
GstElementFactory* gst_elementfactory_load_thyself
                                            (xmlNodePtr parent);

Object Hierarchy


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

Signal Prototypes


"state-change"
            void        user_function      (GstElement *gstelement,
                                            gint arg1,
                                            gpointer user_data);
"new-pad"   void        user_function      (GstElement *gstelement,
                                            GstPad *arg1,
                                            gpointer user_data);
"new-ghost-pad"
            void        user_function      (GstElement *gstelement,
                                            GstPad *arg1,
                                            gpointer user_data);
"error"     void        user_function      (GstElement *gstelement,
                                            GtkString 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_NONE_PENDING	= 0,
  GST_STATE_NULL		= (1 << 0),
  GST_STATE_READY		= (1 << 1),
  GST_STATE_PLAYING		= (1 << 2),
  GST_STATE_PAUSED		= (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_NONE_PENDINGThe element is in the desired state.
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_PLAYINGmeans there really is data flowing through the graph.
GST_STATE_PAUSEDmeans there really is data flowing temporary stops the data flow.


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_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_PLAYING

#define GST_STATE_READY_TO_PLAYING	((GST_STATE_READY<<8) | GST_STATE_PLAYING)

The Element is going from the READY state to the PLAYING 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_PLAYING_TO_READY

#define GST_STATE_PLAYING_TO_READY	((GST_STATE_PLAYING<<8) | GST_STATE_READY)

The Element is going from the PLAYING state to the READY 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,

  /* 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 is in EOS */
  GST_ELEMENT_EOS,

  /* use some padding for future expansion */
  GST_ELEMENT_FLAG_LAST		= GST_OBJECT_FLAG_LAST + 8,
} 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_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


struct GstElement

struct GstElement;


struct GstElementDetails

struct GstElementDetails {
  gchar *longname;              /* long, english name */
  gchar *klass;                 /* type of element, as hierarchy */
  gchar *description;           /* insights of one form or another */
  gchar *version;               /* version of the element */
  gchar *author;                /* who wrote this thing? */
  gchar *copyright;             /* copyright details (year, etc.) */
};

This struct is used to define public information about the element. It describes the element, mostly for the benefit of editors.


struct GstElementFactory

struct GstElementFactory {
  gchar *name;			/* name of element */
  GtkType type;			/* unique GtkType of element */

  GstElementDetails *details;	/* pointer to details struct */

  GList *padtemplates;
  guint16 numpadtemplates;
};

This factory is used when registering the element, and contains the name of the element, the GtkType value for it, as well as a pointer to the GstElementDetails struct for the element.


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

GstElement* gst_element_new                 (void);

Create a new element. Should never be used, as it does no good.

Returns : new element


gst_element_destroy()

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

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

void        gst_element_set_manager         (GstElement *element,
                                             GstElement *manager);

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

element : Element to set manager of.
manager : Element to be the manager.


gst_element_get_manager ()

GstElement* gst_element_get_manager         (GstElement *element);

Returns the manager of the element.

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


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

GstElement* gst_element_load_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


gst_elementfactory_new ()

GstElementFactory* gst_elementfactory_new   (const gchar *name,
                                             GtkType type,
                                             GstElementDetails *details);

Create a new elementfactory capable of insantiating objects of the given type.

name : name of new elementfactory
type : GtkType of new element
details : GstElementDetails structure with element details
Returns : new elementfactory


gst_elementfactory_destroy ()

void        gst_elementfactory_destroy      (GstElementFactory *elementfactory);

Removes the elementfactory from the global list.

elementfactory : factory to destroy


gst_elementfactory_add_padtemplate ()

void        gst_elementfactory_add_padtemplate
                                            (GstElementFactory *elementfactory,
                                             GstPadTemplate *templ);

Add the given padtemplate to this elementfactory.

elementfactory : factory to add the src id to
templ : the padtemplate to add


gst_elementfactory_find ()

GstElementFactory* gst_elementfactory_find  (const gchar *name);

Search for an elementfactory of the given name.

name : name of factory to find
Returns : GstElementFactory if found, NULL otherwise


gst_elementfactory_get_list ()

GList*      gst_elementfactory_get_list     (void);

Get the global list of elementfactories.

Returns : GList of type GstElementFactory


gst_elementfactory_can_src_caps ()

gboolean    gst_elementfactory_can_src_caps (GstElementFactory *factory,
                                             GstCaps *caps);

Checks if the factory can src the given capability.

factory : factory to query
caps : the caps to check
Returns : true if it can sink the capability


gst_elementfactory_can_sink_caps ()

gboolean    gst_elementfactory_can_sink_caps
                                            (GstElementFactory *factory,
                                             GstCaps *caps);

Checks if the factory can sink the given capability.

factory : factory to query
caps : the caps to check
Returns : true if it can sink the capability


gst_elementfactory_can_src_caps_list ()

gboolean    gst_elementfactory_can_src_caps_list
                                            (GstElementFactory *factory,
                                             GList *caps);

Checks if the factory can source the given capability list.

factory : factory to query
caps : the caps list to check
Returns : true if it can src the capabilities


gst_elementfactory_can_sink_caps_list ()

gboolean    gst_elementfactory_can_sink_caps_list
                                            (GstElementFactory *factory,
                                             GList *caps);

Checks if the factory can sink the given capability list.

factory : factory to query
caps : the caps list to check
Returns : true if it can sink the capabilities


gst_elementfactory_create ()

GstElement* gst_elementfactory_create       (GstElementFactory *factory,
                                             const gchar *name);

Create a new element of the type defined by the given elementfactory. It wll be given the name supplied, since all elements require a name as their first argument.

factory : factory to instantiate
name : name of new element
Returns : new GstElement


gst_elementfactory_make ()

GstElement* gst_elementfactory_make         (const gchar *factoryname,
                                             const gchar *name);

Create a new element of the type defined by the given elementfactory. It wll be given the name supplied, since all elements require a name as their first argument.

factoryname : a named factory to instantiate
name : name of new element
Returns : new GstElement


gst_elementfactory_save_thyself ()

xmlNodePtr  gst_elementfactory_save_thyself (GstElementFactory *factory,
                                             xmlNodePtr parent);

Saves the factory into an XML tree.

factory : factory to save
parent : the parent xmlNodePtr
Returns : the new xmlNodePtr


gst_elementfactory_load_thyself ()

GstElementFactory* gst_elementfactory_load_thyself
                                            (xmlNodePtr parent);

Creates a new factory from an xmlNodePtr.

parent : the parent xmlNodePtr
Returns : the new factory

Signals

The "state-change" signal

void        user_function                  (GstElement *gstelement,
                                            gint arg1,
                                            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
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 "new-ghost-pad" signal

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

Is trigered whenever a new ghost pad is added to an element

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


The "error" signal

void        user_function                  (GstElement *gstelement,
                                            GtkString 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.