docs/gst/tmpl/gstevent.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 GstEvent
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 Structure describing events that are passed up and down a pipeline
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 The event classes are used to construct and query events.
  10 </para>
  11
  12 <para>
  13 Events are usually created with gst_event_new() which takes the event type as an argument.
  14 properties specific to the event can be set afterwards with the provided macros.
  15 The event should be unreferenced with gst_event_unref().
  16 </para>
  17 <para>
  18 gst_event_new_seek() is a usually used to create a seek event and it takes the
  19 needed parameters for a seek event.
  20 </para>
  21 <para>
  22 gst_event_new_flush() creates a new flush event.
  23 </para>
  24
  25 <!-- ##### SECTION See_Also ##### -->
  26 <para>
  27 #GstPad, #GstElement
  28 </para>
  29
  30 <!-- ##### SECTION Stability_Level ##### -->
  31
  32
  33 <!-- ##### STRUCT GstEvent ##### -->
  34 <para>
  35
  36 </para>
  37
  38 @mini_object:
  39 @type:
  40 @timestamp:
  41 @src:
  42 @structure:
  43
  44 <!-- ##### ENUM GstEventType ##### -->
  45 <para>
  46 The different major types of events.
  47 </para>
  48
  49 @GST_EVENT_UNKNOWN: unknown event.
  50 @GST_EVENT_FLUSH_START:
  51 @GST_EVENT_FLUSH_STOP:
  52 @GST_EVENT_EOS: an end-of-stream event.
  53 @GST_EVENT_NEWSEGMENT:
  54 @GST_EVENT_TAG:
  55 @GST_EVENT_FILLER:
  56 @GST_EVENT_QOS: a quality of service event
  57 @GST_EVENT_SEEK: a seek event.
  58 @GST_EVENT_NAVIGATION:
  59 @GST_EVENT_CUSTOM_START:
  60
  61 <!-- ##### MACRO GST_EVENT_TRACE_NAME ##### -->
  62 <para>
  63 The name used for memory allocation tracing
  64 </para>
  65
  66
  67
  68 <!-- ##### MACRO GST_EVENT_TYPE ##### -->
  69 <para>
  70 Get the event type.
  71 </para>
  72
  73 @event: The event to query.
  74
  75
  76 <!-- ##### MACRO GST_EVENT_TIMESTAMP ##### -->
  77 <para>
  78 Get the timestamp of the event.
  79 </para>
  80
  81 @event: The event to query.
  82
  83
  84 <!-- ##### MACRO GST_EVENT_SRC ##### -->
  85 <para>
  86 The source object that generated this event
  87 </para>
  88
  89 @event: The event to query
  90
  91
  92 <!-- ##### ENUM GstSeekType ##### -->
  93 <para>
  94 The different types of seek events. When constructing a seek event a format,
  95 a seek method and optional flags are OR-ed together. The seek event is then
  96 inserted into the graph with #gst_pad_send_event() or #gst_element_send_event().
  97
  98 Following example illustrates how to insert a seek event (1 second in the stream)
  99 in a pipeline.
 100 <example>
 101 <title>Insertion of a seek event into a pipeline</title>
 102   <programlisting>
 103   gboolean res;
 104   GstEvent *event;
 105
 106   event = gst_event_new_seek (
 107             GST_FORMAT_TIME |           /* seek on time */
 108             GST_SEEK_METHOD_SET |       /* set the absolute position */
 109             GST_SEEK_FLAG_FLUSH,        /* flush any pending data */
 110             1 * GST_SECOND);            /* the seek offset (1 second) */
 111
 112   res = gst_element_send_event (GST_ELEMENT (osssink), event);
 113   if (!res) {
 114     g_warning ("seek failed");
 115   }
 116   </programlisting>
 117 </example>
 118 </para>
 119
 120 @GST_SEEK_TYPE_NONE:
 121 @GST_SEEK_TYPE_CUR:
 122 @GST_SEEK_TYPE_SET:
 123 @GST_SEEK_TYPE_END:
 124
 125 <!-- ##### MACRO gst_event_ref ##### -->
 126 <para>
 127 Increase the refcount of this event
 128 </para>
 129
 130 @ev: The event to refcount
 131
 132
 133 <!-- ##### MACRO gst_event_unref ##### -->
 134 <para>
 135 Decrease the refcount of an event, freeing it if the refcount reaches 0
 136 </para>
 137
 138 @ev: The event to unref
 139
 140
 141 <!-- ##### MACRO gst_event_copy ##### -->
 142 <para>
 143 Copy the event using the event specific copy function
 144 </para>
 145
 146 @ev: The event to copy
 147 @Returns: A new event that is a copy of the given input event
 148
 149
 150 <!-- ##### FUNCTION gst_event_new_custom ##### -->
 151 <para>
 152
 153 </para>
 154
 155 @type:
 156 @structure:
 157 @Returns:
 158
 159
 160 <!-- ##### FUNCTION gst_event_get_structure ##### -->
 161 <para>
 162
 163 </para>
 164
 165 @event:
 166 @Returns:
 167
 168
 169 <!-- ##### FUNCTION gst_event_new_flush_start ##### -->
 170 <para>
 171
 172 </para>
 173
 174 @Returns:
 175
 176
 177 <!-- ##### FUNCTION gst_event_new_flush_stop ##### -->
 178 <para>
 179
 180 </para>
 181
 182 @Returns:
 183
 184
 185 <!-- ##### FUNCTION gst_event_new_eos ##### -->
 186 <para>
 187
 188 </para>
 189
 190 @Returns:
 191
 192
 193 <!-- ##### FUNCTION gst_event_new_newsegment ##### -->
 194 <para>
 195
 196 </para>
 197
 198 @rate:
 199 @format:
 200 @start_value:
 201 @stop_value:
 202 @base:
 203 @Returns:
 204
 205
 206 <!-- ##### FUNCTION gst_event_parse_newsegment ##### -->
 207 <para>
 208
 209 </para>
 210
 211 @event:
 212 @rate:
 213 @format:
 214 @start_value:
 215 @end_value:
 216 @base:
 217
 218
 219 <!-- ##### FUNCTION gst_event_new_tag ##### -->
 220 <para>
 221
 222 </para>
 223
 224 @taglist:
 225 @Returns:
 226
 227
 228 <!-- ##### FUNCTION gst_event_parse_tag ##### -->
 229 <para>
 230
 231 </para>
 232
 233 @event:
 234 @taglist:
 235
 236
 237 <!-- ##### FUNCTION gst_event_new_filler ##### -->
 238 <para>
 239 Create a new dummy event that should be ignored
 240 </para>
 241
 242 @Returns:
 243
 244
 245 <!-- ##### FUNCTION gst_event_new_qos ##### -->
 246 <para>
 247
 248 </para>
 249
 250 @proportion:
 251 @diff:
 252 @timestamp:
 253 @Returns:
 254
 255
 256 <!-- ##### FUNCTION gst_event_parse_qos ##### -->
 257 <para>
 258
 259 </para>
 260
 261 @event:
 262 @proportion:
 263 @diff:
 264 @timestamp:
 265
 266
 267 <!-- ##### FUNCTION gst_event_new_seek ##### -->
 268 <para>
 269
 270 </para>
 271
 272 @rate:
 273 @format:
 274 @flags:
 275 @cur_type:
 276 @cur:
 277 @stop_type:
 278 @stop:
 279 @Returns:
 280 <!-- # Unused Parameters # -->
 281 @type:
 282 @offset:
 283
 284
 285 <!-- ##### FUNCTION gst_event_parse_seek ##### -->
 286 <para>
 287
 288 </para>
 289
 290 @event:
 291 @rate:
 292 @format:
 293 @flags:
 294 @cur_type:
 295 @cur:
 296 @stop_type:
 297 @stop:
 298
 299
 300 <!-- ##### FUNCTION gst_event_new_navigation ##### -->
 301 <para>
 302
 303 </para>
 304
 305 @structure:
 306 @Returns:
 307
 308