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