gst/gstevent.h

   1 /* GStreamer
   2  * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
   3  *                    2000 Wim Taymans <wim.taymans@chello.be>
   4  *                    2005 Wim Taymans <wim@fluendo.com>
   5  *
   6  * gstevent.h: Header for GstEvent subsystem
   7  *
   8  * This library is free software; you can redistribute it and/or
   9  * modify it under the terms of the GNU Library General Public
  10  * License as published by the Free Software Foundation; either
  11  * version 2 of the License, or (at your option) any later version.
  12  *
  13  * This library is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16  * Library General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU Library General Public
  19  * License along with this library; if not, write to the
  20  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  21  * Boston, MA 02111-1307, USA.
  22  */
  23
  24
  25 #ifndef __GST_EVENT_H__
  26 #define __GST_EVENT_H__
  27
  28 #include <gst/gstminiobject.h>
  29 #include <gst/gstformat.h>
  30 #include <gst/gstobject.h>
  31 #include <gst/gstclock.h>
  32 #include <gst/gststructure.h>
  33 #include <gst/gsttag.h>
  34
  35 G_BEGIN_DECLS
  36
  37 /* bitmaks defining the direction */
  38 #define GST_EVDIR_US    (1 << 0)
  39 #define GST_EVDIR_DS    (1 << 1)
  40 #define GST_EVDIR_BOTH  GST_EVDIR_US | GST_EVDIR_DS
  41 /* mask defining event is serialized with data */
  42 #define GST_EVSER       (1 << 2)
  43 #define GST_EVSHIFT     4
  44
  45 /* when making custom event types, use this macro with the num and
  46  * the given flags */
  47 #define GST_EVENT_MAKE_TYPE(num,flags) (((num) << GST_EVSHIFT) | (flags))
  48
  49 /**
  50  * GstEventType:
  51  * @GST_EVENT_UNKNOWN: unknown event.
  52  * @GST_EVENT_FLUSH_START: Start a flush operation
  53  * @GST_EVENT_FLUSH_STOP: Stop a flush operation
  54  * @GST_EVENT_EOS: End-Of-Stream. No more data is to be expected to follow without
  55  * a NEWSEGMENT event.
  56  * @GST_EVENT_NEWSEGMENT: A new media segment follows in the dataflow.
  57  * @GST_EVENT_TAG: A new set of metadata tags has been found in the stream.
  58  * @GST_EVENT_FILLER: Filler for sparse data streams.
  59  * @GST_EVENT_QOS: A quality message. Used to indicate to upstream elements that the downstream elements
  60  * are being starved of or flooded with data.
  61  * @GST_EVENT_SEEK: A request for a new playback position and rate.
  62  * @GST_EVENT_NAVIGATION: Navigation events are usually used for communicating user
  63  * requests, such as mouse or keyboard movements, to upstream elements.
  64  * @GST_EVENT_CUSTOM_UP: Upstream custom event
  65  * @GST_EVENT_CUSTOM_DS: Downstream custom event that travels in the data flow.
  66  * @GST_EVENT_CUSTOM_DS_OOB: Custom out-of-band downstream event.
  67  * @GST_EVENT_CUSTOM_BOTH: Custom upstream or downstream event. In-band when travelling downstream.
  68  * @GST_EVENT_CUSTOM_BOTH_OOB: Custom upstream or downstream out-of-band event.
  69  *
  70  * GstEventType lists the standard event types that can be sent in a pipeline.
  71  *
  72  * The custom event types can be used for private messages between elements that can't be expressed using normal
  73  * GStreamer buffer passing semantics. Custom events carry an arbitrary GstStructure.
  74  * Specific custom events are distinguished by the name of the structure.
  75  */
  76 typedef enum {
  77   GST_EVENT_UNKNOWN             = GST_EVENT_MAKE_TYPE (0, 0),
  78   /* bidirectional events */
  79   GST_EVENT_FLUSH_START         = GST_EVENT_MAKE_TYPE (1, GST_EVDIR_BOTH),
  80   GST_EVENT_FLUSH_STOP          = GST_EVENT_MAKE_TYPE (2, GST_EVDIR_BOTH),
  81   /* downstream serialized events */
  82   GST_EVENT_EOS                 = GST_EVENT_MAKE_TYPE (3, GST_EVDIR_DS | GST_EVSER),
  83   GST_EVENT_NEWSEGMENT          = GST_EVENT_MAKE_TYPE (4, GST_EVDIR_DS | GST_EVSER),
  84   GST_EVENT_TAG                 = GST_EVENT_MAKE_TYPE (5, GST_EVDIR_DS | GST_EVSER),
  85   GST_EVENT_FILLER              = GST_EVENT_MAKE_TYPE (6, GST_EVDIR_DS | GST_EVSER),
  86   /* upstream events */
  87   GST_EVENT_QOS                 = GST_EVENT_MAKE_TYPE (7, GST_EVDIR_US),
  88   GST_EVENT_SEEK                = GST_EVENT_MAKE_TYPE (8, GST_EVDIR_US),
  89   GST_EVENT_NAVIGATION          = GST_EVENT_MAKE_TYPE (9, GST_EVDIR_US),
  90
  91   /* custom events start here */
  92   GST_EVENT_CUSTOM_UP           = GST_EVENT_MAKE_TYPE (32, GST_EVDIR_US),
  93   GST_EVENT_CUSTOM_DS           = GST_EVENT_MAKE_TYPE (32, GST_EVDIR_DS | GST_EVSER),
  94   GST_EVENT_CUSTOM_DS_OOB       = GST_EVENT_MAKE_TYPE (32, GST_EVDIR_DS),
  95   GST_EVENT_CUSTOM_BOTH         = GST_EVENT_MAKE_TYPE (32, GST_EVDIR_BOTH | GST_EVSER),
  96   GST_EVENT_CUSTOM_BOTH_OOB     = GST_EVENT_MAKE_TYPE (32, GST_EVDIR_BOTH)
  97 } GstEventType;
  98
  99 /**
 100  * GST_EVENT_TRACE_NAME:
 101  *
 102  * The name used for memory allocation tracing
 103  */
 104 #define GST_EVENT_TRACE_NAME    "GstEvent"
 105
 106 typedef struct _GstEvent GstEvent;
 107 typedef struct _GstEventClass GstEventClass;
 108
 109 #define GST_TYPE_EVENT                  (gst_event_get_type())
 110 #define GST_IS_EVENT(obj)               (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GST_TYPE_EVENT))
 111 #define GST_IS_EVENT_CLASS(klass)       (G_TYPE_CHECK_CLASS_TYPE ((klass), GST_TYPE_EVENT))
 112 #define GST_EVENT_GET_CLASS(obj)        (G_TYPE_INSTANCE_GET_CLASS ((obj), GST_TYPE_EVENT, GstEventClass))
 113 #define GST_EVENT(obj)                  (G_TYPE_CHECK_INSTANCE_CAST ((obj), GST_TYPE_EVENT, GstEvent))
 114 #define GST_EVENT_CLASS(klass)          (G_TYPE_CHECK_CLASS_CAST ((klass), GST_TYPE_EVENT, GstEventClass))
 115
 116 /**
 117  * GST_EVENT_TYPE:
 118  * @event: the event to query
 119  *
 120  * Get the event type.
 121  *
 122  * Returns: the #GstEventType of the given event
 123  */
 124 #define GST_EVENT_TYPE(event)           (GST_EVENT(event)->type)
 125 /**
 126  * GST_EVENT_TIMESTAMP:
 127  * @event: the event to query
 128  *
 129  * Get the timestamp of the event.
 130  *
 131  * Returns: the timestamp of the given event
 132  */
 133 #define GST_EVENT_TIMESTAMP(event)      (GST_EVENT(event)->timestamp)
 134 /**
 135  * GST_EVENT_SRC:
 136  * @event: the event to query
 137  *
 138  * The source object that generated this event.
 139  *
 140  * Returns: the source #GstObject for the given event
 141  */
 142 #define GST_EVENT_SRC(event)            (GST_EVENT(event)->src)
 143
 144 #define GST_EVENT_IS_UPSTREAM(ev)       !!(GST_EVENT_TYPE (ev) & GST_EVDIR_US)
 145 #define GST_EVENT_IS_DOWNSTREAM(ev)     !!(GST_EVENT_TYPE (ev) & GST_EVDIR_DS)
 146 #define GST_EVENT_IS_SERIALIZED(ev)     !!(GST_EVENT_TYPE (ev) & GST_EVSER)
 147
 148 /**
 149  * GstSeekType:
 150  * @GST_SEEK_TYPE_NONE: no change in position is required
 151  * @GST_SEEK_TYPE_CUR: change relative to current position
 152  * @GST_SEEK_TYPE_SET: absolute position is requested
 153  * @GST_SEEK_TYPE_END: relative position to duration is requested
 154  *
 155  * The different types of seek events. When constructing a seek event a format,
 156  * a seek method and optional flags are OR-ed together. The seek event is then
 157  * inserted into the graph with #gst_pad_send_event() or
 158  * #gst_element_send_event().
 159
 160  * Following example illustrates how to insert a seek event (1 second in the stream)
 161  * in a pipeline.
 162  * <example>
 163  * <title>Insertion of a seek event into a pipeline</title>
 164  * <programlisting>
 165  *  gboolean res;
 166  *  GstEvent *event;
 167  *
 168  *  event = gst_event_new_seek (
 169  *            GST_FORMAT_TIME |         // seek on time
 170  *            GST_SEEK_METHOD_SET |     // set the absolute position
 171  *            GST_SEEK_FLAG_FLUSH,      // flush any pending data
 172  *            1 * GST_SECOND);          // the seek offset (1 second)
 173  *
 174  *  res = gst_element_send_event (GST_ELEMENT (osssink), event);
 175  *  if (!res) {
 176  *    g_warning ("seek failed");
 177  *  }
 178  * </programlisting>
 179  * </example>
 180  */
 181 typedef enum {
 182   /* one of these */
 183   GST_SEEK_TYPE_NONE            = 0,
 184   GST_SEEK_TYPE_CUR             = 1,
 185   GST_SEEK_TYPE_SET             = 2,
 186   GST_SEEK_TYPE_END             = 3
 187 } GstSeekType;
 188
 189 /**
 190  * GstSeekFlags:
 191  * @GST_SEEK_FLAG_NONE: no flag
 192  * @GST_SEEK_FLAG_FLUSH: flush pipeline
 193  * @GST_SEEK_FLAG_ACCURATE: accurate position is requested, this might
 194  *                     be slower for some formats.
 195  * @GST_SEEK_FLAG_KEY_UNIT: seek to the nearest keyframe. This might be
 196  *                     faster but less accurate.
 197  * @GST_SEEK_FLAG_SEGMENT: perform a segment seek. After the playback
 198  *            of the segment completes, no EOS will be emmited but a
 199  *            SEGMENT_DONE message will be posted on the bus.
 200  */
 201 typedef enum {
 202   GST_SEEK_FLAG_NONE            = 0,
 203   GST_SEEK_FLAG_FLUSH           = (1 << 0),
 204   GST_SEEK_FLAG_ACCURATE        = (1 << 1),
 205   GST_SEEK_FLAG_KEY_UNIT        = (1 << 2),
 206   GST_SEEK_FLAG_SEGMENT         = (1 << 3)
 207 } GstSeekFlags;
 208
 209 struct _GstEvent {
 210   GstMiniObject mini_object;
 211
 212   /*< public >*/ /* with COW */
 213   GstEventType  type;
 214   guint64       timestamp;
 215   GstObject     *src;
 216
 217   GstStructure  *structure;
 218
 219   /*< private >*/
 220   gpointer _gst_reserved[GST_PADDING];
 221 };
 222
 223 struct _GstEventClass {
 224   GstMiniObjectClass mini_object_class;
 225
 226   /*< private >*/
 227   gpointer _gst_reserved[GST_PADDING];
 228 };
 229
 230 void            _gst_event_initialize           (void);
 231
 232 GType           gst_event_get_type              (void);
 233
 234 /* refcounting */
 235 /**
 236  * gst_event_ref:
 237  * @ev: The event to refcount
 238  *
 239  * Increase the refcount of this event.
 240  */
 241 #define         gst_event_ref(ev)               GST_EVENT (gst_mini_object_ref (GST_MINI_OBJECT (ev)))
 242 /**
 243  * gst_event_ref:
 244  * @ev: The event to refcount
 245  *
 246  * Decrease the refcount of an event, freeing it if the refcount reaches 0.
 247  */
 248 #define         gst_event_unref(ev)             gst_mini_object_unref (GST_MINI_OBJECT (ev))
 249
 250 /* copy event */
 251 /**
 252  * gst_event_copy:
 253  * @ev: The event to copy
 254  *
 255  * Copy the event using the event specific copy function.
 256  *
 257  * Returns: A new event that is a copy of the given input event
 258  */
 259 #define         gst_event_copy(ev)              GST_EVENT (gst_mini_object_copy (GST_MINI_OBJECT (ev)))
 260
 261 /* custom event */
 262 GstEvent*       gst_event_new_custom            (GstEventType type, GstStructure *structure);
 263
 264 const GstStructure *
 265                 gst_event_get_structure         (GstEvent *event);
 266
 267 /* flush events */
 268 GstEvent *      gst_event_new_flush_start       (void);
 269 GstEvent *      gst_event_new_flush_stop        (void);
 270
 271 /* EOS event */
 272 GstEvent *      gst_event_new_eos               (void);
 273
 274 /* newsegment events */
 275 GstEvent*       gst_event_new_newsegment        (gdouble rate,
 276                                                  GstFormat format, gint64 start_value, gint64 stop_value,
 277                                                  gint64 base);
 278 void            gst_event_parse_newsegment      (GstEvent *event, gdouble *rate, GstFormat *format,
 279                                                  gint64 *start_value, gint64 *end_value, gint64 *base);
 280 /* tag event */
 281 GstEvent*       gst_event_new_tag               (GstTagList *taglist);
 282 void            gst_event_parse_tag             (GstEvent *event, GstTagList **taglist);
 283
 284 /* filler event */
 285 /* FIXME: FILLER events need to be fully specified and implemented */
 286 GstEvent *      gst_event_new_filler            (void);
 287
 288
 289 /* QOS events */
 290 /* FIXME: QOS events need to be fully specified and implemented */
 291 GstEvent*       gst_event_new_qos               (gdouble proportion, GstClockTimeDiff diff,
 292                                                  GstClockTime timestamp);
 293 void            gst_event_parse_qos             (GstEvent *event, gdouble *proportion, GstClockTimeDiff *diff,
 294                                                  GstClockTime *timestamp);
 295 /* seek event */
 296 GstEvent*       gst_event_new_seek              (gdouble rate, GstFormat format, GstSeekFlags flags,
 297                                                  GstSeekType cur_type, gint64 cur,
 298                                                  GstSeekType stop_type, gint64 stop);
 299 void            gst_event_parse_seek            (GstEvent *event, gdouble *rate, GstFormat *format,
 300                                                  GstSeekFlags *flags,
 301                                                  GstSeekType *cur_type, gint64 *cur,
 302                                                  GstSeekType *stop_type, gint64 *stop);
 303 /* navigation event */
 304 GstEvent*       gst_event_new_navigation        (GstStructure *structure);
 305
 306 G_END_DECLS
 307
 308 #endif /* __GST_EVENT_H__ */