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)
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_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);
void        gst_element_add_ghost_pad       (GstElement *element,
                                             GstPad *pad);
void        gst_element_remove_ghost_pad    (GstElement *element,
                                             GstPad *pad);
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);
xmlNodePtr  gst_element_save_thyself        (GstElement *element,
                                             xmlNodePtr parent);
GstElement* gst_element_load_thyself        (xmlNodePtr parent,
                                             GHashTable *elements);
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 *temp);
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

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	= -1,
  GST_STATE_NULL		= 0,
  GST_STATE_READY		= 1,
  GST_STATE_PLAYING		= 2,
  GST_STATE_PAUSED		= 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)<<4) | 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<<4) | 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<<4) | 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<<4) | 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<<4) | 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<<4) | 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<<4) | 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,

  /* 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


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

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

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

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


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

xmlNodePtr  gst_element_save_thyself        (GstElement *element,
                                             xmlNodePtr parent);

Saves the element as part of the given XML structure

element : GstElement to save
parent : the xml parent node
Returns : the new xml node


gst_element_load_thyself ()

GstElement* gst_element_load_thyself        (xmlNodePtr parent,
                                             GHashTable *elements);

Load the element from the XML description

parent : the xml parent node
elements : a hashtable to store the elements in. This is used to resolve inter element dependecies during the loading.
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 *temp);

Add the given padtemplate to this elementfactory.

elementfactory : factory to add the src id to
temp : 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