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