docs/gst/tmpl/gstevent.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 GstEvent
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 Event definitions.
   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 <!-- ##### ENUM GstEventType ##### -->
  31 <para>
  32 The different major types of events.
  33 </para>
  34
  35 @GST_EVENT_UNKNOWN: unknown event.
  36 @GST_EVENT_EOS: an end-of-stream event.
  37 @GST_EVENT_FLUSH: a flush event.
  38 @GST_EVENT_EMPTY: an empty event.
  39 @GST_EVENT_DISCONTINUOUS: a discontinuous event to indicate the stream has a discontinuity.
  40 @GST_EVENT_QOS: a quality of service event
  41 @GST_EVENT_SEEK: a seek event.
  42 @GST_EVENT_SEEK_SEGMENT: a segment seek with start and stop position
  43 @GST_EVENT_SEGMENT_DONE: the event that will be emited when the segment seek has ended
  44 @GST_EVENT_SIZE: a size suggestion for a peer element
  45 @GST_EVENT_RATE: adjust the output rate of an element
  46 @GST_EVENT_FILLER: a dummy event that should be ignored by plugins
  47 @GST_EVENT_TS_OFFSET: an event to set the time offset on buffers
  48 @GST_EVENT_INTERRUPT: mainly used by _get based elements when they were interrupted
  49                       while waiting for a buffer.
  50 @GST_EVENT_NAVIGATION:
  51 @GST_EVENT_TAG:
  52
  53 <!-- ##### MACRO GST_EVENT_TYPE ##### -->
  54 <para>
  55 Get the event type.
  56 </para>
  57
  58 @event: The event to query.
  59
  60
  61 <!-- ##### MACRO GST_EVENT_SRC ##### -->
  62 <para>
  63 The source object that generated this event
  64 </para>
  65
  66 @event: The event to query
  67
  68
  69 <!-- ##### MACRO GST_EVENT_TIMESTAMP ##### -->
  70 <para>
  71 Get the timestamp of the event.
  72 </para>
  73
  74 @event: The event to query.
  75
  76
  77 <!-- ##### ENUM GstEventFlag ##### -->
  78 <para>
  79 Event flags are used when querying for supported events
  80 </para>
  81
  82 @GST_EVENT_FLAG_NONE: no value
  83 @GST_RATE_FLAG_NEGATIVE: indicates negative rates are supported
  84
  85 <!-- ##### ENUM GstSeekType ##### -->
  86 <para>
  87 The different types of seek events. When constructing a seek event a format,
  88 a seek method and optional flags are OR-ed together. The seek event is then
  89 inserted into the graph with #gst_pad_send_event() or #gst_element_send_event().
  90
  91  <informalexample>
  92   Following example illustrates how to insert a seek event (1 second in the stream)
  93   in a pipeline.
  94
  95   <programlisting>
  96   gboolean res;
  97   GstEvent *event;
  98
  99   event = gst_event_new_seek (
 100             GST_FORMAT_TIME |           /* seek on time */
 101             GST_SEEK_METHOD_SET |       /* set the absolute position */
 102             GST_SEEK_FLAG_FLUSH,        /* flush any pending data */
 103             1 * GST_SECOND);            /* the seek offset (1 second) */
 104
 105   res = gst_element_send_event (GST_ELEMENT (osssink), event);
 106   if (!res) {
 107     g_warning ("seek failed");
 108   }
 109   </programlisting>
 110  </informalexample>
 111 </para>
 112
 113 @GST_SEEK_METHOD_CUR: Seek to an relative position
 114 @GST_SEEK_METHOD_SET: Seek to an absolute position
 115 @GST_SEEK_METHOD_END: Seek relative to the end of the stream
 116 @GST_SEEK_FLAG_FLUSH: Flush any pending data while seeking
 117 @GST_SEEK_FLAG_ACCURATE: Seek as accuratly as possible
 118 @GST_SEEK_FLAG_KEY_UNIT: Seek to a nearby key unit
 119 @GST_SEEK_FLAG_SEGMENT_LOOP: Loop between start and stop in a segmented seek
 120
 121 <!-- ##### ENUM GstSeekAccuracy ##### -->
 122 <para>
 123 The seekaccuracy gives more information of how the seek was performed,
 124 if the seek was accurate or fuzzy.
 125 </para>
 126
 127 @GST_SEEK_CERTAIN: The seek was exact
 128 @GST_SEEK_FUZZY: The seek was fuzzy, exact position can not be guaranteed
 129
 130 <!-- ##### MACRO GST_EVENT_SEEK_TYPE ##### -->
 131 <para>
 132 Get the seektype of the GST_EVENT_SEEK.
 133 </para>
 134
 135 @event: The event to query.
 136
 137
 138 <!-- ##### MACRO GST_EVENT_SEEK_FORMAT ##### -->
 139 <para>
 140 The format of the seek value
 141 </para>
 142
 143 @event: The event operate on
 144
 145
 146 <!-- ##### MACRO GST_EVENT_SEEK_METHOD ##### -->
 147 <para>
 148 The seek method to use as one of #GstSeekType
 149 </para>
 150
 151 @event: The event operate on
 152
 153
 154 <!-- ##### MACRO GST_EVENT_SEEK_FLAGS ##### -->
 155 <para>
 156 The optional seek flags
 157 </para>
 158
 159 @event: The event operate on
 160
 161
 162 <!-- ##### MACRO GST_EVENT_SEEK_OFFSET ##### -->
 163 <para>
 164 Get the offset of the seek event.
 165 </para>
 166
 167 @event: The event to query.
 168
 169
 170 <!-- ##### MACRO GST_EVENT_SEEK_ACCURACY ##### -->
 171 <para>
 172 Indicates how accurate the event was performed.
 173 </para>
 174
 175 @event: The event to query
 176
 177
 178 <!-- ##### MACRO GST_SEEK_FLAGS_MASK ##### -->
 179 <para>
 180 Mask for the flags in the GstSeekType
 181 </para>
 182
 183
 184
 185 <!-- ##### MACRO GST_SEEK_FLAGS_SHIFT ##### -->
 186 <para>
 187 Shift for the flags in the GstSeekType
 188 </para>
 189
 190
 191
 192 <!-- ##### MACRO GST_SEEK_FORMAT_MASK ##### -->
 193 <para>
 194 Mask for the format in the GstSeekType
 195 </para>
 196
 197
 198
 199 <!-- ##### MACRO GST_SEEK_FORMAT_SHIFT ##### -->
 200 <para>
 201 Shift for the format in the GstSeekType
 202 </para>
 203
 204
 205
 206 <!-- ##### MACRO GST_SEEK_METHOD_MASK ##### -->
 207 <para>
 208 Mask for the method in the GstSeekType
 209 </para>
 210
 211
 212
 213 <!-- ##### MACRO GST_SEEK_METHOD_SHIFT ##### -->
 214 <para>
 215 Shift for the method in the GstSeekType
 216 </para>
 217
 218
 219
 220 <!-- ##### MACRO GST_EVENT_DISCONT_NEW_MEDIA ##### -->
 221 <para>
 222 Flag that indicates the discont event was because of a new media
 223 type.
 224 </para>
 225
 226 @event: The event to operate on
 227
 228
 229 <!-- ##### MACRO GST_EVENT_DISCONT_OFFSET ##### -->
 230 <para>
 231 The offset of the discont event. A discont evetn can hold up to 8 different
 232 format/value pairs.
 233 </para>
 234
 235 @event: The event to query
 236 @i: The offset/value pair.
 237
 238
 239 <!-- ##### MACRO GST_EVENT_DISCONT_OFFSET_LEN ##### -->
 240 <para>
 241 Get the number of offset/value pairs this event has.
 242 </para>
 243
 244 @event: The event to query.
 245
 246
 247 <!-- ##### MACRO GST_EVENT_RATE_VALUE ##### -->
 248 <para>
 249 Get access to the rate vale field
 250 </para>
 251
 252 @event: The event to query
 253
 254
 255 <!-- ##### MACRO GST_EVENT_SEEK_ENDOFFSET ##### -->
 256 <para>
 257 The event stop position for a segment seek
 258 </para>
 259
 260 @event: The event to query
 261
 262
 263 <!-- ##### MACRO GST_EVENT_SIZE_FORMAT ##### -->
 264 <para>
 265 The format of the size event.
 266 </para>
 267
 268 @event: The event to query
 269
 270
 271 <!-- ##### MACRO GST_EVENT_SIZE_VALUE ##### -->
 272 <para>
 273 The value of the size event
 274 </para>
 275
 276 @event: The event to query
 277
 278
 279 <!-- ##### MACRO GST_EVENT_IS_INTERRUPT ##### -->
 280 <para>
 281 Check if the event is an interrupt event
 282 </para>
 283
 284 @event: The event to check
 285
 286
 287 <!-- ##### MACRO GST_EVENT_TRACE_NAME ##### -->
 288 <para>
 289 The name used for memory allocation tracing
 290 </para>
 291
 292
 293
 294 <!-- ##### STRUCT GstEvent ##### -->
 295 <para>
 296 The event structure
 297 </para>
 298
 299 @data:
 300 @type:
 301 @timestamp:
 302 @src:
 303
 304 <!-- ##### FUNCTION gst_event_new ##### -->
 305 <para>
 306
 307 </para>
 308
 309 @type:
 310 @Returns:
 311
 312
 313 <!-- ##### MACRO gst_event_copy ##### -->
 314 <para>
 315 Copy the event using the event specific copy function
 316 </para>
 317
 318 @ev: The event to copy
 319 @Returns: A new event that is a copy of the given input event
 320
 321
 322 <!-- ##### MACRO gst_event_ref ##### -->
 323 <para>
 324 Increase the refcount of this event
 325 </para>
 326
 327 @ev: The event to refcount
 328
 329
 330 <!-- ##### MACRO gst_event_ref_by_count ##### -->
 331 <para>
 332 Increase the refcount of the event with the given value
 333 </para>
 334
 335 @ev: The event to refcount
 336 @c: The value to add to the refcount
 337
 338
 339 <!-- ##### MACRO gst_event_unref ##### -->
 340 <para>
 341 Decrease the refcount of an event, freeing it if the refcount reaches 0
 342 </para>
 343
 344 @ev: The event to unref
 345
 346
 347 <!-- ##### FUNCTION gst_event_new_seek ##### -->
 348 <para>
 349
 350 </para>
 351
 352 @type:
 353 @offset:
 354 @Returns:
 355
 356
 357 <!-- ##### FUNCTION gst_event_new_segment_seek ##### -->
 358 <para>
 359
 360 </para>
 361
 362 @type:
 363 @start:
 364 @stop:
 365 @Returns:
 366
 367
 368 <!-- ##### FUNCTION gst_event_new_size ##### -->
 369 <para>
 370
 371 </para>
 372
 373 @format:
 374 @value:
 375 @Returns:
 376
 377
 378 <!-- ##### FUNCTION gst_event_new_discontinuous ##### -->
 379 <para>
 380
 381 </para>
 382
 383 @new_media:
 384 @format1:
 385 @Varargs:
 386 @Returns:
 387
 388
 389 <!-- ##### FUNCTION gst_event_discont_get_value ##### -->
 390 <para>
 391
 392 </para>
 393
 394 @event:
 395 @format:
 396 @value:
 397 @Returns:
 398
 399
 400 <!-- ##### MACRO gst_event_new_filler ##### -->
 401 <para>
 402 Create a new dummy event that should be ignored
 403 </para>
 404
 405
 406
 407 <!-- ##### MACRO gst_event_new_flush ##### -->
 408 <para>
 409 Create a new flush event.
 410 </para>
 411
 412
 413
 414 <!-- ##### FUNCTION gst_event_masks_contains ##### -->
 415 <para>
 416
 417 </para>
 418
 419 @masks:
 420 @mask:
 421 @Returns:
 422
 423
 424 <!-- ##### MACRO GST_EVENT_MASK_FUNCTION ##### -->
 425 <para>
 426 A convenience macro to create event mask functions
 427 </para>
 428
 429 @type: The type of the first argument of the function
 430 @functionname: the name of the function
 431 @...: event masks, the last element is marked with 0
 432
 433