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 /* gstelement.h and gstelementfactory.h include eachother */
  28 typedef struct _GstElement GstElement;
  29 typedef struct _GstElementClass GstElementClass;
  30
  31 /* gstmessage.h needs State */
  32 typedef enum {
  33   GST_STATE_VOID_PENDING        = 0, /* used for GstElement->pending_state when
  34                                         there is no pending state */
  35   GST_STATE_NULL                = 1,
  36   GST_STATE_READY               = 2,
  37   GST_STATE_PAUSED              = 3,
  38   GST_STATE_PLAYING             = 4
  39 } GstState;
  40
  41
  42 #include <gst/gstconfig.h>
  43 #include <gst/gstobject.h>
  44 #include <gst/gstpad.h>
  45 #include <gst/gstbus.h>
  46 #include <gst/gstclock.h>
  47 #include <gst/gstelementfactory.h>
  48 #include <gst/gstplugin.h>
  49 #include <gst/gstpluginfeature.h>
  50 #include <gst/gstindex.h>
  51 #include <gst/gstindexfactory.h>
  52 #include <gst/gstiterator.h>
  53 #include <gst/gstmessage.h>
  54 #include <gst/gsttaglist.h>
  55
  56 G_BEGIN_DECLS
  57
  58 GST_EXPORT GType _gst_element_type;
  59
  60 #define GST_TYPE_ELEMENT                (_gst_element_type)
  61 #define GST_IS_ELEMENT(obj)             (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GST_TYPE_ELEMENT))
  62 #define GST_IS_ELEMENT_CLASS(klass)     (G_TYPE_CHECK_CLASS_TYPE ((klass), GST_TYPE_ELEMENT))
  63 #define GST_ELEMENT_GET_CLASS(obj)      (G_TYPE_INSTANCE_GET_CLASS ((obj), GST_TYPE_ELEMENT, GstElementClass))
  64 #define GST_ELEMENT(obj)                (G_TYPE_CHECK_INSTANCE_CAST ((obj), GST_TYPE_ELEMENT, GstElement))
  65 #define GST_ELEMENT_CLASS(klass)        (G_TYPE_CHECK_CLASS_CAST ((klass), GST_TYPE_ELEMENT, GstElementClass))
  66 #define GST_ELEMENT_CAST(obj)           ((GstElement*)(obj))
  67
  68 /**
  69  * GstStateChangeReturn:
  70  * @GST_STATE_CHANGE_FAILURE   : the state change failed
  71  * @GST_STATE_CHANGE_SUCCESS   : the state change succeeded
  72  * @GST_STATE_CHANGE_ASYNC     : the state change will happen asynchronously
  73  * @GST_STATE_CHANGE_NO_PREROLL: the state change cannot be prerolled
  74  */
  75 typedef enum {
  76   GST_STATE_CHANGE_FAILURE             = 0,
  77   GST_STATE_CHANGE_SUCCESS             = 1,
  78   GST_STATE_CHANGE_ASYNC               = 2,
  79   GST_STATE_CHANGE_NO_PREROLL          = 3
  80 } GstStateChangeReturn;
  81
  82 /* NOTE: this probably should be done with an #ifdef to decide
  83  * whether to safe-cast or to just do the non-checking cast.
  84  */
  85
  86 /**
  87  * GST_STATE:
  88  * @obj: Element to return state for.
  89  *
  90  * This macro returns the current state of the element.
  91  */
  92 #define GST_STATE(obj)                  (GST_ELEMENT(obj)->current_state)
  93
  94 /**
  95  * GST_STATE_PENDING:
  96  * @obj: Element to return the pending state for.
  97  *
  98  * This macro returns the currently pending state of the element.
  99  */
 100 #define GST_STATE_PENDING(obj)          (GST_ELEMENT(obj)->pending_state)
 101 #define GST_STATE_FINAL(obj)            (GST_ELEMENT(obj)->final_state)
 102 #define GST_STATE_ERROR(obj)            (GST_ELEMENT(obj)->state_error)
 103 #define GST_STATE_NO_PREROLL(obj)       (GST_ELEMENT(obj)->no_preroll)
 104
 105 #ifndef GST_DEBUG_STATE_CHANGE
 106 #define GST_STATE_CHANGE(obj) ((1<<(GST_STATE(obj)+8)) | 1<<GST_STATE_PENDING(obj))
 107 #else
 108 inline GstStateChange
 109 _gst_element_get_state_change (GstElement *e)
 110 {
 111   if (e->state < GST_STATE_NULL || e->state > GST_STATE_PLAYING)
 112     g_assert_not_reached ();
 113   if (e->pending_state < GST_STATE_NULL || e->pending_state > GST_STATE_PLAYING)
 114     g_assert_not_reached ();
 115   if (e->state - e->pending_state != 1 && e->pending_state - e->state != 1)
 116     g_assert_not_reached ();
 117   return (1<<(GST_STATE(obj)+8)) | 1<<GST_STATE_PENDING(obj);
 118 }
 119 #define GST_STATE_CHANGE(obj) _gst_element_get_state_change(obj)
 120 #endif
 121
 122 /* FIXME: How to deal with lost_state ? */
 123 /**
 124  * GstStateChange:
 125  * @GST_STATE_CHANGE_NULL_TO_READY    : state change from NULL to READY
 126  * @GST_STATE_CHANGE_READY_TO_PAUSED  : state change from READY to PAUSED
 127  * @GST_STATE_CHANGE_PAUSED_TO_PLAYING: state change from PAUSED to PLAYING
 128  * @GST_STATE_CHANGE_PLAYING_TO_PAUSED: state change from PLAYING to PAUSED
 129  * @GST_STATE_CHANGE_PAUSED_TO_READY  : state change from PAUSED to READY
 130  * @GST_STATE_CHANGE_READY_TO_NULL    : state change from READY to NULL
 131  */
 132 typedef enum /*< flags=0 >*/
 133 {
 134   GST_STATE_CHANGE_NULL_TO_READY        = 1<<(GST_STATE_NULL+8) | 1<<GST_STATE_READY,
 135   GST_STATE_CHANGE_READY_TO_PAUSED      = 1<<(GST_STATE_READY+8) | 1<<GST_STATE_PAUSED,
 136   GST_STATE_CHANGE_PAUSED_TO_PLAYING    = 1<<(GST_STATE_PAUSED+8) | 1<<GST_STATE_PLAYING,
 137   GST_STATE_CHANGE_PLAYING_TO_PAUSED    = 1<<(GST_STATE_PLAYING+8) | 1<<GST_STATE_PAUSED,
 138   GST_STATE_CHANGE_PAUSED_TO_READY      = 1<<(GST_STATE_PAUSED+8) | 1<<GST_STATE_READY,
 139   GST_STATE_CHANGE_READY_TO_NULL        = 1<<(GST_STATE_READY+8) | 1<<GST_STATE_NULL
 140 } GstStateChange;
 141
 142 /**
 143  * GstElementFlags:
 144  * @GST_ELEMENT_LOCKED_STATE: ignore state changes from parent
 145  * @GST_ELEMENT_IS_SINK: the element is a sink
 146  * @GST_ELEMENT_UNPARENTING: Child is being removed from the parent bin.
 147  *  gst_bin_remove() on a child already being removed immediately returns FALSE
 148  * @GST_ELEMENT_FLAG_LAST: offset to define more flags
 149  *
 150  * The standard flags that an element may have.
 151  */
 152 typedef enum
 153 {
 154   GST_ELEMENT_LOCKED_STATE      = GST_OBJECT_FLAG_LAST,
 155   GST_ELEMENT_IS_SINK,
 156   GST_ELEMENT_UNPARENTING,
 157   GST_ELEMENT_FLAG_LAST         = GST_OBJECT_FLAG_LAST + 16
 158 } GstElementFlags;
 159
 160 /**
 161  * GST_ELEMENT_IS_LOCKED_STATE:
 162  * @obj: A #GstElement to query
 163  *
 164  * Check if the element is in the loacked state and therefore will ignore state
 165  * changes from its parent object.
 166  */
 167 #define GST_ELEMENT_IS_LOCKED_STATE(obj)        (GST_FLAG_IS_SET(obj,GST_ELEMENT_LOCKED_STATE))
 168
 169 /**
 170  * GST_ELEMENT_NAME:
 171  * @obj: A #GstElement to query
 172  *
 173  * Gets the name of this element. Use only in core as this is not
 174  * ABI-compatible. Others use gst_element_get_name()
 175  */
 176 #define GST_ELEMENT_NAME(obj)                   (GST_OBJECT_NAME(obj))
 177
 178 /**
 179  * GST_ELEMENT_PARENT:
 180  * @obj: A #GstElement to query
 181  *
 182  * Get the parent object of this element.
 183  */
 184 #define GST_ELEMENT_PARENT(obj)                 (GST_ELEMENT_CAST(GST_OBJECT_PARENT(obj)))
 185
 186 /**
 187  * GST_ELEMENT_BUS:
 188  * @obj: A #GstElement to query
 189  *
 190  * Get the message bus of this element.
 191  */
 192 #define GST_ELEMENT_BUS(obj)                    (GST_ELEMENT_CAST(obj)->bus)
 193
 194 /**
 195  * GST_ELEMENT_CLOCK:
 196  * @obj: A #GstElement to query
 197  *
 198  * Get the clock of this element
 199  */
 200 #define GST_ELEMENT_CLOCK(obj)                  (GST_ELEMENT_CAST(obj)->clock)
 201
 202 /**
 203  * GST_ELEMENT_PADS:
 204  * @obj: A #GstElement to query
 205  *
 206  * Get the pads of this elements.
 207  */
 208 #define GST_ELEMENT_PADS(obj)                   (GST_ELEMENT_CAST(obj)->pads)
 209
 210 /**
 211  * GST_ELEMENT_ERROR:
 212  * @el:     the element that throws the error
 213  * @domain: like CORE, LIBRARY, RESOURCE or STREAM (see #GstError)
 214  * @code:   error code defined for that domain (see #GstError)
 215  * @text:   the message to display (format string and args enclosed in
 216             parentheses)
 217  * @debug:  debugging information for the message (format string and args
 218             enclosed in parentheses)
 219  *
 220  * Utility function that elements can use in case they encountered a fatal
 221  * data processing error. The pipeline will throw an error signal and the
 222  * application will be requested to stop further media processing.
 223  */
 224 #define GST_ELEMENT_ERROR(el, domain, code, text, debug)                \
 225 G_STMT_START {                                                          \
 226   gchar *__txt = _gst_element_error_printf text;                        \
 227   gchar *__dbg = _gst_element_error_printf debug;                       \
 228   if (__txt)                                                            \
 229     GST_WARNING_OBJECT (el, "error: %s", __txt);                        \
 230   if (__dbg)                                                            \
 231     GST_WARNING_OBJECT (el, "error: %s", __dbg);                        \
 232   gst_element_message_full (GST_ELEMENT(el), GST_MESSAGE_ERROR,         \
 233     GST_ ## domain ## _ERROR, GST_ ## domain ## _ERROR_ ## code,        \
 234     __txt, __dbg, __FILE__, GST_FUNCTION, __LINE__);                    \
 235 } G_STMT_END
 236
 237 /**
 238  * GST_ELEMENT_WARNING:
 239  * @el:     the element that throws the error
 240  * @domain: like CORE, LIBRARY, RESOURCE or STREAM (see #GstError)
 241  * @code:   error code defined for that domain (see #GstError)
 242  * @text:   the message to display (format string and args enclosed in
 243             parentheses)
 244  * @debug:  debugging information for the message (format string and args
 245             enclosed in parentheses)
 246  *
 247  * Utility function that elements can use in case they encountered a non-fatal
 248  * data processing problem. The pipeline will throw a warning signal and the
 249  * application will be informed.
 250  */
 251 #define GST_ELEMENT_WARNING(el, domain, code, text, debug)              \
 252 G_STMT_START {                                                          \
 253   gchar *__txt = _gst_element_error_printf text;                        \
 254   gchar *__dbg = _gst_element_error_printf debug;                       \
 255   if (__txt)                                                            \
 256     GST_WARNING_OBJECT (el, "warning: %s", __txt);                      \
 257   if (__dbg)                                                            \
 258     GST_WARNING_OBJECT (el, "warning: %s", __dbg);                      \
 259   gst_element_message_full (GST_ELEMENT(el), GST_MESSAGE_WARNING,       \
 260     GST_ ## domain ## _ERROR, GST_ ## domain ## _ERROR_ ## code,        \
 261   __txt, __dbg, __FILE__, GST_FUNCTION, __LINE__);                      \
 262 } G_STMT_END
 263
 264 /* the state change mutexes and conds */
 265 #define GST_STATE_GET_LOCK(elem)               (GST_ELEMENT_CAST(elem)->state_lock)
 266 #define GST_STATE_LOCK(elem)                   g_mutex_lock(GST_STATE_GET_LOCK(elem))
 267 #define GST_STATE_TRYLOCK(elem)                g_mutex_trylock(GST_STATE_GET_LOCK(elem))
 268 #define GST_STATE_UNLOCK(elem)                 g_mutex_unlock(GST_STATE_GET_LOCK(elem))
 269 #define GST_STATE_GET_COND(elem)               (GST_ELEMENT_CAST(elem)->state_cond)
 270 #define GST_STATE_WAIT(elem)                   g_cond_wait (GST_STATE_GET_COND (elem), GST_STATE_GET_LOCK (elem))
 271 #define GST_STATE_TIMED_WAIT(elem, timeval)    g_cond_timed_wait (GST_STATE_GET_COND (elem), GST_STATE_GET_LOCK (elem),\
 272                                                                 timeval)
 273 #define GST_STATE_SIGNAL(elem)                 g_cond_signal (GST_STATE_GET_COND (elem));
 274 #define GST_STATE_BROADCAST(elem)              g_cond_broadcast (GST_STATE_GET_COND (elem));
 275
 276 struct _GstElement
 277 {
 278   GstObject             object;
 279
 280   /*< public >*/ /* with STATE_LOCK */
 281   /* element state */
 282   GMutex               *state_lock;
 283   GCond                *state_cond;
 284   guint8                current_state;
 285   guint8                pending_state;
 286   guint8                final_state;
 287   gboolean              state_error; /* flag is set when the element has an error in the last state
 288                                         change. it is cleared when doing another state change. */
 289   gboolean              no_preroll;  /* flag is set when the element cannot preroll */
 290   /*< public >*/ /* with LOCK */
 291   GstBus               *bus;
 292
 293   /* allocated clock */
 294   GstClock             *clock;
 295   GstClockTimeDiff      base_time; /* NULL/READY: 0 - PAUSED: current time - PLAYING: difference to clock */
 296
 297   /* element pads, these lists can only be iterated while holding
 298    * the LOCK or checking the cookie after each LOCK. */
 299   guint16               numpads;
 300   GList                *pads;
 301   guint16               numsrcpads;
 302   GList                *srcpads;
 303   guint16               numsinkpads;
 304   GList                *sinkpads;
 305   guint32               pads_cookie;
 306
 307   /*< private >*/
 308   gpointer _gst_reserved[GST_PADDING];
 309 };
 310
 311 struct _GstElementClass
 312 {
 313   GstObjectClass         parent_class;
 314
 315   /*< public >*/
 316   /* the element details */
 317   GstElementDetails      details;
 318
 319   /* factory that the element was created from */
 320   GstElementFactory     *elementfactory;
 321
 322   /* templates for our pads */
 323   GList                 *padtemplates;
 324   gint                   numpadtemplates;
 325   guint32                pad_templ_cookie;
 326
 327   /*< private >*/
 328   /* signal callbacks */
 329   void (*state_changed) (GstElement *element, GstState old, GstState state);
 330   void (*pad_added)     (GstElement *element, GstPad *pad);
 331   void (*pad_removed)   (GstElement *element, GstPad *pad);
 332   void (*no_more_pads)  (GstElement *element);
 333
 334   /*< public >*/
 335   /* virtual methods for subclasses */
 336
 337   /* request/release pads */
 338   GstPad*               (*request_new_pad)      (GstElement *element, GstPadTemplate *templ, const gchar* name);
 339   void                  (*release_pad)          (GstElement *element, GstPad *pad);
 340
 341   /* state changes */
 342   GstStateChangeReturn (*get_state)             (GstElement * element, GstState * state,
 343                                                  GstState * pending, GTimeVal * timeout);
 344   GstStateChangeReturn (*change_state)          (GstElement *element, GstStateChange transition);
 345
 346   /* bus */
 347   void                  (*set_bus)              (GstElement * element, GstBus * bus);
 348
 349   /* set/get clocks */
 350   GstClock*             (*provide_clock)        (GstElement *element);
 351   void                  (*set_clock)            (GstElement *element, GstClock *clock);
 352
 353   /* index */
 354   GstIndex*             (*get_index)            (GstElement *element);
 355   void                  (*set_index)            (GstElement *element, GstIndex *index);
 356
 357   /* query functions */
 358   gboolean              (*send_event)           (GstElement *element, GstEvent *event);
 359
 360   const GstQueryType*   (*get_query_types)      (GstElement *element);
 361   gboolean              (*query)                (GstElement *element, GstQuery *query);
 362
 363   /*< private >*/
 364   gpointer _gst_reserved[GST_PADDING];
 365 };
 366
 367 /* element class pad templates */
 368 void                    gst_element_class_add_pad_template      (GstElementClass *klass, GstPadTemplate *templ);
 369 GstPadTemplate*         gst_element_class_get_pad_template      (GstElementClass *element_class, const gchar *name);
 370 GList*                  gst_element_class_get_pad_template_list (GstElementClass *element_class);
 371 void                    gst_element_class_set_details           (GstElementClass *klass,
 372                                                                  const GstElementDetails *details);
 373
 374 /* element instance */
 375 GType                   gst_element_get_type            (void);
 376
 377 /* basic name and parentage stuff from GstObject */
 378
 379 /**
 380  * gst_element_get_name:
 381  * @elem: a #GstElement to set the name of.
 382  *
 383  * Gets the name of the element.
 384  */
 385 #define                 gst_element_get_name(elem)      gst_object_get_name(GST_OBJECT(elem))
 386
 387 /**
 388  * gst_element_set_name:
 389  * @elem: a #GstElement to set the name of.
 390  * @name: the new name
 391  *
 392  * Sets the name of the element, getting rid of the old name if there was one.
 393  */
 394 #define                 gst_element_set_name(elem,name) gst_object_set_name(GST_OBJECT(elem),name)
 395
 396 /**
 397  * gst_element_get_parent:
 398  * @elem: a #GstElement to get the parent of.
 399  *
 400  * Gets the parent of an element.
 401  */
 402 #define                 gst_element_get_parent(elem)    gst_object_get_parent(GST_OBJECT(elem))
 403
 404 /**
 405  * gst_element_set_parent:
 406  * @elem: a #GstElement to set the parent of.
 407  * @parent: the new parent #GstObject of the element.
 408  *
 409  * Sets the parent of an element.
 410  */
 411 #define                 gst_element_set_parent(elem,parent)     gst_object_set_parent(GST_OBJECT(elem),parent)
 412
 413 /* clocking */
 414 gboolean                gst_element_requires_clock      (GstElement *element);
 415 gboolean                gst_element_provides_clock      (GstElement *element);
 416 GstClock*               gst_element_provide_clock       (GstElement *element);
 417 GstClock*               gst_element_get_clock           (GstElement *element);
 418 void                    gst_element_set_clock           (GstElement *element, GstClock *clock);
 419 void                    gst_element_set_base_time       (GstElement *element, GstClockTime time);
 420 GstClockTime            gst_element_get_base_time       (GstElement *element);
 421
 422 /* indexes */
 423 gboolean                gst_element_is_indexable        (GstElement *element);
 424 void                    gst_element_set_index           (GstElement *element, GstIndex *index);
 425 GstIndex*               gst_element_get_index           (GstElement *element);
 426
 427 /* bus */
 428 void                    gst_element_set_bus             (GstElement * element, GstBus * bus);
 429 GstBus *                gst_element_get_bus             (GstElement * element);
 430
 431 /* pad management */
 432 gboolean                gst_element_add_pad             (GstElement *element, GstPad *pad);
 433 gboolean                gst_element_remove_pad          (GstElement *element, GstPad *pad);
 434 void                    gst_element_no_more_pads        (GstElement *element);
 435
 436 GstPad*                 gst_element_get_pad             (GstElement *element, const gchar *name);
 437 GstPad*                 gst_element_get_static_pad      (GstElement *element, const gchar *name);
 438 GstPad*                 gst_element_get_request_pad     (GstElement *element, const gchar *name);
 439 void                    gst_element_release_request_pad (GstElement *element, GstPad *pad);
 440
 441 GstIterator *           gst_element_iterate_pads        (GstElement * element);
 442 GstIterator *           gst_element_iterate_src_pads    (GstElement * element);
 443 GstIterator *           gst_element_iterate_sink_pads   (GstElement * element);
 444
 445 /* event/query/format stuff */
 446 gboolean                gst_element_send_event          (GstElement *element, GstEvent *event);
 447 gboolean                gst_element_seek                (GstElement *element, gdouble rate,
 448                                                          GstFormat format, GstSeekFlags flags,
 449                                                          GstSeekType cur_type, gint64 cur,
 450                                                          GstSeekType stop_type, gint64 stop);
 451 G_CONST_RETURN GstQueryType*
 452                         gst_element_get_query_types     (GstElement *element);
 453 gboolean                gst_element_query               (GstElement *element, GstQuery *query);
 454
 455 /* messages */
 456 gboolean                gst_element_post_message        (GstElement * element, GstMessage * message);
 457
 458 /* error handling */
 459 gchar *                 _gst_element_error_printf       (const gchar *format, ...);
 460 void                    gst_element_message_full        (GstElement * element, GstMessageType type,
 461                                                          GQuark domain, gint code, gchar * text,
 462                                                          gchar * debug, const gchar * file,
 463                                                          const gchar * function, gint line);
 464
 465 /* state management */
 466 gboolean                gst_element_is_locked_state     (GstElement *element);
 467 gboolean                gst_element_set_locked_state    (GstElement *element, gboolean locked_state);
 468 gboolean                gst_element_sync_state_with_parent (GstElement *element);
 469
 470 GstStateChangeReturn    gst_element_get_state           (GstElement * element,
 471                                                          GstState * state,
 472                                                          GstState * pending,
 473                                                          GTimeVal * timeout);
 474 GstStateChangeReturn    gst_element_set_state           (GstElement *element, GstState state);
 475
 476 void                    gst_element_abort_state         (GstElement * element);
 477 void                    gst_element_commit_state        (GstElement * element);
 478 void                    gst_element_lost_state          (GstElement * element);
 479
 480 /* factory management */
 481 GstElementFactory*      gst_element_get_factory         (GstElement *element);
 482
 483 G_END_DECLS
 484
 485 #endif /* __GST_ELEMENT_H__ */