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/gsttaglist.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 #GstEventType of the event.
 121  */
 122 #define GST_EVENT_TYPE(event)           (GST_EVENT(event)->type)
 123
 124 /**
 125  * GST_EVENT_TIMESTAMP:
 126  * @event: the event to query
 127  *
 128  * Get the #GstClockTime timestamp of the event.
 129  */
 130 #define GST_EVENT_TIMESTAMP(event)      (GST_EVENT(event)->timestamp)
 131
 132 /**
 133  * GST_EVENT_SRC:
 134  * @event: the event to query
 135  *
 136  * The source #GstObject that generated this event.
 137  */
 138 #define GST_EVENT_SRC(event)            (GST_EVENT(event)->src)
 139
 140 #define GST_EVENT_IS_UPSTREAM(ev)       !!(GST_EVENT_TYPE (ev) & GST_EVDIR_US)
 141 #define GST_EVENT_IS_DOWNSTREAM(ev)     !!(GST_EVENT_TYPE (ev) & GST_EVDIR_DS)
 142 #define GST_EVENT_IS_SERIALIZED(ev)     !!(GST_EVENT_TYPE (ev) & GST_EVSER)
 143
 144 /**
 145  * GstSeekType:
 146  * @GST_SEEK_TYPE_NONE: no change in position is required
 147  * @GST_SEEK_TYPE_CUR: change relative to current position
 148  * @GST_SEEK_TYPE_SET: absolute position is requested
 149  * @GST_SEEK_TYPE_END: relative position to duration is requested
 150  *
 151  * The different types of seek events. When constructing a seek event a format,
 152  * a seek method and optional flags are OR-ed together. The seek event is then
 153  * inserted into the graph with #gst_pad_send_event() or
 154  * #gst_element_send_event().
 155  */
 156 typedef enum {
 157   /* one of these */
 158   GST_SEEK_TYPE_NONE            = 0,
 159   GST_SEEK_TYPE_CUR             = 1,
 160   GST_SEEK_TYPE_SET             = 2,
 161   GST_SEEK_TYPE_END             = 3
 162 } GstSeekType;
 163
 164 /**
 165  * GstSeekFlags:
 166  * @GST_SEEK_FLAG_NONE: no flag
 167  * @GST_SEEK_FLAG_FLUSH: flush pipeline
 168  * @GST_SEEK_FLAG_ACCURATE: accurate position is requested, this might
 169  *                     be slower for some formats.
 170  * @GST_SEEK_FLAG_KEY_UNIT: seek to the nearest keyframe. This might be
 171  *                     faster but less accurate.
 172  * @GST_SEEK_FLAG_SEGMENT: perform a segment seek. After the playback
 173  *            of the segment completes, no EOS will be emmited but a
 174  *            SEGMENT_DONE message will be posted on the bus.
 175  */
 176 typedef enum {
 177   GST_SEEK_FLAG_NONE            = 0,
 178   GST_SEEK_FLAG_FLUSH           = (1 << 0),
 179   GST_SEEK_FLAG_ACCURATE        = (1 << 1),
 180   GST_SEEK_FLAG_KEY_UNIT        = (1 << 2),
 181   GST_SEEK_FLAG_SEGMENT         = (1 << 3)
 182 } GstSeekFlags;
 183
 184 struct _GstEvent {
 185   GstMiniObject mini_object;
 186
 187   /*< public >*/ /* with COW */
 188   GstEventType  type;
 189   guint64       timestamp;
 190   GstObject     *src;
 191
 192   GstStructure  *structure;
 193
 194   /*< private >*/
 195   gpointer _gst_reserved[GST_PADDING];
 196 };
 197
 198 struct _GstEventClass {
 199   GstMiniObjectClass mini_object_class;
 200
 201   /*< private >*/
 202   gpointer _gst_reserved[GST_PADDING];
 203 };
 204
 205 void            _gst_event_initialize           (void);
 206
 207 GType           gst_event_get_type              (void);
 208
 209 /* refcounting */
 210 /**
 211  * gst_event_ref:
 212  * @ev: The event to refcount
 213  *
 214  * Increase the refcount of this event.
 215  */
 216 #define         gst_event_ref(ev)               GST_EVENT (gst_mini_object_ref (GST_MINI_OBJECT (ev)))
 217 /**
 218  * gst_event_ref:
 219  * @ev: The event to refcount
 220  *
 221  * Decrease the refcount of an event, freeing it if the refcount reaches 0.
 222  */
 223 #define         gst_event_unref(ev)             gst_mini_object_unref (GST_MINI_OBJECT (ev))
 224
 225 /* copy event */
 226 /**
 227  * gst_event_copy:
 228  * @ev: The event to copy
 229  *
 230  * Copy the event using the event specific copy function.
 231  */
 232 #define         gst_event_copy(ev)              GST_EVENT (gst_mini_object_copy (GST_MINI_OBJECT (ev)))
 233
 234 /* custom event */
 235 GstEvent*       gst_event_new_custom            (GstEventType type, GstStructure *structure);
 236
 237 const GstStructure *
 238                 gst_event_get_structure         (GstEvent *event);
 239
 240 /* flush events */
 241 GstEvent *      gst_event_new_flush_start       (void);
 242 GstEvent *      gst_event_new_flush_stop        (void);
 243
 244 /* EOS event */
 245 GstEvent *      gst_event_new_eos               (void);
 246
 247 /* newsegment events */
 248 GstEvent*       gst_event_new_newsegment        (gdouble rate, GstFormat format,
 249                                                  gint64 start_value, gint64 stop_value,
 250                                                  gint64 base);
 251 void            gst_event_parse_newsegment      (GstEvent *event, gdouble *rate, GstFormat *format,
 252                                                  gint64 *start_value, gint64 *stop_value, gint64 *base);
 253 /* tag event */
 254 GstEvent*       gst_event_new_tag               (GstTagList *taglist);
 255 void            gst_event_parse_tag             (GstEvent *event, GstTagList **taglist);
 256
 257 /* filler event */
 258 /* FIXME: FILLER events need to be fully specified and implemented */
 259 GstEvent *      gst_event_new_filler            (void);
 260
 261
 262 /* QOS events */
 263 /* FIXME: QOS events need to be fully specified and implemented */
 264 GstEvent*       gst_event_new_qos               (gdouble proportion, GstClockTimeDiff diff,
 265                                                  GstClockTime timestamp);
 266 void            gst_event_parse_qos             (GstEvent *event, gdouble *proportion, GstClockTimeDiff *diff,
 267                                                  GstClockTime *timestamp);
 268 /* seek event */
 269 GstEvent*       gst_event_new_seek              (gdouble rate, GstFormat format, GstSeekFlags flags,
 270                                                  GstSeekType cur_type, gint64 cur,
 271                                                  GstSeekType stop_type, gint64 stop);
 272 void            gst_event_parse_seek            (GstEvent *event, gdouble *rate, GstFormat *format,
 273                                                  GstSeekFlags *flags,
 274                                                  GstSeekType *cur_type, gint64 *cur,
 275                                                  GstSeekType *stop_type, gint64 *stop);
 276 /* navigation event */
 277 GstEvent*       gst_event_new_navigation        (GstStructure *structure);
 278
 279 G_END_DECLS
 280
 281 #endif /* __GST_EVENT_H__ */