gst/gstelement.h

   1 /* GStreamer
   2  * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
   3  *               2000,2004 Wim Taymans <wim@fluendo.com>
   4  *
   5  * gstelement.h: Header for GstElement
   6  *
   7  * This library is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU Library General Public
   9  * License as published by the Free Software Foundation; either
  10  * version 2 of the License, or (at your option) any later version.
  11  *
  12  * This library is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15  * Library General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Library General Public
  18  * License along with this library; if not, write to the
  19  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  20  * Boston, MA 02111-1307, USA.
  21  */
  22
  23
  24 #ifndef __GST_ELEMENT_H__
  25 #define __GST_ELEMENT_H__
  26
  27 #include <gst/gstconfig.h>
  28 #include <gst/gsttypes.h>
  29 #include <gst/gstobject.h>
  30 #include <gst/gstpad.h>
  31 #include <gst/gstclock.h>
  32 #include <gst/gstelementfactory.h>
  33 #include <gst/gstplugin.h>
  34 #include <gst/gstpluginfeature.h>
  35 #include <gst/gstindex.h>
  36 #include <gst/gstiterator.h>
  37 #include <gst/gstmessage.h>
  38 #include <gst/gsttag.h>
  39
  40 G_BEGIN_DECLS
  41
  42 GST_EXPORT GType _gst_element_type;
  43
  44 #define GST_TYPE_ELEMENT                (_gst_element_type)
  45 #define GST_IS_ELEMENT(obj)             (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GST_TYPE_ELEMENT))
  46 #define GST_IS_ELEMENT_CLASS(klass)     (G_TYPE_CHECK_CLASS_TYPE ((klass), GST_TYPE_ELEMENT))
  47 #define GST_ELEMENT_GET_CLASS(obj)      (G_TYPE_INSTANCE_GET_CLASS ((obj), GST_TYPE_ELEMENT, GstElementClass))
  48 #define GST_ELEMENT(obj)                (G_TYPE_CHECK_INSTANCE_CAST ((obj), GST_TYPE_ELEMENT, GstElement))
  49 #define GST_ELEMENT_CLASS(klass)        (G_TYPE_CHECK_CLASS_CAST ((klass), GST_TYPE_ELEMENT, GstElementClass))
  50 #define GST_ELEMENT_CAST(obj)           ((GstElement*)(obj))
  51
  52 #define GST_NUM_STATES 4
  53 /* NOTE: this probably should be done with an #ifdef to decide
  54  * whether to safe-cast or to just do the non-checking cast.
  55  */
  56 #define GST_STATE(obj)                  (GST_ELEMENT(obj)->current_state)
  57 #define GST_STATE_PENDING(obj)          (GST_ELEMENT(obj)->pending_state)
  58 #define GST_STATE_ERROR(obj)            (GST_ELEMENT(obj)->state_error)
  59
  60 /* Note: using 8 bit shift mostly "just because", it leaves us enough room to grow <g> */
  61 #define GST_STATE_TRANSITION(obj)       ((GST_STATE(obj)<<8) | GST_STATE_PENDING(obj))
  62 #define GST_STATE_NULL_TO_READY         ((GST_STATE_NULL<<8) | GST_STATE_READY)
  63 #define GST_STATE_READY_TO_PAUSED       ((GST_STATE_READY<<8) | GST_STATE_PAUSED)
  64 #define GST_STATE_PAUSED_TO_PLAYING     ((GST_STATE_PAUSED<<8) | GST_STATE_PLAYING)
  65 #define GST_STATE_PLAYING_TO_PAUSED     ((GST_STATE_PLAYING<<8) | GST_STATE_PAUSED)
  66 #define GST_STATE_PAUSED_TO_READY       ((GST_STATE_PAUSED<<8) | GST_STATE_READY)
  67 #define GST_STATE_READY_TO_NULL         ((GST_STATE_READY<<8) | GST_STATE_NULL)
  68
  69 /* convenience functions */
  70 #ifdef G_HAVE_ISO_VARARGS
  71 #define GST_ELEMENT_QUERY_TYPE_FUNCTION(functionname, ...) \
  72         GST_QUERY_TYPE_FUNCTION (GstElement*, functionname, __VA_ARGS__);
  73 #define GST_ELEMENT_FORMATS_FUNCTION(functionname, ...)    \
  74         GST_FORMATS_FUNCTION (GstElement*, functionname, __VA_ARGS__);
  75 #define GST_ELEMENT_EVENT_MASK_FUNCTION(functionname, ...) \
  76         GST_EVENT_MASK_FUNCTION (GstElement*, functionname, __VA_ARGS__);
  77 #elif defined(G_HAVE_GNUC_VARARGS)
  78 #define GST_ELEMENT_QUERY_TYPE_FUNCTION(functionname, a...) \
  79         GST_QUERY_TYPE_FUNCTION (GstElement*, functionname, a);
  80 #define GST_ELEMENT_FORMATS_FUNCTION(functionname, a...)    \
  81         GST_FORMATS_FUNCTION (GstElement*, functionname, a);
  82 #define GST_ELEMENT_EVENT_MASK_FUNCTION(functionname, a...) \
  83         GST_EVENT_MASK_FUNCTION (GstElement*, functionname, a);
  84 #endif
  85
  86 typedef enum
  87 {
  88   /* private flags that can be used by the scheduler */
  89   GST_ELEMENT_SCHEDULER_PRIVATE1,
  90   GST_ELEMENT_SCHEDULER_PRIVATE2,
  91
  92   /* ignore state changes from parent */
  93   GST_ELEMENT_LOCKED_STATE,
  94
  95   /* the element is a sink */
  96   GST_ELEMENT_IS_SINK,
  97
  98   /* use some padding for future expansion */
  99   GST_ELEMENT_FLAG_LAST         = GST_OBJECT_FLAG_LAST + 16
 100 } GstElementFlags;
 101
 102 #define GST_ELEMENT_IS_LOCKED_STATE(obj)        (GST_FLAG_IS_SET(obj,GST_ELEMENT_LOCKED_STATE))
 103
 104 #define GST_ELEMENT_NAME(obj)                   (GST_OBJECT_NAME(obj))
 105 #define GST_ELEMENT_PARENT(obj)                 (GST_ELEMENT_CAST(GST_OBJECT_PARENT(obj)))
 106 #define GST_ELEMENT_MANAGER(obj)                (GST_ELEMENT_CAST(obj)->manager)
 107 #define GST_ELEMENT_BUS(obj)                    (GST_ELEMENT_CAST(obj)->bus)
 108 #define GST_ELEMENT_SCHEDULER(obj)              (GST_ELEMENT_CAST(obj)->scheduler)
 109 #define GST_ELEMENT_CLOCK(obj)                  (GST_ELEMENT_CAST(obj)->clock)
 110 #define GST_ELEMENT_PADS(obj)                   (GST_ELEMENT_CAST(obj)->pads)
 111
 112 /**
 113  * GST_ELEMENT_ERROR:
 114  * @el: the element that throws the error
 115  * @domain: like CORE, LIBRARY, RESOURCE or STREAM (see #GstError)
 116  * @code: error code defined for that domain (see #GstError)
 117  * @message: the message to display (format string and args enclosed in round brackets)
 118  * @debug: debugging information for the message (format string and args enclosed in round brackets)
 119  *
 120  * Utility function that elements can use in case they encountered a fatal
 121  * data processing error. The pipeline will throw an error signal and the
 122  * application will be requested to stop further media processing.
 123  */
 124 #define GST_ELEMENT_ERROR(el, domain, code, text, debug)                \
 125 G_STMT_START {                                                          \
 126   gchar *__txt = _gst_element_error_printf text;                        \
 127   gchar *__dbg = _gst_element_error_printf debug;                       \
 128   if (__txt)                                                            \
 129     GST_ERROR_OBJECT (el, "%s", __txt);                                 \
 130   if (__dbg)                                                            \
 131     GST_ERROR_OBJECT (el, "%s", __dbg);                                 \
 132   gst_element_message_full (GST_ELEMENT(el), GST_MESSAGE_ERROR,         \
 133     GST_ ## domain ## _ERROR, GST_ ## domain ## _ERROR_ ## code,        \
 134     __txt, __dbg, __FILE__, GST_FUNCTION, __LINE__);                    \
 135 } G_STMT_END
 136
 137 /* log a (non-fatal) warning message and post it on the bus */
 138 #define GST_ELEMENT_WARNING(el, domain, code, text, debug)              \
 139 G_STMT_START {                                                          \
 140   gchar *__txt = _gst_element_error_printf text;                        \
 141   gchar *__dbg = _gst_element_error_printf debug;                       \
 142   if (__txt)                                                            \
 143     GST_WARNING_OBJECT (el, "%s", __txt);                               \
 144   if (__dbg)                                                            \
 145     GST_WARNING_OBJECT (el, "%s", __dbg);                               \
 146   gst_element_message_full (GST_ELEMENT(el), GST_MESSAGE_WARNING,       \
 147     GST_ ## domain ## _ERROR, GST_ ## domain ## _ERROR_ ## code,        \
 148   __txt, __dbg, __FILE__, GST_FUNCTION, __LINE__);                      \
 149 } G_STMT_END
 150
 151 /* the state change mutexes and conds */
 152 #define GST_STATE_GET_LOCK(elem)               (GST_ELEMENT_CAST(elem)->state_lock)
 153 #define GST_STATE_LOCK(elem)                   g_mutex_lock(GST_STATE_GET_LOCK(elem))
 154 #define GST_STATE_TRYLOCK(elem)                g_mutex_trylock(GST_STATE_GET_LOCK(elem))
 155 #define GST_STATE_UNLOCK(elem)                 g_mutex_unlock(GST_STATE_GET_LOCK(elem))
 156 #define GST_STATE_GET_COND(elem)               (GST_ELEMENT_CAST(elem)->state_cond)
 157 #define GST_STATE_WAIT(elem)                   g_cond_wait (GST_STATE_GET_COND (elem), GST_STATE_GET_LOCK (elem))
 158 #define GST_STATE_TIMED_WAIT(elem, timeval)    g_cond_timed_wait (GST_STATE_GET_COND (elem), GST_STATE_GET_LOCK (elem),\
 159                                                                 timeval)
 160 #define GST_STATE_SIGNAL(elem)                 g_cond_signal (GST_STATE_GET_COND (elem));
 161 #define GST_STATE_BROADCAST(elem)              g_cond_broadcast (GST_STATE_GET_COND (elem));
 162
 163 struct _GstElement
 164 {
 165   GstObject             object;
 166
 167   /*< public >*/ /* with STATE_LOCK */
 168   /* element state */
 169   GMutex               *state_lock;
 170   GCond                *state_cond;
 171   guint8                current_state;
 172   guint8                pending_state;
 173   gboolean              state_error; /* flag is set when the element has an error in the last state
 174                                         change. it is cleared when doing another state change. */
 175   /*< public >*/ /* with LOCK */
 176   /* element manager */
 177   GstPipeline          *manager;
 178   GstBus               *bus;
 179   GstScheduler         *scheduler;
 180
 181   /* allocated clock */
 182   GstClock             *clock;
 183   GstClockTimeDiff      base_time; /* NULL/READY: 0 - PAUSED: current time - PLAYING: difference to clock */
 184
 185   /* element pads, these lists can only be iterated while holding
 186    * the LOCK or checking the cookie after each LOCK. */
 187   guint16               numpads;
 188   GList                *pads;
 189   guint16               numsrcpads;
 190   GList                *srcpads;
 191   guint16               numsinkpads;
 192   GList                *sinkpads;
 193   guint32               pads_cookie;
 194
 195   /*< private >*/
 196   gpointer _gst_reserved[GST_PADDING];
 197 };
 198
 199 struct _GstElementClass
 200 {
 201   GstObjectClass         parent_class;
 202
 203   /*< public >*/
 204   /* the element details */
 205   GstElementDetails      details;
 206
 207   /* factory that the element was created from */
 208   GstElementFactory     *elementfactory;
 209
 210   /* templates for our pads */
 211   GList                 *padtemplates;
 212   gint                   numpadtemplates;
 213   guint32                pad_templ_cookie;
 214
 215   /* signal callbacks */
 216   void (*state_change)  (GstElement *element, GstElementState old, GstElementState state);
 217   void (*new_pad)       (GstElement *element, GstPad *pad);
 218   void (*pad_removed)   (GstElement *element, GstPad *pad);
 219   void (*no_more_pads)  (GstElement *element);
 220
 221   /*< protected >*/
 222   /* vtable */
 223
 224   /* request/release pads */
 225   GstPad*               (*request_new_pad)      (GstElement *element, GstPadTemplate *templ, const gchar* name);
 226   void                  (*release_pad)          (GstElement *element, GstPad *pad);
 227
 228   /* state changes */
 229   GstElementStateReturn (*get_state)            (GstElement * element, GstElementState * state,
 230                                                  GstElementState * pending, GTimeVal * timeout);
 231   GstElementStateReturn (*change_state)         (GstElement *element);
 232
 233   /* manager */
 234   void                  (*set_manager)          (GstElement * element, GstPipeline * pipeline);
 235   void                  (*set_bus)              (GstElement * element, GstBus * bus);
 236   void                  (*set_scheduler)        (GstElement *element, GstScheduler *scheduler);
 237
 238   /* set/get clocks */
 239   GstClock*             (*get_clock)            (GstElement *element);
 240   void                  (*set_clock)            (GstElement *element, GstClock *clock);
 241
 242   /* index */
 243   GstIndex*             (*get_index)            (GstElement *element);
 244   void                  (*set_index)            (GstElement *element, GstIndex *index);
 245
 246   /* query functions */
 247   gboolean              (*send_event)           (GstElement *element, GstEvent *event);
 248
 249   const GstQueryType*   (*get_query_types)      (GstElement *element);
 250   gboolean              (*query)                (GstElement *element, GstQuery *query);
 251
 252   /*< private >*/
 253   gpointer _gst_reserved[GST_PADDING];
 254 };
 255
 256 /* element class pad templates */
 257 void                    gst_element_class_add_pad_template      (GstElementClass *klass, GstPadTemplate *templ);
 258 GstPadTemplate*         gst_element_class_get_pad_template      (GstElementClass *element_class, const gchar *name);
 259 GList*                  gst_element_class_get_pad_template_list (GstElementClass *element_class);
 260 void                    gst_element_class_set_details           (GstElementClass *klass,
 261                                                                  const GstElementDetails *details);
 262
 263 /* element instance */
 264 GType                   gst_element_get_type            (void);
 265
 266 /* basic name and parentage stuff from GstObject */
 267 #define                 gst_element_get_name(elem)      gst_object_get_name(GST_OBJECT(elem))
 268 #define                 gst_element_set_name(elem,name) gst_object_set_name(GST_OBJECT(elem),name)
 269 #define                 gst_element_get_parent(elem)    gst_object_get_parent(GST_OBJECT(elem))
 270 #define                 gst_element_set_parent(elem,parent)     gst_object_set_parent(GST_OBJECT(elem),parent)
 271
 272 /* clocking */
 273 gboolean                gst_element_requires_clock      (GstElement *element);
 274 gboolean                gst_element_provides_clock      (GstElement *element);
 275 GstClock*               gst_element_get_clock           (GstElement *element);
 276 void                    gst_element_set_clock           (GstElement *element, GstClock *clock);
 277
 278 /* indexes */
 279 gboolean                gst_element_is_indexable        (GstElement *element);
 280 void                    gst_element_set_index           (GstElement *element, GstIndex *index);
 281 GstIndex*               gst_element_get_index           (GstElement *element);
 282
 283 /* manager and tasks */
 284 void                    gst_element_set_manager         (GstElement * element, GstPipeline * pipeline);
 285 GstPipeline *           gst_element_get_manager         (GstElement * element);
 286 void                    gst_element_set_bus             (GstElement * element, GstBus * bus);
 287 GstBus *                gst_element_get_bus             (GstElement * element);
 288 void                    gst_element_set_scheduler       (GstElement *element, GstScheduler *sched);
 289 GstScheduler*           gst_element_get_scheduler       (GstElement *element);
 290
 291 /* pad management */
 292 gboolean                gst_element_add_pad             (GstElement *element, GstPad *pad);
 293 gboolean                gst_element_remove_pad          (GstElement *element, GstPad *pad);
 294 GstPad *                gst_element_add_ghost_pad       (GstElement *element, GstPad *pad, const gchar *name);
 295 void                    gst_element_no_more_pads        (GstElement *element);
 296
 297 GstPad*                 gst_element_get_pad             (GstElement *element, const gchar *name);
 298 GstPad*                 gst_element_get_static_pad      (GstElement *element, const gchar *name);
 299 GstPad*                 gst_element_get_request_pad     (GstElement *element, const gchar *name);
 300 void                    gst_element_release_request_pad (GstElement *element, GstPad *pad);
 301
 302 GstIterator *           gst_element_iterate_pads        (GstElement * element);
 303
 304 /* event/query/format stuff */
 305 gboolean                gst_element_send_event          (GstElement *element, GstEvent *event);
 306 gboolean                gst_element_seek                (GstElement *element, GstSeekType seek_type,
 307                                                          guint64 offset);
 308 G_CONST_RETURN GstQueryType*
 309                         gst_element_get_query_types     (GstElement *element);
 310 gboolean                gst_element_query               (GstElement *element, GstQuery *query);
 311
 312 /* messages */
 313 gboolean                gst_element_post_message        (GstElement * element, GstMessage * message);
 314
 315 /* error handling */
 316 gchar *                 _gst_element_error_printf       (const gchar *format, ...);
 317 void                    gst_element_message_full        (GstElement * element, GstMessageType type,
 318                                                          GQuark domain, gint code, gchar * text,
 319                                                          gchar * debug, const gchar * file,
 320                                                          const gchar * function, gint line);
 321
 322 /* state management */
 323 gboolean                gst_element_is_locked_state     (GstElement *element);
 324 gboolean                gst_element_set_locked_state    (GstElement *element, gboolean locked_state);
 325 gboolean                gst_element_sync_state_with_parent (GstElement *element);
 326
 327 GstElementStateReturn   gst_element_get_state           (GstElement * element,
 328                                                          GstElementState * state,
 329                                                          GstElementState * pending,
 330                                                          GTimeVal * timeout);
 331 GstElementStateReturn   gst_element_set_state           (GstElement *element, GstElementState state);
 332
 333 void                    gst_element_abort_state         (GstElement * element);
 334 void                    gst_element_commit_state        (GstElement * element);
 335 void                    gst_element_lost_state          (GstElement * element);
 336
 337 /* factory management */
 338 GstElementFactory*      gst_element_get_factory         (GstElement *element);
 339
 340 G_END_DECLS
 341
 342 #endif /* __GST_ELEMENT_H__ */