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